@helping-ai-workflow/md2doc 3.2.0 → 3.3.0

package/lib/editor/client.js

@@ -474,8 +474,8 @@
   // first; S2 gives li blocks a ＋ and it goes live.
   //
   // One helper rather than two `if (result.op === null) return;` lines,
-  // because the idiom is copy-pasted and the seventh site will not remember
-  // either. Declared in the pure core so it is reachable from node: the branch
+  // because the idiom is copy-pasted and the next site to copy it will not
+  // remember either. Declared in the pure core so it is reachable from node: the branch
   // cannot be driven through a gesture today, and a guard that can only be
   // checked by grepping for its own source text is the shape that already
   // failed review once on this plan.
@@ -532,6 +532,20 @@
   const docSourceLib = window.md2docDocSource;
   let lines = ED.lines, blocks = ED.blocks, mtimeMs = ED.mtimeMs;
   let lastParts = null;
+  // F10: 上一次【成功套用】的 render 留下來的東西 —— 當時的整份 `lines`，以及
+  // 當時的文件是不是以一道沒閉合的圍欄收尾。
+  //
+  // fix round 2 (K7): 這裡不再說「跟 `blocks` 一起前進」，那句是錯的。`blocks`
+  // 是被 applyPatch()／applyFullRender() 自己換掉的（applyFullRender() 的第一行
+  // 就是 `blocks = j.blocks`），時機不受套用成功與否管；下面這些狀態則是
+  // applyRenderResult() 在【呼叫那些 apply 之前】讀、在【套用成功之後】才寫的，所以
+  // 判別式讀到的一定是上一份已經上過畫面的狀態。
+  //
+  // 開場值從 bootstrap payload 直接算（ED.lines 與 ED.blocks 是
+  // lib/editor/server.js 的 GET /edit/:id 在同一個回應裡送出來的），這樣一份
+  // 【開檔時就已經沒閉合】的文件不會在使用者的下一個手勢上被誣賴成吞噬。
+  let lastRenderLines = ED.lines.slice();
+  let lastRenderEndedUnclosed = endsWithUnclosedFence(ED.lines, ED.blocks);
   // 檔案原本的換行符。lines 內部永遠是不含 \r 的純內容行；只有 save()
   // 會把它接回這個 EOL，render 一律用 \n（spec §3.11）。
   const EOL = ED.eol || '\n';
@@ -576,6 +590,36 @@
   // section further down for the full shape and lifecycle.
   let currentBurst = null; // { blockEl, editEl, blockId, blockType, depth, original, history } | null
 
+  // T21 item 1: the burst Escape most recently threw away, kept alive for
+  // exactly one document-level Ctrl+Z. Escape means DISCARD and still does —
+  // what changed is that the discard is no longer unrecoverable. Driven on
+  // this branch before the fix, on all three burst surfaces (paragraph, table
+  // cell, list item): type, Escape, then Ctrl+Z ×3 and Ctrl+Y ×3 — the text
+  // was gone after all six, and the title went '● doc' -> 'doc', so the
+  // beforeunload guard was disarmed over it too.
+  //
+  // The burst's OWN history is what carries the text back, which is why this
+  // holds the history object rather than an HTML string: revertBurstAndEnd()
+  // snapshots on both sides of the revert (the discipline every other
+  // mutation in this file already follows — see snapBurstIfActive()), so
+  // restoring is one history.undo() and the entries UNDER it stay reachable
+  // afterwards. `reverted` is the staleness guard: anything that repaints the
+  // surface between the Escape and the Ctrl+Z (a render, another block's
+  // commit) makes this stash unusable, and it is dropped rather than applied
+  // over a document that moved.
+  //
+  // One slot, cleared the moment any burst opens (startBurst()/
+  // startTableBurst()) or the page re-renders (rerenderAll()), so the only
+  // window in which it answers a Ctrl+Z is the one the user is complaining
+  // about: Escape, then Ctrl+Z.
+  let discardedBurst = null; // { history, editEl, blockType, cellIdx, reverted } | null
+
+  function dropDiscardedBurst() {
+    if (!discardedBurst) return;
+    discardedBurst.history.dispose();
+    discardedBurst = null;
+  }
+
   // §10-gap fix (review): the block insertBlockBelow() most recently
   // inserted, tracked from the moment its edit surface is first focused
   // until its FIRST resolution (blur, Escape, explicit commit, or Ctrl+Z) —
@@ -728,8 +772,81 @@
     return await activeEditor.commitNow(); // false → editor stays open, banner already shown
   }
 
+  // `stack.dirtyDepth` is `_done.length - _savedDepth` (lineops.js), so it
+  // moves when an op is pushed onto or popped off the undo stack, or when a
+  // save re-baselines it. The burst substrate keeps what the user typed in
+  // the DOM until the burst resolves, and none of those has happened yet at
+  // that point — so a block that has been typed into but not yet left reads
+  // as clean. MEASURED on `# Doc\n\nAlpha paragraph.\n` (click the
+  // paragraph, type, then navigate away):
+  //   mid-burst    document.title "doc"    no beforeunload dialog
+  //   after blur   document.title "● doc"  dialog raised
+  // This names that gap, and is the shape bystanderCarryOver() already uses
+  // to pick out the block whose bytes are not in `lines` yet — including its
+  // `currentBurst.editEl` guard, kept here because this also runs inside the
+  // beforeunload handler, where a throw would drop the navigation guard
+  // rather than surface.
+  function burstHasUncommittedEdit() {
+    return !!(currentBurst && currentBurst.editEl &&
+      burstBaselineHtml(currentBurst.editEl) !== currentBurst.original);
+  }
+
   function setDirty() {
-    document.title = (stack.dirtyDepth !== 0 ? '● ' : '') + baseTitle;
+    const dirty = stack.dirtyDepth !== 0 || burstHasUncommittedEdit();
+    document.title = (dirty ? '● ' : '') + baseTitle;
+  }
+
+  // setDirty() is push-driven: something has to call it. MEASURED by keeping
+  // the predicate above but removing the watcher below — typing into a
+  // paragraph still left the title at "doc", so nothing repaints it while a
+  // burst is open. That is the second half of the gap. The dot needs
+  // something that fires while the burst is still open, and again when the
+  // surface goes back to its baseline without a commit.
+  //
+  // A mutation watcher rather than a list of call sites, because the
+  // gestures that dirty a burst and the gestures that clean it again do not
+  // share an entry point: typing raises an `input` event, a selection-
+  // toolbar mark does not (MEASURED: pressing B over a selection in a
+  // paragraph burst leaves the surface `<strong>Alpha</strong> paragraph.`
+  // with the document-level `input` listener's inputType log still empty),
+  // and a burst-local Ctrl+Z swaps the whole surface in through innerHTML.
+  //
+  // `attributes` is watched because a gesture exists that writes an
+  // attribute and nothing else into a burst that is left open: the
+  // edge menu's 對齊 reaches cycleColumnAlign()'s
+  // `cell.setAttribute('style', 'text-align:…')`, and runCycleAlign() around
+  // it only snap()s the burst history. MEASURED with `attributes` unwatched,
+  // driving that menu with real mouse events: `document.title` stayed "doc"
+  // while the unload guard DID fire — the predicate saw the edit and the dot
+  // did not.
+  //
+  // 🔗 over an existing link writes an attribute too
+  // (applyLinkToggleBody()'s `whole.setAttribute('href', …)`) and does NOT
+  // establish this: MEASURED through a real modal rather than a stubbed
+  // window.prompt, the prompt takes focus off the surface first, which
+  // resolves and commits the burst, so `stack.dirtyDepth` has already moved
+  // by the time the attribute lands. Not every attribute write in this file
+  // was measured. The table selection chrome is another that reaches a burst
+  // surface; burstBaselineHtml() normalises it away, and MEASURED, neither
+  // it nor a bare cell click produces a dot.
+  //
+  // Cost per delivered batch is a `document.title` write, plus a
+  // burstBaselineHtml() while `stack.dirtyDepth` still reads clean (the `||`
+  // short-circuits past it otherwise). MEASURED, innerHTML serialize plus
+  // its indexOf scans on a rendered table block: 0.02 ms at 7.4 KB, 0.06 ms
+  // at 21 KB, 0.19 ms at 71 KB.
+  const burstDirtyWatcher = new MutationObserver(setDirty);
+
+  // Called wherever a burst opens. disconnect() first because observe() ADDS
+  // a target rather than replacing one, so re-pointing is what keeps a single
+  // watcher single. MEASURED, observing surface A then surface B on the same
+  // observer and mutating both: without the disconnect the callback is
+  // delivered records from A as well as B, with it only from B.
+  function watchBurstForDirtyDot(editEl) {
+    burstDirtyWatcher.disconnect();
+    burstDirtyWatcher.observe(editEl, {
+      childList: true, subtree: true, characterData: true, attributes: true,
+    });
   }
 
   // ── banners (conflict / render-failed / save-failed) ──────────────────
@@ -744,12 +861,17 @@
   // three describe the state of the FILE or the connection and must stay until
   // the user dismisses them.
   let activeBannerIsRefusal = false;
+  // F10 fix round 1 的對稱項：這條 banner 描述的是【文件現在的形狀】，跟
+  // refusal 一樣需要一個「後來的事件可以把它收掉」的記號，但收掉它的條件不
+  // 同（見 dismissSwallowBanner()），所以是另一個旗標而不是共用那一個。
+  let activeBannerIsSwallow = false;
   function showBanner(message, actionLabel, onAction) {
     if (activeBanner) { activeBanner.remove(); activeBanner = null; }
     // Reset unconditionally: refuseStructuralListEdit() sets it back to true
     // straight after its own call, so every OTHER caller gets false without
     // having to know this flag exists.
     activeBannerIsRefusal = false;
+    activeBannerIsSwallow = false;
     const el = document.createElement('div');
     el.className = 'ed-conflict';
     const msg = document.createElement('span');
@@ -768,7 +890,11 @@
     dismissBtn.setAttribute('aria-label', 'Dismiss');
     dismissBtn.addEventListener('click', () => {
       el.remove();
-      if (activeBanner === el) { activeBanner = null; activeBannerIsRefusal = false; }
+      if (activeBanner === el) {
+        activeBanner = null;
+        activeBannerIsRefusal = false;
+        activeBannerIsSwallow = false;
+      }
     });
     el.appendChild(dismissBtn);
     document.body.appendChild(el);
@@ -803,6 +929,151 @@
     );
   }
 
+  // F10 ——「一道沒閉合的圍欄把後面的內容吃掉了」那一句，單獨一個常數。
+  // test/editor-journey.test.js 的 F10 那一列釘的是這串文字本身，而不是
+  // 「畫面上有一條 .ed-conflict」。那個 class 只有 showBanner() 一個產生點，
+  // 而 showBanner() 的呼叫端（grep 全檔逐一開過）橫跨這些彼此無關的家族：
+  //   - 磁碟衝突：showConflictBanner()
+  //   - render 失敗：rerenderAll() 的 'Render failed — network error'／
+  //     'Render failed — ' + reason／'Render failed — malformed server response'
+  //     ，加上 safeRerenderAll() 的 'Render failed — unexpected error'
+  //   - save 失敗：save() 的 'Save failed — network error'／
+  //     'Save failed — malformed server response'／'Save failed — ' + reason
+  //   - 手勢在 render 與 render 之間失去目標：DROPPED_GESTURE_MESSAGE
+  //   - 清單／表格的結構性拒絕：refuseStructuralListEdit()、'無法刪除最後一欄'、
+  //     '無法刪除標題列'、'無法刪除最後一列'
+  //   - burst 降級：'含不支援的格式，改用原始碼編輯'
+  //   - 工具列插圖：TOOLBAR_UNSUPPORTED_IMAGE_MESSAGE、'圖片讀取失敗 — '、
+  //     '圖片上傳失敗 — '（網路 throw／非 2xx／回應格式不正確）、
+  //     TOOLBAR_NO_ANCHOR_MESSAGE
+  // 光看 class 分不出是哪一個。
+  const SWALLOW_MESSAGE = '這道 ``` 圍欄沒有閉合，它後面的內容全部被吃進' +
+    '同一個程式碼區塊裡了。把收尾的圍欄補回去就會復原。';
+
+  // F10 —— 吞噬的【形狀】，不是計數。
+  //
+  // 這支問的是「最後一個區塊是不是一道沒閉合的圍欄」：type 是 code、它的開頭
+  // 那一行真的是一道圍欄（縮排式 code block 的 type 也是 code、開頭行不是圍欄，
+  // 靠 fenceOpenerOf() 排掉），而它底下沒有任何一行能收掉那道圍欄（closesFence()
+  // 認字元與長度 —— 見 fenceOpenerOf() 與 closesFence() 的註解，K1／K3）。只有開頭圍欄、還沒有本文與收尾
+  // 的單行 code 區塊也算沒閉合。
+  //
+  // 為什麼只看最後一個區塊：**頂層**的一道沒閉合的圍欄會一路吃到檔尾，所以它
+  // 就是最後一個區塊。巢狀在 blockquote／清單項裡的圍欄不是這樣，但它也不吃到
+  // 檔尾 —— MEASURED（buildBlockMap）：
+  //   '# Doc\n\n> ```js\n> code\n\nTail.\n'   heading blockquote[3,4] paragraph[6,6]
+  //   '# Doc\n\n- ```js\n  code\n\nTail.\n'   heading li[3,4]         paragraph[6,6]
+  //   '# Doc\n\n```js\ncode\n\nTail.\n'       heading code[3,6]
+  // 容器在空行就結束了，'Tail.' 還在外面、沒有被吃掉，所以這支不看它、也不需要
+  // 看它。
+  //
+  // `srcLines` 是 1-indexed 行號要索引的那個陣列（呼叫端傳模組層的 `lines`
+  // 或 bootstrap 的 ED.lines），`blockList` 是與它同一份快照的 block 陣列。
+  function endsWithUnclosedFence(srcLines, blockList) {
+    if (!Array.isArray(blockList) || blockList.length === 0) return false;
+    const last = blockList[blockList.length - 1];
+    if (!last || last.type !== 'code') return false;
+    const opener = fenceOpenerOf(srcLines[last.startLine - 1]);
+    if (!opener) return false;   // 縮排式 code block：type 也是 code，但開頭不是圍欄
+    for (let n = last.startLine + 1; n <= last.endLine; n++) {
+      if (closesFence(srcLines[n - 1], opener)) return false;
+    }
+    return true;
+  }
+
+  // F10 —— 吞噬與【修剪】的差別是【歸屬】，而歸屬要算數量，不是問有沒有。
+  //
+  // 「形狀 ∧ 區塊少了」擋掉了純計數判別的那族誤報，但放進來另一族：使用者把收
+  // 尾圍欄連同它後面的東西一起【刪掉】（往檔尾 trim），區塊照樣掉、文件照樣以沒
+  // 閉合的圍欄收尾 —— 可是圍欄後面本來就沒東西了，是使用者自己刪的。那時候那句
+  // 話的每一個子句（「後面的內容全部被吃進去」「補回收尾圍欄就會復原」）都是假的。
+  //
+  // 真正的差別：吞噬時，本來活在 fenced code block【外面】的行跑進了裡面；修剪
+  // 時那些行只是不見了。這裡用內容比對，不做行號對齊（對齊在插入／刪除混在一起
+  // 時很脆，這個做法完全不需要它）。
+  //
+  // fix round 3 (L1)：上一版問的是【有沒有】—— 「這一行以前在外面，而現在不在
+  // 外面了」。那個問法朝相反的方向各說一種謊，下面每一種都是驅動出來的：
+  //   往檔尾 trim，而圍欄本文有一行【也】出現在被刪掉的尾巴裡（散文重複了它自己
+  //     用圍欄展示的那道指令，是這個形狀最普通的樣子）→ 什麼都沒被吃掉卻會叫。
+  //   真吞噬，但被吃掉的那一行文件別處【還有一份】→ 「現在不在外面」不成立，
+  //     於是不叫。被吃掉的每一行都有副本時整個吞噬都消音。
+  //   被吃掉的是一個【縮排式】code block → 上一版把它算成「本來就在 code 裡」，
+  //     於是不叫。
+  //
+  // 所以改成算數量，而且是【逐行】判：走過新的尾端圍欄本文裡出現過的每一種非
+  // 空行內容，只要有一行【自己】同時滿足下面這些條件，就是吞噬，當場 return：
+  //
+  //   wasOutCount > nowOutCount —— 這一行在上一份／這一份 render 裡出現在
+  //     fenced code block【外面】的次數。外面的份數變少 ＝ 它被吃進去了。
+  //   nowTotal >= prevTotal —— 同一行在上一份／這一份【整份文件裡】出現的次數
+  //     （圍欄裡的份數也算）。沒有變少 ＝ 它只是換了位置，不是被刪掉。
+  //
+  // fix round 4 (M1)：前半與後半在上一版是【各自加總】再比一次的，那讓不同的
+  // 行互相抵銷，不論哪個方向都出事。真吞噬靜默：code block 裡有一行重複（`}`
+  // 是日常樣子），一次編輯刪掉其中一份並且刪掉收尾圍欄 —— 被吃掉的那一行自己
+  // 前半與後半都成立，卻被那個消失的 `}` 拉低總數而抵銷掉。誤報回來：往檔尾
+  // trim 的同一次編輯裡把本文某一行複製一份 —— 被 trim 掉的那一行撐前半、被複
+  // 製的那一行撐後半，湊出一個沒有任何一行自己成立的「真」。
+  //
+  // 「總數」刻意只算這一行、而且連圍欄裡的份數一起算，不是整份文件的行數：
+  // 最常見的真吞噬是【只刪掉收尾圍欄那一行】，整份文件的非空行數會因此少一行，
+  // 用文件層級的總數當門檻會把它殺掉（那也是為什麼不能用 Δlines >= 0）。
+  //
+  // 「不在 fenced code block 內」不是「不在 code block 內」：縮排式 code block
+  // 的 type 也是 code，但它是文件裡看得見的內容，被一道圍欄吃掉一樣是吞噬。
+  // 靠 fenceOpenerOf() 分辨（開頭那一行是不是圍欄）。
+
+  // 一份 render 裡，每一種非空行內容出現了幾次：`out` 只數【不在任何 fenced
+  // code block 內】的那些，`all` 數整份文件。
+  function lineCounts(srcLines, blockList) {
+    const inFence = {};
+    for (const b of blockList) {
+      if (!b || b.type !== 'code') continue;
+      if (!fenceOpenerOf(srcLines[b.startLine - 1])) continue;
+      for (let n = b.startLine; n <= b.endLine; n++) inFence[n] = true;
+    }
+    const out = Object.create(null);
+    const all = Object.create(null);
+    for (let n = 1; n <= srcLines.length; n++) {
+      const row = srcLines[n - 1];
+      if (typeof row !== 'string' || row.trim() === '') continue;
+      all[row] = (all[row] || 0) + 1;
+      if (!inFence[n]) out[row] = (out[row] || 0) + 1;
+    }
+    return { out: out, all: all };
+  }
+  // `tail` 是新的 block 陣列的最後一個（呼叫端已經確認它是一道沒閉合的圍欄）。
+  function absorbedOutsideContent(prevLines, prevBlocks, newLines, newBlocks, tail) {
+    const was = lineCounts(prevLines, prevBlocks);
+    const now = lineCounts(newLines, newBlocks);
+    const seen = Object.create(null);
+    for (let n = tail.startLine + 1; n <= tail.endLine; n++) {
+      const row = newLines[n - 1];
+      if (typeof row !== 'string' || row.trim() === '' || seen[row]) continue;
+      seen[row] = true;
+      const wasOutCount = was.out[row] || 0;
+      const nowOutCount = now.out[row] || 0;
+      const prevTotal = was.all[row] || 0;
+      const nowTotal = now.all[row] || 0;
+      if (wasOutCount > nowOutCount && nowTotal >= prevTotal) return true;
+    }
+    return false;
+  }
+
+  // F10 fix round 1 —— 吞噬的 banner 必須退場。
+  //
+  // 它不是 refusal，所以 dismissRefusalBanner() 不會碰它（那支只清
+  // `activeBannerIsRefusal`）。退場的條件不是「後來有一次成功的編輯」而是
+  // 「文件不再以沒閉合的圍欄收尾」：圍欄還開著的時候，後面的內容就還被吃著，
+  // 那時候把警告收掉才是說謊。呼叫點在 applyRenderResult() 套用成功之後。
+  function dismissSwallowBanner() {
+    if (!activeBanner || !activeBannerIsSwallow) return;
+    activeBanner.remove();
+    activeBanner = null;
+    activeBannerIsSwallow = false;
+  }
+
   function describeFailure(e) {
     return (e && e.message) ? e.message : String(e);
   }
