@vectojs/markdown 0.16.0 → 0.17.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 (`hasBlockMathOpener`,
+ * `hasContainerOpener`).
+ */
+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,79 @@
+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 shape `blockMath`'s doc comment
+ * documents for `$$`. `incrementalLex.ts`'s `hasContainerOpener()` therefore
+ * degrades an instance the same way `hasBlockMathOpener()` does, using the
+ * same `OPEN_RE` this module exports for that check to share the exact
+ * definition of "a fence is open" with the tokenizer.
+ *
+ * ## 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-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,44 @@ 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 `hasBlockMathOpener`
+ * and `hasContainerOpener`: a footnote definition's continuation-consuming
+ * tokenizer has the exact same forward-reach hazard those two document, now
+ * that it can span a blank line. 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
+ * `hasBlockMathOpener` 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[];

package/dist/markdown-typography.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Typographic replacements: `--`/`---` to en/em dash, `...` to `…`, `(c)`/`(r)`/
+ * `(tm)` to `©`/`®`/`™`, `+-` to `±`, and repeated `!`/`,` collapsing —
+ * `markdown-it`'s `typographer: true` set, minus smart quotes (see below).
+ *
+ * Ported as a **pure text transform** rather than a new tokenizer or `marked`
+ * extension, because that is what it is upstream too: `markdown-it`'s own
+ * `replacements` rule runs as a `core` pass over already-tokenized `text`
+ * content, not a grammar rule, and every substitution here is describable the
+ * same way — a regex over a string that changes no token boundaries. Applying
+ * it as the last step before a `text`-bearing span is pushed keeps this
+ * completely orthogonal to every other inline arm: a bold/italic/code run's
+ * content transforms identically to a plain paragraph's, because it is the same
+ * function call, not a special case duplicated per arm.
+ *
+ * ## Off by default, unlike every other construct in this package
+ *
+ * `markdown-it` itself defaults `typographer` to `false`, and this mirrors
+ * that rather than picking a different default for parity's own sake: the
+ * transform is lossy (a real `--` a caller wanted to keep literal, e.g. a CLI
+ * flag or a code-adjacent range, becomes an en dash with no way back short of
+ * disabling the whole feature) and every other construct in this package
+ * (subscript, superscript, ins/mark, emoji, footnotes) is instead
+ * unconditionally-on syntax recognition with no lossy default to weigh.
+ * `theme.typographer` (default `false`) is the gate, checked once per paragraph
+ * of text collection rather than per span, so a caller who never opts in pays
+ * nothing beyond the one boolean check `collectSpans` already does today for
+ * `inherited`.
+ *
+ * ## Smart quotes are deliberately NOT ported
+ *
+ * `markdown-it`'s `smartquotes` rule curls straight quotes into `‘’“”` by
+ * walking the FULL inline-token sequence of one block with a stack that
+ * matches an opening quote to its closing partner, consulting the previous and
+ * next token's own trailing/leading character across token boundaries (see
+ * `references/markdown-it/lib/rules_core/smartquotes.mjs`'s `process_inlines`).
+ * That is not a per-span text transform — it is a second pass over
+ * `collectSpans`' entire OUTPUT array, with cross-span state (the open-quote
+ * stack) and lookback/lookahead into neighboring spans' text. Porting it here
+ * would mean walking `out` after the fact, which every call site of
+ * `collectSpans`/`applyTypography` would have to remember to do, and getting it
+ * wrong reads as a rendering defect (mismatched curly quotes) rather than a
+ * missing feature. Left unimplemented; a caller wanting curled quotes still
+ * gets straight ones, the same honest fallback every unsupported construct in
+ * this package gets.
+ */
+/**
+ * Apply typographic substitutions to one run of plain text.
+ *
+ * Order matters and mirrors `markdown-it`'s own rule (`replace_scoped` before
+ * `replace_rare`, and within the latter: `+-`, then `...`, then the
+ * `?`/`!`-adjacent ellipsis correction, then `!!!!`/`,,`, then em-dash, then
+ * en-dash):
+ *
+ * - `+-` before `...`: neither can produce the other's trigger character, so
+ *   order between them is actually inert, but matching upstream's order keeps
+ *   this auditable against it rather than needing its own independent proof.
+ * - The em-dash pass runs before the en-dash pass. `---` is three hyphens; the
+ *   en-dash patterns below both require a NON-hyphen on the dash-adjacent side
+ *   (`(?=[^-]|$)` / preceded by whitespace or a non-hyphen-non-space), so `---`
+ *   itself never matches either en-dash pattern regardless of order — but a
+ *   FOUR-hyphen run (`----`) would: the em-dash regex only consumes exactly
+ *   three of the four hyphens (`(^|[^-])---(?=[^-]|$)` requires its OWN
+ *   boundary hyphens to be non-hyphen), leaving a leftover single hyphens on
+ *   either side that the leftover isn't itself `--`. Verified empirically
+ *   against `markdown-it`'s reference implementation that `----` and `---`
+ *   both resolve to one em dash: `----` is not decomposed into em+en, and
+ *   running en-dash first would have changed that (the outer pair of the four
+ *   hyphens would each independently look like the START of a `--` run before
+ *   the em-dash pass ever saw the middle two as a `---`).
+ */
+export declare function applyTypography(text: string): string;