@helping-ai-workflow/md2doc 3.2.1 → 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);
@@ -1349,7 +1537,19 @@ ${itemsHtml}
      it. Fixed chrome takes no layout space, so the page has to make its
      own: this is the only place that offset is written. The mobile rule at
      max-width:1080px above already reserves 60px for .sidebar-toggle; the
-     bar sits above it, so the two offsets ADD there.
+     bar sits above it. That 60px is NOT re-reserved here: T11-2 hides
+     .sidebar-toggle in edit mode (the rule further down this stylesheet), so
+     in edit mode there is no button under the bar to clear, and adding the
+     two offsets left a band of empty page nothing was ever painted into.
+     Measured on the build that did add them, at 1080/1000/800 wide:
+     .page-layout's computed padding-top was 104px against a 44px toolbar —
+     60px of dead space, and a 105px gap between the toolbar's bottom edge
+     and the first block against 45px at 1200 wide, where the desktop rule
+     applies. The @media block below therefore still has to carry an explicit
+     value, identical to the desktop one: the READER stylesheet's own
+     'max-width: 1080px' rule sets padding-top: 60px for the drawer toggle it
+     still shows, and deleting this override would hand the edit page that
+     60px straight back.
      .reader-sidebar is sticky at top: 24px in the base stylesheet — pushed
      down by the same amount here so the outline does not slide under the
      bar, with its height reduced to match so it still ends at the viewport
@@ -1360,7 +1560,7 @@ ${itemsHtml}
     height: calc(100vh - 48px - var(--ed-toolbar-h));
   }
   @media (max-width: 1080px) {
-    .page-layout { padding-top: calc(60px + var(--ed-toolbar-h)); }
+    .page-layout { padding-top: var(--ed-toolbar-h); }
     .reader-sidebar { top: 0; height: 100vh; padding-top: calc(16px + var(--ed-toolbar-h)); }
   }
   /* The 大綱 button's DESKTOP half, on an attribute of its OWN.
@@ -1382,6 +1582,197 @@ ${itemsHtml}
   @media (min-width: 1081px) {
     body[data-ed-outline-hidden] .reader-sidebar,
     body[data-ed-outline-hidden] .sidebar-splitter { display: none; }
+  }
+  /* T11-2 step 3: this button sits at z-index 100 (base stylesheet, above)
+     directly under .ed-toolbar's z-index 101. Measured at 1080x900 and
+     800x900: document.elementFromPoint() at the button's own rect centre
+     returns the toolbar, not the button, at both widths — a real pointer
+     click never lands on it there, only a synthetic .click() does. The
+     toolbar's own left/right are both 0, spanning the full viewport width,
+     so nothing about that occlusion is a function of width; the two
+     measured points are a sample of a band the toolbar covers edge to
+     edge, not two lucky ones. It is safe to remove in edit mode because
+     lib/editor/client.js's toolbar carries its own outline button
+     (runToolbarAction()'s 'outline' case, which calls toggleOutlineSidebar(),
+     the same function this button calls) which opens the identical drawer,
+     and Task 8 gave that toolbar a keyboard cursor (Alt+F10) — the outline
+     button is not among the ids Task 8 measured as stranding the caret on
+     BODY after activation. This rule is edit-mode-only (editModeLayoutCss);
+     reader-mode output never includes it, so the mobile drawer toggle there
+     is unaffected. */
+  .sidebar-toggle { display: none; }
+  /* T11-2 step 5: enterSourceMode() (lib/editor/client.js) sets
+     contentEl.hidden = true and mounts a plain textarea in its place, and
+     setDocMode() writes docMode onto body as data-ed-mode. Measured on that
+     build: with ten TOC links listed, clicking the last one moved neither
+     the (hidden) reading position nor the textarea's own scrollTop
+     (3924 before and after) — the click target was a normal anchor jump /
+     scrollIntoView() reaching into a subtree rooted at .content, and
+     .content's own display:none is what absorbed it; the same subtree
+     relationship holds for a search result's jump target. Hiding the TOC
+     nav and the search-results panel while data-ed-mode="source" removes
+     the two controls whose only reachable target sits in that hidden
+     subtree; the search input row (.reader-tools) is left as-is — driving
+     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; }
+
+  /* ── 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>
@@ -1530,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 {
@@ -1951,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;
   }
@@ -1968,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; }
@@ -2092,6 +2524,17 @@ ${itemsHtml}
     background: #ffffff;
   }
   body[data-lightbox-open] { overflow: hidden; }
+  /* The 'html, body { overflow-x: clip }' rule above keeps documentElement's
+     own overflow-x at clip, not visible, so overflow does not propagate from
+     body to the viewport per the CSS spec's root-propagation rule; the
+     scrolling element stays documentElement, and its overflow-y sits at the
+     visible default. That is the gap the body rule above does not close --
+     measured in test/lightbox.test.js and test/editor-journey.test.js: a
+     wheel over .lightbox-bar, PageDown and End all reach documentElement
+     while it is open. Locking documentElement's own overflow here closes
+     it; JS mirrors the data-lightbox-open attribute onto the html element
+     in openLightbox/closeLightbox below. */
+  html[data-lightbox-open] { overflow: hidden; }
   @media print { .lightbox { display: none !important; } }
   @media (max-width: 1080px) {
     .sidebar-toggle { display: inline-flex; align-items: center; }
@@ -2122,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; }
   }
