@ai-react-markdown/engine 2.4.1 → 2.4.3

package/dist/index.d.cts

@@ -384,6 +384,16 @@ interface FreezeScanCheckpoint {
     prevLineWasValidDef: boolean;
     /** An earlier line of the current paragraph left an unpaired backtick
      *  run — masking is disabled until the paragraph ends (safety gate). */
+    /** A `[` left unclosed at the end of a paragraph line (code spans
+     *  masked). micromark lets a reference label span soft line breaks, so
+     *  the label may close on a LATER line where the per-line REF_RE never
+     *  sees a `[…]` pair (v2.4.1 review P1: `see [foo\nbar] end` + a late
+     *  `[foo bar]: /u` retargeted frozen output). Cleared wherever the
+     *  paragraph ends. */
+    openBracket: {
+        offset: number;
+        text: string;
+    } | null;
     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
@@ -754,34 +764,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>;
 
@@ -850,10 +832,12 @@ interface ChunkData {
  * 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.
+ * `RegistryInternal` is exported from this engine package (the core
+ * renderer consumes it) but NOT from `@ai-react-markdown/core`'s public
+ * barrel — keeping mutators off the consumer-facing 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
@@ -878,18 +862,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;
@@ -906,9 +887,10 @@ interface Registry {
  * 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`
+ * Exported from this module (and the engine barrel) so internal
+ * coordinators (`MarkdownContent`) and tests can hold a strongly-typed
+ * reference, but **not** re-exported from `@ai-react-markdown/core`'s
+ * 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
@@ -1319,11 +1301,13 @@ declare function buildCrossChunkHandlers(): Handlers;
  * 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
+ *   1. `rehype-sanitize` `protocols.<attr>` allowlist — drops the attribute
  *      entirely if the URL's protocol isn't permitted for that attribute.
+ *      Runs in the rehype plugin chain.
+ *   2. `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; its
+ *      return value IS the attribute (`''` renders `href=""`).
  *
  * Cross-chunk references skip BOTH passes naturally: the placeholder hast
  * tag (`<cross-chunk-link>` / `<cross-chunk-image>`) carries only a `label`
@@ -1353,13 +1337,20 @@ declare function buildCrossChunkHandlers(): Handlers;
 type UrlAttrKey = 'href' | 'src';
 type UrlAttrTag = 'a' | 'img';
 /**
- * Run a cross-chunk-resolved URL through both standalone gates.
+ * Run a cross-chunk-resolved URL through both standalone gates, in the
+ * standalone ORDER: `rehype-sanitize`'s protocol allowlist runs in the
+ * plugin chain first (a blocked URL loses the attribute entirely), then
+ * `urlTransform` rewrites whatever survived during the hast visit pass (its
+ * return value is the attribute — `''` from `defaultUrlTransform` renders
+ * `href=""`, exactly like a legal empty destination `[x]: <>`).
  *
- * @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 `''`.
+ * @returns `null` when the protocol gate strips the attribute (render it
+ *   ABSENT); otherwise the transformed URL string — possibly `''`, which
+ *   the caller must render as `href=""` / `src=""` to stay byte-identical
+ *   with standalone (v2.4.1 review: the two used to collapse into `''` and
+ *   the placeholder omitted the attribute for `[x]: <>` too).
  */
-declare function sanitizeCrossChunkUrl(rawUrl: string, key: UrlAttrKey, tagName: UrlAttrTag, urlTransform: UrlTransform, schema: SanitizeSchema): string;
+declare function sanitizeCrossChunkUrl(rawUrl: string, key: UrlAttrKey, tagName: UrlAttrTag, urlTransform: UrlTransform, schema: SanitizeSchema): string | null;
 
 /**
  * The five shipped engine plugins and the default set.
@@ -1670,7 +1661,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
  */
@@ -1754,7 +1749,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
@@ -1868,7 +1864,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.

package/dist/index.d.ts

@@ -384,6 +384,16 @@ interface FreezeScanCheckpoint {
     prevLineWasValidDef: boolean;
     /** An earlier line of the current paragraph left an unpaired backtick
      *  run — masking is disabled until the paragraph ends (safety gate). */
+    /** A `[` left unclosed at the end of a paragraph line (code spans
+     *  masked). micromark lets a reference label span soft line breaks, so
+     *  the label may close on a LATER line where the per-line REF_RE never
+     *  sees a `[…]` pair (v2.4.1 review P1: `see [foo\nbar] end` + a late
+     *  `[foo bar]: /u` retargeted frozen output). Cleared wherever the
+     *  paragraph ends. */
+    openBracket: {
+        offset: number;
+        text: string;
+    } | null;
     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
@@ -754,34 +764,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>;
 
@@ -850,10 +832,12 @@ interface ChunkData {
  * 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.
+ * `RegistryInternal` is exported from this engine package (the core
+ * renderer consumes it) but NOT from `@ai-react-markdown/core`'s public
+ * barrel — keeping mutators off the consumer-facing 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
@@ -878,18 +862,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;
@@ -906,9 +887,10 @@ interface Registry {
  * 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`
+ * Exported from this module (and the engine barrel) so internal
+ * coordinators (`MarkdownContent`) and tests can hold a strongly-typed
+ * reference, but **not** re-exported from `@ai-react-markdown/core`'s
+ * 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
@@ -1319,11 +1301,13 @@ declare function buildCrossChunkHandlers(): Handlers;
  * 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
+ *   1. `rehype-sanitize` `protocols.<attr>` allowlist — drops the attribute
  *      entirely if the URL's protocol isn't permitted for that attribute.
+ *      Runs in the rehype plugin chain.
+ *   2. `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; its
+ *      return value IS the attribute (`''` renders `href=""`).
  *
  * Cross-chunk references skip BOTH passes naturally: the placeholder hast
  * tag (`<cross-chunk-link>` / `<cross-chunk-image>`) carries only a `label`
@@ -1353,13 +1337,20 @@ declare function buildCrossChunkHandlers(): Handlers;
 type UrlAttrKey = 'href' | 'src';
 type UrlAttrTag = 'a' | 'img';
 /**
- * Run a cross-chunk-resolved URL through both standalone gates.
+ * Run a cross-chunk-resolved URL through both standalone gates, in the
+ * standalone ORDER: `rehype-sanitize`'s protocol allowlist runs in the
+ * plugin chain first (a blocked URL loses the attribute entirely), then
+ * `urlTransform` rewrites whatever survived during the hast visit pass (its
+ * return value is the attribute — `''` from `defaultUrlTransform` renders
+ * `href=""`, exactly like a legal empty destination `[x]: <>`).
  *
- * @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 `''`.
+ * @returns `null` when the protocol gate strips the attribute (render it
+ *   ABSENT); otherwise the transformed URL string — possibly `''`, which
+ *   the caller must render as `href=""` / `src=""` to stay byte-identical
+ *   with standalone (v2.4.1 review: the two used to collapse into `''` and
+ *   the placeholder omitted the attribute for `[x]: <>` too).
  */
-declare function sanitizeCrossChunkUrl(rawUrl: string, key: UrlAttrKey, tagName: UrlAttrTag, urlTransform: UrlTransform, schema: SanitizeSchema): string;
+declare function sanitizeCrossChunkUrl(rawUrl: string, key: UrlAttrKey, tagName: UrlAttrTag, urlTransform: UrlTransform, schema: SanitizeSchema): string | null;
 
 /**
  * The five shipped engine plugins and the default set.
@@ -1670,7 +1661,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
  */
@@ -1754,7 +1749,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
@@ -1868,7 +1864,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.