@vectojs/markdown 0.5.0 → 0.6.0

package/dist/index.mjs

@@ -3,6 +3,7 @@ import {
   BidiResolver,
   Entity,
   GlyphRasterAtlas,
+  OBJECT_REPLACEMENT,
   prepareContentGrid,
   SVGEntity,
   beginVectoUserTiming,
@@ -38,7 +39,10 @@ var StreamControllerImpl = class {
     this.signal = options.signal;
     this.onSignalAbort = () => this.abort(this.signal?.reason);
     if (this.signal?.aborted) this.abort(this.signal.reason);
-    else this.signal?.addEventListener("abort", this.onSignalAbort, { once: true });
+    else
+      this.signal?.addEventListener("abort", this.onSignalAbort, {
+        once: true
+      });
   }
   host;
   maxBufferedChars;
@@ -126,10 +130,33 @@ var StreamControllerImpl = class {
       return closePromise;
     }
     this.currentState = "closed";
-    this.cleanup();
-    this.resolveClose?.();
-    this.resolveClose = null;
-    this.rejectClose = null;
+    let settled;
+    try {
+      settled = this.host.onClose?.();
+    } catch (error) {
+      this.cleanup();
+      this.rejectPendingClose(error);
+      return closePromise;
+    }
+    if (settled === void 0) {
+      this.cleanup();
+      this.resolveClose?.();
+      this.resolveClose = null;
+      this.rejectClose = null;
+      return closePromise;
+    }
+    void Promise.resolve(settled).then(
+      () => {
+        this.cleanup();
+        this.resolveClose?.();
+        this.resolveClose = null;
+        this.rejectClose = null;
+      },
+      (error) => {
+        this.cleanup();
+        this.rejectPendingClose(error);
+      }
+    );
     return closePromise;
   }
   abort(reason) {
@@ -395,12 +422,6 @@ function createStreamController(host, options = {}) {
 }
 
 // src/Markdown.ts
-import { mathjax } from "mathjax-full/js/mathjax.js";
-import { TeX } from "mathjax-full/js/input/tex.js";
-import { SVG } from "mathjax-full/js/output/svg.js";
-import { liteAdaptor } from "mathjax-full/js/adaptors/liteAdaptor.js";
-import { RegisterHTMLHandler } from "mathjax-full/js/handlers/html.js";
-import { AllPackages } from "mathjax-full/js/input/tex/AllPackages.js";
 import { measureText, RichText, Stack, Table, Text, Image, UIComponent } from "@vectojs/ui";
 
 // src/MarkdownWorkerSource.ts
@@ -442,23 +463,183 @@ marked.use({
     }
   ]
 });
-var adaptor = liteAdaptor();
-RegisterHTMLHandler(adaptor);
-var tex = new TeX({ packages: AllPackages });
-var svg = new SVG({ fontCache: "local" });
-var htmlMathJax = mathjax.document("", { InputJax: tex, OutputJax: svg });
+var mathConverter = null;
+var mathLoad = null;
+function interop(mod, key) {
+  const ns = mod;
+  if (typeof ns?.[key] !== "undefined") return ns;
+  const fallback = ns?.default;
+  if (fallback && typeof fallback[key] !== "undefined") return fallback;
+  throw new Error(`mathjax-full module is missing export "${key}"`);
+}
+function preloadMathJax() {
+  if (mathLoad) return mathLoad;
+  mathLoad = (async () => {
+    const [mathjaxMod, texMod, svgMod, adaptorMod, handlerMod, packagesMod] = await Promise.all([
+      import("mathjax-full/js/mathjax.js"),
+      import("mathjax-full/js/input/tex.js"),
+      import("mathjax-full/js/output/svg.js"),
+      import("mathjax-full/js/adaptors/liteAdaptor.js"),
+      import("mathjax-full/js/handlers/html.js"),
+      import("mathjax-full/js/input/tex/AllPackages.js")
+    ]);
+    const { mathjax } = interop(mathjaxMod, "mathjax");
+    const { TeX } = interop(texMod, "TeX");
+    const { SVG } = interop(svgMod, "SVG");
+    const { liteAdaptor } = interop(adaptorMod, "liteAdaptor");
+    const { RegisterHTMLHandler } = interop(handlerMod, "RegisterHTMLHandler");
+    const { AllPackages } = interop(packagesMod, "AllPackages");
+    const adaptor = liteAdaptor();
+    RegisterHTMLHandler(adaptor);
+    const tex = new TeX({ packages: AllPackages });
+    const svg = new SVG({ fontCache: "local" });
+    const htmlMathJax = mathjax.document("", { InputJax: tex, OutputJax: svg });
+    mathConverter = (formula, displayMode) => convertMathToSVGDataURI(
+      formula,
+      displayMode,
+      (f, d) => adaptor.innerHTML(htmlMathJax.convert(f, { display: d }))
+    );
+  })().catch((e) => {
+    console.error("MathJax failed to load; formulas will render as TeX source", e);
+  });
+  return mathLoad;
+}
+function isMathJaxReady() {
+  return mathConverter !== null;
+}
+var EX_PER_EM = 0.4421;
+function exToPx(ex, fontSize) {
+  return ex * fontSize * EX_PER_EM;
+}
+function fontSizeFromFont(font) {
+  const pxIndex = font.indexOf("px");
+  if (pxIndex <= 0) return void 0;
+  let start = pxIndex;
+  while (start > 0) {
+    const ch = font[start - 1];
+    if (ch >= "0" && ch <= "9" || ch === ".") start--;
+    else break;
+  }
+  if (start === pxIndex) return void 0;
+  const size = parseFloat(font.slice(start, pxIndex));
+  return Number.isFinite(size) ? size : void 0;
+}
+var mathCache = /* @__PURE__ */ new Map();
+var MATH_CACHE_LIMIT = 256;
+var inlineMathRasters = /* @__PURE__ */ new Map();
+var inlineMathRasterWaiters = /* @__PURE__ */ new Set();
+function ensureInlineMathRaster(uri) {
+  const existing = inlineMathRasters.get(uri);
+  if (existing) return existing;
+  const entry = { decoded: false };
+  inlineMathRasters.set(uri, entry);
+  if (typeof globalThis.Image !== "undefined") {
+    const bitmap = new globalThis.Image();
+    bitmap.onload = () => {
+      entry.decoded = true;
+      for (const notify of inlineMathRasterWaiters) notify();
+    };
+    bitmap.src = uri;
+    entry.bitmap = bitmap;
+  }
+  return entry;
+}
+function paintInlineMath(uri, surface, box) {
+  const raster = ensureInlineMathRaster(uri);
+  if (!raster.decoded || !raster.bitmap) return;
+  surface.drawImage(raster.bitmap, box.x, box.y, box.width, box.height);
+}
+var MATH_LANGS = /* @__PURE__ */ new Set(["math", "latex", "tex"]);
+function containsInlineMath(token) {
+  if (token.type === "inlineMath") return true;
+  const anyToken = token;
+  if (Array.isArray(anyToken.tokens) && anyToken.tokens.some(containsInlineMath)) {
+    return true;
+  }
+  if (Array.isArray(anyToken.items) && anyToken.items.some(containsInlineMath)) {
+    return true;
+  }
+  if (Array.isArray(anyToken.header) && anyToken.header.some(containsInlineMath)) {
+    return true;
+  }
+  if (Array.isArray(anyToken.rows)) {
+    for (const row of anyToken.rows) {
+      if (Array.isArray(row) && row.some(containsInlineMath)) return true;
+    }
+  }
+  return false;
+}
+var FENCE_OPEN_RE = /^ {0,3}(`{3,}|~{3,})/;
+var FENCE_CLOSE_RE = /^ {0,3}(`+|~+)[ \t]*$/;
+function isFenceClosed(raw) {
+  const lines = raw.split("\n");
+  const open = FENCE_OPEN_RE.exec(lines[0]);
+  if (!open) return false;
+  const marker = open[1][0];
+  const minLen = open[1].length;
+  for (let i = 1; i < lines.length; i++) {
+    const close = FENCE_CLOSE_RE.exec(lines[i]);
+    if (close && close[1][0] === marker && close[1].length >= minLen) return true;
+  }
+  return false;
+}
+function paragraphHasImage(token) {
+  return token.tokens?.some((child) => child.type === "image") === true;
+}
+function lastIndexOfImage(tokens) {
+  for (let i = tokens.length - 1; i >= 0; i--) {
+    if (tokens[i].type === "image") return i;
+  }
+  return -1;
+}
+function expectedImageParagraphChildren(tokens) {
+  let children = 0;
+  let inTextRun = false;
+  for (const token of tokens) {
+    if (token.type === "image") {
+      children++;
+      inTextRun = false;
+    } else if (!inTextRun) {
+      children++;
+      inTextRun = true;
+    }
+  }
+  return children;
+}
+function rendersAsMath(token) {
+  return MATH_LANGS.has((token.lang ?? "").toLowerCase()) && token.text.trim() !== "" && isFenceClosed(token.raw);
+}
 function renderMathToSVGDataURI(formula, displayMode) {
+  const key = `${displayMode ? 1 : 0}\0${formula}`;
+  const hit = mathCache.get(key);
+  if (hit) return hit;
+  if (!mathConverter) return null;
+  const converted = mathConverter(formula, displayMode);
+  if (converted) {
+    if (mathCache.size >= MATH_CACHE_LIMIT) {
+      const oldest = mathCache.keys().next().value;
+      if (oldest !== void 0) mathCache.delete(oldest);
+    }
+    mathCache.set(key, converted);
+  }
+  return converted;
+}
+function convertMathToSVGDataURI(formula, displayMode, typeset) {
   try {
-    const node = htmlMathJax.convert(formula, { display: displayMode });
-    const svgString = adaptor.innerHTML(node);
+    const svgString = typeset(formula, displayMode);
     const wMatch = svgString.match(/width="([^"]+)ex"/);
     const hMatch = svgString.match(/height="([^"]+)ex"/);
     const wEx = wMatch ? parseFloat(wMatch[1]) : 10;
     const hEx = hMatch ? parseFloat(hMatch[1]) : 2;
