@ai-react-markdown/engine 2.4.2 → 2.4.5

package/dist/index.d.cts

@@ -425,6 +425,49 @@ 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;
+    /** 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;
 }
 declare function computeFreezeBoundary(text: string, options: FreezeBoundaryOptions, resume?: FreezeScanCheckpoint | null): FreezeScanResult;
 
@@ -764,34 +807,6 @@ interface ExtractContributionsOptions {
      *  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>;
 
@@ -890,18 +905,15 @@ interface Registry {
     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.
+     * Resolve a cross-chunk link definition by label. The returned `url` is
+     * the RAW destination from the contributing chunk's source — the registry
+     * does not sanitize. The library's cross-chunk link/image placeholders run
+     * the full per-attribute sanitization (`sanitizeSchema.protocols` +
+     * `urlTransform`, correct key) at render time.
      *
      * 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>`.
+     * dev tooling) MUST run their own policy before rendering it as an
+     * `href`/`src` — a chunk can define `[evil]: javascript:alert(1)`.
      */
     resolveLinkDef(label: string): LinkDef | null;
     getRefsForLabel(label: string): number;
@@ -1692,7 +1704,11 @@ declare const sanitizeSchema: Schema;
  * 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.
+ * parser mid-cluster. `snap()` (a replacement, or the very first `update`)
+ * is outside this promise by design: it shows the whole replacement text
+ * at once, trailing half-cluster included — a hold-back there would leave
+ * a controller that never drains when nothing follows (v2.4.2 review
+ * P3-1). Hosts that seed a stream mid-cluster get one frame of U+FFFD.
  *
  * @module components/smoothStream/controller
  */
@@ -1776,7 +1792,8 @@ interface SmoothStreamController {
      * a later {@link update} resumes animation.
      */
     finish(): void;
-    /** Jumps to `source` instantly, no animation, and clears any backlog. */
+    /** Jumps to `source` instantly, no animation, and clears any backlog.
+     *  No trailing-grapheme hold-back (see the module docs). */
     snap(source: string): void;
     /**
      * Reveals everything pending right now (skip-animation affordance). Keeps
@@ -1890,7 +1907,12 @@ interface Segment {
  * 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.
+ *   line* (any indentation — container-relative limits are not modelled).
+ *   Mid-line runs are never fence openers. INDENTED code blocks (4+ spaces
+ *   after a blank line, outside any container) are NOT modelled: without a
+ *   container model they cannot be told from a list item's continuation
+ *   paragraph, and protecting them would silence math in nested lists.
+ *   Known limitation — `$` inside an indented code block may be rewritten.
  * - 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.
@@ -1923,6 +1945,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;
 
 /**

package/dist/index.d.ts

@@ -425,6 +425,49 @@ 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;
+    /** 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;
 }
 declare function computeFreezeBoundary(text: string, options: FreezeBoundaryOptions, resume?: FreezeScanCheckpoint | null): FreezeScanResult;
 
@@ -764,34 +807,6 @@ interface ExtractContributionsOptions {
      *  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>;
 
@@ -890,18 +905,15 @@ interface Registry {
     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.
+     * Resolve a cross-chunk link definition by label. The returned `url` is
+     * the RAW destination from the contributing chunk's source — the registry
+     * does not sanitize. The library's cross-chunk link/image placeholders run
+     * the full per-attribute sanitization (`sanitizeSchema.protocols` +
+     * `urlTransform`, correct key) at render time.
      *
      * 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>`.
+     * dev tooling) MUST run their own policy before rendering it as an
+     * `href`/`src` — a chunk can define `[evil]: javascript:alert(1)`.
      */
     resolveLinkDef(label: string): LinkDef | null;
     getRefsForLabel(label: string): number;
@@ -1692,7 +1704,11 @@ declare const sanitizeSchema: Schema;
  * 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.
+ * parser mid-cluster. `snap()` (a replacement, or the very first `update`)
+ * is outside this promise by design: it shows the whole replacement text
+ * at once, trailing half-cluster included — a hold-back there would leave
+ * a controller that never drains when nothing follows (v2.4.2 review
+ * P3-1). Hosts that seed a stream mid-cluster get one frame of U+FFFD.
  *
  * @module components/smoothStream/controller
  */
@@ -1776,7 +1792,8 @@ interface SmoothStreamController {
      * a later {@link update} resumes animation.
      */
     finish(): void;
-    /** Jumps to `source` instantly, no animation, and clears any backlog. */
+    /** Jumps to `source` instantly, no animation, and clears any backlog.
+     *  No trailing-grapheme hold-back (see the module docs). */
     snap(source: string): void;
     /**
      * Reveals everything pending right now (skip-animation affordance). Keeps
@@ -1890,7 +1907,12 @@ interface Segment {
  * 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.
+ *   line* (any indentation — container-relative limits are not modelled).
+ *   Mid-line runs are never fence openers. INDENTED code blocks (4+ spaces
+ *   after a blank line, outside any container) are NOT modelled: without a
+ *   container model they cannot be told from a list item's continuation
+ *   paragraph, and protecting them would silence math in nested lists.
+ *   Known limitation — `$` inside an indented code block may be rewritten.
  * - 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.
@@ -1923,6 +1945,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;
 
 /**