@@ -828,6 +1099,11 @@
   // a dismissible banner explaining what happened. Never throws: every
   // await is inside its own try/catch, so callers never see a rejection.
   async function rerenderAll(editRange) {
+    // T21 item 1: this render is about to replace the surfaces the stash names,
+    // so whatever Escape put there stops being restorable here. The staleness
+    // guard in restoreDiscardedBurst() would refuse it anyway; dropping it at
+    // the source is what keeps a dead history object from being held.
+    dropDiscardedBurst();
     const scrollY = window.scrollY;
     // S3 Task 5 (§4.4 step 2): the line range this render's operation declared
     // for the rebuilt selection. Consumed HERE, before the first failure exit,
@@ -966,14 +1242,114 @@
   }
 
   async function applyRenderResult(j, editRange, scrollY, declaredRange) {
+    // F10 —— 判別式：【形狀 ∧ 歸屬】。
+    //
+    // 第一版是純計數（Δblocks < 0 且 Δlines >= 0）。實測它在再普通不過的編輯
+    // 上就會叫，磁碟位元組卻完全正確 —— 全文原始碼裡把一行的字清掉但行留著
+    // （blocks 4->3、lines 8->8）、⠿「MD 原始碼」裡把一段清成空字串或一個空白
+    // （同樣 4->3、8->8）、把每一段的字都清掉（4->1、8->8）。計數分不開「一個
+    // 區塊因為自己的內容被清空而消失」與「一個區塊因為被別人吸收而消失」。
+    //
+    // 第二版是「形狀 ∧ 區塊少了」。形狀那一半擋掉了上面那族，但效果那一半只
+    // 是計數換個位置，於是放進來一族新的：使用者把收尾圍欄連同它後面的東西一
+    // 起【刪掉】（往檔尾 trim），區塊照樣 4~5 掉到 3、文件照樣以沒閉合的圍欄
+    // 收尾，可是圍欄後面本來就沒東西了 —— 是使用者自己刪的。那時候那句話的
+    // 每一個子句都是假的。
+    //
+    // 這一版把效果那一半換成【歸屬】（見 absorbedOutsideContent()）：新的尾端
+    // 圍欄的本文裡，有沒有哪一行在上一份 render 裡活在 code block 外面、而在
+    // 這一份已經不在外面了。吞噬時有（那些行被吃進去了），修剪時沒有（那些行
+    // 不見了，不是搬進去）。
+    //
+    // 每一項各擋掉一族，而且各有一列 journey 案例釘住它 —— 把那一項【單獨】拿
+    // 掉，那一列就紅。這是機械掃出來的，不是看出來的：判別式、歸屬測試自己的組
+    // 成、圍欄配對器的每一條規則，各自單獨 ablate 一次，每次都把 F9／F10 那一段
+    // 的案例逐列跑過，記錄哪一列紅。
+    //   nowUnclosed              —— 使用者自己按「轉換成 › 程式碼」把重複的一段
+    //                               包進圍欄裡，外面的份數當然少一份，但文件並沒
+    //                               有以沒閉合的圍欄收尾（PIN-shape）
+    //   !lastRenderEndedUnclosed —— 一開檔就沒閉合的文件靠它不被誣賴（PIN-prev、
+    //                               G7）
+    //   absorbedOutsideContent   —— 往檔尾 trim 與「圍欄後面沒東西」靠它擋
+    //                               （K2 的 X4／P1／P2／P7、控制列 C3）
+    //
+    // 量到的漏網（false negative；同一次掃描量到的誤報是零）。把一道 '```' 用
+    // 全文原始碼插進 baseline（'# Doc' / 'Alpha.' / 一段 ```js 圍欄 / '## Next' /
+    // 'Bravo.' / 'Charlie.' / '- x' / '- y'）的每一個行位置，逐一【驅動】過，
+    // 再拿 buildBlockMap 算出的真值（有沒有本來在 code block 外面的非空行跑進
+    // 去了）對答案：
+    //   插在第 6..16 行之前   真的吃到東西 → 有叫
+    //   插在第 4、5、17、18 行之前   什麼都沒吃到 → 沒叫（正確）
+    //   插在第 1、2、3 行之前   真的吃到東西 → 【沒叫】
+    // 第 1/2/3 行那些格的機制跟計數無關：新的開頭圍欄跟文件裡【原本就有的】
+    // 那道收尾圍欄配成一對，所以吃掉東西的那個 code block 是【閉合】的，文件
+    // 也不是以沒閉合的圍欄收尾 —— 形狀那一半看不到它。而且那個結果跟使用者
+    // 自己按 ⠿「轉換成 › 程式碼」得到的形狀一模一樣（同一份語料裡那一列必須
+    // 靜默），兩者只差在意圖，文件本身分不出來。
+    //
+    // 另一族漏網（同樣是量到的，同樣不打算靠再改一版判別式去關）：**同一次編輯
+    // 刪掉收尾圍欄，而且也刪掉了被吃那一行內容的另一份**。被吃的那一行前半成
+    // 立（圍欄外面的份數變少），但後半的整份文件份數也跟著少了，所以那一行自己
+    // 不成立，於是靜默。瀏覽器裡驅動確認過：'Bravo.' 在圍欄裡與圍欄外各一份，
+    // 刪掉圍欄裡那一份與收尾圍欄之後，外面那個 'Bravo.' 真的被吃進去（區塊由
+    // 區塊數真的變少、磁碟是 '# Doc\n\n```js\n\nBravo.\n'），banner 不出現。
+    //
+    // 為什麼不關：拿「這一行在圍欄裡的份數變多了」（nowIn > wasIn）去換掉後半，
+    // 在同一份位置真值的掃描上只關掉一部分漏網，卻把誤報從零帶到有 —— 對一個
+    // 警告來說，誤報那個方向才是致命的（叫錯一次，使用者就再也不信它），而漏掉
+    // 一次警告只是把使用者留在 v3.3.0 之前的狀態：本來就沒有信號。所以這些
+    // 漏網是**寫下來的已知缺口**，不是待修的 bug，也刻意不寫成測試案例 —— 把缺
+    // 口釘成「預期行為」會讓將來真的補起來時看起來像退步。
+    //
+    // 反方向已知的例外，而且它是**設計的極限、不是沒修**：使用者往檔尾 trim，
+    // 同一次編輯又把被 trim 掉那一行的內容複製進圍欄本文。實測那些手勢產生的
+    // 文件**逐位元組相同**（'# Doc\n\n```sh\nsetup\nsetup\n' —— 一邊是把
+    // 'setup' 複製進去再 trim，另一邊是單純刪掉收尾圍欄讓外面那個 'setup' 被吃
+    // 進去），所以任何只看文件內容的判別式都分不開它們。這一格會叫，而它叫的
+    // 那份文件確實跟一次真吞噬的結果一模一樣。
+    //
+    // 讀的時機：`blocks` 與 `lines` 都必須在呼叫 applyPatch()／
+    // applyFullRender() 之前讀 —— applyFullRender() 的第一行就是
+    // `blocks = j.blocks`，applyPatch() 也在它那段 mutation window 之前把
+    // `blocks` 換掉（先存一份 prevBlocks 好在自己的 catch 裡回捲）。`lines`
+    // 已經是這次 render 的輸入（rerenderAll() 送出去的 body 就是
+    // `lines.join('\n')`），而上一份的 `lines` 存在 `lastRenderLines` 裡。
+    const nowUnclosed = endsWithUnclosedFence(lines, j.blocks);
+    const swallowed = nowUnclosed && !lastRenderEndedUnclosed &&
+                      absorbedOutsideContent(lastRenderLines, blocks,
+                                             lines, j.blocks,
+                                             j.blocks[j.blocks.length - 1]);
     const plan = (editRange && window.md2docPatchmap && domMatchesLastRender())
       ? window.md2docPatchmap.patchmap({
           oldBlocks: blocks, newBlocks: j.blocks,
           oldParts: lastParts, newParts: j.parts, editRange: editRange,
         })
       : null;
-    if (plan) return applyPatch(j, plan, declaredRange);
-    return applyFullRender(j, scrollY, declaredRange);
+    const ok = plan ? await applyPatch(j, plan, declaredRange)
+                    : await applyFullRender(j, scrollY, declaredRange);
+    // applyPatch() 與 applyFullRender() 今天都只回 true：applyFullRender() 全函
+    // 式唯一的 return 就是尾端
+    // 那個 `return true`，而 applyPatch() 要嘛回 true、要嘛在自己的 catch 裡
+    // 把整件事交給 applyFullRender()。所以這道門今天不會擋下任何東西；它存
+    // 在是為了把「render 沒套用成功就不要前進上面那些 lastRender* 狀態、也
+    // 要為一次沒上畫面的編輯升起警告」這件事寫在這裡，而不是留給讀者去讀
+    // 它們的本體。
+    if (!ok) return false;
+    lastRenderLines = lines.slice();
+    lastRenderEndedUnclosed = nowUnclosed;
+    // 升 banner 排在套用之後：套用是把新的 DOM 放上畫面那一步，警告的是使用
+    // 者【現在看到的】那份文件。applyPatch()／applyFullRender() 自己不呼叫
+    // showBanner()，所以這一句不會被同一次 render 裡的另一句蓋掉。
+    if (swallowed) {
+      showBanner(SWALLOW_MESSAGE, null, null);
+      activeBannerIsSwallow = true;   // 順序同 refuseStructuralListEdit()：
+                                      // showBanner() 自己會把旗標歸零。
+    } else if (!nowUnclosed) {
+      // 圍欄補回去了（或者這次 render 之後文件本來就不是那個形狀）——
+      // 警告已經不再是真的，收掉。見 dismissSwallowBanner() 的註解。
+      dismissSwallowBanner();
+    }
+    return true;
   }
 
   // Incremental DOM patch: replace ONLY the middle span patchmap identified,
@@ -1023,6 +1399,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,8 +1510,55 @@
       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
+    // Controller ruling F1: the patch path runs the SAME teardown items
     // applyFullRender() runs, unconditionally and in the same relative order.
     // The rationale comments below are copied from applyFullRender() because
     // they document WHY each one exists; the one thing that differs is the
@@ -1219,6 +1667,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 +1744,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 +1887,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()/
@@ -1595,6 +2058,183 @@
     ta.style.height = (ta.scrollHeight + 2) + 'px';
   }
 
+  // F9 —— raw 原始碼編輯器開啟時的 textarea 種子與 caret 落點。
+  //
+  // openRawEditor() 以前收尾一律是
+  // `ta.setSelectionRange(ta.value.length, ta.value.length)`，每一種區塊都落
+  // 在值的結尾。對 fenced code 那個位置在【收尾 fence 之後】。MEASURED
+  // （test/editor-journey.test.js 的 F9 那一列，fixture
+  // '# Doc\n\nAlpha.\n\n```js\nconst a = 1;\n```\n\nBravo.\n'，用真的滑鼠
+  // 按壓點進 code block）：修之前 selectionStart = selectionEnd = 22，而值是
+  // '```js\nconst a = 1;\n```'，長度正是 22 —— caret 就在收尾那串反引號
+  // 之後，打一個字進去，收尾那一行變成 '```Z'，圍欄不再閉合。
+  //
+  // 這支回 `{ value, caret }`：`value` 是要放進 textarea 的字串（通常就是傳
+  // 進來的原始碼；只有下面 b／b' 那些形狀會被動到），`caret` 是 offset。
+  //
+  // 規則不是「caret 永遠不會落在圍欄標記上」—— 那句話是假的，見下面的例外。
+  // 規則是：**只要來源裡存在一個不在圍欄標記上的落點，就選它；空圍欄則種一行
+  // 本文出來給它落**。
+  //
+  //  a) 第一行是一道開頭圍欄（fenceOpenerOf()）→ caret 落在下一行行首，那是
+  //     第一個位在程式碼本文裡的 offset。
+  //  b) 【空的圍欄】（a 的次分類：下一行就是它的【配對】收尾圍欄）→ 本文區一
+  //     行都沒有，兩端的候選位置都在圍欄標記上，**原始碼裡沒有安全的 offset**。
+  //     所以在開頭與收尾圍欄之間種一行空白進 `value`，caret 落在那一行。
+  //  b') 同樣的空圍欄長在一段跨區塊 span 的【尾端】（⠿ 選單的「MD 原始碼」框
+  //     得出來，例如 'Alpha.\n\n```js\n```'）→ 同樣種一行。
+  //  c) 最後一行是某道圍欄的【配對】收尾、而第一行不是開頭圍欄 → 結尾落點會
+  //     落在那道收尾圍欄上，改落在前一行的行尾。
+  //  其餘一律維持結尾落點。
+  //
+  // caret 仍然會落在一行【長得像圍欄】的行上的情形（掃過一批來源形狀量到的 ——
+  // 段落／引用／表格／清單項／html／縮排式 code／各種圍欄與跨區塊 span —— 這些
+  // 情形都不是破壞）：
+  //  - 來源只有一行，而那一行是一道孤零零的開頭圍欄 '```js'（⠿ 對一個只有開
+  //    頭圍欄的 code 區塊就會給出這個）。沒有別的行可選；在那裡打字得到
+  //    '```jsX'，仍然是一道開頭圍欄（info string 從 js 變成 jsX），區塊的收尾
+  //    狀態不變。
+  //  - 來源尾端那一行長得像圍欄，但在這段來源裡【不收掉任何圍欄】，例如
+  //    'Alpha.\n\n```js\ncode\n~~~'：那道 ```js 沒有被收掉，'~~~' 是它的本文。
+  //    在那裡打字只是改本文。
+  //  - a 分支落到的那一行【本身長得像圍欄】，因為它是外層圍欄的本文 —— 巢狀
+  //    圍欄 '~~~\n```\nx\n```\n~~~' 的 caret 就落在第二行那個 ``` 的行首
+  //    （test/editor-journey.test.js 的巢狀圍欄那一列釘的正是這個落點）。在那裡
+  //    打字得到 'Z```'，那一行仍然只是外層圍欄的本文，內外圍欄的配對都不變。
+  //
+  // b 分支不會讓文件變髒：openRawEditor() 的 `hasChanges()` 比對的是這支回
+  // 的 `value`（不是檔案裡那段 `source`），所以剛開起來的 textarea 仍然算
+  // 「沒有變更」，關掉走的是 restore()／cancelAndMaybeDiscard() 這條不寫檔的
+  // 路。`source` 本身留給 reanchor() 用，它比的是檔案的真實位元組。
+  //
+  // 刻意【沒有】照 task-5 brief 一併把 blockquote／image 改成「第一行行首」。
+  // MEASURED（lib/editor/blockmap.js 的 buildBlockMap）：
+  //   '> line one\n> line two'    -> blockquote
+  //   'X> line one\n> line two'   -> paragraph, blockquote   ← 行首落點
+  //   '> line one\n> line twoX'   -> blockquote              ← 結尾落點
+  // 對 blockquote 而言「第一行行首」在 '>' 的前面，打第一個字就把那一行踢出
+  // 引用區塊，比它要取代的結尾落點更糟。image 打在頭尾都等價（'X![a](b.png)' 與
+  // '![a](b.png)X' 都還是 paragraph）。
+  //
+  // 這支為什麼只動圍欄：圍欄是這些形狀裡唯一【結尾就是一個收尾標記】的。把一
+  // 個字打在其他形狀的結尾只是加字 —— MEASURED（buildBlockMap，左為原文、右
+  // 為結尾多打一個 X 之後的 type，左右相同就是沒壞）：
+  //   '| A | B |\n|---|---|\n| 1 | 2 |'  table      -> table
+  //   '    a\n    b'（縮排式 code）       code       -> code
+  //   '- alpha'                            li         -> li
+  //   '<div>\nhi\n</div>'                 html       -> html
+  //   '> a\n> b'                          blockquote -> blockquote
+  //   '![a](b.png)'                        paragraph  -> paragraph
+  // 圍欄的 type 也一樣是 code -> code，所以【單看一個孤立的區塊看不出差別】；
+  // 差別在整份文件上：收尾圍欄被打壞之後就不再收尾，它後面的東西全部併進來。
+  // 那是 test/editor-journey.test.js 的 F10 那一列量到的：5 個區塊掉到 3 個，
+  // 尾巴進磁碟。
+  // 一道圍欄的【開頭】，回 { char, len }；不是開頭圍欄時回 null。
+  //
+  // fix round 2 (K1/K3): 這裡與 closesFence() 取代了原本那對只認「長得像圍欄」
+  // 的 regex。收尾圍欄必須跟開頭圍欄【同一種字元、而且不比它短】，而反引號
+  // 圍欄的 info string 不得再含反引號。它們各修各的：K1 那個被種進空白行的缺
+  // 陷靠的是【收尾必須配對】那一條 —— 把 info string 那條單獨拿掉再掃一次圍欄形
+  // 狀，巢狀那幾種逐字不變（只有名字裡有 backtick-info 的那些形狀會變）。info
+  // string 那條自己的壞法在下面。
+  //
+  // 少了收尾配對那條，'~~~' 開頭、下一行是 '```' 的巢狀圍欄會被誤判成【空圍
+  // 欄】，於是 rawEditorSeed() 那個 grown 分支往使用者的檔案裡種進一行空白，而
+  // 且提交時真的寫到磁碟（40c9569 沒有這個問題，是 588ae30 引進的）。同一個誤判
+  // 的另一面在 endsWithUnclosedFence()：一份以光禿禿 '~~~' 收尾的文件會被當成
+  // 「圍欄有收好」，真正的吞噬因此靜默。
+  //
+  // 少了 info string 那條：'``` a`b' 這一行 marked 當它是【段落】（反引號圍欄的
+  // info string 不能含反引號），下一行才是真正的開頭圍欄。把段落那一行當成開頭
+  // 圍欄之後，它會跟後面那道真的收尾圍欄配成一對，rawEditorSeed() 於是把 caret
+  // 放到【真開頭圍欄】那一行的行首 —— 打一個字就把 '```js' 變成 'Z```js'，開頭
+  // 圍欄消失、收尾那道 ``` 反而變成開頭，它後面的東西被吃進去（實測 ablation
+  // 之後 blocks 從 heading paragraph code[4,6] paragraph 變成
+  // heading paragraph[3,5] code[6,8]）。這條由 test/editor-journey.test.js 的
+  // 「a backtick in the info string is not a fence opener」那一列釘住。
+  function fenceOpenerOf(line) {
+    if (typeof line !== 'string') return null;
+    const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (!m) return null;
+    const char = m[1].charAt(0);
+    if (char === '`' && m[2].indexOf('`') !== -1) return null;
+    return { char: char, len: m[1].length };
+  }
+  // `line` 能不能收掉 `opener` 開的那道圍欄。
+  //
+  // fix round 3 (L2): 這支的需求是 **marked 的行為**，不是 CommonMark 的條文，
+  // 也不是比較有道理的那個讀法 —— `j.blocks` 就是 marked 的 tokenizer 產出的，
+  // 這支只要跟它講的不一樣，判別式就會拿一份跟畫面上不同的文件在推理。
+  // marked 的 fences rule 收尾那一段是 `(?: {0,3}\1[~`]* *(?=\n|$)|$)`：最多三個
+  // 前導空格、接著跟開頭圍欄【逐字相同】的那一串（同字元同長度，`\1` 是
+  // backreference）、再接任意個 ` 或 ~、然後只能是空格。
+  //
+  // MEASURED（把候選行放進 '```\nx\n<候選>\nAFTER\n'，看 buildBlockMap 有沒有
+  // 把 AFTER 留在 code block 外面）—— 上一版跟 marked 在這些行上不一致，而且不
+  // 一致的方向不是單向的：
+  //   '```' + 一個 tab      marked 說【沒收】，上一版說收了 —— 正是 K3 那個 FN1 形狀
+  //   '``` ' + tab、'```' + tab + ' '   同上
+  //   '```~~'（混合的尾巴）  marked 說【收了】，上一版說沒收
+  // 尾端只認空格（marked 是 ` *`，不是 `[ \t]*`），而開頭那一串之後可以再跟
+  // 任意個 ` 或 ~。
+  function closesFence(line, opener) {
+    if (typeof line !== 'string' || !opener) return false;
+    let i = 0;
+    while (i < 3 && line.charAt(i) === ' ') i++;
+    for (let k = 0; k < opener.len; k++) {
+      if (line.charAt(i + k) !== opener.char) return false;
+    }
+    i += opener.len;
+    while (i < line.length && (line.charAt(i) === '`' || line.charAt(i) === '~')) i++;
+    while (i < line.length && line.charAt(i) === ' ') i++;
+    return i === line.length;
+  }
+  // 把 rows 掃一遍，回傳每一對【配對成功】的圍欄 { openIdx, closeIdx }。
+  // 沒有配到收尾的開頭圍欄不會出現在結果裡。
+  function fencePairs(rows) {
+    const pairs = [];
+    let open = null;
+    for (let i = 0; i < rows.length; i++) {
+      if (open) {
+        if (closesFence(rows[i], open.opener)) { pairs.push({ openIdx: open.idx, closeIdx: i }); open = null; }
+        continue;
+      }
+      const o = fenceOpenerOf(rows[i]);
+      if (o) open = { opener: o, idx: i };
+    }
+    return pairs;
+  }
+  function rowStartOffset(rows, idx) {
+    let n = 0;
+    for (let i = 0; i < idx; i++) n += rows[i].length + 1;
+    return n;
+  }
+  function rawEditorSeed(text) {
+    const rows = text.split('\n');
+    // 只有一行的來源直接落在結尾。那一行是一道孤零零的開頭圍欄時，caret 就在
+    // 標記行上 —— 見上面那段註解裡明講的那些例外。
+    if (rows.length === 1) return { value: text, caret: text.length };
+    const pairs = fencePairs(rows);
+    if (fenceOpenerOf(rows[0])) {
+      const first = pairs.filter(function (p) { return p.openIdx === 0; })[0];
+      if (first && first.closeIdx === 1) {
+        const grown = [rows[0], ''].concat(rows.slice(1));
+        return { value: grown.join('\n'), caret: rowStartOffset(grown, 1) };
+      }
+      return { value: text, caret: rowStartOffset(rows, 1) };
+    }
+    const lastIdx = rows.length - 1;
+    const tailPair = pairs.filter(function (p) { return p.closeIdx === lastIdx; })[0];
+    if (tailPair) {
+      if (tailPair.openIdx === lastIdx - 1) {
+        const grown = rows.slice(0, lastIdx).concat(['']).concat(rows.slice(lastIdx));
+        return { value: grown.join('\n'), caret: rowStartOffset(grown, lastIdx) };
+      }
+      return { value: text, caret: rowStartOffset(rows, lastIdx) - 1 };
+    }
+    return { value: text, caret: text.length };
+  }
+
   // v3.1.0 修正 4: `range` ({startLine, endLine}, 1-indexed inclusive) opens
   // the raw editor over an EXPLICIT span of source lines instead of the
   // block's own record. Two callers need it and one property makes both
