@ai-react-markdown/core 1.4.3 → 1.4.5

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 }) => (
@@ -318,6 +322,16 @@ type IsNever<T> = [T] extends [never] ? true : false;
 // https://github.com/sindresorhus/type-fest
 // SPDX-License-Identifier: (MIT OR CC0-1.0)
 // Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+//
+// Vendored verbatim from upstream. The `any[]` spellings in
+// `HasMultipleCallSignatures` and the function-fallback branch are
+// load-bearing for type-fest's variadic-arity matching — replacing them
+// with `unknown[]` would either narrow or widen the inference in a
+// non-equivalent way, and the test suite for those exact helpers lives in
+// type-fest's own repo. Disable the rule at the file scope to mirror
+// upstream while keeping the rest of the package's `no-explicit-any`
+// contract strict.
+/* eslint-disable @typescript-eslint/no-explicit-any */
 
 
 
@@ -664,7 +678,7 @@ declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig
  *
  * Metadata lives in a separate React context so that changes to metadata
  * do not cause re-renders in components that only consume render state
- * (e.g. {@link MarkdownContent}).
+ * (e.g. the internal `MarkdownContent` renderer).
  *
  * ### `TMetadata` is a caller-asserted type
  *
@@ -742,14 +756,16 @@ interface AIMarkdownMetadataProviderProps<TMetadata extends AIMarkdownMetadata =
 type AIMDContentPreprocessor = (content: string) => string;
 
 /**
- * Builds a `rehype-sanitize` schema by handing the caller a deep clone of the
- * library default ({@link sanitizeSchema}) to mutate or replace.
+ * Builds a `rehype-sanitize` schema by handing the caller a deep clone of
+ * the library's internal default schema to mutate or replace.
  *
  * The mutate-and-return pattern matches the ergonomics of Next.js's
  * `webpack(config)` and Express middleware: a callback receives a draft,
  * either modifies it in place (returning nothing) or returns a fresh object
  * to replace it. The library guarantees the draft is a deep clone, so direct
- * mutation never leaks into the shared default singleton.
+ * mutation never leaks into the singleton — and the singleton itself is not
+ * exported, so consumers cannot accidentally hand-roll a schema that drops
+ * the library's cross-chunk tag allowlist or KaTeX className additions.
  *
  * @module components/extendSanitizeSchema
  */
@@ -792,6 +808,16 @@ type SanitizeSchema = typeof defaultSchema;
  * }));
  * ```
  *
+ * @example Inspect the library default (e.g. to learn what's already allowed):
+ * ```ts
+ * // The draft handed to the modifier IS the library default, deep-cloned.
+ * // Logging it once at module load surfaces every default field — protocols,
+ * // attributes, tagNames, etc. — without ever exposing the singleton itself.
+ * extendSanitizeSchema((s) => {
+ *   console.log('default sanitize schema:', s);
+ * });
+ * ```
+ *
  * @remarks Allowing a protocol on `protocols.href` lets the URL through the
  * SECOND sanitize gate. The FIRST gate (`urlTransform`) must permit the
  * same protocol independently — see the `urlTransform` prop on
@@ -853,23 +879,6 @@ declare function extendSanitizeSchema(modifier: (draft: SanitizeSchema) => Sanit
  */
 declare function useStableValue<T>(value: T): T;
 
-/**
- * Builds the `rehype-sanitize` schema used by {@link MarkdownContent}.
- *
- * Extracted into its own module so the merge logic can be unit-tested in
- * isolation without pulling in React or the full markdown pipeline.
- *
- * @module components/sanitizeSchema
- */
-
-type Schema = typeof defaultSchema;
-/**
- * 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.
- */
-declare const sanitizeSchema: Schema;
-
 /**
  * Cross-chunk shared state. Holds per-chunk contributions (refs, defs,
  * linkDefs) keyed by Symbol identity allocated via useId reactId, with
@@ -920,45 +929,62 @@ interface ChunkData {
     ownFootnoteLabels: Set<string>;
     ownLinkLabels: Set<string>;
 }
+/**
+ * Public, read-only view of the cross-chunk registry. This is the type
+ * surfaced by `useDocumentRegistry` and re-exported from the package
+ * barrel. Consumers can:
+ *
+ *   - read the registry's current state (`chunkOrder`, `chunkData`,
+ *     `labelSet`, `version`)
+ *   - observe changes (`subscribe`)
+ *   - run selectors (`globalNumber`, `resolveLinkDef`, …)
+ *
+ * Mutators — `registerChunk`, `allocateSymbol`, `releaseSymbol`,
+ * `contributeLabels`, `contributeChunkData` — are intentionally off this
+ * 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.
+ */
 interface Registry {
-    /** Chunk mount-order Symbol list. **Read-only from outside the registry.**
-     *  Direct mutation (`.push`, `.splice`, index assignment) corrupts
-     *  footnote numbering, "last chunk" detection, and eviction. Use the
-     *  `allocateSymbol` / `releaseSymbol` / `registerChunk` API instead. */
+    /** Chunk mount-order Symbol list. **Read-only.** Direct mutation
+     *  (`.push`, `.splice`, index assignment) corrupts footnote numbering,
+     *  "last chunk" detection, and eviction. */
     readonly chunkOrder: readonly symbol[];
-    /** Chunk Symbol → contribution payload. **Read-only from outside.**
-     *  Use `contributeChunkData` / `contributeLabels` / `registerChunk` to
-     *  publish; direct `.set` / `.delete` bypasses version bumps and
-     *  subscriber wake-ups. */
+    /** Chunk Symbol → contribution payload. **Read-only.** Direct `.set` /
+     *  `.delete` bypasses version bumps and subscriber wake-ups. */
     readonly chunkData: ReadonlyMap<symbol, ChunkData>;
     /** Union of own-def labels across all chunks. PASS 0.5 phantom-injection
-     *  driver. **Read-only from outside.** The registry derives this from
-     *  per-chunk contributions; direct mutation breaks the derivation. */
+     *  driver. **Read-only.** The registry derives this from per-chunk
+     *  contributions; direct mutation breaks the derivation. */
     readonly labelSet: {
         readonly footnoteLabels: ReadonlySet<string>;
         readonly linkLabels: ReadonlySet<string>;
     };
-    /** Monotonic version counter bumped by every mutation. **Read-only from
-     *  outside** — consumers should observe via `subscribe`, not by writing. */
+    /** Monotonic version counter bumped by every mutation. **Read-only** —
+     *  consumers should observe via `subscribe`, not by writing. */
     readonly version: number;
-    /** Allocate (or reuse, for Strict Mode remount) the chunk Symbol for
-     *  `reactId` AND publish this chunk's own def labels (footnotes + links)
-     *  in one call. Canonical pair API used by `MarkdownContent`'s allocate
-     *  effect — combining the two reduces the pair to a single registry
-     *  version step, which downstream consumers see as one wake-up rather
-     *  than two (the second was already coalesced by microtask, but this
-     *  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;
-    releaseSymbol(reactId: string): void;
-    contributeLabels(symbol: symbol, footnotes: Set<string>, links: Set<string>): void;
-    contributeChunkData(symbol: symbol, data: ChunkData): void;
     subscribe(cb: () => void): () => void;
     canonicalFootnoteFor(label: string): symbol | null;
     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.
+     *
+     * 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>`.
+     */
     resolveLinkDef(label: string): LinkDef | null;
     getRefsForLabel(label: string): number;
     /** Map a chunk-local footnote-ref occurrence index (1-based, as emitted by
@@ -1110,8 +1136,8 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      *
      * 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 {@link sanitizeSchema} prop and the
-     * matching {@link extendSanitizeSchema} helper for the second gate.
+     * protocol allowlist. See the `sanitizeSchema` prop on this component
+     * and the {@link extendSanitizeSchema} helper for the second gate.
      *
      * **API stability**: the `UrlTransform` type tracks the upstream
      * `react-markdown` shape and may change with its major versions.
@@ -1119,10 +1145,11 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
     urlTransform?: UrlTransform | null;
     /**
      * Override the `rehype-sanitize` schema applied to the rendered output.
-     * The library default ({@link sanitizeSchema}) 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 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.
      *
      * **Recommended pattern**: build the schema with {@link extendSanitizeSchema}
      * (mutate-and-return form) so those library additions stay intact, and
@@ -1147,10 +1174,11 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      * lose its placeholders. Prefer the helper unless you have a specific
      * reason to opt out.
      *
-     * **Reference stability matters.** Inline `<AIMarkdown sanitizeSchema={{
-     * ...sanitizeSchema, protocols: {...} }}>` is mitigated by an internal
-     * `useStableValue` deep-equal pass, but the safer pattern is still
-     * module-scope. Development builds will `console.warn` on identity flips.
+     * **Reference stability matters.** An inline call
+     * (`sanitizeSchema={extendSanitizeSchema((s) => { … })}`) is mitigated by
+     * an internal `useStableValue` deep-equal pass, but the safer pattern is
+     * still module-scope. Development builds will `console.warn` on identity
+     * flips.
      *
      * **API stability**: the `SanitizeSchema` type tracks the upstream
      * `rehype-sanitize` shape and may change with its major versions.
@@ -1164,4 +1192,4 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
 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 _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, sanitizeSchema, useAIMarkdownMetadata, useAIMarkdownRenderState, useDocumentRegistry, useStableValue };
+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

@@ -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 }) => (
@@ -318,6 +322,16 @@ type IsNever<T> = [T] extends [never] ? true : false;
 // https://github.com/sindresorhus/type-fest
 // SPDX-License-Identifier: (MIT OR CC0-1.0)
 // Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+//
+// Vendored verbatim from upstream. The `any[]` spellings in
+// `HasMultipleCallSignatures` and the function-fallback branch are
+// load-bearing for type-fest's variadic-arity matching — replacing them
+// with `unknown[]` would either narrow or widen the inference in a
+// non-equivalent way, and the test suite for those exact helpers lives in
+// type-fest's own repo. Disable the rule at the file scope to mirror
+// upstream while keeping the rest of the package's `no-explicit-any`
+// contract strict.
+/* eslint-disable @typescript-eslint/no-explicit-any */
 
 
 
