@helping-ai-workflow/md2doc 3.8.0 → 3.9.1

package/README.md

@@ -78,6 +78,10 @@ also pass `--open`.
 | `--version`, `-v` | Print version. |
 | `--help`, `-h` | Print help. |
 
+### Reading view
+
+- **Dark mode** — a ☀/☾ toggle (bottom-right on desktop, top bar on phone). Light by default; the choice is remembered in the browser. PDF and print stay light.
+
 ### Images
 
 Local images referenced from the markdown are resolved against the **markdown file's own

package/lib/editor/client.js

@@ -12823,7 +12823,8 @@
       // S4 Task 2b (user request, 2026-09-01): the ONLY feedback the source
       // block gets. `.ed-handle` is `opacity: 0` off-hover, so from the moment
       // the pointer leaves the block there is nothing under the cursor but the
-      // indicator line. The ruling is a `cursor: grabbing` class on
+      // indicator line. The ruling is a drag-cursor class (`cursor: move`; v3.8.1
+      // dropped `grabbing`, a browser bitmap on Windows) on
       // `document.documentElement` — OUTSIDE `contentEl`, so the "mutate
       // nothing in the content DOM during a drag" invariant this whole gesture
       // rests on still holds, and every cancellation path stays unconditional.
@@ -13578,7 +13579,7 @@
       if (tePointer.hit.kind === 'row') {
         // The column grip hides like the insert bubbles above (it isn't
         // meaningful mid row-drag); the ROW grip stays visible and switches
-        // to its "dragging" visual (grabbing cursor) — it IS the drag
+        // to its "dragging" visual (move cursor) — it IS the drag
         // handle the user is holding, per the brief ("the active grip may
         // stay as the drag handle visual").
         colGrip.hidden = true;

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).
@@ -1346,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) {
@@ -1908,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
@@ -2321,7 +2322,7 @@ const html = `<!DOCTYPE html>
   .sidebar-splitter {
     flex: 0 0 32px;
     align-self: stretch;
-    cursor: col-resize;
+    cursor: ew-resize;
     display: flex;
     justify-content: flex-start;
     touch-action: none;
@@ -2957,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 {
@@ -3062,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
@@ -3540,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
@@ -3567,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. */
@@ -3589,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:
@@ -4001,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])
@@ -4032,7 +4034,9 @@ ${mermaidInitTag}`)
   // 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 = '';
@@ -4078,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;
@@ -4103,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.
@@ -4380,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);
@@ -4403,9 +4446,11 @@ ${mermaidInitTag}`)
         expandTocAncestors(link);
         ensureTocLinkVisible(link);
       }
+      syncReadingTitle(node);
       return;
     }
     syncActiveHeading(node.id);
+    syncReadingTitle(node);
   }
 
   function ensureActiveResultVisible() {
@@ -4623,11 +4668,19 @@ ${mermaidInitTag}`)
   var anchorTop = 0;
   var anchorFrame = 0;
   var suppressAnchorCapture = false;
+  // Column width the anchor was last captured/held at; -1 until the column
+  // ResizeObserver below is installed. See captureScrollAnchor's first guard.
+  var lastAnchorColW = -1;
   var lastLayoutWidth = document.documentElement.clientWidth;
   var lastPixelRatio = window.devicePixelRatio;
 
   function captureScrollAnchor() {
     if (suppressAnchorCapture || !contentEl) return;
+    // A column reflow the ResizeObserver has not delivered yet: during a
+    // splitter drag the next pointermove lands before holdScrollAnchor's
+    // trailing capture frame, so capturing now would pin a post-reflow node
+    // and the observer's restore would then find nothing to correct.
+    if (lastAnchorColW >= 0 && contentEl.clientWidth !== lastAnchorColW) return;
     var rect = contentEl.getBoundingClientRect();
     var hit = document.elementFromPoint(rect.left + rect.width / 2, ANCHOR_LINE);
     var node = (hit && hit.closest) ? hit.closest('main.content > *') : null;
@@ -4679,14 +4732,7 @@ ${mermaidInitTag}`)
     });
   }, { passive: true });
 
-  window.addEventListener('resize', function () {
-    var width = document.documentElement.clientWidth;
-    var ratio = window.devicePixelRatio;
-    // A height-only change (a mobile browser hiding its toolbar, a devtools
-    // dock) reflows nothing, so correcting the scroll would only jerk the page.
-    if (width === lastLayoutWidth && ratio === lastPixelRatio) return;
-    lastLayoutWidth = width;
-    lastPixelRatio = ratio;
+  function holdScrollAnchor() {
     // Hold the anchor across the whole reflow: the scrollTo below fires scroll
     // events that would otherwise re-capture a mid-reflow position.
     suppressAnchorCapture = true;
@@ -4698,8 +4744,37 @@ ${mermaidInitTag}`)
         captureScrollAnchor();
       });
     });
