@vectojs/markdown 0.14.0 → 0.16.0

package/dist/markdown-code.d.ts

@@ -0,0 +1,102 @@
+import { type ContentProjection, type ContentProjectionHint, GlyphRasterAtlas, type GlyphRasterAtlasStats, IRenderer } from '@vectojs/core';
+import { UIComponent } from '@vectojs/ui';
+import { type MarkdownTheme } from './theme';
+/**
+ * A single self-rendering entity for fenced code blocks.
+ *
+ * Replaces the old N×M child-entity explosion (Container → Stack → Text per
+ * segment per line) with a flat leaf that draws its own background + text.
+ */
+export declare class CodeBlock extends UIComponent {
+    private lines;
+    private grid;
+    /** Raw (unhighlighted) lines of the last build, for prefix reuse in buildLines. */
+    private rawLines;
+    private cellWidth;
+    private source;
+    /** Bumped by {@link buildLines} and {@link setSelectable}; read by `Scene`. */
+    private contentEpoch;
+    private lang;
+    private theme;
+    /**
+     * Assigned in the constructor rather than as a field initializer: both come
+     * from `theme`, and a field initializer runs before the constructor body has
+     * a `theme` to read.
+     */
+    private lineH;
+    private pad;
+    private codeFont;
+    selectable: boolean;
+    /**
+     * @param theme Any subset of {@link MarkdownTheme}; missing keys fall back to
+     *   `DEFAULT_THEME` in `./theme`. Accepting a partial theme keeps callers that were
+     *   written against an earlier, smaller `MarkdownTheme` working — this class
+     *   is public API, and a hand-built theme literal would otherwise start
+     *   throwing `lineHeight must be a positive finite number` the moment a new
+     *   size key was added.
+     */
+    constructor(code: string, lang: string, maxWidth: number, theme: MarkdownTheme, selectable?: boolean);
+    /** Re-parse code content (e.g. for live editing). */
+    setCode(code: string, lang?: string): this;
+    /** Enable or disable browser-native selection for this code block. */
+    setSelectable(selectable: boolean): this;
+    getContentEpoch(): number;
+    /**
+     * Change the block's box width.
+     *
+     * Deliberately does **not** rebuild the grid or the highlight, because code does
+     * not reflow: lines are placed on a fixed monospace grid at `col × cellWidth` and
+     * a long line overflows rather than wrapping, so `height` is a function of line
+     * *count* alone. The width only sizes the rounded background. Anything that would
+     * change the glyph geometry — the source, the language, the font — goes through
+     * {@link setCode} and invalidates the grid there.
+     *
+     * @returns `this` for chaining.
+     */
+    setWidth(width: number): this;
+    getContentProjection(hint?: ContentProjectionHint): ContentProjection | null;
+    /**
+     * Re-highlight the code, reusing the highlight of any unchanged line prefix.
+     *
+     * Streaming appends to the END of a block, so all but the last line or two are
+     * byte-identical to the previous call — yet this used to re-highlight every
+     * line on every chunk, making a streamed block O(N) per append and O(N^2)
+     * overall. Reusing the stable prefix makes an append proportional to what
+     * actually changed.
+     *
+     * The last previously-seen line is deliberately NOT reused: a chunk usually
+     * lands mid-line, so that line's text (and therefore its tokenization) changes.
+     */
+    private buildLines;
+    private ensureGrid;
+    /** Code blocks are decorative — not interactive. */
+    isPointInside(): boolean;
+    render(r: IRenderer): void;
+}
+/**
+ * Instrumentation for the code-block glyph atlas in use, or `null` before first
+ * use.
+ *
+ * Exposed so an app or benchmark can confirm the atlas is actually active and
+ * reusing slots. Watch `resets`: a steadily climbing count means the glyph set is
+ * unbounded for the atlas size, so every reset re-rasterizes everything and the
+ * atlas is doing net harm rather than saving work.
+ *
+ * Reports the *most recently used* atlas, which after a zoom is the one now being
+ * blitted — see {@link codeAtlas}.
+ */
+export declare function codeAtlasStats(): GlyphRasterAtlasStats | null;
+/**
+ * The code-block atlas most recently blitted from, or `null` before first use.
+ *
+ * For instrumentation that must map a traced `drawImage` back to the glyph it
+ * painted — a blit carries only a source rect, so `slotAt()` is the only way to
+ * recover the cluster and its metrics. Used by `e2e/text-projection.e2e.ts` to
+ * keep the code-grid positioning assertions working on the blit path.
+ *
+ * "Most recently used" rather than "the one" because atlases are pooled per DPR:
+ * a caller resolving a traced blit wants the atlas that produced it, which is the
+ * one the last render selected. Compare its {@link GlyphRasterAtlas.pixelRatio}
+ * against {@link IRenderer.pixelRatio} to assert the blit is 1:1.
+ */
+export declare function codeAtlas(): GlyphRasterAtlas | null;

