@helping-ai-workflow/md2doc 3.3.0 → 3.4.2

package/lib/editor/client.js

@@ -145,7 +145,63 @@
   // in the opposite direction (a zero-width "after" range) to let the
   // existing UndoStack undo()/redo() pair (lib/editor/lineops.js) handle a
   // pure insertion/pure removal without a third op shape.
-  function commitBlockInsertion(state, blockId, newBlockLines) {
+  /**
+   * Is every line of this paste part of a list?
+   *
+   * "Part of a list" is a list line OR an indented continuation of one — a
+   * wrapped sentence, a nested block, a fenced snippet inside an item. Blank
+   * lines inside the paste are allowed (a list may be loose on purpose; what
+   * this decides is only whether to ADD one at the seam).
+   *
+   * A paste that is a list FOLLOWED BY a paragraph answers false, and should:
+   * the blank line before that paragraph is what keeps it out of the last
+   * item, and the seam's own blank is the lesser problem of the two.
+   */
+  function pasteIsAllListLines(pastedLines) {
+    let sawListLine = false;
+    for (const raw of pastedLines) {
+      const line = String(raw == null ? '' : raw);
+      if (line.trim() === '') continue;
+      if (LIST_LINE_RE.test(line)) { sawListLine = true; continue; }
+      // A continuation has to be indented AND it has to belong to something.
+      if (sawListLine && /^[ \t]/.test(line)) continue;
+      return false;
+    }
+    return sawListLine;
+  }
+
+  // Does this line open a list item? Deliberately the same shape as
+  // list-md.js's own SRC_MARKER_RE (`^([ \t]*)(?:[-*+]|\d{1,9}[.)])([ \t]+)…`),
+  // which is function-local there and answers a different question — it
+  // PARSES a marker, this only CLASSIFIES a line. The two are kept in
+  // agreement by a test that runs both over the same table of lines rather
+  // than by sharing one object: making that one exportable would drag a
+  // browser-side module into commitBlockInsertion(), whose whole value is
+  // that it is a pure function node can call directly.
+  const LIST_LINE_RE = /^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+/;
+
+  /**
+   * `opts.tight` — insert with NO leading blank line, and skip the trailing
+   * one when what follows is itself a list line.
+   *
+   * The always-on blank is right for a paragraph and wrong for a list item:
+   * a blank line between items makes the list LOOSE, every item then renders
+   * as <p>, serializeBlocks() answers 'P' per item, and the run degrades
+   * READ-ONLY with no banner. A user meets that as "I pasted an item beside
+   * my list and now Tab does nothing" — no error, no explanation, nothing to
+   * search for.
+   *
+   * It is why insertListItemAfter() and duplicateListItems() bypass this
+   * function. Paste could not: it carries arbitrary pasted lines, and
+   * re-serialising a run to absorb them would REWRITE the user's bytes —
+   * marker widths, ordinals, and the escaping trap duplicateListItems()
+   * records ('~5px' coming back as '\~5px'). So paste keeps the raw-line
+   * insert and turns the leading blank off instead.
+   *
+   * Opt-in, decided by the caller: every other call site wants the blank.
+   */
+  function commitBlockInsertion(state, blockId, newBlockLines, opts) {
+    const tight = !!(opts && opts.tight);
     const block = state.blocks.find((b) => b.id === blockId);
     // T8 item 1, third helper in the same family: the anchor's range is read as
     // an interval here too (`endLine + 1` is the insertion point, `lines[endLine]`
@@ -157,20 +213,26 @@
     if (anchorRefusal) return anchorRefusal;
     const endLine = block.endLine;
     const nextLine = state.lines[endLine]; // 0-indexed: line right after the block, or undefined at EOF
-    const needsTrailingBlank = nextLine !== undefined && nextLine.trim() !== '';
+    // A list line following a tight insert needs no separator: emitting one
+    // would divorce THAT item from the run instead — the same defect, one
+    // item further down.
+    const needsTrailingBlank = nextLine !== undefined && nextLine.trim() !== '' &&
+      !(tight && LIST_LINE_RE.test(nextLine));
+    const lead = tight ? [] : [''];
     const after = needsTrailingBlank
-      ? ['', ...newBlockLines, '']
-      : ['', ...newBlockLines];
+      ? [...lead, ...newBlockLines, '']
+      : [...lead, ...newBlockLines];
     const op = { startLine: endLine + 1, endLine, before: [], after };
     const r = ops.insertLines(state.lines, endLine, after);
     const blocks = ops.shiftBlocks(state.blocks, blockId, r.delta);
     state.stack.push(op);
     // The new block's own content starts one line after the leading blank
-    // this function always inserts (see `after` above — its first element
-    // is always the fresh leading blank) — callers use this to locate the
-    // freshly-inserted block in the blocks array a subsequent full
-    // rerenderAll() (which recomputes blocks server-side) hands back.
-    const newStartLine = op.startLine + 1;
+    // this function inserts by default (see `after` above) — callers use this
+    // to locate the freshly-inserted block in the blocks array a subsequent
+    // full rerenderAll() (which recomputes blocks server-side) hands back.
+    // A tight insert emits no leading blank, so its content begins on the
+    // first inserted line itself.
+    const newStartLine = tight ? op.startLine : op.startLine + 1;
     return { lines: r.lines, blocks, op, newStartLine };
   }
 
@@ -506,8 +568,147 @@
     return rest === '' ? '#'.repeat(newDepth) : '#'.repeat(newDepth) + ' ' + rest;
   }
 
+  // v3.4.0 batch2 Task 6 fix round 1 (review F6) — which page of a re-baked
+  // multi-page drawio box the reader should land on, and whether we are
+  // entitled to tell them their page is gone.
+  //
+  // Page names are NOT identities. lib/drawio.js's pageNamesOf() pushes '' for
+  // any <diagram> with no name attribute (normal in hand-written and
+  // tool-exported files) and nothing de-duplicates the list, so the old
+  // `newNames.indexOf(keepName)` had two opposite failure modes on perfectly
+  // ordinary input: an all-unnamed file always resolved to index 0, silently
+  // moving the reader back to page 1 with no banner; and a `keepName` of null
+  // (nothing identifiable was open) resolved to -1, raising a banner claiming
+  // a deletion that never happened. A false banner is worse than no banner —
+  // it is what teaches a user to ignore the true one.
+  //
+  // So: use the name only where the name IS an identity (non-empty AND unique
+  // in the old list), fall back to position otherwise, and claim deletion only
+  // where it is actually established — a once-unique name that is now absent,
+  // or a position the document no longer reaches.
+  //
+  // `gone: false` with a moved `landOn` is not silence: the caller lands the
+  // reader on a page that is genuinely the same one (renumbered by a reorder),
+  // which is the outcome Ruling B2-P1's "page still there" branch describes.
+  function resolveDrawioLanding(oldNames, activeIdx, newNames) {
+    const olds = Array.isArray(oldNames) ? oldNames : [];
+    const news = Array.isArray(newNames) ? newNames : [];
+    if (news.length === 0) return { landOn: 0, gone: false };
+    // Nothing identifiable was open (no visible .drawio-page, or an index the
+    // old name list never had). We know nothing, so we claim nothing.
+    if (!(activeIdx >= 0) || activeIdx >= olds.length) return { landOn: 0, gone: false };
+    const name = olds[activeIdx];
+    let oldCount = 0;
+    for (let i = 0; i < olds.length; i++) if (olds[i] === name) oldCount++;
+    if (name !== '' && oldCount === 1) {
+      const hits = [];
+      for (let i = 0; i < news.length; i++) if (news[i] === name) hits.push(i);
+      // Exactly one match: a rename-free reorder, resolved exactly.
+      // More than one: the name stopped being an identity between the two
+      // bakes — land on the first bearer, but do NOT claim a deletion we
+      // cannot establish.
+      if (hits.length > 0) return { landOn: hits[0], gone: false };
+      return { landOn: 0, gone: true };
+    }
+    // Empty or duplicated name: position is the only sound identity left.
+    if (activeIdx < news.length) return { landOn: activeIdx, gone: false };
+    return { landOn: 0, gone: true };
+  }
+
+  // v3.4.0 batch3 Task 7 fix 1 (F2) — the block map after an edit that changed
+  // the line count INSIDE one block and nowhere else.
+  //
+  // This is not `ops.shiftBlocks()` on its own, and the difference is the whole
+  // point. `commitRangeEdit()` anchors its shift on "the last block ENDING at
+  // or before the edited range", and for an edit to a fenced block's BODY that
+  // anchor is the block BEFORE the fence — so its answer moves the fenced
+  // block's own `startLine`, which did not move, and leaves its `endLine`
+  // where it was, which did. Here the edited block is named outright: it keeps
+  // its `startLine`, its `endLine` absorbs the delta, every block after it
+  // moves by the delta, and every block before it is untouched.
+  //
+  // Why it exists at all: the wave editor defers the block map to the render at
+  // the end of a session, and a render can FAIL. Before this, a failed close
+  // render left `blocks` addressing the pre-session document while `lines`
+  // carried the session's delta — MEASURED, the next ordinary paragraph edit
+  // then committed over the blank line after the closing fence, eating the
+  // separator and duplicating the paragraph, with no warning of any kind. The
+  // rule this restores is that no ordinary edit may ever land against a block
+  // map the renderer has not confirmed: where the renderer cannot confirm it,
+  // the session's own arithmetic settles it instead.
+  function shiftBlocksAfterBodyEdit(blocks, blockId, delta) {
+    if (delta === 0) return blocks;
+    return blocks.map((b) => {
+      if (b.id === blockId) return Object.assign({}, b, { endLine: b.endLine + delta });
+      if (b.id > blockId) {
+        return Object.assign({}, b, { startLine: b.startLine + delta, endLine: b.endLine + delta });
+      }
+      return b;
+    });
+  }
+
+  // v3.4.0 batch3 Task 7 fix 2 (MUST-FIX 1) — may a wave session's own commits
+  // simply be popped off the document stack?
+  //
+  // Two questions, asked separately, each answered by the stack itself rather
+  // than by arithmetic over a quantity that can be wrong:
+  //
+  //   `depth`       are there still exactly `ops` entries above where this
+  //                 session started? The pop removes that many, so anything
+  //                 else pushing inside the session (see openWaveEditor()'s
+  //                 `switchAwayFrom()` guard) would make it reverse somebody
+  //                 else's edit.
+  //                 ⚠ This proves the COUNT, not the identity. A foreign push
+  //                 paired with a foreign pop inside one session satisfies it —
+  //                 `discardPristineInsert()` is exactly that shape. It is not
+  //                 reachable today for one reason and it is worth naming: the
+  //                 modal returns on every non-save key, and the only path that
+  //                 could open a block editor mid-session is Ctrl+S's
+  //                 `switchAwayFrom()`, which openWaveEditor() now resolves
+  //                 BEFORE the overlay opens. If that guard ever moves, this
+  //                 check has to become identity-based.
+  //   `savedDepth`  would the pop destroy the state disk was written from? It
+  //                 takes the stack from `baseDepth + ops` back to `baseDepth`,
+  //                 so the answer is yes exactly when the save marker sits
+  //                 ABOVE `baseDepth` — i.e. names a state only reachable
+  //                 through this session's own ops. `null` (the marker
+  //                 invalidated because history diverged past it) is safe: it
+  //                 names nothing, and the document reads dirty either way.
+  //                 ⚠ fix 4 (R4): this question is answered with the marker as
+  //                 it stands NOW, and a save that is still in flight has not
+  //                 moved it yet. MEASURED: paint twice, Ctrl+S inside the
+  //                 session, Escape before the reply — this says the pop is
+  //                 safe and pops a drawing the server has already written. It
+  //                 is not a hole, because the receipt closes it from the other
+  //                 end: when that reply lands, `markSaved()` finds the
+  //                 timeline at its boundary gone, invalidates the marker, and
+  //                 the document reads dirty. But this function cannot see it,
+  //                 and the honest reading of its answer is "safe as far as any
+  //                 save that has REPLIED is concerned".
+  //
+  // Both are POSITIONS compared against the session's own baseline, which is
+  // what makes them sign-safe. What they REPLACE: fix 1 derived "no save
+  // happened" from `stack.dirtyDepth === baseDirtyDepth + ops`. That
+  // implication only runs the way it was used when `baseDirtyDepth >= 0`;
+  // algebraically it is equally satisfied when
+  // `baseDirtyDepth === -(ops taken before the save)`, and a user reaches a
+  // negative baseline by pressing Ctrl+Z once after a save. MEASURED: edit,
+  // Ctrl+S, Ctrl+Z, open the editor, paint, Ctrl+S, paint, Escape — the
+  // predicate read `1 === -1 + 2`, answered "no save", and popped blind,
+  // reproducing the original defect through the fixed code.
+  //
+  // Deliberately NOT "did the marker move": the marker legitimately goes
+  // 1 → null → 1 inside one session (the first wave commit invalidates it, a
+  // mid-session Ctrl+S establishes it again), so watching it for change both
+  // misses that case and refuses the harmless one where only the invalidation
+  // happened.
+  function waveDiscardIsSafe(stack, seam) {
+    if (stack.depth !== seam.baseDepth + seam.ops) return false;
+    return stack.savedDepth === null || stack.savedDepth <= seam.baseDepth;
+  }
+
   if (typeof module === 'object' && module.exports) {
-    module.exports = { extractBlockSource, commitEdit, commitRangeEdit, commitRangeRemoval, commitListBlockRemoval, commitBlockInsertion, planBlockMove, commitBlockMove, reorderSpanRange, spanMoveRange, spanIndentsAreAnchored, blockMoveSeamRefusal, rollbackFailedRender, headingDepthOf, withHeadingDepth };
+    module.exports = { pasteIsAllListLines, LIST_LINE_RE, extractBlockSource, commitEdit, commitRangeEdit, commitRangeRemoval, commitListBlockRemoval, commitBlockInsertion, planBlockMove, commitBlockMove, reorderSpanRange, spanMoveRange, spanIndentsAreAnchored, blockMoveSeamRefusal, rollbackFailedRender, headingDepthOf, withHeadingDepth, resolveDrawioLanding, shiftBlocksAfterBodyEdit, waveDiscardIsSafe };
     return; // node: pure core only
   }
 
@@ -532,6 +733,20 @@
   const docSourceLib = window.md2docDocSource;
   let lines = ED.lines, blocks = ED.blocks, mtimeMs = ED.mtimeMs;
   let lastParts = null;
+  // v3.4.0 batch2 Task 6 fix round 1 (review F1) — true while `lastParts` is
+  // the bootstrap seed taken off the server-rendered DOM (see just below
+  // contentEl) rather than a `parts` array a render actually handed back.
+  // The seed is byte-for-byte the DOM's OWN serialization, which is not the
+  // same string the server emitted (the HTML parser normalizes attribute
+  // quoting, `hidden` becomes `hidden=""`, and so on), so it is fit for the
+  // positional/id checks domMatchesLastRender() makes and for "did this
+  // block's baked output change at all", but NOT for patchmap(), which
+  // diffs the strings themselves. It is also what keeps the documented
+  // "the first commit after a page load is ALWAYS a full render" behaviour
+  // exactly as it was — test/editor-journey.test.js's primed/unprimed axis
+  // is built on that property and would silently lose half its coverage if
+  // seeding `lastParts` quietly enabled the patch route one commit earlier.
+  let lastPartsIsBootstrapSeed = false;
   // F10: 上一次【成功套用】的 render 留下來的東西 —— 當時的整份 `lines`，以及
   // 當時的文件是不是以一道沒閉合的圍欄收尾。
   //
@@ -552,6 +767,28 @@
   const stack = new ops.UndoStack();
   const baseTitle = document.title;
   const contentEl = document.querySelector('.content');
+  // v3.4.0 batch2 Task 6 fix round 1 (review F1, BLOCKING) — establish, at
+  // first paint, the knowledge domMatchesLastRender() is a check ON.
+  //
+  // `lastParts` used to stay null until this tab's FIRST COMMIT, because the
+  // bootstrap payload carries no `parts` and the initial DOM is rendered
+  // server-side (no client render runs at load). refreshStaleDrawio()'s
+  // "does the DOM still match the render I last knew about" guard is
+  // therefore unconditionally false on a freshly opened tab — and "open a
+  // document, don't edit it, change the .drawio in Draw.io" is the exact
+  // story this whole feature exists for. The re-bake was computed, paid for
+  // (a headless-Chromium bake) and thrown away, while the server's baseline
+  // advanced so the signal never came again.
+  //
+  // The guard is right; the bootstrap simply never established what it
+  // checks. It does now: at this point .content's children ARE the render
+  // the server just sent, one element per block, so reading them back is not
+  // an approximation of that knowledge — it is that knowledge. Taken here,
+  // before armEditables() (called at the very bottom of this IIFE) adds its
+  // own attributes, so the seed describes the render rather than the armed
+  // document.
+  lastParts = Array.prototype.map.call(contentEl.children, (el) => el.outerHTML);
+  lastPartsIsBootstrapSeed = true;
 
   // Click-to-switch substrate (Phase-2 Task 1; replaces the old "refuse a
   // second block's editor outright" policy). At most one block editor is
@@ -620,6 +857,90 @@
     discardedBurst = null;
   }
 
+  // v3.4.0 (Task 7 item 5) — the raw-editor twin of `discardedBurst` just
+  // above. Same one-shot contract (answers exactly one Ctrl+Z, the one right
+  // after the Escape/✕ that created it) and the SAME invalidation rule
+  // (dropped the moment any new burst/raw session opens, or the page
+  // re-renders) — see discardedBurst's own comment for why that window has
+  // to be this narrow. It cannot REUSE discardedBurst's mechanism, though:
+  // that one parks a live `history` object keyed on the burst's own DOM node,
+  // and openRawEditor() tears its OWN surface down on open
+  // (`blockEl.innerHTML = ''`) before a textarea ever exists — there is no
+  // node to park a history against. So this parks a plain VALUE snapshot of
+  // the textarea instead (what was typed, where the caret was, and enough of
+  // the session's own addressing — blockId/range/startLine/endLine/source —
+  // to re-derive the same block and verify nothing else moved underneath it)
+  // and Ctrl+Z's job is to RE-OPEN the raw editor and put that value back —
+  // not to commit it. Escape's semantics are unchanged: it still discards,
+  // still leaves. What changes is that the discard is no longer permanent.
+  //
+  // `discardedBurst` and this are mutually exclusive by construction (only
+  // one editing session — a WYSIWYG burst or a raw editor — is ever open at
+  // once): cancelAndMaybeDiscard() below drops any live `discardedBurst` the
+  // moment IT stashes here, and revertBurstAndEnd()/stashDiscardedTableBurst()
+  // drop this the moment THEY stash into `discardedBurst` — so undo()'s
+  // "check the burst stash, then the raw stash" order never answers a stale
+  // one while a fresher discard from the OTHER substrate is sitting unused.
+  let discardedRawEdit = null; // { blockId, range, startLine, endLine, source, value, caret } | null
+
+  function dropDiscardedRawEdit() {
+    discardedRawEdit = null;
+  }
+
+  // v3.4.0 batch3 Task 7 — the wave-editor member of the same family as the
+  // two stashes above. Escape out of the wave overlay still DISCARDS, and this
+  // is what makes the discard recoverable by exactly one document-level
+  // Ctrl+Z, the same one-shot contract `discardedBurst` spells out.
+  //
+  // Which of discardedBurst's rules are reused here, and which cannot be:
+  //
+  //   REUSED — the one-shot window (the only Ctrl+Z it answers is the one
+  //   right after the Escape that created it), the drop-on-any-render rule
+  //   (rerenderAll() clears all three at its top), mutual exclusivity with the
+  //   other two, and a staleness guard that refuses rather than applying a
+  //   restore over a document that moved underneath it.
+  //
+  //   NOT APPLICABLE — parking a live `history` object keyed on the burst's
+  //   own DOM node. discardedBurst can do that because the burst's
+  //   contenteditable survives its own Escape; the wave overlay is mounted on
+  //   `document.body` and `close()` REMOVES it (and every document listener it
+  //   installed) before onClose ever runs, so there is no node and no live
+  //   store left to park. Nor is `editEl`/`burstBaselineHtml()` meaningful:
+  //   nothing the wave editor produces was ever HTML in `.content`.
+  //
+  //   NOT APPLICABLE — "the burst never committed, so `lines` never saw it".
+  //   The wave editor writes back PER GESTURE, so by the time Escape is
+  //   pressed `lines` has seen every one of them and the document stack is
+  //   carrying them. That inverts what Escape has to do: it is the one stash
+  //   in this file whose creation REMOVES ops from the stack (see
+  //   finishWaveSession()) rather than never having put any there.
+  //
+  // So this parks a plain VALUE pair — the block body as it stood before the
+  // session (`source`, which is what `lines` holds again once the Escape has
+  // run) and as it stood at the moment of the Escape (`painted`) — plus enough
+  // addressing to prove nothing else moved. Ctrl+Z's job is to put `painted`
+  // back through an ordinary commit and RE-OPEN the editor over it.
+  let discardedWaveEdit = null; // { blockId, blockStartLine, blockEndLine, startLine, endLine, source, painted } | null
+
+  function dropDiscardedWaveEdit() {
+    discardedWaveEdit = null;
+  }
+
+  // v3.4.0 batch3 Task 7 — a wave gesture whose patch was REFUSED, i.e. work
+  // the user can see in the overlay that `lines` does not hold and cannot be
+  // made to hold by a local patch. Declared up here beside the stashes rather
+  // than down with the rest of the wave wiring (~16900) for one reason:
+  // documentIsDirty() reads it, documentIsDirty() is reachable from the very
+  // first setDirty(), and a `let` declared further down would still be in its
+  // temporal dead zone then.
+  //
+  // This is the second half of the Reload gate. The first half is free —
+  // every write-back that SUCCEEDS goes through commitRangeEdit(), so
+  // `stack.dirtyDepth` already counts it and the beforeunload guard already
+  // covers it. A refusal is the case that guard cannot see, because by
+  // definition nothing reached `lines`.
+  let waveUnwrittenEdit = false;
+
   // §10-gap fix (review): the block insertBlockBelow() most recently
   // inserted, tracked from the moment its edit surface is first focused
   // until its FIRST resolution (blur, Escape, explicit commit, or Ctrl+Z) —
@@ -772,9 +1093,13 @@
     return await activeEditor.commitNow(); // false → editor stays open, banner already shown
   }
 
-  // `stack.dirtyDepth` is `_done.length - _savedDepth` (lineops.js), so it
-  // moves when an op is pushed onto or popped off the undo stack, or when a
-  // save re-baselines it. The burst substrate keeps what the user typed in
+  // `stack.isDirty()` asks whether the undo stack is standing on the state the
+  // last save wrote (lineops.js). `dirtyDepth` is the same question as a
+  // distance, and only while that distance exists at all: once a push has
+  // diverged past the save marker the marker is invalidated, and the getter
+  // then answers `_done.length + 1` — never 0. Either way the answer moves
+  // when an op is pushed onto or popped off the stack, or when a save
+  // re-baselines it. The burst substrate keeps what the user typed in
   // the DOM until the burst resolves, and none of those has happened yet at
   // that point — so a block that has been typed into but not yet left reads
   // as clean. MEASURED on `# Doc\n\nAlpha paragraph.\n` (click the
@@ -791,9 +1116,35 @@
       burstBaselineHtml(currentBurst.editEl) !== currentBurst.original);
   }
 
+  // v3.4.0 §3: single source of truth for "does the document have anything
+  // unsaved" — setDirty() (the title dot), toolbarContext() (the `save`
+  // button's own lit/grey state), and the beforeunload guard further below
+  // all ask this instead of each carrying its own copy of the expression
+  // (review I1: the beforeunload handler used to be a second copy — found
+  // and fixed). Do not inline this back into any call site; that is exactly
+  // the drift this function exists to prevent.
+  // v3.4.0 batch3 Task 7 adds the third term. MEASURED before it existed, with
+  // the wave editor open over a real paint: `document.title` was 'doc', the
+  // file on disk was byte-identical, and pressing the conflict banner's Reload
+  // raised NO beforeunload dialog at all — because this predicate is about
+  // `lines`, and a waveform had never been in `lines`. Two thirds of that gap
+  // close by themselves the moment write-back goes through commitRangeEdit()
+  // (`stack.dirtyDepth` counts it like any other commit); `waveUnwrittenEdit`
+  // is the remaining third — a gesture the store could not express as a local
+  // patch, which the user can see on screen and `lines` does not hold.
+  function documentIsDirty() {
+    // fix 2: `stack.isDirty()`, not `stack.dirtyDepth !== 0`. MEASURED on the
+    // shipped behaviour, with no wave editor involved: edit, Ctrl+S, Ctrl+Z,
+    // one more ordinary edit — the depth came back to 0 FROM BELOW and this
+    // answered false over a document that differed from disk in both edits.
+    // The distance was a second record of "are we standing where we saved";
+    // `UndoStack` now answers that question itself, and a boolean has no zero
+    // to walk through. See lineops.js's own comment for the full story.
+    return stack.isDirty() || burstHasUncommittedEdit() || waveUnwrittenEdit;
+  }
+
   function setDirty() {
-    const dirty = stack.dirtyDepth !== 0 || burstHasUncommittedEdit();
-    document.title = (dirty ? '● ' : '') + baseTitle;
+    document.title = (documentIsDirty() ? '● ' : '') + baseTitle;
   }
 
   // setDirty() is push-driven: something has to call it. MEASURED by keeping
@@ -865,6 +1216,12 @@
   // refusal 一樣需要一個「後來的事件可以把它收掉」的記號，但收掉它的條件不
   // 同（見 dismissSwallowBanner()），所以是另一個旗標而不是共用那一個。
   let activeBannerIsSwallow = false;
+  // Task 9 review I3: the same shape as activeBannerIsRefusal/
+  // activeBannerIsSwallow above, for the keynav-exit banner backlog #10
+  // added. It needs its own dismiss condition too — see
+  // dismissKeynavExitBanner()'s own comment for why Escape, specifically,
+  // is the only OTHER thing allowed to clear it.
+  let activeBannerIsKeynavExit = false;
   function showBanner(message, actionLabel, onAction) {
     if (activeBanner) { activeBanner.remove(); activeBanner = null; }
     // Reset unconditionally: refuseStructuralListEdit() sets it back to true
@@ -872,6 +1229,39 @@
     // having to know this flag exists.
     activeBannerIsRefusal = false;
     activeBannerIsSwallow = false;
+    activeBannerIsKeynavExit = false;
+    // backlog #8 fix: `.ed-conflict` now sits at `top: var(--ed-toolbar-h)`
+    // (lib/md2doc.js) — the SAME floor `.ed-te-menu` (placeTeMenuAboveCell())
+    // explicitly clamps to when there is no room above (`if (top < topInset)
+    // top = r.bottom + …`, `topInset` read straight from --ed-toolbar-h).
+    // Final-review I1 correction: an earlier draft of this comment also named
+    // `.ed-toolbar-menu` here (`toggleToolbarHeadingMenu(): top = r.bottom +
+    // 4`) as if that `+ 4` were the same floor. Retracted — MEASURED:
+    // toggleToolbarHeadingMenu() never reads --ed-toolbar-h at all; its `r` is
+    // the heading-dropdown BUTTON's own rect (a toolbar button, so already
+    // near the band), not a clamp against the token. It lands near the same
+    // band as a side effect of where its trigger sits, not because of a
+    // shared floor. (positionSelToolbar()'s `.ed-seltb` is the same story,
+    // for the same reason — see the parallel correction on the `.ed-conflict`
+    // CSS comment in lib/md2doc.js.)
+    // Any of the four dynamic fixed overlays below could nonetheless be
+    // showing in exactly the band the banner is about to claim; without this,
+    // the banner (z-index 999, above all four) would paint over whichever one
+    // is open, reproducing backlog #8's own defect one layer down instead of
+    // fixing it. Same four functions onAnyScroll() already calls for an
+    // analogous reason (something big just happened; these four don't
+    // outlive it) — reused rather than re-invented — but NOT the identical
+    // call: onAnyScroll() guards its hideTableEdgeMenu() with
+    // `if (!suppressEdgeMenuAutoHide)`, this call is unconditional. The one
+    // window that guard exists for is runCycleAlign()'s ensureTableBurstOpen()
+    // span, which can itself raise a banner (a structural refusal) — but that
+    // branch bails immediately and resets the flag to false before doing
+    // anything the menu's reposition-in-progress state could be corrupted
+    // by, so an unconditional close here has no real target to clobber.
+    hideTableGrips();
+    hideTableInsertBubbles();
+    hideTableEdgeMenu();
+    closeToolbarMenu();
     const el = document.createElement('div');
     el.className = 'ed-conflict';
     const msg = document.createElement('span');
@@ -894,6 +1284,7 @@
         activeBanner = null;
         activeBannerIsRefusal = false;
         activeBannerIsSwallow = false;
+        activeBannerIsKeynavExit = false;
       }
     });
     el.appendChild(dismissBtn);
@@ -902,6 +1293,34 @@
     return el;
   }
 
