@vectojs/markdown 0.16.1 → 0.18.0

package/dist/markdown-abbr.d.ts

@@ -0,0 +1,73 @@
+import type { TokenizerAndRendererExtension, Token } from 'marked';
+/**
+ * `markdown-it-abbr`-style abbreviations: `*[HTML]: HyperText Markup Language`
+ * defines a term, and every later whole-word occurrence of `HTML` in the
+ * document's prose gets a dotted-underline visual treatment.
+ *
+ * This is architecturally unlike every other `PX-0524` span construct. Every
+ * other one (`sub`, `sup`, `ins`, `mark`, `emoji`) is a token-level
+ * substitution: the tokenizer sees the construct's own delimiters and emits a
+ * styled span right there. An abbreviation definition carries no delimiters at
+ * its use site at all — `HTML` in `The HTML spec` is indistinguishable from
+ * any other word until the WHOLE document's definitions are known. So this
+ * module only collects the dictionary; applying it to prose is
+ * `markdown-inline.ts`'s `emitProse` job, which every `collectSpans` leaf now
+ * routes through instead of pushing a bare span.
+ *
+ * ## Why this forces a full-document re-render on change
+ *
+ * A definition can be written anywhere — GFM allows it inline, but the
+ * convention (and this module's only shape) is one line, and streamed
+ * documents commonly put them at the end, same as footnotes. If a definition
+ * arrives in the incremental-lex TAIL while the term it defines already
+ * rendered in the STABLE PREFIX, the prefix's paragraph entities were built by
+ * `collectSpans` before the dictionary contained that term, and `Markdown.ts`'s
+ * `updateTokens` reuses an entity whenever its token's `raw` is byte-identical
+ * — which it is, since the term's OWN paragraph did not change, only a
+ * definition elsewhere did. This is exactly `hasLinkDefinitions`'s own
+ * problem (a reference definition arriving late must retroactively change
+ * already-rendered inline tokens) and gets the same fix at the same layer:
+ * `Markdown.ts` tracks the resolved dictionary across renders and forces a full
+ * rebuild — not merely a full re-LEX, which `incrementalLex.ts` already gets
+ * right regardless — whenever it changes. See `Markdown.ts`'s
+ * `abbreviationsChanged` check next to `updateTokens`.
+ */
+/** `*[TERM]: definition` — collected metadata, not rendered content. */
+export interface AbbrDefToken {
+    type: 'abbrDef';
+    raw: string;
+    /** The term exactly as written between `*[` and `]`, e.g. `HTML`. */
+    term: string;
+    /** The definition text, shown as the term's tooltip title in prose. */
+    definition: string;
+}
+/**
+ * The single `marked.use` block extension, shared between `Markdown.ts` and
+ * `MarkdownWorker.ts` — same lockstep requirement `markdown-footnote.ts`
+ * documents at length: the two lexers must agree exactly.
+ *
+ * No `start()`, for the same reason `footnoteDef` supplies none: a block
+ * `start()` retroactively re-groups paragraphs already emitted (see
+ * `markdown-footnote.ts`'s measured evidence). Its absence costs the same one
+ * spec-adjacent behaviour footnotes already accept — a definition on the line
+ * directly after a paragraph with no blank line between is absorbed into that
+ * paragraph rather than recognised.
+ */
+export declare const ABBR_EXTENSIONS: TokenizerAndRendererExtension[];
+/**
+ * Whether `text` contains an abbreviation-definition line at all.
+ *
+ * Cheap reject first (`*[` is rare outside this construct), matching every
+ * other opener-detector in this package (`hasContainerOpener`,
+ * `hasFootnoteDefOpener`).
+ */
+export declare function hasAbbrDef(text: string): boolean;
+/**
+ * Scan top-level tokens for `abbrDef` entries and build the term dictionary.
+ *
+ * Later definitions of the same term win — the same "last write wins" rule
+ * `marked` itself applies to duplicate link reference definitions — rather
+ * than throwing or silently keeping the first, since a streamed document has
+ * no way to reject a correction after the fact.
+ */
+export declare function collectAbbreviations(tokens: readonly Token[]): ReadonlyMap<string, string>;