@@ -2318,7 +2776,21 @@ ${itemsHtml}
      this element's containing block and left:100% lands it flush against
      the menu's right edge. Source order matters: equal specificity with
      .ed-handle-menu's own left:-4px, so this rule must stay AFTER it. */
-  .ed-handle-submenu { left: 100%; margin-left: 4px; }
+  /* Viewport-clamp backstop: openConvertSubmenu() (lib/editor/client.js)
+     shifts the panel's top up so its bottom clears the viewport when there
+     is room to do so — that shift is the clamp. This rule covers what the
+     shift cannot: a viewport shorter than the panel, where the viewport's
+     own top edge still leaves the panel's bottom edge off-screen. What
+     happens under max-height, in the order it happens: CONVERT_TARGETS's
+     buttons (lib/editor/convert-md.js), each carrying .ed-handle-menu-btn's
+     own height (26px), first shrink via flex as the cap tightens (measured
+     on this branch: 26px at a cap around 342px, stepping down to 18px
+     around a 250px cap) — no scrolling yet, the list still fits end to
+     end, just shorter per row. overflow-y: auto only starts moving content
+     once the rows have already reached that floor and the cap is still
+     tighter than the list at 18px per row. (No backticks in this comment:
+     it lives inside a JS template literal.) */
+  .ed-handle-submenu { left: 100%; margin-left: 4px; max-height: calc(100vh - 8px); overflow-y: auto; }
   .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 ⠿
@@ -2529,7 +3001,23 @@ ${itemsHtml}
     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-btn:hover:not([aria-disabled="true"]) { background: rgba(255, 255, 255, 0.18); }
+  /* v3.3.0 (F2): the four states these buttons report about the selection.
+     'true' (the selection is entirely inside a mark of this type) is the
+     filled treatment the fixed toolbar already uses. 'mixed' (the selection
+     overlaps marks of this type without lying inside one) is deliberately NOT
+     the filled one — pressing it removes marks rather than adding any — so it
+     gets a dashed edge and a half-strength ground instead. 'false' keeps the
+     rule above. INERT is aria-disabled, never the disabled DOM property; see
+     paintSelToolbarMarks() in lib/editor/client.js for why. */
+  .ed-seltb-btn[aria-pressed="true"] {
+    background: #e6edf3; color: #101215; border-color: #e6edf3;
+  }
+  .ed-seltb-btn[aria-pressed="mixed"] {
+    background: rgba(230, 237, 243, 0.3);
+    border-style: dashed; border-color: rgba(230, 237, 243, 0.8);
+  }
+  .ed-seltb-btn[aria-disabled="true"] { opacity: 0.38; cursor: default; }
   .ed-seltb-b { font-weight: bold; }
   .ed-seltb-i { font-style: italic; }
   .ed-seltb-s { text-decoration: line-through; }
@@ -2550,13 +3038,91 @@ ${itemsHtml}
   .ed-toolbar {
     position: fixed; top: 0; left: 0; right: 0; z-index: 101;
     box-sizing: border-box; height: var(--ed-toolbar-h);
-    display: flex; align-items: center; justify-content: center;
+    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
+       container's content is not reachable by scrolling: driven at 820 /
+       640 / 420 px wide, sweeping scrollLeft from 0 to its maximum in 8px
+       steps and reading every button's rect, the buttons that never once sat
+       inside the viewport were [undo] / [undo, redo, headings] /
+       [undo, redo, headings, quote, code, list]. On this build — leading-edge
+       layout plus the padding-right below, driven together, not one at a time
+       — the same sweep leaves that set empty at all three widths.
+
+       padding-right buys the buttons room to clear .ed-toolbar-status, whose
+       fixed box occupies the viewport's right 124px (right: 12px plus
+       min-width: 7rem at this font size). The claim it supports is narrow:
+       SOME scroll position exists at which a given button is clear of the
+       slot. It is NOT "a button can never sit under the slot" — driven at
+       scrollLeft 0 after this change, [outline, preview] still overlap the
+       slot at a 900px viewport and [check, bold, italic, strike] do at 420px.
+       What makes that harmless is the slot's own pointer-events: none, in
+       the rule further down — the load-bearing line, not this one. */
+    padding-right: 124px;
     background: rgba(16, 18, 21, 0.92); color: #e6edf3;
