@helping-ai-workflow/md2doc 3.3.0 → 3.4.0

package/lib/md2doc.js

@@ -20,11 +20,65 @@
 
 const fs            = require('fs');
 const path          = require('path');
+const drawio        = require('./drawio.js');
 
 // 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;
 
+// v3.4.0 batch2 final review R9 — the deferred-diagram placeholders.
+//
+// A placeholder is written by the synchronous marked() pass and read back by
+// an async post-pass roughly four thousand lines away in this same file
+// (bakeDrawio / bakeGraphviz). The two sites used to agree only by
+// character-for-character attribute ordering, and nothing failed if they
+// drifted: a matcher that no longer matches collects zero jobs, the post-pass
+// returns the string untouched, and the placeholder — which carries the
+// base64 of the WHOLE source .drawio file or dot block — ships inside an
+// empty div. Silent, and invisible to every test that only asserts on the
+// baked shape.
+//
+// So the emitter and the matcher are both generated from one ordered field
+// list. Adding, renaming or reordering an attribute changes both at once;
+// there is no edit that can move one without the other.
+//
+// Two rules the field list relies on:
+//   - every value must already be safe inside a double-quoted attribute —
+//     base64 for anything free-form (the source, the alt text), digits for
+//     the page index;
+//   - a field is never omitted. A field with nothing to say carries the empty
+//     string, so the matcher's arity is fixed and "this one had no alt text"
+//     cannot degrade into a no-match.
+function makePlaceholderShape(className, fields) {
+  const open = `<div class="${className}" `;
+  const quoteRe = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, (c) => '\\' + c);
+  return {
+    // `probe` is the cheap "is there anything to do at all?" test the bake
+    // passes run before doing any work. Derived from the first field rather
+    // than spelled out again, for the same no-drift reason as `re`.
+    probe: new RegExp(quoteRe(fields[0][0]) + '='),
+    html(values) {
+      return open + fields.map((f, i) => `${f[0]}="${values[i]}"`).join(' ') + '></div>';
+    },
+    re: new RegExp(
+      quoteRe(open) + fields.map((f) => quoteRe(f[0]) + '="' + f[1] + '"').join(' ') + '><\\/div>',
+      'g'),
+  };
+}
+
+const DRAWIO_PLACEHOLDER = makePlaceholderShape('drawio', [
+  ['data-drawio-src',  '([^"]*)'],
+  ['data-drawio-page', '(\\d+)'],
+  // v3.4.0 batch2 final review R5 — the markdown author's alt text, base64 of
+  // the already-HTML-escaped string marked hands us, so it survives the trip
+  // to bakeDrawio() and becomes the baked box's accessible name.
+  ['data-drawio-alt',  '([^"]*)'],
+]);
+
+const GRAPHVIZ_PLACEHOLDER = makePlaceholderShape('graphviz', [
+  ['data-graphviz-src', '([^"]*)'],
+]);
+
 function firstExistingPath(candidates) {
   for (const candidate of candidates) {
     if (!candidate) {
@@ -321,6 +375,29 @@ async function renderMarkdown(mdText, srcPath, opts = {}) {
   const src = srcPath;
   let usesMermaid = false;
   let usesWaveDrom = false;
+  let usesDrawio = false;
+  // Set only when some drawio reference actually resolves to 2+ pages — the
+  // sheet bar (CSS + runtime) is gated on this, not on usesDrawio alone, so a
+  // single-page .drawio file never pays for multi-page UI.
+  let usesDrawioMultiPage = false;
+  // v3.4.0 batch2 Task 6: every `.drawio`/`.xml` source path this render
+  // actually resolved and read, so a caller (lib/editor/server.js) can stat
+  // them later to notice an external edit — resolveAssetPath()'s result was
+  // previously a pure local inside drawioPlaceholderFor(), never surviving
+  // past the base64 it gets embedded as (see the investigation note this
+  // task shipped with). A Map, not an array, so the same referenced file
+  // linked from two different images is only stat'd once.
+  //
+  // Fix round 1 (review F4): the VALUE is the file's stamp taken here, at
+  // read time, not later by the caller. bakeDrawio() launches headless
+  // Chromium and bakes every page after this function returns — seconds, not
+  // microseconds, on first use — so a stamp taken by the caller AFTER the
+  // bake records bytes that were never baked, and every later comparison
+  // then answers "up to date" about a revision nobody ever rendered. Taken
+  // BEFORE the readFileSync below for the same reason in miniature: a stamp
+  // that is older than the bytes we baked costs one redundant re-render,
+  // while one that is newer loses the change permanently.
+  const drawioRefs = new Map();
   let usesMath = false;
   let blocks = null;
   // ── Local image assets ───────────────────────────────────────────────────────
@@ -436,6 +513,68 @@ async function renderMarkdown(mdText, srcPath, opts = {}) {
     return uri ? uri + fragment : null;
   }
 
+  // v3.4.0 §4. drawio (.drawio / .xml) goes down the graphviz-style path — a
+  // placeholder carrying the source, baked to inline SVG by an async post-pass
+  // — instead of image inlining. Returns the placeholder markup, or null to
+  // mean "not a drawio reference, fall through to the normal image path"
+  // (missing file, non-drawio content, or an extension we don't touch at all).
+  // Must run BEFORE inlineImageSrc(): that function warnOnce()s "not a known
+  // image extension" for anything outside IMAGE_MIME_BY_EXT, and .drawio/.xml
+  // are not image extensions — by the time control reached inlineImageSrc it
+  // would already be too late.
+  function drawioPlaceholderFor(href, altText) {
+    if (!href || isExternalRef(href)) return null;
+    const { filePart, fragment } = splitAssetRef(href);
+    if (!filePart) return null;
+    const ext = path.extname(filePart).toLowerCase();
+    if (ext !== '.drawio' && ext !== '.xml') return null;
+
+    const abs = resolveAssetPath(filePart);
+    if (!abs) return null;   // No such file: let the ordinary image path warn.
+
+    // Stamp BEFORE the read — see the drawioRefs comment above.
+    const stamp = drawio.drawioStampOf(abs);
+    let xml;
+    try { xml = fs.readFileSync(abs, 'utf8'); }
+    catch (e) { return null; }
+
+    if (!drawio.isDrawioXml(xml)) {
+      // Extension matched but the content didn't — worth a warning for
+      // .drawio (that extension promises mxfile/mxGraphModel content), but
+      // not for .xml (most .xml files are not diagrams, so silently falling
+      // through to the normal image/HTML path is the right default).
+      if (ext === '.drawio') {
+        warnOnce(href, `[WARN] .drawio file is not mxfile/mxGraphModel, left as-is: ${href}`);
+      }
+      return null;
+    }
+
+    usesDrawio = true;
+    drawioRefs.set(abs, stamp);
+    const names = drawio.pageNamesOf(xml);
+    if (names.length >= 2) usesDrawioMultiPage = true;
+    // splitAssetRef() keeps the leading '#' (it's re-appended verbatim to a
+    // data: URI elsewhere), but resolvePageIndex() expects the bare page
+    // name/number — strip it here rather than teach resolvePageIndex two
+    // input shapes.
+    const pageFragment = fragment ? fragment.slice(1) : '';
+    const pageIndex = drawio.resolvePageIndex(names, pageFragment);
+    const b64 = Buffer.from(xml, 'utf8').toString('base64');
+    // v3.4.0 batch2 final review R5 — carry the author's alt text through to
+    // bakeDrawio(), which turns it into the baked box's accessible name. It
+    // travels base64-encoded for the same reason the source does: the shared
+    // placeholder shape's contract is that every value is already safe inside
+    // a double-quoted attribute, and an alt text can contain anything.
+    //
+    // `altText` is marked's `token.text`, which is ALREADY HTML-escaped
+    // (MEASURED on marked 14: `![A "q" & <b>](x)` arrives as
+    // `A &quot;q&quot; &amp; &lt;b&gt;`) — the same string the ordinary
+    // `<img alt="${text}">` path below interpolates raw. So it must not be
+    // escaped again here or on the way out.
+    const altB64 = Buffer.from(String(altText || ''), 'utf8').toString('base64');
+    return '\n' + DRAWIO_PLACEHOLDER.html([b64, pageIndex, altB64]) + '\n';
+  }
+
   // A srcset value is a comma-separated list of `<url> <descriptor>` candidates.
   function inlineSrcsetValue(value) {
     const parts = String(value).split(',');
@@ -588,6 +727,8 @@ ${itemsHtml}
 </ul>`;
     }
 
+    // 契約：一律回傳純文字，永遠不帶 HTML 實體。呼叫端（TOC 標籤、
+    // slugifyHeading、startSection）三者都假設這一點。
     function flattenTokenText(tokens) {
       if (!Array.isArray(tokens)) {
         return '';
@@ -598,12 +739,12 @@ ${itemsHtml}
             return flattenTokenText(item.tokens);
           }
           if (item.type === 'codespan') {
-            return item.text || '';
+            return unescapeHtml(item.text || '');
           }
           if (item.tokens) {
             return flattenTokenText(item.tokens);
           }
-          return item.text || '';
+          return unescapeHtml(item.text || '');
         })
         .join('');
     }
@@ -667,8 +808,21 @@ ${itemsHtml}
       return classes;
     }
 
+    // Real HTML tags always have a letter (optionally after a `/`) immediately
+    // after `<` — `<x>`, `</div>`, `<br/>`. This deliberately does NOT match
+    // `<[^>]*>` generically: once flattenTokenText() started handing back
+    // unescaped plain text (v3.4.0 §1), literal author text like "C < D > E"
+    // would otherwise look like a tag and get silently eaten here.
+    //
+    // HTML comments (`<!-- ... -->`) don't start with a letter either, so they
+    // need their own alternative — without it a heading like
+    // "## Section <!-- note --> Title" leaks "note" into the slug
+    // (v3.4.0 Task 1 fix round 1). Known gap, deliberately left open: this
+    // does NOT special-case `<!DOCTYPE ...>` or `<? ... ?>` (processing
+    // instructions) — same non-letter-after-`<` shape, but neither has shown
+    // up in a real heading/prose fixture. Add an alternative here if one does.
     function stripHtmlTags(value) {
-      return String(value || '').replace(/<[^>]*>/g, '');
+      return String(value || '').replace(/<!--[\s\S]*?-->|<\/?[a-zA-Z][^<>]*>/g, '');
     }
 
     function slugifyHeading(value) {
@@ -694,6 +848,19 @@ ${itemsHtml}
         .replace(/'/g, '&#39;');
     }
 
+    // escapeHtml() 的精確逆函式。marked 的 inline lexer 會把 text / codespan
+    // token 的 `text` 欄位跳脫過再交出來，而 heading token 自己的 `text` 是
+    // 原始的 —— flattenTokenText() 用這一支把兩邊拉回同一個狀態。
+    // &amp; 必須最後解：先解它會讓 `&amp;lt;` 變成 `<` 而不是 `&lt;`。
+    function unescapeHtml(value) {
+      return String(value || '')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&');
+    }
+
     // 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
@@ -704,6 +871,13 @@ ${itemsHtml}
       const href  = isObj ? (token.href  || '') : (token || '');
       const title = isObj ? (token.title || '') : (arguments[1] || '');
       const text  = isObj ? (token.text  || '') : (arguments[2] || '');
+
+      // v3.4.0 §4: drawio 走 graphviz 那條路（建置時烤成內嵌 SVG），不走圖片
+      // 內嵌。判別看的是檔案的根元素而不是副檔名 —— ![](foo.xml) 只有在內容
+      // 真的是 mxfile / mxGraphModel 時才是圖，否則原樣落到下面既有的路徑。
+      const drawioOut = drawioPlaceholderFor(href, text);
+      if (drawioOut) return drawioOut;
+
       const uri = inlineImageSrc(href);
       if (!uri) return baseImage.apply(this, arguments);
       // A data: URI is base64 (or an already-encoded payload): no quote, no '<'.
@@ -774,7 +948,7 @@ ${itemsHtml}
         // 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`;
+        return '\n' + GRAPHVIZ_PLACEHOLDER.html([b64]) + '\n';
       }
       // Default: syntax-highlighted code block
       const escaped = code.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
@@ -932,6 +1106,20 @@ ${itemsHtml}
       // falls entirely inside one part, so this is byte-identical to baking the
       // joined string.
       parts = await Promise.all(parts.map(bakeGraphviz));
+      // v3.4.0 §4: 與 graphviz 同一個理由 —— 逐 part 烤，不是 join 之後才烤。
+      // patch 路徑會把 parts[i] 直接插進 DOM，而用戶端沒有 drawio 渲染器
+      // （__md2docInitDiagrams 只處理 mermaid 與 WaveDrom），沒烤的 part 會
+      // 變成一個空的 <div class="drawio">。與 bakeGraphviz 不同的是 drawio
+      // 需要一顆 headless Chromium，所以逐 part 依序（而非並行）烤，讓所有
+      // part 共用同一顆延遲啟動的 browser，一份文件最多開一次。
+      const drawioBrowser = makeLazyBrowserRef();
+      try {
+        for (let i = 0; i < parts.length; i++) {
+          parts[i] = await bakeDrawio(parts[i], drawioBrowser);
+        }
+      } finally {
+        await drawioBrowser.closeIfOpen();
+      }
       bodyHtml = parts.join('\n');
     } else {
       bodyHtml = marked.parse(mdPre);
@@ -1428,7 +1616,164 @@ ${itemsHtml}
      it against the textarea's own line numbers instead is a separate
      feasibility question, not answered here. */
   body[data-ed-mode="source"] .toc,
-  body[data-ed-mode="source"] .search-results { display: none !important; }`;
+  body[data-ed-mode="source"] .search-results { display: none !important; }
+
+  /* ── v3.4.0 batch3 Task 6: the wavedrom editing surface ───────────────
+     Both of these are mounted on document.body by lib/editor/client.js, and
+     that is not a styling choice: .content's children are what the client
+     reads back as its own render and what the WYSIWYG path serialises into
+     the user's markdown, so a panel or a button parked in there ends up in
+     their file. Everything below is therefore positioned against the
+     viewport rather than against .content.
+
+     z-index 998 sits UNDER .ed-conflict (999) on purpose — a save conflict
+     has to stay reachable even while the wave editor is open — and over the
+     toolbar's own band, because the editor is modal over the document. */
+  .ed-wave-edit-btn {
+    position: fixed; z-index: 12; padding: 3px 10px; font-size: 12px;
+    border: 1px solid #bbb; border-radius: 4px; background: #ffffffee;
+    color: #222; cursor: pointer; box-shadow: 0 1px 3px rgba(0,0,0,.2);
+  }
+  .ed-wave-edit-btn:hover { background: #fff; border-color: #888; }
+  .ed-wave-overlay {
+    position: fixed; inset: 0; z-index: 998; background: rgba(0,0,0,.45);
+    display: flex; align-items: center; justify-content: center;
+  }
+  .ed-wave-panel {
+    background: #fff; border-radius: 6px; width: min(1200px, 94vw);
+    height: min(760px, 90vh); display: flex; flex-direction: column;
+    box-shadow: 0 6px 28px rgba(0,0,0,.35); overflow: hidden;
+  }
+  .ed-wave-head {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 8px 12px; border-bottom: 1px solid #e2e2e2; font-weight: bold;
+  }
+  .ed-wave-close {
+    border: 1px solid #bbb; border-radius: 4px; background: #f6f6f6;
+    padding: 3px 12px; cursor: pointer;
+  }
+  /* Which way out keeps the work and which throws it away. Escape is a modal's
+     universal close key and here it discards a whole session, so the header
+     says so next to the button that does not. Normal weight against the bar's
+     bold heading: it is a caption, not a warning the user has to clear. */
+  .ed-wave-escape-hint {
+    margin-left: auto; margin-right: 12px; font-weight: normal;
+    font-size: 11px; color: #7a4b00;
+  }
+  .ed-wave-toolbar {
+    display: flex; flex-wrap: wrap; gap: 12px; align-items: center;
+    padding: 8px 12px; border-bottom: 1px solid #e2e2e2; background: #fafafa;
+  }
+  .ed-wave-brushes, .ed-wave-cycleops, .ed-wave-meta {
+    display: flex; flex-wrap: wrap; gap: 4px; align-items: center;
+  }
+  .ed-wave-brush {
+    width: 28px; height: 28px; border: 1px solid #c4c4c4; border-radius: 4px;
+    background: #fff; font-family: monospace; font-size: 14px; cursor: pointer;
+  }
+  .ed-wave-brush.is-on { background: #1a73e8; color: #fff; border-color: #1a73e8; }
+  .ed-wave-cycleops button, .ed-wave-toolbar button {
+    border: 1px solid #c4c4c4; border-radius: 4px; background: #fff;
+    padding: 3px 8px; font-size: 12px; cursor: pointer;
+  }
+  .ed-wave-toolbar button:disabled { opacity: .45; cursor: default; }
+  .ed-wave-metafield { display: flex; align-items: center; gap: 4px; font-size: 12px; }
+  .ed-wave-metafield input { width: 110px; font-size: 12px; padding: 2px 4px; }
+  /* The "this drawing is not showing you everything" notice. period / phase /
+     config.hscale all change what the ENGINE paints and none of them is
+     modelled by the hand drawing, so a document carrying one says so instead
+     of drawing a confident wrong picture. Full row, so it cannot be mistaken
+     for another toolbar control. */
+  .ed-wave-unmodelled {
+    flex: 1 1 100%; font-size: 12px; color: #7a4b00; background: #fff6e0;
+    border: 1px solid #e8c987; border-radius: 4px; padding: 4px 8px;
+  }
+  /* The stronger of the two notices: not "this drawing is incomplete" but
+     "this block has nothing this editor can edit" (a reg: / assign: block).
+     Same shape as its neighbour so the two read as one family, one step
+     louder because the information gap is bigger. */
+  .ed-wave-nolanes { color: #7a1f00; background: #ffe9e0; border-color: #e8a987; }
+  .ed-wave-body { display: flex; flex: 1 1 auto; min-height: 0; }
+  /* Widths chosen so the DRAWING still gets room at the narrowest viewport this
+     repo's browser tests use (800x600 -> panel 752): 752 - 200 - 160 = 392px,
+     which is 8 cycles at .ed-wave-canvas's 48px pitch. The canvas is a scroll
+     container, so a wider diagram scrolls rather than pushing the preview off —
+     but a canvas column narrower than a couple of cycles would make the drag
+     gesture unusable, and that was the first thing measured to go wrong here
+     (a press landed on the preview column, 116px past the canvas's clip). */
+  .ed-wave-lanes {
+    flex: 0 0 200px; border-right: 1px solid #e2e2e2; overflow: auto;
+    padding: 8px 0 8px 0;
+  }
+  /* The rows are absolutely positioned at index * laneHeight so they line up
+     with the drawing beside them cell for cell. A group title is NOT a row —
+     measured against the pinned engine in Task 2 — so it is drawn as a label in
+     the rail spanning its lanes' rows instead, which is the shape the engine
+     itself gives it (horizontal space in the name column, no vertical space). */
+  .ed-wave-lane-rows { position: relative; }
+  .ed-wave-lane-row {
+    position: absolute; left: 0; right: 0; display: flex; align-items: center;
+    gap: 3px; padding-right: 6px; box-sizing: border-box;
+  }
+  .ed-wave-lane-row.is-selected { background: #eaf2fe; }
+  .ed-wave-lane-name { flex: 1 1 auto; min-width: 0; font-size: 12px; padding: 2px 4px; }
+  .ed-wave-lane-row button {
+    border: 1px solid #cfcfcf; border-radius: 3px; background: #fff;
+    font-size: 11px; line-height: 1; padding: 3px 4px; cursor: pointer;
+  }
+  .ed-wave-lane-row button:disabled { opacity: .4; cursor: default; }
+  .ed-wave-lane-add-tail { position: absolute; left: 6px; }
+  .ed-wave-group, .ed-wave-group-input {
+    position: absolute; width: 14px; padding: 0; font-size: 11px;
+    writing-mode: vertical-rl; text-orientation: mixed; overflow: hidden;
+    border: 1px solid #d8d8d8; border-radius: 3px; background: #f2f2f2;
+    color: #555; cursor: pointer; box-sizing: border-box;
+  }
+  .ed-wave-group-input { width: 16px; height: 90px; cursor: text; }
+  .ed-wave-canvas-wrap { flex: 1 1 auto; overflow: auto; padding: 8px; }
+  .ed-wave-canvas { display: block; }
+  .ed-wave-grid { stroke: #ececec; stroke-width: 1; }
+  .ed-wave-line, .ed-wave-edge { stroke: #111; stroke-width: 2; fill: none; }
+  .ed-wave-weak { stroke-dasharray: 4 3; }
+  .ed-wave-x { fill: #d9d9d9; stroke: #111; stroke-width: 2; }
+  .ed-wave-bus { fill: #f5e9c8; stroke: #111; stroke-width: 2; }
+  .ed-wave-bus-3 { fill: #d8ead3; }
+  .ed-wave-bus-4 { fill: #d6e4f7; }
+  .ed-wave-bus-5 { fill: #f7d6e4; }
+  .ed-wave-buslabel { font-size: 11px; fill: #222; }
+  .ed-wave-selection { fill: rgba(26,115,232,.18); stroke: #1a73e8; stroke-width: 1; }
+  /* The KEYBOARD's own cell, and deliberately not the same mark as the
+     selection: the selection is the RANGE a cycle operation acts on, the
+     cursor is the ONE cell the next keystroke paints, and after Shift+left /
+     right both are on screen at once. pointer-events: none so the rect can
+     never swallow the press the drag underneath it is made of. */
+  .ed-wave-cursor {
+    fill: none; stroke: #d93025; stroke-width: 2; pointer-events: none;
+  }
+  /* The drawing is in the Tab cycle, so it has to SAY when it holds the
+     keyboard: a cell cursor alone leaves a user who just Tabbed onto it with
+     nothing that distinguishes "the drawing has the keyboard" from "the
+     drawing is where I left a cursor before I walked away". */
+  .ed-wave-canvas:focus { outline: 2px solid #1a73e8; outline-offset: 2px; }
+  /* The discontinuity marker. The engine draws one gap <use> per pipe
+     character; drawing none left the two pictures disagreeing on a lane whose
+     levels agreed exactly. */
+  .ed-wave-gap { stroke: #111; stroke-width: 2; fill: none; }
+  .ed-wave-preview {
+    flex: 0 1 340px; min-width: 160px; border-left: 1px solid #e2e2e2;
+    overflow: auto; padding: 8px;
+  }
+  .ed-wave-preview-label { font-size: 11px; color: #666; margin-bottom: 6px; }
+  .ed-wave-status {
+    border-top: 1px solid #e2e2e2; padding: 6px 12px; font-size: 12px;
+    color: #444; min-height: 18px;
+  }
+  .ed-wave-parse-error { padding: 16px; }
+  .ed-wave-parse-message { color: #b00020; font-weight: bold; }
+  .ed-wave-parse-excerpt {
+    background: #f6f6f6; border: 1px solid #e2e2e2; padding: 6px;
+    overflow-x: auto; font-family: monospace; font-size: 12px;
+  }`;
 
   const html = `<!DOCTYPE html>
 <html lang="en">
@@ -1576,6 +1921,24 @@ ${itemsHtml}
     z-index: 98;
   }
   body[data-sidebar-open] .sidebar-scrim { display: block; }
+  /* The scroll LOCK for this same attribute lives inside the
+     '@media (max-width: 1080px)' block below, next to
+     'body[data-sidebar-open] .reader-sidebar { transform: translateX(0); }'
+     — deliberately NOT here at base scope, unlike the rule immediately
+     above. Reason (Ruling I1, review round 2): the mobile-drawer meaning of
+     data-sidebar-open, including .sidebar-scrim's own display:block rule
+     just above, already leaks past its breakpoint by design (see the
+     ⚠ comment above '@media (min-width: 1081px) { body[data-ed-outline-hidden]
+     … }' for why the desktop 大綱 toggle needed its OWN attribute instead of
+     reusing this one — reusing it once already painted the whole desktop
+     viewport grey and click-dead). Nothing here clears data-sidebar-open on
+     resize (grep this file's two resize listeners — scroll anchor and
+     lightbox fit — neither touches it), so a lock at base scope would ALSO
+     survive: open the drawer narrow, widen the window, and the desktop page
+     would go unscrollable on top of the pre-existing grey scrim. The grey
+     scrim is that already-accepted gap; an unscrollable desktop page is not
+     — it is new, and scoping the lock to the same breakpoint the drawer
+     itself is scoped to is what keeps it from outliving the drawer. */
   .reader-tools,
   .search-results,
   .toc {
@@ -1997,7 +2360,29 @@ ${itemsHtml}
   hr { border: none; border-top: 1px solid #e1e4e8; margin: 24px 0; }
   .mermaid { text-align: center; margin: 20px 0; }
   .graphviz { text-align: center; margin: 20px 0; }
-  .content img {
+${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pay for this —
+     conditional injection, same pattern as usesWaveDrom / usesMath below.
+     .drawio needs position: relative because the (conditionally injected,
+     see below) sheet bar is its absolute child — same relationship as
+     .lightbox-stage / .lightbox-canvas, see CLAUDE.md. */
+  .drawio { text-align: center; margin: 20px 0; position: relative; }
+  .drawio svg { max-width: 100%; height: auto; }
+  .drawio-page[hidden] { display: none !important; }
+  .drawio-failed { color: #b91c1c; }
+` : ''}${usesDrawioMultiPage ? `  /* Sheet bar: only when a document actually has a multi-page drawio
+     diagram — a single-page file must not pay for it either. */
+  .drawio-sheetbar {
+    position: absolute; left: 50%; transform: translateX(-50%); bottom: 4px;
+    display: none; gap: 4px; padding: 4px 6px; border-radius: 6px;
+    background: rgba(255,255,255,.92); box-shadow: 0 1px 4px rgba(0,0,0,.18);
+  }
+  .drawio:hover .drawio-sheetbar { display: flex; }
+  .drawio-sheetbar button {
+    border: 0; background: transparent; cursor: pointer;
+    font: inherit; padding: 2px 8px; border-radius: 4px;
+  }
+  .drawio-sheetbar button[aria-pressed="true"] { background: #dbeafe; }
+` : ''}  .content img {
     max-width: 100%;
     height: auto;
   }
@@ -2014,6 +2399,7 @@ ${itemsHtml}
   .content img,
   .content .mermaid,
   .content .graphviz,
+  .content .drawio,
   .content [id^="WaveDrom_Display_"],
   .content .wavedrom-diagram { cursor: zoom-in; }
   .content a img { cursor: pointer; }
@@ -2179,6 +2565,21 @@ ${itemsHtml}
       flex: initial;
     }
     body[data-sidebar-open] .reader-sidebar { transform: translateX(0); }
+    /* Scroll lock for the drawer, same two-rule shape the lightbox uses a
+       few lines above (body[data-lightbox-open] / html[data-lightbox-open])
+       and for the identical reason: 'html, body { overflow-x: clip }' keeps
+       documentElement's own overflow-y at the visible default, so it stays
+       the scrolling element regardless of what 'body' says — a body-only
+       rule leaves the page scrollable behind the scrim. Was missing
+       entirely before this task (a missing lock, not a defeated one). Scoped
+       to THIS breakpoint on purpose — see the comment above
+       '.sidebar-scrim { display: none; … }' near the top of this stylesheet
+       for why base scope would leak an unscrollable desktop page past a
+       resize, since nothing clears data-sidebar-open on one. JS mirrors
+       data-sidebar-open onto documentElement in setSidebarOpen(), matching
+       openLightbox/closeLightbox. */
+    body[data-sidebar-open] { overflow: hidden; }
+    html[data-sidebar-open] { overflow: hidden; }
     .sidebar-splitter { display: none; }
     .heading-anchor { opacity: 1; }
   }
@@ -2639,7 +3040,31 @@ ${itemsHtml}
     box-sizing: border-box; height: var(--ed-toolbar-h);
     display: flex; align-items: center; justify-content: flex-start;
     flex-wrap: nowrap; overflow-x: auto; overflow-y: hidden;
-    gap: 6px; padding: 8px 12px;
+    /* v3.4.0 §3: gap was 6px until the save button (id 'save', file group)
+       landed at the FRONT of the row. Ruling T11-2 (below) requires the
+       outline (☰) button's own centre point to hit-test successfully at
+       800/1080px WITHOUT any scrolling — it is the only way to open the
+       sidebar drawer in edit mode, and that test deliberately does not
+       scroll first. A leading addition shifts every button after it right
+       by its own width; MEASURED at 800px wide before this change: 22
+       buttons put outline's centre at x=795 (row content 975px, overflow
+       175px) — already only a 5px margin inside the 800px viewport. Adding
+       save (23 buttons, row content 1026px, overflow 226px) pushed it to
+       x=846, entirely off screen (elementFromPoint at that point returns
+       null — off-screen, not occluded by another element; contrast the
+       .ed-toolbar-status overlap a few lines down, which returns the
+       covered BUTTON because that slot has pointer-events: none, an
+       entirely different failure shape). This gap value was chosen
+       empirically (a one-off puppeteer script, not a formula — flex gap
+       plus intrinsic button/separator widths do not sum cleanly by hand):
+       re-measured at 800px, outline's centre lands at x=765, a 35px margin
+       — comfortably more headroom than the original 5px, not just barely
+       restored. Also re-verified against the F12 "narrow viewport,
+       scrolling allowed" sweep just below (420/640/820px): every button,
+       save included, still reaches an empty unreachable list and an empty
+       neverClear list at all three — this change does not trade the T11-2
+       no-scroll guarantee for the F12 with-scroll one. */
+    gap: 3px; padding: 8px 12px;
     /* F12, both halves measured on this build at 900px viewport height.
        justify-content was center. Centering an overflowing flex row splits
        the overflow across BOTH ends, and the leading end of a scroll
@@ -2805,6 +3230,18 @@ ${itemsHtml}
     font: inherit; font-size: 13px; line-height: 1.4; cursor: pointer;
   }
   .ed-toolbar-menu-btn:hover { background: rgba(255, 255, 255, 0.18); }
+  /* backlog #7 (Task 9 review, M1): the panel's OWN keyboard cursor
+     (lib/editor/client.js's toolbarMenuIndex / data-ed-tb-menu-cursor) had
+     no matching rule at all — the fix made the six items operable by
+     keyboard but left the cursor invisible, the exact backlog #10 class of
+     defect ("can act, but cannot see where"). Same outline idiom as
+     .ed-toolbar-btn[data-ed-tb-cursor] above, for the same reason (legible
+     over :hover's own background, and over nothing at all when neither
+     applies). */
+  .ed-toolbar-menu-btn[data-ed-tb-menu-cursor] {
+    outline: 2px solid #6ea8fe; outline-offset: -2px;
+    background: rgba(255, 255, 255, 0.18);
+  }
   /* 追加 4: the whole-document source escape hatch. Replaces the rendered
      content column for the duration of source mode; the document's own
      lines[] is untouched until the mode is left (see docsource.js). */
@@ -2828,8 +3265,45 @@ ${itemsHtml}
   }
   .ed-commit { color: #0a7a0a; }
   .ed-cancel { color: #b00020; }
+  /* backlog #8: 'top: 0' used to put this banner directly OVER .ed-toolbar
+     (same top-of-viewport band, and z-index 999 against the bar's 101 wins
+     the paint) — MEASURED (task-10-toolbar-probe.js): all 23 toolbar
+     buttons' own centre points hit-tested to the banner, not the button,
+     for every .ed-conflict banner showBanner() raises (conflict /
+     render-failed / save-failed / dropped-gesture / structural-refusal /
+     swallow all share this one class — there is exactly one producer, see
+     showBanner() in lib/editor/client.js). Floors at the SAME
+     --ed-toolbar-h token placeTeMenuAboveCell()'s .ed-te-menu already
+     clamps to (if top < topInset, top = r.bottom + …, both in
+     lib/editor/client.js) — rather than inventing a new offset.
+     Final-review I1 correction: an earlier draft of this comment also named
+     positionSelToolbar()'s .ed-seltb here, as if it clamped to this same
+     token. Retracted — MEASURED: positionSelToolbar() reads --ed-toolbar-h
+     only to decide whether a selection scrolled fully out of view should
+     hide the bar entirely (rect.bottom <= topInset); the vertical floor it
+     actually clamps 'top' to is a bare margin = 4 local, independent
+     of the toolbar's height. Swept 66 scroll positions: at 17 of them
+     .ed-seltb's own top measures as low as 14.75px — inside this banner's
+     band — with no --ed-toolbar-h involved (task10-seltb-check-probe.js).
+     Not reproduced with a LIVE banner open at the same time (two attempts:
+     a burst's bold toggle never hits /api/render, and Ctrl+S's
+     switchAwayFrom() tears the bar down before a banner could show) — left
+     as a geometry note in CHANGELOG.md's Known issues rather than a
+     behaviour change.
+     Deliberately NOT a z-index change: the toolbar comment above
+     ("z-index sits ... below .ed-conflict (999): a save conflict must
+     always be reachable") still holds — the banner stays the topmost
+     thing, it just no longer shares the toolbar's own band to be on top
+     OF. showBanner() additionally closes .ed-te-grip / .ed-tb-insert /
+     .ed-te-menu / .ed-toolbar-menu — four dynamic fixed overlays that can
+     each land in that band, though (per the correction above) only
+     .ed-te-menu's own code floors there via --ed-toolbar-h; the others
+     land nearby as a side effect of their own trigger's position, not a
+     shared clamp — see showBanner()'s parallel comment in
+     lib/editor/client.js. Closed regardless, so a banner can never land on
+     top of one of those instead. */
   .ed-conflict {
-    position: fixed; top: 0; left: 0; right: 0; padding: 10px;
+    position: fixed; top: var(--ed-toolbar-h); 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;
   }
@@ -3423,8 +3897,10 @@ ${mermaidInitTag}`)
   function setSidebarOpen(open) {
     if (open) {
       document.body.setAttribute('data-sidebar-open', '');
+      document.documentElement.setAttribute('data-sidebar-open', '');
     } else {
       document.body.removeAttribute('data-sidebar-open');
+      document.documentElement.removeAttribute('data-sidebar-open');
     }
     if (sidebarToggle) sidebarToggle.setAttribute('aria-expanded', open ? 'true' : 'false');
   }
@@ -3591,11 +4067,62 @@ ${mermaidInitTag}`)
 
   captureScrollAnchor();
 
+  // ── drawio sheet bar ─────────────────────────────────────────────────────
+  // v3.4.0 §4: switching pages is a pure hidden-attribute toggle. Every page was
+  // rendered to inert SVG at build time (lib/drawio.js's bake pass), so there
+  // is no engine, no diagrams.net script, and no network request here — this
+  // works exactly the same with the network unplugged. Only injected when
+  // usesDrawioMultiPage: a single-page .drawio file must not pay for this UI
+  // at all (matching CSS gate is in the <style> block above).
+${usesDrawioMultiPage ? `  // v3.4.0 batch2 Task 6: wired through a NAMED, reusable hook instead of a
+  // bare one-shot forEach, so the edit-mode client runtime can re-invoke it
+  // — scoped to just one freshly swapped-in block — after a background
+  // refresh re-bakes a \`.drawio\`/\`.xml\` source that changed on disk (see
+  // lib/editor/client.js's stale-drawio handler). Still gated on
+  // usesDrawioMultiPage exactly as before: a single-page document must never
+  // pay for (or even mention) this UI at all — a guard test asserts the
+  // whole feature's class name is absent byte-for-byte from that output, so
+  // nothing below this line may ever run, or exist as source text, outside
+  // this branch.
+  window.__md2docInitDrawioSheetBar = function (rootEl) {
+    var scope = rootEl || document;
+    scope.querySelectorAll('.drawio[data-drawio-pages]').forEach(function (box) {
+      if (box.querySelector('.drawio-sheetbar')) return;   // already wired
+      var names;
+      try { names = JSON.parse(atob(box.getAttribute('data-drawio-pages') || '')); }
+      catch (e) { return; }
+      if (!Array.isArray(names)) return;
+      if (names.length < 2) return;
+      var pages = box.querySelectorAll('.drawio-page');
+      var bar = document.createElement('div');
+      bar.className = 'drawio-sheetbar';
+      names.forEach(function (name, i) {
+        var b = document.createElement('button');
+        b.type = 'button';
+        b.textContent = name || String(i + 1);
+        b.setAttribute('aria-pressed', pages[i] && !pages[i].hidden ? 'true' : 'false');
+        b.addEventListener('click', function (event) {
+          // The bar lives inside .drawio, which is also a lightbox click
+          // target below (LIGHTBOX_TARGETS) — without stopPropagation a page
+          // switch would also bubble up and pop the lightbox open.
+          event.stopPropagation();
+          for (var j = 0; j < pages.length; j++) pages[j].hidden = j !== i;
+          bar.querySelectorAll('button').forEach(function (x, j) {
+            x.setAttribute('aria-pressed', j === i ? 'true' : 'false');
+          });
+        });
+        bar.appendChild(b);
+      });
+      box.appendChild(bar);
+    });
+  };
+  window.__md2docInitDrawioSheetBar(document);
+` : ''}
   // ── Diagram / image lightbox ──────────────────────────────────────────────
   // 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_"], .wavedrom-diagram';
+  var LIGHTBOX_TARGETS = 'img, .mermaid, .graphviz, .drawio, [id^="WaveDrom_Display_"], .wavedrom-diagram';
   var LIGHTBOX_MIN_ZOOM = 0.05;
   var LIGHTBOX_MAX_ZOOM = 8;
   var LIGHTBOX_STEP = 1.25;
@@ -4333,6 +4860,15 @@ ${mermaidInitTag}`)
 
   function lightboxSourceOf(node) {
     if (node.tagName === 'IMG') return node;
+    // A multi-page .drawio bakes every page's <svg> into the DOM (hidden
+    // ones included, so page switching needs no engine) — a plain
+    // querySelector('svg') returns the FIRST one in document order, which is
+    // wrong whenever page 1 isn't the one currently shown. Pick the visible
+    // page's svg instead.
+    if (node.classList && node.classList.contains('drawio')) {
+      var visiblePage = node.querySelector('.drawio-page:not([hidden])');
+      if (visiblePage) return visiblePage.querySelector('svg') || node;
+    }
     return node.querySelector('svg') || node;
   }
 
@@ -4468,12 +5004,34 @@ ${mermaidInitTag}`)
 </body>
 </html>`;
 
-  const bakedHtml = await bakeGraphviz(html);
+  const gvHtml = await bakeGraphviz(html);
   // editMode's bodyHtml is already baked per-part above; re-baking here is a
   // short-circuit no-op (bakeGraphviz bails out when there's no
   // data-graphviz-src left). Non-editMode bodyHtml is baked here as before.
-  const bakedBody = await bakeGraphviz(bodyHtml);
-  return { html: bakedHtml, bodyHtml: bakedBody, parts, blocks };
+  const gvBody = await bakeGraphviz(bodyHtml);
+  // v3.4.0 §4: same short-circuit story for drawio. editMode already baked
+  // every part above, so both calls below are no-ops there (no browser is
+  // opened) — this is only load-bearing for the non-editMode
+  // `bodyHtml = marked.parse(mdPre)` path, which never went through the
+  // per-part loop. `html` and `bodyHtml` share the same placeholders (html
+  // embeds bodyHtml), so both bakes share one lazily-opened browser instead
+  // of paying for two.
+  const drawioBrowser = makeLazyBrowserRef();
+  let bakedHtml, bakedBody;
+  try {
+    bakedHtml = await bakeDrawio(gvHtml, drawioBrowser);
+    bakedBody = await bakeDrawio(gvBody, drawioBrowser);
+  } finally {
+    await drawioBrowser.closeIfOpen();
+  }
+  return {
+    html: bakedHtml, bodyHtml: bakedBody, parts, blocks,
+    // v3.4.0 batch2 Task 6: an added field, not a shape change to the four
+    // existing ones — every call site destructures the specific keys it
+    // wants (checked across lib/editor/server.js and test/*.js), none reads
+    // the object as a whole, so an addition here is backward compatible.
+    drawioRefs: Array.from(drawioRefs, ([p, stamp]) => ({ path: p, stamp })),
+  };
 }
 module.exports = { renderMarkdown };
 
@@ -4481,7 +5039,7 @@ module.exports = { renderMarkdown };
 // in-process WASM engine. Loads the WASM module only when at least one dot
 // block exists, so text-only docs pay nothing.
 async function bakeGraphviz(htmlStr) {
-  if (!/data-graphviz-src=/.test(htmlStr)) return htmlStr;
+  if (!GRAPHVIZ_PLACEHOLDER.probe.test(htmlStr)) return htmlStr;
   let Graphviz;
   try {
     ({ Graphviz } = require('@hpcc-js/wasm-graphviz'));
@@ -4490,7 +5048,7 @@ async function bakeGraphviz(htmlStr) {
     return htmlStr;
   }
   const gv = await Graphviz.load();
-  return htmlStr.replace(/<div class="graphviz" data-graphviz-src="([^"]*)"><\/div>/g, (m, b64) => {
+  return htmlStr.replace(GRAPHVIZ_PLACEHOLDER.re, (m, b64) => {
     const dotSrc = Buffer.from(b64, 'base64').toString('utf8');
     try {
       const svg = gv.dot(dotSrc)
@@ -4515,6 +5073,111 @@ function launchBrowser(puppeteer) {
   });
 }
 
+// v3.4.0 §4. A document with no drawio reference must not pay for opening
+// Chromium. `get()` launches on its first call only (and every later caller
+// awaits the same promise, so a document with several drawio placeholders
+// still opens exactly one browser); `closeIfOpen()` closes it only if `get()`
+// was ever actually called.
+function makeLazyBrowserRef() {
+  let browserPromise = null;
+  return {
+    get() {
+      if (!browserPromise) {
+        const puppeteer = require('puppeteer');
+        browserPromise = launchBrowser(puppeteer);
+      }
+      return browserPromise;
+    },
+    async closeIfOpen() {
+      if (!browserPromise) return;
+      const browser = await browserPromise;
+      await browser.close();
+    },
+  };
+}
+
+// Render every deferred drawio placeholder to inline SVG using a headless
+// Chromium running the vendored drawio viewer (lib/drawio.js). Every page is
+// baked, not just the one selected by the markdown fragment (`#PageName`),
+// so switching pages client-side is a pure `hidden`-attribute toggle with no
+// engine involved — see lib/drawio.js's own comment on why a Node-side XML
+// parser can't substitute for the real layout engine.
+async function bakeDrawio(htmlStr, browserRef) {
+  if (!DRAWIO_PLACEHOLDER.probe.test(htmlStr)) return htmlStr;
+
+  // replace()'s callback can't be async, so collect the jobs first and apply
+  // them (each with its own possible browser-page await) afterwards.
+  const jobs = [];
+  htmlStr.replace(DRAWIO_PLACEHOLDER.re, (m, b64, pageIdx, altB64) => {
+    jobs.push({
+      m,
+      b64,
+      pageIdx: Number(pageIdx),
+      alt: Buffer.from(altB64, 'base64').toString('utf8'),
+    });
+    return m;
+  });
+
+  for (const job of jobs) {
+    const xml = Buffer.from(job.b64, 'base64').toString('utf8');
+    const names = drawio.pageNamesOf(xml);
+    let svgs;
+    try {
+      // One document shares one browser: browserRef.get() only really opens
+      // Chromium on its first call.
+      svgs = await drawio.bakeDrawioSvg(xml, { browser: await browserRef.get() });
+    } catch (e) {
+      // page.evaluate() can reject with a plain string rather than an Error
+      // (observed: puppeteer surfacing a serialization failure as "buffer
+      // error") — e.message would silently read as "undefined" then.
+      const reason = (e && e.message) ? e.message : String(e);
+      console.error('[WARN] drawio render failed:', reason);
+      // A silent blank is the most expensive failure this project has learned
+      // from (v3.3.0) — leave a visible placeholder naming the error instead.
+      const msg = ('drawio 圖無法渲染：' + reason)
+        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+      // The callback form, NOT a replacement string: `msg` is generated
+      // content (a renderer error message), and String.replace() interprets
+      // $$ / $& / $` / $' inside a replacement STRING even when the pattern
+      // is a plain string. A callback's return value is never re-scanned.
+      // See the same note on the success path below.
+      htmlStr = htmlStr.replace(job.m,
+        () => `<div class="drawio drawio-failed"><p>${msg}</p></div>`);
+      continue;
+    }
+    const inner = svgs.map((svg, i) =>
+      `<div class="drawio-page"${i === job.pageIdx ? '' : ' hidden'}>${svg}</div>`).join('');
+    // Page names may contain any character (commas and quotes included), so
+    // they travel as base64-encoded JSON rather than a delimited string — a
+    // delimiter breaks on both "two names glued together" and "a name that
+    // happens to contain the delimiter", and a literal control character
+    // living in the document is invisible to boot.
+    const attr = Buffer.from(JSON.stringify(names), 'utf8').toString('base64');
+    // v3.4.0 batch2 final review R5 — the author already wrote a name in
+    // `![Architecture overview](arch.drawio)`; give the baked box that name.
+    // The role differs by page count on purpose: a multi-page box has the
+    // sheet bar's <button>s appended INSIDE it at runtime, and role="img"
+    // would take them off the accessibility tree entirely, so those boxes get
+    // role="group" — also nameable, children still exposed. No alt text means
+    // no attributes at all: an empty accessible name is worse than none.
+    const named = job.alt
+      ? ` role="${names.length >= 2 ? 'group' : 'img'}" aria-label="${job.alt}"`
+      : '';
+    // v3.4.0 batch2 final review B2 — the callback form is load-bearing.
+    // `inner` is the baked SVG, i.e. arbitrary diagram text, and a
+    // replacement STRING has $$ / $& / $` / $' interpreted in it even when
+    // the pattern is a plain string: a `$$` label silently collapsed to a
+    // single `$`, and a `$&` label (the byte sequence any label with `$`
+    // before `&` produces once the SVG escapes the `&`) spliced this very
+    // placeholder — the whole .drawio file's base64 — into the middle of a
+    // <text> element. bakeGraphviz() above was always a callback; this is the
+    // same rule. Keep it a callback.
+    htmlStr = htmlStr.replace(job.m,
+      () => `<div class="drawio" data-drawio-pages="${attr}"${named}>${inner}</div>`);
+  }
+  return htmlStr;
+}
+
 // 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, dstPath) {