@@ -1677,7 +2317,7 @@
     // delegator so
     // every caller — the delegated degraded-block click, openRawViaGutter(),
     // the burst-degrade path — is closed by one check.
-    if (blockOwnsNoLine(blockEl)) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return; }
+    if (blockOwnsNoLine(blockEl)) { refuseStructuralListEdit(noSourceLineMessageFor(blockEl)); return; }
 
     // v3.1.0 修正 4: the span this editor owns. Without `range` it is exactly
     // the block's own record, so `source` below is byte-identical to what
@@ -1689,7 +2329,7 @@
     // The same inverted-range refusal blockOwnsNoLine() just made for the
     // block, re-asked of the range actually being edited: a caller-supplied
     // span can be malformed even when the anchor block is fine.
-    if (endLine < startLine) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return; }
+    if (endLine < startLine) { refuseStructuralListEdit(noSourceLineMessageFor(blockEl)); return; }
     // A list item's rendered chrome (the .ed-li-marker span, the optional
     // .ed-li-check span, the .ed-li-text surface) is REBUILT BY THE RENDERER
     // from the source line's marker — it is not recoverable from a captured
@@ -1711,7 +2351,11 @@
 
     const ta = document.createElement('textarea');
     ta.className = 'ed-raw';
-    ta.value = source;
+    // F9: `seed.value` 通常 === `source`；只有空圍欄那一種形狀會多一行
+    // 空白本文（見 rawEditorSeed()）。`source` 不可以跟著換掉 ——
+    // reanchor() 拿它跟檔案裡的位元組逐字比。
+    const seed = rawEditorSeed(source);
+    ta.value = seed.value;
 
     // `restore`/`commit` are hoisted function declarations (defined further
     // down in this closure) — referencing them here, before their textual
@@ -1723,7 +2367,10 @@
     // commit()/restore() closures used by the manual Ctrl+Enter/✓/Esc/✕ UI.
     activeEditor = {
       blockEl,
-      hasChanges: () => ta.value !== source,
+      // F9: 比對 `seed.value` 而不是 `source` —— 空圍欄那條路上種進去的那
+      // 一行空白是這個編輯器自己放的，不是使用者打的，把它算成「有變更」
+      // 會讓「開起來看一眼就關掉」變成一次靜默的寫檔。
+      hasChanges: () => ta.value !== seed.value,
       commitNow: commit,
       cancelNow: cancelAndMaybeDiscard,
       reanchor,
@@ -1749,7 +2396,8 @@
     blockEl.appendChild(wrap);
     autoSize(ta);
     ta.focus();
-    ta.setSelectionRange(ta.value.length, ta.value.length);
+    // F9: 不再無條件落在值的結尾 —— 見 rawEditorSeed() 自己的註解。
+    ta.setSelectionRange(seed.caret, seed.caret);
 
     async function restore() {
       // v3.1.0 修正 4: `rangeMode` cannot restore by rewriting innerHTML —
@@ -1764,12 +2412,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
@@ -2019,7 +2672,8 @@
   //   '# D\n\n- a\n\n- - b\n'  --type Z-->  '# D\n\n- a\n\n- Z\n- - b\n'
   //
   // Refusing here closes every such path with one rule, instead of teaching
-  // seven commit helpers about a range shape none of them expect. The block is
+  // each commit helper that reaches ops.replaceLines() (grep
+  // `ops.replaceLines(`) about a range shape none of them expect. The block is
   // still rendered, still selectable, and its CHILD — which does own its line —
   // stays fully editable.
   function blockOwnsNoLine(blockEl) {
@@ -2029,6 +2683,47 @@
     return !!rec && rec.endLine < rec.startLine;
   }
 
+  // Two DIFFERENT things now arrive with an empty range, and blockOwnsNoLine()
+  // cannot tell them apart because the range shape is identical:
+  //
+  //   '- - a'   the outer item genuinely owns no line — its content begins
+  //             with its child. A modelled, legitimate shape.
+  //   degraded  blockmap.js could not LOCATE this item's nested list inside
+  //             the item's own text, so it emptied the whole subtree rather
+  //             than hand out line numbers it had guessed. The item owns a
+  //             line; nobody can say which.
+  //
+  // Answering the second with the first's wording ('沒有自己的來源行') would
+  // tell the user something untrue about their document — that item HAS a
+  // source line. So the flag blockmap.js sets on the degraded records is read
+  // here, instead of re-deriving a cause from `endLine < startLine`, which
+  // carries none.
+  //
+  // No markdown MEASURED so far reaches the second branch: every string a full
+  // journey run hands buildBlockMap(), and every trailing-space variant of
+  // those, produced no `unlocatable` records. So the branch is driven
+  // instead by making the real blockmap search fail — grep
+  // test/editor-journey.test.js for 'already degraded', which wraps marked's
+  // lexer for one row so the server serves a genuinely degraded document, then
+  // clicks the degraded item and reads the banner off the page. MEASURED by that
+  // row, and only that row: the click renders UNLOCATABLE_LINE_MESSAGE, opens no
+  // textarea, and leaves the file byte-identical.
+  //
+  // The other half of the pair is pinned somewhere else and it is worth knowing
+  // where, because no single file renders both: test/editor-client-runtime.test.js
+  // clicks the outer item of a '- - b' same-line nest and asserts the banner
+  // reads NO_SOURCE_LINE_MESSAGE — grep it for '沒有自己的來源行'. Those two
+  // assertions, in two files, are what keep the two causes from collapsing back
+  // into one sentence. This branch is a net for a shape nobody has produced yet,
+  // not a path.
+  function blockRangeIsUnlocatable(blockEl) {
+    if (!blockEl || !blockEl.getAttribute) return false;
+    const raw = blockEl.getAttribute('data-block-id');
+    if (raw === null) return false;
+    const rec = blocks.find((b) => b.id === Number(raw));
+    return !!(rec && rec.unlocatable);
+  }
+
   // Task 4 fix round 1: the message the two blockOwnsNoLine() guards above
   // (openRawEditor / deleteBlockViaGutter) pass into the SHARED
   // refuseStructuralListEdit() helper (defined further down, next to
@@ -2041,6 +2736,23 @@
   // operations it refuses — an insert that answered '無法刪除' would be
   // telling the user something that is not true of the button they pressed.
   const NO_SOURCE_LINE_INSERT_MESSAGE = '此項目沒有自己的來源行，無法在其後插入區塊';
+  // The degraded-subtree wording (see blockRangeIsUnlocatable() above). Each
+  // one NAMES ITS OPERATION exactly as the pair above does — that is the whole
+  // reason the pair above is a pair — and differs from it only in the clause
+  // that states the cause. Deliberately says nothing about the refusal being
+  // temporary: nothing lifts it, so wording like 「已暫停」 would promise a state
+  // change that never comes.
+  const UNLOCATABLE_LINE_MESSAGE = '這段巢狀清單對不到自己的來源行，無法刪除或直接編輯';
+  const UNLOCATABLE_LINE_INSERT_MESSAGE = '這段巢狀清單對不到自己的來源行，無法在其後插入區塊';
+  // Both refusals go through one chooser each, so a call site cannot pick the
+  // right guard and the wrong sentence.
+  function noSourceLineMessageFor(blockEl) {
+    return blockRangeIsUnlocatable(blockEl) ? UNLOCATABLE_LINE_MESSAGE : NO_SOURCE_LINE_MESSAGE;
+  }
+  function noSourceLineInsertMessageFor(blockEl) {
+    return blockRangeIsUnlocatable(blockEl)
+      ? UNLOCATABLE_LINE_INSERT_MESSAGE : NO_SOURCE_LINE_INSERT_MESSAGE;
+  }
 
   // The list markers standing at the head of one source line, left to right.
   // A same-line nest ('- 1. b') puts one marker per nesting level on the line;
@@ -2511,6 +3223,151 @@
     sel.addRange(range);
   }
 
+  // ── Task 15: the two selections Tab writes ───────────────────────────────
+  //
+  // Both go through setBaseAndExtent() rather than the removeAllRanges() +
+  // addRange() pair placeCaretAtEnd() just above uses, because Tab now writes
+  // a selection on every press and the spellings differ in what they
+  // dispatch. Counted on a live cell, applying boundary values that were
+  // ALREADY the ones in force: setBaseAndExtent() dispatched no
+  // selectionchange, removeAllRanges() + addRange() dispatched one, and
+  // selectNodeContents() followed by that pair dispatched one. The resulting
+  // Range is otherwise the same: over a cell holding 'c2', both spellings of
+  // "select the contents" read back start TD offset 0 to end TD offset 1
+  // covering 'c2', and both spellings of each caret placement read back the
+  // matching collapsed pair. On a cell emptied first, setBaseAndExtent()
+  // placed a collapsed selection instead of throwing.
+  //
+  // The element-anchored boundary points are load-bearing beyond tidiness —
+  // see `tabSelectedCellEl` further down, whose release condition is exactly
+  // "the live selection is no longer these".
+  function selectSurfaceContents(el) {
+    const sel = window.getSelection();
+    if (!sel) return;
+    sel.setBaseAndExtent(el, 0, el, el.childNodes.length);
+  }
+
+  function placeCaretAtSurfaceStart(el) {
+    const sel = window.getSelection();
+    if (!sel) return;
+    sel.setBaseAndExtent(el, 0, el, 0);
+  }
+
+  // ── Marks a Range operation leaves behind holding nothing ────────────────
+  //
+  // extractContents() and deleteContents() each act on an element the range
+  // only PARTIALLY contains by taking its contained part and leaving the
+  // original element in place. When the boundary sits at offset 0 of that
+  // element's own first child, everything it held goes and the original is
+  // left holding nothing that renders. Measured, bolding a selection that
+  // starts at the first character of an <em>:
+  //
+  //   before  `Alpha <em>ital</em> bold text here.`
+  //   after   `Alpha <em></em><strong><em>ital</em> bold</strong> text here.`
+  //
+  // Nothing downstream drops that <em>: it still serialises to its delimiter
+  // on each side. The bytes measured on disk, one gesture per line, all from
+  // the same selection:
+  //
+  //   toolbar 粗體  `Alpha *****ital* bold** text here.`
+  //   toolbar 🔗    `Alpha **[*ital* bold](https://example.com) text here.`
+  //   Shift+Enter   `Alpha **<br> text here.`
+  //   paste         `Alpha **PASTED text here.`
+  //   Enter in a li `- Alpha **`
+  //
+  // Each of those re-parses with the stray asterisks as literal text and comes
+  // back escaped on the next save — 「*字號前面都有 \ 跳脫」, the symptom this
+  // was reported as. Journey row `escape-cycle` drives that whole cycle.
+  //
+  // Collecting and dropping are separate functions because the operation
+  // between them differs per call site: extractContents() into a new element
+  // (the mark and link paths), deleteContents() then an insert (Shift+Enter,
+  // paste), and a delete plus a tail extraction (the list split, which folds
+  // its delete range and its tail range into the same collection).
+
+  const EDIT_SURFACE_SEL = '.ed-wys-armed, .ed-wys-cell';
+
+  // The editing surface `node` sits in — a paragraph / heading / list-item
+  // surface, or a table cell. This is what the walk below terminates at, and
+  // the reason it names the CELL rather than the <table>: a cell left holding
+  // nothing must stay a cell, and it does because the walk never reaches it.
+  function editSurfaceOf(node) {
+    const el = node && (node.nodeType === 1 ? node : node.parentNode);
+    return el && el.closest ? el.closest(EDIT_SURFACE_SEL) : null;
+  }
+
+  // The elements the operation could leave empty: the element ancestors of
+  // `range`'s start container and of its end container, up to (not including)
+  // `root`, each tagged with its element depth below `root`. Called BEFORE the
+  // operation, because the Range's boundary points move the moment it runs.
+  //
+  // `into` lets a call site fold several ranges into the same collection; an
+  // element already collected is not collected again.
+  //
+  // A boundary that is not inside `root` contributes nothing, and a falsy
+  // `root` collects nothing at all. Without a terminator inside the editing
+  // surface the walk would climb into the page chrome, and there is nothing up
+  // there this function could nominate for removal. Making that true HERE rather than
+  // trusting each caller is what lets the removal below dereference
+  // `parentNode` unguarded.
+  function collectLeftovers(range, root, into) {
+    const leftovers = into || [];
+    if (!root) return leftovers;
+    const collect = (node) => {
+      if (!node || !root.contains(node)) return;
+      const chain = [];
+      for (let n = node; n && n !== root; n = n.parentNode) {
+        if (n.nodeType === 1) chain.push(n);
+      }
+      // `chain` is deepest-first, so `chain.length - i` is the element depth
+      // below `root` — a value that compares correctly across chains, which a
+      // plain per-chain index would not.
+      chain.forEach((n, i) => {
+        if (!leftovers.some((x) => x.el === n)) leftovers.push({ el: n, depth: chain.length - i });
+      });
+    };
+    collect(range.startContainer);
+    collect(range.endContainer);
+    return leftovers;
+  }
+
+  // Removes the collected elements the operation left holding nothing. Call it
+  // AFTER whatever the call site puts in the range's place, so an element that
+  // now holds the new node is not mistaken for an empty leftover.
+  //
+  // "Holds nothing" is `no child ELEMENT and no text`. Every conjunct of that
+  // test has a journey row that reds when that conjunct alone is removed:
+  //
+  //  * the text test alone would delete a mark left holding a <br> — a hard
+  //    break has no text, but it is content the user typed. Journey row
+  //    `keeps-br`.
+  //  * the element test alone would delete a mark left holding TEXT, which is
+  //    what a selection starting partway into that mark leaves behind. Journey
+  //    row `keeps-text`.
+  //
+  // What it is NOT is a child count. A fully-taken boundary text node is not
+  // removed by extractContents() or by deleteContents(); its data is replaced
+  // with the remainder, so the node survives holding the empty string. Probed
+  // right after the extraction on the bold row — the surviving <em> reported
+  // `<em></em>`, its childNodes still holding a text node whose data was "". A child-count test
+  // never fires on the very shape this exists for.
+  //
+  // Deepest first, so a mark left empty only by the removal of an inner one is
+  // still seen as empty when its own turn comes. Journey row `nested-order`.
+  //
+  // `parentNode` is dereferenced unguarded: a candidate is an ancestor of a
+  // boundary container and a strict descendant of `root` — collectLeftovers()
+  // enforces the descendant part rather than trusting callers. A partially
+  // contained ancestor is exactly what these Range methods leave in place: the
+  // `before`/`after` measurement above is that, seen directly. And the
+  // deepest-first order means a candidate is reached only after every candidate
+  // it contains, so nothing detaches a candidate before its turn.
+  function dropEmptied(leftovers) {
+    leftovers.slice().sort((a, b) => b.depth - a.depth).forEach((x) => {
+      if (!x.el.firstElementChild && x.el.textContent === '') x.el.parentNode.removeChild(x.el);
+    });
+  }
+
   // Paste handler support: insert plain text at the caret via Range surgery,
   // keeping the serializer's input domain closed to plain text + the inline
   // elements it itself produces (bold/italic/code/links/br) — see the brief's
@@ -2533,6 +3390,9 @@
     const sel = window.getSelection();
     if (!sel.rangeCount) return;
     const range = sel.getRangeAt(0);
+    // Same leftover as the toolbar's: a paste over a selection that starts at
+    // the first character of an <em> left `Alpha **PASTED text here.` on disk.
+    const leftovers = collectLeftovers(range, editSurfaceOf(range.startContainer));
     range.deleteContents();
     const segments = String(text).split(/\r\n|\r|\n/);
     segments.forEach((seg, i) => {
@@ -2547,6 +3407,7 @@
       range.setStartAfter(node);
       range.setEndAfter(node);
     });
+    dropEmptied(leftovers);
     sel.removeAllRanges();
     sel.addRange(range);
   }
@@ -2560,11 +3421,20 @@
     const sel = window.getSelection();
     if (!sel.rangeCount) return;
     const range = sel.getRangeAt(0);
+    // Same leftover as the toolbar's: Shift+Enter over a selection that starts
+    // at the first character of an <em> left `Alpha **<br> text here.` on disk.
+    const leftovers = collectLeftovers(range, editSurfaceOf(range.startContainer));
     range.deleteContents();
     const br = document.createElement('br');
     range.insertNode(br);
     range.setStartAfter(br);
     range.setEndAfter(br);
+    // After the <br> is in place, because the <br> can land INSIDE a mark this
+    // very delete emptied and that mark must then be kept. Measured, Shift+Enter
+    // over a selection covering the whole of `<em>ital</em>`:
+    // `Alpha <em><br></em> bold text here.` — dropping before the insert would
+    // have taken that <em> and the caret's new home with it.
+    dropEmptied(leftovers);
     sel.removeAllRanges();
     sel.addRange(range);
   }
@@ -2576,7 +3446,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 +3523,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 +3544,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 ───────────
@@ -3043,6 +3982,21 @@
     });
     sub.style.top = anchorBtn.offsetTop + 'px';
     anchorBtn.parentNode.appendChild(sub);
+    // Clamp the panel's top into the viewport. Measured on this branch:
+    // opening ⠿ then hovering 轉換成 never reads window.innerHeight before
+    // this line, confirming the clamp below did not already exist somewhere
+    // else in this path. getBoundingClientRect() is read after the append
+    // above, so the height it reports is the panel as laid out here, not a
+    // guessed constant, and it already reflects .ed-handle-submenu's own
+    // max-height cap (lib/md2doc.js) when a short viewport has forced that
+    // cap to bite. Its `bottom` already carries the containing block's
+    // screen position, because the `top` set above resolves against that
+    // block (position: absolute). Shifting `top` up by the bottom overflow
+    // is the clamp.
+    const overflowBottom = sub.getBoundingClientRect().bottom - window.innerHeight;
+    if (overflowBottom > 0) {
+      sub.style.top = (anchorBtn.offsetTop - overflowBottom) + 'px';
+    }
     convertSubmenu = sub;
     convertSubmenuViaHover = !!viaHover;
     // The aim triangle needs a previous sample to have an apex; the first
@@ -3377,21 +4331,19 @@
     if (kind === 'code') {
       // Code blocks are never WYSIWYG-armed (armEditables() above has no
       // 'code' branch) — same degraded-block contract as any other fence:
-      // click opens the raw in-place source editor directly. openRawEditor()
-      // itself places the caret at the END of the textarea (its generic
-      // contract, shared with every other raw-edit open path) — that lands
-      // AFTER the closing fence, not on the blank BODY line
-      // BLOCK_SKELETONS['code'] (see its own comment) puts there
-      // specifically so typing has somewhere to land. Move it there once
-      // the textarea exists.
+      // click opens the raw in-place source editor directly.
+      //
+      // F9: this branch used to re-place the caret itself, because
+      // openRawEditor() put it at the END of the textarea — i.e. after the
+      // closing fence, not on the blank BODY line BLOCK_SKELETONS['code']
+      // (`['```', '', '```']`, see its own comment) puts there specifically
+      // so typing has somewhere to land. openRawEditor() now asks
+      // rawEditorSeed() (see its own comment), and for that skeleton — whose
+      // middle row is '' and therefore not a bare fence — it returns the
+      // same offset this branch used to compute, indexOf('\n') + 1, with the
+      // value untouched. So the fix-up is deleted rather than kept as a
+      // no-op that reads like it is still load-bearing.
       await openRawEditor(blockEl);
-      const ta = blockEl.querySelector('textarea.ed-raw');
-      if (ta) {
-        const nlIdx = ta.value.indexOf('\n');
-        const pos = nlIdx === -1 ? ta.value.length : nlIdx + 1;
-        ta.setSelectionRange(pos, pos);
-        ta.focus();
-      }
       return;
     }
     if (kind === 'table') {
@@ -3457,7 +4409,7 @@
     // li block grows no ＋ until S2; S2 is next, and a guard that has to be
     // remembered later is a guard that will not be.
     if (blockOwnsNoLine(liveBlockEl)) {
-      refuseStructuralListEdit(NO_SOURCE_LINE_INSERT_MESSAGE);
+      refuseStructuralListEdit(noSourceLineInsertMessageFor(liveBlockEl));
       return;
     }
     const customLines = opts && Array.isArray(opts.lines) ? opts.lines : null;
@@ -3522,7 +4474,7 @@
       // commitBlockInsertion() is about to read `endLine` and `lines[endLine]`
       // off. Re-checked against the block actually used.
       if (blockOwnsNoLine(anchorEl)) {
-        refuseStructuralListEdit(NO_SOURCE_LINE_INSERT_MESSAGE);
+        refuseStructuralListEdit(noSourceLineInsertMessageFor(anchorEl));
         return;
       }
     }
@@ -3566,6 +4518,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 +4657,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
@@ -3708,9 +4707,10 @@
     // A block that owns no source line has an INVERTED range
     // (endLine === startLine - 1) and every commit helper handed one does
     // something plausible and wrong.
-    if (blockOwnsNoLine(liveBlockEl)) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return null; }
+    if (blockOwnsNoLine(liveBlockEl)) { refuseStructuralListEdit(noSourceLineMessageFor(liveBlockEl)); 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)
@@ -3752,7 +4752,7 @@
       // but "another module filters it" is an argument about another file's
       // output, and this is the guard that stands between an inverted range and
       // a commit helper.
