@helping-ai-workflow/md2doc 3.6.1 → 3.8.0

package/lib/md2doc.js

@@ -140,9 +140,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 +375,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 +771,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 +1041,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 +1215,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 +1231,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 +1305,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++) {
@@ -1423,6 +1514,14 @@ ${itemsHtml}
   /* min-width: 0 so an unbreakable token inside an item cannot widen the row
      past its siblings — that would break the equal-width guarantee above. */
   .ed-block[data-block-type="li"] > .ed-li-text { flex: 1 1 auto; min-width: 0; }
+  /* The MD 原始碼 raw editor replaces the item's children with one .ed-editing
+     wrap, which is then this flex row's only child. Without a grow it shrank
+     to the textarea's intrinsic size and .ed-raw's width: 100% resolved
+     against that: 189px at every viewport width (measured), where every other
+     block's raw editor spans the column. The marker, and with it the indent,
+     is gone while the textarea is open, so it spans the full column at every
+     depth; the source line's own leading spaces show the nesting. */
+  .ed-block[data-block-type="li"] > .ed-editing { flex: 1 1 auto; min-width: 0; }
   /* column-gap already provides the marker/checkbox separation. */
   .ed-block[data-block-type="li"] > .ed-li-check { flex: 0 0 auto; margin-right: 0; }
   .ed-block[data-list-type="ul"] > .ed-li-marker::before { content: "\\2022"; }${edOlCounterCss}
@@ -1601,6 +1700,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
@@ -2129,15 +2232,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;
@@ -2166,7 +2278,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;
@@ -2176,7 +2290,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,
@@ -2232,26 +2346,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;
@@ -2296,65 +2397,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;
   }
@@ -2379,13 +2506,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;
@@ -2393,20 +2521,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;
@@ -2452,8 +2581,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;
@@ -2502,6 +2631,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;
@@ -2526,13 +2657,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;
@@ -2542,17 +2675,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;
@@ -2574,6 +2731,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 {
@@ -2585,15 +2744,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,
@@ -2625,6 +2784,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;
   }
@@ -2645,14 +2817,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 {
@@ -2663,6 +2836,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;
@@ -2672,9 +2852,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;
@@ -2687,7 +2866,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,
@@ -2700,10 +2879,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;
@@ -2917,21 +3093,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;
@@ -2941,10 +3155,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
@@ -2961,7 +3174,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; }
@@ -2986,10 +3198,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; }
@@ -3007,18 +3228,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
@@ -3267,6 +3487,11 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
      indicator' is the singleton line shown while dragging a row.
      '.ed-te-row-dragging' dims the row actually being dragged. */
   .ed-te-hl { background: rgba(59, 130, 246, 0.15) !important; }
+  /* Table cell-range selection: the painted rectangle, and the table that
+     holds one (its caret and native selection are hidden while it stands). */
+  .ed-cell-range { background: rgba(59, 130, 246, 0.18) !important; }
+  .ed-cell-range-active { caret-color: transparent; }
+  .ed-cell-range-active ::selection { background: transparent; }
   .ed-te-menu {
     position: fixed; z-index: 12;
     display: flex; align-items: center; gap: 4px;
@@ -3710,8 +3935,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">
@@ -3799,11 +4023,15 @@ ${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.
   function renderBreadcrumb(sectionId) {
     if (!breadcrumbEl) return;
     if (!sectionIndexById.has(sectionId)) {
@@ -3824,6 +4052,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;
@@ -4403,18 +4632,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;
         }
       }
     }
@@ -5643,6 +5884,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.
@@ -5659,11 +5936,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) {
@@ -5825,6 +6126,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);
@@ -5834,7 +6136,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') {