@ai-react-markdown/core 1.4.5 → 1.4.7

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { JSX, ComponentType, PropsWithChildren, CSSProperties, FC } from 'react';
 import { Element, ElementContent } from 'hast';
 import { defaultSchema } from 'rehype-sanitize';
@@ -238,6 +238,27 @@ interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkd
      * always win.
      */
     documentId: string;
+    /**
+     * Whether {@link documentId} was EXPLICITLY supplied by the consumer (vs.
+     * auto-generated via `useId()`). This is the coordination signal — NOT
+     * `documentId` truthiness, which is always `true` because the provider
+     * auto-fills a fallback id for HTML/`clobberPrefix` purposes.
+     *
+     * `useDocumentRegistry` gates on this: an auto-generated id is unique by
+     * construction, so a chunk that didn't receive a `documentId` has nothing
+     * to coordinate with even when it sits inside `<AIMarkdownDocuments>`. It
+     * must take the standalone (registry === null) path, and this flag is the
+     * only thing that lets the registry hook tell "consumer wants coordination"
+     * apart from "we fabricated an id so the markup stays valid".
+     *
+     * Optional in the type ONLY so external callers that construct an
+     * `AIMarkdownRenderState` literal directly (mocks, fixtures) aren't broken
+     * by this internally-added field — the provider ALWAYS sets a concrete
+     * boolean, and internal consumers coerce a missing value to `false`
+     * (safe default: no coordination). Keeping it `?:` preserves source-level
+     * backward compatibility for the publicly-exported state type.
+     */
+    documentIdExplicit?: boolean;
     /**
      * Per-document URI-safe id prefix used by all clobberable attributes
      * (`id="…"` / `href="#…"`). Derived once by the provider and exposed here
@@ -818,8 +839,10 @@ type SanitizeSchema = typeof defaultSchema;
  * });
  * ```
  *
- * @remarks Allowing a protocol on `protocols.href` lets the URL through the
- * SECOND sanitize gate. The FIRST gate (`urlTransform`) must permit the
+ * @remarks Allowing a protocol on `protocols.href` lets the URL through
+ * Gate 1 (the schema-level per-protocol allowlist, which runs inside the
+ * rehype plugin chain). Gate 2 (`urlTransform`, the per-attribute rewriter
+ * that runs later at render time in `renderHastSubtree`) must permit the
  * same protocol independently — see the `urlTransform` prop on
  * `<AIMarkdown>` and the exported {@link defaultUrlTransform} for
  * composition. Keep the two protocol lists in sync.
@@ -1022,11 +1045,23 @@ declare const AIMarkdownDocuments: FC<AIMarkdownDocumentsProps>;
 /**
  * Returns the registry for the given `documentId`, or `null` if:
  *  - `<AIMarkdown>` is not inside an `<AIMarkdownDocuments>` wrapper, OR
- *  - `documentId` is undefined / empty string.
+ *  - `documentId` is undefined / empty string, OR
+ *  - `documentIdExplicit` is `false` — i.e. the id was auto-generated rather
+ *    than supplied by the consumer.
+ *
+ * The `documentIdExplicit` gate is the crux of the standalone-vs-coordinated
+ * decision. An auto-generated id (`useId()` fallback) is non-empty and unique
+ * by construction, so a chunk carrying one has nothing to coordinate with even
+ * inside the wrapper — it must run standalone. Without this gate, the mere
+ * presence of `<AIMarkdownDocuments>` would drag every uncoordinated chunk
+ * onto the cross-chunk registry path (subscribe / allocate / evict overhead)
+ * for no behavioral gain. The flag defaults to `true` so external callers who
+ * pass an id directly are treated as explicit (passing an id IS the intent to
+ * coordinate); the internal renderer threads through `state.documentIdExplicit`.
  *
  * Callers should treat `null` as "no coordination; run standalone path."
  */