-      if (blockOwnsNoLine(el)) { refuseStructuralListEdit(NO_SOURCE_LINE_MESSAGE); return null; }
+      if (blockOwnsNoLine(el)) { refuseStructuralListEdit(noSourceLineMessageFor(el)); return null; }
       els.push(el);
     }
     return { els: els, recs: members, batch: members.length > 1 };
@@ -3884,7 +4884,168 @@
     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 — most commits past the
+      // first page load take that route, but the FALLBACK stays reachable
+      // through the whole session on its own routes, not just the first
+      // render: `domMatchesLastRender()` (see its own comment) fails on a
+      // block-count, dom-child-count, or per-block-id mismatch just as
+      // readily as on a null `lastParts`, and `safeRerenderAll()`'s
+      // no-`editRange` callers — restore()'s rangeMode exit, the per-li
+      // unsupported-format refusal, commitListStructure()'s no-range exit
+      // (see the wrapper's own comment just above it) — fall back by
+      // contract regardless of dom state.
+      //
+      // 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 via `surface.focus()`, which dispatches focusin
+      // SYNCHRONOUSLY. The first version of this comment read `currentBurst`
+      // as still the OLD burst at guard time, with focusin's
+      // `if (currentBurst) return;` stopping a fresh one from opening — that
+      // was never measured, and does not hold on this route: `switching` is
+      // truthy here (this very commit is the render switchAwayFrom() is
+      // awaiting), so the handler suspends at `if (switching) await
+      // switching;`, the line immediately before that guard, and cannot get
+      // past it until this same call to applyPatch() returns. By then
+      // applyPatch()'s OWN focus-adoption tail has already run — the
+      // `if (!currentBurst && ae && contentEl.contains(ae)) { … startBurst(ae);
+      // … }` further down this function, whose own comment notes undo's
+      // synchronous focusin leaves that check "恆為 false" there (currentBurst
+      // already set by then) — the mirror image of this route, where
+      // currentBurst is null at that point and the check fires, opening a
+      // fresh burst on the very surface `focus()` landed on. The suspended
+      // focusin's `if (currentBurst) return;` reads THAT burst once it
+      // resumes, not the pre-patch one persisting. Either way `burstSurvived`
+      // is false and `resetToolbarBlock()` runs AFTER the caret was handed
+      // back — that half stood correct and still does. 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 +5055,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 +5128,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 +5136,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 +5186,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 +5248,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 +5300,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 +5332,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 +5347,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 +5363,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 +5383,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 +5426,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 +5609,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 +5642,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 +5685,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 +5907,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 +6059,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 +6126,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 +6182,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();
@@ -4897,6 +6268,7 @@
   }
 
   function startBurst(editEl) {
+    dropDiscardedBurst();
     const blockEl = editEl.closest('.ed-block');
     if (!blockEl) return;
     const blockId = Number(blockEl.getAttribute('data-block-id'));
@@ -4911,6 +6283,7 @@
       original: burstBaselineHtml(editEl),
       history,
     };
+    watchBurstForDirtyDot(editEl);
     selToolbarEditEl = editEl;
     if (!selToolbarListener) {
       selToolbarListener = onSelectionChangeForToolbar;
@@ -5230,6 +6603,51 @@
     return document.querySelector('.ed-block[data-block-id="' + target.id + '"]');
   }
 
+  // ── Task 15: where a keyboard caret can actually land ────────────────────
+  //
+  // Hands back the element inside `blockEl` that can hold a caret, or null
+  // when the block has none. It answers with the target rather than a yes/no
+  // so the Tab walk out of a table takes its landing site from the same
+  // measurement that decided the block was reachable at all.
+  //
+  // The class tokens asked for are the ones armEditables() writes: a single
+  // contenteditable surface carrying 'ed-wys-armed' (its paragraph/heading
+  // branch, and the armed row of its li branch), and a table's per-cell
+  // surfaces carrying 'ed-wys-cell'. A block armEditables() left degraded
+  // carries neither.
+  //
+  // Asking a class rather than calling .focus() and reading
+  // document.activeElement back is not caution. Driven over a fixture whose
+  // blocks were a table, a fenced code block, another table, a blockquote, an
+  // image-only paragraph, a thematic break and a plain paragraph,
+  // blockContentEl(blockEl).focus() left document.activeElement on BODY for
+  // every one of them except the paragraph — the tables included, because
+  // blockContentEl() of a table block is the <table> itself and focusing that
+  // moved nothing, while focusing one of its cells does.
+  //
+  // querySelector cannot reach past this block into a nested item's: driven on
+  // a fixture whose list nests, every '.ed-block' in the document was a direct
+  // child of '.content' and none had another '.ed-block' as an ancestor.
+  // md2doc.js emits a nested item's block as a SIBLING carrying 'data-indent',
+  // not inside its parent's.
+  function focusableSurfaceOf(blockEl) {
+    if (!blockEl) return null;
+    return blockEl.querySelector('.ed-wys-armed') || blockEl.querySelector('.ed-wys-cell');
+  }
+
+  // The nearest sibling block in `dir` (+1 forward, -1 back) that has one, or
+  // null. Nothing tests for '.ed-block' on the way past: on the same fixture
+  // every child of '.content' was one, and armEditables() only ever walks
+  // '.ed-block' elements, so an element that was not one carries no surface
+  // for focusableSurfaceOf() to find.
+  function adjacentFocusableBlock(blockEl, dir) {
+    const step = (el) => (dir > 0 ? el.nextElementSibling : el.previousElementSibling);
+    for (let el = blockEl ? step(blockEl) : null; el; el = step(el)) {
+      if (focusableSurfaceOf(el)) return el;
+    }
+    return null;
+  }
+
   // ── S3 Task 2: block multi-select state ────────────────────────────────
   // The selection's identity is a LINE RANGE, never ids and never nodes.
   // buildBlockMap renumbers every id from 0 on every render (blockmap.js's
@@ -5435,8 +6853,9 @@
   // v3.0.2: computeIndentClamp() lives past this file's node early-exit
   // (module.exports at line ~509 ships the pure core only) and nothing on
   // window reaches it, so the stale-span assert added to it in v3.0.2 had
-  // no way to be tested at all. This is the seventh __edTest seam and the
-  // only production surface that change adds.
+  // no way to be tested at all. This joins the other test seams on window
+  // (grep `window.__edTest`) and is the only production surface that change
+  // adds.
   window.__edTestClampProbe = function (spanEls, opBlockEl, opOldIndent, opts) {
     return computeIndentClamp(spanEls, opBlockEl, opOldIndent, opts);
   };
@@ -6045,17 +7464,122 @@
     // real commit is also possible).
     const wasPristineForThisBlock = !!(pristineInsert && pristineInsert.blockId === burst.blockId);
     if (wasPristineForThisBlock) pristineInsert = null;
-    burst.history.dispose();
-    editEl.innerHTML = burst.original;
-    currentBurst = null;
-    resetSelToolbarState();
+    // T21 item 1: a pristine insert keeps the old, unrecoverable shape, and
+    // that is not an oversight — discardPristineInsert() REMOVES the block, so
+    // there is no surface left to restore into and nothing was typed that the
+    // skeleton itself did not carry (the pristine window closes at this
+    // block's first real edit; see pristineInsert's own comment).
     if (wasPristineForThisBlock) {
+      burst.history.dispose();
+      editEl.innerHTML = burst.original;
+      currentBurst = null;
+      resetSelToolbarState();
       await discardPristineInsert(); // rerenderAll() already detaches editEl — nothing left to blur()
       return;
     }
+    // The paired snapshot, the same shape snapBurstIfActive() spells out for
+    // the programmatic mutations that already snap on both sides of
+    // themselves (grep `history.snap('` for them): the state being thrown away
+    // has to be on the stack ABOVE the state being restored, or the undo lands
+    // one entry short. flushTyping() is the pre half here rather than a snap()
+    // — after typing, the debounce is what is holding the typed state.
+    //
+    // Both lines were ablated one at a time and the gesture re-driven, on the
+    // paragraph, and each one alone loses the text: with flushTyping() removed,
+    // Escape then Ctrl+Z left the paragraph reading 'The migration has three
+    // phases.' — the typing gone and not on the document stack either; with the
+    // snap() removed, the same gesture left the same text, i.e. the Ctrl+Z
+    // looked like it did nothing.
+    burst.history.flushTyping();
+    editEl.innerHTML = burst.original;
+    burst.history.snap('escape-discard');
+    discardedBurst = {
+      history: burst.history, editEl, blockType: burst.blockType, cellIdx: -1,
+      reverted: burstBaselineHtml(editEl),
+    };
+    currentBurst = null;
+    resetSelToolbarState();
     editEl.blur();
   }
 
+  // The table twin of the stash above — a table burst's editEl is the whole
+  // <table> and the focused node is one cell, so restoring has to put the
+  // caret back in a cell, by ORDINAL among tableCellsOf() (the same handle
+  // tableBurstUndo() uses, and for the same reason: the innerHTML swap
+  // replaces every cell node).
+  function stashDiscardedTableBurst(burst, tableEl, cellIdx, revertFn) {
+    burst.history.flushTyping();
+    revertFn();
+    burst.history.snap('escape-discard');
+    discardedBurst = {
+      history: burst.history, editEl: tableEl, blockType: 'table', cellIdx,
+      reverted: burstBaselineHtml(tableEl),
+    };
+  }
+
+  // Ctrl+Z with no burst open, when the last thing that happened was an
+  // Escape: put back what that Escape discarded and re-open the burst around
+  // it, so the restored text is a live edit again — dirty dot lit, committed
+  // by the next blur, and one more Ctrl+Z steps back through the same history
+  // to the pre-edit baseline and then cascades out to the document stack.
+  //
+  // Returns false when there is nothing to restore or the stash has gone
+  // stale, and the caller then does the ordinary document undo — which is
+  // what an Escape that discarded NOTHING (focus a surface, press Escape
+  // without editing) must also do: its history has a single entry, undo()
+  // answers null, and the user's Ctrl+Z is not swallowed.
+  //
+  // The order — focus FIRST, then write — is load-bearing. focus() opens a
+  // fresh burst whose `original` is the reverted surface, so the restored
+  // text reads as an edit against it; writing first and focusing after would
+  // make the restored text the new baseline, and resolveBurst()'s zero-edit
+  // guard would then drop it on the way out without committing.
+  function restoreDiscardedBurst() {
+    const d = discardedBurst;
+    discardedBurst = null;
+    if (!d) return false;
+    if (!document.body.contains(d.editEl) || burstBaselineHtml(d.editEl) !== d.reverted) {
+      d.history.dispose();
+      return false;
+    }
+    const typed = d.history.undo();
+    if (typed === null) { d.history.dispose(); return false; }
+    const isTable = d.blockType === 'table';
+    const cells = isTable ? tableCellsOf(d.editEl) : [];
+    const entry = isTable
+      ? (cells[Math.max(0, Math.min(cells.length - 1, d.cellIdx))] || cells[0])
+      : d.editEl;
+    if (!entry) { d.history.dispose(); return false; }
+    entry.focus();
+    if (!currentBurst || currentBurst.editEl !== d.editEl) { d.history.dispose(); return false; }
+    currentBurst.history.dispose();
+    currentBurst.history = d.history;
+    if (isTable) {
+      // See suppressTableFocusout's own comment: this reassignment detaches
+      // the focused cell, and Chromium fires the blur/focusout for it
+      // synchronously, with the burst deliberately still live.
+      const tableEl = d.editEl;
+      suppressTableFocusout = true;
+      try {
+        tableEl.innerHTML = typed;
+      } finally {
+        suppressTableFocusout = false;
+      }
+      const newCells = tableCellsOf(tableEl);
+      const target = newCells[Math.max(0, Math.min(newCells.length - 1, d.cellIdx))] || newCells[0];
+      if (target) {
+        currentBurst.activeCellEl = target;
+        selToolbarEditEl = target;
+        target.focus();
+        placeCaretAtEnd(target);
+      }
+      return true;
+    }
+    d.editEl.innerHTML = typed;
+    placeCaretAtEnd(d.editEl);
+    return true;
+  }
+
   // Ctrl+Z inside a burst: step the burst-local history first; only once
   // it's exhausted (atBottom — the surface is already back to its pre-focus
   // baseline) does this cascade OUT to the document-level undo() stack,
@@ -6120,6 +7644,27 @@
   // paste toggle inside a table cell silently skipped its own burst-history
   // snapshot — Ctrl+Z after it would step PAST the mark (or straight to
   // cascading out of the burst) instead of reverting just that toggle.
