@ai-react-markdown/core 1.2.8 → 1.3.0

package/dist/index.d.cts

@@ -1,6 +1,22 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ComponentType, PropsWithChildren, CSSProperties } from 'react';
-import { Components } from 'react-markdown';
+import { JSX, ComponentType, PropsWithChildren, CSSProperties } from 'react';
+import { Element } from 'hast';
+
+/**
+ * Public types for the local Markdown wrapper. Ported 1:1 from react-markdown
+ * v10's lib/index.js JSDoc, restructured as TypeScript declarations.
+ *
+ * @module components/markdown/types
+ */
+
+/** Extra fields the wrapper passes to user-supplied tag components. */
+interface ExtraProps {
+    node?: Element | undefined;
+}
+/** Map tag names to user components or other tag names. */
+type Components = {
+    [Key in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[Key] & ExtraProps> | keyof JSX.IntrinsicElements;
+};
 
 /**
  * Core type definitions, enums, and default configuration for ai-react-markdown.
@@ -14,9 +30,10 @@ import { Components } from 'react-markdown';
 
 /**
  * Custom component overrides for the markdown renderer.
- * Alias for `react-markdown`'s `Components` type, re-exported under the
- * library's `AIMarkdown` naming convention so consumers don't need a
- * direct `react-markdown` dependency for type imports.
+ * Alias for the local Markdown wrapper's `Components` type (a vendored fork of
+ * react-markdown's), re-exported under the library's `AIMarkdown` naming
+ * convention so consumers don't need a direct `react-markdown` dependency
+ * for type imports.
  */
 type AIMarkdownCustomComponents = Components;
 /**
@@ -27,9 +44,7 @@ declare enum AIMarkdownRenderExtraSyntax {
     /** `==Highlight==` syntax support. */
     HIGHLIGHT = "HIGHLIGHT",
     /** Definition list syntax. @see https://michelf.ca/projects/php-markdown/extra/#def-list */
-    DEFINITION_LIST = "DEFINITION_LIST",
-    /** Superscript (`^text^`) and subscript (`~text~`) syntax. */
-    SUBSCRIPT = "SUBSCRIPT"
+    DEFINITION_LIST = "DEFINITION_LIST"
 }
 /**
  * Display optimization abilities applied during markdown processing.
@@ -46,18 +61,49 @@ declare enum AIMarkdownRenderDisplayOptimizeAbility {
 /**
  * Configuration object controlling which markdown extensions and
  * display optimizations are active during rendering.
+ *
+ * Arrays are typed `readonly` so the interface is assignable from the frozen
+ * {@link defaultAIMarkdownRenderConfig}. Consumers can still pass mutable
+ * arrays since `readonly T[]` is assignable from `T[]`. Note: this is a
+ * compile-time hint only — user-supplied configs are not deep-frozen at
+ * runtime, so the library does not guarantee the object remains unchanged
+ * after it is passed in.
  */
 interface AIMarkdownRenderConfig {
     /** Extra syntax extensions to enable. */
-    extraSyntaxSupported: AIMarkdownRenderExtraSyntax[];
+    readonly extraSyntaxSupported: readonly AIMarkdownRenderExtraSyntax[];
     /** Display optimization abilities to enable. */
-    displayOptimizeAbilities: AIMarkdownRenderDisplayOptimizeAbility[];
+    readonly displayOptimizeAbilities: readonly AIMarkdownRenderDisplayOptimizeAbility[];
+    /**
+     * Whether to enable block-level memoization across renders.
+     *
+     * When `true` (default), the renderer splits each rendered document into
+     * per-block units and memoizes the React subtree of each block by its
+     * source identity (`raw + occurrence + ctx + position`). Unchanged blocks
+     * during streaming skip `toJsxRuntime` and React reconcile work, reducing
+     * per-frame cost roughly proportional to the unchanged fraction of the
+     * document. Output is byte-identical to the disabled path.
+     *
+     * When `false`, the renderer falls back to the legacy bare `<Markdown>`
+     * flow — every render runs the full pipeline end-to-end with no
+     * cross-frame reuse. Useful for debugging, for environments where the
+     * extra `useRef`-backed cache is undesirable, or as an escape hatch if a
+     * future custom rehype plugin interacts badly with the plan abstraction.
+     *
+     * @default true
+     */
+    readonly blockMemoEnabled: boolean;
 }
 /**
  * Sensible default configuration with all extensions and optimizations enabled.
- * Frozen to prevent accidental mutation.
+ * Frozen at both the top level and the inner arrays so this shared singleton
+ * cannot be mutated by any consumer.
  */
