@helping-ai-workflow/md2doc 3.2.0 → 3.2.1

package/lib/editor/client.js

@@ -1023,6 +1023,31 @@
     // property before we are called; it is a PRECONDITION of everything
     // below, not something this function re-derives.
     const children = Array.prototype.slice.call(contentEl.children);
+    // v3.2.1: 「被改寫區塊內的游標」焦點修復。動機來自 undo/redo 的量測——
+    // undo/redo 並非普遍掉焦點：游標在被改寫區間【之外】時 activeElement /
+    // 所屬 block / caret offset 全部存活（連一次讓自己 data-block-id 8→7 的
+    // 結構性 undo 都扛得住）；只有游標落在被改寫區塊【內】才掉到 BODY，之後
+    // 打字被靜默丟棄。所以判準是位置，不是操作種類，也完全不需要 op→block
+    // 映射（實測 op.startLine 在 14 個實例中只有 4 個正確，對 move / insert
+    // 都指向沒有擁有者的空行——該設計已退掉）。
+    //
+    // ⚠ 觸發面不是「只有 undo/redo」：任何一次 patch 只要聚焦的 block 落在
+    // replaceSpan 內就會走到，fix round 1 的 review 點名了兩類非 undo 的呼叫者——
+    //   * 一般的 burst 提交：endBurstWithoutResolve() 不 blur，焦點還留在那個
+    //     即將被換掉的面上；
+    //   * 帶 declaredRange 的批次結構操作：焦點坐在 `.ed-block` 外框上（roving
+    //     tabindex）。
+    // 這兩類上還原完之後常常會被下面 applySelectionClasses() 自己的
+    // `focusEl.focus()` 立刻覆蓋掉（它把焦點搬回選取的 focus block），也就是多
+    // 一趟 focus 往返而已；journey 案例 3 / 4 / 6 走的正是這些路徑，皆綠。
+    //
+    // 必須在 DOM 手術之前算：removeChild 之後 activeElement 已經是 BODY，
+    // 而 `children` 是 patch 前的快照，也是 plan 的索引所指的那份清單。
+    const focusedBlockEl = document.activeElement &&
+      document.activeElement.closest ? document.activeElement.closest('.ed-block') : null;
+    const ci = focusedBlockEl ? children.indexOf(focusedBlockEl) : -1;
+    const focusWasInSpan = ci >= 0 &&
+      ci >= plan.replaceSpan.oldStart && ci <= plan.replaceSpan.oldEnd;
     // Fix round 1 (review Important 1): `blocks`/`lastParts` are the JOIN KEY
     // between the module's model and the DOM, and they are overwritten BEFORE
     // the DOM is touched — armEditables() reads the new `blocks` (see its call
@@ -1109,6 +1134,53 @@
       return applyFullRender(j, window.scrollY, declaredRange);
     }
 
+    if (focusWasInSpan) {
+      // 落在被置換區間內的游標，其節點已經被移除。把焦點放到對應的新節點
+      // （夾在新中段的範圍內），caret 置尾。
+      //
+      // 位置刻意在 teardown 之前，而真正的機制是 fix round 1 的 review 查出來
+      // 的這一條（第一版註解寫的「靠收尾那段焦點檢查認養」是錯的，那段在這條
+      // 路徑上是死碼）：`surface.focus()` 會【同步】觸發 document 層那個委派的
+      // focusin。undo() 早已 await 完 switchAwayFrom()，所以 `switching` 與
+      // `currentBurst` 都是 null——focusin 的兩個 early-return 都不成立——而新
+      // 節點在 insertBefore 之前就被 armEditables(tpl.content) 武裝過了，於是
+      // startBurst() 當場就跑完。打字有人追蹤、Ctrl+S 才寫得進檔案（實測拿掉
+      // 這一塊時 undo 之後打的字連磁碟都到不了）。收尾最後那段
+      // `if (!currentBurst && …)` 的焦點檢查因此在這條路徑上恆為 false。
+      //
+      // 代價要說清楚：下面的 `burstSurvived` 是在這裡【之後】才求值的，所以在
+      // 走到這一塊的 render 上，它量到的是「剛剛由還原開出來的那個 burst」，
+      // 而不是它註解所寫的「patch 前就開著、而且面活過 patch」。受影響的是三個
+      // 以它為閘門的收尾項：currentBurst 的 dispose、resetSelToolbarState()、
+      // resetToolbarBlock()——三者都會改走 survived 分支。結果是好的（剛開的
+      // burst 不被丟掉、startBurst() 剛掛上的 selectionchange listener 不被拆、
+      // toolbarBlockEl 保住 focusin 剛設好的活節點），但那是巧合而不是設計，
+      // 所以在 `burstSurvived` 那裡也留了一行對照註解。不搬 `burstSurvived`
+      // 到還原之前，是刻意的取捨：搬了會讓剛開的 burst 先被 dispose 再由收尾
+      // 重開一次，並把每次 undo 的工具列 degrade 原封不動地留著。
+      // teardown 十二項彼此的相對順序沒有被動到，條件式的 activeEditor 歸零
+      // 仍然在 DOM 手術之後求值。
+      const newLen = plan.replaceSpan.newParts.length;
+      if (newLen > 0) {
+        // landing 恆落在新中段內：ci >= oldStart 保證非負，min() 夾住上界，
+        // 而 patch 後的子節點是 prefix(keepPrefix) + 新中段(newLen) + suffix。
+        // 零寬區間（insert，oldEnd === oldStart - 1）根本進不了 focusWasInSpan。
+        const landing = plan.keepPrefix + Math.min(ci - plan.replaceSpan.oldStart, newLen - 1);
+        const el = contentEl.children[landing];
+        const surface = el ? blockContentEl(el) : null;
+        if (surface) {
+          surface.focus();
+          try {
+            const r = document.createRange();
+            r.selectNodeContents(surface);
+            r.collapse(false);
+            const s = window.getSelection();
+            s.removeAllRanges(); s.addRange(r);
+          } catch (e) { /* best-effort，同 focusBlockAtLine 的處置 */ }
+        }
+      }
+    }
+
     // ── teardown ────────────────────────────────────────────────────────
     // Controller ruling F1: the patch path runs the SAME twelve teardown items
     // applyFullRender() runs, unconditionally and in the same relative order.
@@ -1219,6 +1291,18 @@
     // 的**相對順序**與 applyFullRender() 一致，把 resetSelToolbarState() /
     // resetToolbarBlock() 搬到第 3 項旁邊才是真的改了順序。條件只算一次，
     // 而且算在會動到 currentBurst 的那一項之前（算完才輪得到把它歸零）。
+    // ⚠ v3.2.1 fix round 1：這個節點 identity 判準本身沒變，但它求值的時機
+    // 現在落在上面那塊焦點還原【之後】。還原的 `surface.focus()` 在
+    // switchAwayFrom() 已經結算完的路徑上（undo()/redo()）會【同步】開出一個新
+    // 的 burst（見那裡的註解），所以在那種 render 上這裡量到的 true 說的是
+    // 「現在有一個 burst，而且它的面在文件上」，不是「patch 前那個 burst 活下
+    // 來了」。下面三個以它為閘門的項因此會走 survived 分支。實測（undo 走
+    // patch 路徑）：收尾後工具列 disabled 停在 7/22，不是 resetToolbarBlock()
+    // 跑過該有的 18/22 —— 也就是 resetToolbarBlock() 確實被跳過了，這是
+    // burstSurvived 為 true 的直接證據。反過來，若還原當下 currentBurst 還沒被
+    // 歸零（別條路徑），focusin 的 `if (currentBurst) return;` 會擋掉開 burst，
+    // 這裡照舊量到「舊 burst 的面被拔掉了」＝false，收尾最後那段焦點檢查才是
+    // 接手的人。兩種情形都不需要這一項改判準。
     const burstSurvived = !!(currentBurst && currentBurst.editEl
       && document.body.contains(currentBurst.editEl));
     // Task 2 (Phase 3): same belt-and-braces reasoning for the always-on
@@ -1284,11 +1368,10 @@
     // 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
+    // next click). It has TWO further side effects (v3.2.1: the third was
+    // preview mode's contenteditable re-arm, removed with the mode itself),
+    // and both ride along safely: (1) updateToolbar() is re-derived from the
+    // DOM on the next interaction; (2) closeToolbarMenu() — skipping it leaves
     // the H▾ dropdown standing across a patch, which is benign because
     // `toolbarMenuEl` is appended to document.body, not into a block, so the
     // patch never detaches it, and applyHeadingLevel() re-resolves through
@@ -1428,20 +1511,24 @@
   async function applyFullRender(j, scrollY, declaredRange) {
     blocks = j.blocks;
     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
-    // the fresh nodes (diagram re-init, reader rebind, focus restoration).
-    armEditables(contentEl);
+    // v3.2.1 R2: 必須先於 innerHTML 寫入。這個寫入 detach 掉聚焦的 raw
+    // textarea，同步 focusout 重入 switchAwayFrom() → resolveOpenSession() →
+    // commitNow()，於是同一次編輯提交兩次（實測衍生新 block 時磁碟上文字出現
+    // 兩次；停在同一個 block 內則第二次回 op === null 退化成取消，所以看不出來）。
     // Whatever editor (if any) was open a moment ago just got detached by
-    // the innerHTML replacement above — its own restore()/commit() never
+    // the innerHTML replacement below — its own restore()/commit() never
     // ran, so it never got a chance to null this out itself. Do it here,
     // unconditionally, on every successful swap: this is what makes the
     // undo/redo lockout regression (see the `activeEditor` comment above)
     // structurally impossible even from a call site that forgets to call
     // switchAwayFrom() first.
     activeEditor = null;
+    contentEl.innerHTML = j.parts.join('\n');  // fallback 路徑用 join 還原
+    // Task 2 (Phase 3): re-arm every WYSIWYG-eligible paragraph/heading (and
+    // attach a ⠿ handle to every non-table block) in the freshly-swapped
+    // DOM — see armEditables() below. Must run before anything else touches
+    // the fresh nodes (diagram re-init, reader rebind, focus restoration).
+    armEditables(contentEl);
     // §10-gap fix (review): same belt-and-braces reasoning for
     // `pristineInsert` — its window is meant to close via one of the
     // explicit resolution hooks (resolveBurst()/revertBurstAndEnd()/
@@ -1764,12 +1851,17 @@
         await safeRerenderAll();
         return;
       }
-      blockEl.innerHTML = original;
+      // v3.2.1 R1: 清 activeEditor 必須先於這個 innerHTML 寫入。寫入會 detach
+      // 聚焦的 textarea，Chromium 同步派發 focusout，而 focusout handler 只要
+      // activeEditor 非 null 就會走 switchAwayFrom() → resolveOpenSession() →
+      // commitNow()，把使用者按 Escape 要丟棄的文字提交進檔案（實測落到磁碟）。
+      // 同一函式的 rangeMode 分支早就是這個順序，理由相同。
       // Only clear `activeEditor` if it's still THIS block's entry — it may
       // already have been cleared out from under us (e.g. by rerenderAll()'s
       // own defensive reset on a successful swap elsewhere), and this must
       // never stomp some OTHER block's activeEditor set after this one.
       if (activeEditor && activeEditor.blockEl === blockEl) activeEditor = null;
+      blockEl.innerHTML = original;
       // No re-wiring needed here (unlike the old per-block gutter): block
       // selection / the edit bar are handled by ONE delegated `document`
       // click listener (see wireBlockSelection() below), so this
@@ -2576,7 +2668,51 @@
   // switchAwayFrom() first resolves any editor that's currently open on this
   // (or another) block, same precondition as undo()/redo() below, so this
   // never races a concurrent commit or operates on stale `lines`/`blocks`.