package/dist/markdown-entities.d.ts

@@ -0,0 +1,33 @@
+import { Entity, IRenderer } from '@vectojs/core';
+/**
+ * Leaf entities the Markdown renderer composes: the `<hr>` rule, the blockquote
+ * accent bar, and a bare container for nested layouts.
+ *
+ * These live outside `Markdown.ts` because `MathBlock` extends
+ * `MarkdownContainer`. With the base class declared in `Markdown.ts`, a math
+ * module importing it back forms a cycle that resolves the binding to
+ * `undefined` when the `extends` clause is evaluated, throwing `TypeError:
+ * Class extends value undefined is not a constructor or null` on import.
+ * Verified by reintroducing it deliberately. 22 of 27 test files enter through
+ * `../src/Markdown`, which is the order that trips it. See
+ * `forge/decisions/file-decomposition-2026-08.md`.
+ */
+/** A thin horizontal line (for `<hr>`). */
+export declare class HorizontalRule extends Entity {
+    color: string;
+    constructor(w: number, color: string);
+    isPointInside(): boolean;
+    render(r: IRenderer): void;
+}
+/** A vertical accent bar for blockquotes. */
+export declare class QuoteBorder extends Entity {
+    color: string;
+    constructor(height: number, color: string, width?: number);
+    isPointInside(): boolean;
+    render(r: IRenderer): void;
+}
+/** A simple concrete container entity for nested layouts. */
+export declare class MarkdownContainer extends Entity {
+    isPointInside(_globalX: number, _globalY: number): boolean;
+    render(_r: any): void;
+}

package/dist/markdown-footnote.d.ts