package/dist/markdown-code.d.ts

@@ -1,6 +1,7 @@
 import { type ContentProjection, type ContentProjectionHint, GlyphRasterAtlas, type GlyphRasterAtlasStats, IRenderer } from '@vectojs/core';
 import { UIComponent } from '@vectojs/ui';
-import { type MarkdownTheme } from './theme';
+import { type MarkdownThemePresetName } from './markdown-presets';
+import type { MarkdownTheme } from './theme';
 /**
  * A single self-rendering entity for fenced code blocks.
  *
@@ -28,14 +29,17 @@ export declare class CodeBlock extends UIComponent {
     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.
+     * @param theme Any subset of {@link MarkdownTheme}, or the name of a built-in
+     *   preset (see {@link MarkdownThemePresetName}). 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. Resolved through {@link resolvePresetTheme} so `CodeBlock` can
+     *   be constructed directly with a preset name without going through
+     *   `Markdown`.
      */
-    constructor(code: string, lang: string, maxWidth: number, theme: MarkdownTheme, selectable?: boolean);
+    constructor(code: string, lang: string, maxWidth: number, theme: MarkdownThemePresetName | 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. */

package/dist/markdown-container.d.ts

@@ -0,0 +1,85 @@
+import type { Token, TokenizerAndRendererExtension } from 'marked';
+/**
+ * `:::` fenced containers (`:::note … :::`, `:::warning … :::`), the
+ * `remark-directive`/`markdown-it-container` construct.
+ *
+ * One new `marked.use` **block** extension. Nothing in `marked`'s grammar,
+ * including GFM, tokenizes a `:::` fence at all — verified against
+ * marked@18.0.7: it falls through to plain `paragraph`/`text` (`PX-0524`).
+ *
+ * Registered in `Markdown.ts` and `MarkdownWorker.ts` from this single shared
+ * array, for the reason `markdown-footnote.ts` gives at length: the two
+ * lexers must agree exactly, or the worker emits tokens the renderer has no
+ * arm for.
+ *
+ * Deliberately holds no entity, theme or `@vectojs/*` import, so this module
+ * stays safe to inline into the worker bundle (`scripts/build-worker.js`,
+ * `bundle: true`).
+ */
+/** A `:::kind\n…body…\n:::` block, its body block-lexed like a blockquote's. */
+export interface ContainerToken {
+    type: 'container';
+    raw: string;
+    /**
+     * The word after `:::` on the opening line, e.g. `'note'`. `undefined` for
+     * a bare `:::` with nothing after it — a container with no declared kind
+     * still fences its content, it just has no theme-mapped colour or label.
+     */
+    kind?: string;
+    /** Nested block tokens, exactly as `blockquote`'s `tokens` field. */
+    tokens: Token[];
+}
+/**
+ * The two extensions, in the order they are registered.
+ *
+ * ## No `start()`, for the same reason `footnoteDef` has none
+ *
+ * A block `start()` clips the text handed to the paragraph tokenizer and
+ * retroactively re-groups an already-emitted paragraph the moment a `:::`
+ * appears anywhere ahead — `markdown-footnote.ts`'s doc comment measures this
+ * exhaustively for `[^`, and the same `Lexer.blockTokens` mechanism applies
+ * here verbatim. Omitting it costs the same one CommonMark-adjacent
+ * behaviour footnotes already give up: a fence written directly after a
+ * paragraph line, with no blank line between, is absorbed into that
+ * paragraph instead of opening a container. Verified empirically against
+ * marked@18.0.7.
+ *
+ * ## The forward-reach hazard this construct DOES have
+ *
+ * Unlike `footnoteDef` (single-line, cannot reach past its own token) but
+ * LIKE `blockMath`, an unterminated `:::` opener can absorb arbitrarily much
+ * of the document once its closing fence eventually arrives — the tokenizer
+ * below scans forward for a depth-balanced close with no bound on how far. Measured: a
+ * prefix ending in an open `:::note\nHello` block-lexes to
+ * `[paragraph, space, paragraph]` (an ordinary unterminated-fence-reads-as-
+ * text fallback), and appending `\n\nWorld\n:::\n` collapses ALL of it into a
+ * single `container` token whose nested tokens are `[paragraph('Hello'),
+ * space, paragraph('World')]` — the same forward-reach shape `blockMath`'s
+ * `$$` used to have. `incrementalLex.ts`'s `hasContainerOpener()` therefore
+ * degrades an instance outright, using the same `OPEN_RE` this module exports
+ * for that check to share the exact definition of "a fence is open" with the
+ * tokenizer.
+ *
+ * Note `blockMath` no longer degrades: its tokenizer now stops at a blank line,
+ * so its forward reach is bounded and its backward reach is handled by
+ * `paragraphPairCap`. A `:::` fence still spans blank lines by design — that is
+ * the whole point of a container — so the forward hazard is real here and the
+ * blanket degrade stays.
+ *
+ * ## Why an extension is enough
+ *
+ * `marked.use` extensions run BEFORE the built-in tokenizers (`Lexer.use`
+ * inserts with `unshift`), so `container` claims the `:::` line ahead of the
+ * built-in `paragraph`/`text` rules — the same ordering `footnoteRef`/
+ * `footnoteDef` rely on, contradicting the earlier (wrong) assumption
+ * recorded in `PX-0517`/`DEC-01KZDGBE`.
+ *
+ * ## `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 every other extension in this package.
+ */
+export declare const CONTAINER_EXTENSIONS: TokenizerAndRendererExtension[];
+/** Whether `text` contains a `:::` opener that {@link OPEN_RE} would match. */
+export declare function hasContainerOpener(text: string): boolean;

package/dist/markdown-emoji.d.ts

@@ -0,0 +1,39 @@
+import type { TokenizerAndRendererExtension } from 'marked';
+/**
+ * GitHub-style emoji shortcodes: `:wink:` -> 😉.
+ *
+ * A new `marked.use` inline extension, the same shape as
+ * `markdown-superscript.ts`'s `sup`: `:name:` is not tokenized by marked's
+ * built-in grammar at all (verified against marked@18.0.7 — falls through to
+ * plain `text`, `PX-0524`), so it needs its own tokenizer.
+ *
+ * Unlike `sup`/`ins`/`mark`, the token carries no NEW rendering behaviour —
+ * once resolved, a shortcode is exactly a run of plain text (the emoji
+ * character itself), which the browser's font stack already shapes and colors
+ * via `fillText` like any other codepoint. So this module's only real content
+ * is the lookup table; `collectSpans`' `emoji` arm just pushes the resolved
+ * character with the inherited style, unchanged.
+ *
+ * Registered in `Markdown.ts` and `MarkdownWorker.ts` from this single shared
+ * array, for the reason `markdown-footnote.ts` gives at length: the two lexers
+ * must agree exactly, or the worker emits tokens the renderer has no arm for.
+ *
+ * Deliberately holds no entity, theme or `@vectojs/*` import, so this module
+ * stays safe to inline into the worker bundle (`scripts/build-worker.js`,
+ * `bundle: true`).
+ */
+/** `:name:`, as it appears mid-sentence, already resolved to its character. */
+export interface EmojiToken {
+    type: 'emoji';
+    raw: string;
+    /** The resolved emoji character(s), e.g. `'😉'` — never the shortcode text. */
+    text: string;
+}
+/**
+ * Shortcode -> emoji character, a representative common subset of GitHub's
+ * table (github/gemoji), not the full ~1800-entry set. Extending this table
+ * only ever adds a lookup entry; it never touches the tokenizer or
+ * `collectSpans`, so growing it later is a one-line-per-emoji change.
+ */
+export declare const EMOJI_MAP: Readonly<Record<string, string>>;
+export declare const EMOJI_EXTENSIONS: TokenizerAndRendererExtension[];

package/dist/markdown-entities.d.ts

@@ -31,3 +31,21 @@ export declare class MarkdownContainer extends Entity {
     isPointInside(_globalX: number, _globalY: number): boolean;
     render(_r: any): void;
 }
+/**
+ * A rounded-rect background fill for a `:::` container's full content area.
+ *
+ * A separate leaf rather than folding the fill into {@link QuoteBorder}: a
+ * blockquote's accent bar is the ONLY visual besides its text, but a container
+ * additionally has a background — real callout components (Docusaurus
+ * admonitions, mdBook, GitHub's `[!NOTE]`) all paint one — and the two need
+ * independent geometry (the fill spans the full width, the bar is a narrow
+ * strip at `x=0`), so one entity cannot own both a `width`/`height` box and a
+ * bar `width`.
+ */
+export declare class ContainerBackground extends Entity {
+    color: string;
+    radius: number;
+    constructor(w: number, h: number, color: string, radius: number);
+    isPointInside(): boolean;
+    render(r: IRenderer): void;
+}

package/dist/markdown-fenced-registry.d.ts

@@ -0,0 +1,159 @@
+import type { Entity } from '@vectojs/core';
+import type { MarkdownTheme } from './theme';
+/**
+ * Fenced block renderer registry: pluggable rendering for code fences keyed by
+ * info string.
+ *
+ * Each language (code, math, mermaid, graphviz, …) is a plugin rather than a
+ * branch in `Markdown.renderToken`. Renderers lazy-load on demand and cache
+ * conversions, reusing the pattern math already established.
+ *
+ * ## Lifecycle
+ *
+ * A renderer may be in one of three states:
+ * - **incomplete**: The renderer is registered but its module/assets are not
+ *   loaded yet. The first call to `render()` triggers the load.
+ * - **ready**: The renderer is loaded and can render synchronously.
+ * - **error**: The renderer failed to load or encountered an unrecoverable error.
+ *   Falls back to default code block rendering.
+ *
+ * ## Fallback
+ *
+ * When no renderer is registered for a language, or when a renderer returns
+ * `null`, the registry falls back to the default code block renderer. This
+ * preserves backward compatibility and degrades gracefully.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { FencedBlockRegistry } from '@vectojs/markdown';
+ *
+ * // Register a custom renderer
+ * FencedBlockRegistry.register('mermaid', {
+ *   async load() {
+ *     const mermaid = await import('mermaid');
+ *     return (source, lang, options) => {
+ *       // ... render logic
+ *       return entity;
+ *     };
+ *   }
+ * });
+ *
+ * // Unregister (for testing or cleanup)
+ * FencedBlockRegistry.unregister('mermaid');
+ * ```
+ */
+/**
+ * Options passed to a fenced block renderer.
+ *
+ * Includes the theme, available width, and whether text should be selectable.
+ * Renderers may ignore options that don't apply to their output format.
+ */
+export interface FencedBlockRenderOptions {
+    /** The current Markdown theme (colors, fonts, sizes). */
+    theme: MarkdownTheme;
+    /** Available horizontal space in pixels. */
+    availableWidth: number;
+    /** Whether text content should be selectable. */
+    selectable: boolean;
+}
+/**
+ * A fenced block renderer: converts source code in a specific language to an Entity.
+ *
+ * Returns `null` when rendering fails or the source is invalid. The caller falls
+ * back to a default code block.
+ */
+export type FencedBlockRenderer = (source: string, lang: string, options: FencedBlockRenderOptions) => Entity | null;
+/**
+ * A lazy-loadable renderer specification.
+ *
+ * The `load()` method is called once, the first time a fence with this language
+ * appears. It should return a synchronous renderer function, or `null` if loading
+ * fails. Failures are logged but swallowed — the fence renders as a code block.
+ */
+export interface FencedBlockRendererSpec {
+    /**
+     * Load the renderer asynchronously.
+     *
+     * Called exactly once, the first time a fence with this language is encountered.
+     * Returns a synchronous renderer, or `null` on failure. The promise rejection
+     * is caught and logged; renderers must not leave unhandled rejections.
+     */
+    load: () => Promise<FencedBlockRenderer | null>;
+}
+/**
+ * Register a lazy-loadable fenced block renderer for a language.
+ *
+ * @param lang - The language identifier (case-insensitive). Normalized to lowercase.
+ * @param spec - The renderer specification, with a `load()` method.
+ *
+ * @example
+ * ```typescript
+ * FencedBlockRegistry.register('mermaid', {
+ *   async load() {
+ *     const mermaid = await import('mermaid');
+ *     return (source, lang, options) => {
+ *       // ... render Mermaid diagram
+ *       return entity;
+ *     };
+ *   }
+ * });
+ * ```
+ */
+export declare function registerFencedBlockRenderer(lang: string, spec: FencedBlockRendererSpec): void;
+/**
+ * Unregister a fenced block renderer.
+ *
+ * Used for testing (sabotage tests) and cleanup. After unregistering, fences with
+ * this language fall back to the default code block renderer.
+ *
+ * @param lang - The language identifier (case-insensitive).
+ */
+export declare function unregisterFencedBlockRenderer(lang: string): void;
+/**
+ * Check if a renderer is registered for a language.
+ *
+ * Returns `true` if a renderer is registered, regardless of whether it has loaded yet.
+ *
+ * @param lang - The language identifier (case-insensitive).
+ */
+export declare function hasFencedBlockRenderer(lang: string): boolean;
+/**
+ * Check if a renderer is ready (loaded and available for synchronous rendering).
+ *
+ * Returns `false` if the renderer is not registered, not loaded yet, or failed to load.
+ *
+ * @param lang - The language identifier (case-insensitive).
+ */
+export declare function isFencedBlockRendererReady(lang: string): boolean;
+/**
+ * Begin (or join) loading a fenced block renderer.
+ *
+ * Idempotent: the load promise is cached, so multiple callers share one load.
+ * Failures are swallowed — the renderer simply stays unavailable.
+ *
+ * Call this when a fence with this language first appears, even while it is still
+ * open (incomplete). This prefetches the module so the closing fence can render
+ * synchronously, hiding the lazy load during a stream.
+ *
+ * @param lang - The language identifier (case-insensitive).
+ * @returns A promise that resolves when the renderer is ready, or immediately if
+ *          already loaded.
+ */
+export declare function ensureFencedBlockRenderer(lang: string): Promise<void>;
+/**
+ * Render a fenced code block using the registered renderer for its language.
+ *
+ * Returns `null` if:
+ * - No renderer is registered for this language
+ * - The renderer is not loaded yet
+ * - The renderer returned `null` (rendering failed)
+ *
+ * The caller falls back to the default code block renderer in all three cases.
+ *
+ * @param source - The source code inside the fence.
+ * @param lang - The language identifier (case-insensitive).
+ * @param options - Rendering options (theme, width, selectable).
+ * @returns The rendered entity, or `null` to fall back to default code block.
+ */
+export declare function renderFencedBlock(source: string, lang: string, options: FencedBlockRenderOptions): Entity | null;

package/dist/markdown-footnote.d.ts

@@ -1,4 +1,4 @@
-import type { TokenizerAndRendererExtension } from 'marked';
+import type { Token, TokenizerAndRendererExtension } from 'marked';
 /**
  * GFM footnotes: the two `marked` tokenizer extensions, their token types, and
  * the marker text a reference renders as.
@@ -32,15 +32,45 @@ export interface FootnoteRefToken {
     /** 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. */
+/**
+ * A footnote definition — `[^1]: The note.` — as its own block, optionally
+ * followed by indented continuation lines that extend the body across
+ * multiple paragraphs (`markdown-it`'s and GFM's own shape for this).
+ */
 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. */
+    /** The header line's body text, source text with inline markup unparsed. */
     body: string;
+    /**
+     * Block tokens for any indented continuation content after the header line
+     * (further paragraphs, lists, code, …), block-lexed exactly like a
+     * blockquote's `tokens`. Empty when the definition is single-line, which is
+     * the overwhelming majority — a definition is only ever multi-paragraph when
+     * the source actually indents a second block under it.
+     */
+    tokens: Token[];
 }