+  // Task 9 review I3: MEASURED AT THE TIME — `.ed-conflict` was
+  // `position:fixed; top:0; z-index:999` against `.ed-toolbar`'s
+  // `top:0; height:44px; z-index:101`, so the keynav-exit banner sat OVER
+  // the entire bar (23/23 buttons' centre points hit-tested to the banner,
+  // not their own button) the moment it appeared. Task 10 (backlog #8)
+  // since moved `.ed-conflict` to `top: var(--ed-toolbar-h)` — it no longer
+  // covers the bar at all, for any banner, not just this one — so that
+  // geometry claim is HISTORICAL, kept here only because it is what
+  // motivated wiring Escape below; do not read it as the current state of
+  // `.ed-conflict`. What is still current: a keyboard user had no way to
+  // take this banner down other than a mouse click on ✕ — Escape did not
+  // dismiss it (showBanner() only wires a click handler onto ✕) and a
+  // bare Tab is swallowed by this file's own §3.5 contract whenever nothing
+  // real is focused, which is exactly the state right after this banner's
+  // own cause (a stray key that just exited keynav). Escape is the one key
+  // safe to wire this to: every OTHER banner this file raises (conflict /
+  // save-failed / a structural refusal) describes something that must
+  // survive an incidental Escape elsewhere on the page, but THIS banner's
+  // entire subject is "you just left keyboard mode" — Escape asking to
+  // leave a mode a second time is the same request, not a different one.
+  function dismissKeynavExitBanner() {
+    if (!activeBanner || !activeBannerIsKeynavExit) return false;
+    activeBanner.remove();
+    activeBanner = null;
+    activeBannerIsKeynavExit = false;
+    return true;
+  }
+
   // Review recommendation 5: a refusal banner must not outlive the gesture that
   // raised it. refuseStructuralListEdit() has been dismiss-only since S1, and
   // S3 made it far more reachable (7 of the T8 sweep's 13 selection shapes
@@ -1104,6 +1523,13 @@
     // guard in restoreDiscardedBurst() would refuse it anyway; dropping it at
     // the source is what keeps a dead history object from being held.
     dropDiscardedBurst();
+    // v3.4.0 (Task 7 item 5): same reasoning, same source, for the raw-editor
+    // twin — this render is about to replace `lines`' rendering of whatever
+    // discardedRawEdit's stashed `source` names.
+    dropDiscardedRawEdit();
+    // v3.4.0 batch3 Task 7: and the wave twin — its staleness guard compares
+    // `lines` at a span, which this render is about to repaint from.
+    dropDiscardedWaveEdit();
     const scrollY = window.scrollY;
     // S3 Task 5 (§4.4 step 2): the line range this render's operation declared
     // for the rebuilt selection. Consumed HERE, before the first failure exit,
@@ -1182,10 +1608,17 @@
   // Its VALUE is forwarded to patchmap(), which never reads it (決議 4(b) — it
   // is advisory, and seeding the span from an op's line range measurably
   // widens the answer), so neither the direction nor the width of the range
-  // affects the plan. `lastParts` is null
-  // on the first render of a session (the bootstrap payload carries no parts),
-  // which makes patchmap() return null — so the first commit after a page load
-  // is ALWAYS a full render. That is specified behaviour, not a bug.
+  // affects the plan. The first commit after a page load is ALWAYS a full
+  // render. That is specified behaviour, not a bug — but fix round 2
+  // (re-review G2) corrects HOW it is carried: it used to be that `lastParts`
+  // stayed null until a render landed, and null is what made this gate fall
+  // through. Since the F1 fix, `lastParts` is seeded off the server-rendered
+  // DOM at first paint and is NEVER null after that; the property is carried
+  // by `lastPartsIsBootstrapSeed` instead (the seed is the HTML parser's
+  // re-serialisation, not the server's own `parts` strings, so it must not
+  // reach patchmap(), which diffs those strings). Do NOT use
+  // `lastParts === null` as an "unprimed" test anywhere — it is now always
+  // false.
   // Fix round 2: applyPatch()'s index arithmetic addresses `contentEl`'s
   // element children POSITIONALLY against `lastParts`. That correspondence is
   // not free — several gestures mutate .content's child list DIRECTLY, in the
@@ -1319,7 +1752,7 @@
                       absorbedOutsideContent(lastRenderLines, blocks,
                                              lines, j.blocks,
                                              j.blocks[j.blocks.length - 1]);
-    const plan = (editRange && window.md2docPatchmap && domMatchesLastRender())
+    const plan = (editRange && window.md2docPatchmap && !lastPartsIsBootstrapSeed && domMatchesLastRender())
       ? window.md2docPatchmap.patchmap({
           oldBlocks: blocks, newBlocks: j.blocks,
           oldParts: lastParts, newParts: j.parts, editRange: editRange,
@@ -1424,6 +1857,51 @@
     const ci = focusedBlockEl ? children.indexOf(focusedBlockEl) : -1;
     const focusWasInSpan = ci >= 0 &&
       ci >= plan.replaceSpan.oldStart && ci <= plan.replaceSpan.oldEnd;
+    // v3.4.0 (Task 7 item 1) — the raw-editor twin of applyFullRender()'s
+    // v3.2.1 R2 `activeEditor = null` fix (see its comment), narrowed to the
+    // one case that fix actually needs to cover here. That fix cannot be
+    // copied verbatim: the whole point of the patch path is to let a raw
+    // editor OUTSIDE replaceSpan survive (see "決議 3(1)" below) — nulling
+    // activeEditor unconditionally here would re-orphan exactly the session
+    // item1-scenarioB measured. The hazard is narrower: when activeEditor's
+    // OWN block falls INSIDE replaceSpan, the removeChild loop below is
+    // about to detach it out from under itself, and Chromium's synchronous
+    // focusout for that detach finds `activeEditor` still set (commit()'s own
+    // post-await `activeEditor = null` hasn't run yet — this render IS that
+    // commit's own safeRerenderAll(), still in flight) — reentering
+    // switchAwayFrom() -> resolveOpenSession() -> commitNow() a SECOND time.
+    //
+    // MEASURED (runs/task7-probe2-item1.js + task7-probe4-isolate.js, on a
+    // 2nd-commit-in-session PATCH render that repairs a swallowed fence's
+    // closing marker — the repair spawns a NEW block, same "衍生新 block"
+    // shape the v3.2.1 R2 comment names): the reentrant commit() sees
+    // `blocks` already reassigned to `j.blocks` (this function reassigns it
+    // above, before the mutation below) — i.e. the block's NEW, shrunk
+    // post-split range — but reuses `ta.value`, the STALE, un-shrunk text
+    // that still carries the split-off tail. commitEdit() diffs that against
+    // the (already-correct) `lines` and, since they no longer match, commits
+    // a real op writing the stale tail-bearing text over the shrunk range —
+    // duplicating the tail the FIRST (outer) commit had just placed in its
+    // own new block a moment earlier. Three /api/render calls for one
+    // Ctrl+Enter; the file gained a second 'Trailing paragraph text.'.
+    // Nulling activeEditor here, before the mutation, for exactly the
+    // falls-inside-replaceSpan case closes the hole the same way v3.2.1 R2
+    // closed it for the fallback path, without touching the survives case.
+    //
+    // PRECONDITION worth stating explicitly: this can only fire on a PATCH
+    // render, and patchmap() only runs once `lastParts` is populated — the
+    // very first commit of a session is ALWAYS a full render (see
+    // applyRenderResult()'s own comment). So the defect does NOT reproduce
+    // on a freshly opened document with no prior commit in the same
+    // session; repairing a swallowed fence as literally the first edit
+    // after page load is safe (fallback path). See task-7-report.md and
+    // this fix's test scenario for the measured before/after.
+    if (activeEditor && activeEditor.blockEl) {
+      const aci = children.indexOf(activeEditor.blockEl);
+      if (aci >= plan.replaceSpan.oldStart && aci <= plan.replaceSpan.oldEnd) {
+        activeEditor = null;
+      }
+    }
     // Fix round 1 (review Important 1): `blocks`/`lastParts` are the JOIN KEY
     // between the module's model and the DOM, and they are overwritten BEFORE
     // the DOM is touched — armEditables() reads the new `blocks` (see its call
@@ -1534,8 +2012,15 @@
       // 所以在 `burstSurvived` 那裡也留了一行對照註解。不搬 `burstSurvived`
       // 到還原之前，是刻意的取捨：搬了會讓剛開的 burst 先被 dispose 再由收尾
       // 重開一次，並把每次 undo 的工具列 degrade 原封不動地留著。
-      // teardown 各項彼此的相對順序沒有被動到，條件式的 activeEditor 歸零
-      // 仍然在 DOM 手術之後求值。
+      // teardown 各項彼此的相對順序沒有被動到，**條件式**那一發 activeEditor
+      // 歸零仍然在 DOM 手術之後求值——但這不再是這次 render 唯一可能歸零
+      // `activeEditor` 的地方：v3.4.0 (Task 7 item 1) 在 DOM 手術**之前**另外
+      // 補了一道 pre-mutation 的窄範圍歸零（見 `focusWasInSpan` 正下方那段
+      // `if (activeEditor && activeEditor.blockEl) { … }`），只在
+      // `activeEditor.blockEl` 落在 `plan.replaceSpan` 內時才提前清空。兩者
+      // 不衝突（提前清過的話這裡條件式那段的 `activeEditor &&` 直接短路），但
+      // 讀這段時不要再假設「這次 render 裡 activeEditor 的歸零只有一處、而且
+      // 一定在 DOM 手術之後」。
       const newLen = plan.replaceSpan.newParts.length;
       if (newLen > 0) {
         // landing 恆落在新中段內：ci >= oldStart 保證非負，min() 夾住上界，
@@ -1821,6 +2306,23 @@
         // Never let a reader-runtime rebind failure break block selection/save/undo.
       }
     }
+    // v3.4.0 batch2 Task 6 fix round 1 (review F9): sibling to
+    // __md2docInitDiagrams above, and for the same reason — the swap just
+    // detached every node the multi-page drawio navigation was mounted on,
+    // and nothing else in the tree re-creates it. Left unwired, a document
+    // with a multi-page diagram loses that navigation permanently on the
+    // user's FIRST edit commit of the session, which makes preserving the
+    // reader's open page across a background re-bake largely academic.
+    // Defined only when the document was multi-page at load time (the
+    // lib/md2doc.js gate a byte-exact guard test pins), hence the check.
+    if (window.__md2docInitDrawioSheetBar) {
+      try {
+        window.__md2docInitDrawioSheetBar(contentEl);
+      } catch (e) {
+        // Same contract as the two rebinds around it: never let a
+        // navigation-rebuild failure break block selection / save / undo.
+      }
+    }
     // Fix round 1 (review, comment-only): whenever rebuildBlockSelection()
     // above does NOT take its early-return path it has already called
     // applySelectionClasses() once, via setBlockSelection()/
@@ -1887,6 +2389,7 @@
   async function applyFullRender(j, scrollY, declaredRange) {
     blocks = j.blocks;
     lastParts = j.parts;                       // v3.2.0: 供下一次 patch 當 oldParts
+    lastPartsIsBootstrapSeed = false;
     // v3.2.1 R2: 必須先於 innerHTML 寫入。這個寫入 detach 掉聚焦的 raw
     // textarea，同步 focusout 重入 switchAwayFrom() → resolveOpenSession() →
     // commitNow()，於是同一次編輯提交兩次（實測衍生新 block 時磁碟上文字出現
@@ -2029,6 +2532,23 @@
         // Never let a reader-runtime rebind failure break block selection/save/undo.
       }
     }
+    // v3.4.0 batch2 Task 6 fix round 1 (review F9): sibling to
+    // __md2docInitDiagrams above, and for the same reason — the swap just
+    // detached every node the multi-page drawio navigation was mounted on,
+    // and nothing else in the tree re-creates it. Left unwired, a document
+    // with a multi-page diagram loses that navigation permanently on the
+    // user's FIRST edit commit of the session, which makes preserving the
+    // reader's open page across a background re-bake largely academic.
+    // Defined only when the document was multi-page at load time (the
+    // lib/md2doc.js gate a byte-exact guard test pins), hence the check.
+    if (window.__md2docInitDrawioSheetBar) {
+      try {
+        window.__md2docInitDrawioSheetBar(contentEl);
+      } catch (e) {
+        // Same contract as the two rebinds around it: never let a
+        // navigation-rebuild failure break block selection / save / undo.
+      }
+    }
     setDirty();
     return true;
   }
@@ -2440,6 +2960,47 @@
     async function cancelAndMaybeDiscard() {
       const wasPristineForThisBlock = !!(pristineInsert && pristineInsert.blockId === blockId);
       if (wasPristineForThisBlock) pristineInsert = null;
+      // v3.4.0 (Task 7 item 5): stash what is about to be thrown away, keyed
+      // by VALUE rather than by node — see discardedRawEdit's own comment for
+      // why a node-keyed stash (discardedBurst's own approach) cannot survive
+      // this function's own restore() just below: for the non-rangeMode
+      // branch it does `blockEl.innerHTML = original`.
+      //
+      // ⚠ rangeMode (a multi-block span, or any li) is NOT covered by this
+      // stash, and that is a known, unfixed gap rather than something this
+      // branch happens to also solve — review round 2 measured it on HEAD:
+      // restore()'s rangeMode branch calls `await safeRerenderAll()`, which
+      // reaches rerenderAll(), which calls dropDiscardedRawEdit()
+      // UNCONDITIONALLY a couple of lines into the very Escape gesture that
+      // just created the stash below. So the `discardedRawEdit = {...}`
+      // assignment two lines down is live code but its EFFECT is dead for
+      // every rangeMode session — the stash exists for one statement and is
+      // wiped by its own creator's next `await`. A single li ( -item one ->
+      // ⠿ -> MD 原始碼 -> type -> Escape -> Ctrl+Z) and a multi-block span
+      // both measure `rawAfterUndo: {present:false}` — Ctrl+Z does not bring
+      // the text back on either shape. Fixing this is out of this task's
+      // scope (parked to backlog); this comment exists so nobody reads the
+      // code below as covering rangeMode when it structurally cannot.
+      // Skipped for a pristine insert: discardPristineInsert() (below)
+      // REMOVES the block outright, so there is no surface left to restore a
+      // stash INTO — mirrors revertBurstAndEnd()'s identical
+      // wasPristineForThisBlock exception for the WYSIWYG burst twin.
+      // Skipped when nothing was actually typed (ta.value === seed.value):
+      // the zero-edit auto-cancel-on-unchanged-blur path in
+      // resolveOpenSession() reaches this same function, and there is
+      // nothing to lose there.
+      if (!wasPristineForThisBlock && ta.value !== seed.value) {
+        // Mutual exclusivity with the WYSIWYG twin — see discardedRawEdit's
+        // own comment for why only the more recent of the two stashes may
+        // ever answer the next Ctrl+Z.
+        dropDiscardedBurst();
+        // …and with the wave twin, for the same reason.
+        dropDiscardedWaveEdit();
+        discardedRawEdit = {
+          blockId, range, startLine, endLine, source,
+          value: ta.value, caret: ta.selectionStart,
+        };
+      }
       await restore();
       if (wasPristineForThisBlock) return await discardPristineInsert();
       return true;
@@ -4346,6 +4907,10 @@
       await openRawEditor(blockEl);
       return;
     }
+    // NOTE: `kind === 'line'` never reaches here — insertBlockBelow()'s own
+    // caller excludes it (`if (!customLines && kind !== 'line')`) and
+    // handles the hr's caret landing itself, right where it computes
+    // `result.newStartLine`; see that branch's own backlog #6 comment.
     if (kind === 'table') {
       const tableEl = blockContentEl(blockEl);
       const firstBodyRow = tableEl ? bodyRowsOf(tableEl)[0] : null;
@@ -4481,7 +5046,14 @@
     const liveBlockId = Number(anchorEl.getAttribute('data-block-id'));
     const block = blocks.find((b) => b.id === liveBlockId);
     if (!block) return;
-    const result = commitBlockInsertion({ lines, blocks, stack }, liveBlockId, newLines);
+    // `tight` is only ever honoured when the anchor really is a list item:
+    // the caller decides the CONTENT is list-shaped, this decides the
+    // DESTINATION is a list. Both halves are needed — tight-inserting a list
+    // under a paragraph would glue it to that paragraph's last line.
+    const tight = !!(opts && opts.tight) &&
+      anchorEl.getAttribute('data-block-type') === 'li';
+    const result = commitBlockInsertion({ lines, blocks, stack }, liveBlockId, newLines,
+      { tight });
     const prevLines = lines;
     lines = result.lines;
     const editRange = result.op
@@ -4537,7 +5109,24 @@
       // no declareCollapse(), so re-aiming the bar at the hr cannot contradict
       // a tinted set the way a forced caret would — but "the one site that does
       // not ask the question" is how the next divergence gets in.
-      if (!blockSelection) reaimToolbarBlockAtLine(result.newStartLine);
+      if (!blockSelection) {
+        reaimToolbarBlockAtLine(result.newStartLine);
+        // backlog #6: the "restore the caret too" decision the comment above
+        // deferred. armEditables() has no 'line' branch (same degraded shape
+        // as 'code' — see focusInsertedBlock()'s own branch for the
+        // established precedent), so an <hr> has no contenteditable surface
+        // to land a caret in at all; its own raw editor is the only real
+        // landing. MEASURED (v3.3.0, this comment's own log above):
+        // activeElement stayed BODY whether this branch ran or not — this
+        // closes exactly that gap rather than picking "the anchor block" or
+        // "the block after the hr", the two options the deferred comment
+        // named: neither is where the user's attention actually is right
+        // after pressing 分隔線, which is the hr itself.
+        const target = blocks.find((b) => b.startLine === result.newStartLine);
+        const hrEl = target &&
+          document.querySelector('.ed-block[data-block-id="' + target.id + '"]');
+        if (hrEl) await openRawEditor(hrEl);
+      }
     }
   }
 
@@ -4926,7 +5515,32 @@
   // this does NOT cover is a THROW inside applyPatch()/applyFullRender(),
   // caught by safeRerenderAll(): that can leave the DOM half-swapped, and
   // neither the old behaviour nor this one has an answer for it.
-  function restoreAfterStructuralOp(focusLine, anchorLine) {
+  // `allowRawEditRescue` (Task 9 review I4): the backlog #6 raw-editor
+  // fallback below is opt-in per CALLER, not a blanket behaviour of this
+  // shared landing function. restoreAfterStructuralOp() has four callers —
+  // changeHeadingDepth / convertBlockViaMenu / duplicateBlockViaMenu /
+  // deleteBlockViaGutter — and backlog #6's own text names exactly one
+  // gesture family (轉換成 quote/code), reached only through
+  // convertBlockViaMenu(). MEASURED (review): the guard as first written
+  // was unconditional and DID also fire for 建立副本 (duplicate) on a code
+  // block or a blockquote, and for 刪除 (delete) when the surviving
+  // neighbour was a blockquote — BODY → TEXTAREA.ed-raw in all three,
+  // philosophically consistent (armEditables() never arms quote/code
+  // regardless of which gesture produced one) but never asked for, never
+  // reported, and never tested.
+  // Final-review I2 correction: this paragraph used to also cite backlog #5
+  // (the raw editor's own Escape discarding an uncommitted edit) as a
+  // reason auto-opening one right after a DESTRUCTIVE gesture
+  // (duplicate/delete) would not be free the way it is right after a plain
+  // conversion. Backlog #5 was fixed by 3eb36f9, which landed BEFORE this
+  // very commit on this branch — Escape out of a raw editor no longer
+  // discards the edit, so that risk no longer applies. Retracted rather than
+  // left to mislead whoever next considers widening this rescue. The
+  // narrowing itself still stands on its own merits above (never asked for,
+  // never reported, never tested for duplicate/delete) — widening past
+  // convertBlockViaMenu() to the other three callers remains a separate
+  // decision this task did not make and should not make silently.
+  function restoreAfterStructuralOp(focusLine, anchorLine, allowRawEditRescue) {
     // 有 blockSelection 站著時什麼都不做 —— 見 convertBlockViaMenu() 底下那段
     // 註解：強行還原 caret 會做出「底色仍說已選取、Delete 卻是死鍵」的混種狀態。
     if (blockSelection) return;
@@ -4935,6 +5549,27 @@
       // 降級目標（quote / code）沒有可聚焦編輯面，focusBlockAtLine 會安靜
       // no-op；把 toolbarBlockEl 指回那個 block，工具列才不會塌成 4 顆。
       reaimToolbarBlockAtLine(focusLine);
+      // backlog #6: focusBlockAtLine()'s no-op above is exactly the failure
+      // mode this closes — armEditables() never arms quote/code (no branch
+      // for either in its own condition), so blockContentEl() there hands
+      // back a plain, non-focusable <blockquote>/<pre> and .focus() on it
+      // is silently inert. MEASURED (v3.3.0): 轉換成 quote/code/line left
+      // the caret on BODY with NOTHING to click into — "a mouse user climbs
+      // out by clicking into the text" (activateToolbarCursor()'s own
+      // comment) does not even apply here, since there is no editable text
+      // to click into. The established way to edit either type at all is
+      // the ⠿ menu's own MD 原始碼 raw editor (openRawEditor(), the same
+      // one focusInsertedBlock()'s `kind === 'code'` branch already opens
+      // for a freshly INSERTED code block) — reused here rather than
+      // invented, so the landing this action leaves someone in is the
+      // block's real, only editing surface, not a caret parked over
+      // uneditable prose.
+      if (allowRawEditRescue && document.activeElement === document.body) {
+        const target = blocks.find((b) => b.startLine === focusLine);
+        const blockEl = target &&
+          document.querySelector('.ed-block[data-block-id="' + target.id + '"]');
+        if (blockEl) openRawEditor(blockEl).catch(() => {});
+      }
       return;
     }
     if (anchorLine == null) return;
@@ -5041,7 +5676,10 @@
       // 在全新 DOM 上把 roving focus 裝回 .ed-block wrapper（9 種轉換形狀全部
       // 如此），這時強行還原 caret 會製造混種狀態：底色仍說「已選取」，Delete
       // 卻變成死鍵、Shift+↓ 降級成移動文字游標。所以有選取時什麼都不做。
-      restoreAfterStructuralOp(focusLine, anchor.line);
+      // Task 9 review I4: `true` — this is the ONE call site backlog #6's
+      // raw-editor rescue is scoped to. See restoreAfterStructuralOp()'s
+      // own `allowRawEditRescue` comment.
+      restoreAfterStructuralOp(focusLine, anchor.line, true);
     }
   }
 
@@ -6269,6 +6907,13 @@
 
   function startBurst(editEl) {
     dropDiscardedBurst();
+    // v3.4.0 (Task 7 item 5): opening ANY new session — burst or raw —
+    // invalidates a still-parked raw-edit discard from a different block; see
+    // discardedRawEdit's own comment for why the two stashes must stay
+    // mutually exclusive.
+    dropDiscardedRawEdit();
+    // v3.4.0 batch3 Task 7: …and the wave twin, same rule, three stashes.
+    dropDiscardedWaveEdit();
     const blockEl = editEl.closest('.ed-block');
     if (!blockEl) return;
     const blockId = Number(blockEl.getAttribute('data-block-id'));
@@ -6714,6 +7359,19 @@
   }
   function clearBlockSelection() { blockSelection = null; applySelectionClasses(); }
 
+  // Whether a key event landed in something that takes typed characters —
+  // ANY such thing, wherever it is mounted. The block-selection key branch
+  // documents "focus is on a block wrapper and not on any text surface" as its
+  // precondition; this is that sentence as a check. `isContentEditable` covers
+  // the WYSIWYG surfaces without naming their classes, and the three tag names
+  // cover controls mounted anywhere, `.content` or not.
+  function isTextEntryTarget(el) {
+    if (el === null || el === undefined) return false;
+    if (el.isContentEditable === true) return true;
+    const tag = el.tagName;
+    return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+  }
+
   // ── S3 Task 5: surviving rerenderAll() (§4.4's ordered three steps) ────
   // `contentEl.innerHTML` is replaced wholesale on every commit, so the
   // painted tint and the roving focus holder are destroyed by definition —
@@ -7493,6 +8151,10 @@
     burst.history.flushTyping();
     editEl.innerHTML = burst.original;
     burst.history.snap('escape-discard');