+    /* F12, second half: before this the bar scrolled but nothing on screen
+       said so, so a button parked outside the viewport looked absent rather
+       than off to one side. Two edge gradients, painted only on the side
+       that still has content hidden behind it; the client runtime writes
+       data-ed-tb-overflow from scrollLeft against the scroll maximum.
+
+       Deliberately a background layer on the bar itself rather than a new
+       overlay node. An overlay would have to be taken out of flow to avoid
+       becoming a flex item in this row, and an out-of-flow child of this bar
+       anchors to the scrolled content box and drifts with it (the
+       .ed-toolbar-status note below records that measurement) — while
+       anchoring it to the viewport instead would add a floating layer to the
+       set test/editor-journey.test.js enumerates and demands a scroll answer
+       for. A background layer needs neither: background-attachment defaults
+       to scroll, which pins the gradient to this element's padding box while
+       its contents move underneath.
+
+       These gradients sit behind the buttons, because that is where the
+       painting order puts a background layer: above the background colour,
+       below the element's content. That is the reason they are dark rather
+       than light — darkening the ground a translucent button sits on is what
+       reads as content passing under an edge, where a light wash behind the
+       same button would not. */
+    --ed-tb-edge-l: rgba(0, 0, 0, 0);
+    --ed-tb-edge-r: rgba(0, 0, 0, 0);
+    background-image:
+      linear-gradient(to right, var(--ed-tb-edge-l), rgba(0, 0, 0, 0)),
+      linear-gradient(to left, var(--ed-tb-edge-r), rgba(0, 0, 0, 0));
+    background-repeat: no-repeat;
+    background-position: left center, right center;
+    background-size: 26px 100%, 26px 100%;
     font-size: 13px;
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
   }
+  .ed-toolbar[data-ed-tb-overflow~="left"] { --ed-tb-edge-l: rgba(0, 0, 0, 0.55); }
+  .ed-toolbar[data-ed-tb-overflow~="right"] { --ed-tb-edge-r: rgba(0, 0, 0, 0.55); }
   .ed-toolbar-sep {
     flex: 0 0 auto; width: 1px; height: 18px; margin: 0 2px;
     background: rgba(255, 255, 255, 0.25);
@@ -2570,18 +3136,45 @@ ${itemsHtml}
     white-space: nowrap; cursor: pointer;
   }
   .ed-toolbar-btn:hover:not(:disabled) { background: rgba(255, 255, 255, 0.18); }
+  /* F12: where the toolbar's keyboard cursor is. An outline rather than a
+     background so it stays legible on a button that is already pressed-in
+     (aria-pressed paints that one nearly white). Claim no more for it than a
+     keyboard route: the buttons keep their tabindex="-1" and the caret stays
+     in the document, so no focus move happens for assistive technology to
+     follow, and what this cue does for a screen reader has not been measured
+     here. What it does do is let the row be walked without a mouse. */
+  .ed-toolbar-btn[data-ed-tb-cursor] {
+    outline: 2px solid #6ea8fe; outline-offset: 1px;
+  }
   .ed-toolbar-btn:disabled { opacity: 0.38; cursor: default; }
   .ed-toolbar-btn[aria-pressed="true"] {
     background: #e6edf3; color: #101215; border-color: #e6edf3;
   }
+  /* v3.3.0 (F2): the middle state, matching .ed-seltb-btn[aria-pressed="mixed"]
+     above so the two bars answer the same question the same way. */
+  .ed-toolbar-btn[aria-pressed="mixed"] {
+    background: rgba(230, 237, 243, 0.3);
+    border-style: dashed; border-color: rgba(230, 237, 243, 0.8);
+  }
   .ed-toolbar-b { font-weight: bold; }
   .ed-toolbar-i { font-style: italic; }
   .ed-toolbar-s { text-decoration: line-through; }