-declare const defaultAIMarkdownRenderConfig: AIMarkdownRenderConfig;
+declare const defaultAIMarkdownRenderConfig: Readonly<{
+    extraSyntaxSupported: readonly AIMarkdownRenderExtraSyntax[];
+    displayOptimizeAbilities: readonly AIMarkdownRenderDisplayOptimizeAbility[];
+    blockMemoEnabled: true;
+}>;
 /**
  * Arbitrary metadata that consumers can pass through a dedicated React context.
  * Custom renderers can access this via the {@link useAIMarkdownMetadata} hook.
@@ -140,6 +186,22 @@ interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkd
     variant: AIMarkdownVariant;
     /** Active color scheme. */
     colorScheme: AIMarkdownColorScheme;
+    /**
+     * Stable identifier unique to this *logical markdown document*. Used as
+     * the id namespace for clobberable attributes (`id`, hash hrefs) so two
+     * documents on the same page don't cross-link — e.g. clicking a footnote
+     * `[^1]` in message A won't scroll to the `[^1]` definition in message B.
+     *
+     * Named `documentId` (not `instanceId`) intentionally: when one logical
+     * markdown document is split into multiple `<AIMarkdown>` instances
+     * (chunked / streamed rendering), every chunk SHOULD share the same value
+     * so id-prefixes align across the chunks.
+     *
+     * Auto-generated via React's `useId()` (SSR-safe, stable across
+     * re-renders) when not provided by the consumer; consumer-supplied values
+     * always win.
+     */
+    documentId: string;
     /** Active render configuration. */
     config: TConfig;
 }
@@ -494,16 +556,59 @@ type PartialObjectDeep<ObjectType extends object, Options extends Required<Parti
  * Must be called inside a component rendered as a descendant of `<AIMarkdown>`.
  * Throws if called outside the provider boundary.
  *
- * @typeParam TConfig - Expected configuration shape (defaults to {@link AIMarkdownRenderConfig}).
- * @returns The current render state (does not include metadata — use {@link useAIMarkdownMetadata} for that).
+ * ### `TConfig` is a caller-asserted type, not a derived one
  *
- * @example
+ * The generic parameter is **an assertion the caller makes about the provider
+ * above it** — TypeScript cannot verify that the actual `<AIMarkdown>` in the
+ * tree was configured with a matching `defaultConfig: TConfig`. If you pass a
+ * wider `TConfig` than what the provider actually carries, field access at
+ * compile time will look fine but resolve to `undefined` at runtime.
+ *
+ * The intended pattern is that extension packages (e.g. `@ai-react-markdown/mantine`)
+ * ship their own narrow wrapper hook alongside a matching `defaultConfig`, so the
+ * assertion is made *once* next to the provider configuration and consumers of the
+ * wrapper never touch the raw generic.
+ *
+ * @typeParam TConfig - Caller-asserted configuration shape (defaults to
+ *   {@link AIMarkdownRenderConfig}). Must be aligned with the provider's
+ *   `defaultConfig` — the library does not check this at runtime.
+ * @returns The current render state (does not include metadata — use
+ *   {@link useAIMarkdownMetadata} for that).
+ * @throws If called outside an `<AIMarkdown>` provider tree.
+ *
+ * @example Base usage — no generic, always safe:
  * ```tsx
  * function CustomCodeBlock({ children }: PropsWithChildren) {
  *   const { streaming, config } = useAIMarkdownRenderState();
- *   // ...
+ *   // config: AIMarkdownRenderConfig — guaranteed shape
+ * }
+ * ```
+ *
+ * @example Wrapper-hook pattern — the intended way to use an extended TConfig:
+ * ```tsx
+ * // In your extension package (pin the assertion in one place):
+ * interface ExtendedConfig extends AIMarkdownRenderConfig {
+ *   themeMode: 'light' | 'dark' | 'auto';
  * }
+ * export const extendedDefaultConfig: ExtendedConfig = {
+ *   ...defaultAIMarkdownRenderConfig,
+ *   themeMode: 'auto',
+ * };
+ * export const useExtendedRenderState = () =>
+ *   useAIMarkdownRenderState<ExtendedConfig>();
+ *
+ * // Provider is always configured with the matching defaultConfig:
+ * <AIMarkdown defaultConfig={extendedDefaultConfig} ...>{children}</AIMarkdown>
+ *
+ * // Consumers use the narrow wrapper — no raw generic anywhere:
+ * const { config } = useExtendedRenderState();
+ * config.themeMode; // correctly typed and present at runtime
  * ```