+    // v3.4.0 (Task 7 item 5): mutual exclusivity with the raw-editor twin —
+    // see discardedRawEdit's own comment.
+    dropDiscardedRawEdit();
+    dropDiscardedWaveEdit();
     discardedBurst = {
       history: burst.history, editEl, blockType: burst.blockType, cellIdx: -1,
       reverted: burstBaselineHtml(editEl),
@@ -7511,6 +8173,10 @@
     burst.history.flushTyping();
     revertFn();
     burst.history.snap('escape-discard');
+    // v3.4.0 (Task 7 item 5): mutual exclusivity with the raw-editor twin —
+    // see discardedRawEdit's own comment.
+    dropDiscardedRawEdit();
+    dropDiscardedWaveEdit();
     discardedBurst = {
       history: burst.history, editEl: tableEl, blockType: 'table', cellIdx,
       reverted: burstBaselineHtml(tableEl),
@@ -7580,6 +8246,62 @@
     return true;
   }
 
+  // v3.4.0 (Task 7 item 5) — the raw-editor twin of restoreDiscardedBurst()
+  // just above. Ctrl+Z with no burst/raw editor open, when the last thing
+  // that happened was an Escape/✕ out of a raw editor: RE-OPEN that same raw
+  // editor and put the discarded text back into it — a live, dirty edit
+  // again (hasChanges() reads true against the fresh seed, so the next
+  // blur/Ctrl+Enter commits it, and a further Ctrl+Z steps back through the
+  // reopened session same as any other raw edit). Escape's own semantics —
+  // discard, and leave — are unchanged; only "gone forever" is.
+  //
+  // Staleness guard is asked at the `lines`/`blocks` level rather than the
+  // DOM level restoreDiscardedBurst() uses (`document.body.contains(editEl)`
+  // + a baseline-HTML comparison) — openRawEditor()'s own restore() tears
+  // the textarea's DOM down unconditionally (see discardedRawEdit's own
+  // comment), so there is no live node whose presence would even answer the
+  // question. What has to hold instead is SIMILAR IN SPIRIT to what
+  // reanchor() (this same file, openRawEditor()'s own re-derivation for a
+  // session that survives a patch) asks — same two questions, "does the
+  // block id still name a block?" and "are the bytes at its span still what
+  // this session last saw?" — but it is NOT the same predicate, and the two
+  // must not be conflated: reanchor()'s very first line is
+  // `if (range) return false;`, i.e. it refuses EVERY rangeMode session
+  // outright. The check below has no such refusal — for a single-block
+  // (non-range) discard it asks the two questions above and nothing else.
+  // In practice this asymmetry is moot for rangeMode: discardedRawEdit is
+  // never actually populated for a rangeMode session in the first place
+  // (see cancelAndMaybeDiscard()'s own comment — restore()'s rangeMode
+  // branch wipes the stash via rerenderAll()'s unconditional
+  // dropDiscardedRawEdit() before a Ctrl+Z could ever reach here), so this
+  // function's range-shaped `d.range` field is carried for openRawEditor()'s
+  // signature and is never exercised by a live stash today. Returns false
+  // whenever there is nothing to restore or the stash has gone stale; the
+  // caller then falls through to the ordinary document undo, same contract
+  // as restoreDiscardedBurst().
+  async function restoreDiscardedRawEdit() {
+    const d = discardedRawEdit;
+    discardedRawEdit = null;
+    if (!d) return false;
+    const b = blocks.find((x) => x.id === d.blockId);
+    if (!b || b.startLine !== d.startLine || b.endLine !== d.endLine) return false;
+    if (lines.slice(d.startLine - 1, d.endLine).join('\n') !== d.source) return false;
+    const blockEl = blockElById(d.blockId);
+    if (!blockEl) return false;
+    await openRawEditor(blockEl, d.range);
+    // Re-queried rather than reusing `blockEl` above: openRawEditor()'s own
+    // guard may have resolved a DIFFERENT open session first (switchAwayFrom()),
+    // which can re-render and hand out a fresh node for the same block id.
+    const liveBlockEl = blockElById(d.blockId);
+    const ta = liveBlockEl && liveBlockEl.querySelector('.ed-raw');
+    if (!ta) return false; // a refusal (or a lost race) beat us to it
+    ta.value = d.value;
+    const caret = Math.max(0, Math.min(d.value.length, d.caret));
+    ta.setSelectionRange(caret, caret);
+    autoSize(ta);
+    return true;
+  }
+
   // Ctrl+Z inside a burst: step the burst-local history first; only once
   // it's exhausted (atBottom — the surface is already back to its pre-focus
   // baseline) does this cascade OUT to the document-level undo() stack,
@@ -8757,6 +9479,9 @@
   // re-armed table, not a plain static one).
   function startTableBurst(cellEl) {
     dropDiscardedBurst();
+    // v3.4.0 (Task 7 item 5): see startBurst()'s own comment just above.
+    dropDiscardedRawEdit();
+    dropDiscardedWaveEdit();
     const tableEl = cellEl.closest('table');
     const blockEl = tableEl && tableEl.closest('.ed-block');
     if (!blockEl) return;
@@ -8823,9 +9548,13 @@
       // time this focusin resumes. Instrumented on the F8 fixture (a
       // paragraph left dirty, then a press into the table): the mousedown's
       // focusout resolves that paragraph, and applyRenderResult()'s patch
-      // gate consults domMatchesLastRender(), which reports false while
-      // `lastParts` is still null — as it is until a render has landed — so
-      // the render goes to applyFullRender(), whose `contentEl.innerHTML =`
+      // gate consults domMatchesLastRender(). MEASURED AT THE TIME, when
+      // `lastParts` was still null until a render landed and that is what made
+      // the gate report false. Fix round 2 (re-review G2): `lastParts` is
+      // seeded at first paint now and is never null, so the route below is
+      // reached through `lastPartsIsBootstrapSeed` instead — the ROUTE and the
+      // symptom are unchanged, only the reason the gate declines. The render
+      // goes to applyFullRender(), whose `contentEl.innerHTML =`
       // rewrites .content wholesale. A probe around the `await` above
       // recorded route ["applyFullRender"] together with
       // `document.body.contains(cellEl)` false, on each reproduction driven.
@@ -9372,28 +10101,104 @@
   // here then names a DIFFERENT block. `classList.contains('ed-wys-table')`
   // was the only guard, and every table passes it, so the gesture silently
   // rewrote an untouched neighbouring table (a row drag even promoted one of
-  // its body rows to its header). Re-resolve by `startLine` instead — see
-  // blockElAtLine()'s own comment: a startLine captured before a commit is
-  // the only stable way back to a specific block afterwards — and then
-  // verify the block we landed on really is the same table (header cell
-  // count, header cell text, row count) before handing it to a caller that
-  // is about to mutate it. A commit that shifts this table's own start line
-  // (an insert/delete ABOVE it) leaves nothing to resolve; returning null
-  // drops the gesture, which is the conservative half of the trade — never
-  // mutating the wrong table beats completing every gesture.
+  // its body rows to its header). The fix added `startLine` — see
+  // blockElAtLine()'s own comment — and a real identity check (header cell
+  // count, header cell text, row count) before handing the block to a caller
+  // that is about to mutate it.
+  //
+  // v3.4.0 Task 12: `startLine` ALONE carries the same hazard, one shape
+  // over. DRIVEN, not argued (the v3.3.0 final review tried and could not,
+  // because its fixture's commit never detached the table, so this branch
+  // never ran at all): a six-line paragraph above the table, its raw editor
+  // left dirty with a ONE-line replacement, then a row drag on the table.
+  // The drop's own switchAwayFrom() commits that raw edit — the session's
+  // first render, so it is a full `.content` rewrite and `tableEl` really is
+  // detached here — and every block below moves up 5 lines. With the two
+  // tables 5 lines apart, the SECOND table's new startLine is exactly the
+  // first one's captured one; with matching header cells and row counts,
+  // tableIdentityOf() agrees; and the drag reordered the neighbour's rows on
+  // screen and on disk while the dragged table sat untouched. Instrumented
+  // run and assertion: test/table-anchor-recovery.test.js.
+  //
+  // So this asks the SAME composite anchor handleTableCellFocusIn() above
+  // asks, for the same reason its comment writes down — the two handles fail
+  // on DIFFERENT commits (a line added ahead of the table with the block
+  // count unchanged breaks startLine but not the id; a block added ahead of
+  // it with the line count unchanged breaks the id but not startLine), so
+  // neither subsumes the other and the id is asked first. Whichever answers,
+  // tableIdentityOf() still has to agree. A commit that defeats BOTH handles
+  // leaves nothing to resolve; returning null drops the gesture, which is
+  // the conservative half of the trade — never mutating the wrong table
+  // beats completing every gesture.
+  // v3.4.0 Task 12: this used to be row count + HEADER cell text only, and
+  // that is exactly as much as two different tables in one document can
+  // share by accident — "| A | B |" over two rows describes an enormous
+  // number of real tables, and a document that repeats a header (a register
+  // map, a pin list, one table per block) has several. Both call sites use
+  // this to decide whether a block they re-resolved by a possibly-stale
+  // handle is the table the gesture started on, so a collision there is not
+  // a near miss: the row drag Task 12 drove reordered the NEIGHBOUR's rows,
+  // on screen and on disk, while the dragged table sat untouched. Every
+  // row's cells go in, so two tables collide only when their rendered text
+  // is identical cell for cell.
+  //
+  // The commit being recovered from is always some OTHER block's (a burst on
+  // THIS table early-returns before any of this), so this table's own
+  // rendered text is what it was when the handle was captured — the stronger
+  // identity refuses collisions without refusing the table itself.
+  //
+  // The delimiters are written as ESCAPES, not as literal control bytes.
+  // They used to be literal, which made grep classify this whole 9643-line
+  // file as binary and SILENTLY TRUNCATE its output — a real investigation
+  // was misled by it. The runtime value is identical.
   function tableIdentityOf(tableEl) {
     const headerRow = tableEl ? headerRowOf(tableEl) : null;
     if (!headerRow) return null;
-    // The two delimiters are written as ESCAPES, not as literal control
-    // bytes. They used to be literal, which made grep classify this whole
-    // 9643-line file as binary and SILENTLY TRUNCATE its output — a real
-    // investigation was misled by it. The runtime value is identical.
-    return allRowsOf(tableEl).length + '\x01' +
-      Array.prototype.slice.call(headerRow.cells).map((c) => c.textContent).join('\x00');
-  }
-  async function ensureTableBurstOpen(tableEl) {
+    const rows = allRowsOf(tableEl);
+    return rows.length + '\x01' + rows.map((r) =>
+      Array.prototype.slice.call(r.cells).map((c) => c.textContent).join('\x00')).join('\x02');
+  }
+  // v3.4.0 §2: `forDrag` narrows the policy above for the ROW/COLUMN DRAG
+  // callers only (performRowDrop()/performColDrop() below) — every other
+  // caller (the insert-row/insert-column hover bubbles, cycleAlign(),
+  // deleteRow/deleteColumn's own callers) keeps focusing cells[0] with a
+  // normal, scrolling focus() exactly as before, unchanged.
+  //
+  // Why a drag needs a DIFFERENT policy, not just a smaller guard elsewhere:
+  // a drag gesture never had a focused cell of its own, yet THIS function's
+  // own `cell.focus()` a few lines down is what actually opens the burst in
+  // the first place — the delegated focusin listener
+  // (handleTableCellFocusIn() above) is the ONLY path that calls
+  // startTableBurst(), so the call can't simply be skipped for a drag; the
+  // burst would never open at all, and every existing row/column drag
+  // scenario that asserts "a drop auto-starts a burst" (a cell must be
+  // focused afterward) would break. What can change for a drag, since it
+  // never had an opinion about WHICH cell should end up focused, is WHICH
+  // cell this picks and HOW it focuses it:
+  //   - `{ preventScroll: true }` — a plain focus() with no options scrolls
+  //     its target into view. A stack-traced probe (measured, not guessed —
+  //     see performRowDrop()'s own comment below for the full write-up)
+  //     found this is only HALF the "drag jumps to the header" symptom's
+  //     origin: restoreTableFocus() (below) always re-resolves and
+  //     re-focuses the SAME cell this call already focused — there is no
+  //     way to skip that second focus() by checking an index, since the
+  //     index it would check is always valid by the time it's read (same
+  //     comment). So restoreTableFocus()'s own focus() ALSO needs
+  //     `preventScroll: true` — this call alone was never going to be
+  //     enough.
+  //   - the first BODY cell (a <td>), not cells[0] (the header <th>) — a
+  //     table drag's own regression scenario asserts the resulting active
+  //     element is not a header cell. Every cell (header or body) already
+  //     carries 'ed-wys-cell' (armEditables()'s table branch, arm time), so
+  //     a body cell satisfies "a drop auto-starts a burst" exactly as well
+  //     as the header did — and restoreTableFocus() re-focuses whichever
+  //     cell THIS picks, so picking a body cell here is what keeps its own
+  //     re-focus off the header too. Falls back to cells[0] only when the
+  //     table has no body row at all (nothing to drag in that case anyway).
+  async function ensureTableBurstOpen(tableEl, forDrag) {
     if (currentBurst && currentBurst.blockType === 'table' && currentBurst.editEl === tableEl) return tableEl;
     const blockEl = tableEl.closest('.ed-block');
+    const blockIdAttr = blockEl ? blockEl.getAttribute('data-block-id') : null;
     const blockId = blockEl ? Number(blockEl.getAttribute('data-block-id')) : null;
     const block = blockId != null ? blocks.find((b) => b.id === blockId) : null;
     const startLine = block ? block.startLine : null;
@@ -9402,24 +10207,56 @@
     if (!ok) return null;
     let liveTableEl = tableEl;
     if (!document.body.contains(tableEl)) {
-      const liveBlockEl = startLine != null ? blockElAtLine(startLine) : null;
-      liveTableEl = liveBlockEl ? blockContentEl(liveBlockEl) : null;
-      // T7: both refusals used to `return null` in silence — the drag, the
+      // Both handles are gated by the SAME identity check, so a candidate
+      // that is not a live armed table, or is a table this gesture never
+      // touched, simply does not answer and the next handle gets its turn —
+      // rather than each handle carrying its own copy of the two refusals.
+      const isThisTable = (t) => !!(t && t.classList &&
+        t.classList.contains('ed-wys-table') && identity != null &&
+        tableIdentityOf(t) === identity);
+      const liveTableFrom = (candidateBlockEl) => {
+        const t = candidateBlockEl ? blockContentEl(candidateBlockEl) : null;
+        return isThisTable(t) ? t : null;
+      };
+      liveTableEl =
+        liveTableFrom(blockIdAttr != null
+          ? document.querySelector('.ed-block[data-block-id="' + blockIdAttr + '"]') : null) ||
+        liveTableFrom(startLine != null ? blockElAtLine(startLine) : null);
+      // v3.4.0 Task 12, second half: identity says "this LOOKS like the table
+      // the gesture started on", and a handle says "and it is at the place I
+      // remember". Neither says the answer was the only one available. DRIVEN
+      // on two byte-identical tables (a shape a register map or a pin list
+      // produces by itself) with the gesture on the SECOND one: the commit
+      // renumbered the ids, the captured id landed on the FIRST twin, and
+      // identity — which cannot tell twins apart, however much of the table
+      // it hashes — waved it through. The drag reordered the first table's
+      // rows and left the dragged one alone, on screen and on disk.
+      //
+      // So when the document holds more than one table this gesture could
+      // have started on, no handle is allowed to break the tie: nothing here
+      // knows which twin the user pressed, and the wrong guess rewrites a
+      // table they never touched. Refuse instead — the same conservative half
+      // of the trade this whole recovery already takes. Counted over
+      // `contentEl` (not the whole document) so the grip/bubble chrome
+      // outside it can never be mistaken for a candidate.
+      if (liveTableEl && Array.prototype.slice.call(
+        contentEl.querySelectorAll('.ed-wys-table')).filter(isThisTable).length !== 1) {
+        liveTableEl = null;
+      }
+      // T7: the refusal used to `return null` in silence — the drag, the
       // insert, the alignment change simply did not happen and nothing on
       // screen said why, which is indistinguishable from a broken control.
       // Dropping is still the right answer (see the S1 comment above); saying
       // nothing was not.
-      if (!liveTableEl || !liveTableEl.classList || !liveTableEl.classList.contains('ed-wys-table')) {
-        showBanner(DROPPED_GESTURE_MESSAGE, null, null); return null;
-      }
-      if (identity == null || tableIdentityOf(liveTableEl) !== identity) {
+      if (!liveTableEl) {
         showBanner(DROPPED_GESTURE_MESSAGE, null, null); return null;
       }
     }
     if (currentBurst && currentBurst.blockType === 'table' && currentBurst.editEl === liveTableEl) return liveTableEl;
-    const cell = tableCellsOf(liveTableEl)[0];
+    const cells = tableCellsOf(liveTableEl);
+    const cell = forDrag ? (cells.find((c) => c.tagName !== 'TH') || cells[0]) : cells[0];
     if (!cell) return null;
-    cell.focus();
+    if (forDrag) cell.focus({ preventScroll: true }); else cell.focus();
     return (currentBurst && currentBurst.blockType === 'table' && currentBurst.editEl === liveTableEl)
       ? liveTableEl : null;
   }
@@ -9449,8 +10286,40 @@
     // resolves to (which may differ from `tableEl` if a dirty burst
     // elsewhere just committed and swapped `.content` out from under this
     // click) — never the possibly-now-detached `tableEl` itself.
+    //
+    // v3.4.0 backlog #2 sister fix: same root cause as
+    // onRowInsertBubbleClick() below — `colIndex` is set by
+    // updateTableInsertBubbles() at an EARLIER hover and never re-validated
+    // against the live table here. Unlike `afterRowIndex`, `colIndex` has
+    // NO legal sentinel value at all (no "-1" case; updateTableInsertBubbles()
+    // only ever assigns 0..headerCells.length-1, each meaning "insert after
+    // column i"), so every value this dataset can legitimately hold must
+    // name a real column on `liveTableEl`. A stale colIndex that no longer
+    // does doesn't crash — insertColumn()'s `row.cells[colIndex]` lookup
+    // silently comes back undefined, and `row.insertBefore(cell, ref ?
+    // ref.nextSibling : null)` falls to its `null` branch, silently
+    // APPENDING the new column at the very END of the table instead of
+    // dropping the gesture. MEASURED (task-6-report.md): unreachable via
+    // real gesture today, guarded by the exact same two independent
+    // mechanisms as the row sibling (updateTableInsertBubbles()'s own
+    // proximity-hide, and rerenderAll()'s unconditional
+    // hideTableInsertBubbles()/hideTableGrips() on every full render) — kept
+    // as defense-in-depth against the day either one is weakened, same
+    // reasoning as the row fix.
     const liveTableEl = await ensureTableBurstOpen(tableEl);
     if (!liveTableEl) return;
+    const headerRow = headerRowOf(liveTableEl);
+    const targetCell = headerRow ? headerRow.cells[colIndex] : null;
+    // No sentinel to exclude here (contrast afterRowIndex: -1 above) — any
+    // colIndex that doesn't name a real column on the live table is stale.
+    // Same policy as the DROPPED_GESTURE_MESSAGE precedent this file already
+    // uses throughout (performBlockDrop()/performListItemDrop() et al.,
+    // 15 call sites): can't relocate it on the live table -> drop the
+    // gesture and say so, never guess.
+    if (!targetCell) {
+      showBanner(DROPPED_GESTURE_MESSAGE, null, null);
+      return;
+    }
     currentBurst.history.snap('insert-col-pre');
     insertColumn(liveTableEl, colIndex);
     armNewTableCells(liveTableEl);
@@ -9467,22 +10336,42 @@
     // Final-review Finding 6: same live-table swap as onColInsertBubbleClick()
     // above — the table element reference has to be re-resolved.
     //
-    // ⚠ RETRACTION. An earlier revision of this comment went on to say that
-    // `afterRowIndex`, being a plain integer, stays valid across that swap.
-    // Ruling T3-9 measured the opposite and parked the fix in v3.4.0: the
-    // index names a row of the table the bubble was positioned against, and
-    // after a handover it is read against a different element's row list, so
-    // `bodyRowsOf(liveTableEl)[afterRowIndex]` comes back `undefined`,
-    // `afterRow` is falsy, and insertRow() below takes its
-    // `tbody.insertBefore(newRow, tbody.firstChild)` branch — the same branch
-    // `afterRowIndex: -1` uses deliberately. The row lands at the TOP of the
-    // table rather than the gesture being dropped. Nothing here guards it yet.
-    // Task 14's hide-on-approach fix (see updateTableInsertBubbles() below)
-    // made this bubble reliably pressable, which widened the exposure of that
-    // deferred defect rather than narrowing it.
+    // ⚠ RETRACTION, resolved in v3.4.0 (backlog #2). An earlier revision of
+    // this comment went on to say that `afterRowIndex`, being a plain
+    // integer, stays valid across that swap. Ruling T3-9 measured the
+    // opposite: `afterRowIndex` is set by updateTableInsertBubbles() at
+    // HOVER time, which can be arbitrarily earlier than this click — the
+    // table's row count can shrink in between (its own delete-row, an undo,
+    // anything) without a fresh mousemove ever repositioning the bubble to
+    // notice. `tableIdentityOf()`'s row-count component (used by
+    // ensureTableBurstOpen()'s own detached-table guard below) does NOT
+    // catch this: identity is captured from `tableEl` at THIS click, in the
+    // same synchronous prefix as `afterRowIndex` was just read above — it
+    // always matches whatever the table looks like right now, so a handover
+    // whose SOURCE the row count came from is unrelated to this table passes
+    // it clean. `bodyRowsOf(liveTableEl)[afterRowIndex]` is the only place
+    // that can see the stale index was for a row that no longer exists — a
+    // naive `afterRow` falsy check does not distinguish "no row after this
+    // one" (afterRowIndex: -1, `null` deliberately) from "this index no
+    // longer names anything" (`undefined`), and insertRow() treats both
+    // identically: `tbody.insertBefore(newRow, tbody.firstChild)`, i.e. the
+    // row lands at the TOP of the table instead of the gesture being
+    // dropped. Task 14's hide-on-approach fix (see updateTableInsertBubbles()
+    // below) made this bubble reliably pressable, which widened the exposure
+    // of this deferred defect rather than narrowing it.
     const liveTableEl = await ensureTableBurstOpen(tableEl);
     if (!liveTableEl) return;
     const afterRow = afterRowIndex >= 0 ? bodyRowsOf(liveTableEl)[afterRowIndex] : null;
+    // afterRowIndex >= 0 names a SPECIFIC row that must still exist on the
+    // live table; afterRowIndex === -1 deliberately produces a `null`
+    // afterRow (the header-boundary/first-body-row case) and must NOT be
+    // caught here. Same policy as performRowDrop()/runDeleteRow() above:
+    // can't relocate it on the live table -> drop the gesture and say so,
+    // never guess.
+    if (afterRowIndex >= 0 && !afterRow) {
+      showBanner(DROPPED_GESTURE_MESSAGE, null, null);
+      return;
+    }
     currentBurst.history.snap('insert-row-pre');
     insertRow(liveTableEl, afterRow);
     armNewTableCells(liveTableEl);
@@ -9816,9 +10705,32 @@
   // ~104px to ~60px, which puts the menu under the toolbar while the grip that
   // opens it is still comfortably clickable. Both numbers were measured on
   // this branch, on either side of that change.
-  function placeTeMenuAboveCell(r) {
-    const topInset = parseFloat(getComputedStyle(document.documentElement)
+  /**
+   * The y a viewport-anchored affordance may not go above.
+   *
+   * The toolbar owns the top of the viewport and it owns it at `z-index: 101`,
+   * which is above every floating thing this file positions — so an affordance
+   * placed at a smaller `top` is not merely close to the toolbar, it is UNDER
+   * it: painted, hit-tested and clicked by the bar instead. `--ed-toolbar-h` is
+   * the height the bar reserves, and it is the floor `.ed-te-menu` and
+   * `.ed-seltb` already use; v3.4.0 batch 1 moved `.ed-conflict` to the same
+   * value for the same reason.
+   *
+   * It is a FUNCTION and not a copy of the number in three places because the
+   * number was copied in three places: `.ed-wave-edit-btn` floored at `4`
+   * instead, and measured at 1200x800 with a 180px diagram scrolled to
+   * `r.top = -60` the button painted at `top: 4`, `elementFromPoint` on its own
+   * centre returned `DIV.ed-toolbar`, and a real click left the editor closed —
+   * with no keyboard entry to fall back on, that scroll position had no way in
+   * at all. The next affordance reads this instead of rediscovering it.
+   */
+  function toolbarTopInset() {
+    return parseFloat(getComputedStyle(document.documentElement)
       .getPropertyValue('--ed-toolbar-h')) || 0;
+  }
+
+  function placeTeMenuAboveCell(r) {
+    const topInset = toolbarTopInset();
     let top = r.top - teEdgeMenu.offsetHeight - TE_MENU_GAP_PX;
     if (top < topInset) top = r.bottom + TE_MENU_GAP_PX;
     teEdgeMenu.style.top = top + 'px';
@@ -10390,21 +11302,82 @@
     // from table-leave, burst-end, and drag-start elsewhere) already covers
     // every path that actually needs to clear it.
     //
-    // ⚠ KNOWN GAP, deferred by Ruling T14-5 to v3.4.0: the list below names the
-    // two grips and NOT '.ed-tb-insert', so the hover-insert ＋ bubble — which
-    // is the same kind of `position: fixed` overlay painted over the same band
-    // — falls through to the branches beneath and takes the ⠿ grips down while
-    // the pointer stands on it. The reason it was not closed here is that
-    // widening this test also widens the early return's setGutterKeep() call,
-    // whose behaviour on the ＋ bubble is unmeasured. A reader of this function
-    // should know it is knowingly incomplete rather than infer the list is the
-    // whole set.
-    if (target && target.closest && (target.closest('.ed-te-grip-row') || target.closest('.ed-te-grip-col'))) {
+    // v3.4.0 (backlog #11, closing Ruling T14-5's deferral): the list below
+    // now also names '.ed-tb-insert' — the hover-insert ＋ bubble is the same
+    // kind of `position: fixed` overlay painted over the same band as the two
+    // grips, and without this the pointer standing on it fell through to the
+    // branches beneath and took the ⠿ grips down (hideTableGrips() nulling
+    // gripRowTableEl/gripRowEl/gripColTableEl/gripColIndex, not just hiding
+    // the DOM).
+    //
+    // MEASURED effect on setGutterKeep(), which T14-5 left unmeasured: on a
+    // 2-row/2-col fixture, hovering the header row raised the row grip at
+    // rect {left:402, top:175.7, right:422, bottom:203.7}. The row-insert
+    // bubble for "after the header row" rendered at {left:403, top:199.4,
+    // right:421, bottom:217.4} — the bubble's OWN vertical centre (208.4)
+    // already sits 0.6px below pointInRowGripZone()'s padded zone (bottom
+    // 207.7 = grip bottom + the 4px pad), so a pointer landing there hit the
+    // "not in zone" branch and called hideTableGrips() even before this fix.
+    // Only the bubble's own top ~8px sliver (199.4-207.7) actually overlaps
+    // the zone. Review round 2, M2: that 8.4px is this fixture's number, not
+    // a constant — the general form (derived from the row grip's fixed
+    // CSS height 28px, vertically centred on its own row per
+    // buildTableGrip()/the row-grip positioning above, TE_GRIP_ZONE_PAD_PX=4,
+    // and the bubble's own half-height 9px) is
+    // `overlap = max(0, 27 - headerRowHeight / 2)` for any header row
+    // taller than 18px (shorter than that and the whole 18px bubble sits
+    // inside the zone — unreachable in practice, since padding alone
+    // ('th, td { padding: 7px 14px }') already puts a real header row above
+    // it). It hits 0 — no overlap at all — once the header row is >=54px
+    // tall. This fixture's 37.3px header row gives 27 - 18.6 = 8.4, matching
+    // the measured number above.
+    //
+    // The column-insert bubble does NOT overlap the row grip's
+    // zone on the fixture measured above (x=[884.6, 902.6] against the
+    // grip's padded x=[398,426]) — review round 2 corrected an earlier draft
+    // of this comment that called that "structural", i.e. impossible in
+    // general. It is not: the column bubble sits at `cellRight - half`
+    // (half = TB_BUBBLE_SIZE/2 = 9), so it overlaps the row grip's own
+    // padded zone (right edge at tableLeft + TE_GRIP_ZONE_PAD_PX = tableLeft
+    // + 14, see pointInRowGripZone()) whenever `cellRight <= tableLeft + 23`.
+    // The FIRST column is the only one close enough to matter, and its
+    // MINIMUM width from `th, td { padding: 7px 14px; border: 1px solid … }`
+    // alone (an empty or near-empty first cell) is ~30px — a 7px margin
+    // above the 23px threshold, not a structural gap. That margin is a CSS
+    // padding constant, not a geometric guarantee, and this repo's own
+    // `table { overflow-x: auto }` can erode it directly: scrolling a wide
+    // table's inner content moves `cellRect.right` toward (and, scrolled far
+    // enough, past) `tableRect.left` while the row grip stays anchored to
+    // the table's own (unscrolled) left edge, so the same overlap this
+    // function already tolerates for the row-insert bubble becomes reachable
+    // for the column-insert bubble too on a sufficiently scrolled table. The
+    // BEHAVIOUR conclusion is unaffected either way — that path's delta is
+    // still only the same cosmetic keep-lit loss described above, since
+    // '.ed-tb-insert' never matches '.ed-te-grip-row' regardless of which
+    // bubble the pointer is on — only the "never" in this comment was wrong.
+    //
+    // So the only real change is: for the narrow case where (a) the header
+    // row's own grip is the one currently shown AND (b) the pointer is in
+    // that ~8px sliver of the header row's insert bubble, the old fallback
+    // branch below (pointInRowGripZone()/pointInColGripZone(), reached by
+    // NOT matching this guard) could call setGutterKeep(headerGripBlock())
+    // and light the gutter; the widened guard here calls setGutterKeep(null)
+    // unconditionally instead (same as the existing column-grip branch),
+    // because '.ed-tb-insert' never matches '.ed-te-grip-row'. The ⠿'s
+    // keep-lit assist is not applied while the pointer sits in that sliver.
+    // Accepted: it is a purely cosmetic loss (the block's own :hover keeps
+    // the ⠿ visible whenever the pointer is actually over the block; keep-lit
+    // only covers the pointer being OUTSIDE it) confined to an ~8px band on
+    // one bubble, against hideTableGrips() tearing down all four module-level
+    // refs and both grips' DOM visibility on every approach to any bubble —
+    // the defect this task exists to close.
+    if (target && target.closest &&
+      (target.closest('.ed-te-grip-row') || target.closest('.ed-te-grip-col') || target.closest('.ed-tb-insert'))) {
       // v3.0.2: only the ROW grip is the one that covers the ⠿'s approach.
       // Testing the hit rather than reusing the branch condition matters —
-      // the column grip sits above the table's top border, nowhere near the
-      // ⠿, and lighting the gutter from there is the behaviour change this
-      // fix is scoped to avoid.
+      // the column grip (and, as of v3.4.0, the insert bubble) sits nowhere
+      // near a position lighting the gutter should follow, and lighting it
+      // from there is the behaviour change this fix is scoped to avoid.
       setGutterKeep(target.closest('.ed-te-grip-row') ? headerGripBlock() : null);
       return;
     }
@@ -10715,13 +11688,47 @@
   // 吃掉之後沒有人會把焦點放回去，document.activeElement 會落到 <body>，
   // 於是 keydown 走不到 handleTableCellKeydown，Ctrl+Z 會落到全域 undo()
   // 而先 commit 再退。用序位重新解析目標格並真的 focus。
+  // v3.4.0 §2 (measured, not guessed — see the two call sites' own comment
+  // below for the full chain): by the time this runs, BOTH callers' drags
+  // already have SOME cell focused — either the burst was already open
+  // (the user had genuinely clicked/edited a cell themselves;
+  // ensureTableBurstOpen() early-returns without calling focus() at all in
+  // that case) or ensureTableBurstOpen() just opened a fresh one via its
+  // own `forDrag` branch (which DOES call focus(), on the first body
+  // cell). Either way, a plain focus() here was re-focusing that SAME cell
+  // a second time — a stack-traced probe caught exactly that: two focus()
+  // calls on the identical element, the second one (this one) with no
+  // options, immediately followed by the page scrolling. `preventScroll`
+  // stops that second, redundant scroll without changing which cell ends
+  // up focused.
+  // v3.4.0 §2: `cellIndex < 0`'s fallback used to be `cells[0]` — the
+  // header cell — inherited from before this function had a `forDrag`-style
+  // "avoid the header" policy anywhere. It stayed reachable in theory (a
+  // negative index means "no cell to re-resolve"), but the row/col-drop
+  // stale-index defect fixed below (both call sites now re-resolve against
+  // a rebuild-stable coordinate rather than a cell reference/ordinal that
+  // may have moved) removes every realistic path that could still produce
+  // one here: a drag never deletes the active row/cell, only reorders it,
+  // so a valid `activeCellEl` captured before the drop always resolves to
+  // SOME live cell afterward. Changed anyway, defensively, since both of
+  // this function's only two callers are drag paths (same fact the
+  // `forDrag` policy above is built on): prefer the first BODY cell over
+  // the header, same as `ensureTableBurstOpen()`'s own `forDrag` pick — a
+  // drag landing on the header is exactly the symptom this whole task
+  // fixed, so a fallback that still could is worth closing even if nothing
+  // currently reaches it. Falls through to `cells[0]` only when the table
+  // has no body row at all; `if (!cell) return` below still means "don't
+  // focus anything" for the fully-empty case, covering that alternative
+  // too.
   function restoreTableFocus(tableEl, cellIndex) {
     const cells = tableCellsOf(tableEl);
-    const cell = cells[cellIndex >= 0 ? Math.min(cellIndex, cells.length - 1) : 0];
+    const cell = cellIndex >= 0
+      ? cells[Math.min(cellIndex, cells.length - 1)]
+      : (cells.find((c) => c.tagName !== 'TH') || cells[0]);
     if (!cell) return;
     if (currentBurst && currentBurst.blockType === 'table') currentBurst.activeCellEl = cell;
     selToolbarEditEl = cell;
-    cell.focus();
+    cell.focus({ preventScroll: true });
     placeCaretAtEnd(cell);
   }
 
@@ -10730,7 +11737,11 @@
     // 可能 resolve 掉別的 block 的 dirty burst 並換掉整片 .content，所以
     // 先轉成 allRowsOf() 的 ordinal，之後在 live table 上重新定位。
     const rowIndex = allRowsOf(tableEl).indexOf(rowEl);
-    const liveTableEl = await ensureTableBurstOpen(tableEl);
+    // v3.4.0 §2: `forDrag=true` — see ensureTableBurstOpen()'s own comment.
+    // A row drag never had a focused cell of its own, so if this call is
+    // the one that opens the burst, it must neither scroll the page nor
+    // land on the header cell.
+    const liveTableEl = await ensureTableBurstOpen(tableEl, true);
     if (!liveTableEl) return;
     const liveRows = allRowsOf(liveTableEl);
     if (rowIndex < 0 || !liveRows[rowIndex]) return;
@@ -10747,8 +11758,55 @@
 
     currentBurst.history.snap('drag-row-pre');
     const aligns = columnAlignsOf(liveTableEl);
-    const activeIndex = (currentBurst && currentBurst.activeCellEl)
-      ? tableCellsOf(liveTableEl).indexOf(currentBurst.activeCellEl) : -1;
+    // v3.4.0 §2（量出來的，不是猜的）：這裡曾經寫過
+    // `if (activeIndex >= 0) restoreTableFocus(...)`，想法是拖曳沒點過任何
+    // 儲存格時 activeIndex 應該是 -1、藉此跳過這次呼叫。實測證明那個模型
+    // 錯了——`activeIndex` 在這裡結構上永遠 >= 0：ensureTableBurstOpen()
+    // 只有在 currentBurst 確實是這個表格時才會回傳非 null，而
+    // `currentBurst.activeCellEl` 在 startTableBurst() 建立 currentBurst
+    // 的同一個賦值式裡就一定被設好（不管 burst 是本來就開著、還是這次
+    // ensureTableBurstOpen() 的 forDrag 分支剛開的）。所以「用 index 判斷
+    // 要不要呼叫 restoreTableFocus()」這條路走不通，不要再試。
+    //
+    // 真正的捲動來源是 restoreTableFocus() 自己那次 focus()：它一定會把
+    // ensureTableBurstOpen() 剛剛（forDrag、preventScroll、挑 body 儲存格）
+    // 已經對好焦的那顆儲存格，重新 focus 一次——用一支外接的 stack-trace
+    // 探針量到兩次 focus() 打在同一顆元素上，第二次沒帶 preventScroll，
+    // 緊接著就是那次把畫面拉回去的捲動。修法落在 restoreTableFocus() 自己
+    // 身上（它的 cell.focus() 現在帶 { preventScroll: true }），這裡維持
+    // 無條件呼叫。
+    //
+    // 另一個既存缺陷（跟以上兩件事無關，重排「之前」量、「之後」用同一個
+    // 序位）：原本 `activeIndex` 在這裡（rebuildTableSections() 之前）用
+    // `tableCellsOf(liveTableEl).indexOf(currentBurst.activeCellEl)` 算好，
+    // 卻在下面 restoreTableFocus() 裡對「重排之後」的 cell 清單使用——重排
+    // 只要讓被拖那列插到 activeCellEl 那列前面，中間隔的 cell 數就變了，
+    // 舊序位對到的會是別的儲存格（使用者正在打字那格，焦點卻被丟到別的
+    // TD，接下來每一鍵都寫進錯的儲存格）。用一支 stack-trace 探針量過：
+    // rebuildTableSections() 本身只搬 <tr>（appendChild，never 重建），但
+    // retagCell() 在該列跨越表頭／本文邊界（被升格成表頭或被降成本文）時
+    // **會**造出全新的 <td>/<th>（複製屬性、不是同一顆物件）——用 JS
+    // expando 屬性（不是 HTML attribute，因為 attribute 會被複製過去，測
+    // 不出是不是同一顆）量過：不跨表頭時標記存活，跨表頭時標記消失。
+    // <tr> 元素本身兩種情況都不變（只有 appendChild 搬過），所以「列＋欄」
+    // 這組座標在重排前後都穩，序位不穩。改成：重排前記下 activeRowEl（那
+    // 顆 <tr>）與 activeColIdx（欄序，colIndexOf() 已有）；重排、
+    // armNewTableCells() 都跑完之後，用 `activeRowEl.cells[activeColIdx]`
+    // 重新取得那顆儲存格（不管 retagCell() 換過沒有，同一列同一欄序就是
+    // 使用者原本在打字的那顆），再轉回 restoreTableFocus() 要的序位。
+    // Review fix (M2): `document.body.contains()` first — same guard
+    // refocusAwayFromColumn()/refocusAwayFromRow() above both use before
+    // their own colIndexOf() call. `activeCellEl` DETACHED (not merely
+    // stale) is a state this file already treats as reachable there;
+    // colIndexOf() reads `cellEl.parentElement.cells`, which throws on a
+    // detached node whose parentElement is null — unlike the old
+    // `tableCellsOf(...).indexOf(...)` this replaced, which just returned
+    // -1 for a detached cell. Thrown here (after `history.snap('drag-row-pre')`,
+    // before the reorder) would silently drop the whole gesture.
+    const activeCellBefore = (currentBurst && currentBurst.activeCellEl &&
+      document.body.contains(currentBurst.activeCellEl)) ? currentBurst.activeCellEl : null;
+    const activeRowEl = activeCellBefore ? activeCellBefore.parentElement : null;
+    const activeColIdx = activeCellBefore ? colIndexOf(activeCellBefore) : -1;
     suppressTableFocusout = true;
     try {
       rebuildTableSections(liveTableEl, order, aligns);
@@ -10756,6 +11814,8 @@
       suppressTableFocusout = false;
     }
     armNewTableCells(liveTableEl);
+    const restoredCell = (activeRowEl && activeColIdx >= 0) ? activeRowEl.cells[activeColIdx] : null;
+    const activeIndex = restoredCell ? tableCellsOf(liveTableEl).indexOf(restoredCell) : -1;
     restoreTableFocus(liveTableEl, activeIndex);
     // 插入路徑早就這樣做了，drop 路徑一直沒有：不清的話 grip 還釘在舊
     // 座標、teMenuColIndex 指向已經換位的欄。
@@ -10792,11 +11852,10 @@
   }
 
   async function performColDrop(tableEl, fromIndex, toIndex) {
-    const liveTableEl = await ensureTableBurstOpen(tableEl);
+    // v3.4.0 §2: `forDrag=true` — same reasoning as performRowDrop() above.
+    const liveTableEl = await ensureTableBurstOpen(tableEl, true);
     if (!liveTableEl) return;
     if (toIndex === fromIndex || toIndex === fromIndex + 1) return; // 原地放回
-    const activeIndex = (currentBurst && currentBurst.activeCellEl)
-      ? tableCellsOf(liveTableEl).indexOf(currentBurst.activeCellEl) : -1;
     // 短列必須讓整個操作放棄，不能只跳過那一列（final review M4）：原本
     // `if (!moved) return;` 在 forEach 裡面，短列會被略過、其他列照搬 —— 結果
     // 是欄位彼此錯位，而每一列的 cell 數量都跟原本一樣，ragged-table guard
@@ -10816,6 +11875,27 @@
     } finally {
       suppressTableFocusout = false;
     }
+    // v3.4.0 §2（量出來的，不是猜的——完整說明見 performRowDrop() 對應處的
+    // 同一段註解）：這裡曾經寫過 `if (activeIndex >= 0) restoreTableFocus(...)`，
+    // 想靠 index 擋掉這次呼叫，但 `activeIndex` 在這裡結構上永遠 >= 0
+    // （ensureTableBurstOpen() 只有在 currentBurst 確實是這個表格時才回傳
+    // 非 null，而 currentBurst.activeCellEl 在 startTableBurst() 建立
+    // currentBurst 的同一個賦值式裡就一定被設好）——這條路走不通，不要
+    // 再試。真正的捲動來源是 restoreTableFocus() 自己那次 focus()，修法
+    // 落在它自己身上（`{ preventScroll: true }`），這裡維持無條件呼叫。
+    //
+    // 另一個既存缺陷，跟列拖曳同根、但失效方式不同（欄重排動的是「同一列
+    // 裡 cell 的順序」，不是列本身）：這裡原本也是在上面重排「之前」用
+    // `tableCellsOf(liveTableEl).indexOf(currentBurst.activeCellEl)` 算
+    // `activeIndex`，重排之後才用——欄一旦搬過，每一列裡 cell 的順序都變
+    // 了，`tableCellsOf()`（跨全表攤平）算出來的序位一樣是舊的。用同一支
+    // 探針量過：欄重排的 forEach 是 `row.appendChild(c)`，對已經是那個
+    // row 子節點的 cell 只是搬動、從不建立新節點（跟列拖曳的 retagCell()
+    // 不同，欄拖曳完全不牽涉 TH／TD 轉換），所以不需要「列＋欄」那組座標
+    // ——重排後直接用同一顆 `currentBurst.activeCellEl` 物件重算一次
+    // indexOf() 就對了，物件本身沒被換過。
+    const activeIndex = (currentBurst && currentBurst.activeCellEl)
+      ? tableCellsOf(liveTableEl).indexOf(currentBurst.activeCellEl) : -1;
     restoreTableFocus(liveTableEl, activeIndex);
     hideTableGrips();
     hideTableEdgeMenu();
@@ -11661,6 +12741,12 @@
     // next one.
     blockSelClickSuppressed = false;
     if (blockSelDrag) endBlockSelDrag();
+    // Every defensive teardown above still runs — they are no-ops that must not
+    // be skipped — but nothing behind the modal ARMS a new gesture. The backdrop
+    // already makes this unreachable (measured: a Shift+press-drag on the canvas
+    // and a press-drag on the backdrop both leave the selection null); it is
+    // here so that stays true if the backdrop ever stops being `inset: 0`.
+    if (waveEditorIsModal()) return;
     const hit = hitTestGrip(e.target);
     // A click on a DIFFERENT zone (or entirely outside any zone) dismisses
     // whatever menu is already open, same "any other click closes the ⠿
@@ -12440,6 +13526,15 @@
       snapBurstIfActive(root, 'mark');
       return false;   // unwrapped in place — no modal ever opened
     }
+    // v3.4.0 / v3.3.0 backlog 4: applyMarkToggle() guards its wrap branch with
+    // trimRangeToText() before wrapping; this new-link branch never had the
+    // matching guard. A whitespace-only selection (the space between two
+    // words, say) reached window.prompt() and, on accept, extractRangeInto()
+    // wrapped that bare space in an <a> — an anchor whose entire content was
+    // one space, written straight to disk. Trim first: an all-whitespace
+    // range trims to nothing and trimRangeToText() returns false, so bail
+    // before ever opening the prompt.
+    if (!trimRangeToText(range)) return false;
     const url = window.prompt('連結網址：', 'https://');
     if (url === null || url.trim() === '') return true; // cancelled or empty — no-op
     snapBurstIfActive(root, 'mark-pre');
@@ -12539,8 +13634,7 @@
     const rect = range.getBoundingClientRect();
     // v3.2.1: 原本的零矩形檢查是死碼 —— 實測捲出視野的 Range 仍保有
     // 151x17 的矩形，永遠到不了這一支。改成真正的視窗外檢查。
-    const topInset = parseFloat(getComputedStyle(document.documentElement)
-      .getPropertyValue('--ed-toolbar-h')) || 0;
+    const topInset = toolbarTopInset();
     if (rect.bottom <= topInset || rect.top >= window.innerHeight ||
         rect.right <= 0 || rect.left >= window.innerWidth) {
       // Task 16: of the exits that take this bar down, this is the one that
@@ -12573,8 +13667,25 @@
   // the raw textarea directly on click, no bar/menu step) — see
   // armEditables() above. What's left to route here is: the lightbox
   // exclusion, the ⠿ handle/menu, and opening a degraded block's raw editor.
+  // Fix round 3 (re-review2 Q2): `.drawio` belongs here for the same reason
+  // every other entry does — it is a lightbox target in the reader runtime
+  // (`LIGHTBOX_TARGETS` in lib/md2doc.js), and a click that opens the lightbox
+  // must not ALSO be routed as a click on the block.
+  //
+  // MEASURED before adding it, in a real editor page with a diagram in an
+  // armed paragraph and the same diagram in a DEGRADED table:
+  //   paragraph  lightbox flex/visible, `.ed-raw` count 0, activeElement BODY
+  //              (the armed branch already returns above — no consequence)
+  //   table      lightbox flex/visible, `.ed-raw` count 1,
+  //              activeElement TEXTAREA.ed-raw
+  // i.e. on a degraded block the raw markdown editor silently opened BEHIND
+  // the lightbox. With `.drawio` listed, the diagram behaves exactly like the
+  // `img` / `.mermaid` / `.graphviz` / WaveDrom entries beside it: clicking
+  // the picture opens the picture and nothing else. No capability is lost
+  // that those four do not already lack — the block's source is still one
+  // click away anywhere else in the block.
   const ED_LIGHTBOX_TARGETS =
-    'img, .mermaid, .graphviz, [id^="WaveDrom_Display_"], .wavedrom-diagram';
+    'img, .mermaid, .graphviz, .drawio, [id^="WaveDrom_Display_"], .wavedrom-diagram';
 
   // Single delegated listener, wired once at the bottom of this file. Async
   // because clicking another block (or outside any block) while some
@@ -12687,6 +13798,14 @@
       // would also fall through to "clicked outside any block" below and
       // fire an unwanted switchAwayFrom() right after the menu just opened.
       if (e.target.closest('.ed-te-grip')) return;
+      // v3.4.0 batch3 Task 6: while the wave editor is the modal surface,
+      // nothing behind it takes clicks. This replaced a pair of `closest()`
+      // exclusions for the overlay and its entry button: those were right about
+      // the two cases they named — a click on either used to fall through to
+      // "clicked outside any block" and fire switchAwayFrom() on the document
+      // behind the modal — and wrong about being a list at all.
+      if (waveEditorIsModal()) return;
+      if (e.target.closest('.ed-wave-edit-btn')) return;
       // Task 9: task-list checkbox toggle. The .ed-li-check span is
       // non-focusable chrome — no per-node listener, routed here by
       // delegation. Gate BEFORE mutation (same contract as the structural
@@ -12828,6 +13947,39 @@
 
   // ── save ───────────────────────────────────────────────────────────────
   async function save() {
+    // fix 3: the receipt for the bytes about to leave, taken BEFORE the request
+    // and not after it. `markSaved()` used to read the stack depth when the
+    // RESPONSE landed, and a save round trip is hundreds of milliseconds —
+    // easily long enough to press Ctrl+Z in. MEASURED: type, commit, Ctrl+S,
+    // Ctrl+Z inside the round trip — the 200 marked the post-undo depth as the
+    // saved point, so the title dot went out, the save button greyed,
+    // `beforeunload` stopped firing, AND `mtimeMs` had just advanced so the
+    // conflict check would not catch it either. All three nets failed at once,
+    // and the tab closed leaving on disk an edit the user had explicitly undone.
+    // See UndoStack.saveToken()/markSaved() for why the receipt carries an op
+    // identity and not just a depth.
+    const token = stack.saveToken();
+    //
+    // ⚠ There is deliberately NO in-flight lock and no supersede guard here, and
+    // that is a correction of something this file briefly carried. The premise
+    // for dropping an "older" reply was that a later request's bytes are what
+    // disk ends up holding. That premise is FALSE: the server 409s whenever
+    // `baseMtimeMs` does not match the file (server.js's /api/save), and
+    // `mtimeMs` has exactly one writer — the 200 branch below. So a second save
+    // sent while the first is still in flight necessarily carries a stale
+    // baseline, necessarily 409s, and necessarily writes nothing. The FIRST
+    // reply is the one that describes what is on disk, and dropping it is the
+    // defect, not the fix. MEASURED with the guard in place: type, Ctrl+S,
+    // Ctrl+Z, Ctrl+S — the first 200 was discarded, `markSaved()` never ran, and
+    // the document read CLEAN with the edit still on disk; and without any undo
+    // at all, two Ctrl+S in a row left `mtimeMs` stale forever, so every later
+    // save 409'd and the only way out was the conflict banner's reload. An
+    // exhaustive depth-6 sweep counted 48 settled under-warns with the guard and
+    // 0 without it.
+    //
+    // The receipt above is what makes a late reply safe without any of that: it
+    // describes the bytes it was taken for, so a reply that no longer matches
+    // the timeline refuses itself.
     let res;
     try {
       res = await fetch('/api/save', {
@@ -12848,8 +14000,17 @@
         return;
       }
       mtimeMs = j.mtimeMs;
-      stack.markSaved();
+      stack.markSaved(token);
       setDirty();
+      // v3.4.0 §3: markSaved() just moved documentIsDirty() from true to
+      // false, and the `save` button's own lit/grey state is read off
+      // exactly that value (toolbarContext()'s `dirty` field) — without this
+      // the button stays lit after a successful save until some UNRELATED
+      // gesture happens to repaint the bar. Same repaint entry point
+      // setDirty()'s own callers already share (updateToolbar() diffs its
+      // own signature, so this is cheap on the common "toolbar was already
+      // caught up" case).
+      updateToolbar();
       return;
     }
     if (res.status === 409) {
@@ -12863,6 +14024,140 @@
     showBanner('Save failed — ' + reason + '; changes NOT saved.', null, null);
   }
 
+  // v3.4.0 §3: the "resolve whatever is open, THEN save" precondition —
+  // Ctrl+S's own keydown handler already carries the full explanation (a
+  // mid-burst keystroke has not reached `lines` yet, so save() must not run
+  // before switchAwayFrom() does). The toolbar `save` button needs the
+  // identical precondition, so both callers share this one function instead
+  // of each spelling out `switchAwayFrom().then(...)` on its own — not a
+  // copy of save()'s own body, just its one caller-side precondition named
+  // once.
+  async function commitThenSave() {
+    const ok = await switchAwayFrom();
+    if (ok) return save();
+  }
+
+  // v3.4.0 §3: the save button's own caret rescue. commitThenSave() above
+  // may resolve (commit + re-render) a still-open burst before save() ever
+  // runs, and that render is exactly the class of render that strands the
+  // caret on BODY when the caret was sitting inside the block being
+  // replaced — recorded, for undo/redo/image, in activateToolbarCursor()'s
+  // own comment ("join them ONLY when the surface has an uncommitted
+  // edit"), and unconditionally for quote/code/line (backlog #6, still
+  // open). `save` must not become a fourth name on that list — and
+  // deliberately does NOT reuse undo()/redo()'s own path to avoid it:
+  // neither of them has any rescue at all (that gap is recorded as
+  // deferred, not fixed), so there is nothing there worth copying.
+  //
+  // What captureCaretForSave() saves: which `.ed-block` the caret's FOCUS
+  // end was in (`data-block-id` — stable across a same-shape commit, since
+  // buildBlockMap() numbers every block by document order starting at 0 on
+  // every render, and a text-only edit that neither adds nor removes a
+  // block leaves every block's id exactly where it was) and how many
+  // characters into that block's own rendered text that end sat (every text
+  // node before it, concatenated — the same measure
+  // `Range.toString().length` gives over a selectNodeContents() range
+  // clipped to that point). restoreCaretForSave() reverses it: walk the
+  // (possibly brand-new) block's text nodes until that many characters are
+  // consumed, and collapse a Range there. It is a no-op whenever the caret
+  // was never stranded in the first place (the common case — a clean
+  // document, or a burst with nothing uncommitted, never touches the DOM at
+  // all) — checked by asking whether focus is still on BODY afterwards, not
+  // by trying to predict which of the paths above ran.
+  //
+  // Review C1: `sel.focusNode`/`focusOffset`, not `anchorNode`/
+  // `anchorOffset`, and no `!sel.isCollapsed` bail-out. The first version
+  // gave up on any non-collapsed selection entirely — MEASURED: type at the
+  // end of a block without committing, extend the selection left with
+  // Shift+ArrowLeft, click save — restoreCaretForSave() never ran at all
+  // (captureCaretForSave() had already returned null), and the caret was
+  // left exactly where quote/code/line leave it: on BODY, typing silently
+  // discarded. That is backlog #6's own symptom, reached through a keyboard
+  // path that is not remotely rare (fix a typo with Shift+Arrow, then Ctrl+
+  // S/Alt+F10+Enter on `save`). A collapsed caret is only the special case
+  // where anchor and focus already coincide; using focus and dropping the
+  // guard restores BOTH cases through one path. Collapsing the RESTORED
+  // caret at that single point (rather than reconstructing the whole
+  // pre-click range) is deliberate — landing at the focus end, one keyboard
+  // Shift+Arrow removed from BODY rather than on it, is what backlog #6
+  // asks for; there is no saved anchor position left to rebuild a
+  // non-collapsed selection FROM once the block has been re-rendered.
+  function captureCaretForSave() {
+    const sel = typeof window.getSelection === 'function' ? window.getSelection() : null;
+    if (!sel || sel.rangeCount === 0) return null;
+    const focus = sel.focusNode;
+    if (!focus) return null;
+    const host = focus.nodeType === 1 ? focus : focus.parentElement;
+    const blockEl = host && host.closest ? host.closest('.ed-block') : null;
+    if (!blockEl) return null;
+    const blockId = blockEl.getAttribute('data-block-id');
+    if (blockId === null) return null;
+    const measure = document.createRange();
+    measure.selectNodeContents(blockEl);
+    measure.setEnd(focus, sel.focusOffset);
+    return { blockId: blockId, offset: measure.toString().length };
+  }
+
+  function restoreCaretForSave(saved) {
+    // Nothing to do when the caret was never stranded — leave whatever is
+    // focused (including a genuinely different block the user clicked into
+    // meanwhile) alone.
+    if (!saved || document.activeElement !== document.body) return;
+    const blockEl = contentEl.querySelector(
+      '.ed-block[data-block-id="' + saved.blockId + '"]');
+    // Review M1: `blockEl` is null whenever the commit added or removed
+    // blocks (buildBlockMap() renumbers by document order, so `save`'s own
+    // commit — a plain text edit — cannot do this, but a future caller of
+    // captureCaretForSave()/restoreCaretForSave() might run them around
+    // something structural). There is no corresponding block left to place
+    // a caret in at all, so this silently leaves the caret on BODY — a
+    // strict improvement over guessing at a different block, but not a full
+    // rescue. Falling back to `document.body.focus()` would not help either
+    // (BODY is not focusable), so this is left as a documented, narrower
+    // gap rather than a fixed one.
+    const surface = blockEl && blockContentEl(blockEl);
+    if (!surface) return;
+    const walker = document.createTreeWalker(surface, NodeFilter.SHOW_TEXT);
+    let remaining = saved.offset;
+    let node = walker.nextNode();
+    let target = null;
+    let targetOffset = 0;
+    while (node) {
+      if (remaining <= node.nodeValue.length) { target = node; targetOffset = remaining; break; }
+      remaining -= node.nodeValue.length;
+      node = walker.nextNode();
+    }
+    if (!target) { placeCaretAtEnd(surface); return; }
+    const range = document.createRange();
+    range.setStart(target, targetOffset);
+    range.collapse(true);
+    const sel = window.getSelection();
+    sel.removeAllRanges();
+    sel.addRange(range);
+  }
+
+  // The one entry point the toolbar/keyboard-cursor dispatch calls — wraps
+  // commitThenSave() with the capture/restore pair above. Ctrl+S itself is
+  // untouched: it is not one of the three buttons backlog #6 names, driving it
+  // was out of that task's scope, and wrapping it here too would risk
+  // perturbing the Finding-1/Finding-3 Ctrl+S coverage this branch already has
+  // for reasons that have nothing to do with the caret.
+  //
+  // fix 5 / R9: the sentence here used to say Ctrl+S "still calls
+  // commitThenSave() directly". It does not and has not — the keydown branch
+  // spells the same precondition out inline as
+  // `switchAwayFrom().then((ok) => { if (ok) save(); })`, deliberately, because
+  // that exact line is pinned verbatim by shortcutOrderChecks in
+  // test/editor-client.test.js (its own comment there says so). The two
+  // spellings are behaviourally identical; the claim about which function is
+  // called was simply wrong, and a reader following it would go looking for a
+  // call site that does not exist.
+  async function saveViaToolbar() {
+    const saved = captureCaretForSave();
+    await commitThenSave();
+    restoreCaretForSave(saved);
+  }
+
   // ── undo / redo ───────────────────────────────────────────────────────
   async function undo() {
     // T21 item 1: an Escape that discarded a burst leaves exactly one thing
@@ -12871,6 +14166,16 @@
     // answers false whenever there is no such thing (which is almost always),
     // and the ordinary document undo below runs untouched.
     if (restoreDiscardedBurst()) return;
+    // v3.4.0 (Task 7 item 5): the raw-editor twin — see restoreDiscardedRawEdit()'s
+    // own comment. Mutually exclusive with the burst stash above (see
+    // discardedRawEdit's own comment), so checking both in sequence never
+    // answers a stale one while the other substrate holds the fresher discard.
+    if (await restoreDiscardedRawEdit()) return;
+    // v3.4.0 batch3 Task 7: the wave twin. Third in the sequence for no reason
+    // other than that it is the newest; all three are mutually exclusive by
+    // construction (one editing session at a time) and each nulls its own slot
+    // before deciding, so order cannot make a stale one answer.
+    if (await restoreDiscardedWaveEdit()) return;
     // Resolve any open editor BEFORE the .content-replacing swap below —
     // see the `activeEditor` / switchAwayFrom() comments near its
     // declaration for why this is required (undo/redo silently detaching an
@@ -12944,12 +14249,44 @@
     }
   }
 
+  // backlog #6 — the toolbar's own caret rescue for undo/redo/image, over
+  // the SAME captureCaretForSave()/restoreCaretForSave() pair saveViaToolbar()
+  // above uses, not a copy of it. activateToolbarCursor()'s own landing-note
+  // comment records exactly when this bites: "undo, redo and image join
+  // [quote/code/line, permanently stranded] ONLY when the surface has an
+  // uncommitted edit — the action resolves that burst first, and the
+  // re-render is what drops the caret." That resolve-then-render shape is
+  // undo()/redo()'s own switchAwayFrom() call and pickAndInsertImage()'s own
+  // — identical to what saveViaToolbar() wraps commitThenSave() around — so
+  // the same capture-before/restore-after pair applies unchanged: capture
+  // reads the CURRENT (possibly mid-edit) DOM before anything commits,
+  // restore is a no-op whenever focus never left the DOM in the first place
+  // (the common case, nothing dirty).
+  //
+  // Scoped to the TOOLBAR path ONLY, deliberately: Ctrl+Z/Ctrl+Y (the global
+  // keydown handler further down) still call undo()/redo() directly, and a
+  // focused burst's own Ctrl+Z is `burstUndo()` — an entirely different,
+  // intra-burst mechanism that never reaches this file's undo()/redo() at
+  // all. Widening either of those was out of this task's scope, the same
+  // boundary saveViaToolbar()'s own comment draws around Ctrl+S.
+  async function undoViaToolbar() {
+    const saved = captureCaretForSave();
+    await undo();
+    restoreCaretForSave(saved);
+  }
+
+  async function redoViaToolbar() {
+    const saved = captureCaretForSave();
+    await redo();
+    restoreCaretForSave(saved);
+  }
+
   // ── v3.1.0 §4: the always-visible editing toolbar ──────────────────────
   // The version's headline feature: before this there was no toolbar at all,
   // and every editing affordance was hidden behind a hover gutter, a caret
   // position or a text selection. window.md2docToolbarModel (injected by
   // server.js, built and reviewed as lib/editor/toolbar-model.js) owns the
-  // 22-button roster, the group order that decides separator placement, and
+  // 23-button roster, the group order that decides separator placement, and
   // the whole active/disabled derivation; everything below is mounting and
   // wiring. Nothing here re-derives a button's state by hand — a second
   // opinion about when ⇥ is legal is exactly what the pure-module split
@@ -12974,8 +14311,36 @@
   // intent has to be captured on the keystroke that produced it.
   let plainPasteArmed = false;
 
-  const TOOLBAR_UNSUPPORTED_IMAGE_MESSAGE = '只接受 PNG / JPEG / GIF / WebP 圖片';
+  const TOOLBAR_UNSUPPORTED_IMAGE_MESSAGE =
+    '只接受 PNG / JPEG / GIF / WebP 圖片，或 draw.io 的 .drawio / .xml';
+  // The one place the two accepted diagram extensions are written down on
+  // this side. /api/asset owns the same pair plus the content check.
+  const DRAWIO_NAME_RE = /\.(drawio|xml)$/i;
+
+  /**
+   * Is this File something the insert path will even try to send?
+   *
+   * ONE predicate with three call sites -- the `drop` filter,
+   * `clipboardItemsOf()` and `uploadImageBlob()` -- because three copies of
+   * "is this insertable" is three chances to disagree. v3.4.1's first cut
+   * widened only two of them and the `drop` filter kept dropping .drawio
+   * files on the floor: the filter runs BEFORE insertImages(), so the file
+   * never entered the pipeline and there was no banner, no request, no
+   * failure -- nothing at all happened, which is indistinguishable from the
+   * feature not existing.
+   *
+   * "Will try to send" is the whole claim. Whether anything is WRITTEN is
+   * decided by /api/asset, which re-checks the extension against its own two
+   * literals and then parses the bytes.
+   */
+  function insertableFile(f) {
+    if (!f || !assetLib) return false;
+    return !!(assetLib.extFor(f.type) || DRAWIO_NAME_RE.test(f.name || ''));
+  }
   const TOOLBAR_NO_ANCHOR_MESSAGE = '找不到可以插入圖片的位置';
+  // backlog #10 — see the keydown handler's own comment for why every
+  // stray-key hand-back raises this rather than only some of them.
+  const TOOLBAR_KEYNAV_EXIT_MESSAGE = '已離開鍵盤游標，按 Alt+F10 可以再進入工具列';
 
   // Extra visual classes for the three inline buttons whose own glyph is the
   // affordance (B is bold, I is italic, S is struck through) — the same
@@ -13155,6 +14520,11 @@
       // .ed-seltb is painted from the same measurement — see updateToolbar().
       marks: selectionMarkStates(sel),
       mode: docMode,
+      // v3.4.0 §3: the `save` button's own state. documentIsDirty() (just
+      // above burstHasUncommittedEdit()'s own comment) is the SAME
+      // expression setDirty() paints the title dot from — not a second copy
+      // of it.
+      dirty: documentIsDirty(),
     };
   }
 
@@ -13170,7 +14540,7 @@
     paintSelToolbarMarks(ctx.marks);
     const state = toolbarModel.deriveState(ctx);
     // selectionchange fires on every caret move, so the state is diffed
-    // before any DOM is written — 22 attribute writes per keystroke is a
+    // before any DOM is written — 23 attribute writes per keystroke is a
     // cost with no matching benefit.
     const sig = JSON.stringify(state);
     if (sig === toolbarStateSig) return;
@@ -13181,7 +14551,7 @@
       if (!st || !btn) return;
       btn.disabled = !!st.disabled;
       // aria-pressed ONLY on the buttons that can actually be pressed-in.
-      // Writing it to all 22 made a screen reader announce `undo`, `image`
+      // Writing it to all 23 made a screen reader announce `undo`, `image`
       // and `table` as toggle buttons stuck in the "not pressed" state,
       // which is a lie about what they do.
       if (TOOLBAR_TOGGLE_IDS.has(id)) {
@@ -13225,11 +14595,15 @@
   // The one-pixel margin is a deliberate cushion and NOT a measured
   // requirement — say so rather than inventing a reason for it. Driven at 900
   // and at 420 px wide, the largest scrollLeft the bar accepts came back equal
-  // to scrollWidth minus clientWidth to the pixel (75 and 555), so a strict
-  // comparison would have been correct at both. The cushion is there because
-  // scrollWidth is reported as a whole number over a row whose own width is
-  // not, and what it costs when the two agree is that the gradient goes out a
-  // pixel before the travel ends.
+  // to scrollWidth minus clientWidth to the pixel (42 and 522 — re-measured
+  // for v3.4.0 §3, a one-off puppeteer script, not assumed: .ed-toolbar's gap
+  // 6px -> 3px changed scrollWidth at EVERY width, not just the 420px one a
+  // different scenario already re-pinned, so 900px needed its own fresh
+  // number rather than inheriting the old 75), so a strict comparison would
+  // have been correct at both. The cushion is there because scrollWidth is
+  // reported as a whole number over a row whose own width is not, and what it
+  // costs when the two agree is that the gradient goes out a pixel before the
+  // travel ends.
   function paintToolbarOverflow() {
     if (!toolbarEl) return;
     const max = toolbarEl.scrollWidth - toolbarEl.clientWidth;
@@ -13335,6 +14709,28 @@
     }
   }
 
+  // backlog #10: the ARIA toolbar pattern's own "jump to the edge" keys —
+  // Home to the first enabled button, End to the last. `edge` is -1 for
+  // Home, +1 for End. Unlike moveToolbarCursor()'s relative step, this walks
+  // from the bar's own edge inward rather than from wherever the cursor
+  // currently sits, so it always lands on the true first/last enabled
+  // button regardless of where the cursor started.
+  function moveToolbarCursorToEdge(edge) {
+    const btns = toolbarRovingBtns();
+    if (!btns.length) return;
+    const step = edge < 0 ? 1 : -1;
+    let i = edge < 0 ? 0 : btns.length - 1;
+    for (let count = 0; count < btns.length; count++) {
+      if (!btns[i].disabled) {
+        toolbarRovingIndex = i;
+        paintToolbarRoving();
+        revealToolbarCursor(btns[i]);
+        return;
+      }
+      i += step;
+    }
+  }
+
   // No "already in the mode" guard, because the key branch cannot deliver one:
   // while the mode is on, the entry chord's own key is not one of the keys the
   // mode names, so it takes the hand-back path and ends the mode instead. The
@@ -13353,37 +14749,107 @@
     return true;
   }
 
+  // Task 9 review I2: real DOM focus can land on a genuine standalone
+  // control — `#doc-search-input` (backlog #9's own fix moves focus there
+  // on purpose) or a `textarea.ed-raw` (backlog #6's quote/code/line fix
+  // opens one) — while toolbarRovingIndex is STILL >= 0, because neither
+  // fix touches it (the F12 cursor is virtual by design: "no toolbar
+  // button ever takes DOM focus", see F12's own load-bearing comment
+  // above). MEASURED (review): with focus in `#doc-search-input` holding
+  // 'needle' at selectionStart 6, `Home`/`End`/`ArrowLeft` were ALL still
+  // being read as toolbar-cursor commands (Home/End jumped the BAR to its
+  // first/last button, ArrowLeft moved the bar cursor one step) instead of
+  // moving the text cursor inside the input — the exact new keyboard
+  // dead-end backlog #9 was supposed to fix, now reachable through #9 and
+  // #10 together.
+  //
+  // Scoped to genuine standalone controls only — INPUT/TEXTAREA/SELECT —
+  // not to `.ed-wys-armed`/`.ed-wys-cell`: wireToolbarTracking()'s own
+  // focusin comment is explicit that SOME toolbar activations (list,
+  // ordered-list, check, table, insert-before, insert-after, preview)
+  // deliberately land a focusin on an editable block WITHOUT ending keynav,
+  // so a real block surface must not trip this bail.
+  //
+  // ⚠ FIX ROUND 1 (self-review, caught before ship): `preview`'s own landing
+  // is `sourceTextarea` — a real `<textarea>`, not a `.ed-wys-armed` block —
+  // so the exemption above named it but the first cut of this function did
+  // not actually implement it, and the omission is load-bearing: source
+  // mode's model disables every button except outline/preview (this file's
+  // own "S/4.1 Source mode" comment — the cursor is meant to be walked with
+  // Left/Right/Home/End between those two, THEN activated), and MEASURED,
+  // that walk is exactly what this function's first cut broke — the very
+  // next arrow key after landing in the source textarea silently exited
+  // keynav instead of moving between the two enabled buttons, closing off
+  // the one route backlog #6's own still-open `preview` round-trip gap (see
+  // activateToolbarCursor()'s comment) names as "THE WAY OUT". `sourceTextarea`
+  // is therefore excluded by reference (not by tag/class — an ordinary
+  // `textarea.ed-raw`, e.g. backlog #6's own quote/code rescue, still trips
+  // this bail exactly as intended, since typing there IS the user's own
+  // text, not bar navigation).
+  function toolbarKeynavBlockedByRealControl() {
+    const ae = document.activeElement;
+    if (!ae || ae === sourceTextarea) return false;
+    return !!(ae.tagName && (ae.tagName === 'INPUT' ||
+      ae.tagName === 'TEXTAREA' || ae.tagName === 'SELECT'));
+  }
+
   // Activation goes through the same call the click handler makes, so a
   // keyboard press and a mouse press cannot drift apart.
   //
   // WHERE THE CARET ENDS UP AFTERWARDS, driven button by button over the
   // enabled row in a plain paragraph, pressing Enter on the cursor and then
-  // typing to see whether the characters land anywhere:
-  //
-  //   * quote, code and line end on BODY and typing goes nowhere, with a
-  //     clean burst and with a dirty one alike.
-  //   * undo, redo and image join them ONLY when the surface has an
-  //     uncommitted edit — the action resolves that burst first, and the
-  //     re-render is what drops the caret. With nothing pending they land back
-  //     on the armed paragraph and typing resumes.
-  //   * everything else lands on an editable surface and typing resumes.
-  //
-  // A mouse click on those same buttons does exactly the same thing, so this
-  // is not something the keyboard route introduced — but a mouse user climbs
-  // out by clicking into the text and a keyboard user cannot, because Tab from
-  // BODY goes nowhere. Deferred to v3.4.0 rather than fixed here: the fix is
-  // in the activation path, which the mouse shares.
-  //
-  // THE WAY OUT until then, driven end to end from a stranded BODY: the entry
-  // chord still works there (the bar's own state survives, and its row is
-  // fully enabled), so walking to the mode button and pressing Enter puts the
-  // caret in the source textarea, where typing lands. Coming back the same way
-  // returns the document to edit mode but leaves the caret on BODY again — the
-  // hatch is somewhere to keep typing, not a way back to the WYSIWYG caret.
+  // typing to see whether the characters land anywhere — UPDATED for Task 9
+  // (backlog #6), which fixed the first two bullets below; only the third
+  // remains an open gap, tracked below rather than left unstated:
+  //
+  //   * FIXED: quote, code and line used to end on BODY with typing going
+  //     nowhere, clean burst and dirty one alike. restoreAfterStructuralOp()'s
+  //     `allowRawEditRescue` (convertBlockViaMenu() only — see its own
+  //     comment) and insertBlockBelow()'s `kind === 'line'` branch now open
+  //     that block's raw editor instead, so typing lands there.
+  //   * FIXED: undo, redo and image used to join them ONLY when the surface
+  //     had an uncommitted edit (switchAwayFrom()'s own commit-and-render is
+  //     what dropped the caret). undoViaToolbar()/redoViaToolbar()/
+  //     imageViaToolbar() now wrap the same captureCaretForSave()/
+  //     restoreCaretForSave() pair saveViaToolbar() uses.
+  //   * STILL OPEN: `preview` (cycleDocMode(), the document-wide edit↔source
+  //     toggle) is UNCHANGED — going INTO source mode focuses the source
+  //     textarea correctly, but the RETURN trip (source → edit) still leaves
+  //     the caret on BODY, MEASURED unchanged by this task's own review.
+  //     Deliberately left open rather than rushed: unlike the two bullets
+  //     above, there is no established rescue to reuse here —
+  //     captureCaretForSave()'s block-id + text-offset coordinate system has
+  //     no meaning for a source-textarea cursor position (a raw character
+  //     offset into the WHOLE document string, not one block's rendered
+  //     text), so a correct fix needs its own coordinate mapping and its own
+  //     tests, not a copy-paste of this task's other two fixes. Backlog #6's
+  //     first two clauses no longer make this escape hatch NECESSARY the way
+  //     they used to (quote/code/line now have their own direct rescue,
+  //     rather than needing the preview round-trip as their only way out),
+  //     which is why this is deferred rather than treated as still blocking.
+  //
+  // A mouse click on those same buttons does exactly the same thing, so none
+  // of this is something the keyboard route introduced — a mouse user can
+  // always climb out of the still-open `preview` case by clicking into any
+  // OTHER editable text on the page, where a keyboard user cannot, because Tab
+  // from BODY goes nowhere (this file's own §3.5 contract).
+  //
+  // THE WAY OUT for the still-open case, driven end to end from a stranded
+  // BODY: the entry chord still works there (the bar's own state survives,
+  // and its row is fully enabled), so walking to the mode button and pressing
+  // Enter puts the caret in the source textarea, where typing lands. Coming
+  // back the same way returns the document to edit mode but leaves the caret
+  // on BODY again — the hatch is somewhere to keep typing, not (yet) a way
+  // back to the WYSIWYG caret.
   function activateToolbarCursor() {
     const btn = toolbarRovingBtns()[toolbarRovingIndex];
     if (!btn || btn.disabled) return;
-    Promise.resolve(runToolbarAction(btn.getAttribute('data-ed-tb'), btn))
+    // Task 9 review M3: `true` — this IS the keyboard activation path (the
+    // only caller of runToolbarAction() that is), threaded through so
+    // toggleOutlineSidebar() can tell a keyboard Enter/Space apart from a
+    // mouse click on the identical button. See its own comment for why
+    // `toolbarRovingIndex >= 0` alone was the wrong test.
+    Promise.resolve(runToolbarAction(btn.getAttribute('data-ed-tb'), btn, true))
       .catch(() => {}).then(updateToolbar);
   }
 
@@ -13479,17 +14945,22 @@
     return bar;
   }
 
-  async function runToolbarAction(id, btnEl) {
+  async function runToolbarAction(id, btnEl, viaKeyboard) {
     const blockEl = liveToolbarBlock();
     switch (id) {
+      // v3.4.0 §3: saveViaToolbar() — not save() directly. See its own
+      // comment for why (commitThenSave()'s precondition and its own caret
+      // rescue). backlog #6 gave undo()/redo() the same rescue below, via
+      // undoViaToolbar()/redoViaToolbar() — see their shared comment.
+      case 'save': return saveViaToolbar();
       // ⚠ The BROWSER-side zero-argument undo()/redo(), never `stack.undo` /
       // `stack.redo`. Those are the pure core's helpers (they are what
       // rollbackFailedRender() reverses an op with) and calling them from
       // here would skip switchAwayFrom() and safeRerenderAll() — the exact
       // shape this file records as having produced a silent total lockout
       // recoverable only by reloading the page.
-      case 'undo': return undo();
-      case 'redo': return redo();
+      case 'undo': return undoViaToolbar();
+      case 'redo': return redoViaToolbar();
       case 'headings': return toggleToolbarHeadingMenu(btnEl);
       // The five conversion targets are convert-md.js's own ids, so the
       // gesture goes through convertBlockViaMenu()'s §3.7 / §4.3 gates
@@ -13513,24 +14984,76 @@
       case 'line': return blockEl ? insertBlockBelow(blockEl, 'line') : undefined;
       case 'insert-after': return blockEl ? insertBlockBelow(blockEl, 'paragraph') : undefined;
       case 'insert-before': return blockEl ? insertBlockAbove(blockEl) : undefined;
-      case 'image': return pickAndInsertImage();
-      case 'outline': return toggleOutlineSidebar();
+      // backlog #6: imageViaToolbar() — not pickAndInsertImage() directly.
+      // See its own comment (shared with undoViaToolbar()/redoViaToolbar())
+      // for the caret rescue.
+      case 'image': return imageViaToolbar();
+      case 'outline': return toggleOutlineSidebar(!!viaKeyboard);
       case 'preview': return cycleDocMode();
       default: return undefined;
     }
   }
 
   // ── headings ▾ ─────────────────────────────────────────────────────────
-  // KNOWN GAP, documented rather than fixed: the toolbar's keyboard cursor can
-  // open and close this dropdown, but its items are still reachable by mouse
-  // only — they carry no cursor of their own and the mode's arrow keys move
-  // along the bar, not into the panel. No keyboard route reaches them.
+  // backlog #7 fix: the panel now carries its OWN roving cursor
+  // (toolbarMenuIndex), a second index alongside the bar's toolbarRovingIndex
+  // rather than a repurposing of it — the bar's cursor stays parked on
+  // 'headings' the whole time the menu is open (K6's own pinned assertion:
+  // Escape's first press takes the menu down and LEAVES `at: 'headings'`),
+  // so the panel needed a cursor of its own rather than borrowing the bar's.
+  // -1 means "nothing in the panel highlighted yet" — the state right after
+  // opening, and the state K6 already pins Enter/Space's behaviour against
+  // (see activateToolbarMenuCursor()'s own comment for why that case is not
+  // reinterpreted as "select the first item").
+  let toolbarMenuIndex = -1;
+
+  function toolbarMenuItems() {
+    return toolbarMenuEl
+      ? Array.prototype.slice.call(toolbarMenuEl.querySelectorAll('.ed-toolbar-menu-btn')) : [];
+  }
+
+  function paintToolbarMenuCursor() {
+    toolbarMenuItems().forEach((b, i) => {
+      if (i === toolbarMenuIndex) b.setAttribute('data-ed-tb-menu-cursor', '');
+      else b.removeAttribute('data-ed-tb-menu-cursor');
+    });
+  }
+
+  // None of the six items are ever disabled (every heading depth 1-6 is
+  // always a legal target), so this is a plain wrapping step — no
+  // moveToolbarCursor()-style "skip disabled" walk is needed.
+  function moveToolbarMenuCursor(delta) {
+    const items = toolbarMenuItems();
+    if (!items.length) return;
+    toolbarMenuIndex = ((toolbarMenuIndex + delta) % items.length + items.length) % items.length;
+    paintToolbarMenuCursor();
+    items[toolbarMenuIndex].scrollIntoView({ block: 'nearest' });
+  }
+
+  // K6 (test/editor-journey.test.js) pins Enter/Space, pressed with NOTHING
+  // in the panel highlighted, as the H▾ button's own open/close toggle — the
+  // same activateToolbarCursor() the bar's Enter/Space already runs for
+  // every other button. Only once the user has actually moved the panel
+  // cursor (toolbarMenuIndex >= 0, via ArrowUp/ArrowDown below) does
+  // Enter/Space switch to activating that ITEM instead — reusing the item's
+  // own click handler via .click() so keyboard and mouse activation are the
+  // same code path, the same discipline activateToolbarCursor() itself
+  // documents for the bar's buttons.
+  function activateToolbarMenuCursor() {
+    const items = toolbarMenuItems();
+    const item = toolbarMenuIndex >= 0 ? items[toolbarMenuIndex] : null;
+    if (!item) { activateToolbarCursor(); return; }
+    item.click();
+  }
+
   function closeToolbarMenu() {
     if (toolbarMenuEl) { toolbarMenuEl.remove(); toolbarMenuEl = null; }
+    toolbarMenuIndex = -1;
   }
 
   function toggleToolbarHeadingMenu(btnEl) {
     if (toolbarMenuEl) { closeToolbarMenu(); return; }
+    toolbarMenuIndex = -1;
     const menu = document.createElement('div');
     menu.className = 'ed-toolbar-menu';
     [1, 2, 3, 4, 5, 6].forEach((n) => {
@@ -13683,15 +15206,28 @@
   // lib/md2doc.js. Named for the non-default state because the desktop
   // outline is a sticky column shown by default, which is also what lets
   // aria-expanded below stay truthful on both viewports.
-  function toggleOutlineSidebar() {
+  function toggleOutlineSidebar(viaKeyboard) {
     // The same 1080px breakpoint the stylesheet's own drawer block uses.
     const mobile = typeof window.matchMedia === 'function' &&
       window.matchMedia('(max-width: 1080px)').matches;
     let expanded;
     if (mobile) {
+      // Mirror onto documentElement too, exactly as lib/md2doc.js's own
+      // setSidebarOpen() does — the scroll lock is `html[data-sidebar-open]
+      // { overflow: hidden }` (documentElement, not body, is what a real
+      // gesture actually scrolls; see that rule's comment in lib/md2doc.js).
+      // Final-review C1: this toolbar entry point set only `body`, so the
+      // drawer visually opened but the scroll lock never engaged — the ONLY
+      // way into the drawer in edit mode (`.sidebar-toggle` is display:none
+      // there, see T11-2) left backlog #12 unfixed for edit mode specifically.
       expanded = !document.body.hasAttribute('data-sidebar-open');
-      if (expanded) document.body.setAttribute('data-sidebar-open', '');
-      else document.body.removeAttribute('data-sidebar-open');
+      if (expanded) {
+        document.body.setAttribute('data-sidebar-open', '');
+        document.documentElement.setAttribute('data-sidebar-open', '');
+      } else {
+        document.body.removeAttribute('data-sidebar-open');
+        document.documentElement.removeAttribute('data-sidebar-open');
+      }
     } else {
       expanded = document.body.hasAttribute('data-ed-outline-hidden');
       if (expanded) document.body.removeAttribute('data-ed-outline-hidden');
@@ -13699,6 +15235,42 @@
     }
     const toggle = document.getElementById('sidebar-toggle');
     if (toggle) toggle.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+    // backlog #9: v3.3.0 gave a keyboard route to OPEN the drawer (this very
+    // button, reachable through the toolbar's F12 keynav) but none to
+    // OPERATE what is inside it — the TOC links and the search box
+    // (`#doc-search-input`, lib/md2doc.js's reader-sidebar markup) were
+    // unreachable by keyboard once the drawer was open, because F12's
+    // cursor is VIRTUAL (see its own load-bearing comment: "no toolbar
+    // button ever takes DOM focus") and a bare Tab with NOTHING focused is
+    // deliberately swallowed elsewhere in this file (§3.5's block-indent
+    // contract, a few hundred lines down) — so a keyboard user who had
+    // never clicked into a real control was left with no Tab destination at
+    // all, drawer open or not.
+    //
+    // Scoped to the KEYBOARD path only: a mouse click reaches this same
+    // function, and buildToolbar()'s own mousedown-preventDefault() note is
+    // explicit that a toolbar press must NOT steal focus from whatever
+    // burst the mouse user has open — forcing focus into the search box on
+    // every click would blur that burst (committing it) for no reason a
+    // mouse user asked for. Also scoped to `expanded`: a toggle that just
+    // HID the drawer has nowhere sensible to send focus.
+    //
+    // Task 9 review M3: `viaKeyboard`, an explicit parameter threaded from
+    // activateToolbarCursor() — NOT `toolbarRovingIndex >= 0`, which was
+    // the first cut's test and is wrong: toolbarRovingIndex says whether
+    // keynav is CURRENTLY on, not which INPUT DEVICE fired this particular
+    // activation. MEASURED: press Alt+F10 (keynav now on), then click ☰
+    // with the MOUSE — toolbarRovingIndex is still >= 0 from the earlier
+    // keypress, so the old test treated a plain mouse click as "keyboard",
+    // stealing focus into the search box exactly as the commit message for
+    // backlog #9 says it must not ("a mouse click on the same button must
+    // not steal focus"). `viaKeyboard` is true on ONE call path only —
+    // activateToolbarCursor(), which IS the keyboard route — regardless of
+    // whatever toolbarRovingIndex happens to hold at the time.
+    if (expanded && viaKeyboard) {
+      const search = document.getElementById('doc-search-input');
+      if (search) search.focus();
+    }
   }
 
   // ── 追加 3: images ─────────────────────────────────────────────────────
@@ -13730,7 +15302,13 @@
   // authoritative.
   async function uploadImageBlob(blob) {
     if (!blob) return null;
-    if (!assetLib || !assetLib.extFor(blob.type)) {
+    // A .drawio arrives with `type === ''` -- browsers have no media type for
+    // it -- so `extFor()` alone answered "unsupported" without ever asking the
+    // server. The name is enough to get the request SENT; it is not enough to
+    // get anything written: /api/asset re-checks the extension against its own
+    // two literals and then parses the bytes. Keep the two rules the same
+    // shape, and let the server's refusal be the one the user sees.
+    if (!insertableFile(blob)) {
       showBanner(TOOLBAR_UNSUPPORTED_IMAGE_MESSAGE, null, null);
       return null;
     }
@@ -13760,6 +15338,15 @@
     }
     let j;
     try { j = await res.json(); } catch (e) { j = null; }
+    // A refusal carries a reason; saying "伺服器回應格式不正確" instead is a
+    // second wrong answer on top of the first. The content gate added in
+    // v3.4.1 makes this reachable for an ordinary mistake -- picking an .xml
+    // that is not a draw.io diagram -- so the reason has to arrive.
+    if (!res.ok) {
+      const why = (j && typeof j.error === 'string' && j.error) ? j.error : ('HTTP ' + res.status);
+      showBanner('檔案上傳失敗 — ' + why, null, null);
+      return null;
+    }
     if (!j || typeof j.path !== 'string') {
       showBanner('圖片上傳失敗 — 伺服器回應格式不正確。', null, null);
       return null;
@@ -13873,7 +15460,13 @@
     const dialogIdentity = captureBlockIdentity(anchorEl);
     const input = document.createElement('input');
     input.type = 'file';
-    input.accept = 'image/png,image/jpeg,image/gif,image/webp';
+    // v3.4.1: extension tokens sit beside the MIME tokens deliberately.
+    // `.drawio` has no registered media type, so a MIME-only accept list
+    // cannot name it and the dialog greys the file out -- which is how
+    // v3.4.0 shipped a renderer that embeds .drawio/.xml next to an insert
+    // button that could not pick one. Mixing the two token kinds is what
+    // the attribute is specified for.
+    input.accept = 'image/png,image/jpeg,image/gif,image/webp,.drawio,.xml';
     input.multiple = true;
     input.hidden = true;
     // (a) above.
@@ -13897,6 +15490,21 @@
     input.click();
   }
 
+  // backlog #6 — see undoViaToolbar()/redoViaToolbar()'s shared comment.
+  // pickAndInsertImage() resolves (its own switchAwayFrom() included) well
+  // before the user has picked a file — the `input.click()` above only OPENS
+  // the native file dialog, it does not await a selection — so capturing
+  // before and restoring right after this call lands at exactly the same
+  // point in the gesture saveViaToolbar()'s pair does for `save`: after the
+  // commit-and-render that can strand the caret, before the (much later,
+  // asynchronous, maybe-never-arrives) file selection that focuses somewhere
+  // new anyway.
+  async function imageViaToolbar() {
+    const saved = captureCaretForSave();
+    await pickAndInsertImage();
+    restoreCaretForSave(saved);
+  }
+
   function dragCarriesFiles(e) {
     const dt = e.dataTransfer;
     if (!dt || !dt.types) return false;
@@ -13924,18 +15532,26 @@
     // user is looking at is not the content a drop would write into" — a
     // future third mode inherits the refusal rather than the hole.
     document.addEventListener('dragover', (e) => {
+      // Nothing is dropped into a document behind a modal. Returning WITHOUT
+      // preventDefault() is what makes the browser refuse the drop, so the
+      // gesture is declined visibly rather than swallowed.
+      if (waveEditorIsModal()) return;
       if (docMode !== 'edit') return;
       if (!dragCarriesFiles(e)) return;
       e.preventDefault();
       if (e.dataTransfer) e.dataTransfer.dropEffect = 'copy';
     });
     document.addEventListener('drop', (e) => {
+      // MEASURED before this line existed: a PNG dropped on the open wave panel
+      // took the document behind it from 4 blocks to 5 and put an `<img>` into
+      // `.content`, with the overlay still up and saying nothing.
+      if (waveEditorIsModal()) return;
       if (docMode !== 'edit') return;
       if (!dragCarriesFiles(e)) return;
       const files = e.dataTransfer
         ? Array.prototype.slice.call(e.dataTransfer.files || [])
         : [];
-      const images = files.filter((f) => !!(assetLib && assetLib.extFor(f.type)));
+      const images = files.filter(insertableFile);
       if (!images.length) return; // not ours: let the page do whatever it would
       e.preventDefault();
       const anchorEl = (e.target && e.target.closest) ? e.target.closest('.ed-block') : null;
@@ -13955,8 +15571,15 @@
     try { items['text/html'] = dt.getData('text/html') || ''; } catch (err) { items['text/html'] = ''; }
     const files = dt.files ? Array.prototype.slice.call(dt.files) : [];
     for (let i = 0; i < files.length; i += 1) {
-      if (files[i] && String(files[i].type).indexOf('image/') === 0) {
-        items[files[i].type] = files[i];
+      // This map is keyed by MIME, and a .drawio has no MIME at all, so a
+      // diagram pasted as a FILE goes under the fixed 'file' key that
+      // pickPayload() also looks at. The key is a protocol constant between
+      // these two modules -- the RULE for which files are insertable stays
+      // in insertableFile() alone, so paste-md.js never grows a second
+      // opinion about extensions.
+      if (files[i] && insertableFile(files[i])) {
+        const mime = String(files[i].type || '');
+        items[mime.indexOf('image/') === 0 ? mime : 'file'] = files[i];
         break;
       }
     }
@@ -14023,7 +15646,9 @@
       // commitBlockInsertion()/replaceLines() and therefore through
       // serializeBlocks()'s existing gates, instead of arriving as a pile of
       // foreign nodes the serializer would have to make sense of afterwards.
-      insertBlockBelow(editEl.closest('.ed-block'), 'paragraph', { lines: md.split('\n') });
+      const pastedLines = md.split('\n');
+      insertBlockBelow(editEl.closest('.ed-block'), 'paragraph',
+        { lines: pastedLines, tight: pasteIsAllListLines(pastedLines) });
       return;
     }
     snapBurstIfActive(editEl, 'paste-pre');
@@ -14035,6 +15660,7 @@
     // Capture phase: this only records intent, and must do so before any
     // other keydown handler can preventDefault() its way past it.
     document.addEventListener('keydown', (e) => {
+      if (waveEditorIsModal()) return;
       plainPasteArmed = !!((e.ctrlKey || e.metaKey) && e.shiftKey &&
         (e.key === 'v' || e.key === 'V'));
     }, true);
@@ -14144,6 +15770,15 @@
       updateToolbar();
     });
     document.addEventListener('click', (e) => {
+      // v3.4.0 batch3 Task 6: this file has TWO document-level `click`
+      // delegates, and for one round only the other one asked. Nothing behind
+      // the modal takes clicks — measured benign here today (the toolbar menu
+      // cannot be open behind a modal, keynav cannot be entered while the main
+      // keydown returns first, and `closest('.ed-block')` is null for anything
+      // in the overlay), but "benign today" is a property of the three branches
+      // below rather than of the boundary, and the next branch added here would
+      // inherit an unguarded seat behind a modal.
+      if (waveEditorIsModal()) return;
       if (!e.target || !e.target.closest) return;
       if (e.target.closest('.ed-toolbar') || e.target.closest('.ed-toolbar-menu')) return;
       closeToolbarMenu();
@@ -14262,24 +15897,134 @@
     //           keydown ends the mode and the arrow behind it falls through to
     //           the block-selection extension instead.
     //
-    // A menu raised from this bar goes down on the way past. Without this the
-    // hand-back cleared the cursor cue and left the H▾ dropdown standing, so
-    // the two disagreed and only Escape was any use. Escape is excluded
-    // because the ordered prologue below owns it and takes the menu down
-    // there, in rank order; Enter and Space are excluded because they are the
-    // keys that opened the menu and have to keep closing it.
-    if (toolbarRovingIndex >= 0) {
-      if (toolbarMenuEl && e.key !== 'Escape' && e.key !== 'Enter' && e.key !== ' ') {
-        closeToolbarMenu();
+    // A menu raised from this bar goes down on the way past — UNLESS the key
+    // is one the panel itself now claims (backlog #7, see the nested
+    // `if (toolbarMenuEl)` just below). Before that fix ALL of
+    // Up/Down/Enter/Space fell through this whole file with the menu open
+    // and its six items unreachable by keyboard; without the panel going
+    // down too on everything else, the hand-back cleared the cursor cue and
+    // left the H▾ dropdown standing, so the two disagreed and only Escape
+    // was any use. Escape is excluded because the ordered prologue below
+    // owns it and takes the menu down there, in rank order.
+    // Task 9 review I2: a real control (search box, raw editor textarea)
+    // holding focus quietly ends keynav and hands EVERY key straight to it
+    // — see toolbarKeynavBlockedByRealControl()'s own comment. No banner:
+    // this is not a stray key with nowhere to go, it is the user typing
+    // into something they can see is focused.
+    // ── v3.4.0 batch3 Task 6: the wave editor owns the keyboard, EXCEPT ──
+    // Above everything, including the toolbar's keyboard mode. While that
+    // overlay is up it is modal over the document, and almost every branch
+    // below this line is about a document the user cannot see or reach —
+    // including the `Tab` branch, which used to swallow the key and leave all
+    // of an `aria-modal` dialog's controls unreachable. The overlay's own
+    // capture-phase handler owns Escape, Tab and undo/redo and stops them
+    // before they get here; this is the other half of that deal, stated on this
+    // side so the two cannot drift into disagreeing about who owns what.
+    //
+    // SAVE IS THE EXCEPTION, and it is the exception because ownership is about
+    // which gestures, not only about who. Ctrl+S is not a gesture aimed at the
+    // document the modal is covering — it is the reflex that protects work, and
+    // the wave editor has nothing of its own to save in this task. Swallowing
+    // it cost twice over, both measured: the keystroke did nothing and said
+    // nothing (`disk has MARKA? false` with the overlay open, `true` after
+    // Escape), and — worse — `showConflictBanner()` has exactly ONE producer,
+    // the 409 branch of `save()`, while the toolbar's save control sits under an
+    // `inset: 0` backdrop and outside the focus trap. So with Ctrl+S swallowed,
+    // a disk conflict arising DURING a wave session could not raise a banner at
+    // all: measured, file changed underneath, overlay open, Ctrl+S, banner
+    // `null`. All the work keeping `.ed-conflict` above the modal and inside the
+    // focus trap only ever fired for a banner that predated the overlay.
+    //
+    // ⚠ fix 4 (R1): something else now DEPENDS on this line being as narrow as
+    // it is. `waveDiscardIsSafe()` decides whether a wave session's commits can
+    // be popped off the document stack by comparing a COUNT
+    // (`depth === baseDepth + ops`), which proves only that the same number of
+    // entries sit above where the session started — a foreign push paired with
+    // a foreign pop inside one session satisfies it, and
+    // `discardPristineInsert()` is exactly that shape. It is unreachable today
+    // because this gate returns on every non-save key and because
+    // `openWaveEditor()` resolves the one remaining path (Ctrl+S's
+    // `switchAwayFrom()`) BEFORE the overlay opens. Letting one more gesture
+    // through here re-opens that hole silently; if that is ever the right call,
+    // waveDiscardIsSafe()'s check has to become identity-based first.
+    if (waveEditorIsModal() && !isSaveGesture(e)) return;
+    if (toolbarRovingIndex >= 0 && toolbarKeynavBlockedByRealControl()) {
+      exitToolbarKeynav();
+    } else if (toolbarRovingIndex >= 0) {
+      // backlog #7: the H▾ panel claims Up/Down/Enter/Space for its OWN
+      // roving cursor before anything below gets a look at them — see
+      // toolbarMenuIndex's own comment for why that is a second index
+      // rather than a repurposing of toolbarRovingIndex. Every other key
+      // (Left/Right/Home/End/Tab/…) still closes the panel exactly as
+      // before, which is why the fallback line at the end here is the
+      // ORIGINAL condition with the now-claimed keys still excluded from it
+      // (Escape stays excluded too — the ordered prologue below owns it, in
+      // rank order, same as always).
+      if (toolbarMenuEl) {
+        if (e.key === 'ArrowDown') { e.preventDefault(); moveToolbarMenuCursor(1); return; }
+        if (e.key === 'ArrowUp') { e.preventDefault(); moveToolbarMenuCursor(-1); return; }
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault(); activateToolbarMenuCursor(); return;
+        }
+        if (e.key !== 'Escape') closeToolbarMenu();
       }
       if (e.key === 'ArrowRight') { e.preventDefault(); moveToolbarCursor(1); return; }
       if (e.key === 'ArrowLeft') { e.preventDefault(); moveToolbarCursor(-1); return; }
+      // backlog #10: Home/End are the ARIA toolbar pattern's own "jump to
+      // the first/last item" keys — a natural extension of the roving pair
+      // just above, not a new idiom. Naming them here (instead of letting
+      // them fall to the hand-back branch below) turns two of the seven
+      // keys MEASURED to silently drop the cursor into something USEFUL.
+      if (e.key === 'Home') { e.preventDefault(); moveToolbarCursorToEdge(-1); return; }
+      if (e.key === 'End') { e.preventDefault(); moveToolbarCursorToEdge(1); return; }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault(); activateToolbarCursor(); return;
       }
+      // backlog #10: everything else hands the key back ON PURPOSE — Tab
+      // moves real DOM focus per the document's own tab order (see
+      // buildToolbar()'s own "Tab key belongs to the document's own
+      // structure" note), and a plain character or Backspace has nowhere to
+      // land while the virtual cursor sits over a non-editable BODY, so
+      // letting them fall through is harmless. What is NOT harmless,
+      // MEASURED (v3.3.0): the hand-back left NOTHING on screen to mark it —
+      // `[data-ed-tb-cursor]` and `data-ed-tb-keynav` both went null with the
+      // bar looking exactly as it did the instant before Alt+F10 was first
+      // pressed, so a user who does not catch the outline vanishing has no
+      // way to tell they fell out of keyboard mode. Two fixes were on the
+      // table (v3.3.0's own ruling: 「一併處理，加上可見的信號」 — do both):
+      // teach the specific keys that have somewhere useful to go (Home/End,
+      // above) to stop exiting, AND raise a visible banner on every hand-back
+      // that still exits. Enumerating "every key with nowhere useful to go"
+      // was rejected as the SOLE fix — that list is open-ended and this file
+      // cannot audit it for completeness, while a banner on every hand-back
+      // is correct for any key this branch is ever reached by, including
+      // ones nobody has measured yet.
+      //
+      // Task 9 review I3: `Tab` is excluded from the banner here (though it
+      // still exits keynav, same as before) — it is the ARIA toolbar
+      // pattern's OWN "leave the toolbar" gesture, a legitimate exit rather
+      // than a stray key with nowhere to go, and raising a full-width red
+      // banner over the whole bar for a correct keystroke was the wrong
+      // direction. MEASURED AT THE TIME: dismissKeynavExitBanner() was the
+      // only way a keyboard user could take the earlier, unconditional
+      // banner back down at all (`.ed-conflict` was `z-index:999` over the
+      // bar's own `z-index:101` AND `top:0` against the bar's own `top:0`,
+      // covering all 23 buttons; a bare Tab with nothing focused is
+      // swallowed by this file's own §3.5 contract, so Escape was the only
+      // route left) — excluding Tab here removes most of the cases that
+      // needed that route in the first place, and Escape's own rung below
+      // closes the rest. Task 10 (backlog #8) has since moved `.ed-conflict`
+      // to `top: var(--ed-toolbar-h)`, so it no longer covers the bar for
+      // ANY banner — the "covering all 23 buttons" clause above is
+      // historical (what justified wiring Escape at the time), not the
+      // current geometry.
       if (e.key !== 'Escape' && e.key !== 'Alt' && e.key !== 'Shift' &&
           e.key !== 'Control' && e.key !== 'Meta') {
         exitToolbarKeynav();
+        if (e.key !== 'Tab') {
+          showBanner(TOOLBAR_KEYNAV_EXIT_MESSAGE, null, null);
+          activeBannerIsKeynavExit = true;
+        }
       }
     } else if (e.altKey && e.key === 'F10') {
       e.preventDefault();
@@ -14353,6 +16098,13 @@
       // bar, so it goes out before the bar's keyboard mode does, matching the
       // way the menu rungs above rank against the selection rung below.
       if (toolbarMenuEl) { e.preventDefault(); closeToolbarMenu(); return; }
+      // Task 9 review I3: the keynav-exit banner (backlog #10) is only ever
+      // up once keynav has ALREADY exited, so this and the
+      // exitToolbarKeynav() rung right below it never both apply to the
+      // same Escape — order between the two is not load-bearing, grouped
+      // here only for readability. See dismissKeynavExitBanner()'s own
+      // comment for why Escape, specifically, is safe to wire to it.
+      if (dismissKeynavExitBanner()) { e.preventDefault(); return; }
       if (exitToolbarKeynav()) { e.preventDefault(); return; }
       if (blockSelection) { e.preventDefault(); clearBlockSelection(); return; }
       // Nothing above owns this Escape — fall through to the burst
@@ -14372,6 +16124,17 @@
       // commit failure switchAwayFrom() returns false — the banner it
       // already showed is the visible reason save() is skipped; the burst
       // stays open with the user's text intact rather than saving nothing.
+      //
+      // v3.4.0 §3: this exact precondition — resolve first, save second —
+      // is now also named once as commitThenSave(), for the toolbar `save`
+      // button (see its own comment). Left spelled out here rather than
+      // switched to call it: this line is pinned verbatim by a static
+      // source-shape check in test/editor-client.test.js's
+      // shortcutOrderChecks, which is outside this task's file scope, and
+      // the two spellings are behaviourally identical fire-and-forget calls
+      // — nothing is duplicated here beyond this one line shape, and
+      // save()'s own body is still called exactly once, from inside
+      // commitThenSave() when the toolbar path runs it.
       switchAwayFrom().then((ok) => { if (ok) save(); });
       return;
     }
@@ -14447,7 +16210,19 @@
     // `blockSelection` is the gate, and it is the whole guard: with no set
     // standing there is no focus holder either, and every key below behaves
     // exactly as it did pre-S3.
-    if (blockSelection && !e.ctrlKey && !e.metaKey && !e.altKey) {
+    //
+    // v3.4.0 batch3 Task 6: that invariant is now CHECKED and not assumed. It
+    // was true only because nothing had ever mounted a text field outside
+    // `.content`; the wave editor puts real `<input>`s on document.body, which
+    // are neither `.ed-wys-armed` nor `.ed-wys-cell` either, and a Backspace
+    // typed into one ran deleteSelection() — MEASURED: 3 blocks became 2, the
+    // tail paragraph was gone from the document, and the keystroke never
+    // reached the input at all. Silent data loss behind a modal. A guard that
+    // holds only because nobody has done the thing it forbids is not a guard,
+    // so the text-surface test is spelled out rather than inferred from two
+    // class names, and it protects every future surface too.
+    if (blockSelection && !e.ctrlKey && !e.metaKey && !e.altKey &&
+        !isTextEntryTarget(e.target)) {
       if (e.key === 'Tab') {
         // §3.5, in as many words: 必須 preventDefault()，否則 Tab 在 body 上是
         // 瀏覽器焦點巡覽.
@@ -14468,6 +16243,52 @@
       }
     }
 
+    // v3.4.0 batch3 Task 8: the wave editor's KEYBOARD entry.
+    //
+    // Until this, the only way into it was the `編輯波形` affordance, which is
+    // raised by a `mouseover` and positioned over the diagram — so a keyboard
+    // user could not open it at all. That is the same defect this file has
+    // already paid for twice on other surfaces: an affordance only a pointer
+    // can raise (v3.3.0's `H▾` dropdown) and a panel with no keyboard route
+    // into its contents (the outline drawer, backlog #9).
+    //
+    // Gated on the BLOCK WRAPPER ITSELF, not on `blockSelection` and not on
+    // `closest()`: the focus holder is the same `.ed-block` element in both of
+    // the states that can get here — a standing selection (whose roving
+    // `tabindex` focuses it) and the focus this file hands back when a wave
+    // session closes — so one branch serves the way in and the way back in.
+    //
+    // `closest('.ed-block')` is what the first cut used and it was wrong by
+    // exactly this defect family: EVERY block contains an `.ed-insert` and an
+    // `.ed-handle` <button>, so Enter on the ⠿ of a wavedrom block opened the
+    // wave editor and `preventDefault()`ed the block menu, while SPACE on the
+    // same button still opened the menu — one button, two devices'
+    // conventions, two answers, which is v3.3.0 backlog #4 with the devices
+    // swapped. That path also has no `blockSelection`, so closing the session
+    // it wrongly opened would have ended on `document.body`. It was latent
+    // only because nothing can put the keyboard on those buttons today, and it
+    // would have gone live with the very follow-up this task is asking for.
+    //
+    // `isTextEntryTarget` keeps it away from every editable, where Enter
+    // already means a paragraph break, and the modal gate far above means it
+    // cannot fire while the overlay is up.
+    if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.metaKey && !e.altKey &&
+        !isTextEntryTarget(e.target) && e.target && e.target.classList &&
+        e.target.classList.contains('ed-block')) {
+      const blockEl = e.target;
+      const diagram = waveDiagramInside(blockEl);
+      if (diagram !== null) {
+        e.preventDefault();
+        // Same shape as the affordance's own click handler: reported, not
+        // rethrown. An unhandled rejection out of a keydown listener is a
+        // page-level error, and openWaveEditor() unwinds its own state.
+        openWaveEditor(blockEl).catch((err) => {
+          console.error('md2doc: the wave editor could not open', err);
+        });
+        return;
+      }
+    }
+
     // v2.11.1 acceptance, escape class A: Tab with NOTHING focused. Every
     // branch above is keyed on the event target being some edit surface, and
     // after a commit / Escape / Ctrl+Z, or a click on a bullet marker or in
@@ -14761,6 +16582,12 @@
   });
 
   document.addEventListener('paste', (e) => {
+    // Same question as `drop` above, and for the same reason: what the document
+    // behind a modal receives is nothing. Today the two branches below already
+    // require a `.ed-wys-cell` / `.ed-wys-armed` target, which a paste into a
+    // wave field is not — this is here so the boundary is one predicate rather
+    // than a property of which targets those two selectors happen to match.
+    if (waveEditorIsModal()) return;
     const cellEl = e.target && e.target.closest && e.target.closest('.ed-wys-cell');
     if (cellEl) {
       e.preventDefault();
@@ -14930,25 +16757,1394 @@
   document.addEventListener('scroll', onAnyScroll, { passive: true, capture: true });
 
   window.addEventListener('beforeunload', (e) => {
-    if (stack.dirtyDepth !== 0 || burstHasUncommittedEdit()) {
+    // Review I1: documentIsDirty(), not a second copy of the expression it
+    // wraps — this was the second caller still spelling it out by hand.
+    if (documentIsDirty()) {
       e.preventDefault();
       e.returnValue = '';
       return '';
     }
   });
 
+  // v3.4.0 batch2 Task 6 (Ruling B2-2) — background refresh for a referenced
+  // `.drawio`/`.xml` file that changed on disk, triggered by the ping loop
+  // below seeing `{stale:true}`.
+  //
+  // Deliberately NOT rerenderAll(): that function carries edit-commit
+  // semantics nobody asked for here (dropDiscardedBurst/dropDiscardedRawEdit,
+  // the swallowed-fence banner, `pendingSelectionRange` consumption) — this
+  // only ever touches blocks whose OWN baked diagram actually differs, never
+  // reassigns `blocks`/`lines` (the source text did not change, only a
+  // referenced file's bytes did), and never moves focus out of an editor.
+  //
+  // ── Fix round 2 (re-review G1): ONE criterion for "is there a diagram here"
+  //
+  // The first cut asked two different questions. The pre-fetch guard asked the
+  // DOM (`querySelector('.drawio')`); the per-block loop asked a text regex
+  // over the part strings. They disagree on a block whose rendered markup
+  // merely CONTAINS the literal — a fenced code block or a table cell
+  // documenting this very feature, which this repo's own docs plausibly hold.
+  // Three consequences, all of them real:
+  //   * a fenced code block selected as a diagram block and was replaced
+  //     wholesale on every re-bake (G3),
+  //   * the pre-fetch guard could not see a bail the loop would take, so with
+  //     F2's retry in place the caret resting in that code block cost a full
+  //     /api/render — headless Chromium, every page of every referenced
+  //     diagram — every 10 seconds, forever, with the diagram never updating,
+  //   * and because the bootstrap seed is the HTML parser's re-serialisation
+  //     rather than the server's own strings, the cheap `parts[i] ===
+  //     lastParts[i]` equality never fired on an unedited tab, so ONE external
+  //     write re-swapped EVERY diagram block on the page (G4).
+  //
+  // Both sides now ask the same question, and it is the structural one: does
+  // this markup contain a real element with class `drawio`? The old side reads
+  // the live node; the new side parses the part and reads that. Text that
+  // merely quotes the markup parses to a text node inside <code> and is not
+  // selected by anything. DRAWIO_TEXT_HINT survives only as a cheap SUPERSET
+  // prefilter so the parse is skipped for the overwhelming majority of blocks
+  // — it never decides anything on its own.
+  //
+  // And "did it actually change" is answered by a fingerprint of the baked
+  // diagram taken through the SAME parser on both sides (so the seed's
+  // non-byte-identity cannot leak in), deliberately ignoring `hidden` — that
+  // is the reader's page selection, not part of the bake.
+  const DRAWIO_TEXT_HINT = /class="[^"]*\bdrawio\b/;
+  const DRAWIO_FP_SEP = '';
+
+  // Fix round 3 (re-review2 H2): ALL of them, not the first.
+  // `![a](a.drawio) ![b](b.drawio)` on one markdown line is ONE block holding
+  // TWO `.drawio` boxes — verified by render, and a table row of diagrams does
+  // the same. Round 2 compared only `querySelector('.drawio')`, so a change to
+  // the SECOND file left the comparison equal, the loop `continue`d, `applied`
+  // stayed true, the tab ACKED, and the server advanced its baseline past an
+  // update the DOM never took: silent, permanent, and exactly the invariant
+  // F2 exists to hold. Everything below therefore works on the whole list.
+  function drawioBoxesIn(node) {
+    return (node && node.querySelectorAll)
+      ? Array.prototype.slice.call(node.querySelectorAll('.drawio'))
+      : [];
+  }
+  function drawioBoxIn(node) {
+    return (node && node.querySelector) ? node.querySelector('.drawio') : null;
+  }
+  function parsePartMarkup(part) {
+    const t = document.createElement('template');
+    t.innerHTML = part;
+    return t;
+  }
+  // Fix round 3 (re-review2 H3): the reader's annotation feature mutates the
+  // live `.drawio-page` IN PLACE — `annoSyncInline()` (lib/md2doc.js) wraps the
+  // visible <svg> in `<span class="anno-inline-wrap">` and appends an
+  // `<svg class="anno-inline">` overlay beside it, and the wrap is never
+  // removed again. The fresh parse of a part never carries either, so an
+  // annotated diagram could NEVER fingerprint equal, and G4's whole point —
+  // "a write to a.drawio must not touch the block holding b.drawio" — failed
+  // for exactly the blocks carrying the reader's own work.
+  //
+  // Normalising undoes the wrap on a CLONE so the comparison sees the bake
+  // again. MEASURED: normalising an annotated page yields a string byte-equal
+  // to an unannotated page baked from the same file (1170 chars vs 2171 raw).
+  // The clone only happens when the cheap `querySelector` says there is
+  // something to undo, so an unannotated document pays one selector per page.
+  function drawioPageMarkup(pageEl) {
+    if (!pageEl.querySelector('.anno-inline-wrap')) return pageEl.innerHTML;
+    const c = pageEl.cloneNode(true);
+    Array.prototype.forEach.call(c.querySelectorAll('svg.anno-inline'),
+      function (o) { if (o.parentNode) o.parentNode.removeChild(o); });
+    Array.prototype.forEach.call(c.querySelectorAll('.anno-inline-wrap'),
+      function (w) {
+        const parent = w.parentNode;
+        if (!parent) return;
+        while (w.firstChild) parent.insertBefore(w.firstChild, w);
+        parent.removeChild(w);
+      });
+    return c.innerHTML;
+  }
+  // Identity of what was BAKED into one `.drawio` box. `hidden` is excluded on
+  // purpose (page selection is view state this function must not react to),
+  // and so is the page-navigation node the init hook appends — it is a child
+  // of the box, never of a `.drawio-page`. A failed bake has no pages, so its
+  // rendered error text is its identity instead.
+  function drawioFingerprint(box) {
+    if (!box) return null;
+    const pages = box.querySelectorAll('.drawio-page');
+    if (!pages.length) return 'raw' + DRAWIO_FP_SEP + box.innerHTML;
+    const out = ['pages' + DRAWIO_FP_SEP + (box.getAttribute('data-drawio-pages') || '')];
+    for (let i = 0; i < pages.length; i++) out.push(drawioPageMarkup(pages[i]));
+    return out.join(DRAWIO_FP_SEP);
+  }
+  // Identity of every diagram in one block. The count leads, so a block that
+  // gained or lost a box can never collide with one that did not.
+  function drawioBlockFingerprint(boxes) {
+    const out = [String(boxes.length)];
+    for (let i = 0; i < boxes.length; i++) out.push(drawioFingerprint(boxes[i]));
+    return out.join(DRAWIO_FP_SEP + DRAWIO_FP_SEP);
+  }
+
+  let drawioRefreshInFlight = false;
+  // Fix round 1 (review F2): the token from the last refresh that ACTUALLY
+  // landed in the DOM, to be handed back on the next heartbeat. The server
+  // advances that tab's staleness baseline on this and on nothing else, so
+  // every bail path below — by simply not setting it — is genuinely retried
+  // on the next tick instead of losing the change for the rest of the
+  // session.
+  let drawioAckPending = null;
+
+  // ── Fix round 2 (re-review G1b): a persistent bail must not cost a bake ──
+  //
+  // The three pre-fetch bails below make the long-lived conditions free, and
+  // G1a removes the one post-fetch bail whose condition the pre-fetch side
+  // could not see. What this backs up is everything that cannot be enumerated
+  // in advance: /api/render answering 500 deterministically, a server whose
+  // ref list flaps between two tabs, a future bail nobody thought about here.
+  // Any of those would otherwise re-issue a full render + Chromium bake on
+  // every 10s beat for the life of the session.
+  //
+  // Only a bail that already PAID for a fetch counts. A pre-fetch bail is free
+  // and must stay instant, or a reader who simply rested their caret in a
+  // diagram block would be punished with minutes of latency once they moved.
+  //
+  // The update is delayed, never dropped: the server keeps re-reporting the
+  // same staleness (F2's invariant is untouched), and the next attempt after
+  // the blocking condition clears applies it. DOWNSIDE, stated plainly: after
+  // a run of paid bails, a refresh that WOULD now succeed can wait up to
+  // DRAWIO_BACKOFF_CAP_MS before it is tried. That is the price of bounding
+  // the bake rate to once per that interval instead of once per beat.
+  const DRAWIO_BACKOFF_BASE_MS = 10000;
+  const DRAWIO_BACKOFF_CAP_MS = 160000;
+  const DRAWIO_FETCH_TIMEOUT_MS = 120000;
+  let drawioBailStreak = 0;
+  let drawioNextAttemptAt = 0;
+
+  // Fix round 2 (re-review G6): the deferred notice now carries the moment it
+  // was raised. A banner that surfaces minutes late describes a landing the
+  // reader has long since navigated away from — worse than no banner, and the
+  // same "teaches the user to ignore it" failure F6 was about.
+  const DRAWIO_NOTICE_TTL_MS = 60000;
+  // Fix round 1 (review F5): a notice this background path wants to show but
+  // must not show YET. showBanner() is destructive by construction — its
+  // first statement removes whatever banner is up — and every other caller in
+  // this file is a response to a user gesture. This one fires from a timer,
+  // and the banner it would remove can be the disk-conflict one, which is the
+  // user's only route to resolving a conflict on the one data-safety-critical
+  // path this editor has (it carries the Reload button). So the notice waits
+  // for an empty slot instead of taking one.
+  let drawioDeferredNotice = null;
+  // showBanner() also tears down these four overlays unconditionally. That is
+  // right for a gesture-driven caller and wrong for a timer: firing it while
+  // the reader has a grip, an insert bubble, the table edge menu or the H▾
+  // dropdown open closes it under them at a moment nothing on screen
+  // explains. So the flush waits for those too (re-review G6).
+  function noticeTeardownWouldDisrupt() {
+    if (toolbarMenuEl) return true;
+    if (teEdgeMenu && !teEdgeMenu.hidden) return true;
+    if (rowGrip && !rowGrip.hidden) return true;
+    if (colGrip && !colGrip.hidden) return true;
+    if (rowInsertBubble && !rowInsertBubble.hidden) return true;
+    if (colInsertBubble && !colInsertBubble.hidden) return true;
+    return false;
+  }
+  function noteDrawioNotice(message) {
+    if (activeBanner || noticeTeardownWouldDisrupt()) {
+      drawioDeferredNotice = { message: message, at: Date.now() };
+      return;
+    }
+    drawioDeferredNotice = null;
+    showBanner(message, null, null);
+  }
+  function flushDrawioNotice() {
+    if (!drawioDeferredNotice) return;
+    if (Date.now() - drawioDeferredNotice.at > DRAWIO_NOTICE_TTL_MS) {
+      drawioDeferredNotice = null;   // stale: it no longer describes the page
+      return;
+    }
+    if (activeBanner || noticeTeardownWouldDisrupt()) return;
+    const m = drawioDeferredNotice.message;
+    drawioDeferredNotice = null;
+    showBanner(m, null, null);
+  }
+  const DRAWIO_PAGE_GONE_MSG =
+    '目前檢視的 drawio 分頁已不存在（可能已刪除或改名），已切回第一頁。';
+  // Fix round 3 (re-review2 H3 / Q1 ruling). Annotations are reading-session
+  // scratch — lib/md2doc.js keeps them in a WeakMap keyed by the source node
+  // and says so ("In-memory only — gone on reload"; nothing writes them to
+  // localStorage or to disk) — but they are still the reader's own work, and
+  // a re-bake changes the geometry they were drawn over, so carrying them
+  // across would place marks on shapes that moved. They are dropped, and the
+  // reader is told which diagram lost them and why.
+  const DRAWIO_ANNO_DROPPED_MSG =
+    '這張 drawio 圖在磁碟上被改過，已重新繪製；畫在舊版上的註記無法對應到新的圖形，已移除。';
+
+  // What "never yank focus out from under the user" actually has to mean here.
+  //
+  // An EDITING SURFACE — a contenteditable, a raw-source textarea, an input —
+  // is something the user is working IN; replacing the node under it destroys
+  // work in progress and is never acceptable for a refresh nobody asked for.
+  // Anything else that merely happens to hold focus is not: MEASURED — a
+  // click on the multi-page navigation leaves that <button> as
+  // document.activeElement, and it sits inside the very block a re-bake
+  // replaces. Treating that as "the user is busy here" means the reader who
+  // just picked a page, alt-tabbed to Draw.io and edited the file comes back
+  // to a diagram that (with fix round 1's retry in place) refuses to update
+  // for the whole session instead of losing the update once. So the guard is
+  // scoped to surfaces, and a focused non-surface is allowed to be replaced.
+  function focusIsEditingSurface(node) {
+    if (!node) return false;
+    if (node.isContentEditable) return true;
+    const tag = node.tagName;
+    return tag === 'TEXTAREA' || tag === 'INPUT' || tag === 'SELECT';
+  }
+
+  // Is the user editing inside a block that carries a diagram we may be about
+  // to replace? Checked BEFORE the fetch as well as per block after it: with
+  // F2's retry in place an unconditional fetch would otherwise re-run a full
+  // headless-Chromium bake every 10 seconds for as long as that editor stays
+  // open. G1a is what makes this pre-check and the per-block skip agree: both
+  // now ask drawioBoxIn() about the same live node.
+  function drawioBlockHoldsEditingFocus() {
+    const ae = document.activeElement;
+    if (!ae || !contentEl.contains(ae)) return false;
+    if (!focusIsEditingSurface(ae)) return false;
+    const kids = contentEl.children;
+    for (let i = 0; i < kids.length; i++) {
+      if (!kids[i].contains(ae)) continue;
+      return !!drawioBoxIn(kids[i]);
+    }
+    return false;
+  }
+
+  async function refreshStaleDrawio(token) {
+    if (drawioRefreshInFlight) return;
+    // Review question Q2 / G1b: the cheap "there is nothing on screen this
+    // could possibly change" and "the user is in the middle of something"
+    // answers are given BEFORE the fetch, so a condition that can hold
+    // indefinitely never costs a bake. None of them acks — nothing was
+    // applied, so the next tick must ask again.
+    if (!contentEl.querySelector('.drawio')) return;
+    if (!domMatchesLastRender()) return;
+    if (drawioBlockHoldsEditingFocus()) return;
+    // Fix round 2 (re-review G7): a block drag in flight addresses every block
+    // by ordinal across .content. applyPatch()/applyFullRender() cancel it
+    // because they are gesture-driven and the gesture is already over; a
+    // background timer has no such licence, so it waits the drag out instead.
+    // Free and self-clearing — a drag is a pointer gesture, it cannot last.
+    if (blockDragState) return;
+    // Fix round 3 (re-review2 H1): a `.drawio` inside a table cell makes the
+    // whole TABLE block replaceable by this path (verified by render — round
+    // 2's report claimed the opposite). A live row/column pointer gesture
+    // addresses rows and cells inside that table, so the refresh waits it out
+    // rather than cancelling it from a timer — the same construction, and the
+    // same reasoning, as `blockDragState` just above.
+    if (tePointer) return;
+    if (Date.now() < drawioNextAttemptAt) return;
+    drawioRefreshInFlight = true;
+    // Fix round 2 (re-review G8): without a deadline, one request that never
+    // settles (a server wedged inside a bake — bakeDrawioSvg() has no
+    // per-page timeout of its own) leaves this flag true forever, every later
+    // {stale:true} returns at the line above, and the whole feature is
+    // silently and permanently dead until the user reloads, with no signal at
+    // all. An abort turns that into an ordinary paid bail: backed off, retried.
+    const ctl = (typeof AbortController === 'function') ? new AbortController() : null;
+    const abortTimer = ctl
+      ? setTimeout(function () { try { ctl.abort(); } catch (e) { /* already settled */ } },
+                   DRAWIO_FETCH_TIMEOUT_MS)
+      : null;
+    let paidForAFetch = false;
+    let acked = false;
+    try {
+      const startContent = lines.join('\n');
+      let res;
+      paidForAFetch = true;
+      try {
+        const init = {
+          method: 'POST', headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ fileId: ED.fileId, content: startContent }),
+        };
+        if (ctl) init.signal = ctl.signal;
+        res = await fetch('/api/render', init);
+      } catch (e) { return; }
+      if (!res.ok) return;
+      let j;
+      try { j = await res.json(); } catch (e) { return; }
+      if (!Array.isArray(j.parts) || !Array.isArray(j.blocks)) return;
+      // A real edit may have landed (and its own rerenderAll() already read
+      // the file fresh) while this request was in flight — `lines` no
+      // longer matches what this response was computed from, so there is
+      // nothing left to apply; the document already shows current content.
+      if (lines.join('\n') !== startContent) return;
+      if (!Array.isArray(lastParts) || lastParts.length !== j.parts.length ||
+          !Array.isArray(blocks) || blocks.length !== j.blocks.length) return;
+      // Same precondition applyPatch()'s own plan requires (see
+      // domMatchesLastRender()'s comment): several list gestures mutate
+      // .content's child list directly, between renders, without going
+      // through a commit yet. If the DOM does not positionally match
+      // `lastParts` right now, a mid-gesture edit is in flight — bail rather
+      // than swap the wrong child. Re-read after the await, because the
+      // pre-fetch check above cannot speak for the time the render took; same
+      // for the block drag.
+      if (!domMatchesLastRender()) return;
+      if (blockDragState) return;
+      if (tePointer) return;
+      // Every block this refresh was responsible for has to land before the
+      // server is told the tab is up to date. One skipped block means the
+      // user is still looking at stale bytes, which is exactly the state F2
+      // says must keep being retried.
+      let applied = true;
+      for (let i = 0; i < j.parts.length; i++) {
+        const el = contentEl.children[i];
+        const oldBoxes = drawioBoxesIn(el);
+        // The prefilter is a superset test and decides nothing: it only says
+        // "parsing this part might be worth it".
+        if (!oldBoxes.length && !DRAWIO_TEXT_HINT.test(j.parts[i])) continue;
+        const tpl = parsePartMarkup(j.parts[i]);
+        const newBoxes = drawioBoxesIn(tpl.content);
+        // Neither side holds a real diagram — the hint matched text that only
+        // quotes this markup (a fenced code block, a table cell). Not a
+        // candidate for anything, by either criterion.
+        if (!oldBoxes.length && !newBoxes.length) continue;
+        // Every diagram in the block is compared, and the bake is identical:
+        // nothing to do. This is what keeps one external write from re-swapping
+        // every OTHER diagram on the page (G4) — while H2 is why it has to be
+        // every box and not just the first.
+        if (drawioBlockFingerprint(oldBoxes) === drawioBlockFingerprint(newBoxes)) continue;
+
+        if (!el) { applied = false; continue; }
+        // Never destroy an editor the user has open in this block — see
+        // focusIsEditingSurface() for why it is surfaces and not "anything
+        // focused". Not applied, so not acked: the next tick tries again, and
+        // because the pre-fetch guard asks drawioBoxIn() about the same live
+        // node, that next tick bails BEFORE paying for a render.
+        if (el.contains(document.activeElement) && focusIsEditingSurface(document.activeElement)) {
+          applied = false; continue;
+        }
+        // Fix round 2 (re-review G7): `gutterMenu` and `insertMenu` are ONE
+        // shared node each, appended as a CHILD of whichever block they are
+        // open for. Replacing that block detaches the singleton with no close
+        // path run, leaving `gutterMenuBlockEl`/`insertMenuBlockEl` pointing
+        // at a node no future click can reach — the exact hazard
+        // applyPatch()/applyFullRender() call these two for. Scoped to the
+        // block actually being replaced rather than called unconditionally
+        // the way those two do, and the reason is the one F5 turns on: they
+        // run on a user gesture that is already over, this runs on a 10s
+        // timer, and closing a menu the reader has open on an UNRELATED block
+        // would be a fresh instance of exactly the defect F5 closed.
+        if (gutterMenuBlockEl === el) closeGutterMenu();
+        if (insertMenuBlockEl === el) closeInsertMenu();
+        // Fix round 3 (re-review2 H1). Round 2's report said 「一個 drawio 區塊
+        // 永遠不是表格」 and refused the table resets on that basis. The claim is
+        // FALSE — rendering `| ![d](d.drawio) | x |` yields a
+        // `data-block-type="table"` block whose first cell holds the box, so
+        // this path really can replace a whole table. The grips and the edge
+        // menu live on document.body, so the swap does not detach them: they
+        // stay visibly floating while `teMenuTableEl` / `teMenuRowEl` /
+        // `gripRowTableEl` / `gripRowEl` / `gripColTableEl` point into a tree
+        // nothing can reach. Scoped exactly like the two menus above, and for
+        // the same reason. (A live row/column POINTER gesture is not handled
+        // here at all — `if (tePointer) return;` above waits it out rather
+        // than killing it from a timer, the same construction `blockDragState`
+        // uses. The insert bubbles hold no element reference of their own —
+        // hideTableInsertBubbles() only flips two `hidden` flags — so nothing
+        // of theirs can dangle; the next mousemove re-derives them.)
+        if ((teMenuTableEl && el.contains(teMenuTableEl)) ||
+            (teMenuRowEl && el.contains(teMenuRowEl))) hideTableEdgeMenu();
+        if ((gripRowTableEl && el.contains(gripRowTableEl)) ||
+            (gripRowEl && el.contains(gripRowEl)) ||
+            (gripColTableEl && el.contains(gripColTableEl))) hideTableGrips();
+        // A non-surface node inside this block (the roving-tabindex holder of
+        // a block selection, a page button just clicked) is about to stop
+        // existing. Put focus back on the block wrapper afterwards when the
+        // wrapper is a legitimate focus holder, so a keyboard user keeps
+        // their place instead of being dropped at <body>.
+        const refocusWrapper = el.contains(document.activeElement) && el.hasAttribute('tabindex');
+
+        // Ruling B2-2 (c): preserve the reader's currently-open page across
+        // the swap, falling back to the first page with a visible banner when
+        // it genuinely no longer exists. resolveDrawioLanding() (near the top
+        // of this file, unit-tested) owns the "is a page name an identity
+        // here at all" question — see its comment.
+        //
+        // Fix round 3 (re-review2 H2, second half): captured for EVERY box in
+        // the block, not just the first, so a second multi-page diagram in one
+        // block keeps the reader's page too.
+        const oldLandings = oldBoxes.map(function (box) {
+          if (!box.hasAttribute('data-drawio-pages')) return null;
+          let names = [];
+          try { names = JSON.parse(atob(box.getAttribute('data-drawio-pages') || '')); }
+          catch (e2) { names = []; }
+          if (!Array.isArray(names) || names.length < 2) return null;
+          const pages = box.querySelectorAll('.drawio-page');
+          const activePage = box.querySelector('.drawio-page:not([hidden])');
+          return {
+            names: names,
+            activeIdx: activePage ? Array.prototype.indexOf.call(pages, activePage) : -1,
+          };
+        });
+
+        // Fix round 3 (re-review2 H3, Q1 ruling). The reader's annotations are
+        // drawn INTO this block's `.drawio-page` and cannot be carried onto a
+        // re-baked diagram whose geometry is different — but dropping the
+        // user's own work silently is not something this codebase does. The
+        // unrelated-write case never reaches here at all (drawioPageMarkup()
+        // normalises the annotation subtree out of the fingerprint, so such a
+        // block compares equal and is not swapped); what is left is the case
+        // where the annotated diagram's OWN bytes changed, and that one is
+        // told. Same principle as B2-P1: the two outcomes must not both be
+        // silent.
+        const hadAnnotations = !!(el.querySelector && el.querySelector('.anno-inline-wrap'));
+
+        const fresh = tpl.content.firstElementChild;
+        if (!fresh) { applied = false; continue; }
+        armEditables(tpl.content);
+        // Best-effort carry-over of the wrapper's own visual state. Never
+        // reaches into blockSelection / applySelectionClasses() here — that
+        // call also moves focus, which a background refresh must never do.
+        if (el.classList.contains('ed-selected')) fresh.classList.add('ed-selected');
+        if (el.hasAttribute('tabindex')) fresh.setAttribute('tabindex', el.getAttribute('tabindex'));
+
+        el.replaceWith(fresh);
+        lastParts[i] = j.parts[i];
+        // preventScroll: this is a background refresh — .focus()'s default
+        // scroll-into-view would yank the reader's viewport to a block they
+        // merely left focused before scrolling away.
+        if (refocusWrapper && fresh.focus) fresh.focus({ preventScroll: true });
+        if (hadAnnotations) noteDrawioNotice(DRAWIO_ANNO_DROPPED_MSG);
+
+        // Fix round 1 (review F5 second half): the page landing and its
+        // notice happen whether or not the page-navigation hook exists.
+        // They used to sit INSIDE the hook check, so a document that was
+        // single-page when the tab opened (the hook is gated on that, by a
+        // byte-exact guard test) lost the page preservation AND the
+        // "your page is gone" notice together — both branches of Ruling
+        // B2-P1 going silent at once. Only the navigation rebuild itself
+        // genuinely depends on the hook.
+        if (window.__md2docInitDrawioSheetBar) {
+          try { window.__md2docInitDrawioSheetBar(fresh); } catch (e4) { /* navigation only */ }
+        }
+        const freshBoxes = drawioBoxesIn(fresh);
+        // Align old boxes to new ones BY POSITION, and only when the block
+        // still holds the same number of diagrams. A block whose box count
+        // changed has had one reference stop (or start) being bakeable, and
+        // position no longer identifies anything — landing every box on the
+        // baked default is then the only answer we can stand behind. Claiming
+        // a page deletion there would be the same false-banner mistake F6 was
+        // about, so that case is deliberately quiet.
+        if (freshBoxes.length !== oldBoxes.length) continue;
+        for (let b = 0; b < freshBoxes.length; b++) {
+          const prev = oldLandings[b];
+          if (!prev) continue;                       // was not a multi-page box
+          const box = freshBoxes[b];
+          if (!box.hasAttribute('data-drawio-pages')) continue;
+          let newNames = [];
+          try { newNames = JSON.parse(atob(box.getAttribute('data-drawio-pages') || '')); }
+          catch (e3) { newNames = []; }
+          if (!Array.isArray(newNames)) newNames = [];
+          const newPages = box.querySelectorAll('.drawio-page');
+          const landing = resolveDrawioLanding(prev.names, prev.activeIdx, newNames);
+          // Review Q1: clamp. `data-drawio-pages` and the .drawio-page children
+          // are emitted together by lib/md2doc.js so they cannot disagree
+          // today, but an out-of-range index here hides EVERY page and paints a
+          // blank box — one line is cheaper than that failure.
+          let landOn = landing.landOn;
+          if (!(landOn >= 0) || landOn >= newPages.length) landOn = 0;
+          for (let p = 0; p < newPages.length; p++) newPages[p].hidden = p !== landOn;
+          const bar = box.querySelector('.drawio-sheetbar');
+          if (bar) {
+            bar.querySelectorAll('button').forEach(function (btn, bidx) {
+              btn.setAttribute('aria-pressed', bidx === landOn ? 'true' : 'false');
+            });
+          }
+          if (landing.gone) noteDrawioNotice(DRAWIO_PAGE_GONE_MSG);
+        }
+      }
+      if (applied && typeof token === 'string' && token !== '') {
+        drawioAckPending = token;
+        acked = true;
+      }
+    } finally {
+      if (abortTimer) clearTimeout(abortTimer);
+      drawioRefreshInFlight = false;
+      if (acked) {
+        drawioBailStreak = 0;
+        drawioNextAttemptAt = 0;
+      } else if (paidForAFetch) {
+        drawioBailStreak += 1;
+        const wait = Math.min(DRAWIO_BACKOFF_BASE_MS * Math.pow(2, drawioBailStreak),
+                              DRAWIO_BACKOFF_CAP_MS);
+        drawioNextAttemptAt = Date.now() + wait;
+      }
+    }
+  }
+
   setInterval(() => {
+    // A notice this refresh could not show earlier because the slot was
+    // taken (see noteDrawioNotice) gets its next chance here, on the same
+    // clock — or is dropped if it has gone stale.
+    flushDrawioNotice();
     // /api/ping requires content-type: application/json like the other
     // state-changing POST routes (415 otherwise) — see server.js's CORS
     // defense. A body is included so the header is meaningful, not just
     // present on an otherwise-empty request.
+    //
+    // v3.4.0 batch2 Task 6 (Ruling B2-2): `fileId` + this tab's own
+    // `drawioClientId` let server.js answer whether any `.drawio`/`.xml`
+    // this document references changed on disk since the bytes THIS TAB is
+    // showing — see its own comment on /api/ping. A 204 (no body) means
+    // "nothing stale", the same outcome this heartbeat always had; a 200
+    // with `{stale:true, token}` is new and triggers a background refresh.
+    // `drawioAck` carries back the token of the last refresh that actually
+    // landed, and is the ONLY thing that advances this tab's baseline.
+    // Every failure mode (network error, non-200/204 status, malformed
+    // JSON) is swallowed exactly like the old bare ping already swallowed
+    // everything — a missed signal just waits for the next 10s tick, which
+    // is the accepted worst-case latency for this whole feature.
+    const ack = drawioAckPending;
+    drawioAckPending = null;
     fetch('/api/ping', {
-      method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}',
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ fileId: ED.fileId, drawioClientId: ED.drawioClientId, drawioAck: ack }),
+    }).then((res) => {
+      if (res.status !== 200) return null;
+      return res.json().catch(() => null);
+    }).then((j) => {
+      if (j && j.stale) refreshStaleDrawio(j.token).catch(() => {});
     }).catch(() => {});
   }, 10000);
 
   armEditables(contentEl);
   wireBlockSelection();
+
+  // ── v3.4.0 batch3 Task 6: the wavedrom editing surface ─────────────────
+  //
+  // Entry is a hover affordance over an already-rendered diagram, and the
+  // affordance itself lives on document.body — not in .content. Everything in
+  // .content is read back as this tab's own render (see `lastParts` above) and
+  // the WYSIWYG path turns it into markdown, so a control parked in there would
+  // travel into the user's file. The table grips already sit on body for the
+  // same reason; this follows them rather than inventing a second policy.
+  //
+  // The block is NOT parsed here. Ruling P3-6 parses at Edit-click time, so a
+  // document with forty diagrams pays nothing for thirty-nine of them, and a
+  // block whose WaveJSON cannot be read still gets an editor — one that says
+  // what the parser said and where — instead of a button that silently does
+  // nothing.
+  let waveDiagramEl = null;
+  let waveEditor = null;
+  // The seam Task 7 writes through: which block the open editor came from, and
+  // the line range of the fence's BODY (the fence markers themselves are not
+  // the editor's to rewrite). `lastGesture` is refreshed on every gesture, not
+  // accumulated — wave-ui computes one patch per gesture precisely so a
+  // write-back never has to replay a session's worth of them.
+  //
+  // Task 7's own fields, and why each is here rather than derived:
+  //   ops        how many commits this session has pushed onto the document
+  //              stack. Escape reverses exactly this many — see
+  //              finishWaveSession().
+  //   baseLines  `lines` as it stood when the editor opened, and
+  //   baseBlocks `blocks` likewise. Escape restores both BY VALUE instead of
+  //              trusting the reversal's arithmetic to land back where it
+  //              started; the two are the same answer, and one of them cannot
+  //              be off by a line.
+  //   baseSource the block body the store was opened over, i.e. what `lines`
+  //              holds again once an Escape has run. The stash's staleness
+  //              guard compares against it.
+  //   unwritten  this session has a gesture the file could not express (the
+  //              document-level flag `waveUnwrittenEdit` is the same fact; the
+  //              flag is what documentIsDirty() reads, this is what the
+  //              session's own bookkeeping reads).
+  //   baseDepth  how deep the document's undo stack was at open — the one
+  //              baseline both of waveDiscardIsSafe()'s questions are asked
+  //              against. See that function for the measured sequence that
+  //              killed the arithmetic it replaces (fix 2 / MUST-FIX 1).
+  //   baseRedoTail  the redo branch that existed before the session (fix 1 /
+  //              F3). The session's first commit clears it like any other edit;
+  //              a session that is DISCARDED has to hand it back, or the user
+  //              silently loses a redo to a document that ends up
+  //              byte-identical.
+  let waveSeam = null;
+  // Gestures that arrived with no editor left to own them. Zero is the
+  // invariant, not a tolerance: a paint that lands after the overlay came down
+  // is one the user cancelled, applied to a store nobody can see. It used to be
+  // reachable — an Escape pressed mid-drag left the drag armed and the document
+  // listeners attached, so the eventual release still ran the paint. Counted
+  // rather than merely guarded against, because "it cannot happen" is what the
+  // last version of this said.
+  let waveStrayGestures = 0;
+  const waveEditBtn = document.createElement('button');
+  waveEditBtn.type = 'button';
+  waveEditBtn.className = 'ed-wave-edit-btn';
+  waveEditBtn.textContent = '編輯波形';
+  waveEditBtn.title = '用圖形介面編輯這張時序圖';
+  waveEditBtn.hidden = true;
+  document.body.appendChild(waveEditBtn);
+
+  /**
+   * Whether the wave editor is the modal surface right now.
+   *
+   * The one question every global handler in this file asks about it, and it is
+   * deliberately a question about STATE and not about the event.
+   *
+   * The previous version asked "did this event land inside the overlay?", and
+   * that cannot answer "who owns the screen" — the answer has to be true before
+   * any event arrives. MEASURED: right after the overlay opens,
+   * `document.activeElement` is `document.body`, so every key targeted body and
+   * the editor behind the modal still owned it. Three things fell out of that
+   * one wrong question: Ctrl+Z in the unreadable panel rolled back the markdown
+   * document behind the modal, `Tab` was swallowed by the "nothing focused"
+   * branch so none of the dialog's controls could be reached by keyboard, and
+   * the block-selection delete path stayed live for a body target.
+   *
+   * A target test also means a LIST — one `closest()` per event someone thought
+   * of — and `drop` was the one nobody thought of: a PNG dragged onto the panel
+   * went into the document behind it. A state question has no list.
+   *
+   * A function declaration on purpose: it is hoisted, so the listeners
+   * registered far above can call it, and `waveEditor` is a `let` in this same
+   * scope that is initialised long before any event fires.
+   */
+  function waveEditorIsModal() {
+    return waveEditor !== null;
+  }
+
+  /**
+   * The one gesture the modal does not get to swallow.
+   *
+   * Kept beside the predicate rather than inlined at the call site, because
+   * "which gestures the modal owns" is part of the same answer as "who owns the
+   * screen", and the two belong in one place. Spelled exactly as the save branch
+   * — which is ~1230 lines ABOVE this, in the main `keydown` listener (measured:
+   * this declaration is at 16989, that branch at 15732) — so the two cannot drift
+   * into disagreeing about what a save keystroke is. The direction matters: a
+   * reader who goes looking DOWNWARD finds only the wave wiring, concludes this
+   * comment is stale, and edits one predicate without the other, which is exactly
+   * how the modal starts swallowing Ctrl+S again.
+   *
+   * ── Why this is the only exemption, as of v3.4.0 batch3 ─────────────────
+   *
+   * The question was asked of every branch of that listener rather than answered
+   * for Ctrl+S alone, and the answer is recorded here so the next person adding
+   * a global shortcut can see that it was asked:
+   *
+   *   - Everything about EDITING the document behind the modal — the toolbar's
+   *     keyboard mode, block selection's Tab/Delete/Backspace, the burst
+   *     short-circuits, undo/redo, Escape — is exactly what the modal is for.
+   *     Those stay swallowed.
+   *   - Escape, Tab and undo/redo are additionally CLAIMED by the overlay's own
+   *     capture-phase handler, which stops them before they reach here, so the
+   *     gate is their second line and not their first.
+   *   - `Ctrl+P` / `Ctrl+F` / `Ctrl+A` / `F5` have no handler in this file at
+   *     all, so the gate cannot swallow them: it is a bare `return` with no
+   *     `preventDefault()`, and the browser's own behaviour is untouched.
+   *   - `Ctrl+S` is the only global gesture this file implements that is not
+   *     about the covered document. It is the reflex that protects work, the
+   *     wave editor has nothing of its own to save in this task, and it is the
+   *     only producer of the 409 that raises the disk-conflict banner.
+   *
+   * So: a new global shortcut added below the gate is DEAD while the overlay is
+   * up. If it is about the document, that is correct. If it is not — a help
+   * panel, a command palette, anything the user reaches for regardless of what
+   * is on screen — it belongs in this function.
+   */
+  function isSaveGesture(e) {
+    return (e.ctrlKey || e.metaKey) && !e.shiftKey && e.key === 's';
+  }
+
+  function hideWaveEditBtn() {
+    // Already hidden is the overwhelmingly common case: this is called from a
+    // CAPTURE-phase `mouseover` on the document (once per element the pointer
+    // crosses) and a capture-phase `scroll` on the window (inner scrollers
+    // included). Writing `hidden` unconditionally made every pointer move over
+    // the page a DOM write on document.body's own subtree; the early return
+    // makes both free.
+    if (waveDiagramEl === null && waveEditBtn.hidden) return;
+    waveDiagramEl = null;
+    waveEditBtn.hidden = true;
+  }
+
+  function showWaveEditBtnFor(el) {
+    // Same diagram, already showing: nothing to write. The listener that calls
+    // this fires once per element the pointer crosses, and a diagram is a tree
+    // of them.
+    if (waveDiagramEl === el && !waveEditBtn.hidden) return;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return hideWaveEditBtn();
+    waveDiagramEl = el;
+    waveEditBtn.hidden = false;
+    // Top-right of the diagram, nudged inside it so it never hangs over the
+    // block gutter on the left or off the viewport on the right — and never
+    // above the toolbar's own band, which would put this button UNDER the bar
+    // (z-index 12 against 101) at every scroll position where the diagram's
+    // top edge has gone past it. See `toolbarTopInset()` for the measurement:
+    // the affordance was drawn, was invisible, was not clickable, and was the
+    // feature's only entry point.
+    waveEditBtn.style.top =
+      Math.max(toolbarTopInset() + 4, r.top + 6) + 'px';
+    waveEditBtn.style.left = Math.max(4,
+      Math.min(r.right - waveEditBtn.offsetWidth - 6,
+               window.innerWidth - waveEditBtn.offsetWidth - 6)) + 'px';
+  }
+
+  // The class the diagram init hook tags every rendered display div with; the
+  // id prefix is the same signal for a page that predates the class.
+  const WAVE_DIAGRAM_SEL = '.wavedrom-diagram, [id^="WaveDrom_Display_"]';
+
+  function waveDiagramAt(node) {
+    if (node === null || node === undefined || typeof node.closest !== 'function') return null;
+    return node.closest(WAVE_DIAGRAM_SEL);
+  }
+
+  /**
+   * The rendered diagram INSIDE a block, if it holds one.
+   *
+   * `waveDiagramAt()` answers the pointer's question — "what is under this
+   * element?" — by walking UP. The keyboard's question is the other direction:
+   * the user is standing on a whole block and wants to know whether it is a
+   * waveform. Same selector, deliberately shared, so the affordance a mouse
+   * user gets and the one a keyboard user gets can never come to disagree
+   * about which blocks are editable.
+   *
+   * A function declaration rather than an arrow const: the keydown listener
+   * that calls it is registered hundreds of lines above this point.
+   */
+  function waveDiagramInside(blockEl) {
+    if (blockEl === null || blockEl === undefined ||
+        typeof blockEl.querySelector !== 'function') return null;
+    return blockEl.querySelector(WAVE_DIAGRAM_SEL);
+  }
+
+  document.addEventListener('mouseover', (ev) => {
+    if (waveEditor !== null) return;
+    const t = ev.target;
+    if (t !== null && typeof t.closest === 'function' && t.closest('.ed-wave-edit-btn')) return;
+    const diagram = waveDiagramAt(t);
+    if (diagram === null) { hideWaveEditBtn(); return; }
+    showWaveEditBtnFor(diagram);
+  }, true);
+  window.addEventListener('scroll', () => { if (waveEditor === null) hideWaveEditBtn(); }, true);
+
+  // The fence BODY of one block: its source lines with the opening fence, and
+  // the closing fence when there is one, taken off. An unterminated fence at the
+  // end of the document has no closing line to drop, and dropping the last line
+  // anyway would silently eat a cycle of the user's diagram.
+  function waveBodyOf(block) {
+    const src = lines.slice(block.startLine - 1, block.endLine);
+    let end = src.length;
+    if (end > 1 && /^\s*(?:```+|~~~+)\s*$/.test(src[end - 1])) end--;
+    return {
+      text: src.slice(1, end).join('\n'),
+      startLine: block.startLine + 1,
+      endLine: block.startLine + end - 1,
+    };
+  }
+
+  async function openWaveEditor(diagram) {
+    const ui = window.md2docWaveUi;
+    const mods = window.__md2docWave;
+    // An older cached page that predates the injection must degrade to "the
+    // button does nothing visible", never to a throw out of a click handler.
+    if (!ui || !mods || !mods['wave-store.js'] || !mods['wave-codec.js'] ||
+        !mods['wave-geometry.js']) return;
+    if (waveEditor !== null) return;
+    hideWaveEditBtn();
+
+    // Settle the document BEFORE reading a single line out of it. An open
+    // burst or block editor is committed here, deliberately in front of the
+    // overlay rather than behind it: the commit rewrites `lines` and can
+    // re-render `.content`, and a line range read before that is stale the
+    // moment it is written. A standing block selection goes too — the wave
+    // editor is about to take the keyboard, and a selection the user can no
+    // longer see is a selection they cannot mean.
+    // fix 2 (R2): the return value is not decoration. When it is false an editor
+    // is still open BEHIND the overlay, and the session's own Ctrl+S — which
+    // runs `switchAwayFrom().then(ok => ok && save())` — then commits it,
+    // pushing a NON-wave op inside the session. That op breaks both of the
+    // session's bookkeeping assumptions at once: `seam.ops` no longer counts the
+    // top of the stack (so a discard would reverse somebody else's edit — now
+    // caught by waveDiscardIsSafe()'s depth question), and its line delta would
+    // be attributed to the wave block by settleWaveBlocks(), which is F2's own
+    // failure shape through a door F2 did not close. Every other caller in this
+    // file already treats false as "do not proceed"; so does this one.
+    // Was the keyboard standing ON this block when the editor opened? Asked
+    // BEFORE `switchAwayFrom()`, because that can re-render `.content` and
+    // detach the very elements the question is about.
+    //
+    // A state question, not a「which device opened it」one: the keyboard entry
+    // above always satisfies it, and so does a mouse user who selected the
+    // block first and then pressed the affordance — in both cases the editor
+    // is about to take a keyboard that was somewhere visible, and closing owes
+    // it back. When it is false (the ordinary hover-and-click), the keyboard
+    // was on `document.body` before the overlay opened and this changes
+    // nothing about where it ends up.
+    const cameFromBlockSelection = blockSelection !== null &&
+      typeof diagram.closest === 'function' &&
+      selectionFocusBlockEl() === diagram.closest('.ed-block');
+    if (!(await switchAwayFrom())) return;
+    clearBlockSelection();
+
+    // The re-render `switchAwayFrom()` may have run replaces `.content`
+    // wholesale, so the element that was hovered can be detached and its block
+    // id can have shifted. Re-resolve both, and give up quietly if the diagram
+    // is no longer on screen — the user hovers again, which is cheaper than
+    // opening an editor over a block that is not the one they pointed at.
+    if (!document.contains(diagram)) return;
+    const blockEl = diagram.closest('.ed-block');
+    if (blockEl === null) return;
+    const id = Number(blockEl.getAttribute('data-block-id'));
+    const block = blocks.find((b) => b.id === id);
+    if (!block) return;
+    const body = waveBodyOf(block);
+
+    // The seam is written only once the editor really exists. createWaveEditor
+    // can throw (the `.content` mount guard is a throw by design), and a seam
+    // left standing with no editor behind it is a lie the next gesture would
+    // read.
+    let editor = null;
+    try {
+      editor = ui.createWaveEditor({
+        document: document,
+        host: document.body,
+        source: body.text,
+        codec: mods['wave-codec.js'],
+        geometry: mods['wave-geometry.js'],
+        createStore: mods['wave-store.js'].createStore,
+        // The store's own answer to「哪一條 lane 是哪一條」across one operation,
+        // handed over rather than re-derived: the editor's cell cursor and its
+        // selection are row indexes, and the patch planner reads the identical
+        // function to decide which lane moved. Two implementations of that
+        // question would let a mark paint one lane while the patch wrote
+        // another.
+        laneTrace: mods['wave-store.js'].laneTrace,
+        wavedrom: (typeof WaveDrom !== 'undefined') ? WaveDrom : null,
+        onGesture: (info) => {
+          if (waveSeam === null) { waveStrayGestures++; return; }
+          waveSeam.lastGesture = info;
+          writeWaveGestureBack(info);
+        },
+        onClose: (reason) => {
+          // Read the seam out and null BOTH before doing anything slow: the
+          // predicate every global listener asks (`waveEditorIsModal()`) has to
+          // answer "no" from this instant, and finishWaveSession() below awaits
+          // a render. A seam still standing across that await is one a stray
+          // late gesture could write through.
+          const seam = waveSeam;
+          waveEditor = null;
+          waveSeam = null;
+          finishWaveSession(seam, reason)
+            // …and only then the keyboard, because the commit path RE-RENDERS
+            // `.content` and every block element that existed when the overlay
+            // was up is gone by the time that resolves. Focusing before the
+            // render would put the cursor on a detached node — which is
+            // `document.body` with extra steps.
+            .then(() => { giveKeyboardBackToWaveBlock(seam); })
+            .catch((err) => {
+              console.error('md2doc: the wave editor could not settle its ' +
+                'write-back', err);
+            });
+        },
+      });
+    } catch (err) {
+      waveEditor = null;
+      waveSeam = null;
+      throw err;
+    }
+    waveEditor = editor;
+    waveSeam = { blockId: id, startLine: body.startLine, endLine: body.endLine,
+                 lastGesture: null, ops: 0, unwritten: false,
+                 blockStartLine: block.startLine, blockEndLine: block.endLine,
+                 baseSource: body.text, baseLines: lines, baseBlocks: blocks,
+                 baseDepth: stack.depth, baseRedoTail: stack.redoTail(),
+                 reselect: cameFromBlockSelection };
+    // A fresh session cannot inherit the previous one's unwritten work: that
+    // session is over, and whatever it could not express went with it.
+    waveUnwrittenEdit = false;
+  }
+
+  // ── Task 7: one gesture, one write-back ────────────────────────────────
+  //
+  // Not one write-back per SESSION. Task 5 measured the store's refusal rate
+  // climbing with the number of structural operations stacked up before a
+  // patch is asked for — 8.0% at 1-3 operations, 17.0% at 1-6, and an
+  // independently generated corpus agreed on the shape (6.6% / 18.8%). Those
+  // refusals are correct; they are what replaced a class of silent corruption.
+  // But a refusal the user meets at the END of a session is one they have to
+  // bisect out of their own work, so the patch is computed and applied on the
+  // gesture that caused it. wave-ui already computes exactly one patch per
+  // gesture for this reason; this is the other end of that seam.
+  //
+  // Everything here goes through commitRangeEdit() — the same helper every
+  // other structural gesture in this file commits through — so the write-back
+  // lands on the document undo stack like any other edit. `lines` is never
+  // written directly. Two things fall out of that for free and are load-
+  // bearing, not incidental: `stack.dirtyDepth` counts the waveform (so the
+  // title dot, the save button and the beforeunload guard all see it without
+  // knowing what a waveform is), and Escape can take the session back off the
+  // stack rather than needing a stash of its own for the part that committed.
+  //
+  // What is deliberately NOT done here: re-rendering `.content`. The overlay
+  // covers the document, a render replaces `.content` wholesale, and doing it
+  // per paint would tear down and re-run WaveDrom on every gesture for a
+  // picture nobody can see. `.content` therefore lags `lines` for exactly as
+  // long as the modal is up, and the session's close settles it — a commit by
+  // rendering, an Escape by putting `lines` back to what `.content` is still
+  // showing.
+  function writeWaveGestureBack(info) {
+    const seam = waveSeam;
+    if (seam === null || !info || !info.patch) return;
+    if (info.patch.ok !== true) {
+      waveRefuseGesture(seam, info.patch.reason);
+      return;
+    }
+    const result = commitRangeEdit({ lines, blocks, stack },
+      seam.startLine, seam.endLine, info.patch.text);
+    if (result.op === null) {
+      // `commitRangeEdit()` returns `op: null` for two different reasons, and
+      // only one of them is "nothing to do": text that is already
+      // byte-identical, and — tagged `refused` — a line range it will not touch
+      // at all (an inverted one, i.e. a block that owns no source line).
+      //
+      // The `refused` arm is DEFENSIVE and is not known to be reachable from
+      // here (fix 2 / R3, correcting an earlier claim that it was): the only
+      // inverted seam this path can build comes from `waveBodyOf()` on an empty
+      // fence body, and an empty wavedrom fence renders no `.wavedrom-diagram`,
+      // so there is no hover affordance and no session. It is handled anyway
+      // because the cost of being wrong about that is the silent drop this
+      // whole layer exists to prevent, and the cost of the branch is three
+      // lines.
+      //
+      // fix 1 (F6): the sentence that stood here said this branch catches "an
+      // edit and its inverse inside one session". Re-derived, that is false
+      // under per-gesture write-back — `lines` already holds the forward edit,
+      // so the inverse produces a patch that DIFFERS from the current bytes and
+      // pushes a real second op (MEASURED: paint then the overlay's own undo
+      // gives `ops` 1 → 2, not `op === null`). The net-zero session is handled
+      // further down instead, by unwinding the ops rather than by never having
+      // pushed them.
+      if (result.refused) {
+        waveRefuseGesture(seam,
+          '這個區塊的行範圍不合法（' + result.refused + '），所以沒有東西可以改');
+        return;
+      }
+      seam.unwritten = false;
+      waveUnwrittenEdit = false;
+      setDirty();
+      return;
+    }
+    lines = result.lines;
+    // `blocks` is deliberately left alone until the session settles.
+    // commitRangeEdit()'s shift anchor is the last block ENDING at or before
+    // the edited range, and this range is the fence's BODY — strictly inside
+    // the code block — so the anchor is the block BEFORE it and the shift would
+    // move the wavedrom block's own startLine, which did not move. Leaving
+    // `blocks` at its opening value keeps it merely STALE (every id present,
+    // every span the one `.content` was rendered from) instead of wrong, and
+    // nothing reads it while the modal owns the screen.
+    //
+    // fix 1 (F2): "the close settles it" is now true on BOTH close paths, not
+    // only the one where the render succeeds — see settleWaveBlocks().
+    seam.ops++;
+    seam.endLine = seam.startLine + info.patch.text.split('\n').length - 1;
+    seam.unwritten = false;
+    waveUnwrittenEdit = false;
+    // fix 1 (F5): a session that has come back to the bytes it started from
+    // takes its own ops off the stack again, so the dirty dot goes out instead
+    // of standing for the rest of the session over a byte-identical file.
+    // MEASURED before this: paint, then the overlay's own undo — the document
+    // was back to the original and the title stayed `● doc` permanently.
+    if (bodyNow(seam) === seam.baseSource) unwindWaveOps(seam);
+    setDirty();
+  }
+
+  /** The block body as `lines` holds it right now. */
+  function bodyNow(seam) {
+    return lines.slice(seam.startLine - 1, seam.endLine).join('\n');
+  }
+
+  /** One refusal, recorded and raised. The only producer of `waveUnwrittenEdit`. */
+  function waveRefuseGesture(seam, reason) {
+    // A refusal is not papered over and not rolled back. wave-ui has already
+    // said so on the status line, which is where the user's eyes are, but a
+    // status line is not a decision — this raises it as a banner naming the
+    // lines it could not write and waits for the user to acknowledge it.
+    seam.unwritten = true;
+    waveUnwrittenEdit = true;
+    setDirty();
+    showWaveRefusal(seam, reason);
+  }
+
+  /**
+   * Take this session's own commits back off the document stack — bytes, stack
+   * depth and redo branch — and say whether that was possible.
+   *
+   * What it does NOT give back is the SAVE MARKER. `push()` invalidates that
+   * when history diverges past it, and a withdrawal cannot un-invalidate: the
+   * ops that produced the saved bytes are gone from this stack whether or not
+   * this session later changed its mind. MEASURED: edit, commit, Ctrl+S,
+   * Ctrl+Z, open the editor, paint once, Escape, Ctrl+Y — the session is fully
+   * withdrawn and the document is byte-identical to disk, and `●` still stands
+   * until the next Ctrl+S. That is over-warning, which is the safe direction
+   * and is deliberately not traded for a marker that could be wrong in the
+   * other one.
+   *
+   * Returns false when it was NOT — see waveDiscardIsSafe() for the two
+   * questions that decide it and for why neither is arithmetic over the dirty
+   * depth any more. When it answers false a Ctrl+S landed in the middle (the
+   * one gesture the modal deliberately does not swallow), or something other
+   * than this session pushed, and `discardTop()` must not run: it would either
+   * destroy the state disk was written from, or reverse somebody else's edit.
+   *
+   * The caller decides what to do about a false; this function never leaves the
+   * stack half-unwound.
+   */
+  function unwindWaveOps(seam) {
+    if (seam.ops === 0) return true;
+    if (!waveDiscardIsSafe(stack, seam)) return false;
+    for (let i = 0; i < seam.ops; i++) {
+      if (stack.discardTop(lines) === null) break;
+    }
+    // fix 1 (F3): the session's first commit cleared the redo branch that
+    // existed before it, and `discardTop()` has no way to put that back. A
+    // session that is being withdrawn has to, or the comment below would be
+    // claiming something that is measurably false.
+    stack.setRedoTail(seam.baseRedoTail);
+    // Restored BY VALUE rather than from discardTop()'s own returned arrays:
+    // the two are the same answer, and only one of them can be off by a line.
+    // discardTop() is still called for every op, because popping the stack is
+    // the half `baseLines` cannot do.
+    lines = seam.baseLines;
+    blocks = seam.baseBlocks;
+    seam.ops = 0;
+    seam.endLine = seam.startLine + seam.baseSource.split('\n').length - 1;
+    return true;
+  }
+
+  /**
+   * Make `blocks` agree with `lines` from the session's own arithmetic.
+   *
+   * Only ever needed because the session defers the block map to one render at
+   * the end, and that render can fail. See shiftBlocksAfterBodyEdit()'s own
+   * comment for what a stale `blocks` costs.
+   */
+  function settleWaveBlocks(seam) {
+    blocks = shiftBlocksAfterBodyEdit(seam.baseBlocks, seam.blockId,
+      lines.length - seam.baseLines.length);
+  }
+
+  /**
+   * Say, visibly, that a gesture could not be written — and name where.
+   *
+   * The status line inside the overlay already says it, and that is not
+   * enough: a status line is read while you are looking for it, and this is
+   * the one message in the feature that means "what you are looking at is not
+   * what the file has". So it is raised as a banner — the same `.ed-conflict`
+   * layer the disk-conflict notice uses, which is already painted ABOVE the
+   * modal and already inside the dialog's focus trap (see `modalRoots()` in
+   * wave-ui.js), so it is both visible and Tab-reachable without this having
+   * to invent a second modal layer.
+   *
+   * Nothing is rewritten and nothing is rolled back: `store.toPatch()`'s
+   * refusal travels to the user unchanged, which is what the whole codec layer
+   * exists to make possible.
+   *
+   * ── One coordinate, in the frame the user is looking at (fix 1 / F4) ─────
+   *
+   * The first cut named two: the block's current document line range, and a
+   * line number taken from `rewroteRange`'s offsets. The second was mapped
+   * through the store's own `sourceText` — the body AS IT WAS WHEN THE EDITOR
+   * OPENED, which is the only frame those offsets are exact in, since the store
+   * is created once per session. That mapping was right and the REPORTING was
+   * wrong: nothing in the sentence said the number belonged to a snapshot.
+   * MEASURED after a rename plus two lane-adds — the banner said 「這個區塊自己的
+   * 第 2 行」, which was the `clk` lane at open and is the just-added lane in the
+   * file the user now has, with `clk` one line further down. A user who counts
+   * two lines into the range the same sentence just gave them lands on the
+   * wrong lane.
+   *
+   * It is dropped rather than labelled. A number that needs a paragraph of
+   * frame-of-reference to be safe is not a coordinate, and the store's own
+   * `reason` already names the path it is about — which is the thing that
+   * survives a body whose line count has moved.
+   */
+  function showWaveRefusal(seam, reason) {
+    const range = seam.startLine === seam.endLine
+      ? ('第 ' + seam.startLine + ' 行')
+      : ('第 ' + seam.startLine + '–' + seam.endLine + ' 行');
+    // 知道了 is the confirmation the refusal waits for, and it is a SECOND
+    // button rather than a relabelled ✕: the ✕ on this banner means the same
+    // thing, but a dismiss glyph reads as "hide this" and the whole point of
+    // this banner is that the user has registered what it says. Acknowledging
+    // deliberately does NOT clear `waveUnwrittenEdit` — the work is still
+    // missing from the file after the user has read about it, and the dirty
+    // net is about the work, not about the notice.
+    let el = null;
+    el = showBanner(
+      '這個改動沒辦法只改幾個位元組寫回檔案，所以【沒有】寫回去 —— 編輯器上看到的' +
+      '比檔案裡多一步。受影響的是這個 wavedrom 區塊的內容，' + range +
+      '（不含前後兩道圍欄）。原因：' + reason,
+      '知道了',
+      () => {
+        if (el === null) return;
+        el.remove();
+        // Scoped to OUR element: a newer banner may have replaced this one on
+        // screen between the refusal and the acknowledgement, and taking that
+        // one down would hide something the user has not read.
+        if (activeBanner === el) {
+          activeBanner = null;
+          activeBannerIsRefusal = false;
+          activeBannerIsSwallow = false;
+          activeBannerIsKeynavExit = false;
+        }
+      });
+  }
+
+  /**
+   * Settle a wave session that has just gone off screen.
+   *
+   * `reason` is wave-ui's, not inferred here: 'escape' means the user asked for
+   * the session to be thrown away, anything else means they kept it.
+   */
+  /**
+   * Give the keyboard back to the block the editor was opened over.
+   *
+   * v3.3.0's backlog had FOUR accessibility defects and this batch produced two
+   * more, all of them the same sentence: a gesture ended and left
+   * `document.activeElement` on `document.body`, where the user can see
+   * nothing, Tab is deliberately swallowed, and the next Backspace means
+   * whatever the last selection meant. The wave editor is the biggest surface
+   * in the product to close, so it is the worst place to end there.
+   *
+   * The mark it leaves is a single-block SELECTION and not a bare `.focus()`,
+   * because a bare focus is invisible: `.ed-block.ed-selected:focus` has
+   * `outline: none` and the TINT is this editor's affordance for「鍵盤在這裡」
+   * (see that rule's own comment in lib/md2doc.js). It also puts the user back
+   * exactly where the keyboard entry above starts from, so Enter re-opens the
+   * editor they just left.
+   *
+   * Scoped to `seam.reselect` — the sessions that took a keyboard which was
+   * standing somewhere visible. A hover-and-click session is not made worse by
+   * this and is not given a selection it never asked for.
+   */
+  function giveKeyboardBackToWaveBlock(seam) {
+    if (seam === null || seam === undefined || seam.reselect !== true) return;
+    // Resolved by id against the CURRENT map: the commit path has re-rendered
+    // and re-numbered by now, and settleWaveBlocks() has already moved the
+    // session's own line arithmetic into `blocks`. A block that is no longer
+    // there (a render that failed and left the map short) simply gets nothing —
+    // guessing at a neighbour is how a keyboard ends up selecting a block the
+    // user never pointed at.
+    const b = blocks.find((x) => x.id === seam.blockId);
+    if (!b || !blockElById(seam.blockId)) return;
+    setBlockSelection({ anchorLine: b.startLine, focusLine: b.startLine });
+  }
+
+  async function finishWaveSession(seam, reason) {
+    if (seam === null) return;
+    if (reason === 'escape') {
+      // Escape DISCARDS — the same word it means everywhere else in v3.3.0 —
+      // and here that has to reach the document stack, because the session has
+      // been committing all along.
+      const painted = bodyNow(seam);
+      const hadOps = seam.ops > 0;
+      if (!unwindWaveOps(seam)) {
+        // A Ctrl+S landed inside this session, so its commits cannot simply be
+        // popped — see unwindWaveOps() for the measured failure that produces.
+        // A revert COMMIT is the honest answer instead: the document goes back
+        // to where the session found it, and the stack only ever grows, so
+        // `dirtyDepth` stays strictly positive and can never walk back through
+        // zero over a document that differs from disk. The cost is a `●` the
+        // user clears with one Ctrl+S — which is TRUE, because disk is still
+        // holding the drawing they just discarded.
+        const result = commitRangeEdit({ lines, blocks, stack },
+          seam.startLine, seam.endLine, seam.baseSource);
+        if (result.op !== null) lines = result.lines;
+        blocks = seam.baseBlocks;
+        seam.endLine = seam.startLine + seam.baseSource.split('\n').length - 1;
+        // fix 2 (R1): the redo branch, on THIS path too. Both Escape branches
+        // end with `lines` byte-identical to `seam.baseLines` — only the seam
+        // range is ever written during a session — so the pre-session redo ops
+        // still address the document they were recorded against, and a user who
+        // lands here is otherwise in exactly F3's position: a byte-identical
+        // document with their redo silently eaten. AFTER the commit, because
+        // `push()` is what cleared it.
+        stack.setRedoTail(seam.baseRedoTail);
+      }
+      if (hadOps && painted !== seam.baseSource) {
+        // …and the discard is recoverable by exactly one Ctrl+Z. See
+        // discardedWaveEdit's own comment for which of discardedBurst's rules
+        // this reuses and which of them cannot apply here.
+        dropDiscardedBurst();
+        dropDiscardedRawEdit();
+        discardedWaveEdit = {
+          blockId: seam.blockId,
+          blockStartLine: seam.blockStartLine, blockEndLine: seam.blockEndLine,
+          startLine: seam.startLine, endLine: seam.endLine,
+          source: seam.baseSource, painted: painted,
+        };
+      }
+      // Work the file could not hold goes with the session it belonged to.
+      // The banner that said so is deliberately NOT dismissed here: it is the
+      // only record the user has that something did not survive.
+      waveUnwrittenEdit = false;
+      setDirty();
+      // No render. `.content` was never repainted while the overlay was up, so
+      // it is still showing exactly the base document just restored — rendering
+      // would be a round trip to say nothing.
+      return;
+    }
+    if (seam.unwritten) {
+      // Kept, with a hole in it. The user is told once more on the way out,
+      // because the status line they were reading has just been removed from
+      // the screen along with the rest of the dialog.
+      showBanner(
+        '這次波形編輯有一個改動沒辦法寫回檔案，它沒有留下來 —— 檔案裡是其餘' +
+        '寫得回去的部分（這個區塊的內容在第 ' + seam.startLine + '–' +
+        seam.endLine + ' 行）。',
+        null, null);
+      waveUnwrittenEdit = false;
+      setDirty();
+    }
+    if (seam.ops === 0) return;
+    // fix 1 (F2): `blocks` is settled from the session's own arithmetic BEFORE
+    // the render, not instead of it. A successful render overwrites it with the
+    // server's own map a moment later; a FAILED one — which this path
+    // deliberately does not roll back — leaves this value standing instead of a
+    // map addressing a document that no longer exists. It also closes the
+    // window in which the overlay is reopened while the settling render is
+    // still in flight, which reads `blocks` through waveBodyOf().
+    settleWaveBlocks(seam);
+    // The one render this session pays for. `.content` has been lagging
+    // `lines` since the first gesture; this is where it catches up.
+    // fix 1 (F7): the delta is the session's real line-count change, not 0.
+    // Advisory today (patchmap() reads only its truthiness), wrong regardless.
+    const editRange = { startLine: seam.startLine, endLine: seam.endLine,
+                        delta: lines.length - seam.baseLines.length };
+    const ok = await safeRerenderAll(editRange);
+    if (!ok) {
+      // Deliberately NOT rollbackFailedRender(). Every other commit in this
+      // file rolls back a failed render because the edit it is undoing is one
+      // keystroke; this one can be ten minutes of drawing, and rerenderAll()'s
+      // failure is a round trip to /api/render, not a refusal of the edit. The
+      // work stays in `lines` — dirty, saveable with Ctrl+S, and recoverable by
+      // an ordinary Ctrl+Z — and the banner is corrected, because
+      // rerenderAll()'s own 'Your edit was not applied' would be false here.
+      //
+      // What makes that safe is settleWaveBlocks() above: keeping the work is
+      // only defensible while `blocks` still addresses the document that holds
+      // it. Losing a session is bad; silently corrupting the document the user
+      // keeps editing afterwards is worse, and before fix 1 this path risked
+      // both at once.
+      showBanner(
+        '畫面沒有重畫成功，但你畫的波形還在文件裡（按 Ctrl+S 可以存檔，' +
+        'Ctrl+Z 可以撤銷）。', null, null);
+    }
+  }
+
+  /**
+   * Ctrl+Z straight after an Escape out of the wave editor: put the discarded
+   * drawing back and re-open the editor over it.
+   *
+   * The restore is an ordinary commit, not a special case — so the reopened
+   * session opens over a document that already holds the drawing, one more
+   * Ctrl+Z steps back over the restore itself, and Ctrl+S saves it. That is
+   * the difference from restoreDiscardedRawEdit(), whose stashed value lives
+   * in a textarea until a later blur commits it: there is no "uncommitted
+   * surface" shape available here, because the wave editor's surface IS the
+   * document.
+   *
+   * Staleness is asked at the `lines`/`blocks` level, the same level
+   * restoreDiscardedRawEdit() asks at and for the same reason — the overlay
+   * was removed from the DOM by `close()`, so there is no node whose presence
+   * could answer it.
+   */
+  async function restoreDiscardedWaveEdit() {
+    const d = discardedWaveEdit;
+    discardedWaveEdit = null;
+    if (!d) return false;
+    const b = blocks.find((x) => x.id === d.blockId);
+    if (!b || b.startLine !== d.blockStartLine || b.endLine !== d.blockEndLine) return false;
+    if (lines.slice(d.startLine - 1, d.endLine).join('\n') !== d.source) return false;
+    const prevLines = lines;
+    const result = commitRangeEdit({ lines, blocks, stack },
+      d.startLine, d.endLine, d.painted);
+    if (result.op === null) return false;
+    lines = result.lines;
+    // `blocks` deliberately not reassigned — the same shape every other
+    // commit-then-render site in this file has: the render that follows is what
+    // replaces it, and rollbackFailedRender() below restores `lines` only, so
+    // an assignment here would survive a failed render as the one value nothing
+    // puts back.
+    setDirty();
+    const ok = await safeRerenderAll({
+      startLine: d.startLine,
+      endLine: d.startLine + d.painted.split('\n').length - 1,
+      delta: result.op.after.length - result.op.before.length,
+    });
+    if (!ok) {
+      lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      setDirty();
+      return false;
+    }
+    // Re-open over the block the render just rebuilt. `openWaveEditor()` wants
+    // something INSIDE the block and resolves the block with `closest()`, and
+    // `closest()` matches the element itself — so the block element is a valid
+    // argument and does not depend on WaveDrom having finished painting a
+    // `.wavedrom-diagram` into it yet.
+    const blockEl = blockElById(d.blockId);
+    if (!blockEl) return true; // the drawing is back in the document either way
+    await openWaveEditor(blockEl);
+    return true;
+  }
+
+  // Test-only seam, the same shape and for the same reason as
+  // `__edTestGetSelection` above: the two invariants this feature has that a
+  // scenario cannot otherwise see — whether the overlay is open, and whether
+  // anything ever reached the seam after it closed. Nothing in the product
+  // calls it.
+  window.__edTestWaveState = function () {
+    return {
+      open: waveEditor !== null,
+      stray: waveStrayGestures,
+      // Task 7's three: whether the document currently believes it has
+      // anything unsaved (the thing the Reload button's beforeunload guard
+      // asks), whether this session has work the file could not hold, and
+      // whether a discarded session is sitting there waiting for a Ctrl+Z.
+      dirty: documentIsDirty(),
+      unwritten: waveUnwrittenEdit,
+      stashed: discardedWaveEdit !== null,
+      seam: waveSeam === null ? null : {
+        blockId: waveSeam.blockId,
+        startLine: waveSeam.startLine,
+        endLine: waveSeam.endLine,
+        gestured: waveSeam.lastGesture !== null,
+        ops: waveSeam.ops,
+      },
+    };
+  };
+
+  // fix 1 (F2): whether the block map still addresses the document. A failed
+  // close render used to leave the two disagreeing by the session's line delta,
+  // and the only way a scenario could see it was to make an ordinary edit
+  // afterwards and read the corrupted file — a real assertion, but one that
+  // cannot say WHICH of the two moved. Nothing in the product calls this.
+  window.__edTestBlockSpan = function (id) {
+    const b = blocks.find((x) => x.id === id);
+    return b === undefined ? null : {
+      startLine: b.startLine, endLine: b.endLine, docLines: lines.length,
+      text: lines.slice(b.startLine - 1, b.endLine).join('\n'),
+    };
+  };
+
+  waveEditBtn.addEventListener('click', () => {
+    if (waveDiagramEl === null) return;
+    // The only way this rejects is a programming error — the `.content` mount
+    // guard, which throws by design, or a store that threw where it promised
+    // not to. Reported rather than swallowed, and NOT rethrown: an unhandled
+    // rejection out of a click handler is a page-level error, and the state
+    // this needs to keep consistent (`waveEditor` / `waveSeam`) is already
+    // unwound above.
+    openWaveEditor(waveDiagramEl).catch((err) => {
+      console.error('md2doc: the wave editor could not open', err);
+    });
+  });
+
   // v3.1.0 §4: last, so every const it closes over (stack, BLOCK_SKELETONS,
   // selToolbar, …) is initialised and the bar's first deriveState() sees the
   // armed document rather than an empty one.