@helping-ai-workflow/md2doc 3.0.1 → 3.2.0

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,8 +868,567 @@
     // 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);
+    // 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;
+    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);
+    }
+
+    // ── 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 的那一項之前（算完才輪得到把它歸零）。
+    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 THREE further side effects, and all
+    // three ride along safely: (1) the `docMode === 'preview'` re-arm cannot
+    // matter here — preview sets every surface contenteditable="false", so no
+    // burst can be open to survive; (2) updateToolbar() is re-derived from the
+    // DOM on the next interaction; (3) 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;
-    contentEl.innerHTML = j.bodyHtml;
+    lastParts = j.parts;                       // v3.2.0: 供下一次 patch 當 oldParts
+    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
@@ -943,6 +1513,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 +1573,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 +1595,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 +1652,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 +1666,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 +1726,7 @@
       hasChanges: () => ta.value !== source,
       commitNow: commit,
       cancelNow: cancelAndMaybeDiscard,
+      reanchor,
     };
 
     const controls = document.createElement('div');
@@ -1089,7 +1751,19 @@
     ta.focus();
     ta.setSelectionRange(ta.value.length, ta.value.length);
 
-    function restore() {
+    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;
+      }
       blockEl.innerHTML = original;
       // 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
@@ -1113,11 +1787,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 +1831,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 +1847,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 +1862,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;
     }
 
@@ -1667,6 +2421,57 @@
   // function did by returning early.
   function computeIndentClamp(spanEls, opBlockEl, opOldIndent, opts) {
     if (!indentClamp || !spanEls || !spanEls.length) return null;
+    // v3.0.2 — the structural answer to the stale-`run` pattern that v3.0.1
+    // point-fixed at three call sites, and that both reviewers asked to have
+    // fixed at the call convention instead. There are FIVE call sites, not
+    // three (3483 batch delete, 3812 convert, 5778 batch Tab/Shift+Tab, 6028
+    // caret Tab/Shift+Tab — both indent directions share ONE call site each,
+    // batch vs. caret, not one call site per direction — and the drop's
+    // compute at 8516), and every one of them hands over a `listRunOf()`
+    // result in document order. Two ways that goes stale, both of which
+    // produced a confident wrong number rather than a refusal: a member
+    // DETACHED (getAttribute still answers on a detached node) and a span
+    // still attached but no longer in the run's document order (indexOf()
+    // then reports an opIndex for a layout that no longer exists, so §3.4
+    // rule 2's scope starts in the wrong place). Re-deriving the span here
+    // instead of checking it was rejected: it would quietly change the
+    // contract from "clamp this span" to "clamp the run containing this
+    // op", and the drop is the one caller subtle enough that taking that
+    // expressiveness away is not free.
+    //
+    // It does NOT throw. This file's defensive style (safeRerenderAll at
+    // ~990) is that the editor must not die on one path's failure. But the
+    // refusal is NOT free either: at the drop (8516) a null clamp feeds
+    // spanIndentsAreAnchored() the RAW reordered indents, and that refuses
+    // 1425 of 4067 legal drops where the clamped answer refuses only 14 (the
+    // clamp rescues the other 1411; the measured numbers are recorded at
+    // line ~371). So a false positive here costs the user up to 1411 legal
+    // batch drags, replaced by a banner —
+    // which is why the assert is worth this cost even though the batch-
+    // delete, convert and drop sites each have a scenario whose correct
+    // answer needs a real reclamp (a wrongly-firing assert breaks them
+    // visibly), while neither Tab call site (5778 batch, 6028 caret) has a
+    // scenario that reclamps a TRAILING sibling — see
+    // test/editor-client-runtime.test.js for the per-site detail.
+    const fresh = listRunOf(spanEls[0]);
+    if (fresh.length !== spanEls.length ||
+        fresh.some((el, i) => el !== spanEls[i])) {
+      // Minor 5: the length pair alone is silent on the reordered-but-same-
+      // length case (the ONLY case where an index is diagnostic — a length
+      // mismatch is already self-explanatory), so report the first index at
+      // which the two runs disagree too.
+      const minLen = Math.min(fresh.length, spanEls.length);
+      let badIndex = -1;
+      for (let i = 0; i < minLen; i++) {
+        if (fresh[i] !== spanEls[i]) { badIndex = i; break; }
+      }
+      if (badIndex < 0 && fresh.length !== spanEls.length) badIndex = minLen;
+      console.error('computeIndentClamp: stale span — the run has ' + fresh.length +
+        ' members, the caller passed ' + spanEls.length +
+        ', first differing at index ' + badIndex +
+        '; refusing rather than clamping against a layout that no longer exists');
+      return null;
+    }
     const opEls = Array.isArray(opBlockEl) ? opBlockEl : [opBlockEl];
     const opIndex = [];
     for (let k = 0; k < opEls.length; k++) {
@@ -1813,7 +2618,12 @@
     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);
     }
