fix(preview): block-editing glitches round 3 (G20–G22)

G20: nested list-item editor height uses the range's first client rect, not the
bounding union, so the editor matches the rendered line. G21: committing a nested
item keeps focus on the edited surface (mode-aware refocusTargetForAnchorR0) instead
of jumping to the next block. G22: commit-status bulb + commit-error routing in the
preview. Includes the boundary-splice design, the G20–G22 clean-slate spec, and the
hub-client changelog.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gordonwoodhull

claude-notes/plans/2026-06-18-block-editing-glitches-3.md

@@ -0,0 +1,113 @@
+# Item plane — research-level plan (DEFERRED)
+
+**Date:** 2026-06-19
+**Branch:** TBD (follow-on to `feature/block-editing-improvements`)
+**Status:** RESEARCH / DEFERRED — not scheduled. Sibling of the **block plane**
+(`2026-06-18-boundary-splice-edit-design.md` + `2026-06-19-boundary-splice-implementation.md`).
+
+> This is a research stub, not an implementation plan. It captures the problem,
+> the open design questions, and rough estimates so the work can be picked up
+> cleanly. Do **not** start implementing from this file — it must first go
+> through brainstorming → spec → implementation plan like the block plane did.
+
+## What the item plane is
+
+The block plane splices **`Block`s within a `Blocks` slice** (`Vec<Block>`). The
+item plane splices the *other* element type that lists/tables/def-lists are built
+from:
+
+```rust
+BulletList  { content: Vec<Vec<Block>> }                        // elements: ITEMS (Vec<Block>)
+OrderedList { content: Vec<Vec<Block>>, .. }
+DefinitionList { content: Vec<(Vec<Inline> /*term*/, Vec<Vec<Block>> /*bodies*/)> }
+Table { ... rows of cells ... }                                 // elements: ROWS
+```
+
+Operations: **insert / move / delete an item** (list item, table row, def-list
+entry) — splices on `Vec<Vec<Block>>` (or the table row vector), not on a
+`Blocks` slice. "Add a kanban card", "drag a card to position 4", "add a row",
+"add a definition" all live here.
+
+## Why it was split out of the block plane (decided 2026-06-19)
+
+- **Different element type.** A list item is `Vec<Block>`, not a `Block`. The
+  block plane's `splice_range` operates on `Vec<Block>`; items are one level up.
+- **Different content shape.** A new item's payload is "the blocks that make up
+  the item" — and multi-item inserts need item delimiting. The block plane's
+  `Content` (`md`/`ast` → blocks) does not express "these blocks form item k,
+  those form item k+1".
+- **It is the only thing that wanted a positional slot among sibling item-slices**
+  — i.e. the positional `item`/`(def,body)` coordinates we deliberately kept out
+  of the block plane's `ContainerRef`. Putting them here keeps the block plane
+  fully SI-addressed and index-free.
+- **No current consumer needs a primitive.** Today: typed list editing goes
+  through the text channel (qmd reparse builds items for free); `kanban.tsx`
+  reorders via `replaceNode`-the-whole-list. So the item plane is real future
+  work, not blocking.
+
+## How it composes with the block plane (additivity check)
+
+The split is additive. The item plane adds its **own boundary family** over
+item-arrays; it does not change the block plane's `Boundary`/`ContainerRef`. A
+gesture that fills a freshly-inserted item is "insert item *with content*" (one
+item-plane op), not "insert empty item then block-splice into it" — so the block
+plane never needs `listItem`/`defBody` back.
+
+Sketch (to be designed, not final):
+
+```
+ItemBoundary = beforeItem(listSi, k) | afterItem(listSi, k)
+             | startOfList(listSi)   | endOfList(listSi)        // gap 0 / item-count
+ItemContent  = md(...) parsed as items | items(blockGroups...)   // shape TBD
+insertItemAt(listSi, k, itemContent)  // { from: beforeItem(listSi,k), to: ..., itemContent }
+moveItem(listSi, from, to)            // delete + insert, or a dedicated op
+```
+
+`listSi` SI-matches the specific (possibly nested) list at any depth — depth is
+absorbed by SI exactly as in the block plane; only *one* shallow index per list
+level, never a root path.
+
+## Open design questions (the research)
+
+1. **Item content shape (the hard one).** How does `md('- a\n- b')` map to
+   *items*? How does the `ast` form express "two items"? Single- vs multi-item
+   payloads and delimiting. Does it reuse `Content` or get its own type?
+2. **Tight vs loose lists.** Inserting into a tight list must stay tight — the
+   item-level analog of the block plane's `preserve_leaf_variant` (Plain↔Para).
+   How is tight/loose detected and preserved on insert?
+3. **Ordered-list semantics.** Renumbering, `start`/`style`/`delim` interaction
+   with the incremental writer when items are inserted/removed/reordered.
+4. **Scope: which containers.** Bullet/ordered lists first? Then def-list entries
+   (need a *term*, and bodies are `Vec<Vec<Block>>` — two coordinates) and table
+   rows (fixed column count → row shape validation). Each is its own sub-design.
+5. **Reconciler/writer behavior.** Confirm `compute_reconciliation` handles item
+   count changes cleanly (the `list_*_produces_correct_length` tests in
+   `quarto-ast-reconcile` suggest yes) and that the incremental writer's
+   whole-list re-serialization is acceptable (it is the same nested-edit behavior
+   the block plane already accepts).
+6. **Move semantics.** Is "move item" a first-class op (so reconciliation can
+   keep source fidelity of the moved item) or just delete+insert? Relevant to
+   kanban drag.
+7. **Frontend coordinates.** A list-level component (kanban) has `itemIndex`
+   positionally; a component nested *inside* an item does not (item indices are
+   render-time-local — confirmed 2026-06-19). Decide whether to expose item
+   indices via context, or keep item-plane gestures list-level only.
+
+## Rough estimates (ideal hours, assuming the block plane is in place)
+
+| Scope | Planning | Engineering |
+|---|---|---|
+| Bullet/ordered lists | 3–5h | 8–14h |
+| + def-list entries + table rows | +2–3h | +8–12h |
+
+Biggest swing risks: the **item content shape** (Q1), **tight/loose + ordered
+renumbering** (Q2/Q3), and whether migrating `kanban.tsx` from `replaceNode` to
+item-moves surfaces reconciler quirks (Q5/Q6).
+
+## Entry criteria
+
+Pick this up when a real gesture needs a structural item primitive (e.g. kanban
+drag wanting surgical item moves instead of whole-list `replaceNode`, or a
+nesting-cursor "new list item" that we decide should be structural rather than
+text-reparse). Until then it stays deferred. Start with brainstorming (the
+content shape, Q1, deserves a real design pass), not with code.