+  }
+
+  window.addEventListener('resize', function () {
+    var width = document.documentElement.clientWidth;
+    var ratio = window.devicePixelRatio;
+    // A height-only change (a mobile browser hiding its toolbar, a devtools
+    // dock) reflows nothing, so correcting the scroll would only jerk the page.
+    if (width === lastLayoutWidth && ratio === lastPixelRatio) return;
+    lastLayoutWidth = width;
+    lastPixelRatio = ratio;
+    holdScrollAnchor();
   });
 
+  // The column also narrows and widens with no window resize at all: a
+  // sidebar-splitter drag, its double-click reset and the TOC collapse toggle
+  // only move --md2doc-sidebar-w / data-toc-collapsed, so the 'resize' listener
+  // above never hears about them and the reflow slid the page by thousands of
+  // px. Watch the column itself. Width only: its height changes whenever an
+  // image or diagram finishes loading, which reflows nothing above the anchor.
+  // The first callback (fired by observe()) sees the starting width and does
+  // nothing, so a load that lands on a #hash is never pulled back.
+  if (contentEl && typeof ResizeObserver === 'function') {
+    lastAnchorColW = contentEl.clientWidth;
+    new ResizeObserver(function () {
+      var w = contentEl.clientWidth;
+      if (w === lastAnchorColW) return;
+      lastAnchorColW = w;
+      holdScrollAnchor();
+    }).observe(contentEl);
+  }
+
   captureScrollAnchor();
 
   // ── drawio sheet bar ─────────────────────────────────────────────────────
@@ -5873,6 +5948,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

package/lib/theme/runtime.js