+  //
+  // v3.2.1 final wave: THIN WRAPPER + `finally`, the same shape the other four
+  // sinks use, because this function's own early exits were live holes in
+  // exactly the promise this version's CHANGELOG makes. MEASURED on ddac6ce
+  // with real keystrokes, three runs each: typing in `# Title` then Shift+Tab
+  // went H1.ed-wys-armed / 15 enabled → BODY / 4 enabled, and `###### Title`
+  // then Tab did the same; `## Title` + Tab (the unclamped control) stayed
+  // H3.ed-wys-armed / 15. The clamp is reachable from an ordinary gesture:
+  // handleBurstKeydown()'s `changeHeadingDepth(currentBurst.blockEl,
+  // e.shiftKey ? -1 : 1)` passes a raw ±1 with no `delta === 0` filter (unlike
+  // applyHeadingLevel(), which computes a delta and can hand over 0), so Tab
+  // at either end of H1..H6 lands on `newDepth === curDepth` — an early return
+  // that sits BELOW the switchAwayFrom() that already committed and re-rendered
+  // and ABOVE the restore at the tail.
+  //
+  // The body answers a line on every exit it can name one for:
+  //   * success                  result.op.startLine (the commit's own first
+  //                              written line — see the note at the tail)
+  //   * newDepth === curDepth    block.startLine
+  //   * result.op === null       block.startLine
+  // `block` is looked up out of `blocks` AFTER switchAwayFrom(), so its
+  // startLine is already a post-render coordinate. INSTRUMENTED at that exit
+  // rather than reasoned: on `# Title` typed into and then Shift+Tab-ed, the
+  // clamped return printed
+  //   {sameBlocksArray:false, sameNode:false, blockId:0, startLine:1,
+  //    resolvesToId:0, resolvedText:'TitleX'}
+  // — switchAwayFrom() had replaced both the `blocks` array and the heading's
+  // DOM node, and `block.startLine` still resolved to the LIVE block carrying
+  // the just-committed text, which is exactly what focusBlockAtLine() needs.
+  //
+  // The two re-query failures above it (`blockEl` gone, `block` not in
+  // `blocks`) deliberately answer nothing: there is no block left to aim at,
+  // and guessing a line is worse than restoring no caret.
   async function changeHeadingDepth(blockEl, delta) {
+    let focusLine = null;
+    const anchor = {};
+    try {
+      const out = await changeHeadingDepthBody(blockEl, delta, anchor);
+      if (out != null) focusLine = out;
+    } finally {
+      restoreAfterStructuralOp(focusLine, anchor.line);
+    }
+  }
+
+  async function changeHeadingDepthBody(blockEl, delta, anchor) {
     if (!blockEl) return;
     const blockId = Number(blockEl.getAttribute('data-block-id'));
     // Commits (never discards) whatever burst/editor is open first — same
@@ -2609,6 +2745,9 @@
     }
     const block = blocks.find((b) => b.id === blockId);
     if (!block) return;
+    // Post-switchAwayFrom(), post-render: the landing for every exit below
+    // that writes nothing. See restoreAfterStructuralOp().
+    if (anchor) anchor.line = block.startLine;
     const curLine = lines[block.startLine - 1];
     const curDepth = headingDepthOf(curLine);
     const newDepth = Math.max(1, Math.min(6, curDepth + delta));
@@ -2627,6 +2766,28 @@
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 (controller ruling T5-1): the OTHER sink. H▾ on a block that is
+    // ALREADY a heading routes HERE, not to convertBlockViaMenu() —
+    // applyHeadingLevel() takes that road only for a NON-heading — so without
+    // this, H2 → H4 still ends the way every conversion used to: the render's
+    // teardown ran resetToolbarBlock(), activeElement is BODY and the bar is
+    // down to 4 enabled buttons, and a second operation needs a fresh click.
+    //
+    // Same predicate and the same measurement as convertBlockViaMenu()'s exit
+    // — the wrapper's restoreAfterStructuralOp() is now literally the same
+    // function, so see its note for why it is `blockSelection` and not operand
+    // cardinality, and why forcing a caret while a selection stands
+    // manufactures a broken state rather than fixing one.
+    //
+    // The line is `result.op.startLine`, the commit's OWN first written line:
+    // commitEdit() resolves the block and hands commitRangeEdit() that
+    // startLine, which is where replaceLines() writes `after`. This function
+    // declares no collapse of its own (it is not a set operation), so the
+    // commit result is the only post-commit value it holds — and it is a
+    // RESULT, not a pre-commit `block.startLine` capture. An insertion above
+    // this block cannot have happened between the two, because the commit IS
+    // the only thing that ran.
+    return result.op.startLine;
   }
 
   // ── Task 2 (Phase 3): always-on WYSIWYG editing + burst undo ───────────
@@ -3566,6 +3727,26 @@
       const target = blocks.find((b) => b.startLine === result.newStartLine);
       if (target) pristineInsert = { blockId: target.id };
       await focusInsertedBlock(result.newStartLine, kind);
+    } else if (kind === 'line') {
+      // v3.2.1: <hr> 沒有 placeholder，所以不 focusInsertedBlock()（那是上面
+      // 那個 `kind !== 'line'` 既有的刻意 opt-out）。這一支只做工具列復原：把
+      // toolbarBlockEl 指向新插入的 hr block，讓 bar 不要停在 render teardown
+      // 留下的 4 顆。
+      //
+      // ⚠ 明說量測到的事，不要說希望發生的事：**caret 沒有被還原**。實測
+      // （alpha / bravo / charlie，點進 bravo 再按 分隔線）這一支停用時是
+      // {activeElement: BODY, enabled: 4}、啟用後是 {activeElement: BODY,
+      // enabled: 15}，兩者磁碟 byte-identical。也就是說使用者按完分隔線仍然
+      // 沒有游標，要再點一次 block 才能繼續打字 —— 工具列復原就是這一支交付的
+      // 全部。要連 caret 一起還原是另一個決定（游標該落在錨點 block 還是 hr
+      // 之後的 block），不在本 task 的範圍內。
+      //
+      // Final wave, M4: gated on `blockSelection` like the other four restore
+      // sites. Harmless today — a ＋ 分隔線 pressed with a set standing writes
+      // no declareCollapse(), so re-aiming the bar at the hr cannot contradict
+      // a tinted set the way a forced caret would — but "the one site that does
+      // not ask the question" is how the next divergence gets in.
+      if (!blockSelection) reaimToolbarBlockAtLine(result.newStartLine);
     }
   }
 
@@ -3685,7 +3866,34 @@
   // already been raised — otherwise `{ els, recs, batch }`: the LIVE block
   // elements in document order, their records out of `blocks` (by reference),
   // and whether more than one block is being operated on.
-  async function resolveGutterOperands(blockEl) {
+  //
+  // v3.2.1 final wave: `anchor` is an optional OUT-PARAMETER. When given, its
+  // `.line` is set to the grip block's start line as soon as that block has
+  // been re-resolved against the post-switchAwayFrom() `blocks` — i.e. a
+  // number that is already valid on the freshly rendered DOM. Every refusal
+  // BELOW that assignment therefore leaves the caller holding a live
+  // coordinate for a block the refusal did not touch.
+  //
+  // FIVE exits sit ABOVE it and all of them leave `.line` undefined, which is
+  // the honest answer in each case (N3 — the first version of this sentence
+  // said "the two exits", the same undercount M2 existed to fix, so they are
+  // counted out here one by one):
+  //   1. `if (!blockEl) return null`        — no gesture at all.
+  //   2. `if (!ok) return null`             — switchAwayFrom()'s commit FAILED
+  //      and the session it could not commit is still open with its own
+  //      banner; aiming a caret anywhere would fight it.
+  //   3. the dropped-gesture re-resolve     — the block is genuinely gone.
+  //   4. the no-source-line refusal         — the block is there, but its range
+  //      is inverted (endLine === startLine - 1), and
+  //      `blocks.find(b => b.startLine === …)` would resolve some OTHER block.
+  //   5. `if (!rec)` (a second DROPPED_GESTURE) — the one the undercount lost.
+  //      It is NOT absorbed by 4: blockOwnsNoLine() is `!!rec && rec.endLine <
+  //      rec.startLine`, so it answers FALSE when the id is absent from
+  //      `blocks`, and it also answers false for a provisional block whose
+  //      `data-block-id` is null (blockRecOf() returns null for both). Either
+  //      way there is no record to read a startLine off.
+  // See restoreAfterStructuralOp().
+  async function resolveGutterOperands(blockEl, anchor) {
     if (!blockEl) return null;
     // Finding 5a's mousedown preventDefault() deliberately keeps a dirty burst
     // alive across the ⠿ press, so the commit that lands inside
@@ -3711,6 +3919,7 @@
     if (blockOwnsNoLine(liveBlockEl)) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return null; }
     const rec = blockRecOf(liveBlockEl);
     if (!rec) { showBanner(DROPPED_GESTURE_MESSAGE, null, null); return null; }
+    if (anchor) anchor.line = rec.startLine;
 
     const res = selectionLib
       ? selectionLib.resolveMembership(blockSelection, blocks, rec)
@@ -3884,7 +4093,148 @@
     return run;
   }
 