claude-notes/plans/2026-06-18-boundary-splice-edit-design.md

@@ -15,6 +15,10 @@ be in reverse chronological order (latest first).
 
 -->
 
+### 2026-06-19
+
+- [`c38ca41b`](https://github.com/quarto-dev/q2/commits/c38ca41b): Block-editing fixes (G20–G22): the in-place editor for a nested list item no longer opens taller than the line it replaces; committing a nested-item edit now keeps the edited node selected instead of jumping focus to the next block; and a new commit-status indicator shows whether each edit was a real change or a spurious no-op, surfacing edit errors in the preview.
+
 ### 2026-06-18
 
 - [`8f6d5a0c`](https://github.com/quarto-dev/q2/commits/8f6d5a0c): Block-editing fixes (G14–G19): the nesting cursor is now ON by default; single-line editors no longer inflate to two lines on expand; down-arrow steps correctly out of a blockquote-wrapped loose list; clicking between items reliably activates on the first click with nesting kept live; a stuck "blur the cell you left" effect now always clears; and a spurious no-op write when clicking off an untouched nested block is eliminated.

claude-notes/plans/2026-06-19-boundary-splice-implementation.md

@@ -1,4 +1,5 @@
 import { useState, useCallback, useRef, useEffect, useMemo } from 'react';
+import type { CSSProperties } from 'react';
 import type * as Monaco from 'monaco-editor';
 import type { FileEntry } from '@quarto/preview-renderer/types/project';
 import type { Diagnostic, PreviewNodeEditPayload } from '@quarto/preview-renderer/types/diagnostic';
@@ -281,6 +282,113 @@ async function doRender(
   }
 }
 
+// Exported for unit test. SPURIOUS = the edit round-tripped to identical QMD.
+export function classifyCommitOutcome(
+  newQmd: string,
+  renderedContent: string,
+): 'change' | 'spurious' {
+  return newQmd === renderedContent ? 'spurious' : 'change';
+}
+
+/**
+ * G22: commit-status indicator — a translucent "glass" status dot in the
+ * preview's bottom-right corner that glows out of the page and fades to nothing.
+ *
+ *   pending  → amber  (commit going out)
+ *   change   → green  (real diff written)
+ *   spurious → blue   (no-op round-trip — the false-dirty bug class)
+ *   error    → (not lit here; the error pill takes over the corner)
+ *
+ * Modern / non-skeuomorphic: no bezel, no fixture, no persistence. The dot is
+ * defined by LIGHT not by a housing — a colored radial bloom, a thin colored
+ * glass rim, and a `backdrop-filter` refraction — so it reads on a white page
+ * now and on a dark background later. Idle → opacity 0 (gone). Lit states bloom
+ * in (scale + fade) and dim back out; only the attention state (blue) pulses.
+ */
+const COMMIT_BULB_CSS = `
+@keyframes q2-bulb-pulse {
+  0%, 100% { opacity: 0.84; }
+  50% { opacity: 1; }
+}
+.q2-commit-bulb {
+  position: absolute;
+  /* Sits in the bottom-right corner where the error pill appears, so on error
+     the pill visually replaces the bulb. */
+  bottom: 20px;
+  right: 20px;
+  width: 13px;
+  height: 13px;
+  border-radius: 50%;
+  background: radial-gradient(circle at 50% 45%, var(--c-bright) 0%, var(--c-soft) 58%, transparent 100%);
+  border: 1px solid var(--c-rim);
+  backdrop-filter: blur(3px) saturate(1.4);
+  -webkit-backdrop-filter: blur(3px) saturate(1.4);
+  box-shadow: 0 0 var(--c-glow-blur) var(--c-glow-spread) var(--c-glow);
+  opacity: var(--bulb-opacity);
+  transform: scale(var(--bulb-scale));
+  transition:
+    opacity 300ms ease,
+    box-shadow 220ms ease,
+    background 220ms ease,
+    border-color 220ms ease,
+    transform 300ms cubic-bezier(0.2, 0.7, 0.3, 1.3);
+  pointer-events: none;
+  z-index: 50;
+  will-change: opacity, transform;
+}
+/* Gentle, slow breath — only the attention state (blue) pulses. */
+.q2-commit-bulb[data-pulse="1"] { animation: q2-bulb-pulse 1.5s ease-in-out infinite; }
+`;
+
+export function CommitStatusBulb({
+  status,
+}: {
+  status: 'idle' | 'pending' | 'change' | 'spurious' | 'error';
+}) {
+  // RGB triples + per-state "loudness" — green (a normal change) is quiet; blue
+  // (spurious) glows harder, pulses, and lingers so it pulls the eye. Derived
+  // from one hue so it carries to light and dark backgrounds.
+  //
+  // 'error' is intentionally NOT lit here: on error the bulb hands off to the
+  // error pill (PreviewErrorOverlay), which appears in the same corner — see the
+  // render below where the bulb is suppressed while a commit error is showing.
+  const PALETTE: Record<
+    'pending' | 'change' | 'spurious',
+    { rgb: string; glowA: number; blur: string; spread: string; pulse: boolean; title: string }
+  > = {
+    pending: { rgb: '255,160,30', glowA: 0.42, blur: '9px', spread: '0px', pulse: false, title: 'Committing…' },
+    change: { rgb: '40,200,100', glowA: 0.36, blur: '8px', spread: '0px', pulse: false, title: 'Change committed' },
+    spurious: { rgb: '60,140,255', glowA: 0.6, blur: '13px', spread: '1px', pulse: true, title: 'No change (spurious edit)' },
+  };
+  const on = status === 'pending' || status === 'change' || status === 'spurious';
+  const p = on ? PALETTE[status] : null;
+  const rgb = p?.rgb ?? '128,128,128';
+  return (
+    <>
+      <style>{COMMIT_BULB_CSS}</style>
+      <div
+        className="q2-commit-bulb"
+        data-pulse={p?.pulse ? '1' : undefined}
+        title={p?.title}
+        style={
+          {
+            '--c-bright': `rgba(${rgb},0.92)`,
+            '--c-soft': `rgba(${rgb},0.30)`,
+            '--c-rim': `rgba(${rgb},0.55)`,
+            '--c-glow': `rgba(${rgb},${p?.glowA ?? 0})`,
+            '--c-glow-blur': p?.blur ?? '0px',
+            '--c-glow-spread': p?.spread ?? '0px',
+            // No persistence: idle fades to nothing and shrinks slightly so lit
+            // states bloom back in.
+            '--bulb-opacity': on ? 1 : 0,
+            '--bulb-scale': on ? 1 : 0.55,
+          } as CSSProperties
+        }
+      />
+    </>
+  );
+}
+
 export default function ReactPreview({
   content,
   currentFile,
@@ -391,6 +499,51 @@ export default function ReactPreview({
   const renderTimeoutRef = useRef<number | null>(null);
   const lastContentRef = useRef<string>('');
 
+  // G22: commit-status indicator. Every commit channel (text / subtree /
+  // nesting) funnels through handleSetAst, so we classify the outcome there and
+  // drive ONE bulb overlay from a single status state — no per-site plumbing.
+  const [commitStatus, setCommitStatus] = useState<
+    'idle' | 'pending' | 'change' | 'spurious' | 'error'
+  >('idle');
+  const commitStatusTimerRef = useRef<number | null>(null);
+  const commitPendingSinceRef = useRef<number>(0);
+  // G22: the message for a rejected commit, surfaced in the existing
+  // PreviewErrorOverlay. Persists until the next SUCCESSFUL commit.
+  const [commitError, setCommitError] = useState<string | null>(null);
+
+  // Light the bulb amber when a commit goes out.
+  const beginCommitStatus = useCallback(() => {
+    if (commitStatusTimerRef.current !== null) clearTimeout(commitStatusTimerRef.current);
+    commitPendingSinceRef.current = Date.now();
+    setCommitStatus('pending');
+  }, []);
+
+  // applyNodeEdit is synchronous, so hold 'pending' a minimum so it is visible,
+  // then flip to the result colour, then auto-clear to idle.
+  const settleCommitStatus = useCallback(
+    (result: 'change' | 'spurious' | 'error') => {
+      const MIN_PENDING_MS = 200;
+      // Loudness via dwell time: a normal change blinks briefly; a spurious /
+      // rejected commit lingers longer so it draws the eye.
+      const HOLD_MS = { change: 450, spurious: 1100, error: 1700 }[result];
+      const elapsed = Date.now() - commitPendingSinceRef.current;
+      const delay = Math.max(0, MIN_PENDING_MS - elapsed);
+      if (commitStatusTimerRef.current !== null) clearTimeout(commitStatusTimerRef.current);
+      commitStatusTimerRef.current = window.setTimeout(() => {
+        setCommitStatus(result);
+        commitStatusTimerRef.current = window.setTimeout(() => {
+          setCommitStatus('idle');
+          commitStatusTimerRef.current = null;
+        }, HOLD_MS);
+      }, delay);
+    },
+    [],
+  );
+
+  useEffect(() => () => {
+    if (commitStatusTimerRef.current !== null) clearTimeout(commitStatusTimerRef.current);
+  }, []);
+
   // Handler for cross-document navigation
   const handleNavigateToDocument = useCallback(
     (targetPath: string, anchor: string | null) => {
@@ -522,13 +675,17 @@ export default function ReactPreview({
           );
           return;
         }
+        // G22: a commit is going out — light the bulb amber.
+        beginCommitStatus();
         try {
           let modifiedSubtreeJson: string;
           if (edit.channel === 'text') {
             // Text channel: parse raw QMD → Pandoc JSON → apply_node_edit.
             const parseResult = parseQmdContentSync(edit.newText);
             if (!parseResult.success || !parseResult.ast) {
               console.error('parse_qmd_content failed:', parseResult.error);
+              settleCommitStatus('error'); // G22: parse rejected
+              setCommitError(`Edit could not be parsed: ${parseResult.error ?? 'unknown error'}`);
               return;
             }
             modifiedSubtreeJson = parseResult.ast;
@@ -544,9 +701,15 @@ export default function ReactPreview({
             edit.destinationSourceInfoJson,
             modifiedSubtreeJson,
           );
+          // G22: a commit that round-trips to identical QMD is a SPURIOUS edit
+          // (the false-dirty bug class) — surface it instead of silently writing.
+          settleCommitStatus(classifyCommitOutcome(newQmd, rendered.renderedContent));
+          setCommitError(null); // G22: a successful commit clears the prior error
           onContentRewrite(newQmd);
         } catch (err) {
           console.error('apply_node_edit failed:', err);
+          settleCommitStatus('error'); // G22: apply rejected
+          setCommitError(`Edit could not be applied: ${err instanceof Error ? err.message : String(err)}`);
         }
         return;
       }
@@ -557,11 +720,14 @@ export default function ReactPreview({
         console.error('Failed to write AST back to QMD:', err);
       }
     },
-    [content, onContentRewrite, format, rendered.untransformedAstJson, rendered.renderedContent],
+    [content, onContentRewrite, format, rendered.untransformedAstJson, rendered.renderedContent, beginCommitStatus, settleCommitStatus],
   );
 
   return (
     <div style={{ height: '100%', display: 'flex', flexDirection: 'column', position: 'relative' }}>
+      {/* Bulb lives in the same bottom-right corner as the error pill; while a
+          commit error is showing, the pill replaces the bulb (bulb → idle). */}
+      <CommitStatusBulb status={commitError ? 'idle' : commitStatus} />
       <div style={{ flex: 1, position: 'relative', overflow: 'hidden' }}>
         {rendered.astJson && (previewState === 'GOOD' || previewState === 'ERROR_FROM_GOOD') ? (
           <ReactRenderer
@@ -596,8 +762,8 @@ export default function ReactPreview({
       </div>
       {/* Error overlay shown when error occurs after successful render */}
       <PreviewErrorOverlay
-        error={currentError}
-        visible={previewState === 'ERROR_FROM_GOOD'}
+        error={currentError ?? (commitError ? { message: commitError } : null)}
+        visible={previewState === 'ERROR_FROM_GOOD' || commitError != null}
         collapsed={errorOverlayCollapsed}
         onToggleCollapsed={setErrorOverlayCollapsed}
       />