@@ -0,0 +1,268 @@
+// md2doc reader theme toggle (v3.9.0). Inlined into reader HTML by
+// lib/theme/tokens.js#applyReaderTheme — plain browser JS, not part of the
+// lib/md2doc.js template literal. Must never contain a closing script tag.
+// Spec: docs/superpowers/specs/2026-10-02-dark-mode-design.md
+(function () {
+  'use strict';
+  var KEY = 'md2doc-theme';
+  var root = document.documentElement;
+  var btn = document.getElementById('md2doc-theme-toggle');
+  var dataEl = document.getElementById('md2doc-theme-data');
+  if (!btn || !dataEl) return;
+  btn.hidden = false;
+  var data = JSON.parse(dataEl.textContent);
+  var listeners = [];
+  function onTheme(fn) { listeners.push(fn); }
+  function notify(dark) { for (var i = 0; i < listeners.length; i++) listeners[i](dark); }
+  function isDark() { return root.getAttribute('data-md2doc-theme') === 'dark'; }
+  function save(dark) {
+    try {
+      if (dark) localStorage.setItem(KEY, 'dark'); else localStorage.removeItem(KEY);
+    } catch (e) { /* storage blocked: the choice lasts for this page only */ }
+  }
+  function paint() {
+    var dark = isDark();
+    var label = dark ? 'Dark theme (click for light)' : 'Light theme (click for dark)';
+    btn.textContent = dark ? '☾' : '☀';
+    btn.setAttribute('aria-label', label);
+    btn.title = label;
+  }
+  btn.addEventListener('click', function () {
+    var dark = !isDark();
+    if (dark) root.setAttribute('data-md2doc-theme', 'dark'); else root.removeAttribute('data-md2doc-theme');
+    save(dark);
+    paint();
+    notify(dark);
+  });
+
+  // Phone (<= 1080px): the one button moves into the 44px top bar. A document
+  // with no headings has no bar, so the button keeps floating there.
+  var bar = document.getElementById('mobile-bar');
+  var phone = window.matchMedia('(max-width: 1080px)');
+  function place() {
+    if (bar && phone.matches) { if (btn.parentNode !== bar) bar.appendChild(btn); }
+    else if (btn.parentNode !== document.body) document.body.appendChild(btn);
+  }
+  if (phone.addEventListener) phone.addEventListener('change', place); else if (phone.addListener) phone.addListener(place);
+  place();
+
+  // Print is always light. The dark tokens are @media screen only; the
+  // listeners put diagrams back to their light form while printing.
+  var printedDark = false;
+  window.addEventListener('beforeprint', function () { printedDark = isDark(); if (printedDark) notify(false); });
+  window.addEventListener('afterprint', function () { if (printedDark) notify(true); printedDark = false; });
+
+  paint();
+
+  // ── mermaid: light and dark each drawn once, then swapped as markup ──
+  // The runtime takes over md2doc's own startOnLoad render (mermaid reads
+  // startOnLoad from its config at window load), draws light first so print
+  // and toggle-back always have it, and draws dark the first time it is needed.
+  var mermaids = [].slice.call(document.querySelectorAll('.content .mermaid'));
+  var hasMermaid = typeof window.mermaid !== 'undefined' && mermaids.length > 0;
+  var rendered = { light: null, dark: null };
+  var chain = Promise.resolve();
+  var inFlight = 0;
+  // Which render the hosts hold. The observer below must not recolour a light
+  // render that is shown on purpose (print while dark swaps light back in).
+  var mermaidShown = 'light';
+  function mermaidConfig(theme) {
+    return { startOnLoad: false, theme: 'base', themeVariables: theme === 'dark' ? data.mermaidDark : data.mermaidLight };
+  }
+  function swapMermaid(theme) {
+    mermaidShown = theme;
+    mermaids.forEach(function (el, i) { el.innerHTML = rendered[theme][i]; });
+  }
+  function cached(theme) {
+    var r = rendered[theme];
+    if (!r) return false;
+    for (var i = 0; i < mermaids.length; i++) if (typeof r[i] !== 'string') return false;
+    return true;
+  }
+  // Light: mermaid.run over the source-text hosts, which is what shows mermaid's
+  // own error box for a broken diagram. run() rejects after one, so the cache is
+  // stored either way; otherwise every toggle would redraw everything.
+  function drawLight() {
+    window.mermaid.initialize(mermaidConfig('light'));
+    mermaidShown = 'light';
+    mermaids.forEach(function (el) { el.removeAttribute('data-processed'); el.textContent = el.getAttribute('data-md2doc-src'); });
+    function store() { rendered.light = mermaids.map(function (el) { return el.innerHTML; }); }
+    return window.mermaid.run({ nodes: mermaids }).then(store, function (e) { store(); throw e; });
+  }
+  // Dark: no host is touched until its own svg is ready, so the page never
+  // collapses to source text (WebKit has no scroll anchoring and would lose the
+  // reading position). A broken diagram keeps its current markup.
+  function drawDark() {
+    window.mermaid.initialize(mermaidConfig('dark'));
+    mermaidShown = 'dark';
+    rendered.dark = [];
+    var p = Promise.resolve();
+    mermaids.forEach(function (el, i) {
+      p = p.then(function () {
+        return window.mermaid.render('md2doc-mermaid-dark-' + i, el.getAttribute('data-md2doc-src')).then(function (res) {
+          el.innerHTML = res.svg;
+          if (res.bindFunctions) res.bindFunctions(el);
+          var s = el.querySelector('svg');
+          if (s) { s.setAttribute('data-md2doc-recoloured', ''); s.setAttribute('data-md2doc-live', ''); }
+        }, function () {
+          var stray = document.getElementById('dmd2doc-mermaid-dark-' + i);
+          if (stray && stray.parentNode) stray.parentNode.removeChild(stray);
+          // The host keeps its light render (mermaid's error box); it was drawn light, so it needs the full recolour.
+          var kept = el.querySelector('svg');
+          if (kept && !kept.hasAttribute('data-md2doc-live')) recolourSvg(kept, isDark());
+        }).then(function () { rendered.dark[i] = el.innerHTML; });
+      });
+    });
+    return p.then(function () { window.mermaid.initialize(mermaidConfig('light')); });
+  }
+  function drawMermaid(theme) { return theme === 'dark' ? drawDark() : drawLight(); }
+  function showMermaid(dark) {
+    if (!hasMermaid) return;
+    var theme = dark ? 'dark' : 'light';
+    // Synchronous when nothing is drawing and the render is cached: print needs that.
+    // Known limit: if beforeprint fires while a dark draw is in flight, the light swap
+    // is queued behind it, so that print snapshot can catch the raw mermaid source.
+    if (!inFlight && cached(theme)) { swapMermaid(theme); return; }
+    inFlight++;
+    chain = chain.then(function () { return cached(theme) ? swapMermaid(theme) : drawMermaid(theme); })
+      .catch(function () { /* a failed render leaves mermaid's own error box */ })
+      .then(function () { inFlight--; });
+  }
+  if (hasMermaid) {
+    mermaids.forEach(function (el) { el.setAttribute('data-md2doc-src', el.textContent); });
+    window.mermaid.initialize(mermaidConfig('light'));
+    window.addEventListener('load', function () {
+      showMermaid(false);
+      if (isDark()) showMermaid(true);
+    });
+    onTheme(showMermaid);
+  }
+
+  // ── graphviz / WaveDrom / baked SVG: recolour by computed colour ──
+  // Rules: spec "Diagram recolour rules (D10)". Reading COMPUTED fill/stroke
+  // covers both graphviz presentation attributes and WaveDrom's own <style>.
+  var INK = '#c4c7cc';
+  var TEXT = '#e3e3e3';
+  // .mermaid svg is always included. A live dark render (data-md2doc-live, set by drawDark)
+  // keeps mermaid's own arrowheads, markers and edges: only its labels and node shapes
+  // carrying an author style are recoloured. A baked or light-drawn mermaid svg gets the full rules.
+  var RECOLOUR = '.content .graphviz svg, .content [id^="WaveDrom_Display_"] svg, .content .wavedrom-diagram svg, .content .mermaid svg';
+  var XHTML = 'http://www.w3.org/1999/xhtml';
+  // Saturation caps are the spec D10 values: 0.7 for text, 0.8 for lines, 0.55 for fills.
+  var probe = document.createElement('canvas').getContext('2d');
+  function rgba(c) {
+    if (!c || c === 'none' || c.indexOf('url(') === 0) return null;
+    var m = /rgba?\(([^)]+)\)/.exec(c);
+    if (!m) {
+      probe.fillStyle = '#000'; probe.fillStyle = c; c = probe.fillStyle;
+      if (c.charAt(0) === '#') return [parseInt(c.slice(1, 3), 16), parseInt(c.slice(3, 5), 16), parseInt(c.slice(5, 7), 16), 1];
+      m = /rgba?\(([^)]+)\)/.exec(c);
+      if (!m) return null;
+    }
+    var p = m[1].split(',').map(parseFloat);
+    return [p[0], p[1], p[2], p.length > 3 ? p[3] : 1];
+  }
+  function lum(c) {
+    function f(v) { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }
+    return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]);
+  }
+  function hsl(c) {
+    var r = c[0] / 255, g = c[1] / 255, b = c[2] / 255;
+    var mx = Math.max(r, g, b), mn = Math.min(r, g, b), d = mx - mn, l = (mx + mn) / 2, h = 0, s = 0;
+    if (d) {
+      s = l > 0.5 ? d / (2 - mx - mn) : d / (mx + mn);
+      h = mx === r ? (g - b) / d + (g < b ? 6 : 0) : mx === g ? (b - r) / d + 2 : (r - g) / d + 4;
+      h *= 60;
+    }
+    return [h, s, l];
+  }
+  function tone(c, l, smax) {
+    var x = hsl(c);
+    return 'hsl(' + Math.round(x[0]) + ', ' + Math.round(Math.min(x[1], smax) * 100) + '%, ' + Math.round(l * 100) + '%)';
+  }
+  function lineColour(c) { return hsl(c)[1] > 0.25 ? tone(c, 0.68, 0.8) : INK; }
+  function recolourSvg(svg, dark) {
+    var els = svg.querySelectorAll('polygon, ellipse, path, polyline, rect, line, circle, text, tspan, foreignObject *');
+    var live = svg.hasAttribute('data-md2doc-live');
+    for (var i = 0; i < els.length; i++) {
+      var el = els[i];
+      if (el.hasAttribute('data-md2doc-style')) {
+        var orig = el.getAttribute('data-md2doc-style');
+        if (orig) el.setAttribute('style', orig); else el.removeAttribute('style');
+      } else {
+        if (live && el.namespaceURI !== XHTML) {
+          var own = el.getAttribute('style') || '';
+          // Only what the author styled: node and subgraph shapes, linkStyle edges, text. Never "any inline style":
+          // mermaid writes its own fill and stroke inline (pie legend rects), and markers keep their theme colours.
+          if (el.closest('marker') || !/(^|;)\s*(fill|stroke)\s*:/.test(own) ||
+              !(el.closest('g.node, g.cluster') || el.matches('.flowchart-link') || /^(text|tspan)$/i.test(el.tagName))) continue;
+        }
+        el.setAttribute('data-md2doc-style', el.getAttribute('style') || '');
+      }
+      if (!dark) continue;
+      var cs = getComputedStyle(el);
+      var ov = '';
+      if (el.namespaceURI === XHTML) {
+        // Mermaid flowchart labels: HTML inside foreignObject, coloured by CSS.
+        var fg = rgba(cs.color), bgc = rgba(cs.backgroundColor);
+        if (fg && fg[3] > 0 && lum(fg) < 0.35) ov += 'color:' + (hsl(fg)[1] > 0.25 ? tone(fg, 0.78, 0.7) : TEXT) + ' !important;';
+        if (bgc && bgc[3] > 0) {
+          var BL = lum(bgc);
+          if (BL > 0.85) ov += 'background-color:transparent !important;';
+          else if (BL > 0.3) ov += 'background-color:' + tone(bgc, 0.26, 0.55) + ' !important;';
+        }
+        if (ov) {
+          var hb = el.getAttribute('data-md2doc-style');
+          el.setAttribute('style', (hb ? hb.replace(/;?\s*$/, ';') : '') + ov);
+        }
+        continue;
+      }
+      var fill = rgba(cs.fill), stroke = rgba(cs.stroke);
+      // Overrides are written once, as attribute text, never through el.style:
+      // setProperty leaves style="" on the element after the restore removes
+      // the attribute (Chromium re-serialises it), so light would not be
+      // byte-exact.
+      if (/^(text|tspan)$/i.test(el.tagName)) {
+        if (fill && fill[3] > 0 && lum(fill) < 0.35) ov += 'fill:' + (hsl(fill)[1] > 0.25 ? tone(fill, 0.78, 0.7) : TEXT) + ' !important;';
+      } else {
+        if (fill && fill[3] > 0) {
+          var L = lum(fill);
+          if (L > 0.85) ov += 'fill:transparent !important;';
+          else if (L > 0.3) ov += 'fill:' + tone(fill, 0.26, 0.55) + ' !important;';
+          else if (el.closest('g.edge, marker')) ov += 'fill:' + lineColour(fill) + ' !important;';
+        }
+        if (stroke && stroke[3] > 0 && lum(stroke) < 0.35) ov += 'stroke:' + lineColour(stroke) + ' !important;';
+      }
+      if (ov) {
+        var base = el.getAttribute('data-md2doc-style');
+        el.setAttribute('style', (base ? base.replace(/;?\s*$/, ';') : '') + ov);
+      }
+    }
+    if (dark) svg.setAttribute('data-md2doc-recoloured', ''); else svg.removeAttribute('data-md2doc-recoloured');
+  }
+  function recolourAll(dark) {
+    var svgs = document.querySelectorAll(RECOLOUR);
+    for (var i = 0; i < svgs.length; i++) recolourSvg(svgs[i], dark);
+  }
+  onTheme(recolourAll);
+  // WaveDrom draws again at DOMContentLoaded, load, +250ms and +1000ms; watch
+  // for inserted svgs instead of copying that schedule (same reasoning as
+  // applyDiagramScale's observer in lib/md2doc.js).
+  var content = document.querySelector('.content');
+  if (content && typeof MutationObserver === 'function') {
+    new MutationObserver(function (records) {
+      if (!isDark()) return;
+      for (var r = 0; r < records.length; r++) {
+        var added = records[r].addedNodes;
+        for (var a = 0; a < added.length; a++) {
+          var node = added[a];
+          if (!node || node.nodeType !== 1) continue;
+          if (mermaidShown === 'light' && node.closest && node.closest('.mermaid')) continue;
+          var svgs = node.matches && node.matches(RECOLOUR) ? [node] : (node.querySelectorAll ? node.querySelectorAll(RECOLOUR) : []);
+          for (var k = 0; k < svgs.length; k++) recolourSvg(svgs[k], true);
+        }
+      }
+    }).observe(content, { childList: true, subtree: true });
+  }
+  if (isDark()) recolourAll(true);
+})();