@@ -664,7 +678,7 @@ declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig
  *
  * Metadata lives in a separate React context so that changes to metadata
  * do not cause re-renders in components that only consume render state
- * (e.g. {@link MarkdownContent}).
+ * (e.g. the internal `MarkdownContent` renderer).
  *
  * ### `TMetadata` is a caller-asserted type
  *
@@ -742,14 +756,16 @@ interface AIMarkdownMetadataProviderProps<TMetadata extends AIMarkdownMetadata =
 type AIMDContentPreprocessor = (content: string) => string;
 
 /**
- * Builds a `rehype-sanitize` schema by handing the caller a deep clone of the
- * library default ({@link sanitizeSchema}) to mutate or replace.
+ * Builds a `rehype-sanitize` schema by handing the caller a deep clone of
+ * the library's internal default schema to mutate or replace.
  *
  * The mutate-and-return pattern matches the ergonomics of Next.js's
  * `webpack(config)` and Express middleware: a callback receives a draft,
  * either modifies it in place (returning nothing) or returns a fresh object
  * to replace it. The library guarantees the draft is a deep clone, so direct
- * mutation never leaks into the shared default singleton.
+ * mutation never leaks into the singleton — and the singleton itself is not
+ * exported, so consumers cannot accidentally hand-roll a schema that drops
+ * the library's cross-chunk tag allowlist or KaTeX className additions.
  *
  * @module components/extendSanitizeSchema
  */