+/**
+ * Whether `text` contains a `[^label]:` header that {@link HEADER_RE} would
+ * match, ANYWHERE in the document — the exact condition under which
+ * {@link consumeContinuation} can still be scanning forward (an open
+ * continuation) when more text arrives.
+ *
+ * Used by `incrementalLex.ts`'s degrade check, mirroring `hasContainerOpener`:
+ * a footnote definition's continuation-consuming tokenizer has the exact same
+ * forward-reach hazard a `:::` fence does, now that it can span a blank line.
+ * (`blockMath` used to be the third member of this set; its tokenizer now stops
+ * at a blank line, so it no longer degrades — see `paragraphPairCap`.) Deliberately does not try to determine
+ * whether a SPECIFIC header's continuation is still open — that would need to
+ * replicate the tokenizer's own scan — and instead degrades on the mere
+ * presence of any header, which is safe (if conservative) the same way
+ * `hasContainerOpener` accepts matching inside a fenced code block it would
+ * never actually reach.
+ */
+export declare function hasFootnoteDefOpener(text: string): boolean;
 /**
  * The two extensions, in the order they are registered.
  *

package/dist/markdown-inline.d.ts

@@ -13,6 +13,35 @@ import type { MarkdownTheme } from './theme';
  */
 /** Decode basic HTML entities that `marked` emits in token text. */
 export declare function decodeEntities(text: string): string;
