@trinityui/design-system 2.11.1 → 2.13.0

package/dist/components/AI/AIQueryDisclosure.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview AIQueryDisclosure: the query behind an AI answer, shown on demand (master-plan F-14).
+ * @module components/AI/AIQueryDisclosure
+ *
+ * A thin composition of the shared blocks (no local reimplementation):
+ *
+ * - **Trigger.** D's Disclosure (useDisclosure's inline mode): a `<button type="button">` with
+ *   `aria-expanded` and `aria-controls`. The label is constant ('Query', or 'SQL query' through
+ *   `titleWithLanguage`); `aria-expanded` carries the state and the label never toggles (APG).
+ *   No heading by default (ADR-19); `headingLevel` wraps the trigger in one.
+ * - **Code.** D's CodeBlock: `<pre dir="ltr"><code>`, so the query never mirrors in a
+ *   right-to-left page. While it scrolls it is a focusable group named `codeLabel` (axe
+ *   scrollable-region-focusable). The code area scrolls past `maxHeight`
+ *   (default `theme.spacing(40)`).
+ * - **Copy.** D's CopyButton after the code (Tab reaches the code, then the button): the copy goes
+ *   through `useClipboard` (useCopyAction); 'Query copied' or 'Copy failed' is announced once.
+ *   `onCopy(query)` runs after a successful write, and `AICopyInteraction { success }` is
+ *   reported to AIConfigProvider either way.
+ * - **Metadata.** D's KeyValueList (inline tiles): rows, duration (Intl.NumberFormat, unit
+ *   'second'), dataset, dialect and executed-at (`useFormatAsOf`: the provider's time zone, else
+ *   'UTC' while hydrating, so server and client agree). An inner container query stacks the
+ *   tiles below the 'compact' container width (E-19).
+ * - **Streaming.** A Skeleton replaces the code; the trigger is `aria-disabled` and described by
+ *   the visible reason ('The query is still being generated'). Nothing is announced.
+ * - **Empty.** An empty query that is not streaming renders nothing, with one development warning
+ *   from an effect (ADR-30).
+ * - **Reveal.** With `metadata.queryId` inside a response (AIResponseSourcesProvider, F-08), the
+ *   view registers `{ reveal }`: a source chip's 'Show query' opens it and, after the open
+ *   commit, moves focus to its trigger.
+ * - **Naming.** `expanded`, `defaultExpanded` and `onExpandedChange(expanded, event?)` follow the
+ *   AI family (AISourcesPanel) with the ADR-04 (9) event argument; they map onto useDisclosure's
+ *   open state (the NAMING exception, F-20).
+ * - **Telemetry.** `AIQueryViewInteraction` on expand and collapse; never the query text.
+ *
+ * @example
+ * ```tsx
+ * import { AIQueryDisclosure } from '@trinityui/design-system';
+ *
+ * <AIQueryDisclosure
+ *   query="SELECT region, SUM(net) FROM revenue GROUP BY region"
+ *   language="SQL"
+ *   metadata={{ rowCount: 4, durationMs: 845, dataset: 'finance.revenue' }}
+ * />
+ * ```
+ */
+import * as React from 'react';
+import { type SxProps, type Theme } from '@mui/material/styles';
+import type { HeadingLevel } from '../shared/headingLevel';
+import { type TrinitySlotProps } from '../shared/rootProps';
+import type { AIQueryMetadata } from './types/hitl';
+/**
+ * AIQueryDisclosure's own props.
+ *
+ * @since 2.13.0
+ */
+export interface AIQueryDisclosureOwnProps {
+    /** The query text, as it ran. An empty query renders nothing unless `streaming`. */
+    query: string;
+    /**
+     * The query language as shown, for example 'SQL'. The trigger reads 'SQL query' and the
+     * scrolling code area is named 'SQL query text'.
+     */
+    language?: string;
+    /** The trigger label. It never changes with the state. @default 'Query' (or `titleWithLanguage`) */
+    title?: string;
+    /** Facts about the run: row count, duration, dataset, dialect, when it ran, and its `queryId`. */
+    metadata?: AIQueryMetadata;
+    /** Controlled expansion. */
+    expanded?: boolean;
+    /** Initial expansion when uncontrolled. @default false */
+    defaultExpanded?: boolean;
+    /**
+     * Called with the requested expansion and, when the user caused it, the event. A reveal from a
+     * source chip's 'Show query' has no event.
+     */
+    onExpandedChange?: (expanded: boolean, event?: React.SyntheticEvent) => void;
+    /** The code area scrolls vertically beyond this height. @default theme.spacing(40) */
+    maxHeight?: number | string;
+    /**
+     * The query is still being generated: a Skeleton replaces the code and the trigger is
+     * `aria-disabled` with its visible reason. Adapters map a block's `status` onto it.
+     * @default false
+     */
+    streaming?: boolean;
+    /** Called with the query after it was written to the clipboard. */
+    onCopy?: (query: string) => void | Promise<void>;
+    /** Id of the response block that holds the query, reported with the interactions. */
+    blockId?: string;
+    /** Wraps the trigger in a heading of this level. No heading by default (ADR-19). */
+    headingLevel?: HeadingLevel;
+    className?: string;
+    sx?: SxProps<Theme>;
+    /**
+     * Props for the parts (ADR-04 (6)): `trigger` (the disclosure button), `panel` (the region it
+     * shows), `code` (the `<pre>`), `metadata` (the `<dl>`) and `copyButton`.
+     */
+    slotProps?: {
+        trigger?: TrinitySlotProps<HTMLButtonElement>;
+        panel?: TrinitySlotProps<HTMLDivElement>;
+        code?: TrinitySlotProps<HTMLPreElement>;
+        metadata?: TrinitySlotProps<HTMLDListElement>;
+        copyButton?: TrinitySlotProps<HTMLButtonElement>;
+    };
+}
+/**
+ * Props of {@link AIQueryDisclosure}: its own props plus the root `<div>`'s HTML attributes
+ * (ADR-04).
+ *
+ * @since 2.13.0
+ */
+export type AIQueryDisclosureProps = AIQueryDisclosureOwnProps & Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'title' | keyof AIQueryDisclosureOwnProps>;
+/**
+ * The query behind an AI answer, shown on demand: a disclosure with the query as left-to-right
+ * code, a copy button and the run's metadata. See the module notes.
+ *
+ * @since 2.13.0
+ */
+export declare const AIQueryDisclosure: React.ForwardRefExoticComponent<AIQueryDisclosureOwnProps & Omit<React.HTMLAttributes<HTMLDivElement>, "color" | keyof AIQueryDisclosureOwnProps> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=AIQueryDisclosure.d.ts.map