+  // ── v3.2.1 final wave: ONE landing for all four structural sinks ────────
+  //
+  // The v3.2.1 wrappers restored only on the SUCCESS line the body answered.
+  // Measured on ddac6ce, 轉換成 → 引用 on a hard-wrapped list item (an ENABLED
+  // menu item — `disabled === false`, measured) whose own burst was dirty:
+  // DIV.ed-li-text ed-wys-armed / 16 enabled → BODY / 4 enabled, plus the
+  // banner 「此清單含不支援的格式，無法調整結構」. The `finally` WAS reached;
+  // `focusLine` was simply null there, so focusBlockAtLine() was skipped and
+  // reaimToolbarBlockAtLine(null) returned on its first line — while
+  // resolveGutterOperands()'s own switchAwayFrom() had already committed the
+  // burst and re-rendered, which is what took the foothold away.
+  //
+  // Hence the second coordinate. `focusLine` is the body's SUCCESS landing and
+  // is used exactly as before. `anchorLine` is resolveGutterOperands()'s live
+  // grip line (see its `anchor` out-parameter) and is used ONLY when the body
+  // answered nothing — a refusal, a no-op commit, or a rolled-back render.
+  //
+  // The foothold check on that second path is deliberate and is NOT symmetric
+  // with the first. A refusal can also arrive with the user's caret still
+  // exactly where they left it (a CLEAN burst goes out through
+  // endBurstWithoutResolve(): no commit, no render, focus never moves —
+  // measured: 轉換成 → 引用 on the same hard-wrapped li WITHOUT typing first
+  // leaves DIV.ed-li-text ed-wys-armed / 16 enabled on ddac6ce). Restoring
+  // unconditionally there would drag that caret to the end of the block for no
+  // reason — the same mistake fix round 1 corrected in applyLinkToggle(), and
+  // this is the same predicate it settled on.
+  //
+  // M3, the predicate divergence: the four sinks now AGREE that a rolled-back
+  // render restores. Verified by reading rather than driven (a render failure
+  // needs the server to fail mid-gesture): every `return false` inside
+  // rerenderAll() is one of its four fetch/parse exits, all of them above the
+  // call to applyRenderResult(); applyPatch() and applyFullRender() contain no
+  // `return false` at all (grep: zero hits between them). So a `false` answer
+  // from safeRerenderAll() means the DOM was never touched — the anchor block
+  // is still on screen under the same id — while the switchAwayFrom() that ran
+  // BEFORE it may already have re-rendered and reset the bar. Restoring is
+  // therefore the right answer, and returning empty-handed (what
+  // duplicateBlockViaMenuBody() and deleteBlockViaGutterBody() used to do on
+  // `!okRender`) strands the user in exactly the I1/I2 shape. The one failure
+  // this does NOT cover is a THROW inside applyPatch()/applyFullRender(),
+  // caught by safeRerenderAll(): that can leave the DOM half-swapped, and
+  // neither the old behaviour nor this one has an answer for it.
+  function restoreAfterStructuralOp(focusLine, anchorLine) {
+    // 有 blockSelection 站著時什麼都不做 —— 見 convertBlockViaMenu() 底下那段
+    // 註解：強行還原 caret 會做出「底色仍說已選取、Delete 卻是死鍵」的混種狀態。
+    if (blockSelection) return;
+    if (focusLine != null) {
+      focusBlockAtLine(focusLine, true);   // caretToEnd
+      // 降級目標（quote / code）沒有可聚焦編輯面，focusBlockAtLine 會安靜
+      // no-op；把 toolbarBlockEl 指回那個 block，工具列才不會塌成 4 顆。
+      reaimToolbarBlockAtLine(focusLine);
+      return;
+    }
+    if (anchorLine == null) return;
+    const held = document.activeElement;
+    const heldSurface = held && held.closest
+      ? held.closest('.ed-wys-armed, .ed-wys-cell, .ed-raw') : null;
+    if (heldSurface) {
+      // ⚠ C1. "The caret never left, so there is nothing to do" was TRUE of the
+      // caret and FALSE of the toolbar, and the first version of this guard
+      // skipped both. The bar can be down to 4 while the caret is still sitting
+      // on a live surface, and that is the ORDINARY case, not an edge one: it
+      // is what happens on the PATCH render path, i.e. on every commit after
+      // the first of a page load (`lastParts` is null only for that first one,
+      // so the fallback route — the one this guard was measured on — is
+      // unreachable after it).
+      //
+      // INSTRUMENTED inside applyPatch() on a primed ⠿刪除 refusal, one log
+      // line per step, rather than read off the source:
+      //   route            PATCH
+      //   focusWasInSpan?  v:true  currentBurst:true  burstElAttached:false
+      //                    active:BODY
+      //   afterFocusRestore   active:DIV.ed-li-text ed-wys-armed
+      //                       toolbarBlockElNull:false
+      //   burstSurvived    v:false  currentBurst:true
+      //                    active:DIV.ed-li-text ed-wys-armed
+      //   resetToolbarBlock?  willRun:true
+      //   afterResetToolbarBlock  toolbarBlockElNull:true
+      //   restoreAfterStructuralOp  active:DIV.ed-li-text ed-wys-armed
+      //                             toolbarBlockElNull:true
+      // — applyPatch()'s `focusWasInSpan` block hands focus back to the NEW
+      // surface, and `burstSurvived` is only evaluated afterwards. On this
+      // route `currentBurst` is still the OLD burst (resolveBurst()'s own
+      // teardown has not nulled it yet, which is also why focusin's
+      // `if (currentBurst) return;` stops the focus() from opening a fresh
+      // one), and that old burst's editEl was detached by the patch — so
+      // `burstSurvived` is false and `resetToolbarBlock()` runs AFTER the
+      // caret was handed back. The unprimed run of the same gesture took the
+      // FALLBACK route and arrived here with active:BODY, which is why the
+      // first wave's measurements never saw this.
+      //
+      // So: do not drag the caret (it never left), but DO re-aim the bar, at
+      // the block the caret is actually in rather than at `anchorLine` — those
+      // are the same block on every path measured, and when they ever differ
+      // the caret's own block is the honest answer.
+      const blk = heldSurface.closest('.ed-block');
+      if (blk && document.body.contains(blk)) { toolbarBlockEl = blk; updateToolbar(); }
+      return;
+    }
+    focusBlockAtLine(anchorLine, true);   // caretToEnd
+    reaimToolbarBlockAtLine(anchorLine);
+  }
+
+  // v3.2.1: the caret restore is a THIN WRAPPER around the conversion body so
+  // that it sits at the function's EXIT and every exit reaches it. The body's
+  // pre-commit refusal exits, enumerated (final wave, M2 — the sentence that
+  // stood here said "three" and named three of them):
+  //   1. `if (!operands) return`            — resolveGutterOperands() answered
+  //                                           null (dropped gesture, no source
+  //                                           line, empty/gapped/no-element
+  //                                           batch)
+  //   2. the mixed list/non-list refusal    (BATCH_MIXED_MESSAGE)
+  //   3. the withheld-type refusal          (BATCH_CONVERT_WITHHELD_MESSAGES)
+  //   4. `if (!liRun)`                      (BATCH_MULTIRUN_MESSAGE)
+  //   5. `!listRunSupportsStructuralEdit()` (§4.1's run-wide gate)
+  //   6. `if (!stripped.ok)`                (per-block 「此區塊的格式無法轉換」)
+  // — six, not three, plus `result.op === null` (a commit that wrote nothing)
+  // and the rolled-back render on the tail. Every one of them is reachable
+  // from a lit ⠿ menu item, and the li → list / li → non-list / blocks → list
+  // helpers this function tail-calls carry their own refusals on top.
+  //
+  // The body returns the operated block's post-commit start line, or undefined
+  // when it refused or wrote nothing — `anchor.line` is what covers the
+  // second case (see restoreAfterStructuralOp()).
   async function convertBlockViaMenu(blockEl, target) {
+    let focusLine = null;
+    const anchor = {};
+    try {
+      const out = await convertBlockViaMenuBody(blockEl, target, anchor);
+      if (out != null) focusLine = out;
+    } finally {
+      // v3.2.1: 判準是「有沒有 blockSelection 站著」，不是 operand 數量 ——
+      // 實測 operands.els.length === 1 在「有選取」與「無選取」兩態都成立，
+      // 鑑別力為零。有選取時 declareCollapse() → applySelectionClasses() 已經
+      // 在全新 DOM 上把 roving focus 裝回 .ed-block wrapper（9 種轉換形狀全部
+      // 如此），這時強行還原 caret 會製造混種狀態：底色仍說「已選取」，Delete
+      // 卻變成死鍵、Shift+↓ 降級成移動文字游標。所以有選取時什麼都不做。
+      restoreAfterStructuralOp(focusLine, anchor.line);
+    }
+  }
+
+  async function convertBlockViaMenuBody(blockEl, target, anchor) {
     if (!blockEl || !target) return;
     // §3.3's membership rules and the whole shared preamble — see
     // resolveGutterOperands() above. `els` is ONE contiguous span; the plan's
@@ -3894,7 +4244,7 @@
     // fenced block raw-edited into two paragraphs changes the BLOCK count
     // without changing the LINE count, so an id-indexed delete hit the wrong
     // block, and the same shape silently rewrote a neighbouring table).
-    const operands = await resolveGutterOperands(blockEl);
+    const operands = await resolveGutterOperands(blockEl, anchor);
     if (!operands) return;
     const els = operands.els;
     const recs = operands.recs;
@@ -3967,8 +4317,7 @@
     // the run stays a run and the existing re-serialization machinery applies
     // unchanged.
     if (shape.allLi && convertMd.targetIsList(target)) {
-      await convertListItemsType(els, liRun, recs, target);
-      return;
+      return await convertListItemsType(els, liRun, recs, target);
     }
     // S2 Task 4 / S3 Task 6: li → a NON-list target. The items LEAVE the run,
     // so the span has to be rebuilt in three pieces and §4.3 rule 1's blank
@@ -3976,16 +4325,14 @@
     // lines mid-list with no separator and lazy continuation would swallow them
     // into the item above (measured, §4.3 rule 1).
     if (shape.allLi) {
-      await convertListItemsAway(els, liRun, recs, target);
-      return;
+      return await convertListItemsAway(els, liRun, recs, target);
     }
     // S2 Task 5 / S3 Task 6: non-list blocks BECOME list items, so §4.3 rule
     // 2's looseness policy applies — eat the separator to an adjacent run of
     // the same list type, or the merged list goes LOOSE and every item of it
     // degrades read-only. Same rule, same helper the li → li path above uses.
     if (convertMd.targetIsList(target)) {
-      await convertBlocksIntoList(els, recs, shape.kinds, target);
-      return;
+      return await convertBlocksIntoList(els, recs, shape.kinds, target);
     }
 
     // The plain path: N non-list blocks to a non-list target. One commit over
@@ -4028,6 +4375,11 @@
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 §Task 5: the caller's `focusLine`. NOT a new value and NOT a
+    // pre-commit startLine — it is the very line the collapse above declares,
+    // i.e. the operated span's post-commit first line. The plain path is the
+    // one path that does not move it (the commit replaces the span in place).
+    return first.startLine;
   }
 
   // Is the editor session switchAwayFrom() would resolve open on THIS block?
@@ -4085,12 +4437,51 @@
   // `lines`, and the li path carries the clone through bystanderCarryOver()
   // under the ORIGINAL's block id, so list-md.js replays the file's own bytes
   // for it and only re-states the marker. Both keep a `~5px` a `~5px`.
+  //
+  // v3.2.1: the caret restore is a THIN WRAPPER around the duplication body,
+  // same shape and same reason as convertBlockViaMenu() above: the body has
+  // several exits that duplicate nothing — resolveGutterOperands() answering
+  // null, the mixed-list refusal, each of duplicateListItems()'s four, the
+  // op === null no-op and the failed render on the non-li tail — all of them
+  // reachable from a lit ⠿ menu item, and the wrapper is what makes every one
+  // of them reach the restore. The body answers the ORIGINAL span's first
+  // start line on success and undefined on every one of those exits.
+  //
+  // Final wave: "reach the restore" was true and not sufficient — with
+  // `focusLine` null the restore had nothing to aim at and did nothing. The
+  // refusal exits now land on `anchor.line`; see restoreAfterStructuralOp().
+  //
+  // 落點是【原件】而不是副本。三個理由，其中兩個是這個檔案自己已經寫下的事實：
+  //  1. 一個選單項目只能有一個答案。有 blockSelection 站著時，§3.3 的塌縮把
+  //     集合留在【原件】上（見 body 裡 declareCollapse() 那段註解：副本插在
+  //     所有被複製的東西【下面】，所以原件的行區間原封不動）。落在副本會讓
+  //     「按完 建立副本 之後手上握著什麼」取決於一個看不見的先前狀態。
+  //  2. 原件的行號直接可讀，副本的行號在 li 路徑上要另外付代價。副本帶著
+  //     原件的 data-block-id，所以 runLineOfBlock() 的
+  //     `lineMeta.findIndex((m) => m.blockId === targetId)` 回的是【原件】那
+  //     一行。這不是做不到 —— runLineOfBlock() 對沒有 id 的 block 另有一支
+  //     按位置數行的 fallback，而副本在 span 裡的位置是已知的 `at + 1 + i`。
+  //     代價在別的地方：那個共用的 id 正是 bystanderCarryOver() 逐位元組重播
+  //     副本、而不是重新 escape 它的原因（見下方 duplicateListItems() 的註解，
+  //     一個 '~5px' 不重播就會變成 '\~5px'）。所以這是一個取捨，不是一道牆。
+  //  3. 畫面上沒有東西在使用者底下移動：副本長在下面，原件原地不動。
   async function duplicateBlockViaMenu(blockEl) {
+    let focusLine = null;
+    const anchor = {};
+    try {
+      const out = await duplicateBlockViaMenuBody(blockEl, anchor);
+      if (out != null) focusLine = out;
+    } finally {
+      restoreAfterStructuralOp(focusLine, anchor.line);
+    }
+  }
+
+  async function duplicateBlockViaMenuBody(blockEl, anchor) {
     // §3.3's membership rules plus the shared preamble — see
     // resolveGutterOperands(). The whole span is duplicated by ONE commit; a
     // per-member loop would re-render between items and invalidate every id in
     // between.
-    const operands = await resolveGutterOperands(blockEl);
+    const operands = await resolveGutterOperands(blockEl, anchor);
     if (!operands) return;
     const els = operands.els;
     const recs = operands.recs;
@@ -4098,8 +4489,12 @@
     if (shape.anyLi && !shape.allLi) { refuseStructuralListEdit(BATCH_MIXED_MESSAGE); return; }
 
     if (shape.allLi) {
-      await duplicateListItems(els, recs);
-      return;
+      // recs[0].startLine is unchanged by this commit — duplicateListItems()'s
+      // own declareCollapse() comment is the argument: the copies land after
+      // everything the set owns, and no member's line COUNT can change (a
+      // multi-line target is refused, and §3.8's renumbering only ever changes
+      // marker WIDTH), so the originals still occupy the range they occupied.
+      return (await duplicateListItems(els, recs)) ? recs[0].startLine : undefined;
     }
 
     // The non-li span duplicates as ONE slice of `lines` — separators between
@@ -4126,7 +4521,13 @@
       : undefined;
     if (!(await safeRerenderAll(editRange))) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      return;
     }