+/**
+ * `markdown-it`'s `typographer` substitutions: dashes, ellipsis, trademark
+ * symbols, and quote pairs contained within one run of prose.
+ *
+ * Off by default (`theme.typographer`), matching markdown-it's own default —
+ * these are characters the author did not literally type, so applying them
+ * unconditionally would silently rewrite a document's source.
+ *
+ * ## Quote pairing is INTRA-RUN only
+ *
+ * `"quoted"` becomes curly only when both its opening and closing `"` are in
+ * the SAME decoded text run. A quote that spans an inline-markup boundary
+ * (`"quoted *emphasis* text"` splits into three text tokens around the `em`)
+ * is not paired across that boundary and stays straight. `collectSpans`
+ * recurses per-token with no shared mutable state across siblings, and
+ * markdown-it's own quote rule needs exactly that — a per-paragraph
+ * open/close stack — to pair nested and cross-boundary quotes. Threading that
+ * state through this module's recursion is a materially larger change,
+ * deferred until a real document exercises the gap.
+ *
+ * ## Apostrophes vs. quote delimiters
+ *
+ * A `'` between two letters (`it's`, `y'all`) is a contraction, not a quote
+ * delimiter, and is replaced with a closing curly quote BEFORE quote pairing
+ * runs — otherwise `it's fine, 'nice' day` would pair the apostrophe in
+ * `it's` with the opening `'` of `'nice'`, consuming both instead of matching
+ * `'nice'` on its own.
+ */
+export declare function applyTypography(text: string): string;
 /**
  * Recursively walk the inline token tree, accumulating {@link StyledSpan}s
  * with inherited style overrides (bold, italic, etc.).
@@ -26,7 +55,14 @@ export declare function collectSpans(tokens: Token[], inherited: TextStyle, them
  * its size in its `font` string rather than in any span style, so it cannot be
  * recovered from `inherited`.
  */
