@helping-ai-workflow/md2doc 3.0.2 → 3.2.1

package/lib/editor/client.js

@@ -520,7 +520,18 @@
   const convertMd = window.md2docConvertMd;
   const selectionLib = window.md2docSelection;
   const historyLib = window.md2docHistory;
+  // v3.1.0 Task E: the four Phase-1 modules, injected by server.js ahead of
+  // this file. Read the same way every earlier module is — off `window`, not
+  // via require() (this script is a plain <script> tag in the page, not a
+  // bundle). Each is read defensively at its call sites: an older cached page
+  // that predates the injection must degrade to "the toolbar is absent",
+  // never to "the whole client runtime throws before it arms anything".
+  const toolbarModel = window.md2docToolbarModel;
+  const pasteMd = window.md2docPasteMd;
+  const assetLib = window.md2docAsset;
+  const docSourceLib = window.md2docDocSource;
   let lines = ED.lines, blocks = ED.blocks, mtimeMs = ED.mtimeMs;
+  let lastParts = null;
   // 檔案原本的換行符。lines 內部永遠是不含 \r 的純內容行；只有 save()
   // 會把它接回這個 EOL，render 一律用 \n（spec §3.11）。
   const EOL = ED.eol || '\n';
@@ -816,7 +827,7 @@
   // response — WITHOUT touching contentEl.innerHTML or `blocks`, and shows
   // a dismissible banner explaining what happened. Never throws: every
   // await is inside its own try/catch, so callers never see a rejection.