+ *
+ * @see `@ai-react-markdown/mantine` — real-world reference. Its
+ *   `MantineAIMarkdownRenderConfig`, `defaultMantineAIMarkdownRenderConfig`,
+ *   `<MantineAIMarkdown>` (which passes `defaultConfig` by default), and
+ *   `useMantineAIMarkdownRenderState` implement this exact pattern.
  */
 declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig>(): AIMarkdownRenderState<TConfig>;
 /**
@@ -513,8 +618,24 @@ declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig
  * do not cause re-renders in components that only consume render state
  * (e.g. {@link MarkdownContent}).
  *
- * @typeParam TMetadata - Expected metadata shape (defaults to {@link AIMarkdownMetadata}).
+ * ### `TMetadata` is a caller-asserted type
+ *
+ * Same contract as {@link useAIMarkdownRenderState} — the generic is an
+ * assertion about the `metadata` prop passed to the provider above, not a
+ * value TypeScript can derive.  Unlike render-state config, metadata has no
+ * runtime fallback: if the provider received no `metadata`, the hook returns
+ * `undefined` regardless of the asserted type. Prefer wrapping this hook in
+ * a project-local hook that pins `TMetadata` next to the call site that
+ * actually provides the metadata.
+ *
+ * @typeParam TMetadata - Caller-asserted metadata shape (defaults to
+ *   {@link AIMarkdownMetadata}). Caller is responsible for ensuring the
+ *   provider's `metadata` prop matches this shape.
  * @returns The current metadata, or `undefined` if none was provided.
+ *
+ * @see `@ai-react-markdown/mantine` — `useMantineAIMarkdownMetadata` applies
+ *   the wrapper pattern to this hook, pinning `MantineAIMarkdownMetadata` in
+ *   a single location.
  */
 declare function useAIMarkdownMetadata<TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata>(): TMetadata | undefined;
 /** Props for {@link AIMarkdownRenderStateProvider}. */
@@ -523,6 +644,19 @@ interface AIMarkdownRenderStateProviderProps<TConfig extends AIMarkdownRenderCon
     fontSize: string;
     variant: AIMarkdownVariant;
     colorScheme: AIMarkdownColorScheme;
+    /**
+     * Logical-document identifier used as the id namespace for clobberable
+     * attributes (id / hash hrefs). Optional — when omitted, the provider
+     * auto-generates one via {@link useId} so the provider stays drop-in
+     * usable for direct consumers (e.g. extension packages that don't go
+     * through `<AIMarkdown>`).
+     *
+     * Pass the SAME value to multiple providers / `<AIMarkdown>` instances
+     * when they render chunks of the same logical document — their id
+     * prefixes will align so cross-chunk anchors and (once the parser sees
+     * the full doc) footnote navigation work.
+     */
+    documentId?: string;
     /**
      * Base default config to merge against. When omitted, falls back to
      * {@link defaultAIMarkdownRenderConfig}. Sub-packages (e.g. mantine) can
@@ -572,6 +706,14 @@ type AIMDContentPreprocessor = (content: string) => string;
  * returned, preventing unnecessary re-renders in downstream `useMemo` / `useEffect`
  * consumers that depend on reference equality.
  *
+ * The ref is updated in a layout effect (not during render) so that the cached
+ * reference only advances on COMMITTED renders. In concurrent mode a render
+ * may be discarded (e.g. by Suspense); writing to the ref during render would
+ * let values from discarded renders pollute the cache and leak into subsequent
+ * committed renders. Layout effects run synchronously right after commit, which
+ * closes the window where a same-tick re-render could otherwise observe a stale
+ * `ref.current` and hand back an outdated reference.
+ *
  * @typeParam T - The value type.
  * @param value - The potentially new value to stabilize.
  * @returns The previous reference when deep-equal, otherwise the new value.
@@ -632,12 +774,34 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
     variant?: AIMarkdownVariant;
     /** Color scheme name. Defaults to `'light'`. */
     colorScheme?: AIMarkdownColorScheme;