-    const width = wEx * 8;
-    const height = hEx * 8;
+    const vMatch = svgString.match(/vertical-align:\s*(-?[\d.]+)ex/);
+    const depthEx = vMatch ? Math.max(0, -parseFloat(vMatch[1])) : 0;
     const base64 = btoa(unescape(encodeURIComponent(svgString)));
-    return { uri: `data:image/svg+xml;base64,${base64}`, width, height };
+    return {
+      uri: `data:image/svg+xml;base64,${base64}`,
+      widthEx: wEx,
+      heightEx: hEx,
+      depthEx
+    };
   } catch (e) {
     console.error("MathJax error", e);
     return null;
@@ -473,6 +654,7 @@ function runSyncFallback(entry) {
     entry.cb(0, lexMarkdown(entry.text, entry.userTiming), true);
   } catch (err) {
     console.warn("Markdown sync fallback parse failed", err);
+    entry.onDropped?.();
   }
 }
 if (typeof Worker !== "undefined") {
@@ -998,13 +1180,13 @@ function codeAtlas() {
 function decodeEntities(text) {
   return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
 }
-function collectSpans(tokens, inherited, theme, out) {
+function collectSpans(tokens, inherited, theme, out, blockFontSize) {
   for (const token of tokens) {
     switch (token.type) {
       case "strong": {
         const t = token;
         if (t.tokens) {
-          collectSpans(t.tokens, { ...inherited, bold: true }, theme, out);
+          collectSpans(t.tokens, { ...inherited, bold: true }, theme, out, blockFontSize);
         } else {
           out.push({
             text: decodeEntities(t.text),
@@ -1016,7 +1198,7 @@ function collectSpans(tokens, inherited, theme, out) {
       case "em": {
         const t = token;
         if (t.tokens) {
-          collectSpans(t.tokens, { ...inherited, italic: true }, theme, out);
+          collectSpans(t.tokens, { ...inherited, italic: true }, theme, out, blockFontSize);
         } else {
           out.push({
             text: decodeEntities(t.text),
@@ -1052,10 +1234,31 @@ function collectSpans(tokens, inherited, theme, out) {
       }
       case "inlineMath": {
         const t = token;
-        out.push({
-          text: decodeEntities(t.raw),
-          style: { ...inherited, color: "#fcd34d" }
-        });
+        const runSize = inherited.fontSize ?? blockFontSize ?? theme.fontSize;
+        const rendered = renderMathToSVGDataURI(t.text, false);
+        if (rendered) {
+          const uri = rendered.uri;
+          out.push({
+            text: OBJECT_REPLACEMENT,
+            style: inherited,
+            object: {
+              width: exToPx(rendered.widthEx, runSize),
+              height: exToPx(rendered.heightEx, runSize),
+              depth: exToPx(rendered.depthEx, runSize),
+              // The TeX source is the accessible name: without it a screen reader
+              // receives only the invisible U+FFFC sentinel.
+              alt: t.text,
+              // Without this the box is reserved and stays empty. The engine does
+              // not draw objects, and nothing else in the tree holds the raster.
+              paint: (surface, box) => paintInlineMath(uri, surface, box)
+            }
+          });
+        } else {
+          out.push({
+            text: decodeEntities(t.raw),
+            style: { ...inherited, color: "#fcd34d" }
+          });
+        }
         break;
       }
       case "link": {
@@ -1066,7 +1269,7 @@ function collectSpans(tokens, inherited, theme, out) {
           color: "#38bdf8"
         };
         if (t.tokens && t.tokens.length > 0) {
-          collectSpans(t.tokens, linkStyle, theme, out);
+          collectSpans(t.tokens, linkStyle, theme, out, blockFontSize);
         } else {
           out.push({ text: decodeEntities(t.text), style: linkStyle });
         }
@@ -1075,7 +1278,7 @@ function collectSpans(tokens, inherited, theme, out) {
       case "text": {
         const t = token;
         if ("tokens" in t && t.tokens?.length) {
-          collectSpans(t.tokens, inherited, theme, out);
+          collectSpans(t.tokens, inherited, theme, out, blockFontSize);
         } else {
           const decoded = decodeEntities(t.text);
           if (decoded) {
@@ -1098,10 +1301,37 @@ function collectSpans(tokens, inherited, theme, out) {
     }
   }
 }
+function findUnclosedInline(text) {
+  let best = null;
+  const tick = text.lastIndexOf("`");
+  if (tick !== -1 && tick < text.length - 1) {
+    return { kind: "codespan", at: tick, contentAt: tick + 1 };
+  }
+  if (tick !== -1) return null;
+  const emphasis = /(\*{1,2}(?!\*)|_{1,2}(?!_))(?=[^\s])/g;
+  for (let match = emphasis.exec(text); match !== null; match = emphasis.exec(text)) {
+    const marker = match[1];
+    const at = match.index;
+    if (marker[0] === "_" && at > 0 && /[\w]/.test(text[at - 1])) continue;
+    best = {
+      kind: marker.length === 2 ? "strong" : "em",
+      at,
+      contentAt: at + marker.length
+    };
+  }
+  const bracket = text.lastIndexOf("[");
+  if (bracket !== -1 && bracket < text.length - 1 && (best === null || bracket > best.at)) {
+    const closed = /\]\([^)]*\)/.test(text.slice(bracket));
+    if (!closed) {
+      best = { kind: "link", at: bracket, contentAt: bracket + 1 };
+    }
+  }
+  return best;
+}
 function renderInlineToRichText(tokens, fallbackText, font, color, maxWidth, theme, selectable, onLinkClick) {
   const spans = [];
   if (tokens && tokens.length > 0) {
-    collectSpans(tokens, {}, theme, spans);
+    collectSpans(tokens, {}, theme, spans, fontSizeFromFont(font));
   }
   if (spans.length === 0) {
     spans.push({ text: decodeEntities(fallbackText) });
@@ -1133,6 +1363,51 @@ var Markdown = class extends UIComponent {
   onLayoutUpdated;
   rawMarkdown;
   streamController = null;
+  /**
+   * Trailing-unclosed-syntax policy of the active stream, or `'literal'` when no
+   * stream is open.
+   *
+   * Held here rather than read back off the controller because it is a rendering
+   * concern: `StreamController` owns buffering and pacing and has no view of the
+   * entity tree, while the guess is a transform applied where spans are built.
+   */
+  streamIncompleteMode = "literal";
+  /** End-of-stream callback of the active stream, if it supplied one. */
+  streamOnStable = null;
+  /**
+   * The trailing paragraph entity currently showing an optimistic guess, plus the
+   * token it was rendered from.
+   *
+   * Both halves are needed. The entity is what must be re-rendered to drop the
+   * guess; the token is what it must be re-rendered FROM, and it is the only
+   * copy — `this.tokens` has already moved on by the time an unwind is decided.
+   * `null` means no guess is live, which is the state every `'literal'` stream
+   * and every closed stream stays in.
+   */
+  optimisticTail = null;
+  /** Resolvers waiting for every in-flight worker append to have been applied. */
+  appendSettledWaiters = [];
+  /** True only inside an `onStable` callback, to reject reentrant mutation. */
+  inStableCallback = false;
+  /** Set by {@link destroy} so late settlement work skips a torn-down tree. */
+  isDestroyed = false;
+  /**
+   * This instance's entry in {@link inlineMathRasterWaiters}, or `undefined` if it
+   * has never rendered inline math.
+   *
+   * Subscribed lazily so a document without formulas costs nothing, and held as a
+   * field only so {@link destroy} can remove the exact closure it added.
+   */
+  inlineMathRepaint;
+  /**
+   * True while this document is waiting on the lazy MathJax load.
+   *
+   * Tracked per instance rather than read off the module state because it also
+   * gates settlement: `await close()` and `onStable` must not resolve while a
+   * formula is still showing TeX source, or a caller doing expensive one-time
+   * work on a "final" document would measure and export placeholder boxes.
+   */
+  mathLoadPending = false;
   _userTiming;
   tokens = [];
   // At most one worker lex request in flight at a time. Required for the
@@ -1290,21 +1565,44 @@ var Markdown = class extends UIComponent {
       {
         append: (chunk) => this.appendMarkdownCore(chunk),
         release: (released) => {
-          if (this.streamController === released) this.streamController = null;
+          if (this.streamController !== released) return;
+          this.streamController = null;
+          this.streamIncompleteMode = "literal";
+          this.streamOnStable = null;
+          this.unwindOptimisticTail();
+        },
+        onClose: async () => {
+          await this.waitForAppendSettled();
+          if (this.isDestroyed) return;
+          this.unwindOptimisticTail();
+          const onStable = this.streamOnStable;
+          if (!onStable) return;
+          this.inStableCallback = true;
+          try {
+            onStable(Array.from(this.content.children));
+          } finally {
+            this.inStableCallback = false;
+          }
         }
       },
       options
     );
-    if (controller.state === "open") this.streamController = controller;
+    if (controller.state === "open") {
+      this.streamController = controller;
+      this.streamIncompleteMode = options.incompleteMode ?? "literal";
+      this.streamOnStable = options.onStable ?? null;
+    }
     return controller;
   }
   /** Replace all markdown content (full rebuild). */
   setContent(markdown) {
+    this.assertNotInStableCallback("setContent");
     this.streamController?.abort(new Error("Markdown content was replaced"));
     for (const id of this.pendingWorkerIds) workerCallbacks.delete(id);
     this.pendingWorkerIds.clear();
     this.appendInFlight = false;
     this.appendPending = false;
+    this.flushAppendSettledWaiters();
     this.rawMarkdown = markdown;
     this.workerSourceLen = 0;
     while (this.content.children.length > 0) {
@@ -1320,12 +1618,35 @@ var Markdown = class extends UIComponent {
    * the whole subtree alive until the worker replied), then recurse into the
    * content subtree via `super.destroy()` so every block's resources are freed.
    */
+  /**
+   * Repaint this document when an inline formula's raster finishes decoding.
+   *
+   * Idempotent — called on every render of a math-bearing token, and the set holds
+   * one closure per instance.
+   */
+  subscribeInlineMathRepaint() {
+    if (this.inlineMathRepaint || this.isDestroyed) return;
+    const repaint = () => {
+      if (this.isDestroyed) return;
+      this.scene?.markDirty();
+    };
+    this.inlineMathRepaint = repaint;
+    inlineMathRasterWaiters.add(repaint);
+  }
   destroy() {
+    this.isDestroyed = true;
+    this.optimisticTail = null;
     this.streamController?.destroy();
     for (const id of this.pendingWorkerIds) workerCallbacks.delete(id);
     this.pendingWorkerIds.clear();
     this.appendInFlight = false;
     this.appendPending = false;
+    this.mathLoadPending = false;
+    this.flushAppendSettledWaiters();
+    if (this.inlineMathRepaint) {
+      inlineMathRasterWaiters.delete(this.inlineMathRepaint);
+      this.inlineMathRepaint = void 0;
+    }
     markdownWorker?.postMessage({
       instance: this.workerInstanceId,
       dispose: true
@@ -1514,6 +1835,7 @@ var Markdown = class extends UIComponent {
   }
   /** Append a markdown chunk incrementally. Reuses unchanged prefix entities. */
   appendMarkdown(chunk) {
+    this.assertNotInStableCallback("appendMarkdown");
     this.streamController?.flush();
     return this.appendMarkdownCore(chunk);
   }
@@ -1582,6 +1904,7 @@ var Markdown = class extends UIComponent {
           this.appendPending = false;
           this.dispatchAppend();
         }
+        this.flushAppendSettledWaiters();
       },
       // The worker can't trust what it holds for this request; retry it once with
       // the full text and raws attached. `this.tokens` is untouched (no
@@ -1592,6 +1915,20 @@ var Markdown = class extends UIComponent {
         this.workerSourceLen = 0;
         this.dispatchAppend(true);
       },
+      // Neither the worker nor the fallback lexer could produce tokens for this
+      // request, so `this.tokens` stays as it was. Only the in-flight bookkeeping
+      // needs unwinding — including any coalesced chunk waiting behind it, which
+      // still has to be attempted.
+      onDropped: () => {
+        this.pendingWorkerIds.delete(id);
+        this.appendInFlight = false;
+        this.workerSourceLen = 0;
+        if (this.appendPending) {
+          this.appendPending = false;
+          this.dispatchAppend(true);
+        }
+        this.flushAppendSettledWaiters();
+      },
       text: this.rawMarkdown,
       userTiming: this._userTiming
     });
@@ -1613,6 +1950,647 @@ var Markdown = class extends UIComponent {
       }
     });
   }
+  /**
+   * Spans for one paragraph token exactly as `marked` produced it.
+   *
+   * The literal baseline: what every release renders, and what an optimistic
+   * guess is unwound back to.
+   */
+  literalParagraphSpans(token) {
+    const spans = [];
+    if (token.tokens && token.tokens.length > 0) {
+      collectSpans(token.tokens, {}, this.theme, spans);
+    }
+    if (spans.length === 0) spans.push({ text: token.text });
+    return spans;
+  }
+  /**
+   * Update a reused blockquote's tail child in place, or report that it cannot be.
+   *
+   * The render arm builds `container[border, innerStack]` where every inner block
+   * sits in its own single-child `wrapper`, so the tail entity is
+   * `innerStack.children.at(-1).children[0]`. Only the LAST inner block may be
+   * updated: the inner token list is prefix-stable exactly like the top level (a
+   * growing quote keeps its earlier blocks byte-identical), so anything before the
+   * tail is untouched and anything more complicated than a changed tail falls back
+   * to the caller's rebuild.
+   *
+   * Returns `false` without mutating anything when the shape is not the simple
+   * grow-the-tail case, which is the signal for the caller to rebuild. Every early
+   * return has to leave the entity untouched, or a rejected reuse would leave a
+   * half-updated quote on screen.
+   */
+  /**
+   * Build one list item's spans: inline content plus its marker.
+   *
+   * Shared by the `list` render arm and the streamed-reuse path below, because
+   * the two must produce byte-identical spans — a reused list that disagreed with
+   * a rebuilt one about its marker or its entity decoding would make a streamed
+   * document differ from the same source pasted at once.
+   */
+  /**
+   * Inline spans for one table cell.
+   *
+   * Always returns at least one span. A cell whose markup collapses to nothing —
+   * an empty cell, but also a bare `<span>`, an image, or an HTML comment, none
+   * of which `collectSpans` emits for — falls back to its decoded source text,
+   * which is what the previous string-returning path rendered. That guarantee is
+   * what lets every cell be a `RichText`: an empty cell would otherwise become a
+   * `Text`, and since `Text` has `setText` while `RichText` has `setSpans` and
+   * nothing converts between them, a cell that starts empty and later gains
+   * content could not be updated in place. A streamed table needs exactly that,
+   * because `marked` materializes a partial row as a full row of empty cells and
+   * then fills them one at a time.
+   */
+  tableCellSpans(cell, t) {
+    const spans = [];
+    collectSpans(cell.tokens, {}, t, spans);
+    if (spans.length === 0) spans.push({ text: decodeEntities(cell.text) });
+    return spans;
+  }
+  /**
+   * Spans for one run of consecutive non-image inline tokens.
+   *
+   * A paragraph holding an image renders as a `Stack` of alternating text runs
+   * and images, and this is one text run. Shared by the render arm and
+   * {@link updateImageParagraph} so a reused run cannot drift from a rebuilt one.
+   *
+   * The empty fallback mirrors `renderInlineToRichText('', …)`, which the render
+   * arm passed for these runs: a run is only created when it has at least one
+   * token, so the fallback is for tokens that emit no spans at all rather than
+   * for an empty run.
+   */
+  inlineRunSpans(tokens, t) {
+    const spans = [];
+    if (tokens.length > 0) collectSpans(tokens, {}, t, spans);
+    if (spans.length === 0) spans.push({ text: "" });
+    return spans;
+  }
+  /** One text run of an image-bearing paragraph, as both paths build it. */
+  inlineRunRichText(tokens, availableWidth, t) {
+    return new RichText(this.inlineRunSpans(tokens, t), {
+      font: `${t.fontSize}px ${t.bodyFont}`,
+      color: t.textColor,
+      maxWidth: availableWidth,
+      linkColor: "#38bdf8",
+      selectable: this.selectable,
+      onLinkClick: this.onLinkClick
+    });
+  }
+  /**
+   * One image inside a paragraph, sized by a guess until its bitmap decodes.
+   *
+   * Width and height start at a 16:10 guess because the intrinsic size is not
+   * known until the browser has the bitmap; `onLoad` corrects both from
+   * `naturalWidth`/`naturalHeight`. Extracted from the render arm so the streamed
+   * path reuses this exact entity rather than constructing a second variant.
+   *
+   * `markDirty()` is unconditional, matching the display-math sibling. It used
+   * to sit inside the `naturalWidth && naturalHeight` check, which meant a
+   * source that loads successfully while reporting a zero dimension left the
+   * scene un-notified. `Image` sets `loaded` before invoking this callback, so
+   * its `render()` starts drawing the bitmap either way — the cost was not a
+   * stale placeholder but a box frozen at the guess: measured on Chromium and
+   * Firefox, an `<svg width="0" height="0">` paragraph image kept 800x480 of
+   * reserved layout forever while a normal raster corrected to 80x60. An
+   * `onDemand` scene repaints only when marked, so nothing reclaimed it.
+   *
+   * The box is deliberately left at the guess when the bitmap reports zero.
+   * Collapsing it to 0x0 would make the paragraph reflow correctly but would
+   * also silently delete a reserved region on the strength of one browser
+   * quirk, and `Image.render()` still blits whatever the bitmap holds. Sizing
+   * policy for a zero-dimension source is a separate decision from notifying
+   * the scene, which is the actual defect here.
+   */
+  paragraphImage(imgToken, availableWidth) {
+    const initialWidth = Math.min(800, availableWidth);
+    const initialHeight = Math.round(initialWidth * 0.6);
+    const img = new Image(imgToken.href, {
+      width: initialWidth,
+      height: initialHeight,
+      alt: imgToken.text,
+      radius: 8,
+      onLoad: () => {
+        const bmp = img.bitmap;
+        if (bmp && bmp.naturalWidth && bmp.naturalHeight) {
+          const aspect = bmp.naturalHeight / bmp.naturalWidth;
+          img.width = Math.min(bmp.naturalWidth, availableWidth);
+          img.height = Math.round(img.width * aspect);
+        }
+        this.scene?.markDirty();
+      }
+    });
+    return img;
+  }
+  /** One table cell entity, shared by the render arm and the streamed-table path. */
+  tableCellRichText(cell, header, t) {
+    return new RichText(this.tableCellSpans(cell, t), {
+      font: `${t.fontSize - 2}px ${t.bodyFont}`,
+      color: header ? t.headingColor : t.textColor,
+      baseStyle: header ? { bold: true } : void 0,
+      linkColor: "#38bdf8",
+      selectable: this.selectable,
+      onLinkClick: this.onLinkClick
+    });
+  }
+  listItemSpans(token, index) {
+    const item = token.items[index];
+    const num = Number(token.start ?? 1) + index;
+    const contentSpans = [];
+    if (item.tokens && item.tokens.length > 0) {
+      for (const inner of item.tokens) {
+        if (inner.type === "text" && "tokens" in inner && inner.tokens?.length) {
+          collectSpans(
+            inner.tokens,
+            {},
+            this.theme,
+            contentSpans
+          );
+        } else if ("tokens" in inner && inner.tokens?.length) {
+          collectSpans(
+            inner.tokens,
+            {},
+            this.theme,
+            contentSpans
+          );
+        } else if ("text" in inner) {
+          contentSpans.push({ text: decodeEntities(inner.text) });
+        }
+      }
+    } else {
+      contentSpans.push({ text: decodeEntities(item.text) });
+    }
+    const itemIsRtl = BidiResolver.getBaseLevel(contentSpans.map((s) => s.text).join("")) % 2 === 1;
+    return itemIsRtl ? [...contentSpans, { text: token.ordered ? ` .${num}` : " \u2022" }] : [{ text: token.ordered ? `${num}. ` : "\u2022 " }, ...contentSpans];
+  }
+  /** Construct the `RichText` for one list item. */
+  listItemRichText(token, index, availableWidth, t) {
+    return new RichText(this.listItemSpans(token, index), {
+      font: `${t.fontSize}px ${t.bodyFont}`,
+      color: t.textColor,
+      maxWidth: availableWidth,
+      linkColor: "#38bdf8",
+      selectable: this.selectable,
+      onLinkClick: this.onLinkClick
+    });
+  }
+  /**
+   * Reuse a streamed list's `Stack` instead of rebuilding every item.
+   *
+   * Returns `false` to mean "rebuild instead", exactly like
+   * {@link updateBlockquoteTail}, and every rejection path leaves the entity
+   * untouched so a refused reuse cannot leave a half-updated list on screen.
+   *
+   * This is the shape a stream actually produces: items are APPENDED, and only
+   * the last one grows. That matters for the ordinal marker, which is
+   * position-derived (`start + index`) — under append an already-rendered item's
+   * index never changes, so its marker stays correct. A mid-list insertion would
+   * shift every later ordinal, but no stream produces one.
+   *
+   * Two traps this guards, both found by probing marked 18.0.7 rather than by
+   * reading:
+   *
+   * - **A retained item's `raw` is NOT stable.** `items[1].raw` goes `"- two"` ->
+   *   `"- two\\n"` when item 3 arrives, so a byte-equality guard on `raw` fails on
+   *   every chunk and the fast path would never fire. `text` is stable; compare
+   *   that.
+   * - **A tight list can become loose.** Adding a blank line flips
+   *   `token.loose`, which re-lexes every item's children from `text` to
+   *   `paragraph`. Item 0's own `text` is unchanged, so a naive guard would reuse
+   *   and keep stale spans. Bail when `loose` flips.
+   */
+  updateStreamedList(stack, oldToken, newToken) {
+    if (!(stack instanceof Stack)) return false;
+    if (newToken.items.length < oldToken.items.length || oldToken.items.length === 0) return false;
+    if (oldToken.ordered !== newToken.ordered) return false;
+    if ((oldToken.start ?? 1) !== (newToken.start ?? 1)) return false;
+    if (oldToken.loose !== newToken.loose) return false;
+    if (stack.children.length !== oldToken.items.length) return false;
+    const lastRetained = oldToken.items.length - 1;
+    for (let i = 0; i < lastRetained; i++) {
+      if (oldToken.items[i].text !== newToken.items[i].text) return false;
+    }
+    const availableWidth = this.activeBlockMetrics?.availableWidth ?? this.maxWidth;
+    const t = this.theme;
+    const tailEntity = stack.children[lastRetained];
+    if (oldToken.items[lastRetained].text !== newToken.items[lastRetained].text) {
+      if (!("setSpans" in tailEntity)) return false;
+      tailEntity.setSpans(
+        this.listItemSpans(newToken, lastRetained)
+      );
+    }
+    for (let i = oldToken.items.length; i < newToken.items.length; i++) {
+      stack.add(this.listItemRichText(newToken, i, availableWidth, t));
+    }
+    const last = stack.children.at(-1);
+    if (last) stack.resizeLastChild(last);
+    return true;
+  }
+  /**
+   * Reuse a streamed image-bearing paragraph's `Stack` instead of rebuilding it.
+   *
+   * Returns `false` to mean "rebuild instead", and every rejection happens before
+   * any mutation, so a refused reuse leaves the entity exactly as it was.
+   *
+   * This was the last silent fallthrough in the in-place reuse path. A paragraph
+   * holding an image renders as a `Stack` of alternating text runs and images
+   * rather than one `RichText`, so it has no `setSpans` and failed the ordinary
+   * paragraph gate — with no `else`, which is what made the miss invisible:
+   * `inPlaceUpdates` stayed flat while `entitiesRebuilt` climbed. Measured on a
+   * six-chunk stream, `inPlaceUpdates` 0 / `entitiesRebuilt` 4 with an image
+   * against 4 / 0 for the identical shape without one. Every rebuild also
+   * re-created the `Image`, discarding its decoded bitmap and its corrected
+   * intrinsic size.
+   *
+   * It is *only* a performance path. The obvious worry — that a fresh `Image`
+   * starts at `loaded = false` and so repaints its placeholder slab — was
+   * measured and does not happen: sampling the real canvas pixel at the image
+   * centre in both Chromium and Firefox gives zero placeholder frames after the
+   * first paint, at 60ms and at 0ms between chunks, because a cached bitmap
+   * decodes before the next frame.
+   *
+   * The reuse is deliberately narrow: **only a growing trailing text run**. Probed
+   * against `marked@18.0.7`, that is the shape a stream actually produces once an
+   * image has closed — the image token's `raw` and its index are then stable while
+   * trailing prose grows, and the token list settles at
+   * `[…, image, text]` and stops changing length. Anything else (a new image
+   * arriving, an image token changing, a run appearing before the last image)
+   * falls through to the rebuild, which is correct and rare.
+   *
+   * Note the child list is not one entity per token: consecutive non-image tokens
+   * are merged into one `RichText` by the render arm's `flushText`, so
+   * `[text, text, image]` is two children, not three. The guards therefore compare
+   * *token runs* split at the last image, never token index against child index.
+   */
+  updateImageParagraph(entity, oldToken, newToken) {
+    if (!(entity instanceof Stack)) return false;
+    const oldTokens = oldToken.tokens;
+    const newTokens = newToken.tokens;
+    if (!oldTokens || !newTokens) return false;
+    const oldLastImage = lastIndexOfImage(oldTokens);
+    const newLastImage = lastIndexOfImage(newTokens);
+    if (oldLastImage < 0 || newLastImage < 0) return false;
+    if (oldLastImage !== newLastImage) return false;
+    for (let i = 0; i <= newLastImage; i++) {
+      if (oldTokens[i].raw !== newTokens[i].raw) return false;
+    }
+    const oldTail = oldTokens.slice(oldLastImage + 1);
+    const newTail = newTokens.slice(newLastImage + 1);
+    if (newTail.length === 0) return false;
+    const oldTailRaw = oldTail.map((t2) => t2.raw).join("");
+    const newTailRaw = newTail.map((t2) => t2.raw).join("");
+    if (!newTailRaw.startsWith(oldTailRaw)) return false;
+    const expectedOldChildren = expectedImageParagraphChildren(oldTokens);
+    if (entity.children.length !== expectedOldChildren) return false;
+    const t = this.theme;
+    const availableWidth = this.activeBlockMetrics?.availableWidth ?? this.maxWidth;
+    if (oldTail.length === 0) {
+      entity.add(this.inlineRunRichText(newTail, availableWidth, t));
+    } else {
+      const tailEntity = entity.children[entity.children.length - 1];
+      if (!(tailEntity instanceof RichText)) return false;
+      tailEntity.setSpans(this.inlineRunSpans(newTail, t));
+    }
+    const last = entity.children[entity.children.length - 1];
+    if (last) entity.resizeLastChild(last);
+    return true;
+  }
+  /**
+   * Reuse a streamed table's `Table` entity instead of rebuilding every cell.
+   *
+   * Returns `false` to mean "rebuild instead", and every rejection happens before
+   * any mutation, so a refused reuse leaves the entity exactly as it was.
+   *
+   * A `table` token carries every row, so the rebuild path costs Θ(C·N²)
+   * `RichText` constructions across a stream — and a further 2×, because
+   * `Table.layout()` re-runs `fitCell` on every cell. This was the last block
+   * type without an in-place path.
+   *
+   * Two shapes have to be handled, because of how `marked` lexes a growing table
+   * (probed against 18.0.7): a partial row is materialized immediately as a FULL
+   * row padded with empty cells, and its cells are then filled one at a time. A
+   * 2×2 table passes through eleven distinct row states, of which only two are
+   * clean row appends. So handling appends alone would reject most chunks and
+   * leave the quadratic cost essentially in place:
+   *
+   * 1. the last row's cells are rewritten in place via `setSpans`, and
+   * 2. genuinely new rows go through `Table.appendRows`.
+   *
+   * Cells are compared by `text`, never `raw` — a table cell has no `raw` at all
+   * (its keys are `text`/`tokens`/`header`/`align`).
+   */
+  updateStreamedTable(entity, oldToken, newToken) {
+    if (!(entity instanceof Table)) return false;
+    if (oldToken.header.length !== newToken.header.length) return false;
+    for (let c = 0; c < oldToken.header.length; c++) {
+      if (oldToken.header[c].text !== newToken.header[c].text) return false;
+    }
+    if (newToken.rows.length < oldToken.rows.length) return false;
+    if (entity.rows.length !== oldToken.rows.length) return false;
+    const lastRetained = oldToken.rows.length - 1;
+    for (let r = 0; r < lastRetained; r++) {
+      const oldRow = oldToken.rows[r];
+      const newRow = newToken.rows[r];
+      for (let c = 0; c < oldToken.header.length; c++) {
+        if (oldRow[c]?.text !== newRow[c]?.text) return false;
+      }
+    }
+    if (lastRetained >= 0) {
+      for (let c = 0; c < oldToken.header.length; c++) {
+        const cell = entity.rows[lastRetained]?.[c];
+        if (!(cell instanceof RichText)) return false;
+      }
+    }
+    const t = this.theme;
+    let changed = false;
+    if (lastRetained >= 0) {
+      const oldRow = oldToken.rows[lastRetained];
+      const newRow = newToken.rows[lastRetained];
+      for (let c = 0; c < oldToken.header.length; c++) {
+        if (oldRow[c]?.text === newRow[c]?.text) continue;
+        const cell = entity.rows[lastRetained][c];
+        cell.setSpans(this.tableCellSpans(newRow[c], t));
+        changed = true;
+      }
+    }
+    if (newToken.rows.length > oldToken.rows.length) {
+      const added = newToken.rows.slice(oldToken.rows.length).map((row) => row.map((cell) => this.tableCellRichText(cell, false, t)));
+      entity.appendRows(added);
+    } else if (changed) {
+      entity.layout();
+    }
+    return true;
+  }
+  updateBlockquoteTail(container, oldInner, newInner) {
+    if (oldInner.length !== newInner.length || newInner.length === 0) return false;
+    const tail = newInner.length - 1;
+    for (let i = 0; i < tail; i++) {
+      if (oldInner[i].raw !== newInner[i].raw) return false;
+    }
+    const oldTail = oldInner[tail];
+    const newTail = newInner[tail];
+    if (oldTail.type !== newTail.type) return false;
+    const innerStack = container.children[1];
+    if (!(innerStack instanceof Stack)) return false;
+    const wrapper = innerStack.children.at(-1);
+    if (!wrapper || wrapper.children.length !== 1) return false;
+    const entity = wrapper.children[0];
+    if (!this.producesEntity(newTail)) return false;
+    if (newTail.type === "paragraph" && "setSpans" in entity) {
+      entity.setSpans(
+        this.literalParagraphSpans(newTail)
+      );
+    } else if (newTail.type === "heading" && "setSpans" in entity) {
+      if (oldTail.depth !== newTail.depth) {
+        return false;
+      }
+      entity.setSpans(
+        this.headingSpans(newTail)
+      );
+    } else if (newTail.type === "code" && entity instanceof CodeBlock && !rendersAsMath(newTail)) {
+      const codeToken = newTail;
+      entity.setCode(codeToken.text, codeToken.lang ?? void 0);
+    } else {
+      return false;
+    }
+    wrapper.width = entity.x + entity.width;
+    wrapper.height = entity.height;
+    innerStack.resizeLastChild(wrapper);
+    const border = container.children[0];
+    if (border instanceof QuoteBorder) border.height = innerStack.height || 20;
+    container.height = Math.max(border?.height ?? 0, innerStack.height);
+    return true;
+  }
+  /**
+   * Spans for a heading being updated in place.
+   *
+   * Kept in lockstep with the `heading` arm of {@link renderToken}, which builds
+   * its `RichText` through `renderInlineToRichText`: same `collectSpans` call and
+   * the same `decodeEntities` fallback when a heading has no inline tokens (`##`
+   * with no text yet, which a stream produces before its first word arrives). A
+   * plain `token.text` fallback here would leave an entity-bearing heading
+   * undecoded on the in-place path but decoded on a fresh render.
+   */
+  headingSpans(token) {
+    const spans = [];
+    if (token.tokens && token.tokens.length > 0) {
+      collectSpans(token.tokens, {}, this.theme, spans);
+    }
+    if (spans.length === 0) spans.push({ text: decodeEntities(token.text) });
+    return spans;
+  }
+  /**
+   * Spans for the trailing paragraph with its last unclosed inline construct
+   * rendered as though it had closed, or `null` when there is nothing to guess.
+   *
+   * `null` is the answer for every `'literal'` stream, every closed or absent
+   * stream, and any trailing paragraph whose syntax is all balanced — so the
+   * caller falls back to {@link literalParagraphSpans} and pays nothing.
+   *
+   * Only the paragraph's LAST inline token is scanned. An unclosed construct can
+   * only be there: anything that closed is already its own `strong`/`em`/
+   * `codespan`/`link` token, so a syntax character surviving into a trailing
+   * plain-text run is one `marked` could not pair. Scanning the whole raw string
+   * instead would re-find the markers of already-closed constructs.
+   */
+  optimisticParagraphSpans(token) {
+    if (this.streamIncompleteMode !== "optimistic") return null;
+    if (this.streamController?.state !== "open") return null;
+    const inline = token.tokens;
+    if (!inline || inline.length === 0) return null;
+    let runLength = 1;
+    let runText;
+    const last = inline[inline.length - 1];
+    const prev = inline.length > 1 ? inline[inline.length - 2] : null;
+    const isFlatText = (token2) => token2.type === "text" && !token2.tokens?.length;
+    if (last.type === "link" && last.raw === last.text && prev !== null && isFlatText(prev) && prev.text.endsWith("](")) {
+      runLength = 2;
+      runText = prev.text + last.raw;
+    } else if (isFlatText(last)) {
+      runText = last.text;
+    } else {
+      return null;
+    }
+    const found = findUnclosedInline(runText);
+    if (!found) return null;
+    const spans = [];
+    if (inline.length > runLength) {
+      collectSpans(inline.slice(0, -runLength), {}, this.theme, spans);
+    }
+    const head = runText.slice(0, found.at);
+    if (head) spans.push({ text: decodeEntities(head) });
+    let content = runText.slice(found.contentAt);
+    if (found.kind === "link") {
+      const close = content.indexOf("](");
+      if (close !== -1) content = content.slice(0, close);
+    }
+    if (!content) return null;
+    const style = this.optimisticStyle(found.kind);
+    spans.push({ text: decodeEntities(content), style });
+    return spans;
+  }
+  /** Display style for a guessed-closed construct. */
+  optimisticStyle(kind) {
+    switch (kind) {
+      case "strong":
+        return { bold: true };
+      case "em":
+        return { italic: true };
+      case "codespan":
+        return { color: this.theme.codeColor, fontFamily: this.theme.codeFont };
+      // A link with no closing paren has no href, so it renders as plain text —
+      // no link color and no click affordance for a destination nobody has yet.
+      case "link":
+        return void 0;
+    }
+  }
+  /**
+   * Re-render the paragraph currently showing a guess from its own tokens, with
+   * no overlay, and forget it.
+   *
+   * Idempotent and free when no guess is live, which is what lets `close()`,
+   * `abort()`, and a mid-stream staleness check all call it unconditionally.
+   */
+  /**
+   * Start the MathJax load, and re-typeset this document once it resolves.
+   *
+   * Called from two places, for two different reasons:
+   *
+   * - When an OPEN math fence is rendered. This is a prefetch, and it is what
+   *   makes the lazy load invisible while streaming: the module starts loading
+   *   the moment a formula begins arriving, several chunks before its closing
+   *   fence, so by the time the fence closes the converter is usually already
+   *   installed and the formula typesets synchronously on the normal path.
+   * - When a CLOSED fence could not be typeset because the module is not ready.
+   *   That is the case a rebuild actually exists for: a document constructed with
+   *   math already complete, or a stream that closed a fence faster than the
+   *   module loaded.
+   *
+   * Idempotent per instance. Concurrent callers coalesce onto the one cached
+   * module promise, and `mathLoadPending` keeps a second rebuild from being
+   * queued while the first is outstanding.
+   */
+  ensureMathJax() {
+    if (mathConverter || this.mathLoadPending || this.isDestroyed) return;
+    this.mathLoadPending = true;
+    void preloadMathJax().then(() => {
+      this.mathLoadPending = false;
+      if (this.isDestroyed) return;
+      if (mathConverter) this.retypesetFromTokens();
+      this.flushAppendSettledWaiters();
+    });
+  }
+  /**
+   * Rebuild every block from the tokens already lexed, without re-lexing.
+   *
+   * Used only when MathJax arrives after a formula has already been rendered as
+   * source. Rebuilding wholesale rather than surgically replacing the math blocks
+   * is the deliberate choice: `tokenChildPrefix` maps token indices to child
+   * slots positionally, so swapping one child in place would have to keep that
+   * mapping, the `Stack`'s cached box, and every following sibling's position in
+   * agreement by hand. Re-rendering the same token list in the same order leaves
+   * the mapping trivially correct, and this runs at most once per document — the
+   * same cost as the `setContent` rebuild that already exists.
+   *
+   * The optimistic tail is dropped first. Its `entity` is about to be destroyed,
+   * so the pointer would dangle; unwinding restores literal spans, and if the
+   * stream is still open the next chunk re-applies a guess.
+   */
+  retypesetFromTokens() {
+    this.unwindOptimisticTail();
+    const tokens = this.tokens;
+    while (this.content.children.length > 0) {
+      this.content.children[this.content.children.length - 1].destroy();
+    }
+    for (const token of tokens) {
+      const el = this.renderToken(token);
+      if (el) this.content.add(el);
+    }
+    this.width = this.content.width;
+    this.height = this.content.height;
+    this.scene?.markDirty();
+  }
+  unwindOptimisticTail() {
+    const tail = this.optimisticTail;
+    this.optimisticTail = null;
+    if (!tail || this.isDestroyed) return;
+    const entity = tail.entity;
+    if (!entity.setSpans || entity.parent !== this.content) return;
+    entity.setSpans(this.literalParagraphSpans(tail.token));
+    if (this.content.children.at(-1) === entity) {
+      this.content.resizeLastChild(entity);
+    } else {
+      this.content.layout();
+    }
+    this.width = this.content.width;
+    this.height = this.content.height;
+    this.scene?.markDirty();
+  }
+  /**
+   * Drop a guess that is no longer on the document's trailing paragraph.
+   *
+   * A coalesced append can add a block after the paragraph that owns the guess,
+   * at which point the guess is frozen — the construct can never close, because
+   * no further text lands in that paragraph. Without this the stale styling would
+   * survive until `close()`.
+   *
+   * `writtenThisPass` is the entity whose spans this reconcile already rewrote,
+   * if any: for that one, literal spans are on screen already and re-rendering it
+   * would be wasted layout, so only the bookkeeping is cleared.
+   */
+  dropStaleOptimisticTail(trailing, writtenThisPass) {
+    const tail = this.optimisticTail;
+    if (!tail || tail.entity === trailing) return;
+    if (tail.entity === writtenThisPass) {
+      this.optimisticTail = null;
+      return;
+    }
+    this.unwindOptimisticTail();
+  }
+  /**
+   * Resolve once every in-flight worker append has actually been applied.
+   *
+   * Committing text is not the same as the document reflecting it: `append()`
+   * reaches `dispatchAppend()`, which `postMessage()`s and returns, and the reply
+   * that runs `updateTokens()` lands later. Without waiting here, `close()` could
+   * resolve — and `onStable` fire — against a document missing its last chunk.
+   *
+   * An outstanding lazy MathJax load counts as unsettled for the same reason. A
+   * document whose formulas are still TeX source is not final in any sense a
+   * caller of `onStable` cares about: the boxes are the wrong size, so measuring
+   * or exporting there would capture placeholders.
+   */
+  waitForAppendSettled() {
+    if (!this.appendInFlight && !this.mathLoadPending) return Promise.resolve();
+    return new Promise((resolve) => {
+      this.appendSettledWaiters.push(resolve);
+    });
+  }
+  /**
+   * Release settlement waiters, but only once nothing is outstanding.
+   *
+   * Called at the very END of the worker callback, after its coalesced-re-dispatch
+   * check, rather than wherever `appendInFlight` goes false. Within that callback
+   * `appendInFlight` is cleared and then, if another chunk arrived while the
+   * request was in flight, set straight back to `true` by the re-dispatch — both
+   * synchronously, before anything watching the flag could observe the gap. Only
+   * checking here, after that, waits through the re-dispatch instead of resolving
+   * one chunk early.
+   */
+  flushAppendSettledWaiters() {
+    if (this.appendInFlight || this.mathLoadPending || this.appendSettledWaiters.length === 0) {
+      return;
+    }
+    const waiters = this.appendSettledWaiters;
+    this.appendSettledWaiters = [];
+    for (const resolve of waiters) resolve();
+  }
+  /** Throw if a public mutation is attempted from inside an `onStable` callback. */
+  assertNotInStableCallback(method) {
+    if (this.inStableCallback) {
+      throw new Error(`Markdown.${method}() cannot be called from an onStable callback`);
+    }
+  }
   updateTokens(newTokens, knownMatchLen) {
     const oldTokens = this.tokens;
     const oldChildren = [...this.content.children];
@@ -1632,11 +2610,18 @@ var Markdown = class extends UIComponent {
     }
     const oldTokenToChild = this.tokenChildPrefix;
     const rawMatchLen = matchLen;
+    let pendingTail = null;
+    let spansWrittenTo = null;
     const lastTokenSameType = matchLen === oldTokens.length - 1 && matchLen < newTokens.length && oldTokens[matchLen]?.type === newTokens[matchLen]?.type;
     if (lastTokenSameType && newTokens[matchLen]?.type === "code") {
       const existingEntity = oldChildren[oldTokenToChild[matchLen]];
       const codeToken = newTokens[matchLen];
-      if (existingEntity instanceof CodeBlock) {
+      const oldCodeToken = oldTokens[matchLen];
+      const isMath = rendersAsMath(codeToken);
+      if (isMath && rendersAsMath(oldCodeToken) && oldCodeToken.text === codeToken.text) {
+        this.streamStats.inPlaceUpdates++;
+        matchLen++;
+      } else if (existingEntity instanceof CodeBlock && !isMath) {
         existingEntity.setCode(codeToken.text, codeToken.lang ?? void 0);
         this.streamStats.inPlaceUpdates++;
         matchLen++;
@@ -1645,17 +2630,63 @@ var Markdown = class extends UIComponent {
     } else if (lastTokenSameType && newTokens[matchLen]?.type === "paragraph") {
       const entityIdx = oldTokenToChild[matchLen];
       const existingEntity = oldChildren[entityIdx];
-      if (existingEntity && "setSpans" in existingEntity) {
+      if (existingEntity && "setSpans" in existingEntity && !paragraphHasImage(newTokens[matchLen])) {
         const pToken = newTokens[matchLen];
-        const t = this.theme;
-        const spans = [];
-        if (pToken.tokens && pToken.tokens.length > 0) {
-          collectSpans(pToken.tokens, {}, t, spans);
-        }
-        if (spans.length === 0) {
-          spans.push({ text: pToken.text });
-        }
-        existingEntity.setSpans(spans);
+        const isTrailing = matchLen === newTokens.length - 1;
+        const optimistic = isTrailing ? this.optimisticParagraphSpans(pToken) : null;
+        existingEntity.setSpans(optimistic ?? this.literalParagraphSpans(pToken));
+        spansWrittenTo = existingEntity;
+        if (optimistic) pendingTail = { entity: existingEntity, token: pToken };
+        this.streamStats.inPlaceUpdates++;
+        matchLen++;
+        this.content.resizeLastChild(existingEntity);
+      } else if (existingEntity && this.updateImageParagraph(
+        existingEntity,
+        oldTokens[matchLen],
+        newTokens[matchLen]
+      )) {
+        this.streamStats.inPlaceUpdates++;
+        matchLen++;
+        this.content.resizeLastChild(existingEntity);
+      }
+    } else if (lastTokenSameType && newTokens[matchLen]?.type === "heading") {
+      const existingEntity = oldChildren[oldTokenToChild[matchLen]];
+      const hToken = newTokens[matchLen];
+      const oldToken = oldTokens[matchLen];
+      if (existingEntity && "setSpans" in existingEntity && oldToken?.depth === hToken.depth) {
+        existingEntity.setSpans(this.headingSpans(hToken));
+        spansWrittenTo = existingEntity;
+        this.streamStats.inPlaceUpdates++;
+        matchLen++;
+        this.content.resizeLastChild(existingEntity);
+      }
+    } else if (lastTokenSameType && newTokens[matchLen]?.type === "blockquote") {
+      const existingEntity = oldChildren[oldTokenToChild[matchLen]];
+      const newInner = newTokens[matchLen].tokens;
+      const oldInner = oldTokens[matchLen].tokens;
+      if (existingEntity instanceof MarkdownContainer && newInner && oldInner && this.updateBlockquoteTail(existingEntity, oldInner, newInner)) {
+        this.streamStats.inPlaceUpdates++;
+        matchLen++;
+        this.content.resizeLastChild(existingEntity);
+      }
+    } else if (lastTokenSameType && newTokens[matchLen]?.type === "list") {
+      const existingEntity = oldChildren[oldTokenToChild[matchLen]];
+      if (existingEntity && this.updateStreamedList(
+        existingEntity,
+        oldTokens[matchLen],
+        newTokens[matchLen]
+      )) {
+        this.streamStats.inPlaceUpdates++;
+        matchLen++;
+        this.content.resizeLastChild(existingEntity);
+      }
+    } else if (lastTokenSameType && newTokens[matchLen]?.type === "table") {
+      const existingEntity = oldChildren[oldTokenToChild[matchLen]];
+      if (existingEntity && this.updateStreamedTable(
+        existingEntity,
+        oldTokens[matchLen],
+        newTokens[matchLen]
+      )) {
         this.streamStats.inPlaceUpdates++;
         matchLen++;
         this.content.resizeLastChild(existingEntity);
@@ -1673,10 +2704,24 @@ var Markdown = class extends UIComponent {
         }
       }
     }
+    const lastIndex = newTokens.length - 1;
     for (let i = matchLen; i < newTokens.length; i++) {
       const el = this.renderToken(newTokens[i]);
-      if (el) this.content.add(el);
+      if (!el) continue;
+      this.content.add(el);
+      if (i === lastIndex && newTokens[i].type === "paragraph" && "setSpans" in el) {
+        const pToken = newTokens[i];
+        const optimistic = this.optimisticParagraphSpans(pToken);
+        if (optimistic) {
+          el.setSpans(optimistic);
+          this.content.resizeLastChild(el);
+          pendingTail = { entity: el, token: pToken };
+          spansWrittenTo = el;
+        }
+      }
     }
+    this.dropStaleOptimisticTail(pendingTail?.entity ?? null, spansWrittenTo);
+    if (pendingTail) this.optimisticTail = pendingTail;
     this.setTokens(newTokens, rawMatchLen);
     this.width = this.content.width;
     this.height = this.content.height;
@@ -1739,6 +2784,10 @@ var Markdown = class extends UIComponent {
       availableWidth: this.maxWidth
     };
     const availableWidth = metrics.availableWidth;
+    if (containsInlineMath(token)) {
+      if (!mathConverter) this.ensureMathJax();
+      this.subscribeInlineMathRepaint();
+    }
     switch (token.type) {
       // ── Headings ─────────────────────────────────────────────────────
       case "heading": {
@@ -1760,7 +2809,7 @@ var Markdown = class extends UIComponent {
       // ── Paragraphs ───────────────────────────────────────────────────
       case "paragraph": {
         const pToken = token;
-        if (!pToken.tokens || !pToken.tokens.some((t2) => t2.type === "image")) {
+        if (!paragraphHasImage(pToken)) {
           return renderInlineToRichText(
             pToken.tokens,
             pToken.text,
@@ -1780,43 +2829,14 @@ var Markdown = class extends UIComponent {
         let currentTokens = [];
         const flushText = () => {
           if (currentTokens.length > 0) {
-            stack.add(
-              renderInlineToRichText(
-                currentTokens,
-                "",
-                bodyFont,
-                t.textColor,
-                availableWidth,
-                t,
-                this.selectable,
-                this.onLinkClick
-              )
-            );
+            stack.add(this.inlineRunRichText(currentTokens, availableWidth, t));
             currentTokens = [];
           }
         };
         for (const child of pToken.tokens) {
           if (child.type === "image") {
             flushText();
-            const imgToken = child;
-            const initialWidth = Math.min(800, availableWidth);
-            const initialHeight = Math.round(initialWidth * 0.6);
-            const img = new Image(imgToken.href, {
-              width: initialWidth,
-              height: initialHeight,
-              alt: imgToken.text,
-              radius: 8,
-              onLoad: () => {
-                const bmp = img.bitmap;
-                if (bmp && bmp.naturalWidth && bmp.naturalHeight) {
-                  const aspect = bmp.naturalHeight / bmp.naturalWidth;
-                  img.width = Math.min(bmp.naturalWidth, availableWidth);
-                  img.height = Math.round(img.width * aspect);
-                  if (this.scene) this.scene.markDirty();
-                }
-              }
-            });
-            stack.add(img);
+            stack.add(this.paragraphImage(child, availableWidth));
           } else {
             currentTokens.push(child);
           }
@@ -1828,13 +2848,22 @@ var Markdown = class extends UIComponent {
       case "code": {
         const codeToken = token;
         const lang = (codeToken.lang ?? "").toLowerCase();
-        if (lang === "math" || lang === "latex" || lang === "tex") {
+        if (MATH_LANGS.has(lang)) this.ensureMathJax();
+        if (rendersAsMath(codeToken)) {
           const mathData = renderMathToSVGDataURI(codeToken.text, true);
           if (mathData) {
+            const intrinsicW = exToPx(mathData.widthEx, t.fontSize);
+            const intrinsicH = exToPx(mathData.heightEx, t.fontSize);
             const mathImg = new Image(mathData.uri, {
-              width: Math.min(availableWidth, mathData.width),
-              height: mathData.height * Math.min(1, availableWidth / mathData.width),
-              alt: codeToken.text
+              width: Math.min(availableWidth, intrinsicW),
+              height: intrinsicH * Math.min(1, availableWidth / intrinsicW),
+              alt: codeToken.text,
+              // The SVG decodes asynchronously and Image paints a placeholder
+              // until it lands. Without this an `onDemand` scene, which repaints
+              // only when marked dirty, leaves the formula a blank slab forever.
+              onLoad: () => {
+                this.scene?.markDirty();
+              }
             });
             const wrapper = new MarkdownContainer();
             mathImg.x = 16;
@@ -1883,62 +2912,22 @@ var Markdown = class extends UIComponent {
         container.height = Math.max(border.height, innerStack.height);
         return container;
       }
-      // ── Lists ────────────────────────────────────────────────────────
+      // ── Lists ────────────────────────────────────────────────
       case "list": {
         const listToken = token;
         const listStack = new Stack({ direction: "vertical", gap: 6 });
         for (let i = 0; i < listToken.items.length; i++) {
-          const item = listToken.items[i];
-          const num = Number(listToken.start ?? 1) + i;
-          const contentSpans = [];
-          if (item.tokens && item.tokens.length > 0) {
-            for (const inner of item.tokens) {
-              if (inner.type === "text" && "tokens" in inner && inner.tokens?.length) {
-                collectSpans(inner.tokens, {}, t, contentSpans);
-              } else if ("tokens" in inner && inner.tokens?.length) {
-                collectSpans(inner.tokens, {}, t, contentSpans);
-              } else if ("text" in inner) {
-                contentSpans.push({
-                  text: decodeEntities(inner.text)
-                });
-              }
-            }
-          } else {
-            contentSpans.push({ text: decodeEntities(item.text) });
-          }
-          const itemIsRtl = BidiResolver.getBaseLevel(contentSpans.map((s) => s.text).join("")) % 2 === 1;
-          const itemSpans = itemIsRtl ? [...contentSpans, { text: listToken.ordered ? ` .${num}` : " \u2022" }] : [{ text: listToken.ordered ? `${num}. ` : "\u2022 " }, ...contentSpans];
-          const itemRt = new RichText(itemSpans, {
-            font: bodyFont,
-            color: t.textColor,
-            maxWidth: Math.max(0, availableWidth - 24),
-            linkColor: "#38bdf8",
-            selectable: this.selectable,
-            onLinkClick: this.onLinkClick
-          });
-          itemRt.x = 12;
-          listStack.add(itemRt);
+          listStack.add(this.listItemRichText(listToken, i, availableWidth, t));
         }
         return listStack;
       }
       // ── Table ────────────────────────────────────────────────────────
       case "table": {
         const tblToken = token;
-        const buildCell = (cell, header) => {
-          const spans = [];
-          collectSpans(cell.tokens, {}, t, spans);
-          if (spans.length === 0) return decodeEntities(cell.text);
-          return new RichText(spans, {
-            font: `${t.fontSize - 2}px ${t.bodyFont}`,
-            color: header ? t.headingColor : t.textColor,
-            baseStyle: header ? { bold: true } : void 0,
-            linkColor: "#38bdf8",
-            selectable: this.selectable,
-            onLinkClick: this.onLinkClick
-          });
-        };
-        const headers = tblToken.header.map((cell) => buildCell(cell, true));
-        const rows = tblToken.rows.map((row) => row.map((cell) => buildCell(cell, false)));
+        const headers = tblToken.header.map((cell) => this.tableCellRichText(cell, true, t));
+        const rows = tblToken.rows.map(
+          (row) => row.map((cell) => this.tableCellRichText(cell, false, t))
+        );
         return new Table({
           headers,
           rows,
@@ -1988,5 +2977,7 @@ export {
   CodeBlock,
   Markdown,
   codeAtlas,
-  codeAtlasStats
+  codeAtlasStats,
+  isMathJaxReady,
+  preloadMathJax
 };