-declare function useDocumentRegistry(documentId: string | undefined): Registry | null;
+declare function useDocumentRegistry(documentId: string | undefined, documentIdExplicit?: boolean): Registry | null;
 
 /**
  * Props for the `<AIMarkdown>` component.
@@ -1099,10 +1134,14 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      */
     documentId?: string;
     /**
-     * Override the function that decides which URL protocols are allowed
-     * through the FIRST sanitization gate. The default allowlist mirrors
-     * `react-markdown` / GitHub: `http`, `https`, `irc`, `ircs`, `mailto`,
-     * `xmpp`. Anything else is rewritten to `''`.
+     * Override the per-attribute URL rewriter (Gate 2 of the two-gate model).
+     * Runs at render time during the hast traversal in `renderHastSubtree`,
+     * after Gate 1 (`rehype-sanitize` schema) has already filtered URLs by
+     * protocol allowlist in the rehype plugin chain.
+     *
+     * The default allowlist mirrors `react-markdown` / GitHub: `http`,
+     * `https`, `irc`, `ircs`, `mailto`, `xmpp`. Anything else is rewritten
+     * to `''`.
      *
      * **Recommended pattern**: compose with the exported
      * {@link defaultUrlTransform} so the built-in XSS protections survive,
@@ -1131,13 +1170,13 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      * as a dependency. Defining the function inline (`urlTransform={(url) =>
      * …}`) creates a new closure on every parent render, discards the cache
      * for the entire markdown document on each render, and effectively
-     * disables Phase 5 memoization. In development the library will
+     * disables block-level memoization. In development the library will
      * `console.warn` if it detects this pattern.
      *
      * Allowing a protocol here is necessary but **not sufficient** to render
-     * a link — the second gate (`rehype-sanitize`) also enforces its own
-     * protocol allowlist. See the `sanitizeSchema` prop on this component
-     * and the {@link extendSanitizeSchema} helper for the second gate.
+     * a link — Gate 1 (`rehype-sanitize` schema) also enforces its own
+     * protocol allowlist and runs first. See the `sanitizeSchema` prop on
+     * this component and the {@link extendSanitizeSchema} helper for Gate 1.
      *
      * **API stability**: the `UrlTransform` type tracks the upstream
      * `react-markdown` shape and may change with its major versions.
@@ -1146,10 +1185,13 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
     /**
      * Override the `rehype-sanitize` schema applied to the rendered output.
      * The library default extends `rehype-sanitize`'s own `defaultSchema`
-     * with the `<mark>` tag, KaTeX class names, and the cross-chunk
-     * coordination tags (`cross-chunk-link`, `cross-chunk-image`,
-     * `footnote-sup`). The default is not exported as a value — see
-     * {@link extendSanitizeSchema} for how to inspect or extend it safely.
+     * with the `<mark>` tag, the `math-inline` / `math-display` className
+     * markers `remark-math` emits on `<code>` (KaTeX's own output classes
+     * survive separately because `rehype-katex` runs after `rehype-sanitize`),
+     * and the cross-chunk coordination tags (`cross-chunk-link`,
+     * `cross-chunk-image`, `footnote-sup`). The default is not exported as a
+     * value — see {@link extendSanitizeSchema} for how to inspect or extend
+     * it safely.
      *
      * **Recommended pattern**: build the schema with {@link extendSanitizeSchema}
      * (mutate-and-return form) so those library additions stay intact, and
@@ -1189,7 +1231,7 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
  * Root component that preprocesses markdown content and renders it through
  * a configurable remark/rehype pipeline wrapped in typography and style layers.
  */
-declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, defaultConfig, config, metadata, Typography, ExtraStyles, variant, colorScheme, documentId, urlTransform, sanitizeSchema, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_runtime.JSX.Element;
+declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, defaultConfig, config, metadata, Typography, ExtraStyles, variant, colorScheme, documentId, urlTransform, sanitizeSchema, }: AIMarkdownProps<TConfig, TRenderData>) => react.JSX.Element;
 declare const _default: typeof AIMarkdownComponent;
 
 export { type AIMDContentPreprocessor, type AIMarkdownColorScheme, type AIMarkdownCustomComponents, AIMarkdownDocuments, type AIMarkdownDocumentsProps, type AIMarkdownExtraStylesComponent, type AIMarkdownExtraStylesProps, type AIMarkdownMetadata, type AIMarkdownProps, type AIMarkdownRenderConfig, AIMarkdownRenderDisplayOptimizeAbility, AIMarkdownRenderExtraSyntax, type AIMarkdownRenderState, type AIMarkdownTypographyComponent, type AIMarkdownTypographyProps, type AIMarkdownVariant, type ChunkData, type FootnoteDef, type LinkDef, type PartialDeep, type RefKind, type RefRecord, type Registry, type SanitizeSchema, type UrlTransform, _default as default, defaultAIMarkdownRenderConfig, defaultUrlTransform, extendSanitizeSchema, useAIMarkdownMetadata, useAIMarkdownRenderState, useDocumentRegistry, useStableValue };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { JSX, ComponentType, PropsWithChildren, CSSProperties, FC } from 'react';
 import { Element, ElementContent } from 'hast';
 import { defaultSchema } from 'rehype-sanitize';