package/dist/components/AI/AIQueryDisclosure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIQueryDisclosure.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIQueryDisclosure.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAS1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI1E,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,cAAc,CAAC;AAK/D;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,cAAc,KAAK,IAAI,CAAC;IAC7E,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;QAC9C,KAAK,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;QACzC,IAAI,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;QACxC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;QAC9C,UAAU,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;KAClD,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,GAC5D,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,yBAAyB,CAAC,CAAC;AA4ClG;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,0LAgK5B,CAAC"}

package/dist/components/AI/AIRelatedQuestions.d.ts

@@ -2,28 +2,56 @@
  * @fileoverview AIRelatedQuestions component.
  * @module components/AI/AIRelatedQuestions
  * AI Related Questions Component
- * Collapsible panel displaying related/follow-up questions with filled background surface
+ * Collapsible panel displaying related/follow-up questions with filled background surface.
+ * A question is a string or an {@link AIRelatedQuestion}; a verified one shows the
+ * AIVerificationBadge ('Verified', glyph and text) after its text (G-24a).
  *
  * @example
  * ```tsx
  *  import { AIRelatedQuestions } from '@trinityui/design-system';
  *
  *  <AIRelatedQuestions
- *    questions="Example"
+ *    questions={['Compare by region', { id: 'q4', text: 'Project Q4', verified: true }]}
+ *    onQuestionSelect={(question, index) => ask(question.text)}
  *  />
  *  ```
  */
 import React from 'react';
 import { SxProps, Theme } from '@mui/material';
+import { type TrinityRootProps } from '../shared/rootProps';
 /**
- * Props for AIRelatedQuestions component.
+ * One related question, when it carries more than its text (G-24a).
+ * @since 2.13.0
  */
