@helping-ai-workflow/md2doc 2.11.1 → 2.12.0

package/lib/editor/indent-clamp.js

@@ -30,7 +30,12 @@
   //                  §3.4's global convention). For a multi-block operation
   //                  this is the SMALLEST old indent in the set — anchoring on
   //                  the first member instead drives later members negative on
-  //                  a delete and no-ops an entire batch Tab.
+  //                  a delete (§3.4 rule 3's first worked failure). It is the
+  //                  bound for the blocks BELOW the set only; how far the set
+  //                  ITSELF may move is a separate question the caller answers
+  //                  (client.js batchIndentDelta(), which since the 2026-08-31
+  //                  D1 review takes the minimum head-room across ALL members,
+  //                  not the head-room of this shallowest one).
   //   opts.removed          — the operated block(s) no longer exist.
   //   opts.operatedBecomes  — the operated block is still there but is no
   //                           longer a list item (§3.3 conversion); the value

package/lib/editor/selection.js

@@ -0,0 +1,204 @@
+'use strict';
+/* Spec §3.3 / §3.6 / §4.4 — block 多選的純模型.
+   UMD, same shape as indent-clamp.js: `require`-able in node for the unit
+   tests, and injected into the editor page as `window.md2docSelection`. */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.md2docSelection = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  // A selection's identity is a LINE RANGE — never block ids, never DOM nodes.
+  // buildBlockMap() renumbers every id from 0 on every render (blockmap.js:170)
+  // and every batch operation triggers a full rerenderAll(), so an id or an
+  // element held across a commit is a dangling reference into a document that
+  // no longer exists. Every post-commit recovery path already in client.js
+  // (blockElAtLine, reresolveBlockEl, focusBlockAtLine) goes through startLine
+  // for exactly this reason. Nothing in this file reads the DOM, and nothing
+  // outside it may hand this file an id.
+  //
+  //   a selection   — { anchorLine, focusLine }, or null for "nothing selected"
+  //   a block       — a record from buildBlockMap(): { id, type, startLine,
+  //                   endLine, ... }. Read here for startLine/endLine only;
+  //                   `id` is passed through untouched for the caller's own use.
+  //   `blocks`      — the whole live block list, in document order.
+
+  // ── the no-line exclusion ────────────────────────────────────────────
+  // buildBlockMap emits a block for the OUTER item of a same-line nest
+  // ("- - a" -> outer {startLine:3, endLine:2}, inner {startLine:3,
+  // endLine:3}), and its range is INVERTED because it owns no source line of
+  // its own. Such a block has no line for a range to touch, so it can never be
+  // a member of a line-range selection. This is the same predicate as
+  // blockOwnsNoLine() in client.js:928, which is the guard every structural
+  // path in the editor already checks before it writes bytes.
+  function ownsALine(b) {
+    return !!b && typeof b.startLine === 'number' && typeof b.endLine === 'number'
+      && b.endLine >= b.startLine;
+  }
+
+  function lineOf(v) {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+
+  // ── normalize ────────────────────────────────────────────────────────
+  // Orders anchor/focus into the {startLine, endLine} shape the block records
+  // and the UndoStack op shape already use, so the two never have to be
+  // mentally converted at a call site. Returns null rather than a NaN range
+  // for "no selection" — a NaN range compares false against everything and
+  // would silently produce an empty member set that looks like a real answer.
+  function normalize(sel) {
+    if (!sel) return null;
+    const a = lineOf(sel.anchorLine);
+    const f = lineOf(sel.focusLine);
+    if (a === null || f === null) return null;
+    return { startLine: Math.min(a, f), endLine: Math.max(a, f) };
+  }
+
+  // ── membership ───────────────────────────────────────────────────────
+  // Membership is INTERSECTION, not containment: a multi-line block touched
+  // anywhere is wholly selected. Block selection has no partial state (§3.6 —
+  // the visual is a tint over whole blocks), so a code fence whose middle line
+  // is in range is in the set exactly as much as a one-line paragraph is.
+  // Returns block RECORDS in document order, never ids and never elements.
+  function membersOf(sel, blocks) {
+    const r = normalize(sel);
+    if (!r) return [];
+    return (blocks || []).filter(
+      (b) => ownsALine(b) && b.startLine <= r.endLine && b.endLine >= r.startLine);
+  }
+
+  // There is deliberately NO per-block `isSelected()` here. One existed until
+  // 2026-08-31 and never had a production caller in `lib/`: every paint and
+  // every operation asks membersOf() for the whole set at once, because a batch
+  // needs the set's contiguity and its index range, not N independent yes/no
+  // answers. Its assertions were all over SINGLE-line blocks, so the
+  // intersection-not-containment rule was pinned by membersOf()'s multi-line
+  // fixture alone and nothing was lost by removing it. A future caller that
+  // genuinely wants one block's answer should re-add it WITH that caller and
+  // with a multi-line fixture, rather than inherit an untested export.
+
+  // ── extendTo ─────────────────────────────────────────────────────────
+  // Shift+Click and a drag both move the FOCUS and keep the anchor where the
+  // gesture started; that is what makes a selection reversible by dragging
+  // back. With no prior selection there is no anchor to keep, so the gesture
+  // starts one collapsed at that line.
+  function extendTo(sel, line) {
+    const l = lineOf(line);
+    if (l === null) return sel || null;
+    const a = sel ? lineOf(sel.anchorLine) : null;
+    return { anchorLine: a === null ? l : a, focusLine: l };
+  }
+
+  // ── stepFocus ────────────────────────────────────────────────────────
+  // §4.4's Shift+↑↓. Moves by BLOCK, not by line: blocks do not tile the
+  // document (blank separator lines belong to nothing), so a per-line step
+  // would park the focus on a line that owns no block and collapse the set to
+  // nothing on the way past. Blocks that own no source line are skipped for
+  // the same reason membersOf() excludes them — landing on one would leave a
+  // selection whose member set is empty.
+  //
+  // Clamped at both ends: stepping past either end is a no-op, never an error
+  // and never a wrap. `dir` is any negative number for up, anything else down.
+  function stepFocus(sel, blocks, dir) {
+    if (!sel) return sel || null;
+    const nav = (blocks || []).filter(ownsALine);
+    if (!nav.length) return sel;
+    const focus = lineOf(sel.focusLine);
+    if (focus === null) return sel;
+    const step = dir < 0 ? -1 : 1;
+
+    // The focus normally sits exactly on a block's startLine, because that is
+    // what this function and the gesture handlers write. If it does not (a
+    // caller resolved a raw click y-coordinate, say), take the nearest block
+    // at or after it, and the last block when the line is past the end.
+    let i = nav.findIndex((b) => b.startLine === focus);
+    if (i === -1) i = nav.findIndex((b) => b.startLine > focus);
+    if (i === -1) i = nav.length - 1;
+
+    const j = Math.max(0, Math.min(nav.length - 1, i + step));
+    return { anchorLine: sel.anchorLine, focusLine: nav[j].startLine };
+  }
+
+  // ── §3.3's membership rule ───────────────────────────────────────────
+  // "grip 在選取集合內 → 作用整個集合；grip 在集合外 → 先把集合換成該單一
+  // block 再作用." One helper so every operation asks the question the same
+  // way instead of each menu handler re-deriving it.
+  //
+  // `opBlock` MUST be a record out of `blocks` — identity is by reference, not
+  // by id (this module never touches ids) and not by line tuple (a nest three
+  // deep like "- - - a" produces two structurally identical phantoms, so a
+  // tuple compare is genuinely ambiguous). A record from anywhere else answers
+  // 'single', which is the conservative direction: it operates on one block
+  // rather than silently on N.
+  //
+  // "By reference" is a TESTED contract, not a description of the current line
+  // of code. `id` is passed through untouched and never compared, so a shallow
+  // COPY of a member — same id, same lines, different object — is a different
+  // block here and answers 'single'. test/selection.test.js pins exactly that
+  // case, because it is the only fixture that separates this from
+  // `members.some((m) => m.id === opBlock.id)`: every other fixture in the
+  // suite hands in a record straight out of `blocks`, where the two agree.
+  //
+  // A selection of exactly the grip block is 'batch' with one member, not a
+  // fallthrough to 'single'. The two answers are byte-identical for a single
+  // block today, but a caller that special-cased size 1 would drift the moment
+  // batch and single paths diverge.
+  function resolveMembership(sel, blocks, opBlock) {
+    const members = membersOf(sel, blocks);
+    if (opBlock && members.indexOf(opBlock) !== -1) return { mode: 'batch', members };
+    return { mode: 'single', members: opBlock ? [opBlock] : [] };
+  }
+
+  // ── collapseTo ───────────────────────────────────────────────────────
+  // §3.3: "操作後集合塌縮為「操作結果所涵蓋的行區間」". Every structural
+  // operation declares the line range it produced; rerenderAll() re-derives
+  // the member set from that range against the freshly built block list. §4.4:
+  // if the range does not resolve, the selection is CLEARED rather than left
+  // dangling — an operation that removed everything it touched declares an
+  // empty (inverted) range, and that is not a selection of one line.
+  function collapseTo(range) {
+    if (!range) return null;
+    const s = lineOf(range.startLine);
+    const e = lineOf(range.endLine);
+    if (s === null || e === null || e < s) return null;
+    return { anchorLine: s, focusLine: e };
+  }
+
+  // ── spanIsContiguous ─────────────────────────────────────────────────
+  // Batch convert/delete/duplicate rewrite their single-item entry points to
+  // take ONE contiguous index range — a loop would re-render between items and
+  // invalidate every id in between, which is the defect class recorded at
+  // client.js:3298 and :4806. This is the gate that says a set can be
+  // expressed that way.
+  //
+  // Indices are taken over the WHOLE `blocks` list, phantoms included. A
+  // no-line phantom sitting between two members ('- a\n- - b\n- c\n' ->
+  // li{1,1} | phantom{2,1} | li{2,2} | li{3,3}) is never a member, but it IS
+  // in the DOM run a batch operation would slice, and every structural path
+  // already refuses a phantom (blockOwnsNoLine). Reporting false there hands
+  // the caller a refusal instead of a range it cannot honour.
+  function spanIsContiguous(members, blocks) {
+    const list = members || [];
+    if (list.length <= 1) {
+      // 0 members has no gap to find; the caller checks emptiness itself,
+      // because "nothing selected" and "a set with a hole in it" deserve
+      // different messages.
+      return list.every((m) => (blocks || []).indexOf(m) !== -1);
+    }
+    const idx = list.map((m) => (blocks || []).indexOf(m));
+    if (idx.some((i) => i < 0)) return false;
+    idx.sort((a, b) => a - b);
+    for (let k = 1; k < idx.length; k++) if (idx[k] !== idx[k - 1] + 1) return false;
+    return true;
+  }
+
+  return {
+    normalize,
+    membersOf,
+    extendTo,
+    stepFocus,
+    resolveMembership,
+    collapseTo,
+    spanIsContiguous,
+  };
+});

