@vectojs/markdown 0.14.0 → 0.15.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-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 {};

package/dist/theme.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Color, typography and spacing tokens for `@vectojs/markdown`.
+ *
+ * Split out of `Markdown.ts` so `CodeBlock` and the inline renderer can take a
+ * theme without importing the whole component, which would make the module
+ * graph cyclic. See `forge/decisions/file-decomposition-2026-08.md`.
+ */
+/**
+ * Color, typography and spacing theme for Markdown rendering.
+ *
+ * The shape is deliberately **flat**, not a nested token tree. Every key is
+ * optional and merged over {@link DEFAULT_THEME} by a single spread, so adding a
+ * key is backward compatible and a caller may override exactly one value
+ * without restating a group. A nested `{ colors: {...}, spacing: {...} }` shape
+ * would need a deep merge and would break every existing caller.
+ *
+ * Sizes and spacing are **numbers in px**, not CSS strings, because the values
+ * are consumed by canvas layout arithmetic rather than by a stylesheet.
+ */
+export interface MarkdownTheme {
+    /** Body text color. */
+    textColor?: string;
+    /** Heading text color. */
+    headingColor?: string;
+    /** Code text color (inline + block). */
+    codeColor?: string;
+    /** Code block background color. */
+    codeBgColor?: string;
+    /** Blockquote border/accent color. */
+    quoteBorderColor?: string;
+    /**
+     * Blockquote text color. Defaults to {@link MarkdownTheme.textColor} so
+     * blockquote body text matches surrounding prose unless overridden.
+     */
+    quoteTextColor?: string;
+    /** Horizontal-rule color. */
+    hrColor?: string;
+    /** Table background color. */
+    tableBgColor?: string;
+    /** Table header background color. */
+    tableHeaderBgColor?: string;
+    /** Link text color. */
+    linkColor?: string;
+    /**
+     * Color for TeX source shown verbatim when a formula could not be typeset.
+     * Deliberately distinct from body text so an untypeset formula is visible as
+     * a failure rather than reading as prose.
+     */
+    mathFallbackColor?: string;
+    /** Code-block keyword color. */
+    syntaxKeywordColor?: string;
+    /** Code-block string-literal color. */
+    syntaxStringColor?: string;
+    /** Code-block comment color. */
+    syntaxCommentColor?: string;
+    /** Code-block numeric-literal color. */
+    syntaxNumberColor?: string;
+    /** Body font. */
+    bodyFont?: string;
+    /** Monospace font for code. */
+    codeFont?: string;
+    /** Base font size in px. */
+    fontSize?: number;
+    /**
+     * Font sizes in px for heading depths 1-6. A shorter array is padded by
+     * repeating its last entry; depths past the end clamp to the last entry.
+     */
+    headingSizes?: readonly number[];
+    /** Code-block font size in px. */
+    codeFontSize?: number;
+    /**
+     * Table cell font size in px.
+     *
+     * Left `undefined` by default and **derived** as `fontSize - 2` (clamped to
+     * at least 1) rather than defaulted to a literal, because that is how it was
+     * hardcoded before it became a key: a caller who raises only `fontSize` must
+     * keep getting a proportionally larger table, which a fixed default would
+     * silently break.
+     */
+    tableFontSize?: number;
+    /** Code-block line height in px. */
+    codeLineHeight?: number;
+    /**
+     * Line height in px for body text drawn through the plain-`Text` fallback
+     * path (an unrecognised block token that still carries `text`).
+     */
+    bodyLineHeight?: number;
+    /** Vertical gap in px between top-level blocks. */
+    blockGap?: number;
+    /** Inner padding in px of a code block. */
+    codePadding?: number;
+    /** Corner radius in px of a code block. */
+    codeRadius?: number;
+    /** Vertical gap in px between list items. */
+    listGap?: number;
+    /** Vertical gap in px between blocks inside one multi-block list item. */
+    listItemGap?: number;
+    /** Left indent in px of a blockquote's contents. */
+    quoteIndent?: number;
+    /** Width in px of a blockquote's accent border. */
+    quoteBorderWidth?: number;
+    /** Vertical gap in px between blocks inside a blockquote. */
+    quoteInnerGap?: number;
+    /** Corner radius in px of an image. */
+    imageRadius?: number;
+    /**
+     * Height of an image that renders *inline*, as a multiple of the run's font
+     * size.
+     *
+     * Applies only where an image shares a line with text — a heading or a table
+     * cell. An image that is its own block (the ordinary `![alt](url)` paragraph)
+     * still renders at its natural size capped to the available width, and ignores
+     * this.
+     *
+     * A cap rather than the natural size, because an inline object's box is fixed
+     * when the span is collected while the natural size is known only after the
+     * decode, and because a 512px logo written into an `h1` would otherwise tower
+     * over its own heading. The width follows the natural aspect ratio, so a wide
+     * badge stays wide. `1.15` keeps a square icon a little shorter than the line it
+     * sits on, which is where a cap-height glyph puts its own ink.
+     */
+    inlineImageScale?: number;
+}
+/**
+ * Resolved defaults. Every key of {@link MarkdownTheme} has an entry here, so a
+ * resolved theme is `Required<MarkdownTheme>` and no consumer needs a fallback.
+ *
+ * Two entries are placeholders that {@link resolveTheme} overwrites when the
+ * caller did not set them: `quoteTextColor` (follows `textColor`) and
+ * `tableFontSize` (derived from `fontSize`). They still carry a literal so this
+ * object satisfies `Required<MarkdownTheme>`; read {@link resolveTheme} for the
+ * value a caller actually gets.
+ */
+export declare const DEFAULT_THEME: Required<MarkdownTheme>;
+/**
+ * Merge a caller's partial theme over {@link DEFAULT_THEME}.
+ *
+ * `tableFontSize` is **derived** from the resolved `fontSize` when the caller
+ * did not set it explicitly, so raising only `fontSize` still scales tables.
+ * A plain spread cannot express that: `DEFAULT_THEME` has to satisfy
+ * `Required<MarkdownTheme>`, so its literal would always win over the
+ * derivation.
+ */
+export declare function resolveTheme(theme?: MarkdownTheme): Required<MarkdownTheme>;
+/**
+ * Font size in px for a 1-based heading depth, clamping past the end of
+ * `headingSizes` and tolerating a short or empty array.
+ *
+ * Extracted so the heading renderer and any caller inspecting the scale agree;
+ * an inline `sizes[Math.min(depth - 1, 5)]` silently yields `undefined` for a
+ * theme that supplied fewer than six sizes.
+ */
+export declare function headingSize(theme: Required<MarkdownTheme>, depth: number): number;