@@ -0,0 +1,133 @@
+import type { TokenizerAndRendererExtension } from 'marked';
+/**
+ * GFM footnotes: the two `marked` tokenizer extensions, their token types, and
+ * the marker text a reference renders as.
+ *
+ * This module is the **single** registration source for both `marked.use` call
+ * sites — `Markdown.ts` and `MarkdownWorker.ts`. They must agree exactly: a
+ * worker lexing with a different extension set than the main thread produces
+ * tokens the renderer has no arm for, which is why `MarkdownWorker.ts` already
+ * carries a comment demanding lockstep for the math tokenizers. Sharing one
+ * array makes the divergence impossible rather than merely discouraged, and it
+ * costs nothing in the worker bundle: `scripts/build-worker.js` runs esbuild
+ * with `bundle: true`, so this import is inlined into the emitted worker source.
+ *
+ * Deliberately holds **no** entity, theme or `@vectojs/*` import. The whole
+ * module is inlined into the worker string, so a dependency on the render layer
+ * would drag the UI packages into a worker that only lexes text.
+ */
+/**
+ * A footnote reference — `[^1]` or `[^note]` — as it appears mid-sentence.
+ *
+ * Carries `label`, not `text`. That is load-bearing in two places: `Markdown`'s
+ * `producesEntity` falls back to `'text' in token` for an unknown type and
+ * `renderToken`'s `default:` arm renders `.text` as a plain block, so a token
+ * spelling its payload `text` would silently route through the fallback and
+ * reproduce the very defect this replaces. A distinct field name makes an
+ * unhandled footnote token render nothing instead of rendering wrongly.
+ */
+export interface FootnoteRefToken {
+    type: 'footnoteRef';
+    raw: string;
+    /** The label exactly as written between `[^` and `]`, e.g. `1` or `note`. */
+    label: string;
+}
+/** A footnote definition line — `[^1]: The note.` — as its own block. */
+export interface FootnoteDefToken {
+    type: 'footnoteDef';
+    raw: string;
+    /** The label exactly as written, matching a {@link FootnoteRefToken}'s. */
+    label: string;
+    /** The note body, source text with inline markup left unparsed. */
+    body: string;
+}
+/**
+ * The two extensions, in the order they are registered.
+ *
+ * ## Neither supplies `start()`, and the block one must not
+ *
+ * `start()` is not the harmless optimisation it looks like. `Lexer.blockTokens`
+ * clips the text handed to the paragraph tokenizer whenever any extension's
+ * `startBlock` hook reports a position, and sets a flag that merges the *next*
+ * paragraph into the clipped one — so a `[^` anywhere ahead retroactively
+ * re-groups paragraphs already emitted.
+ *
+ * Measured against marked 18.0.7 on `incrementalLex.ts`'s own probe string,
+ * `'Term\n: definition-ish\n| partial | table |\n| --- |\n\nAfter.\n'` followed
+ * by `'\n[^1]: n\n'`:
+ *
+ * - with a block `start()`: `[paragraph, space, paragraph, space, footnoteDef]`
+ *   — four content tokens collapse to three and the `Term` paragraph is **lost**
+ * - without it: `[paragraph, paragraph, space, paragraph, space, footnoteDef]`,
+ *   identical to the no-extension baseline
+ *
+ * It also breaks the invariant every incremental offset is derived from — that
+ * the tokens' `raw` strings tile their source. With a block `start()`,
+ * `'A[^1] B[^2].\n\n[^1]: One.\n[^2]: Two.\n'` yields a paragraph whose `raw` is
+ * `'A\n[^1] B[^2].'`: a newline the source does not contain. A 2x2 matrix over
+ * (block `start()`, inline `start()`) attributes both symptoms to the block one
+ * alone.
+ *
+ * The inline `start()` is simply not load-bearing — with and without it the
+ * inline token sequence is identical — so it is omitted for the smaller surface.
+ *
+ * Omitting the block `start()` costs one spec-adjacent behaviour, and it is the
+ * behaviour that is already correct: a definition on the line directly after a
+ * paragraph line, with no blank line between, is absorbed into that paragraph.
+ * CommonMark says the same of link reference definitions (they cannot interrupt
+ * a paragraph) and GFM says it of footnote definitions.
+ *
+ * ## Why an extension is enough
+ *
+ * A `marked.use` extension **runs before** the built-in tokenizers, not after:
+ * `Lexer.blockTokens` and `Lexer.inlineTokens` both begin with
+ * `this.options.extensions?.<level>?.some(...)`, and `Marked.use` inserts with
+ * `unshift`. So `footnoteRef` claims `[^1]` ahead of the built-in `link` rule
+ * and `footnoteDef` claims the definition line ahead of the `def` rule. Both are
+ * necessary. Without them, marked 18.0.7 splits on whether the note body
+ * contains a space, because a link destination cannot:
+ *
+ * - `[^1]: The note.` → `[paragraph, space, paragraph]`, the definition showing
+ *   as a stray body paragraph and `Here[^1] is text.` printing its raw syntax
+ * - `[^1]: Note.` → `[paragraph, space, def]`, where the reference becomes a
+ *   real inline `link` with `href: 'Note.'` — a **clickable link to a garbage
+ *   URL** — and the definition line vanishes from the output entirely
+ *
+ * A test written only against the first case passes while the second still ships.
+ *
+ * Claiming the definition before the `def` rule has a second effect worth
+ * naming: `tokens.links` stays empty, so a footnoted document no longer trips
+ * the permanent `'link-definition'` degrade in `incrementalLex.ts`.
+ *
+ * ## `renderer` is required but unreachable
+ *
+ * `marked.use` demands one for a custom token, and `@vectojs/markdown` never
+ * calls `marked.parse` — it renders from the token tree. Returning `raw`
+ * matches what the math extensions do, so an HTML round-trip is lossless rather
+ * than silently dropping the note.
+ */
+export declare const FOOTNOTE_EXTENSIONS: TokenizerAndRendererExtension[];
+/**
+ * The visible marker for a label: `1` → `[1]`.
+ *
+ * Brackets rather than a raised superscript because {@link TextStyle} has no
+ * baseline shift, and `InlineObjectSurface` exposes only `drawImage` — so a
+ * genuinely raised marker would mean rasterizing text, at a cost far past what a
+ * reference marker is worth. Size alone carries the signal instead
+ * (`theme.footnoteMarkerScale`).
+ *
+ * Unicode superscript digits (`¹`) were the obvious alternative and are wrong
+ * here: they exist only for digits, so `[^note]` could not use them, and a
+ * document mixing numeric and named labels would render two different marker
+ * styles. Font coverage for the full set is also uneven.
+ *
+ * The `^` is dropped — `[^1]` is source syntax, `[1]` is the conventional
+ * printed marker — and the label is printed **as written** rather than
+ * renumbered to GFM's 1, 2, 3 by order of first reference. Renumbering needs
+ * document-wide state, which is exactly the non-local dependency that makes
+ * incremental lexing unsound: a reference arriving late would renumber markers
+ * already on screen. incremark reaches the same conclusion from the other
+ * direction, patching micromark to stop checking whether a definition exists so
+ * a reference can parse before its definition arrives.
+ */
+export declare function footnoteMarker(label: string): string;