+  //
+  // v3.3.0 地基 B — every caller of THIS function now snapshots on BOTH sides
+  // of its mutation (the `*-pre` reasons are the pre-mutation half). The table
+  // structural ops — insert row, insert column, delete row, delete column,
+  // cycle column align, drag row, drag column — take the same paired shape but
+  // call currentBurst.history.snap() directly; grep `history.snap('` to see
+  // all of them at once. The burst history's
+  // undo() pops the top and returns the entry BELOW it, so the stack top has
+  // to describe the DOM as it currently stands; a lone post-mutation snap
+  // makes the top "typed text + the mark" with nothing between it and the
+  // block's opening state, and one Ctrl+Z therefore threw away the sentence
+  // the user had just typed along with the mark. MEASURED before the fix, on
+  // a paragraph typed into and then bolded from the toolbar: the DOM after
+  // Ctrl+Z was "Alpha paragraph." — the whole ` typed sentence` gone.
+  //
+  // The extra call is free when nothing has changed: history.snap() compares
+  // its capture against the stack top and pushes only on a difference, so a
+  // pre-mutation snap taken when the top is already current adds no entry.
+  //
+  // `reason` is metadata only — createBurstHistory().snap() does not read it
+  // (see lib/editor/history.js).
   function snapBurstIfActive(root, reason) {
     if (currentBurst && (currentBurst.editEl === root || currentBurst.editEl.contains(root))) {
       currentBurst.history.snap(reason);
@@ -6150,6 +7695,14 @@
       if (e.key === 'Tab') e.preventDefault();
       return;
     }
+    // T21 item 2: the landing mark survives a RUN of Tabs and nothing else.
+    // Shift is excluded because it is Shift+Tab's own first keydown, and
+    // excluding it is what lets a backwards walk keep walking. Every other
+    // key — a character, Ctrl, Escape — is the user starting to work on the
+    // block they landed on, and from then on Tab means what it has always
+    // meant here (heading depth / list indent). Set BEFORE the li dispatch
+    // below so both surfaces see the same cleared mark.
+    if (e.key !== 'Tab' && e.key !== 'Shift') currentBurst.arrivedByTab = false;
     // Task 8 (Phase 4): per-li burst — Enter / Shift+Enter / Tab / Shift+Tab
     // are owned by handleLiKeydown() below (spec §4's key semantics for li
     // surfaces, acceptance rows 1, 3, 5, 6, 7, 8). Every other key (Escape,
@@ -6180,6 +7733,19 @@
     // whatever the commit message that introduced this said.
     if (e.key === 'Tab') {
       e.preventDefault();
+      // T21 item 2: a Tab that ARRIVED here keeps walking instead of editing
+      // what it landed on. Task 15 gave Tab a cross-block landing but left the
+      // next Tab reading as this branch, and a key being used to navigate then
+      // silently rewrote the document: driven on the fixture table, pressing
+      // its last body cell and then Tab four times took '### Build snippet' to
+      // '######' and Ctrl+S wrote that to disk; backwards from the first
+      // header cell, Shift+Tab twice outdented '  - epsilon' to '- epsilon' on
+      // disk. Both were silent — a heading changing size and the title's dot
+      // were the only tells.
+      if (currentBurst.arrivedByTab) {
+        walkToAdjacentBlockByTab(currentBurst.blockEl, e.shiftKey ? -1 : 1);
+        return;
+      }
       if (currentBurst.blockType === 'heading') {
         changeHeadingDepth(currentBurst.blockEl, e.shiftKey ? -1 : 1);
       }
@@ -6188,6 +7754,7 @@
     if (e.key === 'Enter') {
       e.preventDefault();
       if (e.shiftKey) {
+        snapBurstIfActive(editEl, 'br-pre');
         insertBrAtCaret();
         snapBurstIfActive(editEl, 'br');
       } else {
@@ -6337,9 +7904,10 @@
   }
 
   // Splits `blockEl` into two sibling BLOCKS at the caret via Range surgery —
-  // the same extractContents()-based pattern wrapRangeIn() above already uses,
+  // the same extractContents()-based pattern extractRangeInto() below uses,
   // so inline formatting (a caret mid-<strong>, say) splits cleanly instead of
-  // being torn.
+  // being torn, and sharing collectLeftovers()/dropEmptied() with it so the
+  // split does not leave an emptied mark behind — see inside.
   //
   // The caret lives inside the block's own `<div class="ed-li-text">` surface,
   // so the tail range runs to the END OF THAT DIV and the new block gets a
@@ -6370,10 +7938,21 @@
     // Containment is checked BEFORE deleteContents() so the refusal below is a
     // true no-op rather than "the selection was deleted, then we gave up".
     if (range.startContainer !== textEl && !textEl.contains(range.startContainer)) return null;
+    // Leftover marks, collected across this function's range operations before
+    // they run, and dropped once the tail extraction below has run.
+    // `textEl` — this item's own `.ed-li-text` — is the walk's terminator, not
+    // the document root: the surface itself must survive an Enter that empties
+    // it. Measured before this: Enter with the caret on the first character of
+    // the <em> in `- Alpha *ital* rest` left the upper item on disk as
+    // `- Alpha **`. Nothing was lost there, every character stayed in the right
+    // item — the damage was the stray delimiters, which escape to `\*\*` on the
+    // save after that.
+    const leftovers = collectLeftovers(range, textEl);
     if (!range.collapsed) range.deleteContents(); // collapses to the start point
     const tailRange = document.createRange();
     tailRange.setStart(range.startContainer, range.startOffset);
     tailRange.setEnd(textEl, textEl.childNodes.length);
+    collectLeftovers(tailRange, textEl, leftovers);
     const tailFrag = tailRange.extractContents();
 
     const newBlock = document.createElement('div');
@@ -6398,6 +7977,12 @@
     newText.appendChild(tailFrag);
     newBlock.appendChild(newText);
     blockEl.parentNode.insertBefore(newBlock, blockEl.nextSibling);
+    // After the delete and the tail extraction have run. Dropping between them
+    // would judge a mark before the extraction had emptied it — the pre-fix bug
+    // again. What does NOT matter is where this sits relative to the new item
+    // being built: measured in review, dropping before the tail is rehomed but
+    // after those Range operations gives byte-identical output.
+    dropEmptied(leftovers);
     return newBlock;
   }
 
@@ -6905,6 +8490,18 @@
     // last-item case, where the answer must be an EMPTY span (serializes to
     // '', which is what takes commitListStructure()'s range-removal path).
     const survivors = runEls.filter((el) => el !== li);
+    // Load-bearing, not incidental: `li` is the item the caret is IN, and
+    // removeListItem() detaches exactly that node — the one Chromium
+    // currently has focus on — from the DOM. Drop this suppression span and
+    // that detach's synchronous blur/focusout reaches resolveBurst() mid-
+    // mutation, with the run still in its PRE-removal shape (see
+    // `suppressLiFocusout`'s own comment above: "observed: '- <br>' written
+    // back for an item that had just been deleted"). That costs an extra
+    // resolveBurst({type:'li'}) committing a run nobody meant to commit, on
+    // top of the one commitListStructure() below already performs — one
+    // keystroke becomes two undo ops, and the second undo writes that stray
+    // '- <br>' to disk. Do not fold this into a "the node barely moved"
+    // cleanup.
     mutateListRun(() => removeListItem(li));
     // No `mutatedEl`: `li` is not IN `survivors`, and every block that is was
     // left exactly as the file has it.
@@ -6927,8 +8524,15 @@
   function handleLiKeydown(e, editEl) {
     if (e.key !== 'Enter' && e.key !== 'Tab') return false;
     e.preventDefault();
+    // T21 item 2, the li half — see handleBurstKeydown()'s Tab branch. Ahead
+    // of the run gates below because a walk needs no run: it is leaving.
+    if (e.key === 'Tab' && currentBurst && currentBurst.arrivedByTab) {
+      walkToAdjacentBlockByTab(currentBurst.blockEl, e.shiftKey ? -1 : 1);
+      return true;
+    }
     // Row 2: Shift+Enter is an in-block line break, not a structural change.
     if (e.key === 'Enter' && e.shiftKey) {
+      snapBurstIfActive(editEl, 'br-pre');
       insertBrAtCaret();
       snapBurstIfActive(editEl, 'br');
       return true;
@@ -6961,6 +8565,16 @@
       // which is a complete no-op — nothing mutated, nothing committed, file
       // byte-identical.
       const oldIndent = Number(li.getAttribute('data-indent')) || 0;
+      // INERT here: indentListItem()/outdentListItem() are attribute-only in
+      // this flat model (setBlockIndent() on `li` and its subtree — see the
+      // note on outdentListItem() further down this function) and never
+      // detach the focused node, so the synchronous blur/focusout this span
+      // exists to catch never fires, whether or not the flag is set.
+      // Measured: primed a burst on `li`, ran this mutation, and no
+      // focusout fired — `document.activeElement` stayed put and the node
+      // never left the document. Kept for uniformity with the load-bearing
+      // span in convertEmptyTopLevelLiToParagraph() above, not because this
+      // one guards anything measured.
       const changed = mutateListRun(() => {
         if (!(e.shiftKey ? outdentListItem(li) : indentListItem(li))) return false;
         // v3.0.1: `run` above is a PRE-mutation snapshot, captured while `li`
@@ -7023,6 +8637,9 @@
       // Row 3: one press = one outdent, with the SAME semantics as Shift+Tab
       // (adoption included). RULING F-Q: an item that OWNS a sublist takes this
       // path too — its subtree travels with it, so there is nothing to orphan.
+      // INERT here too, same measurement as the Tab span above:
+      // outdentListItem() is attribute-only and never detaches the focused
+      // node.
       const outdented = mutateListRun(() => {
         if (!outdentListItem(li)) return false;
         // The surface can still hold things the user reads as "nothing" but a
@@ -7033,10 +8650,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;
@@ -7062,6 +8703,10 @@
       return true;
     }
     // Row 1: split at the caret; the caret goes to the START of the new block.
+    // INERT here too, same measurement as the Tab span above:
+    // splitListItemAtCaret() keeps `li` itself in place (only `newLi` is a
+    // freshly-inserted sibling) and never touches the focused node's
+    // attachment.
     const newLi = mutateListRun(() => splitListItemAtCaret(li));
     if (!newLi) return true;
     run = listRunOf(newLi);
@@ -7111,6 +8756,7 @@
   // branch — so a burst-undo snapshot restore below reproduces a fully
   // re-armed table, not a plain static one).
   function startTableBurst(cellEl) {
+    dropDiscardedBurst();
     const tableEl = cellEl.closest('table');
     const blockEl = tableEl && tableEl.closest('.ed-block');
     if (!blockEl) return;
@@ -7124,6 +8770,7 @@
       depth: null, original: burstBaselineHtml(tableEl), history,
       activeCellEl: cellEl,
     };
+    watchBurstForDirtyDot(tableEl);
     selToolbarEditEl = cellEl;
     if (!selToolbarListener) {
       selToolbarListener = onSelectionChangeForToolbar;
@@ -7147,6 +8794,21 @@
     }
     const blockEl = tableEl.closest('.ed-block');
     const blockId = blockEl ? blockEl.getAttribute('data-block-id') : null;
+    // Captured HERE, while the pressed cell is still in the document (the
+    // delegated focusin listener that calls this passes its own `e.target`),
+    // for the stale recovery further down — see its comment for what each
+    // handle is for and what was measured about it. A commit resolved by the
+    // `await` below rebinds `blocks` to the new render's list
+    // (applyFullRender()'s own first lines), so a startLine belonging to the
+    // pre-commit list has to be read before it.
+    const pressedRowEl = cellEl.parentElement;
+    const pressedRow = pressedRowEl ? allRowsOf(tableEl).indexOf(pressedRowEl) : -1;
+    const pressedCol = pressedRowEl
+      ? Array.prototype.indexOf.call(pressedRowEl.cells, cellEl) : -1;
+    const blockNum = blockEl ? Number(blockEl.getAttribute('data-block-id')) : null;
+    const blockAtPress = blockNum != null ? blocks.find((b) => b.id === blockNum) : null;
+    const pressedStartLine = blockAtPress ? blockAtPress.startLine : null;
+    const pressedIdentity = tableIdentityOf(tableEl);
     if (switching) await switching;
     if (currentBurst && currentBurst.blockType === 'table' && currentBurst.blockEl &&
         currentBurst.blockEl.getAttribute('data-block-id') === blockId) {
@@ -7157,9 +8819,56 @@
     if (currentBurst) return; // a concurrent focusin (a DIFFERENT block) already won the race
     let liveCellEl = cellEl;
     if (!document.body.contains(cellEl)) {
-      const liveBlockEl = blockId != null ? document.querySelector('.ed-block[data-block-id="' + blockId + '"]') : null;
-      const liveTableEl = liveBlockEl ? blockContentEl(liveBlockEl) : null;
-      liveCellEl = liveTableEl ? tableCellsOf(liveTableEl)[0] : null;
+      // Reached when the pressed cell's node is gone from the document by the
+      // time this focusin resumes. Instrumented on the F8 fixture (a
+      // paragraph left dirty, then a press into the table): the mousedown's
+      // focusout resolves that paragraph, and applyRenderResult()'s patch
+      // gate consults domMatchesLastRender(), which reports false while
+      // `lastParts` is still null — as it is until a render has landed — so
+      // the render goes to applyFullRender(), whose `contentEl.innerHTML =`
+      // rewrites .content wholesale. A probe around the `await` above
+      // recorded route ["applyFullRender"] together with
+      // `document.body.contains(cellEl)` false, on each reproduction driven.
+      // Recovering the cell as `tableCellsOf(...)[0]` therefore dropped the
+      // caret into the header cell rather than the pressed one; driven to
+      // disk, a `QQ` typed straight after the press came back as
+      // `| QQA | B |`.
+      //
+      // What DOES come back after that rewrite, measured across the same
+      // commit: the pressed cell's (row, col) seat in its table. Naming the
+      // table again is the other half, and the handle this recovery already
+      // used was driven alongside the one ensureTableBurstOpen() re-resolves
+      // through — neither subsumes the other:
+      //   a raw edit adding a LINE ahead of the table, block count unchanged
+      //     -> data-block-id still names this table; startLine names the
+      //        paragraph that grew
+      //   a raw edit adding a BLOCK ahead of the table, line count unchanged
+      //     -> data-block-id names a renumbered neighbour; startLine still
+      //        names this table
+      // so the id is asked first and the startLine handle answers when it
+      // cannot, for the reason ensureTableBurstOpen()'s S1 comment writes
+      // down. Whichever one answers, tableIdentityOf() has to agree before a
+      // caret is placed: a commit that renumbers ids can leave the captured
+      // id pointing at a DIFFERENT table, and the same (row, col) seat
+      // inside THAT table is one the user never pressed — driven on a
+      // fixture holding a second table, dropping this check landed the caret
+      // in the neighbour's body cell. A commit that moves this table's start
+      // line AND renumbers its id leaves nothing for either handle to
+      // resolve; no caret is then placed, the conservative half of the trade
+      // ensureTableBurstOpen() already takes.
+      const liveTableFrom = (candidateBlockEl) => {
+        const t = candidateBlockEl ? blockContentEl(candidateBlockEl) : null;
+        if (!t || !t.classList || !t.classList.contains('ed-wys-table')) return null;
+        if (pressedIdentity == null || tableIdentityOf(t) !== pressedIdentity) return null;
+        return t;
+      };
+      const liveTableEl =
+        liveTableFrom(blockId != null
+          ? document.querySelector('.ed-block[data-block-id="' + blockId + '"]') : null) ||
+        liveTableFrom(pressedStartLine != null ? blockElAtLine(pressedStartLine) : null);
+      const liveRowEl = (liveTableEl && pressedRow >= 0)
+        ? allRowsOf(liveTableEl)[pressedRow] : null;
+      liveCellEl = (liveRowEl && pressedCol >= 0) ? liveRowEl.cells[pressedCol] : null;
       if (!liveCellEl || !liveCellEl.classList.contains('ed-wys-cell')) return;
       liveCellEl.focus();
       return;
@@ -7167,13 +8876,123 @@
     startTableBurst(liveCellEl);
   }
 
+  // Tab / Shift+Tab inside a table. Two things were measured on a table whose
+  // cells were A, B, c1 and c2, before this version, and both are fixed here:
+  //
+  //   * At either end of the cell list the target index was CLAMPED, so the
+  //     press resolved back to the cell it started from. The handler still ran
+  //     and its preventDefault() was readable in the bubble phase, so the
+  //     browser's own Tab traversal was consumed as well. Pressed in c2 it
+  //     left document.activeElement on that same TD, the block count and the
+  //     file's bytes unchanged, and the only visible effect was the caret
+  //     moving to the end of the cell it was already in. Shift+Tab in A was
+  //     the same dead key.
+  //   * The landing placed a COLLAPSED caret at the end of the target cell, so
+  //     typing straight after a Tab appended rather than replaced: Tab out of
+  //     A and then typing ZZ left B holding 'BZZ'.
+  //
+  // Now a step within the table SELECTS the target cell's contents, which is
+  // what makes "Tab, then type" a replacement the way a spreadsheet does, and
+  // a step off either end leaves the table — leaveTableByTab() below.
+  //
+  // Tab does not add a row past the last cell. That is the product's answer,
+  // not something missing here.
   function moveActiveTableCell(cellEl, delta) {
     const tableEl = cellEl.closest('table');
     const cells = tableCellsOf(tableEl);
-    const idx = cells.indexOf(cellEl);
-    const next = Math.max(0, Math.min(cells.length - 1, idx + delta));
-    const target = cells[next];
-    if (target) { target.focus(); placeCaretAtEnd(target); }
+    const next = cells.indexOf(cellEl) + delta;
+    if (next >= 0 && next < cells.length) {
+      const target = cells[next];
+      target.focus();
+      selectSurfaceContents(target);
+      // Keep the floating .ed-seltb down over exactly this selection — see
+      // `tabSelectedCellEl`'s own comment for what releases it again.
+      tabSelectedCellEl = target;
+      return;
+    }
+    leaveTableByTab(tableEl, delta);
+  }
+
+  // Tab off either end of a table: to the nearest block in that direction that
+  // focusableSurfaceOf() finds a surface in, degraded blocks stepped over.
+  //
+  // The burst is resolved FIRST, rather than focusing the destination and
+  // leaving the resulting focusout to do it. Focus leaving the table is itself
+  // what ends a table burst, and a burst carrying an edit ends by committing
+  // and re-rendering, which rewrites '.content' wholesale. Driven on a table
+  // left dirty when the press lands, watching focusin/focusout for that one
+  // press:
+  //
+  //   resolve first (this shape) — focusout on the cell, then a single
+  //     focusin, on the destination this function re-resolved. The element
+  //     captured before the resolution was gone from the document by then;
+  //     ablating the re-resolution and focusing THAT captured node instead
+  //     landed the caret on no editable surface — document.activeElement came
+  //     back carrying no class and the whole page as its text.
+  //   focus first — focusout on the cell, focusin on the destination,
+  //     focusout on it again as the render detaches it, focusin on its
+  //     replacement. The caret does arrive, by a longer road and through a
+  //     node that is being taken apart underneath it.
+  //
+  // Resolving first and re-resolving afterwards is also the shape
+  // ensureTableBurstOpen() above already uses against the same hazard.
+  //
+  // captureBlockIdentity() / reresolveBlockEl() is the handle, for the reason
+  // their own comment writes down: blockmap.js renumbers ids from zero on
+  // every render, so a captured id can name the destination's NEIGHBOUR after
+  // a commit that changed the block count, and the start line plus the block's
+  // own source lines is what proves the block sitting there afterwards is the
+  // one the press was aimed at. When it cannot be proven nothing is focused —
+  // the conservative half of the trade the gutter gestures already take.
+  //
+  // Nothing is focused when no such block exists either, and the caller's
+  // preventDefault() still stands over that press. Handing it back to the
+  // browser is not the alternative: buildGutterHandle() sets tabindex="-1" on
+  // the per-block chrome precisely because a browser-run Tab walks into it,
+  // and the document-level Tab branch near the bottom of this file already
+  // treats a Tab from inside an '.ed-block' as a deliberate silent no-op.
+  // T21 item 2 split this in two. The body below is the LANDING, and it is no
+  // longer only a table's exit: once a Tab has moved the caret across a block
+  // boundary, the next Tab has to be able to move it again, so the block it
+  // just landed on calls the same function. leaveTableByTab() underneath is
+  // the table's own name for it, kept because the whole comment above is
+  // written about that gesture.
+  //
+  // `arrivedByTab` is the landing's mark on the burst it just opened, and the
+  // burst object is the right place for it: bursts are per focus, so the mark
+  // cannot outlive the surface it describes, and clicking into some other
+  // block opens a burst without it. handleBurstKeydown()/handleLiKeydown()
+  // read it to decide that a further Tab means "move on" rather than "edit
+  // this" — see the measurement in handleBurstKeydown()'s Tab branch.
+  //
+  // The mark is set for whatever kind of burst the landing opened, and only
+  // the paragraph/heading/li Tab branches ever READ it: a table cell's Tab is
+  // owned by handleTableCellKeydown(), which already means "move on" (to the
+  // next cell, and off the end back through here). Scoping the WRITE to
+  // non-table destinations as well was tried and dropped — ablating that
+  // condition alone changed no measured behaviour (the row that Tabs out of
+  // one table, into the next, and then on to its second cell stayed green
+  // either way), so it was a condition no test could speak for.
+  async function walkToAdjacentBlockByTab(fromBlockEl, delta) {
+    const destBlockEl = adjacentFocusableBlock(fromBlockEl, delta);
+    if (!destBlockEl) return;
+    const identity = captureBlockIdentity(destBlockEl);
+    const ok = await switchAwayFrom();
+    if (!ok) return;
+    const liveBlockEl = document.body.contains(destBlockEl)
+      ? destBlockEl : reresolveBlockEl(identity);
+    const surface = focusableSurfaceOf(liveBlockEl);
+    if (!surface) return;
+    surface.focus();
+    // A caret at the start of the destination, not a selection of the whole
+    // of it: selecting a paragraph the user only tabbed past would put every
+    // word of it one keystroke from being replaced.
+    placeCaretAtSurfaceStart(surface);
+    if (currentBurst) currentBurst.arrivedByTab = true;
+  }
+
+  async function leaveTableByTab(tableEl, delta) {
+    await walkToAdjacentBlockByTab(tableEl ? tableEl.closest('.ed-block') : null, delta);
   }
 
   // Esc inside a table burst: revert to the pre-focus baseline and end the
@@ -7199,15 +9018,25 @@
     // as revertBurstAndEnd() above.
     const wasPristineForThisBlock = !!(pristineInsert && pristineInsert.blockId === burst.blockId);
     if (wasPristineForThisBlock) pristineInsert = null;
-    burst.history.dispose();
+    // T21 item 1: same split as revertBurstAndEnd() above — a pristine insert
+    // is about to lose its whole block, so nothing is stashed for it.
+    const cells = tableCellsOf(tableEl);
+    const cellIdx = cells.indexOf(burst.activeCellEl || cellEl);
+    if (wasPristineForThisBlock) burst.history.dispose();
     currentBurst = null;
     resetSelToolbarState();
     hideTableInsertBubbles();
     hideTableGrips();
     hideTableEdgeMenu();
     cancelTeDrag();
-    tableEl.innerHTML = burst.original;
-    if (wasPristineForThisBlock) await discardPristineInsert();
+    if (wasPristineForThisBlock) {
+      tableEl.innerHTML = burst.original;
+      await discardPristineInsert();
+      return;
+    }
+    stashDiscardedTableBurst(burst, tableEl, cellIdx, () => {
+      tableEl.innerHTML = burst.original;
+    });
   }
 
   // Ctrl+Z inside a table burst: symmetric to burstUndo() above, but a
@@ -7307,6 +9136,7 @@
     if (!currentBurst || currentBurst.blockType !== 'table' || currentBurst.editEl !== tableEl) return;
     if (e.key === 'Enter') {
       e.preventDefault();
+      snapBurstIfActive(tableEl, 'br-pre');
       insertBrAtCaret();
       snapBurstIfActive(tableEl, 'br');
       return;
@@ -7621,6 +9451,7 @@
     // click) — never the possibly-now-detached `tableEl` itself.
     const liveTableEl = await ensureTableBurstOpen(tableEl);
     if (!liveTableEl) return;
+    currentBurst.history.snap('insert-col-pre');
     insertColumn(liveTableEl, colIndex);
     armNewTableCells(liveTableEl);
     currentBurst.history.snap('insert-col');
@@ -7634,11 +9465,25 @@
     const afterRowIndex = Number(rowInsertBubble.dataset.afterRowIndex); // -1 -> header (first body row)
     if (!tableEl || Number.isNaN(afterRowIndex)) return;
     // Final-review Finding 6: same live-table swap as onColInsertBubbleClick()
-    // above — `afterRowIndex` is a plain integer so it stays valid across
-    // the swap unchanged, only the table element reference needs re-resolving.
+    // above — the table element reference has to be re-resolved.
+    //
+    // ⚠ RETRACTION. An earlier revision of this comment went on to say that
+    // `afterRowIndex`, being a plain integer, stays valid across that swap.
+    // Ruling T3-9 measured the opposite and parked the fix in v3.4.0: the
+    // index names a row of the table the bubble was positioned against, and
+    // after a handover it is read against a different element's row list, so
+    // `bodyRowsOf(liveTableEl)[afterRowIndex]` comes back `undefined`,
+    // `afterRow` is falsy, and insertRow() below takes its
+    // `tbody.insertBefore(newRow, tbody.firstChild)` branch — the same branch
+    // `afterRowIndex: -1` uses deliberately. The row lands at the TOP of the
+    // table rather than the gesture being dropped. Nothing here guards it yet.
+    // Task 14's hide-on-approach fix (see updateTableInsertBubbles() below)
+    // made this bubble reliably pressable, which widened the exposure of that
+    // deferred defect rather than narrowing it.
     const liveTableEl = await ensureTableBurstOpen(tableEl);
     if (!liveTableEl) return;
     const afterRow = afterRowIndex >= 0 ? bodyRowsOf(liveTableEl)[afterRowIndex] : null;
+    currentBurst.history.snap('insert-row-pre');
     insertRow(liveTableEl, afterRow);
     armNewTableCells(liveTableEl);
     currentBurst.history.snap('insert-row');
@@ -7658,7 +9503,52 @@
   // pointer (Event#target) at those coordinates.
   function updateTableInsertBubbles(x, y, target) {
     const blockEl = target && target.closest && target.closest('.ed-block[data-block-type="table"]');
-    const tableEl = blockEl ? blockContentEl(blockEl) : null;
+    // v3.3.0 F7: a raised bubble, and the row grip, are `position: fixed`
+    // overlays on document.body painted OVER the very band that raises the
+    // bubble — the bubble is centred on the boundary it offers and the row
+    // grip straddles the table's left border — so a pointer reaching for a
+    // bubble arrives on one of them and `target` stops being a table
+    // descendant. Resolving the table from `target` alone then hides the
+    // bubble the pointer is reaching for, the next mousemove finds a cell
+    // again and raises it, and the bubble flickers along the whole
+    // approach; whether it is up when the press lands comes down to where
+    // the last move happened to fall. MEASURED on this repo's puppeteer,
+    // walking the pointer horizontally across the row bubble's own band: the
+    // mousemove targets alternated between the bubble and whatever is
+    // painted under it, and the bubble went hidden on the alternating
+    // events where the bubble itself was the target. So fall back to the table
+    // this hover already resolved, and leave the proximity tests below to
+    // decide visibility from x/y exactly as they do for any other pointer
+    // position, rather than freezing whatever was last shown.
+    //
+    // The `.ed-block::before` corridor needs no entry here: it is a
+    // pseudo-element OF the block, so a hit inside it reports the block as
+    // `target` and the closest() above already matches (MEASURED at
+    // x = tableLeft - 10: `DIV.ed-block`). That is why nothing in this fix
+    // touches its `pointer-events`, which lib/md2doc.js documents as
+    // deliberately absent — being hit-testable is what that corridor is for.
+    // That "for" is this fix's hit-test above, not the corridor's ONLY job:
+    // the same rule also carries the block's own ⠿/＋ gutter :hover reveal
+    // (lib/md2doc.js's own comment on `.ed-block::before` — "deliberately
+    // NOT pointer-events: none: that would stop it being hit-tested, which
+    // is the entire mechanism"). This fix measured that the hit-test still
+    // resolves to the block for the bubble; it did not re-measure whether
+    // the gutter's hover reveal still behaves as before, so setting
+    // `pointer-events: none` here to simplify the table-bubble case remains
+    // untried, not merely undesirable.
+    //
+    // The COLUMN grip is deliberately absent from the list below: it is
+    // anchored on the header cell's CENTRE while the column bubble's band
+    // hugs that same cell's RIGHT edge. MEASURED on the fixture used to
+    // drive this fix, the column grip spanned x [639.3, 667.3] while the
+    // header cells' right edges sat at 894 and 1375.5 — the grip's rect
+    // never reaches either band, so a guard for it here is one no test on
+    // this fixture could hold down.
+    let tableEl = blockEl ? blockContentEl(blockEl) : null;
+    if (!tableEl && target && target.closest &&
+      target.closest('.ed-tb-insert, .ed-te-grip-row')) {
+      tableEl = hoveredInsertTableEl;
+    }
     if (!tableEl || !tableEl.classList.contains('ed-wys-table')) {
       hideTableInsertBubbles();
       hoveredInsertTableEl = null;
@@ -7753,8 +9643,11 @@
   // currently holds focus, so Chromium fires a synchronous focusout
   // mid-mutation — exactly the quirk tableBurstUndo()/tableBurstRedo()'s
   // innerHTML-snapshot restore has to guard. performRowDrop() therefore
-  // wraps it in `suppressTableFocusout` (the third of the flag's four sites)
-  // and puts focus back explicitly via restoreTableFocus(). An earlier
+  // wraps it in `suppressTableFocusout` — one of the sites that set that flag,
+  // alongside tableBurstUndo(), tableBurstRedo(), performColDrop() and
+  // restoreDiscardedBurst()'s table branch; test/editor-client.test.js pins
+  // the set and audits each one for its try/finally — and puts focus back
+  // explicitly via restoreTableFocus(). An earlier
   // revision moved the <tr> with a plain `insertBefore()`, which reparents
   // in one synchronous step, never blurs, and needed no guard — the header
   // promotion requirement is what retired that. The menu's delete ops (which
@@ -7763,9 +9656,17 @@
   //
   // Both the menu (delete/align) and the drag's DOM move are burst
   // mutations: ensureTableBurstOpen() (Task 5, above) auto-starts a burst
-  // on this table if none is open yet, then the op mutates the live DOM and
-  // calls currentBurst.history.snap() — committed on table-leave like any
-  // other table edit. Refusal banners reuse the exact wording the retired
+  // on this table if none is open yet, then the op snapshots the live DOM
+  // (`snap('<reason>-pre')`), mutates it, and snapshots again — committed on
+  // table-leave like any other table edit. The pre-snapshot is v3.3.0 地基 B;
+  // see snapBurstIfActive()'s comment for why a lone post-snapshot loses the
+  // text the user typed into a cell just before the structural edit. The
+  // structural ops it names (insert/delete row and column, cycle column align,
+  // drag row and column) call currentBurst.history.snap() DIRECTLY rather than
+  // through snapBurstIfActive(), which is why they were not in that function's
+  // call-site inventory — the guard snapBurstIfActive() applies is already
+  // supplied here by ensureTableBurstOpen()'s non-null return, which is
+  // itself conditioned on `currentBurst.editEl === liveTableEl`. Refusal banners reuse the exact wording the retired
   // Phase-2 click-select edit toolbar used for these same three guards (see
   // commit 0661cde, now dead code with zero call sites — this task is what
   // revives deleteRow()/deleteColumn()/cycleColumnAlign() unchanged, per
@@ -7789,6 +9690,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
@@ -7880,6 +9795,35 @@
     teEdgeMenu.hidden = false;
   }
 
+  // The column menu's vertical placement, shared by showColumnMenu() and by
+  // runCycleAlign()'s reposition so the two can never drift apart. Above the
+  // header cell by default, BELOW it when there is not enough room above —
+  // the same "no room above, go below" fallback positionSelToolbar() uses.
+  //
+  // The floor is `.ed-toolbar`'s height, not zero. That toolbar is
+  // `position: fixed` at the top of the viewport at z-index 101 and this menu
+  // is at 12, so a menu placed inside that band is painted UNDER it and stops
+  // being clickable while still reporting `hidden === false` and a perfectly
+  // ordinary rectangle. Measured at 800x600 on a document whose first block is
+  // the table: the menu's own top was 20.5px and
+  // `document.elementsFromPoint()` at the 對齊 button's own centre returned
+  // `DIV.ed-toolbar` first, with the button second — so the click landed on the
+  // toolbar and runCycleAlign() never ran.
+  //
+  // That band became reachable when the edit page stopped reserving 60px for
+  // the .sidebar-toggle it hides (lib/md2doc.js's `@media (max-width: 1080px)`
+  // .page-layout rule): the same first-block table's header top moved from
+  // ~104px to ~60px, which puts the menu under the toolbar while the grip that
+  // opens it is still comfortably clickable. Both numbers were measured on
+  // this branch, on either side of that change.
+  function placeTeMenuAboveCell(r) {
+    const topInset = parseFloat(getComputedStyle(document.documentElement)
+      .getPropertyValue('--ed-toolbar-h')) || 0;
+    let top = r.top - teEdgeMenu.offsetHeight - TE_MENU_GAP_PX;
+    if (top < topInset) top = r.bottom + TE_MENU_GAP_PX;
+    teEdgeMenu.style.top = top + 'px';
+  }
+
   function showColumnMenu(tableEl, colIndex) {
     if (teMenuKind === 'col' && teMenuTableEl === tableEl && teMenuColIndex === colIndex) {
       hideTableEdgeMenu(); // re-clicking the same column's edge toggles the menu closed
@@ -7896,7 +9840,15 @@
     const cell = headerRow ? headerRow.cells[colIndex] : null;
     const r = (cell || tableEl).getBoundingClientRect();
     positionTeMenu(r.left, r.top);
-    teEdgeMenu.style.top = (r.top - teEdgeMenu.offsetHeight - TE_MENU_GAP_PX) + 'px';
+    // Task 9 fix round 1 (Ruling T9-5) left this line unfloored, on a
+    // measurement that said the col grip stops being clickable before the
+    // header's top can get low enough to matter. That measurement is
+    // RETRACTED: it only ever asked whether the menu's top went NEGATIVE, and
+    // the menu is unreachable well before that — it goes under `.ed-toolbar`,
+    // which is 44px tall and paints over this menu. See
+    // placeTeMenuAboveCell() for what was measured instead, and for why the
+    // band is reachable by an ordinary mouse now.
+    placeTeMenuAboveCell(r);
   }
 
   function showRowMenu(tableEl, rowEl) {
@@ -7915,6 +9867,20 @@
     const tableRect = tableEl.getBoundingClientRect();
     positionTeMenu(tableRect.left, r.top);
     teEdgeMenu.style.left = (tableRect.left - teEdgeMenu.offsetWidth - TE_MENU_GAP_PX) + 'px';
+    // Task 9 fix round 1 (Ruling T9-5): same clamp shape as
+    // openConvertSubmenu()'s .ed-handle-submenu fix — measure the menu's
+    // own rendered bottom now that positionTeMenu() has placed and shown
+    // it, and shift `top` up by the bottom overflow when there is one.
+    // `.ed-te-menu` is `position: fixed` (lib/md2doc.js), so its own
+    // getBoundingClientRect() is already in viewport coordinates. Scoped to
+    // showRowMenu(): the row menu's `top` starts at the row's own top,
+    // which is the case the review measured overflowing at an ordinary
+    // window height. showColumnMenu() positions upward from the header
+    // instead and carries its own floor — placeTeMenuAboveCell().
+    const overflowBottom = teEdgeMenu.getBoundingClientRect().bottom - window.innerHeight;
+    if (overflowBottom > 0) {
+      teEdgeMenu.style.top = (r.top - overflowBottom) + 'px';
+    }
   }
 
   // Moves `currentBurst.activeCellEl` to a cell that will SURVIVE deleting
@@ -7970,6 +9936,7 @@
       showBanner('無法刪除最後一欄', null, null);
       return;
     }
+    currentBurst.history.snap('delete-col-pre');
     refocusAwayFromColumn(liveTableEl, colIndex);
     deleteColumn(liveTableEl, colIndex);
     currentBurst.history.snap('delete-col');
@@ -8001,6 +9968,7 @@
       showBanner('無法刪除最後一列', null, null);
       return;
     }
+    currentBurst.history.snap('delete-row-pre');
     refocusAwayFromRow(liveTableEl, liveRowEl);
     deleteRow(liveRowEl);
     currentBurst.history.snap('delete-row');
@@ -8012,14 +9980,85 @@
     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; }
+      currentBurst.history.snap('align-col-pre');
+      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);
+        placeTeMenuAboveCell(r);
+      }
+    });
   }
 
   // ── Notion-style row/column grip handles ─────────────────────────────
@@ -8350,6 +10389,16 @@
     // whatever was last shown untouched instead; hideTableGrips() (called
     // from table-leave, burst-end, and drag-start elsewhere) already covers
     // every path that actually needs to clear it.
+    //
+    // ⚠ KNOWN GAP, deferred by Ruling T14-5 to v3.4.0: the list below names the
+    // two grips and NOT '.ed-tb-insert', so the hover-insert ＋ bubble — which
+    // is the same kind of `position: fixed` overlay painted over the same band
+    // — falls through to the branches beneath and takes the ⠿ grips down while
+    // the pointer stands on it. The reason it was not closed here is that
+    // widening this test also widens the early return's setGutterKeep() call,
+    // whose behaviour on the ＋ bubble is unmeasured. A reader of this function
+    // should know it is knowingly incomplete rather than infer the list is the
+    // whole set.
     if (target && target.closest && (target.closest('.ed-te-grip-row') || target.closest('.ed-te-grip-col'))) {
       // v3.0.2: only the ROW grip is the one that covers the ⠿'s approach.
       // Testing the hit rather than reusing the branch condition matters —
@@ -8696,6 +10745,7 @@
     order.splice(toIndex > rowIndex ? toIndex - 1 : toIndex, 0, moved);
     if (order.every((row, i) => row === liveRows[i])) return; // 原地放回：不動 DOM、不 snap
 
+    currentBurst.history.snap('drag-row-pre');
     const aligns = columnAlignsOf(liveTableEl);
     const activeIndex = (currentBurst && currentBurst.activeCellEl)
       ? tableCellsOf(liveTableEl).indexOf(currentBurst.activeCellEl) : -1;
@@ -8753,6 +10803,7 @@
     // 看不出任何異常。寧可整個不動。
     const dropRows = allRowsOf(liveTableEl);
     if (!dropRows.length || dropRows.some((row) => !row.cells[fromIndex])) return;
+    currentBurst.history.snap('drag-col-pre');
     suppressTableFocusout = true;
     try {
       dropRows.forEach((row) => {
@@ -9840,6 +11891,60 @@
   // is active, so this always names whatever element the toolbar's mark
   // toggles should act on right now.
   let selToolbarEditEl = null;
+  // Task 15: the cell whose whole contents the Tab walk selected, or null.
+  // Tab now writes a full-cell selection on every press, and
+  // onSelectionChangeForToolbar() below asks only "is there a non-collapsed
+  // selection inside `selToolbarEditEl`" — which a Tab-made selection answers
+  // yes to, so the floating .ed-seltb rose over the cell on every press.
+  //
+  // Keyed on the CELL ELEMENT, never on a Range. A release condition phrased
+  // as "the selection went collapsed" would fire on its own during a
+  // re-render: measured across a commit that took the full-render route, a
+  // Range built over a cell before it neither threw nor reported itself
+  // broken afterwards, while the cell it was built from did — see the probe
+  // figures quoted with the release check in onSelectionChangeForToolbar().
+  //
+  // Released the moment the live selection stops being exactly this cell's
+  // contents, which is also what keeps a HAND-MADE selection out of the
+  // suppression: the boundary points written here are the cell element itself
+  // at offset zero and at its child count, while a selection the user builds
+  // is anchored in the text. Driven on a cell holding 'c2', a drag across it,
+  // a double click, a triple click and Ctrl+A each read back a startContainer
+  // of '#text', so none of them matches.
+  //
+  // What this cannot reach, and does not cause: a press that begins INSIDE the
+  // standing selection is Chromium's own drag-the-selected-text gesture.
+  // Driven straight after a Tab, it dispatched dragstart and dragend and not
+  // one selectionchange, so no release condition of any shape gets a hearing —
+  // the same with this suppression removed. Anything that collapses the
+  // selection first (a click, an arrow key) puts an ordinary drag back, and
+  // that drag releases here. Meanwhile the FIXED toolbar's inline buttons stay
+  // enabled throughout: hasFormattableSelection() answers for those and knows
+  // nothing about this flag, measured with B live over a suppressed selection.
+  let tabSelectedCellEl = null;
+  // Task 16: set when positionSelToolbar() below takes .ed-seltb down over a
+  // selection that left the viewport while staying alive, and cleared when
+  // the bar goes back up. Its lifetime has to reach OUTSIDE the
+  // `selToolbar.parentNode` gate in onAnyScroll(), because that gate is what
+  // the removal turns against the bar: with the node detached the gate
+  // returns before anything can re-ask.
+  //
+  // Measured on a paragraph selection in a document of filler paragraphs,
+  // before this flag existed — scrolled to +150 the bar followed, its top
+  // moving 192 -> 42; at +1500 it was gone from the DOM; scrolled back to the
+  // top it stayed gone while the selection still read non-collapsed with its
+  // rect back at top 234. A synthetic selectionchange dispatched at that
+  // point put the bar back at top 192, which is what says the missing state
+  // was the permission to re-ask rather than a live selection.
+  //
+  // Opposite polarity to tabSelectedCellEl above: that flag holds the bar
+  // DOWN, this one lets it back UP. Keyed on neither a cell nor a Range — the
+  // defect reproduces on a paragraph, where there is no cell to key on, and
+  // the re-ask reads the selection back off the document when it fires. It
+  // says nothing about WHY the bar is down right now: measured after a Tab
+  // walk moved on from a scrolled-away selection, it read true while Task
+  // 15's suppression was what held the bar down.
+  let selToolbarOffViewport = false;
   // The currently-attached onSelectionChangeForToolbar function reference (or
   // null) — kept at this module scope, NOT just inside openWysiwygEditor()'s
   // closure, specifically so a call site OUTSIDE that closure (rerenderAll()
@@ -9860,6 +11965,13 @@
     }
     hideSelToolbar();
     selToolbarEditEl = null;
+    // Task 15: the Tab suppression is part of the same "a session is open"
+    // state, so it goes down with the rest of it.
+    tabSelectedCellEl = null;
+    // Task 16: same reasoning — "the bar is down because it scrolled out of
+    // view" is a statement about an open session's selection, and there is no
+    // session left to make it about.
+    selToolbarOffViewport = false;
   }
 
   // Shows/repositions/hides the floating selection toolbar as the selection
@@ -9901,6 +12013,37 @@
         hideSelToolbar();
         return;
       }
+      // Task 15 (T15-5): a selection the Tab walk wrote keeps this bar down.
+      // Asked here, below the collapsed exit above, on purpose — focusing a
+      // cell parks a collapsed selection in it a moment before the walk writes
+      // the real one, and releasing on that would let the bar up again on the
+      // very press this is suppressing.
+      //
+      // The BOUNDARY comparison is the working half: it says whether this is
+      // still the Tab's own selection or one the user has since built by hand,
+      // and each of its four terms was ablated on its own against a selection
+      // differing in that term alone — every one of them left its own input
+      // wrongly suppressed, and no other.
+      //
+      // The isConnected term is belt and braces, and honestly so: ablating it
+      // changed no measured behaviour, because a detached cell fails the
+      // boundary comparison as well. It is asked anyway because the cell
+      // element is the only handle that can be asked at all — driven across a
+      // commit that took the full-render route, a Range built over a cell
+      // beforehand reported startContainer.isConnected true and covered the
+      // empty string afterwards, while that same cell reported isConnected
+      // false. A Range collapses in silence, so a release keyed on one would
+      // fire during a re-render of its own accord.
+      if (tabSelectedCellEl) {
+        if (tabSelectedCellEl.isConnected &&
+            range.startContainer === tabSelectedCellEl && range.startOffset === 0 &&
+            range.endContainer === tabSelectedCellEl &&
+            range.endOffset === tabSelectedCellEl.childNodes.length) {
+          hideSelToolbar();
+          return;
+        }
+        tabSelectedCellEl = null;
+      }
       positionSelToolbar(range);
     } finally {
       // In a `finally` so every early return above still refreshes the bar —
@@ -9950,18 +12093,84 @@
     return r;
   }
 
+  // Extracts the range's contents into `el`, puts `el` where the range was,
+  // and drops the marks the extraction emptied — the fused form of
+  // collectLeftovers() + dropEmptied() above, which is all an extractContents()
+  // call site needs. applyMarkToggle()'s wrap branch reaches it through
+  // wrapRangeIn() below; applyLinkToggleBody()'s new-link path calls it
+  // directly. A native Ctrl+B does not arrive here at all: client.js binds no
+  // Ctrl/Cmd + b/i/u, so that keystroke reaches the contenteditable as the
+  // browser's own execCommand and produces a <b>. The journey suite drives
+  // that keystroke and the toolbar button side by side, each with its own tag
+  // pattern, for exactly that reason.
+  function extractRangeInto(range, el, root) {
+    const leftovers = collectLeftovers(range, root);
+    el.appendChild(range.extractContents());
+    range.insertNode(el);
+    dropEmptied(leftovers);
+    return el;
+  }
+
   // Wraps the range's contents in a brand-new `<tag>` element via Range
   // surgery (extractContents/insertNode — plain DOM Range methods, NOT
   // execCommand). Returns a Range spanning the new element's contents.
-  function wrapRangeIn(range, tag) {
-    const el = document.createElement(tag.toLowerCase());
-    el.appendChild(range.extractContents());
-    range.insertNode(el);
+  function wrapRangeIn(range, tag, root) {
+    const el = extractRangeInto(range, document.createElement(tag.toLowerCase()), root);
     const r = document.createRange();
     r.selectNodeContents(el);
     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
@@ -10010,12 +12219,14 @@
 
     const whole = wholeSelectionMark(range, tag, root);
     if (whole) {
+      snapBurstIfActive(root, 'mark-pre');
       reselectAndReposition(unwrapElement(whole));
       snapBurstIfActive(root, 'mark');
       return;
     }
     const overlapping = overlappingMarks(range, tag, root);
     if (overlapping.length > 0) {
+      snapBurstIfActive(root, 'mark-pre');
       const extended = extendRangeOverMarks(range, overlapping);
       // Re-query against the EXTENDED range: `overlapping` above was
       // computed from the original (smaller) range, and every mark the
@@ -10025,26 +12236,192 @@
       snapBurstIfActive(root, 'mark');
       return;
     }
-    reselectAndReposition(wrapRangeIn(range, tag));
+    if (!trimRangeToText(range)) return;   // 全空白／collapsed 選取：no-op
+    snapBurstIfActive(root, 'mark-pre');
+    reselectAndReposition(wrapRangeIn(range, tag, root));
     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
+      snapBurstIfActive(root, 'mark-pre');
       if (url.trim() === '') {
         reselectAndReposition(unwrapElement(whole));
       } else {
@@ -10052,37 +12429,45 @@
         reselectAndReposition(range);
       }
       snapBurstIfActive(root, 'mark');
-      return;
+      return true;
     }
     const overlapping = overlappingMarks(range, 'A', root);
     if (overlapping.length > 0) {
+      snapBurstIfActive(root, 'mark-pre');
       const extended = extendRangeOverMarks(range, overlapping);
       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
+    snapBurstIfActive(root, 'mark-pre');
     const el = document.createElement('a');
     el.setAttribute('href', url.trim());
-    el.appendChild(range.extractContents());
-    range.insertNode(el);
+    extractRangeInto(range, el, root);
     const r = document.createRange();
     r.selectNodeContents(el);
     reselectAndReposition(r);
     snapBurstIfActive(root, 'mark');
+    return true;
   }
 
+  // The .ed-seltb buttons, paired with the mark each one toggles, for
+  // paintSelToolbarMarks() below. Filled by buildSelToolbar(), which runs once.
+  const selToolbarMarkBtns = [];
+
   function buildSelToolbar() {
     const el = document.createElement('div');
     el.className = 'ed-seltb';
-    function addBtn(cls, label, ariaLabel, onClick) {
+    function addBtn(cls, label, ariaLabel, tag, onClick) {
       const b = document.createElement('button');
       b.type = 'button';
       b.className = 'ed-seltb-btn ' + cls;
       b.textContent = label;
       b.setAttribute('aria-label', ariaLabel);
+      b.setAttribute('aria-pressed', 'false');
+      selToolbarMarkBtns.push({ btn: b, tag: tag });
       // Keep the DOM selection intact across the click: without this, the
       // button (outside the contenteditable root) stealing focus on
       // mousedown would collapse the selection before the click handler
@@ -10092,15 +12477,53 @@
       el.appendChild(b);
       return b;
     }
-    addBtn('ed-seltb-b', 'B', 'Bold', () => applyMarkToggle('STRONG'));
-    addBtn('ed-seltb-i', 'I', 'Italic', () => applyMarkToggle('EM'));
-    addBtn('ed-seltb-s', 'S', '刪除線', () => applyMarkToggle('DEL'));
-    addBtn('ed-seltb-u', 'U', '底線', () => applyMarkToggle('U'));
-    addBtn('ed-seltb-code', '<>', 'Code', () => applyMarkToggle('CODE'));
-    addBtn('ed-seltb-link', '\u{1F517}', 'Link', () => applyLinkToggle());
+    addBtn('ed-seltb-b', 'B', 'Bold', 'STRONG', () => applyMarkToggle('STRONG'));
+    addBtn('ed-seltb-i', 'I', 'Italic', 'EM', () => applyMarkToggle('EM'));
+    addBtn('ed-seltb-s', 'S', '刪除線', 'DEL', () => applyMarkToggle('DEL'));
+    addBtn('ed-seltb-u', 'U', '底線', 'U', () => applyMarkToggle('U'));
+    addBtn('ed-seltb-code', '<>', 'Code', 'CODE', () => applyMarkToggle('CODE'));
+    addBtn('ed-seltb-link', '\u{1F517}', 'Link', 'A', () => applyLinkToggle());
     return el;
   }
 
+  // v3.3.0 (F2): the floating bar's own four-state painting, from the same
+  // `ctx.marks` the fixed toolbar's five are derived from.
+  //
+  // ⚠ `aria-disabled`, never the `disabled` property. Each of these buttons
+  // keeps the selection alive across its own click through the `mousedown`
+  // preventDefault() addBtn() installs above, and a disabled <button>
+  // dispatches no mousedown at all, so that preventDefault would never run.
+  //
+  // MEASURED, real mouse press (move / down / 80ms / up) on the B button over
+  // an inert selection, with a capture-phase counter on `document` and a click
+  // counter on the button itself. As it ships:
+  //   {"active":"P.ed-wys-armed","sel":" ","seltb":true,"downs":1,"clicks":1}
+  // and the block's innerHTML byte-identical before and after. The same press
+  // with `disabled` set on that button instead:
+  //   {"active":"BODY.","sel":" ","seltb":false,"downs":0,"clicks":0}
+  // — no mousedown reaches the document at all, the focus lands on BODY and
+  // the bar is gone by the time the press ends. buildToolbar() can afford
+  // `disabled` on the fixed bar because it installs a capture-phase
+  // `pointerdown` guard on that bar's container; there is no such
+  // container-level interception here.
+  //
+  // So the press on an inert button still runs applyMarkToggle(), which is
+  // fine: the same measurement shows the block unchanged. Nothing here needs
+  // to intercept it.
+  let selToolbarMarkSig = null;
+  function paintSelToolbarMarks(marks) {
+    const sig = JSON.stringify(marks);
+    if (sig === selToolbarMarkSig) return;
+    selToolbarMarkSig = sig;
+    selToolbarMarkBtns.forEach((entry) => {
+      const m = marks ? marks[entry.tag] : null;
+      entry.btn.setAttribute('aria-pressed',
+        m === 'whole' ? 'true' : (m === 'partial' ? 'mixed' : 'false'));
+      if (m === 'inert') entry.btn.setAttribute('aria-disabled', 'true');
+      else entry.btn.removeAttribute('aria-disabled');
+    });
+  }
+
   const selToolbar = buildSelToolbar();
 
   function hideSelToolbar() {
@@ -10114,8 +12537,23 @@
   // `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) {
+      // Task 16: of the exits that take this bar down, this is the one that
+      // leaves a live selection behind, so it is the one that arms the
+      // re-ask on scroll. Walked by grepping hideSelToolbar(), its other
+      // callers are reached by a session ending, by the selection collapsing
+      // or leaving the edit root, by Task 15's Tab suppression, or by a mark
+      // toggle with no range to reselect.
+      selToolbarOffViewport = true;
+      hideSelToolbar(); return;
+    }
     if (!selToolbar.parentNode) document.body.appendChild(selToolbar);
+    selToolbarOffViewport = false;
     const gap = 8, margin = 4;
     const tbRect = selToolbar.getBoundingClientRect();
     let top = rect.top - tbRect.height - gap;
@@ -10157,9 +12595,13 @@
     // handler's async switchAwayFrom()->resolveBurst()->rerenderAll()
     // commit chain BEFORE the click event that opens the menu ever fires.
     // At human click speed (a real, non-zero gap between mousedown and
-    // mouseup) that commit's /api/render round trip can finish and swap
-    // `.content` — detaching THIS very button — before mouseup, and a
-    // click event never fires at all for a target removed from the
+    // mouseup) that commit's /api/render round trip can finish and REPLACE
+    // THE BLOCK ELEMENT inside `.content` — detaching THIS very button,
+    // which lives in that block — before mouseup. (`.content` itself is
+    // NOT swapped: applyFullRender() assigns `contentEl.innerHTML`, which
+    // rebuilds its children but keeps the element, and the patch route
+    // removes just the one block; both were traced, see the v3.3.0 note
+    // below.) A click event never fires at all for a target removed from the
     // document between mousedown and mouseup: the first click is silently
     // eaten (no menu opens), and only a second click on the fresh,
     // re-armed handle actually works. preventDefault() here stops the
@@ -10168,9 +12610,53 @@
     // §10-gap fix: same reasoning as the ⠿ handle above, for the ＋ insert
     // button — a mousedown-triggered blur on a dirty burst elsewhere would
     // otherwise race this button's own click the exact same way.
+    // v3.3.0 階段 0: the two MENU-ITEM classes join the list. `.ed-handle` /
+    // `.ed-insert` are the buttons that OPEN the menus;
+    // `.ed-handle-menu-btn` / `.ed-insert-menu-btn` are the items INSIDE them
+    // (buildGutterMenu()/buildInsertMenu() give every item one of those two
+    // classes), and neither menu's items carry a mousedown preventDefault()
+    // of their own. The ⠿/＋ gutter builds exactly four kinds of pressable
+    // BUTTON — the handle, the ＋ button, a gutter-menu item (the 轉換成
+    // submenu's buttons share that class) and an insert-menu item — and
+    // before this line only the first two were covered. The menu PANEL
+    // itself (`div.ed-handle-menu`, which has padding) is deliberately not
+    // in that list: a press landing in the gap between two items still
+    // steals focus, and is out of scope here.
+    //
+    // Trace taken with ONLY `.ed-handle`/`.ed-insert` in this list, dirty
+    // burst on the block, an 80 ms press on 建立副本, listeners on mousedown /
+    // focusout / fetch / mouseup / click plus a MutationObserver naming the
+    // removed node (unprimed fallback route | primed patch route):
+    //
+    //   +7ms  | +5ms  mousedown on .ed-handle-menu-btn, defaultPrevented=false
+    //   +7ms  | +5ms  focusout on the burst's .ed-wys-armed, activeElement→BODY
+    //   +8ms  | +6ms  POST /api/render   (the focusout handler's commit)
+    //   +28ms | +12ms response applied — the removed node is the BLOCK ELEMENT,
+    //                 removed from `.content` (which keeps its own identity)
+    //                 and replaced by a different node with the same
+    //                 data-block-id; the fallback rebuilds all of `.content`'s
+    //                 children, the patch route removes just this one. The menu
+    //                 — parked by toggleGutterMenu()/toggleInsertMenu() with
+    //                 blockEl.appendChild() — is removed WITH the block.
+    //   +93ms | +91ms mouseup, target now the replacement block's surface, and
+    //                 NO click event at all: the pressed node left the document
+    //                 between mousedown and mouseup.
+    //
+    // Same trace with these two selectors added: no focusout and no
+    // /api/render before mouseup — the item keeps its click, and the commit
+    // runs afterwards from inside the item's own handler.
     document.addEventListener('mousedown', (e) => {
+      // T21 item 2: pointing at something is the other way (besides pressing a
+      // key that is not Tab — see handleBurstKeydown()) of saying the walk is
+      // over. A click that lands on the SAME surface the walk arrived at does
+      // not open a new burst, so without this the mark would survive a
+      // deliberate caret placement and the next Tab would leave instead of
+      // indenting the item the user had just aimed at.
+      if (currentBurst) currentBurst.arrivedByTab = false;
       if (e.target && e.target.closest &&
-          (e.target.closest('.ed-handle') || e.target.closest('.ed-insert'))) e.preventDefault();
+          (e.target.closest('.ed-handle') || e.target.closest('.ed-insert') ||
+           e.target.closest('.ed-handle-menu-btn') ||
+           e.target.closest('.ed-insert-menu-btn'))) e.preventDefault();
     });
     document.addEventListener('click', async (e) => {
       // S3 Task 4: the trailing click of a gesture that already answered this
@@ -10379,6 +12865,12 @@
 
   // ── undo / redo ───────────────────────────────────────────────────────
   async function undo() {
+    // T21 item 1: an Escape that discarded a burst leaves exactly one thing
+    // for the next Ctrl+Z to undo, and it is not on this stack — the burst
+    // never committed, so `lines` never saw it. restoreDiscardedBurst()
+    // answers false whenever there is no such thing (which is almost always),
+    // and the ordinary document undo below runs untouched.
+    if (restoreDiscardedBurst()) return;
     // Resolve any open editor BEFORE the .content-replacing swap below —
     // see the `activeEditor` / switchAwayFrom() comments near its
     // declaration for why this is required (undo/redo silently detaching an
@@ -10471,7 +12963,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;
@@ -10494,8 +12987,19 @@
   // The buttons whose model state can ever report `active: true` — i.e. the
   // real toggles, and the only ones that may carry aria-pressed. Every other
   // button is a command, not a toggle.
-  // v3.2.0: derived, not mirrored. A seventh toggle added to toolbar-model.js
-  // used to need a matching edit here, and forgetting it made aria-pressed lie.
+  // v3.2.0: derived, not mirrored. Adding a toggle to toolbar-model.js used to
+  // need a matching edit here, and forgetting it made aria-pressed lie.
+  //
+  // v3.3.0 (F2), recorded rather than changed: `check` is outside this set on
+  // purpose. It is `toggle: false` while its conversion-group siblings quote /
+  // code / list / ordered-list are `toggle: true`, which is honest only for as
+  // long as deriveState() never sets `check.active` — and it does not: that
+  // function assigns nothing to `state.check` beyond the disabled flags every
+  // button gets. What would change that is a rule lighting ☑ when the current
+  // block is already a task item. The flag would have to flip in the same
+  // edit, because this set is what decides whether aria-pressed is written at
+  // all, and a button that can report `active` while sitting outside it says
+  // nothing where it should say `true`.
   const TOOLBAR_TOGGLE_IDS = new Set(
     (toolbarModel ? toolbarModel.BUTTONS : []).filter((b) => b.toggle).map((b) => b.id));
 
@@ -10515,10 +13019,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();
   }
 
@@ -10544,6 +13067,67 @@
       selToolbarEditEl.contains(range.endContainer);
   }
 
+  // The mark elements the toolbars toggle. 'U' is here because .ed-seltb has a
+  // U button (buildSelToolbar(), earlier in this file); toolbar-model.js's
+  // MARK_TAG_BY_ID covers the fixed toolbar's inline group and does not
+  // mention it.
+  const MARK_TAGS = ['STRONG', 'EM', 'DEL', 'CODE', 'A', 'U'];
+
+  // v3.3.0 (F2): which of those marks the current selection is in, as the
+  // four-state vocabulary both toolbars paint from — or null when there is no
+  // formattable selection at all. The three non-null states below name the
+  // branch applyMarkToggle() would take on that tag, in its own order:
+  //
+  //   'whole'   `wholeSelectionMark()` hit — the unwrap branch.
+  //   'partial' `overlappingMarks()` non-empty — the extend-and-unwrap branch.
+  //   'none'    neither — the wrap branch, which would wrap something.
+  //   'inert'   neither, and the wrap branch would refuse.
+  //
+  // Two things about 'inert' are load-bearing and neither is guessable from
+  // the button:
+  //
+  //  * It is asked per tag, not once. Only applyMarkToggle()'s THIRD branch is
+  //    guarded by trimRangeToText(); the first two run to completion on an
+  //    all-whitespace selection. MEASURED: with the single space inside
+  //    `**bold text**` selected, pressing B took the unwrap branch — the
+  //    <strong> was gone, the paragraph's text was unchanged, and the file
+  //    saved back with no `**` in it. So drawing every button inert there
+  //    would grey out a button that acts.
+  //  * 'A' never reaches it. The link button does not go through
+  //    applyMarkToggle() at all — applyLinkToggleBody() above has the same
+  //    first two branches but its third calls window.prompt() and
+  //    extractRangeInto() with no trim guard anywhere, so an all-whitespace
+  //    selection prompts and wraps. MEASURED: selecting the single space in
+  //    `Alpha bold text …` and pressing 🔗 raised the dialog 「連結網址：」 and
+  //    left `Alpha<a href="https://probe/"> </a>bold text …` in the block. So
+  //    drawing 🔗 inert there would grey out a button that acts.
+  //
+  // trimRangeToText() is tag-independent, so it is asked once. It is asked
+  // with a CLONE: it calls setStart/setEnd on the range it is handed whenever
+  // it returns true, and this function runs on every selectionchange, so the
+  // live range would have the user's own selection edges pulled in off every
+  // caret move that the open burst's selectionchange listener hears. `wholeSelectionMark()` and `overlappingMarks()` take the live
+  // range. test/editor-journey.test.js drives a keyboard selection across a
+  // marked run and asserts, at each step, that the range's boundary points are
+  // byte-identical either side of the selectionchange dispatch and that the
+  // string it covers has grown by one character. Ablated to check the suite can
+  // see it: putting a setStart() into wholeSelectionMark(), and again into
+  // overlappingMarks(), each turned the suite red.
+  function selectionMarkStates(sel) {
+    if (!hasFormattableSelection(sel)) return null;
+    const root = selToolbarEditEl;
+    const range = sel.getRangeAt(0);
+    const wrappable = trimRangeToText(range.cloneRange());
+    const out = {};
+    for (const tag of MARK_TAGS) {
+      if (wholeSelectionMark(range, tag, root)) out[tag] = 'whole';
+      else if (overlappingMarks(range, tag, root).length > 0) out[tag] = 'partial';
+      else if (wrappable || tag === 'A') out[tag] = 'none';
+      else out[tag] = 'inert';
+    }
+    return out;
+  }
+
   // ctx for toolbarModel.deriveState(). Every field is read off the DOM /
   // `lines` at call time; nothing is cached, so a stale value cannot outlive
   // a render.
@@ -10566,13 +13150,25 @@
       // hasFormattableSelection() (just above) is their refusal test spelled
       // once, rather than a looser "is anything selected anywhere on the page".
       hasSelection: hasFormattableSelection(sel),
+      // The identity behind that boolean: selectionMarkStates() (just above)
+      // measures it here because toolbar-model.js may not touch the DOM, and
+      // .ed-seltb is painted from the same measurement — see updateToolbar().
+      marks: selectionMarkStates(sel),
       mode: docMode,
     };
   }
 
   function updateToolbar() {
     if (!toolbarEl || !toolbarBtns || !toolbarModel) return;
-    const state = toolbarModel.deriveState(toolbarContext());
+    const ctx = toolbarContext();
+    // Both bars, one measurement. paintSelToolbarMarks() runs BEFORE the `sig`
+    // early-return below, because that signature is built from the toolbar's
+    // own buttons and .ed-seltb has one — U — that none of them speaks for:
+    // moving the selection between plain text and a <u> run changes nothing in
+    // `state`, so the early return would fire and U would keep whatever it last
+    // said. Pinned by a journey row that drives exactly that move.
+    paintSelToolbarMarks(ctx.marks);
+    const state = toolbarModel.deriveState(ctx);
     // selectionchange fires on every caret move, so the state is diffed
     // before any DOM is written — 22 attribute writes per keystroke is a
     // cost with no matching benefit.
@@ -10589,12 +13185,206 @@
       // and `table` as toggle buttons stuck in the "not pressed" state,
       // which is a lie about what they do.
       if (TOOLBAR_TOGGLE_IDS.has(id)) {
-        btn.setAttribute('aria-pressed', st.active ? 'true' : 'false');
+        // v3.3.0 (F2): three values, not two. `mixed` is what the five inline
+        // buttons report over a selection that overlaps marks of their tag
+        // without lying inside one — pressing them there removes the marks
+        // rather than adding any, and 'true'/'false' can say neither.
+        btn.setAttribute('aria-pressed',
+          st.mixed ? 'mixed' : (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);
+      }
+    });
+    // Label edits above change the row's width (H becomes H1, 編輯 becomes
+    // 原始碼), which moves the scroll maximum, so repaint the edge hint here
+    // too. Placed inside the diffed branch on purpose: an unchanged sig means
+    // no attribute was written, therefore no width moved.
+    paintToolbarOverflow();
+    // The write above can disable the button the keyboard cursor is sitting
+    // on. A real focus would have been thrown back to BODY by the browser at
+    // this point, and Tab from BODY goes nowhere — driven on this build, a
+    // dozen consecutive Tabs starting from BODY left activeElement on BODY
+    // every time — so the keyboard would be stuck there. A virtual cursor has
+    // nothing to lose: it steps to the next enabled button instead.
+    const cursorBtn = toolbarRovingBtns()[toolbarRovingIndex];
+    if (cursorBtn && cursorBtn.disabled) moveToolbarCursor(1);
+  }
+
+  // F12: which end of the bar still has buttons behind it. The stylesheet
+  // turns each token into an edge gradient; nothing here decides how it looks.
+  //
+  // The one-pixel margin is a deliberate cushion and NOT a measured
+  // requirement — say so rather than inventing a reason for it. Driven at 900
+  // and at 420 px wide, the largest scrollLeft the bar accepts came back equal
+  // to scrollWidth minus clientWidth to the pixel (75 and 555), so a strict
+  // comparison would have been correct at both. The cushion is there because
+  // scrollWidth is reported as a whole number over a row whose own width is
+  // not, and what it costs when the two agree is that the gradient goes out a
+  // pixel before the travel ends.
+  function paintToolbarOverflow() {
+    if (!toolbarEl) return;
+    const max = toolbarEl.scrollWidth - toolbarEl.clientWidth;
+    const sl = toolbarEl.scrollLeft;
+    const tokens = [];
+    if (sl > 1) tokens.push('left');
+    if (sl < max - 1) tokens.push('right');
+    const v = tokens.join(' ');
+    if (toolbarEl.getAttribute('data-ed-tb-overflow') !== v) {
+      toolbarEl.setAttribute('data-ed-tb-overflow', v);
+    }
+  }
+
+  // ── F12, keyboard entry to the toolbar ────────────────────────────────
+  //
+  // The cursor here is VIRTUAL: no toolbar button ever takes DOM focus, and
+  // the caret stays exactly where the user left it. That is not a stylistic
+  // choice, it is what makes the rest of this safe. buildToolbar()'s own
+  // ⚠ LOAD-BEARING note records why: a toolbar <button> taking focus fires
+  // the armed surface's focusout, which commits and re-renders, and the
+  // selection the pressed button was about to act on is gone before its click
+  // handler runs. The mousedown preventDefault() there stops that happening
+  // by mouse; keeping DOM focus still means it cannot happen by keyboard
+  // either, and no focusout exemption has to be invented for the way back
+  // out.
+  //
+  // toolbarRovingIndex is an index into the bar's buttons in DOM order, or
+  // -1 while the mode is off.
+  let toolbarRovingIndex = -1;
+
+  function toolbarRovingBtns() {
+    return toolbarEl ? Array.prototype.slice.call(
+      toolbarEl.querySelectorAll('.ed-toolbar-btn')) : [];
+  }
+
+  function paintToolbarRoving() {
+    const btns = toolbarRovingBtns();
+    btns.forEach((b, i) => {
+      if (i === toolbarRovingIndex) b.setAttribute('data-ed-tb-cursor', '');
+      else b.removeAttribute('data-ed-tb-cursor');
     });
+    if (!toolbarEl) return;
+    if (toolbarRovingIndex < 0 || !btns[toolbarRovingIndex]) {
+      toolbarEl.removeAttribute('data-ed-tb-keynav');
+    } else {
+      toolbarEl.setAttribute('data-ed-tb-keynav',
+        btns[toolbarRovingIndex].getAttribute('data-ed-tb'));
+    }
+  }
+
+  // Scroll the cursor into the strip the buttons rest in, which is narrower
+  // than the bar: the mode slot occupies the right-hand end of it. The right
+  // boundary is read off the slot's own rect rather than repeating the
+  // padding-right the stylesheet reserves, so the two cannot drift apart.
+  // The arithmetic is spelled out rather than delegated to scrollIntoView(),
+  // whose contract is written against the whole chain of scrollable ancestors
+  // while the only box that should move here is this one.
+  function revealToolbarCursor(btn) {
+    if (!toolbarEl) return;
+    const bar = toolbarEl.getBoundingClientRect();
+    const slotEl = toolbarEl.querySelector('.ed-toolbar-status');
+    const right = slotEl
+      ? Math.min(bar.right, slotEl.getBoundingClientRect().left) : bar.right;
+    // Rounded AWAY from the edge being cleared, not by the nearest whole
+    // number. These boxes have fractional widths while scrollLeft is stored
+    // whole, so asking for a flush landing can round the button back under the
+    // edge it was supposed to clear: driven with plain subtraction, walking
+    // leftwards along the row at a 420px viewport parked stops at a left edge
+    // of -0.39, -0.19 and -0.09, and flooring instead put every one of them
+    // back inside. Rounding this way spends at most a whole pixel of extra
+    // travel and cannot undershoot. What it does not buy is the last
+    // fractional pixel at the very end of the travel — the row's own width
+    // ends in .109 and scrollWidth is whole, so the trailing button still
+    // overhangs the slot by that much with the bar scrolled as far as it
+    // goes; that residue is the one the reachability row's own note describes.
+    const r = btn.getBoundingClientRect();
+    if (r.left < bar.left) {
+      toolbarEl.scrollLeft = Math.floor(toolbarEl.scrollLeft - (bar.left - r.left));
+    } else if (r.right > right) {
+      toolbarEl.scrollLeft = Math.ceil(toolbarEl.scrollLeft + (r.right - right));
+    }
+  }
+
+  // Steps over disabled buttons. The walk is bounded by the button count and
+  // wraps, so a bar with nothing enabled would leave the index where it was
+  // rather than spin — see the model's own guarantee that this cannot happen
+  // (deriveState() keeps `preview` out of every disabling branch, including
+  // the source-mode override; T11-2 later exempted `outline` from that
+  // override too, so the enabled set there is `['outline','preview']` — the
+  // guarantee holds more strongly than when this was written, not less).
+  function moveToolbarCursor(delta) {
+    const btns = toolbarRovingBtns();
+    if (!btns.length) return;
+    let i = toolbarRovingIndex;
+    for (let step = 0; step < btns.length; step++) {
+      i = ((i + delta) % btns.length + btns.length) % btns.length;
+      if (!btns[i].disabled) {
+        toolbarRovingIndex = i;
+        paintToolbarRoving();
+        revealToolbarCursor(btns[i]);
+        return;
+      }
+    }
+  }
+
+  // No "already in the mode" guard, because the key branch cannot deliver one:
+  // while the mode is on, the entry chord's own key is not one of the keys the
+  // mode names, so it takes the hand-back path and ends the mode instead. The
+  // gesture is therefore a toggle, and that is pinned rather than inferred.
+  // moveToolbarCursor() is the null guard as well — it starts by asking the
+  // bar for its buttons, and answers an empty list when there is no bar.
+  function enterToolbarKeynav() {
+    toolbarRovingIndex = -1;
+    moveToolbarCursor(1);
+  }
+
+  function exitToolbarKeynav() {
+    if (toolbarRovingIndex < 0) return false;
+    toolbarRovingIndex = -1;
+    paintToolbarRoving();
+    return true;
+  }
+
+  // Activation goes through the same call the click handler makes, so a
+  // keyboard press and a mouse press cannot drift apart.
+  //
+  // WHERE THE CARET ENDS UP AFTERWARDS, driven button by button over the
+  // enabled row in a plain paragraph, pressing Enter on the cursor and then
+  // typing to see whether the characters land anywhere:
+  //
+  //   * quote, code and line end on BODY and typing goes nowhere, with a
+  //     clean burst and with a dirty one alike.
+  //   * undo, redo and image join them ONLY when the surface has an
+  //     uncommitted edit — the action resolves that burst first, and the
+  //     re-render is what drops the caret. With nothing pending they land back
+  //     on the armed paragraph and typing resumes.
+  //   * everything else lands on an editable surface and typing resumes.
+  //
+  // A mouse click on those same buttons does exactly the same thing, so this
+  // is not something the keyboard route introduced — but a mouse user climbs
+  // out by clicking into the text and a keyboard user cannot, because Tab from
+  // BODY goes nowhere. Deferred to v3.4.0 rather than fixed here: the fix is
+  // in the activation path, which the mouse shares.
+  //
+  // THE WAY OUT until then, driven end to end from a stranded BODY: the entry
+  // chord still works there (the bar's own state survives, and its row is
+  // fully enabled), so walking to the mode button and pressing Enter puts the
+  // caret in the source textarea, where typing lands. Coming back the same way
+  // returns the document to edit mode but leaves the caret on BODY again — the
+  // hatch is somewhere to keep typing, not a way back to the WYSIWYG caret.
+  function activateToolbarCursor() {
+    const btn = toolbarRovingBtns()[toolbarRovingIndex];
+    if (!btn || btn.disabled) return;
+    Promise.resolve(runToolbarAction(btn.getAttribute('data-ed-tb'), btn))
+      .catch(() => {}).then(updateToolbar);
   }
 
   function buildToolbar() {
@@ -10638,11 +13428,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;
   }
@@ -10689,6 +13521,10 @@
   }
 
   // ── headings ▾ ─────────────────────────────────────────────────────────