-blockFontSize?: number): void;
+blockFontSize?: number, 
+/**
+ * The document's `*[TERM]: definition` dictionary, applied to every prose
+ * leaf via {@link emitProse}. Defaults to {@link NO_ABBREVIATIONS} so every
+ * call site that has none to thread — nested recursive calls, and callers
+ * predating this feature — costs nothing extra.
+ */
+abbr?: ReadonlyMap<string, string>): void;
 /**
  * One trailing inline construct that has opened but not closed yet.
  *
@@ -55,4 +91,6 @@ export interface UnclosedInline {
  */
 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;
+export declare function renderInlineToRichText(tokens: Token[] | undefined, fallbackText: string, font: string, color: string, maxWidth: number, theme: Required<MarkdownTheme>, selectable: boolean, onLinkClick?: (url: string) => void, 
+/** The document's `*[TERM]: definition` dictionary — see {@link emitProse}. */
+abbr?: ReadonlyMap<string, string>): RichText;

package/dist/markdown-ins-mark.d.ts

@@ -0,0 +1,33 @@
+import type { TokenizerAndRendererExtension } from 'marked';
+/**
+ * `markdown-it`-style insert and highlight: `++inserted++`, `==marked==`.
+ *
+ * Two new `marked.use` inline extensions, the same shape as
+ * `markdown-superscript.ts`'s `sup`: neither `+` nor `==` is tokenized by
+ * marked's built-in grammar at all (verified against marked@18.0.7 — both fall
+ * through to plain `text`, `PX-0524`), so each needs its own tokenizer rather
+ * than reusing an existing token type the way single-tilde subscript reuses
+ * `del`.
+ *
+ * Registered in `Markdown.ts` and `MarkdownWorker.ts` from this single shared
+ * array, for the reason `markdown-footnote.ts` gives at length: the two lexers
+ * must agree exactly, or the worker emits tokens the renderer has no arm for.
+ *
+ * Deliberately holds no entity, theme or `@vectojs/*` import, so this module
+ * stays safe to inline into the worker bundle (`scripts/build-worker.js`,
+ * `bundle: true`).
+ */
+/** `++content++`, as it appears mid-sentence. See `SuperscriptToken` for why
+ *  this carries `text` rather than a distinct field name. */
+export interface InsToken {
+    type: 'ins';
+    raw: string;
+    text: string;
+}
+/** `==content==`, as it appears mid-sentence. */
+export interface MarkToken {
+    type: 'mark';
+    raw: string;
+    text: string;
+}
+export declare const INS_MARK_EXTENSIONS: TokenizerAndRendererExtension[];

