docs(block-editing): design spec for nesting-cursor UI enhancements

Design for three follow-on UI enhancements to the nesting cursor, plus a
mechanical "locked tile" -> "outer block" rename sequenced first:

- Geometry snapshot: size nest-move destinations from the block subtree's
  original rendered geometry (captured pre-swap), not the edit-distorted
  live DOM. Block-relative keys with a derived topBlockR0 (self-heal-robust).
- Caret-aware nest-in: descend toward the caret's surface via line-anchoring
  against the untransformed AST; commit-if-dirty unifies with the reland path.
- Mode-aware activation highlight: locked-mode hover/focus shows the outer
  block that activates; roving-tabindex made mode-aware to match.

Captures both reflection passes, risks, and the TDD checklist. q2-preview
iframe-side only; no Rust/WASM change.

Author: gordonwoodhull

claude-notes/plans/2026-06-14-nesting-cursor-ui-enhancements.md

@@ -0,0 +1,271 @@
+# Nesting-cursor UI enhancements — geometry snapshot, caret-aware nest-in, mode-aware highlight
+
+**Date:** 2026-06-14
+**Branch:** feature/block-editing-improvements (worktree `.worktrees/block-editing`)
+**Builds on:** `2026-06-11-block-editing-improvements.md` (the nesting-cursor / outer-block
+editor, Phases 1–3.5, all done). Same machinery; this plan is a follow-on set of UI
+enhancements + one mechanical rename, all q2-preview-only.
+**Status:** Design settled through two reflection passes (see *Reflections* below).
+All cross-feature ambiguities resolved with the user. TDD-first; ready to expand into the
+per-phase checklist.
+
+## Overview
+
+Three UI enhancements to the (already shipped) nesting cursor, plus a vocabulary rename
+sequenced first:
+
+0. **Rename "locked tile" → "outer block"** — a pure mechanical rename, committed before any
+   feature work, so the features are written in the final vocabulary.
+1. **Geometry snapshot** — fix wrong editing-surface sizes when moving the nesting cursor
+   in/out. Capture the original rendered geometry of a multilevel block's whole subtree at
+   activation (before the textarea swap) and size nest-move destinations from that snapshot
+   instead of the edit-distorted live DOM.
+2. **Caret-aware nest-in** — nest-in descends toward the surface the **caret** is in, not a
+   frozen "first clicked leaf". Implemented in line space against the untransformed AST.
+3. **Mode-aware activation indicators** — in locked mode the hover/focus highlight shows the
+   **outer block** that will actually activate (not the deepest leaf); roving-tabindex becomes
+   mode-aware to match.
+
+All three are gated behind the existing `unlockNestingCursor` preference except Feature 3's
+locked-mode highlight change (which improves the *default* locked experience).
+
+## Background / where the machinery lives
+
+Citations are post-rename names; the rename mapping is in §0. Current tree (pre-rename) uses
+`lockedTiles.ts` / `resolveLockedTile` / etc.
+
+- **Activation** — `useBlockEditHover.tsx`: `activate(el)` (`:59`) resolves the click mode-aware
+  (leaf in unlocked, `resolveOuterBlock` in locked), captures the identity triple
+  (`captureEditTarget`), measures the box (`measureBlockBox`), seeds the draft, and calls
+  `setEditTarget`. Hover outline is `box-shadow` set in `outlineElement` (`:49`) off
+  `findEditTarget` = `closest('[data-block-pool-id]')` (the deepest leaf — **the Feature-3
+  bug**). Roving-tabindex `onKeyDown` (`:227`) focuses `enumerateOuterBlocks` **unconditionally**
+  (**the Feature-3 follow-on**).
+- **Edit substitution** — `dispatchers.tsx`: `renderMeasuredEdit` (`:47`) replaces the *entire*
+  matched subtree with a synthetic `<div id="q2-active-edit-region">` (ref =
+  `activeEditRegionRef`) sized by `editTarget.contentHeight`/`boxStyle`. The nesting chord is
+  handled in `EditTextarea`'s `onKeyDown` (`:281`) via `classifyNestingKey` → `requestNestingMove`.
+  `LEFT_INSET_STRIPPED_TYPES` (`:60`) zeroes left margin/pad/border for list/quote types.
+- **Nest moves** — `PreviewRoot.tsx`: `requestNestingMove(dir)` (`:780`) → `applyNestingRetarget`
+  (`:742`); the latter reseeds the draft from the destination buffer and re-anchors `editTarget`,
+  measuring the destination box via `outerBlockForAnchorR0(... {exactOnly:true})` →
+  `measureBlockBox`, **else keeping the current box** (`:752-753`, the stale fallback — **the
+  Feature-1 bug**). `requestNestingSelect(r0,r1)` (`:794`) is the breadcrumb crumb-jump; both share
+  `applyNestingRetarget`. `pendingCaretRef` is set `null` on nest moves (`:762`).
+- **Nesting surfaces** — `nestingNav.ts`: `buildNestingSurfaces(sourceIndex)` (`:62`) → sorted
+  `{r0,r1}[]`; `parentSurface` (`:103`) / `childSurfaceToward` (`:147`) navigate by **byte
+  containment** (`childSurfaceToward` uses an **exclusive** end, `:165`). `buildAncestorPath` (`:307`)
+  builds the breadcrumb path from the **live cursor** (`anchorR0/R1`). No geometry anywhere —
+  surfaces are pure source coordinates.
+- **Breadcrumb** — `BreadcrumbChip.tsx`: keys off `et.anchorR0/R1` (`:44`), repositions on
+  `anchorR0/R1` change (`:40`) — already re-derives on every cursor move.
+- **Cross-surface move / reland** — `PreviewRoot.tsx`: the Phase-2 arrow move uses
+  `pendingLanding {intent, destLine, …}` (`:301`), commits when dirty, and re-resolves the
+  destination post-render by **line** (`map.lineOf`, via `utils/byteLineMap.ts`). Nest moves
+  (Feature 2, commit-if-dirty) **reuse this infrastructure** with a nest-specific resolution.
+- **Self-heal** — `PreviewRoot.tsx:244-285`: on an external re-render, `findReanchorCandidate`
+  re-anchors `anchorR0/R1` by content-verification (KEEP) or closes the editor (DROP). Keeps the
+  box on KEEP.
+
+---
+
+## §0 — Rename: "locked tile" → "outer block"
+
+The concept "which near-top block activates in locked mode" is currently called a **locked
+tile**. Rename to **outer block** (reads against the mode pair: *locked mode activates outer
+blocks; nesting mode descends to inner/leaf surfaces*). **One mechanical commit, first**, mirroring
+the prior depth→nesting rename (`16382ff2`). No behavior change.
+
+| Current | New |
+| --- | --- |
+| `lockedTiles.ts` (+ `lockedTiles.integration.test.ts`, `lockedTiles-p2-3b.integration.test.ts`) | `outerBlocks.ts` (+ matching test files) |
+| `resolveLockedTile` | `resolveOuterBlock` |
+| `enumerateLockedTiles` | `enumerateOuterBlocks` |
+| `tileForAnchorR0` | `outerBlockForAnchorR0` |
+| `measureTileBox` *(mode-neutral)* | `measureBlockBox` |
+| `isVisibleTile` *(mode-neutral)* | `isVisibleBlock` |
+| "locked tile" in comments/docs, test vars (`tileA`, `destTile`, `mockTileRects`, …) | "outer block" / `outerBlockA`, `destBlock`, `mockBlockRects`, … |
+
+`measureBlockBox` / `isVisibleBlock` drop "tile" rather than gain "outer" because they operate on
+*any* surface (nesting-mode leaves included). New symbols added by Features 1–2
+(`snapshotOuterBlockGeometry`, `childSurfaceTowardLine`, `enumerateNestingLeaves`) are authored
+with final names in the renamed files.
+
+---
+
+## §1 — Geometry snapshot for nesting-cursor moves
+
+### The bug
+The nest-move destination box is measured from the **live DOM at move time**, but during an
+open editing session the active subtree is a synthetic textarea, so the destination surface is
+distorted (nest-out: parent contains a textarea, not the real child) or absent (nest-in: the
+child isn't rendered at all → `applyNestingRetarget` keeps the stale parent box). `PreviewRoot.tsx:751`
+even documents the gap ("real box fidelity for 'in'/jumps is P3.5").
+
+### The fix
+Capture the original rendered geometry of the whole top-level block's subtree **at activation,
+before the swap**, keyed by source identity, and have nest moves size from that snapshot.
+
+**Capture (`snapshotOuterBlockGeometry`)** — a new pure helper in `outerBlocks.ts`:
+1. From the opened element, climb to the outermost `[data-block-pool-id]` (the top-level block),
+   reusing the chain-walk in `resolveOuterBlock`.
+2. If the subtree has **≤ 1** visible `[data-block-pool-id]` (a flat block) → return empty (no
+   nesting possible; the single `measureBlockBox` at open already sizes it).
+3. Otherwise `querySelectorAll('[data-block-pool-id]')` within it, filter to visible, and
+   `measureBlockBox` each. Key each by **block-relative r0** (`pool[id].r[0] − topBlockR0`); value
+   = `{contentHeight, boxStyle}`.
+
+**`topBlockR0` is derived, not stored** — the outermost `NestingSurface` containing the active
+range (climb `parentSurface` to `null`). Computed from the *same* source index at both capture and
+lookup, so block-relative keys are **shift-invariant under an insert-above** with no re-keying and
+no `editTarget` field. (Off-path-internal edits remain best-effort — documented.)
+
+**Where capture runs** — at **every fresh editor-open**, synchronously *before* `setEditTargetRaw`
+(a post-open effect is too late; the children are already swapped out):
+- `activate()` (`useBlockEditHover.tsx`),
+- the Phase-2 reland opens (`PreviewRoot.tsx:388`, `:479`) and click-switch (`:387`).
+Only `applyNestingRetarget` **consumes** the snapshot; the Phase-2 opens still measure their own
+(rendered) outer-block destination live — `snapshot[thatBlock]` equals that live measure anyway.
+
+**Consume** — `applyNestingRetarget` replaces the live-DOM measure block (`:752-761`) with a
+snapshot lookup keyed by `next.r0 − topBlockR0(current)`. Fallback to today's best-effort if the
+key is missing (jsdom/no-layout, or an unrendered surface).
+
+**Lifecycle** — `editGeometryRef: Map<number, {contentHeight, boxStyle}>` on `PreviewRoot`. Written
+at each open; **kept** across self-heal KEEP (keys stay valid); **cleared** when `editTarget → null`
+(the `setEditTarget(null)` wrapper, `:191`).
+
+**Gating** — only captured when `unlockNestingCursor` is on AND the block is multilevel. Locked
+default and flat blocks: zero cost.
+
+**Validation insight:** `snapshot[surface]` is *by construction* identical to the box a direct
+click on that surface would produce (both measure the same element in the same pre-swap DOM). So
+"nest-in to item 3" reproduces "click item 3", which is already correct.
+
+---
+
+## §2 — Caret-aware nest-in
+
+### Behavior
+Nest-in descends toward the surface the **live caret** is in (not the frozen `leafAnchorR0`). The
+live cursor + caret are the **single source of truth**; the breadcrumb re-derives from the cursor
+each render and stays consistent.
+
+### Mechanism — line space end to end
+- **Caret → source line:** `selectionStart` → buffer line `Lb` (count `\n` before caret) →
+  `sourceLine Ls = lineOf(cursorR0) + Lb`. This holds for **both** draft kinds: a verbatim slice
+  trivially preserves lines, and a regenerated clean buffer strips `> `/indent **per line**, which
+  preserves line count and order.
+- **Source line → child:** new pure `childSurfaceTowardLine(surfaces, cursorR0, cursorR1, Ls, map)`
+  picks the direct child whose **line span** `[lineOf(r0), lineOf(r1)]` contains `Ls`. Line space
+  sidesteps the `> `/indent prefix (which only shifts *columns*) and `childSurfaceToward`'s
+  exclusive-end byte containment. Fallback (caret on a no-child line, e.g. a blockquote `>`
+  separator): nearest direct child by line distance.
+- **Line-count mismatch → warn-and-proceed:** if `draft` line count ≠ the cursor node's source
+  line count, `console.warn(siKey, draftLines, sourceLines)` and **still** use line-anchoring
+  (better than collapsing to line 1; a real reflow regression stays visible).
+
+### Caret reading — centralized
+`requestNestingMove('in')` reads the live textarea itself via
+`activeEditRegionRef.current?.querySelector('textarea')` (`selectionStart` survives the breadcrumb
+button click), so the keyboard chord (`dispatchers.tsx`) and the `▶` button
+(`BreadcrumbChip.tsx`) share one source of truth — no signature change.
+
+### Round-trip caret placement (consistency)
+Reusing `pendingCaretRef` + `caretGeometry`:
+- **nest-in:** place the caret in the child's reseeded draft at `draftLine = Ls − lineOf(childR0)`.
+- **nest-out:** place the caret at the **exited child's** line in the parent draft, so an immediate
+  nest-in returns to the same child (not the first).
+Without this, `pendingCaretRef = null` defaults the caret to the top and out-then-in jumps to the
+first child.
+
+### `leafAnchorR0`
+Demoted to a pure fallback (no readable caret / programmatic). The P3.4 "crumb-jump preserves the
+original leaf" test (test 6) is **updated** to the caret model: after a crumb jump, the next
+nest-in follows the caret.
+
+### Commit-if-dirty, then nest (unifies with the move/reland path)
+A nest move while the buffer is dirty must **not** discard edits (today `applyNestingRetarget`
+reseeds with no commit — a data-loss footgun, worsened by caret-aware nest-in). Mirror the Phase-2
+arrow-move:
+- **Unmodified** → synchronous hop: resolve via the snapshot box, no commit, no re-render.
+- **Modified** → commit (`SET_AST`), stash a **nest-variant `pendingLanding`** keyed by the caret's
+  **source line** + direction, re-resolve the destination **post-render by line-containment** in
+  the new source index, then open (live-measure + fresh snapshot). Round-trip caret line projects
+  through the commit like `destLine`.
+- Caveat (carried over): committing at the list level reformats/renumbers the whole list (the
+  existing wholesale-container-rewrite risk).
+
+---
+
+## §3 — Mode-aware activation indicators
+
+### Hover / touch outline (the reported bug)
+The outline highlights the deepest leaf, but locked-mode click activates the **outer block** —
+the highlight promises a granularity the click doesn't deliver. Make the outline use the same mode
+branch `activate()` and the click-switch already use:
+- **Locked:** `resolveOuterBlock(el)` — highlight the whole list/blockquote/coincident wrapper.
+- **Nesting:** unchanged — the leaf (`closest('[data-block-pool-id]')`).
+Two call sites: `onPointerMove` mouse hover (`:128`) and the touch branch of `onPointerDown` (`:178`).
+Dedupe by comparing the *resolved* element (and only re-resolve when the raw leaf changes, to keep
+`pointermove` cheap).
+
+### Roving-tabindex (follow-on for consistency)
+`onKeyDown` (`:227`) focuses `enumerateOuterBlocks` unconditionally, so after the hover fix mouse
+and keyboard would disagree in nesting mode. Make it mode-aware:
+- **Locked:** `enumerateOuterBlocks` (today).
+- **Nesting:** new pure `enumerateNestingLeaves(host)` (visible `[data-block-pool-id]` with no
+  pool-id descendant), so arrows focus/activate the same leaves mouse does.
+
+---
+
+## Reflections (resolved)
+
+1. **Snapshot must capture at all fresh-open sites, synchronously pre-swap** — not just
+   `activate()`. (§1 *Where capture runs*.)
+2. **`topBlockR0` derived, not stored** — simpler than store+re-anchor; shift-invariant keys. (§1.)
+3. **Caret→child in line space via a new helper** — `childSurfaceToward`'s exclusive-end byte
+   containment misfires on the prefix. (§2.)
+4. **Caret reading centralized in `requestNestingMove`.** (§2.)
+5. **Caret-driven nest-in vs. breadcrumb invariant** → caret wins; breadcrumb re-derives from the
+   live cursor (already structural); P3.4 test updated. (§2.)
+6. **Roving-tabindex made mode-aware** to match Feature 3. (§3.)
+7. **Round-trip caret placement** is the concrete mechanism that makes in/out consistent. (§2.)
+8. **Nest-move-while-dirty discarded edits** → commit-if-dirty, unifying with the reland path. (§2.)
+9. **Snapshot == direct-click box by construction** — de-risks Feature 1. (§1.)
+10. **Snapshot ↔ nesting-surface alignment** (DOM pool-id set == source-index non-Opaque set) is an
+    assumption — add a regression test (a nested list/blockquote).
+
+## Risks / watch-items
+- **Snapshot capture cost** — `getComputedStyle` + `getBoundingClientRect` per surface, once per
+  activation, gated to unlock+multilevel. Fine now; watch on pathologically large blocks.
+- **Hover re-resolution cost** — `resolveOuterBlock` per `pointermove` (coincidence rect-climb);
+  deduped by raw-leaf change.
+- **Off-path-internal concurrent edit** — block-relative keys (and a re-anchored cursor) can be
+  stale for surfaces after an in-block sibling edit; best-effort fallback. Bounded; documented.
+- **Wholesale container rewrite on a dirty list-level commit** — unchanged Phase-3 risk; snapshot
+  never byte-asserts siblings.
+- **Line-count mismatch (reflow)** — warn-and-proceed; the warning surfaces a real regression.
+
+## Verification
+- **jsdom/RTL:** snapshot capture + consume (mock `getBoundingClientRect` per surface, the existing
+  `mockBlockRects` pattern); `childSurfaceTowardLine`; mode-aware outline + roving; commit-if-dirty
+  nest reland; surface/pool alignment. Fail-on-revert on each behavior lever.
+- **Playwright (`hub-client/e2e`):** the real-pixel confirmation of the two reported cases — nested
+  list, click sublist → nest-out covers full parent+child; click parent → nest-in sizes to one
+  item; caret on item 3 → nest-in opens item 3; locked hover highlights the whole list. (jsdom has
+  no layout; this is the genuine end-to-end tier, as in Phase 3.5.)
+- **Rust/WASM:** none — all three features are iframe-side TS. (The regenerated-buffer line-count
+  property relies on the existing per-line `> `/indent strip; no writer change.)
+
+## TDD checklist (to expand via writing-plans)
+- [ ] **§0 Rename** (mechanical, first commit) — `outerBlocks.ts` + symbol/test-var sweep; green
+  build + suites; no behavior delta.
+- [ ] **§1 Geometry snapshot** — capture helper + gating + lifecycle; derive `topBlockR0`; consume
+  in `applyNestingRetarget`; capture at all open sites; self-heal KEEP keeps keys valid; alignment
+  test; Playwright pixel check.
+- [ ] **§2 Caret-aware nest-in** — `childSurfaceTowardLine`; caret→source-line; centralized caret
+  read; warn-and-proceed; round-trip caret placement; `leafAnchorR0` fallback + P3.4 test update;
+  commit-if-dirty reland (nest-variant `pendingLanding`); Playwright caret check.
+- [ ] **§3 Mode-aware indicators** — mode-aware outline (mouse + touch); `enumerateNestingLeaves` +
+  mode-aware roving; dedupe; Playwright locked-hover check.