+  // KNOWN GAP, documented rather than fixed: the toolbar's keyboard cursor can
+  // open and close this dropdown, but its items are still reachable by mouse
+  // only — they carry no cursor of their own and the mode's arrow keys move
+  // along the bar, not into the panel. No keyboard route reaches them.
   function closeToolbarMenu() {
     if (toolbarMenuEl) { toolbarMenuEl.remove(); toolbarMenuEl = null; }
   }
@@ -10713,8 +13549,21 @@
     });
     document.body.appendChild(menu);
     const r = btnEl.getBoundingClientRect();
-    menu.style.top = (r.bottom + 4) + 'px';
+    const top = r.bottom + 4;
+    menu.style.top = top + 'px';
     menu.style.left = Math.max(4, Math.min(r.left, window.innerWidth - 140)) + 'px';
+    // Task 9 fix round 1 (Ruling T9-5): same clamp shape as
+    // openConvertSubmenu()'s .ed-handle-submenu fix above — measure the
+    // panel's own rendered bottom after it is appended and positioned, and
+    // shift `top` up by the bottom overflow when there is one.
+    // `.ed-toolbar-menu` is `position: fixed` (lib/md2doc.js), so its own
+    // getBoundingClientRect() is already in viewport coordinates and `top`
+    // needs no containing-block translation the way the absolute-positioned
+    // submenu did.
+    const overflowBottom = menu.getBoundingClientRect().bottom - window.innerHeight;
+    if (overflowBottom > 0) {
+      menu.style.top = (top - overflowBottom) + 'px';
+    }
     toolbarMenuEl = menu;
   }
 
