@ai-react-markdown/core 1.4.4 → 1.4.6

package/dist/index.d.cts

@@ -183,6 +183,10 @@ interface AIMarkdownTypographyProps extends PropsWithChildren {
      * `font-size: var(--aim-font-size-root)` to opt out of `em` compounding
      * when a stable size is needed.
      *
+     * The built-in `default` variant consumes this variable: its spacing,
+     * font-size, and heading tokens are defined as `calc(var(--aim-font-size-root) * k)`,
+     * so the `fontSize` prop proportionally scales every rendered dimension.
+     *
      * @example
      * ```tsx
      * const MyTypography: AIMarkdownTypographyComponent = ({ children, fontSize, style }) => (
@@ -234,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
@@ -814,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.
@@ -1018,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.
@@ -1095,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,
@@ -1127,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.
@@ -1142,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

package/dist/index.d.ts

@@ -183,6 +183,10 @@ interface AIMarkdownTypographyProps extends PropsWithChildren {
      * `font-size: var(--aim-font-size-root)` to opt out of `em` compounding
      * when a stable size is needed.
      *
+     * The built-in `default` variant consumes this variable: its spacing,
+     * font-size, and heading tokens are defined as `calc(var(--aim-font-size-root) * k)`,
+     * so the `fontSize` prop proportionally scales every rendered dimension.
+     *
      * @example
      * ```tsx
      * const MyTypography: AIMarkdownTypographyComponent = ({ children, fontSize, style }) => (
@@ -234,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
@@ -814,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.
@@ -1018,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.
@@ -1095,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,
@@ -1127,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.
@@ -1142,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