-export interface AIRelatedQuestionsProps {
-    /** List of related questions */
-    questions: string[];
-    /** Callback when a question is clicked */
+export interface AIRelatedQuestion {
+    /** A stable id, used as the list key. Without one the key is the text and its occurrence. */
+    id?: string;
+    /** The question: shown, and passed to `onQuestionClick`. */
+    text: string;
+    /**
+     * A pre-checked suggestion (R15): the verification badge ('Verified', a glyph and the word,
+     * never colour alone) follows the text and is part of the button's name.
+     */
+    verified?: boolean;
+}
+/**
+ * AIRelatedQuestions' own props.
+ */
+export interface AIRelatedQuestionsOwnProps {
+    /**
+     * List of related questions: strings, or {@link AIRelatedQuestion} objects (since 2.13.0)
+     * for an id and the verified flag. Both can be mixed.
+     */
+    questions: Array<string | AIRelatedQuestion>;
+    /** Callback when a question is clicked: the question's text. */
     onQuestionClick?: (question: string) => void;
-    /** Panel title */
+    /**
+     * Callback when a question is clicked: the question (a string is passed as `{ text }`) and its
+     * index. Fires alongside `onQuestionClick`.
+     * @since 2.13.0
+     */
+    onQuestionSelect?: (question: AIRelatedQuestion, index: number) => void;
+    /** Panel title. Default: the `ai.relatedQuestions.title` string ('Related questions'). */
     title?: string;
     /** Whether panel is initially expanded */
     defaultExpanded?: boolean;
@@ -31,15 +59,26 @@ export interface AIRelatedQuestionsProps {
     expanded?: boolean;
     /** Callback when expanded state changes */
     onExpandedChange?: (expanded: boolean) => void;
-    /** Empty state title when no questions */
+    /** Empty state title when no questions. Default: `ai.relatedQuestions.emptyTitle`. */
     emptyTitle?: string;
-    /** Empty state description */
+    /** Empty state description. Default: `ai.relatedQuestions.emptyDescription`. */
     emptyDescription?: string;
     /** Show empty state instead of hiding */
     showEmpty?: boolean;
-    /** Custom sx props */
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the panel's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
+/**
+ * Props for AIRelatedQuestions: its own props, plus the HTML attributes of its root `div`
+ * (`id`, `data-*`, `aria-*`), which reach the root (ADR-04, WI-40).
+ */
+export interface AIRelatedQuestionsProps extends AIRelatedQuestionsOwnProps, TrinityRootProps<HTMLDivElement, AIRelatedQuestionsOwnProps> {
+}
 /**
  * AI Related Questions - Collapsible panel with clickable follow-up questions
  * Features:

package/dist/components/AI/AIRelatedQuestions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIRelatedQuestions.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIRelatedQuestions.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AACxC,OAAO,EAWL,OAAO,EACP,KAAK,EACN,MAAM,eAAe,CAAC;AAQvB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,gCAAgC;IAChC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0CAA0C;IAC1C,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,gGAiM9B,CAAC;AAEF,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"AIRelatedQuestions.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIRelatedQuestions.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAUL,OAAO,EACP,KAAK,EACN,MAAM,eAAe,CAAC;AAQvB,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAO1E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,EAAE,KAAK,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;IAC7C,gEAAgE;IAChE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxE,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,0BAA0B,EAAE,gBAAgB,CAAC,cAAc,EAAE,0BAA0B,CAAC;CAAG;AAM5I;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,gGA4M9B,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/components/AI/AIResponseRenderer.d.ts

@@ -5,48 +5,160 @@
  * Iterates over `AIResponse.blocks` and dispatches each block to a renderer.
  * Pure rendering — no layout wrapper, no business logic, no AIMessage chrome.
  *
- * **Block types supported natively:**
- * - `text` — rendered via `AITextBlock`
+ * **Resolution order** (ADR-05 (2)), for each block, the first step that answers wins:
+ * 1. `renderBlock(block)`: a node renders, `null` skips the block, `undefined` falls through
+ *    (`onRenderBlock` is its deprecated alias; `renderBlock` wins when both are passed);
+ * 2. `blockRenderers[block.type]`: a block renderer component (`null` skips the block);
+ * 3. the renderers a host provides (ChatThread and the other organisms; `null` skips the block);
+ * 4. the built-in renderer: `text` blocks render through `AITextBlock`;
+ * 5. nothing: the block is skipped, with one development warning per block type.
  *
- * **Everything else** (table / chart / image / form / actions / custom types)
- * goes through the `onRenderBlock` escape hatch, giving the consumer full
- * control over rendering. If `onRenderBlock` is not provided and the block
- * type is not `text`, the block is skipped with a console warning.
+ * Table, chart, image, form and actions blocks are consumer-rendered. The interactive blocks
+ * (query, clarification, plan-review) render through block renderers, which receive
+ * `onBlockEvent`, `readOnly` and `onActionError`.
  *
- * This design keeps the component focused (text-only natively) while giving
- * consumers a clean extension point. The previous version embedded hard-coded
- * placeholders for block types that were never implemented — those are now
- * the consumer's responsibility via `onRenderBlock`.
+ * **Ids.** A block id comes from the model, so it is data, never a DOM id: each block's root
+ * carries `data-block-id={block.id}` and the DOM id `getBlockDomId(idPrefix, block.id)` (G-OD12).
+ * Equal ids inside one response still get their own React keys and DOM ids.
+ *
+ * **Sources.** The renderer provides the response's `sources` to its blocks, so a consumer table
+ * or chart renderer reads a cell's or point's sources with `useBlockSources(block.id)` (F-08).
+ * Text blocks with `citations: true` render their `[^id]` markers as source chips numbered by
+ * `response.sources` (F-13, G-37+). While `streaming`, a marker that names no source yet is
+ * hidden instead of shown as written; when the response completes the markers resolve in place.
+ *
+ * **Headings.** `headingOffset` moves markdown headings down (`#` becomes h2 with 1). It defaults
+ * to 1 inside a ChatThread, so a response's `#` is never the page's h1 there, and to 0 standalone.
+ *
+ * **Error** (G-34, G-OD8): `response.error` renders after the blocks as an inline error Alert
+ * titled 'This response failed' (`ai.responseRenderer.errorTitle`), with `error.message` as plain
+ * text. The Alert has no live role: standalone, the renderer announces the title and message
+ * once, assertively, through `useAnnounce`; inside a thread (InThreadContext) it announces
+ * nothing, because the thread's log reads the added content. Retry belongs to AIMessage's footer.
+ *
+ * **Isolation** (G-39+): each block renders inside its own error boundary. A block whose renderer
+ * throws shows 'This part of the response is unavailable' (`ai.responseRenderer.blockUnavailable`)
+ * in its place, read-only and not live, and `onBlockError` reports it; the other blocks and
+ * messages keep rendering. A text block whose `content` is not a string shows the same state.
+ *
+ * **Diagnostics** (development only, once each, from effects): a block type with no renderer, an
+ * interactive block without an id, repeated block ids, and a renderer whose identity changes on
+ * three commits in a row (define renderers at module scope or memoize them).
  *
  * @example
  * ```tsx
  * <AIResponseRenderer
  *   response={response}
- *   onRenderBlock={(block) => {
+ *   renderBlock={(block) => {
  *     if (block.type === 'chart') return <MyChart data={block.data} />;
- *     if (block.type === 'table') return <MyTable rows={block.rows} />;
- *     return null; // fall back to default handling
+ *     if (block.type === 'image') return null; // skip the block
+ *     return undefined; // fall through to blockRenderers and the built-in text renderer
  *   }}
  * />
+ *
+ * const blockRenderers = {
+ *   table: ({ block, id }) => <MyTable id={id} data-block-id={block.id} rows={block.rows} />,
+ * } satisfies AIResponseRendererProps['blockRenderers'];
+ *
+ * <AIResponseRenderer response={response} blockRenderers={blockRenderers} />
  * ```
  */
 import React from 'react';
-import { type AIResponse, type AIResponseBlock } from './types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { type AIResponse, type AIResponseBlock } from './types/response';
+import type { AIActionErrorContext, AIBlockEvent } from './types/hitl';
+import { type AIBlockRendererMap } from './blockRendererContext';
 /**
- * Props for AIResponseRenderer component.
+ * Props for AIResponseRenderer component: its own props plus the root `<div>`'s HTML
+ * attributes (ADR-04). The renderer owns no root attribute, so `className`, `id`, `data-*` and
+ * `aria-*` all reach the root.
  */
-export interface AIResponseRendererProps {
+export interface AIResponseRendererProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'> {
     /** The AIResponse object to render */
     response: AIResponse;
-    /** Gap between blocks (default: aiSpacing.sm) */
+    /**
+     * Gap between blocks. A number is pixels (`blockGap={12}` is 12px); omit it to use theme
+     * spacing, `theme.spacing(aiSpacing.sm)` (8px in the default theme), which follows the theme's
+     * spacing and its presets. Values below 2 or with a fraction log a development warning: they
+     * are usually theme spacing units passed as pixels.
+     */
     blockGap?: number;
     /**
-     * Extensibility hook for non-text block types (table, chart, image, form,
-     * actions, custom). Called for every block the renderer encounters. Return
-     * a ReactNode to render, `null` to skip, or `undefined` to fall back to the
-     * default handling (which renders text blocks and skips everything else).
+     * Renders any block first (step 1 of the resolution order), text blocks included. Called for
+     * every block. Return a node to render it, `null` to skip it, or `undefined` to fall through to
+     * `blockRenderers`, a host's renderers and the built-in text renderer.
+     *
+     * @since 2.13.0
+     */
+    renderBlock?: (block: AIResponseBlock) => React.ReactNode | null | undefined;
+    /**
+     * @deprecated Use `renderBlock`, which takes the same function (or `blockRenderers` for one
+     * component per block type). Removed in v3.0. Passing it logs one development warning;
+     * `renderBlock` wins when both are passed.
      */
     onRenderBlock?: (block: AIResponseBlock) => React.ReactNode | undefined;
+    /**
+     * Block renderers by block type (step 2 of the resolution order). Each receives
+     * `AIBlockRendererProps` for its own block type. An entry wins over a renderer a host provides;
+     * `null` skips that block type. Keep the object and its components stable (module scope or
+     * `useMemo`).
+     *
+     * @since 2.13.0
+     */
+    blockRenderers?: AIBlockRendererMap;
+    /**
+     * Called with what the user did in an interactive block (`AIBlockEvent`). A returned promise
+     * drives the block's pending state, and its rejection the block's error.
+     *
+     * @since 2.13.0
+     */
+    onBlockEvent?: (event: AIBlockEvent) => void | Promise<void>;
+    /**
+     * The response is history: block renderers show content and recorded answers without controls.
+     * @default false
+     * @since 2.13.0
+     */
+    readOnly?: boolean;
+    /**
+     * Called when an action inside a block fails, with `{ source: 'block', blockId }`.
+     *
+     * @since 2.13.0
+     */
+    onActionError?: (error: unknown, context: AIActionErrorContext) => void;
+    /**
+     * Called when a block fails to render: its renderer threw, so the block shows a read-only
+     * 'unavailable' state while the other blocks keep rendering. Receives the error and the block's
+     * `id` and `type`.
+     *
+     * @since 2.13.0
+     */
+    onBlockError?: (error: unknown, context: {
+        blockId?: string;
+        type: string;
+    }) => void;
+    /**
+     * Prefix of the blocks' DOM ids (`getBlockDomId(idPrefix, block.id)`). Defaults to the root's
+     * `id`, which is generated when you pass none.
+     *
+     * @since 2.13.0
+     */
+    idPrefix?: string;
+    /**
+     * The response is still streaming in: a citation marker that names no source yet is hidden
+     * (it may be cut off or its source may not have arrived), not shown as written.
+     * @default false
+     * @since 2.13.0
+     */
+    streaming?: boolean;
+    /**
+     * Moves the markdown headings of text blocks down by this many levels (clamped at h6). Default:
+     * 1 inside a ChatThread (InThreadContext), so `#` renders as h2 under the page's h1; 0
+     * standalone.
+     * @since 2.13.0
+     */
+    headingOffset?: 0 | 1 | 2 | 3 | 4 | 5;
+    /** Styles for the root, applied after the renderer's own (object, function or array). */
+    sx?: SxProps<Theme>;
 }
 /**
  * AIResponseRenderer - Iterates over AIResponse blocks and dispatches each

package/dist/components/AI/AIResponseRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIResponseRenderer.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIResponseRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAe,MAAM,SAAS,CAAC;AAQ7E;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,QAAQ,EAAE,UAAU,CAAC;IACrB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;CACzE;AAMD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,gGA2B9B,CAAC;AAqDF,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"AIResponseRenderer.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIResponseRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAQvE,OAAO,EAAyC,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAcxG;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClG,sCAAsC;IACtC,QAAQ,EAAE,UAAU,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,KAAK,CAAC,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7E;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;IACxE;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACxE;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrF;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,yFAAyF;IACzF,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AA+HD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,gGAuF9B,CAAC;AAmIF,eAAe,kBAAkB,CAAC"}

package/dist/components/AI/AIResponseSourcesContext.d.ts

@@ -0,0 +1,83 @@
+import type { Context, ReactElement, ReactNode } from 'react';
+import type { AIResponseSource } from './types/response';
+/** The key of a table cell: block id, row (rowKey value or 0-based index) and column key. */
+export declare function cellKey(blockId: string, row: string | number, column: string): string;
+/** The key of a chart point: block id, series `dataKey` and 0-based data index. */
+export declare function pointKey(blockId: string, series: string, index: number): string;
+/** The lookups of one `sources` array. Built once per array identity. */
+export interface ResponseSourcesIndex {
+    /** The sources, as given. */
+    readonly sources: readonly AIResponseSource[];
+    /** Source id to its 1-based number. The first occurrence of a repeated id wins. */
+    readonly numberById: ReadonlyMap<string, number>;
+    /** Block id to the sources that list it in `blockIds`, in `sources` order. */
+    readonly byBlock: ReadonlyMap<string, readonly AIResponseSource[]>;
+    /** `cellKey(...)` to the sources whose `cellRefs` name that cell, in `sources` order. */
+    readonly byCell: ReadonlyMap<string, readonly AIResponseSource[]>;
+    /** `pointKey(...)` to the sources whose `pointRefs` name that point, in `sources` order. */
+    readonly byPoint: ReadonlyMap<string, readonly AIResponseSource[]>;
+}
+/** Builds every lookup in one pass over the sources and their refs (no rescans later). */
+export declare function indexResponseSources(sources: readonly AIResponseSource[]): ResponseSourcesIndex;
+/** What a query view registers: how to open itself and move focus to its trigger. */
+export interface QueryRegistration {
+    reveal: () => void;
+}
+/** The registry of query views by `queryId`. One per provider, created once. */
+export interface QueryRegistry {
+    /** Registers a query view. Returns the function that unregisters it (only that registration). */
+    registerQuery(queryId: string, registration: QueryRegistration): () => void;
+    /** Reveals the query with `queryId`. `false` when no view registered it. */
+    revealQuery(queryId: string): boolean;
+    /** Whether a view registered `queryId`. Read it through `useIsQueryRegistered` to re-render on changes. */
+    isQueryRegistered(queryId: string): boolean;
+    /** Subscribes to registrations and unregistrations (`useSyncExternalStore`). */
+    subscribe(listener: () => void): () => void;
+}
+/** Creates an empty query registry. */
+export declare function createQueryRegistry(): QueryRegistry;
+/** What `useResponseSources` returns inside a provider. Stable while `sources` and `unresolvedCitations` stay the same. */
+export interface ResponseSourcesContextValue extends QueryRegistry {
+    /** The indexed sources. */
+    readonly index: ResponseSourcesIndex;
+    /** How text blocks render a citation marker that names no source: as written, or not at all (while streaming). */
+    readonly unresolvedCitations: 'literal' | 'hide';
+    /** The 1-based number of a source, `undefined` for an unknown id. */
+    getSourceNumber(sourceId: string): number | undefined;
+}
+/**
+ * The context behind `useResponseSources`. Created with `@__PURE__` and no other module-level
+ * statement, so bundles that never mount the provider drop it (OD-A3).
+ *
+ * @internal
+ */
+export declare const AIResponseSourcesContext: Context<ResponseSourcesContextValue | null>;
+/** Props of {@link AIResponseSourcesProvider}. */
+export interface AIResponseSourcesProviderProps {
+    /** The response's sources. Keep the array's identity while it does not change; append while streaming. */
+    sources?: readonly AIResponseSource[];
+    /** How text blocks render a citation marker that names no source. Default `'literal'`; G passes `'hide'` while streaming. */
+    unresolvedCitations?: 'literal' | 'hide';
+    children?: ReactNode;
+}
+/**
+ * Provides a response's sources, their lookups and the query registry to the blocks inside it.
+ *
+ * @internal
+ */
+export declare function AIResponseSourcesProvider({ sources, unresolvedCitations, children }: AIResponseSourcesProviderProps): ReactElement;
+/**
+ * The nearest response's sources, lookups and query registry; `null` outside an
+ * `AIResponseSourcesProvider`.
+ *
+ * @internal
+ */
+export declare function useResponseSources(): ResponseSourcesContextValue | null;
+/**
+ * Whether a query view registered `queryId` in the nearest provider; re-renders when that
+ * changes. `false` outside a provider, during server rendering and for an undefined id.
+ *
+ * @internal
+ */
+export declare function useIsQueryRegistered(queryId: string | undefined): boolean;
+//# sourceMappingURL=AIResponseSourcesContext.d.ts.map

package/dist/components/AI/AIResponseSourcesContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIResponseSourcesContext.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIResponseSourcesContext.ts"],"names":[],"mappings":"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"}