@helping-ai-workflow/md2doc 3.13.0 → 3.14.0

package/lib/md2doc.js

@@ -185,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'));
 
@@ -232,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);
@@ -335,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
@@ -345,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
@@ -732,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);
       }
@@ -758,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 }];
@@ -978,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
@@ -1048,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.
@@ -1068,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.
@@ -1103,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
@@ -1133,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) {
@@ -1205,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,
@@ -1224,19 +1371,41 @@ ${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]);
+          // v3.14.0 T10: the reader wraps an svg-only block in .inline-svg for the
+          // dark white plate; edit mode keeps its DOM, so it marks the wrapper.
+          const svgPlate = ((t.type === 'html' && t.block && wrapsSvg(t.text)) ||
+            (t.type === 'paragraph' && wrapsSvgParagraph(t.raw))) ? ' data-svg-plate="1"' : '';
+          parts.push(
+            `<div class="ed-block" data-block-id="${b.id}" data-block-type="${b.type}"${svgPlate}>` +
+            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
@@ -1270,7 +1439,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.
@@ -1286,6 +1460,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>
@@ -1304,7 +1483,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">
@@ -1314,7 +1493,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>`;
@@ -2539,6 +2718,7 @@ const html = `<!DOCTYPE html>
     padding: 0 2px;
     border-radius: 3px;
   }
+  mark.search-hit-block { display: block; }
   .toc {
     display: flex;
     flex-direction: column;
@@ -2674,6 +2854,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;
@@ -3264,6 +3450,16 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
     outline: 2px solid var(--md-accent); outline-offset: 2px;
     caret-color: var(--md-accent);
   }
+  /* v3.14.0 T4: the empty-paragraph hint. syncEmptyMark() in the client sets
+     data-ed-empty on a paragraph surface with no text; a real paragraph shows
+     the hint while focused, the transient (an empty document's, or one Enter
+     left behind) shows it even unfocused so a blank line is never a blank
+     page. An empty transient also gets a line of height of its own. */
+  .ed-block[data-block-type="paragraph"] > .ed-wys-armed[data-ed-empty]:focus::before,
+  .ed-block[data-ed-transient] > .ed-wys-armed[data-ed-empty]::before {
+    content: attr(data-placeholder); color: var(--md-muted-2); pointer-events: none;
+  }
+  .ed-block[data-ed-transient] > .ed-wys-armed { min-height: 1.6em; }
   /* Task 5: table cells armed PERMANENTLY (one edit surface per CELL, not
      per table root — see armEditables()'s 'table' branch in the client
      runtime) — same "no persistent outline, blue on :focus" language as
@@ -3995,6 +4191,7 @@ ${mermaidInitTag}`)
     results: [],
     selectedResultIndex: -1,
     activeHighlight: null,
+    activeHighlights: [],
   };
   window.__readerState = readerState;
 
@@ -4137,14 +4334,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;
@@ -4183,15 +4384,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();
   }
@@ -4296,13 +4536,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;
   }
 
@@ -4349,80 +4598,179 @@ ${mermaidInitTag}`)
     )).join('');
   }
 
+  // On the edit page every block sits in a .ed-block wrapper, so the heading's
+  // siblings are wrappers: the section ends at the next wrapper that is, or
+  // directly holds, a heading of the same or a shallower depth. In the reader
+  // the unit is the heading itself and the walk is the one it always was.
   function sectionBoundary(sectionId) {
     const start = document.getElementById(sectionId);
     if (!start) return null;
     const startDepth = Number(start.getAttribute('data-reader-depth') || '1');
+    const unit = start.closest('.ed-block') || start;
     let end = null;
-    let node = start.nextElementSibling;
+    let node = unit.nextElementSibling;
     while (node) {
-      if (node.matches && node.matches('[data-reader-heading]')) {
-        const depth = Number(node.getAttribute('data-reader-depth') || '1');
+      let heading = null;
+      if (node.matches && node.matches('[data-reader-heading]')) heading = node;
+      else if (unit !== start && node.querySelector) heading = node.querySelector(':scope > [data-reader-heading]');
+      if (heading) {
+        const depth = Number(heading.getAttribute('data-reader-depth') || '1');
         if (depth <= startDepth) {
-          end = node;
+          end = heading;
           break;
         }
       }
       node = node.nextElementSibling;
     }
-    return { start, end };
-  }
-
+    return { start, end, container: unit.parentNode };
+  }
+
+  // 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;
+    const { start, end, container } = bounds;
     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, button')) 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, .ed-li-text, 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) {
@@ -4670,6 +5018,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;
@@ -4715,8 +5068,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() {
@@ -4724,9 +5082,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;
@@ -4735,6 +5097,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;
@@ -4774,6 +5143,7 @@ ${mermaidInitTag}`)
       if (w === lastAnchorColW) return;
       lastAnchorColW = w;
       holdScrollAnchor();
+      scheduleReadingLinePass();
     }).observe(contentEl);
   }