package/lib/theme/tokens.js

@@ -0,0 +1,140 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+// v3.9.0 dark mode: the reader's colour table and the CSS that applies it.
+// Spec: docs/superpowers/specs/2026-10-02-dark-mode-design.md
+//
+// applyReaderTheme() (added in Task 2) hands the reader <style> block to
+// applyThemeTokens(). Every colour literal that has a role below becomes
+// var(--md-<name>), and :root defines each var as that SAME literal, so light
+// rendering is exactly what it was. Dark redefines the vars inside
+// @media screen only, which is what keeps print light.
+
+const THEME_TOKENS = [
+  { name: 'bg', light: ['#ffffff', '#fff'], dark: '#1b1b1d' },
+  { name: 'panel', light: ['#f3f5f7'], dark: '#232325' },
+  { name: 'surface', light: ['#f6f8fa'], dark: '#2a2a2d' },
+  { name: 'surface-2', light: ['#fafbfc'], dark: '#2a2a2d' },
+  { name: 'fg', light: ['#24292e'], dark: '#e3e3e3' },
+  { name: 'strong', light: ['#1f2328'], dark: '#f5f6f7' },
+  { name: 'muted', light: ['#57606a'], dark: '#a3a6ab' },
+  { name: 'muted-2', light: ['#59636e'], dark: '#a3a6ab' },
+  { name: 'subtle', light: ['#6a737d'], dark: '#a3a6ab' },
+  { name: 'rule', light: ['#e1e4e8'], dark: '#38393c' },
+  { name: 'rule-2', light: ['#d8dee4'], dark: '#38393c' },
+  { name: 'rule-3', light: ['#dfe2e5'], dark: '#38393c' },
+  { name: 'rule-strong', light: ['#c9ced4'], dark: '#505257' },
+  { name: 'border', light: ['#d0d7de'], dark: '#46484c' },
+  { name: 'hover', light: ['#e3e8ee'], dark: '#303134' },
+  { name: 'hover-2', light: ['#e8edf2'], dark: '#303134' },
+  { name: 'hover-3', light: ['#eef2f6'], dark: '#303134' },
+  { name: 'accent', light: ['#0969da'], dark: '#6ea8f5' },
+  { name: 'active-fg', light: ['#0550ae'], dark: '#a5c9f8' },
+  { name: 'active-fg-2', light: ['#0b57d0'], dark: '#a5c9f8' },
+  { name: 'active-bg', light: ['#dbe6f3'], dark: '#24364f' },
+  { name: 'hit-bg', light: ['#fff5c2'], dark: '#4d4417' },
+  { name: 'mark-bg', light: ['#fde68a'], dark: '#6e5e14' },
+  { name: 'code', light: ['#b93a0c'], dark: '#ff9f70' },
+  { name: 'accent-soft', light: ['#93c5fd'], dark: '#6ea8f5' },
+  { name: 'error', light: ['#b91c1c'], dark: '#ff8a8a' },
+];
+
+// Literals in reader rules that deliberately stay literal. Measured on real
+// output (mac-tx-core design doc, 2026-10-02): '#000' is the TOC edge-fade
+// mask (alpha only, never painted); '#dbeafe' is the draw.io sheet-bar
+// pressed button, which sits inside the white draw.io plate in dark.
+const KEEP_LITERALS = ['#000', '#dbeafe'];
+
+// Content links: today they use the browser default, which stays in light.
+const LINK_DARK = '#79b0f6';
+
+// Rules whose literals stay literal: the editor's own UI (edit mode is light
+// only) and the lightbox, which is a dark overlay already.
+const SKIP_SELECTOR = /(^|[\s,>+~(])(html\.ed-|\.ed-|\.lightbox)/;
+
+const MERMAID_LIGHT_VARS = {
+  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 MERMAID_DARK_VARS = Object.assign({}, MERMAID_LIGHT_VARS, {
+  primaryColor: '#24364f', primaryBorderColor: '#6ea8f5', primaryTextColor: '#f5f6f7', lineColor: '#a3a6ab',
+  secondaryColor: '#2a2a2d', tertiaryColor: '#1b1b1d', edgeLabelBackground: '#1b1b1d',
+});
+
+const LITERAL_TO_TOKEN = new Map();
+for (const t of THEME_TOKENS) for (const l of t.light) LITERAL_TO_TOKEN.set(l, t.name);
+
+// Line-based on purpose: the reader CSS is one declaration per line or one
+// rule per line, and a line-based pass leaves comment prose (which names
+// colours) alone. `selector` is the text before the last '{' seen.
+function applyThemeTokens(css) {
+  let selector = '';
+  return css.split('\n').map((line) => {
+    const brace = line.indexOf('{');
+    if (brace !== -1) selector = line.slice(0, brace);
+    if (/^\s*(\/\*|\*)/.test(line)) return line;
+    if (SKIP_SELECTOR.test(selector)) return line;
+    return line.replace(/#[0-9a-fA-F]{3,6}\b/g, (m) => {
+      const name = LITERAL_TO_TOKEN.get(m.toLowerCase());
+      return name ? 'var(--md-' + name + ')' : m;
+    });
+  }).join('\n');
+}
+
+function themeCss() {
+  const D = ':root[data-md2doc-theme="dark"]';
+  const light = THEME_TOKENS.map((t) => '--md-' + t.name + ': ' + t.light[0] + ';').join(' ');
+  const dark = THEME_TOKENS.map((t) => '--md-' + t.name + ': ' + t.dark + ';').join(' ');
+  return [
+    '  /* v3.9.0 dark mode (lib/theme/tokens.js). Light values are the literals they replace. */',
+    '  :root { ' + light + ' }',
+    '  @media screen {',
+    '    ' + D + ' { ' + dark + ' color-scheme: dark; }',
+    '    ' + D + ' .content a:not(.heading-anchor), ' + D + ' .content a:not(.heading-anchor):visited { color: ' + LINK_DARK + '; }',
+    '    ' + D + ' .content img { background: #ffffff; border-radius: 4px; box-shadow: 0 0 0 10px #ffffff; }',
+    '    ' + D + ' .content .drawio { background: #ffffff; border-radius: 6px; box-shadow: 0 0 0 10px #ffffff; }',
+    '    ' + D + ' .lightbox-canvas > svg[data-md2doc-recoloured] { background: var(--md-bg); }',
+    '  }',
+    '  .md2doc-theme-toggle { position: fixed; right: 20px; bottom: 20px; z-index: 60; width: 40px; height: 40px;',
+    '    border-radius: 50%; display: grid; place-items: center; padding: 0; font-size: 18px; line-height: 1;',
+    '    cursor: pointer; border: 1px solid var(--md-border); background: var(--md-bg); color: var(--md-strong);',
+    '    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.18); }',
+    '  .md2doc-theme-toggle[hidden] { display: none; }',
+    '  .md2doc-theme-toggle:hover { background: var(--md-hover); }',
+    '  .md2doc-theme-toggle:focus-visible { outline: 2px solid var(--md-accent); outline-offset: 2px; }',
+    '  .mobile-bar .md2doc-theme-toggle { position: static; margin-left: auto; flex: 0 0 auto; width: 36px; height: 36px;',
+    '    box-shadow: none; font-size: 17px; }',
+    '  @media print { .md2doc-theme-toggle { display: none !important; } }',
+  ].join('\n');
+}
+
+
+// Runs before any stylesheet, so a saved dark choice never flashes light.
+const EARLY_SCRIPT = "<script>try{if(localStorage.getItem('md2doc-theme')==='dark')document.documentElement.setAttribute('data-md2doc-theme','dark');}catch(e){}</script>";
+const TOGGLE_HTML = '<button type="button" class="md2doc-theme-toggle" hidden id="md2doc-theme-toggle" aria-label="Light theme (click for dark)" title="Light theme (click for dark)">☀</button>';
+const RUNTIME_JS = fs.readFileSync(path.join(__dirname, 'runtime.js'), 'utf8');
+
+// The reader <style> is the first one after </title>; KaTeX's own <style>
+// comes after it, so "last </style> before </head>" is the wrong anchor here.
+function applyReaderTheme(html) {
+  const titleEnd = html.indexOf('</title>');
+  const start = titleEnd < 0 ? -1 : html.indexOf('<style>', titleEnd);
+  const end = start < 0 ? -1 : html.indexOf('</style>', start);
+  if (end < 0) throw new Error('applyReaderTheme: reader <style> block not found');
+  let out = html.slice(0, start) + applyThemeTokens(html.slice(start, end)) + '\n' + themeCss() + '\n' + html.slice(end);
+  const head = out.indexOf('<head>\n');
+  if (head < 0) throw new Error('applyReaderTheme: <head> not found');
+  out = out.slice(0, head + 7) + EARLY_SCRIPT + '\n' + out.slice(head + 7);
+  // lastIndexOf: inlined diagram libraries carry '</body>' inside strings.
+  const bodyEnd = out.lastIndexOf('</body>');
+  if (bodyEnd < 0) throw new Error('applyReaderTheme: </body> not found');
+  const data = JSON.stringify({ mermaidLight: MERMAID_LIGHT_VARS, mermaidDark: MERMAID_DARK_VARS });
+  return out.slice(0, bodyEnd) + TOGGLE_HTML + '\n<script id="md2doc-theme-data" type="application/json">' + data +
+    '</script>\n<script>\n' + RUNTIME_JS + '\n</script>\n' + out.slice(bodyEnd);
+}
+
+module.exports = {
+  THEME_TOKENS, KEEP_LITERALS, LINK_DARK, MERMAID_LIGHT_VARS, MERMAID_DARK_VARS,
+  applyThemeTokens, themeCss, applyReaderTheme,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "3.8.0",
+  "version": "3.9.1",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, Graphviz, and draw.io support",
   "keywords": [
     "markdown",
@@ -45,7 +45,7 @@
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",
-    "test": "node test/md2doc.test.js && node test/blockmap.test.js && node test/drawio.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/selection.test.js && node test/cell-range.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/table-anchor-recovery.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js && node test/table-width.test.js && node test/toolbar-model.test.js && node test/docsource.test.js && node test/asset.test.js && node test/paste-md.test.js && node test/patchmap.test.js && node test/wave-codec.test.js && node test/wave-draw.test.js && node test/wave-geometry.test.js && node test/wave-store.test.js && node test/wave-rail-clearance.test.js && node test/editor-journey.test.js && node test/detach-census.test.js && node test/editor-arrow-nav.test.js && node test/editor-cell-range.test.js && node test/reader-design.test.js",
+    "test": "node test/md2doc.test.js && node test/blockmap.test.js && node test/drawio.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/selection.test.js && node test/cell-range.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/table-anchor-recovery.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js && node test/table-width.test.js && node test/toolbar-model.test.js && node test/docsource.test.js && node test/asset.test.js && node test/paste-md.test.js && node test/patchmap.test.js && node test/wave-codec.test.js && node test/wave-draw.test.js && node test/wave-geometry.test.js && node test/wave-store.test.js && node test/wave-rail-clearance.test.js && node test/editor-journey.test.js && node test/detach-census.test.js && node test/editor-arrow-nav.test.js && node test/editor-cell-range.test.js && node test/reader-design.test.js && node test/theme.test.js",
     "test:browser": "node test/reader-click.test.js"
   },
   "repository": {