@@ -10788,7 +13637,7 @@
     // A block that owns no source line has an inverted range, and there is
     // no line to splice in front of.
     if (!rec || rec.endLine < rec.startLine) {
-      refuseStructuralListEdit(NO_SOURCE_LINE_INSERT_MESSAGE);
+      refuseStructuralListEdit(noSourceLineInsertMessageFor(liveBlockEl));
       return;
     }
     const at = rec.startLine;
@@ -10960,18 +13809,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 +13919,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;
@@ -11091,6 +14013,7 @@
       const md = String(payload.value == null ? '' : payload.value).replace(/\r\n?/g, '\n');
       if (md.trim() === '') return;
       if (isInlineSafePaste(md)) {
+        snapBurstIfActive(editEl, 'paste-pre');
         insertTextAtCaret(md);
         snapBurstIfActive(editEl, 'paste');
         return;
@@ -11103,6 +14026,7 @@
       insertBlockBelow(editEl.closest('.ed-block'), 'paragraph', { lines: md.split('\n') });
       return;
     }
+    snapBurstIfActive(editEl, 'paste-pre');
     insertTextAtCaret(payload.value || '');
     snapBurstIfActive(editEl, 'paste');
   }
@@ -11117,12 +14041,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 +14115,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
@@ -11219,6 +14147,16 @@
       if (!e.target || !e.target.closest) return;
       if (e.target.closest('.ed-toolbar') || e.target.closest('.ed-toolbar-menu')) return;
       closeToolbarMenu();
