@helping-ai-workflow/md2doc 3.2.1 → 3.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @helping-ai-workflow/md2doc
 
-> Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support.
+> Markdown → HTML / PDF renderer with WaveDrom, Mermaid, Graphviz, and draw.io support.
 
 A single global CLI (`md2doc`) you can call from any directory.
 
@@ -8,7 +8,9 @@ A single global CLI (`md2doc`) you can call from any directory.
 
 Requires Node.js 18 or higher. The first install pulls puppeteer (≈ 170 MB Chromium download); subsequent installs reuse it.
 
-Chromium is only needed for **PDF export** and the optional `--bake-svg` flag. HTML diagram rendering needs nothing extra — Graphviz runs in-process via WebAssembly, and Mermaid / WaveDrom are bundled and inlined, so diagrams render **offline with no system Graphviz and no CDN**.
+Chromium is needed for **PDF export**, for the optional `--bake-svg` flag, and for **`.drawio` diagrams**, which are always rendered to SVG at generation time. Everything else needs nothing extra — Graphviz runs in-process via WebAssembly, and Mermaid / WaveDrom are bundled and inlined.
+
+Nothing is fetched at render time or at read time: every engine, including the vendored draw.io viewer, runs locally, so documents render and read **offline with no system Graphviz, no draw.io install and no CDN**.
 
 ### Recommended: install via nvm
 
@@ -100,8 +102,8 @@ in several places grows the HTML accordingly. PDF output is unaffected.
 
 ### Viewing diagrams
 
-Click any image, Mermaid, Graphviz or WaveDrom graphic in the rendered HTML to open it
-full-screen.
+Click any image, Mermaid, Graphviz, draw.io or WaveDrom graphic in the rendered HTML to
+open it full-screen.
 
 | Input | Action |
 |---|---|
@@ -280,7 +282,7 @@ version-control-friendly.
 ### Degraded blocks: code, diagrams, images, math
 
 Blocks containing content WYSIWYG cannot represent (code fences, Mermaid/Graphviz/
-WaveDrom diagrams, images, LaTeX math, or unstyled HTML) automatically degrade to
+WaveDrom/draw.io diagrams, images, LaTeX math, or unstyled HTML) automatically degrade to
 raw-edit mode: click the block to open the raw Markdown source in a textarea, make
 your changes, then press `Ctrl+Enter` to commit or `Esc` to cancel.
 