-  async function rerenderAll() {
+  async function rerenderAll(editRange) {
     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,
@@ -849,7 +860,7 @@
       showBanner('Render failed — malformed server response. Your edit was not applied.', null, null);
       return false;
     }
-    if (typeof j.bodyHtml !== 'string' || !Array.isArray(j.blocks)) {
+    if (!Array.isArray(j.parts) || !Array.isArray(j.blocks)) {
       showBanner('Render failed — malformed server response. Your edit was not applied.', null, null);
       return false;
     }
@@ -857,21 +868,667 @@
     // gesture asked for it has succeeded. Review recommendation 5 — a stale
     // structural refusal is cleared HERE and nowhere else.
     dismissRefusalBanner();
+    // Task E: rerenderAll() now takes `editRange` as its own parameter —
+    // every call site that has a real op computes it there (see the 18
+    // safeRerenderAll() call sites that pass one) and threads it down through
+    // safeRerenderAll() to here. Passed straight through to
+    // applyRenderResult() as the second positional argument; Task F is what
+    // actually reads it to decide patch-vs-fallback.
+    //
+    // Fix round 1: `scrollY` and `declaredRange` are captured ABOVE, before
+    // the extraction boundary (they must be read early — see their own
+    // comments — well before this point), so they are NOT part of the
+    // moved tail and are out of `applyFullRender`'s scope unless threaded
+    // through explicitly. Passed positionally here and through
+    // applyRenderResult() rather than folded into `j` (which is the
+    // server's response payload, not render-context the CALLER derived).
+    return applyRenderResult(j, editRange, scrollY, declaredRange);
+  }
+
+  // v3.2.0 Task F: patch-vs-fallback dispatch.
+  //
+  // `scrollY`/`declaredRange` are rerenderAll()'s own pre-fetch captures
+  // (see its comments) — applyFullRender() needs them for the same
+  // window.scrollTo()/rebuildBlockSelection() calls the tail always made,
+  // but as a sibling function it cannot reach rerenderAll()'s locals by
+  // closure, so they ride along here instead.
+  //
+  // `scrollY` is forwarded to applyFullRender() ONLY (controller ruling F3):
+  // the fallback needs it because `contentEl.innerHTML = ...` destroys and
+  // rebuilds every node, collapsing the scroll extent to zero for an instant;
+  // the patch path leaves the prefix and suffix nodes attached, so the scroll
+  // position never moves and re-applying a pre-fetch scrollY would fight the
+  // browser (the reader may legitimately be somewhere else by the time the
+  // response lands).
+  //
+  // `editRange` gates the patch attempt AS A BOOLEAN and in no other way: the
+  // 3 call sites with no committed op pass nothing and fall back by contract.
+  // 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.
+  // 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
+  // window between two renders, and every one of them breaks it:
+  //
+  //   :insertListItemAfter()   inserts a PROVISIONAL li (no data-block-id at
+  //                            all) as a sibling before its own commit renders
+  //   :splitListItemAtCaret()  same shape, on Enter inside a li
+  //   :duplicateListItem()     inserts cloneNode()d copies, which carry the
+  //                            ORIGINAL's data-block-id — duplicated ids
+  //   :moveListItem()          re-inserts existing li elements at a new
+  //                            position: the COUNT is unchanged and every id
+  //                            is still present, only the ORDER moved
+  //   :removeListItem()        REMOVES li elements outright (the Backspace-
+  //                            join and multi-item-delete paths), so the
+  //                            child count drops below lastParts.length
+  //                            before the render that would explain it
+  //
+  // MEASURED on the ＋→清單 gesture with a dirty burst open on the anchor
+  // (test/editor-client-runtime.test.js:3918): two commits land back to back,
+  // and at the second one `lastParts.length` is 3 while contentEl has 4
+  // children. patchmap computes a zero-width insertion at index 2, the removal
+  // loop removes nothing, and the fragment is inserted BEFORE the provisional
+  // node — which nobody then removes. Four li blocks where three belong. The
+  // fallback never had the problem: `innerHTML =` wipes whatever the gesture
+  // left behind.
+  //
+  // So the patch path checks, cheaply and positionally, that the DOM still
+  // reads exactly as the last render left it: same number of children, and
+  // child i still carrying block i's id. Any of the four mutations above fails
+  // one of those, and that render falls back — i.e. exactly the pre-v3.2.0
+  // behaviour for those gestures, which is why this cannot regress them.
+  //
+  // ⚠ What it does NOT check is whether a kept node's MARKUP still equals the
+  // part that produced it — a gesture that rewrites an attribute in place
+  // (data-indent, data-list-start) without changing the child list passes this
+  // guard. That is a different family (kept nodes carrying stale local state)
+  // and is tracked separately; do not grow this predicate into it without
+  // measuring the cost, because unlike this walk that one is not O(1) per node.
+  function domMatchesLastRender() {
+    if (!Array.isArray(lastParts) || !Array.isArray(blocks)) return false;
+    if (blocks.length !== lastParts.length) return false;
+    const kids = contentEl.children;
+    if (kids.length !== lastParts.length) return false;
+    for (let i = 0; i < kids.length; i++) {
+      // Compared against blocks[i].id rather than against `i`: the two are the
+      // same today (blockmap.js hands out a positional ordinal, which is what
+      // makes patchmap's idDelta rewrite work at all) but the JOIN KEY is the
+      // id, and stating it that way is what keeps this honest if that identity
+      // is ever relaxed.
+      if (kids[i].getAttribute('data-block-id') !== String(blocks[i].id)) return false;
+    }
+    return true;
+  }
+
+  async function applyRenderResult(j, editRange, scrollY, declaredRange) {
+    const plan = (editRange && window.md2docPatchmap && domMatchesLastRender())
+      ? window.md2docPatchmap.patchmap({
+          oldBlocks: blocks, newBlocks: j.blocks,
+          oldParts: lastParts, newParts: j.parts, editRange: editRange,
+        })
+      : null;
+    if (plan) return applyPatch(j, plan, declaredRange);
+    return applyFullRender(j, scrollY, declaredRange);
+  }
+
+  // Incremental DOM patch: replace ONLY the middle span patchmap identified,
+  // leaving every prefix and suffix node attached. Keeping those nodes in
+  // place is the whole point — it is what preserves document.activeElement,
+  // the caret offset, already-rendered mermaid/WaveDrom SVGs and the scroll
+  // position across a commit.
+  //
+  // `declaredRange` arrives as a PARAMETER and is never re-read from
+  // `pendingSelectionRange` here (controller ruling F2): rerenderAll() already
+  // consumed that module-level slot before it even issued the fetch (see its
+  // own comment for why it must be consumed that early), so re-reading it here
+  // would always yield undefined and silently drop selection restoration on
+  // every patched commit.
+  async function applyPatch(j, plan, declaredRange) {
+    // 步驟 4 的五步。順序是 spec 決議 2(c) 定死的：
+    //   1) 消費 pendingSelectionRange（已由 rerenderAll() 在 fetch 之前做掉，
+    //      值以 declaredRange 參數傳進來——ruling F2）
+    //   2) 組 <template> 並 armEditables(t.content) —— 唯一可以吃容器的一件事
+    //   3) 移除 replaceSpan 節點、insertBefore 插入
+    //   4) 重寫被保留後綴節點的 data-block-id
+    //   5) rebuildBlockSelection(declaredRange) → __md2docInitDiagrams(contentEl)
+    //      → __md2docRebindReader() → applySelectionClasses()
+    //
+    // Step 5's internal order matches applyFullRender()'s, deliberately:
+    // rebuildBlockSelection() sits BEFORE the two `try`-swallowed rebind
+    // blocks so a diagram-init throw can never skip it (applyFullRender()'s
+    // own comment says exactly that). The brief's snippet listed the rebinds
+    // first; its prose says to preserve the existing relative order, and the
+    // prose is what is right — a selection silently lost on the render that
+    // introduced the document's first mermaid fence is the failure it names.
+    //
+    // The snapshot is taken BEFORE any mutation: every index below
+    // (`oldStart`..`oldEnd`, and the `oldEnd + 1` reference node) is an index
+    // into the PRE-patch child list, which is what patchmap computed against.
+    // contentEl's element children are the `.ed-block` parts, 1:1 and in
+    // document order: lib/md2doc.js emits each part as a single
+    // `<div class="ed-block" …>…</div>` (the only two emit sites) and the
+    // client only ever assigns `parts.join('\n')` into contentEl. The chrome
+    // is never a direct child — the ⠿ handle, the ＋ button, the gutter menu
+    // and the insert menu all go on a BLOCK, and the source-mode textarea is
+    // inserted as contentEl's SIBLING.
+    //
+    // Fix round 2: that is NOT unconditionally true between renders — four
+    // list gestures mutate this child list directly. domMatchesLastRender()
+    // (see its comment, above applyRenderResult) is what establishes the
+    // property before we are called; it is a PRECONDITION of everything
+    // below, not something this function re-derives.
+    const children = Array.prototype.slice.call(contentEl.children);
+    // v3.2.1: 「被改寫區塊內的游標」焦點修復。動機來自 undo/redo 的量測——
+    // undo/redo 並非普遍掉焦點：游標在被改寫區間【之外】時 activeElement /
+    // 所屬 block / caret offset 全部存活（連一次讓自己 data-block-id 8→7 的
+    // 結構性 undo 都扛得住）；只有游標落在被改寫區塊【內】才掉到 BODY，之後
+    // 打字被靜默丟棄。所以判準是位置，不是操作種類，也完全不需要 op→block
+    // 映射（實測 op.startLine 在 14 個實例中只有 4 個正確，對 move / insert
+    // 都指向沒有擁有者的空行——該設計已退掉）。
+    //
+    // ⚠ 觸發面不是「只有 undo/redo」：任何一次 patch 只要聚焦的 block 落在
+    // replaceSpan 內就會走到，fix round 1 的 review 點名了兩類非 undo 的呼叫者——
+    //   * 一般的 burst 提交：endBurstWithoutResolve() 不 blur，焦點還留在那個
+    //     即將被換掉的面上；
+    //   * 帶 declaredRange 的批次結構操作：焦點坐在 `.ed-block` 外框上（roving
+    //     tabindex）。
+    // 這兩類上還原完之後常常會被下面 applySelectionClasses() 自己的
+    // `focusEl.focus()` 立刻覆蓋掉（它把焦點搬回選取的 focus block），也就是多
+    // 一趟 focus 往返而已；journey 案例 3 / 4 / 6 走的正是這些路徑，皆綠。
+    //
+    // 必須在 DOM 手術之前算：removeChild 之後 activeElement 已經是 BODY，
+    // 而 `children` 是 patch 前的快照，也是 plan 的索引所指的那份清單。
+    const focusedBlockEl = document.activeElement &&
+      document.activeElement.closest ? document.activeElement.closest('.ed-block') : null;
+    const ci = focusedBlockEl ? children.indexOf(focusedBlockEl) : -1;
+    const focusWasInSpan = ci >= 0 &&
+      ci >= plan.replaceSpan.oldStart && ci <= plan.replaceSpan.oldEnd;
+    // 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
+    // below), so the order is forced. That opens a window in which a throw
+    // would leave the model describing a DOM that was never built: the
+    // exception bubbles to safeRerenderAll()'s catch, the user is told "Your
+    // edit was not applied", `false` comes back — and the NEXT commit then
+    // diffs parts describing blocks that do not exist, so every index is
+    // wrong and nothing reports it. Same silent-failure shape as ruling F4.
+    //
+    // applyFullRender() has no such window: its `blocks`/`lastParts` →
+    // innerHTML → armEditables() order means the same throw leaves a
+    // consistent "DOM swapped, just not armed" state that the next render
+    // heals. So the patch path buys the equivalent guarantee explicitly:
+    // capture, and put the whole mutation window in a try that rolls the two
+    // back and lets the FALLBACK land the commit instead of losing it.
+    const prevBlocks = blocks;
+    const prevLastParts = lastParts;
     blocks = j.blocks;
-    contentEl.innerHTML = j.bodyHtml;
-    // Task 2 (Phase 3): re-arm every WYSIWYG-eligible paragraph/heading (and
-    // attach a ⠿ handle to every non-table block) in the freshly-swapped
-    // DOM — see armEditables() below. Must run before anything else touches
-    // the fresh nodes (diagram re-init, reader rebind, focus restoration).
-    armEditables(contentEl);
+    lastParts = j.parts;
+
+    try {
+      // <template> 是刻意指名的，不是「隨便一種容器」：
+      //   createDocumentFragment() + innerHTML  -> innerHTML 不存在，什麼都插不進去、不報錯
+      //   Range.createContextualFragment()      -> 文件裡作者手寫的 raw <script> 每次 patch 重新執行
+      // 暫存 <div> 也正確，只多一圈 child drain。
+      const tpl = document.createElement('template');
+      tpl.innerHTML = plan.replaceSpan.newParts.join('\n');
+      // 必須在 blocks 已換成新陣列之後——armEditables 的 li 分支走
+      // canWysiwygForLi → blockOwnsNoLine，那支讀的是模組層的 `blocks`；
+      // 用舊陣列判斷會把一個「不擁有任何來源行」的 li 誤武裝成 contenteditable。
+      //
+      // ⚠ 只對新片段呼叫，永遠不要對被保留的前綴／後綴節點再跑一次：
+      // armEditables 不是 idempotent（⠿ handle 與 ＋ button 是無條件
+      // appendChild），double-arm 實測會變成 10 個 handle 而不是 5 個。
+      armEditables(tpl.content);
+
+      // 保留節點永不 detach：只移除中段，其餘原地不動。
+      // 不得用 replaceChildren() 或 remove-and-re-append 重建整份子節點列表——
+      // 實測 detach 再插回同一位置會讓 document.activeElement 掉回 BODY。
+      //
+      // Fix round 1 (review, comment-only): this removes ELEMENTS, so the `\n`
+      // TEXT nodes `parts.join('\n')` left between the removed blocks stay
+      // behind. Harmless today — `contentEl.children` and allBlockEls()'s
+      // querySelectorAll both skip text nodes, and nothing in this file reads
+      // `contentEl.childNodes` — but it does mean `.content`'s child-NODE shape
+      // after a patch differs from its shape after a full render, which would
+      // matter to any future test that asserts on childNodes rather than
+      // children.
+      for (let i = plan.replaceSpan.oldStart; i <= plan.replaceSpan.oldEnd; i++) {
+        if (children[i]) contentEl.removeChild(children[i]);
+      }
+      // 參考節點是「第一個被保留的後綴節點」。它在 children 快照裡的 index 是
+      // oldEnd + 1，而且因為後綴從未被 detach，那個 object 現在仍在 DOM 裡。
+      // 後綴為空時是 null，insertBefore(frag, null) 等同 append。
+      const refNode = children[plan.replaceSpan.oldEnd + 1] || null;
+      contentEl.insertBefore(tpl.content, refNode);   // fragment 會被排空並保序
+
+      // 被保留的後綴節點的 data-block-id 已經過期（id 是位置序號）。
+      // 前綴恆為 0：id 即索引，前綴在兩份陣列裡都佔 0..k-1。
+      if (plan.idDelta !== 0) {
+        const all = contentEl.children;
+        for (let i = all.length - plan.keepSuffix; i < all.length; i++) {
+          const el = all[i];
+          const oldId = Number(el.getAttribute('data-block-id'));
+          el.setAttribute('data-block-id', String(oldId + plan.idDelta));
+        }
+      }
+    } catch (e) {
+      // Roll the model back to what the (still-unmutated, or only partly
+      // mutated) DOM last agreed with, then land the commit through the
+      // fallback rather than losing it — applyFullRender() rebuilds .content
+      // wholesale, so it is correct from a half-patched DOM too.
+      //
+      // ⚠ `window.scrollY` here does NOT violate ruling F3. F3 forbids
+      // re-applying rerenderAll()'s STALE pre-fetch snapshot on the patch
+      // path, because the patch path never collapses the scroll extent. This
+      // is the CURRENT scroll position, read at this instant, handed to an
+      // innerHTML swap that genuinely does collapse it. Different value,
+      // different reason. Do not "correct" it to the `scrollY` parameter —
+      // applyPatch() deliberately does not take one.
+      blocks = prevBlocks;
+      lastParts = prevLastParts;
+      return applyFullRender(j, window.scrollY, declaredRange);
+    }
+
+    if (focusWasInSpan) {
+      // 落在被置換區間內的游標，其節點已經被移除。把焦點放到對應的新節點
+      // （夾在新中段的範圍內），caret 置尾。
+      //
+      // 位置刻意在 teardown 之前，而真正的機制是 fix round 1 的 review 查出來
+      // 的這一條（第一版註解寫的「靠收尾那段焦點檢查認養」是錯的，那段在這條
+      // 路徑上是死碼）：`surface.focus()` 會【同步】觸發 document 層那個委派的
+      // focusin。undo() 早已 await 完 switchAwayFrom()，所以 `switching` 與
+      // `currentBurst` 都是 null——focusin 的兩個 early-return 都不成立——而新
+      // 節點在 insertBefore 之前就被 armEditables(tpl.content) 武裝過了，於是
+      // startBurst() 當場就跑完。打字有人追蹤、Ctrl+S 才寫得進檔案（實測拿掉
+      // 這一塊時 undo 之後打的字連磁碟都到不了）。收尾最後那段
+      // `if (!currentBurst && …)` 的焦點檢查因此在這條路徑上恆為 false。
+      //
+      // 代價要說清楚：下面的 `burstSurvived` 是在這裡【之後】才求值的，所以在
+      // 走到這一塊的 render 上，它量到的是「剛剛由還原開出來的那個 burst」，
+      // 而不是它註解所寫的「patch 前就開著、而且面活過 patch」。受影響的是三個
+      // 以它為閘門的收尾項：currentBurst 的 dispose、resetSelToolbarState()、
+      // resetToolbarBlock()——三者都會改走 survived 分支。結果是好的（剛開的
+      // burst 不被丟掉、startBurst() 剛掛上的 selectionchange listener 不被拆、
+      // toolbarBlockEl 保住 focusin 剛設好的活節點），但那是巧合而不是設計，
+      // 所以在 `burstSurvived` 那裡也留了一行對照註解。不搬 `burstSurvived`
+      // 到還原之前，是刻意的取捨：搬了會讓剛開的 burst 先被 dispose 再由收尾
+      // 重開一次，並把每次 undo 的工具列 degrade 原封不動地留著。
+      // teardown 十二項彼此的相對順序沒有被動到，條件式的 activeEditor 歸零
+      // 仍然在 DOM 手術之後求值。
+      const newLen = plan.replaceSpan.newParts.length;
+      if (newLen > 0) {
+        // landing 恆落在新中段內：ci >= oldStart 保證非負，min() 夾住上界，
+        // 而 patch 後的子節點是 prefix(keepPrefix) + 新中段(newLen) + suffix。
+        // 零寬區間（insert，oldEnd === oldStart - 1）根本進不了 focusWasInSpan。
+        const landing = plan.keepPrefix + Math.min(ci - plan.replaceSpan.oldStart, newLen - 1);
+        const el = contentEl.children[landing];
+        const surface = el ? blockContentEl(el) : null;
+        if (surface) {
+          surface.focus();
+          try {
+            const r = document.createRange();
+            r.selectNodeContents(surface);
+            r.collapse(false);
+            const s = window.getSelection();
+            s.removeAllRanges(); s.addRange(r);
+          } catch (e) { /* best-effort，同 focusBlockAtLine 的處置 */ }
+        }
+      }
+    }
+
+    // ── teardown ────────────────────────────────────────────────────────
+    // Controller ruling F1: the patch path runs the SAME twelve teardown items
+    // applyFullRender() runs, unconditionally and in the same relative order.
+    // The rationale comments below are copied from applyFullRender() because
+    // they document WHY each one exists; the one thing that differs is the
+    // trigger — there the nodes were detached by the innerHTML replacement,
+    // here they were detached by the removeChild loop above (or, for state
+    // that points at a node in the KEPT span, they were not detached at all,
+    // which is exactly why leaving the state standing is not automatically
+    // safe either: `blocks` and every data-block-id under it just changed).
+    //
+    // Fix round 1 (review, comment-only) — the consequence a future change to
+    // this list has to know about: the fallback's innerHTML replacement also
+    // WIPES any uncommitted burst text, which is what keeps the DOM and
+    // `lines[]` consistent when item 3 disposes the burst. The patch path
+    // leaves that text sitting in a kept node while `currentBurst` has already
+    // been disposed. Unreachable today — every call site goes through
+    // switchAwayFrom() first, which is what applyFullRender()'s own comment
+    // calls "technically unreachable" — but that is precisely what this
+    // belt-and-braces teardown is insurance against, and on THIS path a future
+    // call site that forgets switchAwayFrom() leaves text visible in the DOM,
+    // absent from `lines[]`, with its undo history already disposed.
+    //
+    // Whatever editor (if any) was open a moment ago may have just been
+    // detached by the span removal above — its own restore()/commit() never
+    // ran, so it never got a chance to null this out itself. On the FALLBACK
+    // path this is done unconditionally, which is what makes the undo/redo
+    // lockout regression (see the `activeEditor` comment above) structurally
+    // impossible even from a call site that forgets to call switchAwayFrom().
+    //
+    // ── Final review item 1 / 決議 3(1) 的 activeEditor 對稱項 ───────────
+    // 決議 3(1) 的論證逐字適用在這裡，而它原本沒有被問過：fallback 之所以
+    // 可以無條件歸零，是因為 `contentEl.innerHTML = ` 把每個節點都拔掉了
+    // ——面也一起從螢幕上消失。patch 保留節點，而 openRawEditor() 的
+    // `.ed-raw` 包裝是塞進**區塊自己**（`blockEl.innerHTML = '';
+    // blockEl.appendChild(wrap)`），所以 contentEl 的子節點數與每一個
+    // data-block-id 都沒有變、domMatchesLastRender() 照過、patch 照跑——
+    // 落在前綴／後綴裡的 textarea 於是活過 patch，而這一行把它變成沒人
+    // 追蹤的殭屍：switchAwayFrom() 再也看不到它，點開別處不會自動提交，
+    // 而下一次任何 rerenderAll() 會把它連同未提交的文字一起蓋掉。
+    //
+    // 實測可達（scratchpad/item1-scenarioB.js，兩次 run 一致）。序列是
+    // 「render 往返途中開一個 raw editor」，與決議 3(2) 為 currentBurst 記下
+    // 的那條 race 同形，只是觸發點必須是**在 fetch 之前就 settle 掉
+    // switchAwayFrom() 的**站點（undo()/redo()/changeHeadingDepth()…），
+    // 因為 resolveBurst() 自己那條路徑把整個 render 關在 `switching` 的
+    // single-flight 裡，反而把並行的點擊序列化掉：
+    //   openRawEditor-entry   {blockId:'2', currentBurst:false, activeEditor:false}
+    //   dispatch              {patch:true, keepPrefix:4, oldStart:4, oldEnd:4,
+    //                          activeEditor:true, rawTextareas:1}
+    //   patch-teardown        {activeEditor:true, activeEditorBlockAttached:true,
+    //                          activeEditorBlockId:'2', rawTextareas:1}
+    // 接著在存活的 textarea 裡打字、點到別的區塊、Ctrl+S：
+    //   [after clicking away] {rawTextareas:1, rawValue:'…const LOST = 2;'}
+    //   [file on disk]        '# Doc\n\nCode anchor.\n\n```js\nconst x = 1;\n```\n…'
+    //   [LOST typing present in file?] NO — data loss
+    // 螢幕上看得到，檔案裡沒有——與決議 3(1) 為 burst 記下的完全同一種缺陷。
+    //
+    // 判準與 burst 那項同形，而且必須同形：實測
+    // `document.body.contains(activeEditor.blockEl)`，不得由 patchmap 的
+    // index 算術推論。推論錯的代價是 activeEditor 指著已 detach 的節點，
+    // 正好是上面那段「undo/redo lockout」在防的事——所以節點沒活下來時
+    // 一律走原本的無條件歸零，lockout 仍然結構上不可能。
+    //
+    // 多一道 burst 不需要的閘門：burst 的 `blockId` 是唯一會 stale 的欄位，
+    // 其餘都從新的 `blocks` 現查；openRawEditor() 的 session 則把
+    // `blockId`/`startLine`/`endLine` 三個都閉包成常數，所以留下來之前要先
+    // 讓它把三者從現在的 DOM 屬性與新的 `blocks` 重新推導成功
+    // （reanchor()，見那裡的註解——推導不出來就退回歸零）。
+    if (!(activeEditor && activeEditor.blockEl
+        && document.body.contains(activeEditor.blockEl)
+        && activeEditor.reanchor())) {
+      activeEditor = null;
+    }
+    // §10-gap fix (review): same belt-and-braces reasoning for
+    // `pristineInsert` — its window is meant to close via one of the
+    // explicit resolution hooks (resolveBurst()/revertBurstAndEnd()/
+    // revertTableBurstAndEnd()/cancelAndMaybeDiscard()) BEFORE any
+    // rerenderAll() reaches here.
+    //
+    // Final review item 1, second half — 這一項**刻意沒有**跟著上面開例外，
+    // 而且理由不是「到不了」：同一條 race 一樣到得了這裡。是這個狀態被
+    // 這次 render 本身作廢了。`pristineInsert` 的整個意思是「undo stack 的
+    // **最頂端**那一筆就是我這個插入 op」——discardPristineInsert() 走
+    // `stack.discardTop()`（lib/editor/lineops.js），它無條件 pop 最頂端那筆
+    // 並就地反轉，不驗證那筆是不是自己的。而任何走到 applyPatch 的 render
+    // 都帶著一個 truthy 的 editRange，也就是**剛剛有一筆 op 被推上 stack**
+    // （commitRangeEdit / commitBlockInsertion / undo()/redo() 的搬動）。所以
+    // patch 之後把 `pristineInsert` 留著，等於讓之後任何一次「放棄這個空
+    // 區塊」去 pop 並反轉**別人的**那一筆——那是比它要防的孤兒佔位區塊更
+    // 嚴重的失敗。要讓這一項變成可以開例外，得先讓 discardTop() 認得 op
+    // 的 identity（例如 discardPristineInsert() 記下 op 物件本身、pop 前先
+    // 比對），在那之前無條件歸零就是正解。
+    pristineInsert = null;
+    // ── Task G / 決議 3：teardown 的三項例外 ─────────────────────────
+    // 判準必須是「burst 的編輯面在 patch 之後仍然連在文件上」的**節點
+    // identity 實測**，不得由 index 算術推論。推論錯的代價是 burst 指著已
+    // detach 的節點——正是上面 activeEditor / toolbarBlockEl 那兩段註解在防的
+    // 事，而且跳過 dispose() 時若節點其實已被換掉，會同時留下一疊
+    // innerHTML 快照與一個閉包住 detached 節點的 captureFn。
+    //
+    // 為什麼只在 patch 路徑需要這個例外：fallback 的 `contentEl.innerHTML = `
+    // 把每一個節點都拔掉，所以 12 項 teardown 把任何編輯面孤兒化都是安全的
+    // （螢幕上也一併消失）。patch 保留前綴與後綴節點，所以同一套 teardown
+    // 會把一個螢幕上還在、焦點還在的面變成沒人追蹤的殭屍。
+    //
+    // 三項例外各自留在原位 gate，不抄成一個 if 區塊：ruling F1 要求這 12 項
+    // 的**相對順序**與 applyFullRender() 一致，把 resetSelToolbarState() /
+    // resetToolbarBlock() 搬到第 3 項旁邊才是真的改了順序。條件只算一次，
+    // 而且算在會動到 currentBurst 的那一項之前（算完才輪得到把它歸零）。
+    // ⚠ v3.2.1 fix round 1：這個節點 identity 判準本身沒變，但它求值的時機
+    // 現在落在上面那塊焦點還原【之後】。還原的 `surface.focus()` 在
+    // switchAwayFrom() 已經結算完的路徑上（undo()/redo()）會【同步】開出一個新
+    // 的 burst（見那裡的註解），所以在那種 render 上這裡量到的 true 說的是
+    // 「現在有一個 burst，而且它的面在文件上」，不是「patch 前那個 burst 活下
+    // 來了」。下面三個以它為閘門的項因此會走 survived 分支。實測（undo 走
+    // patch 路徑）：收尾後工具列 disabled 停在 7/22，不是 resetToolbarBlock()
+    // 跑過該有的 18/22 —— 也就是 resetToolbarBlock() 確實被跳過了，這是
+    // burstSurvived 為 true 的直接證據。反過來，若還原當下 currentBurst 還沒被
+    // 歸零（別條路徑），focusin 的 `if (currentBurst) return;` 會擋掉開 burst，
+    // 這裡照舊量到「舊 burst 的面被拔掉了」＝false，收尾最後那段焦點檢查才是
+    // 接手的人。兩種情形都不需要這一項改判準。
+    const burstSurvived = !!(currentBurst && currentBurst.editEl
+      && document.body.contains(currentBurst.editEl));
+    // Task 2 (Phase 3): same belt-and-braces reasoning for the always-on
+    // WYSIWYG burst — nulling here, not in resolveBurst(), is what keeps this
+    // a single source of truth, mirroring activeEditor just above.
+    // Task G: skipped when the burst's surface survived the patch — nulling it
+    // there is what strands a live, focused, still-typeable surface with
+    // nothing tracking it (the `input`/`focusout` handlers are both predicated
+    // on `currentBurst.editEl === editEl`, and `focusin` only fires on
+    // ENTERING, so focus that never left never reopens one).
+    if (!burstSurvived && currentBurst) { currentBurst.history.dispose(); currentBurst = null; }
+    // Task 5: the hover-edge insert bubbles and the row/column grip handles
+    // are positioned against a specific table's geometry; a stale bubble left
+    // visible (pointing at now-detached or re-rendered geometry) would
+    // misbehave on the next click. hideTableGrips() clears their tracked
+    // table/row/column references too.
+    hideTableInsertBubbles();
+    hideTableGrips();
+    // Task 4 fix (review finding): the SAME reasoning applies to the
+    // selection toolbar and its document-level selectionchange listener.
+    // Every call site today resolves the session via switchAwayFrom() first
+    // (making this technically unreachable), but that safety depends on every
+    // FUTURE call site remembering to — exactly how the Task 3 listener-leak
+    // regression happened. resetSelToolbarState() is idempotent.
+    // Task G: travels with the `currentBurst` exception above, and must. The
+    // `selectionchange` listener it removes is attached by startBurst() /
+    // startTableBurst() and by NOTHING else, so on a surviving burst whose
+    // focus never leaves there is no later focusin to re-attach it — measured,
+    // the floating selection toolbar and the fixed bar's five inline-format
+    // buttons (which piggyback on that same listener, and which this version's
+    // `hasSelection` wiring also rides) stay dead until the user clicks away
+    // and back.
+    if (!burstSurvived) resetSelToolbarState();
+    // Task 6: same belt-and-braces reasoning again for the edge-click menu
+    // and any in-flight row drag.
+    hideTableEdgeMenu();
+    cancelTeDrag();
+    // S4 Task 2: same belt-and-braces reasoning for an in-flight ⠿ block drag —
+    // the gesture's ordinal refers to a block index that this patch may have
+    // just renumbered. Nothing was mutated by the drag, so there is nothing to
+    // revert; the state simply must not survive the render.
+    cancelBlockDrag();
+    // Final-review Finding 5b (Important): the ⠿ gutter menu — toggleGutterMenu()
+    // appends the ONE shared `gutterMenu` node as a CHILD of whichever block
+    // it's open for, so a removed block took it away without its own close
+    // path ever running. Left uncleared, `gutterMenuBlockEl` keeps pointing at
+    // a detached node and the NEXT toggleGutterMenu() call on that same stale
+    // reference would treat the menu as already open instead of opening fresh.
+    // closeGutterMenu() is idempotent.
+    closeGutterMenu();
+    // §10-gap fix: same belt-and-braces reasoning for the ＋ insert menu —
+    // it's the same "singleton node appended as a child of whichever block
+    // it's open for" idiom as gutterMenu just above.
+    closeInsertMenu();
+    // v3.1.0 §4: and the SAME belt-and-braces reasoning one more time for the
+    // toolbar's tracked block. `toolbarBlockEl` points INTO the subtree that
+    // was just patched, and a detached node's getAttribute() still answers
+    // perfectly happily: left standing, the bar would keep reporting the old
+    // block's type/indent/heading depth and every button would act on a node
+    // no click can ever reach again.
+    // Task G: same exception, same reason — `toolbarBlockEl` is only ever
+    // re-set on focusin / the click delegation, so clearing it under a burst
+    // whose focus never leaves kills every block-dependent toolbar button until
+    // the user clicks away and back (MEASURED on the smoke fixture: disabled
+    // goes 7/22 -> 18/22, and nothing calls updateToolbar() again until the
+    // next click). It has TWO further side effects (v3.2.1: the third was
+    // preview mode's contenteditable re-arm, removed with the mode itself),
+    // and both ride along safely: (1) updateToolbar() is re-derived from the
+    // DOM on the next interaction; (2) closeToolbarMenu() — skipping it leaves
+    // the H▾ dropdown standing across a patch, which is benign because
+    // `toolbarMenuEl` is appended to document.body, not into a block, so the
+    // patch never detaches it, and applyHeadingLevel() re-resolves through
+    // liveToolbarBlock(), which self-heals a detached `toolbarBlockEl`.
+    if (!burstSurvived) resetToolbarBlock();
+
+    // Task G step 2: re-derive the surviving burst's `blockId` FROM THE DOM
+    // ATTRIBUTE — never assign it independently.
+    //
+    // startBurst()/startTableBurst() derive `blockId` from
+    // `blockEl.getAttribute('data-block-id')`, so on a kept node it is the
+    // FIELD that goes stale, not the attribute: the id rewrite inside the try
+    // above already renumbered every kept suffix node. bystanderCarryOver()
+    // compares `String(currentBurst.blockId)` against a node's getAttribute()
+    // result AS STRINGS; if the field and the attribute disagree in either
+    // direction a dirty burst stops being excluded from the replay and the
+    // replay overwrites the user's uncommitted typing. Hence the fixed order:
+    // the patch rewrites the attribute first, this re-derives the field from
+    // it. `blockEl` is `editEl.closest('.ed-block')` captured at burst-start
+    // and, because `burstSurvived` measured `editEl` as still attached, it is
+    // the same still-attached element.
+    if (burstSurvived) {
+      currentBurst.blockId = Number(currentBurst.blockEl.getAttribute('data-block-id'));
+    }
+
+    // S3 Task 5 (§4.4's ordered three steps): armEditables() above was step 1;
+    // this is steps 2 and 3 — rebuild the member set from the declared (or
+    // still-standing) LINE RANGE against the freshly built `blocks`. It sits
+    // AFTER the unconditional teardown above so nothing there can null what it
+    // just set, and BEFORE the two `try`-swallowed rebind blocks below so a
+    // diagram-init throw can never skip it.
+    //
+    // Fix round 1 (review, ruling F3 amendment): there are TWO scroll sources
+    // applyFullRender()'s `window.scrollTo(0, scrollY)` compensates, and only
+    // one of them is absent here. The one F3 correctly ruled out is the
+    // innerHTML swap collapsing the scroll extent — that cannot happen on this
+    // path, and re-applying the stale pre-fetch snapshot would fight the
+    // browser. The other is rebuildBlockSelection()'s own tail: it ends in
+    // `focusEl.focus()`, which scrolls the focus holder into view (the comment
+    // above applyFullRender()'s scrollTo says exactly this). That source is
+    // very much still live here, so a keyboard-driven patched commit taken
+    // while the block selection is scrolled off-screen would jump the viewport
+    // where the fallback would not.
+    //
+    // Compensated precisely: read the CURRENT scroll position immediately
+    // before, restore it immediately after, and only if the call actually
+    // moved it. Never the pre-fetch `scrollY` — applyPatch() deliberately does
+    // not take one.
+    const scrollBeforeSelection = window.scrollY;
+    rebuildBlockSelection(declaredRange);
+    if (window.scrollY !== scrollBeforeSelection) {
+      window.scrollTo(0, scrollBeforeSelection);
+    }
+    // 這三個都是 document-scoped，必須在插入之後、對整份文件跑：
+    // __md2docInitDiagrams 的 WaveDrom 分支自述「has no per-root scoping API
+    // — ProcessAll() always scans the whole document」，實測對 detached
+    // fragment 呼叫時 mermaid 畫得出來但 WaveDrom 完全沒動。
+    if (window.__md2docInitDiagrams) {
+      try {
+        window.__md2docInitDiagrams(contentEl);
+      } catch (e) {
+        // Same Phase-1 known limitation as the fallback path: a newly
+        // introduced diagram type whose library global was never loaded stays
+        // unrendered until reload. Never let that break the rest of the editor.
+      }
+    }
+    if (window.__md2docRebindReader) {
+      try {
+        window.__md2docRebindReader();
+      } catch (e) {
+        // Never let a reader-runtime rebind 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()/
+    // clearBlockSelection() — so on those renders this is a redundant SECOND
+    // pass, costing one extra blur/focus round trip. It is kept unconditional
+    // anyway, because the case where it is genuinely load-bearing is exactly
+    // the case where rebuildBlockSelection() early-returns: a plain typing
+    // commit with no selection anywhere, where nothing else would clear the
+    // KEPT nodes' stale `.ed-selected`/tabindex.
+    //
+    // applySelectionClasses() 必須跑：它是 total 的（先把 `.ed-selected` 與
+    // tabindex 從每一個區塊清掉再重套）。innerHTML 置換時代那份「保留節點的
+    // 殘留 class 自動消失」的免費午餐在 patch 路徑沒有了。
+    applySelectionClasses();
+
+    // ── Task G step 3 / 決議 3(1)：patch 收尾的焦點檢查 ────────────────
+    // endBurstWithoutResolve() 有 11 個呼叫點，全部在 render 之前，而
+    // ⠿／＋／工具列的 mousedown 都無條件 preventDefault()——刻意的，好讓
+    // 焦點留在 armed 面上（既有 runtime 測試斷言「⠿ 的 mousedown 不得 blur
+    // 還開著的 dirty burst」）。今天安全只因為 innerHTML 置換把那個節點
+    // 拔掉；patch 保留節點，就把「焦點還在、currentBurst 為 null」從邊角
+    // 變成日常。那個狀態下：打字不被追蹤（input listener 以
+    // currentBurst.editEl 為前提）、移開焦點什麼都不提交（focusout 同理）
+    // ——螢幕上看得到，檔案裡沒有。
+    //
+    // 位置是刻意的：在 teardown 之後（這時 currentBurst 才真的歸零了），
+    // 也在 rebuildBlockSelection() / applySelectionClasses() 之後——那兩支的
+    // focusEl.focus() 可能把焦點搬到一個 `.ed-block` 上（那是真的移走了，
+    // 不該重開 burst）。先開再讓它搬走只會多觸發一輪 focusout →
+    // resolveBurst()。又因為 resetSelToolbarState() 已經跑完（!burstSurvived
+    // 才會走到這裡），startBurst() 重新掛上的 selectionchange listener 不會被
+    // 回頭拆掉。
+    //
+    // ⚠ 這一步會改動 switchAwayFrom() 的後置條件。resolveOpenSession() 解掉
+    // currentBurst、await 完 render 之後就直接 return true，不再重檢；而工具列
+    // 與 ⠿／＋ 的 mousedown 都 preventDefault()，焦點會留在原面上。所以這裡可能
+    // 在那個被 await 的 render 裡重開一個 burst，讓 switchAwayFrom() 帶著一個
+    // 開著的 session 回傳 true——它自己的 doc comment 說它是「單一、完整的
+    // make it safe to proceed 閘門」。這是刻意的取捨：那個面上的鍵入沒人追蹤才是
+    // 資料遺失，而重開的 burst 是乾淨的（original 就是當下的 innerHTML），
+    // 下一次 focusout 會把它零編輯解掉。已知的一個後果是本輪修掉的那個：
+    // openRawEditor() 原本只擋 activeEditor，於是它註冊 activeEditor 之後的
+    // ta.focus() 會把這個 bystander burst 的 focusout 變成一次 switchAwayFrom()，
+    // 連帶把剛開的 raw editor 一起收掉——見那裡的 Task G fix round 1 註解。
+    // 任何新的「開一個 session 然後自己搬焦點」的路徑都要先解掉 burst。
+    //
+    // startBurst() 吃 editEl（`.ed-wys-armed` 本人）、startTableBurst() 吃 cellEl
+    // （`.ed-wys-cell` 本人，它自己 closest('table')）——兩者都正好是
+    // activeElement，所以直接傳。兩者都不呼叫 focus()，不搞 scrollIntoView，
+    // 所以這裡**不需要** rebuildBlockSelection() 那種 scroll 補償。
+    const ae = document.activeElement;
+    if (!currentBurst && ae && contentEl.contains(ae)) {
+      if (ae.classList.contains('ed-wys-cell')) startTableBurst(ae);
+      else if (ae.classList.contains('ed-wys-armed')) startBurst(ae);
+    }
+    // Same tail as applyFullRender(): the dirty dot and the `true` that tells
+    // every safeRerenderAll() caller the commit landed. Omitting either is the
+    // exact silent-failure shape ruling F4 warns about — safeRerenderAll()'s
+    // try/catch would swallow a throw and the DOM would still look right.
+    setDirty();
+    return true;
+  }
+
+  async function applyFullRender(j, scrollY, declaredRange) {
+    blocks = j.blocks;
+    lastParts = j.parts;                       // v3.2.0: 供下一次 patch 當 oldParts
+    // v3.2.1 R2: 必須先於 innerHTML 寫入。這個寫入 detach 掉聚焦的 raw
+    // textarea，同步 focusout 重入 switchAwayFrom() → resolveOpenSession() →
+    // commitNow()，於是同一次編輯提交兩次（實測衍生新 block 時磁碟上文字出現
+    // 兩次；停在同一個 block 內則第二次回 op === null 退化成取消，所以看不出來）。
     // Whatever editor (if any) was open a moment ago just got detached by
-    // the innerHTML replacement above — its own restore()/commit() never
+    // the innerHTML replacement below — its own restore()/commit() never
     // ran, so it never got a chance to null this out itself. Do it here,
     // unconditionally, on every successful swap: this is what makes the
     // undo/redo lockout regression (see the `activeEditor` comment above)
     // structurally impossible even from a call site that forgets to call
     // switchAwayFrom() first.
     activeEditor = null;
+    contentEl.innerHTML = j.parts.join('\n');  // fallback 路徑用 join 還原
+    // Task 2 (Phase 3): re-arm every WYSIWYG-eligible paragraph/heading (and
+    // attach a ⠿ handle to every non-table block) in the freshly-swapped
+    // DOM — see armEditables() below. Must run before anything else touches
+    // the fresh nodes (diagram re-init, reader rebind, focus restoration).
+    armEditables(contentEl);
     // §10-gap fix (review): same belt-and-braces reasoning for
     // `pristineInsert` — its window is meant to close via one of the
     // explicit resolution hooks (resolveBurst()/revertBurstAndEnd()/
@@ -943,6 +1600,19 @@
     // it's the same "singleton node appended as a child of whichever block
     // it's open for" idiom as gutterMenu just above.
     closeInsertMenu();
+    // v3.1.0 §4: and the SAME belt-and-braces reasoning one more time for the
+    // toolbar's tracked block. The toolbar node itself is mounted on
+    // document.body (see mountToolbar() below) precisely so the innerHTML
+    // replacement above cannot destroy it — but `toolbarBlockEl` points INTO
+    // the subtree that was just swapped, and a detached node's
+    // getAttribute() still answers perfectly happily: left standing, the bar
+    // would keep reporting the old block's type/indent/heading depth and
+    // every button would act on a node no click can ever reach again. Zeroing
+    // it re-derives the model's documented no-block state (undo/redo/outline/
+    // preview stay live, everything else greys out) — the same contract
+    // closeGutterMenu()/closeInsertMenu() above have, and idempotent for the
+    // same reason.
+    resetToolbarBlock();
     // S3 Task 5 (§4.4's ordered three steps): armEditables() above was step
     // 1; this is steps 2 and 3 — rebuild the member set from the declared (or
     // still-standing) LINE RANGE against the freshly built `blocks`, clear it
@@ -990,9 +1660,16 @@
   // Defensive wrapper around every rerenderAll() call site: guarantees the
   // caller never sees an unhandled rejection even if a future change to
   // rerenderAll() (or one of its callees) introduces a stray throw.
-  async function safeRerenderAll() {
+  //
+  // Task E: `editRange` passes straight through to rerenderAll(). Callers
+  // with a real committed op compute it there and pass it; the 3 no-op call
+  // sites (restore()'s rangeMode exit, the per-li unsupported-format
+  // refusal, and commitListStructure()'s no-range exit) pass nothing, which
+  // falls back to a full re-render by contract — patch can only compare
+  // renderer output, never DOM the user has already touched.
+  async function safeRerenderAll(editRange) {
     try {
-      return await rerenderAll();
+      return await rerenderAll(editRange);
     } catch (e) {
       showBanner('Render failed — unexpected error (' + describeFailure(e) +
         '). Your edit was not applied.', null, null);
@@ -1005,9 +1682,48 @@
     ta.style.height = (ta.scrollHeight + 2) + 'px';
   }
 
-  async function openRawEditor(blockEl) {
+  // v3.1.0 修正 4: `range` ({startLine, endLine}, 1-indexed inclusive) opens
+  // the raw editor over an EXPLICIT span of source lines instead of the
+  // block's own record. Two callers need it and one property makes both
+  // work: a list item (whose source line carries its marker and leading
+  // columns, and which must NOT go through the run re-serializer while a
+  // textarea is standing where its .ed-li-text should be) and a multi-block
+  // ⠿ selection (whose span is several blocks' lines at once). Both also
+  // switch this editor's teardown from an innerHTML rewrite to a real
+  // re-render — see restore() below for why that is not optional.
+  async function openRawEditor(blockEl, range) {
     if (blockEl.querySelector('.ed-raw')) return; // already editing this block
-    if (activeEditor && activeEditor.blockEl !== blockEl) {
+    // Task G fix round 1 (npm test RED on f63c88a): the guard below used to
+    // read `activeEditor` ALONE, so a WYSIWYG burst open on a DIFFERENT block
+    // survived into this function — and then `ta.focus()` (a few lines down,
+    // after `activeEditor` has already been registered) blurs that surface,
+    // whose delegated focusout calls switchAwayFrom(). resolveOpenSession()
+    // resolves BOTH kinds of session, so it resolves the burst AND then finds
+    // the brand-new, unmodified `activeEditor` and calls cancelNow() on it —
+    // which for a pristine insert is cancelAndMaybeDiscard() -> the freshly
+    // inserted block is discarded and its textarea never survives the gesture.
+    //
+    // MEASURED (scratchpad taskG-repro-code.js, replaying
+    // test/editor-client-runtime.test.js's Section 10「abandoned inserts
+    // (all 5 kinds)」): + -> 程式碼 with stale focus left on an untouched
+    // bystander paragraph produced
+    //   openRawEditor {currentBurst:true, activeEditor:false}
+    //   resolveOpenSession {currentBurst:true, activeEditor:true, pristineInsert:6}
+    //   cancelAndMaybeDiscard {blockId:6, pristineInsert:6}
+    // and zero code blocks left in the DOM. Only 程式碼 is affected because it
+    // is the one insert kind that registers an `activeEditor` before moving
+    // focus; the other four just focus another armed surface.
+    //
+    // The burst arm was previously unreachable — every caller resolved the
+    // session first — which is why the guard only ever named `activeEditor`.
+    // applyPatch()'s step-3 focus check makes it reachable: it adopts focus
+    // that a preventDefault()-ing gesture left standing on a bystander, so a
+    // burst can now be open on a block nobody is interacting with. Resolving
+    // it HERE (before `activeEditor` is registered, so the focusout that
+    // `ta.focus()` fires finds nothing to resolve) is the same defense-in-
+    // depth this guard already documents, applied to the other session kind.
+    if ((activeEditor && activeEditor.blockEl !== blockEl) ||
+        (currentBurst && currentBurst.blockEl !== blockEl)) {
       // Click-to-switch (see `activeEditor` / switchAwayFrom() comments
       // above): resolve whatever editor IS open before opening this one.
       // Defense in depth — the delegated click listener (wireBlockSelection
@@ -1023,7 +1739,10 @@
       const ok = await switchAwayFrom();
       if (!ok) return; // the open editor's auto-commit failed; stay put
     }
-    const blockId = Number(blockEl.getAttribute('data-block-id'));
+    // v3.2.0 (final review item 1): `let`, not `const` — reanchor() below
+    // re-derives all three of `blockId`/`startLine`/`endLine` when this
+    // session survives an incremental patch. See its own comment.
+    let blockId = Number(blockEl.getAttribute('data-block-id'));
     const block = blocks.find((b) => b.id === blockId);
     if (!block) return;
     // Task 4 fix round 1 (Critical, second path): a block that owns no source
@@ -1034,16 +1753,45 @@
     // INSERTS the text as a new line instead of replacing anything, leaving
     // the clicked item untouched and a stray line in the file (measured:
     // '# Doc\n\n- a\n\n- - b\n' + 'ZZZ' -> '# Doc\n\n- a\n\nZZZ\n- - b\n').
-    // The only such blocks today are list items (RULING F-O independently
-    // forbids a textarea inside one), and they are never armed, so before
-    // Task 4 gave every block a ⠿ this was reached by a plain body click and
-    // stayed unreported. Guarded HERE rather than at the click delegator so
+    // The only such blocks today are list items, and they are never armed, so
+    // before Task 4 gave every block a ⠿ this was reached by a plain body
+    // click and stayed unreported. (Until v3.1.0 this note also cited RULING
+    // F-O as an independent second reason. F-O is superseded for the ⠿ menu
+    // — see toggleGutterMenu() below — so this guard now carries the case
+    // ALONE, and it is the one that always mattered: a block that owns no
+    // source line has nothing to seed a textarea WITH, no matter how the
+    // editor is torn down afterwards.) Guarded HERE rather than at the click
+    // delegator so
     // every caller — the delegated degraded-block click, openRawViaGutter(),
     // the burst-degrade path — is closed by one check.
     if (blockOwnsNoLine(blockEl)) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return; }
 
+    // v3.1.0 修正 4: the span this editor owns. Without `range` it is exactly
+    // the block's own record, so `source` below is byte-identical to what
+    // extractBlockSource(lines, block) returned before — that helper IS this
+    // slice, and every pre-v3.1.0 call site keeps its behaviour unchanged.
+    // v3.2.0 (final review item 1): `let` for the same reason as `blockId`.
+    let startLine = range ? range.startLine : block.startLine;
+    let endLine = range ? range.endLine : block.endLine;
+    // The same inverted-range refusal blockOwnsNoLine() just made for the
+    // block, re-asked of the range actually being edited: a caller-supplied
+    // span can be malformed even when the anchor block is fine.
+    if (endLine < startLine) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return; }
+    // A list item's rendered chrome (the .ed-li-marker span, the optional
+    // .ed-li-check span, the .ed-li-text surface) is REBUILT BY THE RENDERER
+    // from the source line's marker — it is not recoverable from a captured
+    // innerHTML string once the item's own text has been rewritten, which is
+    // exactly what RULING F-O objected to. So a li (and any explicit range)
+    // commits through commitRangeEdit() over these lines rather than through
+    // the run serializer, and tears down through a real re-render — which
+    // removes F-O's stated premise rather than working around it. Ruling 13
+    // (v3.1.0) supersedes F-O for THIS surface, the ⠿ menu's MD 原始碼, and
+    // for that surface only: the burst-degrade refusal in resolveBurst() and
+    // the blockOwnsNoLine() guard just above both still stand, for reasons
+    // that were never F-O's.
+    const rangeMode = !!range || blockEl.getAttribute('data-block-type') === 'li';
     const original = blockEl.innerHTML;
-    const source = extractBlockSource(lines, block);
+    const source = lines.slice(startLine - 1, endLine).join('\n');
 
     const wrap = document.createElement('div');
     wrap.className = 'ed-editing';
@@ -1065,6 +1813,7 @@
       hasChanges: () => ta.value !== source,
       commitNow: commit,
       cancelNow: cancelAndMaybeDiscard,
+      reanchor,
     };
 
     const controls = document.createElement('div');
@@ -1089,13 +1838,30 @@
     ta.focus();
     ta.setSelectionRange(ta.value.length, ta.value.length);
 
-    function restore() {
-      blockEl.innerHTML = original;
+    async function restore() {
+      // v3.1.0 修正 4: `rangeMode` cannot restore by rewriting innerHTML —
+      // for a li that string would have to carry the marker/check/text chrome
+      // back, and for a multi-block span there is more than one block's DOM
+      // to put back in the first place. A re-render rebuilds all of it from
+      // `lines`, which this path never touched (restore() NEVER commits), so
+      // the document is byte-identical either way — this is a different way
+      // of repainting the same bytes, not a different edit.
+      if (rangeMode) {
+        if (activeEditor && activeEditor.blockEl === blockEl) activeEditor = null;
+        await safeRerenderAll();
+        return;
+      }
+      // v3.2.1 R1: 清 activeEditor 必須先於這個 innerHTML 寫入。寫入會 detach
+      // 聚焦的 textarea，Chromium 同步派發 focusout，而 focusout handler 只要
+      // activeEditor 非 null 就會走 switchAwayFrom() → resolveOpenSession() →
+      // commitNow()，把使用者按 Escape 要丟棄的文字提交進檔案（實測落到磁碟）。
+      // 同一函式的 rangeMode 分支早就是這個順序，理由相同。
       // Only clear `activeEditor` if it's still THIS block's entry — it may
       // already have been cleared out from under us (e.g. by rerenderAll()'s
       // own defensive reset on a successful swap elsewhere), and this must
       // never stomp some OTHER block's activeEditor set after this one.
       if (activeEditor && activeEditor.blockEl === blockEl) activeEditor = null;
+      blockEl.innerHTML = original;
       // No re-wiring needed here (unlike the old per-block gutter): block
       // selection / the edit bar are handled by ONE delegated `document`
       // click listener (see wireBlockSelection() below), so this
@@ -1113,11 +1879,41 @@
     async function cancelAndMaybeDiscard() {
       const wasPristineForThisBlock = !!(pristineInsert && pristineInsert.blockId === blockId);
       if (wasPristineForThisBlock) pristineInsert = null;
-      restore();
+      await restore();
       if (wasPristineForThisBlock) return await discardPristineInsert();
       return true;
     }
 
+    // v3.2.0 final review item 1 — 決議 3(1) 的 activeEditor 對稱項。
+    //
+    // 這個 session 的 `blockId` / `startLine` / `endLine` 是開啟當下從**那一
+    // 份** `blocks` 抓下來的；fallback 路徑上那從來不是問題，因為
+    // `contentEl.innerHTML = ` 會把這個 textarea 一起拔掉。patch 路徑保留
+    // 前綴／後綴節點，所以它可以活過一次 render，而 render 之後 `blocks`
+    // 已整份換掉、被保留後綴節點的 data-block-id 也被重寫過。
+    //
+    // applyPatch() 的 teardown 在實測 `document.body.contains(blockEl)` 成立
+    // 之後呼叫這支，把三個欄位從**現在**的 DOM 屬性與新的 `blocks` 重新
+    // 推導。回傳 false 代表推導不出來，呼叫端必須退回原本的無條件歸零：
+    //   - `range`：呼叫端指定的跨區塊 span（⠿ 選單的「MD 原始碼」批次路徑）
+    //     在新的 `blocks` 裡沒有單一對應記錄，無從重新推導。
+    //   - 區塊在新的 `blocks` 裡不存在（防禦；節點還在就不該發生）。
+    //   - 重新切出來的來源**不是** byte-identical：那表示這個區塊底下的行
+    //     真的變了，`ta.value` 與 `source` 都已經不是檔案裡的東西，沿用這個
+    //     session 會把過期的文字提交回去。patch 只保留 parts 相同的節點，所以
+    //     正常情況下這個等式成立；不成立時退回歸零是保守的正解。
+    function reanchor() {
+      if (range) return false;
+      const id = Number(blockEl.getAttribute('data-block-id'));
+      const b = blocks.find((x) => x.id === id);
+      if (!b || b.endLine < b.startLine) return false;
+      if (lines.slice(b.startLine - 1, b.endLine).join('\n') !== source) return false;
+      blockId = id;
+      startLine = b.startLine;
+      endLine = b.endLine;
+      return true;
+    }
+
     // Returns true when the editor is resolved (committed, or a no-op
     // commit that fell back to a cancel) — safe for a caller (switchAwayFrom
     // included) to proceed. Returns false only when the render actually
@@ -1127,7 +1923,13 @@
     // network hiccup must never silently discard what they typed). The
     // failure banner is already shown by safeRerenderAll()/rerenderAll().
     async function commit() {
-      const result = commitEdit({ lines, blocks, stack }, blockId, ta.value);
+      // v3.1.0 修正 4: an explicit range commits over ITS OWN span. commitEdit()
+      // is the by-id wrapper over exactly this call (it looks the block up and
+      // delegates), so the two branches are the same pipeline — replaceLines()
+      // + one undo op — differing only in which lines they name.
+      const result = rangeMode
+        ? commitRangeEdit({ lines, blocks, stack }, startLine, endLine, ta.value)
+        : commitEdit({ lines, blocks, stack }, blockId, ta.value);
       if (result.op === null) {
         // §10-gap fix (review): an explicit commit (Ctrl+Enter/✓) whose
         // text happens to be byte-identical to `source` is still an
@@ -1137,7 +1939,12 @@
       }
       const prevLines = lines;
       lines = result.lines;
-      const ok = await safeRerenderAll();
+      const editRange = result.op
+        ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+            endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+            delta: result.op.after.length - result.op.before.length }
+        : undefined;
+      const ok = await safeRerenderAll(editRange);
       if (!ok) {
         // Roll back the optimistic edit: pop the op safeRerenderAll's
         // failure means was never actually rendered, so `lines` stays
@@ -1147,9 +1954,48 @@
         lines = rollbackFailedRender({ lines, stack }, result, prevLines);
         return false;
       }
-      // Success: rerenderAll() already replaced the whole .content subtree
-      // (this block included) and nulled `activeEditor` itself — nothing
-      // left to do here.
+      // Success. On the FALLBACK path rerenderAll() replaced the whole
+      // .content subtree (this block included) and nulled `activeEditor`
+      // itself, so there was nothing left to do here.
+      //
+      // v3.2.0 final review item 1: that is no longer unconditional. The
+      // patch path only detaches this block when it lands inside
+      // `replaceSpan` — and a commit very often leaves it OUTSIDE: whenever
+      // the edit's visible effect is a NEW block AFTER this one (a line
+      // appended below a fence, a paragraph typed under a paragraph) this
+      // block's own part is byte-identical before and after, so patchmap
+      // keeps it in `keepPrefix` and the textarea stays on screen, on top of
+      // content that was already repainted around it.
+      //
+      // MEASURED at HEAD, before this repair (scratchpad/item1-zombie.js
+      // --head): Ctrl+Enter on a code fence with one line appended commits
+      // correctly to the file but leaves `rawTextareas: 1` standing forever
+      // — unclickable, because both the delegated click handler and
+      // openRawEditor() early-return on a block that already has a `.ed-raw`.
+      // With the `activeEditor` exception above it is worse than cosmetic:
+      // the session stays live with its ORIGINAL `source`, so the next
+      // switchAwayFrom() sees hasChanges() and commits the same text a
+      // second time (measured: 'const LOST = 2;' twice in the file).
+      //
+      // A kept node's part is byte-identical by construction — that is the
+      // only reason patchmap kept it — so `original` (this block's innerHTML
+      // captured at open, i.e. post-armEditables) is exactly the content to
+      // put back. Same one-line repaint the non-range restore() below uses,
+      // for the same reason.
+      //
+      // ⚠ 順序不可對調，而且不是防禦性的：`blockEl.innerHTML =` 會把還握著
+      // 焦點的 textarea 就地 detach，Chromium 在那當下**同步**送出一次
+      // focusout，委派的 focusout handler 走 switchAwayFrom() →
+      // resolveOpenSession() → activeEditor.commitNow()。先重繪再歸零時，
+      // 那一發看到的還是這個 session、hasChanges() 仍為真，於是把同一段文字
+      // 再提交一次（實測：'ZZZ tail.' 在檔案裡出現兩次，stack 是
+      // commit → focusout → switchAwayFrom → resolveOpenSession → commitNow）。
+      // 先歸零就沒有東西可以被重新解析。rangeMode 的 restore() 早就是這個
+      // 順序，理由相同。
+      if (activeEditor && activeEditor.blockEl === blockEl) activeEditor = null;
+      if (document.body.contains(blockEl) && blockEl.querySelector('.ed-raw')) {
+        blockEl.innerHTML = original;
+      }
       return true;
     }
 
@@ -1822,7 +2668,51 @@
   // switchAwayFrom() first resolves any editor that's currently open on this
   // (or another) block, same precondition as undo()/redo() below, so this
   // never races a concurrent commit or operates on stale `lines`/`blocks`.
+  //
+  // v3.2.1 final wave: THIN WRAPPER + `finally`, the same shape the other four
+  // sinks use, because this function's own early exits were live holes in
+  // exactly the promise this version's CHANGELOG makes. MEASURED on ddac6ce
+  // with real keystrokes, three runs each: typing in `# Title` then Shift+Tab
+  // went H1.ed-wys-armed / 15 enabled → BODY / 4 enabled, and `###### Title`
+  // then Tab did the same; `## Title` + Tab (the unclamped control) stayed
+  // H3.ed-wys-armed / 15. The clamp is reachable from an ordinary gesture:
+  // handleBurstKeydown()'s `changeHeadingDepth(currentBurst.blockEl,
+  // e.shiftKey ? -1 : 1)` passes a raw ±1 with no `delta === 0` filter (unlike
+  // applyHeadingLevel(), which computes a delta and can hand over 0), so Tab
+  // at either end of H1..H6 lands on `newDepth === curDepth` — an early return
+  // that sits BELOW the switchAwayFrom() that already committed and re-rendered
+  // and ABOVE the restore at the tail.
+  //
+  // The body answers a line on every exit it can name one for:
+  //   * success                  result.op.startLine (the commit's own first
+  //                              written line — see the note at the tail)
+  //   * newDepth === curDepth    block.startLine
+  //   * result.op === null       block.startLine
+  // `block` is looked up out of `blocks` AFTER switchAwayFrom(), so its
+  // startLine is already a post-render coordinate. INSTRUMENTED at that exit
+  // rather than reasoned: on `# Title` typed into and then Shift+Tab-ed, the
+  // clamped return printed
+  //   {sameBlocksArray:false, sameNode:false, blockId:0, startLine:1,
+  //    resolvesToId:0, resolvedText:'TitleX'}
+  // — switchAwayFrom() had replaced both the `blocks` array and the heading's
+  // DOM node, and `block.startLine` still resolved to the LIVE block carrying
+  // the just-committed text, which is exactly what focusBlockAtLine() needs.
+  //
+  // The two re-query failures above it (`blockEl` gone, `block` not in
+  // `blocks`) deliberately answer nothing: there is no block left to aim at,
+  // and guessing a line is worse than restoring no caret.
   async function changeHeadingDepth(blockEl, delta) {
+    let focusLine = null;
+    const anchor = {};
+    try {
+      const out = await changeHeadingDepthBody(blockEl, delta, anchor);
+      if (out != null) focusLine = out;
+    } finally {
+      restoreAfterStructuralOp(focusLine, anchor.line);
+    }
+  }
+
+  async function changeHeadingDepthBody(blockEl, delta, anchor) {
     if (!blockEl) return;
     const blockId = Number(blockEl.getAttribute('data-block-id'));
     // Commits (never discards) whatever burst/editor is open first — same
@@ -1855,6 +2745,9 @@
     }
     const block = blocks.find((b) => b.id === blockId);
     if (!block) return;
+    // Post-switchAwayFrom(), post-render: the landing for every exit below
+    // that writes nothing. See restoreAfterStructuralOp().
+    if (anchor) anchor.line = block.startLine;
     const curLine = lines[block.startLine - 1];
     const curDepth = headingDepthOf(curLine);
     const newDepth = Math.max(1, Math.min(6, curDepth + delta));
@@ -1864,10 +2757,37 @@
     if (result.op === null) return;
     const prevLines = lines;
     lines = result.lines;
-    const okRender = await safeRerenderAll();
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 (controller ruling T5-1): the OTHER sink. H▾ on a block that is
+    // ALREADY a heading routes HERE, not to convertBlockViaMenu() —
+    // applyHeadingLevel() takes that road only for a NON-heading — so without
+    // this, H2 → H4 still ends the way every conversion used to: the render's
+    // teardown ran resetToolbarBlock(), activeElement is BODY and the bar is
+    // down to 4 enabled buttons, and a second operation needs a fresh click.
+    //
+    // Same predicate and the same measurement as convertBlockViaMenu()'s exit
+    // — the wrapper's restoreAfterStructuralOp() is now literally the same
+    // function, so see its note for why it is `blockSelection` and not operand
+    // cardinality, and why forcing a caret while a selection stands
+    // manufactures a broken state rather than fixing one.
+    //
+    // The line is `result.op.startLine`, the commit's OWN first written line:
+    // commitEdit() resolves the block and hands commitRangeEdit() that
+    // startLine, which is where replaceLines() writes `after`. This function
+    // declares no collapse of its own (it is not a set operation), so the
+    // commit result is the only post-commit value it holds — and it is a
+    // RESULT, not a pre-commit `block.startLine` capture. An insertion above
+    // this block cannot have happened between the two, because the commit IS
+    // the only thing that ran.
+    return result.op.startLine;
   }
 
   // ── Task 2 (Phase 3): always-on WYSIWYG editing + burst undo ───────────
@@ -2378,37 +3298,42 @@
     gutterMenuConvert.hidden = convertWithheldFor(blockType);
     gutterMenuDuplicate.hidden = false;
     gutterMenuDelete.hidden = false;
-    // RULING F-O: 'MD 原始碼' is hidden for a list item PERMANENTLY, not as a
-    // phased measure. openRawEditor() replaces the block's innerHTML with a
-    // <textarea>, and a li is one line of a run that is serialized as a whole
-    // — a textarea inside it is content the serializer cannot represent, and
-    // restore() would have to rebuild the marker/check/text chrome from a
-    // string. Every other block type keeps it: the menu is a SINGLETON moved
-    // between blocks, so this must be reset on every open, not set once.
+    // 'MD 原始碼' is offered for EVERY block type, list items included, and
+    // for a multi-block selection. The menu is a SINGLETON moved between
+    // blocks, so this is still written on every open rather than set once.
     // (test/editor-reader-rebind.test.js drives raw-edit through this button
     // by its exact text on a paragraph.)
     //
-    // §3.7's other sentence about this item — 「多選時不顯示 `MD 原始碼`」 —
-    // is the half S3 shipped without. openRawViaGutter() rewrites ONE block's
-    // source lines, so over a set of N it silently answers for the grip's
-    // block and ignores the rest: an item that appears to act on the selection
-    // and does not.
+    // ⚠ THIS REVERSES RULING F-O, deliberately and at spec level (v3.1.0
+    // Ruling 13), for this surface and this surface only. F-O read: 'MD
+    // 原始碼' is hidden for a list item PERMANENTLY, because openRawEditor()
+    // replaces the block's innerHTML with a <textarea> — and a li is one line
+    // of a run serialized as a whole, so a textarea inside it is content the
+    // serializer cannot represent, and restore() would have to rebuild the
+    // marker/check/text chrome out of a string. 修正 4 removes that premise
+    // instead of arguing with it: a li now raw-edits an explicit LINE RANGE,
+    // commits it through commitRangeEdit() rather than the run
+    // re-serializer, and RESTORES BY RE-RENDERING rather than by rewriting
+    // innerHTML, so no serializer ever sees the textarea and no chrome is
+    // ever rebuilt by hand.
     //
-    // The question is §3.3's MEMBERSHIP question, asked exactly the way every
-    // set operation asks it (resolveGutterOperands() → resolveMembership(),
-    // identifying the grip block by REFERENCE into `blocks` — Task 1 carry 4),
-    // and not "is anything selected". Two states answer differently and both
-    // keep the item: a set of exactly the grip block is a set of ONE, which
-    // raw-edits fine; and a set standing elsewhere in the document is not this
-    // grip's set at all — §3.3 turns that gesture into a single-block operation
-    // before it acts, so the item is right there too.
-    const mdRec = blockRecOf(blockEl);
-    const mdMembership = (selectionLib && mdRec)
-      ? selectionLib.resolveMembership(blockSelection, blocks, mdRec)
-      : { mode: 'single', members: mdRec ? [mdRec] : [] };
-    const mdMultiSelected =
-      mdMembership.mode === 'batch' && mdMembership.members.length > 1;
-    gutterMenuMd.hidden = (blockType === 'li') || mdMultiSelected;
+    // F-O's OTHER call sites are NOT in scope and still refuse, each for a
+    // reason that was never F-O's: openRawEditor()'s blockOwnsNoLine() guard
+    // (a block with an inverted range has no line to seed a textarea with)
+    // and resolveBurst()'s unsupported-inline-content path (that refusal is
+    // about the CONTENT, not the container).
+    //
+    // §3.7's other sentence about this item — 「多選時不顯示 `MD 原始碼`」 —
+    // is also lifted, and for the same kind of reason: it existed because
+    // openRawViaGutter() rewrote ONE block's source lines, so over a set of N
+    // it silently answered for the grip's block and ignored the rest. It now
+    // opens on the WHOLE span's line range (§3.3 membership, asked through
+    // resolveGutterOperands() so the contiguity and no-source-line gates come
+    // with it), so the item does what it appears to do.
+    // The membership question itself moved WITH the decision it feeds, into
+    // openRawViaGutter() (it now chooses the RANGE instead of the
+    // visibility), so it is asked exactly once, in the place that acts on it.
+    gutterMenuMd.hidden = false;
     blockEl.appendChild(gutterMenu);
   }
 
@@ -2522,6 +3447,13 @@
     list: ['-'],
     table: ['| A | B |', '|---|---|', '|  |  |'],
     code: ['```', '', '```'],
+    // v3.1.0 §4: the toolbar's ― button. '---' is safe as a thematic break
+    // here specifically because commitBlockInsertion() ALWAYS writes a
+    // leading blank line (see its own comment) — a '---' directly under a
+    // non-blank line would instead lex as a setext H2 and silently promote
+    // whatever preceded it. Nothing else in this file may reuse this
+    // skeleton through a path that does not guarantee that blank.
+    line: ['---'],
   };
 
   // Selects the entirety of `el`'s content (used right after focusing a
@@ -2567,7 +3499,28 @@
     const prevLines = lines;
     lines = discarded.lines;
     setDirty();
-    const okRender = await safeRerenderAll();
+    // v3.2.0: UndoStack.undo()/discardTop() reverse the op when applying it but
+    // return the unmodified FORWARD op, so the range actually rewritten is
+    // [op.startLine, op.startLine + op.after.length - 1] and the delta is the
+    // mirror of the forward one. Using op.endLine here would name the opposite
+    // direction — the span the op wrote on the way FORWARD, not the one this
+    // reversal just rewrote.
+    //
+    // Final review item 4 — what naming it wrongly would cost today: nothing.
+    // Per 決議 4(b) `editRange` is ADVISORY. patchmap() destructures
+    // oldBlocks/newBlocks/oldParts/newParts and never reads it; the kept
+    // prefix/suffix is the longest common run of the two PART arrays, and
+    // seeding it from an op's line range only ever made the answer worse
+    // (measured in 決議 4(b): seeded kept 0 of 5, pure-parts kept 4 of 5).
+    // Its one client-side use is the truthiness gate in applyRenderResult().
+    // So the direction changes no plan — this is simply the correct value for
+    // whenever something does start reading it.
+    const editRange = discarded.op
+      ? { startLine: discarded.op.startLine,
+          endLine: discarded.op.startLine + discarded.op.after.length - 1,
+          delta: discarded.op.before.length - discarded.op.after.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       stack.push(discarded.op); // put it back — see discardTop()'s own comment
       lines = prevLines;
@@ -2620,7 +3573,16 @@
   // dirty burst, swapping the whole `.content` subtree and detaching
   // `blockEl` along with it — same "ensureTableBurstOpen()'s Finding 6"
   // recovery idiom used throughout this file), THEN acts.
-  async function insertBlockBelow(blockEl, kind) {
+  // v3.1.0 §4 / 追加 2 / 追加 3: `opts.lines` supplies EXPLICIT source lines
+  // instead of one of the five placeholder skeletons — the image-drop path
+  // (`![](assets/…)`) and the paste path (turndown's markdown) both need to
+  // land real content, and both must land it as SOURCE so it goes through
+  // commitBlockInsertion()/replaceLines() like every other edit rather than
+  // being spliced into the DOM behind serializeBlocks()'s back. Everything
+  // else about the insert — the run-wide gate, the subtree anchor, the
+  // rollback — is shared, which is the whole reason this is one extra
+  // parameter and not a second insertion path.
+  async function insertBlockBelow(blockEl, kind, opts) {
     if (!blockEl) return;
     // T7: captured BEFORE switchAwayFrom(), because that is what can renumber
     // the ids — see captureBlockIdentity()'s comment.
@@ -2659,7 +3621,8 @@
       refuseStructuralListEdit(NO_SOURCE_LINE_INSERT_MESSAGE);
       return;
     }
-    const newLines = BLOCK_SKELETONS[kind];
+    const customLines = opts && Array.isArray(opts.lines) ? opts.lines : null;
+    const newLines = customLines || BLOCK_SKELETONS[kind];
     if (!newLines) return;
 
     // ── S2 Task 7: a LIST ITEM anchor (§6's S1 note item 3) ────────────────
@@ -2730,7 +3693,12 @@
     const result = commitBlockInsertion({ lines, blocks, stack }, liveBlockId, newLines);
     const prevLines = lines;
     lines = result.lines;
-    const okRender = await safeRerenderAll();
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
       return;
@@ -2739,9 +3707,47 @@
     // see `pristineInsert`'s own comment for the full contract. `blocks`
     // was just reassigned by the successful rerenderAll() above, so this
     // is the server-authoritative id for the block at `newStartLine`.
-    const target = blocks.find((b) => b.startLine === result.newStartLine);
-    if (target) pristineInsert = { blockId: target.id };
-    await focusInsertedBlock(result.newStartLine, kind);
+    //
+    // v3.1.0: a custom-lines insert is NEITHER pristine NOR focus-and-select.
+    // `pristineInsert` means "a placeholder the user has not touched yet, so
+    // abandoning it removes it again" — applied to a dropped image or a
+    // pasted paragraph it would silently delete real content the moment the
+    // user clicked elsewhere without typing. focusAndSelectAll() is wrong for
+    // the same reason: it selects the block's whole content so the first
+    // keystroke replaces it, which is what a ZWSP placeholder wants and what
+    // a just-pasted paragraph very much does not.
+    //
+    // 'line' is excluded for the same reason from the other direction: both
+    // are PLACEHOLDER semantics, and an <hr> has no placeholder. There is
+    // nothing for focusAndSelectAll() to select (the block's content element
+    // is the rule itself), and "abandoning it un-typed removes it again"
+    // describes a skeleton waiting to be filled in — a thematic break is
+    // finished the moment it exists.
+    if (!customLines && kind !== 'line') {
+      const target = blocks.find((b) => b.startLine === result.newStartLine);
+      if (target) pristineInsert = { blockId: target.id };
+      await focusInsertedBlock(result.newStartLine, kind);
+    } else if (kind === 'line') {
+      // v3.2.1: <hr> 沒有 placeholder，所以不 focusInsertedBlock()（那是上面
+      // 那個 `kind !== 'line'` 既有的刻意 opt-out）。這一支只做工具列復原：把
+      // toolbarBlockEl 指向新插入的 hr block，讓 bar 不要停在 render teardown
+      // 留下的 4 顆。
+      //
+      // ⚠ 明說量測到的事，不要說希望發生的事：**caret 沒有被還原**。實測
+      // （alpha / bravo / charlie，點進 bravo 再按 分隔線）這一支停用時是
+      // {activeElement: BODY, enabled: 4}、啟用後是 {activeElement: BODY,
+      // enabled: 15}，兩者磁碟 byte-identical。也就是說使用者按完分隔線仍然
+      // 沒有游標，要再點一次 block 才能繼續打字 —— 工具列復原就是這一支交付的
+      // 全部。要連 caret 一起還原是另一個決定（游標該落在錨點 block 還是 hr
+      // 之後的 block），不在本 task 的範圍內。
+      //
+      // Final wave, M4: gated on `blockSelection` like the other four restore
+      // sites. Harmless today — a ＋ 分隔線 pressed with a set standing writes
+      // 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);
+    }
   }
 
 
@@ -2860,7 +3866,34 @@
   // already been raised — otherwise `{ els, recs, batch }`: the LIVE block
   // elements in document order, their records out of `blocks` (by reference),
   // and whether more than one block is being operated on.
-  async function resolveGutterOperands(blockEl) {
+  //
+  // v3.2.1 final wave: `anchor` is an optional OUT-PARAMETER. When given, its
+  // `.line` is set to the grip block's start line as soon as that block has
+  // been re-resolved against the post-switchAwayFrom() `blocks` — i.e. a
+  // number that is already valid on the freshly rendered DOM. Every refusal
+  // BELOW that assignment therefore leaves the caller holding a live
+  // coordinate for a block the refusal did not touch.
+  //
+  // FIVE exits sit ABOVE it and all of them leave `.line` undefined, which is
+  // the honest answer in each case (N3 — the first version of this sentence
+  // said "the two exits", the same undercount M2 existed to fix, so they are
+  // counted out here one by one):
+  //   1. `if (!blockEl) return null`        — no gesture at all.
+  //   2. `if (!ok) return null`             — switchAwayFrom()'s commit FAILED
+  //      and the session it could not commit is still open with its own
+  //      banner; aiming a caret anywhere would fight it.
+  //   3. the dropped-gesture re-resolve     — the block is genuinely gone.
+  //   4. the no-source-line refusal         — the block is there, but its range
+  //      is inverted (endLine === startLine - 1), and
+  //      `blocks.find(b => b.startLine === …)` would resolve some OTHER block.
+  //   5. `if (!rec)` (a second DROPPED_GESTURE) — the one the undercount lost.
+  //      It is NOT absorbed by 4: blockOwnsNoLine() is `!!rec && rec.endLine <
+  //      rec.startLine`, so it answers FALSE when the id is absent from
+  //      `blocks`, and it also answers false for a provisional block whose
+  //      `data-block-id` is null (blockRecOf() returns null for both). Either
+  //      way there is no record to read a startLine off.
+  // See restoreAfterStructuralOp().
+  async function resolveGutterOperands(blockEl, anchor) {
     if (!blockEl) return null;
     // Finding 5a's mousedown preventDefault() deliberately keeps a dirty burst
     // alive across the ⠿ press, so the commit that lands inside
@@ -2886,6 +3919,7 @@
     if (blockOwnsNoLine(liveBlockEl)) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return null; }
     const rec = blockRecOf(liveBlockEl);
     if (!rec) { showBanner(DROPPED_GESTURE_MESSAGE, null, null); return null; }
+    if (anchor) anchor.line = rec.startLine;
 
     const res = selectionLib
       ? selectionLib.resolveMembership(blockSelection, blocks, rec)
@@ -3059,7 +4093,148 @@
     return run;
   }
 
+  // ── v3.2.1 final wave: ONE landing for all four structural sinks ────────
+  //
+  // The v3.2.1 wrappers restored only on the SUCCESS line the body answered.
+  // Measured on ddac6ce, 轉換成 → 引用 on a hard-wrapped list item (an ENABLED
+  // menu item — `disabled === false`, measured) whose own burst was dirty:
+  // DIV.ed-li-text ed-wys-armed / 16 enabled → BODY / 4 enabled, plus the
+  // banner 「此清單含不支援的格式，無法調整結構」. The `finally` WAS reached;
+  // `focusLine` was simply null there, so focusBlockAtLine() was skipped and
+  // reaimToolbarBlockAtLine(null) returned on its first line — while
+  // resolveGutterOperands()'s own switchAwayFrom() had already committed the
+  // burst and re-rendered, which is what took the foothold away.
+  //
+  // Hence the second coordinate. `focusLine` is the body's SUCCESS landing and
+  // is used exactly as before. `anchorLine` is resolveGutterOperands()'s live
+  // grip line (see its `anchor` out-parameter) and is used ONLY when the body
+  // answered nothing — a refusal, a no-op commit, or a rolled-back render.
+  //
+  // The foothold check on that second path is deliberate and is NOT symmetric
+  // with the first. A refusal can also arrive with the user's caret still
+  // exactly where they left it (a CLEAN burst goes out through
+  // endBurstWithoutResolve(): no commit, no render, focus never moves —
+  // measured: 轉換成 → 引用 on the same hard-wrapped li WITHOUT typing first
+  // leaves DIV.ed-li-text ed-wys-armed / 16 enabled on ddac6ce). Restoring
+  // unconditionally there would drag that caret to the end of the block for no
+  // reason — the same mistake fix round 1 corrected in applyLinkToggle(), and
+  // this is the same predicate it settled on.
+  //
+  // M3, the predicate divergence: the four sinks now AGREE that a rolled-back
+  // render restores. Verified by reading rather than driven (a render failure
+  // needs the server to fail mid-gesture): every `return false` inside
+  // rerenderAll() is one of its four fetch/parse exits, all of them above the
+  // call to applyRenderResult(); applyPatch() and applyFullRender() contain no
+  // `return false` at all (grep: zero hits between them). So a `false` answer
+  // from safeRerenderAll() means the DOM was never touched — the anchor block
+  // is still on screen under the same id — while the switchAwayFrom() that ran
+  // BEFORE it may already have re-rendered and reset the bar. Restoring is
+  // therefore the right answer, and returning empty-handed (what
+  // duplicateBlockViaMenuBody() and deleteBlockViaGutterBody() used to do on
+  // `!okRender`) strands the user in exactly the I1/I2 shape. The one failure
+  // 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) {
+    // 有 blockSelection 站著時什麼都不做 —— 見 convertBlockViaMenu() 底下那段
+    // 註解：強行還原 caret 會做出「底色仍說已選取、Delete 卻是死鍵」的混種狀態。
+    if (blockSelection) return;
+    if (focusLine != null) {
+      focusBlockAtLine(focusLine, true);   // caretToEnd
+      // 降級目標（quote / code）沒有可聚焦編輯面，focusBlockAtLine 會安靜
+      // no-op；把 toolbarBlockEl 指回那個 block，工具列才不會塌成 4 顆。
+      reaimToolbarBlockAtLine(focusLine);
+      return;
+    }
+    if (anchorLine == null) return;
+    const held = document.activeElement;
+    const heldSurface = held && held.closest
+      ? held.closest('.ed-wys-armed, .ed-wys-cell, .ed-raw') : null;
+    if (heldSurface) {
+      // ⚠ C1. "The caret never left, so there is nothing to do" was TRUE of the
+      // caret and FALSE of the toolbar, and the first version of this guard
+      // skipped both. The bar can be down to 4 while the caret is still sitting
+      // on a live surface, and that is the ORDINARY case, not an edge one: it
+      // is what happens on the PATCH render path, i.e. on every commit after
+      // the first of a page load (`lastParts` is null only for that first one,
+      // so the fallback route — the one this guard was measured on — is
+      // unreachable after it).
+      //
+      // INSTRUMENTED inside applyPatch() on a primed ⠿刪除 refusal, one log
+      // line per step, rather than read off the source:
+      //   route            PATCH
+      //   focusWasInSpan?  v:true  currentBurst:true  burstElAttached:false
+      //                    active:BODY
+      //   afterFocusRestore   active:DIV.ed-li-text ed-wys-armed
+      //                       toolbarBlockElNull:false
+      //   burstSurvived    v:false  currentBurst:true
+      //                    active:DIV.ed-li-text ed-wys-armed
+      //   resetToolbarBlock?  willRun:true
+      //   afterResetToolbarBlock  toolbarBlockElNull:true
+      //   restoreAfterStructuralOp  active:DIV.ed-li-text ed-wys-armed
+      //                             toolbarBlockElNull:true
+      // — applyPatch()'s `focusWasInSpan` block hands focus back to the NEW
+      // surface, and `burstSurvived` is only evaluated afterwards. On this
+      // route `currentBurst` is still the OLD burst (resolveBurst()'s own
+      // teardown has not nulled it yet, which is also why focusin's
+      // `if (currentBurst) return;` stops the focus() from opening a fresh
+      // one), and that old burst's editEl was detached by the patch — so
+      // `burstSurvived` is false and `resetToolbarBlock()` runs AFTER the
+      // caret was handed back. The unprimed run of the same gesture took the
+      // FALLBACK route and arrived here with active:BODY, which is why the
+      // first wave's measurements never saw this.
+      //
+      // So: do not drag the caret (it never left), but DO re-aim the bar, at
+      // the block the caret is actually in rather than at `anchorLine` — those
+      // are the same block on every path measured, and when they ever differ
+      // the caret's own block is the honest answer.
+      const blk = heldSurface.closest('.ed-block');
+      if (blk && document.body.contains(blk)) { toolbarBlockEl = blk; updateToolbar(); }
+      return;
+    }
+    focusBlockAtLine(anchorLine, true);   // caretToEnd
+    reaimToolbarBlockAtLine(anchorLine);
+  }
+
+  // v3.2.1: the caret restore is a THIN WRAPPER around the conversion body so
+  // that it sits at the function's EXIT and every exit reaches it. The body's
+  // pre-commit refusal exits, enumerated (final wave, M2 — the sentence that
+  // stood here said "three" and named three of them):
+  //   1. `if (!operands) return`            — resolveGutterOperands() answered
+  //                                           null (dropped gesture, no source
+  //                                           line, empty/gapped/no-element
+  //                                           batch)
+  //   2. the mixed list/non-list refusal    (BATCH_MIXED_MESSAGE)
+  //   3. the withheld-type refusal          (BATCH_CONVERT_WITHHELD_MESSAGES)
+  //   4. `if (!liRun)`                      (BATCH_MULTIRUN_MESSAGE)
+  //   5. `!listRunSupportsStructuralEdit()` (§4.1's run-wide gate)
+  //   6. `if (!stripped.ok)`                (per-block 「此區塊的格式無法轉換」)
+  // — six, not three, plus `result.op === null` (a commit that wrote nothing)
+  // and the rolled-back render on the tail. Every one of them is reachable
+  // from a lit ⠿ menu item, and the li → list / li → non-list / blocks → list
+  // helpers this function tail-calls carry their own refusals on top.
+  //
+  // The body returns the operated block's post-commit start line, or undefined
+  // when it refused or wrote nothing — `anchor.line` is what covers the
+  // second case (see restoreAfterStructuralOp()).
   async function convertBlockViaMenu(blockEl, target) {
+    let focusLine = null;
+    const anchor = {};
+    try {
+      const out = await convertBlockViaMenuBody(blockEl, target, anchor);
+      if (out != null) focusLine = out;
+    } finally {
+      // v3.2.1: 判準是「有沒有 blockSelection 站著」，不是 operand 數量 ——
+      // 實測 operands.els.length === 1 在「有選取」與「無選取」兩態都成立，
+      // 鑑別力為零。有選取時 declareCollapse() → applySelectionClasses() 已經
+      // 在全新 DOM 上把 roving focus 裝回 .ed-block wrapper（9 種轉換形狀全部
+      // 如此），這時強行還原 caret 會製造混種狀態：底色仍說「已選取」，Delete
+      // 卻變成死鍵、Shift+↓ 降級成移動文字游標。所以有選取時什麼都不做。
+      restoreAfterStructuralOp(focusLine, anchor.line);
+    }
+  }
+
+  async function convertBlockViaMenuBody(blockEl, target, anchor) {
     if (!blockEl || !target) return;
     // §3.3's membership rules and the whole shared preamble — see
     // resolveGutterOperands() above. `els` is ONE contiguous span; the plan's
@@ -3069,7 +4244,7 @@
     // fenced block raw-edited into two paragraphs changes the BLOCK count
     // without changing the LINE count, so an id-indexed delete hit the wrong
     // block, and the same shape silently rewrote a neighbouring table).
-    const operands = await resolveGutterOperands(blockEl);
+    const operands = await resolveGutterOperands(blockEl, anchor);
     if (!operands) return;
     const els = operands.els;
     const recs = operands.recs;
@@ -3142,8 +4317,7 @@
     // the run stays a run and the existing re-serialization machinery applies
     // unchanged.
     if (shape.allLi && convertMd.targetIsList(target)) {
-      await convertListItemsType(els, liRun, recs, target);
-      return;
+      return await convertListItemsType(els, liRun, recs, target);
     }
     // S2 Task 4 / S3 Task 6: li → a NON-list target. The items LEAVE the run,
     // so the span has to be rebuilt in three pieces and §4.3 rule 1's blank
@@ -3151,16 +4325,14 @@
     // lines mid-list with no separator and lazy continuation would swallow them
     // into the item above (measured, §4.3 rule 1).
     if (shape.allLi) {
-      await convertListItemsAway(els, liRun, recs, target);
-      return;
+      return await convertListItemsAway(els, liRun, recs, target);
     }
     // S2 Task 5 / S3 Task 6: non-list blocks BECOME list items, so §4.3 rule
     // 2's looseness policy applies — eat the separator to an adjacent run of
     // the same list type, or the merged list goes LOOSE and every item of it
     // degrades read-only. Same rule, same helper the li → li path above uses.
     if (convertMd.targetIsList(target)) {
-      await convertBlocksIntoList(els, recs, shape.kinds, target);
-      return;
+      return await convertBlocksIntoList(els, recs, shape.kinds, target);
     }
 
     // The plain path: N non-list blocks to a non-list target. One commit over
@@ -3194,10 +4366,20 @@
       startLine: first.startLine,
       endLine: first.startLine + md.split('\n').length - 1,
     });
-    const okRender = await safeRerenderAll();
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 §Task 5: the caller's `focusLine`. NOT a new value and NOT a
+    // pre-commit startLine — it is the very line the collapse above declares,
+    // i.e. the operated span's post-commit first line. The plain path is the
+    // one path that does not move it (the commit replaces the span in place).
+    return first.startLine;
   }
 
   // Is the editor session switchAwayFrom() would resolve open on THIS block?
@@ -3255,12 +4437,51 @@
   // `lines`, and the li path carries the clone through bystanderCarryOver()
   // under the ORIGINAL's block id, so list-md.js replays the file's own bytes
   // for it and only re-states the marker. Both keep a `~5px` a `~5px`.
+  //
+  // v3.2.1: the caret restore is a THIN WRAPPER around the duplication body,
+  // same shape and same reason as convertBlockViaMenu() above: the body has
+  // several exits that duplicate nothing — resolveGutterOperands() answering
+  // null, the mixed-list refusal, each of duplicateListItems()'s four, the
+  // op === null no-op and the failed render on the non-li tail — all of them
+  // reachable from a lit ⠿ menu item, and the wrapper is what makes every one
+  // of them reach the restore. The body answers the ORIGINAL span's first
+  // start line on success and undefined on every one of those exits.
+  //
+  // Final wave: "reach the restore" was true and not sufficient — with
+  // `focusLine` null the restore had nothing to aim at and did nothing. The
+  // refusal exits now land on `anchor.line`; see restoreAfterStructuralOp().
+  //
+  // 落點是【原件】而不是副本。三個理由，其中兩個是這個檔案自己已經寫下的事實：
+  //  1. 一個選單項目只能有一個答案。有 blockSelection 站著時，§3.3 的塌縮把
+  //     集合留在【原件】上（見 body 裡 declareCollapse() 那段註解：副本插在
+  //     所有被複製的東西【下面】，所以原件的行區間原封不動）。落在副本會讓
+  //     「按完 建立副本 之後手上握著什麼」取決於一個看不見的先前狀態。
+  //  2. 原件的行號直接可讀，副本的行號在 li 路徑上要另外付代價。副本帶著
+  //     原件的 data-block-id，所以 runLineOfBlock() 的
+  //     `lineMeta.findIndex((m) => m.blockId === targetId)` 回的是【原件】那
+  //     一行。這不是做不到 —— runLineOfBlock() 對沒有 id 的 block 另有一支
+  //     按位置數行的 fallback，而副本在 span 裡的位置是已知的 `at + 1 + i`。
+  //     代價在別的地方：那個共用的 id 正是 bystanderCarryOver() 逐位元組重播
+  //     副本、而不是重新 escape 它的原因（見下方 duplicateListItems() 的註解，
+  //     一個 '~5px' 不重播就會變成 '\~5px'）。所以這是一個取捨，不是一道牆。
+  //  3. 畫面上沒有東西在使用者底下移動：副本長在下面，原件原地不動。
   async function duplicateBlockViaMenu(blockEl) {
+    let focusLine = null;
+    const anchor = {};
+    try {
+      const out = await duplicateBlockViaMenuBody(blockEl, anchor);
+      if (out != null) focusLine = out;
+    } finally {
+      restoreAfterStructuralOp(focusLine, anchor.line);
+    }
+  }
+
+  async function duplicateBlockViaMenuBody(blockEl, anchor) {
     // §3.3's membership rules plus the shared preamble — see
     // resolveGutterOperands(). The whole span is duplicated by ONE commit; a
     // per-member loop would re-render between items and invalidate every id in
     // between.
-    const operands = await resolveGutterOperands(blockEl);
+    const operands = await resolveGutterOperands(blockEl, anchor);
     if (!operands) return;
     const els = operands.els;
     const recs = operands.recs;
@@ -3268,8 +4489,12 @@
     if (shape.anyLi && !shape.allLi) { refuseStructuralListEdit(BATCH_MIXED_MESSAGE); return; }
 
     if (shape.allLi) {
-      await duplicateListItems(els, recs);
-      return;
+      // recs[0].startLine is unchanged by this commit — duplicateListItems()'s
+      // own declareCollapse() comment is the argument: the copies land after
+      // everything the set owns, and no member's line COUNT can change (a
+      // multi-line target is refused, and §3.8's renumbering only ever changes
+      // marker WIDTH), so the originals still occupy the range they occupied.
+      return (await duplicateListItems(els, recs)) ? recs[0].startLine : undefined;
     }
 
     // The non-li span duplicates as ONE slice of `lines` — separators between
@@ -3289,9 +4514,20 @@
     // answer as "keep what is standing" and says so explicitly, which is what
     // keeps this correct if the insertion point ever moves.
     declareCollapse({ startLine: first.startLine, endLine: last.endLine });
-    if (!(await safeRerenderAll())) {
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    if (!(await safeRerenderAll(editRange))) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      return;
     }
+    // The insertion is anchored on the LAST member and lands BELOW it, so
+    // ops.shiftBlocks() moved only ids greater than that one — the span's own
+    // first start line is the same number before and after, which is the same
+    // fact declareCollapse() above relies on.
+    return first.startLine;
   }
 
   // The li half of 建立副本. The copy is spliced into the run's own span and the
@@ -3300,10 +4536,15 @@
   // §3.8's renumbering falls out of the re-serialization ('1. alpha' duplicated
   // gives '1. alpha / 2. alpha / 3. bravo', not '1. alpha / 1. alpha / 2.
   // bravo').
+  //
+  // v3.2.1: returns commitListStructure()'s own true/false, and false for each
+  // of the four refusal exits — duplicateBlockViaMenu()'s wrapper needs to tell
+  // a refusal (nothing was duplicated, the block is still where it was) apart
+  // from a completed duplicate.
   async function duplicateListItems(liEls, recs) {
     // Every list batch is one run's problem — see batchRunOf().
     const run = batchRunOf(liEls);
-    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return; }
+    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return false; }
     // §4.3's run-wide gate — 轉換／建立副本／刪除／拖曳 each make this call for
     // themselves; there is no shared helper. Its input is §3.4 rule 2's scope,
     // which is exactly what listRunOf() returns (the outermost run PLUS every
@@ -3311,14 +4552,14 @@
     // it adds the item's lines over again), so a multi-line li refuses as a
     // TARGET while remaining a perfectly good bystander — and in a batch EVERY
     // member is a target.
-    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return; }
+    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return false; }
     // Captured BEFORE the copy enters the span. The copy carries the
     // ORIGINAL's data-block-id — that is what makes bystanderCarryOver() replay
     // its bytes rather than re-escape them — so runRangeOfBlocks() would
     // resolve it to the original's record, and on a duplicate of the span's
     // LAST member that silently re-states the range's end line.
     const range = runRangeOfBlocks({ lines, blocks, stack }, run);
