@helping-ai-workflow/md2doc 3.12.1 → 3.13.1

package/lib/md2doc.js

@@ -23,6 +23,8 @@ const path          = require('path');
 const drawio        = require('./drawio.js');
 const { applyReaderTheme } = require('./theme/tokens');
 const { highlightCode } = require('./highlight');
+const waveCodec    = require('./editor/wave-codec.js');
+const waveOverflow = require('./wave-overflow.js');
 
 // How long to let client-side WaveDrom / Mermaid scripts render before we
 // snapshot the DOM (PDF print, or --bake-svg inert-SVG bake).
@@ -183,6 +185,9 @@ function buildKatexStyleTag() {
 // it per-call would grow the registry unboundedly in a long-lived process
 // (the editor server calls renderMarkdown() once per edit).
 let marked, Renderer;
+// v3.13.1 (T9b): set by renderMarkdown() around its synchronous parse — see the
+// blockKatex renderer below. Null at every other time.
+let blockMathText = null;
 try {
   ({ marked, Renderer } = require('marked'));
 
@@ -230,6 +235,14 @@ try {
   // default no-space-adjacency rules keep prose currency ($5 to $10) unrendered.
   const markedKatex = require('marked-katex-extension');
   marked.use(markedKatex({ throwOnError: false }));
+  // v3.13.1 (T9b): a $$ block renders through the extension's own renderer,
+  // which the per-call renderer overrides never reach, so the search index
+  // would miss it. This one hands its TeX to the render in progress, then
+  // returns false so the extension's renderer still draws the formula.
+  marked.use({ extensions: [{ name: 'blockKatex', renderer(token) {
+    if (blockMathText) blockMathText(token.text);
+    return false;
+  } }] });
 } catch (e) {
   console.error('[ERROR] marked not found — install with: npm install marked');
   console.error(e.message);
@@ -333,7 +346,10 @@ function renderEditModeList(listToken, blocks, biRef, out) {
     let inner;
     if (!item.loose && ownTokens.length === 1 && ownTokens[0].type === 'text') {
       // Tight item with a single text token: use static parseInline to get
-      // clean inline HTML without a <p> wrapper.
+      // clean inline HTML without a <p> wrapper. parseInline never reaches the
+      // block renderers, so the item's text is indexed for search here
+      // (v3.13.1 T9b; biRef.indexInline is set by renderMarkdown).
+      if (biRef.indexInline) biRef.indexInline(ownTokens[0].tokens);
       inner = marked.Parser.parseInline(ownTokens[0].tokens);
     } else {
       // Loose item or non-standard own-token shape: use marked.parser, which
@@ -343,7 +359,10 @@ function renderEditModeList(listToken, blocks, biRef, out) {
       // marked pretty-prints a trailing "\n" after the closing tag, which is
       // insignificant to every serializer (list-md.js drops it via isBlankText)
       // but would render as a phantom blank line inside the item.
-      inner = marked.parser(ownTokens).trim();
+      // biRef.parseItem (renderMarkdown) is marked.parser with the search
+      // index told that a text run here is wrapped in a made-up paragraph,
+      // as in a loose item, so each item is indexed once (v3.13.1 T9b).
+      inner = (biRef.parseItem ? biRef.parseItem(ownTokens) : marked.parser(ownTokens)).trim();
     }
     // The receiving half of list-md.js's SETEXT ESCAPE (see
     // escapeSetextHazard() there): an empty list item that is the first child
@@ -730,21 +749,27 @@ async function renderMarkdown(mdText, srcPath, opts = {}) {
     const sections = [];
     let currentSection = null;
 
-    function startSection({ id, depth, text }) {
+    // The search index: one string per section, built from the text the
+    // reader sees, the way the in-text marks read it (highlightFirstOccurrence
+    // in the reader runtime). Both sides must agree, or the results list finds
+    // a phrase the reader cannot mark.
+    function startSection({ id, depth, text, search }) {
       currentSection = {
         id,
         depth,
         title: text,
-        searchTextParts: [text],
+        searchTextParts: [search === undefined ? text : search.replace(/\s+/g, ' ').trim()],
       };
       sections.push(currentSection);
     }
 
+    // Takes plain text (sectionInlineText, code, TeX): no tag stripping here,
+    // so code such as "if (a<b && c>d)" is indexed as written.
     function appendSectionText(value) {
       if (!currentSection || !value) {
         return;
       }
-      const clean = stripHtmlTags(value).replace(/\s+/g, ' ').trim();
+      const clean = String(value).replace(/\s+/g, ' ').trim();
       if (clean) {
         currentSection.searchTextParts.push(clean);
       }
@@ -756,13 +781,37 @@ async function renderMarkdown(mdText, srcPath, opts = {}) {
       }
       for (const cell of cells) {
         if (cell && Array.isArray(cell.tokens)) {
-          appendSectionText(flattenTokenText(cell.tokens));
+          appendSectionText(sectionInlineText(cell.tokens));
         } else if (cell && typeof cell.text === 'string') {
-          appendSectionText(cell.text);
+          appendSectionText(stripHtmlTags(cell.text));
         }
       }
     }
 
+    // v3.13.1 (T9b): inline tokens as the reader sees them, for the search
+    // index. Inline math is its TeX source (the reader runtime reads a formula
+    // from its TeX annotation); a hard break or a literal <br> is a space (the
+    // runtime reads a br element as one); other inline html carries no text;
+    // an image's alt text is not on the page. A text token's text is escaped
+    // by marked, so a tag in it is real markup (the checkbox a loose task item
+    // gets) and is stripped before the entities are decoded.
+    function sectionInlineText(tokens) {
+      if (!Array.isArray(tokens)) {
+        return '';
+      }
+      return tokens
+        .map((item) => {
+          if (item.type === 'br') return ' ';
+          if (item.type === 'html') return /^<br\b/i.test(item.text || '') ? ' ' : '';
+          if (item.type === 'image') return '';
+          if (item.type === 'inlineKatex') return item.text || '';
+          if (item.type === 'codespan') return unescapeHtml(item.text || '');
+          if (item.tokens) return sectionInlineText(item.tokens);
+          return unescapeHtml(stripHtmlTags(String(item.text || '').replace(/<br\b[^>]*>/gi, ' ')));
+        })
+        .join('');
+    }
+
     function buildTocTree(items) {
       const root = [];
       const stack = [{ depth: 0, children: root }];
@@ -976,9 +1025,64 @@ ${itemsHtml}
       return out + '>';
     };
 
+    // R7 甲 (v3.13.1): a block that is nothing but one or more native <svg>
+    // elements gets the class inline-svg, so dark mode can put it on a white
+    // plate like images and draw.io. Decided on the block's own source, not
+    // its tokens: marked lexes '<svg><text>x</text></svg>' on one line as a
+    // paragraph of html,html,text,html,html tokens, and '<svg ...>' alone on
+    // its first line as one block html token. Outside the svg elements only
+    // whitespace may appear, so an svg inside prose is never wrapped. Reader
+    // output only: edit mode keeps its block DOM exactly as it was.
+    // Not covered: an svg in a tight list item or a table cell reaches the
+    // renderer as inline tokens with no block of its own, so it gets no plate.
+    // HTML comments are dropped before any <svg> is looked at: '<!-- <svg> -->'
+    // opens nothing.
+    function noComments(src) { return String(src || '').replace(/<!--[\s\S]*?-->/g, ''); }
+    function isSvgOnly(src) {
+      const s = noComments(src).trim();
+      if (!/^<svg[\s>]/i.test(s) || !/<\/svg>$/i.test(s)) return false;
+      const tag = /<(\/?)svg\b[^>]*?(\/?)>/gi;
+      let depth = 0, last = 0, m;
+      while ((m = tag.exec(s)) !== null) {
+        if (depth === 0 && s.slice(last, m.index).trim()) return false;
+        if (m[1]) depth--; else if (!m[2]) depth++;
+        if (depth < 0) return false;
+        last = tag.lastIndex;
+      }
+      return depth === 0 && !s.slice(last).trim();
+    }
+    // An outer <svg> that a blank line split into several html blocks is still
+    // open while its later blocks render; a <div> there would close it early, so
+    // no html block is wrapped until it closes. Only raw html blocks can keep an
+    // svg open: a paragraph's <p> and </p> end any open svg in the browser's
+    // parser (measured in Chromium and WebKit), so a paragraph always resets the
+    // count, and text in a code span or an svg left unclosed inside a paragraph
+    // never holds later blocks hostage. Counted per block, in document order.
+    let openSvg = 0;
+    function svgNet(src) {
+      const tag = /<(\/?)svg\b[^>]*?(\/?)>/gi;
+      let n = 0, m;
+      const s = noComments(src);
+      while ((m = tag.exec(s)) !== null) { if (m[1]) n--; else if (!m[2]) n++; }
+      return n;
+    }
+    function wrapsSvg(src) {
+      const wrap = openSvg === 0 && isSvgOnly(src);
+      openSvg = Math.max(0, openSvg + svgNet(src));
+      return wrap;
+    }
+    function wrapsSvgParagraph(src) {
+      openSvg = 0;
+      return isSvgOnly(src);
+    }
+
     const baseHtml = renderer.html.bind(renderer);
     renderer.html = function(token) {
-      return inlineImagesInHtmlChunk(baseHtml.apply(this, arguments));
+      const out = inlineImagesInHtmlChunk(baseHtml.apply(this, arguments));
+      if (!opts.editMode && token && token.block && wrapsSvg(token.text)) {
+        return '<div class="inline-svg">' + out.trim() + '</div>\n';
+      }
+      return out;
     };
 
     // Spec §3.12 — a markdown HARD BREAK and a literal '<br>' the source spelled
@@ -1004,6 +1108,7 @@ ${itemsHtml}
       renderer.br = function() { return '<br data-hard-break="1">'; };
     }
 
+    let waveBlockCount = 0;
     renderer.code = function(token) {
       // token is either a string (old API) or {text, lang} object (new API)
       const lang = (typeof token === 'object') ? (token.lang || '') : (arguments[1] || '');
@@ -1011,6 +1116,29 @@ ${itemsHtml}
 
       if (lang === 'wavedrom') {
         usesWaveDrom = true;
+        waveBlockCount++;
+        // CLI-only: the CLI passes its source path as opts.warnWaveOverflow;
+        // library and --edit renders leave it unset and stay silent.
+        // One line per diagram, never one per label (final review M1): the
+        // per-label lines of one diagram each named their own scale, and
+        // following the first ("set to 2") left the next one ("to 4") still
+        // overflowing. The line names the count, the label that needs the
+        // most, and the one scale that fits them all (suggestScale).
+        if (opts.warnWaveOverflow) {
+          try {
+            const parsed = waveCodec.parseSource(code);
+            const list = parsed.ok ? waveOverflow.overflowOf(parsed.doc) : [];
+            if (list.length > 0) {
+              let worst = list[0];
+              for (const o of list) if (o.needScale > worst.needScale) worst = o;
+              const named = '"' + worst.label + '" in ' + worst.name;
+              const what = list.length === 1
+                ? '1 data label is wider than its segment (' + named + ')'
+                : list.length + ' data labels are wider than their segments (worst: ' + named + ')';
+              console.error(`md2doc: ${opts.warnWaveOverflow}: wavedrom #${waveBlockCount}: ${what}; set config.hscale to ${waveOverflow.suggestScale(list)} (estimated)`);
+            }
+          } catch (e) { /* a warning must never break a render */ }
+        }
         return `\n<script type="WaveDrom">\n${code}\n</script>\n`;
       }
       if (lang === 'mermaid') {
@@ -1022,6 +1150,8 @@ ${itemsHtml}
         return `\n<div class="mermaid">\n${escapeHtml(code)}\n</div>\n`;
       }
       if (lang === 'math') {
+        // Indexed as its TeX, like inline and $$ math (T9b).
+        appendSectionText(code);
         // KaTeX renders synchronously to static HTML (class="katex"); no client
         // runtime, no async post-pass. throwOnError:false degrades a bad formula
         // to red error text instead of crashing the whole render.
@@ -1042,7 +1172,9 @@ ${itemsHtml}
       }
       // Default: fenced code. v3.10.0 colours registered languages here, at
       // render time (lib/highlight.js); an unknown or missing language stays
-      // plain escaped text.
+      // plain escaped text. v3.13.1 (T9b): indexed for search as written, so a
+      // name that only a code block holds is found and marked.
+      appendSectionText(code);
       const coloured = highlightCode(code, lang);
       // The info string goes into an attribute: escape it (an info string such
       // as x" onmouseover=… must stay text). Ordinary language names are unchanged.
@@ -1077,21 +1209,54 @@ ${itemsHtml}
         id: headingId,
         text: headingText,
       });
-      startSection({ depth, id: headingId, text: headingText });
+      startSection({ depth, id: headingId, text: headingText, search: sectionInlineText(token.tokens) });
 
       return `<h${depth} id="${headingId}" class="heading-with-anchor" data-reader-heading data-reader-depth="${depth}">${headingHtml}<a class="heading-anchor" href="#${headingId}" aria-label="Link to this section">#</a></h${depth}>\n`;
     };
 
+    // A list item's text is indexed as it renders, in reading order with its
+    // block children: marked's parser hands each of the item's block-level
+    // text tokens (the only text tokens that carry inline .tokens) to
+    // renderer.text. In a loose item the parser then wraps that run of text in
+    // a paragraph it makes up from the HTML it just rendered (a formula as
+    // KaTeX markup); renderer.text arms a one-shot skip for that paragraph.
+    // Real paragraph tokens (in a loose item, those after a nested list) are
+    // indexed by renderer.paragraph as usual.
+    let looseItemText = false;
+    let skipMadeUpParagraph = false;
+    const baseText = renderer.text.bind(renderer);
+    renderer.text = function(token) {
+      if (token && Array.isArray(token.tokens)) {
+        appendSectionText(sectionInlineText(token.tokens));
+        if (looseItemText) skipMadeUpParagraph = true;
+      }
+      return baseText(token);
+    };
     const baseParagraph = renderer.paragraph.bind(renderer);
     renderer.paragraph = function(token) {
-      appendSectionText(flattenTokenText(token.tokens));
+      if (skipMadeUpParagraph) {
+        skipMadeUpParagraph = false;
+      } else {
+        appendSectionText(sectionInlineText(token.tokens));
+      }
+      // R7 甲: see isSvgOnly above renderer.html.
+      if (!opts.editMode && wrapsSvgParagraph(token.raw)) {
+        return baseParagraph(token).replace(/^<p>/, '<p class="inline-svg">');
+      }
       return baseParagraph(token);
     };
 
     const baseListitem = renderer.listitem.bind(renderer);
     renderer.listitem = function(token) {
-      appendSectionText(flattenTokenText(token.tokens));
-      const html = baseListitem(token);
+      // Indexes nothing itself: see renderer.text above.
+      const outerLoose = looseItemText;
+      looseItemText = !!token.loose;
+      let html;
+      try {
+        html = baseListitem(token);
+      } finally {
+        looseItemText = outerLoose;
+      }
       if (!token.task) return html;
       // v3.10.0: a task item drops its bullet and keeps its own text in a span,
       // so a checked item's strike-through stops at its own words — CSS
@@ -1107,8 +1272,14 @@ ${itemsHtml}
 
     const baseBlockquote = renderer.blockquote.bind(renderer);
     renderer.blockquote = function(token) {
-      appendSectionText(flattenTokenText(token.tokens));
-      return baseBlockquote(token);
+      // Its paragraphs index themselves (indexing them here too doubled them).
+      const outerLoose = looseItemText;
+      looseItemText = false;
+      try {
+        return baseBlockquote(token);
+      } finally {
+        looseItemText = outerLoose;
+      }
     };
 
     renderer.table = function(token) {
@@ -1179,6 +1350,8 @@ ${itemsHtml}
         return `<a href="#${escAttr(slug)}">[${escAttr(body)}]</a>`;
       });
 
+    // A $$ block's TeX reaches the index through the blockKatex hook at the
+    // top of the file, set only while this render's synchronous parse runs.
     if (opts.editMode) {
       // Ranges are computed on mdPre. The [[...]] preprocessing above only
       // replaces text within single lines and never adds/removes newlines,
@@ -1198,19 +1371,37 @@ ${itemsHtml}
       // flat list renderer above threads through its own recursion (see
       // liRunStartsHere()).
       const biRef = { v: 0, prevLi: null, types: [] };
-      for (const t of tokens) {
-        if (t.type === 'space') continue;
-        if (t.type === 'list') {
-          parts.push(...renderEditModeList(t, blocks, biRef));
-          continue;
+      // The edit page searches this index too: renderEditModeList indexes each
+      // item through these two, once, in the edit DOM's order (an item's own
+      // block, then its nested lists).
+      biRef.indexInline = (inlineTokens) => appendSectionText(sectionInlineText(inlineTokens));
+      biRef.parseItem = (ownTokens) => {
+        const outerLoose = looseItemText;
+        looseItemText = true;
+        try {
+          return marked.parser(ownTokens);
+        } finally {
+          looseItemText = outerLoose;
         }
-        resetLiRunState(biRef); // §3.8 rule (c): a non-li block ends every run
-        const b = blocks[biRef.v++];
-        const inner = marked.parser([t]);
-        parts.push(
-          `<div class="ed-block" data-block-id="${b.id}" data-block-type="${b.type}">` +
-          inner + '</div>'
-        );
+      };
+      try {
+        blockMathText = appendSectionText;
+        for (const t of tokens) {
+          if (t.type === 'space') continue;
+          if (t.type === 'list') {
+            parts.push(...renderEditModeList(t, blocks, biRef));
+            continue;
+          }
+          resetLiRunState(biRef); // §3.8 rule (c): a non-li block ends every run
+          const b = blocks[biRef.v++];
+          const inner = marked.parser([t]);
+          parts.push(
+            `<div class="ed-block" data-block-id="${b.id}" data-block-type="${b.type}">` +
+            inner + '</div>'
+          );
+        }
+      } finally {
+        blockMathText = null;
       }
       // Development-time alignment guard: the render walk and blockmap.js's
       // pushListItemBlocks must consume blocks[] in lockstep. A mismatch means
@@ -1244,7 +1435,12 @@ ${itemsHtml}
       }
       bodyHtml = parts.join('\n');
     } else {
-      bodyHtml = marked.parse(mdPre);
+      try {
+        blockMathText = appendSectionText;
+        bodyHtml = marked.parse(mdPre);
+      } finally {
+        blockMathText = null;
+      }
     }
     // Both the ```math fence and the $/$$ extension emit class="katex" — a single
     // post-parse scan is the source of truth for conditional CSS injection.
@@ -1260,6 +1456,11 @@ ${itemsHtml}
     ).replace(/</g, '\\u003c');
     if (tocItems.length > 0) {
       const tocTree = buildTocTree(tocItems);
+      // v3.13.1 (R3): two or more H1s kept as the TOC's top level are
+      // chapters; the marker lets CSS set each chapter apart with a rule and
+      // a gap. A flattened single-H1 TOC (its H2s on top) never carries it.
+      const tocRoots = flattenSingleRoot(tocTree);
+      const tocChapters = tocRoots === tocTree && tocTree.filter((n) => n.depth === 1).length >= 2;
       tocHtml = `<aside class="reader-sidebar" data-reader-sidebar>
   <section class="reader-tools">
     <label class="reader-search-label" for="doc-search-input">Search</label>
@@ -1278,7 +1479,7 @@ ${itemsHtml}
     </div>
     <div id="search-results-list"></div>
   </section>
-  <nav class="toc" aria-label="Table of contents" data-reader-toc>
+  <nav class="toc" aria-label="Table of contents" data-reader-toc${tocChapters ? ' data-toc-chapters' : ''}>
     <div class="toc-header">
       <span class="toc-title">Contents</span>
       <div class="toc-header-actions">
@@ -1288,7 +1489,7 @@ ${itemsHtml}
       </div>
       <div class="toc-breadcrumb" data-toc-breadcrumb aria-label="Current location"></div>
     </div>
-    ${renderTocNodes(flattenSingleRoot(tocTree))}
+    ${renderTocNodes(tocRoots)}
   </nav>
 </aside>
 <div class="sidebar-splitter" id="sidebar-splitter" role="separator" aria-orientation="vertical" aria-label="Resize sidebar"></div>`;
@@ -1787,488 +1988,341 @@ ${edUlMarkerCss}${edOlCounterCss}
     position: fixed; inset: 0; z-index: 998; background: rgba(0,0,0,.45);
     display: flex; align-items: center; justify-content: center;
   }
-  /* v3.6.0 Task 13: width cap raised from 1200px to 1920px — MEASURED
-     (createEditorServer, four real viewports): at 1200px the cap itself
-     was the binding constraint at 1280/1600/1920 alike (94vw there is
-     1203/1504/1805px, all above the old 1200px cap), so every screen from a
-     1280 laptop up to a 1920 monitor got the IDENTICAL canvas width — the
-     exact complaint that opened this version ("a bigger monitor buys the
-     user nothing"). 1920px is chosen so 94vw is the actual governor at
-     every one of those four measured sizes (94% of 1920 is 1804.8, still
-     under the new cap) — this number is a ceiling for a screen wider than
-     that, not a value that binds within the measured range. At 800x600,
-     94vw (752px) was already narrower than either cap, so that viewport is
-     unchanged by this. See task-13-report.md for the re-measured
-     toolbar/canvas table. */
+  /* Wave redesign Task 6b (spec section 4.1): one column, top to bottom:
+     title bar, toolbar, the notice card, the stage, the hint bar. The side
+     rail is gone and the stage takes the whole width. The width cap of
+     1920px is v3.6.0 Task 13's: below it, 94vw governs at every measured
+     screen size. position: relative because the toolbar's popovers are
+     placed against the panel. */
   .ed-wave-panel {
-    background: #fff; border-radius: 6px; width: min(1920px, 94vw);
+    position: relative; background: #fff; border-radius: 6px; width: min(1920px, 94vw);
     height: min(760px, 90vh); display: flex; flex-direction: column;
     box-shadow: 0 6px 28px rgba(0,0,0,.35); overflow: hidden;
   }
   .ed-wave-head {
-    display: flex; align-items: center; justify-content: space-between;
-    padding: 8px 12px; border-bottom: 1px solid #e2e2e2; font-weight: bold;
-  }
+    display: flex; align-items: center; gap: 12px;
+    padding: 8px 12px; border-bottom: 1px solid #e2e2e2;
+  }
+  .ed-wave-title { font-weight: bold; }
+  /* The FILE's save state (spec section 4.8), the same two states and
+     colours as the edit toolbar's own status slot. */
+  .ed-wave-save { margin-left: auto; font-size: 12px; color: var(--md-ed-ok); }
+  .ed-wave-save[data-dirty="1"] { color: var(--md-ed-dirty); }
   .ed-wave-close {
-    border: 1px solid #bbb; border-radius: 4px; background: #f6f6f6;
-    padding: 3px 12px; cursor: pointer;
-  }
-  /* Which way out keeps the work and which throws it away. Escape is a modal's
-     universal close key and here it discards a whole session, so the header
-     says so next to the button that does not. Normal weight against the bar's
-     bold heading: it is a caption, not a warning the user has to clear. */
-  .ed-wave-escape-hint {
-    margin-left: auto; margin-right: 12px; font-weight: normal;
-    font-size: 11px; color: #7a4b00;
+    border: 0; border-radius: 4px; background: transparent; color: #555;
+    width: 28px; height: 28px; font-size: 15px; line-height: 1; cursor: pointer;
   }
+  .ed-wave-close:hover { background: var(--md-ed-hover); }
+  /* Spec section 4.2: one row; groups are divided by a thin rule and 完成
+     sits on the right. Buttons are quiet until hovered or switched on. */
   .ed-wave-toolbar {
-    display: flex; flex-wrap: wrap; gap: 12px; align-items: center;
-    padding: 8px 12px; border-bottom: 1px solid #e2e2e2; background: #fafafa;
-  }
-  /* v3.6.0 Task 12: the eight captioned sections themselves. .ed-wave-tools
-     is the row that holds them (the SAME element as .ed-wave-toolbar
-     above -- that class still owns the bar's padding/border/background,
-     this one owns only the group row's own gap). Each .ed-wave-tool-group
-     is a bordered chip so eight adjacent sections read as eight things, not
-     one longer wall of buttons; the caption sits to its buttons' LEFT (see
-     wave-panels.js's toolGroup() for why not above). */
-  .ed-wave-tools { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; }
-  .ed-wave-tool-group {
-    display: flex; align-items: center; gap: 4px;
-    padding: 2px 6px; border: 1px solid #ececec; border-radius: 6px;
-  }
-  .ed-wave-tool-caption {
-    font-size: 10px; color: #8a8a8a; letter-spacing: .5px;
-    white-space: nowrap; margin-right: 2px;
-  }
-  .ed-wave-brushes, .ed-wave-meta {
     display: flex; flex-wrap: wrap; gap: 4px; align-items: center;
+    padding: 6px 12px; border-bottom: 1px solid #e2e2e2; background: #fafafa;
   }
-  /* v3.6.0 Task 10: widened from a 28x28 bare-character square to a small
-     column (glyph on top, the character kept as a caption underneath) so
-     the 22-brush palette says what each brush paints instead of relying on
-     the letter alone -- nine of those 22 (P, N, u, d, h, l, 2, 6-9) have no
-     obvious on-canvas picture from the character by itself. */
-  /* '.ed-wave-brushes .ed-wave-brush', not the bare class: '.ed-wave-toolbar
-     button' below outranks a single class on specificity (class+type beats
-     class alone) and would otherwise win the padding fight and squeeze the
-     24px-wide icon into a content box narrower than it is. */
-  .ed-wave-brushes .ed-wave-brush {
-    width: 34px; height: 40px; border: 1px solid #c4c4c4; border-radius: 4px;
-    background: #fff; font-family: monospace; cursor: pointer;
-    display: flex; flex-direction: column; align-items: center;
-    justify-content: center; gap: 1px; padding: 2px 0; box-sizing: border-box;
-  }
-  .ed-wave-brush.is-on { background: #1a73e8; color: #fff; border-color: #1a73e8; }
-  .ed-wave-brush-char { font-size: 11px; line-height: 1; }
-  /* The glyph itself. Its shapes are drawn by wave-draw.js's levelIcon,
-     which reuses renderCanvas's own drawing functions (bandOf, brickPath,
-     the bus/clock/gap helpers) -- never a second hand-drawn set, so a
-     change to how a brush paints on the real canvas cannot leave the
-     toolbar showing the old picture. */
-  .ed-wave-level-icon { display: block; overflow: visible; }
   .ed-wave-toolbar button {
-    border: 1px solid #c4c4c4; border-radius: 4px; background: #fff;
-    padding: 3px 8px; font-size: 12px; cursor: pointer;
-  }
-  .ed-wave-toolbar button:disabled { opacity: .45; cursor: default; }
-  /* v3.5.0 Task 7: the 關聯線 arm button, armed or mid-drag. Same on/off
-     treatment as .ed-wave-brush.is-on above — a picked tool reads the same
-     way whichever toolbar it lives in. */
-  .ed-wave-edge-arm.is-on { background: #1a73e8; color: #fff; border-color: #1a73e8; }
-  /* v3.6.0 Task 13: the fixed 110px input width that used to live here moved
-     into .ed-wave-section-body input below — every .ed-wave-metafield
-     now lives inside a right-hand panel (關聯線/文件/Lane), not the toolbar,
-     and a panel field should fill the ~340px column rather than sit at a
-     width chosen for the old horizontal toolbar row. */
-  .ed-wave-metafield { display: flex; align-items: center; gap: 4px; font-size: 12px; }
-  /* v3.6.0 Task 13: the 關聯線 panel's own content, stacked vertically now
-     that it lives in a narrow side column rather than a wide flex-wrap
-     toolbar row (the old 'flex: 1 1 100%' here was what made it claim a
-     full row of THAT row; a panel body has no siblings to share a row
-     with). */
-  .ed-wave-edgebar { display: flex; flex-direction: column; gap: 4px; }
-  /* The "this drawing is not showing you everything" notice. period / phase /
-     config.hscale all change what the ENGINE paints and none of them is
-     modelled by the hand drawing, so a document carrying one says so instead
-     of drawing a confident wrong picture. Full row, so it cannot be mistaken
-     for another toolbar control. */
-  .ed-wave-unmodelled {
-    flex: 1 1 100%; font-size: 12px; color: #7a4b00; background: #fff6e0;
-    border: 1px solid #e8c987; border-radius: 4px; padding: 4px 8px;
-  }
-  /* The stronger of the two notices: not "this drawing is incomplete" but
-     "this block has nothing this editor can edit" (a reg: / assign: block).
-     Same shape as its neighbour so the two read as one family, one step
-     louder because the information gap is bigger. */
-  .ed-wave-nolanes { color: #7a1f00; background: #ffe9e0; border-color: #e8a987; }
-  /* v3.6.0 Task 13 fix round 1 (Critical 2): position: relative added.
-     .ed-wave-side[data-expanded] below is position: absolute, and neither
-     .ed-wave-panel nor (until this line) this element had a position of
-     their own — so its containing block was .ed-wave-overlay
-     (position: fixed; inset: 0), the WHOLE viewport, not the dialog.
-     .ed-wave-panel's own overflow: hidden did not clip it either: clipping
-     follows the containing-block chain, not DOM nesting, so the rail
-     rendered against viewport corners at a narrow window and covered
-     .ed-wave-head's 關閉 button — the only discoverable way to close the
-     dialog (a hit-test at 關閉's own rectangle returned the edge panel's
-     delete button instead; Escape still worked but was not discoverable).
-     Anchoring the rail to THIS element rather than to .ed-wave-panel itself
-     is deliberate, not incidental: .ed-wave-body sits below .ed-wave-head
-     and above .ed-wave-status, so top: 0 / bottom: 0 on the rail now lands
-     at body's own top/bottom — never over the header (關閉) or the status
-     line — without this rule having to know either one's height. */
-  .ed-wave-body { display: flex; flex: 1 1 auto; min-height: 0; position: relative; }
-  /* v3.6.0 Task 13: the old comment here hand-computed the canvas's leftover
-     width from the (now gone) .ed-wave-preview column's own flex-basis;
-     that arithmetic no longer applies — the third column is .ed-wave-side
-     below, which collapses to a 28px rail under 1100px specifically so the
-     canvas is not squeezed the way a fixed 160px minimum used to squeeze it
-     at 800x600 (MEASURED before this task: canvas width there was only
-     282px). Re-measured after this task at four real viewports; see
-     task-13-report.md rather than a formula here — a number derived by hand
-     drifts the moment any sibling column's own width changes, which is
-     exactly what this task did. */
-  .ed-wave-lanes {
-    flex: 0 0 200px; border-right: 1px solid #e2e2e2; overflow: auto;
-    padding: 8px 0 8px 0;
-  }
-  /* The rows are absolutely positioned at index * laneHeight so they line up
-     with the drawing beside them cell for cell. A group title is NOT a row —
-     measured against the pinned engine in Task 2 — so it is drawn as a label in
-     the rail spanning its lanes' rows instead, which is the shape the engine
-     itself gives it (horizontal space in the name column, no vertical space). */
-  .ed-wave-lane-rows { position: relative; }
-  /* v3.6.0 Task 14: a row is a drag handle, a name field and (on a {}
-     spacer) a badge. It used to be six buttons plus the field, and the six
-     did not fit: flexed into what was left of 200px the field measured
-     45px on the most crowded row, and a browser given a 24px box and a
-     three-character Chinese caption lays that caption out VERTICALLY — the
-     editor shipped columns of stacked glyphs where labels were meant.
-     Those six are toolbar buttons now (the 訊號 / 群組 sections), acting
-     on the one selection. */
-  .ed-wave-lane-row {
-    position: absolute; left: 0; right: 0; display: flex; align-items: center;
-    gap: 6px; padding-right: 6px; box-sizing: border-box;
-  }
-  .ed-wave-lane-row.is-selected { background: #eaf2fe; }
-  .ed-wave-lane-handle {
-    flex: 0 0 auto; cursor: move; color: #aaa; user-select: none; font-size: 13px;
-  }
-  .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
-     wave fixture): rail 201px, handle 9.5px, badge 36px, and the field comes
-     out 178.5px ungrouped, 162.5px one group deep, 136.5px on the {} spacer
-     row that also carries the badge — writing-mode horizontal-tb on all six.
-     So 120 is slack at every depth this fixture reaches, NOT a computed
-     exact fit. Deeper nesting spends 16px a level and would eventually hit
-     the floor; there the field stops shrinking and .ed-wave-lanes scrolls,
-     which is the trade this rule chooses on purpose. */
-  .ed-wave-lane-name {
-    flex: 1 1 auto; min-width: 120px; font-size: 12px; padding: 2px 4px;
-  }
-  .ed-wave-lane-badge { flex: 0 0 auto; font-size: 10px; color: #888; }
-  .ed-wave-group, .ed-wave-group-input {
-    position: absolute; width: 14px; padding: 0; font-size: 11px;
-    writing-mode: vertical-rl; text-orientation: mixed; overflow: hidden;
-    border: 1px solid #d8d8d8; border-radius: 3px; background: #f2f2f2;
-    color: #555; cursor: pointer; box-sizing: border-box;
-  }
-  .ed-wave-group-input { width: 16px; height: 90px; cursor: text; }
-  /* position: relative so the data-label field below (v3.5.0 Task 11) has
-     an offsetParent to measure from: wave-ui.js reads canvas.offsetLeft /
-     offsetTop against THIS element, not a hard-coded copy of the padding
-     number just below, so the two cannot drift apart if that padding ever
-     changes. */
-  .ed-wave-canvas-wrap { flex: 1 1 auto; overflow: auto; padding: 8px; position: relative; }
-  .ed-wave-canvas { display: block; }
-  /* v3.5.0 Task 11: the bus data-label field, positioned by wave-ui.js's
-     openDataEdit() from geometry.cellRect() — left/top/width/height are all
-     set inline per cell, so only the visual skin lives here. Sized to sit
-     exactly over the box it labels, text centred to match .ed-wave-buslabel
-     beside it in the drawing underneath, box-sizing so the border does not
-     push the field past the cell it is meant to cover. */
-  .ed-wave-data-input {
-    position: absolute; z-index: 1; box-sizing: border-box; text-align: center;
-    font-size: 11px; padding: 0 2px; border: 1px solid #1a73e8; border-radius: 2px;
-    background: #fff; color: #222;
-  }
-  .ed-wave-grid { stroke: #ececec; stroke-width: 1; }
-  .ed-wave-line, .ed-wave-edge { stroke: #111; stroke-width: 2; fill: none; }
-  /* v3.6.0 Task 10: the toolbar glyph's plain-level backbone (0/1/h/l/z/u/d
-     only -- bus/clock/x/gap glyphs draw their own shape with their own
-     fixed canvas colour instead, further down). Declared after the rule
-     above on purpose: both are single-class selectors, so source order is
-     what lets currentColor win over the fixed #111 for this one case,
-     turning the icon white together with the rest of the button's text
-     under .ed-wave-brush.is-on. */
+    border: 1px solid transparent; border-radius: 4px; background: transparent;
+    color: #333; padding: 4px 8px; font-size: 13px; min-height: 32px; cursor: pointer;
+  }
+  .ed-wave-toolbar button:hover { background: var(--md-ed-hover); }
+  .ed-wave-toolbar button:disabled { opacity: .45; cursor: default; background: transparent; }
+  .ed-wave-sep { width: 1px; align-self: stretch; margin: 4px 4px; background: #e2e2e2; }
+  .ed-wave-toolbar .ed-wave-done {
+    margin-left: auto; background: #1a73e8; color: #fff; border-color: #1a73e8; padding: 4px 14px;
+  }
+  .ed-wave-toolbar .ed-wave-done:hover { background: #1a73e8; }
+  /* A brush: the level's glyph with its keyboard character in the lower
+     right corner (spec section 4.2). The glyph is wave-draw.js levelIcon,
+     built from the same brick helpers that model the engine's bricks. The
+     selector names the button type so it outranks the generic toolbar
+     button rule above. */
+  button.ed-wave-brush {
+    position: relative; width: 38px; height: 34px; padding: 2px; box-sizing: border-box;
+    border: 1px solid #c4c4c4; border-radius: 4px; background: #fff; font-family: monospace;
+    display: inline-flex; align-items: center; justify-content: center; cursor: pointer;
+  }
+  .ed-wave-brush-char {
+    position: absolute; right: 2px; bottom: 1px; font-size: 9px; line-height: 1; color: #555;
+  }
+  .ed-wave-toolbar button.ed-wave-brush.is-on, .ed-wave-pop button.ed-wave-brush.is-on,
+  .ed-wave-toolbar .ed-wave-brush-more.is-on, .ed-wave-toolbar .ed-wave-edge-arm.is-on {
+    background: #1a73e8; color: #fff; border-color: #1a73e8;
+  }
+  .ed-wave-brush.is-on .ed-wave-brush-char { color: #fff; }
+  .ed-wave-level-icon { display: block; overflow: visible; }
+  /* The glyph's shapes: the plain-level backbone follows the button's text
+     colour (so a picked brush turns white with its caption); bus, x, clock
+     and gap glyphs carry their own canvas colours. */
+  .ed-wave-line { stroke: #111; stroke-width: 2; fill: none; }
   .ed-wave-level-icon-path { stroke: currentColor; }
   .ed-wave-weak { stroke-dasharray: 4 3; }
-  /* v3.5.0 Task 10: the P/N explicit-edge arrowhead — see wave-ui.js's
-     drawLane isClock branch for the measurement behind its shape and
-     placement. Filled, no stroke, matching the line colour above. */
   .ed-wave-clock-arrow { fill: #111; stroke: none; }
   .ed-wave-x { fill: #d9d9d9; stroke: #111; stroke-width: 2; }
   .ed-wave-bus { fill: #f5e9c8; stroke: #111; stroke-width: 2; }
   .ed-wave-bus-3 { fill: #d8ead3; }
   .ed-wave-bus-4 { fill: #d6e4f7; }
   .ed-wave-bus-5 { fill: #f7d6e4; }
-  /* v3.5.0 Task 11 fix round 2: this text, not the box under it, is the
-     click target that opens the data-label field (wave-ui.js's onCanvasDown
-     gates on ev.target.classList.contains('ed-wave-buslabel') — pressing
-     anywhere else in the bus box still paints). pointer-events:
-     visiblePainted is the SVG initial value already, so this changes
-     nothing on its own; it is written out explicitly because that default
-     is now load-bearing for a real gesture, not incidental — a future
-     blanket pointer-events: none added upstream of this rule would
-     silently make the label unclickable again, and this line is what a
-     reviewer would have to notice and remove. */
-  .ed-wave-buslabel { font-size: 11px; fill: #222; pointer-events: visiblePainted; cursor: text; }
-  /* v3.5.0 Task 11 fix round 3: the hit target for an UNLABELLED bus run —
-     drawLane draws this circle in place of the text when the run has no
-     label, sharing the ed-wave-buslabel class above (same pointer-events,
-     same cursor: text) so onCanvasDown's hit test needed no change. Kept
-     visually quiet on purpose: dim and small, so a diagram full of
-     unlabelled buses reads as buses first and marks second, not as a field
-     of dots. Geometry (position, radius) is inline per cell, sized against
-     that cell's own box in drawLane so it always stays a small fraction of
-     it — this rule is skin only. */
-  .ed-wave-buslabel-empty { fill: #666; opacity: .35; }
-  /* v3.5.0 Task 11 fix round 4: this rect's job is to SHOW what cycle range
-     is selected, never to be pressed. pointer-events: none, so it can never
-     swallow a press meant for whatever it happens to be sitting over —
-     reviewer-measured, a bus label whose run is one cycle wide can sit
-     right up against this rect's own right edge (stroke included), and
-     without this a second press on that same label landed on the
-     selection's stroke instead of the label text underneath it, and the
-     data-label field never opened. Same principle as .ed-wave-cursor two
-     rules below, applied to the OTHER highlight this drawing draws. */
-  .ed-wave-selection {
-    fill: rgba(26,115,232,.18); stroke: #1a73e8; stroke-width: 1;
-    pointer-events: none;
-  }
-  /* The KEYBOARD's own cell, and deliberately not the same mark as the
-     selection: the selection is the RANGE a cycle operation acts on, the
-     cursor is the ONE cell the next keystroke paints, and after Shift+left /
-     right both are on screen at once. pointer-events: none so the rect can
-     never swallow the press the drag underneath it is made of. */
-  .ed-wave-cursor {
-    fill: none; stroke: #d93025; stroke-width: 2; pointer-events: none;
-  }
-  /* The drawing is in the Tab cycle, so it has to SAY when it holds the
-     keyboard: a cell cursor alone leaves a user who just Tabbed onto it with
-     nothing that distinguishes "the drawing has the keyboard" from "the
-     drawing is where I left a cursor before I walked away". */
+  .ed-wave-gap { stroke: #111; stroke-width: 2; fill: none; }
+  /* The one popover the toolbar has open at a time (wave-ui.js places it
+     under its button): 更多's grouped brush grid, the 訊號 and 匯出 menus. */
+  .ed-wave-pop {
+    position: absolute; z-index: 4; background: #fff; border: 1px solid #e2e2e2;
+    border-radius: 6px; box-shadow: 0 4px 16px var(--md-ed-shadow); padding: 6px;
+  }
+  .ed-wave-menu { display: flex; flex-direction: column; min-width: 140px; }
+  .ed-wave-menu-item {
+    border: 0; background: transparent; color: #333; text-align: left;
+    padding: 6px 10px; font-size: 13px; border-radius: 4px; cursor: pointer;
+  }
+  .ed-wave-menu-item:hover, .ed-wave-menu-item:focus { background: var(--md-ed-hover); }
+  /* Task 8: a menu item says the key its action also has (the grip menu's
+     F2, Ctrl+D, Alt+arrows, Del) on its right; 刪除 is red. */
+  .ed-wave-menu-item { display: flex; align-items: center; gap: 16px; }
+  .ed-wave-menu-label { flex: 1 1 auto; }
+  .ed-wave-menu-key { flex: 0 0 auto; font-size: 11px; color: #8a8a8a; }
+  .ed-wave-menu-item.is-danger { color: var(--md-ed-err); }
+  /* Task 8: the grip menu's 週期與相位 panel, period and phase of one lane. */
+  .ed-wave-period-pop { display: flex; flex-direction: column; gap: 6px; }
+  .ed-wave-period-row { display: flex; align-items: center; gap: 8px; font-size: 12px; color: #333; }
+  .ed-wave-period-cap { flex: 0 0 84px; }
+  .ed-wave-period-input {
+    width: 72px; box-sizing: border-box; padding: 3px 6px; font-size: 12px;
+    border: 1px solid #e2e2e2; border-radius: 4px; background: #fff; color: #222;
+  }
+  /* Task 10 (spec section 4.6): the settings popover, the whole diagram.
+     Title and cycle width on top, the overflow card under them, the rulers
+     and the foot title folded under the advanced toggle. */
+  .ed-wave-settings-pop { display: flex; flex-direction: column; gap: 6px; width: 260px; }
+  .ed-wave-set-cap { font-size: 11px; color: #8a8a8a; margin-top: 2px; }
+  .ed-wave-set-row { display: flex; align-items: center; gap: 8px; font-size: 12px; color: #333; }
+  .ed-wave-set-label { flex: 0 0 44px; }
+  .ed-wave-set-input {
+    flex: 1 1 auto; min-width: 0; box-sizing: border-box; padding: 3px 6px; font-size: 12px;
+    font-family: inherit; border: 1px solid #e2e2e2; border-radius: 4px; background: #fff; color: #222;
+  }
+  textarea.ed-wave-set-input { resize: vertical; }
+  .ed-wave-set-scales { display: flex; gap: 4px; }
+  .ed-wave-set-scales button, .ed-wave-set-advanced, .ed-wave-set-fix {
+    border: 1px solid #e2e2e2; border-radius: 4px; background: #fff; color: #333;
+    padding: 3px 10px; font-size: 12px; cursor: pointer;
+  }
+  .ed-wave-set-scales button:hover, .ed-wave-set-advanced:hover, .ed-wave-set-fix:hover { background: var(--md-ed-hover); }
+  .ed-wave-set-scales button[aria-pressed="true"] { background: #1a73e8; color: #fff; border-color: #1a73e8; }
+  .ed-wave-set-advanced { align-self: flex-start; }
+  .ed-wave-set-advanced::after { content: " ⌄"; }
+  .ed-wave-set-advanced[aria-expanded="true"]::after { content: " ⌃"; }
+  .ed-wave-set-adv { display: flex; flex-direction: column; gap: 6px; }
+  .ed-wave-set-adv[hidden] { display: none; }
+  .ed-wave-set-overflow {
+    display: flex; flex-direction: column; align-items: flex-start; gap: 6px; padding: 6px 8px;
+    border: 1px dashed var(--md-ed-dirty); border-radius: 4px; font-size: 12px; color: #333;
+  }
+  .ed-wave-set-overflow[hidden] { display: none; }
+  .ed-wave-set-fix { color: var(--md-ed-dirty); border-color: var(--md-ed-dirty); }
+  /* The export menu's last line: what every export looks like. */
+  .ed-wave-export-note {
+    border-top: 1px solid #e2e2e2; margin-top: 4px; padding: 6px 10px 2px; font-size: 11px; color: #8a8a8a;
+  }
+  /* The chip beside a label wider than its segment; one press widens the
+     cycles. Above the layer, so a press on it never paints. */
+  .ed-wave-overflow-chip {
+    position: absolute; z-index: 2; white-space: nowrap; padding: 1px 6px; font-size: 11px;
+    line-height: 14px; border: 1px solid var(--md-ed-dirty); border-radius: 8px;
+    background: var(--md-ed-surface); color: var(--md-ed-dirty); cursor: pointer;
+  }
+  .ed-wave-overflow-chip[hidden] { display: none; }
+  .ed-wave-brush-grid { display: flex; flex-direction: column; gap: 6px; }
+  .ed-wave-brush-group { display: flex; align-items: center; gap: 8px; }
+  .ed-wave-brush-group-title { flex: 0 0 32px; font-size: 11px; color: #8a8a8a; }
+  .ed-wave-brushes { display: flex; flex-wrap: wrap; gap: 4px; }
+  /* Spec section 4.9: what the editor cannot place, right under the
+     toolbar, in neutral colours, and it can be folded away. */
+  .ed-wave-notice {
+    display: flex; align-items: flex-start; gap: 8px; padding: 6px 12px;
+    border-bottom: 1px solid #e2e2e2; background: #fafafa; color: #555; font-size: 12px;
+  }
+  .ed-wave-notice[hidden] { display: none; }
+  .ed-wave-notice-text { flex: 1 1 auto; }
+  .ed-wave-notice[data-folded] .ed-wave-notice-text {
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  }
+  .ed-wave-notice-fold {
+    flex: 0 0 auto; border: 0; background: transparent; color: #1a73e8;
+    font-size: 12px; cursor: pointer; padding: 0 4px;
+  }
+  /* The stage: the canvas's scroll container, the dialog's whole width.
+     position: relative so the data-label field (wave-ui.js openDataEdit)
+     is placed in its scrolled content box. */
+  .ed-wave-stage {
+    flex: 1 1 auto; min-height: 0; overflow: auto; padding: 8px; position: relative;
+  }
+  /* The engine's svg and the interaction layer share this box. The top
+     padding is the room for the layer's cycle ruler, which sits above the
+     engine's drawing (wave-ui.js RULER_GAP is the baseline's distance). */
+  .ed-wave-canvas-host { position: relative; display: inline-block; padding-top: 20px; }
+  .ed-wave-canvas-error { color: #b00020; padding: 8px; }
+  .ed-wave-canvas { display: block; }
+  /* The drawing is in the Tab cycle, so it has to say when it holds the
+     keyboard. */
   .ed-wave-canvas:focus { outline: 2px solid #1a73e8; outline-offset: 2px; }
-  /* The discontinuity marker. The engine draws one gap <use> per pipe
-     character; drawing none left the two pictures disagreeing on a lane whose
-     levels agreed exactly. v3.5.0 Task 11 fix round 4 audit: drawLane's own
-     comment already calls this "last so it sits over the trace it
-     interrupts" — purely decorative, drawn on top purely to be seen, the
-     exact shape of thing that swallowed a press meant for the bus label
-     underneath it (see .ed-wave-selection above). A gap cycle inside a bus
-     run can land at that run's own label position, so pointer-events: none
-     here too, on the same principle, not because a concrete collision was
-     reproduced. */
-  .ed-wave-gap { stroke: #111; stroke-width: 2; fill: none; pointer-events: none; }
-  /* v3.5.0 Task 6: edge: relationship lines, drawn by wave-ui.js's
-     renderEdges() after every lane. Named .ed-wave-edge-* (with a hyphen)
-     rather than .ed-wave-edge, which is already the brick-to-brick
-     transition tick inside ONE lane (two rules above) — a different mark
-     with a different meaning, and CSS class matching is exact-token so the
-     two never collide, but the names are kept visually distinct too.
-     Colours match the engine's own arc-shape.js style string
-     (stroke:#0041c4) so a line drawn here and the same line in the
-     WaveDrom preview beside it read as the same colour. */
-  .ed-wave-edge-path { stroke: #0041c4; stroke-width: 1; fill: none; }
-  .ed-wave-edge-path.is-on { stroke: #1a73e8; stroke-width: 2; }
-  /* v3.5.0 Task 8: the edge an in-flight endpoint drag is dragging, drawn at
-     its own ACTUAL (still-committed) position — the document does not
-     change until the drop — but faded so it reads as "not where this will
-     end up" once wave-ui.js's own dashed .ed-wave-edge-pending preview line
-     (same mechanism Task 7's not-yet-written edge already uses) is standing
-     next to it. Combines with .is-on: the dragged edge is always the
-     selected one (renderEdges()'s own comment), so both classes are present
-     together and this only lowers opacity on top of that colour. */
-  .ed-wave-edge-path.is-drag-source { opacity: .35; }
-  /* The invisible, wide-stroke click target layered over each visible path
-     (see renderEdges()'s own comment) — pointer-events: stroke is what makes
-     a transparent stroke hit-testable at all, since a stroke that paints
-     nothing is not visiblePainted by the SVG default. */
-  .ed-wave-edge-hit { stroke: transparent; stroke-width: 10; fill: none; pointer-events: stroke; }
-  /* v3.5.0 Task 11 fix round 4 audit, closed in round 5: this text (drawn
-     by renderEdges, AFTER .ed-wave-edge-hit) is the same shape of hazard as
-     .ed-wave-selection and .ed-wave-gap above — purely decorative, sits on
-     top of the fat invisible click target a press aimed at SELECTING the
-     edge is meant to land on. Round 4 found this but could not apply
-     pointer-events: none to the bare class: ed-wave-edge-label is not this
-     text's own class alone — wave-ui.js's sidebar edgeLabelInput (the real,
-     keyboard-and-mouse text field for editing an edge's label) uses the
-     IDENTICAL class name, and a blanket rule would have also landed on
-     that input field and blocked clicking into it with the mouse.
-     Round 5's fix: scope the SELECTOR by element instead of renaming
-     anything. text.ed-wave-edge-label only ever matches the SVG <text>
-     wave-ui.js draws on the canvas — the sidebar control is an <input>, a
-     different element entirely, and keeps its own default pointer-events
-     untouched no matter what class it shares. */
-  text.ed-wave-edge-label { pointer-events: none; }
-  .ed-wave-edge-label { font-size: 11px; fill: #333; }
-  /* v3.6.0 Task 8: the canvas's own name column — a mirror of the rail's
-     .ed-wave-lane-name / .ed-wave-group (see the comment above
-     .ed-wave-lane-rows). Unlike .ed-wave-edge-label these two class names
-     are not shared with any non-SVG control, so pointer-events: none goes
-     straight on the class rather than needing the element-scoped selector
-     that rule uses. MEASURED (task-8-report.md): the longest lane name in
-     this repo's fixtures is 12 chars ("he said \"hi\""), which at 11px in
-     both the app's default sans-serif and the worst case (monospace)
-     measures well under the 110px a top-level name has to fit in
-     (nameColWidth 120 - NAME_GAP 10), so SIZES.nameColWidth stays 120. */
-  .ed-wave-lane-label, .ed-wave-group-label { pointer-events: none; }
-  .ed-wave-lane-label { font-size: 11px; fill: #333; }
-  .ed-wave-group-label {
-    font-size: 11px; fill: #555; writing-mode: vertical-rl; text-orientation: mixed;
-  }
-  /* v3.6.0 Task 9: the cycle ruler and the head/foot bands — see
-     wave-draw.js's drawRuler()/drawBand() comment for the geometry (tick on
-     boundaries, tock at centres, both filtered by every) and why this is
-     read-only with respect to the document. Purely decorative like the name
-     column above it, so pointer-events: none on the same principle. The
-     ruler's own fill matches the pinned engine's own muted class (fill
-     #aaa, node_modules/wavedrom's waveSkin CSS) so a tick/tock painted here
-     reads the same shade as the identical mark in the WaveDrom preview
-     beside it; the head/foot titles use the darker ed-wave-lane-label shade
-     instead, matching the engine's own plain black fill for head.text /
-     foot.text closely enough at this scale without introducing a third
-     grey. */
-  .ed-wave-ruler-tick, .ed-wave-ruler-tock, .ed-wave-head-text, .ed-wave-foot-text {
-    pointer-events: none;
+  /* The interaction layer's marks (wave-draw.js createLayer). None of them
+     takes a press: the layer svg itself does, and the pointer is resolved
+     to a cell by geometry. The exceptions are a transition dot, which takes
+     it through its wider transparent ring, and the edges' hit twins below. */
+  .ed-wave-ruler-num, .ed-wave-ruler-plus, .ed-wave-row-hover, .ed-wave-hover-col,
+  .ed-wave-selection, .ed-wave-cursor, .ed-wave-dot-mark, .ed-wave-pending,
+  .ed-wave-edge-sel, .ed-wave-edge-end, .ed-wave-overflow, .ed-wave-drop-line { pointer-events: none; }
+  /* Task 8: where a lane dragged by its grip will land. */
+  .ed-wave-drop-line { stroke: #1a73e8; stroke-width: 2; }
+  .ed-wave-ruler-num { font-size: 11px; fill: #aaa; }
+  .ed-wave-ruler-num.is-on { fill: #1a73e8; font-weight: bold; }
+  .ed-wave-ruler-plus-glyph { font-size: 14px; font-weight: bold; fill: #1a73e8; }
+  /* Task 7: the ruler's plus inserts a cycle where it stands, so its ring
+     (wave-draw.js createLayer) is the one ruler mark that takes a press. */
+  .ed-wave-ruler-plus-hit { pointer-events: all; cursor: pointer; }
+  .ed-wave-row-hover, .ed-wave-hover-col { fill: var(--md-ed-sel); }
+  .ed-wave-selection { fill: rgba(26,115,232,.18); stroke: #1a73e8; stroke-width: 1; }
+  /* The keyboard's own cell, deliberately not the selection's mark: the
+     selection is the range an operation acts on, the cursor the one cell
+     the next keystroke paints, and both can be on screen at once. */
+  .ed-wave-cursor { fill: none; stroke: #d93025; stroke-width: 2; }
+  .ed-wave-dot { cursor: crosshair; }
+  .ed-wave-dot-hit { pointer-events: all; }
+  .ed-wave-dot-mark { fill: #fff; stroke: #1a73e8; stroke-width: 1.5; }
+  .ed-wave-dot.is-hot .ed-wave-dot-mark { fill: #1a73e8; stroke: #0041c4; }
+  .ed-wave-pending { stroke: #1a73e8; stroke-width: 2; stroke-dasharray: 5 4; fill: none; }
+  .ed-wave-edge-sel { stroke: #1a73e8; stroke-width: 2; fill: none; }
+  .ed-wave-edge-end { fill: #1a73e8; stroke: #fff; stroke-width: 1.5; }
+  .ed-wave-overflow { fill: none; stroke: var(--md-ed-dirty); stroke-width: 1.5; stroke-dasharray: 3 2; }
+  /* The bus data-label field, placed over its cell by openDataEdit; only
+     the skin lives here. */
+  .ed-wave-data-input {
+    position: absolute; z-index: 1; box-sizing: border-box; text-align: center;
+    font-size: 11px; padding: 0 2px; border: 1px solid #1a73e8; border-radius: 2px;
+    background: #fff; color: #222;
   }
-  .ed-wave-ruler-tick, .ed-wave-ruler-tock { font-size: 11px; fill: #aaa; }
-  .ed-wave-head-text, .ed-wave-foot-text { font-size: 11px; fill: #333; }
-  .ed-wave-edge-handle { fill: #1a73e8; stroke: #ffffff; }
-  .ed-wave-edge-arrow { fill: #0041c4; }
-  .ed-wave-edge-tee { stroke: #0041c4; }
-  /* v3.5.0 Task 7: the pending line an armed drag or keyboard two-step is
-     standing on, from wave-ui.js's renderCanvas() — UI state only, never a
-     document read, so it is dashed rather than the solid .ed-wave-edge-path
-     colour to read as "not written yet". pointer-events: none so it can
-     never itself become the thing a press lands on. */
-  .ed-wave-edge-pending {
-    stroke: #1a73e8; stroke-width: 2; stroke-dasharray: 5 4; fill: none;
-    pointer-events: none;
+  /* Task 8 (spec section 4.4): the name column. Each row and each group
+     title has a grip, laid over the column by wave-ui.js (the box sits on
+     the canvas host padding box, above the layer). A grip shows for the row
+     the pointer is over, while it has the keyboard and while its menu is
+     open; otherwise it is invisible and takes no press, so the column under
+     it stays the name the pointer means. */
+  .ed-wave-grips { position: absolute; left: 0; top: 0; width: 0; height: 0; z-index: 2; }
+  .ed-wave-grip {
+    position: absolute; width: 16px; height: 22px; padding: 0; margin: 0;
+    display: flex; align-items: center; justify-content: center;
+    border: 0; border-radius: 4px; background: var(--md-ed-surface); color: var(--md-ed-glyph);
+    font-size: 13px; line-height: 1; cursor: pointer; opacity: 0; pointer-events: none;
+  }
+  .ed-wave-grip.is-on, .ed-wave-grip:focus, .ed-wave-grip[aria-expanded="true"] {
+    opacity: 1; pointer-events: auto;
+  }
+  .ed-wave-grip:hover, .ed-wave-grip[aria-expanded="true"] { background: var(--md-ed-hover); color: #333; }
+  .ed-wave-grip:focus { outline: 2px solid #1a73e8; outline-offset: 0; }
+  /* The in-place name field over a signal name (right-aligned, like the
+     name the engine draws) or a group title. */
+  .ed-wave-rename {
+    position: absolute; z-index: 3; box-sizing: border-box; text-align: right;
+    font-size: 14px; padding: 0 6px; border: 1px solid #1a73e8; border-radius: 3px;
+    background: #fff; color: #222;
   }
-  /* v3.6.0 Task 11: the transition dots wave-draw.js's drawTransitions()
-     paints while edge-creation is armed -- the visual answer to "where can
-     I aim". pointer-events: none for the same reason ed-wave-selection and
-     the other UI-state marks above are: the actual hit-testing runs through
-     geometry.boundaryAt against the pointer's raw coordinates
-     (wave-ui.js's cellFromEvent/onCanvasHover), never through this circle
-     as a DOM target, so it must never itself swallow the press it exists
-     to help aim. The [data-hot] variant is the same dot, larger and
-     filled solid, for the one nearest the pointer right now
-     (state.hoverBoundary in drawTransitions). */
-  .ed-wave-transition {
-    fill: #ffffff; stroke: #1a73e8; stroke-width: 1.5; pointer-events: none;
-  }
-  .ed-wave-transition[data-hot] { fill: #1a73e8; stroke: #0041c4; }
-  /* v3.6.0 Task 13: the old flex-basis/border/padding here were for
-     .ed-wave-preview as a direct flex child of .ed-wave-body; it now
-     lives inside .ed-wave-section-body (the 預覽 panel), which already
-     supplies the column width and padding, so only its own scroll behaviour
-     is left to set — a wide diagram's preview SVG must scroll within the
-     panel rather than stretching the whole 340px column. */
-  .ed-wave-preview { overflow: auto; max-height: 260px; }
-  .ed-wave-preview-label { font-size: 11px; color: #666; margin-bottom: 6px; }
-  /* v3.6.0 Task 13: the right-hand column — five collapsible panels
-     (關聯線/文件/Lane/預覽/原始碼) replacing the old direct
-     .ed-wave-preview column. 'flex: 0 0 340px' (not '0 1'): unlike the
-     old preview column, this one does not shrink when the canvas wants
-     more room — width-budget wins go through .ed-wave-panel's own cap
-     above, not by starving this column, because starving it re-introduces
-     the exact 160px-minimum squeeze this task's own .ed-wave-lanes
-     comment measured as the 800x600 defect. Below 1100px it collapses to a
-     28px rail instead (media query below) for the identical reason. */
-  /* v3.6.0 Task 13 fix round 4: box-sizing: border-box added. wave-ui.js's
-     clearSelectedEdgeOfSide() sets an inline width (in border-box, i.e.
-     rendered, pixels — the same unit getBoundingClientRect() reports
-     everywhere else it measures this element) to keep the selected edge's
-     own handle clear of this panel when expanded. Under the default
-     content-box sizing, width excludes padding (16px) and the border
-     (1px), so a JS-computed width landed 17px narrower on screen than
-     intended — MEASURED, not assumed: an inline width of 310px rendered at
-     327px. border-box makes width mean the same thing in CSS and in
-     getBoundingClientRect(), so the two agree without wave-ui.js having to
-     hardcode this rule's own padding/border numbers into its arithmetic. */
-  .ed-wave-side {
-    box-sizing: border-box; flex: 0 0 340px; border-left: 1px solid #e2e2e2;
-    overflow: auto; padding: 8px; display: flex; flex-direction: column; gap: 8px;
-  }
-  .ed-wave-section { border: 1px solid #ececec; border-radius: 6px; }
-  .ed-wave-section-title {
-    display: block; width: 100%; text-align: left; border: 0; background: #fafafa;
-    font: inherit; font-size: 11px; letter-spacing: .5px; color: #555;
-    padding: 5px 8px; cursor: pointer; border-radius: 6px 6px 0 0;
-  }
-  .ed-wave-section-body { display: none; padding: 8px; }
-  /* v3.6.0 Task 13 fix round 3: data-open is this SECTION's own toggle
-     state (wave-panels.js's section()) and says NOTHING about whether the
-     RAIL is currently showing it — those are two independent attributes on
-     two different elements. A section can report data-open with a
-     zero-size, unhittable body the whole time .ed-wave-side itself is
-     collapsed to its <1100px 28px rail (below): 關聯線/文件/Lane all default
-     data-open, and none of that changes just because the rail hides them.
-     Left deliberately this way rather than making data-open track actual
-     visibility — that would conflate "this section is open" with "the rail
-     happens to be showing right now", and toggling ONE section would then
-     have to silently relabel every OTHER already-open section's own state
-     too. What actually closes the gap this could otherwise leave (a control
-     that LOOKS reachable in the DOM but is not) is wave-ui.js's render()
-     expanding the rail on the one transition that matters (selecting an
-     edge) rather than this attribute pretending to mean something it does
-     not. */
-  .ed-wave-section[data-open] .ed-wave-section-body { display: block; }
-  .ed-wave-section-body label { display: flex; align-items: center; gap: 6px; margin: 4px 0; }
-  .ed-wave-section-body label span { flex: 0 0 96px; font-size: 12px; color: #555; }
-  .ed-wave-section-body input {
-    flex: 1 1 auto; min-width: 0; font-size: 12px; padding: 2px 4px;
-  }
-  .ed-wave-source {
-    margin: 0; font-size: 11px; line-height: 1.45; white-space: pre;
-    overflow: auto; max-height: 260px;
-  }
-  /* 視窗窄於這條線時右欄收成一條直立標籤，展開時覆蓋在畫布上 —— 否則
-     800x600 的測試視窗下畫布會被 340px 固定寬的側欄吃掉大半，拖曳手勢會
-     不可用（v3.6.0 Task 13 自己的 .ed-wave-lanes 註解量到的舊值：只剩
-     282px）。收起時仍是普通文件流寬度（28px），展開時疊在畫布上方而不擠
-     壓它。data-expanded 有三個來源：wave-panels.js 的 section() 點擊 title、
-     同檔案的 collapseBtn 反過來移除它、以及 fix round 3 新增的
-     wave-panels.js 的 expandSide()（由 wave-ui.js 的 render() 在
-     selectedEdge 從 null 變成有值的那一拍呼叫——選取一條 edge 之後，
-     整個回饋只長在這個側欄的關聯線面板裡，窄視窗下不展開就等於使用者
-     什麼都看不到、也按不到）。 */
-  /* v3.6.0 Task 13 fix round 1: the collapse-back button. Hidden everywhere
-     except the one state it exists for — the <1100px rail, expanded — so it
-     never shows, and never sits in the tab order, at a wide viewport or in
-     the rail's own default collapsed state. */
-  .ed-wave-side-collapse { display: none; }
-  @media (max-width: 1100px) {
-    .ed-wave-side { flex: 0 0 28px; padding: 4px 2px; }
-    .ed-wave-side:not([data-expanded]) .ed-wave-section-body { display: none; }
-    .ed-wave-side[data-expanded] {
-      position: absolute; right: 0; top: 0; bottom: 0; width: 340px;
-      background: #ffffff; z-index: 3; flex: 0 0 340px; padding: 8px;
-    }
-    .ed-wave-side[data-expanded] .ed-wave-side-collapse {
-      display: block; width: 100%; text-align: right; border: 0;
-      background: transparent; font-size: 12px; color: #555; cursor: pointer;
-      padding: 2px 4px 6px;
-    }
+  .ed-wave-rename.is-group { text-align: left; }
+  /* The add-a-signal row under the last lane. */
+  .ed-wave-add-lane {
+    display: block; margin: 4px 0 0; border: 0; border-radius: 4px; background: transparent;
+    color: #1a73e8; font-size: 12px; padding: 4px 8px; cursor: pointer;
+  }
+  .ed-wave-add-lane:hover, .ed-wave-add-lane:focus { background: var(--md-ed-hover); }
+  /* Spec section 4.3: the floating toolbar over a selected run of cycles,
+     placed against the panel by wave-ui.js (above the run, or below it when
+     there is no room). Under the popovers (z-index 4), so 電位's grid opens
+     over it. */
+  .ed-wave-range {
+    position: absolute; z-index: 3; display: flex; align-items: center; gap: 2px;
+    padding: 3px; background: #fff; border: 1px solid #e2e2e2; border-radius: 6px;
+    box-shadow: 0 4px 16px var(--md-ed-shadow); white-space: nowrap;
+  }
+  .ed-wave-range button {
+    border: 0; border-radius: 4px; background: transparent; color: #333;
+    padding: 4px 8px; font-size: 12px; cursor: pointer;
+  }
+  .ed-wave-range button:hover, .ed-wave-range button:focus { background: var(--md-ed-hover); }
+  /* Task 9 (spec section 4.5): the edges. The engine draws them under the
+     layer, so the layer carries a transparent twin of each for a press to
+     land on: the line (hit on its wide stroke only), the label box and an
+     unlabelled self-loop ring (hit on their area). A selected edge has a
+     ring at each end that takes a press, under its visible mark. The
+     selection is drawn with the engine path and its matrix, so its width
+     must not scale with it. */
+  .ed-wave-edge-hit { pointer-events: stroke; cursor: pointer; }
+  .ed-wave-edge-label-hit, .ed-wave-edge-loop-hit { pointer-events: all; }
+  .ed-wave-edge-end-hit { pointer-events: all; cursor: move; }
+  .ed-wave-edge-sel { vector-effect: non-scaling-stroke; }
+  .ed-wave-note-sel { fill: none; stroke: #1a73e8; stroke-width: 1.5; pointer-events: none; }
+  /* The toolbar beside a selected edge or note (right of its label),
+     placed against the panel like the range toolbar; 更多 lists its shapes
+     on a second row. */
+  .ed-wave-edge-bar {
+    position: absolute; z-index: 3; display: flex; flex-wrap: wrap; align-items: center; gap: 2px;
+    max-width: 360px; padding: 3px; background: #fff; border: 1px solid #e2e2e2; border-radius: 6px;
+    box-shadow: 0 4px 16px var(--md-ed-shadow); white-space: nowrap;
+  }
+  .ed-wave-edge-group { display: flex; gap: 1px; padding-right: 3px; margin-right: 1px; border-right: 1px solid #e2e2e2; }
+  .ed-wave-edge-bar button {
+    border: 0; border-radius: 4px; background: transparent; color: #333;
+    padding: 4px 8px; font-size: 12px; cursor: pointer;
+  }
+  .ed-wave-edge-bar button:hover, .ed-wave-edge-bar button:focus { background: var(--md-ed-hover); }
+  .ed-wave-edge-bar button[aria-pressed="true"] { background: #1a73e8; color: #fff; }
+  .ed-wave-edge-bar button.is-danger { color: var(--md-ed-err); }
+  .ed-wave-edge-more-list { display: flex; flex-wrap: wrap; gap: 1px; flex-basis: 100%; }
+  .ed-wave-edge-more-list[hidden] { display: none; }
+  .ed-wave-edge-more-list button { font-family: monospace; }
+  /* The one-line field over an edge's label or a point note. */
+  .ed-wave-edge-input {
+    position: absolute; z-index: 3; box-sizing: border-box; text-align: center;
+    font-size: 12px; padding: 0 4px; border: 1px solid #1a73e8; border-radius: 3px;
+    background: #fff; color: #222;
   }
-  .ed-wave-status {
-    border-top: 1px solid #e2e2e2; padding: 6px 12px; font-size: 12px;
-    color: #444; min-height: 18px;
+  /* Spec section 4.8: the bottom line says what can be done next, never
+     what just happened (results go to the toast). Task 11: the sentence
+     follows the state, and 「? 全部快捷鍵」 sits fixed at its right end. */
+  .ed-wave-hint {
+    display: flex; align-items: center; gap: 12px;
+    border-top: 1px solid #e2e2e2; padding: 3px 8px 3px 12px; font-size: 12px; color: #444; min-height: 24px;
+  }
+  .ed-wave-hint-text { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .ed-wave-hint-help {
+    flex: 0 0 auto; border: 0; border-radius: 4px; background: transparent; color: #1a73e8;
+    font-size: 12px; padding: 3px 8px; cursor: pointer;
+  }
+  .ed-wave-hint-help:hover, .ed-wave-hint-help[aria-expanded="true"] { background: var(--md-ed-hover); }
+  /* Task 11: the shortcut card, in the middle of the editor (wave-ui.js
+     centres it), above every other popover and floating toolbar. */
+  .ed-wave-shortcuts {
+    z-index: 5; box-sizing: border-box; width: min(600px, calc(100% - 16px));
+    max-height: calc(100% - 16px); overflow: auto; padding: 10px 14px 14px;
+  }
+  .ed-wave-shortcuts:focus { outline: none; }
+  .ed-wave-shortcuts-head { display: flex; align-items: center; margin-bottom: 4px; }
+  .ed-wave-shortcuts-title { flex: 1 1 auto; font-weight: bold; font-size: 14px; color: #222; }
+  .ed-wave-shortcuts-close {
+    border: 0; border-radius: 4px; background: transparent; color: #555;
+    width: 26px; height: 26px; font-size: 13px; cursor: pointer;
+  }
+  .ed-wave-shortcuts-close:hover { background: var(--md-ed-hover); }
+  .ed-wave-shortcuts-body { display: grid; grid-template-columns: 1fr 1fr; gap: 8px 24px; }
+  .ed-wave-shortcut-title { font-weight: bold; font-size: 12px; color: #444; margin: 6px 0 4px; }
+  .ed-wave-shortcut-row { display: flex; align-items: baseline; gap: 10px; font-size: 12px; color: #333; padding: 2px 0; }
+  .ed-wave-shortcut-keys { flex: 0 0 92px; display: flex; flex-wrap: wrap; gap: 3px; }
+  .ed-wave-shortcut-keys kbd {
+    font-family: inherit; font-size: 11px; line-height: 16px; padding: 0 4px;
+    border: 1px solid #e2e2e2; border-radius: 3px; background: #fff; color: #222; white-space: nowrap;
+  }
+  /* The cursor narration: for a screen reader only, so visually hidden but
+     never display: none (a live region that is not rendered is not read). */
+  .ed-wave-live {
+    position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0;
+    overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0;
   }
   .ed-wave-parse-error { padding: 16px; }
   .ed-wave-parse-message { color: #b00020; font-weight: bold; }
@@ -2660,6 +2714,7 @@ const html = `<!DOCTYPE html>
     padding: 0 2px;
     border-radius: 3px;
   }
+  mark.search-hit-block { display: block; }
   .toc {
     display: flex;
     flex-direction: column;
@@ -2795,6 +2850,12 @@ const html = `<!DOCTYPE html>
   .toc-list-level-1 > .toc-item > details > summary > a {
     font-size: 0.95em;
   }
+  /* v3.13.1 (R3): chapters of a multi-H1 TOC, set apart by a rule and a gap; weight unchanged. */
+  .toc[data-toc-chapters] > .toc-list-level-1 > .toc-item + .toc-item {
+    margin-top: 10px;
+    padding-top: 6px;
+    border-top: 1px solid #d8dee4;
+  }
   .toc-list-level-2 > .toc-item > a,
   .toc-list-level-2 > .toc-item > details > summary > a {
     font-size: 0.9em;
@@ -4116,6 +4177,7 @@ ${mermaidInitTag}`)
     results: [],
     selectedResultIndex: -1,
     activeHighlight: null,
+    activeHighlights: [],
   };
   window.__readerState = readerState;
 
@@ -4258,14 +4320,18 @@ ${mermaidInitTag}`)
   // 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.
+  // it out of that band hands tracking back to the line. The last sections of
+  // a document can be too short to ever reach the line: at the bottom of the
+  // page a clicked heading anywhere on screen keeps its row lit. Only a click
+  // pins, so a plain scroll to the bottom still follows 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;
+      const atBottom = window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
+      if (pinned && tocLinks.has(pinned.id) && top >= -40 && (top <= line || (atBottom && top < window.innerHeight))) return pinned;
       pinnedHeadingId = null;
     }
     let first = null;
@@ -4304,15 +4370,54 @@ ${mermaidInitTag}`)
     syncActiveHeading(node.id);
     syncReadingTitle(node);
   }
-  window.addEventListener('scroll', () => {
+  // Scrolls are not the only thing that moves a heading across the line: a
+  // height-only window resize moves the line itself (and reflows nothing, so
+  // no scroll follows), and a column resize reflows the text under it.
+  function scheduleReadingLinePass() {
     if (readingLinePending) return;
     readingLinePending = true;
     requestAnimationFrame(readingLinePass);
-  }, { passive: true });
+  }
+  window.addEventListener('scroll', scheduleReadingLinePass, { passive: true });
+  window.addEventListener('resize', scheduleReadingLinePass);
+  // Ends the freeze a selected search result put on the highlight. The freeze
+  // also kept the TOC from opening the hit's path, and the next pass may find
+  // the same section (the reader is still inside the hit's section), which
+  // syncActiveHeading skips as no change: so the next frame re-syncs the row
+  // itself, opening its path and centring it.
+  function endSearchFreeze() {
+    observerFrozen = false;
+    requestAnimationFrame(resyncTocToScroll);
+  }
+  // A TOC click is the reader leaving a search hit: it also ends the freeze,
+  // so the clicked row lights.
   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);
+    if (!link) return;
+    pinnedHeadingId = link.getAttribute('href').slice(1);
+    endSearchFreeze();
   });
+  // So does a scroll of the page by hand (R6b, R17): a wheel, a touch drag or
+  // a scroll key. Inside the sidebar (the results list, the TOC) or the
+  // lightbox the same gestures work that control, and keep the freeze; so do
+  // a sideways wheel (a wide table's swipe), ctrl+wheel (zoom) and a key typed
+  // into a field. A programmatic scroll (the result jump itself) fires none of
+  // these events.
+  const SCROLL_KEYS = new Set(['PageUp', 'PageDown', 'Home', 'End', 'ArrowUp', 'ArrowDown', ' ', 'Spacebar']);
+  const unfreezeOnUserScroll = (event) => {
+    if (!observerFrozen) return;
+    const target = event.target;
+    if (event.type === 'wheel' && (event.deltaY === 0 || event.ctrlKey)) return;
+    if (event.type === 'keydown') {
+      if (!SCROLL_KEYS.has(event.key) || lightboxIsOpen()) return;
+      if (target instanceof Element && (target.closest('input, textarea, select') || target.isContentEditable)) return;
+    }
+    if (target instanceof Element && target.closest('.reader-sidebar, .lightbox')) return;
+    endSearchFreeze();
+  };
+  window.addEventListener('wheel', unfreezeOnUserScroll, { passive: true });
+  window.addEventListener('touchmove', unfreezeOnUserScroll, { passive: true });
+  window.addEventListener('keydown', unfreezeOnUserScroll);
   function bindHeadingObserver() {
     readingLinePass();
   }
@@ -4417,13 +4522,22 @@ ${mermaidInitTag}`)
     });
   }
 
+  // A hit that crosses inline markup is several marks (see
+  // highlightFirstOccurrence); each is unwrapped and its own parent normalised,
+  // which rejoins the text it was cut from, so main.content is byte-identical.
+  // A math mark wraps a whole formula and cut nothing, so it is only unwrapped.
   function clearSelectedHighlight() {
-    const mark = readerState.activeHighlight;
-    if (mark && mark.parentNode) {
-      const text = document.createTextNode(mark.textContent || '');
-      mark.parentNode.replaceChild(text, mark);
-      text.parentNode.normalize();
-    }
+    const marks = readerState.activeHighlights.length
+      ? readerState.activeHighlights
+      : (readerState.activeHighlight ? [readerState.activeHighlight] : []);
+    marks.forEach((mark) => {
+      const parent = mark.parentNode;
+      if (!parent) return;
+      while (mark.firstChild) parent.insertBefore(mark.firstChild, mark);
+      parent.removeChild(mark);
+      if (!mark.classList.contains('search-hit-math')) parent.normalize();
+    });
+    readerState.activeHighlights = [];
     readerState.activeHighlight = null;
   }
 
@@ -4489,61 +4603,153 @@ ${mermaidInitTag}`)
     return { start, end };
   }
 
+  // A whitespace-only text node is the real space between words when it sits in
+  // an inline element or between two inline siblings ("**bold** *italic*").
+  // Between blocks (and inside list / table structure) it is markup layout:
+  // block boundaries get a virtual space instead, and a mark must never land
+  // there (a mark as a direct child of a ul or tr).
+  const INLINE_SELECTOR = 'a, abbr, b, bdi, bdo, cite, code, data, del, dfn, em, i, img, ins, kbd, mark, q, s, samp, small, span, strong, sub, sup, time, u, var';
+  function isInlineSibling(node) {
+    if (!node) return false;
+    if (node.nodeType === Node.TEXT_NODE) return !!node.nodeValue.trim();
+    return node.nodeType === Node.ELEMENT_NODE && node.matches(INLINE_SELECTOR);
+  }
+  function isInlineSpace(node) {
+    const parent = node.parentElement;
+    if (!parent) return false;
+    if (parent.matches(INLINE_SELECTOR)) return true;
+    return isInlineSibling(node.previousSibling) && isInlineSibling(node.nextSibling);
+  }
+
+  // The section's text as one string, read the way the search index reads it
+  // (renderer side, sectionInlineText): whitespace runs fold to one space and
+  // letters to lower case, as normalizeText folds the query; a br element is a
+  // space; a formula (.katex) is its TeX source, taken from its annotation, and
+  // its MathML and glyph markup are never walked; two blocks are joined by a
+  // space. Every flat position maps back to its (node, offset), so a phrase can
+  // cross a heading's .sec number, inline code, bold, a soft or hard line break
+  // or a formula. Spaces that stand for a br or a block boundary map to no node
+  // and are never wrapped. The walk stops at the first node that completes a
+  // hit, so a long section is not read past its first occurrence.
   function highlightFirstOccurrence(sectionId, query) {
     const bounds = sectionBoundary(sectionId);
     if (!bounds) return null;
     const { start, end } = bounds;
     const container = start.parentNode;
     if (!container) return null;
-    const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, {
+    const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT, {
       acceptNode(node) {
-        if (!node.nodeValue || !node.nodeValue.trim()) return NodeFilter.FILTER_REJECT;
-        if (node.parentElement && node.parentElement.closest(SKIP_SELECTOR)) return NodeFilter.FILTER_REJECT;
-        if (node.parentElement && node.parentElement.closest('.reader-sidebar')) return NodeFilter.FILTER_REJECT;
+        if (node.nodeType === Node.ELEMENT_NODE) {
+          if (node.matches(SKIP_SELECTOR) || node.matches('.reader-sidebar, .heading-anchor')) return NodeFilter.FILTER_REJECT;
+          return node.matches('br, .katex') ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+        }
+        if (!node.nodeValue) return NodeFilter.FILTER_REJECT;
+        if (!node.nodeValue.trim() && !isInlineSpace(node)) return NodeFilter.FILTER_REJECT;
         return NodeFilter.FILTER_ACCEPT;
       },
     });
-    let inRange = false;
-    const queryLower = query.toLowerCase();
+    // Nothing before the heading is in range, so the walk starts at it.
+    walker.currentNode = start;
+    const BLOCK = 'p, li, td, th, h1, h2, h3, h4, h5, h6, pre, blockquote, dt, dd, figcaption, .katex-display';
+    const nodes = [];
+    let flat = '';
+    const at = [];
+    let space = true;
+    let lastBlock = null;
+    let idx = -1;
     while (walker.nextNode()) {
       const node = walker.currentNode;
-      if (!inRange) {
-        if (start.contains(node)) {
-          inRange = true;
-        } else if (start.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_FOLLOWING) {
-          inRange = true;
-        } else {
-          continue;
-        }
-      }
-      if (node.parentElement && node.parentElement.closest('.heading-anchor')) continue;
       if (end) {
         const pos = end.compareDocumentPosition(node);
         if (end === node || end.contains(node) || (pos & Node.DOCUMENT_POSITION_FOLLOWING)) {
           break;
         }
       }
-      const text = node.nodeValue;
-      const idx = text.toLowerCase().indexOf(queryLower);
-      if (idx === -1) continue;
-      const before = text.slice(0, idx);
-      const match = text.slice(idx, idx + query.length);
-      const after = text.slice(idx + query.length);
+      if (node.nodeName === 'BR') {
+        if (!space) {
+          flat += ' ';
+          at.push(null);
+          space = true;
+        }
+        continue;
+      }
+      const isMath = node.nodeType === Node.ELEMENT_NODE;
+      let text = node.nodeValue;
+      if (isMath) {
+        const tex = node.querySelector('annotation[encoding="application/x-tex"]');
+        text = tex ? tex.textContent : '';
+        // Resume the walk after the formula's last descendant.
+        let last = node;
+        while (last.lastChild) last = last.lastChild;
+        walker.currentNode = last;
+      }
+      const ni = nodes.length;
+      nodes.push(node);
+      const prevLen = flat.length;
+      const block = (node.parentElement && node.parentElement.closest(BLOCK)) || (isMath ? node : null);
+      if (ni && block !== lastBlock && !space) {
+        flat += ' ';
+        at.push(null);
+        space = true;
+      }
+      lastBlock = block;
+      for (let i = 0; i < text.length; i++) {
+        if (/\\s/.test(text[i])) {
+          if (space) continue;
+          flat += ' ';
+          at.push([ni, i]);
+          space = true;
+        } else {
+          // A few characters lower-case to two code units; map each to i.
+          const lower = text[i].toLowerCase();
+          flat += lower;
+          for (let u = 0; u < lower.length; u++) at.push([ni, i]);
+          space = false;
+        }
+      }
+      // Only a hit that ends in this node's text can be new.
+      idx = flat.indexOf(query, Math.max(0, prevLen - query.length + 1));
+      if (idx !== -1) break;
+    }
+    if (idx === -1) return null;
+    // node index -> [first offset, last offset] of the hit inside that node
+    const spans = new Map();
+    for (let k = idx; k < idx + query.length; k++) {
+      const p = at[k];
+      if (!p) continue;
+      const span = spans.get(p[0]) || [p[1], p[1]];
+      span[1] = p[1];
+      spans.set(p[0], span);
+    }
+    // One mark per node, wrapping only that node's slice, so the .sec / code /
+    // bold wrappers stay whole siblings and clearing restores the markup
+    // exactly. Last node first; each node is split only once anyway. A formula
+    // is marked whole from outside, so KaTeX's own markup is never cut; a
+    // display formula's mark goes around its .katex-display (KaTeX styles
+    // .katex-display > .katex) and is a block, so its background shows.
+    const marks = [];
+    Array.from(spans.keys()).sort((a, b) => b - a).forEach((ni) => {
+      const node = nodes[ni];
       const mark = document.createElement('mark');
       mark.className = 'search-hit is-selected';
-      mark.textContent = match;
-      const parent = node.parentNode;
-      if (!parent) return null;
-      if (before) parent.insertBefore(document.createTextNode(before), node);
-      parent.insertBefore(mark, node);
-      if (after) {
-        node.nodeValue = after;
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        const display = node.parentElement && node.parentElement.classList.contains('katex-display') ? node.parentElement : null;
+        const target = display || node;
+        mark.classList.add('search-hit-math');
+        if (display) mark.classList.add('search-hit-block');
+        target.parentNode.insertBefore(mark, target);
+        mark.appendChild(target);
       } else {
-        parent.removeChild(node);
+        const span = spans.get(ni);
+        const range = document.createRange();
+        range.setStart(node, span[0]);
+        range.setEnd(node, span[1] + 1);
+        range.surroundContents(mark);
       }
-      return mark;
-    }
-    return null;
+      marks.unshift(mark);
+    });
+    readerState.activeHighlights = marks;
+    return marks[0] || null;
   }
 
   function jumpToAndHighlight(result) {
@@ -4791,6 +4997,11 @@ ${mermaidInitTag}`)
   var anchorTop = 0;
   var anchorFrame = 0;
   var suppressAnchorCapture = false;
+  // Set by any scroll that is not our own restore, cleared by a capture: the
+  // anchor then describes a position the page has already left (R1, R9).
+  var anchorStale = false;
+  // scrollY when the anchor was captured or last restored by us.
+  var anchorScrollY = 0;
   // 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;
@@ -4836,8 +5047,13 @@ ${mermaidInitTag}`)
       }
     }
     if (!node) return;
+    // A display formula's search mark is itself a child of the column, and
+    // clearing the search removes it: pin the formula inside it instead.
+    if (node.matches('mark.search-hit') && node.firstElementChild) node = node.firstElementChild;
     anchorNode = node;
     anchorTop = node.getBoundingClientRect().top;
+    anchorScrollY = window.scrollY;
+    anchorStale = false;
   }
 
   function restoreScrollAnchor() {
@@ -4845,9 +5061,13 @@ ${mermaidInitTag}`)
     var delta = anchorNode.getBoundingClientRect().top - anchorTop;
     if (!delta) return;
     window.scrollTo(window.scrollX, window.scrollY + delta);
+    // Our own correction is not a newer scroll: without this, the next frame
+    // of a splitter drag reads it as one and drops the anchor.
+    anchorScrollY = window.scrollY;
   }
 
   window.addEventListener('scroll', function () {
+    if (!suppressAnchorCapture) anchorStale = true;
     if (anchorFrame) return;
     anchorFrame = window.requestAnimationFrame(function () {
       anchorFrame = 0;
@@ -4856,6 +5076,13 @@ ${mermaidInitTag}`)
   }, { passive: true });
 
   function holdScrollAnchor() {
+    // A scroll issued before this reflow's frame may not have dispatched its
+    // event yet (resize runs before scroll in a frame): compare offsets too.
+    // A shorter document clamping the offset is not somebody else's scroll.
+    var maxY = document.documentElement.scrollHeight - window.innerHeight;
+    var moved = Math.abs(window.scrollY - anchorScrollY) > 1;
+    var clamped = window.scrollY < anchorScrollY && window.scrollY >= maxY - 1;
+    if (anchorStale || (moved && !clamped)) anchorNode = null;
     // Hold the anchor across the whole reflow: the scrollTo below fires scroll
     // events that would otherwise re-capture a mid-reflow position.
     suppressAnchorCapture = true;
@@ -4895,6 +5122,7 @@ ${mermaidInitTag}`)
       if (w === lastAnchorColW) return;
       lastAnchorColW = w;
       holdScrollAnchor();
+      scheduleReadingLinePass();
     }).observe(contentEl);
   }
 
@@ -6377,6 +6605,9 @@ 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;
+  // bin/md2doc.js renders each format of one input in its own process and
+  // passes this to every one after the first, so --html --pdf warns once.
+  const WAVE_WARN = !process.argv.slice(4).includes('--no-wave-warn');
   if (!src || !dst) {
     console.error('Usage: node md2doc.js <input.md> <output.html|pdf>');
     process.exit(1);
@@ -6386,7 +6617,7 @@ if (require.main === module) {
 
   (async () => {
     const mdText = fs.readFileSync(src, 'utf8');
-    const { html } = await renderMarkdown(mdText, path.resolve(src), { lang: LANG_ARG });
+    const { html } = await renderMarkdown(mdText, path.resolve(src), { lang: LANG_ARG, warnWaveOverflow: WAVE_WARN ? src : undefined });
     let finalHtml = html;
 
     if (ext === '.html') {