@ai-react-markdown/core 1.3.0 → 1.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { JSX, ComponentType, PropsWithChildren, CSSProperties } from 'react';
-import { Element } from 'hast';
+import { JSX, ComponentType, PropsWithChildren, CSSProperties, FC } from 'react';
+import { Element, ElementContent } from 'hast';
 
 /**
  * Public types for the local Markdown wrapper. Ported 1:1 from react-markdown
@@ -93,6 +93,18 @@ interface AIMarkdownRenderConfig {
      * @default true
      */
     readonly blockMemoEnabled: boolean;
+    /**
+     * Default `true`. Controls Direction A: whether `<AIMarkdown>` (standalone
+     * mode) protects orphan `footnoteDefinition` nodes from being silently
+     * dropped by `mdast-util-to-hast` when no corresponding `footnoteReference`
+     * exists. Implemented via a custom `footnoteDefinition` handler that
+     * proactively registers the label in `state.footnoteOrder`.
+     *
+     * When `<AIMarkdown>` is wrapped in `<AIMarkdownDocuments>`, this field
+     * is ignored — the wrapper's `preserveOrphanReferences` prop overrides
+     * unconditionally for all chunks under it.
+     */
+    readonly preserveOrphanReferences: boolean;
 }
 /**
  * Sensible default configuration with all extensions and optimizations enabled.
@@ -103,6 +115,7 @@ declare const defaultAIMarkdownRenderConfig: Readonly<{
     extraSyntaxSupported: readonly AIMarkdownRenderExtraSyntax[];
     displayOptimizeAbilities: readonly AIMarkdownRenderDisplayOptimizeAbility[];
     blockMemoEnabled: true;
+    preserveOrphanReferences: true;
 }>;
 /**
  * Arbitrary metadata that consumers can pass through a dedicated React context.
@@ -202,6 +215,14 @@ interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkd
      * always win.
      */
     documentId: string;
+    /**
+     * Per-document URI-safe id prefix used by all clobberable attributes
+     * (`id="…"` / `href="#…"`). Derived once by the provider as
+     * `${encodeURIComponent(documentId)}-user-content-` and exposed here so
+     * downstream consumers (placeholder components, cross-chunk anchor logic)
+     * read a single canonical source instead of recomputing locally.
+     */
+    clobberPrefix: string;
     /** Active render configuration. */
     config: TConfig;
 }
@@ -726,6 +747,138 @@ type AIMDContentPreprocessor = (content: string) => string;
  */
 declare function useStableValue<T>(value: T): T;
 
