@ai-react-markdown/engine 2.3.3 → 2.4.1

package/dist/index.d.cts

@@ -184,7 +184,10 @@ declare const defaultUrlTransform: UrlTransform;
  *    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.
+ *    (`<div` at EOL, attributes wrapping) count as opens. Closers that
+ *    OVERLAP their opener (`<!-->`, `<!--->`, line-start `<?>`) close on
+ *    the spot — CommonMark and parse5 agree — so the markup after them is
+ *    scanned, not skipped as construct interior.
  * 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
@@ -215,19 +218,29 @@ declare const defaultUrlTransform: UrlTransform;
  *    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).
+ *    reproduced on v1.8.0). Every candidate emitted while the remnant is
+ *    the last frozen child is rejected (they stay rejected for good); once
+ *    a later confirmed content line pins the seam from the frozen side,
+ *    the candidates AFTER that line are safe again. Dropping candidates
+ *    only over-blocks (safe direction). Whitespace-only remnant counts.
+ *    A type 2-5 block that opens AND closes on its first line owns the
+ *    rest of that line as raw content too (`<!-- c --> tail`) — same seam.
  * 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).
+ *    the comment scan would skip real markup as comment interior), and
+ *    every point where CommonMark's terminator and parse5's tokenizer
+ *    DISAGREE about where a raw construct ends (`--!>` closes a comment
+ *    for parse5 only; a `<?…`/`<![CDATA[…` bogus comment ends at its
+ *    first `>` for parse5 but at `?>`/`]]>` for CommonMark; a paragraph-
+ *    inline `<?>` is open to micromark, closed to parse5) — the bytes in
+ *    between are raw text to one grammar and real markup to the other, and
+ *    the hast is parse5's. 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)
  *
