@helping-ai-workflow/md2doc 3.0.0 → 3.0.2

package/lib/editor/client.js

@@ -1667,6 +1667,57 @@
   // function did by returning early.
   function computeIndentClamp(spanEls, opBlockEl, opOldIndent, opts) {
     if (!indentClamp || !spanEls || !spanEls.length) return null;
+    // v3.0.2 — the structural answer to the stale-`run` pattern that v3.0.1
+    // point-fixed at three call sites, and that both reviewers asked to have
+    // fixed at the call convention instead. There are FIVE call sites, not
+    // three (3483 batch delete, 3812 convert, 5778 batch Tab/Shift+Tab, 6028
+    // caret Tab/Shift+Tab — both indent directions share ONE call site each,
+    // batch vs. caret, not one call site per direction — and the drop's
+    // compute at 8516), and every one of them hands over a `listRunOf()`
+    // result in document order. Two ways that goes stale, both of which
+    // produced a confident wrong number rather than a refusal: a member
+    // DETACHED (getAttribute still answers on a detached node) and a span
+    // still attached but no longer in the run's document order (indexOf()
+    // then reports an opIndex for a layout that no longer exists, so §3.4
+    // rule 2's scope starts in the wrong place). Re-deriving the span here
+    // instead of checking it was rejected: it would quietly change the
+    // contract from "clamp this span" to "clamp the run containing this
+    // op", and the drop is the one caller subtle enough that taking that
+    // expressiveness away is not free.
+    //
+    // It does NOT throw. This file's defensive style (safeRerenderAll at
+    // ~990) is that the editor must not die on one path's failure. But the
+    // refusal is NOT free either: at the drop (8516) a null clamp feeds
+    // spanIndentsAreAnchored() the RAW reordered indents, and that refuses
+    // 1425 of 4067 legal drops where the clamped answer refuses only 14 (the
+    // clamp rescues the other 1411; the measured numbers are recorded at
+    // line ~371). So a false positive here costs the user up to 1411 legal
+    // batch drags, replaced by a banner —
+    // which is why the assert is worth this cost even though the batch-
+    // delete, convert and drop sites each have a scenario whose correct
+    // answer needs a real reclamp (a wrongly-firing assert breaks them
+    // visibly), while neither Tab call site (5778 batch, 6028 caret) has a
+    // scenario that reclamps a TRAILING sibling — see
+    // test/editor-client-runtime.test.js for the per-site detail.
+    const fresh = listRunOf(spanEls[0]);
+    if (fresh.length !== spanEls.length ||
+        fresh.some((el, i) => el !== spanEls[i])) {
+      // Minor 5: the length pair alone is silent on the reordered-but-same-
+      // length case (the ONLY case where an index is diagnostic — a length
+      // mismatch is already self-explanatory), so report the first index at
+      // which the two runs disagree too.
+      const minLen = Math.min(fresh.length, spanEls.length);
+      let badIndex = -1;
+      for (let i = 0; i < minLen; i++) {
+        if (fresh[i] !== spanEls[i]) { badIndex = i; break; }
+      }
+      if (badIndex < 0 && fresh.length !== spanEls.length) badIndex = minLen;
+      console.error('computeIndentClamp: stale span — the run has ' + fresh.length +
+        ' members, the caller passed ' + spanEls.length +
+        ', first differing at index ' + badIndex +
+        '; refusing rather than clamping against a layout that no longer exists');
+      return null;
+    }
     const opEls = Array.isArray(opBlockEl) ? opBlockEl : [opBlockEl];
     const opIndex = [];
     for (let k = 0; k < opEls.length; k++) {
@@ -2009,6 +2060,30 @@
       '<path d="M6.6 7.2v4.2"/><path d="M9.4 7.2v4.2"/>',
     // MD 原始碼 — angle brackets: source, not prose.
     code: '<path d="M6 3.6L2 8l4 4.4"/><path d="M10 3.6L14 8l-4 4.4"/>',
+    // ── v3.0.1: one icon per 轉換成 target ────────────────────────────────
+    // Keys are CONVERT_TARGETS[].id verbatim; openConvertSubmenu() looks them
+    // up by that id, so a rename on either side must be made on both.
+    // 文字 — a paragraph pilcrow, drawn rather than typed so it inherits the
+    // same stroke weight as every sibling icon.
+    text: '<path d="M9 2.5H6.2a2.7 2.7 0 0 0 0 5.4H9"/><path d="M9 2.5v11"/><path d="M11.8 2.5v11"/>',
+    // 標題 1–6 — an "H" plus the level, as two strokes and a numeral bar set.
+    h1: '<path d="M3 3v10"/><path d="M8 3v10"/><path d="M3 8h5"/><path d="M11.5 6.5l1.5-1v7.5"/>',
+    h2: '<path d="M3 3v10"/><path d="M8 3v10"/><path d="M3 8h5"/><path d="M11 6.6a1.6 1.6 0 0 1 2.7 1.1c0 1.4-2.7 2.6-2.7 5.3h3"/>',
+    h3: '<path d="M3 3v10"/><path d="M8 3v10"/><path d="M3 8h5"/><path d="M11 5.8h2.7l-1.6 2.6a1.8 1.8 0 1 1-1.3 3"/>',
+    h4: '<path d="M3 3v10"/><path d="M8 3v10"/><path d="M3 8h5"/><path d="M13 5.8v7.2"/><path d="M13 10.7h-2.6l2.2-4.9"/>',
+    h5: '<path d="M3 3v10"/><path d="M8 3v10"/><path d="M3 8h5"/><path d="M13.5 5.8h-2.6v2.8a1.9 1.9 0 1 1-.5 3.6"/>',
+    h6: '<path d="M3 3v10"/><path d="M8 3v10"/><path d="M3 8h5"/><path d="M13.4 6.2a1.9 1.9 0 0 0-3 1.5v3.2a1.8 1.8 0 1 0 3.1-1.3 1.8 1.8 0 0 0-3.1 1.3"/>',
+    // 項目符號列表 — three dots with three rules.
+    ul: '<circle cx="3.2" cy="4.2" r="1"/><circle cx="3.2" cy="8" r="1"/><circle cx="3.2" cy="11.8" r="1"/>' +
+      '<path d="M6.4 4.2h7.4"/><path d="M6.4 8h7.4"/><path d="M6.4 11.8h7.4"/>',
+    // 編號列表 — the same three rules led by 1/2/3 strokes.
+    ol: '<path d="M2.2 3.4l1-.6v2.8"/><path d="M2 8.2a1 1 0 0 1 1.7.7c0 .9-1.7 1.6-1.7 2.4h1.9"/>' +
+      '<path d="M2.1 11.4h1.6l-1 1.1a1 1 0 1 1-.7 1.2"/>' +
+      '<path d="M6.4 4.2h7.4"/><path d="M6.4 8.6h7.4"/><path d="M6.4 12.9h7.4"/>',
+    // 待辦清單 — a checked box.
+    task: '<rect x="2.2" y="2.6" width="10.8" height="10.8" rx="2.4"/><path d="M5.2 8.2l2.1 2.1 3.8-4"/>',
+    // 引用 — a quote bar plus two shortened rules.
+    quote: '<path d="M3 3.4v9.2"/><path d="M6.4 5.4h7.2"/><path d="M6.4 8h7.2"/><path d="M6.4 10.6h4.6"/>',
   };
   function menuIconMarkup(name) {
     return '<svg class="ed-menu-icon" viewBox="0 0 16 16" width="16" height="16" ' +
@@ -2191,7 +2266,13 @@
       const b = document.createElement('button');
       b.type = 'button';
       b.className = 'ed-handle-menu-btn';
-      b.textContent = t.label;
+      // v3.0.1: the submenu carries icons too. Without them its labels start
+      // at the button's own padding while the parent menu's start past a 16px
+      // icon, so the two levels' text does not share a vertical line — the
+      // exact defect the user reported. `.ed-handle-menu-btn` is already a
+      // flex row with a gap, so an icon plus a text node is all it takes.
+      b.innerHTML = menuIconMarkup(t.id);
+      b.appendChild(document.createTextNode(t.label));
       b.setAttribute('aria-label', 'Convert to ' + t.id);
       b.addEventListener('click', (e) => {
         e.stopPropagation();
@@ -4186,7 +4267,16 @@
     // S1 removed the pre-per-li 'list' branch that lived here: blockmap has not
     // emitted type:'list' blocks since Phase 4, so no startBurst() call could
     // produce blockType === 'list' and the branch was already dead code.
-    const result = burst.blockType === 'table' ? tableMd.serializeTable(burst.editEl)
+    // v3.0.1: hand the serializer the table's CURRENT source lines so it can
+    // reuse the author's own column widths instead of flattening the whole
+    // table to minimal form over a one-cell edit. extractBlockSource() is the
+    // same helper the raw editor prefills from, so "what the file says" has
+    // exactly one definition.
+    const tableBlockRec = burst.blockType === 'table'
+      ? blocks.find((b) => b.id === burst.blockId) : null;
+    const result = burst.blockType === 'table'
+      ? tableMd.serializeTable(burst.editEl,
+          tableBlockRec ? extractBlockSource(lines, tableBlockRec) : null)
       : inlineMd.serializeInline(burst.editEl);
     if (result.unsupported.length > 0) {
       // Degrade-never-lose (same contract as Phase 2's openWysiwygEditor()
@@ -4452,6 +4542,15 @@
   window.__edTestForceRerender = function () { return rerenderAll(); };
   window.__edTestTruncateTo = function (n) { lines = lines.slice(0, n); };
 
+  // v3.0.2: computeIndentClamp() lives past this file's node early-exit
+  // (module.exports at line ~509 ships the pure core only) and nothing on
+  // window reaches it, so the stale-span assert added to it in v3.0.2 had
+  // no way to be tested at all. This is the seventh __edTest seam and the
+  // only production surface that change adds.
+  window.__edTestClampProbe = function (spanEls, opBlockEl, opOldIndent, opts) {
+    return computeIndentClamp(spanEls, opBlockEl, opOldIndent, opts);
+  };
+
   // ── S3 Task 4: the entry and exit GESTURES ─────────────────────────────
   // §4.4 entries: (a) press inside a block and drag across its boundary;
   // (b) Shift+Click; (c) Shift+↑↓. Exits: Escape (Task 3's keydown prologue)
@@ -5468,16 +5567,29 @@
   function indentListItem(blockEl) {
     const self = liAttrs(blockEl);
     if (!self) return false;
-    // Rule (d): the first item of a LIST has nothing above it to nest under.
-    // Without this the §3.4 clamp would happily read the previous list's last
-    // item as "the previous block" and indent this one underneath it, merging
-    // two lists the user never asked to join. Pre-S1 this fell out of
-    // `previousElementSibling` being null inside the item's own <ul>.
-    if (self.listStart) return false;
     const all = allBlockEls();
     const i = all.indexOf(blockEl);
     if (i < 0) return false;
     const prev = liAttrs(all[i - 1]);
+    // Rule (d), narrowed (v3.0.1). The old rule was `if (self.listStart)
+    // return false` — the first item of a LIST has nothing above it to nest
+    // under. That over-refused: a bullet outdented to indent 0 directly
+    // BELOW an ordered item is a listStart (a ul following an ol) whose
+    // previous block is a perfectly good parent, and the user could never
+    // indent it back. The half that still has to be refused is the one the
+    // old rule was really aimed at: two list tokens the user kept apart with
+    // a BLANK LINE. Indenting the second one makes listRunOf() span both,
+    // and re-serializing that span swallows the blank line — a rewrite of
+    // lines nobody touched, which is the one thing this editor must never do.
+    // Contiguity is a fact about the FILE, so it is read off `blocks`, not
+    // guessed from the DOM.
+    if (self.listStart) {
+      if (!prev) return false;
+      const prevRec = blockRecOf(all[i - 1]);
+      const selfRec = blockRecOf(blockEl);
+      if (!prevRec || !selfRec) return false;
+      if (prevRec.endLine + 1 !== selfRec.startLine) return false;
+    }
     const max = prev ? prev.indent + 1 : 0;
     const next = Math.min(self.indent + 1, max);
     if (next === self.indent) return false;
@@ -5554,22 +5666,39 @@
 
   // How far ONE member may move, as a magnitude (0 or 1), never a signed
   // delta. `dir` is +1 (Tab) or -1 (Shift+Tab). The ceiling restates
-  // indentListItem()'s own single-item rule — the list-start clause included,
-  // so a set that opens a list cannot nest itself under the previous list's
-  // last item — and the floor is outdentListItem()'s (indent 0 cannot rise).
-  // Both read PRE-move indents, which is §3.4's global convention ("the
-  // operated block's indent" always means the value before the operation), and
-  // it is what makes the minimum below well-defined: every member is measured
-  // against the document as it stands, not against members already moved.
+  // indentListItem()'s own single-item rule, v3.0.1's narrowed list-start
+  // clause included: a listStart member still refuses UNLESS the block
+  // immediately before it (by file line, via blockRecOf — same contiguity
+  // check, same code shape as indentListItem()'s, kept in that shape
+  // deliberately so the two stay in visible agreement) is a contiguous list
+  // item, in which case it has real head-room like any other item. Before
+  // v3.0.1 this was unconditional (`if (self.listStart) return 0;`) —
+  // batch Tab on a listStart block was refused outright, matching
+  // indentListItem()'s then-unconditional refusal. Narrowing ONE of the two
+  // without the other silently reintroduces the single-item defect on the
+  // batch axis: a listStart item directly below a contiguous ordered item,
+  // selected as part of a batch, would stay refused even though the very
+  // same block indents fine on its own. The floor is outdentListItem()'s
+  // (indent 0 cannot rise), untouched by this narrowing. Both read PRE-move
+  // indents, which is §3.4's global convention ("the operated block's
+  // indent" always means the value before the operation), and it is what
+  // makes the minimum below well-defined: every member is measured against
+  // the document as it stands, not against members already moved.
   function memberIndentHeadroom(el, dir) {
     const self = liAttrs(el);
     if (!self) return 0;
     if (dir < 0) return self.indent > 0 ? 1 : 0;
-    if (self.listStart) return 0;
     const all = allBlockEls();
     const i = all.indexOf(el);
     if (i < 0) return 0;
     const prev = liAttrs(all[i - 1]);
+    if (self.listStart) {
+      if (!prev) return 0;
+      const prevRec = blockRecOf(all[i - 1]);
+      const selfRec = blockRecOf(el);
+      if (!prevRec || !selfRec) return 0;
+      if (prevRec.endLine + 1 !== selfRec.startLine) return 0;
+    }
     const max = prev ? prev.indent + 1 : 0;
     return Math.max(0, Math.min(1, max - self.indent));
   }
@@ -5623,7 +5752,30 @@
       // segment delta for the blocks below instead of N independent clamps, and
       // its rule 1 then walks the operated blocks in document order so each is
       // measured against the member above it that the same pass just settled.
-      applyIndentClamp(run, liEls, oldIndent);
+      //
+      // v3.0.1 (review round 1 follow-up): `run` above is batchRunOf()'s
+      // PRE-mutation snapshot — the exact same staleness handleLiKeydown()'s
+      // single-item Tab branch had before its own v3.0.1 fix (see that
+      // call's comment). For a single-member batch on a listStart item whose
+      // ceiling memberIndentHeadroom() has just narrowed (a bullet directly
+      // below a contiguous ordered item), the pre-mutation run is `[liEls[0]]`
+      // alone — batchRunOf() never walked backward past the list-start
+      // boundary, because before this fix nothing could ever cross it. With
+      // no anchor IN the span, applyIndentClamp()'s rule 1 has nothing to
+      // bound the indent the forEach above just wrote against, and clamps it
+      // straight back to 0 — silently undoing the write, MEASURED directly:
+      // narrowing memberIndentHeadroom() alone left the covering test RED.
+      // A FRESH listRunOf(liEls[0]) call here — taken after the write above —
+      // walks back from the NEW indent and finds the real parent, exactly
+      // like the post-mutation `liveRun = listRunOf(liEls[0])` a few lines
+      // below (the COMMIT span) already does; using the same fresh call for
+      // the clamp keeps the two consistent, same reasoning as
+      // handleLiKeydown()'s Tab branch. Provably identical to the old stale
+      // `run` for every case where no member was ever a list-start
+      // (listRunOf() slices by INDEX RANGE, and neither the range's
+      // start/end index nor the elements between them shift when only
+      // already-run-member indents change).
+      applyIndentClamp(listRunOf(liEls[0]), liEls, oldIndent);
     });
     // Re-derived AFTER the mutation, like the caret Tab's: an indent change can
     // move a block between runs.
@@ -5854,7 +6006,26 @@
       const oldIndent = Number(li.getAttribute('data-indent')) || 0;
       const changed = mutateListRun(() => {
         if (!(e.shiftKey ? outdentListItem(li) : indentListItem(li))) return false;
-        applyIndentClamp(run, li, oldIndent);
+        // v3.0.1: `run` above is a PRE-mutation snapshot, captured while `li`
+        // still had its OLD indent. That is fine for outdentListItem() — the
+        // clamp's model rereads every element's CURRENT data-indent off the
+        // DOM, so it self-corrects regardless of which elements the snapshot
+        // names — but indentListItem() can now move a rule-(d) list-start
+        // item (a bullet directly below an ordered item, say) whose own
+        // pre-mutation run is `[li]` alone: nothing shallower ever preceded
+        // it, because runBlocksOf() stops at a list-start by design. With no
+        // anchor IN the span, applyIndentClamp()'s rule 1 has nothing to
+        // bound the indent this call just wrote against, and clamps it
+        // straight back to 0 — silently undoing the write. A FRESH
+        // listRunOf(li) call here — taken after the write above — walks back
+        // from li's NEW indent and finds the real parent, exactly like the
+        // post-mutation `run = listRunOf(li)` a few lines below (the COMMIT
+        // span) already does; using the same fresh call for the clamp keeps
+        // the two consistent. Provably identical to the old stale `run` for
+        // every case where li was never a list-start (listRunOf() slices by
+        // INDEX RANGE, and neither the range's start/end index nor the
+        // elements between them shift when only li's own indent changes).
+        applyIndentClamp(listRunOf(li), li, oldIndent);
         return true;
       });
       if (!changed) return true;
@@ -6426,8 +6597,12 @@
   function tableIdentityOf(tableEl) {
     const headerRow = tableEl ? headerRowOf(tableEl) : null;
     if (!headerRow) return null;
-    return allRowsOf(tableEl).length + '
' +
-      Array.prototype.slice.call(headerRow.cells).map((c) => c.textContent).join('');
+    // The two delimiters are written as ESCAPES, not as literal control
+    // bytes. They used to be literal, which made grep classify this whole
+    // 9643-line file as binary and SILENTLY TRUNCATE its output — a real
+    // investigation was misled by it. The runtime value is identical.
+    return allRowsOf(tableEl).length + '\x01' +
+      Array.prototype.slice.call(headerRow.cells).map((c) => c.textContent).join('\x00');
   }
   async function ensureTableBurstOpen(tableEl) {
     if (currentBurst && currentBurst.blockType === 'table' && currentBurst.editEl === tableEl) return tableEl;
@@ -6907,19 +7082,20 @@
   // listener (wired near the bottom of this file) that already drives
   // updateTableInsertBubbles() — see its own comment for the coalescing
   // contract this reuses.
-  // Geometry, per axis (they are NOT mirror images — see below):
+  // Geometry, per axis (v3.0.1: they are mirror images again):
   //   COLUMN grip: its CENTRELINE coincides with the table's TOP border, so
   //     its hit rect straddles that border by half its own height on each
   //     side (P0-a).
-  //   ROW grip: its LEFT EDGE coincides with the table's LEFT border, so the
-  //     whole grip is INSIDE the table. This is spec §4.2 hit-test
-  //     conflict 2's ruling, landed in S4 T1.
-  //
-  // Why the row axis had to break the symmetry. The block's own gutter ⠿
-  // hangs outside the content box at [blockLeft-22, blockLeft-4], and a
-  // table block's own table starts AT blockLeft, so a row grip centred on
-  // the table's left border occupied [blockLeft-10, blockLeft+10] and
-  // overlapped the ⠿'s right 6px. Both are position: fixed / absolutely
+  //   ROW grip: its CENTRELINE coincides with the table's LEFT border, so
+  //     its hit rect straddles that border by half its own width on each
+  //     side — same shape as the column grip, restored in v3.0.1 (spec §4.2
+  //     hit-test conflict 2).
+  //
+  // History: why the row axis briefly broke the symmetry, and how that was
+  // undone. The block's own gutter ⠿ hangs outside the content box, and a
+  // table block's own table starts at that same left edge, so a row grip
+  // centred on the table's left border occupied [blockLeft-10, blockLeft+10]
+  // and overlapped the ⠿'s right 6px. Both are position: fixed / absolutely
   // positioned overlays and the grip is a document.body child at z-index 7,
   // so the grip won that hit test whenever it was showing — which is
   // whenever the pointer had recently been over a table cell. MEASURED on
@@ -6930,20 +7106,32 @@
   // 402..407. S4 makes the ⠿ a drag handle, so those 6px would have started
   // a table ROW drag instead of a block move.
   //
-  // An earlier revision (v2.10.1) already tried the inset and was reverted,
+  // S4 T1 (v2.12.0) fixed that by INSETTING the grip instead — its left edge
+  // on the table's left border, entirely inside the table, no more straddle.
+  // That broke the row/column symmetry (the column grip still straddles the
+  // table's top border, because nothing of the page's own chrome lives up
+  // there) and was reported as a v3.0.1 visual regression. An even earlier
+  // revision (v2.10.1) had already tried an inset like it and been reverted,
   // because a 20px grip inside a cell whose left padding is 14px sits on
-  // that cell's TEXT. That is fixed on the CSS side this time rather than by
-  // giving the grip back its outside half: lib/md2doc.js pads the first
-  // column to --ed-te-cell-pad-left (the grip's own width plus the gutter
-  // pair's breathing gap) in EDIT MODE ONLY. The ⠿ ↔ grip clearance that
-  // remains is exactly that same breathing-gap token — see the edit-mode
-  // :root block in lib/md2doc.js, which spells both tokens out; this file
-  // deliberately does not name them, because test/editor-client.test.js
-  // forbids the retired hover-gutter class name as a bare substring and the
-  // token names contain it. Neither edge is written down twice, so the two
-  // cannot drift apart again — drift is what produced this defect (the CSS
-  // comment claiming "an 8px gap" was describing v2.11.0's pair position,
-  // which v2.11.1 replaced).
+  // that cell's TEXT — S4 T1 avoided repeating that by widening the first
+  // column's own edit-mode padding to clear the inset grip.
+  //
+  // v3.0.1 undoes the inset rather than re-tuning it: the row grip goes back
+  // to straddling the border (this file's change, see updateTableEdgeGrips()
+  // below), and the ⠿/＋ pair itself moves further LEFT instead (a shift
+  // token declared alongside the gutter's own tokens in lib/md2doc.js) — the
+  // overlap is removed at its SOURCE, not by moving the grip out of the
+  // ⠿'s way. That also means the first column's edit-mode padding widening
+  // is gone: the grip's straddling half (10px) fits inside the column's
+  // default 14px padding on its own, so v2.10.1's original defect does not
+  // come back. Neither the ⠿'s right edge nor the grip's left edge is
+  // written down as a literal on either side of the gap between them — see
+  // the shift-token comment in lib/md2doc.js's edit-mode :root block, which
+  // this file deliberately does not name (test/editor-client.test.js forbids
+  // the retired hover-gutter class name as a bare substring and the token
+  // name contains it) — so the two cannot drift apart the way v2.11.0's pair
+  // position once did (the CSS comment claiming "an 8px gap" was describing
+  // that stale position, which v2.11.1 replaced).
   // test/editor-client-runtime.test.js asserts BOTH directions: every pixel
   // of a block's ⠿ answers that ⠿ (row grip hidden and showing), and the row
   // grip's own centre answers the row grip.
@@ -6962,6 +7150,19 @@
   // reported overlap corner AND verifies the z-index ordering directly —
   // re-verify it if either the grip's or bubble's z-index ever changes.
 
+  // --ed-te-grip-row-w, read once and cached. The token is the single source
+  // of truth for the grip's width (lib/md2doc.js declares it); parsing it here
+  // means the JS never carries a second copy of the number.
+  let gripRowWidthCache = null;
+  function gripRowWidthPx() {
+    if (gripRowWidthCache !== null) return gripRowWidthCache;
+    const raw = getComputedStyle(document.documentElement)
+      .getPropertyValue('--ed-te-grip-row-w');
+    const n = parseFloat(raw);
+    gripRowWidthCache = Number.isFinite(n) && n > 0 ? n : 20;
+    return gripRowWidthCache;
+  }
+
   function buildTableGrip(cls, ariaLabel) {
     const b = document.createElement('button');
     b.type = 'button';
@@ -6998,6 +7199,40 @@
   let gripColTableEl = null;
   let gripColIndex = null;
 
+  // v3.0.2 — the gutter keep-alive for the table row grip. Held in its own
+  // module-level reference, NOT read back off `gripRowTableEl`, because
+  // hideTableGrips() below nulls that at its own line 7246-7248: a teardown
+  // that went looking for the block through it would find null exactly when
+  // it needs to clear the class, and rerenderAll()'s hideTableGrips() call
+  // reaches it with the table already detached.
+  let gutterKeepEl = null;
+
+  function setGutterKeep(blockEl) {
+    const next = blockEl || null;
+    if (gutterKeepEl === next) return;
+    if (gutterKeepEl) gutterKeepEl.classList.remove('ed-keep-lit');
+    gutterKeepEl = next;
+    if (gutterKeepEl) gutterKeepEl.classList.add('ed-keep-lit');
+  }
+
+  function clearGutterKeep() { setGutterKeep(null); }
+
+  // The block whose gutter the CURRENTLY SHOWN row grip is covering, or null
+  // when there is nothing to keep lit. Two conditions, both load-bearing:
+  //
+  //   • gripRowTableEl / gripRowEl may be null while a grip is nonetheless
+  //     visible — a header-only table takes the else branch at 7466-7470 and
+  //     nulls both, then the column grip is shown unconditionally just
+  //     below. Both callers of this function are reached in that state.
+  //   • only the HEADER row's grip shares a Y with the ⠿. Keeping the
+  //     gutter lit for a body row's grip would light the ⠿ in a place the
+  //     defect never occurred — a behaviour change beyond the fix.
+  function headerGripBlock() {
+    if (!gripRowTableEl || !gripRowEl) return null;
+    if (gripRowEl !== headerRowOf(gripRowTableEl)) return null;
+    return gripRowTableEl.closest('.ed-block');
+  }
+
   function hideTableGrips() {
     rowGrip.hidden = true;
     colGrip.hidden = true;
@@ -7012,6 +7247,7 @@
     gripRowEl = null;
     gripColTableEl = null;
     gripColIndex = null;
+    clearGutterKeep();
   }
 
   // Bug fix (user acceptance) — history: grips were originally BOTH
@@ -7025,16 +7261,18 @@
   // gripCenter(), which jump straight to the grip's own coordinates) could
   // ever land on it; a real mouse gesture could not.
   //
-  // Current geometry (the two axes DIVERGED in S4 T1, §4.2 conflict 2): the
-  // COLUMN grip still straddles the table's TOP border, half above / half
-  // below, so the corridor-crossing bug described above still applies to it
-  // exactly as originally described and pointInColGripZone() still covers
-  // the outside-the-border corridor. The ROW grip is now entirely INSIDE the
-  // table (its left edge on the table's left border), so a pointer
-  // travelling from a cell to it never leaves the table and there is no
-  // corridor to cross — pointInRowGripZone() is the padded grip rect alone.
-  // See its own comment for why the old formula was deleted rather than
-  // left in place to evaluate to the empty set.
+  // Current geometry (v3.0.1 restored the row axis to mirror the column
+  // axis — see the "Notion-style row/column grip handles" section comment
+  // above for the S4 T1 detour into an inset row grip and how it was
+  // undone): BOTH grips straddle their own border again, the COLUMN grip
+  // half above / half below the table's TOP border and the ROW grip half
+  // outside / half inside the table's LEFT border. The corridor-crossing
+  // bug described above therefore applies to BOTH axes' straddling shape in
+  // principle, and pointInColGripZone() still covers the column's
+  // outside-the-border corridor exactly as before. pointInRowGripZone()
+  // deliberately does NOT get an equivalent corridor formula back, even
+  // though the straddle is back — see its own comment for why the padded
+  // grip rect alone is still sufficient.
   //
   // Review fix (Important, first pass over-permissive): the first version of
   // this fix kept a grip visible while the pointer was ANYWHERE within the
@@ -7047,30 +7285,28 @@
   // SPECIFIC shown grip's own anchor (pointInRowGripZone()/
   // pointInColGripZone() below) instead of the whole table.
   //
-  // What each keep-zone covers TODAY — and the two axes diverged when §4.2
-  // conflict 2 moved the row grip inside the table (S4 T1):
-  //   pointInColGripZone() still keeps the ORIGINAL corridor shape: the
-  //     union of (the column grip's own padded rect) and (the straight strip
-  //     between the grip's own TOP edge and the table's top border, x clamped
-  //     to the anchor COLUMN's own horizontal extent, padded). The column
-  //     grip still straddles the top border, so that corridor is still real.
-  //   pointInRowGripZone() is now the padded grip rect ALONE. Its corridor
-  //     was the strip between the grip's own LEFT edge and the table's LEFT
-  //     border; with the grip's left edge ON that border the strip is empty,
-  //     and §4.6 explicitly warns that leaving the formula in place would
-  //     make it (and the two scenarios downstream of it) silently vacuous
-  //     rather than red. It is deleted rather than left to read as if it did
-  //     something. Nothing is lost: the corridor existed because a pointer
-  //     travelling from a cell to a border-straddling grip had to leave the
-  //     table on the way, and a grip that is entirely inside the table has no
-  //     such approach — the pointer goes cell -> grip, and the
-  //     `target.closest('.ed-te-grip-row')` early return at the top of
-  //     updateTableEdgeGrips() covers the moment it arrives. The observable
-  //     change is that leaving the table on the left now hides the row grip
-  //     immediately, at the anchor row's own height as well as at any other
-  //     row's; the scenario named below asserts both halves, because "hidden
-  //     at another row's height" alone is true of any geometry once the
-  //     corridor is gone.
+  // What each keep-zone covers TODAY:
+  //   pointInColGripZone() keeps the ORIGINAL corridor shape: the union of
+  //     (the column grip's own padded rect) and (the straight strip between
+  //     the grip's own TOP edge and the table's top border, x clamped to the
+  //     anchor COLUMN's own horizontal extent, padded). The column grip
+  //     straddles the top border, so that corridor is real.
+  //   pointInRowGripZone() is the padded grip rect ALONE, no corridor term —
+  //     kept that way through the v3.0.1 straddle restoration on purpose,
+  //     not left behind by accident. A pointer travelling from inside a body
+  //     cell to the row grip's own centre (which sits exactly on the
+  //     table's left border) never has to leave the table's horizontal
+  //     extent on the way there, so the padded rect alone already covers
+  //     every REAL (non-teleporting) approach this file's own test suite
+  //     exercises — see "table grips: the row grip straddles the table's
+  //     left border again…" in test/editor-client-runtime.test.js. That is
+  //     narrower than the column axis's guarantee (nothing approaches the
+  //     row grip from further out along the table's own left edge the way a
+  //     pointer can approach the column grip from above it), which is why
+  //     the two functions are allowed to stay asymmetric even though the
+  //     grips' shapes are not. If a future report finds a real pointer path
+  //     that does need a corridor term here, that is a new, separate defect
+  //     — not evidence this reasoning was wrong when it was written.
   // A pointer outside either grip's own zone is a genuine exit and still
   // hides the grip via hideTableGrips(), same as before. Neither fix touches
   // either grip's size or z-index, so the click-priority guarantee (bubble
@@ -7090,16 +7326,32 @@
   function pointInRowGripZone(x, y) {
     if (rowGrip.hidden || !gripRowTableEl || !gripRowEl ||
       !document.body.contains(gripRowEl) || !document.body.contains(gripRowTableEl)) return false;
-    // §4.2 衝突 2（S4 T1）之後 row grip 整個落在表格內側，左緣就壓在表格
-    // 左邊界上，所以舊的走廊公式 `x >= gr.left && x <= tableRect.left` 塌成
-    // 空集合。§4.6 已經預告過這件事：留著它不會變紅，只會變成空測。這裡
-    // 直接刪掉，keep-zone 只剩 grip 自己的 padded rect。
-    // 走廊本來只為了一件事存在——指標從儲存格走向一個跨在邊界上的 grip
-    // 時必定會先離開表格；grip 內移之後那條路徑整段都在表格內（先是
-    // 儲存格，接著是 grip 自己，由 updateTableEdgeGrips() 開頭那個
-    // `target.closest('.ed-te-grip-row')` 早退接手），所以沒有走廊可走。
-    // 對使用者可見的差別是：從左側離開表格會立刻收掉 row grip，錨定那一
-    // 列的高度也不例外。
+    // v3.0.1 恢復跨界：row grip 的中心線重新落在表格左邊界上（不再是
+    // S4 T1 那個左緣頂在邊界上、整個縮進表格內側的做法）。與 ⠿ 的重疊
+    // 改在源頭解決——往左再位移的是頁面 gutter 的 ⠿/＋ 那一對按鈕本身
+    // （多移動一個位移 token，宣告在 lib/md2doc.js 的編輯模式 :root 區
+    // 塊，此檔案依慣例不直接引用其名稱），不是移動 grip。
+    //
+    // 走廊公式沒有跟著補回來，是刻意維持的範圍決定，不是漏掉：
+    // TE_GRIP_ZONE_PAD_PX=4 的 padded rect 涵蓋 [tableLeft-14,
+    // tableLeft+14]（grip 本身 20px 寬、跨在邊界上是 [tableLeft-10,
+    // tableLeft+10]，外加 4px 緩衝）。指標從儲存格內側走向 grip 中心
+    // （正好落在 tableLeft）的整段路徑，x 一律 >= tableLeft，從未離開
+    // 表格的水平範圍，所以「儲存格 -> grip」這條測試套件唯一驗證過的
+    // 真實（非瞬移）路徑，本來就不需要走廊公式。哪天真的量到一條需要
+    // 走廊的真實路徑（例如從表格左側、gutter 那一側靠近），那是新的、
+    // 獨立的缺陷，不代表這裡當初的推論錯了。
+    //
+    // 誠實記一筆巧合，不要誤讀成保證：⠿ 的右緣恰好落在 tableLeft-14，
+    // 與這個 padded rect 的左緣相觸、不重疊——這是 TE_GRIP_ZONE_PAD_PX
+    // 這個寫死的 4，與 lib/md2doc.js 那個 4px 呼吸間距 token 兩個各自
+    // 獨立宣告出來的巧合，不是誰推導誰的保證。任一邊數值改動，觸點都
+    // 可能變成 1px 縫隙或重疊，沒有任何型別檢查會抓到。這是既有狀態，
+    // 不是本次修正引入或修掉的東西。
+    //
+    // 對使用者可見的差別：離開表格左側不再等於立刻收掉 row grip——padded
+    // rect 本身就已經探出表格邊界 14px，所以指標要離開這整個 padded rect
+    // （水平或垂直）才會真的收掉，錨定那一列的高度也不例外。
     return pointInPaddedRect(x, y, rowGrip.getBoundingClientRect(), TE_GRIP_ZONE_PAD_PX);
   }
 
@@ -7141,7 +7393,15 @@
     // whatever was last shown untouched instead; hideTableGrips() (called
     // from table-leave, burst-end, and drag-start elsewhere) already covers
     // every path that actually needs to clear it.
-    if (target && target.closest && (target.closest('.ed-te-grip-row') || target.closest('.ed-te-grip-col'))) return;
+    if (target && target.closest && (target.closest('.ed-te-grip-row') || target.closest('.ed-te-grip-col'))) {
+      // v3.0.2: only the ROW grip is the one that covers the ⠿'s approach.
+      // Testing the hit rather than reusing the branch condition matters —
+      // the column grip sits above the table's top border, nowhere near the
+      // ⠿, and lighting the gutter from there is the behaviour change this
+      // fix is scoped to avoid.
+      setGutterKeep(target.closest('.ed-te-grip-row') ? headerGripBlock() : null);
+      return;
+    }
     const blockEl = target && target.closest && target.closest('.ed-block[data-block-type="table"]');
     const tableEl = blockEl ? blockContentEl(blockEl) : null;
     const cellEl = (tableEl && target && target.closest) ? target.closest('th, td') : null;
@@ -7154,10 +7414,15 @@
       // comment for why not the whole table). Keep that grip up while still
       // in its zone; only actually hide once the pointer has left both
       // zones entirely.
-      if (pointInRowGripZone(x, y) || pointInColGripZone(x, y)) return;
+      const inRowZone = pointInRowGripZone(x, y);
+      if (inRowZone || pointInColGripZone(x, y)) {
+        setGutterKeep(inRowZone ? headerGripBlock() : null);
+        return;
+      }
       hideTableGrips();
       return;
     }
+    clearGutterKeep();
 
     const tableRect = tableEl.getBoundingClientRect();
     const rowEl = cellEl.parentElement;
@@ -7167,10 +7432,11 @@
     // Row grip: every row, including the header — the first row of a
     // markdown table IS the header, so any row must be draggable to the
     // top to become it. ONE position rule for all of them (user acceptance:
-    // 「grip 位置都一樣」) — its LEFT EDGE on the table's left border, i.e.
-    // entirely inside the table (spec §4.2 hit-test conflict 2, landed
-    // S4 T1 — see the geometry note above buildTableGrip() for the
-    // measurement that forced it), vertically centred on its own row; no
+    // 「grip 位置都一樣」) — its CENTRELINE on the table's left border, i.e.
+    // straddling it half outside / half inside the table, restored in
+    // v3.0.1 (spec §4.2 hit-test conflict 2 — see the geometry note above
+    // buildTableGrip() for the S4 T1 detour into an inset grip and how it
+    // was undone), vertically centred on its own row; no
     // header special case. The
     // one exception is a header-only table (no body rows): its single row
     // is thead's only row, and dragging it away would empty the thead —
@@ -7183,16 +7449,18 @@
       // Fallback height matches .ed-te-grip-row's own CSS height exactly
       // (28) — offsetHeight reads 0 while `hidden` (display: none) is still
       // true on the FIRST show of a hover session, before the
-      // `hidden = false` assignment below takes effect. There is no width
-      // fallback any more, and that is the point: the left edge is the
-      // table's own border, so the grip's WIDTH is not an input to its
-      // position at all. It used to be (`tableRect.left - gw / 2`), which
-      // meant the CSS width and this literal `20` had to agree for the
-      // gutter clearance to hold — exactly the drift §4.2 conflict 2 is
-      // about. The width now lives in one place only, the
-      // --ed-te-grip-row-w token in lib/md2doc.js.
+      // `hidden = false` assignment below takes effect.
       const gh = rowGrip.offsetHeight || 28;
-      rowGrip.style.left = tableRect.left + 'px';
+      // v3.0.1: back to STRADDLING the table's left border (the S4 T1 inset
+      // was a workaround for the ⠿ hit-test overlap; the ⠿/＋ pair has
+      // since moved further left via a CSS shift token in lib/md2doc.js,
+      // which removes the overlap at its source). The width is read from the
+      // token rather than written as a literal here: offsetWidth reads 0
+      // while `hidden` is still true on the first show of a hover session,
+      // and a hard-coded fallback is exactly the CSS/JS drift the token
+      // exists to prevent.
+      const gw = rowGrip.offsetWidth || gripRowWidthPx();
+      rowGrip.style.left = (tableRect.left - gw / 2) + 'px';
       rowGrip.style.top = (r.top + r.height / 2 - gh / 2) + 'px';
       rowGrip.hidden = false;
     } else {