+      // F12: a press somewhere else is a hand-back, so the bar's keyboard
+      // cursor goes with it. Deliberately hung on click and not on focusin:
+      // SOME activations do land a focusin on an editable surface, and hanging
+      // the hand-back there would end the mode after a single press for those.
+      // Driven with an uncommitted edit pending, the ones that fire a focusin
+      // are list, ordered-list, check, table, insert-before, insert-after and
+      // preview; headings, outline, and everything in the landing note on
+      // activateToolbarCursor() fire none. So this cannot be a blanket claim
+      // about activation, and the earlier version of this comment made it one.
+      exitToolbarKeynav();
       const blockEl = e.target.closest('.ed-block');
       if (blockEl) toolbarBlockEl = blockEl;
       updateToolbar();
@@ -11245,15 +14183,110 @@
     // this reason: the conflict banner, the selection toolbar, the table
     // grips and the table edge menu.
     document.body.appendChild(toolbarEl);
+    // A scroll event does not bubble, so this one is on the bar itself rather
+    // than folded into the document-level capture-phase listener at the foot
+    // of this file. That listener does receive the bar's own scroll —
+    // measured, capture reaches a target that never bubbles — but what it
+    // does with it is tear down grips and menus, which has nothing to do with
+    // repainting an edge gradient.
+    //
+    // The resize listener is not redundant with the scroll one. A viewport
+    // change moves clientWidth, and whether it also produces a scroll event
+    // depends on where the bar happens to be resting: driven from 420px out
+    // to 1400px, the bar sitting at its scroll maximum got a scroll event
+    // (the clamp back to zero), and the bar already at zero got none at all,
+    // while both had to end up with the hint out.
+    toolbarEl.addEventListener('scroll', paintToolbarOverflow, { passive: true });
+    window.addEventListener('resize', paintToolbarOverflow);
     document.body.setAttribute('data-ed-mode', docMode);
+    paintModeStatus();
     wireToolbarTracking();
     wireImageDrop();
     wirePlainPasteArming();
+    // No separate first paint of the edge hint here: on this call the
+    // remembered toolbar signature is still its initial empty string, which no
+    // JSON.stringify() of a state object can equal, so updateToolbar() takes
+    // its write branch and repaints on the way out. Driven at a 420px-wide
+    // viewport, the bar carries the right-hand token before any gesture.
     updateToolbar();
   }
 
   // ── global key handling ─────────────────────────────────────────────────
   document.addEventListener('keydown', (e) => {
+    // ── F12: the toolbar's keyboard mode owns its own keys ─────────────
+    // Above everything, including the `.ed-raw` textarea bail further down.
+    // That bail returns for EVERY key, so an entry gesture placed under it
+    // would be dead while a degraded block's raw editor holds focus — driven
+    // from that editor, the gesture lands on the bar and the caret stays in
+    // the textarea. Source mode is a different surface (`textarea.ed-source`,
+    // which that bail does not match) and reaches the bar as well; there the
+    // model disables the row apart from the button that gets you back out, so
+    // the cursor lands on that one.
+    //
+    // Escape is NOT claimed here. It belongs to the ordered prologue just
+    // below, which already ranks a drag and an open menu above everything
+    // else; the rung that leaves this mode was inserted there, in rank order,
+    // rather than jumped ahead of them.
+    //
+    // Anything this mode does not name hands the keyboard straight back: the
+    // mode ends and the keystroke carries on down this listener to whatever
+    // would have had it.
+    //
+    // The modifier names in that list are KEY NAMES, not modifier flags:
+    // `e.key === 'Control'` is the Control key pressed BY ITSELF, which
+    // browsers dispatch a keydown for — driven, and the row asserts that
+    // dispatch before it asserts anything about the cue, because a browser
+    // that stayed silent would make the whole check pass while proving
+    // nothing. Without the exclusions that keydown reaches the hand-back, so a
+    // user who presses Control to begin a chord loses the cursor before
+    // finishing it. That bare press is the shape that separates them, and each
+    // is ablated on its own against it rather than reasoned about as a set.
+    //
+    // A chord does NOT separate them, which is why an earlier reading here
+    // called `Control` and `Meta` unpinnable: Ctrl+S ends the mode and writes
+    // the file whether or not `Control` is excluded, because the `s` behind it
+    // is unnamed here and hands back before the save branch below runs. The
+    // exclusion does its work at the modifier's own keydown, which lands
+    // before the key a chord is named for ever arrives.
+    //
+    // `Alt` and `Shift` carry a second duty on top of that:
+    //
+    //   Alt   — WITHOUT it the entry chord stops toggling. The Alt keydown
+    //           would end the mode, and the F10 behind it would then arrive
+    //           with the mode already off and re-enter, so pressing the chord
+    //           a second time would look like it did nothing. WITH it, the
+    //           Alt keydown is ignored and the F10 lands as an unnamed key,
+    //           which is what ends the mode. The exclusion is the cause of the
+    //           toggle, not a defence against it.
+    //   Shift — keeps Shift+Arrow on the toolbar cursor. Without it the Shift
+    //           keydown ends the mode and the arrow behind it falls through to
+    //           the block-selection extension instead.
+    //
+    // A menu raised from this bar goes down on the way past. Without this the
+    // hand-back cleared the cursor cue and left the H▾ dropdown standing, so
+    // the two disagreed and only Escape was any use. Escape is excluded
+    // because the ordered prologue below owns it and takes the menu down
+    // there, in rank order; Enter and Space are excluded because they are the
+    // keys that opened the menu and have to keep closing it.
+    if (toolbarRovingIndex >= 0) {
+      if (toolbarMenuEl && e.key !== 'Escape' && e.key !== 'Enter' && e.key !== ' ') {
+        closeToolbarMenu();
+      }
+      if (e.key === 'ArrowRight') { e.preventDefault(); moveToolbarCursor(1); return; }
+      if (e.key === 'ArrowLeft') { e.preventDefault(); moveToolbarCursor(-1); return; }
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault(); activateToolbarCursor(); return;
+      }
+      if (e.key !== 'Escape' && e.key !== 'Alt' && e.key !== 'Shift' &&
+          e.key !== 'Control' && e.key !== 'Meta') {
+        exitToolbarKeynav();
+      }
+    } else if (e.altKey && e.key === 'F10') {
+      e.preventDefault();
+      enterToolbarKeynav();
+      return;
+    }
+
     // ── S3 §4.4: Escape priority is drag > menu > selection > burst ─────
     // A new ordered PROLOGUE, not a reshuffle of what follows (§4.4 is
     // explicit about that). The two target-based short-circuits further down
@@ -11316,6 +14349,11 @@
         closeInsertMenu();
         return;
       }
+      // F12, in rank order: the H▾ dropdown is a menu raised from inside the
+      // bar, so it goes out before the bar's keyboard mode does, matching the
+      // way the menu rungs above rank against the selection rung below.
+      if (toolbarMenuEl) { e.preventDefault(); closeToolbarMenu(); return; }
+      if (exitToolbarKeynav()) { e.preventDefault(); return; }
       if (blockSelection) { e.preventDefault(); clearBlockSelection(); return; }
       // Nothing above owns this Escape — fall through to the burst
       // short-circuits below, where Escape-reverts-the-burst still belongs.
@@ -11605,18 +14643,121 @@
     switchAwayFrom();
   });
 
-  document.addEventListener('input', (e) => {
-    const cellEl = e.target && e.target.closest && e.target.closest('.ed-wys-cell');
+  // The `inputType` values Chromium reports for the BROWSER's own formatting
+  // commands. md2doc binds no formatting shortcut of its own — the keys its
+  // `ctrlKey || metaKey` branches act on are `Enter`, `z`, `y`, shift+`Z`,
+  // `s` and shift+`v`/`V`: the raw editor's commit, undo, redo, save and
+  // plain-paste arming. `b`, `i` and `u` are not among them, so Ctrl+B
+  // reaches the contenteditable as the browser's own execCommand and does not
+  // pass through any snapBurstIfActive() call site.
+  //
+  // MEASURED (puppeteer 24.42.0 / headless Chromium, an `.ed-wys-armed`
+  // paragraph, ' typed sentence' typed then a five-character selection
+  // bolded with Ctrl+B) — exactly two events, in this order:
+  //
+  //   beforeinput  inputType="formatBold"  innerHTML "Alpha paragraph. typed sentence"
+  //   input        inputType="formatBold"  innerHTML "Alpha paragraph. <b>typed</b> sentence"
+  //
+  // i.e. the mutation is the beforeinput's default action, so a beforeinput
+  // listener still sees the pre-mutation DOM. That is what makes the pair
+  // below the native-command equivalent of the `*-pre` / post snapshots every
+  // programmatic call site takes (grep `snapBurstIfActive(` and
+  // `history.snap('` for the two families).
+  //
+  // Three of the inputTypes below were actually driven end to end and are
+  // pinned by journey rows: formatBold (Ctrl+B), formatItalic (Ctrl+I),
+  // formatUnderline (Ctrl+U) — measured tags `<b>` / `<i>` / `<u>`. The rest —
+  // formatStrikeThrough, formatSuperscript, formatSubscript, formatRemove —
+  // are listed on the same mechanism but have NOT been driven here; they cost
+  // nothing when they never fire, and they are not a claim that they work.
+  //
+  // A Set, not an object literal: an object literal inherits from
+  // Object.prototype, so `types['constructor']` and `types['toString']` are
+  // truthy and an inputType named like a prototype key would take the format
+  // path. `.has()` answers only for what is actually listed.
+  const NATIVE_FORMAT_INPUT_TYPES = new Set([
+    'formatBold', 'formatItalic', 'formatUnderline', 'formatStrikeThrough',
+    'formatSuperscript', 'formatSubscript', 'formatRemove'
+  ]);
+
+  // Resolves the burst history that owns `e.target`, or null. This is the
+  // selection logic the `input` listener carried inline before v3.3.0, lifted
+  // out unchanged so the new `beforeinput` listener answers the same question
+  // the same way: a `.ed-wys-cell` only counts when the current burst is the
+  // table burst over its own <table>, and any other surface only counts when
+  // it IS the current burst's editEl.
+  function burstHistoryForInputEvent(e) {
+    if (!e.target || !e.target.closest) return null;
+    const cellEl = e.target.closest('.ed-wys-cell');
     if (cellEl) {
       const tableEl = cellEl.closest('table');
       if (currentBurst && currentBurst.blockType === 'table' && currentBurst.editEl === tableEl) {
-        currentBurst.history.noteTyping();
+        return currentBurst.history;
       }
+      return null;
+    }
+    const editEl = e.target.closest('.ed-wys-armed');
+    if (!editEl || !currentBurst || currentBurst.editEl !== editEl) return null;
+    return currentBurst.history;
+  }
+
+  // Capture phase, matching the phase the ordering above was measured in.
+  document.addEventListener('beforeinput', (e) => {
+    if (!NATIVE_FORMAT_INPUT_TYPES.has(e.inputType)) return;
+    const history = burstHistoryForInputEvent(e);
+    if (!history) return;
+    history.snap('native-format-pre');
+  }, true);
+
+  document.addEventListener('input', (e) => {
+    const history = burstHistoryForInputEvent(e);
+    if (!history) return;
+    if (NATIVE_FORMAT_INPUT_TYPES.has(e.inputType)) {
+      // The post-mutation half, and it is LOAD-BEARING — do not simplify it
+      // back to noteTyping(). noteTyping() does not push anything for this
+      // event: it snaps only when the PREVIOUS pending capture is already
+      // >= debounceMs old, then sets `isPendingSnap = true` (history.js,
+      // noteTyping()). Nothing clears that flag on a timer — only snap(),
+      // start() and dispose() assign it false — so the pending capture stands
+      // until something flushes it, and undo() flushes it as its first act.
+      // By then the capture is of the DOM as it is at UNDO time, not as it
+      // was when the command ran.
+      //
+      // TRACED by wrapping window.md2docHistory.createBurstHistory and
+      // logging every call with the stack size on both sides. Two gestures,
+      // this line present vs. swapped for noteTyping():
+      //
+      //   ── Ctrl+B, keep typing inside the window, Ctrl+Z ────────────────
+      //   with:     snap('native-format-pre') 1->2   snap('native-format') 2->3
+      //             noteTyping() 3->3 x2             undo() 3->3
+      //             DOM after undo "Alpha paragraph. <b>typed</b> sentence"
+      //   without:  snap('native-format-pre') 1->2   noteTyping() 2->2 x3
+      //             undo() 2->2
+      //             DOM after undo "Alpha paragraph. typed sentence"
+      //
+      // Read the `undo() N->N` rows: the size does not drop, so undo() pushed
+      // one entry (its flushTyping()) and popped one. WITHOUT this line that
+      // flushed entry is "bold + XY", so the pop lands one entry short of the
+      // bold and the bold is undone together with everything typed after it —
+      // this task's own defect with a different prefix. The journey row
+      // 「原生 Ctrl+B 後【400ms 內】繼續打字」 pins exactly that.
+      //
+      //   ── Ctrl+B, 250ms pause, Ctrl+Z (the four earlier rows) ──────────
+      //   with:     snap('native-format-pre') 1->2   snap('native-format') 2->3
+      //             undo() 3->2
+      //   without:  snap('native-format-pre') 1->2   noteTyping() 2->2
+      //             undo() 2->2
+      //   both:     DOM after undo "Alpha paragraph. typed sentence"
+      //
+      // Those four rows do NOT pin this line, and the reason is NOT that the
+      // pause cleared anything — the `undo() 2->2` above shows the pending
+      // capture was still there and was flushed. It is that with nothing
+      // typed after the command, the flushed capture EQUALS what this line
+      // would have pushed, so undo steps back to the same entry either way.
+      history.snap('native-format');
       return;
     }
-    const editEl = e.target && e.target.closest && e.target.closest('.ed-wys-armed');
-    if (!editEl || !currentBurst || currentBurst.editEl !== editEl) return;
-    currentBurst.history.noteTyping();
+    history.noteTyping();
   });
 
   document.addEventListener('paste', (e) => {
@@ -11624,6 +14765,7 @@
     if (cellEl) {
       e.preventDefault();
       const dt = e.clipboardData || window.clipboardData;
+      snapBurstIfActive(cellEl.closest('table'), 'paste-pre');
       insertTextAtCaret(dt ? dt.getData('text/plain') : '');
       snapBurstIfActive(cellEl.closest('table'), 'paste');
       return;
@@ -11708,8 +14850,87 @@
     });
   });
 
+  // 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;
+      // 沒升起 → 0 次 layout read。Task 16 adds a boolean read here and
+      // nothing else. Measured over a scroll burst against instrumented
+      // Range/Element rect getters and getComputedStyle: with nothing
+      // selected, with a burst open over a collapsed caret, and with a
+      // selection that went collapsed while the bar was scrolled away, the
+      // reads positionSelToolbar() performs stayed at zero — the same
+      // figures as before this line changed. What does read layout per
+      // scroll now is a live non-collapsed selection inside the edit root:
+      // over the same burst that went from two Range rects to eighteen, one
+      // per scroll event, which is the state this branch exists to re-ask.
+      if (!selToolbar.parentNode && !selToolbarOffViewport) return;
+      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; }
+      // Task 15's suppression is asked on this path too, and it has to be:
+      // before Task 16 the gate above returned on a detached bar, so a
+      // scroll could not raise one. It can now, and a Tab-made full-cell
+      // selection is a live non-collapsed selection inside the edit root —
+      // the shape the checks above admit. Measured with this line dropped,
+      // on a hand selection raised over a cell, scrolled out of view and
+      // then walked on by Tab: the scroll that Tab's own focus() causes
+      // appended .ed-seltb over the Tab's selection, and it was down again by
+      // the time the gesture settled — so the settled state reads the same
+      // with this line and without it, and a MutationObserver counting the
+      // append is what sees the difference.
+      //
+      // The flag is read, not the boundary comparison that releases it in
+      // onSelectionChangeForToolbar(): a scroll has no release to make, it
+      // has to honour what the last selectionchange decided, and reading the
+      // flag costs no layout.
+      if (tabSelectedCellEl) { hideSelToolbar(); return; }
+      positionSelToolbar(range);
+    });
+  }
+  document.addEventListener('scroll', onAnyScroll, { passive: true, capture: true });
+
   window.addEventListener('beforeunload', (e) => {
-    if (stack.dirtyDepth !== 0) {
+    if (stack.dirtyDepth !== 0 || burstHasUncommittedEdit()) {
       e.preventDefault();
       e.returnValue = '';
       return '';