@@ -792,6 +808,16 @@ type SanitizeSchema = typeof defaultSchema;
  * }));
  * ```
  *
+ * @example Inspect the library default (e.g. to learn what's already allowed):
+ * ```ts
+ * // The draft handed to the modifier IS the library default, deep-cloned.
+ * // Logging it once at module load surfaces every default field — protocols,
+ * // attributes, tagNames, etc. — without ever exposing the singleton itself.
+ * extendSanitizeSchema((s) => {
+ *   console.log('default sanitize schema:', s);
+ * });
+ * ```
+ *
  * @remarks Allowing a protocol on `protocols.href` lets the URL through the
  * SECOND sanitize gate. The FIRST gate (`urlTransform`) must permit the
  * same protocol independently — see the `urlTransform` prop on
@@ -853,23 +879,6 @@ declare function extendSanitizeSchema(modifier: (draft: SanitizeSchema) => Sanit
  */
 declare function useStableValue<T>(value: T): T;
 
-/**
- * Builds the `rehype-sanitize` schema used by {@link MarkdownContent}.
- *
- * Extracted into its own module so the merge logic can be unit-tested in
- * isolation without pulling in React or the full markdown pipeline.
- *
- * @module components/sanitizeSchema
- */
-
-type Schema = typeof defaultSchema;
-/**
- * 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.
- */
-declare const sanitizeSchema: Schema;
-
 /**
  * Cross-chunk shared state. Holds per-chunk contributions (refs, defs,
  * linkDefs) keyed by Symbol identity allocated via useId reactId, with
@@ -920,45 +929,62 @@ interface ChunkData {
     ownFootnoteLabels: Set<string>;
     ownLinkLabels: Set<string>;
 }
+/**
+ * Public, read-only view of the cross-chunk registry. This is the type
+ * surfaced by `useDocumentRegistry` and re-exported from the package
+ * barrel. Consumers can:
+ *
+ *   - read the registry's current state (`chunkOrder`, `chunkData`,
+ *     `labelSet`, `version`)
+ *   - observe changes (`subscribe`)
+ *   - run selectors (`globalNumber`, `resolveLinkDef`, …)
+ *
+ * Mutators — `registerChunk`, `allocateSymbol`, `releaseSymbol`,
+ * `contributeLabels`, `contributeChunkData` — are intentionally off this
+ * 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.
+ */
 interface Registry {
-    /** Chunk mount-order Symbol list. **Read-only from outside the registry.**
-     *  Direct mutation (`.push`, `.splice`, index assignment) corrupts
-     *  footnote numbering, "last chunk" detection, and eviction. Use the
-     *  `allocateSymbol` / `releaseSymbol` / `registerChunk` API instead. */
+    /** Chunk mount-order Symbol list. **Read-only.** Direct mutation
+     *  (`.push`, `.splice`, index assignment) corrupts footnote numbering,
+     *  "last chunk" detection, and eviction. */
     readonly chunkOrder: readonly symbol[];
-    /** Chunk Symbol → contribution payload. **Read-only from outside.**
-     *  Use `contributeChunkData` / `contributeLabels` / `registerChunk` to
-     *  publish; direct `.set` / `.delete` bypasses version bumps and
-     *  subscriber wake-ups. */
+    /** Chunk Symbol → contribution payload. **Read-only.** Direct `.set` /
+     *  `.delete` bypasses version bumps and subscriber wake-ups. */
     readonly chunkData: ReadonlyMap<symbol, ChunkData>;
     /** Union of own-def labels across all chunks. PASS 0.5 phantom-injection
-     *  driver. **Read-only from outside.** The registry derives this from
-     *  per-chunk contributions; direct mutation breaks the derivation. */
+     *  driver. **Read-only.** The registry derives this from per-chunk
+     *  contributions; direct mutation breaks the derivation. */
     readonly labelSet: {
         readonly footnoteLabels: ReadonlySet<string>;
         readonly linkLabels: ReadonlySet<string>;
     };
-    /** Monotonic version counter bumped by every mutation. **Read-only from
-     *  outside** — consumers should observe via `subscribe`, not by writing. */
+    /** Monotonic version counter bumped by every mutation. **Read-only** —
+     *  consumers should observe via `subscribe`, not by writing. */
     readonly version: number;
-    /** Allocate (or reuse, for Strict Mode remount) the chunk Symbol for
-     *  `reactId` AND publish this chunk's own def labels (footnotes + links)
-     *  in one call. Canonical pair API used by `MarkdownContent`'s allocate
-     *  effect — combining the two reduces the pair to a single registry
-     *  version step, which downstream consumers see as one wake-up rather
-     *  than two (the second was already coalesced by microtask, but this
-     *  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;
-    releaseSymbol(reactId: string): void;
-    contributeLabels(symbol: symbol, footnotes: Set<string>, links: Set<string>): void;
-    contributeChunkData(symbol: symbol, data: ChunkData): void;
     subscribe(cb: () => void): () => void;
     canonicalFootnoteFor(label: string): symbol | null;
     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.
+     *
+     * 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>`.
+     */
     resolveLinkDef(label: string): LinkDef | null;
     getRefsForLabel(label: string): number;
     /** Map a chunk-local footnote-ref occurrence index (1-based, as emitted by
@@ -1110,8 +1136,8 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      *
      * 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 {@link sanitizeSchema} prop and the
-     * matching {@link extendSanitizeSchema} helper for the second gate.
+     * protocol allowlist. See the `sanitizeSchema` prop on this component
+     * and the {@link extendSanitizeSchema} helper for the second gate.
      *
      * **API stability**: the `UrlTransform` type tracks the upstream
      * `react-markdown` shape and may change with its major versions.
@@ -1119,10 +1145,11 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
     urlTransform?: UrlTransform | null;
     /**
      * Override the `rehype-sanitize` schema applied to the rendered output.
-     * The library default ({@link sanitizeSchema}) 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 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.
      *
      * **Recommended pattern**: build the schema with {@link extendSanitizeSchema}
      * (mutate-and-return form) so those library additions stay intact, and
@@ -1147,10 +1174,11 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      * lose its placeholders. Prefer the helper unless you have a specific
      * reason to opt out.
      *
-     * **Reference stability matters.** Inline `<AIMarkdown sanitizeSchema={{
-     * ...sanitizeSchema, protocols: {...} }}>` is mitigated by an internal
-     * `useStableValue` deep-equal pass, but the safer pattern is still
-     * module-scope. Development builds will `console.warn` on identity flips.
+     * **Reference stability matters.** An inline call
+     * (`sanitizeSchema={extendSanitizeSchema((s) => { … })}`) is mitigated by
+     * an internal `useStableValue` deep-equal pass, but the safer pattern is
+     * still module-scope. Development builds will `console.warn` on identity
+     * flips.
      *
      * **API stability**: the `SanitizeSchema` type tracks the upstream
      * `rehype-sanitize` shape and may change with its major versions.
@@ -1164,4 +1192,4 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
 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 _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, sanitizeSchema, useAIMarkdownMetadata, useAIMarkdownRenderState, useDocumentRegistry, useStableValue };
+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 };