@@ -2327,37 +3137,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);
   }
 
@@ -2471,6 +3286,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
@@ -2516,7 +3338,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;
@@ -2569,7 +3412,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.
@@ -2608,7 +3460,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) ────────────────
@@ -2679,7 +3532,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;
@@ -2688,9 +3546,27 @@
     // 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);
+    }
   }
 
 
@@ -3143,7 +4019,12 @@
       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);
     }
@@ -3238,7 +4119,12 @@
     // 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);
     }
   }
@@ -3370,7 +4256,12 @@
     // 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);
     }
@@ -3804,7 +4695,12 @@
     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);
     }
   }
@@ -3861,7 +4757,12 @@
       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);
     }
   }
@@ -3927,7 +4828,27 @@
       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
@@ -4119,10 +5040,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);
@@ -4202,7 +5133,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;
@@ -4258,7 +5194,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
@@ -4491,6 +5432,15 @@
   window.__edTestForceRerender = function () { return rerenderAll(); };
   window.__edTestTruncateTo = function (n) { lines = lines.slice(0, n); };
 
+  // v3.0.2: computeIndentClamp() lives past this file's node early-exit
+  // (module.exports at line ~509 ships the pure core only) and nothing on
+  // window reaches it, so the stale-span assert added to it in v3.0.2 had
+  // no way to be tested at all. This is the seventh __edTest seam and the
+  // only production surface that change adds.
+  window.__edTestClampProbe = function (spanEls, opBlockEl, opOldIndent, opts) {
+    return computeIndentClamp(spanEls, opBlockEl, opOldIndent, opts);
+  };
+
   // ── S3 Task 4: the entry and exit GESTURES ─────────────────────────────
   // §4.4 entries: (a) press inside a block and drag across its boundary;
   // (b) Shift+Click; (c) Shift+↑↓. Exits: Escape (Task 3's keydown prologue)
@@ -4904,7 +5854,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
@@ -5773,7 +6728,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);
     }
@@ -5806,6 +6766,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
@@ -7139,6 +8156,40 @@
   let gripColTableEl = null;
   let gripColIndex = null;
 
+  // v3.0.2 — the gutter keep-alive for the table row grip. Held in its own
+  // module-level reference, NOT read back off `gripRowTableEl`, because
+  // hideTableGrips() below nulls that at its own line 7246-7248: a teardown
+  // that went looking for the block through it would find null exactly when
+  // it needs to clear the class, and rerenderAll()'s hideTableGrips() call
+  // reaches it with the table already detached.
+  let gutterKeepEl = null;
+
+  function setGutterKeep(blockEl) {
+    const next = blockEl || null;
+    if (gutterKeepEl === next) return;
+    if (gutterKeepEl) gutterKeepEl.classList.remove('ed-keep-lit');
+    gutterKeepEl = next;
+    if (gutterKeepEl) gutterKeepEl.classList.add('ed-keep-lit');
+  }
+
+  function clearGutterKeep() { setGutterKeep(null); }
+
+  // The block whose gutter the CURRENTLY SHOWN row grip is covering, or null
+  // when there is nothing to keep lit. Two conditions, both load-bearing:
+  //
+  //   • gripRowTableEl / gripRowEl may be null while a grip is nonetheless
+  //     visible — a header-only table takes the else branch at 7466-7470 and
+  //     nulls both, then the column grip is shown unconditionally just
+  //     below. Both callers of this function are reached in that state.
+  //   • only the HEADER row's grip shares a Y with the ⠿. Keeping the
+  //     gutter lit for a body row's grip would light the ⠿ in a place the
+  //     defect never occurred — a behaviour change beyond the fix.
+  function headerGripBlock() {
+    if (!gripRowTableEl || !gripRowEl) return null;
+    if (gripRowEl !== headerRowOf(gripRowTableEl)) return null;
+    return gripRowTableEl.closest('.ed-block');
+  }
+
   function hideTableGrips() {
     rowGrip.hidden = true;
     colGrip.hidden = true;
@@ -7153,6 +8204,7 @@
     gripRowEl = null;
     gripColTableEl = null;
     gripColIndex = null;
+    clearGutterKeep();
   }
 
   // Bug fix (user acceptance) — history: grips were originally BOTH
@@ -7298,7 +8350,15 @@
     // whatever was last shown untouched instead; hideTableGrips() (called
     // from table-leave, burst-end, and drag-start elsewhere) already covers
     // every path that actually needs to clear it.
