@helping-ai-workflow/md2doc 3.7.0 → 3.9.0

package/lib/md2doc.js

@@ -21,6 +21,7 @@
 const fs            = require('fs');
 const path          = require('path');
 const drawio        = require('./drawio.js');
+const { applyReaderTheme } = require('./theme/tokens');
 
 // How long to let client-side WaveDrom / Mermaid scripts render before we
 // snapshot the DOM (PDF print, or --bake-svg inert-SVG bake).
@@ -140,9 +141,14 @@ const waveDromSkinTag = inlineScriptTag(localWaveDromSkin, 'wavedrom');
 const waveDromTag     = inlineScriptTag(localWaveDromJs, 'wavedrom');
 const mermaidScriptTag = inlineScriptTag(localMermaidJs, 'mermaid');
 
+// v3.8.0 (design review item 5): mermaid in md2doc's link blue on a light
+// tint, the body font, white edge labels. Shared by the reader init below and
+// the edit-mode init hook so both modes draw the same diagram.
+const MERMAID_CONFIG_JS = "theme: 'base', themeVariables: { fontFamily: '-apple-system, BlinkMacSystemFont, \"Segoe UI\", Arial, \"Microsoft JhengHei\", sans-serif', primaryColor: '#eaf2fd', primaryBorderColor: '#0969da', primaryTextColor: '#1f2328', lineColor: '#57606a', secondaryColor: '#f6f8fa', tertiaryColor: '#ffffff', edgeLabelBackground: '#ffffff' }";
+
 const mermaidInitTag = `<script type="text/javascript" data-md2doc-diagram-engine="mermaid">
   if (typeof mermaid !== 'undefined') {
-    mermaid.initialize({ startOnLoad: true, theme: 'default' });
+    mermaid.initialize({ startOnLoad: true, ${MERMAID_CONFIG_JS} });
   }
 </script>`;
 
@@ -370,9 +376,76 @@ function renderEditModeList(listToken, blocks, biRef, out) {
   return parts;
 }
 