@@ -238,6 +238,27 @@ interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkd
      * always win.
      */
     documentId: string;
+    /**
+     * Whether {@link documentId} was EXPLICITLY supplied by the consumer (vs.
+     * auto-generated via `useId()`). This is the coordination signal — NOT
+     * `documentId` truthiness, which is always `true` because the provider
+     * auto-fills a fallback id for HTML/`clobberPrefix` purposes.
+     *
+     * `useDocumentRegistry` gates on this: an auto-generated id is unique by
+     * construction, so a chunk that didn't receive a `documentId` has nothing
+     * to coordinate with even when it sits inside `<AIMarkdownDocuments>`. It
+     * must take the standalone (registry === null) path, and this flag is the
+     * only thing that lets the registry hook tell "consumer wants coordination"
+     * apart from "we fabricated an id so the markup stays valid".
+     *
+     * Optional in the type ONLY so external callers that construct an
+     * `AIMarkdownRenderState` literal directly (mocks, fixtures) aren't broken
+     * by this internally-added field — the provider ALWAYS sets a concrete
+     * boolean, and internal consumers coerce a missing value to `false`
+     * (safe default: no coordination). Keeping it `?:` preserves source-level
+     * backward compatibility for the publicly-exported state type.
+     */
+    documentIdExplicit?: boolean;
     /**
      * Per-document URI-safe id prefix used by all clobberable attributes
      * (`id="…"` / `href="#…"`). Derived once by the provider and exposed here
@@ -818,8 +839,10 @@ type SanitizeSchema = typeof defaultSchema;
  * });
  * ```
  *
- * @remarks Allowing a protocol on `protocols.href` lets the URL through the
- * SECOND sanitize gate. The FIRST gate (`urlTransform`) must permit the
+ * @remarks Allowing a protocol on `protocols.href` lets the URL through
+ * Gate 1 (the schema-level per-protocol allowlist, which runs inside the
+ * rehype plugin chain). Gate 2 (`urlTransform`, the per-attribute rewriter
+ * that runs later at render time in `renderHastSubtree`) must permit the
  * same protocol independently — see the `urlTransform` prop on
  * `<AIMarkdown>` and the exported {@link defaultUrlTransform} for
  * composition. Keep the two protocol lists in sync.
@@ -1022,11 +1045,23 @@ declare const AIMarkdownDocuments: FC<AIMarkdownDocumentsProps>;
 /**
  * Returns the registry for the given `documentId`, or `null` if:
  *  - `<AIMarkdown>` is not inside an `<AIMarkdownDocuments>` wrapper, OR
- *  - `documentId` is undefined / empty string.
+ *  - `documentId` is undefined / empty string, OR
+ *  - `documentIdExplicit` is `false` — i.e. the id was auto-generated rather
+ *    than supplied by the consumer.
+ *
+ * The `documentIdExplicit` gate is the crux of the standalone-vs-coordinated
+ * decision. An auto-generated id (`useId()` fallback) is non-empty and unique
+ * by construction, so a chunk carrying one has nothing to coordinate with even
+ * inside the wrapper — it must run standalone. Without this gate, the mere
+ * presence of `<AIMarkdownDocuments>` would drag every uncoordinated chunk
+ * onto the cross-chunk registry path (subscribe / allocate / evict overhead)
+ * for no behavioral gain. The flag defaults to `true` so external callers who
+ * pass an id directly are treated as explicit (passing an id IS the intent to
+ * coordinate); the internal renderer threads through `state.documentIdExplicit`.
  *
  * Callers should treat `null` as "no coordination; run standalone path."
  */
