# Block Editor

## Objective

Edit long-form content as a stack of blocks you can reorder, nest, and mix with embeds.

A typed-block editing surface for the app's long-form content, backed by a versioned block tree.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Define the block types the content actually needs: paragraph, heading, list, image, quote, code, divider, embed. Give each a stable stored shape and ship those, rather than an open-ended block system in the hope that types get added later.
2. Extend the app's existing Rich Text Editor for inline formatting inside a block rather than running two editing engines side by side. The block editor owns the structure; the existing editor owns the text.
3. Reuse the app's existing Autosave, Version History, and Undo Actions. A second history stack that only covers this editor will disagree with the record's real history.
4. Convert pasted content into known block types on the way in. Storing pasted markup verbatim means storing whatever the source page happened to contain, scripts included.
5. Reuse Drag-and-Drop Reordering for moving blocks, and make sure every reorder is also reachable from the keyboard.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Content written today must still open after the block types change. Store a version on the tree, migrate forward on read, and keep unrecognised blocks intact rather than dropping them.
- Pasted markup from a document or another site carries styles, scripts, and tracked-change annotations. Map what you recognise onto real block types and discard the rest.
- Splitting a paragraph with Enter and merging it back with Backspace must leave the caret exactly where the writer expects. A caret that jumps to the top of the document on every merge makes the editor unusable.
- Dragging to reorder on a touch screen competes with scrolling. Require a deliberate long press or a dedicated handle so a scroll gesture never moves a block.
- A crashed or reloaded tab must not cost an hour of writing. Keep a local copy of unsaved blocks and offer to restore it, clearly distinguished from the saved version.
- Images inside blocks must reserve their dimensions so the document does not reflow under the writer's cursor while they load, and each needs alt text.
- An embed block renders somebody else's page. Show the source link and a readable fallback for when the third party is blocked, deleted, or down.
- Two people opening the same document must not silently overwrite each other. Detect that the stored version has moved and say so rather than saving on top of it.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Content is stored as a versioned tree of typed blocks that survives schema changes.
- [ ] Blocks can be added, reordered, nested, and deleted with both pointer and keyboard.
- [ ] Pasted content becomes known block types and no raw markup is stored.
- [ ] The caret stays where the writer expects across block splits and merges.
- [ ] Touch drag moves blocks only on a deliberate gesture and never blocks page scroll.
- [ ] Unsaved work is recoverable after a crashed or reloaded tab.
- [ ] Autosave, undo, and version history come from the app's existing implementations.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.