package/dist/markdown-image.d.ts

@@ -0,0 +1,126 @@
+import type { InlineObjectBox, InlineObjectSurface } from '@vectojs/core';
+import type { Token, Tokens } from 'marked';
+/**
+ * Image predicates over a `marked` token tree, plus the raster store for images
+ * that render *inline* rather than as their own block.
+ *
+ * Still a leaf — it imports no other module of this package, so nothing here has
+ * an edge back into `Markdown.ts`. The predicates are pure; the raster store below
+ * is not, and is here rather than in `markdown-inline.ts` so that everything
+ * deciding how an image reaches the screen lives in one file. The predicates are
+ * kept together because they decide, between them, whether a paragraph renders as
+ * one `RichText` or as a `Stack` of runs and images — a disagreement among them
+ * silently drops a picture. See
+ * `forge/decisions/file-decomposition-2026-08.md`.
+ */
+/**
+ * Whether a paragraph renders as a `Stack` of runs and images rather than one
+ * `RichText`.
+ *
+ * The same test the `paragraph` render arm uses, so the reconciler and the
+ * renderer cannot disagree about which shape a token produces.
+ *
+ * The search is over **descendants, not direct children**. `marked` nests an
+ * image as deeply as the source does — `[![a](u)](dest)` is
+ * `paragraph > link > image` and `- item ![a](u)` is
+ * `list_item > text > [text, image]` — so a direct-children test failed every
+ * nested form, sent the run to `inlineRunRichText`, which has no image support,
+ * and dropped the image with no warning. Recursing costs one walk of an inline
+ * run and removes the whole class rather than the two shapes that were reported.
+ */
+export declare function paragraphHasImage(token: Tokens.Paragraph): boolean;
+/**
+ * Whether any token in this inline run, at any depth, is an image.
+ *
+ * The one place the question is answered, so the predicate above, the list-item
+ * tier check and the flattening the render arms do cannot drift apart.
+ */
+export declare function containsImage(tokens: Token[] | undefined): boolean;
+/**
+ * An inline run with nested images lifted to the top level, in source order.
+ *
+ * The paragraph arm splits a run into one `Stack` child per image plus one per
+ * maximal run of non-image tokens, which requires every image to be a direct
+ * member of the array it iterates. An image inside a link or an emphasis is not,
+ * so the run is flattened first.
+ *
+ * A wrapper is replaced by its children rather than dropped, so the text inside a
+ * link that also holds an image survives. Only wrappers **containing** an image
+ * are opened: a plain link keeps its own token, and therefore keeps the styling
+ * and click handling `renderInlineToRichText` gives it.
+ */
+/**
+ * Every image in an inline run, at any depth, in source order.
+ *
+ * Pairs with `stripImages`: together they partition a run into the prose a
+ * `RichText` can render and the images it cannot.
+ */
+export declare function imagesOf(tokens: Token[] | undefined): Tokens.Image[];
+/**
+ * The same token with every nested image removed, prose intact.
+ *
+ * A wrapper that held only an image is dropped; one that also held text keeps the
+ * text. Used for a list item's lead run, which must show its marker and its prose
+ * while its images render as blocks beneath.
+ */
+export declare function stripImages<T extends Token>(token: T): T;
+export declare function liftNestedImages(tokens: Token[]): Token[];
+/** Index of the last `image` token in an inline run, or -1 if there is none. */
+export declare function lastIndexOfImage(tokens: Token[]): number;
+/**
+ * How many `Stack` children the paragraph render arm builds for an inline run.
+ *
+ * One child per image, plus one per *maximal run* of consecutive non-image
+ * tokens — the arm merges those into a single `RichText` via `flushText`, so this
+ * is not `tokens.length`. Kept in lockstep with that arm; it is what
+ * `updateImageParagraph` checks to confirm the entity it was handed is the one
+ * built for the old tokens.
+ */
+/**
+ * A decoding raster for one inline image, keyed by URL.
+ *
+ * Separate from the paragraph path's `Image` entity, which owns its own bitmap and
+ * resizes itself in `onLoad`. An inline image cannot do that: it is an
+ * `InlineObject`, and the box it occupies is fixed when the span is collected, so
+ * the natural size has to be readable from here before the next layout rather than
+ * applied to an entity afterwards.
+ */
+export interface InlineImageRaster {
+    /** `undefined` when this environment has no `Image` (SSR, plain unit tests). */
+    bitmap?: HTMLImageElement;
+    decoded: boolean;
+    /** Natural size, known only once decoded. */
+    naturalWidth?: number;
+    naturalHeight?: number;
+    /** Set when the decode failed, so a broken URL is not retried every frame. */
+    failed?: boolean;
+}
+/** Subscribe `notify` to inline-image decodes. Idempotent per closure. */
+export declare function subscribeInlineImageRaster(notify: () => void): void;
+/**
+ * Unsubscribe `notify`.
+ *
+ * Must be called on teardown: the set is module-level and lives as long as the
+ * page, so a retained closure retains the whole entity tree that created it.
+ */
+export declare function unsubscribeInlineImageRaster(notify: () => void): void;
+/**
+ * Ensure the raster for `src` is decoding, and return it.
+ *
+ * Synchronous and idempotent: the span collector calls it while measuring and the
+ * paint path calls it on every visible frame, and only the first call starts a
+ * decode. Exported because the span collector needs the natural size to size its
+ * box, which is the whole reason this store reports one.
+ */
+export declare function ensureInlineImageRaster(src: string): InlineImageRaster;
+/**
+ * Paint one inline image into the box the layout engine reserved for it.
+ *
+ * Draws nothing until the raster decodes — one frame of empty box, then a repaint
+ * through {@link inlineImageRasterWaiters}. Mirrors `paintInlineMath`; a
+ * placeholder slab would flash a grey rectangle mid-sentence on every first paint.
+ */
+export declare function paintInlineImage(src: string, surface: InlineObjectSurface, box: InlineObjectBox): void;
+/** Drop every cached raster. Tests only — a decode is process-wide state. */
+export declare function clearInlineImageRasters(): void;
+export declare function expectedImageParagraphChildren(tokens: Token[]): number;