+    /**
+     * Stable identifier for the *logical markdown document* this `<AIMarkdown>`
+     * is rendering. Used as the id namespace for all clobberable attributes
+     * (`id`, hash hrefs) so two documents on the same page do not cross-link —
+     * e.g. clicking a footnote `[^1]` in message A will not scroll to the
+     * `[^1]` definition in message B.
+     *
+     * Why `documentId` and not `instanceId`: when one logical document is
+     * split across multiple `<AIMarkdown>` instances (chunked / streamed
+     * rendering), every chunk should share the SAME `documentId` so their
+     * id-prefixes line up. The id is per-document, not per-React-instance.
+     *
+     * When omitted, an id is auto-generated via React's `useId()` (SSR-safe
+     * and stable across re-renders). Pass an explicit value when you need
+     * deterministic ids (snapshot tests, cross-component deep links) or when
+     * multiple instances render the same logical document.
+     *
+     * Consumer-supplied values pass through `encodeURIComponent` at the prefix
+     * construction site, so any string is safe — including ids with reserved
+     * characters like `:`, `/`, or spaces.
+     */
+    documentId?: string;
 }
 /**
  * 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, }: 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, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_runtime.JSX.Element;
 declare const _default: typeof AIMarkdownComponent;
 
 export { type AIMDContentPreprocessor, type AIMarkdownColorScheme, type AIMarkdownCustomComponents, type AIMarkdownExtraStylesComponent, type AIMarkdownExtraStylesProps, type AIMarkdownMetadata, type AIMarkdownProps, type AIMarkdownRenderConfig, AIMarkdownRenderDisplayOptimizeAbility, AIMarkdownRenderExtraSyntax, type AIMarkdownRenderState, type AIMarkdownTypographyComponent, type AIMarkdownTypographyProps, type AIMarkdownVariant, type PartialDeep, _default as default, defaultAIMarkdownRenderConfig, useAIMarkdownMetadata, useAIMarkdownRenderState, useStableValue };

package/dist/index.d.ts

@@ -1,6 +1,22 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ComponentType, PropsWithChildren, CSSProperties } from 'react';
-import { Components } from 'react-markdown';
+import { JSX, ComponentType, PropsWithChildren, CSSProperties } from 'react';
+import { Element } from 'hast';
+
+/**
+ * Public types for the local Markdown wrapper. Ported 1:1 from react-markdown
+ * v10's lib/index.js JSDoc, restructured as TypeScript declarations.
+ *
+ * @module components/markdown/types
+ */
+
+/** Extra fields the wrapper passes to user-supplied tag components. */
+interface ExtraProps {
+    node?: Element | undefined;
+}
+/** Map tag names to user components or other tag names. */
+type Components = {
+    [Key in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[Key] & ExtraProps> | keyof JSX.IntrinsicElements;
+};
 
 /**
  * Core type definitions, enums, and default configuration for ai-react-markdown.
@@ -14,9 +30,10 @@ import { Components } from 'react-markdown';
 
 /**
  * Custom component overrides for the markdown renderer.
- * Alias for `react-markdown`'s `Components` type, re-exported under the
- * library's `AIMarkdown` naming convention so consumers don't need a
- * direct `react-markdown` dependency for type imports.
+ * Alias for the local Markdown wrapper's `Components` type (a vendored fork of
+ * react-markdown's), re-exported under the library's `AIMarkdown` naming
+ * convention so consumers don't need a direct `react-markdown` dependency
+ * for type imports.
  */
 type AIMarkdownCustomComponents = Components;
 /**
@@ -27,9 +44,7 @@ declare enum AIMarkdownRenderExtraSyntax {
     /** `==Highlight==` syntax support. */
     HIGHLIGHT = "HIGHLIGHT",
     /** Definition list syntax. @see https://michelf.ca/projects/php-markdown/extra/#def-list */
-    DEFINITION_LIST = "DEFINITION_LIST",
-    /** Superscript (`^text^`) and subscript (`~text~`) syntax. */
-    SUBSCRIPT = "SUBSCRIPT"
+    DEFINITION_LIST = "DEFINITION_LIST"
 }
 /**
  * Display optimization abilities applied during markdown processing.
@@ -46,18 +61,49 @@ declare enum AIMarkdownRenderDisplayOptimizeAbility {
 /**
  * Configuration object controlling which markdown extensions and
  * display optimizations are active during rendering.
+ *
+ * Arrays are typed `readonly` so the interface is assignable from the frozen
+ * {@link defaultAIMarkdownRenderConfig}. Consumers can still pass mutable
+ * arrays since `readonly T[]` is assignable from `T[]`. Note: this is a
+ * compile-time hint only — user-supplied configs are not deep-frozen at
+ * runtime, so the library does not guarantee the object remains unchanged
+ * after it is passed in.
  */
 interface AIMarkdownRenderConfig {
     /** Extra syntax extensions to enable. */
-    extraSyntaxSupported: AIMarkdownRenderExtraSyntax[];
+    readonly extraSyntaxSupported: readonly AIMarkdownRenderExtraSyntax[];
     /** Display optimization abilities to enable. */
-    displayOptimizeAbilities: AIMarkdownRenderDisplayOptimizeAbility[];
+    readonly displayOptimizeAbilities: readonly AIMarkdownRenderDisplayOptimizeAbility[];
+    /**
+     * Whether to enable block-level memoization across renders.
+     *
+     * When `true` (default), the renderer splits each rendered document into
+     * per-block units and memoizes the React subtree of each block by its
+     * source identity (`raw + occurrence + ctx + position`). Unchanged blocks
+     * during streaming skip `toJsxRuntime` and React reconcile work, reducing
+     * per-frame cost roughly proportional to the unchanged fraction of the
+     * document. Output is byte-identical to the disabled path.
+     *
+     * When `false`, the renderer falls back to the legacy bare `<Markdown>`
+     * flow — every render runs the full pipeline end-to-end with no
+     * cross-frame reuse. Useful for debugging, for environments where the
+     * extra `useRef`-backed cache is undesirable, or as an escape hatch if a
+     * future custom rehype plugin interacts badly with the plan abstraction.
+     *
+     * @default true
+     */
+    readonly blockMemoEnabled: boolean;
 }
 /**
  * Sensible default configuration with all extensions and optimizations enabled.
- * Frozen to prevent accidental mutation.
+ * Frozen at both the top level and the inner arrays so this shared singleton
+ * cannot be mutated by any consumer.
  */