+    // The insertion is anchored on the LAST member and lands BELOW it, so
+    // ops.shiftBlocks() moved only ids greater than that one — the span's own
+    // first start line is the same number before and after, which is the same
+    // fact declareCollapse() above relies on.
+    return first.startLine;
   }
 
   // The li half of 建立副本. The copy is spliced into the run's own span and the
@@ -4135,10 +4536,15 @@
   // §3.8's renumbering falls out of the re-serialization ('1. alpha' duplicated
   // gives '1. alpha / 2. alpha / 3. bravo', not '1. alpha / 1. alpha / 2.
   // bravo').
+  //
+  // v3.2.1: returns commitListStructure()'s own true/false, and false for each
+  // of the four refusal exits — duplicateBlockViaMenu()'s wrapper needs to tell
+  // a refusal (nothing was duplicated, the block is still where it was) apart
+  // from a completed duplicate.
   async function duplicateListItems(liEls, recs) {
     // Every list batch is one run's problem — see batchRunOf().
     const run = batchRunOf(liEls);
-    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return; }
+    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return false; }
     // §4.3's run-wide gate — 轉換／建立副本／刪除／拖曳 each make this call for
     // themselves; there is no shared helper. Its input is §3.4 rule 2's scope,
     // which is exactly what listRunOf() returns (the outermost run PLUS every
@@ -4146,14 +4552,14 @@
     // it adds the item's lines over again), so a multi-line li refuses as a
     // TARGET while remaining a perfectly good bystander — and in a batch EVERY
     // member is a target.
-    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return; }
+    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return false; }
     // Captured BEFORE the copy enters the span. The copy carries the
     // ORIGINAL's data-block-id — that is what makes bystanderCarryOver() replay
     // its bytes rather than re-escape them — so runRangeOfBlocks() would
     // resolve it to the original's record, and on a duplicate of the span's
     // LAST member that silently re-states the range's end line.
     const range = runRangeOfBlocks({ lines, blocks, stack }, run);
-    if (!range) return;
+    if (!range) return false;
 
     // §4.3, measured: after the SUBTREE, not after the item's own line.
     // subtreeBlocksAfter() is the flat model's subtree — the contiguous run of
@@ -4166,7 +4572,7 @@
     const subtree = subtreeBlocksAfter(anchorLi, Number(anchorLi.getAttribute('data-indent')) || 0);
     const lastEl = subtree.length ? subtree[subtree.length - 1] : anchorLi;
     const at = run.indexOf(lastEl);
-    if (at < 0) return;
+    if (at < 0) return false;
 
     const copies = liEls.map((liEl) => liEl.cloneNode(true));
     // `data-list-start` is the ONLY carrier of "marked's lexer opened a new
@@ -4209,33 +4615,161 @@
       startLine: recs[0].startLine,
       endLine: recs[recs.length - 1].endLine,
     });
-    await commitListStructure(span, null, false,
+    return await commitListStructure(span, null, false,
       { presetRange: range, carryOver: bystanderCarryOver(span) });
   }
   // Deletes `blockEl`'s ENTIRE line range (generalizing commitListBlockRemoval()
   // — unchanged, see its own comment — to any block type, not just an
   // emptied-out list). Same resolve-first / re-query-live-block-by-id
   // precondition as insertBlockBelow() above.
+  //
+  // v3.2.1: the caret restore is a THIN WRAPPER around the removal body, same
+  // shape as convertBlockViaMenu() above. A delete has no "back to the block it
+  // operated on" — the block is gone — so the body answers the HOLE's line
+  // coordinate (the removed span's own first start line) and
+  // blockLineAfterRemoval() below turns that into a block that still exists.
+  //
+  // 有 blockSelection 站著時什麼都不做的判準與 convertBlockViaMenu() 相同，
+  // 但在這條路徑上它幾乎總是讓路：批次刪除的 §3.3 塌縮是 declareCollapse(null)
+  // ＝清空集合（見 body 內那段註解），render 之後 blockSelection 已經是 null。
+  // 那是對的 —— 沒有集合站著就沒有「底色仍說已選取、Delete 卻是死鍵」的混種
+  // 狀態可言，而使用者剛把手上唯一的著力點刪掉，更需要拿回一個。
   async function deleteBlockViaGutter(blockEl) {
+    let removed = null;
+    const anchor = {};
+    try {
+      const out = await deleteBlockViaGutterBody(blockEl, anchor);
+      if (out) removed = out;
+    } finally {
+      // Final wave: on the refusal / rolled-back-render exits `removed` is
+      // null, so the landing falls through to `anchor.line` — the block the
+      // gesture named, which a refusal left exactly where it was. On the
+      // SUCCESS path that block no longer exists, which is why the success
+      // coordinate is blockLineAfterRemoval()'s carried neighbour and not the
+      // anchor: restoreAfterStructuralOp() only consults `anchor.line` when
+      // the first argument is null.
+      const focusLine = removed ? blockLineAfterRemoval(removed) : null;
+      // `anchor.line` is the line of the block that was just DELETED, so it is
+      // offered only when the body refused. A successful delete that cannot
+      // name a landing (blockLineAfterRemoval() answering null — an emptied
+      // document) must restore nothing rather than aim at the hole.
+      restoreAfterStructuralOp(focusLine, removed ? null : anchor.line);
+    }
+  }
+
+  // The block the user is left holding once a span has been removed. Takes the
+  // `{ prevLine, spanIsFirst }` the body captured BEFORE its commit:
+  //
+  //   prevLine    the block immediately ABOVE the removed span, or null when
+  //               there is none. A PRE-commit start line, and stable across the
+  //               render for ONE reason that covers every path, not a reason
+  //               per path:
+  //
+  //                 commitRangeRemoval() and commitRangeEdit() compute the
+  //                 SAME anchor — `blocks.filter((b) => b.endLine <= endLine)
+  //                 .pop()`, textually identical in both — and hand it to
+  //                 ops.shiftBlocks(), which moves a block only when
+  //                 `b.id > editedId` (lineops.js). Ids are positional
+  //                 ordinals in document order, so the block above the span has
+  //                 a SMALLER id than every block inside it, and the anchor is
+  //                 at least the span's last member (that member is itself in
+  //                 the filtered list). The neighbour therefore fails
+  //                 `b.id > editedId` whichever helper runs.
+  //
+  //               ⚠ Fix round 3. The sentence that stood here said the li path
+  //               calls NEITHER of those helpers. That is false, and its own
+  //               named example is the counter-example: commitListStructure()
+  //               routes `md === ''` — no survivors, i.e. a WHOLE-RUN delete —
+  //               straight into commitRangeRemoval(). Instrumented and driven
+  //               rather than read: 刪除 over all three items of
+  //               '- alpha / - bravo / - charlie' printed
+  //                 commitRangeRemoval range=5..7 anchor=id4(7..7)
+  //                 shiftBlocks editedId=4 delta=-4 movedIds=[5] untouchedIds=[0,1,2,3,4]
+  //               while a partial delete of the same run printed
+  //                 commitRangeEdit range=5..7 anchor=id4(7..7)
+  //                 shiftBlocks editedId=4 delta=-1 movedIds=[5] untouchedIds=[0,1,2,3,4]
+  //               — two different helpers, the same anchor, and in both the
+  //               neighbour (id1) sits in `untouchedIds`. Five gestures were
+  //               instrumented this way (whole run, middle item, first item, a
+  //               non-li paragraph, and a run that is the entire document) and
+  //               the neighbour was untouched in all five.
+  //   spanIsFirst true when the removed span WAS the document's first block, so
+  //               "no previous block" is a fact rather than a failed lookup —
+  //               see deleteBlockViaGutterBody()'s own comment for why those two
+  //               are not the same answer.
+  //
+  // 「上面那一個、游標落在它的結尾」是 Notion 的答案，也是 Backspace 併行的
+  // 落點；這個編輯器的 ⠿ / 建立副本 / 轉換成 整組詞彙都是 Notion 的。
+  //
+  // ⚠ Fix round 1, item 2: this used to INFER the neighbour from the hole's
+  // coordinate — "the largest post-render startLine strictly below it". That is
+  // wrong whenever commitRangeRemoval() takes its `sl -= 1` branch (the line
+  // after the span is not blank, so it absorbs the blank ABOVE instead): every
+  // block BELOW the hole then moves up too, the first of them lands one line
+  // ABOVE the hole's own start line, and taking the maximum picks THAT
+  // deterministically over the real previous block. Driven on '…Bravo para.\n' immediately followed by
+  // a block that interrupts a paragraph — an ATX heading, a list, a fenced
+  // code block, an hr — the caret landed on the block BELOW the hole in all
+  // four, and on the code / hr shapes (no focusable surface) it landed nowhere
+  // at all. The answer is not derivable from the hole; it has to be carried.
+  //
+  // With `spanIsFirst`, whatever is first NOW is the block that moved up into
+  // the hole — `blocks[0]`, no search needed. Answers null for a delete that
+  // emptied the document, and for the unreachable "span not found" case, where
+  // guessing a block is worse than restoring no caret at all.
+  function blockLineAfterRemoval(removed) {
+    if (removed.prevLine != null) return removed.prevLine;
+    if (!removed.spanIsFirst) return null;
+    return blocks.length ? blocks[0].startLine : null;
+  }
+
+  async function deleteBlockViaGutterBody(blockEl, anchor) {
     // §3.3's membership rules plus the shared preamble (identity capture,
     // switchAwayFrom(), the re-resolve after a commit that re-rendered, and the
     // no-source-line refusal) — see resolveGutterOperands(). The stake on the
     // re-resolve is highest here: an id shift used to make this delete a
     // DIFFERENT block's lines, with the ⠿ menu the user pressed pointing at a
     // block that survived.
-    const operands = await resolveGutterOperands(blockEl);
+    const operands = await resolveGutterOperands(blockEl, anchor);
     if (!operands) return;
     const els = operands.els;
     const recs = operands.recs;
     const shape = spanListKinds(els);
     if (shape.anyLi && !shape.allLi) { refuseStructuralListEdit(BATCH_MIXED_MESSAGE); return; }
+    // Fix round 1, item 2: the block immediately ABOVE the span, read out of
+    // the PRE-commit `blocks` and carried to the wrapper. It cannot be
+    // recovered afterwards from the hole's coordinate — see
+    // blockLineAfterRemoval()'s own comment for the measurement. `blocks` is in
+    // document order (blockmap.js hands out a positional ordinal), so the
+    // element before recs[0] is that neighbour.
+    //
+    // Located by OBJECT IDENTITY, and the three outcomes are kept apart on
+    // purpose (fix round 2, item 3 — `at > 0` folded the third into the
+    // second and would have landed the caret on the document's first block
+    // with no signal at all):
+    //   at > 0   there is a previous block; its start line is the landing.
+    //   at === 0 the span IS the document's first block — `spanIsFirst` tells
+    //            blockLineAfterRemoval() to take the moved-up fallback.
+    //   at < 0   recs[0] is not in `blocks`. Unreachable as written:
+    //            resolveGutterOperands() builds `recs` from this very array
+    //            (blockRecOf()'s `blocks.find()` for the single case,
+    //            selection.js's membersOf() `blocks.filter()` for the batch —
+    //            both hand back the SAME object references), and nothing
+    //            awaits between its return and this line, so `blocks` cannot
+    //            have been replaced in between. If it ever becomes reachable,
+    //            both flags stay false/null and the wrapper simply restores no
+    //            caret and re-aims the toolbar — a bar-only degrade, never a
+    //            landing on the wrong block.
+    const at = blocks.indexOf(recs[0]);
+    const prevLine = at > 0 ? blocks[at - 1].startLine : null;
+    const spanIsFirst = at === 0;
     // Spec §6, "S1 期間的已知危險" item 1: a LIST ITEM's delete is not a line
     // splice. S1 is what first put a ⠿ on a li, and the plain range removal
     // below corrupts a list three separate ways — see
     // deleteListItemsViaGutter() for the measurements and the routing.
     if (shape.allLi) {
-      await deleteListItemsViaGutter(els);
-      return;
+      return (await deleteListItemsViaGutter(els))
+        ? { prevLine: prevLine, spanIsFirst: spanIsFirst } : undefined;
     }
     // A contiguous span of non-list blocks is one line range: the separators
     // between its members are inside it by construction (members are adjacent
@@ -4264,7 +4798,9 @@
     const okRender = await safeRerenderAll(editRange);
     if (!okRender) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      return;
     }