-    if (!range) return;
+    if (!range) return false;
 
     // §4.3, measured: after the SUBTREE, not after the item's own line.
     // subtreeBlocksAfter() is the flat model's subtree — the contiguous run of
@@ -3331,7 +4572,7 @@
     const subtree = subtreeBlocksAfter(anchorLi, Number(anchorLi.getAttribute('data-indent')) || 0);
     const lastEl = subtree.length ? subtree[subtree.length - 1] : anchorLi;
     const at = run.indexOf(lastEl);
-    if (at < 0) return;
+    if (at < 0) return false;
 
     const copies = liEls.map((liEl) => liEl.cloneNode(true));
     // `data-list-start` is the ONLY carrier of "marked's lexer opened a new
@@ -3374,33 +4615,161 @@
       startLine: recs[0].startLine,
       endLine: recs[recs.length - 1].endLine,
     });
-    await commitListStructure(span, null, false,
+    return await commitListStructure(span, null, false,
       { presetRange: range, carryOver: bystanderCarryOver(span) });
   }
   // Deletes `blockEl`'s ENTIRE line range (generalizing commitListBlockRemoval()
   // — unchanged, see its own comment — to any block type, not just an
   // emptied-out list). Same resolve-first / re-query-live-block-by-id
   // precondition as insertBlockBelow() above.
