@ai-react-markdown/engine 2.4.3 → 2.5.0

package/dist/index.d.cts

@@ -360,6 +360,16 @@ interface FreezeScanCheckpoint {
     piOpen: boolean;
     declOpen: boolean;
     cdataOpen: boolean;
+    /** parse5 BOGUS COMMENT open inside a real html-flow run: `<!` not
+     *  followed by `--` / letter / `[CDATA[`, or `</` not followed by a
+     *  letter (`<!\n`, `<!-`, `</\n`, `<//`) — eaten up to the next `>`;
+     *  a `</div>` inside is comment text, not a close (2026-08-19 review r2
+     *  P1-3: the balance zeroed past an open div). micromark has no such
+     *  construct: those bytes are just html-block content. */
+    bogusOpen: boolean;
+    /** The RAW_TEXT_ELEMENTS element currently open (its content is text to
+     *  parse5): tags and comment tokens are ignored until `</name>`. */
+    rawTextOpen: string | null;
     inFence: boolean;
     fenceChar: string;
     fenceLen: number;
@@ -425,7 +435,61 @@ interface FreezeScanCheckpoint {
      *  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[];
+    /** Line-truncated CLOSING tags (`</div` + EOL, no `>`) inside an html-flow
+     *  run, waiting for a `>` on a later line of the same run. Unlike opens
+     *  they are NOT counted up front: a close tag cannot carry attributes, so
+     *  `para </style` (prose to micromark, still-open element to parse5 —
+     *  RAWTEXT waits for the `>`) must not zero the balance (2026-08-19
+     *  review P1 — the boundary crossed an open `<style>`). Confirmed and
+     *  applied only when a later line of the run brings the `>` (parse5
+     *  completes the end tag; micromark's block ends at the blank anyway);
+     *  dropped unapplied at the blank (element stays counted — over-block).
+     *  Paragraph-context truncated closes are never pended: a `>` at block
+     *  indent on the next line is a blockquote to micromark, and the one
+     *  shape that would complete the inline close (`</b\n    >`, a 4+-space
+     *  lazy continuation) is not modelled — the element stays counted,
+     *  over-block. */
+    pendingTruncatedCloses: string[];
+    /** An html-flow line ended inside a tag (`<div`, `</div`, `<br` — open,
+     *  close or void, with or without attributes): parse5's tokenizer is
+     *  still in that tag, so on the following lines everything up to the
+     *  FIRST `>` is attribute garbage — `</div>` there does NOT close
+     *  anything (oracle review of 2.4.4: `<div>\n<div>\n</div\n</div>` froze
+     *  past the still-open outer div; pre-existing, 1-char slices). While
+     *  set: a line without `>` gets no tag scan at all; the line with the
+     *  `>` completes the pending close (if any), then only its text after
+     *  that `>` is scanned. Cleared there and at the blank line. */
+    tagAcrossLines: boolean;
+    /** Indent of the line that set `tagAcrossLines`. A following line that
+     *  DE-INDENTS below it may have left the container (a list item's html
+     *  block ends there; hast-util-raw resets the tokenizer at the li/ul
+     *  boundary, so a `<div>` on that line is a real start tag, not garbage)
+     *  — or may still be the same html block (root-level `  </div\n</div>`,
+     *  still garbage). Unknowable here → poison (oracle 3rd pass). */
+    tagAcrossLinesIndent: number;
+    /** parse5's position inside that tag's attribute area at the end of the
+     *  last scanned line (see TagAttrState). A quoted value left open swallows
+     *  `>` and line endings; a `>` that arrives while `outside` ends the tag. */
+    tagAcrossLinesState: TagAttrState;
+    /** The html-flow run since the last blank REALLY started as a micromark
+     *  html block (type 6 / type 1 / a paragraph-not-interrupting type 7) —
+     *  as opposed to `htmlFlowSinceBlank`, which any `<tag` / `</tag` line
+     *  start sets (over-approximation, fine for its over-blocking uses). Only
+     *  in a real run are the bytes raw to parse5 across line endings; the
+     *  cross-line-tag garbage model (`tagAcrossLines`, pended closes) is
+     *  gated on it — in a paragraph starting `</i` the next line's `<div>` /
+     *  `<!--` are REAL blocks (oracle re-check of 2.4.4: gating on
+     *  htmlFlowSinceBlank swallowed them — a new under-block). Sticky to the
+     *  blank; a type 6/1 start on a later line of a non-real run promotes it. */
+    htmlFlowReal: boolean;
 }
+/** parse5 tokenizer position inside a tag's attribute area, tracked across
+ *  line endings for `tagAcrossLines` (2026-08-19 review r2 P1-2 / P2-3):
+ *  `outside` = before/in an attribute name (a `"` here starts a NAME, not a
+ *  value); `afterEq` = just past `=`; `unquoted` = in an unquoted value
+ *  (whitespace ends it); `"` / `'` = inside a quoted value — `>` and line
+ *  endings are value bytes there, only the matching quote leaves it. */
+type TagAttrState = 'outside' | 'afterEq' | 'unquoted' | '"' | "'";
 declare function computeFreezeBoundary(text: string, options: FreezeBoundaryOptions, resume?: FreezeScanCheckpoint | null): FreezeScanResult;
 
 /**
@@ -649,38 +713,6 @@ interface DefLabels {
     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
@@ -906,8 +938,18 @@ interface RegistryInternal extends Registry {
      *  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;
+    registerChunk(reactId: string, footnotes: Set<string>, links: Set<string>, documentIndex?: number): symbol;
+    /** `documentIndex` — the chunk's position in the DOCUMENT (not its mount
+     *  order). Without it a chunk joins `chunkOrder` at the end, which is
+     *  wrong for any list that unmounts and remounts chunks: a virtualized
+     *  transcript scrolling back re-registers an earlier chunk after the ones
+     *  still mounted, and footnote numbering plus "which chunk renders the
+     *  aggregate footer" follow that order (2026-08-19 review r2 P2-10).
+     *  Chunks that supply an index are kept sorted by it; chunks without one
+     *  keep mount order after them. */
+    allocateSymbol(reactId: string, documentIndex?: number): symbol;
+    /** @internal Insert a chunk Symbol at its document position. */
+    _placeChunk(sym: symbol, documentIndex?: number): void;
     releaseSymbol(reactId: string): void;
     contributeLabels(symbol: symbol, footnotes: Set<string>, links: Set<string>): void;
     contributeChunkData(symbol: symbol, data: ChunkData): void;
@@ -915,6 +957,8 @@ interface RegistryInternal extends Registry {
         symbol: symbol;
         refcount: number;
     }>;
+    /** Symbol → the `documentIndex` its chunk supplied (see allocateSymbol). */
+    _chunkIndex: Map<symbol, number>;
     _subscribers: Set<() => void>;
     _notifyScheduled: boolean;
     _notify(): void;
@@ -1019,6 +1063,12 @@ type SanitizeSchema = typeof defaultSchema;
  *   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.
+ * - **Widening is total.** Adding a tag to `tagNames` admits that element
+ *   with ALL of its semantics — `script`, `iframe`, `style`, `object`,
+ *   `form`, `base` re-enter the tree verbatim, and the two-gate URL story
+ *   in the README / SECURITY.md no longer describes your renderer. Prefer
+ *   allowing an attribute or a protocol over allowing an element; treat
+ *   any element you add as trusted input.
  *
  * @param modifier - Receives a deep clone of the library default. Mutate it
  *   freely; either return the (possibly different) result, or return
@@ -1413,10 +1463,16 @@ declare function isFootnoteSection(node: Element): boolean;
 
 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.
+ * The form of raw chunk SOURCE that the PASS 0.5 substring pre-check compares
+ * registry labels against. It is exactly {@link normalizeId}: micromark's
+ * `identifier` (what the registry keys are built from) is the label's
+ * source bytes with backslashes KEPT (`[^a\*b]` → `a\*b`; only the `label`
+ * field is unescaped), so the source must NOT be unescaped before matching
+ * — an unescaping pass made every label holding an escaped punctuation
+ * character miss the pre-check for good, and the cross-chunk reference
+ * rendered as literal `[text][label]` (2026-08-19 review r2 P2-5; the
+ * 2.4.5 narrowing to ASCII punctuation kept the wrong premise). Kept as a
+ * named export for API stability.
  */
 declare function normalizeForMatch(s: string): string;
 
@@ -1604,25 +1660,6 @@ type AttributeEntry = NonNullable<NonNullable<Schema['attributes']>[string]>[num
  *   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;
 
 /**
@@ -1902,6 +1939,20 @@ declare function preprocessLaTeX(str: string): string;
  */
 declare function createIncrementalLatexPreprocessor(options?: {
     freezeThreshold?: number;
+    /** Failure backoff (default on). Tests that rely on `freezeThreshold: 0`
+     *  to attempt a freeze on EVERY call turn it off, so 1-char chunkings keep
+     *  exercising the cut rules instead of skipping most attempts; backoff
+     *  can only freeze LESS, so passing without it implies passing with it.
+     *  @internal */
+    backoff?: boolean;
+    /** Test hook: called once per freeze ATTEMPT (a scan of the active
+     *  region) with the region's length and how many source bytes the
+     *  attempt froze (0 = failed), so the backoff bound and freeze progress
+     *  can be pinned. @internal */
+    onAttempt?: (info: {
+        activeLength: number;
+        frozenBytes: number;
+    }) => void;
 }): (content: string) => string;
 
 /**
@@ -1970,4 +2021,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, 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 };
+export { type AIMDContentPreprocessor, type AIMarkdownEnginePlugin, type AIMarkdownEnginePluginName, type AdvanceOptions, type AdvanceResult, type AllowElement, type ChunkData, type Contribution, type CrossChunkHandlerOptions, DEFAULT_PAYLOAD, 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, 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

@@ -360,6 +360,16 @@ interface FreezeScanCheckpoint {
     piOpen: boolean;
     declOpen: boolean;
     cdataOpen: boolean;
+    /** parse5 BOGUS COMMENT open inside a real html-flow run: `<!` not
+     *  followed by `--` / letter / `[CDATA[`, or `</` not followed by a
+     *  letter (`<!\n`, `<!-`, `</\n`, `<//`) — eaten up to the next `>`;
+     *  a `</div>` inside is comment text, not a close (2026-08-19 review r2
+     *  P1-3: the balance zeroed past an open div). micromark has no such
+     *  construct: those bytes are just html-block content. */
+    bogusOpen: boolean;
+    /** The RAW_TEXT_ELEMENTS element currently open (its content is text to
+     *  parse5): tags and comment tokens are ignored until `</name>`. */
+    rawTextOpen: string | null;
     inFence: boolean;
     fenceChar: string;
     fenceLen: number;
@@ -425,7 +435,61 @@ interface FreezeScanCheckpoint {
      *  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[];
+    /** Line-truncated CLOSING tags (`</div` + EOL, no `>`) inside an html-flow
+     *  run, waiting for a `>` on a later line of the same run. Unlike opens
+     *  they are NOT counted up front: a close tag cannot carry attributes, so
+     *  `para </style` (prose to micromark, still-open element to parse5 —
+     *  RAWTEXT waits for the `>`) must not zero the balance (2026-08-19
+     *  review P1 — the boundary crossed an open `<style>`). Confirmed and
+     *  applied only when a later line of the run brings the `>` (parse5
+     *  completes the end tag; micromark's block ends at the blank anyway);
+     *  dropped unapplied at the blank (element stays counted — over-block).
+     *  Paragraph-context truncated closes are never pended: a `>` at block
+     *  indent on the next line is a blockquote to micromark, and the one
+     *  shape that would complete the inline close (`</b\n    >`, a 4+-space
+     *  lazy continuation) is not modelled — the element stays counted,
+     *  over-block. */
+    pendingTruncatedCloses: string[];
+    /** An html-flow line ended inside a tag (`<div`, `</div`, `<br` — open,
+     *  close or void, with or without attributes): parse5's tokenizer is
+     *  still in that tag, so on the following lines everything up to the
+     *  FIRST `>` is attribute garbage — `</div>` there does NOT close
+     *  anything (oracle review of 2.4.4: `<div>\n<div>\n</div\n</div>` froze
+     *  past the still-open outer div; pre-existing, 1-char slices). While
+     *  set: a line without `>` gets no tag scan at all; the line with the
+     *  `>` completes the pending close (if any), then only its text after
+     *  that `>` is scanned. Cleared there and at the blank line. */
+    tagAcrossLines: boolean;
+    /** Indent of the line that set `tagAcrossLines`. A following line that
+     *  DE-INDENTS below it may have left the container (a list item's html
+     *  block ends there; hast-util-raw resets the tokenizer at the li/ul
+     *  boundary, so a `<div>` on that line is a real start tag, not garbage)
+     *  — or may still be the same html block (root-level `  </div\n</div>`,
+     *  still garbage). Unknowable here → poison (oracle 3rd pass). */
+    tagAcrossLinesIndent: number;
+    /** parse5's position inside that tag's attribute area at the end of the
+     *  last scanned line (see TagAttrState). A quoted value left open swallows
+     *  `>` and line endings; a `>` that arrives while `outside` ends the tag. */
+    tagAcrossLinesState: TagAttrState;
+    /** The html-flow run since the last blank REALLY started as a micromark
+     *  html block (type 6 / type 1 / a paragraph-not-interrupting type 7) —
+     *  as opposed to `htmlFlowSinceBlank`, which any `<tag` / `</tag` line
+     *  start sets (over-approximation, fine for its over-blocking uses). Only
+     *  in a real run are the bytes raw to parse5 across line endings; the
+     *  cross-line-tag garbage model (`tagAcrossLines`, pended closes) is
+     *  gated on it — in a paragraph starting `</i` the next line's `<div>` /
+     *  `<!--` are REAL blocks (oracle re-check of 2.4.4: gating on
+     *  htmlFlowSinceBlank swallowed them — a new under-block). Sticky to the
+     *  blank; a type 6/1 start on a later line of a non-real run promotes it. */
+    htmlFlowReal: boolean;
 }
+/** parse5 tokenizer position inside a tag's attribute area, tracked across
+ *  line endings for `tagAcrossLines` (2026-08-19 review r2 P1-2 / P2-3):
+ *  `outside` = before/in an attribute name (a `"` here starts a NAME, not a
+ *  value); `afterEq` = just past `=`; `unquoted` = in an unquoted value
+ *  (whitespace ends it); `"` / `'` = inside a quoted value — `>` and line
+ *  endings are value bytes there, only the matching quote leaves it. */
+type TagAttrState = 'outside' | 'afterEq' | 'unquoted' | '"' | "'";
 declare function computeFreezeBoundary(text: string, options: FreezeBoundaryOptions, resume?: FreezeScanCheckpoint | null): FreezeScanResult;
 
 /**
@@ -649,38 +713,6 @@ interface DefLabels {
     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
@@ -906,8 +938,18 @@ interface RegistryInternal extends Registry {
      *  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;
+    registerChunk(reactId: string, footnotes: Set<string>, links: Set<string>, documentIndex?: number): symbol;
+    /** `documentIndex` — the chunk's position in the DOCUMENT (not its mount
+     *  order). Without it a chunk joins `chunkOrder` at the end, which is
+     *  wrong for any list that unmounts and remounts chunks: a virtualized
+     *  transcript scrolling back re-registers an earlier chunk after the ones
+     *  still mounted, and footnote numbering plus "which chunk renders the
+     *  aggregate footer" follow that order (2026-08-19 review r2 P2-10).
+     *  Chunks that supply an index are kept sorted by it; chunks without one
+     *  keep mount order after them. */
+    allocateSymbol(reactId: string, documentIndex?: number): symbol;
+    /** @internal Insert a chunk Symbol at its document position. */
+    _placeChunk(sym: symbol, documentIndex?: number): void;
     releaseSymbol(reactId: string): void;
     contributeLabels(symbol: symbol, footnotes: Set<string>, links: Set<string>): void;
     contributeChunkData(symbol: symbol, data: ChunkData): void;
@@ -915,6 +957,8 @@ interface RegistryInternal extends Registry {
         symbol: symbol;
         refcount: number;
     }>;
+    /** Symbol → the `documentIndex` its chunk supplied (see allocateSymbol). */
+    _chunkIndex: Map<symbol, number>;
     _subscribers: Set<() => void>;
     _notifyScheduled: boolean;
     _notify(): void;
@@ -1019,6 +1063,12 @@ type SanitizeSchema = typeof defaultSchema;
  *   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.
+ * - **Widening is total.** Adding a tag to `tagNames` admits that element
+ *   with ALL of its semantics — `script`, `iframe`, `style`, `object`,
+ *   `form`, `base` re-enter the tree verbatim, and the two-gate URL story
+ *   in the README / SECURITY.md no longer describes your renderer. Prefer
+ *   allowing an attribute or a protocol over allowing an element; treat
+ *   any element you add as trusted input.
  *
  * @param modifier - Receives a deep clone of the library default. Mutate it
  *   freely; either return the (possibly different) result, or return
@@ -1413,10 +1463,16 @@ declare function isFootnoteSection(node: Element): boolean;
 
 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.
+ * The form of raw chunk SOURCE that the PASS 0.5 substring pre-check compares
+ * registry labels against. It is exactly {@link normalizeId}: micromark's
+ * `identifier` (what the registry keys are built from) is the label's
+ * source bytes with backslashes KEPT (`[^a\*b]` → `a\*b`; only the `label`
+ * field is unescaped), so the source must NOT be unescaped before matching
+ * — an unescaping pass made every label holding an escaped punctuation
+ * character miss the pre-check for good, and the cross-chunk reference
+ * rendered as literal `[text][label]` (2026-08-19 review r2 P2-5; the
+ * 2.4.5 narrowing to ASCII punctuation kept the wrong premise). Kept as a
+ * named export for API stability.
  */
 declare function normalizeForMatch(s: string): string;
 
@@ -1604,25 +1660,6 @@ type AttributeEntry = NonNullable<NonNullable<Schema['attributes']>[string]>[num
  *   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;
 
 /**
@@ -1902,6 +1939,20 @@ declare function preprocessLaTeX(str: string): string;
  */
 declare function createIncrementalLatexPreprocessor(options?: {
     freezeThreshold?: number;
+    /** Failure backoff (default on). Tests that rely on `freezeThreshold: 0`
+     *  to attempt a freeze on EVERY call turn it off, so 1-char chunkings keep
+     *  exercising the cut rules instead of skipping most attempts; backoff
+     *  can only freeze LESS, so passing without it implies passing with it.
+     *  @internal */
+    backoff?: boolean;
+    /** Test hook: called once per freeze ATTEMPT (a scan of the active
+     *  region) with the region's length and how many source bytes the
+     *  attempt froze (0 = failed), so the backoff bound and freeze progress
+     *  can be pinned. @internal */
+    onAttempt?: (info: {
+        activeLength: number;
+        frozenBytes: number;
+    }) => void;
 }): (content: string) => string;
 
 /**
@@ -1970,4 +2021,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, 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 };
+export { type AIMDContentPreprocessor, type AIMarkdownEnginePlugin, type AIMarkdownEnginePluginName, type AdvanceOptions, type AdvanceResult, type AllowElement, type ChunkData, type Contribution, type CrossChunkHandlerOptions, DEFAULT_PAYLOAD, 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, measureStage, mergeClassNameAllowlist, normalizeForMatch, normalizeId, pangu, parseStage, phantomSuffixCloser, preprocessAIMDContent, preprocessLaTeX, rehypeFooterAdorn, rehypeRebaseHashLinks, removeComments, sanitizeCrossChunkUrl, sanitizeSchema, shortenDocumentId, smartypants, sourceIdFromFootnoteLiId, splitByProtectedRegions, subscribeStageTimings, transformStage, withDefs };