@helping-ai-workflow/md2doc 2.8.0 → 2.10.0

package/lib/md2doc.js

@@ -21,19 +21,9 @@
 const fs            = require('fs');
 const path          = require('path');
 
-const [,, src, dst] = process.argv;
-const BAKE_SVG = process.argv.slice(4).includes('--bake-svg');
-
 // How long to let client-side WaveDrom / Mermaid scripts render before we
 // snapshot the DOM (PDF print, or --bake-svg inert-SVG bake).
 const DIAGRAM_RENDER_WAIT_MS = 2500;
-if (!src || !dst) {
-  console.error('Usage: node md2doc.js <input.md> <output.html|pdf>');
-  process.exit(1);
-}
-
-const ext = path.extname(dst).toLowerCase();
-const md  = fs.readFileSync(src, 'utf8');
 
 function firstExistingPath(candidates) {
   for (const candidate of candidates) {
@@ -106,11 +96,6 @@ const mermaidInitTag = `<script type="text/javascript" data-md2doc-diagram-engin
 // Use a custom renderer to intercept fenced code blocks before marked escapes
 // their content. This is the correct approach — pre-processing the raw markdown
 // string causes marked to re-parse the injected HTML and mangle indented lines.
-
-let usesMermaid = false;
-let usesWaveDrom = false;
-let usesMath = false;
-
 // Self-contained KaTeX stylesheet: inline katex.min.css with each woff2 @font-face
 // rewritten to a base64 data: URI and the woff/ttf alternates stripped, so a
 // math-bearing HTML prints offline (and in puppeteer PDF) with no font fetch.
@@ -129,582 +114,698 @@ function buildKatexStyleTag() {
   return `<style data-md2doc-math>${css}</style>`;
 }
 
-// ── Local image assets ───────────────────────────────────────────────────────
-// Image srcs in the markdown are relative to the SOURCE markdown, but the HTML
-// is normally written somewhere else entirely (the OS temp dir by default), so
-// a relative src resolves against the wrong directory and the image silently
-// never loads. Resolve every local reference against the markdown's own
-// directory and inline it as a data: URI — the same self-contained principle
-// the embedded CSS / KaTeX fonts already follow, and the only form that also
-// survives the puppeteer PDF path (which renders from its own temp HTML).
-const SRC_DIR = path.dirname(path.resolve(src));
-const LARGE_ASSET_WARN_BYTES = 4 * 1024 * 1024;
-
-// Doubles as the allowlist: a reference whose extension is not an image is left
-// alone. Without that gate, `![x](../../../.ssh/id_rsa)` would happily base64
-// the file into a document meant to be shared.
-const IMAGE_MIME_BY_EXT = {
-  '.png':  'image/png',
-  '.jpg':  'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.jfif': 'image/jpeg',
-  '.gif':  'image/gif',
-  '.svg':  'image/svg+xml',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.bmp':  'image/bmp',
-  '.ico':  'image/x-icon',
-  '.apng': 'image/apng',
-  '.tif':  'image/tiff',
-  '.tiff': 'image/tiff',
-};
-
-const inlinedAssetCache = new Map();
-const skippedAssetWarned = new Set();
-
-// Only a scheme we actually know is treated as remote — a bare `letter+colon`
-// test would misread both a Windows drive (`C:/img.png`) and a filename that
-// merely contains a colon. `//host/x.png` is protocol-relative.
-const EXTERNAL_REF_RE = /^(?:(?:https?|data|file|blob|ftps?|mailto|tel|about|chrome|chrome-extension|moz-extension):|\/\/)/i;
-
-function isExternalRef(href) {
-  return EXTERNAL_REF_RE.test(String(href).trim());
-}
+// ── marked setup (installed once at require time) ───────────────────────────
+// marked.use() has no de-dup: it unshifts a fresh copy of these tokenizers
+// into marked's shared/global extension registry on every call. These two
+// extensions don't depend on any per-document state (mdText/srcPath), so they
+// are installed exactly once here rather than inside renderMarkdown() — doing
+// it per-call would grow the registry unboundedly in a long-lived process
+// (the editor server calls renderMarkdown() once per edit).
+let marked, Renderer;
+try {
+  ({ marked, Renderer } = require('marked'));
 
-function warnOnce(href, message) {
-  if (skippedAssetWarned.has(href)) return;
-  skippedAssetWarned.add(href);
-  console.error(message);
-}
+  // Code-aware subscript / superscript as marked inline extensions.
+  // The old raw-text pre-pass (mdPre.replace(/~([^~]+)~/...)) ran BEFORE marked
+  // tokenised, so it rewrote ~NOT / ^XOR operators inside fenced, indented and
+  // inline code into <sub>/<sup> (96 such mangles in one RTL spec). As inline
+  // extensions marked tokenises code first, so these never fire inside code.
+  // The tokenizer also requires a single whitespace-free token (~x~ / ^x^), so
+  // spaced operator expressions (~a & ~b, a ^ b) and lone operators (2^24, ~rst)
+  // stay literal even in prose — only a genuine subscript/superscript converts.
+  marked.use({
+    extensions: [
+      {
+        name: 'subscript',
+        level: 'inline',
+        start(src) { const i = src.indexOf('~'); return i < 0 ? undefined : i; },
+        tokenizer(src) {
+          const m = /^~(?=\S)([^~\s\n]+)~/.exec(src);
+          if (m) {
+            return { type: 'subscript', raw: m[0], text: m[1],
+                     tokens: this.lexer.inlineTokens(m[1]) };
+          }
+        },
+        renderer(token) { return `<sub>${this.parser.parseInline(token.tokens)}</sub>`; },
+      },
+      {
+        name: 'superscript',
+        level: 'inline',
+        start(src) { const i = src.indexOf('^'); return i < 0 ? undefined : i; },
+        tokenizer(src) {
+          const m = /^\^(?=\S)([^^\s\n]+)\^/.exec(src);
+          if (m) {
+            return { type: 'superscript', raw: m[0], text: m[1],
+                     tokens: this.lexer.inlineTokens(m[1]) };
+          }
+        },
+        renderer(token) { return `<sup>${this.parser.parseInline(token.tokens)}</sup>`; },
+      },
+    ],
+  });
 
-// Splits `assets/pic.svg?v=2#gear` into its path and its fragment. The query is
-// dropped (it is cache-busting for a fetch that no longer happens); the
-// fragment is kept and re-attached to the data URI, since it selects a view /
-// symbol inside an SVG rather than addressing the file.
-function splitAssetRef(href) {
-  const raw = String(href).trim();
-  const hash = raw.indexOf('#');
-  const withoutHash = hash === -1 ? raw : raw.slice(0, hash);
-  const fragment = hash === -1 ? '' : raw.slice(hash);
-  return { filePart: withoutHash.replace(/\?.*$/, ''), fragment };
+  // $$…$$ (display) and $…$ (inline) math via KaTeX. marked tokenizes code
+  // spans/fences first, so $ inside code stays literal; the extension's
+  // default no-space-adjacency rules keep prose currency ($5 to $10) unrendered.
+  const markedKatex = require('marked-katex-extension');
+  marked.use(markedKatex({ throwOnError: false }));
+} catch (e) {
+  console.error('[ERROR] marked not found — install with: npm install marked');
+  console.error(e.message);
+  process.exit(1);
 }
 
-function resolveAssetPath(filePart) {
-  if (!filePart) return null;
-  let decoded = filePart;
-  try {
-    decoded = decodeURIComponent(filePart);
-  } catch (_) {
-    // Malformed percent-escapes: probe the raw form only.
-  }
-  const candidates = [];
-  for (const c of [decoded, filePart]) {
-    candidates.push(path.isAbsolute(c) ? c : path.resolve(SRC_DIR, c));
-  }
-  return firstExistingPath(candidates);
+// Render one list token into per-li ed-block HTML.
+// biRef is a shared box { v: <int> } that advances through blocks[] in the
+// same DFS order as blockmap.js pushListItemBlocks:
+//   1. Push the item's own block.
+//   2. Recurse into that item's nested child lists, left-to-right.
+//   3. Move on to the next sibling item.
+// RULING F-L: use marked.Parser.parseInline ONLY when the item is tight
+// (!item.loose) AND its own non-list tokens are exactly one 'text' token.
+// In every other case emit marked.parser(ownTokens) so that loose items keep
+// their <p> wrapper — list-md.js detects loose items by the <p> and flags them
+// as unsupported per-li (spec §8). Stripping the <p> would cause silent
+// data-shape corruption on the first edit.
+function renderEditModeList(listToken, blocks, biRef) {
+  const tag = listToken.ordered ? 'ol' : 'ul';
+  const startAttr = (listToken.ordered && listToken.start && listToken.start !== 1)
+    ? ` start="${listToken.start}"` : '';
+  const items = listToken.items.map((item) => {
+    const b = blocks[biRef.v++];
+    const ownTokens = item.tokens.filter((tk) => tk.type !== 'list');
+    let inner;
+    if (!item.loose && ownTokens.length === 1 && ownTokens[0].type === 'text') {
+      // Tight item with a single text token: use static parseInline to get
+      // clean inline HTML without a <p> wrapper.
+      inner = marked.Parser.parseInline(ownTokens[0].tokens);
+    } else {
+      // Loose item or non-standard own-token shape: use marked.parser, which
+      // emits block-level HTML (including <p> for loose items).  The <p>
+      // presence is load-bearing for list-md.js's loose-item detection.
+      inner = marked.parser(ownTokens);
+    }
+    const check = b.listType === 'task'
+      ? `<span class="ed-li-check" data-checked="${b.checked ? 1 : 0}" role="checkbox" aria-checked="${b.checked}"></span>`
+      : '';
+    // Recurse into nested child lists AFTER this item's block (matches
+    // pushListItemBlocks order: own block → nested lists → next sibling).
+    const children = item.tokens.filter((tk) => tk.type === 'list')
+      .map((ct) => renderEditModeList(ct, blocks, biRef)).join('\n');
+    return `<li class="ed-block" data-block-id="${b.id}" data-block-type="li"` +
+      ` data-list-type="${b.listType}" data-indent="${b.indent}">` +
+      check + `<div class="ed-li-text">${inner}</div>` + children + '</li>';
+  });
+  return `<${tag}${startAttr}>\n${items.join('\n')}\n</${tag}>`;
 }
 
-// Returns a data: URI, or null when the reference must be left untouched
-// (remote URL, already a data: URI, non-image extension, or no such file).
-function inlineImageSrc(href) {
-  if (!href || isExternalRef(href)) return null;
-  const { filePart, fragment } = splitAssetRef(href);
-  if (!filePart) return null;
+async function renderMarkdown(mdText, srcPath, opts = {}) {
+  const md = mdText;
+  const src = srcPath;
+  let usesMermaid = false;
+  let usesWaveDrom = false;
+  let usesMath = false;
+  let blocks = null;
+  // ── Local image assets ───────────────────────────────────────────────────────
+  // Image srcs in the markdown are relative to the SOURCE markdown, but the HTML
+  // is normally written somewhere else entirely (the OS temp dir by default), so
+  // a relative src resolves against the wrong directory and the image silently
+  // never loads. Resolve every local reference against the markdown's own
+  // directory and inline it as a data: URI — the same self-contained principle
+  // the embedded CSS / KaTeX fonts already follow, and the only form that also
+  // survives the puppeteer PDF path (which renders from its own temp HTML).
+  const SRC_DIR = path.dirname(path.resolve(src));
+  const LARGE_ASSET_WARN_BYTES = 4 * 1024 * 1024;
+
+  // Doubles as the allowlist: a reference whose extension is not an image is left
+  // alone. Without that gate, `![x](../../../.ssh/id_rsa)` would happily base64
+  // the file into a document meant to be shared.
+  const IMAGE_MIME_BY_EXT = {
+    '.png':  'image/png',
+    '.jpg':  'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.jfif': 'image/jpeg',
+    '.gif':  'image/gif',
+    '.svg':  'image/svg+xml',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.bmp':  'image/bmp',
+    '.ico':  'image/x-icon',
+    '.apng': 'image/apng',
+    '.tif':  'image/tiff',
+    '.tiff': 'image/tiff',
+  };
 
-  const mime = IMAGE_MIME_BY_EXT[path.extname(filePart).toLowerCase()];
-  if (!mime) {
-    warnOnce(href, `[WARN] not a known image extension, left as-is: ${href}`);
-    return null;
+  const inlinedAssetCache = new Map();
+  const skippedAssetWarned = new Set();
+
+  // Only a scheme we actually know is treated as remote — a bare `letter+colon`
+  // test would misread both a Windows drive (`C:/img.png`) and a filename that
+  // merely contains a colon. `//host/x.png` is protocol-relative.
+  const EXTERNAL_REF_RE = /^(?:(?:https?|data|file|blob|ftps?|mailto|tel|about|chrome|chrome-extension|moz-extension):|\/\/)/i;
+
+  function isExternalRef(href) {
+    return EXTERNAL_REF_RE.test(String(href).trim());
   }
 
-  const abs = resolveAssetPath(filePart);
-  if (!abs) {
-    warnOnce(href, `[WARN] image not found, left as-is: ${href} (resolved against ${SRC_DIR})`);
-    return null;
+  function warnOnce(href, message) {
+    if (skippedAssetWarned.has(href)) return;
+    skippedAssetWarned.add(href);
+    console.error(message);
   }
 
-  let uri = inlinedAssetCache.get(abs);
-  if (uri === undefined) {
-    uri = null;
+  // Splits `assets/pic.svg?v=2#gear` into its path and its fragment. The query is
+  // dropped (it is cache-busting for a fetch that no longer happens); the
+  // fragment is kept and re-attached to the data URI, since it selects a view /
+  // symbol inside an SVG rather than addressing the file.
+  function splitAssetRef(href) {
+    const raw = String(href).trim();
+    const hash = raw.indexOf('#');
+    const withoutHash = hash === -1 ? raw : raw.slice(0, hash);
+    const fragment = hash === -1 ? '' : raw.slice(hash);
+    return { filePart: withoutHash.replace(/\?.*$/, ''), fragment };
+  }
+
+  function resolveAssetPath(filePart) {
+    if (!filePart) return null;
+    let decoded = filePart;
     try {
-      const stat = fs.statSync(abs);
-      if (!stat.isFile()) throw new Error('not a regular file');
-      if (stat.size > LARGE_ASSET_WARN_BYTES) {
-        console.error(`[WARN] inlining large image (${(stat.size / 1048576).toFixed(1)} MB): ${href}`);
-      }
-      uri = `data:${mime};base64,${fs.readFileSync(abs).toString('base64')}`;
-    } catch (e) {
-      console.error(`[WARN] could not inline image ${href}: ${e.message}`);
-      uri = null;
+      decoded = decodeURIComponent(filePart);
+    } catch (_) {
+      // Malformed percent-escapes: probe the raw form only.
+    }
+    const candidates = [];
+    for (const c of [decoded, filePart]) {
+      candidates.push(path.isAbsolute(c) ? c : path.resolve(SRC_DIR, c));
     }
-    inlinedAssetCache.set(abs, uri);
+    return firstExistingPath(candidates);
   }
-  return uri ? uri + fragment : null;
-}
 
-// A srcset value is a comma-separated list of `<url> <descriptor>` candidates.
-function inlineSrcsetValue(value) {
-  const parts = String(value).split(',');
-  let changed = false;
-  const rebuilt = parts.map((part) => {
-    const m = part.match(/^(\s*)(\S+)(\s*.*)$/);
-    if (!m) return part;
-    const uri = inlineImageSrc(m[2]);
-    if (!uri) return part;
-    changed = true;
-    return m[1] + uri + m[3];
-  });
-  return changed ? rebuilt.join(',') : null;
-}
+  // Returns a data: URI, or null when the reference must be left untouched
+  // (remote URL, already a data: URI, non-image extension, or no such file).
+  function inlineImageSrc(href) {
+    if (!href || isExternalRef(href)) return null;
+    const { filePart, fragment } = splitAssetRef(href);
+    if (!filePart) return null;
 
-// Author-written <img> / <source> tags (specs use them for width= and for
-// <picture>) need the same rewrite. Scoped to markdown-authored HTML chunks
-// only — never run over the whole page, whose bundled mermaid / katex JS also
-// contains '<img' literals.
-// The tag matcher is attribute-aware: a quoted value may legally contain '>',
-// and a plain [^>]* would truncate the tag and miss a src that sits after it.
-const ASSET_TAG_RE = /<(?:img|source)\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
-const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
-const SRC_ATTR_RE   = /(\s(?:src|srcset)\s*=\s*)(?:(["'])([^"']*)\2|([^\s"'=<>`]+))/gi;
-
-function inlineImagesInTag(tag) {
-  return tag.replace(SRC_ATTR_RE, (match, lead, quote, quoted, bare) => {
-    const raw = (quoted !== undefined ? quoted : bare) || '';
-    const decoded = raw.replace(/&amp;/g, '&');
-    const isSrcset = /srcset\s*=\s*$/i.test(lead);
-    const value = isSrcset ? inlineSrcsetValue(decoded) : inlineImageSrc(decoded);
-    return value ? `${lead}"${value}"` : match;
-  });
-}
+    const mime = IMAGE_MIME_BY_EXT[path.extname(filePart).toLowerCase()];
+    if (!mime) {
+      warnOnce(href, `[WARN] not a known image extension, left as-is: ${href}`);
+      return null;
+    }
 
-function inlineImagesInHtmlChunk(chunk) {
-  if (!chunk || !/<(?:img|source)\b/i.test(chunk)) return chunk;
-  // Step over comments untouched — a commented-out <img> is not displayed, so
-  // inlining it would only bloat the output (or smuggle a file into it).
-  let out = '';
-  let last = 0;
-  HTML_COMMENT_RE.lastIndex = 0;
-  let m;
-  while ((m = HTML_COMMENT_RE.exec(chunk)) !== null) {
-    out += chunk.slice(last, m.index).replace(ASSET_TAG_RE, inlineImagesInTag) + m[0];
-    last = m.index + m[0].length;
-  }
-  return out + chunk.slice(last).replace(ASSET_TAG_RE, inlineImagesInTag);
-}
+    const abs = resolveAssetPath(filePart);
+    if (!abs) {
+      warnOnce(href, `[WARN] image not found, left as-is: ${href} (resolved against ${SRC_DIR})`);
+      return null;
+    }
 
-let bodyHtml;
-let tocHtml = '';
-let serializedSections = '[]';
-try {
-  const { marked, Renderer } = require('marked');
-  const katex = require('katex');
-
-  const renderer = new Renderer();
-  const tocItems = [];
-  const slugCounts = new Map();
-  const sections = [];
-  let currentSection = null;
-
-  function startSection({ id, depth, text }) {
-    currentSection = {
-      id,
-      depth,
-      title: text,
-      searchTextParts: [text],
-    };
-    sections.push(currentSection);
+    let uri = inlinedAssetCache.get(abs);
+    if (uri === undefined) {
+      uri = null;
+      try {
+        const stat = fs.statSync(abs);
+        if (!stat.isFile()) throw new Error('not a regular file');
+        if (stat.size > LARGE_ASSET_WARN_BYTES) {
+          console.error(`[WARN] inlining large image (${(stat.size / 1048576).toFixed(1)} MB): ${href}`);
+        }
+        uri = `data:${mime};base64,${fs.readFileSync(abs).toString('base64')}`;
+      } catch (e) {
+        console.error(`[WARN] could not inline image ${href}: ${e.message}`);
+        uri = null;
+      }
+      inlinedAssetCache.set(abs, uri);
+    }
+    return uri ? uri + fragment : null;
+  }
+
+  // A srcset value is a comma-separated list of `<url> <descriptor>` candidates.
+  function inlineSrcsetValue(value) {
+    const parts = String(value).split(',');
+    let changed = false;
+    const rebuilt = parts.map((part) => {
+      const m = part.match(/^(\s*)(\S+)(\s*.*)$/);
+      if (!m) return part;
+      const uri = inlineImageSrc(m[2]);
+      if (!uri) return part;
+      changed = true;
+      return m[1] + uri + m[3];
+    });
+    return changed ? rebuilt.join(',') : null;
+  }
+
+  // Author-written <img> / <source> tags (specs use them for width= and for
+  // <picture>) need the same rewrite. Scoped to markdown-authored HTML chunks
+  // only — never run over the whole page, whose bundled mermaid / katex JS also
+  // contains '<img' literals.
+  // The tag matcher is attribute-aware: a quoted value may legally contain '>',
+  // and a plain [^>]* would truncate the tag and miss a src that sits after it.
+  const ASSET_TAG_RE = /<(?:img|source)\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+  const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+  const SRC_ATTR_RE   = /(\s(?:src|srcset)\s*=\s*)(?:(["'])([^"']*)\2|([^\s"'=<>`]+))/gi;
+
+  function inlineImagesInTag(tag) {
+    return tag.replace(SRC_ATTR_RE, (match, lead, quote, quoted, bare) => {
+      const raw = (quoted !== undefined ? quoted : bare) || '';
+      const decoded = raw.replace(/&amp;/g, '&');
+      const isSrcset = /srcset\s*=\s*$/i.test(lead);
+      const value = isSrcset ? inlineSrcsetValue(decoded) : inlineImageSrc(decoded);
+      return value ? `${lead}"${value}"` : match;
+    });
   }
 
-  function appendSectionText(value) {
-    if (!currentSection || !value) {
-      return;
-    }
-    const clean = stripHtmlTags(value).replace(/\s+/g, ' ').trim();
-    if (clean) {
-      currentSection.searchTextParts.push(clean);
+  function inlineImagesInHtmlChunk(chunk) {
+    if (!chunk || !/<(?:img|source)\b/i.test(chunk)) return chunk;
+    // Step over comments untouched — a commented-out <img> is not displayed, so
+    // inlining it would only bloat the output (or smuggle a file into it).
+    let out = '';
+    let last = 0;
+    HTML_COMMENT_RE.lastIndex = 0;
+    let m;
+    while ((m = HTML_COMMENT_RE.exec(chunk)) !== null) {
+      out += chunk.slice(last, m.index).replace(ASSET_TAG_RE, inlineImagesInTag) + m[0];
+      last = m.index + m[0].length;
+    }
+    return out + chunk.slice(last).replace(ASSET_TAG_RE, inlineImagesInTag);
+  }
+
+  let bodyHtml;
+  let tocHtml = '';
+  let serializedSections = '[]';
+  // NOTE: intentionally no try/catch here. A throw from marked/katex parsing
+  // (pathological markdown, a malformed extension token, etc.) must propagate
+  // to the caller: the CLI's outer `(async () => {...})().catch(...)` exits 1,
+  // and the long-lived editor server's route wraps renderMarkdown in its own
+  // try/catch to return a 500 and keep serving. Swallowing it here with
+  // process.exit(1) (the old behavior) used to kill the whole editor server on
+  // any render-time throw — see lib/editor/server.js's /api/render handler.
+  // The *module-level* require('marked') failure above (~line 172) still has
+  // its own catch, since that one really is unrecoverable at load time.
+  {
+    const katex = require('katex');
+
+    const renderer = new Renderer();
+    const tocItems = [];
+    const slugCounts = new Map();
+    const sections = [];
+    let currentSection = null;
+
+    function startSection({ id, depth, text }) {
+      currentSection = {
+        id,
+        depth,
+        title: text,
+        searchTextParts: [text],
+      };
+      sections.push(currentSection);
     }
-  }
 
-  function collectCellText(cells) {
-    if (!Array.isArray(cells)) {
-      return;
-    }
-    for (const cell of cells) {
-      if (cell && Array.isArray(cell.tokens)) {
-        appendSectionText(flattenTokenText(cell.tokens));
-      } else if (cell && typeof cell.text === 'string') {
-        appendSectionText(cell.text);
+    function appendSectionText(value) {
+      if (!currentSection || !value) {
+        return;
+      }
+      const clean = stripHtmlTags(value).replace(/\s+/g, ' ').trim();
+      if (clean) {
+        currentSection.searchTextParts.push(clean);
       }
     }
-  }
-
-  function buildTocTree(items) {
-    const root = [];
-    const stack = [{ depth: 0, children: root }];
 
-    for (const item of items) {
-      const node = { ...item, children: [] };
-      while (stack.length > 1 && item.depth <= stack[stack.length - 1].depth) {
-        stack.pop();
+    function collectCellText(cells) {
+      if (!Array.isArray(cells)) {
+        return;
+      }
+      for (const cell of cells) {
+        if (cell && Array.isArray(cell.tokens)) {
+          appendSectionText(flattenTokenText(cell.tokens));
+        } else if (cell && typeof cell.text === 'string') {
+          appendSectionText(cell.text);
+        }
       }
-      stack[stack.length - 1].children.push(node);
-      stack.push(node);
     }
 
-    return root;
-  }
+    function buildTocTree(items) {
+      const root = [];
+      const stack = [{ depth: 0, children: root }];
+
+      for (const item of items) {
+        const node = { ...item, children: [] };
+        while (stack.length > 1 && item.depth <= stack[stack.length - 1].depth) {
+          stack.pop();
+        }
+        stack[stack.length - 1].children.push(node);
+        stack.push(node);
+      }
 
-  function renderTocNodes(nodes, level = 1) {
-    if (!nodes.length) {
-      return '';
+      return root;
     }
 
-    const itemsHtml = nodes
-      .map((node) => {
-        const linkHtml = `<a href="#${node.id}" title="${escapeHtml(node.text)}">${escapeHtml(node.text)}</a>`;
-        const hasChildren = node.children && node.children.length > 0;
+    function renderTocNodes(nodes, level = 1) {
+      if (!nodes.length) {
+        return '';
+      }
 
-        if (!hasChildren) {
-          return `<li class="toc-item toc-level-${level}">${linkHtml}</li>`;
-        }
+      const itemsHtml = nodes
+        .map((node) => {
+          const linkHtml = `<a href="#${node.id}" title="${escapeHtml(node.text)}">${escapeHtml(node.text)}</a>`;
+          const hasChildren = node.children && node.children.length > 0;
+
+          if (!hasChildren) {
+            return `<li class="toc-item toc-level-${level}">${linkHtml}</li>`;
+          }
 
-        return `<li class="toc-item toc-level-${level} toc-parent">
+          return `<li class="toc-item toc-level-${level} toc-parent">
   <details>
     <summary>${linkHtml}</summary>
     ${renderTocNodes(node.children, level + 1)}
   </details>
 </li>`;
-      })
-      .join('\n');
+        })
+        .join('\n');
 
-    return `<ul class="toc-list toc-list-level-${level}">
+      return `<ul class="toc-list toc-list-level-${level}">
 ${itemsHtml}
 </ul>`;
-  }
-
-  function flattenTokenText(tokens) {
-    if (!Array.isArray(tokens)) {
-      return '';
     }
-    return tokens
-      .map((item) => {
-        if (item.type === 'link' || item.type === 'em' || item.type === 'strong' || item.type === 'del') {
-          return flattenTokenText(item.tokens);
-        }
-        if (item.type === 'codespan') {
+
+    function flattenTokenText(tokens) {
+      if (!Array.isArray(tokens)) {
+        return '';
+      }
+      return tokens
+        .map((item) => {
+          if (item.type === 'link' || item.type === 'em' || item.type === 'strong' || item.type === 'del') {
+            return flattenTokenText(item.tokens);
+          }
+          if (item.type === 'codespan') {
+            return item.text || '';
+          }
+          if (item.tokens) {
+            return flattenTokenText(item.tokens);
+          }
           return item.text || '';
+        })
+        .join('');
+    }
+
+    function unbreakableRun(s) {
+      // Treat `_` as a break point — identifiers like `pmac_tx_*` are unbreakable in CSS but breakable for classification.
+      const matches = String(s || '').match(/[A-Za-z0-9\-./@:]+/g);
+      if (!matches) return 0;
+      let max = 0;
+      for (const m of matches) if (m.length > max) max = m.length;
+      return max;
+    }
+
+    function cellRawText(cell) {
+      if (!cell) return '';
+      if (Array.isArray(cell.tokens)) return flattenTokenText(cell.tokens);
+      return String(cell.text || '');
+    }
+
+    function classifyColumns(token) {
+      const colCount = (token.header || []).length;
+      const classes = [];
+      for (let i = 0; i < colCount; i++) {
+        const allCells = [];
+        if (token.header && token.header[i]) allCells.push(token.header[i]);
+        const dataCells = [];
+        if (Array.isArray(token.rows)) {
+          for (const row of token.rows) {
+            if (row && row[i]) {
+              allCells.push(row[i]);
+              dataCells.push(row[i]);
+            }
+          }
         }
-        if (item.tokens) {
-          return flattenTokenText(item.tokens);
+        const allTexts = allCells.map(cellRawText);
+        const dataTexts = dataCells.map(cellRawText);
+        // Header labels (e.g. "Clock Domain") often contain whitespace not representative of cell content; use data rows for the heuristic and fall back to header only when the column has no data.
+        const heuristicTexts = dataTexts.length > 0 ? dataTexts : allTexts;
+        let maxTokenLen = 0;
+        let totalLen = 0;
+        let hasWhitespace = false;
+        let hasSentence = false;
+        for (const t of heuristicTexts) {
+          const r = unbreakableRun(t);
+          if (r > maxTokenLen) maxTokenLen = r;
+          totalLen += t.length;
+          if (/\s/.test(t)) hasWhitespace = true;
+          if (/。|\. /.test(t)) hasSentence = true;
         }
-        return item.text || '';
-      })
-      .join('');
-  }
-
-  function unbreakableRun(s) {
-    // Treat `_` as a break point — identifiers like `pmac_tx_*` are unbreakable in CSS but breakable for classification.
-    const matches = String(s || '').match(/[A-Za-z0-9\-./@:]+/g);
-    if (!matches) return 0;
-    let max = 0;
-    for (const m of matches) if (m.length > max) max = m.length;
-    return max;
-  }
+        const avgCellLen = heuristicTexts.length ? (totalLen / heuristicTexts.length) : 0;
 
-  function cellRawText(cell) {
-    if (!cell) return '';
-    if (Array.isArray(cell.tokens)) return flattenTokenText(cell.tokens);
-    return String(cell.text || '');
-  }
-
-  function classifyColumns(token) {
-    const colCount = (token.header || []).length;
-    const classes = [];
-    for (let i = 0; i < colCount; i++) {
-      const allCells = [];
-      if (token.header && token.header[i]) allCells.push(token.header[i]);
-      const dataCells = [];
-      if (Array.isArray(token.rows)) {
-        for (const row of token.rows) {
-          if (row && row[i]) {
-            allCells.push(row[i]);
-            dataCells.push(row[i]);
-          }
+        // Narrow takes precedence over prose (tie-break: prefer narrow / conservative).
+        if (maxTokenLen <= 12 && !hasWhitespace) {
+          classes.push('col-narrow');
+        } else if (avgCellLen > 40 || hasSentence) {
+          classes.push('col-prose');
+        } else {
+          classes.push('col-default');
         }
       }
-      const allTexts = allCells.map(cellRawText);
-      const dataTexts = dataCells.map(cellRawText);
-      // Header labels (e.g. "Clock Domain") often contain whitespace not representative of cell content; use data rows for the heuristic and fall back to header only when the column has no data.
-      const heuristicTexts = dataTexts.length > 0 ? dataTexts : allTexts;
-      let maxTokenLen = 0;
-      let totalLen = 0;
-      let hasWhitespace = false;
-      let hasSentence = false;
-      for (const t of heuristicTexts) {
-        const r = unbreakableRun(t);
-        if (r > maxTokenLen) maxTokenLen = r;
-        totalLen += t.length;
-        if (/\s/.test(t)) hasWhitespace = true;
-        if (/。|\. /.test(t)) hasSentence = true;
-      }
-      const avgCellLen = heuristicTexts.length ? (totalLen / heuristicTexts.length) : 0;
-
-      // Narrow takes precedence over prose (tie-break: prefer narrow / conservative).
-      if (maxTokenLen <= 12 && !hasWhitespace) {
-        classes.push('col-narrow');
-      } else if (avgCellLen > 40 || hasSentence) {
-        classes.push('col-prose');
-      } else {
-        classes.push('col-default');
-      }
-    }
-    return classes;
-  }
-
-  function stripHtmlTags(value) {
-    return String(value || '').replace(/<[^>]*>/g, '');
-  }
-
-  function slugifyHeading(value) {
-    const base = stripHtmlTags(value)
-      .normalize('NFKD')
-      .replace(/[\u0300-\u036f]/g, '')
-      .trim()
-      .toLowerCase()
-      .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-      || 'section';
-    const count = slugCounts.get(base) || 0;
-    slugCounts.set(base, count + 1);
-    return count === 0 ? base : `${base}-${count + 1}`;
-  }
-
-  function escapeHtml(value) {
-    return String(value || '')
-      .replace(/&/g, '&amp;')
-      .replace(/</g, '&lt;')
-      .replace(/>/g, '&gt;')
-      .replace(/"/g, '&quot;')
-      .replace(/'/g, '&#39;');
-  }
+      return classes;
+    }
+
+    function stripHtmlTags(value) {
+      return String(value || '').replace(/<[^>]*>/g, '');
+    }
+
+    function slugifyHeading(value) {
+      const base = stripHtmlTags(value)
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        || 'section';
+      const count = slugCounts.get(base) || 0;
+      slugCounts.set(base, count + 1);
+      return count === 0 ? base : `${base}-${count + 1}`;
+    }
+
+    function escapeHtml(value) {
+      return String(value || '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+    }
+
+    // marked's tokenizer already escapes alt / title (its default image renderer
+    // interpolates both raw), so this must NOT escape them again. Only the src is
+    // ours; everything else — including cleanUrl() on a src we leave alone — stays
+    // marked's job, so non-inlined images render exactly as before.
+    const baseImage = renderer.image.bind(renderer);
+    renderer.image = function(token) {
+      const isObj = (token !== null && typeof token === 'object');
+      const href  = isObj ? (token.href  || '') : (token || '');
+      const title = isObj ? (token.title || '') : (arguments[1] || '');
+      const text  = isObj ? (token.text  || '') : (arguments[2] || '');
+      const uri = inlineImageSrc(href);
+      if (!uri) return baseImage.apply(this, arguments);
+      // A data: URI is base64 (or an already-encoded payload): no quote, no '<'.
+      let out = `<img src="${uri}" alt="${text}"`;
+      if (title) out += ` title="${title}"`;
+      return out + '>';
+    };
 
-  // marked's tokenizer already escapes alt / title (its default image renderer
-  // interpolates both raw), so this must NOT escape them again. Only the src is
-  // ours; everything else — including cleanUrl() on a src we leave alone — stays
-  // marked's job, so non-inlined images render exactly as before.
-  const baseImage = renderer.image.bind(renderer);
-  renderer.image = function(token) {
-    const isObj = (token !== null && typeof token === 'object');
-    const href  = isObj ? (token.href  || '') : (token || '');
-    const title = isObj ? (token.title || '') : (arguments[1] || '');
-    const text  = isObj ? (token.text  || '') : (arguments[2] || '');
-    const uri = inlineImageSrc(href);
-    if (!uri) return baseImage.apply(this, arguments);
-    // A data: URI is base64 (or an already-encoded payload): no quote, no '<'.
-    let out = `<img src="${uri}" alt="${text}"`;
-    if (title) out += ` title="${title}"`;
-    return out + '>';
-  };
+    const baseHtml = renderer.html.bind(renderer);
+    renderer.html = function(token) {
+      return inlineImagesInHtmlChunk(baseHtml.apply(this, arguments));
+    };
 
-  const baseHtml = renderer.html.bind(renderer);
-  renderer.html = function(token) {
-    return inlineImagesInHtmlChunk(baseHtml.apply(this, arguments));
-  };
+    renderer.code = function(token) {
+      // token is either a string (old API) or {text, lang} object (new API)
+      const lang = (typeof token === 'object') ? (token.lang || '') : (arguments[1] || '');
+      const code = (typeof token === 'object') ? token.text : token;
 
-  renderer.code = function(token) {
-    // token is either a string (old API) or {text, lang} object (new API)
-    const lang = (typeof token === 'object') ? (token.lang || '') : (arguments[1] || '');
-    const code = (typeof token === 'object') ? token.text : token;
-
-    if (lang === 'wavedrom') {
-      usesWaveDrom = true;
-      return `\n<script type="WaveDrom">\n${code}\n</script>\n`;
-    }
-    if (lang === 'mermaid') {
-      usesMermaid = true;
-      // Escape so the browser delivers the literal source to mermaid. Raw
-      // injection lets the HTML parser consume entities and tags first —
-      // an author's &lt;IP&gt; became an <IP> element mermaid sanitized
-      // away — diverging from GitHub's escaped-code-block semantics.
-      return `\n<div class="mermaid">\n${escapeHtml(code)}\n</div>\n`;
-    }
-    if (lang === 'math') {
-      // KaTeX renders synchronously to static HTML (class="katex"); no client
-      // runtime, no async post-pass. throwOnError:false degrades a bad formula
-      // to red error text instead of crashing the whole render.
-      try {
-        return `\n${katex.renderToString(code, { displayMode: true, throwOnError: false })}\n`;
-      } catch (e) {
-        const esc = code.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
-        return `<pre><code class="language-math">${esc}</code></pre>\n`;
+      if (lang === 'wavedrom') {
+        usesWaveDrom = true;
+        return `\n<script type="WaveDrom">\n${code}\n</script>\n`;
       }
-    }
-    if (lang === 'dot' || lang === 'graphviz') {
-      // Defer rendering to the async bakeGraphviz() post-pass so the
-      // synchronous marked() pass stays sync. The dot source is carried as
-      // base64 in a data attribute — safe for arbitrary dot syntax (quotes,
-      // angle brackets, newlines) inside an HTML attribute.
-      const b64 = Buffer.from(code, 'utf8').toString('base64');
-      return `\n<div class="graphviz" data-graphviz-src="${b64}"></div>\n`;
-    }
-    // Default: syntax-highlighted code block
-    const escaped = code.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
-    return `<pre><code class="language-${lang}">${escaped}</code></pre>\n`;
-  };
+      if (lang === 'mermaid') {
+        usesMermaid = true;
+        // Escape so the browser delivers the literal source to mermaid. Raw
+        // injection lets the HTML parser consume entities and tags first —
+        // an author's &lt;IP&gt; became an <IP> element mermaid sanitized
+        // away — diverging from GitHub's escaped-code-block semantics.
+        return `\n<div class="mermaid">\n${escapeHtml(code)}\n</div>\n`;
+      }
+      if (lang === 'math') {
+        // KaTeX renders synchronously to static HTML (class="katex"); no client
+        // runtime, no async post-pass. throwOnError:false degrades a bad formula
+        // to red error text instead of crashing the whole render.
+        try {
+          return `\n${katex.renderToString(code, { displayMode: true, throwOnError: false })}\n`;
+        } catch (e) {
+          const esc = code.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+          return `<pre><code class="language-math">${esc}</code></pre>\n`;
+        }
+      }
+      if (lang === 'dot' || lang === 'graphviz') {
+        // Defer rendering to the async bakeGraphviz() post-pass so the
+        // synchronous marked() pass stays sync. The dot source is carried as
+        // base64 in a data attribute — safe for arbitrary dot syntax (quotes,
+        // angle brackets, newlines) inside an HTML attribute.
+        const b64 = Buffer.from(code, 'utf8').toString('base64');
+        return `\n<div class="graphviz" data-graphviz-src="${b64}"></div>\n`;
+      }
+      // Default: syntax-highlighted code block
+      const escaped = code.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+      return `<pre><code class="language-${lang}">${escaped}</code></pre>\n`;
+    };
 
-  renderer.heading = function(token) {
-    const depth = Number(token.depth || 1);
-    const headingText = stripHtmlTags(flattenTokenText(token.tokens) || token.text || '');
-    const headingId = slugifyHeading(headingText);
-    const headingHtml = this.parser.parseInline(token.tokens);
+    renderer.heading = function(token) {
+      const depth = Number(token.depth || 1);
+      const headingText = stripHtmlTags(flattenTokenText(token.tokens) || token.text || '');
+      const headingId = slugifyHeading(headingText);
+      const headingHtml = this.parser.parseInline(token.tokens);
 
-    tocItems.push({
-      depth,
-      id: headingId,
-      text: headingText,
-    });
-    startSection({ depth, id: headingId, text: headingText });
+      tocItems.push({
+        depth,
+        id: headingId,
+        text: headingText,
+      });
+      startSection({ depth, id: headingId, text: headingText });
 
-    return `<h${depth} id="${headingId}" class="heading-with-anchor" data-reader-heading data-reader-depth="${depth}">${headingHtml}<a class="heading-anchor" href="#${headingId}" aria-label="Link to this section">#</a></h${depth}>\n`;
-  };
+      return `<h${depth} id="${headingId}" class="heading-with-anchor" data-reader-heading data-reader-depth="${depth}">${headingHtml}<a class="heading-anchor" href="#${headingId}" aria-label="Link to this section">#</a></h${depth}>\n`;
+    };
 
-  const baseParagraph = renderer.paragraph.bind(renderer);
-  renderer.paragraph = function(token) {
-    appendSectionText(flattenTokenText(token.tokens));
-    return baseParagraph(token);
-  };
+    const baseParagraph = renderer.paragraph.bind(renderer);
+    renderer.paragraph = function(token) {
+      appendSectionText(flattenTokenText(token.tokens));
+      return baseParagraph(token);
+    };
 
-  const baseListitem = renderer.listitem.bind(renderer);
-  renderer.listitem = function(token) {
-    appendSectionText(flattenTokenText(token.tokens));
-    return baseListitem(token);
-  };
+    const baseListitem = renderer.listitem.bind(renderer);
+    renderer.listitem = function(token) {
+      appendSectionText(flattenTokenText(token.tokens));
+      return baseListitem(token);
+    };
 
-  const baseBlockquote = renderer.blockquote.bind(renderer);
-  renderer.blockquote = function(token) {
-    appendSectionText(flattenTokenText(token.tokens));
-    return baseBlockquote(token);
-  };
+    const baseBlockquote = renderer.blockquote.bind(renderer);
+    renderer.blockquote = function(token) {
+      appendSectionText(flattenTokenText(token.tokens));
+      return baseBlockquote(token);
+    };
 
-  renderer.table = function(token) {
-    collectCellText(token.header);
-    if (Array.isArray(token.rows)) {
-      for (const row of token.rows) {
-        collectCellText(row);
+    renderer.table = function(token) {
+      collectCellText(token.header);
+      if (Array.isArray(token.rows)) {
+        for (const row of token.rows) {
+          collectCellText(row);
+        }
       }
-    }
 
-    const classes = classifyColumns(token);
-    const colHtml = classes
-      .map((c) => (c === 'col-default' ? '<col>' : `<col class="${c}">`))
-      .join('');
-    const cellClassAttr = (i) => {
-      const c = classes[i];
-      if (c === 'col-narrow') return ' class="cell-narrow"';
-      if (c === 'col-prose')  return ' class="cell-prose"';
-      return '';
-    };
-    const alignStyle = (cell) => (cell && cell.align)
-      ? ` style="text-align:${cell.align}"`
-      : '';
-
-    const headerCells = (token.header || []).map((cell, i) => {
-      const inner = cell && Array.isArray(cell.tokens)
-        ? this.parser.parseInline(cell.tokens)
+      const classes = classifyColumns(token);
+      const colHtml = classes
+        .map((c) => (c === 'col-default' ? '<col>' : `<col class="${c}">`))
+        .join('');
+      const cellClassAttr = (i) => {
+        const c = classes[i];
+        if (c === 'col-narrow') return ' class="cell-narrow"';
+        if (c === 'col-prose')  return ' class="cell-prose"';
+        return '';
+      };
+      const alignStyle = (cell) => (cell && cell.align)
+        ? ` style="text-align:${cell.align}"`
         : '';
-      return `<th${cellClassAttr(i)}${alignStyle(cell)}>${inner}</th>`;
-    }).join('');
-    const headerHtml = `<thead><tr>${headerCells}</tr></thead>`;
 
-    const bodyRows = Array.isArray(token.rows) ? token.rows.map((row) => {
-      const cells = (row || []).map((cell, i) => {
+      const headerCells = (token.header || []).map((cell, i) => {
         const inner = cell && Array.isArray(cell.tokens)
           ? this.parser.parseInline(cell.tokens)
           : '';
-        return `<td${cellClassAttr(i)}${alignStyle(cell)}>${inner}</td>`;
+        return `<th${cellClassAttr(i)}${alignStyle(cell)}>${inner}</th>`;
       }).join('');
-      return `<tr>${cells}</tr>`;
-    }).join('') : '';
-    const bodyHtmlPart = `<tbody>${bodyRows}</tbody>`;
-
-    return `<table>\n<colgroup>${colHtml}</colgroup>\n${headerHtml}\n${bodyHtmlPart}\n</table>\n`;
-  };
-
-  marked.setOptions({ gfm: true, breaks: false, renderer });
-
-  // Code-aware subscript / superscript as marked inline extensions.
-  // The old raw-text pre-pass (mdPre.replace(/~([^~]+)~/...)) ran BEFORE marked
-  // tokenised, so it rewrote ~NOT / ^XOR operators inside fenced, indented and
-  // inline code into <sub>/<sup> (96 such mangles in one RTL spec). As inline
-  // extensions marked tokenises code first, so these never fire inside code.
-  // The tokenizer also requires a single whitespace-free token (~x~ / ^x^), so
-  // spaced operator expressions (~a & ~b, a ^ b) and lone operators (2^24, ~rst)
-  // stay literal even in prose — only a genuine subscript/superscript converts.
-  marked.use({
-    extensions: [
-      {
-        name: 'subscript',
-        level: 'inline',
-        start(src) { const i = src.indexOf('~'); return i < 0 ? undefined : i; },
-        tokenizer(src) {
-          const m = /^~(?=\S)([^~\s\n]+)~/.exec(src);
-          if (m) {
-            return { type: 'subscript', raw: m[0], text: m[1],
-                     tokens: this.lexer.inlineTokens(m[1]) };
-          }
-        },
-        renderer(token) { return `<sub>${this.parser.parseInline(token.tokens)}</sub>`; },
-      },
-      {
-        name: 'superscript',
-        level: 'inline',
-        start(src) { const i = src.indexOf('^'); return i < 0 ? undefined : i; },
-        tokenizer(src) {
-          const m = /^\^(?=\S)([^^\s\n]+)\^/.exec(src);
-          if (m) {
-            return { type: 'superscript', raw: m[0], text: m[1],
-                     tokens: this.lexer.inlineTokens(m[1]) };
-          }
-        },
-        renderer(token) { return `<sup>${this.parser.parseInline(token.tokens)}</sup>`; },
-      },
-    ],
-  });
-
-  // $$…$$ (display) and $…$ (inline) math via KaTeX. marked tokenizes code
-  // spans/fences first, so $ inside code stays literal; the extension's
-  // default no-space-adjacency rules keep prose currency ($5 to $10) unrendered.
-  const markedKatex = require('marked-katex-extension');
-  marked.use(markedKatex({ throwOnError: false }));
+      const headerHtml = `<thead><tr>${headerCells}</tr></thead>`;
+
+      const bodyRows = Array.isArray(token.rows) ? token.rows.map((row) => {
+        const cells = (row || []).map((cell, i) => {
+          const inner = cell && Array.isArray(cell.tokens)
+            ? this.parser.parseInline(cell.tokens)
+            : '';
+          return `<td${cellClassAttr(i)}${alignStyle(cell)}>${inner}</td>`;
+        }).join('');
+        return `<tr>${cells}</tr>`;
+      }).join('') : '';
+      const bodyHtmlPart = `<tbody>${bodyRows}</tbody>`;
+
+      return `<table>\n<colgroup>${colHtml}</colgroup>\n${headerHtml}\n${bodyHtmlPart}\n</table>\n`;
+    };
 
-  // Pre-process the remaining non-standard inline syntax before marked parses
-  const escAttr = (s) => String(s)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-  const mdPre = md
-    .replace(/\[\[([^\]\n]+)\]\]/g, (_, inner) => {  // [[ref-id, §sub]] → clickable citation
-      const body = inner.trim();
-      const slug = body.split(',', 1)[0].trim();
-      return `<a href="#${escAttr(slug)}">[${escAttr(body)}]</a>`;
-    });
+    // subscript/superscript and $…$/$$…$$ KaTeX extensions are installed once
+    // at module-require time (see the top-level marked setup above) — marked's
+    // global extension registry is shared, and marked.use() has no de-dup.
+    // setOptions() through the marked.parse()/parser()/lexer() calls below
+    // must stay synchronous: marked keeps its renderer/options as shared
+    // global state, so an await between setOptions and parse would let a
+    // concurrent renderMarkdown() call for a DIFFERENT request overwrite
+    // this renderer mid-render (the editor server handles requests
+    // concurrently, unlike the one-shot CLI).
+    marked.setOptions({ gfm: true, breaks: false, renderer });
+
+    // Pre-process the remaining non-standard inline syntax before marked parses
+    const escAttr = (s) => String(s)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+    const mdPre = md
+      .replace(/\[\[([^\]\n]+)\]\]/g, (_, inner) => {  // [[ref-id, §sub]] → clickable citation
+        const body = inner.trim();
+        const slug = body.split(',', 1)[0].trim();
+        return `<a href="#${escAttr(slug)}">[${escAttr(body)}]</a>`;
+      });
 
-  bodyHtml = marked.parse(mdPre);
-  // Both the ```math fence and the $/$$ extension emit class="katex" — a single
-  // post-parse scan is the source of truth for conditional CSS injection.
-  usesMath = /class="katex/.test(bodyHtml);
-  serializedSections = JSON.stringify(
-    sections.map((section) => ({
-      id: section.id,
-      depth: section.depth,
-      title: section.title,
-      searchText: section.searchTextParts.join(' '),
-    }))
-  ).replace(/</g, '\\u003c');
-  if (tocItems.length > 0) {
-    const tocTree = buildTocTree(tocItems);
-    tocHtml = `<aside class="reader-sidebar" data-reader-sidebar>
+    if (opts.editMode) {
+      // Ranges are computed on mdPre. The [[...]] preprocessing above only
+      // replaces text within single lines and never adds/removes newlines,
+      // so line ranges stay valid against the ORIGINAL md the client holds
+      // (guarded by the '[[...]] must not shift lines' test).
+      const { buildBlockMap } = require('./editor/blockmap.js');
+      blocks = buildBlockMap(mdPre).blocks;
+      // marked.lexer() inline-lexes as part of block lexing (verified against
+      // marked 14.1.4: a paragraph token's `.tokens` already holds resolved
+      // inline tokens such as `strong`/`link`, not raw text) — so
+      // marked.parser([t]) on one already-lexed top-level token reproduces
+      // exactly what the whole-document parse would emit for that token,
+      // using the same renderer/options set above.
+      const tokens = marked.lexer(mdPre);
+      const parts = [];
+      const biRef = { v: 0 };
+      for (const t of tokens) {
+        if (t.type === 'space') continue;
+        if (t.type === 'list') {
+          parts.push(renderEditModeList(t, blocks, biRef));
+          continue;
+        }
+        const b = blocks[biRef.v++];
+        const inner = marked.parser([t]);
+        parts.push(
+          `<div class="ed-block" data-block-id="${b.id}" data-block-type="${b.type}">` +
+          inner + '</div>'
+        );
+      }
+      bodyHtml = parts.join('\n');
+    } else {
+      bodyHtml = marked.parse(mdPre);
+    }
+    // Both the ```math fence and the $/$$ extension emit class="katex" — a single
+    // post-parse scan is the source of truth for conditional CSS injection.
+    usesMath = /class="katex/.test(bodyHtml);
+    serializedSections = JSON.stringify(
+      sections.map((section) => ({
+        id: section.id,
+        depth: section.depth,
+        title: section.title,
+        searchText: section.searchTextParts.join(' '),
+      }))
+    ).replace(/</g, '\\u003c');
+    if (tocItems.length > 0) {
+      const tocTree = buildTocTree(tocItems);
+      tocHtml = `<aside class="reader-sidebar" data-reader-sidebar>
   <section class="reader-tools">
     <label class="reader-search-label" for="doc-search-input">Search</label>
     <div class="reader-search-row">
@@ -735,17 +836,110 @@ ${itemsHtml}
   </nav>
 </aside>
 <div class="sidebar-splitter" id="sidebar-splitter" role="separator" aria-orientation="vertical" aria-label="Resize sidebar"></div>`;
+    }
   }
-} catch (e) {
-  console.error('[ERROR] marked not found — install with: npm install marked');
-  console.error(e.message);
-  process.exit(1);
-}
 
-// ── HTML template ────────────────────────────────────────────────────────────
-const title = path.basename(src, '.md');
+  // ── HTML template ────────────────────────────────────────────────────────────
+  const title = path.basename(src, '.md');
+
+  // Edit-mode only: the reader runtime's diagram init becomes a re-invokable,
+  // idempotent hook (needed by a later task so re-rendered blocks can trigger
+  // diagram init again after a DOM swap, without a full page reload).
+  // Mermaid is explicitly initialized with startOnLoad:false here and driven
+  // entirely through this hook — running it alongside the non-edit path's
+  // `startOnLoad:true` auto-scan would race the same DOMContentLoaded event
+  // and risk mermaid processing (or erroring on) the same node twice.
+  // WaveDrom is driven entirely through this hook too (the non-edit path's
+  // own 4x-retry `renderWaveDrom` script is dropped in edit mode below) —
+  // WaveDrom.ProcessAll() (node_modules/wavedrom/lib/process-all.js) always
+  // rescans `document.querySelectorAll('*')` for elements whose `.type` is
+  // (case-insensitively) 'wavedrom' and unconditionally inserts a fresh
+  // WaveDrom_Display_* node for every match; it never marks a source node
+  // processed. Calling it more than once therefore re-renders (and
+  // duplicates the DOM nodes for) every diagram already rendered, not just
+  // new ones — confirmed empirically via puppeteer: 3 consecutive
+  // ProcessAll() calls produced WaveDrom_Display_* counts 1 -> 2 -> 3. Worse,
+  // ProcessAll() numbers whatever it finds THIS call starting at index 0
+  // (WaveDrom_Display_0, WaveDrom_Display_1, ...), and internally resolves
+  // both the source JSON (`eva('InputJSON_' + i)`) and the render target
+  // (`renderWaveForm` -> `getElementById('WaveDrom_Display_' + i)`) via
+  // getElementById — so on a second call, an id reused from an EARLIER call
+  // that's still sitting on an old, already-rendered node collides with the
+  // new call's id 0, and getElementById resolves to whichever element is
+  // FIRST in document order: a stale id can make a brand-new diagram get
+  // rendered from an old diagram's source JSON, or into an old diagram's
+  // display div (silently overwriting it), leaving the true new div empty —
+  // confirmed empirically the same way (adding a fresh unprocessed wavedrom
+  // script and re-invoking left the new WaveDrom_Display_* node with no
+  // <svg> while the original diagram's div picked up the new content
+  // instead). `type="WaveDrom"` / `id="InputJSON_*"` / `id="WaveDrom_Display_*"`
+  // are the only signals ProcessAll and its helpers use, so the fix is to
+  // reclaim all of those off every already-processed node before each call,
+  // so the call's fresh 0-based numbering can never collide with anything
+  // still resolvable via getElementById.
+  const diagramInitHookScript = `<script type="text/javascript" data-md2doc-diagram-engine="init-hook">
+  var __md2docWavedromSeq = 0;
+  window.__md2docInitDiagrams = function (rootEl) {
+    rootEl = rootEl || document;
+    if (typeof mermaid !== 'undefined') {
+      mermaid.initialize({ startOnLoad: false, theme: 'default' });
+      var mermaidNodes = rootEl.querySelectorAll ? rootEl.querySelectorAll('.mermaid') : [];
+      var pending = [];
+      for (var i = 0; i < mermaidNodes.length; i++) {
+        if (mermaidNodes[i].getAttribute('data-processed') !== 'true') {
+          pending.push(mermaidNodes[i]);
+        }
+      }
+      if (pending.length) {
+        mermaid.init(undefined, pending);
+      }
+    }
+    if (typeof WaveDrom !== 'undefined') {
+      // WaveDrom has no per-root scoping API — ProcessAll() always scans the
+      // whole document, so this branch is intentionally NOT scoped to
+      // rootEl (known limitation of this hook's "scoped to rootEl" contract
+      // for WaveDrom specifically). Only call it when there is at least one
+      // still-unprocessed script(type=WaveDrom) source node anywhere in the
+      // document; a node is "unprocessed" as long as its type attribute
+      // still literally reads "WaveDrom" (case as emitted by the code
+      // renderer above).
+      var wavePending = document.querySelectorAll('script[type="WaveDrom"]');
+      if (wavePending.length) {
+        // Reclaim every id ProcessAll's getElementById lookups could
+        // otherwise re-resolve to a stale, already-rendered node from an
+        // earlier call (see the comment above this script for why).
+        var stale = document.querySelectorAll(
+          '[id^="WaveDrom_Display_"], script[id^="InputJSON_"]'
+        );
+        for (var s = 0; s < stale.length; s++) {
+          stale[s].id = 'md2doc-wavedrom-done-' + (__md2docWavedromSeq++);
+        }
+        WaveDrom.ProcessAll();
+        for (var j = 0; j < wavePending.length; j++) {
+          // ProcessAll() just inserted the display div as the immediately
+          // preceding sibling of its source script node (see process-all.js:
+          // parentNode.insertBefore(node0, points.item(i))). Tag it with a
+          // stable class BEFORE the id reclaim above can ever rename it away
+          // (on a later call) — the CSS cursor rule and the lightbox click
+          // target selector both key off this class (in addition to the
+          // WaveDrom_Display_ id prefix, which non-edit pages rely on and
+          // never rename), so a diagram stays clickable and zoom-in-affordant
+          // for its whole lifetime, independent of id reclaiming.
+          var displayDiv = wavePending[j].previousElementSibling;
+          if (displayDiv) {
+            displayDiv.classList.add('wavedrom-diagram');
+          }
+          wavePending[j].setAttribute('type', 'WaveDrom-done');
+        }
+      }
+    }
+  };
+  window.addEventListener('DOMContentLoaded', function () {
+    window.__md2docInitDiagrams(document);
+  });
+</script>`;
 
-const html = `<!DOCTYPE html>
+  const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
@@ -825,7 +1019,7 @@ const html = `<!DOCTYPE html>
     align-self: stretch;
     cursor: col-resize;
     display: flex;
-    justify-content: center;
+    justify-content: flex-start;
     touch-action: none;
     user-select: none;
   }
@@ -835,6 +1029,7 @@ const html = `<!DOCTYPE html>
     border-radius: 2px;
     background: transparent;
     transition: background 0.15s ease;
+    margin-left: 4px;
   }
   .sidebar-splitter:hover::before,
   .sidebar-splitter.is-dragging::before {
@@ -1328,7 +1523,8 @@ const html = `<!DOCTYPE html>
   .content img,
   .content .mermaid,
   .content .graphviz,
-  .content [id^="WaveDrom_Display_"] { cursor: zoom-in; }
+  .content [id^="WaveDrom_Display_"],
+  .content .wavedrom-diagram { cursor: zoom-in; }
   .content a img { cursor: pointer; }
 
   .lightbox {
@@ -1501,6 +1697,249 @@ const html = `<!DOCTYPE html>
     pre  { font-size: 9pt; }
     a[href]:after { content: none; }
   }
+  /* Editor runtime (browser --edit mode). These selectors only ever appear
+     in edit-mode renders (.ed-block wrappers are only emitted when
+     opts.editMode is set — see the marked.lexer()/marked.parser() loop
+     above), so shipping this unconditionally is inert on normal HTML
+     output, same precedent as the lightbox selectors above. */
+  .ed-block { position: relative; cursor: pointer; }
+  .ed-block:hover { outline: 1px dashed #b0b0b0; }
+  .ed-li-text { display: block; min-height: 1em; }
+  li.ed-block { cursor: text; }
+  .ed-li-check { display: inline-block; width: 14px; height: 14px; margin-right: 6px;
+    border: 1px solid #8a8a8a; border-radius: 3px; vertical-align: middle; cursor: pointer; }
+  .ed-li-check[data-checked="1"] { background: #3b82f6; border-color: #3b82f6; }
+  /* Phase 3 Task 2: always-on paragraph/heading/list editing. Every eligible
+     block's content element is contenteditable from the moment it renders
+     (armEditables() in the client runtime) — no persistent outline (that
+     would outline the whole document at once); the blue "editing" outline
+     only appears while the surface is actually focused, via :focus, so it
+     naturally shows/hides itself in lockstep with the burst lifecycle
+     (focusin starts a burst, focusout ends it) without any JS-driven class
+     toggling. */
+  .ed-wys-armed { cursor: text; }
+  .ed-wys-armed:focus {
+    outline: 2px solid #3b82f6; outline-offset: 2px;
+    caret-color: #3b82f6;
+  }
+  /* Task 5: table cells armed PERMANENTLY (one edit surface per CELL, not
+     per table root — see armEditables()'s 'table' branch in the client
+     runtime) — same "no persistent outline, blue on :focus" language as
+     .ed-wys-armed above, but INSET (negative offset), not outset: the
+     enclosing table element has overflow-x: auto (see the table ruleset
+     below), which would clip an outset outline on any cell near the
+     table's horizontal edges. */
+  .ed-wys-cell { cursor: text; }
+  .ed-wys-cell:focus {
+    outline: 2px solid #3b82f6; outline-offset: -2px;
+    caret-color: #3b82f6;
+  }
+  /* Phase 3 Task 2: the ⠿ block-actions handle — one real per-block node
+     (not a floating, JS-repositioned element like .ed-seltb/.ed-tb-insert),
+     sat in the block's left gutter and revealed on hover. Only ever a
+     visibility toggle (opacity), never display or pointer-events, so a
+     script-driven click still reaches it even without a real hover. */
+  .ed-handle {
+    position: absolute; left: -22px; top: 0; width: 18px; height: 20px;
+    display: flex; align-items: center; justify-content: center;
+    padding: 0; margin: 0; border: none; border-radius: 4px;
+    background: transparent; color: #8a8a8a; font-size: 13px; line-height: 1;
+    cursor: pointer; opacity: 0; transition: opacity .12s ease, background .12s ease;
+  }
+  .ed-block:hover .ed-handle,
+  .ed-handle:focus { opacity: 1; }
+  .ed-handle:hover { background: rgba(0, 0, 0, 0.08); }
+  /* The ⠿ handle's small menu: heading ± / MD 原始碼 / close. Dark
+     translucent pill, bordered icon buttons — same visual language as
+     .ed-seltb below. */
+  .ed-handle-menu {
+    position: absolute; top: -4px; left: -4px; z-index: 6;
+    display: flex; align-items: center; gap: 4px;
+    padding: 4px 6px; border-radius: 8px;
+    background: rgba(16, 18, 21, 0.92); color: #e6edf3;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  }
+  .ed-handle-menu-btn {
+    min-width: 28px; height: 26px; padding: 0 8px;
+    border: 1px solid rgba(255, 255, 255, 0.25); border-radius: 6px;
+    background: rgba(255, 255, 255, 0.08); color: inherit;
+    font: inherit; font-size: 12px; line-height: 1;
+    white-space: nowrap; cursor: pointer;
+  }
+  .ed-handle-menu-btn:hover { background: rgba(255, 255, 255, 0.18); }
+  .ed-handle-menu-btn[hidden] { display: none; }
+  /* §10-gap fix: block-level INSERT — the ＋ button sits NEXT TO the ⠿
+     handle in the left gutter, same node/visibility-toggle shape as
+     .ed-handle above (real per-block node, opacity-only reveal on hover).
+     STACKED ABOVE the handle (same left:-22px column, top shifted up)
+     rather than beside it horizontally: .page-layout's own left padding is
+     only 24px, and .ed-handle at left:-22px already consumes nearly all of
+     it (its absolute viewport x lands at roughly 2px in a real edit-page
+     layout — measured directly). A second 18px-wide button placed FURTHER
+     left (e.g. left:-44px) would land at a NEGATIVE viewport x and be
+     unreachable/unclickable outside the visible page. The brief's own
+     wording allows this ("left gutter, above or beside it"). */
+  .ed-insert {
+    position: absolute; left: -22px; top: -22px; width: 18px; height: 20px;
+    display: flex; align-items: center; justify-content: center;
+    padding: 0; margin: 0; border: none; border-radius: 4px;
+    background: transparent; color: #8a8a8a; font-size: 13px; line-height: 1;
+    cursor: pointer; opacity: 0; transition: opacity .12s ease, background .12s ease;
+  }
+  .ed-block:hover .ed-insert,
+  .ed-insert:focus { opacity: 1; }
+  .ed-insert:hover { background: rgba(0, 0, 0, 0.08); }
+  /* The ＋ button's small menu: 段落/標題/清單/表格/程式碼 — same dark
+     translucent pill language as .ed-handle-menu above. */
+  .ed-insert-menu {
+    position: absolute; top: -4px; left: -4px; z-index: 6;
+    display: flex; align-items: center; gap: 4px;
+    padding: 4px 6px; border-radius: 8px;
+    background: rgba(16, 18, 21, 0.92); color: #e6edf3;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  }
+  .ed-insert-menu-btn {
+    min-width: 28px; height: 26px; padding: 0 8px;
+    border: 1px solid rgba(255, 255, 255, 0.25); border-radius: 6px;
+    background: rgba(255, 255, 255, 0.08); color: inherit;
+    font: inherit; font-size: 12px; line-height: 1;
+    white-space: nowrap; cursor: pointer;
+  }
+  .ed-insert-menu-btn:hover { background: rgba(255, 255, 255, 0.18); }
+  /* Task 5: hover-edge column/row insert bubbles — a SINGLETON pair of "＋"
+     buttons (client runtime repositions them via getBoundingClientRect(),
+     never creates more than these two). Visual language deliberately
+     matches .ed-handle above (small, low-contrast, no persistent chrome)
+     rather than .ed-seltb/.ed-handle-menu's dark pill — this is a single
+     small affordance shown only within TB_EDGE_PX of a boundary, not a
+     toolbar. position: fixed matches the viewport-relative coordinates the
+     client runtime computes via getBoundingClientRect(). */
+  .ed-tb-insert {
+    position: fixed; z-index: 8;
+    width: 18px; height: 18px; padding: 0; margin: 0;
+    display: flex; align-items: center; justify-content: center;
+    border: 1px solid #3b82f6; border-radius: 50%;
+    background: #fff; color: #3b82f6; font-size: 13px; line-height: 1;
+    cursor: pointer; box-shadow: 0 1px 4px rgba(0, 0, 0, 0.2);
+  }
+  .ed-tb-insert:hover { background: #3b82f6; color: #fff; }
+  .ed-tb-insert[hidden] { display: none; }
+  /* Task 6: table edge-click menus (delete/align) + row drag-reorder.
+     '.ed-te-hl' marks the currently-selected column's cells (th+td) or row
+     (the <tr> itself) — !important because the sticky-first-column rules
+     below (tbody td:first-child / thead th:first-child) carry higher
+     specificity (0,1,2 vs this class's 0,1,0) and would otherwise win over
+     a first-column/first-row highlight despite this rule appearing later in
+     source order. '.ed-te-menu' is a SINGLETON floating menu (position:
+     fixed, same viewport-relative idiom as .ed-seltb/.ed-tb-insert above),
+     relabeled/repositioned per click rather than rebuilt. '.ed-te-drop-
+     indicator' is the singleton line shown while dragging a row.
+     '.ed-te-row-dragging' dims the row actually being dragged. */
+  .ed-te-hl { background: rgba(59, 130, 246, 0.15) !important; }
+  .ed-te-menu {
+    position: fixed; z-index: 12;
+    display: flex; align-items: center; gap: 4px;
+    padding: 4px 6px; border-radius: 8px;
+    background: rgba(16, 18, 21, 0.92); color: #e6edf3;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  }
+  .ed-te-menu[hidden] { display: none; }
+  .ed-te-menu-btn {
+    min-width: 28px; height: 26px; padding: 0 8px;
+    border: 1px solid rgba(255, 255, 255, 0.25); border-radius: 6px;
+    background: rgba(255, 255, 255, 0.08); color: inherit;
+    font: inherit; font-size: 12px; line-height: 1;
+    white-space: nowrap; cursor: pointer;
+  }
+  .ed-te-menu-btn:hover { background: rgba(255, 255, 255, 0.18); }
+  .ed-te-menu-btn[hidden] { display: none; }
+  .ed-te-drop-indicator {
+    position: fixed; z-index: 8; height: 3px; border-radius: 2px;
+    background: #3b82f6; pointer-events: none;
+  }
+  .ed-te-drop-indicator[hidden] { display: none; }
+  .ed-te-row-dragging { opacity: 0.4; }
+  /* Notion-style grip handles: replace the original invisible TE_EDGE_PX=8
+     proximity zone (user-acceptance feedback: unusably small, no visible
+     affordance) with two real, adequately-sized (>=18x24px) click/drag
+     targets. '.ed-te-grip-row' is a vertical 6-dot handle shown just LEFT
+     of the hovered BODY row (never the header); '.ed-te-grip-col' is a
+     horizontal 6-dot handle shown just ABOVE the hovered column (every
+     column). Dots are plain <span>s laid out via CSS grid with
+     place-content: center, so the dot cluster stays compact/centered
+     regardless of the button's own (larger, hit-target-sized) box — no
+     images, no background gradients. '.ed-te-grip-dragging' is the row
+     grip's own "active drag handle" visual (grabbing cursor) while a row
+     drag is in flight — see cancelTeDrag()/the pointermove listener in the
+     client runtime. */
+  .ed-te-grip {
+    position: fixed; z-index: 9; padding: 0; margin: 0; border: none;
+    border-radius: 4px; background: transparent;
+    display: grid; place-content: center;
+    transition: background .12s ease;
+  }
+  .ed-te-grip[hidden] { display: none; }
+  .ed-te-grip:hover { background: rgba(0, 0, 0, 0.06); }
+  .ed-te-grip-dot { width: 3px; height: 3px; border-radius: 50%; background: #9ca3af; }
+  .ed-te-grip:hover .ed-te-grip-dot { background: #6b7280; }
+  .ed-te-grip-row {
+    width: 20px; height: 28px; cursor: grab; z-index: 7;
+    grid-template-columns: repeat(2, 3px); grid-template-rows: repeat(3, 3px);
+    gap: 3px 4px;
+  }
+  .ed-te-grip-row.ed-te-grip-dragging { cursor: grabbing; }
+  .ed-te-grip-col {
+    width: 28px; height: 24px; cursor: pointer; z-index: 7;
+    grid-template-columns: repeat(3, 3px); grid-template-rows: repeat(2, 3px);
+    gap: 4px 3px;
+  }
+  /* Task 4: floating selection toolbar (bold/italic/strikethrough/underline/
+     code/link), shown over a
+     non-collapsed selection inside an active WYSIWYG session. position:
+     fixed matches the viewport-relative coordinates the client runtime
+     computes via Range.getBoundingClientRect(). z-index sits below
+     .ed-conflict (999). */
+  .ed-seltb {
+    position: fixed; z-index: 15;
+    display: flex; align-items: center; gap: 4px;
+    padding: 4px 6px; border-radius: 8px;
+    background: rgba(16, 18, 21, 0.92); color: #e6edf3;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  }
+  .ed-seltb-btn {
+    min-width: 28px; height: 26px; padding: 0 8px;
+    border: 1px solid rgba(255, 255, 255, 0.25); border-radius: 6px;
+    background: rgba(255, 255, 255, 0.08); color: inherit;
+    font: inherit; font-size: 13px; line-height: 1;
+    white-space: nowrap; cursor: pointer;
+  }
+  .ed-seltb-btn:hover { background: rgba(255, 255, 255, 0.18); }
+  .ed-seltb-b { font-weight: bold; }
+  .ed-seltb-i { font-style: italic; }
+  .ed-seltb-s { text-decoration: line-through; }
+  .ed-seltb-u { text-decoration: underline; }
+  .ed-editing { position: relative; }
+  .ed-raw {
+    display: block; width: 100%; font-family: monospace; font-size: 13px;
+    min-height: 3em; box-sizing: border-box; padding: 6px;
+    border: 1px solid #808080; resize: vertical;
+  }
+  .ed-controls { display: flex; gap: 6px; margin-top: 4px; }
+  .ed-controls button {
+    font-size: 13px; padding: 2px 10px; cursor: pointer;
+    border: 1px solid #b0b0b0; border-radius: 4px; background: #fff;
+  }
+  .ed-commit { color: #0a7a0a; }
+  .ed-cancel { color: #b00020; }
+  .ed-conflict {
+    position: fixed; top: 0; left: 0; right: 0; padding: 10px;
+    background: #b00020; color: #fff; z-index: 999; text-align: center;
+    display: flex; align-items: center; justify-content: center; gap: 12px;
+  }
+  .ed-conflict button {
+    background: #fff; color: #b00020; border: none; border-radius: 4px;
+    padding: 4px 12px; cursor: pointer; font-weight: bold;
+  }
 </style>
 ${usesMath ? buildKatexStyleTag() : ''}
 </head>
@@ -1515,7 +1954,20 @@ ${bodyHtml}
 </div>
 
 <!-- WaveDrom -->
-${usesWaveDrom ? `${waveDromSkinTag}
+${usesWaveDrom
+    ? (opts.editMode
+        // Edit mode: WaveDrom init is driven entirely by diagramInitHookScript
+        // (emitted from the Mermaid section below, unconditionally whenever
+        // opts.editMode is true) — NOT by this block's own retry script.
+        // Running both here would race: this script's own DOMContentLoaded
+        // listener calls the un-deduped WaveDrom.ProcessAll() directly, so if
+        // it fires before the hook gets a chance to mark the source node
+        // processed, the very first page load already double-renders the
+        // diagram. Only embedding the library here (no init script) removes
+        // that race and leaves the hook as the single authority.
+        ? `${waveDromSkinTag}
+${waveDromTag}`
+        : `${waveDromSkinTag}
 ${waveDromTag}
 <script type="text/javascript" data-md2doc-diagram-engine="wavedrom">
   function renderWaveDrom() {
@@ -1527,11 +1979,17 @@ ${waveDromTag}
   window.addEventListener('load', renderWaveDrom);
   setTimeout(renderWaveDrom, 250);
   setTimeout(renderWaveDrom, 1000);
-</script>` : ''}
+</script>`)
+    : ''}
 
 <!-- Mermaid -->
-${usesMermaid ? `${mermaidScriptTag}
-${mermaidInitTag}` : ''}
+${usesMermaid
+    ? (opts.editMode
+        ? `${mermaidScriptTag}
+${diagramInitHookScript}`
+        : `${mermaidScriptTag}
+${mermaidInitTag}`)
+    : (opts.editMode ? diagramInitHookScript : '')}
 
 <!-- Reader runtime -->
 <script id="reader-section-data" type="application/json">${serializedSections}</script>
@@ -1549,7 +2007,14 @@ ${mermaidInitTag}` : ''}
 
   const rawData = document.getElementById('reader-section-data');
   const sections = rawData ? JSON.parse(rawData.textContent || '[]') : [];
-  const headingNodes = Array.from(document.querySelectorAll('[data-reader-heading]'));
+  // let, not const: edit mode's rerenderAll() swaps .content's innerHTML
+  // wholesale after a commit (see lib/editor/client.js), which detaches every
+  // node this was captured from. window.__md2docRebindReader() below
+  // re-queries and reassigns this same binding so every closure in this IIFE
+  // that reads headingNodes (detectActiveHeading, the zoom/resize scroll
+  // anchor's binary search, …) sees the live nodes without needing its own
+  // re-init call — they all close over this one variable, not a copy of it.
+  let headingNodes = Array.from(document.querySelectorAll('[data-reader-heading]'));
   const tocLinks = new Map(
     Array.from(document.querySelectorAll('.toc a[href^="#"]')).map((link) => [link.getAttribute('href').slice(1), link])
   );
@@ -1648,8 +2113,22 @@ ${mermaidInitTag}` : ''}
     }
   }
 
-  if (typeof IntersectionObserver !== 'undefined' && headingNodes.length) {
-    const observer = new IntersectionObserver((entries) => {
+  // Hoisted out of a bare if block (and into a rebindable function) so that
+  // window.__md2docRebindReader() below can disconnect the stale observer
+  // and create a fresh one over the post-edit heading nodes — an observer
+  // keeps observing the exact node references passed to observe(), so after
+  // .content's innerHTML is replaced wholesale, the old observer is watching
+  // detached nodes that will never intersect anything again.
+  let headingObserver = null;
+  function bindHeadingObserver() {
+    if (headingObserver) {
+      headingObserver.disconnect();
+      headingObserver = null;
+    }
+    if (typeof IntersectionObserver === 'undefined' || !headingNodes.length) {
+      return;
+    }
+    headingObserver = new IntersectionObserver((entries) => {
       if (observerFrozen) {
         return;
       }
@@ -1660,8 +2139,9 @@ ${mermaidInitTag}` : ''}
         syncActiveHeading(visible[0].target.id);
       }
     }, { rootMargin: '0px 0px -65% 0px', threshold: [0, 1] });
-    headingNodes.forEach((node) => observer.observe(node));
+    headingNodes.forEach((node) => headingObserver.observe(node));
   }
+  bindHeadingObserver();
 
   // Paint the breadcrumb immediately so the header is populated before the
   // first IntersectionObserver callback fires.
@@ -1669,6 +2149,26 @@ ${mermaidInitTag}` : ''}
     renderBreadcrumb(sections[0].id);
   }
 
+  // Edit mode only: re-init hook, sibling to window.__md2docInitDiagrams
+  // (defined in diagramInitHookScript above for edit-mode pages), called
+  // from lib/editor/client.js's rerenderAll() right after it swaps
+  // .content's innerHTML on a commit. Re-queries the heading nodes that
+  // just got replaced and rebinds the IntersectionObserver onto them, so
+  // TOC highlighting / breadcrumb tracking / the zoom-resize scroll anchor
+  // (all of which read the headingNodes binding above) keep working
+  // against live nodes instead of silently going dead after the first edit.
+  // Defined unconditionally (this script runs on every page, not just edit
+  // mode) but never invoked outside the edit-mode client — non-edit pages'
+  // on-load behavior is unchanged since nothing here calls it automatically.
+  window.__md2docRebindReader = function () {
+    // Always re-queries the whole document, matching the initial-load query
+    // above — heading nodes only ever live inside .content, but scoping this
+    // to a passed-in root would just be an equivalent, more fragile way of
+    // saying the same thing.
+    headingNodes = Array.from(document.querySelectorAll('[data-reader-heading]'));
+    bindHeadingObserver();
+  };
+
   const allTocDetails = () => Array.from(document.querySelectorAll('.toc details'));
   const expandAllBtn = document.getElementById('toc-expand-all');
   if (expandAllBtn) {
@@ -2197,7 +2697,7 @@ ${mermaidInitTag}` : ''}
   // Specs are read at 100% but their block diagrams and waveforms are drawn far
   // wider than the column, so the inline copy is unreadably small. Clicking one
   // pops it into a modal stage that zooms and scrolls.
-  var LIGHTBOX_TARGETS = 'img, .mermaid, .graphviz, [id^="WaveDrom_Display_"]';
+  var LIGHTBOX_TARGETS = 'img, .mermaid, .graphviz, [id^="WaveDrom_Display_"], .wavedrom-diagram';
   var LIGHTBOX_MIN_ZOOM = 0.05;
   var LIGHTBOX_MAX_ZOOM = 8;
   var LIGHTBOX_STEP = 1.25;
@@ -2216,7 +2716,8 @@ ${mermaidInitTag}` : ''}
   // scratch, and localStorage keys would go stale when the doc regenerates).
   var ANNO_NS = 'http://www.w3.org/2000/svg';
   var ANNO_COLORS = ['#ef4444', '#3b82f6', '#22c55e', '#f59e0b', '#111827'];
-  var ANNO_WIDTHS = [0.6, 1, 1.8];
+  // Office-like absolute stroke widths: rendered px at fit zoom (S/M/L).
+  var ANNO_WIDTHS = [1, 2, 4];
   var annoStore = (typeof WeakMap === 'function') ? new WeakMap() : null;
   var annoShapes = [];
   var annoSvg = null;
@@ -2227,7 +2728,7 @@ ${mermaidInitTag}` : ''}
   var annoRedoStack = [];
   var annoStrokeW = 3;
   var annoColor = ANNO_COLORS[0];
-  var annoWidthScale = 1;
+  var annoWidth = ANNO_WIDTHS[1];
   var annoToolButtons = {};
   var annoStyleButtons = [];
   var annoSourceNode = null;
@@ -2367,7 +2868,7 @@ ${mermaidInitTag}` : ''}
       el.setAttribute('stroke-linecap', 'round');
     }
     el.setAttribute('stroke', color);
-    el.setAttribute('stroke-width', (annoStrokeW * (shape.ws || 1)).toFixed(1));
+    el.setAttribute('stroke-width', (shape.sw || annoStrokeW).toFixed(2));
     return el;
   }
 
@@ -2411,13 +2912,14 @@ ${mermaidInitTag}` : ''}
         }
         hit.setAttribute('fill', 'none');
         hit.setAttribute('stroke', 'transparent');
-        hit.setAttribute('stroke-width', String(annoStrokeW * 5));
+        hit.setAttribute('stroke-width', String(Math.max((shape.sw || annoStrokeW) * 5, 10 / (lightboxFitZoom || 1))));
         hit.setAttribute('data-anno-hit', '');
         g.appendChild(hit);
       }
       annoSvg.appendChild(g);
     });
     if (annoSelected && annoShapes.indexOf(annoSelected) !== -1) {
+      var u = 1.5 / (lightboxFitZoom || 1); // ~1.5px at fit zoom
       var box = annoBBox(annoSelected);
       var ui = document.createElementNS(ANNO_NS, 'rect');
       ui.setAttribute('data-anno-ui', '');
@@ -2425,10 +2927,10 @@ ${mermaidInitTag}` : ''}
       ui.setAttribute('width', Math.max(0.1, box.w)); ui.setAttribute('height', Math.max(0.1, box.h));
       ui.setAttribute('fill', 'none');
       ui.setAttribute('stroke', '#3b82f6');
-      ui.setAttribute('stroke-width', String(Math.max(1, annoStrokeW / 2)));
-      ui.setAttribute('stroke-dasharray', (annoStrokeW * 2) + ' ' + annoStrokeW);
+      ui.setAttribute('stroke-width', String(u));
+      ui.setAttribute('stroke-dasharray', (u * 4) + ' ' + (u * 2));
       annoSvg.appendChild(ui);
-      var hs = annoStrokeW * 3;
+      var hs = u * 6;
       [[box.x, box.y], [box.x + box.w, box.y], [box.x, box.y + box.h], [box.x + box.w, box.y + box.h]]
         .forEach(function (corner, i) {
           var h = document.createElementNS(ANNO_NS, 'rect');
@@ -2460,7 +2962,7 @@ ${mermaidInitTag}` : ''}
     } else if (op.kind === 'style') {
       var style = reverse ? op.before : op.after;
       op.shape.color = style.color;
-      op.shape.ws = style.ws;
+      op.shape.sw = style.sw;
     } else if (op.kind === 'clear') {
       if (reverse) op.shapes.forEach(function (s) { annoShapes.push(s); });
       else annoShapes.length = 0;
@@ -2507,21 +3009,21 @@ ${mermaidInitTag}` : ''}
 
   function setAnnoStyle(patch) {
     if (patch.color) annoColor = patch.color;
-    if (patch.ws) annoWidthScale = patch.ws;
+    if (patch.w) annoWidth = patch.w;
     annoStyleButtons.forEach(function (entry) {
       entry.button.classList.toggle('is-active',
-        entry.kind === 'color' ? entry.value === annoColor : entry.value === annoWidthScale);
+        entry.kind === 'color' ? entry.value === annoColor : entry.value === annoWidth);
     });
     // With a selection, the pickers restyle it (undoably); otherwise they only
     // set the style for the next shape.
     if (annoSelected) {
-      var beforeStyle = { color: annoSelected.color, ws: annoSelected.ws };
+      var beforeStyle = { color: annoSelected.color, sw: annoSelected.sw };
       annoSelected.color = patch.color || annoSelected.color;
-      annoSelected.ws = patch.ws || annoSelected.ws;
+      if (patch.w) annoSelected.sw = patch.w / (lightboxFitZoom || 1);
       annoPushOp({
         kind: 'style', shape: annoSelected,
         before: beforeStyle,
-        after: { color: annoSelected.color, ws: annoSelected.ws },
+        after: { color: annoSelected.color, sw: annoSelected.sw },
       });
       annoRedraw();
     }
@@ -2690,6 +3192,11 @@ ${mermaidInitTag}` : ''}
         annoSelected = null;
         annoRedraw();
       }
+      // The baked clone still shows the shape at its old spot — revert to the
+      // base image for the gesture; the overlay alone renders the live shapes.
+      if (annoDraft && annoCloneEl && annoCloneEl.tagName === 'IMG' && annoBaseSrc) {
+        annoCloneEl.src = annoBaseSrc;
+      }
       return;
     }
     var shape;
@@ -2699,7 +3206,7 @@ ${mermaidInitTag}` : ''}
     else if (annoMode === 'a') shape = { type: 'arrow', x1: pt.x, y1: pt.y, x2: pt.x, y2: pt.y };
     else shape = { type: 'rect', x: pt.x, y: pt.y, w: 0, h: 0 };
     shape.color = annoColor;
-    shape.ws = annoWidthScale;
+    shape.sw = annoWidth / (lightboxFitZoom || 1);
     annoDraft = { kind: 'draw', shape: shape, start: pt, el: annoShapeEl(shape), clientDist: 0, lastClient: [event.clientX, event.clientY] };
     annoSvg.appendChild(annoDraft.el);
   }
@@ -2766,6 +3273,8 @@ ${mermaidInitTag}` : ''}
     }
     if (d.moved) {
       annoPushOp({ kind: 'geom', shape: d.shape, before: d.before, after: annoGeomOf(d.shape) });
+    } else {
+      annoBake(); // gesture reverted the clone to the base image — restore it
     }
     annoRedraw();
   }
@@ -2845,9 +3354,9 @@ ${mermaidInitTag}` : ''}
       bar.appendChild(swatch);
     });
     [['S', ANNO_WIDTHS[0]], ['M', ANNO_WIDTHS[1]], ['L', ANNO_WIDTHS[2]]].forEach(function (width) {
-      var button = lightboxButton(width[0], 'Stroke width ' + width[0], function () { setAnnoStyle({ ws: width[1] }); });
+      var button = lightboxButton(width[0], 'Stroke width ' + width[1] + 'px', function () { setAnnoStyle({ w: width[1] }); });
       button.setAttribute('data-anno-width', String(width[1]));
-      if (width[1] === annoWidthScale) button.classList.add('is-active');
+      if (width[1] === annoWidth) button.classList.add('is-active');
       annoStyleButtons.push({ kind: 'width', value: width[1], button: button });
       bar.appendChild(button);
     });
@@ -2948,7 +3457,18 @@ ${mermaidInitTag}` : ''}
 
     var isVector = !!(source.tagName && source.tagName.toLowerCase() === 'svg');
     var clone = source.cloneNode(true);
-    clone.removeAttribute('id');
+    // Mermaid scopes its embedded <style> to the svg's #id — dropping the id
+    // kills the theme. Rename it instead (avoids a duplicate id) and rewrite
+    // the scoped selectors to the new name.
+    if (isVector && source.id) {
+      var lightboxCloneId = 'lightbox-' + source.id;
+      clone.setAttribute('id', lightboxCloneId);
+      Array.prototype.forEach.call(clone.querySelectorAll('style'), function (styleEl) {
+        styleEl.textContent = styleEl.textContent.split('#' + source.id).join('#' + lightboxCloneId);
+      });
+    } else {
+      clone.removeAttribute('id');
+    }
     clone.removeAttribute('class');
     clone.removeAttribute('style');
     clone.removeAttribute('width');
@@ -3048,6 +3568,12 @@ ${mermaidInitTag}` : ''}
 </body>
 </html>`;
 
+  const bakedHtml = await bakeGraphviz(html);
+  const bakedBody = await bakeGraphviz(bodyHtml);
+  return { html: bakedHtml, bodyHtml: bakedBody, blocks };
+}
+module.exports = { renderMarkdown };
+
 // Render every deferred dot/graphviz placeholder to inline SVG using the
 // in-process WASM engine. Loads the WASM module only when at least one dot
 // block exists, so text-only docs pay nothing.
@@ -3088,7 +3614,7 @@ function launchBrowser(puppeteer) {
 
 // Pre-render mermaid/wavedrom to inert SVG using headless Chromium, then strip
 // the diagram-engine runtime scripts so the output HTML carries no diagram JS.
-async function bakeDiagrams(htmlStr) {
+async function bakeDiagrams(htmlStr, dstPath) {
   if (!/data-md2doc-diagram-engine/.test(htmlStr)) return htmlStr;
   let puppeteer;
   try {
@@ -3097,7 +3623,7 @@ async function bakeDiagrams(htmlStr) {
     console.error('[ERROR] --bake-svg requires puppeteer/Chromium — install it, or drop --bake-svg:', e.message);
     process.exit(1);
   }
-  const tmp = dst.replace(/\.html$/i, '._bake.html');
+  const tmp = dstPath.replace(/\.html$/i, '._bake.html');
   fs.writeFileSync(tmp, htmlStr, 'utf8');
   let browser;
   try {
@@ -3121,59 +3647,72 @@ async function bakeDiagrams(htmlStr) {
   }
 }
 
-// ── Output ───────────────────────────────────────────────────────────────────
-(async () => {
-  let finalHtml = await bakeGraphviz(html);
-
-  if (ext === '.html') {
-    if (BAKE_SVG) finalHtml = await bakeDiagrams(finalHtml);
-    fs.writeFileSync(dst, finalHtml, 'utf8');
-    console.log(`[HTML] ${src} → ${dst}`);
-
-  } else if (ext === '.pdf') {
-    if (BAKE_SVG) console.log('[INFO] --bake-svg is redundant for PDF output (already static); ignoring');
-    let puppeteer;
-    try {
-      puppeteer = require('puppeteer');
-    } catch (e) {
-      console.error('[ERROR] puppeteer not found — install with: npm install puppeteer');
-      process.exit(1);
-    }
+// ── CLI ──────────────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const [,, src, dst] = process.argv;
+  const BAKE_SVG = process.argv.slice(4).includes('--bake-svg');
+  if (!src || !dst) {
+    console.error('Usage: node md2doc.js <input.md> <output.html|pdf>');
+    process.exit(1);
+  }
 
-    // Write temporary HTML, launch headless Chromium, export PDF.
-    // Case-insensitive: an uppercase .PDF dst must not make tmp === dst, or the
-    // unlinkSync below deletes the freshly written PDF.
-    const tmp = dst.replace(/\.pdf$/i, '._tmp.html');
-    fs.writeFileSync(tmp, finalHtml, 'utf8');
+  const ext = path.extname(dst).toLowerCase();
 
-    const browser = await launchBrowser(puppeteer);
-    const page = await browser.newPage();
+  (async () => {
+    const mdText = fs.readFileSync(src, 'utf8');
+    const { html } = await renderMarkdown(mdText, path.resolve(src), {});
+    let finalHtml = html;
 
-    await page.goto('file://' + path.resolve(tmp), { waitUntil: 'load' });
+    if (ext === '.html') {
+      if (BAKE_SVG) finalHtml = await bakeDiagrams(finalHtml, dst);
+      fs.writeFileSync(dst, finalHtml, 'utf8');
+      console.log(`[HTML] ${src} → ${dst}`);
 
-    // Allow WaveDrom / Mermaid scripts time to render diagrams.
-    // NOTE: this sleep is load-bearing for the DEFAULT (view-time) render path.
-    // It is only safe to drop under --bake-svg, where the DOM is already final SVG.
-    await new Promise(r => setTimeout(r, DIAGRAM_RENDER_WAIT_MS));
+    } else if (ext === '.pdf') {
+      if (BAKE_SVG) console.log('[INFO] --bake-svg is redundant for PDF output (already static); ignoring');
+      let puppeteer;
+      try {
+        puppeteer = require('puppeteer');
+      } catch (e) {
+        console.error('[ERROR] puppeteer not found — install with: npm install puppeteer');
+        process.exit(1);
+      }
 
-    await page.pdf({
-      path:            dst,
-      format:          'A4',
-      printBackground: true,
-      outline:         true,
-      tagged:          true,
-      margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' }
-    });
+      // Write temporary HTML, launch headless Chromium, export PDF.
+      // Case-insensitive: an uppercase .PDF dst must not make tmp === dst, or the
+      // unlinkSync below deletes the freshly written PDF.
+      const tmp = dst.replace(/\.pdf$/i, '._tmp.html');
+      fs.writeFileSync(tmp, finalHtml, 'utf8');
+
+      const browser = await launchBrowser(puppeteer);
+      const page = await browser.newPage();
+
+      await page.goto('file://' + path.resolve(tmp), { waitUntil: 'load' });
+
+      // Allow WaveDrom / Mermaid scripts time to render diagrams.
+      // NOTE: this sleep is load-bearing for the DEFAULT (view-time) render path.
+      // It is only safe to drop under --bake-svg, where the DOM is already final SVG.
+      await new Promise(r => setTimeout(r, DIAGRAM_RENDER_WAIT_MS));
+
+      await page.pdf({
+        path:            dst,
+        format:          'A4',
+        printBackground: true,
+        outline:         true,
+        tagged:          true,
+        margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' }
+      });
 
-    await browser.close();
-    fs.unlinkSync(tmp);
-    console.log(`[PDF]  ${src} → ${dst}`);
+      await browser.close();
+      fs.unlinkSync(tmp);
+      console.log(`[PDF]  ${src} → ${dst}`);
 
-  } else {
-    console.error('[ERROR] Output extension must be .html or .pdf');
+    } else {
+      console.error('[ERROR] Output extension must be .html or .pdf');
+      process.exit(1);
+    }
+  })().catch((e) => {
+    console.error('[ERROR]', (e && e.stack) || e);
     process.exit(1);
-  }
-})().catch((e) => {
-  console.error('[ERROR]', (e && e.stack) || e);
-  process.exit(1);
-});
+  });
+}