-declare const defaultAIMarkdownRenderConfig: AIMarkdownRenderConfig;
+declare const defaultAIMarkdownRenderConfig: Readonly<{
+    extraSyntaxSupported: readonly AIMarkdownRenderExtraSyntax[];
+    displayOptimizeAbilities: readonly AIMarkdownRenderDisplayOptimizeAbility[];
+    blockMemoEnabled: true;
+}>;
 /**
  * Arbitrary metadata that consumers can pass through a dedicated React context.
  * Custom renderers can access this via the {@link useAIMarkdownMetadata} hook.
@@ -140,6 +186,22 @@ interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkd
     variant: AIMarkdownVariant;
     /** Active color scheme. */
     colorScheme: AIMarkdownColorScheme;
+    /**
+     * Stable identifier unique to this *logical markdown document*. Used as
+     * the id namespace for clobberable attributes (`id`, hash hrefs) so two
+     * documents on the same page don't cross-link — e.g. clicking a footnote
+     * `[^1]` in message A won't scroll to the `[^1]` definition in message B.
+     *
+     * Named `documentId` (not `instanceId`) intentionally: when one logical
+     * markdown document is split into multiple `<AIMarkdown>` instances
+     * (chunked / streamed rendering), every chunk SHOULD share the same value
+     * so id-prefixes align across the chunks.
+     *
+     * Auto-generated via React's `useId()` (SSR-safe, stable across
+     * re-renders) when not provided by the consumer; consumer-supplied values
+     * always win.
+     */
+    documentId: string;
     /** Active render configuration. */
     config: TConfig;
 }
@@ -494,16 +556,59 @@ type PartialObjectDeep<ObjectType extends object, Options extends Required<Parti
  * Must be called inside a component rendered as a descendant of `<AIMarkdown>`.
  * Throws if called outside the provider boundary.
  *