+  //
+  // v3.2.1: the caret restore is a THIN WRAPPER around the removal body, same
+  // shape as convertBlockViaMenu() above. A delete has no "back to the block it
+  // operated on" — the block is gone — so the body answers the HOLE's line
+  // coordinate (the removed span's own first start line) and
+  // blockLineAfterRemoval() below turns that into a block that still exists.
+  //
+  // 有 blockSelection 站著時什麼都不做的判準與 convertBlockViaMenu() 相同，
+  // 但在這條路徑上它幾乎總是讓路：批次刪除的 §3.3 塌縮是 declareCollapse(null)
+  // ＝清空集合（見 body 內那段註解），render 之後 blockSelection 已經是 null。
+  // 那是對的 —— 沒有集合站著就沒有「底色仍說已選取、Delete 卻是死鍵」的混種
+  // 狀態可言，而使用者剛把手上唯一的著力點刪掉，更需要拿回一個。
   async function deleteBlockViaGutter(blockEl) {
+    let removed = null;
+    const anchor = {};
+    try {
+      const out = await deleteBlockViaGutterBody(blockEl, anchor);
+      if (out) removed = out;
+    } finally {
+      // Final wave: on the refusal / rolled-back-render exits `removed` is
+      // null, so the landing falls through to `anchor.line` — the block the
+      // gesture named, which a refusal left exactly where it was. On the
+      // SUCCESS path that block no longer exists, which is why the success
+      // coordinate is blockLineAfterRemoval()'s carried neighbour and not the
+      // anchor: restoreAfterStructuralOp() only consults `anchor.line` when
+      // the first argument is null.
+      const focusLine = removed ? blockLineAfterRemoval(removed) : null;
+      // `anchor.line` is the line of the block that was just DELETED, so it is
+      // offered only when the body refused. A successful delete that cannot
+      // name a landing (blockLineAfterRemoval() answering null — an emptied
+      // document) must restore nothing rather than aim at the hole.
+      restoreAfterStructuralOp(focusLine, removed ? null : anchor.line);
+    }
+  }
+
+  // The block the user is left holding once a span has been removed. Takes the
+  // `{ prevLine, spanIsFirst }` the body captured BEFORE its commit:
+  //
+  //   prevLine    the block immediately ABOVE the removed span, or null when
+  //               there is none. A PRE-commit start line, and stable across the
+  //               render for ONE reason that covers every path, not a reason
+  //               per path:
+  //
+  //                 commitRangeRemoval() and commitRangeEdit() compute the
+  //                 SAME anchor — `blocks.filter((b) => b.endLine <= endLine)
+  //                 .pop()`, textually identical in both — and hand it to
+  //                 ops.shiftBlocks(), which moves a block only when
+  //                 `b.id > editedId` (lineops.js). Ids are positional
+  //                 ordinals in document order, so the block above the span has
+  //                 a SMALLER id than every block inside it, and the anchor is
+  //                 at least the span's last member (that member is itself in
+  //                 the filtered list). The neighbour therefore fails
+  //                 `b.id > editedId` whichever helper runs.
+  //
+  //               ⚠ Fix round 3. The sentence that stood here said the li path
+  //               calls NEITHER of those helpers. That is false, and its own
+  //               named example is the counter-example: commitListStructure()
+  //               routes `md === ''` — no survivors, i.e. a WHOLE-RUN delete —
+  //               straight into commitRangeRemoval(). Instrumented and driven
+  //               rather than read: 刪除 over all three items of
+  //               '- alpha / - bravo / - charlie' printed
+  //                 commitRangeRemoval range=5..7 anchor=id4(7..7)
+  //                 shiftBlocks editedId=4 delta=-4 movedIds=[5] untouchedIds=[0,1,2,3,4]
+  //               while a partial delete of the same run printed
+  //                 commitRangeEdit range=5..7 anchor=id4(7..7)
+  //                 shiftBlocks editedId=4 delta=-1 movedIds=[5] untouchedIds=[0,1,2,3,4]
+  //               — two different helpers, the same anchor, and in both the
+  //               neighbour (id1) sits in `untouchedIds`. Five gestures were
+  //               instrumented this way (whole run, middle item, first item, a
+  //               non-li paragraph, and a run that is the entire document) and
+  //               the neighbour was untouched in all five.
+  //   spanIsFirst true when the removed span WAS the document's first block, so
+  //               "no previous block" is a fact rather than a failed lookup —
+  //               see deleteBlockViaGutterBody()'s own comment for why those two
+  //               are not the same answer.
+  //
+  // 「上面那一個、游標落在它的結尾」是 Notion 的答案，也是 Backspace 併行的
+  // 落點；這個編輯器的 ⠿ / 建立副本 / 轉換成 整組詞彙都是 Notion 的。
+  //
+  // ⚠ Fix round 1, item 2: this used to INFER the neighbour from the hole's
+  // coordinate — "the largest post-render startLine strictly below it". That is
+  // wrong whenever commitRangeRemoval() takes its `sl -= 1` branch (the line
+  // after the span is not blank, so it absorbs the blank ABOVE instead): every
+  // block BELOW the hole then moves up too, the first of them lands one line
+  // ABOVE the hole's own start line, and taking the maximum picks THAT
+  // deterministically over the real previous block. Driven on '…Bravo para.\n' immediately followed by
+  // a block that interrupts a paragraph — an ATX heading, a list, a fenced
+  // code block, an hr — the caret landed on the block BELOW the hole in all
+  // four, and on the code / hr shapes (no focusable surface) it landed nowhere
+  // at all. The answer is not derivable from the hole; it has to be carried.
+  //
+  // With `spanIsFirst`, whatever is first NOW is the block that moved up into
+  // the hole — `blocks[0]`, no search needed. Answers null for a delete that
+  // emptied the document, and for the unreachable "span not found" case, where
+  // guessing a block is worse than restoring no caret at all.
+  function blockLineAfterRemoval(removed) {
+    if (removed.prevLine != null) return removed.prevLine;
+    if (!removed.spanIsFirst) return null;
+    return blocks.length ? blocks[0].startLine : null;
+  }
+
+  async function deleteBlockViaGutterBody(blockEl, anchor) {
     // §3.3's membership rules plus the shared preamble (identity capture,
     // switchAwayFrom(), the re-resolve after a commit that re-rendered, and the
     // no-source-line refusal) — see resolveGutterOperands(). The stake on the
     // re-resolve is highest here: an id shift used to make this delete a
     // DIFFERENT block's lines, with the ⠿ menu the user pressed pointing at a
     // block that survived.
-    const operands = await resolveGutterOperands(blockEl);
+    const operands = await resolveGutterOperands(blockEl, anchor);
     if (!operands) return;
     const els = operands.els;
     const recs = operands.recs;
     const shape = spanListKinds(els);
     if (shape.anyLi && !shape.allLi) { refuseStructuralListEdit(BATCH_MIXED_MESSAGE); return; }
+    // Fix round 1, item 2: the block immediately ABOVE the span, read out of
+    // the PRE-commit `blocks` and carried to the wrapper. It cannot be
+    // recovered afterwards from the hole's coordinate — see
+    // blockLineAfterRemoval()'s own comment for the measurement. `blocks` is in
+    // document order (blockmap.js hands out a positional ordinal), so the
+    // element before recs[0] is that neighbour.
+    //
+    // Located by OBJECT IDENTITY, and the three outcomes are kept apart on
+    // purpose (fix round 2, item 3 — `at > 0` folded the third into the
+    // second and would have landed the caret on the document's first block
+    // with no signal at all):
+    //   at > 0   there is a previous block; its start line is the landing.
+    //   at === 0 the span IS the document's first block — `spanIsFirst` tells
+    //            blockLineAfterRemoval() to take the moved-up fallback.
+    //   at < 0   recs[0] is not in `blocks`. Unreachable as written:
+    //            resolveGutterOperands() builds `recs` from this very array
+    //            (blockRecOf()'s `blocks.find()` for the single case,
+    //            selection.js's membersOf() `blocks.filter()` for the batch —
+    //            both hand back the SAME object references), and nothing
+    //            awaits between its return and this line, so `blocks` cannot
+    //            have been replaced in between. If it ever becomes reachable,
+    //            both flags stay false/null and the wrapper simply restores no
+    //            caret and re-aims the toolbar — a bar-only degrade, never a
+    //            landing on the wrong block.
+    const at = blocks.indexOf(recs[0]);
+    const prevLine = at > 0 ? blocks[at - 1].startLine : null;
+    const spanIsFirst = at === 0;
     // Spec §6, "S1 期間的已知危險" item 1: a LIST ITEM's delete is not a line
     // splice. S1 is what first put a ⠿ on a li, and the plain range removal
     // below corrupts a list three separate ways — see
     // deleteListItemsViaGutter() for the measurements and the routing.
     if (shape.allLi) {
-      await deleteListItemsViaGutter(els);
-      return;
+      return (await deleteListItemsViaGutter(els))
+        ? { prevLine: prevLine, spanIsFirst: spanIsFirst } : undefined;
     }
     // A contiguous span of non-list blocks is one line range: the separators
     // between its members are inside it by construction (members are adjacent
@@ -3421,10 +4790,17 @@
     // inverted range, and §4.4 says a range that no longer resolves clears).
     // Declared immediately before the render, never earlier (Task 5 carry 5).
     declareCollapse(null);
-    const okRender = await safeRerenderAll();
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      return;
     }