package/dist/markdown-inline.d.ts

@@ -0,0 +1,58 @@
+import { type StyledSpan, type TextStyle } from '@vectojs/core';
+import { RichText } from '@vectojs/ui';
+import type { Token } from 'marked';
+import type { MarkdownTheme } from './theme';
+/**
+ * Inline tokens to `RichText` spans: the entity decoder, the span collector and
+ * its switch, the unclosed-delimiter scanner for optimistic streaming, and the
+ * `RichText` factory.
+ *
+ * Depends one way on `./markdown-math` (inline formulas become object spans) and
+ * takes the theme as a type only, so nothing here imports the component. See
+ * `forge/decisions/file-decomposition-2026-08.md`.
+ */
+/** Decode basic HTML entities that `marked` emits in token text. */
+export declare function decodeEntities(text: string): string;
+/**
+ * Recursively walk the inline token tree, accumulating {@link StyledSpan}s
+ * with inherited style overrides (bold, italic, etc.).
+ */
+export declare function collectSpans(tokens: Token[], inherited: TextStyle, theme: Required<MarkdownTheme>, out: StyledSpan[], 
+/**
+ * The size the enclosing block is drawn at, when it is not the theme body size.
+ *
+ * Only inline math uses it: `ex` is font-relative, so a formula's reserved box
+ * has to be resolved against the size of the run it sits in. A heading carries
+ * its size in its `font` string rather than in any span style, so it cannot be
+ * recovered from `inherited`.
+ */
+blockFontSize?: number): void;
+/**
+ * One trailing inline construct that has opened but not closed yet.
+ *
+ * `at` is the index in the scanned text of the construct's first syntax
+ * character, so the caller can split there: everything before it keeps whatever
+ * `marked` already decided, everything after it is the construct's content.
+ */
+export interface UnclosedInline {
+    kind: 'strong' | 'em' | 'codespan' | 'link';
+    /** Index of the opening marker's first character. */
+    at: number;
+    /** Index just past the opening marker, where the content starts. */
+    contentAt: number;
+}
+/**
+ * Find the last unclosed inline construct in one trailing text run.
+ *
+ * Only ever called with the text of the FINAL inline token of the document's
+ * final paragraph. That is the only place an unclosed construct can be: a
+ * construct that closed is already its own `strong`/`em`/`codespan`/`link`
+ * token, so whatever syntax characters survive into a plain text token are
+ * exactly the ones `marked` could not pair up.
+ *
+ * Returns `null` when nothing plausible is open, which is the common case and
+ * must stay cheap — this runs once per streamed chunk.
+ */
+export declare function findUnclosedInline(text: string): UnclosedInline | null;
+/** Parse inline markdown tokens and produce a {@link RichText} entity. */
+export declare function renderInlineToRichText(tokens: Token[] | undefined, fallbackText: string, font: string, color: string, maxWidth: number, theme: Required<MarkdownTheme>, selectable: boolean, onLinkClick?: (url: string) => void): RichText;