@@ -372,9 +374,19 @@ digraph G { A -> B }
 ```
 ````
 
-All three render directly in the output (HTML or PDF), **offline and with no system dependencies**: Graphviz `dot` runs in-process via WebAssembly (no system `dot` binary required), and Mermaid / WaveDrom are bundled and inlined (no CDN). Each engine's runtime is embedded only when the document actually uses that diagram type.
+A fourth engine, **draw.io**, is referenced with image syntax rather than a code fence, because a `.drawio` file is an external artifact rather than inline source:
+
+```markdown
+![Architecture overview](arch.drawio)
+![Just the Flow sheet](arch.drawio#Flow)
+![Just the second sheet](arch.drawio#2)
+```
+
+A `.xml` file is treated as a diagram only when its root element really is `<mxfile>` or `<mxGraphModel>`; anything else falls through to the ordinary image path unchanged. `#Name` selects a sheet by name, `#N` by 1-based position (a name wins over a number). The alt text becomes the rendered box's accessible name. Multi-sheet files get a small sheet bar on hover — every sheet is baked into the output, so switching sheets involves no engine.
+
+All four render directly in the output (HTML or PDF), **offline and with no system dependencies**: Graphviz `dot` runs in-process via WebAssembly (no system `dot` binary required), Mermaid / WaveDrom are bundled and inlined (no CDN), and `.drawio` files are rendered by a vendored draw.io viewer running in a build-time headless Chromium. Each engine's runtime is embedded only when the document actually uses that diagram type — and the draw.io viewer never is, at any size, because `.drawio` diagrams are fully pre-rendered (a multi-sheet document carries only a few lines of sheet-switching script, not an engine).
 
-By default, Mermaid and WaveDrom render in the browser when the HTML is opened; pass `--bake-svg` to pre-render them to inert SVG at generation time instead (Graphviz is always pre-rendered to SVG).
+By default, Mermaid and WaveDrom render in the browser when the HTML is opened; pass `--bake-svg` to pre-render them to inert SVG at generation time instead (Graphviz and draw.io are always pre-rendered to SVG).
 
 ## Why a global CLI
 
@@ -382,4 +394,17 @@ Multiple repos used to ship copies of this script. They drifted. This package ce
 
 ## Licence
 
-MIT.
+md2doc's own source is **MIT** — see [`LICENSE`](LICENSE).
+
+The published package is not MIT-only, because it ships one vendored
+third-party file: `vendor/drawio/viewer-static.min.js`, the draw.io /
+diagrams.net viewer (v31.3.2, ~4 MB), under the **Apache License 2.0**.
+Its licence text and a per-component NOTICE travel with it, in
+[`vendor/drawio/LICENSE`](vendor/drawio/LICENSE) and
+[`vendor/drawio/NOTICE`](vendor/drawio/NOTICE).
+
+**Running a licence scan? Start at
+[`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).** It lists everything
+redistributed inside the tarball, including the components bundled inside
+the draw.io viewer itself (DOMPurify, pako, spin.js, Rough.js), and says
+how each finding was established.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,44 @@
+# Third-party notices
+
+md2doc's own source code is licensed under the MIT License — see
+[`LICENSE`](LICENSE). `"license": "MIT"` in `package.json` refers to that
+code and only to that code.
+
+**The published npm package also contains code that is not md2doc's and
+is not MIT.** If you are running a licence scan, this is the file you
+want; the per-component detail is one level down, next to the artifact it
+describes.
+
+## Vendored at rest (inside the published tarball)
+
+| Path | What | Licence | Detail |
+|---|---|---|---|
+| `vendor/drawio/viewer-static.min.js` | draw.io / diagrams.net viewer, v31.3.2, 4,151,717 bytes | **Apache License 2.0** | [`vendor/drawio/LICENSE`](vendor/drawio/LICENSE), [`vendor/drawio/NOTICE`](vendor/drawio/NOTICE) |
+
+That single 4 MB file is a verbatim copy of
+`src/main/webapp/js/viewer-static.min.js` from
+[jgraph/drawio](https://github.com/jgraph/drawio) at tag `v31.3.2`
+(sha256 `2fabaaa3e28d5f80f943285a2ce19c22cf870857203255f1e0347ef93693a297`).
+md2doc executes it only inside a build-time headless Chromium, to turn
+`.drawio` references into inline SVG; it is never emitted into output
+HTML and never fetched over the network.
+
+The Apache-2.0 text ships **inside `vendor/drawio/`**, next to the file it
+covers, rather than only at the repository root — so it survives being
+copied, vendored or extracted along with the artifact.
+
+That bundle is itself not licence-homogeneous. It contains DOMPurify
+3.4.13 (Apache-2.0 OR MPL-2.0), pako 2.2.0 (MIT AND Zlib), spin.js 2.0.0
+(MIT) and Rough.js 4.6.6 (MIT).
+[`vendor/drawio/NOTICE`](vendor/drawio/NOTICE) records each one's version,
+licence, where inside the bundle it sits, **how that was established**,
+and which of those findings rest on provenance rather than on a
+declaration in the artifact itself.
+
+## Runtime dependencies (installed by npm, not vendored)
+
+md2doc's `dependencies` (marked, mermaid, wavedrom, katex, puppeteer,
+turndown, `@hpcc-js/wasm-graphviz`) are ordinary npm packages: they are
+resolved into your `node_modules` by your own installer, carry their own
+licence files there, and are not redistributed inside md2doc's tarball.
+They are out of scope for this file.

package/lib/drawio.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// drawio (.drawio / .xml) 來源的判別與頁面解析。
+//
+// 這一支刻意不碰 marked、不碰瀏覽器 —— 判別與頁名是純字串處理，可以用純函式
+// 測；真的需要 headless Chromium 的只有 bakeDrawioSvg()（見同檔下方）。
+//
+// 為什麼不用 XML parser：md2doc 不引進新的 runtime 依賴，而這裡要回答的問題
+// （根元素是什麼、有哪些 <diagram name>）用受控的 regex 就夠。輸入是本機檔案
+// 而不是網路內容，且判別失敗的後果是「當成普通圖片、原樣留著」——不是安全邊界。
+
+// 開頭的 XML 宣告、DOCTYPE、註解、空白都要跳過，才看得到真正的根元素。
+const LEADING_NOISE = /^(?:\s|<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)*/;
+
+// 根元素判別：兩處（isDrawioXml / pageNamesOf）共用同一顆函式，避免各自維護
+// 一份「跳過前導雜訊」的 regex 而在 DOCTYPE / 自我封閉標籤上悄悄長歪。
+//
+// 標籤後面接的字元用 `[\s\/>]` 而不是 `[\s>]`：自我封閉的 `<mxfile/>` 或
+// `<mxGraphModel/>`（沒有任何屬性、也沒有子節點）在真實檔案裡少見，但一旦
+// 出現，`[\s>]` 會因為下一個字元是 `/` 而漏判成「不是 drawio」——用
+// `foo(root, 'not a diagram')` 這種輸入實測會踩到。同時要擋掉
+// `<mxfilex>` / `<mxGraphModelFoo>` 這種前綴相同、但其實是別的標籤的輸入，
+// 所以字元類仍然是白名單而不是「以 mxfile 開頭就算」。
+function rootKindOf(text) {
+  const rest = String(text || '').replace(LEADING_NOISE, '');
+  if (/^<mxfile[\s\/>]/.test(rest)) return 'mxfile';
+  if (/^<mxGraphModel[\s\/>]/.test(rest)) return 'mxGraphModel';
+  return null;
+}
+
+function isDrawioXml(text) {
+  return rootKindOf(text) !== null;
+}
+
+function pageNamesOf(text) {
+  const s = String(text || '');
+  if (rootKindOf(s) !== 'mxfile') {
+    // <mxGraphModel> 直接當一頁，沒有名字。
+    return [''];
+  }
+  const names = [];
+  const re = /<diagram\b([^>]*)>/g;
+  let m;
+  while ((m = re.exec(s)) !== null) {
+    const nameAttr = /\bname\s*=\s*"([^"]*)"/.exec(m[1]);
+    names.push(nameAttr ? nameAttr[1] : '');
+  }
+  return names.length ? names : [''];
+}
+
+function resolvePageIndex(names, fragment) {
+  const frag = String(fragment == null ? '' : fragment);
+  if (!frag) return 0;
+  const byName = names.indexOf(frag);
+  if (byName >= 0) return byName;
+  if (/^\d+$/.test(frag)) {
+    const n = Number(frag);
+    if (n >= 1 && n <= names.length) return n - 1;
+  }
+  return 0;
+}
+
+// v3.4.0 batch2 Task 6 fix round 1 (review F7) — the identity of a referenced
+// `.drawio`/`.xml` file's bytes AS THIS PROCESS LAST SAW THEM.
+//
+// (mtimeMs, size) rather than mtimeMs alone: this project's own environment
+// notes document a filesystem (WSL DrvFs over /mnt/c) that degrades and
+// behaves oddly around timestamps, and coarse-granularity mtimes are also the
+// norm on SMB shares — a rewrite landing inside the same tick as the recorded
+// one compares equal and is never reported. Size costs nothing extra (the
+// Stats object is already in hand) and closes that hole for every edit that
+// changes the file's length.
+//
+// Returns null when the file cannot be stat'd at all. That deliberately
+// collapses "deleted" and "unreadable" (EACCES, an editor's atomic-replace
+// window) into one value: for staleness they are the same answer — "the bytes
+// you baked are no longer the bytes on disk" — and the caller has no repair
+// action that would differ between them. The cost is diagnostic only.
+function drawioStampOf(absPath) {
+  try {
+    const st = fs.statSync(absPath);
+    return String(st.mtimeMs) + '/' + String(st.size);
+  } catch (e) {
+    return null;
+  }
+}
+
+const VIEWER_PATH = path.join(__dirname, '..', 'vendor', 'drawio', 'viewer-static.min.js');
+
+// 每一頁烤成一份 SVG。
+//
+// 為什麼是 headless Chromium 而不是 Node 裡的某個函式庫：drawio 的版面
+// 計算（自動換行、文字度量、stencil 形狀）依賴真正的瀏覽器排版引擎，
+// 沒有等價的 Node 實作。md2doc 已經有 puppeteer（PDF 匯出在用），所以這
+// 不是新依賴。
+//
+// 遠端路徑預設值必須在 viewer 載入之前就改寫掉。viewer 自己的寫法是
+// `window.PROXY_URL = window.PROXY_URL || "https://viewer.diagrams.net/proxy"`
+// 這種形式 —— `||` 代表先設好的值會勝出，所以 addScriptTag 之前先 evaluate。
+//
+// 數字要講清楚，因為下面那份清單看起來很像「全部」：viewer 裡這種形狀的
+// 遠端預設值共有 14 個（11 個指向 diagrams.net、3 個指向 github/gitlab），
+// 下面只中和了靜態渲染路徑真的會讀到的 8 個，外加 2 個載入旗標。沒中和的
+// 6 個（EXPORT_URL、VSS_CONVERT_URL、DRAWIO_LIGHTBOX_URL、DRAWIO_GITHUB_URL、
+// DRAWIO_GITHUB_API_URL、DRAWIO_GITLAB_URL）屬於匯出／格式轉換／git 整合功能，
+// GraphViewer.createViewerForElement() 這條路不會叫到它們。
+//
+// 所以「輸出離線可用」這個保證**不是**靠這份清單完整，而是靠 test/drawio.test.js
+// 對產出斷言沒有任何遠端 URL。要加功能而動到 viewer 的其他能力時，先重新量，
+// 不要假設這 8 個就是全部。
+async function bakeDrawioSvg(xmlText, opts) {
+  const o = opts || {};
+  const names = pageNamesOf(xmlText);
+  let browser = o.browser;
+  let ownBrowser = false;
+  if (!browser) {
+    const puppeteer = require('puppeteer');
+    browser = await puppeteer.launch({
+      headless: 'new',
+      args: ['--no-sandbox', '--disable-setuid-sandbox',
+             '--disable-crash-reporter', '--disable-dev-shm-usage'],
+    });
+    ownBrowser = true;
+  }
+  const page = await browser.newPage();
+  try {
+    await page.setContent('<!doctype html><html><body></body></html>');
+    await page.evaluate(() => {
+      // 全部指向 about:blank 之下的相對路徑：viewer 取不到就用內建的
+      // 基本形狀，而不是去打網路。md2doc 的輸出必須離線可用。
+      window.PROXY_URL = '';
+      window.STYLE_PATH = '';
+      window.SHAPES_PATH = '';
+      window.STENCIL_PATH = '';
+      window.DRAW_MATH_URL = '';
+      window.GRAPH_IMAGE_PATH = '';
+      window.mxImageBasePath = '';
+      window.mxBasePath = '';
+      window.mxLoadStylesheets = false;
+      window.mxLoadResources = false;
+    });
+    await page.addScriptTag({ path: VIEWER_PATH });
+
+    const out = [];
+    for (let i = 0; i < names.length; i++) {
+      const svg = await page.evaluate((xml, pageIndex) => {
+        const el = document.createElement('div');
+        el.className = 'mxgraph';
+        // width 不設會讓 GraphViewer 把圖縮到容器寬度。
+        el.setAttribute('data-mxgraph', JSON.stringify({
+          xml: xml, page: pageIndex, highlight: '#0000ff',
+          toolbar: null, resize: true, nav: false,
+        }));
+        document.body.appendChild(el);
+        window.GraphViewer.createViewerForElement(el);
+        const svgEl = el.querySelector('svg');
+        const html = svgEl ? svgEl.outerHTML : null;
+        el.remove();
+        return html;
+      }, xmlText, i);
+
+      if (!svg) {
+        throw new Error('drawio viewer produced no SVG for page ' + (i + 1) +
+          ' (' + (names[i] || 'unnamed') + ')');
+      }
+      out.push(svg);
+    }
+    return out;
+  } finally {
+    await page.close();
+    if (ownBrowser) await browser.close();
+  }
+}
+
+module.exports = { isDrawioXml, pageNamesOf, resolvePageIndex, bakeDrawioSvg, drawioStampOf };

package/lib/editor/blockmap.js

@@ -12,6 +12,79 @@ function trimmedLineCount(raw) {
   return content === '' ? 1 : content.split('\n').length;
 }
 
+// v3.4.0 (backlog #13, closing the "改動前後相同" observation for real):
+// MEASURED on marked 14.1.4, a top-level 'paragraph' token's `raw` can carry
+// an internal newline that names NO real blank line in the source. Minimal
+// case: 'a\n\tb\n---\n- x\n- y\n\ntail\n' — the paragraph's raw comes back as
+// 'a\n\n\tb\n' (3 newlines) for what is 2 real source lines ('a', a TAB- or
+// >=4-space-over-indented lazy continuation 'b'); every block from the '---'
+// onward then names the line ABOVE its real one. This is not "only literal
+// '---'" — a table SEPARATOR row immediately after the same over-indented
+// continuation ('|---|', ':---') reproduces it too, and the trigger tracks
+// the count of over-indented continuation lines, not any single terminator
+// (see runs/task11-item13-scope-hunt*.js: 195+ cases across continuation
+// width x repeat-count x fifteen terminators — corruption only where the
+// line right after the continuation is dash/equals-shaped, matching
+// whatever internal check marked runs to decide a following line MIGHT be a
+// setext-heading underline; every other terminator tried — the other hr
+// markers, headings, blockquotes, fences, header-led tables, lists, a
+// genuine setext '===' — left raw uncorrupted in every case). A 'heading'
+// token was TRIED as a second covered type (it goes through the same marked
+// code path — setext heading construction IS this ambiguity's positive
+// case) and REJECTED: test/blockmap.test.js's own first fixture ('# Title\n\n
+// Para one.\n\n…') broke immediately, because ATX headings legitimately FOLD
+// a trailing blank-line run into their own raw when nothing else does (raw
+// '# Title\n\n' for a heading followed by one blank line, with no separate
+// 'space' token) — exactly the behaviour this file's own header comment
+// documents ("A token's raw may include trailing newlines … folded in").
+// `t.text` for a heading is just its own single line of prose ("Title", 0
+// newlines) and has no way to reconstruct how many blank lines got folded
+// after it, so text-based counting silently DROPS that fold and lands the
+// next block one line early. Paragraphs do not fold trailing blanks this way
+// (MEASURED: a blank-line run after a paragraph always comes back as its own
+// separate 'space' token, at EOF and mid-document alike — see
+// runs/task11-item13-parafold.js), which is exactly why paragraphs are safe
+// to cover here and headings are not.
+//
+// This file's own item-level code already named the general family: a lazy
+// continuation's `text`-token raw is SYNTHESISED ("a lazy continuation comes
+// back as \"x\n\ncont\n\" (three newlines) for two source lines" — see
+// childListStartOffsets()'s header comment), which is why that code never
+// trusts a `text` token's raw for cursor advancement. This is the same
+// defence at buildBlockMap()'s TOP level, where a top-level 'paragraph' is
+// marked's equivalent of an in-item lazy continuation — the top level had no
+// corresponding defence because the header comment's own stated basis for
+// trusting top-level raws ("at top level the raws are faithful source
+// slices") is exactly the assumption this case disproves.
+//
+// The fix does not detect corruption and fall back conditionally; it simply
+// never counts newlines out of a 'paragraph' token's `raw` at all. `t.text`
+// — marked's own dedented join of the token's real content lines, e.g.
+// "a\nb" for the fixture above — was MEASURED to stay correct in every
+// corrupted case found in the sweep: its newline count always equals (real
+// source lines consumed - 1), carrying none of the synthetic blank lines
+// `raw` picks up. And on every UNCORRUPTED case, `text`-based and
+// `raw`-based counting agree exactly — MEASURED via a direct before/after
+// diff of buildBlockMap()'s own OUTPUT (not just the raw newline count) over
+// every fixture already in test/blockmap.test.js plus a 60000-document
+// random line-soup fuzz corpus (see runs/task11-item13-fuzz-oracle.js and
+// the report) — so there is no accuracy cost paid on the common path.
+//
+// Every OTHER top-level token type is left on the original raw-based
+// computation, unconditionally: the sweep found no corruption outside
+// 'paragraph', and 'space' tokens in particular NEED their raw's FULL,
+// untrimmed newline count (to skip a multi-blank-line run) — trimmedLineCount()
+// or text-based counting would get that case wrong on purpose, not by
+// oversight.
+function topLevelLineInfo(t) {
+  if (t.type === 'paragraph' && typeof t.text === 'string') {
+    const contentNewlines = (t.text.match(/\n/g) || []).length;
+    const endsWithNewline = t.raw.charAt(t.raw.length - 1) === '\n';
+    return { span: contentNewlines + 1, rawNewlines: contentNewlines + (endsWithNewline ? 1 : 0) };
+  }
+  return { span: trimmedLineCount(t.raw), rawNewlines: (t.raw.match(/\n/g) || []).length };
+}
+
 // Recursively emit one `li` block per list item at every depth.
 // Recursion order (mirrored by Task 4's render walk):
 //   1. Push the item's own block.
@@ -63,35 +136,123 @@ function indexOfAtLineStart(content, needle, from) {
   return at;
 }
 
+// The search above is a byte-for-byte `indexOf`, and marked does not hand back
+// bytes that match byte-for-byte: a nested list token's `raw` has the trailing
+// spaces stripped off its LAST line while the enclosing `item.text` keeps them.
+// MEASURED on this repo's marked, for '# H\n\n- alpha\n  - beta\n  - \n- gamma\n':
+//
+//   item.text          "alpha\n- beta\n- "      <- trailing space kept
+//   child list tk.raw  "- beta\n-\n"            <- trailing space gone, \n added
+//
+// so `content.indexOf(tk.raw)` was -1, and the guessed offset 0 that followed
+// shifted every descendant's startLine UP one line. That is not a corner: the
+// markdown the CLIENT serialises mid-session contains the shape:
+// '# H\n\n- alpha\n  - beta\n    - \n- gamma\n' was captured coming back from
+// client.js during a test/editor-journey.test.js run and mapped to an inverted
+// range under the old search. Ordinary authored markdown does it too — an
+// everyday flat-plus-nested list corrupts the moment a trailing space lands on
+// its nested line. Neither of those two strings is itself a fixture — they came
+// out of a capture harness and a mutation sweep that are not in the repo. What
+// IS pinned, and what to read instead, is the shape FAMILY — grep 'trailing
+// space' in test/blockmap.test.js for the range assertions, and 'eats the item
+// above' in test/editor-journey.test.js for the gestures that used to do
+// exactly that.
+//
+// Both sides are put through the same normalisation before the search: trailing
+// spaces and tabs are dropped from every line. Two properties are relied on,
+// and they are different from each other:
+//
+//   LINE OFFSETS SURVIVE. The transform only ever removes characters that are
+//   not '\n', so it cannot change a line count — a character offset found in
+//   the normalised copy names the same LINE offset it would have named in the
+//   original, and a line offset is the only thing this function returns.
+//
+//   SUBSTRINGS SURVIVE. If the needle occurred in the content before, the
+//   normalised needle occurs in the normalised content. Every '\n' inside the
+//   needle is the same '\n' in the content, so a space run sitting before it is
+//   stripped identically on both sides; the two can only disagree at the
+//   needle's own END, where the needle may lose a trailing run the content
+//   keeps. That only makes the needle SHORTER, and a prefix of a substring is
+//   still a substring. (Byte identity of two equal strings under a shared
+//   transform is the wrong lemma here — it says nothing about a needle whose
+//   surroundings differ from its own end.)
+//
+// The needle additionally loses its trailing newlines (`\n+$`), because the raw
+// of a token that ends the item carries a terminator `item.text` does not have.
+// That leaves `pos` on the newline (or newlines) that ended the consumed token
+// rather than after them, so both searches below start earlier than they used
+// to and a match could in principle land on one of those bytes. One argument
+// rules that out for both searches at once, so it is the only one stated here:
+// to match at a position occupied by a newline, the NEEDLE would have to begin
+// with a newline. MEASURED over the journey capture plus a synthetic sweep of
+// nested lists (blank lines, fenced code, blockquotes, tab indents, ordered and
+// task markers): no nested list token's `raw` began with '\n'. Labelled
+// MEASURED and not invariant — nothing downstream may assume it.
+function stripTrailingLineSpace(s) {
+  return s.replace(/[ \t]+$/gm, '');
+}
+
+// Returns { offsets, unlocatable }. `offsets` keeps its old contract exactly:
+// one entry per child list token, always, in order. `unlocatable` is true when
+// at least one of those entries is a GUESS rather than a found position —
+// see pushListItemBlocks(), which is what acts on it.
 function childListStartOffsets(item) {
-  const content = typeof item.text === 'string' ? item.text : '';
+  const content = stripTrailingLineSpace(
+    typeof item.text === 'string' ? item.text : ''
+  );
   const offsets = [];
+  let unlocatable = false;
   let pos = 0;
   for (const tk of item.tokens || []) {
+    const needle = stripTrailingLineSpace(typeof tk.raw === 'string' ? tk.raw : '')
+      .replace(/\n+$/, '');
     if (tk.type === 'list') {
-      let at = indexOfAtLineStart(content, tk.raw, pos);
-      if (at < 0) at = content.indexOf(tk.raw, pos);
+      // An empty needle would make `indexOf` answer `pos` for any content, i.e.
+      // report a find that was never made. Treated as not-found instead.
+      let at = needle === '' ? -1 : indexOfAtLineStart(content, needle, pos);
+      if (at < 0 && needle !== '') at = content.indexOf(needle, pos);
       // Unlocatable (a shape this walk does not model): fall back to the line
       // the cursor is already on. Never skip — a missing block desynchronises
       // the render walk and takes the whole document down.
+      if (at < 0) unlocatable = true;
       offsets.push(at < 0 ? lineOffsetAt(content, pos) : lineOffsetAt(content, at));
-      if (at >= 0) pos = at + tk.raw.length;
+      if (at >= 0) pos = at + needle.length;
       continue;
     }
     // `text` raws are synthesised; everything else is a faithful slice and is
     // consumed so later searches start beyond it.
     if (tk.type === 'text') continue;
-    const at = content.indexOf(tk.raw, pos);
-    if (at >= 0) pos = at + tk.raw.length;
+    // BEHAVIOUR CHANGE, small and deliberate: before the trailing-newline trim
+    // above, a `space` token (a blank-line run inside the item) had a needle of
+    // pure newlines and this branch consumed it, advancing `pos` past the blank
+    // run. Trimmed, that needle is '' — and `''.indexOf` answers `pos` for any
+    // content, i.e. a find that was never made — so the token is skipped and
+    // `pos` stays where it was, which means every later search starts earlier
+    // than it used to.
+    //
+    // What establishes that this is harmless is an ABLATION, not an argument: a
+    // copy of this function that still advances `pos` past an empty needle
+    // (using the untrimmed raw) produced block maps identical to these on every
+    // document of the journey capture, of its trailing-space mutations, and of a
+    // synthetic nested-list sweep. The same sweeps also show `space` was the
+    // only token type whose needle ever collapsed to '' — which is the only type
+    // that CAN, its raw being whitespace by construction.
+    if (needle === '') continue;
+    const at = content.indexOf(needle, pos);
+    if (at >= 0) pos = at + needle.length;
   }
-  return offsets;
+  return { offsets, unlocatable };
 }
 
-function pushListItemBlocks(listToken, cursor, indent, blocks, nextId) {
+// `inheritedUnlocatable` is how an item degrades its whole subtree: see the
+// `degraded` note below the block literal.
+function pushListItemBlocks(listToken, cursor, indent, blocks, nextId, inheritedUnlocatable) {
   for (const item of listToken.items) {
     const childListTokens = item.tokens.filter((t) => t.type === 'list');
     const totalSpan = trimmedLineCount(item.raw);
-    const childLineOffsets = childListStartOffsets(item);
+    const located = childListStartOffsets(item);
+    const childLineOffsets = located.offsets;
+    const degraded = !!inheritedUnlocatable || located.unlocatable;
 
     // The item's OWN block covers its contiguous leading lines only — up to its
     // first child.
@@ -136,12 +297,58 @@ function pushListItemBlocks(listToken, cursor, indent, blocks, nextId) {
     // is never editable and no commit path can start on it. If you add a
     // consumer that walks block ranges, either honour that emptiness or check
     // for it; do not assume `startLine <= endLine`.
+    //
+    // DEGRADED SUBTREE. When childListStartOffsets() could not FIND a child
+    // list and had to guess its line, every line number computed from that
+    // guess is fiction, and the fiction does not stop at the parent: the guess
+    // is the offset each descendant's cursor is built from, so an entire nested
+    // run gets addresses belonging to the lines ABOVE it. That is not an
+    // abstract risk — it is the shape a user is in between typing a nested
+    // marker and typing its first character, and the observed result was that
+    // client.js's bystanderCarryOver() replayed the WRONG source line over a
+    // sibling: '- alpha\n  - beta\n  - \n' committed back as
+    // '- alpha\n  - alpha\n-\n', with beta gone from the file.
+    //
+    // So the whole subtree — this item and, via `inheritedUnlocatable`, every
+    // item below it — is given an EMPTY range (endLine === startLine - 1)
+    // rather than a wrong one. Empty is a shape this codebase already defines
+    // and already defends: client.js's blockOwnsNoLine() is `endLine <
+    // startLine`, and the functions that call it directly are
+    // canWysiwygForLi() (arming), openRawEditor() (the raw textarea),
+    // insertBlockBelow() (the ＋ paths, twice — anchor and subtree tail),
+    // resolveGutterOperands() (twice — where the ⠿ menu's 刪除 and every other
+    // grip operation resolves its targets, reached from deleteBlockViaGutter()
+    // through deleteBlockViaGutterBody()) and bystanderCarryOver() (the replay
+    // of untouched siblings). So an empty range refuses at every arming and
+    // commit boundary instead of writing somebody else's line.
+    //
+    // Every block is still PUSHED. lib/md2doc.js's edit-mode render walk
+    // consumes blocks[] in lockstep and throws on `biRef.v !== blocks.length`,
+    // so a skipped block takes the whole document down; an empty range costs
+    // that check nothing, and server.js's assertBlockRangesFit() only rejects
+    // `endLine > lines.length`, which a shortened range can never trip.
+    //
+    // `unlocatable` marks these records so the client can say WHY it refused.
+    // Same-line nesting ('- - a') produces an empty range too, and it is a
+    // legitimate, fully-modelled shape — it does not get the flag, and it
+    // keeps its own existing wording.
+    //
+    // ACCEPTED RESIDUAL: the degraded subtree's source lines end up owned by no
+    // block at all. lib/editor/selection.js's `ownsALine()` is
+    // `b.endLine >= b.startLine`, and membersOf() filters on it, so those lines
+    // fall out of every block selection — a drag across them selects the blocks
+    // either side and nothing in between. That is the price of emptying the
+    // subtree instead of corrupting it, and it is the right trade: a wrong
+    // range writes over somebody else's line, an absent one only cannot be
+    // selected. Unreachable as this is written (no markdown found so far makes
+    // the search fail); recorded here so whoever first reaches it meets this
+    // in the code rather than in the field.
     const ownSpan = childLineOffsets.length ? childLineOffsets[0] : totalSpan;
     const block = {
       id: nextId.v++,
       type: 'li',
       startLine: cursor,
-      endLine: cursor + ownSpan - 1,
+      endLine: degraded ? cursor - 1 : cursor + ownSpan - 1,
       // Two independent axes (RULING F-N): GFM allows `1. [ ] a`, so
       // ordered-ness and task-ness cannot share one field. `listType` is the
       // LIST's type; `task` is the ITEM's.
@@ -150,12 +357,13 @@ function pushListItemBlocks(listToken, cursor, indent, blocks, nextId) {
       indent,
     };
     if (item.task) block.checked = !!item.checked;
+    if (degraded) block.unlocatable = true;
     blocks.push(block);
     // Every child is emitted, unconditionally: blocks[] is consumed in lockstep
     // by lib/md2doc.js's render walk, so a skipped child desynchronises the two
     // and the render runs off the end of the array.
     childListTokens.forEach((ct, k) => {
-      pushListItemBlocks(ct, cursor + childLineOffsets[k], indent + 1, blocks, nextId);
+      pushListItemBlocks(ct, cursor + childLineOffsets[k], indent + 1, blocks, nextId, degraded);
     });
     // advance cursor by full item raw newlines; fall back to totalSpan if raw
     // has no trailing newline (EOF item).
@@ -169,23 +377,23 @@ function buildBlockMap(mdText) {
   let cursor = 1; // current line number of the token's first character
   const nextId = { v: 0 };
   for (const t of tokens) {
-    const rawNewlines = (t.raw.match(/\n/g) || []).length;
+    const info = topLevelLineInfo(t);
     if (t.type === 'list') {
       pushListItemBlocks(t, cursor, 0, blocks, nextId);
     } else if (t.type !== 'space') {
-      const content = t.raw.replace(/\n+$/, '');
-      const span = content === '' ? 1 : content.split('\n').length;
       blocks.push({
         id: nextId.v++,
         type: t.type,
         startLine: cursor,
-        endLine: cursor + span - 1,
+        endLine: cursor + info.span - 1,
       });
     }
-    // advance by full raw (including folded trailing blank lines).
+    // advance by full raw (including folded trailing blank lines) for every
+    // type except 'paragraph'/'heading', which use topLevelLineInfo()'s
+    // text-based count instead — see its own comment for why.
     // If raw has no trailing newline (EOF), the next token doesn't exist,
     // so the off-by-one is unobservable.
-    cursor += rawNewlines;
+    cursor += info.rawNewlines;
   }
   return { blocks, lineCount: mdText.split('\n').length };
 }