+    return { prevLine: prevLine, spanIsFirst: spanIsFirst };
   }
 
   // Spec §6, "S1 期間的已知危險" item 1 — the ⠿ delete of a LIST ITEM.
@@ -4295,19 +4831,24 @@
   // commit the re-serialized survivors over that range with every one of them
   // carried over verbatim — nothing here rewrites any survivor's CONTENT, only
   // its marker and its leading columns.
+  //
+  // v3.2.1: returns commitListStructure()'s own true/false, and false for each
+  // of its three refusal exits — deleteBlockViaGutter()'s wrapper needs to tell
+  // a refusal (nothing was removed, the block is still where it was) apart from
+  // a completed delete before it goes looking for a neighbour.
   async function deleteListItemsViaGutter(liEls) {
     // Every list batch is one run's problem — see batchRunOf().
     const run = batchRunOf(liEls);
-    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return; }
+    if (!run) { refuseStructuralListEdit(BATCH_MULTIRUN_MESSAGE); return false; }
     // §4.3's run-wide gate, whose input is §3.4 rule 2's scope — which is
     // exactly what listRunOf() returns (the outermost run PLUS every
     // descendant of its members), so the deeper runs this delete is about to
     // re-indent are covered, not just the target's own. Deleting is NOT
     // column-only: it removes the target's lines outright, so a multi-line
     // target refuses per §4.1 — and in a batch every member is a target.
-    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return; }
+    if (!listRunSupportsStructuralEdit(run, liEls)) { refuseStructuralListEdit(); return false; }
     const range = runRangeOfBlocks({ lines, blocks, stack }, run);
-    if (!range) return;
+    if (!range) return false;
     // §3.4 rule 3's batch anchor: the SMALLEST old indent in the set, never the
     // first member's — see spanMinIndent().
     const oldIndent = spanMinIndent(liEls);
@@ -4333,7 +4874,7 @@
     // this path is the one it makes after the commit — the `!range` bail above
     // it cannot fire, `presetRange` is non-null by construction here.
     declareCollapse(null);
-    await commitListStructure(survivors, null, false,
+    return await commitListStructure(survivors, null, false,
       { presetRange: range, carryOver: bystanderCarryOver(survivors) });
   }
 
@@ -4555,6 +5096,10 @@
     });
     await commitListStructure(run, null, false,
       { presetRange: range, carryOver: bystanderCarryOver(run) });
+    // v3.2.1 §Task 5: the caller's `focusLine` — the same post-shift line the
+    // collapse just declared, never the pre-commit startLine (the merge
+    // widening above moves it by exactly `shift`).
+    return recs[0].startLine + shift;
   }
 
   // The `data-block-type` a conversion target will carry once it is committed.
@@ -4703,6 +5248,11 @@
     if (!(await safeRerenderAll(editRange))) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 §Task 5: the caller's `focusLine` — the converted piece's own
+    // first emitted line, which is what the collapse above declares. The
+    // pre-commit startLine is wrong here: the split rebuilds the run in three
+    // pieces and §4.3 rule 1's blanks move the converted half.
+    return outStart;
   }
 
   // S2 Task 5 — 轉換成 › 項目符號列表 / 編號列表 / 待辦清單 on a block that is
@@ -4765,6 +5315,10 @@
     if (!(await safeRerenderAll(editRange))) {
       lines = rollbackFailedRender({ lines, stack }, result, prevLines);
     }
+    // v3.2.1 §Task 5: the caller's `focusLine` — the WIDENED range's first
+    // line, which is where the merged list actually starts. `recs[0].startLine`
+    // would be wrong whenever §4.3 rule 2 ate a separator above the span.
+    return merged.startLine;
   }
 
   // The `.ed-li-check` chrome for a li that has just BECOME a task item.
@@ -4817,12 +5371,18 @@
       // focus/blur cycle on that same block (click into it, click back out
       // — e.g. after Esc-ing the raw editor) re-armed that same stale DOM
       // and committed it as if it were live content: the "discarded" edit
-      // resurrected itself into `lines`. Restore the pre-edit snapshot
-      // FIRST, mirroring revertBurstAndEnd()'s own contract, so nothing is
-      // left behind for a later burst to accidentally pick up and commit.
-      currentBurst.editEl.innerHTML = currentBurst.original;
-      currentBurst.history.dispose();
+      // resurrected itself into `lines`.
+      // v3.2.1: 先清 currentBurst 再寫 innerHTML。對 TABLE burst，editEl 是
+      // <table> 而聚焦節點是子代 .ed-wys-cell，所以這個寫入會 detach 聚焦的
+      // cell；Chromium 同步派發 focusout，而 focusout 的 table 分支只要
+      // currentBurst 非 null 就會 resolveBurst() 並提交 —— 這顆按鈕的職責是
+      // 丟棄，實測卻把打的字寫進磁碟。revertTableBurstAndEnd() 早就是這個
+      // 順序，而它的註解正是說明「先清 currentBurst」才是它不需要抑制旗標
+      // 的原因；上一版這裡的註解宣稱在鏡像那份契約，實際把它倒過來了。
+      const dyingBurst = currentBurst;
       currentBurst = null;
+      dyingBurst.history.dispose();
+      dyingBurst.editEl.innerHTML = dyingBurst.original;
       resetSelToolbarState();
     } else {
       const ok = await switchAwayFrom();
@@ -7033,10 +7593,34 @@
         // (/[ \t]+$/) does not, so it would survive into the committed line.
         // Either way the user sees an empty item and must get a bare '-'. Clear
         // the surface under the SAME normalisation the branch condition used —
-        // liSurfaceHoldsNothing() — inside the suppression span (an innerHTML
-        // assignment on the focused node triggers the very same Chromium unfocus
-        // quirk), and only once the outdent above has actually happened, since a
-        // refused press must leave the DOM byte-identical.
+        // liSurfaceHoldsNothing() — and only once the outdent above has
+        // actually happened, since a refused press must leave the DOM
+        // byte-identical.
+        //
+        // ⚠ Final wave, I4. The sentence that stood here said this innerHTML
+        // assignment is itself a reason the write must sit inside
+        // mutateListRun()'s suppression span — "an innerHTML assignment on the
+        // focused node triggers the very same Chromium unfocus quirk". MEASURED
+        // false, and its own premise is the counter-example: `textEl` IS the
+        // focused node, and writing its innerHTML replaces only its SUBTREE —
+        // the element itself is never detached. Control experiment, driven in a
+        // real page: focus a `.ed-li-text`, count focusout on it and on
+        // `document` (capture), then assign `''` — 0 focusout, 0 blur,
+        // `document.activeElement` still that same node, node still in the
+        // document.
+        //
+        // What the span IS for is written at `suppressLiFocusout`'s own
+        // declaration: a structural list key can move, split or REMOVE the
+        // focused block, and Chromium's synchronous unfocus then reaches
+        // resolveBurst() with the run still in its pre-mutation shape. This
+        // assignment is inside the span because it is part of the same
+        // mutation, not because it contributes a focusout of its own.
+        //
+        // No claim is made here about WHICH callee needs it, and deliberately
+        // not about outdentListItem(): that function is attribute-only in this
+        // flat model — it calls setBlockIndent() on the block and its subtree
+        // (`data-indent` + a CSS custom property) and re-parents nothing, so it
+        // is not the answer either.
         const textEl = liTextEl(li);
         if (textEl && liSurfaceHoldsNothing(textEl)) textEl.innerHTML = '';
         return true;
@@ -7789,6 +8373,20 @@
   // (possibly now-stale, post-delete) column/row it came from.
   let teHighlightEls = [];
 
+  // v3.2.1 fix round 1: same idiom as `suppressTableFocusout`/
+  // `suppressLiFocusout` above — a flag set for the exact synchronous-ish
+  // span of one operation that would otherwise be torn down by a listener
+  // reacting to a side effect THAT OPERATION ITSELF triggers. Here:
+  // runCycleAlign()'s `ensureTableBurstOpen()` can call a cell's `.focus()`,
+  // which can scroll the page for real — and the resulting 'scroll' event
+  // is asynchronous relative to the focus() call (measured: it does not
+  // reliably land before runCycleAlign()'s own code resumes after the
+  // `await`), so a plain "check teMenuKind again afterward" re-open would
+  // race it and sometimes miss. onAnyScroll() checks this flag before
+  // calling hideTableEdgeMenu() so the menu's open state is never torn down
+  // in the first place during that span, whichever tick the event lands on.
+  let suppressEdgeMenuAutoHide = false;
+
   function clearEdgeHighlight() {
     // classList.remove() leaves a dangling `class=""` behind on any element
     // the renderer/armEditables() emitted with NO class of its own — a
@@ -8012,14 +8610,84 @@
     const colIndex = teMenuColIndex;
     if (!tableEl || colIndex == null) return;
     // Final-review Finding 6: same live-table swap as runDeleteColumn() above.
-    const liveTableEl = await ensureTableBurstOpen(tableEl);
-    if (!liveTableEl) return;
-    cycleColumnAlign(liveTableEl, colIndex);
-    currentBurst.history.snap('align-col');
-    // Stays open (unlike delete): repeated clicks keep cycling. The
-    // column's cells are the SAME nodes (cycleColumnAlign() only touches
-    // the `style` attribute) so the existing highlight is still valid —
-    // nothing to reposition/rehighlight.
+    // v3.2.1 fix round 1: ensureTableBurstOpen() below can call a cell's
+    // .focus(), which can scroll the page for real — and v3.2.1's onAnyScroll
+    // (this file's module-level scroll listener) calls hideTableEdgeMenu() on
+    // every scroll, which would reset teMenuKind/teMenuTableEl/teMenuColIndex
+    // to null and un-highlight the column, breaking this function's own
+    // "stays open, repeated clicks keep cycling" contract below. Measured
+    // TWICE: (1) a plain "re-check state and re-show if it changed" fix
+    // RACES the resulting 'scroll' event, which is asynchronous relative to
+    // the `.focus()` call and does not reliably land before this function
+    // resumes after the `await` — so suppress the menu's own auto-hide for
+    // this span instead (`suppressEdgeMenuAutoHide`, see its own comment).
+    // (2) clearing that suppression in a plain `finally` right after the
+    // `await` ALSO raced it — the pending 'scroll' event can land AFTER this
+    // function has already resumed and cleared the flag, since a
+    // `focus()`-triggered scroll is not guaranteed to be delivered within
+    // the same microtask turn as the promise chain above. Measured fix:
+    // browsers dispatch a pending scroll before the next
+    // requestAnimationFrame callback runs (it is part of the "update the
+    // rendering" steps that precede rAF callbacks in the same frame), so
+    // holding the flag through one rAF tick lets a pending scroll land AND
+    // be swallowed before this lifts it.
+    let liveTableEl;
+    suppressEdgeMenuAutoHide = true;
+    try {
+      liveTableEl = await ensureTableBurstOpen(tableEl);
+      if (!liveTableEl) { suppressEdgeMenuAutoHide = false; return; }
+      cycleColumnAlign(liveTableEl, colIndex);
+      currentBurst.history.snap('align-col');
+    } catch (e) {
+      suppressEdgeMenuAutoHide = false;
+      throw e;
+    }
+    requestAnimationFrame(() => {
+      suppressEdgeMenuAutoHide = false;
+      // Fix round 2 (Important, caught by the re-reviewer): suppressing
+      // hideTableEdgeMenu() only stops onAnyScroll from closing the menu —
+      // it does NOT stop `ensureTableBurstOpen()`'s own `switchAwayFrom()`
+      // from closing it for an UNRELATED, legitimate reason when a burst was
+      // open on a DIFFERENT block: switchAwayFrom() -> resolveBurst() ->
+      // hideTableEdgeMenu() (unconditional, not suppressed — only
+      // onAnyScroll's call is gated) nulls teMenuKind/teMenuTableEl/
+      // teMenuColIndex and clears the highlight. Without this guard the
+      // unconditional reposition below would then make that CORRECTLY-
+      // closed menu visible again — empty of highlight, and inert (its own
+      // teMenuKind/teMenuColIndex are null, so a second 對齊/刪除欄 click
+      // reads no target and does nothing) — floating over the document
+      // until the next scroll happens to close it for an unrelated reason.
+      // Only reposition when the menu is STILL the one this call opened:
+      // same kind, same column, and the table identity matches EITHER
+      // `tableEl` (showColumnMenu() was called with this — the pre-swap
+      // identity, read from its own definition above — and nothing since
+      // has touched teMenuTableEl) or `liveTableEl` (belt-and-braces, in
+      // case some future path re-opens the menu against the live node).
+      if (teMenuKind !== 'col' || teMenuColIndex !== colIndex ||
+          (teMenuTableEl !== liveTableEl && teMenuTableEl !== tableEl)) return;
+      // Stays open (unlike delete) UNLESS ensureTableBurstOpen()'s
+      // switchAwayFrom() legitimately closed it above (guard just above) —
+      // repeated clicks keep cycling. The column's cells are the SAME nodes
+      // (cycleColumnAlign() only touches the `style` attribute) so the
+      // existing highlight is still valid — nothing to rehighlight.
+      // `.ed-te-menu` is `position: fixed` (viewport-relative) though, so if
+      // the suppressed span above actually scrolled the page, its left/top
+      // are now stale relative to the header cell; reposition on every call
+      // that gets past the identity guard three lines up (same math as
+      // showColumnMenu(), skipping its toggle-closed branch — that branch would
+      // wrongly close a menu that never actually asked to close). Final wave,
+      // M1: "unconditionally" is what this said before that guard was added,
+      // and it stopped being true then — a call whose menu is no longer the one
+      // it opened returns above and repositions nothing. A no-op scroll makes
+      // this a no-op reposition (same numbers back).
+      const headerRow = headerRowOf(liveTableEl);
+      const cell = headerRow ? headerRow.cells[colIndex] : null;
+      if (cell) {
+        const r = cell.getBoundingClientRect();
+        positionTeMenu(r.left, r.top);
+        teEdgeMenu.style.top = (r.top - teEdgeMenu.offsetHeight - TE_MENU_GAP_PX) + 'px';
+      }
+    });
   }
 
   // ── Notion-style row/column grip handles ─────────────────────────────
@@ -9962,6 +10630,56 @@
     return r;
   }
 
