brookmd 0.29.1 → 0.30.0

package/dist/hi.js

@@ -32,6 +32,50 @@ const KEYWORDS_SQL = new Set(
     " "
   )
 );
+const KEYWORDS_JAVA = new Set(
+  "abstract assert boolean break byte case catch char class const continue default do double else enum extends false final finally float for goto if implements import instanceof int interface long native new null package private protected public record return sealed short static strictfp super switch synchronized this throw throws transient true try var void volatile while yield".split(
+    " "
+  )
+);
+const KEYWORDS_C = new Set(
+  "auto bool break case char const continue default do double else enum extern false float for goto if inline int long register restrict return short signed sizeof static struct switch true typedef union unsigned void volatile while NULL".split(
+    " "
+  )
+);
+const KEYWORDS_CPP = /* @__PURE__ */ new Set([
+  ...KEYWORDS_C,
+  ...["catch", "class", "concept", "constexpr", "const_cast", "decltype", "delete", "dynamic_cast", "explicit", "export", "final", "friend", "mutable", "namespace", "new", "noexcept", "nullptr", "operator", "override", "private", "protected", "public", "reinterpret_cast", "requires", "static_assert", "static_cast", "template", "this", "throw", "try", "typeid", "typename", "using", "virtual"]
+]);
+const KEYWORDS_CS = new Set(
+  "abstract as async await base bool break byte case catch char checked class const continue decimal default delegate do double dynamic else enum event explicit extern false finally fixed float for foreach get goto if implicit in int interface internal is lock long nameof namespace new null object operator out override params private protected public readonly record ref return sbyte sealed set short sizeof stackalloc static string struct switch this throw true try typeof uint ulong unchecked unsafe ushort using var virtual void volatile while yield".split(
+    " "
+  )
+);
+const KEYWORDS_PHP = new Set(
+  "abstract and array as bool break callable case catch class clone const continue declare default do echo else elseif empty enum extends final finally float fn for foreach function global goto if implements include include_once instanceof insteadof int interface isset list match namespace new null or parent print private protected public readonly require require_once return self static string switch throw trait true try unset use var void while xor yield false".split(
+    " "
+  )
+);
+const KEYWORDS_RUBY = new Set(
+  "BEGIN END alias and begin break case class def defined? do else elsif end ensure false for if in module next nil not or redo require require_relative rescue retry return self super then true undef unless until when while yield attr_accessor attr_reader attr_writer lambda proc".split(
+    " "
+  )
+);
+const KEYWORDS_SWIFT = new Set(
+  "actor any as associatedtype async await break case catch class continue default defer deinit do else enum extension fallthrough false fileprivate for func guard if import in indirect init inout internal is lazy let mutating nil open operator private protocol public repeat rethrows return self Self some static struct subscript super switch throw throws true try typealias var where while".split(
+    " "
+  )
+);
+const KEYWORDS_KOTLIN = new Set(
+  "abstract actual annotation as break by catch class companion const constructor continue crossinline data do dynamic else enum expect external false field final finally for fun get if import in infix init inline inner interface internal is it lateinit noinline null object open operator out override package private protected public reified return sealed set super suspend tailrec this throw true try typealias typeof val var vararg when where while".split(
+    " "
+  )
+);
+const KEYWORDS_DOCKER = new Set(
+  "ADD ARG AS CMD COPY ENTRYPOINT ENV EXPOSE FROM HEALTHCHECK LABEL MAINTAINER ONBUILD RUN SHELL STOPSIGNAL USER VOLUME WORKDIR as".split(
+    " "
+  )
+);
 const jsPats = [
   ["com", /\/\/[^\n]*/y],
   ["com", /\/\*[\s\S]*?\*\//y],
@@ -125,27 +169,137 @@ const cssPats = [
   ["pun", /[:;,{}()]/y],
   ["ws", /\s+/y]
 ];
-const LANGS = {
-  js: { pats: jsPats, kw: KEYWORDS_JS },
-  javascript: { pats: jsPats, kw: KEYWORDS_JS },
-  ts: { pats: jsPats, kw: KEYWORDS_TS },
-  tsx: { pats: jsPats, kw: KEYWORDS_TS },
-  jsx: { pats: jsPats, kw: KEYWORDS_JS },
-  typescript: { pats: jsPats, kw: KEYWORDS_TS },
-  rust: { pats: rustPats, kw: KEYWORDS_RUST },
-  rs: { pats: rustPats, kw: KEYWORDS_RUST },
-  py: { pats: pyPats, kw: KEYWORDS_PY },
-  python: { pats: pyPats, kw: KEYWORDS_PY },
-  go: { pats: goPats, kw: KEYWORDS_GO },
-  bash: { pats: bashPats, kw: KEYWORDS_BASH },
-  sh: { pats: bashPats, kw: KEYWORDS_BASH },
-  shell: { pats: bashPats, kw: KEYWORDS_BASH },
-  json: { pats: jsonPats },
-  sql: { pats: sqlPats, kw: KEYWORDS_SQL },
-  html: { pats: htmlPats },
-  xml: { pats: htmlPats },
-  css: { pats: cssPats }
-};
+const cFamilyPats = [
+  ["com", /\/\/[^\n]*/y],
+  ["com", /\/\*[\s\S]*?\*\//y],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /'(?:\\.|[^'\\\n])*'/y],
+  // The suffix class after a hex literal must not overlap the hex digits:
+  // `[\da-fA-F_]+` followed by `[lLfFdDuU]*` shares `d D f F`, and a long hex
+  // run ending in a non-suffix word char then backtracks quadratically (a
+  // 16 KB run cost ~0.5 s). Hex/binary take only `[lLuU]`; decimal keeps the
+  // float suffixes, whose class is disjoint from digits.
+  ["num", /\b(?:0x[\da-fA-F_]+[lLuU]*|0b[01_]+[lLuU]*|\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?[lLfFdDuU]*)\b/y],
+  ["dec", /@[A-Za-z_]\w*/y],
+  ["ident", /[A-Za-z_]\w*/y],
+  ["pun", /[+\-*/=<>!&|^~?:;,.[\](){}%]/y],
+  ["ws", /\s+/y]
+];
+const cPats = [["mac", /#[ \t]*[A-Za-z_]+/y], ...cFamilyPats];
+const phpPats = [
+  ["com", /\/\/[^\n]*/y],
+  ["com", /#[^\n]*/y],
+  ["com", /\/\*[\s\S]*?\*\//y],
+  ["tag", /<\?php\b|<\?=|\?>/y],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /'(?:\\.|[^'\\\n])*'/y],
+  ["var", /\$+[A-Za-z_]\w*/y],
+  ["num", /\b(?:0x[\da-fA-F_]+|\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?)\b/y],
+  ["ident", /[A-Za-z_]\w*/y],
+  ["pun", /[+\-*/=<>!&|^~?:;,.[\](){}%@\\]/y],
+  ["ws", /\s+/y]
+];
+const rubyPats = [
+  ["com", /#[^\n]*/y],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /'(?:\\.|[^'\\\n])*'/y],
+  ["lt", /:[A-Za-z_]\w*[?!]?/y],
+  ["var", /@@?[A-Za-z_]\w*|\$[A-Za-z_]\w*/y],
+  ["num", /\b\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?\b/y],
+  ["ident", /[A-Za-z_]\w*[?!]?/y],
+  ["pun", /[+\-*/=<>!&|^~?:;,.[\](){}%]/y],
+  ["ws", /\s+/y]
+];
+const yamlPats = [
+  ["com", /#[^\n]*/y],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /'(?:''|[^'\n])*'/y],
+  ["attr", /[A-Za-z_][\w.\-]*(?=:(?:\s|$))/y],
+  ["lt", /\b(?:true|false|null|True|False|Null|TRUE|FALSE|NULL|yes|no|on|off)\b/y],
+  ["num", /-?\b\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?\b/y],
+  ["var", /[&*][A-Za-z_][\w.\-]*/y],
+  ["ident", /[A-Za-z_][\w.\-]*/y],
+  ["pun", /[:\-?[\]{},>|!]/y],
+  ["ws", /\s+/y]
+];
+const tomlPats = [
+  ["com", /#[^\n]*/y],
+  ["sel", /^\[\[?[^\]\n]*\]\]?/my],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /'[^'\n]*'/y],
+  ["lt", /\b(?:true|false)\b/y],
+  ["attr", /[A-Za-z_][\w.\-]*(?=[ \t]{0,2}=)/y],
+  ["num", /[+-]?\b\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?\b/y],
+  ["ident", /[A-Za-z_][\w.\-]*/y],
+  ["pun", /[=[\]{},.:+\-]/y],
+  ["ws", /\s+/y]
+];
+const diffPats = [
+  ["com", /^(?:diff |index |similarity |rename |new file|deleted file|old mode|new mode|Binary |@@|---|\+\+\+)[^\n]*/my],
+  ["str", /^\+[^\n]*/my],
+  ["kw", /^-[^\n]*/my],
+  // `ws` FIRST, ahead of the context-line catch-all: the streaming checkpoint
+  // (hi-inc.ts) cuts a whitespace run in two just after a newline and re-matches
+  // `\s+` from there, so no other pattern may be able to start on whitespace —
+  // `[^\n]+` would happily swallow a line's indentation and re-tokenize the cut
+  // differently from a run that never stopped.
+  ["ws", /\s+/y],
+  ["txt", /[^\n]+/y]
+];
+const dockerPats = [
+  ["com", /#[^\n]*/y],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /'[^'\n]*'/y],
+  ["var", /\$\{[^}\n]*\}|\$\w+/y],
+  ["num", /\b\d+\b/y],
+  ["ident", /[A-Za-z_][\w.\-]*/y],
+  ["pun", /[|&;<>(){}[\]=,:@/\\*+]/y],
+  ["ws", /\s+/y]
+];
+const LANGS = /* @__PURE__ */ Object.create(null);
+const REGISTERED = /* @__PURE__ */ new Set();
+function def(names, pats, kw) {
+  const entry = kw === void 0 ? { pats } : { pats, kw };
+  for (const name of names.split(" ")) LANGS[name] = entry;
+}
+def("js javascript jsx", jsPats, KEYWORDS_JS);
+def("ts tsx typescript", jsPats, KEYWORDS_TS);
+def("rust rs", rustPats, KEYWORDS_RUST);
+def("py python", pyPats, KEYWORDS_PY);
+def("go", goPats, KEYWORDS_GO);
+def("bash sh shell", bashPats, KEYWORDS_BASH);
+def("json", jsonPats);
+def("sql", sqlPats, KEYWORDS_SQL);
+def("html xml", htmlPats);
+def("css", cssPats);
+def("java", cFamilyPats, KEYWORDS_JAVA);
+def("c", cPats, KEYWORDS_C);
+def("cpp c++", cPats, KEYWORDS_CPP);
+def("cs csharp", cFamilyPats, KEYWORDS_CS);
+def("swift", cFamilyPats, KEYWORDS_SWIFT);
+def("kt kotlin", cFamilyPats, KEYWORDS_KOTLIN);
+def("php", phpPats, KEYWORDS_PHP);
+def("rb ruby", rubyPats, KEYWORDS_RUBY);
+def("yaml yml", yamlPats);
+def("toml", tomlPats);
+def("diff", diffPats);
+def("dockerfile", dockerPats, KEYWORDS_DOCKER);
+const BUILTIN = Object.keys(LANGS);
+const BUILTIN_ENTRIES = new Map(Object.entries(LANGS));
+function __builtinLangs() {
+  return BUILTIN.slice();
+}
+function isRegisteredLang(lang) {
+  return REGISTERED.has(lang.toLowerCase());
+}
+function __resetLanguages() {
+  for (const k of Object.keys(LANGS)) delete LANGS[k];
+  for (const [k, v] of BUILTIN_ENTRIES) LANGS[k] = v;
+  REGISTERED.clear();
+}
+function hasLang(lang) {
+  return LANGS[lang.toLowerCase()] !== void 0;
+}
 function escapeHtml(s) {
   const n = s.length;
   let i = 0;
@@ -188,7 +342,7 @@ function stepHighlight(code, lang, state, chars, sink) {
       const [cls, re] = pats[i];
       re.lastIndex = pos;
       const m = re.exec(code);
-      if (!m || m.index !== pos) continue;
+      if (!m || m.index !== pos || m[0].length === 0) continue;
       const text = m[0];
       const after = pos + text.length;
       let finalCls = cls;
@@ -233,12 +387,79 @@ function highlight(code, lang) {
   }
   return state.out;
 }
+const TOKEN_CLASSES = /* @__PURE__ */ new Set([
+  "kw",
+  "str",
+  "rx",
+  "num",
+  "lt",
+  "com",
+  "fn",
+  "ty",
+  "mac",
+  "dec",
+  "attr",
+  "sel",
+  "tag",
+  "var",
+  "pun",
+  "txt",
+  "ident",
+  "ws"
+]);
+function registerLanguage(names, def_) {
+  const list = typeof names === "string" ? [names] : names;
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new TypeError("registerLanguage: expected a language name or a non-empty array of names");
+  }
+  for (const name of list) {
+    if (typeof name !== "string" || name === "") {
+      throw new TypeError("registerLanguage: every language name must be a non-empty string");
+    }
+  }
+  if (def_ === null || typeof def_ !== "object" || !Array.isArray(def_.pats) || def_.pats.length === 0) {
+    throw new TypeError("registerLanguage: `pats` must be a non-empty array of [token, regexp] pairs");
+  }
+  const pats = [];
+  for (let i = 0; i < def_.pats.length; i++) {
+    const pair = def_.pats[i];
+    if (!Array.isArray(pair) || pair.length < 2) {
+      throw new TypeError(`registerLanguage: pattern ${i} must be a [token, regexp] pair`);
+    }
+    const [cls, re] = pair;
+    if (typeof cls !== "string" || !TOKEN_CLASSES.has(cls)) {
+      throw new TypeError(
+        `registerLanguage: pattern ${i} has unknown token class ${JSON.stringify(cls)} \u2014 expected one of ${[...TOKEN_CLASSES].join(", ")}`
+      );
+    }
+    if (!(re instanceof RegExp) || !re.sticky) {
+      throw new TypeError(`registerLanguage: pattern ${i} (${cls}) must be a sticky RegExp (the \`y\` flag)`);
+    }
+    re.lastIndex = 0;
+    if (re.exec("") !== null) {
+      throw new TypeError(`registerLanguage: pattern ${i} (${cls}) matches the empty string`);
+    }
+    pats.push([cls, re]);
+  }
+  const kw = def_.kw === void 0 ? void 0 : new Set(def_.kw);
+  const entry = kw === void 0 ? { pats } : { pats, kw };
+  for (const name of list) {
+    const key = name.toLowerCase();
+    LANGS[key] = entry;
+    REGISTERED.add(key);
+  }
+}
 function supportedLangs() {
   return Object.keys(LANGS);
 }
 export {
+  __builtinLangs,
+  __resetLanguages,
   escapeHtml,
+  hasLang,
   highlight,
+  isRegisteredLang,
+  registerLanguage,
   stepHighlight,
   supportedLangs
 };

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  *   - BrookClient: owns one Web Worker + Rust parser per stream
  *   - BrookMarkdown: React component that subscribes to a BrookClient
  *   - Block / Patch / BlockKind types
- *   - highlight: optional in-house syntax highlighter
+ *   - highlight / registerLanguage: optional in-house syntax highlighter
  *
  * Typical use (React + a Vite-like bundler):
  *
@@ -18,6 +18,7 @@
 export { BrookClient, BrookPool, getDefaultPool, sourceFingerprint } from "./client.js";
 export type { PersistableSnapshot } from "./client.js";
 export { BrookMarkdown, useBrookStream, useBrookMarkdownString } from "./react.js";
-export { highlight, supportedLangs } from "./hi.js";
+export { highlight, registerLanguage, supportedLangs } from "./hi.js";
+export type { LanguageDef } from "./hi.js";
 export { htmlToReact, parseTrustedHtml, safeUrl, wrapLink } from "./html-to-react.js";
-export type { Block, BlockKind, BlockKindTag, BlockComponentProps, Components, Patch, FromWorker, ToWorker, WorkerLike, ParserConfig, Align, TableCell, TableData, HeadingData, CodeBlockData, MathBlockData, ListData, NestedBlock, ContainerData, Decorator, UrlTransform, BrookNode, } from "./types.js";
+export type { Block, BlockKind, BlockKindTag, BlockComponentProps, Components, Patch, FromWorker, ToWorker, WorkerLike, ParserConfig, Align, TableCell, TableData, HeadingData, CodeBlockData, MathBlockData, ListData, NestedBlock, ContainerData, Decorator, UrlTransform, LinkClickInfo, BrookNode, } from "./types.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 import { BrookClient, BrookPool, getDefaultPool, sourceFingerprint } from "./client.js";
 import { BrookMarkdown, useBrookStream, useBrookMarkdownString } from "./react.js";
-import { highlight, supportedLangs } from "./hi.js";
+import { highlight, registerLanguage, supportedLangs } from "./hi.js";
 import { htmlToReact, parseTrustedHtml, safeUrl, wrapLink } from "./html-to-react.js";
 export {
   BrookClient,
@@ -10,6 +10,7 @@ export {
   highlight,
   htmlToReact,
   parseTrustedHtml,
+  registerLanguage,
   safeUrl,
   sourceFingerprint,
   supportedLangs,

package/dist/react.d.ts

@@ -1,6 +1,7 @@
+import { type MouseEvent as ReactMouseEvent } from "react";
 import type { Block, BlockComponentProps, Components } from "./types.js";
 import { BrookClient } from "./client.js";
-import type { Decorator, ParserConfig, RenderMetricsHook, UrlTransform } from "./types-core.js";
+import type { Decorator, LinkClickInfo, ParserConfig, RenderMetricsHook, UrlTransform } from "./types-core.js";
 /**
  * Render a streaming markdown document from a BrookClient. Each block is its
  * own memoized React node keyed by its stable parser-assigned ID, so React
@@ -137,13 +138,23 @@ interface BrookMarkdownProps {
      * the whole fence per chunk). The settled markup is byte-identical either way
      * — only the tail's colours are provisional, and they may shift as bytes
      * arrive (`"hello` is a stray quote plus an identifier until its closing quote
-     * lands). Set `false` for the pre-0.27 behaviour: plain body until close.
+     * lands).
+     *
+     * - `true` / omitted — `"wavefront"`.
+     * - `"wavefront"` — the frozen prefix is coloured; the speculative tail (in
+     *   practice the line being typed) renders as plain text until its line
+     *   completes. The tail is one text node updated through its character data,
+     *   which is what keeps the option's cost at the DOM near zero.
+     * - `"eager"` — colour the tail on every patch too, by rebuilding its span
+     *   markup each time. Sub-line colour latency, ~all of the option's
+     *   style/layout cost.
+     * - `false` — the pre-0.27 behaviour: plain body until close.
      *
      * No effect on SSR (the server renders closed blocks only), and none at all
      * when `components.CodeBlock` / `components.pre` / `components.code` take over
      * the block — an override bypasses the built-in highlighter entirely.
      */
-    streamingHighlight?: boolean;
+    streamingHighlight?: boolean | "wavefront" | "eager";
     /**
      * @internal TEST-ONLY. Turn off the incremental apply paths (the open code
      * block's frozen/tail mirror and the open generic block's delta splice) so
@@ -214,6 +225,21 @@ interface BrookMarkdownProps {
      * supplied. Guard with `if (!block) return <>{children}</>`.
      */
     onBlockError?: (error: Error, info: BlockErrorInfo) => void;
+    /**
+     * Called when a rendered link is clicked — for in-app routing, analytics, or
+     * an "open citations in a drawer" affordance.
+     *
+     * DELEGATED: exactly ONE `onClick` sits on the `.brook-md` root and the anchor
+     * is resolved from the event target. No per-anchor prop is ever added, so this
+     * is invisible to the per-block memo — unlike `components` / `decorators`, a
+     * fresh closure each render re-renders NO blocks (hoisting is tidy, but costs
+     * you nothing here).
+     *
+     * The handler gets React's synthetic event, so `event.preventDefault()`
+     * cancels the navigation. A still-streaming anchor (`data-brook-pending`:
+     * label rendered, URL not yet arrived) is never reported.
+     */
+    onLinkClick?: (event: ReactMouseEvent<HTMLElement>, link: LinkClickInfo) => void;
 }
 /** Context handed to {@link BrookMarkdownProps.onBlockError}. */
 export interface BlockErrorInfo {
@@ -289,7 +315,7 @@ interface BlockViewProps {
     virtualize?: boolean;
     sanitize?: (html: string) => string;
     childMemo?: boolean;
-    streamingHighlight?: boolean;
+    streamingHighlight?: boolean | "wavefront" | "eager";
     /** @internal TEST-ONLY — see BrookMarkdownProps.__fullRebuild. */
     __fullRebuild?: boolean;
     onRenderMetrics?: RenderMetricsHook;

package/dist/react.js

@@ -64,7 +64,8 @@ function BrookMarkdownFromClient({
   deferTail,
   decorators,
   urlTransform,
-  onBlockError
+  onBlockError,
+  onLinkClick
 }) {
   const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
   useUnstablePropWarning("decorators", decorators);
@@ -84,15 +85,30 @@ function BrookMarkdownFromClient({
     } : void 0,
     [client, onRenderMetrics]
   );
+  const rootRef = useRef(null);
+  const handleLinkClick = onLinkClick ? (e) => {
+    const root = rootRef.current;
+    const el = e.target;
+    if (!root || !el || typeof el.closest !== "function") return;
+    const a = el.closest("a[href]");
+    if (!a || !root.contains(a) || a.hasAttribute("data-brook-pending")) return;
+    onLinkClick(e, {
+      href: a.getAttribute("href") ?? "",
+      text: a.textContent ?? "",
+      element: a
+    });
+  } : void 0;
   const rootClass = isDeferring ? className ? `brook-md brook-deferred ${className}` : "brook-md brook-deferred" : className ? `brook-md ${className}` : "brook-md";
   return /* @__PURE__ */ jsxs(
     "div",
     {
+      ref: rootRef,
       className: rootClass,
       id,
       role,
       "aria-live": ariaLive,
       "aria-atomic": ariaAtomic,
+      onClick: handleLinkClick,
       children: [
         rendered.map(
           (b, i) => (

package/dist/renderers/CodeBlock.d.ts

@@ -9,8 +9,9 @@ interface Props {
      * as the highlight itself. Absent (blockData off) the HTML is decoded here.
      */
     code?: string;
-    /** Highlight the block while it is still open. Default true. */
-    streamingHighlight?: boolean;
+    /** Highlight the block while it is still open. Default true (`"wavefront"`);
+     *  `"eager"` colours the speculative tail on every patch; `false` opts out. */
+    streamingHighlight?: boolean | "wavefront" | "eager";
     /**
      * The block this markup came from, when the renderer is driven by the stream.
      * Only used to apply the wire's `html_delta` to the PLAIN escaped body of an

package/dist/renderers/CodeBlock.js

@@ -3,7 +3,7 @@ import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useStat
 import { highlight } from "../hi.js";
 import { highlightDeferred, highlightWithin } from "../hi-defer.js";
 import { createInc, incHighlight, incSeed } from "../hi-inc.js";
-import { newIncCode, paintIncCode } from "../splice.js";
+import { incView, newIncCode, paintIncCode } from "../splice.js";
 import { useHtmlSplice } from "../react-splice.js";
 import { extractLang } from "../block-props.js";
 function decodeText(html) {
@@ -21,6 +21,7 @@ function CodeBlockImpl({ html, open, code, streamingHighlight, block, __fullRebu
   const lang = extractLang(html) || "text";
   const text = useMemo(() => open ? "" : code ?? decodeText(html), [html, open, code]);
   const streaming = open && streamingHighlight !== false;
+  const tailMode = streamingHighlight === "eager" ? "eager" : "wavefront";
   const openText = useMemo(
     () => streaming ? code ?? decodeText(html) : "",
     [streaming, code, html]
@@ -48,8 +49,18 @@ function CodeBlockImpl({ html, open, code, streamingHighlight, block, __fullRebu
       incRef.current = st;
     }
     const markup = st === null ? null : incHighlight(st, openText);
-    setInc(markup === null ? null : { lang, html: markup });
-  }, [streaming, openText, lang]);
+    setInc(
+      markup === null ? null : {
+        lang,
+        html: markup,
+        // `view` is only ever WRITTEN by the full-rebuild reference, which
+        // has to show the same thing the mirror paints or the parity fuzz
+        // would be comparing two different visual contracts. The mirrored
+        // path derives the tail itself, so it does not pay for this.
+        view: __fullRebuild ? incView(st, markup, tailMode) : markup
+      }
+    );
+  }, [streaming, openText, lang, tailMode, __fullRebuild]);
   const [slow, setSlow] = useState(null);
   useEffect(() => {
     if (!text || sync !== null) {
@@ -75,7 +86,7 @@ function CodeBlockImpl({ html, open, code, streamingHighlight, block, __fullRebu
   }, [text, lang, sync]);
   const settled = sync ?? (slow !== null && slow.text === text && slow.lang === lang ? slow.html : null);
   const streamed = streaming && inc !== null && inc.lang === lang ? inc.html : null;
-  const highlighted = settled ?? streamed;
+  const highlighted = settled ?? (streamed === null ? null : inc.view);
   const mirrored = settled === null && streamed !== null && !__fullRebuild;
   useIsoLayoutEffect(() => {
     if (!mirrored) {
@@ -85,14 +96,16 @@ function CodeBlockImpl({ html, open, code, streamingHighlight, block, __fullRebu
     const node = codeRef.current;
     const st = incRef.current;
     if (node === null || st === null || streamed === null) return;
+    const markup = st.html;
+    if (markup === null) return;
     let m = mirrorRef.current;
-    if (m === null || m.code !== node || m.lang !== lang) {
+    if (m === null || m.code !== node || m.lang !== lang || m.mode !== tailMode) {
       node.innerHTML = "";
-      m = newIncCode(node, lang, st);
+      m = newIncCode(node, lang, st, tailMode);
       mirrorRef.current = m;
     }
-    if (!paintIncCode(m, st, streamed)) {
-      node.innerHTML = streamed;
+    if (!paintIncCode(m, st, markup)) {
+      node.innerHTML = incView(st, markup, tailMode);
       mirrorRef.current = null;
     }
   });

package/dist/solid.js

@@ -8,6 +8,7 @@ function mountSolid(getProps, container, registerCleanup) {
     sanitize: p.sanitize,
     virtualize: p.virtualize,
     stickToBottom: p.stickToBottom,
+    onLinkClick: p.onLinkClick,
     highlightCode: p.highlightCode,
     batch: p.batch
   });

package/dist/splice.d.ts

@@ -63,6 +63,41 @@ export declare function noteSplice(next: Block, prev: Block, keep: number): void
  * @internal Renderer-only; not part of the public API.
  */
 export declare function spliceKeep(from: Block, to: Block): number | undefined;
+/**
+ * How an open fence's SPECULATIVE TAIL is painted. The frozen prefix is painted
+ * the same way either way — appended once, never touched again.
+ *
+ * - `"wavefront"` (the default) — the tail is ONE TEXT NODE holding the plain
+ *   source, updated per patch through its character data. No elements are
+ *   created, no markup is parsed, and nothing before it is disturbed, so a patch
+ *   costs the browser a text measure instead of a style/layout pass over a
+ *   freshly built span tree. Colour therefore arrives at the checkpoint — in
+ *   practice one source line behind the stream head.
+ * - `"eager"` — the tail is its highlighted MARKUP, re-parsed on every patch.
+ *   Colour is immediate, at the cost of rebuilding a span-dense subtree per
+ *   frame. This is what the mirror always did.
+ *
+ * Both settle to the same bytes: the tail is thrown away and re-derived at every
+ * patch regardless, and the close-time markup comes from the frozen prefix plus
+ * one final tokenizer run (see hi-inc.ts).
+ */
+export type TailMode = "wavefront" | "eager";
+/**
+ * The markup an open fence's `<code>` holds under `mode` — what the mirror
+ * paints incrementally, and what a caller that cannot mirror (a rebuild, the
+ * test-only full-rebuild reference) has to write in one go so the two agree.
+ *
+ * For `"eager"` that is hi-inc's markup verbatim. For `"wavefront"` the frozen
+ * prefix keeps its spans and the tail is the escaped source, which is exactly
+ * what the tail TEXT NODE serializes to.
+ *
+ * The wavefront tail comes from `st.text`/`st.c` rather than from `markup`,
+ * because the plain source is not recoverable from the tail's markup without
+ * re-parsing it. That is only sound while `markup` is the very string this state
+ * just produced, so a stale pair is handed back untouched rather than paired
+ * with a tail it does not belong to.
+ */
+export declare function incView(st: IncState, markup: string, mode: TailMode): string;
 /**
  * The live `<code>` of an OPEN code block, split the way hi-inc splits its
  * markup: a **frozen** run of children (proven immutable — appended once and
@@ -71,15 +106,17 @@ export declare function spliceKeep(from: Block, to: Block): number | undefined;
  *
  * The two regions are NOT wrapped in elements — `frozenEnd` is simply the last
  * child that belongs to the frozen run — so the resulting `innerHTML` is
- * byte-identical to the `code.innerHTML = markup` this replaces. Only the node
- * *count* differs (a splice can leave two adjacent text nodes where a one-shot
- * parse would have made one), which serializes the same and is exactly what a
- * browser does for any streamed append.
+ * byte-identical to the `code.innerHTML = incView(...)` this replaces. Only the
+ * node *count* differs (a splice can leave two adjacent text nodes where a
+ * one-shot parse would have made one), which serializes the same and is exactly
+ * what a browser does for any streamed append.
  */
 export interface IncCode {
     code: Element;
     /** The language the mirror was built for; a change invalidates it. */
     lang: string;
+    /** How the tail is painted; fixed for the mirror's whole life. */
+    mode: TailMode;
     /** Last child of the frozen run — everything after it is the tail. */
     frozenEnd: ChildNode | null;
     /** Chars of `IncState.frozenHtml` already mirrored into the DOM. */
@@ -93,21 +130,31 @@ export interface IncCode {
      *  else on the streaming path combined. */
     frozenEnd0: ChildNode | null;
     frozenLen0: number;
-    /** The tail markup currently in the DOM, so an unchanged tail is not rewritten. */
+    /** What is on screen after `frozenEnd`, so an unchanged tail is not rewritten:
+     *  the tail MARKUP in `"eager"` mode, the tail SOURCE in `"wavefront"`. */
     tail: string;
+    /** `"wavefront"` only: the single text node carrying the tail source. Created
+     *  once per mirror and then only ever written through its character data —
+     *  that is the whole cost saving, so it is never replaced while it lives. */
+    tailText: Text | null;
 }
 /** A fresh, empty mirror for a `<code>` that has nothing painted into it yet. */
-export declare function newIncCode(code: Element, lang: string, st: IncState): IncCode;
+export declare function newIncCode(code: Element, lang: string, st: IncState, mode: TailMode): IncCode;
 /**
  * Mirror hi-inc's frozen/tail split into a live `<code>`: append whatever the
- * frozen prefix settled since the last patch, then replace the speculative
- * tail. Returns false when the mirror cannot be trusted (see the length
- * invariant below) so the caller falls back to a full node rebuild.
+ * frozen prefix settled since the last patch, then update the speculative tail.
+ * Returns false when the mirror cannot be trusted (see the invariants below) so
+ * the caller falls back to a full node rebuild.
  *
  * Cost per patch is |newly frozen| + |tail|. The frozen term sums, across the
  * whole stream, to one pass over the final markup; the tail is bounded by
- * hi-inc's CAP. That is what makes an open fence linear at the DOM, not just
- * at the tokenizer.
+ * hi-inc's CAP. That is what makes an open fence linear at the DOM, not just at
+ * the tokenizer.
+ *
+ * In `"wavefront"` mode the tail term is also the CHEAPEST shape the DOM has:
+ * one character-data write, no elements created and no markup parsed. Only a
+ * checkpoint advance parses anything, and then only the newly frozen slice — so
+ * span creation drops from (tail spans × patches) to one pass over the block.
  */
 export declare function paintIncCode(ic: IncCode, st: IncState, markup: string): boolean;
 /**