+// <html lang> for a rendered document (v3.8.0, design review item 2).
+// Tagged zh-Hant when Han characters are at least 10% of (CJK characters +
+// Latin words), counted outside code; when kana is at least 20% of
+// (Han + kana) it is ja, and when Hangul is at least 20% of (Han + Hangul)
+// it is ko (both still need CJK to be 10% of the prose). Measured 2026-10-01: English docs
+// (README, CLAUDE.md) <= 0.013, mixed zh/en specs in mac_top/docs >= 0.237,
+// so 0.10 leaves a wide margin on both sides. Traditional vs Simplified is
+// not detected: every Chinese document this tool renders today is zh-Hant.
+const LANG_TAG_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+function detectDocLang(mdText) {
+  const prose = String(mdText)
+    // Fences are anchored to line starts (up to 3 spaces of indent) and the
+    // closing fence must be at least as long as the opening one, so an inline
+    // mention of the marker, or a shorter marker line inside a longer fence,
+    // cannot swallow the prose around it. Backticks are written as x60 escapes.
+    .replace(/^ {0,3}(\x60{3,})[^\n\x60]*\n[\s\S]*?^ {0,3}\1\x60*[ \t\r]*$/gm, '')
+    .replace(/^ {0,3}(~{3,})[^\n]*\n[\s\S]*?^ {0,3}\1~*[ \t\r]*$/gm, '')
+    .replace(/\x60[^\x60\n]*\x60/g, '');
+  const han = (prose.match(/[\u3400-\u9fff]/g) || []).length;
+  const kana = (prose.match(/[\u3040-\u30ff]/g) || []).length;
+  const hangul = (prose.match(/[\uac00-\ud7af\u1100-\u11ff\u3130-\u318f]/g) || []).length;
+  const words = (prose.match(/[A-Za-z]+/g) || []).length;
+  // Kana or Hangul only count as Japanese or Korean when CJK text is the bulk
+  // of the document at all (same 10% floor as zh-Hant); one stray の in an
+  // English or Chinese document must not flip its language.
+  const cjk = han + kana + hangul;
+  if (cjk + words === 0) return 'en';
+  if (cjk / (cjk + words) >= 0.10) {
+    if (kana / (han + kana) >= 0.2) return 'ja';
+    if (hangul / (han + hangul) >= 0.2) return 'ko';
+  }
+  return (han + kana) / (han + kana + words) >= 0.10 ? 'zh-Hant' : 'en';
+}
+
+// v3.8.0 (design review item 12): the paragraph immediately after the
+// document's FIRST </h1>, when EVERY line of it is "<strong>Key:</strong>
+// value", is the spec's metadata block — rendered as a two-column <dl>.
+// Allow-list rule: one non-matching line and the paragraph is left alone.
+function renderDocMetaBlock(bodyHtml) {
+  const at = bodyHtml.indexOf('</h1>');
+  if (at < 0) return bodyHtml;
+  const head = bodyHtml.slice(0, at + 5);
+  const tail = bodyHtml.slice(at + 5);
+  const m = tail.match(/^(\s*)<p>([\s\S]*?)<\/p>/);
+  if (!m) return bodyHtml;
+  const lines = m[2].split('\n').filter((l) => l.trim());
+  const rows = lines.map((l) => l.match(/^\s*<strong>([^<]+):<\/strong>\s*([\s\S]*)$/));
+  if (rows.length < 2 || rows.some((r) => !r)) return bodyHtml;
+  const items = rows.map((r) => '<dt>' + r[1] + '</dt><dd>' + r[2] + '</dd>').join('');
+  return head + m[1] + '<dl class="doc-meta">' + items + '</dl>' + tail.slice(m[0].length);
+}
+
+// v3.8.0 sidebar icons. Path data from Lucide (ISC licence, see
+// THIRD-PARTY-NOTICES.md), inlined so the single-file output works offline.
+const ICON_SVG_OPEN = '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">';
+const READER_ICONS = {
+  unfold: ICON_SVG_OPEN + '<path d="M12 22v-6"/><path d="M12 8V2"/><path d="M4 12H2"/><path d="M10 12H8"/><path d="M16 12h-2"/><path d="M22 12h-2"/><path d="m15 19-3 3-3-3"/><path d="m15 5-3-3-3 3"/></svg>',
+  fold: ICON_SVG_OPEN + '<path d="M12 22v-6"/><path d="M12 8V2"/><path d="M4 12H2"/><path d="M10 12H8"/><path d="M16 12h-2"/><path d="M22 12h-2"/><path d="m15 19-3-3-3 3"/><path d="m15 5-3 3-3-3"/></svg>',
+  panel: ICON_SVG_OPEN + '<rect x="3" y="3" width="18" height="18" rx="2"/><path d="M9 3v18"/><path d="m16 15-3-3 3-3"/></svg>',
+  up: ICON_SVG_OPEN + '<path d="m18 15-6-6-6 6"/></svg>',
+  down: ICON_SVG_OPEN + '<path d="m6 9 6 6 6-6"/></svg>',
+  x: ICON_SVG_OPEN + '<path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>',
+};
+
 async function renderMarkdown(mdText, srcPath, opts = {}) {
   const md = mdText;
   const src = srcPath;
+  const docLang = (typeof opts.lang === 'string' && LANG_TAG_RE.test(opts.lang))
+    ? opts.lang
+    : detectDocLang(md);
   let usesMermaid = false;
   let usesWaveDrom = false;
   let usesDrawio = false;
@@ -699,6 +772,16 @@ async function renderMarkdown(mdText, srcPath, opts = {}) {
       return root;
     }
 
+    // v3.8.0 (design review item 7+8): when the document's only H1 is its
+    // title and it has sections, list those sections at the TOC's top level —
+    // the title row indented every entry one level and carried no information.
+    // Several H1s are chapters and are kept as they are.
+    function flattenSingleRoot(tree) {
+      return tree.length === 1 && tree[0].depth === 1 && tree[0].children.length
+        ? tree[0].children
+        : tree;
+    }
+
     function renderTocNodes(nodes, level = 1) {
       if (!nodes.length) {
         return '';
@@ -959,7 +1042,14 @@ ${itemsHtml}
       const depth = Number(token.depth || 1);
       const headingText = stripHtmlTags(flattenTokenText(token.tokens) || token.text || '');
       const headingId = slugifyHeading(headingText);
-      const headingHtml = this.parser.parseInline(token.tokens);
+      const inlineHtml = this.parser.parseInline(token.tokens);
+      // v3.8.0 (design review item 4): a leading section number ("4.1 ",
+      // "12. ") gets its own span so CSS can widen the gap after it. The
+      // space stays in the markup, so textContent is unchanged. Read mode
+      // only — the editor turns heading DOM back into Markdown.
+      const headingHtml = opts.editMode
+        ? inlineHtml
+        : inlineHtml.replace(/^(\d+(?:\.\d+)*\.?)(\s)/, '<span class="sec">$1</span>$2');
 
       tocItems.push({
         depth,
@@ -1126,6 +1216,7 @@ ${itemsHtml}
     }
     // Both the ```math fence and the $/$$ extension emit class="katex" — a single
     // post-parse scan is the source of truth for conditional CSS injection.
+    if (!opts.editMode) bodyHtml = renderDocMetaBlock(bodyHtml);
     usesMath = /class="katex/.test(bodyHtml);
     serializedSections = JSON.stringify(
       sections.map((section) => ({
@@ -1141,30 +1232,31 @@ ${itemsHtml}
   <section class="reader-tools">
     <label class="reader-search-label" for="doc-search-input">Search</label>
     <div class="reader-search-row">
-      <input type="search" id="doc-search-input" placeholder="Enter keyword and press Enter">
-      <button id="doc-search-submit" type="button">Search</button>
-      <button id="doc-search-clear" type="button">Clear</button>
+      <input type="search" id="doc-search-input" placeholder="Search this document">
+      <button id="doc-search-submit" type="button" tabindex="-1">Search</button>
+      <button id="doc-search-clear" type="button" aria-label="Clear search" title="Clear search">${READER_ICONS.x}</button>
     </div>
   </section>
   <section class="search-results" id="search-results" hidden>
     <div class="search-results-header">
       <span class="search-results-title">Results</span>
       <span id="search-result-count" class="reader-status">0</span>
-      <button id="search-prev" type="button" disabled aria-label="Previous match">◀</button>
-      <button id="search-next" type="button" disabled aria-label="Next match">▶</button>
+      <button id="search-prev" type="button" disabled aria-label="Previous match" title="Previous match">${READER_ICONS.up}</button>
+      <button id="search-next" type="button" disabled aria-label="Next match" title="Next match">${READER_ICONS.down}</button>
     </div>
     <div id="search-results-list"></div>
   </section>
   <nav class="toc" aria-label="Table of contents" data-reader-toc>
     <div class="toc-header">
+      <span class="toc-title">Contents</span>
       <div class="toc-header-actions">
-        <button id="toc-expand-all" type="button" aria-label="Expand all">⊞</button>
-        <button id="toc-collapse-all" type="button" aria-label="Collapse all">⊟</button>
-        <button id="toc-collapse-toggle" type="button" aria-label="Collapse table of contents" title="Collapse / expand sidebar">◀</button>
+        <button id="toc-expand-all" type="button" aria-label="Expand all" title="Expand all">${READER_ICONS.unfold}</button>
+        <button id="toc-collapse-all" type="button" aria-label="Collapse all" title="Collapse all">${READER_ICONS.fold}</button>
+        <button id="toc-collapse-toggle" type="button" aria-label="Collapse table of contents" title="Collapse / expand sidebar">${READER_ICONS.panel}</button>
       </div>
       <div class="toc-breadcrumb" data-toc-breadcrumb aria-label="Current location"></div>
     </div>
-    ${renderTocNodes(tocTree)}
+    ${renderTocNodes(flattenSingleRoot(tocTree))}
   </nav>
 </aside>
 <div class="sidebar-splitter" id="sidebar-splitter" role="separator" aria-orientation="vertical" aria-label="Resize sidebar"></div>`;
@@ -1214,7 +1306,7 @@ ${itemsHtml}
   window.__md2docInitDiagrams = function (rootEl) {
     rootEl = rootEl || document;
     if (typeof mermaid !== 'undefined') {
-      mermaid.initialize({ startOnLoad: false, theme: 'default' });
+      mermaid.initialize({ startOnLoad: false, ${MERMAID_CONFIG_JS} });
       var mermaidNodes = rootEl.querySelectorAll ? rootEl.querySelectorAll('.mermaid') : [];
       var pending = [];
       for (var i = 0; i < mermaidNodes.length; i++) {
@@ -1255,7 +1347,7 @@ ${itemsHtml}
           // (on a later call) — the CSS cursor rule and the lightbox click
           // target selector both key off this class (in addition to the
           // WaveDrom_Display_ id prefix, which non-edit pages rely on and
-          // never rename), so a diagram stays clickable and zoom-in-affordant
+          // never rename), so a diagram stays clickable and shows its click cursor
           // for its whole lifetime, independent of id reclaiming.
           var displayDiv = wavePending[j].previousElementSibling;
           if (displayDiv) {
@@ -1609,6 +1701,10 @@ ${itemsHtml}
      reader-mode output never includes it, so the mobile drawer toggle there
      is unaffected. */
   .sidebar-toggle { display: none; }
+  .mobile-bar { display: none; }
+  /* The reader bar is gone in edit mode, so its 52px anchor offset goes too
+     (it moved scrollIntoView landings under the edit toolbar). */
+  .content [id] { scroll-margin-top: 0; }
   /* 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
@@ -1813,9 +1909,9 @@ ${itemsHtml}
   }
   .ed-wave-lane-row.is-selected { background: #eaf2fe; }
   .ed-wave-lane-handle {
-    flex: 0 0 auto; cursor: grab; color: #aaa; user-select: none; font-size: 13px;
+    flex: 0 0 auto; cursor: move; color: #aaa; user-select: none; font-size: 13px;
   }
-  .ed-wave-lane-handle:active { cursor: grabbing; }
+  .ed-wave-lane-handle:active { cursor: move; }
   /* min-width, not just flex-grow: min-width is what a flex item will not
      shrink past, and shrinking past it is the vertical-text failure above.
      MEASURED after this change (real page, 800x600, the journey suite's own
@@ -2137,15 +2233,24 @@ ${itemsHtml}
     overflow-x: auto; font-family: monospace; font-size: 12px;
   }`;
 
-  const html = `<!DOCTYPE html>
-<html lang="en">
+  // The phone bar only exists when there is a TOC for its button to open: a
+// document with no headings has no sidebar, and an empty bar would carry a
+// button that opens an empty drawer.
+const mobileBarHtml = tocHtml
+  ? '<header class="mobile-bar" id="mobile-bar">\n' +
+    '<button class="sidebar-toggle" id="sidebar-toggle" type="button" aria-label="Toggle sidebar" aria-expanded="false">☰</button>\n' +
+    '<span class="mobile-bar-title" id="mobile-bar-title"></span>\n' +
+    '</header>\n'
+  : '';
+const html = `<!DOCTYPE html>
+<html lang="${docLang}">
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${title}</title>
 <style>
   body {
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, "PingFang TC", "Microsoft JhengHei", "Noto Sans CJK TC", "Noto Sans TC", sans-serif;
     margin: 0;
     padding: 0;
     line-height: 1.65;
@@ -2174,7 +2279,9 @@ ${itemsHtml}
     min-width: 0;
     height: calc(100vh - 48px);
     overflow: hidden;
-    padding-right: 8px;
+    padding: 12px 8px 12px 12px;
+    background: #f3f5f7;
+    border-radius: 10px;
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
@@ -2184,7 +2291,7 @@ ${itemsHtml}
     flex-basis: 36px;
     width: 36px;
     min-width: 36px;
-    padding-right: 0;
+    padding: 12px 4px;
   }
   body[data-toc-collapsed] .reader-tools,
   body[data-toc-collapsed] .search-results,
@@ -2215,7 +2322,7 @@ ${itemsHtml}
   .sidebar-splitter {
     flex: 0 0 32px;
     align-self: stretch;
-    cursor: col-resize;
+    cursor: ew-resize;
     display: flex;
     justify-content: flex-start;
     touch-action: none;
@@ -2240,26 +2347,13 @@ ${itemsHtml}
     display: none;
   }
   #toc-collapse-toggle {
-    margin-left: 0;
-    padding: 2px 8px;
-    font: inherit;
-    font-size: 0.9em;
-    line-height: 1;
-    border: 1px solid #d0d7de;
-    border-radius: 6px;
-    background: #ffffff;
-    color: #57606a;
-    cursor: pointer;
     transition: transform 0.15s ease;
   }
-  #toc-collapse-toggle:hover {
-    background: #eef2f6;
-    color: #24292e;
-  }
   @media (max-width: 1080px) {
     #toc-collapse-toggle { display: none; }
   }
   .reader-tools { flex: 0 0 auto; }
+  .mobile-bar { display: none; }
   .sidebar-toggle {
     display: none;
     position: fixed;
@@ -2304,65 +2398,91 @@ ${itemsHtml}
   .reader-tools,
   .search-results,
   .toc {
-    border: 1px solid #d0d7de;
-    border-radius: 10px;
-    background: #f8fafc;
-    padding: 12px 14px;
+    border: none;
+    background: transparent;
+    padding: 2px 0;
   }
-  .reader-search-label {
-    display: block;
-    font-size: 0.78rem;
-    font-weight: 700;
-    letter-spacing: 0.08em;
-    text-transform: uppercase;
-    color: #57606a;
-    margin-bottom: 6px;
+  .reader-search-label,
+  #doc-search-submit {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
   }
   .reader-search-row {
+    position: relative;
     display: flex;
-    gap: 6px;
-    margin-bottom: 8px;
+    margin-bottom: 4px;
   }
   .reader-search-row input[type="search"] {
     flex: 1 1 auto;
     min-width: 0;
-    padding: 6px 8px;
+    padding: 7px 30px 7px 10px;
     border: 1px solid #d0d7de;
     border-radius: 6px;
+    background: #ffffff;
     font: inherit;
   }
-  .reader-search-row button {
-    padding: 4px 10px;
-    font: inherit;
-    font-size: 0.85em;
-    border: 1px solid #d0d7de;
-    border-radius: 6px;
-    background: #ffffff;
+  .reader-search-row input[type="search"]::-webkit-search-cancel-button {
+    -webkit-appearance: none;
+    appearance: none;
+    display: none;
+  }
+  #doc-search-clear {
+    position: absolute;
+    right: 4px;
+    top: 50%;
+    transform: translateY(-50%);
+    display: inline-grid;
+    place-items: center;
+    padding: 4px;
+    line-height: 0;
+    border: none;
+    border-radius: 4px;
+    background: transparent;
+    color: #59636e;
     cursor: pointer;
   }
-  .reader-search-row button:hover {
-    background: #eef2f6;
+  #doc-search-clear:hover {
+    background: #e3e8ee;
+    color: #1f2328;
+  }
+  #doc-search-input:placeholder-shown ~ #doc-search-clear {
+    display: none;
   }
   .search-results-header,
   .toc-header {
     display: flex;
-    flex-direction: column;
-    align-items: stretch;
-    gap: 4px;
+    flex-direction: row;
+    align-items: center;
+    gap: 6px;
     margin-bottom: 8px;
   }
+  .toc-header {
+    justify-content: space-between;
+    border-bottom: 1px solid #d8dee4;
+    padding-bottom: 6px;
+  }
+  body[data-toc-collapsed] .toc-header {
+    border-bottom: none;
+  }
   .toc-header-actions {
     flex: 0 0 auto;
     display: flex;
-    gap: 6px;
+    gap: 2px;
     justify-content: flex-end;
   }
-  /* Sticky breadcrumb: stacked ancestor chain of the current scroll position.
-     Each row is single-line + ellipsis; full text on hover via title=. */
+  /* Breadcrumb: kept in the DOM (the runtime and editor-reader-rebind read it)
+     but hidden since v3.8.0 — the TOC highlights the whole active path instead. */
   .toc-breadcrumb {
     flex: 1 1 auto;
     min-width: 0;
-    display: flex;
+    display: none;
     flex-direction: column;
     gap: 1px;
   }
@@ -2387,13 +2507,14 @@ ${itemsHtml}
   }
   .search-results-title,
   .toc-title {
-    font-size: 0.78rem;
-    font-weight: 700;
-    letter-spacing: 0.08em;
-    text-transform: uppercase;
-    color: #57606a;
+    font-size: 0.86rem;
+    font-weight: 600;
+    color: #1f2328;
     flex: 0 0 auto;
   }
+  body[data-toc-collapsed] .toc-title {
+    display: none;
+  }
   .reader-status {
     flex: 1 1 auto;
     font-size: 0.82em;
@@ -2401,20 +2522,21 @@ ${itemsHtml}
   }
   .search-results-header button,
   .toc-header button {
-    padding: 2px 8px;
+    display: inline-grid;
+    place-items: center;
+    padding: 4px;
     font: inherit;
-    font-size: 0.9em;
-    line-height: 1;
-    border: 1px solid #d0d7de;
+    line-height: 0;
+    border: none;
     border-radius: 6px;
-    background: #ffffff;
-    color: #57606a;
+    background: transparent;
+    color: #59636e;
     cursor: pointer;
   }
   .search-results-header button:hover,
   .toc-header button:hover {
-    background: #eef2f6;
-    color: #24292e;
+    background: #e3e8ee;
+    color: #1f2328;
   }
   .search-results-header button:disabled {
     opacity: 0.45;
@@ -2460,8 +2582,8 @@ ${itemsHtml}
     background: #eef2f6;
   }
   .search-result-item.is-active {
-    background: #dbeafe;
-    box-shadow: inset 0 0 0 1px #93c5fd;
+    background: #dbe6f3;
+    box-shadow: none;
   }
   .search-result-title {
     font-weight: 600;
@@ -2510,6 +2632,8 @@ ${itemsHtml}
        the shift+wheel handler; appears only when a title actually overflows. */
     overflow-x: auto;
     scrollbar-width: thin;
+    -webkit-mask-image: linear-gradient(90deg, #000 calc(100% - 26px), transparent);
+    mask-image: linear-gradient(90deg, #000 calc(100% - 26px), transparent);
   }
   .toc ul {
     list-style: none;
@@ -2534,13 +2658,15 @@ ${itemsHtml}
     min-width: 100%;
     color: #57606a;
     text-decoration: none;
-    padding: 2px 0;
+    padding: 2px 8px;
     line-height: 1.4;
     white-space: nowrap;
     box-sizing: border-box;
+    border-radius: 4px;
   }
   .toc summary > a {
-    flex: 0 0 auto;
+    flex: 1 0 auto;
+    min-width: 0;
   }
   .toc summary {
     min-width: 0;
@@ -2550,17 +2676,41 @@ ${itemsHtml}
   }
   .toc a:hover {
     color: #0969da;
+    background: #e8edf2;
   }
   .toc a.is-active {
-    color: #0b57d0;
-    font-weight: 700;
+    color: #0550ae;
+    font-weight: 600;
+    background: #dbe6f3;
   }
   .toc a.is-match {
-    color: #355070;
-    background: #eaf2ff;
+    color: inherit;
+    background: #fff5c2;
+  }
+  .toc li:has(a.is-active) > details > summary > a:not(.is-active) {
+    color: #1f2328;
+    font-weight: 600;
+  }
+  .reader-sidebar :is(a, button, input, summary):focus-visible,
+  .mobile-bar button:focus-visible,
+  .content a:focus-visible {
+    outline: 2px solid #0969da;
+    outline-offset: 2px;
     border-radius: 4px;
-    padding-left: 4px;
-    padding-right: 4px;
+  }
+  .toc :is(a, summary):focus-visible {
+    outline-offset: -2px;
+  }
+  /* The list's right-edge fade is a mask, and a mask clips the ring of a
+     focused row along with the text. Lift it while a row holds focus. */
+  .toc > .toc-list:has(:focus-visible) {
+    -webkit-mask-image: none;
+    mask-image: none;
+  }
+  .toc-header button:focus-visible,
+  .search-results-header button:focus-visible,
+  .reader-sidebar .search-result-item:focus-visible {
+    outline-offset: -2px;
   }
   .toc details {
     margin: 0;
@@ -2582,6 +2732,8 @@ ${itemsHtml}
     font-size: 0.78em;
     line-height: 1.8;
     flex: 0 0 auto;
+    width: 12px;
+    text-align: center;
     transform: translateY(1px);
   }
   .toc details[open] > summary::before {
@@ -2593,15 +2745,15 @@ ${itemsHtml}
     border-left: 1px solid #d8dee4;
   }
   .toc-item:not(.toc-parent) > a {
-    padding-left: 18px;
+    padding-left: 26px;
   }
   .toc-list-level-1 > .toc-item > a,
   .toc-list-level-1 > .toc-item > details > summary > a {
-    font-weight: 600;
+    font-size: 0.95em;
   }
   .toc-list-level-2 > .toc-item > a,
   .toc-list-level-2 > .toc-item > details > summary > a {
-    font-size: 0.95em;
+    font-size: 0.9em;
   }
   .toc-list-level-3 > .toc-item > a,
   .toc-list-level-3 > .toc-item > details > summary > a,
@@ -2633,6 +2785,19 @@ ${itemsHtml}
   }
   .content > * { max-width: 100%; }
   .content iframe, .content video, .content canvas { max-width: 100%; height: auto; }
+  .doc-meta {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+    gap: 4px 20px;
+    background: #f6f8fa;
+    border-radius: 6px;
+    padding: 12px 16px;
+    margin: 16px 0 28px;
+    font-size: 0.92em;
+    line-height: 1.55;
+  }
+  .doc-meta dt { color: #57606a; }
+  .doc-meta dd { margin: 0; }
   .heading-with-anchor {
     position: relative;
   }
@@ -2653,14 +2818,15 @@ ${itemsHtml}
     color: #0969da;
   }
   h1 { font-size: 2em;   border-bottom: 2px solid #e1e4e8; padding-bottom: 10px; margin-top: 1.5em; }
-  h2 { font-size: 1.5em; border-bottom: 1px solid #e1e4e8; padding-bottom: 6px;  margin-top: 1.4em; }
-  h3 { font-size: 1.2em; margin-top: 1.3em; }
-  h4 { font-size: 1.05em; margin-top: 1.2em; }
+  h2 { font-size: 1.5em; border-bottom: 1px solid #e1e4e8; padding-bottom: 6px;  margin-top: 2.2em; margin-bottom: 0.7em; }
+  h3 { font-size: 1.3em; margin-top: 2em; margin-bottom: 0.5em; }
+  h4 { font-size: 1.1em; margin-top: 1.8em; margin-bottom: 0.4em; }
+  .sec { margin-right: 0.4em; font-variant-numeric: tabular-nums; }
   code {
     background: #f6f8fa;
     padding: 2px 5px;
     border-radius: 3px;
-    font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+    font-family: "Cascadia Mono", Consolas, "SFMono-Regular", "Liberation Mono", Menlo, "Microsoft JhengHei", monospace;
     font-size: 0.875em;
   }
   pre {
@@ -2671,6 +2837,13 @@ ${itemsHtml}
     line-height: 1.45;
   }
   pre code { background: none; padding: 0; font-size: 0.875em; }
+  .content :not(pre) > code {
+    background: none;
+    padding: 0;
+    border-radius: 0;
+    color: #b93a0c;
+    font-size: 0.92em;
+  }
   table {
     display: block;
     border-collapse: collapse;
@@ -2680,9 +2853,8 @@ ${itemsHtml}
     font-size: 0.9em;
     overflow-x: auto;
   }
-  th, td { border: 1px solid #dfe2e5; padding: 7px 14px; text-align: left; }
-  th { background: #f6f8fa; font-weight: 600; }
-  tr:nth-child(even) { background: #fafbfc; }
+  th, td { border: none; border-bottom: 1px solid #e1e4e8; padding: 7px 14px; text-align: left; vertical-align: top; }
+  th { font-weight: 600; border-bottom: 2px solid #c9ced4; }
   .content table th,
   .content table td {
     overflow-wrap: normal;
@@ -2695,7 +2867,7 @@ ${itemsHtml}
   .content table th code {
     white-space: nowrap;
   }
-  .content table { table-layout: auto; }
+  .content table { table-layout: auto; font-variant-numeric: tabular-nums; }
   .content table col.col-narrow { width: 1%; }
   .content table col.col-prose { width: auto; }
   .content table th.cell-narrow,
@@ -2708,10 +2880,7 @@ ${itemsHtml}
     background: #ffffff;
   }
   .content table thead th:first-child {
-    background: #f6f8fa;
-  }
-  .content table tbody tr:nth-child(even) td:first-child {
-    background: #fafbfc;
+    background: #ffffff;
   }
   blockquote {
     border-left: 4px solid #dfe2e5;
@@ -2789,7 +2958,7 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
   .content .graphviz,
   .content .drawio,
   .content [id^="WaveDrom_Display_"],
-  .content .wavedrom-diagram { cursor: zoom-in; }
+  .content .wavedrom-diagram { cursor: pointer; }
   .content a img { cursor: pointer; }
 
   .lightbox {
@@ -2894,10 +3063,10 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
     position: relative;
     flex: 1 1 auto;
     overflow: auto;
-    cursor: grab;
+    cursor: move;
     overscroll-behavior: contain;
   }
-  .lightbox-stage[data-panning] { cursor: grabbing; }
+  .lightbox-stage[data-panning] { cursor: move; }
   .lightbox-canvas { margin: 0 auto; position: relative; }
   /* Sized in px by the runtime; the child follows, so the scroll extent grows
      with the zoom. A CSS transform would scale the pixels and leave the scroll
@@ -2925,21 +3094,59 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
   html[data-lightbox-open] { overflow: hidden; }
   @media print { .lightbox { display: none !important; } }
   @media (max-width: 1080px) {
+    .content table td.cell-prose,
+    .content table th.cell-prose { min-width: 15em; }
     .sidebar-toggle { display: inline-flex; align-items: center; }
+    .mobile-bar {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      height: 44px;
+      padding: 0 12px;
+      box-sizing: border-box;
+      background: #ffffff;
+      border-bottom: 1px solid #d8dee4;
+      z-index: 100;
+    }
+    .mobile-bar .sidebar-toggle {
+      position: static;
+      box-shadow: none;
+    }
+    .mobile-bar-title {
+      min-width: 0;
+      flex: 1 1 auto;
+      font-size: 14px;
+      font-weight: 600;
+      color: #24292e;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    .content [id] { scroll-margin-top: 52px; }
+    /* The 60px clears the fixed bar, so it only applies when the bar exists
+       (a document with no headings has none). :where() keeps the selector at
+       the specificity of a bare class, so the edit-mode override still wins. */
+    .page-layout:where(.mobile-bar ~ *) {
+      padding-top: 60px;
+    }
     .page-layout {
       display: block;
       max-width: 100%;
-      padding-top: 60px;
     }
     .reader-sidebar {
       position: fixed;
-      top: 0;
+      top: 44px;
       left: 0;
       bottom: 0;
       width: 85%;
       max-width: 360px;
-      height: 100vh;
-      background: #ffffff;
+      height: calc(100vh - 44px);
+      background: #f3f5f7;
+      border-radius: 0;
       z-index: 99;
       transform: translateX(-100%);
       transition: transform 0.2s ease;
@@ -2949,10 +3156,9 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
       display: flex;
       flex-direction: column;
       gap: 12px;
-      box-shadow: 2px 0 12px rgba(0,0,0,0.15);
       flex: initial;
     }
-    body[data-sidebar-open] .reader-sidebar { transform: translateX(0); }
+    body[data-sidebar-open] .reader-sidebar { transform: translateX(0); box-shadow: 2px 0 12px rgba(0,0,0,0.15); }
     /* 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
@@ -2969,7 +3175,6 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
     body[data-sidebar-open] { overflow: hidden; }
     html[data-sidebar-open] { overflow: hidden; }
     .sidebar-splitter { display: none; }
-    .heading-anchor { opacity: 1; }
   }
   @media print {
     body { font-size: 11pt; }
@@ -2994,10 +3199,19 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
       padding: 0 10px;
     }
     .reader-sidebar,
+    .mobile-bar,
     .sidebar-toggle,
     .sidebar-splitter,
     .sidebar-scrim { display: none !important; }
     .content { max-width: 100%; }
+    /* A4 lays out at about 680px, inside the max-width: 1080px block above,
+       so its 15em prose floor applied to print; the table scrolls
+       horizontally on screen and a PDF clips what overflows. Drop the floor.
+       The sticky first column goes static so its bottom border prints. */
+    .content table td.cell-prose,
+    .content table th.cell-prose { min-width: 0; }
+    .content table tbody td:first-child,
+    .content table thead th:first-child { position: static; }
     .heading-anchor { display: none; }
     pre  { font-size: 9pt; }
     a[href]:after { content: none; }
@@ -3015,18 +3229,17 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
      .ed-te-hl).
 
      The descendant rules and their !important are not decoration, they are
-     the whole problem: <pre> (#f6f8fa), <th> (#f6f8fa), the zebra stripe
-     tr:nth-child(even) (#fafbfc) and the sticky first column (#ffffff) all
+     the whole problem: <pre> (#f6f8fa) and the sticky first column (#ffffff)
      carry OPAQUE backgrounds, and the sticky column additionally paints at
-     z-index: 1 over anything drawn beneath it. Two of those beat a plain
-     descendant selector on specificity alone — counted:
-     .content table tbody tr:nth-child(even) td:first-child is (0,3,4)
-     against this rule's (0,3,2), and .content table tbody td:first-child is
-     (0,2,3) against the same (0,3,2) — so without !important the tint is
-     invisible on exactly the blocks a user is most likely to select. .ed-te-hl
-     needed the identical treatment for the identical reason. This ADDS rules
-     rather than reordering the sticky/zebra/header set, which CLAUDE.md says
-     wins by source order and must not be moved.
+     z-index: 1 over anything drawn beneath it. Until v3.8.0 the grey <th>
+     (#f6f8fa) and the zebra stripe tr:nth-child(even) (#fafbfc, whose sticky
+     override .content table tbody tr:nth-child(even) td:first-child was
+     (0,3,4) against this rule's (0,3,2)) did too; v3.8.0 removed both, and
+     the th / tr:nth-child(even) selectors below stay so a later restyle
+     cannot quietly reopen the hole. Without !important the tint is invisible
+     on exactly the blocks a user is most likely to select. .ed-te-hl needed
+     the identical treatment for the identical reason. This ADDS rules rather
+     than reordering the sticky-column rules, which win by source order.
      (No backticks in this comment: it lives inside a JS template literal.)
 
      :focus outline is suppressed because the roving tabindex below focuses a
@@ -3328,7 +3541,7 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
      having: '.ed-handle' (the button the gesture starts on), '.ed-handle-menu-btn'
      and every table grip carry their own 'cursor: pointer', and a plain
      inherited cursor loses to all of them. */
-  html.ed-block-dragging, html.ed-block-dragging * { cursor: grabbing !important; }
+  html.ed-block-dragging, html.ed-block-dragging * { cursor: move !important; }
   /* Notion-style grip handles: replace the original invisible TE_EDGE_PX=8
      proximity zone (user-acceptance feedback: unusably small, no visible
      affordance) with two real, adequately-sized (>=18x24px) click/drag
@@ -3355,7 +3568,7 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
      place-content: center, so the dot cluster stays compact/centered
      regardless of the button's own (larger, hit-target-sized) box — no
      images, no background gradients. '.ed-te-grip-dragging' is EITHER
-     grip's own "active drag handle" visual (grabbing cursor) while a row OR
+     grip's own "active drag handle" visual (move cursor) while a row OR
      column drag is in flight (Task 8: columns became draggable too, same
      as rows) — see cancelTeDrag()/the pointermove listener in the client
      runtime. */
@@ -3377,17 +3590,17 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
      the position was a hard-coded literal 20. */
   :root { --ed-te-grip-row-w: 20px; }
   .ed-te-grip-row {
-    width: var(--ed-te-grip-row-w); height: 28px; cursor: grab; z-index: 7;
+    width: var(--ed-te-grip-row-w); height: 28px; cursor: move; z-index: 7;
     grid-template-columns: repeat(2, 3px); grid-template-rows: repeat(3, 3px);
     gap: 3px 4px;
   }
-  .ed-te-grip-row.ed-te-grip-dragging { cursor: grabbing; }
+  .ed-te-grip-row.ed-te-grip-dragging { cursor: move; }
   .ed-te-grip-col {
-    width: 28px; height: 24px; cursor: grab; z-index: 7;
+    width: 28px; height: 24px; cursor: move; z-index: 7;
     grid-template-columns: repeat(3, 3px); grid-template-rows: repeat(2, 3px);
     gap: 4px 3px;
   }
-  .ed-te-grip-col.ed-te-grip-dragging { cursor: grabbing; }
+  .ed-te-grip-col.ed-te-grip-dragging { cursor: move; }
   /* Task 4: floating selection toolbar (bold/italic/strikethrough/underline/
      code/link), shown over a
      non-collapsed selection inside an active WYSIWYG session. position:
@@ -3723,8 +3936,7 @@ ${opts.editMode ? editModeLayoutCss : ''}
 ${usesMath ? buildKatexStyleTag() : ''}
 </head>
 <body>
-<button class="sidebar-toggle" id="sidebar-toggle" type="button" aria-label="Toggle sidebar" aria-expanded="false">☰</button>
-<div class="sidebar-scrim" id="sidebar-scrim"></div>
+${mobileBarHtml}<div class="sidebar-scrim" id="sidebar-scrim"></div>
 <div class="page-layout">
 ${tocHtml}
 <main class="content">
@@ -3790,9 +4002,10 @@ ${mermaidInitTag}`)
   // wholesale after a commit (see lib/editor/client.js), which detaches every
   // node this was captured from. window.__md2docRebindReader() below
   // re-queries and reassigns this same binding so every closure in this IIFE
-  // that reads headingNodes (detectActiveHeading, the zoom/resize scroll
-  // anchor's binary search, …) sees the live nodes without needing its own
-  // re-init call — they all close over this one variable, not a copy of it.
+  // that reads headingNodes (readingLineHeading, …) sees the live nodes without
+  // needing its own re-init call — they all close over this one variable, not a
+  // copy of it. (The zoom/resize anchoring, captureScrollAnchor, does not read
+  // it: it walks contentEl.children.)
   let headingNodes = Array.from(document.querySelectorAll('[data-reader-heading]'));
   const tocLinks = new Map(
     Array.from(document.querySelectorAll('.toc a[href^="#"]')).map((link) => [link.getAttribute('href').slice(1), link])
@@ -3812,12 +4025,18 @@ ${mermaidInitTag}`)
   }
 
   const breadcrumbEl = document.querySelector('[data-toc-breadcrumb]');
+  const mobileBarTitle = document.getElementById('mobile-bar-title');
+  if (mobileBarTitle && sections.length) mobileBarTitle.textContent = sections[0].title;
   const sectionIndexById = new Map(sections.map((section, i) => [section.id, i]));
 
   // Sticky breadcrumb: the ancestor chain (shallow→deep) of the active section.
   // For each decreasing depth, take the nearest preceding section, then append
-  // the active section itself. Rendered as stacked, indented, clickable rows.
+  // the active section itself. The rows are still written into the breadcrumb
+  // element, but CSS hides it (the TOC highlights the path); the useful output
+  // today is the last link's title, which names the mobile bar.
+  let breadcrumbId = null;
   function renderBreadcrumb(sectionId) {
+    breadcrumbId = sectionId;
     if (!breadcrumbEl) return;
     if (!sectionIndexById.has(sectionId)) {
       breadcrumbEl.innerHTML = '';
@@ -3837,6 +4056,7 @@ ${mermaidInitTag}`)
       return;
     }
     const minDepth = chain[0].depth;
+    if (mobileBarTitle) mobileBarTitle.textContent = chain[chain.length - 1].title;
     breadcrumbEl.innerHTML = chain
       .map((section, i) => {
         const indent = (section.depth - minDepth) * 10;
@@ -3862,11 +4082,24 @@ ${mermaidInitTag}`)
     if (!scroller) return;
     const scrollerRect = scroller.getBoundingClientRect();
     const linkRect = link.getBoundingClientRect();
-    if (linkRect.top < scrollerRect.top) {
-      scroller.scrollTop += linkRect.top - scrollerRect.top;
-    } else if (linkRect.bottom > scrollerRect.bottom) {
-      scroller.scrollTop += linkRect.bottom - scrollerRect.bottom;
+    // Keep the active row at about 40% of the TOC box instead of nudging it
+    // back to an edge: the highlight stays mid-box, never at 0% or 95%.
+    const target = scroller.scrollTop + (linkRect.top - scrollerRect.top) - scroller.clientHeight * 0.4;
+    if (Math.abs(target - scroller.scrollTop) <= 2) return;
+    const out = linkRect.bottom < scrollerRect.top || linkRect.top > scrollerRect.bottom;
+    const calm = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    scroller.scrollTo({ top: target, behavior: out || calm ? 'auto' : 'smooth' });
+  }
+
+  // Accordion: only the active row's ancestor path stays open.
+  function collapseOtherTocDetails(link) {
+    const keep = new Set();
+    for (let node = link && link.closest('details'); node; node = node.parentElement && node.parentElement.closest('details')) {
+      keep.add(node);
     }
+    Array.from(document.querySelectorAll('.toc-list details[open]')).forEach((node) => {
+      if (!keep.has(node)) node.open = false;
+    });
   }
 
   let observerFrozen = false;
@@ -3887,52 +4120,92 @@ ${mermaidInitTag}`)
       next.classList.add('is-active');
       if (!freezeSidebar) {
         expandTocAncestors(next);
+        collapseOtherTocDetails(next);
         ensureTocLinkVisible(next);
       }
     }
   }
 
-  // Hoisted out of a bare if block (and into a rebindable function) so that
-  // window.__md2docRebindReader() below can disconnect the stale observer
-  // and create a fresh one over the post-edit heading nodes — an observer
-  // keeps observing the exact node references passed to observe(), so after
-  // .content's innerHTML is replaced wholesale, the old observer is watching
-  // detached nodes that will never intersect anything again.
-  let headingObserver = null;
-  function bindHeadingObserver() {
-    if (headingObserver) {
-      headingObserver.disconnect();
-      headingObserver = null;
-    }
-    if (typeof IntersectionObserver === 'undefined' || !headingNodes.length) {
-      return;
+  // The reading line: the last heading that has a TOC row and sits at or
+  // above 35% of the viewport height (the first such heading when none has
+  // reached the line yet). Headings without a TOC row (a lone H1 is flattened
+  // away) are skipped, so the highlight never lands on a row that is not there.
+  // A TOC click lands the clicked heading at the top of the page; when its
+  // section is shorter than the gap down to the line, the next heading is
+  // already above the line and would steal the highlight from the row that was
+  // just clicked. The clicked heading stays the answer for as long as it is
+  // still between the page top and the line, and the first scroll that moves
+  // it out of that band hands tracking back to the line.
+  let pinnedHeadingId = null;
+  function readingLineHeading() {
+    const line = window.innerHeight * 0.35;
+    if (pinnedHeadingId) {
+      const pinned = document.getElementById(pinnedHeadingId);
+      const top = pinned ? pinned.getBoundingClientRect().top : Infinity;
+      if (pinned && tocLinks.has(pinned.id) && top >= -40 && top <= line) return pinned;
+      pinnedHeadingId = null;
     }
-    headingObserver = new IntersectionObserver((entries) => {
-      if (observerFrozen) {
-        return;
-      }
-      const visible = entries
-        .filter((entry) => entry.isIntersecting)
-        .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
-      if (visible[0]) {
-        syncActiveHeading(visible[0].target.id);
+    let first = null;
+    let candidate = null;
+    for (const node of headingNodes) {
+      if (!tocLinks.has(node.id)) continue;
+      if (!first) first = node;
+      if (node.getBoundingClientRect().top <= line) {
+        candidate = node;
+      } else {
+        break;
       }
-    }, { rootMargin: '0px 0px -65% 0px', threshold: [0, 1] });
-    headingNodes.forEach((node) => headingObserver.observe(node));
+    }
+    return candidate || first;
+  }
+
+  // One scroll listener, installed once, throttled to one pass per animation
+  // frame. bindHeadingObserver keeps its name because
+  // window.__md2docRebindReader calls it after an edit-mode re-render; it only
+  // runs a pass now, since headingNodes is read live on every pass.
+  // A lone H1 has no TOC row, so the highlight skips it; the bar still names
+  // the document while that H1 is on screen, as it always has, and names the
+  // active section once the H1 has scrolled off.
+  function syncReadingTitle(node) {
+    const first = sections[0] ? document.getElementById(sections[0].id) : null;
+    const onScreen = first && first !== node && !tocLinks.has(first.id) && first.getBoundingClientRect().top >= 0;
+    const titleId = onScreen ? first.id : node.id;
+    if (titleId !== breadcrumbId) renderBreadcrumb(titleId);
+  }
+  let readingLinePending = false;
+  function readingLinePass() {
+    readingLinePending = false;
+    if (observerFrozen) return;
+    const node = readingLineHeading();
+    if (!node) return;
+    syncActiveHeading(node.id);
+    syncReadingTitle(node);
+  }
+  window.addEventListener('scroll', () => {
+    if (readingLinePending) return;
+    readingLinePending = true;
+    requestAnimationFrame(readingLinePass);
+  }, { passive: true });
+  document.addEventListener('click', (event) => {
+    const link = event.target && event.target.closest && event.target.closest('.toc a[href^="#"]');
+    if (link) pinnedHeadingId = link.getAttribute('href').slice(1);
+  });
+  function bindHeadingObserver() {
+    readingLinePass();
   }
-  bindHeadingObserver();
 
   // Paint the breadcrumb immediately so the header is populated before the
-  // first IntersectionObserver callback fires.
+  // first reading-line pass runs, then run that pass once on load.
   if (sections[0]) {
     renderBreadcrumb(sections[0].id);
   }
+  bindHeadingObserver();
 
   // Edit mode only: re-init hook, sibling to window.__md2docInitDiagrams
   // (defined in diagramInitHookScript above for edit-mode pages), called
   // from lib/editor/client.js's rerenderAll() right after it swaps
   // .content's innerHTML on a commit. Re-queries the heading nodes that
-  // just got replaced and rebinds the IntersectionObserver onto them, so
+  // just got replaced and runs one reading-line pass over them, so
   // TOC highlighting / breadcrumb tracking / the zoom-resize scroll anchor
   // (all of which read the headingNodes binding above) keep working
   // against live nodes instead of silently going dead after the first edit.
@@ -4164,22 +4437,8 @@ ${mermaidInitTag}`)
     }
   }
 
-  function detectActiveHeading() {
-    const threshold = 120;
-    let candidate = null;
-    for (const node of headingNodes) {
-      const rect = node.getBoundingClientRect();
-      if (rect.top <= threshold) {
-        candidate = node;
-      } else {
-        break;
-      }
-    }
-    return candidate || headingNodes[0] || null;
-  }
-
   function resyncTocToScroll() {
-    const node = detectActiveHeading();
+    const node = readingLineHeading();
     if (!node) return;
     if (readerState.activeSectionId === node.id) {
       const link = tocLinks.get(node.id);
@@ -4187,9 +4446,11 @@ ${mermaidInitTag}`)
         expandTocAncestors(link);
         ensureTocLinkVisible(link);
       }
+      syncReadingTitle(node);
       return;
     }
     syncActiveHeading(node.id);
+    syncReadingTitle(node);
   }
 
   function ensureActiveResultVisible() {
@@ -4416,18 +4677,30 @@ ${mermaidInitTag}`)
     var hit = document.elementFromPoint(rect.left + rect.width / 2, ANCHOR_LINE);
     var node = (hit && hit.closest) ? hit.closest('main.content > *') : null;
     if (!node) {
-      // Between blocks, or over a gap: fall back to the last heading above the
-      // anchor line. Heading offsets are monotonic in document order, so this
-      // is a binary search rather than a scan of every heading each frame.
+      // Over a gap (a heading's top margin, the space between blocks): pin the
+      // first block that starts below the anchor line, which is what the reader
+      // sees next to it. Falling back to the last heading ABOVE the line would
+      // pin something up to a whole section away. Block tops are monotonic in
+      // document order, so this is a binary search over the column's children.
+      var kids = contentEl.children;
       var lo = 0;
-      var hi = headingNodes.length - 1;
+      var hi = kids.length - 1;
       while (lo <= hi) {
         var mid = (lo + hi) >> 1;
-        if (headingNodes[mid].getBoundingClientRect().top <= ANCHOR_LINE) {
-          node = headingNodes[mid];
-          lo = mid + 1;
-        } else {
+        // A child with no layout boxes (every WaveDrom fence leaves a script
+        // element) reports an all-zero rect, which would break the
+        // monotonic order the search depends on. Compare the nearest
+        // following child that is rendered; none left before hi means the
+        // answer is in the lower half.
+        var probe = mid;
+        while (probe <= hi && !kids[probe].getClientRects().length) probe++;
+        if (probe > hi) {
           hi = mid - 1;
+        } else if (kids[probe].getBoundingClientRect().top > ANCHOR_LINE) {
+          node = kids[probe];
+          hi = mid - 1;
+        } else {
+          lo = probe + 1;
         }
       }
     }
@@ -5645,6 +5918,9 @@ ${usesDrawioMultiPage ? `  // v3.4.0 batch2 Task 6: wired through a NAMED, reusa
   } finally {
     await drawioBrowser.closeIfOpen();
   }
+  // v3.9.0 dark mode: a post-pass over the finished reader HTML (lib/theme/).
+  // Edit mode is light-only; noTheme is an internal switch for the light-lock test.
+  if (!opts.editMode && !opts.noTheme) bakedHtml = applyReaderTheme(bakedHtml);
   return {
     html: bakedHtml, bodyHtml: bakedBody, parts, blocks,
     // v3.4.0 batch2 Task 6: an added field, not a shape change to the four
@@ -5656,6 +5932,42 @@ ${usesDrawioMultiPage ? `  // v3.4.0 batch2 Task 6: wired through a NAMED, reusa
 }
 module.exports = { renderMarkdown };
 
+// Index of the first "{" in dot source that opens the graph body: not inside a
+// double-quoted string, a // or /* */ comment, a line starting with # (dot
+// treats it as preprocessor output), or an HTML-like <...> id. -1 if none.
+function firstDotBrace(src) {
+  let i = 0;
+  const n = src.length;
+  while (i < n) {
+    const c = src[i];
+    if (c === '"') {
+      i++;
+      while (i < n && src[i] !== '"') i += src[i] === '\\' ? 2 : 1;
+      i++;
+    } else if (c === '/' && src[i + 1] === '/') {
+      while (i < n && src[i] !== '\n') i++;
+    } else if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      i = end < 0 ? n : end + 2;
+    } else if (c === '#' && (i === 0 || src[i - 1] === '\n')) {
+      while (i < n && src[i] !== '\n') i++;
+    } else if (c === '<') {
+      let depth = 0;
+      while (i < n) {
+        if (src[i] === '<') depth++;
+        else if (src[i] === '>' && --depth === 0) break;
+        i++;
+      }
+      i++;
+    } else if (c === '{') {
+      return i;
+    } else {
+      i++;
+    }
+  }
+  return -1;
+}
+
 // Render every deferred dot/graphviz placeholder to inline SVG using the
 // in-process WASM engine. Loads the WASM module only when at least one dot
 // block exists, so text-only docs pay nothing.
@@ -5672,11 +5984,35 @@ async function bakeGraphviz(htmlStr) {
   return htmlStr.replace(GRAPHVIZ_PLACEHOLDER.re, (m, b64) => {
     const dotSrc = Buffer.from(b64, 'base64').toString('utf8');
     try {
-      const svg = gv.dot(dotSrc)
+      // Graphviz measures label widths with the font it lays out in, and with
+      // no fontname that is Times, whose metrics are narrower than the sans
+      // the SVG is drawn in -- so labels overflowed their boxes. Declare
+      // Helvetica BEFORE layout, right after the first brace; a fontname the
+      // author writes later in the source still wins. Exactly "Helvetica":
+      // a "Helvetica,sans-Serif" family list falls back to Times widths.
+      const at = firstDotBrace(dotSrc);
+      const laidOut = at < 0 ? dotSrc : dotSrc.slice(0, at + 1) +
+        ' graph [fontname="Helvetica"]; node [fontname="Helvetica"]; edge [fontname="Helvetica"]; ' + dotSrc.slice(at + 1);
+      let laid;
+      try {
+        laid = gv.dot(laidOut);
+      } catch (injectErr) {
+        // Injection must never turn a valid graph into an error: lay the
+        // original source out as the author wrote it.
+        if (laidOut === dotSrc) throw injectErr;
+        laid = gv.dot(dotSrc);
+      }
+      const svg = laid
         .replace(/<\?xml[^>]*\?>/g, '')
         .replace(/<!DOCTYPE[\s\S]*?>/g, '')
         // drop graphviz's "Generated by graphviz" banner comment so the div and <svg> are adjacent
         .replace(/<!--[\s\S]*?-->/g, '')
+        // v3.8.0: graphviz falls back to Times when no fontname is set. The
+        // injection above makes Helvetica the layout font, so this rewrite
+        // now only touches an author's explicit Times-Roman, or a figure
+        // whose injection fell back to the original source; other explicit
+        // fontnames are untouched.
+        .replace(/font-family="Times,serif"/g, 'font-family="Helvetica,sans-Serif"')
         .trim();
       return `<div class="graphviz">${svg}</div>`;
     } catch (e) {
@@ -5838,6 +6174,7 @@ async function bakeDiagrams(htmlStr, dstPath) {
 if (require.main === module) {
   const [,, src, dst] = process.argv;
   const BAKE_SVG = process.argv.slice(4).includes('--bake-svg');
+  const LANG_ARG = (process.argv.slice(4).find((a) => a.startsWith('--lang=')) || '').slice('--lang='.length) || undefined;
   if (!src || !dst) {
     console.error('Usage: node md2doc.js <input.md> <output.html|pdf>');
     process.exit(1);
@@ -5847,7 +6184,7 @@ if (require.main === module) {
 
   (async () => {
     const mdText = fs.readFileSync(src, 'utf8');
-    const { html } = await renderMarkdown(mdText, path.resolve(src), {});
+    const { html } = await renderMarkdown(mdText, path.resolve(src), { lang: LANG_ARG });
     let finalHtml = html;
 
     if (ext === '.html') {