-    if (target && target.closest && (target.closest('.ed-te-grip-row') || target.closest('.ed-te-grip-col'))) return;
+    if (target && target.closest && (target.closest('.ed-te-grip-row') || target.closest('.ed-te-grip-col'))) {
+      // v3.0.2: only the ROW grip is the one that covers the ⠿'s approach.
+      // Testing the hit rather than reusing the branch condition matters —
+      // the column grip sits above the table's top border, nowhere near the
+      // ⠿, and lighting the gutter from there is the behaviour change this
+      // fix is scoped to avoid.
+      setGutterKeep(target.closest('.ed-te-grip-row') ? headerGripBlock() : null);
+      return;
+    }
     const blockEl = target && target.closest && target.closest('.ed-block[data-block-type="table"]');
     const tableEl = blockEl ? blockContentEl(blockEl) : null;
     const cellEl = (tableEl && target && target.closest) ? target.closest('th, td') : null;
@@ -7311,10 +8371,15 @@
       // comment for why not the whole table). Keep that grip up while still
       // in its zone; only actually hide once the pointer has left both
       // zones entirely.
-      if (pointInRowGripZone(x, y) || pointInColGripZone(x, y)) return;
+      const inRowZone = pointInRowGripZone(x, y);
+      if (inRowZone || pointInColGripZone(x, y)) {
+        setGutterKeep(inRowZone ? headerGripBlock() : null);
+        return;
+      }
       hideTableGrips();
       return;
     }
+    clearGutterKeep();
 
     const tableRect = tableEl.getBoundingClientRect();
     const rowEl = cellEl.parentElement;
@@ -8205,7 +9270,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);
     }
@@ -8804,16 +9874,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
@@ -9305,7 +10399,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.
@@ -9321,7 +10436,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);
@@ -9329,6 +10452,806 @@
     }
   }
 
+  // ── 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 three-state document mode: 'edit' | 'source' | 'preview'.
+  // 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();
+    // A render that lands while the document is in preview mode re-arms every
+    // surface as editable (armEditables() has no notion of modes), so the
+    // mode's one real effect has to be re-applied on the fresh DOM.
+    if (docMode === 'preview') applyPreviewEditability(false);
+    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');
+      }
+      // Only `headings` carries a label (H / H1..H6); every other button
+      // keeps the glyph it was built with.
+      if (typeof st.label === 'string') btn.textContent = st.label;
+    });
+  }
+
+  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;
+    });
+    toolbarBtns = btns;
+    // v3.1.0 的 spec 承諾「元素存在但無內容，§3 上線時填入、不需要重排版面」，
+    // 但元素從未被建立。這裡把承諾兌現：佔好寬度、無內容。
+    const statusEl = document.createElement('span');
+    statusEl.className = 'ed-toolbar-status';
+    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 });
+  }
+
+  function pickAndInsertImage() {
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = 'image/png,image/jpeg,image/gif,image/webp';
+    input.multiple = true;
+    input.hidden = true;
+    const anchorEl = liveToolbarBlock() || lastBlockEl();
+    document.body.appendChild(input);
+    input.addEventListener('change', () => {
+      const files = input.files ? Array.prototype.slice.call(input.files) : [];
+      input.remove();
+      if (files.length) insertImages(files, anchorEl);
+    });
+    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.
+    //
+    // In PREVIEW mode the toolbar reports every editing button as disabled, so
+    // the mode PRESENTS as read-only; a drop that silently wrote a file and
+    // inserted a block would make that presentation a lie.
+    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 ─────────────────────
+  function applyPreviewEditability(editable) {
+    const surfaces = contentEl.querySelectorAll('.ed-wys-armed, .ed-wys-cell');
+    for (let i = 0; i < surfaces.length; i += 1) {
+      surfaces[i].setAttribute('contenteditable', editable ? 'true' : 'false');
+    }
+  }
+
+  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;
+    }
+    if (docMode === 'preview') applyPreviewEditability(true);
+    docMode = next;
+    if (docMode === 'source') enterSourceMode();
+    if (docMode === 'preview') applyPreviewEditability(false);
+    document.body.setAttribute('data-ed-mode', docMode);
+    updateToolbar();
+  }
+
+  // ── 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);
+    wireToolbarTracking();
+    wireImageDrop();
+    wirePlainPasteArming();
+    updateToolbar();
+  }
+
   // ── global key handling ─────────────────────────────────────────────────
   document.addEventListener('keydown', (e) => {
     // ── S3 §4.4: Escape priority is drag > menu > selection > burst ─────
@@ -9709,8 +11632,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
@@ -9800,4 +11728,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();
 })();