+/**
+ * Cross-chunk shared state. Holds per-chunk contributions (refs, defs,
+ * linkDefs) keyed by Symbol identity allocated via useId reactId, with
+ * refcount + microtask-deferred reclamation for React Strict Mode safety.
+ *
+ * @module components/documentRegistry
+ */
+
+interface FootnoteDef {
+    /** Already-normalized identifier (uppercase). Used as dictionary key for
+     *  case-insensitive cross-chunk lookups. */
+    identifier: string;
+    /** mdast's case-folded identifier — the exact string mdast-util-to-hast
+     *  emits in `<li id="${clobberPrefix}fn-${sourceIdentifier}">` and that
+     *  `FootnoteSupNumber` mirrors in its anchor href. Needed so the aggregate
+     *  footer's `<li id>` and backref href match the inline `<sup>`'s href
+     *  exactly (otherwise hash navigation breaks). Optional so unit-test
+     *  fixtures don't need to fabricate it; production data always supplies it. */
+    sourceIdentifier?: string;
+    /** Content extracted from the source markdown footnote definition. */
+    contentSource: string;
+    /** Per-def hast body (the def's mdast children after mdast-util-to-hast
+     *  conversion). Drives AggregateFootnotesIfLast to render the consolidated
+     *  footer at the end of each document's last chunk. Optional so unit-test
+     *  fixtures can build minimal FootnoteDef objects without producing hast. */
+    bodyHast?: ElementContent[];
+}
+interface LinkDef {
+    /** Already-normalized identifier (uppercase). */
+    identifier: string;
+    url: string;
+    title?: string;
+}
+type RefKind = 'footnote' | 'link' | 'image';
+interface RefRecord {
+    /** Already-normalized identifier (uppercase). */
+    label: string;
+    /** Which markdown reference space this entry belongs to. Footnote refs,
+     *  link refs, and image refs occupy disjoint namespaces in GFM, so they
+     *  must be filtered separately when computing footnote numbers / refcounts. */
+    kind: RefKind;
+    referenceType?: 'full' | 'collapsed' | 'shortcut';
+}
+interface ChunkData {
+    refs: RefRecord[];
+    defs: Map<string, FootnoteDef>;
+    linkDefs: Map<string, LinkDef>;
+    ownFootnoteLabels: Set<string>;
+    ownLinkLabels: Set<string>;
+}
+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. */
+    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. */
+    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. */
+    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. */
+    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;
+    resolveLinkDef(label: string): LinkDef | null;
+    getRefsForLabel(label: string): number;
+    /** Map a chunk-local footnote-ref occurrence index (1-based, as emitted by
+     *  `customMdastHandlers`) to the corresponding document-wide occurrence
+     *  index across all chunks. Used by `FootnoteSupNumber` to build a unique
+     *  `id="fnref-X-N"` for each ref instance and by `AggregateFootnotesIfLast`
+     *  to enumerate per-occurrence backrefs. Returns `null` if the ref isn't
+     *  registered yet (registry mid-flight). */
+    globalOccurrenceForRef(chunkSym: symbol, label: string, localOccurrence: number): number | null;
+}
+
+/**
+ * Optional outer wrapper enabling cross-chunk coordination for any
+ * `<AIMarkdown>` instances rendered as descendants. Each unique
+ * `documentId` partitions its own Registry.
+ *
+ * Without this wrapper, `<AIMarkdown>` instances render independently
+ * (current behavior). With it, multiple chunks sharing a `documentId`
+ * coordinate footnote numbering, linkReference/imageReference resolution,
+ * and anchor jumps across chunks.
+ *
+ * @module components/AIMarkdownDocuments
+ */
+
+interface AIMarkdownDocumentsProps extends PropsWithChildren {
+    /**
+     * Default `true`. Unconditionally controls orphan-reference protection
+     * for all chunks under this wrapper, overriding their individual
+     * `config.preserveOrphanReferences`. Does not control cross-chunk
+     * coordination itself (that's gated by wrapper presence + `documentId`).
+     */
+    preserveOrphanReferences?: boolean;
+}
+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.
+ *
+ * Callers should treat `null` as "no coordination; run standalone path."
+ */
+declare function useDocumentRegistry(documentId: string | undefined): Registry | null;
+
 /**
  * Props for the `<AIMarkdown>` component.
  *
@@ -804,4 +957,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, }: 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 };
+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, _default as default, defaultAIMarkdownRenderConfig, useAIMarkdownMetadata, useAIMarkdownRenderState, useDocumentRegistry, useStableValue };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { JSX, ComponentType, PropsWithChildren, CSSProperties } from 'react';
-import { Element } from 'hast';
+import { JSX, ComponentType, PropsWithChildren, CSSProperties, FC } from 'react';
+import { Element, ElementContent } from 'hast';
 
 /**
  * Public types for the local Markdown wrapper. Ported 1:1 from react-markdown
@@ -93,6 +93,18 @@ interface AIMarkdownRenderConfig {
      * @default true
      */
     readonly blockMemoEnabled: boolean;
+    /**
+     * Default `true`. Controls Direction A: whether `<AIMarkdown>` (standalone
+     * mode) protects orphan `footnoteDefinition` nodes from being silently
+     * dropped by `mdast-util-to-hast` when no corresponding `footnoteReference`
+     * exists. Implemented via a custom `footnoteDefinition` handler that
+     * proactively registers the label in `state.footnoteOrder`.
+     *
+     * When `<AIMarkdown>` is wrapped in `<AIMarkdownDocuments>`, this field
+     * is ignored — the wrapper's `preserveOrphanReferences` prop overrides
+     * unconditionally for all chunks under it.
+     */
+    readonly preserveOrphanReferences: boolean;
 }
 /**
  * Sensible default configuration with all extensions and optimizations enabled.
@@ -103,6 +115,7 @@ declare const defaultAIMarkdownRenderConfig: Readonly<{
     extraSyntaxSupported: readonly AIMarkdownRenderExtraSyntax[];
     displayOptimizeAbilities: readonly AIMarkdownRenderDisplayOptimizeAbility[];
     blockMemoEnabled: true;
+    preserveOrphanReferences: true;
 }>;
 /**
  * Arbitrary metadata that consumers can pass through a dedicated React context.
@@ -202,6 +215,14 @@ interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkd
      * always win.
      */
     documentId: string;
+    /**
+     * Per-document URI-safe id prefix used by all clobberable attributes
+     * (`id="…"` / `href="#…"`). Derived once by the provider as
+     * `${encodeURIComponent(documentId)}-user-content-` and exposed here so
+     * downstream consumers (placeholder components, cross-chunk anchor logic)
+     * read a single canonical source instead of recomputing locally.
+     */
+    clobberPrefix: string;
     /** Active render configuration. */
     config: TConfig;
 }