-declare function useDocumentRegistry(documentId: string | undefined): Registry | null;
+declare function useDocumentRegistry(documentId: string | undefined, documentIdExplicit?: boolean): Registry | null;
 
 /**
  * Props for the `<AIMarkdown>` component.
@@ -1099,10 +1134,14 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      */
     documentId?: string;
     /**
-     * Override the function that decides which URL protocols are allowed
-     * through the FIRST sanitization gate. The default allowlist mirrors
-     * `react-markdown` / GitHub: `http`, `https`, `irc`, `ircs`, `mailto`,
-     * `xmpp`. Anything else is rewritten to `''`.
+     * Override the per-attribute URL rewriter (Gate 2 of the two-gate model).
+     * Runs at render time during the hast traversal in `renderHastSubtree`,
+     * after Gate 1 (`rehype-sanitize` schema) has already filtered URLs by
+     * protocol allowlist in the rehype plugin chain.
+     *
+     * The default allowlist mirrors `react-markdown` / GitHub: `http`,
+     * `https`, `irc`, `ircs`, `mailto`, `xmpp`. Anything else is rewritten
+     * to `''`.
      *
      * **Recommended pattern**: compose with the exported
      * {@link defaultUrlTransform} so the built-in XSS protections survive,
@@ -1131,13 +1170,13 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      * as a dependency. Defining the function inline (`urlTransform={(url) =>
      * …}`) creates a new closure on every parent render, discards the cache
      * for the entire markdown document on each render, and effectively
-     * disables Phase 5 memoization. In development the library will
+     * disables block-level memoization. In development the library will
      * `console.warn` if it detects this pattern.
      *
      * Allowing a protocol here is necessary but **not sufficient** to render
-     * a link — the second gate (`rehype-sanitize`) also enforces its own
-     * protocol allowlist. See the `sanitizeSchema` prop on this component
-     * and the {@link extendSanitizeSchema} helper for the second gate.
+     * a link — Gate 1 (`rehype-sanitize` schema) also enforces its own
+     * protocol allowlist and runs first. See the `sanitizeSchema` prop on
+     * this component and the {@link extendSanitizeSchema} helper for Gate 1.
      *
      * **API stability**: the `UrlTransform` type tracks the upstream
      * `react-markdown` shape and may change with its major versions.
@@ -1146,10 +1185,13 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
     /**
      * Override the `rehype-sanitize` schema applied to the rendered output.
      * The library default extends `rehype-sanitize`'s own `defaultSchema`
-     * with the `<mark>` tag, KaTeX class names, and the cross-chunk
-     * coordination tags (`cross-chunk-link`, `cross-chunk-image`,
-     * `footnote-sup`). The default is not exported as a value — see
-     * {@link extendSanitizeSchema} for how to inspect or extend it safely.
+     * with the `<mark>` tag, the `math-inline` / `math-display` className
+     * markers `remark-math` emits on `<code>` (KaTeX's own output classes
+     * survive separately because `rehype-katex` runs after `rehype-sanitize`),
+     * and the cross-chunk coordination tags (`cross-chunk-link`,
+     * `cross-chunk-image`, `footnote-sup`). The default is not exported as a
+     * value — see {@link extendSanitizeSchema} for how to inspect or extend
+     * it safely.
      *
      * **Recommended pattern**: build the schema with {@link extendSanitizeSchema}
      * (mutate-and-return form) so those library additions stay intact, and
@@ -1189,7 +1231,7 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
  * Root component that preprocesses markdown content and renders it through
  * a configurable remark/rehype pipeline wrapped in typography and style layers.
  */
-declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, defaultConfig, config, metadata, Typography, ExtraStyles, variant, colorScheme, documentId, urlTransform, sanitizeSchema, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_runtime.JSX.Element;
+declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, defaultConfig, config, metadata, Typography, ExtraStyles, variant, colorScheme, documentId, urlTransform, sanitizeSchema, }: AIMarkdownProps<TConfig, TRenderData>) => react.JSX.Element;
 declare const _default: typeof AIMarkdownComponent;
 
 export { type AIMDContentPreprocessor, type AIMarkdownColorScheme, type AIMarkdownCustomComponents, AIMarkdownDocuments, type AIMarkdownDocumentsProps, type AIMarkdownExtraStylesComponent, type AIMarkdownExtraStylesProps, type AIMarkdownMetadata, type AIMarkdownProps, type AIMarkdownRenderConfig, AIMarkdownRenderDisplayOptimizeAbility, AIMarkdownRenderExtraSyntax, type AIMarkdownRenderState, type AIMarkdownTypographyComponent, type AIMarkdownTypographyProps, type AIMarkdownVariant, type ChunkData, type FootnoteDef, type LinkDef, type PartialDeep, type RefKind, type RefRecord, type Registry, type SanitizeSchema, type UrlTransform, _default as default, defaultAIMarkdownRenderConfig, defaultUrlTransform, extendSanitizeSchema, useAIMarkdownMetadata, useAIMarkdownRenderState, useDocumentRegistry, useStableValue };