+    return { prevLine: prevLine, spanIsFirst: spanIsFirst };
   }
 
   // Spec §6, "S1 期間的已知危險" item 1 — the ⠿ delete of a LIST ITEM.
@@ -3455,19 +4831,24 @@
   // commit the re-serialized survivors over that range with every one of them
   // carried over verbatim — nothing here rewrites any survivor's CONTENT, only
   // its marker and its leading columns.
+  //
+  // v3.2.1: returns commitListStructure()'s own true/false, and false for each
+  // of its three refusal exits — deleteBlockViaGutter()'s wrapper needs to tell
+  // a refusal (nothing was removed, the block is still where it was) apart from
+  // a completed delete before it goes looking for a neighbour.
   async function deleteListItemsViaGutter(liEls) {
     // Every list batch is one run's problem — see batchRunOf().
     const run = batchRunOf(liEls);
-    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return; }
+    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return false; }
     // §4.3's run-wide gate, whose input is §3.4 rule 2's scope — which is
     // exactly what listRunOf() returns (the outermost run PLUS every
     // descendant of its members), so the deeper runs this delete is about to
     // re-indent are covered, not just the target's own. Deleting is NOT
     // column-only: it removes the target's lines outright, so a multi-line
     // target refuses per §4.1 — and in a batch every member is a target.
-    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return; }
+    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return false; }
     const range = runRangeOfBlocks({ lines, blocks, stack }, run);
-    if (!range) return;
+    if (!range) return false;
     // §3.4 rule 3's batch anchor: the SMALLEST old indent in the set, never the
     // first member's — see spanMinIndent().
     const oldIndent = spanMinIndent(liEls);
@@ -3493,7 +4874,7 @@
     // this path is the one it makes after the commit — the `!range` bail above
     // it cannot fire, `presetRange` is non-null by construction here.
     declareCollapse(null);
-    await commitListStructure(survivors, null, false,
+    return await commitListStructure(survivors, null, false,
       { presetRange: range, carryOver: bystanderCarryOver(survivors) });
   }
 
@@ -3715,6 +5096,10 @@
     });
     await commitListStructure(run, null, false,
       { presetRange: range, carryOver: bystanderCarryOver(run) });
+    // v3.2.1 §Task 5: the caller's `focusLine` — the same post-shift line the
+    // collapse just declared, never the pre-commit startLine (the merge
+    // widening above moves it by exactly `shift`).
+    return recs[0].startLine + shift;
   }
 
   // The `data-block-type` a conversion target will carry once it is committed.
@@ -3855,9 +5240,19 @@
     const prevLines = lines;
     lines = result.lines;
     declareCollapse({ startLine: outStart, endLine: outEnd });
-    if (!(await safeRerenderAll())) {
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    if (!(await safeRerenderAll(editRange))) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 §Task 5: the caller's `focusLine` — the converted piece's own
+    // first emitted line, which is what the collapse above declares. The
+    // pre-commit startLine is wrong here: the split rebuilds the run in three
+    // pieces and §4.3 rule 1's blanks move the converted half.
+    return outStart;
   }
 
   // S2 Task 5 — 轉換成 › 項目符號列表 / 編號列表 / 待辦清單 on a block that is
@@ -3912,9 +5307,18 @@
       startLine: merged.startLine,
       endLine: merged.startLine + md.split('\n').length - 1,
     });
-    if (!(await safeRerenderAll())) {
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    if (!(await safeRerenderAll(editRange))) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 §Task 5: the caller's `focusLine` — the WIDENED range's first
+    // line, which is where the merged list actually starts. `recs[0].startLine`
+    // would be wrong whenever §4.3 rule 2 ate a separator above the span.
+    return merged.startLine;
   }
 
   // The `.ed-li-check` chrome for a li that has just BECOME a task item.
@@ -3967,18 +5371,44 @@
       // focus/blur cycle on that same block (click into it, click back out
       // — e.g. after Esc-ing the raw editor) re-armed that same stale DOM
       // and committed it as if it were live content: the "discarded" edit
-      // resurrected itself into `lines`. Restore the pre-edit snapshot
-      // FIRST, mirroring revertBurstAndEnd()'s own contract, so nothing is
-      // left behind for a later burst to accidentally pick up and commit.
-      currentBurst.editEl.innerHTML = currentBurst.original;
-      currentBurst.history.dispose();
+      // resurrected itself into `lines`.
+      // v3.2.1: 先清 currentBurst 再寫 innerHTML。對 TABLE burst，editEl 是
+      // <table> 而聚焦節點是子代 .ed-wys-cell，所以這個寫入會 detach 聚焦的
+      // cell；Chromium 同步派發 focusout，而 focusout 的 table 分支只要
+      // currentBurst 非 null 就會 resolveBurst() 並提交 —— 這顆按鈕的職責是
+      // 丟棄，實測卻把打的字寫進磁碟。revertTableBurstAndEnd() 早就是這個
+      // 順序，而它的註解正是說明「先清 currentBurst」才是它不需要抑制旗標
+      // 的原因；上一版這裡的註解宣稱在鏡像那份契約，實際把它倒過來了。
+      const dyingBurst = currentBurst;
       currentBurst = null;
+      dyingBurst.history.dispose();
+      dyingBurst.editEl.innerHTML = dyingBurst.original;
       resetSelToolbarState();
     } else {
       const ok = await switchAwayFrom();
       if (!ok) return;
     }
-    openRawEditor(blockEl);
+    // v3.1.0 修正 4: which LINES this raw edit owns is now §3.3's membership
+    // question, asked through the same door every other ⠿ operation uses.
+    // resolveGutterOperands() brings the whole shared preamble with it — the
+    // re-resolve after a commit that re-rendered, the no-source-line refusal,
+    // the emptiness and CONTIGUITY gates — which is what makes a span range
+    // safe to take as `recs[0].startLine .. recs[last].endLine`: a disjoint
+    // selection would refuse here rather than quietly swallowing the blocks
+    // sitting in the gap. Its own switchAwayFrom() is a no-op by this point
+    // (the branch above already resolved whatever was open).
+    const operands = await resolveGutterOperands(blockEl);
+    if (!operands) return;
+    const els = operands.els;
+    const recs = operands.recs;
+    const liveBlockEl = els[0];
+    const isLi = liveBlockEl.getAttribute('data-block-type') === 'li';
+    // A single non-li block keeps the pre-v3.1.0 path exactly: no range, so
+    // openRawEditor() uses the block's own record and restores by innerHTML.
+    const range = (recs.length > 1 || isLi)
+      ? { startLine: recs[0].startLine, endLine: recs[recs.length - 1].endLine }
+      : null;
+    await openRawEditor(liveBlockEl, range);
   }
 
   // Starts a burst on `editEl` (a `.ed-wys-armed` content element) — called
@@ -4170,10 +5600,20 @@
       const { md: runMd, unsupported, unsupportedByLi, lineMeta } =
         listMd.serializeBlocks(runEls, { carryOver: carry });
       // Refuse if the EDITED li itself has unsupported inline content.
-      // RULING F-O: do NOT call openRawEditor() on a list block — injecting
-      // a textarea into list structure corrupts list-md serialization and
-      // renders badly. Show banner + teardown + rerenderAll (file is untouched,
-      // burst never wrote to `lines`) + return false.
+      // Show banner + teardown + rerenderAll (file is untouched, burst never
+      // wrote to `lines`) + return false — this path does NOT fall back to
+      // openRawEditor().
+      //
+      // ⚠ v3.1.0 Ruling 13 supersedes RULING F-O for the ⠿ menu's MD 原始碼
+      // (see toggleGutterMenu()), and NOT for this site. Two different
+      // reasons: F-O was about the CONTAINER (a textarea cannot live inside a
+      // serialized run), which 修正 4 answers by restoring through a
+      // re-render; this refusal is about the CONTENT — the run's own
+      // serializer has just reported it cannot round-trip this item, and
+      // silently opening an editor from inside a burst resolution would be a
+      // second, unasked-for gesture on top of a failed one. The banner's
+      // advice ('改用原始碼編輯') is now literally actionable, which it was
+      // not before: the user can reach exactly that through the ⠿ menu.
       const editedIdStr = String(burst.blockId);
       if (unsupportedByLi.some((u) => u.blockId === editedIdStr)) {
         showBanner('含不支援的格式，改用原始碼編輯', null, null);
@@ -4253,7 +5693,12 @@
       }
       const liPrevLines = lines;
       lines = liCommitResult.lines;
-      const liOk = await safeRerenderAll();
+      const editRange = liCommitResult.op
+        ? { startLine: Math.min(liCommitResult.op.startLine, liCommitResult.op.endLine + 1),
+            endLine: Math.max(liCommitResult.op.startLine - 1, liCommitResult.op.endLine),
+            delta: liCommitResult.op.after.length - liCommitResult.op.before.length }
+        : undefined;
+      const liOk = await safeRerenderAll(editRange);
       if (!liOk) {
         lines = rollbackFailedRender({ lines, stack }, liCommitResult, liPrevLines);
         return false;
@@ -4309,7 +5754,12 @@
     }
     const prevLines = lines;
     lines = commitResult.lines;
-    const ok = await safeRerenderAll();
+    const editRange = commitResult.op
+      ? { startLine: Math.min(commitResult.op.startLine, commitResult.op.endLine + 1),
+          endLine: Math.max(commitResult.op.startLine - 1, commitResult.op.endLine),
+          delta: commitResult.op.after.length - commitResult.op.before.length }
+      : undefined;
+    const ok = await safeRerenderAll(editRange);
     if (!ok) {
       lines = rollbackFailedRender({ lines, stack }, commitResult, prevLines);
       // Burst stays open: DOM/history untouched, banner already shown by
@@ -4964,7 +6414,12 @@
     // still sitting there un-committed — re-render anyway so what's on screen
     // is always exactly what's in `lines`.
     if (result.op !== null) lines = result.lines;
-    const ok = await safeRerenderAll();
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const ok = await safeRerenderAll(editRange);
     if (!ok) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
       // Deliberately NOT a second safeRerenderAll(), unlike the two refusals
@@ -5833,7 +7288,12 @@
     // §3.3's collapse: a depth change rewrites no line COUNT, so the set
     // collapses onto the lines it already held.
     declareCollapse({ startLine: first.startLine, endLine: last.endLine });
-    const okRender = await safeRerenderAll();
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
@@ -5866,6 +7326,63 @@
     await changeHeadingDepthsInSpan(els, recs, dir);
   }
 
+  // v3.1.0 §4: the toolbar's ⇥ / ⇤ buttons. A ZERO-ARGUMENT commit wrapper,
+  // placed beside tabSelection(dir) above because it is the same shape of
+  // thing: a gesture that is not a keystroke, driving a mutation whose only
+  // existing entry point wanted a KeyboardEvent.
+  //
+  // Why this function has to exist at all: indentListItem()/outdentListItem()
+  // (further up) only ever write `data-indent` on the DOM and return a
+  // boolean. They never touch `lines`, never push an undo op, never
+  // re-render. Wiring a toolbar button straight to either of them produces a
+  // list that visibly re-indents and then snaps back on the next render, with
+  // the file byte-identical throughout. Everything that makes Tab a real edit
+  // lives in handleLiKeydown()'s Tab branch — the run-wide gate, the mutation
+  // under mutateListRun()'s focusout suppression, the indent clamp, the
+  // bystander carry-over and the one-op commit — so that is what is
+  // reproduced here, in the same order, with `e.shiftKey` replaced by `dir`.
+  //
+  // `caretLiBlock()` is zero-argument (it reads window.getSelection()), which
+  // is what makes an editEl-free wrapper possible: the toolbar has no event
+  // target inside the run, only a live caret — and the caret is the right
+  // answer anyway, since a run has one editable surface per item.
+  //
+  // dir > 0 indents, dir < 0 outdents.
+  async function indentCaretLi(dir) {
+    const li = caretLiBlock();
+    if (!li) return;
+    let run = listRunOf(li);
+    if (!run.length) return;
+    // `columnOnly`: an indent change rewrites nothing but leading columns, so
+    // a hard-wrapped item is allowed to be the target — same reading, and the
+    // same measurement, as the Tab branch this mirrors.
+    if (!listRunSupportsStructuralEdit(run, li, { columnOnly: true })) {
+      refuseStructuralListEdit();
+      return;
+    }
+    const oldIndent = Number(li.getAttribute('data-indent')) || 0;
+    const changed = mutateListRun(() => {
+      if (!(dir < 0 ? outdentListItem(li) : indentListItem(li))) return false;
+      // v3.0.1, carried over VERBATIM and deliberately: the clamp must read a
+      // FRESH listRunOf(li) — taken after the write above — not the
+      // pre-mutation `run` captured outside. indentListItem() can move a
+      // rule-(d) list-start item whose pre-mutation run is `[li]` alone; with
+      // no anchor in the span, applyIndentClamp()'s rule 1 has nothing to
+      // bound the new indent against and clamps it straight back to 0,
+      // silently undoing the write. See handleLiKeydown()'s own copy of this
+      // note for the full derivation.
+      applyIndentClamp(listRunOf(li), li, oldIndent);
+      return true;
+    });
+    if (!changed) return; // at the boundary: nothing mutated, nothing committed
+    run = listRunOf(li);
+    // Column-only: nothing's CONTENT moved, so every block in the span — the
+    // target included — is a bystander whose source bytes come back
+    // untouched. Built once and shared with runLineOfBlock() below.
+    const carry = bystanderCarryOver(run, null);
+    await commitListStructure(run, runLineOfBlock(run, li, carry), true, { carryOver: carry });
+  }
+
   // §3.6's 「Delete 整批刪」, whose 2026-08-31 ruling is that it goes through
   // the SAME batch path as the ⠿ menu's 刪除 and that no second deletion path
   // is written. deleteBlockViaGutter() already resolves §3.3's membership for
@@ -6076,10 +7593,34 @@
         // (/[ \t]+$/) does not, so it would survive into the committed line.
         // Either way the user sees an empty item and must get a bare '-'. Clear
         // the surface under the SAME normalisation the branch condition used —
-        // liSurfaceHoldsNothing() — inside the suppression span (an innerHTML
-        // assignment on the focused node triggers the very same Chromium unfocus
-        // quirk), and only once the outdent above has actually happened, since a
-        // refused press must leave the DOM byte-identical.
+        // liSurfaceHoldsNothing() — and only once the outdent above has
+        // actually happened, since a refused press must leave the DOM
+        // byte-identical.
+        //
+        // ⚠ Final wave, I4. The sentence that stood here said this innerHTML
+        // assignment is itself a reason the write must sit inside
+        // mutateListRun()'s suppression span — "an innerHTML assignment on the
+        // focused node triggers the very same Chromium unfocus quirk". MEASURED
+        // false, and its own premise is the counter-example: `textEl` IS the
+        // focused node, and writing its innerHTML replaces only its SUBTREE —
+        // the element itself is never detached. Control experiment, driven in a
+        // real page: focus a `.ed-li-text`, count focusout on it and on
+        // `document` (capture), then assign `''` — 0 focusout, 0 blur,
+        // `document.activeElement` still that same node, node still in the
+        // document.
+        //
+        // What the span IS for is written at `suppressLiFocusout`'s own
+        // declaration: a structural list key can move, split or REMOVE the
+        // focused block, and Chromium's synchronous unfocus then reaches
+        // resolveBurst() with the run still in its pre-mutation shape. This
+        // assignment is inside the span because it is part of the same
+        // mutation, not because it contributes a focusout of its own.
+        //
+        // No claim is made here about WHICH callee needs it, and deliberately
+        // not about outdentListItem(): that function is attribute-only in this
+        // flat model — it calls setBlockIndent() on the block and its subtree
+        // (`data-indent` + a CSS custom property) and re-parents nothing, so it
+        // is not the answer either.
         const textEl = liTextEl(li);
         if (textEl && liSurfaceHoldsNothing(textEl)) textEl.innerHTML = '';
         return true;
@@ -6832,6 +8373,20 @@
   // (possibly now-stale, post-delete) column/row it came from.
   let teHighlightEls = [];
 