+  // v3.2.1: 在字元空間修剪 Range 的前後空白，再交給 wrapRangeIn()。
+  // 不用 startOffset/endOffset 步進：當邊界容器是【元素節點】時那些 offset
+  // 索引的是【子節點】而非字元，一次遞減會跳過整個文字節點。實測人類拖曳
+  // 選取 105 次都不會產生元素邊界，但編輯器自己的 reselectAndReposition() 會。
+  function trimRangeToText(range) {
+    const parts = [];
+    const take = (n) => {
+      const len = n.data.length;
+      let a, b;
+      try { a = range.comparePoint(n, 0); b = range.comparePoint(n, len); }
+      catch (e) { return; }
+      if (b < 0 || a > 0) return;                 // 整個節點落在範圍外
+      const from = (n === range.startContainer && n.nodeType === 3) ? range.startOffset : 0;
+      const to = (n === range.endContainer && n.nodeType === 3) ? range.endOffset : len;
+      if (to > from) parts.push({ n: n, from: from, to: to });
+    };
+    const root = range.commonAncestorContainer;
+    const walk = (node) => {
+      if (node.nodeType === 3) { take(node); return; }
+      for (let c = node.firstChild; c; c = c.nextSibling) walk(c);
+    };
+    // v3.2.1 review: root.nodeType === 3 的情況已經由 walk() 自己的
+    // `node.nodeType === 3` 分支正確處理（single-text-node 選取時
+    // startContainer/endContainer 必為同一個 text node，也就是這裡的
+    // root——take() 的 `n === range.startContainer`／`n === range.endContainer`
+    // 判斷照樣成立）。原本 `root.nodeType === 3 ? root : root` 兩支完全相同，
+    // 是無效的死碼，這裡直接呼叫 walk(root)；journey 測試（選取整個落在單一
+    // text node 內）已驗證這條路徑產出正確的 from/to。
+    walk(root);
+    if (!parts.length) return false;
+    // 從頭砍掉空白
+    while (parts.length) {
+      const p = parts[0];
+      while (p.from < p.to && /\s/.test(p.n.data[p.from])) p.from++;
+      if (p.from < p.to) break;
+      parts.shift();
+    }
+    // 從尾砍掉空白
+    while (parts.length) {
+      const p = parts[parts.length - 1];
+      while (p.to > p.from && /\s/.test(p.n.data[p.to - 1])) p.to--;
+      if (p.to > p.from) break;
+      parts.pop();
+    }
+    if (!parts.length) return false;              // 全空白選取 → 不包裝
+    range.setStart(parts[0].n, parts[0].from);
+    range.setEnd(parts[parts.length - 1].n, parts[parts.length - 1].to);
+    return true;
+  }
+
   // Marks of `tag` that the range overlaps (fully or partially) — called
   // only AFTER wholeSelectionMark() has already returned null, so any hit
   // here is by construction a partial-overlap case (see the toggle-policy
@@ -10025,26 +10743,190 @@
       snapBurstIfActive(root, 'mark');
       return;
     }
+    if (!trimRangeToText(range)) return;   // 全空白／collapsed 選取：no-op
     reselectAndReposition(wrapRangeIn(range, tag));
     snapBurstIfActive(root, 'mark');
   }
 
+  // Resolves once a `focusout` has been dispatched at `el` AND that dispatch
+  // has fully finished, or after `ms` milliseconds if no focusout arrives at
+  // all — whichever comes first.
+  //
+  // Two things about it are load-bearing and both were measured on the 🔗
+  // gesture:
+  //
+  //  * The wait is needed because the blur a native modal causes is delivered
+  //    on the browser's own schedule, NOT as a task queued by the code that
+  //    opened the modal: window.prompt() returned at t=27ms and the focusout
+  //    landed at t=28ms, i.e. after the caller had already returned. So a plain
+  //    setTimeout(0) is not a substitute for listening.
+  //  * The resolve is handed to a TIMER rather than called from the listener.
+  //    A listener's own resolve() only queues a microtask, and the HTML spec
+  //    performs a microtask checkpoint after EACH listener callback of a
+  //    browser-initiated dispatch — so an awaiter resumed from there runs
+  //    BEFORE the document-level focusout delegator further along the same
+  //    propagation path, and therefore before anything that delegator starts
+  //    exists to be waited on. Measured exactly that way: resolving from the
+  //    listener left `switching` still null at the awaiter, and the caret was
+  //    lost to the render that followed. A timer moves the resume to the next
+  //    task, after the whole dispatch.
+  function nextFocusout(el, ms) {
+    return new Promise((resolve) => {
+      let deadline = null;
+      const finish = () => {
+        el.removeEventListener('focusout', onFocusout);
+        if (deadline !== null) { clearTimeout(deadline); deadline = null; }
+        resolve();
+      };
+      const onFocusout = () => { setTimeout(finish, 0); };
+      el.addEventListener('focusout', onFocusout);
+      deadline = setTimeout(finish, ms);
+    });
+  }
+
+  // v3.2.1: THIN WRAPPER over the toggle body below, same shape as
+  // convertBlockViaMenu() — but the restoration cannot sit in a plain
+  // synchronous finally here, and that is the whole difference. MEASURED, with
+  // an in-page focus/mutation trace on the 🔗 button:
+  //
+  //   t=21ms  window.prompt() entered      t=27ms  prompt() returned
+  //   t=28ms  focusout on the armed surface (the modal's own blur, delivered
+  //           after the body had already finished its DOM surgery)
+  //   t=31ms  focusin — the browser hands focus straight back
+  //   t=52ms  a SECOND focusout, this one from applyFullRender() (captured
+  //           stack: applyFullRender <- applyRenderResult <- rerenderAll)
+  //   t=66ms  document.activeElement === BODY, toolbar down to 4 buttons
+  //
+  // So the thing that costs the user their foothold is not the modal: focus
+  // comes back on its own. It is that the document's focusout delegator read
+  // the modal's blur as "the user left this surface" and ran switchAwayFrom()
+  // -> resolveBurst() -> commitEdit() -> rerenderAll(), and that render
+  // replaced the whole .content subtree the restored focus was sitting in.
+  // The other four inline-format buttons (toolbar-model.js's `group: 'inline'`
+  // is bold / italic / strike / inline-code / link — five, of which link is
+  // this one) never hit this, because none of them opens a modal and so none
+  // of them ever blurs.
+  //
+  // The two awaits below are therefore each waiting for one specific thing:
+  // nextFocusout() for that blur to be dispatched at all, and `switching` for
+  // the commit + render it started to finish. Only then is there a live block
+  // to aim at.
+  async function applyLinkToggle() {
+    const root = selToolbarEditEl;
+    const sel = typeof window.getSelection === 'function' ? window.getSelection() : null;
+    // hasFormattableSelection() is the body's own four guards spelled once (see
+    // its comment). When it is false the body returns before it can reach
+    // window.prompt(), so there is no modal, no blur, and nothing to wait for.
+    // Waiting anyway would stall this call for the whole timeout and then move
+    // the caret to the end of a block the user never edited.
+    //
+    // ⚠ Final wave, I3. `willPrompt` is a NECESSARY condition for a modal, not
+    // a sufficient one, and the sentence that used to stand at the restore
+    // said otherwise. Those four guards do match the body's four, but the body
+    // has a FIFTH pre-prompt exit they know nothing about: the
+    // `overlapping.length > 0` branch, where a selection that only PARTIALLY
+    // overlaps an existing link unwraps it and returns without ever calling
+    // window.prompt(). MEASURED on ddac6ce — selecting `lpha lin` across
+    // `Alpha <a>linked</a> …` and clicking 🔗 gave `dialogs: 0` while
+    // `willPrompt` was true. Behaviour was still correct there, but only
+    // because the `stillHeld` gate below happened to catch it; the guarantee
+    // the comment claimed did not exist. So the body now REPORTS whether it
+    // prompted and the wait is gated on that report rather than on the
+    // prediction. `blurred` still has to be ARMED before the body runs (the
+    // blur it waits for is caused from inside it) — an armed-but-unused
+    // promise settles on its own 400ms timeout, which removes its own listener
+    // and resolves nobody.
+    const willPrompt = hasFormattableSelection(sel);
+    // Captured BEFORE the body: `selToolbarEditEl` is one of the things the
+    // render nulls. The LINE survives that render — resolveBurst() commits
+    // through commitEdit(state, burst.blockId, newText), an in-place replace of
+    // this block's own line range, and ops.shiftBlocks() only shifts blocks
+    // whose id is GREATER than the edited one, so nothing can move this block's
+    // own start line.
+    const rec = willPrompt && root && root.closest
+      ? blockRecOf(root.closest('.ed-block')) : null;
+    const line = rec ? rec.startLine : null;
+    // Armed before the body runs, because the blur it is waiting for is caused
+    // by a call inside the body. The timeout is the fallback for a browser that
+    // does not blur on a modal at all; its cost when it fires is one caret
+    // moved to the end of the block the link was just written into.
+    const blurred = willPrompt && root ? nextFocusout(root, 400) : null;
+    let prompted = false;
+    try {
+      prompted = applyLinkToggleBody() === true;
+    } finally {
+      if (blurred && prompted) {
+        await blurred;
+        if (switching) await switching;
+        // Fix round 1, item 1: reaching here means the modal DID open (the
+        // body said so), not that the user confirmed it. On Esc / cancel the body does no DOM
+        // surgery, the burst goes out through endBurstWithoutResolve(), there
+        // is no commit and no render — and the focus the modal took comes back
+        // by itself (the t=31ms focusin in the trace above). Restoring on top
+        // of that collapses the user's selection to a caret at the block's end.
+        // Driven, 🔗 then Esc: with this gate the selection is still 'Alpha'
+        // (non-collapsed, 20 buttons); without it, '' and collapsed.
+        //
+        // So the restore only fires when the foothold is actually GONE. The
+        // accept path is unaffected — the render has just run and
+        // activeElement is BODY there — and a 400ms timeout misfire becomes
+        // harmless for the same reason.
+        const held = document.activeElement;
+        const stillHeld = held && held.closest &&
+          held.closest('.ed-wys-armed, .ed-wys-cell, .ed-raw');
+        // 有 blockSelection 站著時什麼都不做 —— 與 convertBlockViaMenu() 同一個
+        // 判準、同一個理由：強行還原 caret 會做出「底色仍說已選取、Delete 卻是
+        // 死鍵」的混種狀態。
+        if (!stillHeld && !blockSelection && line != null) {
+          focusBlockAtLine(line, true);   // caretToEnd
+        }
+        // ⚠ C1, second occurrence of the same root cause. The re-aim used to
+        // sit INSIDE the `!stillHeld` branch, so a call that kept its foothold
+        // restored nothing at all — and on the PATCH render path (every commit
+        // after a page load's first) applyPatch() hands focus back to the new
+        // surface and only THEN runs resetToolbarBlock(), so "foothold held"
+        // and "bar collapsed to 4" are the ordinary combination, not a
+        // contradiction. Measured, 🔗 accept: unprimed P.ed-wys-armed/15,
+        // primed P.ed-wys-armed/4. The caret restore stays gated (fix round
+        // 1's Esc/cancel finding); only the bar comes out.
+        if (!blockSelection && line != null) {
+          // 就【這個還原目前所攜帶的座標】（一個 block 的起始行）而言，TABLE
+          // 儲存格是還原不回 caret 的形狀：`root` 是 CELL，但 `line` 只能指到
+          // 整張表這個 block，而 blockContentEl() 對 table 回傳
+          // firstElementChild ＝ <table> 本身，它沒有 tabindex、focus() 是
+          // no-op。實測結果因此是 journey 的 bar-only 形狀（V2d 釘住）：連結
+          // 正確寫進磁碟、工具列 15 顆仍瞄著那張表，但 activeElement 是 BODY。
+          // 這不是死路 —— 儲存格的 (row, col) 在 re-render 之間是穩定的，帶著
+          // 它就能還原；只是本版沒有帶。reaim 是目前這個形狀下唯一還拿得回來
+          // 的東西 —— 沒有它工具列會塌成 4 顆。
+          reaimToolbarBlockAtLine(line);
+        }
+      }
+    }
+  }
+
   // Link is its own entry point (not applyMarkToggle) because "unwrap" here
   // means "prompt to edit or clear the URL", and "wrap" means "prompt for a
   // URL first" — both need window.prompt() before any DOM surgery happens.