@@ -353,6 +366,12 @@ interface FreezeScanCheckpoint {
     inMath: boolean;
     /** Opening dollar-run length while inMath — the close run must match it. */
     mathFenceLen: number;
+    /** Indent (0-3 spaces) of the line that opened the current fence/math
+     *  block. Not a blocker input — read by `phantomSuffixCloser` to emit a
+     *  closer at the SAME indent, which closes the block whether it sits at
+     *  top level (≤3 spaces are allowed there) or inside a list item whose
+     *  content indent the opener line already satisfies. */
+    openIndent: number;
     blankRun: number;
     lastBlankStart: number;
     /** Rolling blocker-3 verdict ("nearest decisive block start so far"). */
@@ -392,6 +411,10 @@ interface FreezeScanCheckpoint {
      *  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;
+    /** Tag names of line-truncated opens (`<div` at EOL) counted into
+     *  tagBalance but not yet confirmed by a later `>` — reverted at the next
+     *  blank line (a tag cannot span one). See TRUNCATED_TAG_RE. */
+    pendingTruncatedTags: string[];
 }
 declare function computeFreezeBoundary(text: string, options: FreezeBoundaryOptions, resume?: FreezeScanCheckpoint | null): FreezeScanResult;
 
@@ -687,6 +710,17 @@ interface DefLabelScanner {
  */
 declare function createDefLabelScanner(parse?: (source: string) => DefLabels): DefLabelScanner;
 
+/**
+ * The id fragment mdast-util-to-hast derives from a footnote identifier for
+ * `fn-…` / `fnref-…` (`normalizeUri(identifier.toLowerCase())` — percent-
+ * encodes non-ASCII, whitespace and URL-unsafe punctuation). Every place
+ * that MINTS a footnote id — the standalone footer (upstream), the
+ * cross-chunk marks and the aggregate footer — must use this same
+ * encoding, or a mark's `href` and its `<li id>` disagree (v2.4.0 review:
+ * the fallback mark wrote the raw label while the local footer was
+ * encoded; `[^注]` / `[^a%b]` anchors broke).
+ */
+declare function footnoteSafeId(identifier: string): string;
 /**
  * Extract the SOURCE identifier from a footnote `<li>` id, covering both id
  * shapes in the codebase — standalone (mdast-util-to-hast `fn-` +
@@ -1196,6 +1230,49 @@ interface PhantomLabels {
  * Labels are expected to already be normalized via normalizeId (uppercase).
  */
 declare function buildPhantomSuffix(phantoms: PhantomLabels): string;
+/**
+ * The bytes to put BETWEEN a chunk's content and its phantom suffix so the
+ * suffix's definition lines are parsed as definitions.
+ *
+ * `buildPhantomSuffix` is appended (never prepended: the incremental engine
+ * treats the suffix as an always-tail input, and prepending would shift
+ * every source position). But an append lands INSIDE whatever block the
+ * content ends in — and a fenced code block or `$$` flow-math block that is
+ * still open at the end of a streaming frame swallows everything up to EOF:
+ * the sentinel lines render as code/math text and, since no definition was
+ * registered, every cross-chunk reference in the chunk falls back to literal
+ * `[text][label]` for the whole time the block streams (2026-08 project
+ * review, core-render-01). Closing the block first is output-neutral: an
+ * unclosed fence/math block already renders exactly the lines it has, so
+ * `content + closer` yields the same code/math node value (positions
+ * extend past `content.length`, which every consumer already tolerates for
+ * the suffix's own nodes).
+ *
+ * A closer is emitted ONLY for a block whose opener line sits at column 0:
+ * that is provably a top-level fence, which only a top-level closer (same
+ * char, ≥ length, ≤3 spaces indent) can end — exactly what the line scanner
+ * tracks. Openers with any indent are left alone: the line model cannot
+ * see container boundaries, and an indented opener may live in a list item
+ * that later de-indented content already ended (micromark closed the fence
+ * with the item; an emitted closer would OPEN a new fence around the
+ * sentinel lines — v2.4.0 review R1) or be closed by a ≥4-space closer the
+ * `^ {0,3}` scan does not recognize. Those shapes keep the plain append
+ * (swallowed at worst — the pre-2.4.0 behaviour), never a wrong closer.
+ *
+ * Only fences and flow math are closed. Raw-HTML constructs (`<!--`, `<?`,
+ * `<![CDATA[`, `<!X`, `<script>`) that stay open to EOF also swallow the
+ * suffix (invisibly — sanitize strips them), but their closers are not
+ * position-neutral for the paragraph-inline forms and the shapes are rare
+ * in LLM output; they keep the plain-append behaviour. When the scanner's
+ * fence/math phase is untrusted (`phasePoisonedAt` — a suppressed open in a
+ * container, see computeFreezeBoundary blocker 7) no closer is emitted
+ * either: a wrong closer would OPEN a block around the suffix.
+ *
+ * Returns '' when nothing needs closing. Cost: one line scan of `content`
+ * (regex per line; no reference tracking) — only paid by chunks that have a
+ * non-empty phantom suffix.
+ */
+declare function phantomSuffixCloser(content: string): string;
 
 /**
  * Custom mdast-util-to-hast handlers for cross-chunk label resolution.
@@ -1343,19 +1420,6 @@ declare const defaultEnginePlugins: readonly AIMarkdownEnginePlugin[];
  */
 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.
@@ -1692,7 +1756,13 @@ interface SmoothStreamController {
     finish(): void;
     /** Jumps to `source` instantly, no animation, and clears any backlog. */
     snap(source: string): void;
-    /** Reveals everything pending right now (skip-animation affordance). */
+    /**
+     * Reveals everything pending right now (skip-animation affordance). Keeps
+     * the grapheme discipline: while the stream is not finished, the trailing
+     * grapheme of the source stays held back exactly as the animation would
+     * hold it (a surrogate half or a growing ZWJ sequence must never reach
+     * the parser); {@link finish} or the next {@link update} confirms it.
+     */
     flush(): void;
     /** Subscribes to visible-prefix changes. Returns the unsubscribe. */
     subscribe(listener: () => void): () => void;
@@ -1899,4 +1969,4 @@ type RemendPreprocessorOptions = Omit<RemendOptions, 'katex' | 'inlineKatex'>;
  */
 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, hasLoneSurrogate, highlight, isFootnoteSection, lastRegionStart, measureStage, mergeClassNameAllowlist, normalizeForMatch, normalizeId, pangu, parseStage, preprocessAIMDContent, preprocessLaTeX, rehypeFooterAdorn, rehypeRebaseHashLinks, removeComments, sanitizeCrossChunkUrl, sanitizeSchema, shortenDocumentId, smartypants, sourceIdFromFootnoteLiId, splitByProtectedRegions, subscribeStageTimings, transformStage, withDefs };
+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, footnoteSafeId, getEnginePluginInternals, hasLoneSurrogate, highlight, isFootnoteSection, lastRegionStart, measureStage, mergeClassNameAllowlist, normalizeForMatch, normalizeId, pangu, parseStage, phantomSuffixCloser, preprocessAIMDContent, preprocessLaTeX, rehypeFooterAdorn, rehypeRebaseHashLinks, removeComments, sanitizeCrossChunkUrl, sanitizeSchema, shortenDocumentId, smartypants, sourceIdFromFootnoteLiId, splitByProtectedRegions, subscribeStageTimings, transformStage, withDefs };

package/dist/index.d.ts

@@ -184,7 +184,10 @@ declare const defaultUrlTransform: UrlTransform;
  *    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.
+ *    (`<div` at EOL, attributes wrapping) count as opens. Closers that
+ *    OVERLAP their opener (`<!-->`, `<!--->`, line-start `<?>`) close on
+ *    the spot — CommonMark and parse5 agree — so the markup after them is
+ *    scanned, not skipped as construct interior.
  * 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
@@ -215,19 +218,29 @@ declare const defaultUrlTransform: UrlTransform;
  *    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).