+  // v3.2.1 fix round 1: same idiom as `suppressTableFocusout`/
+  // `suppressLiFocusout` above — a flag set for the exact synchronous-ish
+  // span of one operation that would otherwise be torn down by a listener
+  // reacting to a side effect THAT OPERATION ITSELF triggers. Here:
+  // runCycleAlign()'s `ensureTableBurstOpen()` can call a cell's `.focus()`,
+  // which can scroll the page for real — and the resulting 'scroll' event
+  // is asynchronous relative to the focus() call (measured: it does not
+  // reliably land before runCycleAlign()'s own code resumes after the
+  // `await`), so a plain "check teMenuKind again afterward" re-open would
+  // race it and sometimes miss. onAnyScroll() checks this flag before
+  // calling hideTableEdgeMenu() so the menu's open state is never torn down
+  // in the first place during that span, whichever tick the event lands on.
+  let suppressEdgeMenuAutoHide = false;
+
   function clearEdgeHighlight() {
     // classList.remove() leaves a dangling `class=""` behind on any element
     // the renderer/armEditables() emitted with NO class of its own — a
@@ -7055,14 +8610,84 @@
     const colIndex = teMenuColIndex;
     if (!tableEl || colIndex == null) return;
     // Final-review Finding 6: same live-table swap as runDeleteColumn() above.
-    const liveTableEl = await ensureTableBurstOpen(tableEl);
-    if (!liveTableEl) return;
-    cycleColumnAlign(liveTableEl, colIndex);
-    currentBurst.history.snap('align-col');
-    // Stays open (unlike delete): repeated clicks keep cycling. The
-    // column's cells are the SAME nodes (cycleColumnAlign() only touches
-    // the `style` attribute) so the existing highlight is still valid —
-    // nothing to reposition/rehighlight.
+    // v3.2.1 fix round 1: ensureTableBurstOpen() below can call a cell's
+    // .focus(), which can scroll the page for real — and v3.2.1's onAnyScroll
+    // (this file's module-level scroll listener) calls hideTableEdgeMenu() on
+    // every scroll, which would reset teMenuKind/teMenuTableEl/teMenuColIndex
+    // to null and un-highlight the column, breaking this function's own
+    // "stays open, repeated clicks keep cycling" contract below. Measured
+    // TWICE: (1) a plain "re-check state and re-show if it changed" fix
+    // RACES the resulting 'scroll' event, which is asynchronous relative to
+    // the `.focus()` call and does not reliably land before this function
+    // resumes after the `await` — so suppress the menu's own auto-hide for
+    // this span instead (`suppressEdgeMenuAutoHide`, see its own comment).
+    // (2) clearing that suppression in a plain `finally` right after the
+    // `await` ALSO raced it — the pending 'scroll' event can land AFTER this
+    // function has already resumed and cleared the flag, since a
+    // `focus()`-triggered scroll is not guaranteed to be delivered within
+    // the same microtask turn as the promise chain above. Measured fix:
+    // browsers dispatch a pending scroll before the next
+    // requestAnimationFrame callback runs (it is part of the "update the
+    // rendering" steps that precede rAF callbacks in the same frame), so
+    // holding the flag through one rAF tick lets a pending scroll land AND
+    // be swallowed before this lifts it.
+    let liveTableEl;
+    suppressEdgeMenuAutoHide = true;
+    try {
+      liveTableEl = await ensureTableBurstOpen(tableEl);
+      if (!liveTableEl) { suppressEdgeMenuAutoHide = false; return; }
+      cycleColumnAlign(liveTableEl, colIndex);
+      currentBurst.history.snap('align-col');
+    } catch (e) {
+      suppressEdgeMenuAutoHide = false;
+      throw e;
+    }
+    requestAnimationFrame(() => {
+      suppressEdgeMenuAutoHide = false;
+      // Fix round 2 (Important, caught by the re-reviewer): suppressing
+      // hideTableEdgeMenu() only stops onAnyScroll from closing the menu —
+      // it does NOT stop `ensureTableBurstOpen()`'s own `switchAwayFrom()`
+      // from closing it for an UNRELATED, legitimate reason when a burst was
+      // open on a DIFFERENT block: switchAwayFrom() -> resolveBurst() ->
+      // hideTableEdgeMenu() (unconditional, not suppressed — only
+      // onAnyScroll's call is gated) nulls teMenuKind/teMenuTableEl/
+      // teMenuColIndex and clears the highlight. Without this guard the
+      // unconditional reposition below would then make that CORRECTLY-
+      // closed menu visible again — empty of highlight, and inert (its own
+      // teMenuKind/teMenuColIndex are null, so a second 對齊/刪除欄 click
+      // reads no target and does nothing) — floating over the document
+      // until the next scroll happens to close it for an unrelated reason.
+      // Only reposition when the menu is STILL the one this call opened:
+      // same kind, same column, and the table identity matches EITHER
+      // `tableEl` (showColumnMenu() was called with this — the pre-swap
+      // identity, read from its own definition above — and nothing since
+      // has touched teMenuTableEl) or `liveTableEl` (belt-and-braces, in
+      // case some future path re-opens the menu against the live node).
+      if (teMenuKind !== 'col' || teMenuColIndex !== colIndex ||
+          (teMenuTableEl !== liveTableEl && teMenuTableEl !== tableEl)) return;
+      // Stays open (unlike delete) UNLESS ensureTableBurstOpen()'s
+      // switchAwayFrom() legitimately closed it above (guard just above) —
+      // repeated clicks keep cycling. The column's cells are the SAME nodes
+      // (cycleColumnAlign() only touches the `style` attribute) so the
+      // existing highlight is still valid — nothing to rehighlight.
+      // `.ed-te-menu` is `position: fixed` (viewport-relative) though, so if
+      // the suppressed span above actually scrolled the page, its left/top
+      // are now stale relative to the header cell; reposition on every call
+      // that gets past the identity guard three lines up (same math as
+      // showColumnMenu(), skipping its toggle-closed branch — that branch would
+      // wrongly close a menu that never actually asked to close). Final wave,
+      // M1: "unconditionally" is what this said before that guard was added,
+      // and it stopped being true then — a call whose menu is no longer the one
+      // it opened returns above and repositions nothing. A no-op scroll makes
+      // this a no-op reposition (same numbers back).
+      const headerRow = headerRowOf(liveTableEl);
+      const cell = headerRow ? headerRow.cells[colIndex] : null;
+      if (cell) {
+        const r = cell.getBoundingClientRect();
+        positionTeMenu(r.left, r.top);
+        teEdgeMenu.style.top = (r.top - teEdgeMenu.offsetHeight - TE_MENU_GAP_PX) + 'px';
+      }
+    });
   }
 
   // ── Notion-style row/column grip handles ─────────────────────────────
@@ -8313,7 +9938,12 @@
     // (blockSelection)` guard is what stops this single-block gesture from
     // INVENTING a selection when none was standing.
     declareCollapse(result.newRange);
-    const okRender = await safeRerenderAll();
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
@@ -8912,16 +10542,40 @@
   // same way activateCell() used to — brief: "wire your cell edit root the
   // same way paragraph editing does (reuse, don't fork)").
   function onSelectionChangeForToolbar() {
-    const sel = window.getSelection();
-    if (!sel || sel.rangeCount === 0 || sel.isCollapsed) { hideSelToolbar(); return; }
-    const range = sel.getRangeAt(0);
-    if (!selToolbarEditEl ||
-        !selToolbarEditEl.contains(range.startContainer) ||
-        !selToolbarEditEl.contains(range.endContainer)) {
-      hideSelToolbar();
-      return;
+    // v3.1.0: the fixed toolbar's five inline-format buttons enable/disable on
+    // exactly the same question this listener already answers ("is there a
+    // non-collapsed selection inside `selToolbarEditEl`?"), so it piggybacks
+    // here instead of attaching a SECOND document-level selectionchange
+    // listener.
+    //
+    // That is not just tidiness. test/editor-client-runtime.test.js
+    // instruments document.addEventListener for this exact type and asserts
+    // the live count is 1 during a session and 0 after — the property being
+    // that a burst's listener is removed on rerender and never stacks. A
+    // permanent second listener would not leak or stack, but it would move
+    // that counter's baseline and force three numeric assertions plus a
+    // waitForFunction(count === 0) to be rewritten around it, weakening a
+    // leak guard to accommodate a convenience. Reusing this one keeps the
+    // guard exactly as written, and is also strictly more correct: with no
+    // burst open `selToolbarEditEl` is null, so `hasSelection` is false —
+    // which is precisely when this listener is not attached.
+    try {
+      const selNow = window.getSelection();
+      if (!selNow || selNow.rangeCount === 0 || selNow.isCollapsed) { hideSelToolbar(); return; }
+      const range = selNow.getRangeAt(0);
+      if (!selToolbarEditEl ||
+          !selToolbarEditEl.contains(range.startContainer) ||
+          !selToolbarEditEl.contains(range.endContainer)) {
+        hideSelToolbar();
+        return;
+      }
+      positionSelToolbar(range);
+    } finally {
+      // In a `finally` so every early return above still refreshes the bar —
+      // the collapse-to-caret exits are exactly the ones that must turn the
+      // mark buttons back off.
+      updateToolbar();
     }
-    positionSelToolbar(range);
   }
 
   // Nearest ancestor of `node` (inclusive) with tagName `tag`, stopping at
@@ -8976,6 +10630,56 @@
     return r;
   }
 
+  // v3.2.1: 在字元空間修剪 Range 的前後空白，再交給 wrapRangeIn()。
+  // 不用 startOffset/endOffset 步進：當邊界容器是【元素節點】時那些 offset
+  // 索引的是【子節點】而非字元，一次遞減會跳過整個文字節點。實測人類拖曳
+  // 選取 105 次都不會產生元素邊界，但編輯器自己的 reselectAndReposition() 會。
+  function trimRangeToText(range) {
+    const parts = [];
+    const take = (n) => {
+      const len = n.data.length;
+      let a, b;
+      try { a = range.comparePoint(n, 0); b = range.comparePoint(n, len); }
+      catch (e) { return; }
+      if (b < 0 || a > 0) return;                 // 整個節點落在範圍外
+      const from = (n === range.startContainer && n.nodeType === 3) ? range.startOffset : 0;
+      const to = (n === range.endContainer && n.nodeType === 3) ? range.endOffset : len;
+      if (to > from) parts.push({ n: n, from: from, to: to });
+    };
+    const root = range.commonAncestorContainer;
+    const walk = (node) => {
+      if (node.nodeType === 3) { take(node); return; }
+      for (let c = node.firstChild; c; c = c.nextSibling) walk(c);
+    };
+    // v3.2.1 review: root.nodeType === 3 的情況已經由 walk() 自己的
+    // `node.nodeType === 3` 分支正確處理（single-text-node 選取時
+    // startContainer/endContainer 必為同一個 text node，也就是這裡的
+    // root——take() 的 `n === range.startContainer`／`n === range.endContainer`
+    // 判斷照樣成立）。原本 `root.nodeType === 3 ? root : root` 兩支完全相同，
+    // 是無效的死碼，這裡直接呼叫 walk(root)；journey 測試（選取整個落在單一
+    // text node 內）已驗證這條路徑產出正確的 from/to。
+    walk(root);
+    if (!parts.length) return false;
+    // 從頭砍掉空白
+    while (parts.length) {
+      const p = parts[0];
+      while (p.from < p.to && /\s/.test(p.n.data[p.from])) p.from++;
+      if (p.from < p.to) break;
+      parts.shift();
+    }
+    // 從尾砍掉空白
+    while (parts.length) {
+      const p = parts[parts.length - 1];
+      while (p.to > p.from && /\s/.test(p.n.data[p.to - 1])) p.to--;
+      if (p.to > p.from) break;
+      parts.pop();
+    }
+    if (!parts.length) return false;              // 全空白選取 → 不包裝
+    range.setStart(parts[0].n, parts[0].from);
+    range.setEnd(parts[parts.length - 1].n, parts[parts.length - 1].to);
+    return true;
+  }
+
   // Marks of `tag` that the range overlaps (fully or partially) — called
   // only AFTER wholeSelectionMark() has already returned null, so any hit
   // here is by construction a partial-overlap case (see the toggle-policy
@@ -9039,26 +10743,190 @@
       snapBurstIfActive(root, 'mark');
       return;
     }
+    if (!trimRangeToText(range)) return;   // 全空白／collapsed 選取：no-op
     reselectAndReposition(wrapRangeIn(range, tag));
     snapBurstIfActive(root, 'mark');
   }
 
+  // Resolves once a `focusout` has been dispatched at `el` AND that dispatch
+  // has fully finished, or after `ms` milliseconds if no focusout arrives at
+  // all — whichever comes first.
+  //
+  // Two things about it are load-bearing and both were measured on the 🔗
+  // gesture:
+  //
+  //  * The wait is needed because the blur a native modal causes is delivered
+  //    on the browser's own schedule, NOT as a task queued by the code that
+  //    opened the modal: window.prompt() returned at t=27ms and the focusout
+  //    landed at t=28ms, i.e. after the caller had already returned. So a plain
+  //    setTimeout(0) is not a substitute for listening.
+  //  * The resolve is handed to a TIMER rather than called from the listener.
+  //    A listener's own resolve() only queues a microtask, and the HTML spec
+  //    performs a microtask checkpoint after EACH listener callback of a
+  //    browser-initiated dispatch — so an awaiter resumed from there runs
+  //    BEFORE the document-level focusout delegator further along the same
+  //    propagation path, and therefore before anything that delegator starts
+  //    exists to be waited on. Measured exactly that way: resolving from the
+  //    listener left `switching` still null at the awaiter, and the caret was
+  //    lost to the render that followed. A timer moves the resume to the next
+  //    task, after the whole dispatch.
+  function nextFocusout(el, ms) {
+    return new Promise((resolve) => {
+      let deadline = null;
+      const finish = () => {
+        el.removeEventListener('focusout', onFocusout);
+        if (deadline !== null) { clearTimeout(deadline); deadline = null; }
+        resolve();
+      };
+      const onFocusout = () => { setTimeout(finish, 0); };
+      el.addEventListener('focusout', onFocusout);
+      deadline = setTimeout(finish, ms);
+    });
+  }
+
+  // v3.2.1: THIN WRAPPER over the toggle body below, same shape as
+  // convertBlockViaMenu() — but the restoration cannot sit in a plain
+  // synchronous finally here, and that is the whole difference. MEASURED, with
+  // an in-page focus/mutation trace on the 🔗 button:
+  //
+  //   t=21ms  window.prompt() entered      t=27ms  prompt() returned
+  //   t=28ms  focusout on the armed surface (the modal's own blur, delivered
+  //           after the body had already finished its DOM surgery)
+  //   t=31ms  focusin — the browser hands focus straight back
+  //   t=52ms  a SECOND focusout, this one from applyFullRender() (captured
+  //           stack: applyFullRender <- applyRenderResult <- rerenderAll)
+  //   t=66ms  document.activeElement === BODY, toolbar down to 4 buttons
+  //
+  // So the thing that costs the user their foothold is not the modal: focus
+  // comes back on its own. It is that the document's focusout delegator read
+  // the modal's blur as "the user left this surface" and ran switchAwayFrom()
+  // -> resolveBurst() -> commitEdit() -> rerenderAll(), and that render
+  // replaced the whole .content subtree the restored focus was sitting in.
+  // The other four inline-format buttons (toolbar-model.js's `group: 'inline'`
+  // is bold / italic / strike / inline-code / link — five, of which link is
+  // this one) never hit this, because none of them opens a modal and so none
+  // of them ever blurs.
+  //
+  // The two awaits below are therefore each waiting for one specific thing:
+  // nextFocusout() for that blur to be dispatched at all, and `switching` for
+  // the commit + render it started to finish. Only then is there a live block
+  // to aim at.
+  async function applyLinkToggle() {
+    const root = selToolbarEditEl;
+    const sel = typeof window.getSelection === 'function' ? window.getSelection() : null;
+    // hasFormattableSelection() is the body's own four guards spelled once (see
+    // its comment). When it is false the body returns before it can reach
+    // window.prompt(), so there is no modal, no blur, and nothing to wait for.
+    // Waiting anyway would stall this call for the whole timeout and then move
+    // the caret to the end of a block the user never edited.
+    //
+    // ⚠ Final wave, I3. `willPrompt` is a NECESSARY condition for a modal, not
+    // a sufficient one, and the sentence that used to stand at the restore
+    // said otherwise. Those four guards do match the body's four, but the body
+    // has a FIFTH pre-prompt exit they know nothing about: the
+    // `overlapping.length > 0` branch, where a selection that only PARTIALLY
+    // overlaps an existing link unwraps it and returns without ever calling
+    // window.prompt(). MEASURED on ddac6ce — selecting `lpha lin` across
+    // `Alpha <a>linked</a> …` and clicking 🔗 gave `dialogs: 0` while
+    // `willPrompt` was true. Behaviour was still correct there, but only
+    // because the `stillHeld` gate below happened to catch it; the guarantee
+    // the comment claimed did not exist. So the body now REPORTS whether it
+    // prompted and the wait is gated on that report rather than on the
+    // prediction. `blurred` still has to be ARMED before the body runs (the
+    // blur it waits for is caused from inside it) — an armed-but-unused
+    // promise settles on its own 400ms timeout, which removes its own listener
+    // and resolves nobody.
+    const willPrompt = hasFormattableSelection(sel);
+    // Captured BEFORE the body: `selToolbarEditEl` is one of the things the
+    // render nulls. The LINE survives that render — resolveBurst() commits
+    // through commitEdit(state, burst.blockId, newText), an in-place replace of
+    // this block's own line range, and ops.shiftBlocks() only shifts blocks
+    // whose id is GREATER than the edited one, so nothing can move this block's
+    // own start line.
+    const rec = willPrompt && root && root.closest
+      ? blockRecOf(root.closest('.ed-block')) : null;
+    const line = rec ? rec.startLine : null;
+    // Armed before the body runs, because the blur it is waiting for is caused
+    // by a call inside the body. The timeout is the fallback for a browser that
+    // does not blur on a modal at all; its cost when it fires is one caret
+    // moved to the end of the block the link was just written into.
+    const blurred = willPrompt && root ? nextFocusout(root, 400) : null;
+    let prompted = false;
+    try {
+      prompted = applyLinkToggleBody() === true;
+    } finally {
+      if (blurred && prompted) {
+        await blurred;
+        if (switching) await switching;
+        // Fix round 1, item 1: reaching here means the modal DID open (the
+        // body said so), not that the user confirmed it. On Esc / cancel the body does no DOM
+        // surgery, the burst goes out through endBurstWithoutResolve(), there
+        // is no commit and no render — and the focus the modal took comes back
+        // by itself (the t=31ms focusin in the trace above). Restoring on top
+        // of that collapses the user's selection to a caret at the block's end.
+        // Driven, 🔗 then Esc: with this gate the selection is still 'Alpha'
+        // (non-collapsed, 20 buttons); without it, '' and collapsed.
+        //
+        // So the restore only fires when the foothold is actually GONE. The
+        // accept path is unaffected — the render has just run and
+        // activeElement is BODY there — and a 400ms timeout misfire becomes
+        // harmless for the same reason.
+        const held = document.activeElement;
+        const stillHeld = held && held.closest &&
+          held.closest('.ed-wys-armed, .ed-wys-cell, .ed-raw');
+        // 有 blockSelection 站著時什麼都不做 —— 與 convertBlockViaMenu() 同一個
+        // 判準、同一個理由：強行還原 caret 會做出「底色仍說已選取、Delete 卻是
+        // 死鍵」的混種狀態。
+        if (!stillHeld && !blockSelection && line != null) {
+          focusBlockAtLine(line, true);   // caretToEnd
+        }
+        // ⚠ C1, second occurrence of the same root cause. The re-aim used to
+        // sit INSIDE the `!stillHeld` branch, so a call that kept its foothold
+        // restored nothing at all — and on the PATCH render path (every commit
+        // after a page load's first) applyPatch() hands focus back to the new
+        // surface and only THEN runs resetToolbarBlock(), so "foothold held"
+        // and "bar collapsed to 4" are the ordinary combination, not a
+        // contradiction. Measured, 🔗 accept: unprimed P.ed-wys-armed/15,
+        // primed P.ed-wys-armed/4. The caret restore stays gated (fix round
+        // 1's Esc/cancel finding); only the bar comes out.
+        if (!blockSelection && line != null) {
+          // 就【這個還原目前所攜帶的座標】（一個 block 的起始行）而言，TABLE
+          // 儲存格是還原不回 caret 的形狀：`root` 是 CELL，但 `line` 只能指到
+          // 整張表這個 block，而 blockContentEl() 對 table 回傳
+          // firstElementChild ＝ <table> 本身，它沒有 tabindex、focus() 是
+          // no-op。實測結果因此是 journey 的 bar-only 形狀（V2d 釘住）：連結
+          // 正確寫進磁碟、工具列 15 顆仍瞄著那張表，但 activeElement 是 BODY。
+          // 這不是死路 —— 儲存格的 (row, col) 在 re-render 之間是穩定的，帶著
+          // 它就能還原；只是本版沒有帶。reaim 是目前這個形狀下唯一還拿得回來
+          // 的東西 —— 沒有它工具列會塌成 4 顆。
+          reaimToolbarBlockAtLine(line);
+        }
+      }
+    }
+  }
+
   // Link is its own entry point (not applyMarkToggle) because "unwrap" here
   // means "prompt to edit or clear the URL", and "wrap" means "prompt for a
   // URL first" — both need window.prompt() before any DOM surgery happens.
