docs(openspec): propose block merging via BlocksAPI.merge

[gohabereg]

What

Planning only. This PR adds the merge-blocks-on-delete OpenSpec change for #135. It contains no code changes.

One new API method, BlocksAPI.merge, with two overloads:

• merge({ block }) merges a block into the block before it. Only neighbouring blocks can be merged, so one block is enough.
• merge({ index }) takes a range that crosses blocks. It removes the content inside the range and the blocks in between, then joins the end block into the start block.
• Both return where the blocks joined ({ block, key, offset }). merge never moves the caret, like split and convert.

How merging works:

• The second block is always converted into the first. The first block keeps its id and tool. What the second block contributes is chosen by its conversionConfig.export: a key path keeps formatting, a function gives plain text, and with no config the first text input is used. There's no direction and no separate convert step.
• Empty blocks give way. If the first block is empty, it's removed instead and the second block survives.
• Blocks without text inputs are unmergeable. merge throws for them. On the keyboard, Backspace or Delete next to such a block removes it.

The DOM adapter only maps events to calls:

• Deleting, typing, pasting or pressing Enter over a cross-block selection makes one merge({ index }) call, then the insert or split where the blocks joined.
• Backspace and Delete at block edges call merge({ block }).
• The current per-adapter cross-block slicing is removed.

There's no canMerge, no new tool option, and no change to SelectionAPI, TextAPI or the model.

Why

v3 is one contenteditable with cross-block selection, so merging is also needed whenever a deletion crosses a block boundary, not only on Backspace/Delete as in v2. Today none of these cases join anything:

• Backspace and Delete at a boundary do nothing.
• A cross-block selection delete leaves the two edge blocks apart. There's a @todo support input merging in BlockToolAdapter at that spot.

Notes for reviewers

• Several earlier designs were rejected; the design records why. They were: a v2-style merge/canMerge plus a canBeMerged option, a new SelectionAPI.deleteContent, extending TextAPI.remove, and two-step convert-then-merge on Backspace.
• Undo grouping is out of scope. It depends on undo-group-by-task (docs(openspec): propose undo grouping by browser task #201 / feat(core): group undo steps by browser task #203). That change makes a merge a single undo step and fixes undo of block removal, which currently throws.
• Related open work:
  • feat(model)!: store TextNode inline formatting as canonical runs #198, the run-based inline model: the formatting clean-up at the join point uses only public model operations, so it works with either model.
  • docs(openspec): propose clipboard paste for plain text and EditorJS payload #191, clipboard paste: it hands selections spanning several inputs back to insertFromPaste, which this change routes through merge({ index }).
• Deviations from v2:
  • Formatting survives a merge between different tools.
  • Text blocks that v2 refused to merge now merge.
  • Blocks without text inputs are removed rather than receiving the caret.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.