package/dist/markdown-presets.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Named theme presets for `@vectojs/markdown`.
+ *
+ * Each preset is a full {@link MarkdownTheme} partial whose color tokens are
+ * sourced verbatim from the palette's upstream specification:
+ *
+ * - **`githubDark`** — GitHub Dark Default (Primer dark palette).
+ *   Source: `primer/github-vscode-theme` / `rouge-ruby/rouge` Primer primitives.
+ * - **`githubLight`** — GitHub Light Default (Primer light palette).
+ *   Source: same — P_RED_5, P_BLUE_6/P_BLUE_8, P_GRAY_5, P_GRAY_9, canvas tokens.
+ * - **`dracula`** — Dracula Classic.
+ *   Source: https://draculatheme.com/spec and https://github.com/dracula/dracula-theme
+ * - **`solarizedDark`** — Solarized dark mode.
+ *   Source: https://ethanschoonover.com/solarized/ (L*a*b canonical, sRGB values).
+ * - **`solarizedLight`** — Solarized light mode.
+ *   Source: same palette, base-pair swapped per Schoonover's own CSS snippet
+ *   (light: `base3:base0` background/foreground, `base2` background highlight,
+ *   `base1` comments; dark: `base03:base0`, `base02`, `base01`).
+ *
+ * Spacing and typography keys are NOT set in presets: they remain at
+ * {@link DEFAULT_THEME} defaults so a caller who passes `theme: 'dracula'`
+ * gets Dracula colors on a correctly-spaced layout without having to restate
+ * every dimension.
+ *
+ * Light presets apply a CONTRAST PASS on translucent overlays
+ * (`codeBgColor`, `tableHeaderBgColor`, `containerBgColor`, `markHighlightColor`,
+ * `hrColor`): the stock theme is dark and its translucent values composite
+ * against a near-black surface. On a white/cream background the same RGBA
+ * values produce the wrong visual weight, so light presets use opaque or
+ * differently-composited colors derived from the palette instead.
+ */
+import { type MarkdownTheme } from './theme';
+/** Names of the built-in theme presets. */
+export type MarkdownThemePresetName = 'githubDark' | 'githubLight' | 'dracula' | 'solarizedDark' | 'solarizedLight';
+/** Look-up table from preset name to its partial {@link MarkdownTheme}. */
+export declare const PRESET_THEMES: Readonly<Record<MarkdownThemePresetName, MarkdownTheme>>;
+/**
+ * Return `true` if `value` is a recognised {@link MarkdownThemePresetName}.
+ *
+ * Use this to branch on `theme?: MarkdownThemePresetName | MarkdownTheme`
+ * before calling {@link resolvePresetTheme}.
+ */
+export declare function isPresetName(value: unknown): value is MarkdownThemePresetName;
+/**
+ * Resolve a `theme` option that may be a preset name, a full/partial
+ * {@link MarkdownTheme}, or `undefined`, into a `Required<MarkdownTheme>`.
+ *
+ * Always calls {@link resolveTheme} rather than spreading {@link PRESET_THEMES}
+ * or `DEFAULT_THEME` directly, so the derived keys (`tableFontSize` from
+ * `fontSize`, `quoteTextColor`/`footnoteColor` from `textColor`/`linkColor`)
+ * still apply on top of a preset exactly as they do for a hand-written theme —
+ * a preset that sets `linkColor` but not `footnoteColor` should still get a
+ * footnote marker in the preset's link color, not the stock accent.
+ *
+ * A plain `MarkdownTheme` object is passed straight to `resolveTheme` unchanged
+ * (this is the pre-existing, non-preset path); a preset name is looked up in
+ * {@link PRESET_THEMES} first.
+ */
+export declare function resolvePresetTheme(theme?: MarkdownThemePresetName | MarkdownTheme): Required<MarkdownTheme>;