+ *    reproduced on v1.8.0). Every candidate emitted while the remnant is
+ *    the last frozen child is rejected (they stay rejected for good); once
+ *    a later confirmed content line pins the seam from the frozen side,
+ *    the candidates AFTER that line are safe again. Dropping candidates
+ *    only over-blocks (safe direction). Whitespace-only remnant counts.
+ *    A type 2-5 block that opens AND closes on its first line owns the
+ *    rest of that line as raw content too (`<!-- c --> tail`) — same seam.
  * 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).
+ *    the comment scan would skip real markup as comment interior), and
+ *    every point where CommonMark's terminator and parse5's tokenizer
+ *    DISAGREE about where a raw construct ends (`--!>` closes a comment
+ *    for parse5 only; a `<?…`/`<![CDATA[…` bogus comment ends at its
+ *    first `>` for parse5 but at `?>`/`]]>` for CommonMark; a paragraph-
+ *    inline `<?>` is open to micromark, closed to parse5) — the bytes in
+ *    between are raw text to one grammar and real markup to the other, and
+ *    the hast is parse5's. 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)
  *
@@ -353,6 +366,12 @@ interface FreezeScanCheckpoint {
     inMath: boolean;
     /** Opening dollar-run length while inMath — the close run must match it. */
     mathFenceLen: number;
+    /** Indent (0-3 spaces) of the line that opened the current fence/math
+     *  block. Not a blocker input — read by `phantomSuffixCloser` to emit a
+     *  closer at the SAME indent, which closes the block whether it sits at
+     *  top level (≤3 spaces are allowed there) or inside a list item whose
+     *  content indent the opener line already satisfies. */
+    openIndent: number;
     blankRun: number;
     lastBlankStart: number;
     /** Rolling blocker-3 verdict ("nearest decisive block start so far"). */
@@ -392,6 +411,10 @@ interface FreezeScanCheckpoint {
      *  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;
+    /** Tag names of line-truncated opens (`<div` at EOL) counted into
+     *  tagBalance but not yet confirmed by a later `>` — reverted at the next
+     *  blank line (a tag cannot span one). See TRUNCATED_TAG_RE. */
+    pendingTruncatedTags: string[];
 }
 declare function computeFreezeBoundary(text: string, options: FreezeBoundaryOptions, resume?: FreezeScanCheckpoint | null): FreezeScanResult;
 
@@ -687,6 +710,17 @@ interface DefLabelScanner {
  */
 declare function createDefLabelScanner(parse?: (source: string) => DefLabels): DefLabelScanner;
 
+/**
+ * The id fragment mdast-util-to-hast derives from a footnote identifier for
+ * `fn-…` / `fnref-…` (`normalizeUri(identifier.toLowerCase())` — percent-
+ * encodes non-ASCII, whitespace and URL-unsafe punctuation). Every place
+ * that MINTS a footnote id — the standalone footer (upstream), the
+ * cross-chunk marks and the aggregate footer — must use this same
+ * encoding, or a mark's `href` and its `<li id>` disagree (v2.4.0 review:
+ * the fallback mark wrote the raw label while the local footer was
+ * encoded; `[^注]` / `[^a%b]` anchors broke).
+ */
+declare function footnoteSafeId(identifier: string): string;
 /**
  * Extract the SOURCE identifier from a footnote `<li>` id, covering both id
  * shapes in the codebase — standalone (mdast-util-to-hast `fn-` +
@@ -1196,6 +1230,49 @@ interface PhantomLabels {
  * Labels are expected to already be normalized via normalizeId (uppercase).
  */
 declare function buildPhantomSuffix(phantoms: PhantomLabels): string;
+/**
+ * The bytes to put BETWEEN a chunk's content and its phantom suffix so the
+ * suffix's definition lines are parsed as definitions.
+ *
+ * `buildPhantomSuffix` is appended (never prepended: the incremental engine
+ * treats the suffix as an always-tail input, and prepending would shift
+ * every source position). But an append lands INSIDE whatever block the
+ * content ends in — and a fenced code block or `$$` flow-math block that is
+ * still open at the end of a streaming frame swallows everything up to EOF:
+ * the sentinel lines render as code/math text and, since no definition was
+ * registered, every cross-chunk reference in the chunk falls back to literal
+ * `[text][label]` for the whole time the block streams (2026-08 project
+ * review, core-render-01). Closing the block first is output-neutral: an
+ * unclosed fence/math block already renders exactly the lines it has, so
+ * `content + closer` yields the same code/math node value (positions
+ * extend past `content.length`, which every consumer already tolerates for
+ * the suffix's own nodes).
+ *
+ * A closer is emitted ONLY for a block whose opener line sits at column 0:
+ * that is provably a top-level fence, which only a top-level closer (same
+ * char, ≥ length, ≤3 spaces indent) can end — exactly what the line scanner
+ * tracks. Openers with any indent are left alone: the line model cannot
+ * see container boundaries, and an indented opener may live in a list item
+ * that later de-indented content already ended (micromark closed the fence
+ * with the item; an emitted closer would OPEN a new fence around the
+ * sentinel lines — v2.4.0 review R1) or be closed by a ≥4-space closer the
+ * `^ {0,3}` scan does not recognize. Those shapes keep the plain append
+ * (swallowed at worst — the pre-2.4.0 behaviour), never a wrong closer.
+ *
+ * Only fences and flow math are closed. Raw-HTML constructs (`<!--`, `<?`,
+ * `<![CDATA[`, `<!X`, `<script>`) that stay open to EOF also swallow the
+ * suffix (invisibly — sanitize strips them), but their closers are not
+ * position-neutral for the paragraph-inline forms and the shapes are rare
+ * in LLM output; they keep the plain-append behaviour. When the scanner's
+ * fence/math phase is untrusted (`phasePoisonedAt` — a suppressed open in a
+ * container, see computeFreezeBoundary blocker 7) no closer is emitted
+ * either: a wrong closer would OPEN a block around the suffix.
+ *
+ * Returns '' when nothing needs closing. Cost: one line scan of `content`
+ * (regex per line; no reference tracking) — only paid by chunks that have a
+ * non-empty phantom suffix.
+ */
+declare function phantomSuffixCloser(content: string): string;
 
 /**
  * Custom mdast-util-to-hast handlers for cross-chunk label resolution.
@@ -1343,19 +1420,6 @@ declare const defaultEnginePlugins: readonly AIMarkdownEnginePlugin[];
  */
 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.
@@ -1692,7 +1756,13 @@ interface SmoothStreamController {
     finish(): void;
     /** Jumps to `source` instantly, no animation, and clears any backlog. */
     snap(source: string): void;
-    /** Reveals everything pending right now (skip-animation affordance). */
+    /**
+     * Reveals everything pending right now (skip-animation affordance). Keeps
+     * the grapheme discipline: while the stream is not finished, the trailing
+     * grapheme of the source stays held back exactly as the animation would
+     * hold it (a surrogate half or a growing ZWJ sequence must never reach
+     * the parser); {@link finish} or the next {@link update} confirms it.
+     */
     flush(): void;
     /** Subscribes to visible-prefix changes. Returns the unsubscribe. */
     subscribe(listener: () => void): () => void;
@@ -1899,4 +1969,4 @@ type RemendPreprocessorOptions = Omit<RemendOptions, 'katex' | 'inlineKatex'>;
  */
 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, hasLoneSurrogate, highlight, isFootnoteSection, lastRegionStart, measureStage, mergeClassNameAllowlist, normalizeForMatch, normalizeId, pangu, parseStage, preprocessAIMDContent, preprocessLaTeX, rehypeFooterAdorn, rehypeRebaseHashLinks, removeComments, sanitizeCrossChunkUrl, sanitizeSchema, shortenDocumentId, smartypants, sourceIdFromFootnoteLiId, splitByProtectedRegions, subscribeStageTimings, transformStage, withDefs };
+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, footnoteSafeId, getEnginePluginInternals, hasLoneSurrogate, highlight, isFootnoteSection, lastRegionStart, measureStage, mergeClassNameAllowlist, normalizeForMatch, normalizeId, pangu, parseStage, phantomSuffixCloser, preprocessAIMDContent, preprocessLaTeX, rehypeFooterAdorn, rehypeRebaseHashLinks, removeComments, sanitizeCrossChunkUrl, sanitizeSchema, shortenDocumentId, smartypants, sourceIdFromFootnoteLiId, splitByProtectedRegions, subscribeStageTimings, transformStage, withDefs };