-  function applyLinkToggle() {
+  //
+  // Final wave, I3: returns TRUE iff this call actually reached a
+  // window.prompt(), and false on every exit that did not — the four guards at
+  // the top AND the partial-overlap unwrap in the middle, which is the one the
+  // wrapper's `willPrompt` prediction cannot see. The wrapper waits for the
+  // modal's blur only on a true.
+  function applyLinkToggleBody() {
     const root = selToolbarEditEl;
-    if (!root) return;
+    if (!root) return false;
     const sel = window.getSelection();
-    if (!sel.rangeCount) return;
+    if (!sel.rangeCount) return false;
     const range = sel.getRangeAt(0);
-    if (range.collapsed) return;
-    if (!root.contains(range.startContainer) || !root.contains(range.endContainer)) return;
+    if (range.collapsed) return false;
+    if (!root.contains(range.startContainer) || !root.contains(range.endContainer)) return false;
 
     const whole = wholeSelectionMark(range, 'A', root);
     if (whole) {
       const url = window.prompt('連結網址（留空以移除連結）：', whole.getAttribute('href') || '');
-      if (url === null) return; // cancelled — leave the link untouched
+      if (url === null) return true; // cancelled — leave the link untouched
       if (url.trim() === '') {
         reselectAndReposition(unwrapElement(whole));
       } else {
@@ -9066,7 +10934,7 @@
         reselectAndReposition(range);
       }
       snapBurstIfActive(root, 'mark');
-      return;
+      return true;
     }
     const overlapping = overlappingMarks(range, 'A', root);
     if (overlapping.length > 0) {
@@ -9074,10 +10942,10 @@
       overlappingMarks(extended, 'A', root).forEach((m) => unwrapElement(m));
       reselectAndReposition(extended);
       snapBurstIfActive(root, 'mark');
-      return;
+      return false;   // unwrapped in place — no modal ever opened
     }
     const url = window.prompt('連結網址：', 'https://');
-    if (url === null || url.trim() === '') return; // cancelled or empty — no-op
+    if (url === null || url.trim() === '') return true; // cancelled or empty — no-op
     const el = document.createElement('a');
     el.setAttribute('href', url.trim());
     el.appendChild(range.extractContents());
@@ -9086,6 +10954,7 @@
     r.selectNodeContents(el);
     reselectAndReposition(r);
     snapBurstIfActive(root, 'mark');
+    return true;
   }
 
   function buildSelToolbar() {
@@ -9128,7 +10997,14 @@
   // `position: fixed`.
   function positionSelToolbar(range) {
     const rect = range.getBoundingClientRect();
-    if (rect.width === 0 && rect.height === 0) { hideSelToolbar(); return; }
+    // v3.2.1: 原本的零矩形檢查是死碼 —— 實測捲出視野的 Range 仍保有
+    // 151x17 的矩形，永遠到不了這一支。改成真正的視窗外檢查。
+    const topInset = parseFloat(getComputedStyle(document.documentElement)
+      .getPropertyValue('--ed-toolbar-h')) || 0;
+    if (rect.bottom <= topInset || rect.top >= window.innerHeight ||
+        rect.right <= 0 || rect.left >= window.innerWidth) {
+      hideSelToolbar(); return;
+    }
     if (!selToolbar.parentNode) document.body.appendChild(selToolbar);
     const gap = 8, margin = 4;
     const tbRect = selToolbar.getBoundingClientRect();
@@ -9413,7 +11289,28 @@
     // DECLARED rather than cleared outright so the rollback below leaves a
     // standing selection alone when the render fails.
     declareSelectionRange(null);
-    const ok = await safeRerenderAll();
+    // v3.2.0: UndoStack.undo()/discardTop() reverse the op when applying it but
+    // return the unmodified FORWARD op, so the range actually rewritten is
+    // [op.startLine, op.startLine + op.after.length - 1] and the delta is the
+    // mirror of the forward one. Using op.endLine here would name the opposite
+    // direction — the span the op wrote on the way FORWARD, not the one this
+    // reversal just rewrote.
+    //
+    // Final review item 4 — what naming it wrongly would cost today: nothing.
+    // Per 決議 4(b) `editRange` is ADVISORY. patchmap() destructures
+    // oldBlocks/newBlocks/oldParts/newParts and never reads it; the kept
+    // prefix/suffix is the longest common run of the two PART arrays, and
+    // seeding it from an op's line range only ever made the answer worse
+    // (measured in 決議 4(b): seeded kept 0 of 5, pure-parts kept 4 of 5).
+    // Its one client-side use is the truthiness gate in applyRenderResult().
+    // So the direction changes no plan — this is simply the correct value for
+    // whenever something does start reading it.
+    const editRange = r.op
+      ? { startLine: r.op.startLine,
+          endLine: r.op.startLine + r.op.after.length - 1,
+          delta: r.op.before.length - r.op.after.length }
+      : undefined;
+    const ok = await safeRerenderAll(editRange);
     if (!ok) {
       // Reverse the undo attempt: push the op back and restore `lines` to
       // what was on screen before this undo was requested.
@@ -9429,7 +11326,15 @@
     if (!r) return;
     lines = r.lines;
     declareSelectionRange(null); // §4.4, same as undo() above
-    const ok = await safeRerenderAll();
+    // redo() is NOT reversed — it goes through
+    // replaceLines(lines, op.startLine, op.endLine, op.after), so the
+    // ordinary forward formula applies here, unlike undo() above.
+    const editRange = r.op
+      ? { startLine: Math.min(r.op.startLine, r.op.endLine + 1),
+          endLine: Math.max(r.op.startLine - 1, r.op.endLine),
+          delta: r.op.after.length - r.op.before.length }
+      : undefined;
+    const ok = await safeRerenderAll(editRange);
     if (!ok) {
       // Reverse the redo attempt: pop the op back off and restore `lines`.
       const rollback = stack.undo(lines);
@@ -9437,6 +11342,954 @@
     }
   }
 
+  // ── 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
+  // 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
+  // exists to prevent.
+  //
+  // EVERY existing entry point stays: the ⠿ menu, the ＋ menu and the
+  // floating selection toolbar are untouched. This is one more road to the
+  // same operations, not a replacement for any of them.
+  let toolbarEl = null;
+  let toolbarBtns = null;   // { [buttonId]: HTMLButtonElement }
+  let toolbarMenuEl = null; // the H▾ dropdown panel, or null when closed
+  let toolbarBlockEl = null;
+  let toolbarStateSig = '';
+  // 追加 4's document mode: 'edit' | 'source'. v3.2.1 removed the third
+  // state ('preview'); docsource.js's MODES comment records why.
+  // docsource.js owns the cycle order and the lines[]<->string conversion.
+  let docMode = 'edit';
+  let sourceTextarea = null;
+  let sourceBaseLines = null;
+  // 追加 2: Ctrl+Shift+V arms a plain-text-only paste for the NEXT paste
+  // event. A ClipboardEvent carries no modifier state of its own, so the
+  // 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_NO_ANCHOR_MESSAGE = '找不到可以插入圖片的位置';
+
+  // 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
+  // idiom .ed-seltb-b/-i/-s use.
+  const TOOLBAR_BTN_CLASS = {
+    bold: 'ed-toolbar-b', italic: 'ed-toolbar-i', strike: 'ed-toolbar-s',
+  };
+
+  // The buttons whose model state can ever report `active: true` — i.e. the
+  // real toggles, and the only ones that may carry aria-pressed. Every other
+  // button is a command, not a toggle.
+  // v3.2.0: derived, not mirrored. A seventh toggle added to toolbar-model.js
+  // used to need a matching edit here, and forgetting it made aria-pressed lie.
+  const TOOLBAR_TOGGLE_IDS = new Set(
+    (toolbarModel ? toolbarModel.BUTTONS : []).filter((b) => b.toggle).map((b) => b.id));
+
+  // The block the bar currently reports on, or null. `null` is the model's
+  // documented no-block state (undo/redo/outline/preview live, everything
+  // else greyed), which is exactly what rerenderAll()'s teardown wants — see
+  // resetToolbarBlock() below.
+  function liveToolbarBlock() {
+    if (toolbarBlockEl && document.body.contains(toolbarBlockEl)) return toolbarBlockEl;
+    toolbarBlockEl = null;
+    return null;
+  }
+
+  // Called from rerenderAll()'s belt-and-braces teardown. A detached node's
+  // getAttribute() still answers, so a tracked block that survived the
+  // .content swap would keep the bar reporting a block no click can reach.
+  function resetToolbarBlock() {
+    toolbarBlockEl = null;
+    closeToolbarMenu();
+    updateToolbar();
+  }
+
+  // v3.2.1: point the bar back at the block a structural op just produced.
+  //
+  // rerenderAll()'s teardown calls resetToolbarBlock() (toolbarBlockEl = null,
+  // bar repainted in its no-block state: 4 enabled buttons), and nothing
+  // re-points it unless a focusin/click lands on a block. That is fine when
+  // the op ends with focusBlockAtLine() — the surface's focus event runs
+  // wireToolbarTracking()'s focusin handler, which does exactly this. It is
+  // NOT fine for a target with no focusable surface (quote / code / hr), where
+  // focusBlockAtLine() silently no-ops and the bar would stay collapsed on a
+  // block that is right there on screen. updateToolbar() is what repaints;
+  // resetToolbarBlock() is idempotent, so re-pointing after it is safe.
+  // Resolves nothing and touches nothing when `line` is null or the block is
+  // gone (a refusal, a rolled-back render).
+  function reaimToolbarBlockAtLine(line) {
+    if (line == null) return;
+    const target = blocks.find((b) => b.startLine === line);
+    if (!target) return;
+    const blockEl = document.querySelector('.ed-block[data-block-id="' + target.id + '"]');
+    if (!blockEl) return;
+    toolbarBlockEl = blockEl;
+    updateToolbar();
+  }
+
+  // Final review item 5: the EXACT predicate applyMarkToggle() and
+  // applyLinkToggle() gate on — all four of their conditions, not three.
+  // Kept as one function so the toolbar's enablement and the actions' own
+  // refusal cannot drift apart: whenever this says true, both actions run.
+  //
+  // The fourth condition (containment) is the one `hasSelection` used to
+  // omit, and it is reachable: a drag-select that STARTS inside an open
+  // burst and ENDS in the next block leaves the selection non-collapsed with
+  // `selToolbarEditEl` still set. The floating selection toolbar already
+  // asks this same question of itself and correctly hides (see its
+  // selectionchange listener above), but updateToolbar() still ran and lit
+  // the five inline-format buttons over a selection every one of them
+  // silently refuses — precisely the dead-button failure this version's
+  // enablement wiring exists to remove.
+  function hasFormattableSelection(sel) {
+    if (!selToolbarEditEl || !sel || sel.rangeCount === 0 || sel.isCollapsed) return false;
+    const range = sel.getRangeAt(0);
+    if (range.collapsed) return false;
+    return selToolbarEditEl.contains(range.startContainer) &&
+      selToolbarEditEl.contains(range.endContainer);
+  }
+
+  // ctx for toolbarModel.deriveState(). Every field is read off the DOM /
+  // `lines` at call time; nothing is cached, so a stale value cannot outlive
+  // a render.
+  function toolbarContext() {
+    const blockEl = liveToolbarBlock();
+    const blockType = blockEl ? blockEl.getAttribute('data-block-type') : null;
+    let headingDepth = 1;
+    if (blockType === 'heading') {
+      const rec = blockRecOf(blockEl);
+      if (rec && rec.endLine >= rec.startLine) headingDepth = headingDepthOf(lines[rec.startLine - 1]);
+    }
+    const sel = typeof window.getSelection === 'function' ? window.getSelection() : null;
+    return {
+      blockType: blockType,
+      indent: blockEl ? (Number(blockEl.getAttribute('data-indent')) || 0) : 0,
+      headingDepth: headingDepth,
+      inList: blockType === 'li',
+      listOrdered: !!blockEl && blockEl.getAttribute('data-list-type') === 'ol',
+      // The mark buttons act through applyMarkToggle()/applyLinkToggle();
+      // hasFormattableSelection() (just above) is their refusal test spelled
+      // once, rather than a looser "is anything selected anywhere on the page".
+      hasSelection: hasFormattableSelection(sel),
+      mode: docMode,
+    };
+  }
+
+  function updateToolbar() {
+    if (!toolbarEl || !toolbarBtns || !toolbarModel) return;
+    const state = toolbarModel.deriveState(toolbarContext());
+    // selectionchange fires on every caret move, so the state is diffed
+    // before any DOM is written — 22 attribute writes per keystroke is a
+    // cost with no matching benefit.
+    const sig = JSON.stringify(state);
+    if (sig === toolbarStateSig) return;
+    toolbarStateSig = sig;
+    Object.keys(toolbarBtns).forEach((id) => {
+      const st = state[id];
+      const btn = toolbarBtns[id];
+      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`
+      // 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)) {
+        btn.setAttribute('aria-pressed', st.active ? 'true' : 'false');
+      }
+      // `headings` (H / H1..H6) and, since v3.2.1, the mode button carry a
+      // derived label; every other button keeps the glyph it was built with.
+      if (typeof st.label === 'string') btn.textContent = st.label;
+      // v3.2.1: a per-mode title CANNOT be baked in buildToolbar() — the mode
+      // button's title names the NEXT state, so it has to be rewritten every
+      // time the mode changes. It rides the same diffed loop as everything
+      // else: `title` is part of the state object, therefore part of `sig`.
+      if (typeof st.title === 'string') {
+        btn.title = st.title;
+        btn.setAttribute('aria-label', st.title);
+      }
+    });
+  }
+
+  function buildToolbar() {
+    const bar = document.createElement('div');
+    bar.className = 'ed-toolbar';
+    bar.setAttribute('role', 'toolbar');
+    bar.setAttribute('aria-label', '編輯工具列');
+    const btns = {};
+    let prevGroup = null;
+    toolbarModel.BUTTONS.forEach((def) => {
+      // GROUPS order doubles as separator placement: one divider wherever
+      // consecutive buttons change group.
+      if (prevGroup !== null && def.group !== prevGroup) {
+        const sep = document.createElement('span');
+        sep.className = 'ed-toolbar-sep';
+        bar.appendChild(sep);
+      }
+      prevGroup = def.group;
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'ed-toolbar-btn' +
+        (TOOLBAR_BTN_CLASS[def.id] ? ' ' + TOOLBAR_BTN_CLASS[def.id] : '');
+      btn.textContent = def.icon;
+      btn.title = def.title;
+      btn.setAttribute('aria-label', def.title);
+      btn.setAttribute('data-ed-tb', def.id);
+      // Not a tab stop, same as the ⠿ / ＋ gutter buttons: this is chrome,
+      // and the Tab key belongs to the document's own structure.
+      btn.setAttribute('tabindex', '-1');
+      // ⚠ LOAD-BEARING, not a nicety. Without it the five inline-format
+      // buttons are dead on arrival: a <button> taking focus on mousedown
+      // fires the armed surface's focusout, which commits and re-renders,
+      // so applyMarkToggle()'s `selToolbarEditEl` is null and the selection
+      // is gone before the click handler ever runs. buildSelToolbar() and
+      // both table grip builders defend themselves the identical way.
+      btn.addEventListener('mousedown', (e) => e.preventDefault());
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        Promise.resolve(runToolbarAction(def.id, btn)).catch(() => {}).then(updateToolbar);
+      });
+      bar.appendChild(btn);
+      btns[def.id] = btn;
+    });
+    // Fix round 1, item 3: a click on a DISABLED toolbar button used to take
+    // the caret with it — the same gesture and the same symptom this release
+    // exists for. MEASURED, and the two halves matter separately:
+    //
+    //  * `mousedown` and `click` are NOT dispatched at all for a disabled
+    //    <button> — 0 of each at a capture-phase listener on `document`, for
+    //    the whole propagation path, so the per-button mousedown
+    //    preventDefault() a few lines above cannot run and neither could one
+    //    on this container.
+    //  * `pointerdown` IS dispatched (1 at that same document listener) and is
+    //    cancellable, and cancelling it suppresses the compatibility mousedown
+    //    together with its default action — which is the focus move.
+    //
+    // Driven, caret in a paragraph, clicking the disabled 🅑: without this
+    // handler activeElement was BODY in both the untouched-burst state (bar
+    // still 15) and the typed-in state (bar down to 4, because that focusout
+    // ran a full commit + render); with it, P.ed-wys-armed / 15 in both.
+    //
+    // Scope: capture phase on the bar, and preventDefault() ONLY when the
+    // press resolves to a disabled button. Never stopPropagation() — the
+    // document-level pointerdown delegator (table grips, ⠿ block drag, block
+    // selection) still sees the event, and finds nothing to arm, exactly as
+    // before. An ENABLED button, a separator, the status slot and the bar's
+    // own background are all untouched. The H▾ dropdown is NOT inside this
+    // subtree (toggleToolbarHeadingMenu() appends it to document.body), so it
+    // is out of reach here and keeps its own per-item mousedown handler.
+    bar.addEventListener('pointerdown', (e) => {
+      const pressed = e.target && e.target.closest ? e.target.closest('button') : null;
+      if (pressed && pressed.disabled) e.preventDefault();
+    }, true);
+    toolbarBtns = btns;
+    // v3.1.0 的 spec 承諾「元素存在但無內容，§3 上線時填入、不需要重排版面」，
+    // 但元素從未被建立。這裡把承諾兌現：佔好寬度。內容不再是空的 ——
+    // paintModeStatus() 會在 mountToolbar() 掛上之後、以及每次 setDocMode()
+    // 切換時寫入當前模式名稱。
+    const statusEl = document.createElement('span');
+    statusEl.className = 'ed-toolbar-status';
+    // Final wave, M7: the only announcement a mode switch ever gets. Every
+    // toolbar button is `tabindex="-1"` (see buildToolbar()'s own note), so a
+    // screen reader is never focused on the mode button when it is pressed and
+    // hears nothing about the state that just changed; the slot's text is the
+    // only thing that says so. `role="status"` carries an implicit
+    // aria-live="polite", and the explicit attribute is written alongside it
+    // because that implication is the part assistive tech has historically
+    // been inconsistent about — belt and braces, one line, no layout cost.
+    statusEl.setAttribute('role', 'status');
+    statusEl.setAttribute('aria-live', 'polite');
+    bar.appendChild(statusEl);
+    return bar;
+  }
+
+  async function runToolbarAction(id, btnEl) {
+    const blockEl = liveToolbarBlock();
+    switch (id) {
+      // ⚠ 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 '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
+      // (withheld types, mixed spans, run support) exactly like the ⠿
+      // submenu's items do.
+      case 'quote': return blockEl ? convertBlockViaMenu(blockEl, 'quote') : undefined;
+      case 'code': return blockEl ? convertBlockViaMenu(blockEl, 'code') : undefined;
+      case 'list': return blockEl ? convertBlockViaMenu(blockEl, 'ul') : undefined;
+      case 'ordered-list': return blockEl ? convertBlockViaMenu(blockEl, 'ol') : undefined;
+      case 'check': return blockEl ? convertBlockViaMenu(blockEl, 'task') : undefined;
+      case 'bold': return applyMarkToggle('STRONG');
+      case 'italic': return applyMarkToggle('EM');
+      case 'strike': return applyMarkToggle('DEL');
+      case 'inline-code': return applyMarkToggle('CODE');
+      case 'link': return applyLinkToggle();
+      // NOT indentListItem()/outdentListItem(): those only write data-indent
+      // on the DOM and never commit. See indentCaretLi()'s own comment.
+      case 'outdent': return indentCaretLi(-1);
+      case 'indent': return indentCaretLi(1);
+      case 'table': return blockEl ? insertBlockBelow(blockEl, 'table') : undefined;
+      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();
+      case 'preview': return cycleDocMode();
+      default: return undefined;
+    }
+  }
+
+  // ── headings ▾ ─────────────────────────────────────────────────────────
+  function closeToolbarMenu() {
+    if (toolbarMenuEl) { toolbarMenuEl.remove(); toolbarMenuEl = null; }
+  }
+
+  function toggleToolbarHeadingMenu(btnEl) {
+    if (toolbarMenuEl) { closeToolbarMenu(); return; }
+    const menu = document.createElement('div');
+    menu.className = 'ed-toolbar-menu';
+    [1, 2, 3, 4, 5, 6].forEach((n) => {
+      const item = document.createElement('button');
+      item.type = 'button';
+      item.className = 'ed-toolbar-menu-btn';
+      item.textContent = '標題 ' + n;
+      item.setAttribute('tabindex', '-1');
+      item.addEventListener('mousedown', (e) => e.preventDefault());
+      item.addEventListener('click', (e) => {
+        e.stopPropagation();
+        closeToolbarMenu();
+        Promise.resolve(applyHeadingLevel(n)).catch(() => {}).then(updateToolbar);
+      });
+      menu.appendChild(item);
+    });
+    document.body.appendChild(menu);
+    const r = btnEl.getBoundingClientRect();
+    menu.style.top = (r.bottom + 4) + 'px';
+    menu.style.left = Math.max(4, Math.min(r.left, window.innerWidth - 140)) + 'px';
+    toolbarMenuEl = menu;
+  }
+
+  // changeHeadingDepth(blockEl, delta) takes a RELATIVE delta and has no
+  // blockType guard, while headingDepthOf() answers 1 for any non-heading
+  // line — so calling it on a paragraph silently prefixes '## ' and turns it
+  // into an H2 while bypassing convertBlockViaMenu()'s gates entirely. Both
+  // halves of that are handled here: a non-heading is CONVERTED through the
+  // gate (convert-md.js's 'h1'..'h6' targets already carry the level), and a
+  // heading gets a delta computed against its own current depth.
+  async function applyHeadingLevel(n) {
+    const blockEl = liveToolbarBlock();
+    if (!blockEl) return;
+    if (blockEl.getAttribute('data-block-type') !== 'heading') {
+      await convertBlockViaMenu(blockEl, 'h' + n);
+      return;
+    }
+    const rec = blockRecOf(blockEl);
+    if (!rec || rec.endLine < rec.startLine) return;
+    const delta = n - headingDepthOf(lines[rec.startLine - 1]);
+    if (delta === 0) return;
+    await changeHeadingDepth(blockEl, delta);
+  }
+
+  // ── insert above ───────────────────────────────────────────────────────
+  // commitBlockInsertion() only ever inserts AFTER a block's range, so
+  // "insert above" is expressed the way this file already expresses it (see
+  // convertEmptyTopLevelLiToParagraph()'s own preceding-block lookup):
+  // anchor on the block before this one. That keeps one insertion path and
+  // one set of gates rather than teaching the pure core a direction.
+  async function insertBlockAbove(blockEl) {
+    const rec = blockRecOf(blockEl);
+    if (!rec) return;
+    const preceding = blocks
+      .filter((b) => b.id !== rec.id && b.endLine < rec.startLine && b.endLine >= b.startLine)
+      .pop();
+    if (preceding) {
+      const anchorEl = blockElAtLine(preceding.startLine);
+      if (anchorEl) { await insertBlockBelow(anchorEl, 'paragraph'); return; }
+    }
+    // Nothing above to anchor on — see insertParagraphAtTop(). Refusing here
+    // instead would leave the document's FIRST block permanently impossible
+    // to precede: the ⠿ and ＋ menus both insert below, so this button is the
+    // only affordance that reaches that position at all.
+    await insertParagraphAtTop(blockEl);
+  }
+
+  // The document's first block has no predecessor to insert BELOW, and
+  // commitBlockInsertion() only ever inserts after a block's range. Rather
+  // than teach the pure core a direction (a change under byte-stability and
+  // roundtrip fixtures), the insert is expressed as a REPLACE of that
+  // block's own first source line by [skeleton, '', that same line] — the
+  // same commitRangeEdit()/replaceLines() pipeline as every other edit,
+  // therefore one undo op, and no new primitive.
+  //
+  // The switchAwayFrom() + re-resolve preamble is insertBlockBelow()'s,
+  // for its reasons: the resolution can commit a dirty burst, whose
+  // rerenderAll() detaches the very node this was called with.
+  async function insertParagraphAtTop(blockEl) {
+    const identity = captureBlockIdentity(blockEl);
+    const selfSession = ownsOpenSession(blockEl);
+    const ok = await switchAwayFrom();
+    if (!ok) return;
+    let liveBlockEl = blockEl;
+    if (!document.body.contains(blockEl)) {
+      liveBlockEl = reresolveBlockEl(identity) ||
+        (selfSession ? reresolveBlockElAfterSelfCommit(identity) : null);
+      if (!liveBlockEl) { showBanner(DROPPED_GESTURE_MESSAGE, null, null); return; }
+    }
+    const rec = blockRecOf(liveBlockEl);
+    // A block that owns no source line has an inverted range, and there is
+    // no line to splice in front of.
+    if (!rec || rec.endLine < rec.startLine) {
+      refuseStructuralListEdit(NO_SOURCE_LINE_INSERT_MESSAGE);
+      return;
+    }
+    const at = rec.startLine;
+    const newText = BLOCK_SKELETONS.paragraph.concat(['', lines[at - 1]]).join('\n');
+    const result = commitRangeEdit({ lines, blocks, stack }, at, at, newText);
+    if (result.op === null) return;
+    const prevLines = lines;
+    lines = result.lines;
+    const editRange = result.op
+      ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+          endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+          delta: result.op.after.length - result.op.before.length }
+      : undefined;
+    const okRender = await safeRerenderAll(editRange);
+    if (!okRender) {
+      lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      return;
+    }
+    // The new paragraph starts exactly where the old first line did — same
+    // pristine + focus contract insertBlockBelow() gives a skeleton insert.
+    const target = blocks.find((b) => b.startLine === at);
+    if (target) pristineInsert = { blockId: target.id };
+    await focusInsertedBlock(at, 'paragraph');
+  }
+
+  // ── 大綱 ───────────────────────────────────────────────────────────────
+  // TWO attributes, chosen by viewport, and that is not an accident.
+  //
+  // `body[data-sidebar-open]` is the reader runtime's own attribute (see
+  // lib/md2doc.js's setSidebarOpen()) and it drives the MOBILE drawer. The
+  // first cut of this function reused it on desktop too, on the premise that
+  // nothing outside the max-width:1080px block read it. That premise was
+  // false, and the failure was severe: `body[data-sidebar-open]
+  // .sidebar-scrim { display: block; }` sits at BASE scope, so on a desktop
+  // viewport the button painted a full-viewport 35%-black scrim over the
+  // whole page (position:fixed; inset:0; z-index:98) — the document went
+  // grey and unclickable, and the scrim's own click handler then called
+  // setSidebarOpen(false), so the first click anywhere undid it and the
+  // whole gesture read as a flicker.
+  //
+  // Desktop therefore gets a PRIVATE attribute nothing else reads,
+  // `data-ed-outline-hidden`, matched by an edit-mode-only rule in
+  // 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() {
+    // 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) {
+      expanded = !document.body.hasAttribute('data-sidebar-open');
+      if (expanded) document.body.setAttribute('data-sidebar-open', '');
+      else document.body.removeAttribute('data-sidebar-open');
+    } else {
+      expanded = document.body.hasAttribute('data-ed-outline-hidden');
+      if (expanded) document.body.removeAttribute('data-ed-outline-hidden');
+      else document.body.setAttribute('data-ed-outline-hidden', '');
+    }
+    const toggle = document.getElementById('sidebar-toggle');
+    if (toggle) toggle.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+  }
+
+  // ── 追加 3: images ─────────────────────────────────────────────────────
+  function lastBlockEl() {
+    const all = contentEl.querySelectorAll('.ed-block');
+    return all.length ? all[all.length - 1] : null;
+  }
+
+  function blobToBase64(blob) {
+    return new Promise((resolve, reject) => {
+      const fr = new FileReader();
+      fr.onerror = () => reject(new Error('could not read the image'));
+      fr.onload = () => {
+        // readAsDataURL gives 'data:<mime>;base64,<payload>' — the endpoint
+        // wants the payload alone, and derives the extension from the mime
+        // it is told, never from this prefix.
+        const s = String(fr.result || '');
+        const comma = s.indexOf(',');
+        resolve(comma === -1 ? '' : s.slice(comma + 1));
+      };
+      fr.readAsDataURL(blob);
+    });
+  }
+
+  // Uploads one blob and answers its 'assets/<name>' path, or null (a banner
+  // is already showing by then). The MIME whitelist is asked BEFORE the round
+  // trip so an unsupported drop is refused instantly and locally — the server
+  // asks the same question again, and it is the server's answer that is
+  // authoritative.
+  async function uploadImageBlob(blob) {
+    if (!blob) return null;
+    if (!assetLib || !assetLib.extFor(blob.type)) {
+      showBanner(TOOLBAR_UNSUPPORTED_IMAGE_MESSAGE, null, null);
+      return null;
+    }
+    let data;
+    try {
+      data = await blobToBase64(blob);
+    } catch (e) {
+      showBanner('圖片讀取失敗 — ' + describeFailure(e), null, null);
+      return null;
+    }
+    let res;
+    try {
+      res = await fetch('/api/asset', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          fileId: ED.fileId, mime: blob.type, name: blob.name || 'image', data: data,
+        }),
+      });
+    } catch (e) {
+      showBanner('圖片上傳失敗 — ' + describeFailure(e) + '。檔案未寫入。', null, null);
+      return null;
+    }
+    if (!res.ok) {
+      const reason = await describeHttpFailure(res);
+      showBanner('圖片上傳失敗 — ' + reason + '。檔案未寫入。', null, null);
+      return null;
+    }
+    let j;
+    try { j = await res.json(); } catch (e) { j = null; }
+    if (!j || typeof j.path !== 'string') {
+      showBanner('圖片上傳失敗 — 伺服器回應格式不正確。', null, null);
+      return null;
+    }
+    return j.path;
+  }
+
+  // asset.js's sanitizeName() deliberately keeps spaces (and everything else
+  // that is not a path separator or a drive colon) — a screenshot really is
+  // called 'Screen Shot 2026-09-03 at 14.02.11.png'. A bare space, or a
+  // parenthesis, inside an inline image destination ends the destination
+  // early, so `![](assets/My Shot.png)` renders as literal text. Percent-
+  // encoding exactly those characters fixes it in both directions: browsers
+  // resolve the escape, and md2doc's own resolveAssetPath() decodes the
+  // filePart before probing the disk (it also probes the raw form, so
+  // non-ASCII characters are deliberately left alone rather than escaped).
+  // '%' itself is encoded FIRST by being in the same character class, so a
+  // filename that already contains one cannot be double-decoded.
+  const TOOLBAR_MD_DEST_UNSAFE_RE = /[%\s()<>"']/g;
+  function markdownImageDest(p) {
+    return String(p == null ? '' : p).replace(TOOLBAR_MD_DEST_UNSAFE_RE, (c) => {
+      const hex = c.charCodeAt(0).toString(16).toUpperCase();
+      return '%' + (hex.length < 2 ? '0' + hex : hex);
+    });
+  }
+
+  // Uploads every image in `blobs` and lands them as ONE block insertion.
+  // One insertion, not one per image: each insert re-renders and detaches the
+  // anchor, so a loop would be inserting against a stale node from the second
+  // image onward — and it would also cost one undo op per image for what the
+  // user experienced as a single drop. Blank lines between the paths keep
+  // them separate paragraphs instead of one paragraph of soft breaks.
+  async function insertImages(blobs, anchorEl) {
+    const paths = [];
+    for (let i = 0; i < blobs.length; i += 1) {
+      const p = await uploadImageBlob(blobs[i]);
+      if (p) paths.push(p);
+    }
+    if (!paths.length) return;
+    const target = (anchorEl && document.body.contains(anchorEl)) ? anchorEl : lastBlockEl();
+    if (!target) { showBanner(TOOLBAR_NO_ANCHOR_MESSAGE, null, null); return; }
+    const newLines = [];
+    paths.forEach((p, i) => {
+      if (i > 0) newLines.push('');
+      newLines.push('![](' + markdownImageDest(p) + ')');
+    });
+    await insertBlockBelow(target, 'paragraph', { lines: newLines });
+  }
+
+  // v3.2.1: 「插入圖片竟然無法在我當前的位置後插入，每次都跑到最後」. Two
+  // separate mechanisms put the image at EOF, and BOTH were measured — the
+  // second one is the reason this function is longer than it looks like it
+  // needs to be.
+  //
+  //   (a) `input.click()` below is a SYNTHETIC click. It bubbles to the
+  //       document delegator, which reads it as a click landing outside every
+  //       block → switchAwayFrom() → commit + re-render → the anchor node
+  //       captured a moment earlier is detached → insertImages() falls back to
+  //       lastBlockEl() and the image lands at the end of the file.
+  //       Deterministic whenever the block the user is in is dirty, which is
+  //       exactly the reported gesture.
+  //
+  //   (b) stopPropagation() on that click is NECESSARY BUT NOT SUFFICIENT. It
+  //       fixes the reported gesture, yet the anchor stayed a raw DOM node
+  //       held across the file dialog: a FULL render landing between the click
+  //       and the `change` event detaches it and the image is back at EOF.
+  //       The v3.2.0 patch path is not the exposure — two forced mid-dialog
+  //       renders (a commit in another block, a ⠿ 刪除 of another block) were
+  //       measured to patch and leave the anchor attached — but a full render
+  //       is one patchmap() miss away (it returns null whenever there is no
+  //       usable editRange), and a real OS file dialog stays open for as long
+  //       as the user takes. So the window is small, not hypothetical.
+  //
+  // Hence both halves: stop the synthetic click from reading as an
+  // outside-click, AND resolve the open session BEFORE the picker opens while
+  // carrying the anchor as a stable IDENTITY that is re-resolved when the
+  // files come back, instead of as a node reference. The identity triple is
+  // insertBlockBelow()'s (captureBlockIdentity / ownsOpenSession /
+  // reresolveBlockEl + reresolveBlockElAfterSelfCommit) — that function solved
+  // this same problem for its own anchor and the image path simply never
+  // adopted it. Do not "simplify" the re-resolution away: it is the half that
+  // survives the dialog.
+  //
+  // ⚠ ORDERING: `await switchAwayFrom()` runs BEFORE input.click(). Chrome
+  // gates the file picker on TRANSIENT user activation, which is time-based
+  // (~5 s) and is NOT spent by awaiting a promise, so the picker still opens.
+  // The journey scenario presses 🖼 on a DIRTY block, so a real commit — an
+  // /api/render round trip — runs inside that await; if the activation were
+  // spent, waitForFileChooser() there would time out. A commit slower than
+  // the activation window would be the one way this ordering could bite.
+  async function pickAndInsertImage() {
+    // Captured BEFORE switchAwayFrom(), because that is what can renumber the
+    // ids and rewrite the source — see captureBlockIdentity()'s comment.
+    const blockEl = liveToolbarBlock() || lastBlockEl();
+    const identity = captureBlockIdentity(blockEl);
+    // The commit inside switchAwayFrom() can be a rewrite of THIS block's own
+    // source, in which case reresolveBlockEl()'s fingerprint is guaranteed to
+    // miss because WE are the reason the source changed; the narrowed
+    // re-resolve is used only then. Same reasoning as insertBlockBelow().
+    const selfSession = ownsOpenSession(blockEl);
+    if (!(await switchAwayFrom())) return;
+    const anchorEl = (blockEl && document.body.contains(blockEl))
+      ? blockEl
+      : (reresolveBlockEl(identity) ||
+        (selfSession ? reresolveBlockElAfterSelfCommit(identity) : null));
+    if (!anchorEl) { showBanner(TOOLBAR_NO_ANCHOR_MESSAGE, null, null); return; }
+    // Re-captured AFTER the commit: `identity` above holds the PRE-commit
+    // fingerprint, which the commit we just awaited may itself have
+    // invalidated. What has to survive the dialog is the anchor as it stands
+    // now.
+    const dialogIdentity = captureBlockIdentity(anchorEl);
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = 'image/png,image/jpeg,image/gif,image/webp';
+    input.multiple = true;
+    input.hidden = true;
+    // (a) above.
+    input.addEventListener('click', (e) => e.stopPropagation());
+    document.body.appendChild(input);
+    input.addEventListener('change', () => {
+      const files = input.files ? Array.prototype.slice.call(input.files) : [];
+      input.remove();
+      if (!files.length) return;
+      // (b) above. A render that landed while the dialog was open detached
+      // `anchorEl`; the identity still names the block the user pointed at.
+      // If even that misses, the block the user aimed at no longer exists as
+      // it was — refuse (and skip the upload, so no orphan lands in the
+      // user's assets/) rather than silently appending at EOF, which is the
+      // very symptom being fixed.
+      const live = document.body.contains(anchorEl)
+        ? anchorEl : reresolveBlockEl(dialogIdentity);
+      if (!live) { showBanner(TOOLBAR_NO_ANCHOR_MESSAGE, null, null); return; }
+      insertImages(files, live);
+    });
+    input.click();
+  }
+
+  function dragCarriesFiles(e) {
+    const dt = e.dataTransfer;
+    if (!dt || !dt.types) return false;
+    return Array.prototype.indexOf.call(dt.types, 'Files') !== -1;
+  }
+
+  function wireImageDrop() {
+    // ⚠ BOTH listeners are gated on `docMode === 'edit'`, and that gate is
+    // load-bearing rather than tidy-minded.
+    //
+    // In SOURCE mode `enterSourceMode()` only sets `contentEl.hidden = true` —
+    // every `.ed-block` is still in the DOM, so `lastBlockEl()` resolves and an
+    // ungated drop ran the whole upload plus an `insertBlockBelow()` commit
+    // behind the hidden content, against `lines`. The textarea the user is
+    // looking at still held the PRE-drop source, and `leaveSourceMode()` then
+    // commits `commitRangeEdit(1, lines.length, ta.value)` over the post-drop
+    // `lines` — erasing the reference that was just inserted. MEASURED:
+    // '# Doc\n\nBody para.\n' -> source mode -> drop x.png -> type EDITED ->
+    // leave, and the file ends '# Doc\n\nBody para.\n\nEDITED\n' with
+    // assets/x.png orphaned on disk. No error, no visible effect, and a stray
+    // binary left in what is usually a git working tree.
+    //
+    // v3.2.1: `!== 'edit'` rather than `=== 'source'` on purpose. Source is
+    // the only other mode today, but the gate's reason is "the content the
+    // 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) => {
+      if (docMode !== 'edit') return;
+      if (!dragCarriesFiles(e)) return;
+      e.preventDefault();
+      if (e.dataTransfer) e.dataTransfer.dropEffect = 'copy';
+    });
+    document.addEventListener('drop', (e) => {
+      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)));
+      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;
+      insertImages(images, anchorEl || liveToolbarBlock() || lastBlockEl());
+    });
+  }
+
+  // ── 追加 2: paste ──────────────────────────────────────────────────────
+  // Reads a real DataTransfer into the plain { 'mime/type': string | Blob }
+  // shape paste-md.js's pickPayload() documents. Only ONE image flavour is
+  // taken: pickPayload picks the first it finds anyway, and a clipboard can
+  // carry several encodings of the same bitmap.
+  function clipboardItemsOf(dt) {
+    const items = {};
+    if (!dt) return items;
+    try { items['text/plain'] = dt.getData('text/plain') || ''; } catch (err) { items['text/plain'] = ''; }
+    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];
+        break;
+      }
+    }
+    return items;
+  }
+
+  // A converted payload that is ONE line carrying no markdown syntax at all
+  // is indistinguishable from the plain-text paste this editor has always
+  // done — and that case (copy a word or a phrase out of a browser, paste it
+  // mid sentence) must keep landing at the caret rather than becoming a new
+  // block. Anything else is real structure and takes the source path.
+  //
+  // The test is split in two because markdown's characters are NOT all alike.
+  // The first cut used one character class for both kinds and put '-', '#'
+  // and '!' in it — which re-introduced exactly the regression this test
+  // exists to prevent, since 'e-mail', 'state-of-the-art' and 'Hello!' are
+  // ordinary prose that would have become new paragraph blocks. Those three
+  // only begin a construct at LINE POSITION, so they belong in the
+  // start-anchored test, not the anywhere test. ('![' is still caught: the
+  // '[' is in the anywhere class.)
+  const TOOLBAR_INLINE_UNSAFE_RE = /[*_`~\[\]<>|\\]/;
+  const TOOLBAR_BLOCK_START_RE =
+    /^(?: {4}|\t|#{1,6}(?:\s|$)|[-*+][ \t]|\d+[.)][ \t]|>|`{3}|~{3}|-{3}|={3})/;
+  function isInlineSafePaste(md) {
+    if (md === '' || md.indexOf('\n') !== -1) return false;
+    if (TOOLBAR_INLINE_UNSAFE_RE.test(md)) return false;
+    return !TOOLBAR_BLOCK_START_RE.test(md);
+  }
+
+  function handleArmedPaste(dt, editEl) {
+    const items = clipboardItemsOf(dt);
+    const carriesSomething = Object.keys(items).some((k) => (
+      typeof items[k] === 'string' ? items[k] !== '' : !!items[k]));
+    // An EMPTY paste is not the paste the gesture asked for, and must not
+    // consume the Ctrl+Shift+V arming. MEASURED in headless Chromium: the
+    // Ctrl+Shift+V keystroke ITSELF dispatches a paste event carrying no
+    // flavours at all (`types: []`, `getData('text/plain') === ''`) before
+    // any real clipboard content arrives. Consuming `plainPasteArmed` there
+    // disarmed the very paste the user had just asked to be plain — the
+    // gesture silently degraded to a normal rich paste. Returning early also
+    // saves an insertTextAtCaret('') that would snapshot the burst for a
+    // no-op edit.
+    if (!carriesSomething) return;
+    const plainOnly = plainPasteArmed;
+    plainPasteArmed = false;
+    const payload = pasteMd
+      ? pasteMd.pickPayload(items, plainOnly)
+      : { kind: 'text', value: dt ? dt.getData('text/plain') : '' };
+    if (payload.kind === 'image') {
+      insertImages([payload.blob], editEl.closest('.ed-block'));
+      return;
+    }
+    if (payload.kind === 'markdown') {
+      const md = String(payload.value == null ? '' : payload.value).replace(/\r\n?/g, '\n');
+      if (md.trim() === '') return;
+      if (isInlineSafePaste(md)) {
+        insertTextAtCaret(md);
+        snapBurstIfActive(editEl, 'paste');
+        return;
+      }
+      // Landed as SOURCE below the caret's block, never spliced into the
+      // WYSIWYG DOM: that is what guarantees it passes through
+      // 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') });
+      return;
+    }
+    insertTextAtCaret(payload.value || '');
+    snapBurstIfActive(editEl, 'paste');
+  }
+
+  function wirePlainPasteArming() {
+    // 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) => {
+      plainPasteArmed = !!((e.ctrlKey || e.metaKey) && e.shiftKey &&
+        (e.key === 'v' || e.key === 'V'));
+    }, true);
+  }
+
+  // ── 追加 4: the whole-document source escape hatch ─────────────────────
+  // v3.2.1: applyPreviewEditability() lived here and was preview mode's ONLY
+  // effect. Preview is gone (docsource.js's MODES comment carries the
+  // measurement), and with it the last caller of this function.
+
+  function enterSourceMode() {
+    // The pre-edit snapshot fromSource() diffs against. Omitting it makes
+    // `changed` unconditionally true (docsource.js's documented fail-safe),
+    // i.e. a needless write of byte-identical content on every exit.
+    sourceBaseLines = lines.slice();
+    const ta = document.createElement('textarea');
+    ta.className = 'ed-source';
+    ta.setAttribute('aria-label', '文件原始碼');
+    ta.value = docSourceLib.toSource(lines, EOL);
+    contentEl.hidden = true;
+    contentEl.parentNode.insertBefore(ta, contentEl);
+    sourceTextarea = ta;
+    ta.focus();
+  }
+
+  // Returns false when the commit's render failed — the textarea is then left
+  // standing with the user's text intact (a failed round trip must never be
+  // the thing that discards a whole document's edit), and the mode does not
+  // advance.
+  async function leaveSourceMode() {
+    const ta = sourceTextarea;
+    if (!ta) return true;
+    const parsed = docSourceLib.fromSource(ta.value, EOL, sourceBaseLines);
+    if (parsed.changed) {
+      // 全量置換 through the SAME replaceLines() pipeline every other edit
+      // uses — one commitRangeEdit over the whole document, therefore one
+      // undo op, and no second writer of `lines`.
+      const result = commitRangeEdit({ lines, blocks, stack }, 1, lines.length,
+        parsed.lines.join('\n'));
+      if (result.op !== null) {
+        const prevLines = lines;
+        lines = result.lines;
+        setDirty();
+        const editRange = result.op
+          ? { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+              endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+              delta: result.op.after.length - result.op.before.length }
+          : undefined;
+        const ok = await safeRerenderAll(editRange);
+        if (!ok) {
+          lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+          setDirty();
+          return false;
+        }
+      }
+    }
+    sourceTextarea = null;
+    sourceBaseLines = null;
+    ta.remove();
+    contentEl.hidden = false;
+    return true;
+  }
+
+  async function cycleDocMode() {
+    if (!docSourceLib) return;
+    await setDocMode(docSourceLib.next(docMode));
+  }
+
+  async function setDocMode(next) {
+    if (next === docMode) return;
+    if (docMode === 'edit') {
+      // Same precondition every structural operation has: resolve whatever
+      // session is open before the DOM it lives in is swapped or hidden.
+      const ok = await switchAwayFrom();
+      if (!ok) return;
+    }
+    if (docMode === 'source') {
+      const ok = await leaveSourceMode();
+      if (!ok) return;
+    }
+    docMode = next;
+    if (docMode === 'source') enterSourceMode();
+    document.body.setAttribute('data-ed-mode', docMode);
+    paintModeStatus();
+    updateToolbar();
+  }
+
+  // v3.2.1: 模式必須說出來 —— 使用者按第二下以為卡住，其實是進了 source。
+  // Called from setDocMode() AND from mountToolbar(), so the slot is truthful
+  // from the first paint rather than only after the first mode change.
+  function paintModeStatus() {
+    const statusEl = document.querySelector('.ed-toolbar-status');
+    if (statusEl) statusEl.textContent = docMode === 'source' ? '原始碼' : '編輯';
+  }
+
+  // ── mount ──────────────────────────────────────────────────────────────
+  function wireToolbarTracking() {
+    // Which block the bar reports on. Delegated at document level (never a
+    // per-block listener) for the same reason every other affordance in this
+    // file is: blocks are rebuilt wholesale on every render.
+    document.addEventListener('focusin', (e) => {
+      if (!e.target || !e.target.closest) return;
+      if (e.target.closest('.ed-toolbar') || e.target.closest('.ed-toolbar-menu')) return;
+      const blockEl = e.target.closest('.ed-block');
+      if (!blockEl) return;
+      toolbarBlockEl = blockEl;
+      updateToolbar();
+    });
+    document.addEventListener('click', (e) => {
+      if (!e.target || !e.target.closest) return;
+      if (e.target.closest('.ed-toolbar') || e.target.closest('.ed-toolbar-menu')) return;
+      closeToolbarMenu();
+      const blockEl = e.target.closest('.ed-block');
+      if (blockEl) toolbarBlockEl = blockEl;
+      updateToolbar();
+    });
+    // NOTE: there is deliberately NO selectionchange listener here — the
+    // burst's own onSelectionChangeForToolbar() calls updateToolbar() for us.
+    // See that function for why a second one must not be attached.
+  }
+
+  function mountToolbar() {
+    // An older cached page can be running this runtime without the v3.1.0
+    // module tags. Degrade to "no toolbar" rather than throwing before
+    // armEditables() has run.
+    if (!toolbarModel) return;
+    toolbarEl = buildToolbar();
+    // ⚠ document.body, NOT contentEl. rerenderAll()'s fallback path does
+    // `contentEl.innerHTML = j.parts.join('\n')` (v3.2.0: `/api/render`
+    // answers `{ parts, blocks }` and there is no `bodyHtml` on the wire any
+    // more — see applyFullRender()), replacing .content's children wholesale,
+    // and only armEditables() rebuilds anything afterwards — it knows nothing
+    // about a toolbar. A bar mounted inside .content would
+    // vanish on the first commit with nothing left to bring it back. Every
+    // persistent chrome node in this file is on document.body for exactly
+    // this reason: the conflict banner, the selection toolbar, the table
+    // grips and the table edge menu.
+    document.body.appendChild(toolbarEl);
+    document.body.setAttribute('data-ed-mode', docMode);
+    paintModeStatus();
+    wireToolbarTracking();
+    wireImageDrop();
+    wirePlainPasteArming();
+    updateToolbar();
+  }
+
   // ── global key handling ─────────────────────────────────────────────────
   document.addEventListener('keydown', (e) => {
     // ── S3 §4.4: Escape priority is drag > menu > selection > burst ─────
@@ -9817,8 +12670,13 @@
     if (!editEl) return;
     e.preventDefault();
     const dt = e.clipboardData || window.clipboardData;
-    insertTextAtCaret(dt ? dt.getData('text/plain') : '');
-    snapBurstIfActive(editEl, 'paste');
+    // v3.1.0 追加 2: paste-md.js decides what the clipboard actually holds
+    // (text/html -> markdown, an image, or plain text) and this routes the
+    // answer. The TABLE-CELL branch above deliberately keeps its plain-text
+    // behaviour: a cell cannot host a block, and a converted markdown table
+    // pasted into one cell would be a nested structure the serializer has no
+    // way to represent.
+    handleArmedPaste(dt, editEl);
   });
 
   // Task 5: hover-edge insert bubbles — one delegated, rAF-throttled