package/lib/editor/server.js

@@ -23,6 +23,12 @@ const INDENT_CLAMP_SRC = fs.readFileSync(path.join(__dirname, 'indent-clamp.js')
 // indent-clamp.js above — it only has to land before client.js reads
 // window.md2docConvertMd.
 const CONVERT_MD_SRC = fs.readFileSync(path.join(__dirname, 'convert-md.js'), 'utf8');
+// S3 spec §3.3/§3.6/§4.4: the pure block multi-select model — line-range
+// normalization, membership, Shift+arrow stepping, the §3.3 grip rule and the
+// post-operation collapse. Same "no dependency on any other editor module"
+// property as indent-clamp.js and convert-md.js above; it only has to land
+// before client.js reads window.md2docSelection.
+const SELECTION_SRC = fs.readFileSync(path.join(__dirname, 'selection.js'), 'utf8');
 
 function readJson(req, limitBytes = 50 * 1024 * 1024) {
   return new Promise((resolve, reject) => {
@@ -159,6 +165,7 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
           `<script>${HISTORY_SRC}</script>\n` +
           `<script>${INDENT_CLAMP_SRC}</script>\n` +
           `<script>${CONVERT_MD_SRC}</script>\n` +
+          `<script>${SELECTION_SRC}</script>\n` +
           `<script>${clientJs}</script>\n`;
         // Splice at the LAST "</body>" — the document's real closing tag.
         // The first occurrence can sit inside an inlined diagram bundle's JS

package/lib/md2doc.js

@@ -2050,6 +2050,36 @@ ${itemsHtml}
      output, same precedent as the lightbox selectors above. */
   .ed-block { position: relative; cursor: pointer; }
   .ed-block:hover { outline: 1px dashed #b0b0b0; }
+  /* S3: the block-level multi-select tint (spec §3.6). rgba, never opaque —
+     §3.6 says the text underneath stays readable. #3b82f6 is the editor's
+     established blue (.ed-wys-armed:focus, .ed-li-check[data-checked="1"],
+     .ed-te-hl).
+
+     The descendant rules and their !important are not decoration, they are
+     the whole problem: <pre> (#f6f8fa), <th> (#f6f8fa), the zebra stripe
+     tr:nth-child(even) (#fafbfc) and the sticky first column (#ffffff) all
+     carry OPAQUE backgrounds, and the sticky column additionally paints at
+     z-index: 1 over anything drawn beneath it. Two of those beat a plain
+     descendant selector on specificity alone — counted:
+     .content table tbody tr:nth-child(even) td:first-child is (0,3,4)
+     against this rule's (0,3,2), and .content table tbody td:first-child is
+     (0,2,3) against the same (0,3,2) — so without !important the tint is
+     invisible on exactly the blocks a user is most likely to select. .ed-te-hl
+     needed the identical treatment for the identical reason. This ADDS rules
+     rather than reordering the sticky/zebra/header set, which CLAUDE.md says
+     wins by source order and must not be moved.
+     (No backticks in this comment: it lives inside a JS template literal.)
+
+     :focus outline is suppressed because the roving tabindex below focuses a
+     .ed-block for real (spec §4.4 wants a real focus holder, not <body>) and
+     the tint — not a second ring — is the selection's affordance. */
+  .ed-block.ed-selected { background: rgba(59, 130, 246, 0.15); }
+  .ed-block.ed-selected pre,
+  .ed-block.ed-selected th,
+  .ed-block.ed-selected tr:nth-child(even),
+  .ed-block.ed-selected tbody td:first-child,
+  .ed-block.ed-selected thead th:first-child { background: rgba(59, 130, 246, 0.15) !important; }
+  .ed-block.ed-selected:focus { outline: none; }
   /* white-space: pre-line is LOAD-BEARING, not styling — do not relax it.
      A hard-wrapped ("lazy continuation") list item's own content contains a
      real newline, and its .ed-li-text is an editing host. Under the default
@@ -2111,7 +2141,9 @@ ${itemsHtml}
   .ed-block:hover .ed-handle,
   .ed-handle:focus { opacity: 1; }
   .ed-handle:hover { background: rgba(0, 0, 0, 0.08); }
-  /* The ⠿ handle's menu: 轉換成 › / 建立副本 / 刪除 / MD 原始碼 (spec §3.7).
+  /* The ⠿ handle's menu: 轉換成 › / 建立副本 / 刪除 / MD 原始碼 (spec §3.7),
+     each led by a 16px currentColor icon (v2.12.0; drawn in
+     lib/editor/client.js's MENU_ICON_PATHS).
      Dark translucent panel, bordered rows — same visual language as
      .ed-seltb below.
 
@@ -2135,7 +2167,23 @@ ${itemsHtml}
     background: rgba(255, 255, 255, 0.08); color: inherit;
     font: inherit; font-size: 12px; line-height: 1;
     text-align: left; white-space: nowrap; cursor: pointer;
-  }
+    /* v2.12.0: a flex ROW so the icon and the label share a baseline-free
+       centre line and a fixed gap. The row is still one flex item of the
+       column above, and align-items: stretch there keeps every row the same
+       width, so S2's one-left-edge / monotonic-top invariants are untouched.
+       The submenu's own buttons carry this class and no icon; a lone text node
+       is an anonymous flex item at flex-start, i.e. exactly where text-align
+       put it. */
+    display: flex; align-items: center; gap: 8px;
+  }
+  /* Notion's own sizing. The stroke colour is NOT set here on purpose: the
+     markup carries stroke="currentColor" (lib/editor/client.js), so the icon
+     is whatever colour .ed-handle-menu's own color property is, and follows a
+     retheme for free. A hex here would break that silently. (No backticks in
+     this comment: it lives inside a JS template literal.)
+     flex: 0 0 auto because a 16px-wide flex item next to a nowrap label
+     would otherwise be the thing that shrinks. */
+  .ed-menu-icon { flex: 0 0 auto; width: 16px; height: 16px; }
   /* The 轉換成 submenu carries BOTH classes, so it inherits every rule above
      and only overrides the horizontal offset. It is a CHILD of the menu, and
      the menu is itself position:absolute, so the menu's own padding box is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
   "keywords": [
     "markdown",
@@ -36,7 +36,7 @@
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",
-    "test": "node test/md2doc.test.js && node test/blockmap.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js"
+    "test": "node test/md2doc.test.js && node test/blockmap.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/selection.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js"
   },
   "repository": {
     "type": "git",