-  /* H1 fix: the brief's literal margin-left: auto (a flex-flow item) was
-     measured to break .ed-toolbar's justify-content: center — an auto
-     margin on any flex item absorbs ALL positive free space before
-     justify-content sees any, so the ~22-button group snapped flush left on
-     every viewport wide enough not to overflow. position: fixed removes
+  /* H1 fix — and its reason has since moved, so both readings are kept here
+     rather than one silently standing in for the other. The brief's literal
+     margin-left: auto (a flex-flow item) was measured on v3.2.0 to break
+     .ed-toolbar's justify-content: center — an auto margin on any flex item
+     absorbs ALL positive free space before justify-content sees any, so the
+     ~22-button group snapped flush left on every viewport wide enough not to
+     overflow. F12 replaced that declaration with justify-content: flex-start
+     (the .ed-toolbar rule above), so flush left IS the shipped layout now and
+     that particular failure mode no longer exists. What the rule guards today
+     is the slot's out-of-flow-ness, and the assertion beside it in
+     test/editmode-render.test.js carries the re-driven numbers: against the
+     slot as it ships the margin changes nothing at all, while putting the slot
+     back in flow with it turns the slot into a scrolling flex item
+     (scrollWidth 975 -> 1093 at 420px) and moves its rect off the strip
+     .ed-toolbar's padding-right reserves for it ([1276, 1388] -> [1164, 1276]
+     at 1400px). position: fixed removes
      the slot from the flex layout entirely (buttons measured byte-identical
      to a build with the slot absent, at both a 1400px and a 420px viewport),
      and — unlike position: absolute against .ed-toolbar's own
@@ -2593,14 +3186,17 @@ ${itemsHtml}
      H2 fix: pointer-events: none below is LOAD-BEARING, not decorative.
      v3.2.1 filled this slot with the current mode's name ('編輯' / '原始碼'),
      so it no longer ships empty — but that content is inert TEXT, never a
-     control, which is exactly what keeps the rule below sufficient. At narrow viewports .ed-toolbar's own
-     overflow-x: auto lets the button row scroll to a rest position where
-     this fixed 7rem box's footprint physically covers three real buttons
-     (image / outline / preview, measured at 420px width, scrollLeft at its
-     max 221) — document.elementFromPoint() over any of them resolves to
-     this span, not the button underneath, and a real click on it never
-     reaches the button's listener. Harmless today only because the span
-     carries nothing to interact with. WHOEVER PUTS A CONTROL HERE (or
+     control, which is exactly what keeps the rule below sufficient. The
+     overlap it keeps harmless is real and still present after F12 moved this
+     bar's scroll geometry: at scrollLeft 0, this box's footprint covers
+     outline and preview at a 900px-wide viewport, and check / bold / italic /
+     strike at 420px. Re-driven on this build, hit-testing the middle of each
+     of those overlaps: with the rule as it ships,
+     document.elementFromPoint() answers the BUTTON at every one of them; flip
+     this span's pointer-events to auto and leave everything else alone, and
+     every one of them answers this span instead. That reading is the same hit
+     test a press resolves through, and the rule below is what stands between
+     the two readings — not the span's emptiness. WHOEVER PUTS A CONTROL HERE (or
      wires up two-way sync, §3) MUST remove or scope this
      rule AND independently solve the overlap (e.g. reflow the slot in-flow
      at narrow widths, or shrink/hide it below some width) — simply
@@ -2613,13 +3209,19 @@ ${itemsHtml}
     pointer-events: none; }
   /* The H▾ dropdown: same singleton-panel idiom as .ed-insert-menu, but
      anchored to a fixed bar rather than moved into a block, so it is
-     positioned in viewport coordinates by the client runtime. */
+     positioned in viewport coordinates by the client runtime.
+     max-height/overflow-y: same backstop role as .ed-handle-submenu above
+     (Task 9 fix round 1, Ruling T9-5) — toggleToolbarHeadingMenu()
+     (lib/editor/client.js) does the shift-to-fit; this covers a viewport
+     shorter than the panel, where the shift alone cannot bring the whole
+     list on-screen. */
   .ed-toolbar-menu {
     position: fixed; z-index: 102;
     display: flex; flex-direction: column; gap: 2px;
     padding: 4px; border-radius: 8px;
     background: rgba(16, 18, 21, 0.96); color: #e6edf3;
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.35);
+    max-height: calc(100vh - 8px); overflow-y: auto;
   }
   .ed-toolbar-menu[hidden] { display: none; }
   .ed-toolbar-menu-btn {
@@ -2628,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). */
@@ -2651,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;
   }
@@ -3246,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');
   }
@@ -3414,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;
@@ -4156,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;
   }
 
@@ -4206,6 +4919,7 @@ ${mermaidInitTag}`)
     lightboxReturnScroll = window.scrollY;
     suppressAnchorCapture = true;
     document.body.setAttribute('data-lightbox-open', '');
+    document.documentElement.setAttribute('data-lightbox-open', '');
     lightboxEl.hidden = false;
     lightboxStage.scrollTop = 0;
     lightboxStage.scrollLeft = 0;
@@ -4218,6 +4932,7 @@ ${mermaidInitTag}`)
     if (!lightboxIsOpen()) return;
     lightboxEl.hidden = true;
     document.body.removeAttribute('data-lightbox-open');
+    document.documentElement.removeAttribute('data-lightbox-open');
     annoCancelDraft();
     annoSyncInline();
     annoSourceNode = null;
@@ -4289,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 };
 
@@ -4302,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'));
@@ -4311,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)
@@ -4336,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) {