package/dist/markdown-superscript.d.ts

@@ -0,0 +1,36 @@
+import type { TokenizerAndRendererExtension } from 'marked';
+/**
+ * `markdown-it`-style superscript: `19^th^`, `x^2^`.
+ *
+ * A new `marked.use` inline extension, unlike subscript — single-tilde already
+ * lexed to a real token (`del`) that `collectSpans` merely had to recognise by
+ * `raw`. Nothing in `marked`'s built-in grammar produces a token for `^…^` at
+ * all: it falls through to plain `text`, verified against marked@18.0.7 in
+ * `PX-0524`. So superscript needs its own tokenizer, the same shape as
+ * `markdown-footnote.ts`'s `footnoteRef`.
+ *
+ * Registered in `Markdown.ts` and `MarkdownWorker.ts` from this single shared
+ * array, for the reason `markdown-footnote.ts` gives at length: the two lexers
+ * must agree exactly, or the worker emits tokens the renderer has no arm for.
+ *
+ * Deliberately holds no entity, theme or `@vectojs/*` import, so this module
+ * stays safe to inline into the worker bundle (`scripts/build-worker.js`,
+ * `bundle: true`).
+ */
+/**
+ * `^content^`, as it appears mid-sentence.
+ *
+ * Carries `text` rather than a distinct field name — unlike
+ * {@link import('./markdown-footnote').FootnoteRefToken}, which avoids `text`
+ * so an unhandled token falls through to nothing rather than to a wrong
+ * render. A superscript token IS mostly text, just raised: `producesEntity`'s
+ * `'text' in token` fallback rendering it as an ordinary block if this arm were
+ * ever missing is a reasonable enough degradation (plain, unraised text) that
+ * the distinct-name defence footnotes need does not apply here.
+ */
+export interface SuperscriptToken {
+    type: 'sup';
+    raw: string;
+    text: string;
+}
+export declare const SUPERSCRIPT_EXTENSIONS: TokenizerAndRendererExtension[];