-  function applyLinkToggle() {
+  //
+  // Final wave, I3: returns TRUE iff this call actually reached a
+  // window.prompt(), and false on every exit that did not — the four guards at
+  // the top AND the partial-overlap unwrap in the middle, which is the one the
+  // wrapper's `willPrompt` prediction cannot see. The wrapper waits for the
+  // modal's blur only on a true.
+  function applyLinkToggleBody() {
     const root = selToolbarEditEl;
-    if (!root) return;
+    if (!root) return false;
     const sel = window.getSelection();
-    if (!sel.rangeCount) return;
+    if (!sel.rangeCount) return false;
     const range = sel.getRangeAt(0);
-    if (range.collapsed) return;
-    if (!root.contains(range.startContainer) || !root.contains(range.endContainer)) return;
+    if (range.collapsed) return false;
+    if (!root.contains(range.startContainer) || !root.contains(range.endContainer)) return false;
 
     const whole = wholeSelectionMark(range, 'A', root);
     if (whole) {
       const url = window.prompt('連結網址（留空以移除連結）：', whole.getAttribute('href') || '');
-      if (url === null) return; // cancelled — leave the link untouched
+      if (url === null) return true; // cancelled — leave the link untouched
       if (url.trim() === '') {
         reselectAndReposition(unwrapElement(whole));
       } else {
@@ -10052,7 +10934,7 @@
         reselectAndReposition(range);
       }
       snapBurstIfActive(root, 'mark');
-      return;
+      return true;
     }
     const overlapping = overlappingMarks(range, 'A', root);
     if (overlapping.length > 0) {
@@ -10060,10 +10942,10 @@
       overlappingMarks(extended, 'A', root).forEach((m) => unwrapElement(m));
       reselectAndReposition(extended);
       snapBurstIfActive(root, 'mark');
-      return;
+      return false;   // unwrapped in place — no modal ever opened
     }
     const url = window.prompt('連結網址：', 'https://');
-    if (url === null || url.trim() === '') return; // cancelled or empty — no-op
+    if (url === null || url.trim() === '') return true; // cancelled or empty — no-op
     const el = document.createElement('a');
     el.setAttribute('href', url.trim());
     el.appendChild(range.extractContents());
@@ -10072,6 +10954,7 @@
     r.selectNodeContents(el);
     reselectAndReposition(r);
     snapBurstIfActive(root, 'mark');
+    return true;
   }
 
   function buildSelToolbar() {
@@ -10114,7 +10997,14 @@
   // `position: fixed`.
   function positionSelToolbar(range) {
     const rect = range.getBoundingClientRect();
-    if (rect.width === 0 && rect.height === 0) { hideSelToolbar(); return; }
+    // v3.2.1: 原本的零矩形檢查是死碼 —— 實測捲出視野的 Range 仍保有
+    // 151x17 的矩形，永遠到不了這一支。改成真正的視窗外檢查。
+    const topInset = parseFloat(getComputedStyle(document.documentElement)
+      .getPropertyValue('--ed-toolbar-h')) || 0;
+    if (rect.bottom <= topInset || rect.top >= window.innerHeight ||
+        rect.right <= 0 || rect.left >= window.innerWidth) {
+      hideSelToolbar(); return;
+    }
     if (!selToolbar.parentNode) document.body.appendChild(selToolbar);
     const gap = 8, margin = 4;
     const tbRect = selToolbar.getBoundingClientRect();
@@ -10471,7 +11361,8 @@
   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'.
+  // 追加 4's document mode: 'edit' | 'source'. v3.2.1 removed the third
+  // state ('preview'); docsource.js's MODES comment records why.
   // docsource.js owns the cycle order and the lines[]<->string conversion.
   let docMode = 'edit';
   let sourceTextarea = null;
@@ -10515,10 +11406,29 @@
   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();
+  }
+
+  // v3.2.1: point the bar back at the block a structural op just produced.
+  //
+  // rerenderAll()'s teardown calls resetToolbarBlock() (toolbarBlockEl = null,
+  // bar repainted in its no-block state: 4 enabled buttons), and nothing
+  // re-points it unless a focusin/click lands on a block. That is fine when
+  // the op ends with focusBlockAtLine() — the surface's focus event runs
+  // wireToolbarTracking()'s focusin handler, which does exactly this. It is
+  // NOT fine for a target with no focusable surface (quote / code / hr), where
+  // focusBlockAtLine() silently no-ops and the bar would stay collapsed on a
+  // block that is right there on screen. updateToolbar() is what repaints;
+  // resetToolbarBlock() is idempotent, so re-pointing after it is safe.
+  // Resolves nothing and touches nothing when `line` is null or the block is
+  // gone (a refusal, a rolled-back render).
+  function reaimToolbarBlockAtLine(line) {
+    if (line == null) return;
+    const target = blocks.find((b) => b.startLine === line);
+    if (!target) return;
+    const blockEl = document.querySelector('.ed-block[data-block-id="' + target.id + '"]');
+    if (!blockEl) return;
+    toolbarBlockEl = blockEl;
     updateToolbar();
   }
 
@@ -10591,9 +11501,17 @@
       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.
+      // `headings` (H / H1..H6) and, since v3.2.1, the mode button carry a
+      // derived label; every other button keeps the glyph it was built with.
       if (typeof st.label === 'string') btn.textContent = st.label;
+      // v3.2.1: a per-mode title CANNOT be baked in buildToolbar() — the mode
+      // button's title names the NEXT state, so it has to be rewritten every
+      // time the mode changes. It rides the same diffed loop as everything
+      // else: `title` is part of the state object, therefore part of `sig`.
+      if (typeof st.title === 'string') {
+        btn.title = st.title;
+        btn.setAttribute('aria-label', st.title);
+      }
     });
   }
 
@@ -10638,11 +11556,53 @@
       bar.appendChild(btn);
       btns[def.id] = btn;
     });
+    // Fix round 1, item 3: a click on a DISABLED toolbar button used to take
+    // the caret with it — the same gesture and the same symptom this release
+    // exists for. MEASURED, and the two halves matter separately:
+    //
+    //  * `mousedown` and `click` are NOT dispatched at all for a disabled
+    //    <button> — 0 of each at a capture-phase listener on `document`, for
+    //    the whole propagation path, so the per-button mousedown
+    //    preventDefault() a few lines above cannot run and neither could one
+    //    on this container.
+    //  * `pointerdown` IS dispatched (1 at that same document listener) and is
+    //    cancellable, and cancelling it suppresses the compatibility mousedown
+    //    together with its default action — which is the focus move.
+    //
+    // Driven, caret in a paragraph, clicking the disabled 🅑: without this
+    // handler activeElement was BODY in both the untouched-burst state (bar
+    // still 15) and the typed-in state (bar down to 4, because that focusout
+    // ran a full commit + render); with it, P.ed-wys-armed / 15 in both.
+    //
+    // Scope: capture phase on the bar, and preventDefault() ONLY when the
+    // press resolves to a disabled button. Never stopPropagation() — the
+    // document-level pointerdown delegator (table grips, ⠿ block drag, block
+    // selection) still sees the event, and finds nothing to arm, exactly as
+    // before. An ENABLED button, a separator, the status slot and the bar's
+    // own background are all untouched. The H▾ dropdown is NOT inside this
+    // subtree (toggleToolbarHeadingMenu() appends it to document.body), so it
+    // is out of reach here and keeps its own per-item mousedown handler.
+    bar.addEventListener('pointerdown', (e) => {
+      const pressed = e.target && e.target.closest ? e.target.closest('button') : null;
+      if (pressed && pressed.disabled) e.preventDefault();
+    }, true);
     toolbarBtns = btns;
     // v3.1.0 的 spec 承諾「元素存在但無內容，§3 上線時填入、不需要重排版面」，
-    // 但元素從未被建立。這裡把承諾兌現：佔好寬度、無內容。
+    // 但元素從未被建立。這裡把承諾兌現：佔好寬度。內容不再是空的 ——
+    // paintModeStatus() 會在 mountToolbar() 掛上之後、以及每次 setDocMode()
+    // 切換時寫入當前模式名稱。
     const statusEl = document.createElement('span');
     statusEl.className = 'ed-toolbar-status';