package/dist/markdown-math.d.ts

@@ -0,0 +1,169 @@
+import { type InlineObjectBox, type InlineObjectSurface, type DevtoolsDescriptor } from '@vectojs/core';
+import type { Token, Tokens } from 'marked';
+import { MarkdownContainer } from './markdown-entities';
+/**
+ * Begin (or join) loading the math engine, resolving once formulas typeset
+ * synchronously.
+ *
+ * Idempotent and safe to call from anywhere: the promise is cached, so N callers
+ * and N documents share one module load. Rejection is swallowed deliberately —
+ * a failed load must degrade to TeX source in a CodeBlock, not reject a caller's
+ * `await close()` or leave an unhandled rejection on the page. `mathConverter`
+ * simply stays null and every formula keeps rendering as source.
+ */
+export declare function preloadMathJax(): Promise<void>;
+/** Whether formulas can be typeset without waiting. Exposed for tests. */
+export declare function isMathJaxReady(): boolean;
+/** Convert an `ex` measurement to px at a given font size. */
+export declare function exToPx(ex: number, fontSize: number): number;
+/**
+ * The px size out of a CSS font shorthand (`'bold 28px Inter, sans-serif'` → 28).
+ *
+ * `undefined` when there is no `px` size to read, so the caller can fall back to
+ * the theme rather than silently substituting a wrong number. `@vectojs/ui` has an
+ * equivalent `fontSizePx` in `measure.ts`, but it is not re-exported from that
+ * package's barrel and it returns a hardcoded 16 on failure, which would hide a
+ * malformed font behind a plausible-looking box.
+ *
+ * Deliberately not a regex. The obvious `/(\d+(?:\.\d+)?)px/` is polynomial: the
+ * digit run can backtrack from every start position when no `px` follows, so a
+ * font string of many digits costs O(n^2) — CodeQL flagged exactly that here
+ * (`js/polynomial-redos`, high), and `font` comes from caller-supplied theme
+ * input. Anchoring on `px` first and walking back over the digits is linear.
+ */
+export declare function fontSizeFromFont(font: string): number | undefined;
+/**
+ * A converted formula: its SVG data URI and the intrinsic box scraped off it.
+ *
+ * The box is in **`ex` units**, not px, because `ex` is font-relative and one
+ * cached conversion is reused across runs of different sizes (inline math in a
+ * heading versus body prose). Callers resolve to px with {@link exToPx} at the
+ * size of the run the formula actually sits in.
+ */
+interface MathRender {
+    uri: string;
+    /** Intrinsic width in `ex`. */
+    widthEx: number;
+    /** Intrinsic height in `ex`, ascent + descent. */
+    heightEx: number;
+    /**
+     * How far the box descends below the text baseline, in `ex`, as a positive
+     * number.
+     *
+     * MathJax emits this as `style="vertical-align:-N ex"` on the root `<svg>`.
+     * Measured on 8 formulas spanning subscripts, superscripts, fractions, big
+     * operators and radicals, it equals the viewBox-derived depth exactly, so it
+     * is read straight off the attribute rather than computed from the viewBox.
+     */
+    depthEx: number;
+}
+/**
+ * Subscribe `notify` to inline-formula raster decodes.
+ *
+ * A function rather than exporting the `Set`, so the collection stays private to
+ * this module once the math cluster moves out of `Markdown.ts`. Idempotent per
+ * closure, since `Set` de-duplicates.
+ */
+export declare function subscribeInlineMathRaster(notify: () => void): void;
+/**
+ * Unsubscribe `notify`.
+ *
+ * Must be called on teardown: the set is module-level and lives as long as the
+ * page, so a retained closure retains the whole entity tree that created it.
+ */
+export declare function unsubscribeInlineMathRaster(notify: () => void): void;
+/**
+ * Paint one inline formula into the box the layout engine reserved for it.
+ *
+ * Draws nothing until the raster has decoded — one frame of blank box, then a
+ * repaint via {@link inlineMathRasterWaiters}. Drawing a placeholder slab instead
+ * would flash a grey rectangle mid-sentence on every first paint.
+ */
+export declare function paintInlineMath(uri: string, surface: InlineObjectSurface, box: InlineObjectBox): void;
+export declare const MATH_LANGS: Set<string>;
+/**
+ * Whether a token subtree contains an `inlineMath` token.
+ *
+ * Recursive because inline math nests: inside `strong`/`em`, a link's children, a
+ * list item's tokens, a blockquote, or a table cell. Used only to decide whether
+ * to start the lazy MathJax load, so a false negative delays typesetting rather
+ * than corrupting output — but a missed nesting site means a formula in, say, a
+ * table cell never typesets at all.
+ */
+export declare function containsInlineMath(token: Token): boolean;
+/**
+ * Whether a fenced-code token's source actually contains its closing fence.
+ *
+ * `marked` lexes an unterminated fence as a COMPLETE `code` token as soon as the
+ * info string is read, so a formula streamed a few characters at a time arrives
+ * as a long run of whole tokens, nearly all of them syntactically invalid TeX.
+ * The token carries no "closed" flag (probed against marked 18.0.7: the keys are
+ * exactly `type`, `raw`, `lang`, `text` whether or not the fence is closed), so
+ * `raw` is the only signal. Per CommonMark a closing fence is a line of at least
+ * as many of the SAME fence character as the opening, indented at most three
+ * spaces, followed by nothing but whitespace.
+ */
+export declare function isFenceClosed(raw: string): boolean;
+/**
+ * Whether this `code` token renders as a typeset formula rather than a CodeBlock.
+ *
+ * Single source of truth for that decision, because three places have to agree
+ * on it: the render arm, the top-level in-place update path, and the blockquote
+ * tail path. If the two update paths disagreed with the renderer they would call
+ * `setCode` on an entity that is not a CodeBlock, or leave a CodeBlock on screen
+ * where a formula belongs.
+ *
+ * An empty closed fence is deliberately NOT math: it renders as the empty
+ * CodeBlock any other empty fence would, rather than as a zero-width image.
+ */
+export declare function rendersAsMath(token: Tokens.Code): boolean;
+/**
+ * A cached formula render, or null when one is not available *yet*.
+ *
+ * Null deliberately means two things at once — "MathJax is not loaded" and "the
+ * conversion failed" — because the caller's response to both is identical: show
+ * the TeX source in a CodeBlock. Keeping them one signal is what let the render
+ * arm stay unchanged when loading became lazy. A cache hit is answered even
+ * before MathJax loads, so a formula already converted once (the common case on
+ * a re-render, and for the closed fence whose `raw` grows by a trailing newline)
+ * never waits on the module.
+ *
+ * The cache lookup being ahead of the `mathConverter` check is intentional but
+ * currently unobservable: `mathConverter` only ever goes null -> set, so nothing
+ * can be in the cache while it is still null. Swapping the two lines changes no
+ * behaviour today (confirmed by mutation: no test fails). It is written this way
+ * so the cache stays authoritative if the converter ever becomes resettable.
+ */
+export declare function renderMathToSVGDataURI(formula: string, displayMode: boolean, color: string): MathRender | null;
+/**
+ * One display formula: a `$$..$$` block or a closed ```` ```math ```` fence.
+ *
+ * A named class rather than a bare {@link MarkdownContainer} because the formula
+ * needs a stable handle, and after the switch to an inline object it has none:
+ * the typeset raster lives in a `paint` closure captured by the span, so removing
+ * the `Image` entity left nothing exposing either the source or the SVG bytes.
+ * Devtools, tests, and anything auditing what a formula actually rendered all
+ * want that. `markstream-vue` reaches the same conclusion from the DOM side and
+ * publishes `data-markstream-mode` on its math node for the same reason.
+ *
+ * Deliberately carries no typeset-vs-source flag. A formula MathJax has not
+ * converted yet renders as a bare {@link CodeBlock} of its TeX, which this class
+ * does not wrap — wrapping it would put a container between `content` and a
+ * `CodeBlock` that the streamed `setCode` path locates by type. So a flag would
+ * have exactly one reachable value, which is the dead-API trap that cost CTX-0208
+ * a debugging pass. Add it together with wrapping the fallback, or not at all.
+ */
+export declare class MathBlock extends MarkdownContainer {
+    /**
+     * The TeX source, exactly as written between the delimiters.
+     *
+     * Also the projected text and the accessible name, so this is the one string a
+     * reader can find, select, and copy.
+     */
+    readonly formula: string;
+    /** The `data:image/svg+xml` URI of the typeset glyphs. */
+    readonly svgUri: string;
+    constructor(formula: string, svgUri: string);
+    getDevtoolsDescriptor(): DevtoolsDescriptor;
+}
+export {};