- * @typeParam TConfig - Expected configuration shape (defaults to {@link AIMarkdownRenderConfig}).
- * @returns The current render state (does not include metadata — use {@link useAIMarkdownMetadata} for that).
+ * ### `TConfig` is a caller-asserted type, not a derived one
  *
- * @example
+ * The generic parameter is **an assertion the caller makes about the provider
+ * above it** — TypeScript cannot verify that the actual `<AIMarkdown>` in the
+ * tree was configured with a matching `defaultConfig: TConfig`. If you pass a
+ * wider `TConfig` than what the provider actually carries, field access at
+ * compile time will look fine but resolve to `undefined` at runtime.
+ *
+ * The intended pattern is that extension packages (e.g. `@ai-react-markdown/mantine`)
+ * ship their own narrow wrapper hook alongside a matching `defaultConfig`, so the
+ * assertion is made *once* next to the provider configuration and consumers of the
+ * wrapper never touch the raw generic.
+ *
+ * @typeParam TConfig - Caller-asserted configuration shape (defaults to
+ *   {@link AIMarkdownRenderConfig}). Must be aligned with the provider's
+ *   `defaultConfig` — the library does not check this at runtime.
+ * @returns The current render state (does not include metadata — use
+ *   {@link useAIMarkdownMetadata} for that).
+ * @throws If called outside an `<AIMarkdown>` provider tree.
+ *
+ * @example Base usage — no generic, always safe:
  * ```tsx
  * function CustomCodeBlock({ children }: PropsWithChildren) {
  *   const { streaming, config } = useAIMarkdownRenderState();
- *   // ...
+ *   // config: AIMarkdownRenderConfig — guaranteed shape
+ * }
+ * ```
+ *
+ * @example Wrapper-hook pattern — the intended way to use an extended TConfig:
+ * ```tsx
+ * // In your extension package (pin the assertion in one place):
+ * interface ExtendedConfig extends AIMarkdownRenderConfig {
+ *   themeMode: 'light' | 'dark' | 'auto';
  * }
+ * export const extendedDefaultConfig: ExtendedConfig = {
+ *   ...defaultAIMarkdownRenderConfig,
+ *   themeMode: 'auto',
+ * };
+ * export const useExtendedRenderState = () =>
+ *   useAIMarkdownRenderState<ExtendedConfig>();
+ *
+ * // Provider is always configured with the matching defaultConfig:
+ * <AIMarkdown defaultConfig={extendedDefaultConfig} ...>{children}</AIMarkdown>
+ *
+ * // Consumers use the narrow wrapper — no raw generic anywhere:
+ * const { config } = useExtendedRenderState();
+ * config.themeMode; // correctly typed and present at runtime
  * ```
+ *
+ * @see `@ai-react-markdown/mantine` — real-world reference. Its
+ *   `MantineAIMarkdownRenderConfig`, `defaultMantineAIMarkdownRenderConfig`,
+ *   `<MantineAIMarkdown>` (which passes `defaultConfig` by default), and
+ *   `useMantineAIMarkdownRenderState` implement this exact pattern.
  */
 declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig>(): AIMarkdownRenderState<TConfig>;
 /**
@@ -513,8 +618,24 @@ declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig
  * do not cause re-renders in components that only consume render state
  * (e.g. {@link MarkdownContent}).
  *
- * @typeParam TMetadata - Expected metadata shape (defaults to {@link AIMarkdownMetadata}).
+ * ### `TMetadata` is a caller-asserted type
+ *
+ * Same contract as {@link useAIMarkdownRenderState} — the generic is an
+ * assertion about the `metadata` prop passed to the provider above, not a
+ * value TypeScript can derive.  Unlike render-state config, metadata has no
+ * runtime fallback: if the provider received no `metadata`, the hook returns
+ * `undefined` regardless of the asserted type. Prefer wrapping this hook in
+ * a project-local hook that pins `TMetadata` next to the call site that
+ * actually provides the metadata.
+ *
+ * @typeParam TMetadata - Caller-asserted metadata shape (defaults to
+ *   {@link AIMarkdownMetadata}). Caller is responsible for ensuring the
+ *   provider's `metadata` prop matches this shape.
  * @returns The current metadata, or `undefined` if none was provided.
+ *
+ * @see `@ai-react-markdown/mantine` — `useMantineAIMarkdownMetadata` applies
+ *   the wrapper pattern to this hook, pinning `MantineAIMarkdownMetadata` in
+ *   a single location.
  */
 declare function useAIMarkdownMetadata<TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata>(): TMetadata | undefined;
 /** Props for {@link AIMarkdownRenderStateProvider}. */