+    // Final wave, M7: the only announcement a mode switch ever gets. Every
+    // toolbar button is `tabindex="-1"` (see buildToolbar()'s own note), so a
+    // screen reader is never focused on the mode button when it is pressed and
+    // hears nothing about the state that just changed; the slot's text is the
+    // only thing that says so. `role="status"` carries an implicit
+    // aria-live="polite", and the explicit attribute is written alongside it
+    // because that implication is the part assistive tech has historically
+    // been inconsistent about — belt and braces, one line, no layout cost.
+    statusEl.setAttribute('role', 'status');
+    statusEl.setAttribute('aria-live', 'polite');
     bar.appendChild(statusEl);
     return bar;
   }
@@ -10960,18 +11920,90 @@
     await insertBlockBelow(target, 'paragraph', { lines: newLines });
   }
 
-  function pickAndInsertImage() {
+  // v3.2.1: 「插入圖片竟然無法在我當前的位置後插入，每次都跑到最後」. Two
+  // separate mechanisms put the image at EOF, and BOTH were measured — the
+  // second one is the reason this function is longer than it looks like it
+  // needs to be.
+  //
+  //   (a) `input.click()` below is a SYNTHETIC click. It bubbles to the
+  //       document delegator, which reads it as a click landing outside every
+  //       block → switchAwayFrom() → commit + re-render → the anchor node
+  //       captured a moment earlier is detached → insertImages() falls back to
+  //       lastBlockEl() and the image lands at the end of the file.
+  //       Deterministic whenever the block the user is in is dirty, which is
+  //       exactly the reported gesture.
+  //
+  //   (b) stopPropagation() on that click is NECESSARY BUT NOT SUFFICIENT. It
+  //       fixes the reported gesture, yet the anchor stayed a raw DOM node
+  //       held across the file dialog: a FULL render landing between the click
+  //       and the `change` event detaches it and the image is back at EOF.
+  //       The v3.2.0 patch path is not the exposure — two forced mid-dialog
+  //       renders (a commit in another block, a ⠿ 刪除 of another block) were
+  //       measured to patch and leave the anchor attached — but a full render
+  //       is one patchmap() miss away (it returns null whenever there is no
+  //       usable editRange), and a real OS file dialog stays open for as long
+  //       as the user takes. So the window is small, not hypothetical.
+  //
+  // Hence both halves: stop the synthetic click from reading as an
+  // outside-click, AND resolve the open session BEFORE the picker opens while
+  // carrying the anchor as a stable IDENTITY that is re-resolved when the
+  // files come back, instead of as a node reference. The identity triple is
+  // insertBlockBelow()'s (captureBlockIdentity / ownsOpenSession /
+  // reresolveBlockEl + reresolveBlockElAfterSelfCommit) — that function solved
+  // this same problem for its own anchor and the image path simply never
+  // adopted it. Do not "simplify" the re-resolution away: it is the half that
+  // survives the dialog.
+  //
+  // ⚠ ORDERING: `await switchAwayFrom()` runs BEFORE input.click(). Chrome
+  // gates the file picker on TRANSIENT user activation, which is time-based
+  // (~5 s) and is NOT spent by awaiting a promise, so the picker still opens.
+  // The journey scenario presses 🖼 on a DIRTY block, so a real commit — an
+  // /api/render round trip — runs inside that await; if the activation were
+  // spent, waitForFileChooser() there would time out. A commit slower than
+  // the activation window would be the one way this ordering could bite.
+  async function pickAndInsertImage() {
+    // Captured BEFORE switchAwayFrom(), because that is what can renumber the
+    // ids and rewrite the source — see captureBlockIdentity()'s comment.
+    const blockEl = liveToolbarBlock() || lastBlockEl();
+    const identity = captureBlockIdentity(blockEl);
+    // The commit inside switchAwayFrom() can be a rewrite of THIS block's own
+    // source, in which case reresolveBlockEl()'s fingerprint is guaranteed to
+    // miss because WE are the reason the source changed; the narrowed
+    // re-resolve is used only then. Same reasoning as insertBlockBelow().
+    const selfSession = ownsOpenSession(blockEl);
+    if (!(await switchAwayFrom())) return;
+    const anchorEl = (blockEl && document.body.contains(blockEl))
+      ? blockEl
+      : (reresolveBlockEl(identity) ||
+        (selfSession ? reresolveBlockElAfterSelfCommit(identity) : null));
+    if (!anchorEl) { showBanner(TOOLBAR_NO_ANCHOR_MESSAGE, null, null); return; }
+    // Re-captured AFTER the commit: `identity` above holds the PRE-commit
+    // fingerprint, which the commit we just awaited may itself have
+    // invalidated. What has to survive the dialog is the anchor as it stands
+    // now.
+    const dialogIdentity = captureBlockIdentity(anchorEl);
     const input = document.createElement('input');
     input.type = 'file';
     input.accept = 'image/png,image/jpeg,image/gif,image/webp';
     input.multiple = true;
     input.hidden = true;
-    const anchorEl = liveToolbarBlock() || lastBlockEl();
+    // (a) above.
+    input.addEventListener('click', (e) => e.stopPropagation());
     document.body.appendChild(input);
     input.addEventListener('change', () => {
       const files = input.files ? Array.prototype.slice.call(input.files) : [];
       input.remove();
-      if (files.length) insertImages(files, anchorEl);
+      if (!files.length) return;
+      // (b) above. A render that landed while the dialog was open detached
+      // `anchorEl`; the identity still names the block the user pointed at.
+      // If even that misses, the block the user aimed at no longer exists as
+      // it was — refuse (and skip the upload, so no orphan lands in the
+      // user's assets/) rather than silently appending at EOF, which is the
+      // very symptom being fixed.
+      const live = document.body.contains(anchorEl)
+        ? anchorEl : reresolveBlockEl(dialogIdentity);
+      if (!live) { showBanner(TOOLBAR_NO_ANCHOR_MESSAGE, null, null); return; }
+      insertImages(files, live);
     });
     input.click();
   }
@@ -10998,9 +12030,10 @@
     // 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.
+    // v3.2.1: `!== 'edit'` rather than `=== 'source'` on purpose. Source is
+    // the only other mode today, but the gate's reason is "the content the
+    // user is looking at is not the content a drop would write into" — a
+    // future third mode inherits the refusal rather than the hole.
     document.addEventListener('dragover', (e) => {
       if (docMode !== 'edit') return;
       if (!dragCarriesFiles(e)) return;
@@ -11117,12 +12150,9 @@
   }
 
   // ── 追加 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');
-    }
-  }
+  // v3.2.1: applyPreviewEditability() lived here and was preview mode's ONLY
+  // effect. Preview is gone (docsource.js's MODES comment carries the
+  // measurement), and with it the last caller of this function.
 
   function enterSourceMode() {
     // The pre-edit snapshot fromSource() diffs against. Omitting it makes
@@ -11194,14 +12224,21 @@
       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);
+    paintModeStatus();
     updateToolbar();
   }
 
+  // v3.2.1: 模式必須說出來 —— 使用者按第二下以為卡住，其實是進了 source。
+  // Called from setDocMode() AND from mountToolbar(), so the slot is truthful
+  // from the first paint rather than only after the first mode change.
+  function paintModeStatus() {
+    const statusEl = document.querySelector('.ed-toolbar-status');
+    if (statusEl) statusEl.textContent = docMode === 'source' ? '原始碼' : '編輯';
+  }
+
   // ── mount ──────────────────────────────────────────────────────────────
   function wireToolbarTracking() {
     // Which block the bar reports on. Delegated at document level (never a
@@ -11246,6 +12283,7 @@
     // grips and the table edge menu.
     document.body.appendChild(toolbarEl);
     document.body.setAttribute('data-ed-mode', docMode);
+    paintModeStatus();
     wireToolbarTracking();
     wireImageDrop();
     wirePlainPasteArming();
@@ -11708,6 +12746,58 @@
     });
   });
 
+  // v3.2.1: client.js 原本的 scroll 監聽器數量是 0，所以每一個 position:fixed
+  // 的浮層在捲動後都停在原視窗座標。grip／bubble 有 mousemove 驅動可重新升起，
+  // 隱藏它們就夠；.ed-seltb 沒有（它只由 selectionchange 與
+  // applyMarkToggle／applyLinkToggle 驅動，而捲動不觸發 selectionchange），
+  // 純隱藏會讓它永遠回不來，所以它要重新定位、只在選取整個離開視窗時才隱藏。
+  // capture 階段是必要的：真正會自己捲的不是 .content（overflow-y: visible，
+  // 實測 scrollHeight === clientHeight，捲的其實是 document）——是側欄的
+  // .toc-list／#search-results-list（皆 overflow-y: auto，TOC 標題夠多時
+  // 實測 scrollHeight > clientHeight）與 .lightbox-stage（overflow: auto）。
+  // 這些容器的 scroll 事件不冒泡，只有 capture 階段收得到。
+  // 副作用（已記錄，非缺陷）：正因為 capture 連這些側欄容器的捲動都收，捲動
+  // TOC 或搜尋結果清單時——即使正文內容一格都沒動——也會隱藏 table grips
+  // 並關掉開著的 .ed-te-menu。
+  //
+  // 這個監聽器刻意是「模組層級、只掛一次、永不移除」，不跟著任何一次
+  // burst 的生命週期走（不在 resetSelToolbarState() 裡拆）。理由：真正會
+  // 刪資料的 .ed-te-menu／grip 家族（見上面 Task 5 的 mousemove 委派）不需要
+  // 任何 burst 就能被叫出來 —— 使用者可以單純把游標移到表格上（觸發上面那個
+  // 無條件掛載的 mousemove）升起 grip、打開 .ed-te-menu，此時完全沒有
+  // selToolbarListener（那個監聽器只在 burst 開著時才存在）。若把這個捲動
+  // 監聽器綁在 burst 身上，恰好在「grip／選單開著但沒有 burst」這個狀態下
+  // 它會不存在。resetSelToolbarState() 本身也會在每次 rerender 時執行（六個
+  // 呼叫點之一在本檔的 rerenderAll() 路徑上），把監聽器綁在它身上還會讓
+  // 監聽器在 session 中途被拆掉、且永不重掛。
+  let selScrollRaf = 0;
+  function onAnyScroll() {
+    if (tePointer && tePointer.dragging) return;   // 拖曳中不動
+    hideTableGrips();
+    hideTableInsertBubbles();
+    // v3.2.1 fix round 1: suppressEdgeMenuAutoHide — see its own comment —
+    // is set for runCycleAlign()'s ensureTableBurstOpen() span, whose
+    // cell.focus() can itself be the cause of this very scroll event; that
+    // operation repositions the menu itself afterward, so skip tearing its
+    // state down here (grip/bubble/toolbar-menu hiding above and below is
+    // unaffected — they re-raise on the next mousemove regardless).
+    if (!suppressEdgeMenuAutoHide) hideTableEdgeMenu(); // ← 真正會刪資料的是選單，不是 grip
+    closeToolbarMenu();
+    if (selScrollRaf) return;
+    selScrollRaf = requestAnimationFrame(() => {
+      selScrollRaf = 0;
+      if (!selToolbar.parentNode) return;          // 沒升起 → 0 次 layout read
+      const sel = window.getSelection();
+      if (!sel || !sel.rangeCount || sel.isCollapsed) { hideSelToolbar(); return; }
+      const range = sel.getRangeAt(0);
+      if (!selToolbarEditEl ||
+          !selToolbarEditEl.contains(range.startContainer) ||
+          !selToolbarEditEl.contains(range.endContainer)) { hideSelToolbar(); return; }
+      positionSelToolbar(range);
+    });
+  }
+  document.addEventListener('scroll', onAnyScroll, { passive: true, capture: true });
+
   window.addEventListener('beforeunload', (e) => {
     if (stack.dirtyDepth !== 0) {
       e.preventDefault();