@@ -9888,6 +12746,58 @@
     });
   });
 
+  // v3.2.1: client.js 原本的 scroll 監聽器數量是 0，所以每一個 position:fixed
+  // 的浮層在捲動後都停在原視窗座標。grip／bubble 有 mousemove 驅動可重新升起，
+  // 隱藏它們就夠；.ed-seltb 沒有（它只由 selectionchange 與
+  // applyMarkToggle／applyLinkToggle 驅動，而捲動不觸發 selectionchange），
+  // 純隱藏會讓它永遠回不來，所以它要重新定位、只在選取整個離開視窗時才隱藏。
+  // capture 階段是必要的：真正會自己捲的不是 .content（overflow-y: visible，
+  // 實測 scrollHeight === clientHeight，捲的其實是 document）——是側欄的
+  // .toc-list／#search-results-list（皆 overflow-y: auto，TOC 標題夠多時
+  // 實測 scrollHeight > clientHeight）與 .lightbox-stage（overflow: auto）。
+  // 這些容器的 scroll 事件不冒泡，只有 capture 階段收得到。
+  // 副作用（已記錄，非缺陷）：正因為 capture 連這些側欄容器的捲動都收，捲動
+  // TOC 或搜尋結果清單時——即使正文內容一格都沒動——也會隱藏 table grips
+  // 並關掉開著的 .ed-te-menu。
+  //
+  // 這個監聽器刻意是「模組層級、只掛一次、永不移除」，不跟著任何一次
+  // burst 的生命週期走（不在 resetSelToolbarState() 裡拆）。理由：真正會
+  // 刪資料的 .ed-te-menu／grip 家族（見上面 Task 5 的 mousemove 委派）不需要
+  // 任何 burst 就能被叫出來 —— 使用者可以單純把游標移到表格上（觸發上面那個
+  // 無條件掛載的 mousemove）升起 grip、打開 .ed-te-menu，此時完全沒有
+  // selToolbarListener（那個監聽器只在 burst 開著時才存在）。若把這個捲動
+  // 監聽器綁在 burst 身上，恰好在「grip／選單開著但沒有 burst」這個狀態下
+  // 它會不存在。resetSelToolbarState() 本身也會在每次 rerender 時執行（六個
+  // 呼叫點之一在本檔的 rerenderAll() 路徑上），把監聽器綁在它身上還會讓
+  // 監聽器在 session 中途被拆掉、且永不重掛。
+  let selScrollRaf = 0;
+  function onAnyScroll() {
+    if (tePointer && tePointer.dragging) return;   // 拖曳中不動
+    hideTableGrips();
+    hideTableInsertBubbles();
+    // v3.2.1 fix round 1: suppressEdgeMenuAutoHide — see its own comment —
+    // is set for runCycleAlign()'s ensureTableBurstOpen() span, whose
+    // cell.focus() can itself be the cause of this very scroll event; that
+    // operation repositions the menu itself afterward, so skip tearing its
+    // state down here (grip/bubble/toolbar-menu hiding above and below is
+    // unaffected — they re-raise on the next mousemove regardless).
+    if (!suppressEdgeMenuAutoHide) hideTableEdgeMenu(); // ← 真正會刪資料的是選單，不是 grip
+    closeToolbarMenu();
+    if (selScrollRaf) return;
+    selScrollRaf = requestAnimationFrame(() => {
+      selScrollRaf = 0;
+      if (!selToolbar.parentNode) return;          // 沒升起 → 0 次 layout read
+      const sel = window.getSelection();
+      if (!sel || !sel.rangeCount || sel.isCollapsed) { hideSelToolbar(); return; }
+      const range = sel.getRangeAt(0);
+      if (!selToolbarEditEl ||
+          !selToolbarEditEl.contains(range.startContainer) ||
+          !selToolbarEditEl.contains(range.endContainer)) { hideSelToolbar(); return; }
+      positionSelToolbar(range);
+    });
+  }
+  document.addEventListener('scroll', onAnyScroll, { passive: true, capture: true });
+
   window.addEventListener('beforeunload', (e) => {
     if (stack.dirtyDepth !== 0) {
       e.preventDefault();
@@ -9908,4 +12818,8 @@
 
   armEditables(contentEl);
   wireBlockSelection();
+  // 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.
+  mountToolbar();
 })();