@ai-react-markdown/core 1.4.2 → 1.4.4

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { JSX, ComponentType, PropsWithChildren, CSSProperties, FC } from 'react';
 import { Element, ElementContent } from 'hast';
+import { defaultSchema } from 'rehype-sanitize';
 
 /**
  * Public types for the local Markdown wrapper. Ported 1:1 from react-markdown
@@ -17,6 +18,24 @@ interface ExtraProps {
 type Components = {
     [Key in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[Key] & ExtraProps> | keyof JSX.IntrinsicElements;
 };
+/** Transform every URL on every element attribute. Return null/empty to strip. */
+type UrlTransform = (url: string, key: string, node: Readonly<Element>) => string | null | undefined;
+
+/**
+ * Default URL transform — same allowlist as react-markdown / GitHub.
+ *
+ * @module components/markdown/urlTransform
+ */
+
+/**
+ * Make a URL safe.
+ *
+ * Allows `http`, `https`, `irc`, `ircs`, `mailto`, and `xmpp` protocols, plus
+ * URLs relative to the current protocol (e.g. `/foo`). Other protocols are
+ * stripped to the empty string. Mirrors GitHub's behaviour and matches
+ * `micromark-util-sanitize-uri` minus the URL-encoding pass.
+ */
+declare const defaultUrlTransform: UrlTransform;
 
 /**
  * Core type definitions, enums, and default configuration for ai-react-markdown.
@@ -299,6 +318,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 */
 
 
 
@@ -645,7 +674,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
  *
@@ -722,6 +751,97 @@ 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'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 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
+ */
+
+/**
+ * The full `rehype-sanitize` schema type. Re-exported as the canonical
+ * library-internal alias so other modules don't each redeclare
+ * `typeof defaultSchema`.
+ *
+ * The shape is owned by `rehype-sanitize`; consumers should treat it as
+ * tracking that upstream type — it may evolve across rehype-sanitize major
+ * versions.
+ */
+type SanitizeSchema = typeof defaultSchema;
+/**
+ * Build a sanitize schema by mutating (or replacing) a deep clone of the
+ * library default.
+ *
+ * Designed to be called ONCE at module scope so the returned object has a
+ * stable identity across renders — passing it directly into
+ * `<AIMarkdown sanitizeSchema={…}>` keeps the block-memo cache warm.
+ *
+ * @example Append a custom URL protocol via mutation:
+ * ```ts
+ * const SCHEMA = extendSanitizeSchema((s) => {
+ *   s.protocols!.href!.push('myapp');
+ *   s.protocols!.src!.push('myapp');
+ * });
+ *
+ * function App() {
+ *   return <AIMarkdown content={…} sanitizeSchema={SCHEMA} />;
+ * }
+ * ```
+ *
+ * @example Return-style replacement for wider edits:
+ * ```ts
+ * const SCHEMA = extendSanitizeSchema((s) => ({
+ *   ...s,
+ *   tagNames: [...(s.tagNames ?? []), 'my-widget'],
+ * }));
+ * ```
+ *
+ * @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
+ * `<AIMarkdown>` and the exported {@link defaultUrlTransform} for
+ * composition. Keep the two protocol lists in sync.
+ *
+ * ### Footguns
+ *
+ * - **Reassigning the local parameter** (`(s) => { s = { …new schema… }; }`)
+ *   does NOT replace the draft — JS only rebinds the local variable. Either
+ *   mutate the original draft or `return` the new object explicitly.
+ * - **Returning `null`** is treated the same as returning nothing (the
+ *   modified draft is used). The TypeScript signature does not permit
+ *   `null`, but JS callers or `as`-casted code paths could silently hit
+ *   this. Prefer `return` with no value, or an explicit `return draft;`.
+ * - **Throwing inside the modifier** propagates to the call site
+ *   uncaught — there is no try/catch. Callers usually invoke this once at
+ *   module load, where a thrown error surfaces as a startup-time crash and
+ *   is the correct failure mode.
+ *
+ * @param modifier - Receives a deep clone of the library default. Mutate it
+ *   freely; either return the (possibly different) result, or return
+ *   nothing to use the mutated draft. Returning `undefined` (and, by
+ *   convention, `null`) is treated the same as a mutate-only call.
+ * @returns A new `Schema` object — never the library default singleton.
+ */
+declare function extendSanitizeSchema(modifier: (draft: SanitizeSchema) => SanitizeSchema | void): SanitizeSchema;
+
 /**
  * Hook for referential stability of deep-equal values.
  *
@@ -805,45 +925,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
@@ -957,12 +1094,98 @@ interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRen
      * characters like `:`, `/`, or spaces.
      */
     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 `''`.
+     *
+     * **Recommended pattern**: compose with the exported
+     * {@link defaultUrlTransform} so the built-in XSS protections survive,
+     * and define the result at module scope so its identity is stable across
+     * renders:
+     *
+     * ```ts
+     * import AIMarkdown, { defaultUrlTransform } from '@ai-react-markdown/core';
+     *
+     * const ALLOWED = /^(myapp|tel):/i;
+     * const URL_TRANSFORM = (url, key, node) =>
+     *   ALLOWED.test(url) ? url : defaultUrlTransform(url, key, node);
+     *
+     * function App() {
+     *   return <AIMarkdown urlTransform={URL_TRANSFORM} ... />;
+     * }
+     * ```
+     *
+     * **Regex-escaping**: scheme names per RFC 3986 may contain `+`, `-`, and
+     * `.` (e.g. `web+app`, `coap+tcp`). All three are regex metacharacters,
+     * so write `/^web\+app:/i` rather than `/^web+app:/i`. The latter would
+     * match URLs starting with `we`, `wee`, `weee`, … and silently broaden
+     * the allowlist.
+     *
+     * **Reference stability matters.** The block-memo cache treats this prop
+     * 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
+     * `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.
+     *
+     * **API stability**: the `UrlTransform` type tracks the upstream
+     * `react-markdown` shape and may change with its major versions.
+     */
+    urlTransform?: UrlTransform | null;
+    /**
+     * 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.
+     *
+     * **Recommended pattern**: build the schema with {@link extendSanitizeSchema}
+     * (mutate-and-return form) so those library additions stay intact, and
+     * define the result at module scope:
+     *
+     * ```ts
+     * import AIMarkdown, { extendSanitizeSchema } from '@ai-react-markdown/core';
+     *
+     * const SCHEMA = extendSanitizeSchema((s) => {
+     *   s.protocols.href.push('myapp');
+     *   s.protocols.src.push('myapp');
+     * });
+     *
+     * function App() {
+     *   return <AIMarkdown sanitizeSchema={SCHEMA} ... />;
+     * }
+     * ```
+     *
+     * **Footgun**: hand-rolling a schema (e.g. spreading from
+     * `rehype-sanitize`'s `defaultSchema` directly) silently drops the
+     * cross-chunk tag allowlist — coordinated multi-chunk rendering will then
+     * lose its placeholders. Prefer the helper unless you have a specific
+     * reason to opt out.
+     *
+     * **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.
+     */
+    sanitizeSchema?: SanitizeSchema;
 }
 /**
  * Root component that preprocesses markdown content and renders it through
  * a configurable remark/rehype pipeline wrapped in typography and style layers.
  */
-declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, defaultConfig, config, metadata, Typography, ExtraStyles, variant, colorScheme, documentId, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_runtime.JSX.Element;
+declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, defaultConfig, config, metadata, Typography, ExtraStyles, variant, colorScheme, documentId, urlTransform, sanitizeSchema, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_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, _default as default, defaultAIMarkdownRenderConfig, 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 };