@@ -726,6 +747,138 @@ type AIMDContentPreprocessor = (content: string) => string;
  */
 declare function useStableValue<T>(value: T): T;
 
+/**
+ * Cross-chunk shared state. Holds per-chunk contributions (refs, defs,
+ * linkDefs) keyed by Symbol identity allocated via useId reactId, with
+ * refcount + microtask-deferred reclamation for React Strict Mode safety.
+ *
+ * @module components/documentRegistry
+ */
+
+interface FootnoteDef {
+    /** Already-normalized identifier (uppercase). Used as dictionary key for
+     *  case-insensitive cross-chunk lookups. */
+    identifier: string;
+    /** mdast's case-folded identifier — the exact string mdast-util-to-hast
+     *  emits in `<li id="${clobberPrefix}fn-${sourceIdentifier}">` and that
+     *  `FootnoteSupNumber` mirrors in its anchor href. Needed so the aggregate
+     *  footer's `<li id>` and backref href match the inline `<sup>`'s href
+     *  exactly (otherwise hash navigation breaks). Optional so unit-test
+     *  fixtures don't need to fabricate it; production data always supplies it. */
+    sourceIdentifier?: string;
+    /** Content extracted from the source markdown footnote definition. */
+    contentSource: string;
+    /** Per-def hast body (the def's mdast children after mdast-util-to-hast
+     *  conversion). Drives AggregateFootnotesIfLast to render the consolidated
+     *  footer at the end of each document's last chunk. Optional so unit-test
+     *  fixtures can build minimal FootnoteDef objects without producing hast. */
+    bodyHast?: ElementContent[];
+}
+interface LinkDef {
+    /** Already-normalized identifier (uppercase). */
+    identifier: string;
+    url: string;
+    title?: string;
+}
+type RefKind = 'footnote' | 'link' | 'image';
+interface RefRecord {
+    /** Already-normalized identifier (uppercase). */
+    label: string;
+    /** Which markdown reference space this entry belongs to. Footnote refs,
+     *  link refs, and image refs occupy disjoint namespaces in GFM, so they
+     *  must be filtered separately when computing footnote numbers / refcounts. */
+    kind: RefKind;
+    referenceType?: 'full' | 'collapsed' | 'shortcut';
+}
+interface ChunkData {
+    refs: RefRecord[];
+    defs: Map<string, FootnoteDef>;
+    linkDefs: Map<string, LinkDef>;
+    ownFootnoteLabels: Set<string>;
+    ownLinkLabels: Set<string>;
+}
+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. */
+    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. */
+    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. */
+    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. */
+    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;
+    resolveLinkDef(label: string): LinkDef | null;
+    getRefsForLabel(label: string): number;
+    /** Map a chunk-local footnote-ref occurrence index (1-based, as emitted by
+     *  `customMdastHandlers`) to the corresponding document-wide occurrence
+     *  index across all chunks. Used by `FootnoteSupNumber` to build a unique
+     *  `id="fnref-X-N"` for each ref instance and by `AggregateFootnotesIfLast`
+     *  to enumerate per-occurrence backrefs. Returns `null` if the ref isn't
+     *  registered yet (registry mid-flight). */
+    globalOccurrenceForRef(chunkSym: symbol, label: string, localOccurrence: number): number | null;
+}
+
+/**
+ * Optional outer wrapper enabling cross-chunk coordination for any
+ * `<AIMarkdown>` instances rendered as descendants. Each unique
+ * `documentId` partitions its own Registry.
+ *
+ * Without this wrapper, `<AIMarkdown>` instances render independently
+ * (current behavior). With it, multiple chunks sharing a `documentId`
+ * coordinate footnote numbering, linkReference/imageReference resolution,
+ * and anchor jumps across chunks.
+ *
+ * @module components/AIMarkdownDocuments
+ */
+
+interface AIMarkdownDocumentsProps extends PropsWithChildren {
+    /**
+     * Default `true`. Unconditionally controls orphan-reference protection
+     * for all chunks under this wrapper, overriding their individual
+     * `config.preserveOrphanReferences`. Does not control cross-chunk
+     * coordination itself (that's gated by wrapper presence + `documentId`).
+     */
+    preserveOrphanReferences?: boolean;
+}
+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.
+ *
+ * Callers should treat `null` as "no coordination; run standalone path."
+ */
+declare function useDocumentRegistry(documentId: string | undefined): Registry | null;
+
 /**
  * Props for the `<AIMarkdown>` component.
  *
@@ -804,4 +957,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, }: 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 };
+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, _default as default, defaultAIMarkdownRenderConfig, useAIMarkdownMetadata, useAIMarkdownRenderState, useDocumentRegistry, useStableValue };