@ai-react-markdown/engine 2.3.0

package/dist/index.d.ts

@@ -0,0 +1,1863 @@
+import { Element, Parents, Root as Root$1, ElementContent } from 'hast';
+import { Root } from 'mdast';
+import { Options } from 'remark-rehype';
+import { PluggableList, Processor, Plugin } from 'unified';
+import { VFile } from 'vfile';
+import { BuildVisitor } from 'unist-util-visit';
+import { defaultSchema } from 'rehype-sanitize';
+import { Handlers } from 'mdast-util-to-hast';
+import { RemendOptions } from 'remend';
+
+/**
+ * Streaming stress-payload fixtures, extracted verbatim from core's
+ * stories/streaming/scenarios.ts (boundary action ⑦): the engine's
+ * equivalence/sensitivity test batteries consume DEFAULT_PAYLOAD/withDefs,
+ * and stories keep using them through the engine entry — one source, no
+ * drifting copies.
+ *
+ * @module fixtures/scenarios
+ */
+declare const DEFAULT_PAYLOAD: string;
+/**
+ * Append the definitions tail to a payload (any payload — including the
+ * ALREADY-SCALED one; apply after `.repeat()` so one tail serves the whole
+ * document and no repeat seam glues a def line onto the next repetition).
+ *
+ * What this exercises — and what it does NOT: the default payload contains
+ * zero definitions, so without this tail the def-label scanner runs on a
+ * best-case input and the aggregate footnote footer never renders. With
+ * it, def lines stream through the scanner's active region (its full-parse
+ * slow path) and the footer assembles. It does NOT exercise the
+ * cross-chunk PHANTOM path: each benchmark side is a single chunk, so no
+ * label is ever defined "elsewhere" and the phantom candidate set stays
+ * empty — measuring that needs a second chunk contributing definitions
+ * the first one references.
+ */
+declare function withDefs(payload: string): string;
+
+/**
+ * Pipeline-facing types for the Markdown processing stages. The pure half of
+ * core's `components/markdown/types.ts`, split out in boundary action ③:
+ * every field here is consumed by the framework-agnostic pipeline
+ * (processor/transform/stages); the React-only `components` field stays in
+ * core, whose `Options` extends {@link PipelineOptions} with it.
+ *
+ * Ported 1:1 from react-markdown v10's lib/index.js JSDoc.
+ *
+ * @module components/markdown/types
+ */
+
+/** Filter callback for elements. Return falsy to drop. */
+type AllowElement = (element: Readonly<Element>, index: number, parent: Readonly<Parents> | undefined) => boolean | null | undefined;
+/** Transform every URL on every element attribute. Return null/empty to strip. */
+type UrlTransform = (url: string, key: string, node: Readonly<Element>) => string | null | undefined;
+/** Configuration consumed by the pipeline stages (parse/transform). */
+interface PipelineOptions {
+    allowElement?: AllowElement | null | undefined;
+    allowedElements?: ReadonlyArray<string> | null | undefined;
+    children?: string | null | undefined;
+    disallowedElements?: ReadonlyArray<string> | null | undefined;
+    rehypePlugins?: PluggableList | null | undefined;
+    remarkPlugins?: PluggableList | null | undefined;
+    remarkRehypeOptions?: Readonly<Options> | null | undefined;
+    skipHtml?: boolean | null | undefined;
+    unwrapDisallowed?: boolean | null | undefined;
+    urlTransform?: UrlTransform | null | undefined;
+}
+/**
+ * Internal: deprecated prop entry. `to` was `keyof Options` before the ③
+ * bisection; `'components'` is the one Options key that lives React-side,
+ * kept in the union so the deprecation table stays byte-identical.
+ */
+interface Deprecation {
+    from: string;
+    id: string;
+    to?: keyof PipelineOptions | 'components';
+}
+
+/**
+ * Unified processor and VFile setup. Ported 1:1 from react-markdown
+ * v10 `createProcessor` and `createFile`.
+ *
+ * @module components/markdown/processor
+ */
+
+/**
+ * Build the unified processor: remark-parse → remarkPlugins → remark-rehype →
+ * rehypePlugins. Returns an unfrozen processor — caller is expected to call
+ * `.parse()` and `.runSync()` (or `.run()`) on it.
+ */
+declare function createProcessor(options: Readonly<PipelineOptions>): Processor<Root, Root, Root$1, undefined, undefined>;
+/**
+ * Wrap the markdown string in a VFile so plugins that consume `file.value`
+ * work. Mirrors react-markdown: in dev `unreachable` throws an AssertionError
+ * for non-string `children`; in prod it silently no-ops, leaving `file.value`
+ * undefined and unified treating the input as empty.
+ */
+declare function createFile(options: Readonly<PipelineOptions>): VFile;
+
+/**
+ * The pure pipeline stages, lifted verbatim from core's Markdown.tsx
+ * (boundary action ②): parseStage / transformStage are framework-agnostic
+ * (mdast/hast in, hast out) and are consumed by the incremental-parse
+ * engine, so they live engine-side; renderHastSubtree and the `<Markdown>`
+ * component stay in core.
+ *
+ * The deprecation table and validation travel with parseStage — every
+ * caller (React or not) must get identical validation semantics.
+ *
+ * @module components/markdown/stages
+ */
+
+/** Bundled processor + parsed mdast + VFile, ready to feed `transformStage`. */
+interface ParsedMarkdown {
+    processor: Processor<Root, Root, Root$1, undefined, undefined>;
+    file: VFile;
+    mdast: Root;
+}
+/**
+ * Stage 1: validate options, build the unified processor, parse the markdown
+ * source into raw (pre-transform) mdast. The returned `mdast` is mutated in
+ * place by remark plugins during {@link transformStage}, but its top-level
+ * `position` offsets remain valid keys for hast→mdast lookup.
+ */
+declare function parseStage(options: Readonly<PipelineOptions>): ParsedMarkdown;
+/**
+ * Stage 2: run remark transformers, remark-rehype, and rehype plugins. Returns
+ * the final hast Root. The mdast in {@link ParsedMarkdown} may be mutated
+ * by remark transformers as a side effect of this call.
+ */
+declare function transformStage(parsed: ParsedMarkdown): Root$1;
+
+/**
+ * Single-pass hast tree transform: rewrites raw HTML, runs `urlTransform` on
+ * URL attributes, and applies `allowedElements` / `disallowedElements` /
+ * `allowElement` filters. Ported 1:1 from react-markdown v10.
+ *
+ * @module components/markdown/transform
+ */
+
+interface TransformContext {
+    allowedElements: ReadonlyArray<string> | null | undefined;
+    allowElement: AllowElement | null | undefined;
+    disallowedElements: ReadonlyArray<string> | null | undefined;
+    skipHtml: boolean | null | undefined;
+    unwrapDisallowed: boolean | null | undefined;
+    urlTransform: UrlTransform;
+}
+declare function buildTransform(ctx: TransformContext): BuildVisitor<Root$1>;
+
+/**
+ * Default URL transform — same allowlist as react-markdown / GitHub.
+ *
+ * @module components/markdown/urlTransform
+ */
+
+/**
+ * Make a URL safe.
+ *
+ * Allows `http`, `https`, `irc`, `ircs`, `mailto`, and `xmpp` protocols, plus
+ * URLs relative to the current protocol (e.g. `/foo`). Other protocols are
+ * stripped to the empty string. Mirrors GitHub's behaviour and matches
+ * `micromark-util-sanitize-uri` minus the URL-encoding pass.
+ */
+declare const defaultUrlTransform: UrlTransform;
+
+/**
+ * Freeze-boundary detector for incremental (prefix-freeze) parsing.
+ *
+ * Production port of the "L4" rule validated by the measurement study in
+ * `src/experiments/prefixFreeze/` (see its README for the ablation ladder,
+ * the falsification results, and the intentional two-way divergence note —
+ * stricter blockers AND looser code-span masking; the corpus-scoped
+ * directional pin lives in detectorConsistency.test.ts).
+ *
+ * The boundary is the largest source offset `b` such that, for ANY future
+ * append to `text`, the markdown blocks that begin before `b` parse
+ * byte-identically. Candidates are confirmed blank lines outside fenced
+ * code and flow math; a candidate survives only if every blocker below
+ * clears:
+ *
+ * 1. **Raw-HTML balance** — an unclosed container tag (or `<!--` comment)
+ *    before the candidate lets rehype-raw reparent later top-level siblings
+ *    into it (the v1.5.1 swallow bug, commit a8e89ec). Tag balance is
+ *    tracked outside fences; while any tag, comment, or raw block
+ *    (`<?…?>` / `<!DECL…>` / `<![CDATA[…]]>` — CommonMark html block types
+ *    3–5) is open, candidates are blocked. Line-truncated tag starts
+ *    (`<div` at EOL, attributes wrapping) count as opens.
+ * 2. **`$$` flow math** — remark-math's flow math swallows blank lines and
+ *    runs to EOF when unclosed (verified empirically); its closing fence
+ *    must sit at LINE START (a mid-line `$$` does not close it). Math
+ *    interiors are treated exactly like fence interiors: no candidates.
+ * 3. **Continuation context** — CommonMark lists, footnote definitions, and
+ *    indented code blocks are NOT terminated by blank lines; later indented
+ *    lines can extend a block that "ended" before the candidate. With the
+ *    definition-list extension enabled, `: description` bodies behave the
+ *    same way.
+ * 4. **Definition-list term claim** (`options.defListEnabled`) — the
+ *    micromark definition-list extension scans BACKWARD across exactly one
+ *    blank line to claim a preceding paragraph as a `<dt>`. A candidate
+ *    whose blank run is 1 is only safe once the next line is confirmed to
+ *    never match `^ {0,3}:[ \t]`; runs of ≥ 2 blanks are immune.
+ * 5. **Reference taint** — micromark decides reference-ness at parse time,
+ *    so a later `[label]:` definition retargets earlier literal `[text]`.
+ *    Every reference-style candidate before the boundary must resolve
+ *    against a SETTLED definition (one followed by a confirmed blank line).
+ *    Labels are matched with micromark's own `normalizeIdentifier`
+ *    (Unicode case folding — `toLowerCase` is the unsafe direction).
+ *    Definitions must START a block (or chain a valid definition line) —
+ *    a def-shaped paragraph continuation line is literal text.
+ * 6. **Raw-remnant seam** — an html FLOW run can swallow non-tag lines
+ *    (e.g. a `$$` math fence glued under `</details>`); once tag balance
+ *    returns to zero, that remnant becomes FLOATING text that parse5/
+ *    rehype-raw attaches at the root, and its hast shape (position vs
+ *    seam-owned position-less, trailing-newline ownership) depends on
+ *    whether a sibling node FOLLOWS it. A tail block that flips between
+ *    def (no hast output) and paragraph therefore reshapes the frozen
+ *    region retroactively (2026-07-31 direction-battery counterexample,
+ *    reproduced on v1.8.0). The candidate adjacent to such a run is
+ *    rejected until a later confirmed content line pins the seam from the
+ *    frozen side; dropping candidates only over-blocks (safe direction).
+ * 7. **Phase poison** (`phasePoisonedAt`) — points where this line-level
+ *    model may have DIVERGED from micromark and provably cannot resync:
+ *    a fence/math open suppressed by `htmlFlowSinceBlank` (only certainly
+ *    swallowed at top level — in a container it really opens and the
+ *    open/close phase inverts permanently), and a paragraph-inline `<!--`
+ *    that fails to close by end of line (literal text to micromark, but
+ *    the comment scan would skip real markup as comment interior). Every
+ *    candidate past the first such point is rejected, sticky; candidates
+ *    at or before it stay valid — the ambiguous region then re-parses
+ *    inside the tail (pure over-block).
+ *
+ * ## Incremental scanning (checkpoint resume)
+ *
+ * The hot path calls this once per streamed frame. Appends leave every
+ * previously-CONFIRMED line byte-identical, so the scan checkpoints its
+ * entire per-line state after the last confirmed line (one whose
+ * terminating `\n` exists) and, given `resume`, re-lexes only from there.
+ * The trailing PARTIAL line is never baked into the checkpoint: it cannot
+ * emit candidates (unconfirmed lines are never blank), its tag/ref effects
+ * cannot affect candidates that all precede it, and the next frame re-lexes
+ * it from scratch. Resume MUTATES the checkpoint monotonically and is
+ * idempotent for identical input — but a checkpoint belongs to exactly one
+ * advancing state lineage (advanceIncrementalParse's), never share it.
+ *
+ * Continuation hazards (blocker 3) are a forward-rolling verdict updated at
+ * each decisive block start — equivalent to the previous per-candidate
+ * upward walk ("nearest decisive block start above") at O(1) per candidate.
+ * Reference taint (blocker 5) maintains defs and an unresolved-ref list
+ * incrementally; settling is monotone, so resolved entries only ever leave.
+ *
+ * ## Inline code-span masking
+ *
+ * `` `<div>` ``, `` `[x]` `` and `` `[^n]` `` in prose are code, not
+ * markup. Before HTML/ref/footnote extraction each line is masked using
+ * micromark's own pairing rule (equal-length backtick runs, leftmost
+ * first) — but ONLY when the pairing is provably intra-line: if any run on
+ * a line is left unpaired, or an earlier line of the same paragraph left
+ * one unpaired, masking is disabled for the rest of the paragraph. A
+ * cross-line span can therefore never cause an unmask mismatch: every
+ * masked span is one micromark would pair identically. Skipped masking
+ * only over-blocks (safe direction).
+ *
+ * A line only counts as blank once its terminating newline exists: the
+ * trailing partial line is UNCONFIRMED (the next chunk may append content
+ * to it) and treating it as blank breaks boundary monotonicity.
+ *
+ * Footnote refs/defs participate in blockers 3 and 5 like their link
+ * counterparts (separate label namespace); the engine splices across them
+ * via injection replay (v2).
+ */
+interface FreezeBoundaryOptions {
+    /** Whether remark-definition-list is in the active plugin chain (the
+     *  `enginePlugins` selection includes `definitionList`). Enables blockers 3b/4. */
+    defListEnabled: boolean;
+    /**
+     * Whether `$$` flow math is in the grammar (remark-math). Default `true`
+     * (the engine's own profile). The def-label scanner runs a PINNED
+     * remark-parse+gfm subset where `$$` is ordinary paragraph text — under
+     * that grammar the math branch is a MASKING hole: `inMath` returns early
+     * without comment/fence scanning, so `$$\n<!--\n$$` reads as a closed
+     * math block here while the subset grammar sees an OPEN type-2 HTML
+     * comment running to `-->`/EOF (a candidate after it would let a
+     * standalone tail parse invent ghost defs). With `false`, `$$` lines take
+     * the ordinary text path and comments/fences inside are scanned.
+     */
+    mathFlow?: boolean;
+    /**
+     * Whether blocker 5 (reference taint) applies. Default `true`: the
+     * engine must reject candidates past an unresolved `[label]` because a
+     * later definition retargets the reference's PARSE. The def-label
+     * scanner only extracts definition IDENTITIES — a pure block-level fact
+     * unaffected by how inline references resolve — and under taint a
+     * streaming citation footer (defs with no settling blank line yet)
+     * collapses the boundary to the body's first reference, zeroing the
+     * caching this profile exists for. `false` skips ref tracking entirely.
+     */
+    referenceTaint?: boolean;
+}
+interface FreezeScanResult {
+    /** Largest freeze-safe boundary, or 0 when nothing can be frozen. */
+    boundary: number;
+    /** Opaque resume state — pass back on the next APPEND-ONLY call to skip
+     *  re-lexing the confirmed prefix. Single-consumer; see module docs. */
+    checkpoint: FreezeScanCheckpoint;
+}
+interface Candidate {
+    /** Freeze boundary: start of the line after this blank line. */
+    offset: number;
+    /** Consecutive confirmed blank lines (outside fences/math) ending here. */
+    blankRun: number;
+    /** No unbalanced HTML container / comment / raw block before this point. */
+    htmlBalanced: boolean;
+    /** Rolling continuation-hazard verdict at emission (blocker 3). */
+    hazard: boolean;
+    /** Blocker-6: the run ending at this blank left balanced FLOATING raw
+     *  remnant whose hast seam is tail-dependent; reject this candidate. */
+    seamRisk: boolean;
+    /** Blocker-4 settle verdict, decided by the NEXT confirmed line (`null`
+     *  while that line hasn't confirmed — only the newest candidate can be
+     *  pending). Storing the verdict instead of the line lets the checkpoint
+     *  drop its lines array, which retained a full copy of the document
+     *  (round-2 review: ~2-3× doc size per mounted instance). */
+    defListSettled: boolean | null;
+}
+interface UnresolvedRef {
+    offset: number;
+    label: string;
+    footnote: boolean;
+}
+/** Mutable resume state. All fields describe the scan strictly BEFORE the
+ *  first unconfirmed character (`confirmedOffset`). */
+interface FreezeScanCheckpoint {
+    defListEnabled: boolean;
+    /** Grammar-profile switches baked at creation — a checkpoint is only
+     *  resumable under the exact profile that built it. */
+    mathFlow: boolean;
+    referenceTaint: boolean;
+    /** Start offset of the first line NOT yet baked into this checkpoint. */
+    confirmedOffset: number;
+    candidates: Candidate[];
+    defs: Map<string, number>;
+    footnoteDefs: Map<string, number>;
+    unresolvedRefs: UnresolvedRef[];
+    tagBalance: Map<string, number>;
+    openTotal: number;
+    commentOpen: boolean;
+    piOpen: boolean;
+    declOpen: boolean;
+    cdataOpen: boolean;
+    inFence: boolean;
+    fenceChar: string;
+    fenceLen: number;
+    inMath: boolean;
+    /** Opening dollar-run length while inMath — the close run must match it. */
+    mathFenceLen: number;
+    blankRun: number;
+    lastBlankStart: number;
+    /** Rolling blocker-3 verdict ("nearest decisive block start so far"). */
+    hazardVerdict: boolean;
+    /** Previous confirmed line was blank (block-start detection). */
+    prevLineBlank: boolean;
+    /** Previous confirmed line was a plain text line (def-chain detection). */
+    prevLineWasText: boolean;
+    /** Previous confirmed line registered a VALID definition (def chains). */
+    prevLineWasValidDef: boolean;
+    /** An earlier line of the current paragraph left an unpaired backtick
+     *  run — masking is disabled until the paragraph ends (safety gate). */
+    paragraphHasUnpairedRun: boolean;
+    /** Blocker-6 pending flag: a confirmed html-flow line left balanced
+     *  floating raw remnant, and no later content line has pinned the seam
+     *  yet. Persists across blank lines (every candidate emitted while set
+     *  has the remnant as its last frozen child); cleared by the next
+     *  non-blank line that starts OUTSIDE an html-flow run. */
+    htmlSeamPending: boolean;
+    /** A line since the last blank started with `<` at block indent — an html
+     *  FLOW block is (approximately) running, and it only ends at a blank
+     *  line. micromark does no inline parsing there: backtick runs are
+     *  literal text, so code-span masking would hide REAL tags from the
+     *  balance scan (under-block — fuzz counterexample: `</details>` followed
+     *  by an unblanked `` `<div>` `` line). While set, masking is skipped —
+     *  which can only over-block (safe direction). */
+    htmlFlowSinceBlank: boolean;
+    /** Offset of the first fence/math OPEN suppressed by `htmlFlowSinceBlank`
+     *  (Infinity = none). Whether the run really swallowed that line depends
+     *  on container context the line scan cannot see (`<embed` inside a list
+     *  item is a lazy paragraph line, and the glued `$$` a REAL math open —
+     *  seed-20260757 under-block: the tracker's fence phase INVERTS from that
+     *  line on, every later close reads as an open, and the corruption never
+     *  resyncs). Candidates past this offset are rejected outright — sticky,
+     *  pure over-block; candidates before it are untouched (the ambiguous
+     *  region then re-parses inside the tail). The rolling hazard poison for
+     *  ambiguous tag names stays, but it decays at the next decisive block
+     *  start — this field is the phase-corruption backstop that does not. */
+    phasePoisonedAt: number;
+}
+declare function computeFreezeBoundary(text: string, options: FreezeBoundaryOptions, resume?: FreezeScanCheckpoint | null): FreezeScanResult;
+
+/**
+ * Pure splice helpers for incremental (prefix-freeze) parsing: cut the
+ * frozen prefix out of the previous frame's trees, re-base a tail-only
+ * parse into document coordinates, and join the two into fresh roots.
+ *
+ * Invariant these helpers exist to uphold (enforced by the
+ * splice-equivalence arbiter test, NOT asserted at runtime): the spliced
+ * `{mdast, hast}` is deep-equal — positions included — to a full pipeline
+ * run over the whole content. Defined on UNRENDERED trees; after a render,
+ * `renderHastSubtree` mutates hast in place (convergent `data.originalUrls`
+ * stash, raw→text rewrite — see Markdown.tsx), so no in-component
+ * deep-equal check is possible or attempted.
+ *
+ * Prefix link/image definitions are PREPENDED to the tail source (not
+ * appended: a streaming tail routinely ends inside an unclosed fence or
+ * `$$` block that would swallow appended lines, and appended defs would
+ * invert CommonMark first-def-wins against a same-label tail def).
+ * Definitions emit zero hast (mdast-util-to-hast has no `definition`
+ * handler), so their only trace is `definition` mdast nodes inside the
+ * injected region, which are dropped before the join. Definition text is
+ * sliced verbatim from the previous content via node positions — exact
+ * source roundtrip preserves escapes and multi-line titles.
+ *
+ * Sanitize-STRIPPED prefix nodes (HTML comments, `<?…?>` bogus comments,
+ * `<script>`) are modeled explicitly: their wrap separators survive as
+ * orphans, and `alignPrefixCut` re-derives the mdast↔hast pairing from
+ * separator-run lengths (B0-probe-verified: one orphan '\n' per stripped
+ * child's gap slot; separators MERGED into raw trailing literals count via
+ * their trailing newlines — `literalCredit`). Layouts outside the model
+ * return null → full-parse fallback for the frame.
+ */
+
+/** Prefix footnote/definition events in DOCUMENT ORDER. Order is the whole
+ *  point: mdast-util-to-hast's footnoteOrder/footnoteCounts are built from
+ *  encounter order, and the replay must reproduce it exactly. */
+type InjectionEvent = 
+/** Link/image definition — parse-time resolution only, zero hast. */
+{
+    kind: 'def';
+    source: string;
+}
+/** Footnote definition — sliced from the PHYSICAL LINE START (column
+ *  invariance for the footer position rebase). */
+ | {
+    kind: 'footnoteDef';
+    source: string;
+    origStart: number;
+    origLine: number;
+}
+/** Consecutive footnote references, verbatim source tokens. Seeds
+ *  footnoteOrder (first-encounter) and footnoteCounts (backref -N ids). */
+ | {
+    kind: 'refs';
+    tokens: string[];
+};
+interface PrefixInjectionPlan {
+    events: InjectionEvent[];
+    /** True when an event exists that CANNOT be injected reliably — the caller
+     *  must fall back to a full parse for this frame (safe, one-frame cost). */
+    uninjectable: boolean;
+    /** False when the plan must NOT be cached for resume: a position-less
+     *  top-level child cannot be partitioned by the resume offset, so a
+     *  resumed walk would re-visit it and duplicate its events (round-2
+     *  review). Fresh walks stay correct — they just can't be incremental. */
+    cacheable?: boolean;
+}
+/** A plan cached in engine state: valid for any LATER boundary of the same
+ *  append lineage, because events derive from (content, positions) alone
+ *  and the boundary is monotone under appends — new frames only APPEND
+ *  events for children in [cached.boundary, newBoundary). */
+interface CachedInjectionPlan extends PrefixInjectionPlan {
+    boundary: number;
+}
+
+/**
+ * React-free state machine for incremental (prefix-freeze) parsing.
+ *
+ * Given the previous frame's state and the current content, either splice
+ * a frozen prefix with a tail-only parse or run the full pipeline. Every
+ * gate failure degrades to the full path — the caller cannot observe a
+ * difference except through `usedIncremental` and the dev-only stage
+ * timings. The splice output is deep-equal to a full parse (the
+ * splice-equivalence arbiter test enforces this; see spliceParse.ts).
+ *
+ * Gate order (first failure wins):
+ *  - G0 depsKey identity — the parse inputs beyond `content` (plugin
+ *    arrays, remark-rehype options, handlers, documentId, …) must be
+ *    identical to the previous frame's. This intentionally covers MORE
+ *    than the component's G3 12-dep flush (e.g. `preserveOrphanReferences`
+ *    flips reach the handlers without touching any G3 field).
+ *  - G1 append — `content.startsWith(prev.content)`; equal content returns
+ *    the previous trees unchanged. Non-append rewrites (including Stage-A
+ *    preprocessor rewrites near the stream end) land here.
+ *  - G3 boundary — `b = min(computeFreezeBoundary(content), prev.stableBoundary)`
+ *    must be > 0. The `min` with the PREVIOUS frame's boundary is
+ *    load-bearing, not defensive: the freshly computed boundary proves
+ *    stability of the CURRENT parse's prefix, but the splice reuses the
+ *    PREVIOUS parse's nodes — e.g. a shortcut ref rendered literal last
+ *    frame must not be frozen the moment its definition arrives and the
+ *    fresh boundary jumps past it. `prev.stableBoundary` is exactly the
+ *    "stable under all future appends" property for prev's nodes.
+ *  - G4 straddle (defensive) — no prev top-level mdast child may cross the
+ *    boundary; the detector's blockers should already prevent this.
+ *
+ * (v1's G2 footnote bypass is GONE. Footnotes splice via INJECTION REPLAY:
+ * the prefix's footnote event sequence — defs and refs ×count, in document
+ * order, collected from prev.mdast — is prepended to the tail source, so
+ * the tail run's mdast-util-to-hast state (footnoteOrder / footnoteCounts /
+ * footnoteById) is seeded exactly and its footer regenerates the WHOLE
+ * document's section; the injected nodes are stripped from both trees and
+ * the footer's positions are rewritten by the dual rule in spliceParse.
+ * Prefix inline hast is naturally stable — numbering is first-reference
+ * order, which appends cannot change for the prefix. The detector's
+ * reference taint (footnote namespace) keeps unresolved `[^x]` out of the
+ * frozen prefix, C0-probe + arbiter verified.)
+ *
+ * `nextState.stableBoundary` is written on BOTH paths from the same single
+ * boundary computation.
+ */
+
+interface IncrementalParseState {
+    /** The CHUNK's own text — excludes the phantom suffix. */
+    content: string;
+    /** The phantom suffix this state's trees were parsed with ('' standalone). */
+    phantomSuffix: string;
+    /** Post-transform trees (transformStage mutates mdast in place; these are
+     *  the settled shapes) — of `content + phantomSuffix`. */
+    mdast: Root;
+    hast: Root$1;
+    /** Scan boundary at the frame that produced these trees. */
+    stableBoundary: number;
+    /** Detector resume state: append frames re-lex only past the confirmed
+     *  prefix instead of the whole document (E2). Single-consumer mutable —
+     *  owned by this state lineage. */
+    scanCheckpoint: FreezeScanCheckpoint | null;
+    /** Injection-plan resume state: events derive from (content, positions)
+     *  alone, so within an append lineage only children past the cached
+     *  boundary need visiting (final-review R3 — without this the plan walk
+     *  re-visits the entire frozen prefix every splice frame). Null until the
+     *  first splice frame; carried verbatim across full-path append frames. */
+    injectionPlan: CachedInjectionPlan | null;
+    /** Identity tuple of every parse input beyond `content` (G0). */
+    depsKey: readonly unknown[];
+}
+type IncrementalStage = 'scan' | 'parse' | 'transform';
+interface AdvanceOptions {
+    remarkPlugins: PipelineOptions['remarkPlugins'];
+    rehypePlugins: PipelineOptions['rehypePlugins'];
+    /** The FULLY-MERGED remark-rehype options (handlers, clobberPrefix, …) —
+     *  exactly what the full path would pass to parseStage. */
+    remarkRehypeOptions: PipelineOptions['remarkRehypeOptions'];
+    depsKey: readonly unknown[];
+    /** Whether remark-definition-list is active (`enginePlugins` includes `definitionList`). */
+    defListEnabled: boolean;
+    /** Cross-chunk phantom-definition suffix (coordinated mode) — appended to
+     *  the parse input but NEVER frozen: the append gate, boundary scan, and
+     *  prefix cut all see `content` alone, and the suffix re-parses with the
+     *  tail every frame. It may shrink/grow/reorder between frames (registry
+     *  label churn) without invalidating the frozen prefix — the reference
+     *  taint keeps every phantom-resolved ref in the tail (a phantom's def is
+     *  never IN `content`, so such refs never settle). '' when standalone. */
+    phantomSuffix?: string;
+    /** Optional stage-timing wrapper (the component passes measureStage). */
+    measure?: <T>(stage: IncrementalStage, fn: () => T) => T;
+}
+interface AdvanceResult {
+    mdast: Root;
+    hast: Root$1;
+    usedIncremental: boolean;
+    /** The boundary the splice used (0 on the full path). */
+    boundary: number;
+    nextState: IncrementalParseState;
+}
+declare function advanceIncrementalParse(prev: IncrementalParseState | null, content: string, options: AdvanceOptions): AdvanceResult;
+
+/**
+ * Source-offset attribution for top-level hast children.
+ *
+ * hast positions alone cannot delimit a frozen prefix: rehype-katex
+ * replaces a math block with a position-less span (and other plugins can
+ * do the same), and mdast-util-to-hast's root `wrap()` interleaves
+ * position-less `'\n'` text separators. Each top-level hast child is
+ * therefore attributed a source offset:
+ *
+ * - its own `position.start.offset` when present;
+ * - otherwise the start of the first top-level MDAST child at or after the
+ *   running cursor (top-level mdast children always carry positions — this
+ *   mirrors blockMemo's source-offset lookup);
+ * - the synthetic footnote section is attributed `Infinity` — it is never
+ *   freeze-eligible (production handles it via `FootnoteSectionEntry` /
+ *   `aggregateFootnotesIfLast`, not positional identity).
+ *
+ * The returned array is non-decreasing except for `Infinity` entries, so
+ * "children attributed before offset b" is always a prefix of the child
+ * list.
+ *
+ * Extracted from the prefixFreeze experiment's falsification harness
+ * (which now imports this module) — the production splice and the
+ * experiment must cut prefixes identically or the experiment stops being
+ * evidence.
+ */
+
+declare function attributeHastChildren(mdast: Root, hast: Root$1, stopAt?: number): number[];
+
+/**
+ * TEST/STORY helper (not exported from the package barrel): prefix
+ * snapshots sliced at CODE-POINT granularity, so a frame boundary never
+ * splits a surrogate pair. Every streaming verifier in the repo — the
+ * splice-equivalence arbiter, the prefixFreeze experiment harness, and the
+ * Storybook smoke/playground streams — derives its frame sequence from
+ * this one implementation; a change here (e.g. moving to grapheme
+ * clusters) changes them all together instead of leaving four copies to
+ * drift (review finding R4).
+ */
+declare function codePointSnapshots(payload: string, chunkSize: number): string[];
+
+interface DefLabels {
+    footnoteLabels: Set<string>;
+    linkLabels: Set<string>;
+}
+declare function collectDefLabels(source: string): DefLabels;
+/** Index just past the LAST blank line of `source`, or 0 if none.
+ *  Plain non-overlapping scan: for runs of blanks ("\n\n\n") this can land
+ *  a newline or two early, but the slack is whitespace-only and whitespace
+ *  can never satisfy DEF_LINE_START_RE, so the decision is identical.
+ *  @internal exported for tests only — the fast path is otherwise
+ *  indistinguishable from a full parse whose sets came out equal. */
+declare function lastRegionStart(source: string): number;
+/** A line that can START a definition, matched by the FULL def signature:
+ *  container prefixes (blockquote `>`, list bullets, ordered-list digits),
+ *  then `[label]` with the closing bracket IMMEDIATELY followed by `:` —
+ *  remark accepts a definition only with that adjacency (grammar-verified:
+ *  `[x]\n: url` and `[x] : url` are paragraphs, and `[a][b]: url` is a
+ *  reference because the label's first unescaped `]` isn't followed by
+ *  `:`). The label alternation admits escape pairs (`\]` stays inside the
+ *  label) and spans newlines (labels may soft-wrap; they cannot cross the
+ *  blank line that bounds the region). Both alternatives are disjoint, so
+ *  the scan is linear — no backtracking blowup on bracket-dense regions.
+ *
+ *  Requiring the signature (not just a line-start `[`) is what keeps the
+ *  streaming-heavy shapes — bulleted link lists `- [t](u)`, task boxes
+ *  `- [x]`, reference lists `- [a][b]` — on the fast path; a bracket-only
+ *  probe made every append inside a blank-line-free link list pay a full
+ *  reparse (the measured Documents+smooth cliff). An INCOMPLETE def line
+ *  (`[x` with `]:` still in flight) correctly stays on the fast path too:
+ *  the parser sees no definition in it either, and the region re-check on
+ *  the completing append flips to the full parse exactly when the answer
+ *  can change. The `m` flag also matches at index 0, which is a true line
+ *  start (the region begins just past a blank line or at the document
+ *  start). Residual over-matching (e.g. `[x]:` inside an open code fence)
+ *  is safe: it costs a redundant full parse, never a wrong result.
+ *  @internal exported for tests only. */
+declare const DEF_LINE_START_RE: RegExp;
+interface DefLabelScanner {
+    /** Equivalent to `collectDefLabels(source)` at every call, but cheap for
+     *  the streaming common case. Returns a REFERENCE-STABLE result while the
+     *  label set is unchanged. */
+    scan(source: string): DefLabels;
+}
+/**
+ * Append-aware wrapper around {@link collectDefLabels} for the streaming
+ * hot path: PASS 0 re-runs on every token, but its result — the def label
+ * set — almost never changes while prose streams in.
+ *
+ * Fast path: when the new source merely APPENDS to the previous one, the
+ * label set can only differ if the affected region contains a line-start
+ * `[label]:` def signature (see DEF_LINE_START_RE — mid-line brackets,
+ * bulleted links, task boxes and reference lists all lack the adjacent
+ * `]:` and stay on the fast path). That region is the previous source's
+ * text SINCE ITS LAST BLANK LINE plus the appended text — not just the
+ * appended text, because CommonMark definitions span lines (`[x]:` with
+ * the destination on the next line) and a trailing append can re-type an
+ * entire paragraph (setext `===`). No construct that produces or destroys
+ * a definition crosses a blank line (labels, destinations and titles all
+ * forbid them), so text before that boundary is settled. When the region
+ * has no def-capable line, the previous result is returned AS-IS;
+ * otherwise (and for any non-append change) a full re-parse runs, and the
+ * previous result object is kept whenever the recomputed sets are equal.
+ *
+ * Misjudging conservatively (an unnecessary `[` hit — e.g. inside an open
+ * code fence) only costs a redundant full parse, never a wrong result.
+ *
+ * The reference stability doubles as churn control: consumers that list
+ * the result in effect deps (chunk re-registration) stop firing per token.
+ *
+ * @param parse Full-parse fallback — injectable so tests can COUNT parses
+ *   and assert the fast path actually fires (from the outside, a skipped
+ *   parse is indistinguishable from a parse whose sets came out equal).
+ *   Production callers never pass it.
+ */
+declare function createDefLabelScanner(parse?: (source: string) => DefLabels): DefLabelScanner;
+
+/**
+ * Extract the SOURCE identifier from a footnote `<li>` id, covering both id
+ * shapes in the codebase — standalone (mdast-util-to-hast `fn-` +
+ * `normalizeUri`, then the sanitize clobber + rehypeRebaseHashLinks linkage)
+ * and aggregate (`${clobberPrefix}fn-${sourceIdentifier}`, raw). Exported as
+ * the single source of truth for li-id parsing: the streaming cursor's
+ * anchor targeting (`detectAnchor`) reuses it so a clobber-linkage change
+ * can never drift the two consumers apart.
+ */
+declare function sourceIdFromFootnoteLiId(idProp: string, clobberPrefix?: string): string | null;
+declare function extractDefBodiesFromHast(hast: Root$1, clobberPrefix?: string): Map<string, ElementContent[]>;
+
+type Contribution = {
+    kind: 'ref';
+    refKind: 'footnote' | 'link' | 'image';
+    label: string;
+    referenceType?: 'full' | 'collapsed' | 'shortcut';
+} | {
+    kind: 'fnDef';
+    label: string;
+    sourceIdentifier: string;
+    content: string;
+} | {
+    kind: 'linkDef';
+    label: string;
+    url: string;
+    title?: string;
+};
+interface ExtractContributionsOptions {
+    /** Already-normalized labels that were phantom-injected at PASS 0.5.
+     *  Defs matching these are skipped to avoid leaking sentinel rows into
+     *  registry.chunkData. */
+    phantomFootnoteLabels?: Set<string>;
+    /**
+     * Caller's resolved URL transform (typically `props.urlTransform ??
+     * defaultUrlTransform`). Applied to every emitted `linkDef.url` so the
+     * registry stores already-sanitized URLs.
+     *
+     * Cross-chunk link/image references render through the registry rather
+     * than the in-tree hast (which is where react-markdown's transform pass
+     * normally enforces `urlTransform`). Without this, a chunk defining
+     * `[evil]: javascript:alert(1)` could XSS a sibling chunk that uses
+     * `[click][evil]` — the standalone path strips the protocol; the cross-
+     * chunk path would have rendered `<a href="javascript:…">`. Sanitizing at
+     * contribute time also benefits any future consumer that reads
+     * `Registry.resolveLinkDef` directly.
+     *
+     * Invocation contract mirrors react-markdown's hast-pass call site
+     * (`buildTransform` in `./markdown/transform.ts`): a synthetic
+     * `<a href={url}>` element stands in for the node argument since
+     * mdast `definition` nodes have no hast counterpart. The key is `'href'`
+     * — link defs are far more common than image defs, and protocol-allowlist
+     * transforms (including `defaultUrlTransform`) are key-agnostic anyway.
+     * A `null` return collapses to the empty string, matching how
+     * `transform.ts` would render a blocked attribute.
+     *
+     * Omitting this option preserves v1 behavior (URLs stored raw). Library
+     * callers should always supply it; the option stays optional so unit-test
+     * fixtures that don't care about URL safety can construct minimal calls.
+     */
+    urlTransform?: UrlTransform;
+}
+declare function extractContributions(mdast: Root, options?: ExtractContributionsOptions): Generator<Contribution>;
+
+/**
+ * Cross-chunk shared state. Holds per-chunk contributions (refs, defs,
+ * linkDefs) keyed by Symbol identity allocated via useId reactId, with
+ * refcount + microtask-deferred reclamation for React Strict Mode safety.
+ *
+ * @module components/documentRegistry
+ */
+
+interface FootnoteDef {
+    /** Already-normalized identifier (uppercase). Used as dictionary key for
+     *  case-insensitive cross-chunk lookups. */
+    identifier: string;
+    /** mdast's case-folded identifier — the exact string mdast-util-to-hast
+     *  emits in `<li id="${clobberPrefix}fn-${sourceIdentifier}">` and that
+     *  `FootnoteSupNumber` mirrors in its anchor href. Needed so the aggregate
+     *  footer's `<li id>` and backref href match the inline `<sup>`'s href
+     *  exactly (otherwise hash navigation breaks). Optional so unit-test
+     *  fixtures don't need to fabricate it; production data always supplies it. */
+    sourceIdentifier?: string;
+    /** Content extracted from the source markdown footnote definition. */
+    contentSource: string;
+    /** Per-def hast body (the def's mdast children after mdast-util-to-hast
+     *  conversion). Drives AggregateFootnotesIfLast to render the consolidated
+     *  footer at the end of each document's last chunk. Optional so unit-test
+     *  fixtures can build minimal FootnoteDef objects without producing hast. */
+    bodyHast?: ElementContent[];
+}
+interface LinkDef {
+    /** Already-normalized identifier (uppercase). */
+    identifier: string;
+    url: string;
+    title?: string;
+}
+type RefKind = 'footnote' | 'link' | 'image';
+interface RefRecord {
+    /** Already-normalized identifier (uppercase). */
+    label: string;
+    /** Which markdown reference space this entry belongs to. Footnote refs,
+     *  link refs, and image refs occupy disjoint namespaces in GFM, so they
+     *  must be filtered separately when computing footnote numbers / refcounts. */
+    kind: RefKind;
+    referenceType?: 'full' | 'collapsed' | 'shortcut';
+}
+interface ChunkData {
+    refs: RefRecord[];
+    defs: Map<string, FootnoteDef>;
+    linkDefs: Map<string, LinkDef>;
+    ownFootnoteLabels: Set<string>;
+    ownLinkLabels: Set<string>;
+}
+/**
+ * Public, read-only view of the cross-chunk registry. This is the type
+ * surfaced by `useDocumentRegistry` and re-exported from the package
+ * barrel. Consumers can:
+ *
+ *   - read the registry's current state (`chunkOrder`, `chunkData`,
+ *     `labelSet`, `version`)
+ *   - observe changes (`subscribe`)
+ *   - run selectors (`globalNumber`, `resolveLinkDef`, …)
+ *
+ * Mutators — `registerChunk`, `allocateSymbol`, `releaseSymbol`,
+ * `contributeLabels`, `contributeChunkData` — are intentionally off this
+ * interface. Driving the registry directly is reserved for internal
+ * coordinators (the package's own `MarkdownContent` renderer) and tests,
+ * which import the wider `RegistryInternal` type from this module.
+ * `RegistryInternal` is exported here but NOT re-exported from the package
+ * barrel — keeping mutators off the public surface prevents a misbehaving
+ * consumer-component from corrupting refcounts, skipping version bumps, or
+ * otherwise breaking the invariants the renderer relies on.
+ */
+interface Registry {
+    /** Chunk mount-order Symbol list. **Read-only.** Direct mutation
+     *  (`.push`, `.splice`, index assignment) corrupts footnote numbering,
+     *  "last chunk" detection, and eviction. */
+    readonly chunkOrder: readonly symbol[];
+    /** Chunk Symbol → contribution payload. **Read-only.** Direct `.set` /
+     *  `.delete` bypasses version bumps and subscriber wake-ups. */
+    readonly chunkData: ReadonlyMap<symbol, ChunkData>;
+    /** Union of own-def labels across all chunks. PASS 0.5 phantom-injection
+     *  driver. **Read-only.** The registry derives this from per-chunk
+     *  contributions; direct mutation breaks the derivation. */
+    readonly labelSet: {
+        readonly footnoteLabels: ReadonlySet<string>;
+        readonly linkLabels: ReadonlySet<string>;
+    };
+    /** Monotonic version counter bumped by every mutation. **Read-only** —
+     *  consumers should observe via `subscribe`, not by writing. */
+    readonly version: number;
+    subscribe(cb: () => void): () => void;
+    canonicalFootnoteFor(label: string): symbol | null;
+    canonicalLinkFor(label: string): symbol | null;
+    globalNumber(label: string): number | null;
+    /**
+     * Resolve a cross-chunk link definition by label. The returned `url` is the
+     * value the contributing chunk's `urlTransform` produced — cross-chunk
+     * link/image references run a second, per-attribute sanitization pass
+     * (`urlTransform` + `sanitizeSchema.protocols`) at render time, so the
+     * placeholder components themselves never trust this value blindly.
+     *
+     * Consumers reading `def.url` directly (custom backlink panels, analytics,
+     * dev tooling) receive a defense-in-depth-filtered string but should still
+     * pipe it through their own `urlTransform` if they intend to render it as
+     * an `href`/`src` — the contribute-time pass uses the `'href'` key and a
+     * synthetic `<a>` node, so a key-aware policy may treat the value
+     * differently when used as an `<img src>`.
+     */
+    resolveLinkDef(label: string): LinkDef | null;
+    getRefsForLabel(label: string): number;
+    /** Map a chunk-local footnote-ref occurrence index (1-based, as emitted by
+     *  `customMdastHandlers`) to the corresponding document-wide occurrence
+     *  index across all chunks. Used by `FootnoteSupNumber` to build a unique
+     *  `id="fnref-X-N"` for each ref instance and by `AggregateFootnotesIfLast`
+     *  to enumerate per-occurrence backrefs. Returns `null` if the ref isn't
+     *  registered yet (registry mid-flight). */
+    globalOccurrenceForRef(chunkSym: symbol, label: string, localOccurrence: number): number | null;
+}
+/**
+ * Internal registry surface — extends {@link Registry} with the mutator
+ * methods and implementation-private fields (reactId-keyed refcount table,
+ * subscriber set, microtask-coalesce flag, `_notify` itself).
+ *
+ * Exported from this module so internal coordinators (`MarkdownContent`)
+ * and tests can hold a strongly-typed reference, but **not** re-exported
+ * from the package barrel — a consumer flipping `_notifyScheduled = true`
+ * or pushing into `chunkOrder` directly would silently break the
+ * coalesce / numbering invariants. The runtime value returned by
+ * {@link createRegistry} always satisfies this wider shape; public consumers
+ * just see the narrowed {@link Registry} view.
+ */
+interface RegistryInternal extends Registry {
+    /** Allocate (or reuse, for Strict Mode remount) the chunk Symbol for
+     *  `reactId` AND publish this chunk's own def labels (footnotes + links)
+     *  in one call. Canonical pair API used by `MarkdownContent`'s allocate
+     *  effect — combining the two reduces the pair to a single registry
+     *  version step, which downstream consumers see as one wake-up rather
+     *  than two (the second was already coalesced by microtask, but this
+     *  keeps the version monotonic-by-1-per-mount which makes debugging
+     *  easier). The granular `allocateSymbol` / `contributeLabels` methods
+     *  remain available for tests that need to exercise each step. */
+    registerChunk(reactId: string, footnotes: Set<string>, links: Set<string>): symbol;
+    allocateSymbol(reactId: string): symbol;
+    releaseSymbol(reactId: string): void;
+    contributeLabels(symbol: symbol, footnotes: Set<string>, links: Set<string>): void;
+    contributeChunkData(symbol: symbol, data: ChunkData): void;
+    _reactIdMap: Map<string, {
+        symbol: symbol;
+        refcount: number;
+    }>;
+    _subscribers: Set<() => void>;
+    _notifyScheduled: boolean;
+    _notify(): void;
+}
+/**
+ * Construct a new Registry. `onEmpty`, if supplied, is invoked once each
+ * time the registry transitions to "no chunks alive" — i.e. the last
+ * tracked chunk's deferred `releaseSymbol` cleanup just removed its
+ * entry, leaving `chunkOrder` and `chunkData` both empty. The container
+ * uses this to evict the registry from its `documentId → Registry` map
+ * so long-lived SPAs that cycle through many `documentId` values don't
+ * accumulate empty shells.
+ *
+ * `onEmpty` fires synchronously from inside the releaseSymbol microtask,
+ * so the registry's state is guaranteed quiescent during the callback —
+ * no other code can interleave between the empty-state check and the
+ * caller's eviction logic.
+ */
+declare function createRegistry(onEmpty?: () => void): RegistryInternal;
+
+/**
+ * Builds a `rehype-sanitize` schema by handing the caller a deep clone of
+ * the library's internal default schema to mutate or replace.
+ *
+ * The mutate-and-return pattern matches the ergonomics of Next.js's
+ * `webpack(config)` and Express middleware: a callback receives a draft,
+ * either modifies it in place (returning nothing) or returns a fresh object
+ * to replace it. The library guarantees the draft is a deep clone, so direct
+ * mutation never leaks into the singleton — and the singleton itself is not
+ * exported, so consumers cannot accidentally hand-roll a schema that drops
+ * the library's cross-chunk tag allowlist or KaTeX className additions.
+ *
+ * @module components/extendSanitizeSchema
+ */
+
+/**
+ * The full `rehype-sanitize` schema type. Re-exported as the canonical
+ * library-internal alias so other modules don't each redeclare
+ * `typeof defaultSchema`.
+ *
+ * The shape is owned by `rehype-sanitize`; consumers should treat it as
+ * tracking that upstream type — it may evolve across rehype-sanitize major
+ * versions.
+ */
+type SanitizeSchema = typeof defaultSchema;
+/**
+ * Build a sanitize schema by mutating (or replacing) a deep clone of the
+ * library default.
+ *
+ * Designed to be called ONCE at module scope so the returned object has a
+ * stable identity across renders — passing it directly into
+ * `<AIMarkdown sanitizeSchema={…}>` keeps the block-memo cache warm.
+ *
+ * @example Append a custom URL protocol via mutation:
+ * ```ts
+ * const SCHEMA = extendSanitizeSchema((s) => {
+ *   s.protocols!.href!.push('myapp');
+ *   s.protocols!.src!.push('myapp');
+ * });
+ *
+ * function App() {
+ *   return <AIMarkdown content={…} sanitizeSchema={SCHEMA} />;
+ * }
+ * ```
+ *
+ * @example Return-style replacement for wider edits:
+ * ```ts
+ * const SCHEMA = extendSanitizeSchema((s) => ({
+ *   ...s,
+ *   tagNames: [...(s.tagNames ?? []), 'my-widget'],
+ * }));
+ * ```
+ *
+ * @example Inspect the library default (e.g. to learn what's already allowed):
+ * ```ts
+ * // The draft handed to the modifier IS the library default, deep-cloned.
+ * // Logging it once at module load surfaces every default field — protocols,
+ * // attributes, tagNames, etc. — without ever exposing the singleton itself.
+ * extendSanitizeSchema((s) => {
+ *   console.log('default sanitize schema:', s);
+ * });
+ * ```
+ *
+ * @remarks Allowing a protocol on `protocols.href` lets the URL through
+ * Gate 1 (the schema-level per-protocol allowlist, which runs inside the
+ * rehype plugin chain). Gate 2 (`urlTransform`, the per-attribute rewriter
+ * that runs later at render time in `renderHastSubtree`) must permit the
+ * same protocol independently — see the `urlTransform` prop on
+ * `<AIMarkdown>` and the exported {@link defaultUrlTransform} for
+ * composition. Keep the two protocol lists in sync.
+ *
+ * ### Footguns
+ *
+ * - **Reassigning the local parameter** (`(s) => { s = { …new schema… }; }`)
+ *   does NOT replace the draft — JS only rebinds the local variable. Either
+ *   mutate the original draft or `return` the new object explicitly.
+ * - **Returning `null`** is treated the same as returning nothing (the
+ *   modified draft is used). The TypeScript signature does not permit
+ *   `null`, but JS callers or `as`-casted code paths could silently hit
+ *   this. Prefer `return` with no value, or an explicit `return draft;`.
+ * - **Throwing inside the modifier** propagates to the call site
+ *   uncaught — there is no try/catch. Callers usually invoke this once at
+ *   module load, where a thrown error surfaces as a startup-time crash and
+ *   is the correct failure mode.
+ *
+ * @param modifier - Receives a deep clone of the library default. Mutate it
+ *   freely; either return the (possibly different) result, or return
+ *   nothing to use the mutated draft. Returning `undefined` (and, by
+ *   convention, `null`) is treated the same as a mutate-only call.
+ * @returns A new `Schema` object — never the library default singleton.
+ */
+declare function extendSanitizeSchema(modifier: (draft: SanitizeSchema) => SanitizeSchema | void): SanitizeSchema;
+
+/**
+ * Type definitions for the sealed engine plugin system (v2 input surface).
+ *
+ * An "engine plugin" is a first-class, core-exported description of one
+ * configurable entry in the unified plugin chain. The five shipped plugins
+ * replace the two v1.x enums (`AIMarkdownRenderExtraSyntax` /
+ * `AIMarkdownRenderDisplayOptimizeAbility`) as the public way to select
+ * optional parse-level capability.
+ *
+ * ## Why the set is sealed
+ *
+ * The incremental (prefix-freeze) parse engine's boundary scanner is
+ * syntax-aware — it must know the boundary rules of every multiline
+ * construct in the chain (see `computeFreezeBoundary`'s `defListEnabled`
+ * option). Open plugin injection would void the engine's verification
+ * record (50k-sample fuzz, direction batteries, byte equivalence), so
+ * plugins are born where the certification rig lives: `packages/core`.
+ * Wrappers curate (bundle default sets, filter, facade sugar); consumers
+ * select. New parse-level capability lands via an upstream PR into core.
+ * Third-party *content* extension stays open through `contentPreprocessors`
+ * and `customComponents`.
+ *
+ * ## Seal mechanics
+ *
+ * The seal is a type-level contract and design declaration, not runtime
+ * tamper-proofing — the same guarantee class as `Object.freeze`. The
+ * `'~sealed'` marker key makes accidental construction a type error while
+ * keeping the type structural, which is required for the type to remain
+ * assignable across the package's two build entries (the root entry and
+ * the `/plugins` subpath must stay mutually assignable whether or not the
+ * build duplicates this declaration per entry; a `unique symbol` brand
+ * would break the duplicated case. Current tsup output happens to share
+ * one declaration chunk between the entries — an implementation detail
+ * the seal deliberately does not lean on). A second, runtime gate
+ * (`getEnginePluginInternals`, enforced in `sanitizeEnginePlugins`)
+ * additionally rejects any object that lacks EITHER the marker or the
+ * internal stage metadata, so a type-level forge is dropped at runtime
+ * with a dev warning. Deliberately forging both keys voids the engine's
+ * verification record.
+ *
+ * @module plugins/defs
+ */
+/**
+ * Names of the shipped engine plugins. Closed to third-party EXTENSION (see
+ * module docs), but an OPEN set across 2.x versions: new plugin names may be
+ * added in minor releases. Do not write exhaustive `switch` statements or
+ * `Record<AIMarkdownEnginePluginName, …>` maps over this union — both break
+ * on the next addition. Feature-test with `Set`/`includes` instead.
+ */
+type AIMarkdownEnginePluginName = 'highlight' | 'definitionList' | 'smartypants' | 'pangu' | 'removeComments';
+/**
+ * A sealed engine plugin. Values are core-exported singletons from
+ * `@ai-react-markdown/core/plugins`; pass them to the `enginePlugins` prop
+ * of `<AIMarkdown>`.
+ *
+ * - Passing an array replaces the default set wholesale (array-atomic
+ *   semantics); omitting the prop means `defaultEnginePlugins` (all five).
+ * - The produced chain position of each plugin comes from canonical
+ *   per-stage tables keyed by name (`pluginChain.ts`) — the order of the
+ *   user-supplied array is irrelevant.
+ * - Duplicate members are deduplicated with a dev warning.
+ * - Serializing plugin objects is unsupported; transport
+ *   {@link AIMarkdownEnginePlugin.name} instead and map names back to the
+ *   exported singletons at the edge (remote-config scenarios).
+ */
+interface AIMarkdownEnginePlugin {
+    /** Stable identifier; the serialization escape hatch. */
+    readonly name: AIMarkdownEnginePluginName;
+    /**
+     * @internal Type-level seal — constructible only inside core. Third-party
+     * construction (including deliberately forging this marker) voids the
+     * incremental engine's verification record.
+     */
+    readonly '~sealed': 'ai-react-markdown/engine-plugin';
+}
+/**
+ * Chain stage a plugin belongs to. Determines the plugin's splice position
+ * in the produced remark chain — user array order never does.
+ * @internal
+ */
+type EnginePluginStage = 'extraSyntax' | 'displayOptimize';
+/**
+ * Runtime metadata carried by every sealed plugin object. Not part of the
+ * public type — internal consumers read it through
+ * {@link getEnginePluginInternals}.
+ * @internal
+ */
+interface EnginePluginInternals {
+    readonly stage: EnginePluginStage;
+}
+/**
+ * Read a sealed plugin's internal metadata. Returns `null` for objects that
+ * do not carry it (a forged or foreign object) so callers can reject them
+ * defensively instead of crashing.
+ * @internal
+ */
+declare function getEnginePluginInternals(plugin: AIMarkdownEnginePlugin): EnginePluginInternals | null;
+
+/**
+ * THE single source of the production plugin chain.
+ *
+ * `MarkdownContent`'s memos, the splice-equivalence arbiter's option
+ * catalog (`incrementalParse/testPluginCatalog.ts`), and the prefixFreeze
+ * experiment harness all build their chains HERE — plugin-order drift
+ * between the renderer and its verification suites previously required
+ * hand-synchronized copies, and a missed copy would silently leave the
+ * arbiter testing a non-production pipeline.
+ *
+ * Two deliberate NON-consumers, kept as independent mirrors on purpose:
+ * - `byteEquivalence.test.tsx`'s `legacyPlugins()` — it is the REFERENCE
+ *   implementation the new pipeline is compared against; importing this
+ *   module would make that comparison circular.
+ * - `positionPropagation.test.ts` — it pins the position-retention
+ *   contract of the exact stack and must fail loudly when the stack
+ *   changes, not silently follow it.
+ *
+ * @module components/pluginChain
+ */
+
+type RemarkPlugins = NonNullable<PipelineOptions['remarkPlugins']>;
+type RehypePlugins = NonNullable<PipelineOptions['rehypePlugins']>;
+type RemarkRehypeOptions = NonNullable<PipelineOptions['remarkRehypeOptions']>;
+/** The always-on remark chain with plugin-gated extras spliced at their
+ *  contractual positions. ORDER IS LOAD-BEARING — see the arbiter suite. */
+declare function buildCoreRemarkPlugins(enginePlugins: readonly AIMarkdownEnginePlugin[]): RemarkPlugins;
+/** The rehype chain. `clobberPrefix` namespaces ids per instance; pass ''
+ *  for unprefixed output (test harnesses). */
+declare function buildCoreRehypePlugins(sanitizeSchema: SanitizeSchema, clobberPrefix: string): RehypePlugins;
+/** Base remark-rehype options (before the standalone/coordinated handler
+ *  merge that `MarkdownContent`'s pipeline memo layers on top). */
+declare function buildCoreRemarkRehypeOptions(enableDefinitionList: boolean): RemarkRehypeOptions;
+
+/**
+ * `rehypeRebaseHashLinks` — restore intra-document hash navigation after
+ * `rehype-sanitize` clobbers `id` attributes.
+ *
+ * ### Why this exists
+ *
+ * `rehype-sanitize` defends against ID-clobbering attacks (e.g. a malicious
+ * `<div id="window">` shadowing `window.window`) by prefixing every clobberable
+ * attribute (`id`, `name`, `aria-describedby`, `aria-labelledby`) with
+ * `clobberPrefix` (default `'user-content-'`). It does **not** rewrite `href`
+ * values, since hashes are not themselves clobbering vectors. As a result,
+ * any intra-document link — `[ref](#section)`, GFM footnote anchors, or raw
+ * `<a id="x"><a href="#x">` pairs — points at an unprefixed hash while its
+ * target id has been prefixed: navigation breaks.
+ *
+ * Pair this plugin with `remarkRehypeOptions: { clobberPrefix: '' }` so that
+ * `mdast-util-to-hast` does not also prefix (avoiding `user-content-user-content-`
+ * double prefixes), and place it **after** `rehype-sanitize` in the rehype
+ * pipeline. The result mirrors GitHub's rendering: a single, consistent
+ * `user-content-` prefix on every id and matching hash href.
+ *
+ * @module components/rehypeRebaseHashLinks
+ */
+
+interface RehypeRebaseHashLinksOptions {
+    /** Prefix to apply. Must match the `clobberPrefix` used by `rehype-sanitize`. */
+    prefix?: string;
+}
+declare const rehypeRebaseHashLinks: Plugin<[RehypeRebaseHashLinksOptions?], Root$1>;
+
+declare function rehypeFooterAdorn(): (tree: Root$1) => void;
+
+/**
+ * Direction B: source-level phantom-definition injection helpers.
+ *
+ * @module components/remarkInjectPhantomDefs
+ */
+declare const SENTINEL_LINK_URL = "__aimd_sentinel_link__";
+declare const SENTINEL_FN_CONTENT = "__aimd_sentinel_fn__";
+interface PhantomLabels {
+    missingFootnotes: Set<string>;
+    missingLinks: Set<string>;
+}
+/**
+ * The phantom-definition SUFFIX for labels not locally defined ('' when
+ * there are none). Kept separate from the join so the incremental engine
+ * can treat it as always-tail: the suffix may shrink/grow/reorder between
+ * frames (registry label churn) without breaking the append gate.
+ *
+ * Labels are expected to already be normalized via normalizeId (uppercase).
+ */
+declare function buildPhantomSuffix(phantoms: PhantomLabels): string;
+
+/**
+ * Custom mdast-util-to-hast handlers for cross-chunk label resolution.
+ *
+ * Direction A: `footnoteDefinitionHandler` mutates `state.footnoteOrder` so
+ * `state.footer()` emits a `<section data-footnotes>` even when no
+ * `footnoteReference` exists locally (orphan-def protection).
+ *
+ * Direction B: `linkReferenceHandler` / `imageReferenceHandler` /
+ * `footnoteReferenceHandler` short-circuit the default to-hast output and
+ * emit custom hast tags (`cross-chunk-link` / `cross-chunk-image` /
+ * `footnote-sup`) carrying `label` + `referenceType` properties. These tags
+ * map to React placeholder components in Phase 11. The sentinel URL is never
+ * read — the handlers only need to know that the def is resolvable
+ * (i.e. present in state.definitionById).
+ *
+ * All identifier comparisons normalize via {@link normalizeId} to match
+ * mdast-util-to-hast's internal uppercase keying convention.
+ *
+ * @module components/customMdastHandlers
+ */
+
+interface CrossChunkHandlerOptions {
+    /** Set of labels (already normalized) that this chunk phantom-injected
+     *  into its source for parser acceptance. Handlers use this to short-circuit
+     *  state writes that would otherwise leak sentinel content into the footer. */
+    phantomFootnoteLabels: Set<string>;
+    /** Same role for link/image defs. */
+    phantomLinkLabels: Set<string>;
+    /** When true, footnoteDefinitionHandler proactively registers orphan defs
+     *  to state.footnoteOrder (Direction A). */
+    preserveOrphan: boolean;
+    /** Passed through to placeholder hast properties so React components can
+     *  partition by document. */
+    documentId: string;
+}
+declare function buildCrossChunkHandlers(): Handlers;
+
+/**
+ * Two-gate URL sanitization for cross-chunk link/image placeholders.
+ *
+ * In the standalone path, every `<a href>` and `<img src>` element passes
+ * through TWO gates before render:
+ *
+ *   1. `urlTransform(url, key, node)` — the caller's allowlist (default:
+ *      `defaultUrlTransform`, which mirrors GitHub's protocol allowlist).
+ *      Runs in `markdown/transform.ts` during the hast visit pass.
+ *   2. `rehype-sanitize` `protocols.<attr>` allowlist — drops the attribute
+ *      entirely if the URL's protocol isn't permitted for that attribute.
+ *
+ * Cross-chunk references skip BOTH passes naturally: the placeholder hast
+ * tag (`<cross-chunk-link>` / `<cross-chunk-image>`) carries only a `label`
+ * attribute; the real URL is looked up from the registry at React render
+ * time, AFTER both passes have run. Without an explicit re-sanitization
+ * here, cross-chunk renders would observably diverge from standalone:
+ *
+ *   - A `[evil]: javascript:…` def in chunk A used by chunk B would render
+ *     a live `javascript:` link, even though the same source in standalone
+ *     mode is stripped.
+ *   - A consumer who allows a custom scheme via `urlTransform` but did NOT
+ *     add it to `sanitizeSchema.protocols` would see standalone strip the
+ *     `href`, but cross-chunk render it — silently breaking the "two gates,
+ *     defense in depth" contract documented in README.
+ *   - A key-aware `urlTransform` (e.g. one that allows a scheme only on
+ *     `href` but not `src`) would behave correctly in standalone but be
+ *     bypassed in the cross-chunk image path if we sanitized once at
+ *     contribute time with a fixed key.
+ *
+ * This helper makes the cross-chunk path observably identical to the
+ * standalone two-gate pipeline, parameterised by the correct `key` for
+ * each tag (`'href'` for `<a>`, `'src'` for `<img>`).
+ *
+ * @module components/crossChunkUrlSanitize
+ */
+
+type UrlAttrKey = 'href' | 'src';
+type UrlAttrTag = 'a' | 'img';
+/**
+ * Run a cross-chunk-resolved URL through both standalone gates.
+ *
+ * @returns Sanitized URL string. Empty string when either gate strips the
+ *   URL — matches `defaultUrlTransform`'s and `rehype-sanitize`'s observable
+ *   behavior of replacing a blocked URL with `''`.
+ */
+declare function sanitizeCrossChunkUrl(rawUrl: string, key: UrlAttrKey, tagName: UrlAttrTag, urlTransform: UrlTransform, schema: SanitizeSchema): string;
+
+/**
+ * The five shipped engine plugins and the default set.
+ *
+ * Construction happens ONLY here (principle P7: capability construction
+ * follows the verification harness — the certification rig lives in this
+ * package). Each object is frozen and carries internal stage metadata that
+ * fixes its position in the produced chain; see `plugins/defs.ts` for the
+ * seal rationale.
+ *
+ * @module plugins/catalog
+ */
+
+/** `==Highlight==` syntax support (v1.x: `AIMarkdownRenderExtraSyntax.HIGHLIGHT`). */
+declare const highlight: AIMarkdownEnginePlugin;
+/**
+ * Definition list syntax (v1.x: `AIMarkdownRenderExtraSyntax.DEFINITION_LIST`).
+ * @see https://michelf.ca/projects/php-markdown/extra/#def-list
+ */
+declare const definitionList: AIMarkdownEnginePlugin;
+/** Strip HTML comments from the content (v1.x: `REMOVE_COMMENTS`). */
+declare const removeComments: AIMarkdownEnginePlugin;
+/**
+ * Typographic enhancements via SmartyPants — curly quotes, em-dashes, etc.
+ * (v1.x: `SMARTYPANTS`). @see https://www.npmjs.com/package/smartypants
+ */
+declare const smartypants: AIMarkdownEnginePlugin;
+/** Automatic spacing between CJK and half-width characters (v1.x: `PANGU`). */
+declare const pangu: AIMarkdownEnginePlugin;
+/**
+ * The default engine plugin set — all five, in canonical chain order.
+ * Parity with the v1.x shipped defaults (`defaultAIMarkdownRenderConfig`).
+ *
+ * The recommended "turn one off" idiom:
+ * ```ts
+ * <AIMarkdown enginePlugins={defaultEnginePlugins.filter((p) => p !== pangu)} />
+ * ```
+ */
+declare const defaultEnginePlugins: readonly AIMarkdownEnginePlugin[];
+
+/**
+ * Shared hast predicates — engine-side home for detection helpers consumed
+ * by both the incremental-parse engine (attributeHastChildren's seam
+ * attribution) and core's block-memo renderer.
+ *
+ * Lifted verbatim from core's blockMemo.ts (boundary action ①): blockMemo
+ * stays React-side while incrementalParse moves into the engine, and this
+ * predicate was the one value-level edge between them.
+ *
+ * @module components/hastPredicates
+ */
+
+/**
+ * Detect mdast-util-to-hast's synthesized footnote `<section data-footnotes>`.
+ * Position-based detection alone would be too broad — any future rehype plugin
+ * that appends a position-less node would be misclassified. We assert by
+ * `tagName === 'section'` AND presence of the `dataFootnotes` property.
+ */
+declare function isFootnoteSection(node: Element): boolean;
+
+/**
+ * CommonMark §4.7 label normalization. Used as the single canonical form
+ * for all label-keyed structures (registry maps, phantomFootnoteLabels Set,
+ * labelSet, etc.) and for handler comparisons against mdast-util-to-hast's
+ * internal `state.definitionById` / `state.footnoteById` keys.
+ *
+ * Direction is uppercase to align with mdast-util-to-hast internals
+ * (`String(identifier).toUpperCase()`). Direction is irrelevant once both
+ * sides agree; uppercase chosen to match the upstream library to minimize
+ * adapter calls.
+ *
+ * @module components/normalizeId
+ */
+declare function normalizeId(s: string): string;
+/**
+ * Same as {@link normalizeId} plus resolution of backslash escapes.
+ * Used by PASS 0.5 substring pre-check against raw chunk source text:
+ * sources may write `[foo\]bar]` but the resulting label identifier is
+ * `foo]bar`, so we must unescape source before substring matching.
+ */
+declare function normalizeForMatch(s: string): string;
+
+/**
+ * Shorten long consumer-supplied `documentId` values down to a fixed-length
+ * Base62 hash so they don't bloat every rendered `id="…"` / `href="#…"`.
+ *
+ * Trade-offs:
+ *   - Non-cryptographic hash (MurmurHash3 x86 32-bit) — pure speed, excellent
+ *     avalanche on the structured inputs we actually receive (UUIDs, nanoids,
+ *     `useId()` outputs, opaque chat-message ids). Collision domain is 2^32;
+ *     at ~77,000 active document ids the birthday-paradox collision rate hits
+ *     ~50%, which is far beyond any realistic single-page chat workload.
+ *   - Only kicks in past a length threshold (default 16) so short, hand-picked
+ *     ids stay readable and existing test fixtures (`'tst'`, `'doc-a'`, …)
+ *     plus `useId()`'s `'_r_0_'`-style output (≤7 chars) pass through untouched.
+ *   - Pure function: same input always yields the same output. Two chunks
+ *     sharing one logical `documentId` therefore still produce identical
+ *     prefixes, so cross-chunk anchor and footnote coordination is preserved.
+ *
+ * Why MurmurHash3 specifically (vs the simpler FNV-1a):
+ *   - FNV-1a does NOT pass SMHasher's avalanche test. For *structured* inputs
+ *     like UUIDs (fixed hyphen positions, hex-only alphabet) its lower bits
+ *     show measurable bias, which translates to a higher *practical* collision
+ *     rate than the theoretical 2^32 figure suggests.
+ *   - MurmurHash3's finalizer (`fmix32`) — `h ^= h>>>16; h = imul(h, M1);
+ *     h ^= h>>>13; h = imul(h, M2); h ^= h>>>16` — is purpose-built to
+ *     flatten any local pattern that survives the body, which is what gets
+ *     it through SMHasher. That's the entire engineering reason for the
+ *     ~30-line code-size delta vs FNV-1a.
+ *
+ * @module components/shortenDocumentId
+ */
+/**
+ * Shorten a `documentId` for use inside an HTML id prefix.
+ *
+ * @param id - The raw documentId (consumer-supplied or `useId()` fallback).
+ * @param threshold - Only ids strictly longer than this get hashed.
+ *   Defaults to `16`, which leaves short hand-picked ids and React's
+ *   `useId()` outputs unchanged but catches UUIDs (36 chars) and nanoids.
+ * @returns Either the original `id` (when short) or a 1–6 char Base62 hash.
+ */
+declare function shortenDocumentId(id: string, threshold?: number): string;
+
+/**
+ * Dev-only pipeline stage timing.
+ *
+ * The block-memo render path runs four distinct stages per content change
+ * (parse → transform → build → render). Which one dominates depends on the
+ * workload — plugin mix, document length, math density — and every
+ * optimization decision should start from that split, not from a guess.
+ *
+ * Two delivery channels, deliberately separate:
+ *
+ * - **Programmatic consumers** (the BlockMemoCompare story's profiler)
+ *   use {@link subscribeStageTimings} — a private, direct callback
+ *   channel. It must NOT go through the User Timing API: React 19 dev
+ *   builds emit one `performance.measure` per component render
+ *   ("component tracks"), so a page-global 'measure' observer receives a
+ *   flood of foreign entries it has to filter, and — measured — anything
+ *   that scans or clears the buffer becomes O(buffer) with MILLIONS of
+ *   entries in a long session.
+ * - **DevTools timeline visibility**: {@link measureStage} still emits
+ *   one `performance.measure` per stage, named
+ *   `ai-markdown:stage:<stage>`. Emission is an append — cheap. It does
+ *   NOT clear per name afterwards: Chromium's `clearMeasures(name)` scans
+ *   the whole buffer, and under the React-dev flood that per-call scan
+ *   cost ~35% of main-thread time ON THE INSTRUMENTED SIDE ONLY —
+ *   inverting the very benchmark this instrumentation serves. Our own
+ *   growth is ~4 entries per streamed token; the benchmark harness
+ *   bulk-clears the buffer between runs (see useRenderProfiler.reset).
+ *
+ * Production builds fold {@link ENABLED} to `false`: the dual dev/prod
+ * build resolves `process.env.NODE_ENV` at build time (tsup `env`), so
+ * the published dist carries no env read at all; in-repo src consumers
+ * (storybook, vitest) run under Vite/Node where the text is substituted
+ * or `process` exists. The whole thing costs one boolean check per stage.
+ *
+ * @module components/devStageTimings
+ */
+/** The stages of the block-memo render pipeline, in execution order.
+ *  Single source of truth: the union type, the emitted measure names, and
+ *  any display ordering (ProfilerPanel) all derive from this tuple.
+ *  `scan` is the incremental-parse boundary detector (emitted only when
+ *  `incrementalParse` routes through the incremental engine);
+ *  when incremental parsing splices, `parse`/`transform` cover the
+ *  TAIL-ONLY work — the honest per-frame cost, not the full-document one. */
+declare const PIPELINE_STAGES: readonly ["scan", "parse", "transform", "build", "render"];
+type PipelineStage = (typeof PIPELINE_STAGES)[number];
+/** Prefix for the emitted `performance.measure` entry names. */
+declare const STAGE_MEASURE_PREFIX = "ai-markdown:stage:";
+/** `instanceId` is the emitting `<AIMarkdown>`'s documentId — listeners on a
+ *  page with several instances (e.g. an A/B comparison where BOTH sides run
+ *  the block-memo path) filter by it; a page-wide aggregate ignores it. */
+type StageListener = (stage: PipelineStage, durationMs: number, instanceId?: string) => void;
+/**
+ * Subscribe to stage timings over the private callback channel (dev-only;
+ * in production builds {@link measureStage} never emits, so listeners
+ * simply stay silent). Returns an unsubscribe function.
+ *
+ * This exists so the benchmark profiler does NOT have to observe the
+ * page-global 'measure' entry type: React 19 dev floods that channel with
+ * one measure per component render, which would have to be filtered per
+ * batch — and the module-level listener set is still page-scoped, so the
+ * one-consumer-per-page discipline from the story docs continues to apply.
+ */
+declare function subscribeStageTimings(listener: StageListener): () => void;
+/**
+ * Run `fn` as the named pipeline stage. In dev: notifies
+ * {@link subscribeStageTimings} listeners and emits one
+ * `performance.measure` for DevTools timeline visibility. The
+ * single-callable shape (instead of a start/end pair) makes the stage
+ * name a typed argument and the pairing unforgettable: a call site cannot
+ * mismatch or drop an end call. If `fn` throws, nothing is emitted for
+ * the aborted stage.
+ *
+ * NOTE: emission is append-only — never clear per name from here. See the
+ * module docs: `clearMeasures(name)` is O(page buffer), and React 19
+ * dev's component tracks grow that buffer without bound.
+ */
+declare function measureStage<T>(stage: PipelineStage, fn: () => T, instanceId?: string): T;
+
+/**
+ * Builds the `rehype-sanitize` schema used by the internal markdown renderer.
+ *
+ * Extracted into its own module so the merge logic can be unit-tested in
+ * isolation without pulling in React or the full markdown pipeline.
+ *
+ * @module components/sanitizeSchema
+ */
+
+type Schema = typeof defaultSchema;
+type AttributeEntry = NonNullable<NonNullable<Schema['attributes']>[string]>[number];
+/**
+ * Extend the allowlist for a tag's `className` attribute with extra class
+ * names while preserving all other default entries.
+ *
+ * `findDefinition` in hast-util-sanitize returns the *first* matching entry
+ * for a given property name, so appending a second `className` entry would be
+ * ignored. Instead, merge the allowed values into the existing entry.
+ *
+ * Edge cases:
+ * - `existing` is `undefined` → returns a single new `['className', ...extra]`
+ * - `existing` has no `className` entry → appends one with just the extras
+ * - `existing` has a bare-string `'className'` entry (hast-util-sanitize's
+ *   "allow all values" form) → would be narrowed to an allow-list. This is a
+ *   semantics change, but the current `defaultSchema.attributes.code` entry
+ *   is always tuple-form, so this branch is defensive only.
+ */
+declare function mergeClassNameAllowlist(existing: ReadonlyArray<AttributeEntry> | undefined, extraClassNames: readonly string[]): AttributeEntry[];
+/**
+ * The full sanitize schema used by the markdown renderer: extends
+ * `defaultSchema` to allow `<mark>`, the KaTeX math class names, and the
+ * three custom hast tags emitted by cross-chunk coordination handlers.
+ *
+ * **Owns its arrays and objects.** The shallow spread of `defaultSchema`
+ * alone would leave `attributes.a`, `attributes.img`, `protocols`,
+ * `ancestors`, and similar nested fields aliased to `rehype-sanitize`'s
+ * default singleton. A consumer who reasonably (but mistakenly) writes
+ * `sanitizeSchema.protocols.href.push('myapp')` would then poison
+ * `rehype-sanitize`'s `defaultSchema` for every other consumer in the
+ * process — a cross-package side-effect that's near-impossible to debug.
+ *
+ * One `cloneDeep` at module init breaks that aliasing without measurable
+ * cost (init-time only, single small object graph). The recommended
+ * extension API is still {@link extendSanitizeSchema}, which clones again
+ * per call; this layer just makes the exported singleton safe if someone
+ * skips the helper.
+ */
+declare const sanitizeSchema: Schema;
+
+/**
+ * Smooth-stream controller — framework-free typewriter pacing.
+ *
+ * Reveals an accumulated source string as a gradually growing prefix
+ * (`getVisible()`), stepping by grapheme cluster at a rate that adapts to
+ * backlog. The revealed prefix is append-only between snaps, which is
+ * exactly the incremental-parse engine's fast path — the controller sits
+ * upstream of the renderer and never touches the parse pipeline.
+ *
+ * Pacing model — an adaptive jitter buffer (audio-playout style):
+ * - The controller estimates the source's arrival rate and burst interval
+ *   with irregular-sampling EMAs (recorded on every append), and derives a
+ *   target buffer B* ≈ bufferFactor × one burst's worth of text — the
+ *   causality floor for smoothing bursts of that period.
+ * - Streaming: rate = max(floor, rateEma + (backlog − B*) / correctionTau).
+ *   Feedforward tracks the source speed (bounded lag at any model speed);
+ *   the feedback term pins the backlog near B*, dipping BELOW the source
+ *   rate on purpose when the buffer runs low so it can refill instead of
+ *   running dry between bursts. The floor is a tiny anti-freeze trickle,
+ *   deliberately smaller than any realistic arrival rate.
+ * - Pre-stats (first burst after construction/snap): no estimate exists
+ *   yet, so the backlog reveals over roughly one correction window.
+ * - Finished: rate = backlog / time-to-deadline, deadline stamped at
+ *   `finish() + drainMs` — the backlog empties BY the deadline instead of
+ *   decaying toward it forever.
+ * - A deadline credit accumulator converts elapsed time (injectable
+ *   `now()`) into whole-grapheme reveals per scheduled frame — timers
+ *   carry no state between frames, so throttled/paused schedulers
+ *   self-correct on the next tick instead of drifting.
+ * - The public tuning surface is three named presets ({@link SmoothStreamPacing});
+ *   the numeric parameters stay controller-level for advanced hosts.
+ *
+ * Grapheme discipline: stepping uses `Intl.Segmenter` (code-point fallback)
+ * and the trailing grapheme of the source is held back until it is
+ * confirmed — by more text arriving or by `finish()` — so a surrogate
+ * half or a still-growing emoji ZWJ sequence is never revealed to the
+ * parser mid-cluster.
+ *
+ * @module components/smoothStream/controller
+ */
+/**
+ * The public pacing surface: three named trade-off points on the
+ * latency-vs-smoothness axis (the audio-plugin buffer-preset convention —
+ * perceptual parameters resist meaningful numeric tuning).
+ *
+ * - `'smooth'` — target ~1.7 bursts of buffer: almost never runs dry
+ *   between server flushes, at the cost of a little extra lag.
+ * - `'balanced'` (default) — ~1 burst of buffer, the causality floor for
+ *   smoothing: minimal lag that can still bridge a typical gap.
+ * - `'responsive'` — sub-burst buffer: lowest lag, accepts an occasional
+ *   visible pause between bursts.
+ */
+type SmoothStreamPacing = 'smooth' | 'balanced' | 'responsive';
+/** The numeric parameter bundle a {@link SmoothStreamPacing} preset names. */
+interface SmoothStreamPacingParams {
+    /** Target buffer as a multiple of one estimated burst's worth of text. */
+    bufferFactor: number;
+    /**
+     * Feedback time constant (ms): how fast the backlog is steered toward
+     * the target buffer. Also the pre-stats reveal window for the first
+     * burst, before any arrival estimate exists.
+     */
+    correctionTauMs: number;
+    /** Smoothing horizon (ms) for the arrival-rate / burst-interval EMAs. */
+    emaTauMs: number;
+    /**
+     * Anti-freeze floor (grapheme clusters/s). Deliberately tiny — smaller
+     * than any realistic arrival rate — so the feedback term can slow the
+     * reveal below the source rate to refill the buffer, without ever
+     * freezing visible progress entirely.
+     */
+    minCharsPerSecond: number;
+    /**
+     * Hard drain budget after {@link SmoothStreamController.finish}: a
+     * deadline is stamped at `finish() + drainMs` and the rate scales with
+     * remaining-backlog / remaining-time, so the backlog empties BY the
+     * deadline (not asymptotically). Consumed when the deadline is stamped —
+     * changing it affects the next drain, not one in progress.
+     */
+    drainMs: number;
+}
+interface SmoothStreamOptions extends Partial<SmoothStreamPacingParams> {
+    /**
+     * Named pacing preset, the intended tuning surface. Individual
+     * {@link SmoothStreamPacingParams} fields act as advanced per-field
+     * overrides on top of the chosen preset. Default `'balanced'`.
+     */
+    pacing?: SmoothStreamPacing;
+    /**
+     * Injectable clock (milliseconds, monotonic preferred). Defaults to
+     * `performance.now`, falling back to `Date.now`. Tests inject a manual
+     * clock — pacing must never race the wall clock.
+     */
+    now?: () => number;
+    /**
+     * Injectable frame scheduler: schedules `cb` once, ASYNCHRONOUSLY, and
+     * returns a cancel function. A scheduler that invokes `cb` synchronously
+     * violates the contract (the returned cancel handle would be recorded
+     * after the tick already cleared it, stranding the controller). Defaults
+     * to `requestAnimationFrame` with a `setTimeout` fallback so the
+     * controller also runs under node.
+     */
+    schedule?: (cb: () => void) => () => void;
+}
+interface SmoothStreamController {
+    /**
+     * Sets the full accumulated source. An append-extension of the current
+     * source animates; anything else — the FIRST update after construction
+     * included — snaps (content replacement is not a stream). An identical
+     * string is a no-op, so replayed effects (StrictMode) are safe.
+     * Calling `update` after {@link finish} re-enters streaming: multi-round
+     * LLM flows (stream → tool call → stream) keep one controller.
+     */
+    update(source: string): void;
+    /**
+     * Signals end of stream: confirms the held-back trailing grapheme and
+     * switches the control law to the `drainMs` window. Not terminal —
+     * a later {@link update} resumes animation.
+     */
+    finish(): void;
+    /** Jumps to `source` instantly, no animation, and clears any backlog. */
+    snap(source: string): void;
+    /** Reveals everything pending right now (skip-animation affordance). */
+    flush(): void;
+    /** Subscribes to visible-prefix changes. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The currently revealed prefix. Reference-stable between changes —
+     * safe as a `useSyncExternalStore` snapshot.
+     */
+    getVisible(): string;
+    /** True when the visible prefix has caught up with the full source. */
+    isDrained(): boolean;
+    /**
+     * Cancels any scheduled frame and drops all subscribers. NOT terminal:
+     * any subsequent call ({@link update}, {@link subscribe}, …) revives the
+     * controller. React StrictMode's dev-only effect replay (mount → cleanup
+     * → re-run) disposes and then reuses the same state-held instance — a
+     * permanently-latching dispose would kill the reveal in dev forever.
+     * After a REAL unmount nothing calls back in, so disposal sticks.
+     */
+    dispose(): void;
+}
+/**
+ * The three preset bundles. Calibrated against the burst patterns in the
+ * SmoothStream stories (server-buffer-like flushes at slow and fast model
+ * speeds); frozen so a shared reference can't be mutated by a consumer.
+ */
+declare const SMOOTH_STREAM_PACING_PRESETS: Readonly<Record<SmoothStreamPacing, Readonly<SmoothStreamPacingParams>>>;
+declare const createSmoothStreamController: (options?: SmoothStreamOptions) => SmoothStreamController;
+
+/**
+ * Type definitions for the content preprocessor pipeline.
+ *
+ * @module preprocessors/defs
+ */
+/**
+ * A synchronous function that transforms raw markdown content before it is
+ * passed to the remark/rehype rendering pipeline.
+ *
+ * Preprocessors run in sequence -- each receives the output of the previous one.
+ *
+ * @param content - The raw (or partially processed) markdown string.
+ * @returns The transformed markdown string.
+ *
+ * @example
+ * ```ts
+ * const stripFrontmatter: AIMDContentPreprocessor = (content) =>
+ *   content.replace(/^---[\s\S]*?---\n/, '');
+ * ```
+ */
+type AIMDContentPreprocessor = (content: string) => string;
+
+/**
+ * Content preprocessing pipeline.
+ *
+ * Runs all preprocessors (built-in + user-supplied) in sequence before
+ * the markdown string is handed to react-markdown. The built-in LaTeX
+ * preprocessor always runs first, followed by any extra preprocessors
+ * provided by the consumer.
+ *
+ * @module preprocessors
+ */
+
+/**
+ * Run the full preprocessing pipeline on raw markdown content.
+ *
+ * @param content - Raw markdown string.
+ * @param extraPreprocessors - Optional user-supplied preprocessors appended after the built-in ones.
+ * @param latexPreprocessor - The LaTeX stage. Defaults to the stateless
+ *   {@link preprocessLaTeX}; the renderer passes a per-instance
+ *   append-aware wrapper (byte-identical output, O(active tail) on
+ *   streaming appends) so per-frame reveals stop paying O(document).
+ * @returns The preprocessed markdown string ready for rendering.
+ */
+declare function preprocessAIMDContent(content: string, extraPreprocessors?: AIMDContentPreprocessor[], latexPreprocessor?: AIMDContentPreprocessor): string;
+
+/**
+ * LaTeX preprocessing pipeline.
+ *
+ * Normalizes raw markdown so that LaTeX expressions survive the remark/rehype
+ * rendering pipeline intact. The main entry point is {@link preprocessLaTeX},
+ * which splits content into protected regions (code blocks, inline code, HTML
+ * tags) and applies a sequence of transformations to the unprotected text:
+ *
+ * 1. Escape mhchem commands (`\ce`, `\pu`)
+ * 2. Escape currency dollar signs (e.g. `$100`, `$1,000.50`)
+ * 3. Convert bracket delimiters (`\[...\]`, `\(...\)`) to dollar delimiters
+ * 4. Escape pipes inside closed LaTeX blocks to prevent GFM table interference
+ * 5. Escape pipes inside unclosed LaTeX blocks (streaming partial content)
+ * 6. Escape underscores inside `\text{...}` commands
+ * 7. Convert single-dollar delimiters to double-dollar delimiters
+ * 8. Truncate trailing unclosed LaTeX blocks (streaming protection)
+ *
+ * Thanks to the implementations from the following repositories:
+ * - https://github.com/lobehub/lobe-ui/blob/master/src/hooks/useMarkdown/latex.ts
+ * - https://github.com/danny-avila/LibreChat/blob/main/client/src/utils/latex.ts
+ *
+ * @module preprocessors/latex
+ */
+interface Segment {
+    text: string;
+    isCode: boolean;
+}
+/**
+ * Split content into alternating text and protected segments.
+ * Protected segments (isCode: true) are excluded from LaTeX processing:
+ * - fenced multiline code blocks: 3+ backticks or tildes at the *start of a
+ *   line* (≤3 space indent). Mid-line runs are never fence openers.
+ * - inline code spans: a run of N backticks closed by another run of exactly
+ *   N backticks. May span newlines. Multi-backtick forms (e.g. `` `` `x` ``)
+ *   are supported so literal backtick characters can appear inside.
+ * - HTML tags (e.g. `<span>$</span>` where `$` should not be treated as LaTeX).
+ */
+declare function splitByProtectedRegions(content: string): Segment[];
+/**
+ * Main LaTeX preprocessor entry point.
+ *
+ * Splits the input into protected regions (code blocks, inline code, HTML tags)
+ * and applies the full normalization pipeline to unprotected text segments.
+ * Returns the input unchanged when no LaTeX-related characters (`$`, `\[`, `\(`)
+ * are detected.
+ *
+ * @param str - Raw markdown string.
+ * @returns The preprocessed string with normalized LaTeX delimiters.
+ */
+declare function preprocessLaTeX(str: string): string;
+/**
+ * Append-aware `preprocessLaTeX`: one instance per streaming lineage (the
+ * component holds it like the smooth-stream controller). Byte-identical to
+ * `preprocessLaTeX(full)` on every call; non-append input resets all state;
+ * identical input replays the cached output (StrictMode/idempotence).
+ *
+ * @param options.freezeThreshold Active-region size below which no freeze
+ *   is attempted. Tests pass `0` so SHORT pinned counterexamples actually
+ *   exercise the freeze path instead of passing vacuously through the
+ *   full-reprocess fallback.
+ * @internal Wired by the renderer; not part of the public API.
+ */
+declare function createIncrementalLatexPreprocessor(options?: {
+    freezeThreshold?: number;
+}): (content: string) => string;
+
+/**
+ * Optional streaming tail-repair preprocessor built on `remend` (the
+ * markdown-termination engine extracted from Vercel's Streamdown).
+ *
+ * While a response streams, the tail of the markdown source is frequently
+ * mid-construct — `**bold` without its closer, an unterminated `` `code ``
+ * span, a half-typed `[link](url`. The stock pipeline renders those frames
+ * literally (asterisks and all) until the closing bytes arrive. Wrapping the
+ * content with this preprocessor completes the unterminated syntax so every
+ * frame renders styled.
+ *
+ * NOT enabled by default — opt in per instance:
+ *
+ * ```tsx
+ * const remend = createRemendPreprocessor();
+ * <AIMarkdown content={content} contentPreprocessors={[remend]} />
+ * ```
+ *
+ * Create the preprocessor ONCE (module scope or `useMemo`) — a fresh function
+ * identity per render would defeat `contentPreprocessors`' stable-value
+ * memoization and re-run the whole pipeline every frame.
+ *
+ * Interactions (see docs/content-preprocessors.md for the full discussion):
+ *
+ * - **block-memo**: zero conflict. Repairs only append/adjust the tail;
+ *   earlier blocks' bytes are untouched, so their hast digests still hit.
+ * - **incremental parse** (`incrementalParse`): frames whose tail was
+ *   repaired are not byte-appends of the previous frame, so the engine's
+ *   append gate falls back to a full parse for exactly those frames (not
+ *   sticky — splicing resumes once the construct closes in the real bytes).
+ * - **`preprocessLaTeX`**: user preprocessors run AFTER the built-in LaTeX
+ *   pass. Math repair is therefore disabled here (`katex`/`inlineKatex`
+ *   forced off) — the LaTeX preprocessor already owns `$` handling,
+ *   including truncating unclosed `$$` tails.
+ * - **complete documents**: on well-formed text remend is a no-op, so the
+ *   final frame renders identically with or without it. A document that
+ *   legitimately ends inside an unterminated marker (a trailing lone `*`)
+ *   will get it closed — acceptable for streaming UIs, but don't apply this
+ *   preprocessor to static content.
+ *
+ * @module preprocessors/remend
+ */
+
+/** Options accepted by {@link createRemendPreprocessor} — everything remend
+ *  supports except the math toggles, which this pipeline reserves for the
+ *  built-in LaTeX preprocessor. */
+type RemendPreprocessorOptions = Omit<RemendOptions, 'katex' | 'inlineKatex'>;
+/**
+ * Build an {@link AIMDContentPreprocessor} that completes unterminated
+ * markdown syntax at the streaming tail.
+ *
+ * Deviations from remend's own defaults:
+ *
+ * - `linkMode: 'text-only'` (overridable) — remend's default (`'protocol'`)
+ *   substitutes a `streamdown:incomplete-link` placeholder URL, but this
+ *   pipeline's URL sanitizer strips unknown protocols, which would leave a
+ *   dead `<a>` for the duration of the stream. Rendering the link text
+ *   plainly until the real URL arrives looks better under our sanitize
+ *   defaults.
+ * - `katex`/`inlineKatex` forced off (NOT overridable — removed from the
+ *   option type) — the built-in LaTeX preprocessor (which runs first)
+ *   already rewrites and truncates `$`/`$$` constructs; two writers on the
+ *   same delimiters would fight.
+ */
+declare function createRemendPreprocessor(options?: RemendPreprocessorOptions): AIMDContentPreprocessor;
+
+export { type AIMDContentPreprocessor, type AIMarkdownEnginePlugin, type AIMarkdownEnginePluginName, type AdvanceOptions, type AdvanceResult, type AllowElement, type ChunkData, type Contribution, type CrossChunkHandlerOptions, DEFAULT_PAYLOAD, DEF_LINE_START_RE, type DefLabelScanner, type DefLabels, type Deprecation, type EnginePluginInternals, type EnginePluginStage, type ExtractContributionsOptions, type FootnoteDef, type FreezeBoundaryOptions, type IncrementalParseState, type IncrementalStage, type LinkDef, PIPELINE_STAGES, type ParsedMarkdown, type PhantomLabels, type PipelineOptions, type PipelineStage, type RefKind, type RefRecord, type Registry, type RegistryInternal, type RehypePlugins, type RehypeRebaseHashLinksOptions, type RemarkPlugins, type RemarkRehypeOptions, type RemendPreprocessorOptions, SENTINEL_FN_CONTENT, SENTINEL_LINK_URL, SMOOTH_STREAM_PACING_PRESETS, STAGE_MEASURE_PREFIX, type SanitizeSchema, type SmoothStreamController, type SmoothStreamOptions, type SmoothStreamPacing, type SmoothStreamPacingParams, type TransformContext, type UrlAttrKey, type UrlAttrTag, type UrlTransform, advanceIncrementalParse, attributeHastChildren, buildCoreRehypePlugins, buildCoreRemarkPlugins, buildCoreRemarkRehypeOptions, buildCrossChunkHandlers, buildPhantomSuffix, buildTransform, codePointSnapshots, collectDefLabels, computeFreezeBoundary, createDefLabelScanner, createFile, createIncrementalLatexPreprocessor, createProcessor, createRegistry, createRemendPreprocessor, createSmoothStreamController, defaultEnginePlugins, defaultUrlTransform, definitionList, extendSanitizeSchema, extractContributions, extractDefBodiesFromHast, getEnginePluginInternals, highlight, isFootnoteSection, lastRegionStart, measureStage, mergeClassNameAllowlist, normalizeForMatch, normalizeId, pangu, parseStage, preprocessAIMDContent, preprocessLaTeX, rehypeFooterAdorn, rehypeRebaseHashLinks, removeComments, sanitizeCrossChunkUrl, sanitizeSchema, shortenDocumentId, smartypants, sourceIdFromFootnoteLiId, splitByProtectedRegions, subscribeStageTimings, transformStage, withDefs };