# Mermaid diagrams in editable plans should behave like atomic blocks
## Summary
When a planning document renders a Mermaid diagram in editable mode, the rendered diagram should behave like a single diagram block rather than like hidden editable text. Users should be able to select, copy, cut, and delete the diagram as one unit, and ordinary cursor/selection gestures should not silently operate on partial invisible Mermaid source.

## Problem
We recently enabled Mermaid rendering in editable planning documents. This improves readability, but it creates a mismatched editing model:

* the user sees an image-like diagram
* the editor still exposes the underlying Mermaid source text to destructive actions and some selection flows

That mismatch is confusing and unsafe. A diagram that looks like an image should not be partially deleted via hidden text offsets.

## Goals
* Make rendered Mermaid diagrams in editable plans feel like atomic block content.
* Ensure destructive actions act on the entire Mermaid block rather than partial hidden source.
* Ensure pointer and keyboard selection flows do not place users “inside” invisible Mermaid source text during normal editing.
* Preserve the authored Mermaid markdown in storage, export, and copy flows.
* Keep the rendered Mermaid experience visually consistent with the existing notebook/plan block model.

## Non-goals
* Adding a dedicated inline Mermaid source editor for this iteration.
* Changing the rendering theme, zoom behavior, or clipboard image-byte behavior.
* Changing the behavior of ordinary non-Mermaid code blocks.
* Reworking the entire notebook command/block selection model beyond what is needed for rendered Mermaid.

## Figma / design references
Figma: none provided

## User experience
These rules apply to Mermaid diagrams that are visibly rendered inside editable planning documents.

### Atomic selection
* Single-clicking a rendered Mermaid diagram selects the entire diagram block.
* The selected state must be visually obvious and must read as a block selection, not a text cursor placed inside the diagram.
* When a Mermaid block is selected, the selection applies to the whole authored Mermaid block, not just to a subset of its source text.

### Cursor behavior
* Ordinary cursor placement should land before or after a rendered Mermaid diagram, not inside the hidden Mermaid source.
* Keyboard navigation should treat the rendered Mermaid diagram as a boundary in the document flow.
* Users should not be able to end up with a text cursor at an invisible offset in the middle of the Mermaid source through normal pointer or keyboard interactions.
* Vertical keyboard traversal must be symmetric around a rendered Mermaid diagram. If the first `Down` press from the visible cursor position immediately above the diagram crosses that block boundary, the first `Up` press from the visible cursor position immediately below the diagram must also cross into the diagram boundary instead of skipping over it.

### Delete, backspace, and cut
* If a rendered Mermaid diagram is selected as a block, `Delete`, `Backspace`, and cut actions remove the entire Mermaid block.
* “Entire Mermaid block” means the authored fenced Mermaid markdown needed to reconstruct the diagram, not just a substring of the diagram body.
* Undo and redo should restore and remove the diagram atomically.

### Drag and range selection
* If a drag selection, shift-selection, or other range-based text selection crosses a rendered Mermaid diagram, the resulting selection should include the Mermaid diagram as a whole block.
* The editor should not create a partially selected hidden Mermaid source range when the visible interaction crosses the diagram.
* Copying or cutting such a selection should preserve whole-block Mermaid behavior.
* Horizontal `Shift`-selection must use the same Mermaid boundary semantics as plain left/right cursor movement. If `Right` jumps across a rendered Mermaid block atomically, `Shift+Right` must expand across that same block atomically, and `Shift+Left` must shrink back across it on the next keypress.
* Vertical `Shift`-selection across a rendered Mermaid diagram must be reversible from both sides of the block. After expanding a selection with `Shift+Up` or `Shift+Down`, pressing the opposite arrow while `Shift` remains held must shrink the selection back across that Mermaid boundary on the very next keypress.

### Copy behavior
* Copying a selected Mermaid block should place the full authored Mermaid fenced block in plain text so that pasting into markdown reconstructs the diagram.
* When HTML clipboard output is available, the copied content may also include the rendered diagram representation in HTML.
* Direct image-byte clipboard support remains out of scope.

### Storage and export
* Planning documents must continue to store and export the original Mermaid markdown rather than persisting the rendered image.
* This feature changes editing semantics, not the saved document format.

### Scope
* This behavior is required for editable planning documents and plan-backed notebook surfaces where Mermaid is rendered.
* If Mermaid rendering is disabled and the raw code block is shown instead, existing raw markdown editing behavior may remain unchanged.

## Success criteria
* Clicking a rendered Mermaid diagram in an editable plan selects the whole diagram block.
* Users cannot accidentally delete only part of an invisible Mermaid source block through normal editing flows.
* `Backspace`, `Delete`, cut, undo, and redo operate on rendered Mermaid diagrams atomically.
* Copying a selected Mermaid block preserves the authored Mermaid markdown in plain text.
* Crossing a Mermaid diagram with drag or shift-based selection results in whole-block behavior rather than partial invisible-source behavior.
* Horizontal left/right movement and horizontal `Shift`-selection use the same atomic Mermaid crossings in both directions, including when reversing an in-progress selection.
* Vertical movement and vertical `Shift`-selection around a Mermaid block are symmetric and reversible from both the above-diagram and below-diagram cursor positions.
* The document still round-trips as raw Mermaid markdown when saved or exported.

## Validation
* Add focused editor-model tests for Mermaid block selection, delete/backspace behavior, cut behavior, copy behavior, and undo/redo behavior.
* Add coverage for range-selection flows that cross a rendered Mermaid block.
* Add hit-testing or selection tests that verify cursor/selection resolution does not land inside hidden Mermaid source offsets during normal rendered interactions.
* Add focused keyboard-selection tests that verify `Shift+Left` / `Shift+Right` reuse the same atomic Mermaid crossings as `Left` / `Right`, including reversing an expanded selection from either side of the block.
* Add focused keyboard-navigation tests that verify `Up`/`Down` and `Shift+Up`/`Shift+Down` behave symmetrically around rendered Mermaid blocks.
* Manually verify in an editable plan that:
  * clicking selects the whole diagram
  * delete/backspace remove the whole diagram
  * copy produces whole Mermaid markdown
  * drag/range selection does not partially select invisible source

## Open questions
* Do we want a dedicated follow-up affordance for explicitly editing Mermaid source while rendered mode is active, or is block-level delete/reinsert sufficient for now?