@@ -523,6 +644,19 @@ interface AIMarkdownRenderStateProviderProps<TConfig extends AIMarkdownRenderCon
     fontSize: string;
     variant: AIMarkdownVariant;
     colorScheme: AIMarkdownColorScheme;
+    /**
+     * Logical-document identifier used as the id namespace for clobberable
+     * attributes (id / hash hrefs). Optional — when omitted, the provider
+     * auto-generates one via {@link useId} so the provider stays drop-in
+     * usable for direct consumers (e.g. extension packages that don't go
+     * through `<AIMarkdown>`).
+     *
+     * Pass the SAME value to multiple providers / `<AIMarkdown>` instances
+     * when they render chunks of the same logical document — their id
+     * prefixes will align so cross-chunk anchors and (once the parser sees
+     * the full doc) footnote navigation work.
+     */
+    documentId?: string;
     /**
      * Base default config to merge against. When omitted, falls back to
      * {@link defaultAIMarkdownRenderConfig}. Sub-packages (e.g. mantine) can
@@ -572,6 +706,14 @@ type AIMDContentPreprocessor = (content: string) => string;
  * returned, preventing unnecessary re-renders in downstream `useMemo` / `useEffect`
  * consumers that depend on reference equality.
  *
+ * The ref is updated in a layout effect (not during render) so that the cached
+ * reference only advances on COMMITTED renders. In concurrent mode a render
+ * may be discarded (e.g. by Suspense); writing to the ref during render would
+ * let values from discarded renders pollute the cache and leak into subsequent
+ * committed renders. Layout effects run synchronously right after commit, which
+ * closes the window where a same-tick re-render could otherwise observe a stale
+ * `ref.current` and hand back an outdated reference.
+ *
  * @typeParam T - The value type.
  * @param value - The potentially new value to stabilize.
  * @returns The previous reference when deep-equal, otherwise the new value.
@@ -632,12 +774,34 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
     variant?: AIMarkdownVariant;
     /** Color scheme name. Defaults to `'light'`. */
     colorScheme?: AIMarkdownColorScheme;
+    /**
+     * Stable identifier for the *logical markdown document* this `<AIMarkdown>`
+     * is rendering. Used as the id namespace for all clobberable attributes
+     * (`id`, hash hrefs) so two documents on the same page do not cross-link —
+     * e.g. clicking a footnote `[^1]` in message A will not scroll to the
+     * `[^1]` definition in message B.
+     *
+     * Why `documentId` and not `instanceId`: when one logical document is
+     * split across multiple `<AIMarkdown>` instances (chunked / streamed
+     * rendering), every chunk should share the SAME `documentId` so their
+     * id-prefixes line up. The id is per-document, not per-React-instance.
+     *
+     * When omitted, an id is auto-generated via React's `useId()` (SSR-safe
+     * and stable across re-renders). Pass an explicit value when you need
+     * deterministic ids (snapshot tests, cross-component deep links) or when
+     * multiple instances render the same logical document.
+     *
+     * Consumer-supplied values pass through `encodeURIComponent` at the prefix
+     * construction site, so any string is safe — including ids with reserved
+     * characters like `:`, `/`, or spaces.
+     */
+    documentId?: string;
 }
 /**
  * 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, }: 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, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_runtime.JSX.Element;
 declare const _default: typeof AIMarkdownComponent;
 
 export { type AIMDContentPreprocessor, type AIMarkdownColorScheme, type AIMarkdownCustomComponents, type AIMarkdownExtraStylesComponent, type AIMarkdownExtraStylesProps, type AIMarkdownMetadata, type AIMarkdownProps, type AIMarkdownRenderConfig, AIMarkdownRenderDisplayOptimizeAbility, AIMarkdownRenderExtraSyntax, type AIMarkdownRenderState, type AIMarkdownTypographyComponent, type AIMarkdownTypographyProps, type AIMarkdownVariant, type PartialDeep, _default as default, defaultAIMarkdownRenderConfig, useAIMarkdownMetadata, useAIMarkdownRenderState, useStableValue };