glirastes 0.4.0 → 0.5.1

package/dist/cjs/react/tool-renderers/registry.d.ts

@@ -0,0 +1,31 @@
+import type { ComponentType } from 'react';
+import type { SchemaLike } from '../../types.js';
+export interface ToolResultRendererProps<TOutput = unknown> {
+    definitionId: string;
+    /** Model-facing tool name as stored in the message. */
+    toolName: string;
+    schemaVersion: number;
+    output: TOutput;
+}
+/**
+ * A local, compact result component for one tool. `outputSchema` guards the
+ * stored output: messages written by an older tool version fall back to an
+ * older renderer version or the default block instead of crashing.
+ */
+export interface ToolResultRenderer<TOutput = unknown> {
+    definitionId: string;
+    schemaVersion: number;
+    outputSchema: SchemaLike<TOutput>;
+    component: ComponentType<ToolResultRendererProps<TOutput>>;
+}
+export type AnyToolResultRenderer = ToolResultRenderer<any>;
+export interface ResolvedToolResultRenderer {
+    renderer: AnyToolResultRenderer;
+    output: unknown;
+}
+export interface ToolResultRendererRegistry {
+    readonly size: number;
+    resolve(toolName: string, output: unknown): ResolvedToolResultRenderer | undefined;
+}
+export declare function defineToolResultRenderer<TOutput>(renderer: ToolResultRenderer<TOutput>): ToolResultRenderer<TOutput>;
+export declare function createToolResultRendererRegistry(renderers: ReadonlyArray<AnyToolResultRenderer>): ToolResultRendererRegistry;

package/dist/cjs/react/tool-renderers/registry.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineToolResultRenderer = defineToolResultRenderer;
+exports.createToolResultRendererRegistry = createToolResultRendererRegistry;
+const DEFINITION_ID = /^[A-Za-z0-9_.-]{1,200}$/;
+function defineToolResultRenderer(renderer) {
+    return renderer;
+}
+function modelFacingName(definitionId) {
+    return definitionId.replace(/\./g, '_');
+}
+function createToolResultRendererRegistry(renderers) {
+    const byName = new Map();
+    const seen = new Set();
+    for (const renderer of renderers) {
+        if (!DEFINITION_ID.test(renderer.definitionId)) {
+            throw new Error(`Invalid renderer definitionId: ${renderer.definitionId}`);
+        }
+        if (!Number.isInteger(renderer.schemaVersion) || renderer.schemaVersion < 1) {
+            throw new Error(`Renderer ${renderer.definitionId} needs a positive integer schemaVersion`);
+        }
+        const identity = `${renderer.definitionId}@${renderer.schemaVersion}`;
+        if (seen.has(identity))
+            throw new Error(`Duplicate renderer: ${identity}`);
+        seen.add(identity);
+        for (const name of new Set([renderer.definitionId, modelFacingName(renderer.definitionId)])) {
+            const list = byName.get(name) ?? [];
+            list.push(renderer);
+            list.sort((left, right) => right.schemaVersion - left.schemaVersion);
+            byName.set(name, list);
+        }
+    }
+    return Object.freeze({
+        size: seen.size,
+        resolve(toolName, output) {
+            for (const renderer of byName.get(toolName) ?? []) {
+                let parsed;
+                try {
+                    parsed = renderer.outputSchema.safeParse(output);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.success)
+                    return { renderer, output: parsed.data };
+            }
+            return undefined;
+        },
+    });
+}

package/dist/cjs/react/tool-renderers/renderer-boundary.d.ts

@@ -0,0 +1,18 @@
+import { Component, type ReactNode } from 'react';
+interface RendererBoundaryProps {
+    fallback: ReactNode;
+    children: ReactNode;
+}
+/** A failing custom renderer degrades to the default tool result block. */
+export declare class RendererBoundary extends Component<RendererBoundaryProps, {
+    failed: boolean;
+}> {
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    render(): ReactNode;
+}
+export {};

package/dist/cjs/react/tool-renderers/renderer-boundary.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RendererBoundary = void 0;
+const react_1 = require("react");
+/** A failing custom renderer degrades to the default tool result block. */
+class RendererBoundary extends react_1.Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+exports.RendererBoundary = RendererBoundary;

package/dist/cjs/react/transports/vercel/vercel-ai-chat.d.ts

@@ -46,4 +46,4 @@ export interface VercelAiChatProps extends AiChatProviderConfig, FloatingChatUIP
  * and `FloatingChatUIProps` (title, defaultOpen, width, height, draggable,
  * resizable, shortcut, showClearButton) are accepted as top-level props.
  */
-export declare function VercelAiChat({ endpoint, headers, autoResumeOnApproval, bodyExtras, sessions, title, defaultOpen, draggable, resizable, size, hideTriggerWhenOpen, shortcut, showClearButton, confirmClear, showSessionSwitcher, headerActions, triggerIcon, showMic, children, ...providerConfig }: VercelAiChatProps): import("react/jsx-runtime").JSX.Element;
+export declare function VercelAiChat({ endpoint, headers, autoResumeOnApproval, bodyExtras, sessions, title, open, onOpenChange, defaultOpen, draggable, resizable, size, hideTriggerWhenOpen, shortcut, showClearButton, confirmClear, showSessionSwitcher, headerActions, triggerIcon, showMic, welcomeMessage, portal, mode, defaultMode, onModeChange, layoutControls, collapsed, onCollapsedChange, sidebarWidth, minSidebarWidth, maxSidebarWidth, onSidebarWidthChange, layoutLabels, keepMounted, persistDimensions, persistSidebarWidth, children, ...providerConfig }: VercelAiChatProps): import("react/jsx-runtime").JSX.Element;

package/dist/cjs/react/transports/vercel/vercel-ai-chat.js

@@ -29,7 +29,7 @@ const vercel_js_1 = require("../vercel.js");
  * and `FloatingChatUIProps` (title, defaultOpen, width, height, draggable,
  * resizable, shortcut, showClearButton) are accepted as top-level props.
  */
-function VercelAiChat({ endpoint, headers, autoResumeOnApproval, bodyExtras, sessions, title, defaultOpen, draggable, resizable, size, hideTriggerWhenOpen, shortcut, showClearButton, confirmClear, showSessionSwitcher, headerActions, triggerIcon, showMic, children, ...providerConfig }) {
+function VercelAiChat({ endpoint, headers, autoResumeOnApproval, bodyExtras, sessions, title, open, onOpenChange, defaultOpen, draggable, resizable, size, hideTriggerWhenOpen, shortcut, showClearButton, confirmClear, showSessionSwitcher, headerActions, triggerIcon, showMic, welcomeMessage, portal, mode, defaultMode, onModeChange, layoutControls, collapsed, onCollapsedChange, sidebarWidth, minSidebarWidth, maxSidebarWidth, onSidebarWidthChange, layoutLabels, keepMounted, persistDimensions, persistSidebarWidth, children, ...providerConfig }) {
     const [activeId, setActiveId] = (0, react_1.useState)(() => {
         if (sessions?.activeId)
             return sessions.activeId;
@@ -77,5 +77,5 @@ function VercelAiChat({ endpoint, headers, autoResumeOnApproval, bodyExtras, ses
             },
         };
     }, [sessions, activeId, providerConfig.session]);
-    return ((0, jsx_runtime_1.jsx)(ai_chat_provider_js_1.AiChatProvider, { transport: transport, ...providerConfig, session: effectiveSession, children: children ?? ((0, jsx_runtime_1.jsx)(floating_chat_ui_js_1.FloatingChatUI, { title: title, defaultOpen: defaultOpen, draggable: draggable, resizable: resizable, size: size, hideTriggerWhenOpen: hideTriggerWhenOpen, shortcut: shortcut, showClearButton: showClearButton, confirmClear: confirmClear, showSessionSwitcher: showSessionSwitcher, headerActions: headerActions, triggerIcon: triggerIcon, showMic: showMic })) }));
+    return ((0, jsx_runtime_1.jsx)(ai_chat_provider_js_1.AiChatProvider, { transport: transport, ...providerConfig, session: effectiveSession, children: children ?? ((0, jsx_runtime_1.jsx)(floating_chat_ui_js_1.FloatingChatUI, { title: title, open: open, onOpenChange: onOpenChange, defaultOpen: defaultOpen, draggable: draggable, resizable: resizable, size: size, hideTriggerWhenOpen: hideTriggerWhenOpen, shortcut: shortcut, showClearButton: showClearButton, confirmClear: confirmClear, showSessionSwitcher: showSessionSwitcher, headerActions: headerActions, triggerIcon: triggerIcon, showMic: showMic, welcomeMessage: welcomeMessage, portal: portal, mode: mode, defaultMode: defaultMode, onModeChange: onModeChange, layoutControls: layoutControls, collapsed: collapsed, onCollapsedChange: onCollapsedChange, sidebarWidth: sidebarWidth, minSidebarWidth: minSidebarWidth, maxSidebarWidth: maxSidebarWidth, onSidebarWidthChange: onSidebarWidthChange, layoutLabels: layoutLabels, keepMounted: keepMounted, persistDimensions: persistDimensions, persistSidebarWidth: persistSidebarWidth })) }));
 }

package/dist/cjs/react/transports/vercel.d.ts

@@ -8,6 +8,12 @@
  * Requires `@ai-sdk/react` and `ai` as peer dependencies.
  */
 import type { ChatTransport, ChatTransportConfig } from '../types.js';
+/**
+ * Body of each chat request: the client actions the open page handles, so
+ * the server refuses the others, plus the host's extras.
+ * @internal
+ */
+export declare function chatRequestBody(extras: Record<string, unknown> | (() => Record<string, unknown>) | undefined): Record<string, unknown>;
 export interface UseVercelAiChatTransportOptions extends ChatTransportConfig {
     /**
      * When true, automatically resumes generation after all pending

package/dist/cjs/react/transports/vercel.js

@@ -9,10 +9,21 @@
  * Requires `@ai-sdk/react` and `ai` as peer dependencies.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.chatRequestBody = chatRequestBody;
 exports.useVercelAiChatTransport = useVercelAiChatTransport;
 const react_1 = require("react");
 const react_2 = require("@ai-sdk/react");
 const ai_1 = require("ai");
+const ui_action_bus_js_1 = require("../../browser/ui-action-bus.js");
+/**
+ * Body of each chat request: the client actions the open page handles, so
+ * the server refuses the others, plus the host's extras.
+ * @internal
+ */
+function chatRequestBody(extras) {
+    const resolved = !extras ? {} : typeof extras === 'function' ? extras() : extras;
+    return { glirastesClientActions: (0, ui_action_bus_js_1.getDefaultUiActionBus)().registeredActionIds(), ...resolved };
+}
 function useVercelAiChatTransport(options) {
     const { endpoint, headers: userHeaders, onData, autoResumeOnApproval = true, bodyExtras, } = options;
     const headersRef = (0, react_1.useRef)(userHeaders);
@@ -36,12 +47,7 @@ function useVercelAiChatTransport(options) {
                 return typeof h === 'function' ? h() : h ?? {};
             }
             : undefined,
-        body: () => {
-            const extras = bodyExtrasRef.current;
-            if (!extras)
-                return {};
-            return typeof extras === 'function' ? extras() : extras;
-        },
+        body: () => chatRequestBody(bodyExtrasRef.current),
     }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps -- headersRef/bodyExtrasRef are stable
     [endpoint, !!userHeaders]);

package/dist/cjs/react/types.d.ts

@@ -1,4 +1,9 @@
 import type { ReactNode, ReactElement, ComponentType, MouseEvent as ReactMouseEvent } from 'react';
+import type { UiActionBus } from '../browser/ui-action-bus.js';
+import type { ClarificationRequest } from '../contracts/clarification.js';
+import type { AnyToolResultRenderer } from './tool-renderers/registry.js';
+import type { ChatInteractionsConfig, PendingChatCommand } from './interactions/registry.js';
+export type { ClarificationOption, ClarificationRequest, ClarificationTarget, } from '../contracts/clarification.js';
 /**
  * Data part emitted by the transport during streaming.
  * Used for pipeline reports, truncation, and custom data events.
@@ -82,16 +87,28 @@ export interface UseDeepgramTranscriptionOptions {
     baseUrl?: string;
     /** Returns the current auth token for WebSocket authentication */
     getToken?: () => string | null | undefined;
+    /**
+     * The app's own speech provider instead of the Deepgram stream, for example
+     * a `RecordedSttAdapter`. `baseUrl` and `getToken` are then unused. Keep
+     * one instance across renders; a new one ends the running recording.
+     */
+    adapter?: import('./stt/controller.js').SttProviderAdapter;
     onInterimTranscript?: (text: string) => void;
     onError?: (error: string) => void;
 }
 export interface UseDeepgramTranscriptionReturn {
+    phase: import('./stt/controller.js').SttSessionPhase;
     isRecording: boolean;
     isConnecting: boolean;
     error: string | null;
     transcript: string;
-    startRecording: () => Promise<void>;
-    stopRecording: () => string;
+    interimTranscript: string;
+    displayTranscript: string;
+    stream: MediaStream | null;
+    startRecording: (previousDraft?: string) => Promise<void>;
+    stopRecording: () => Promise<string>;
+    cancelRecording: () => Promise<string>;
+    retry: () => Promise<void>;
 }
 export interface VoiceInputButtonProps {
     onTranscript: (text: string) => void;
@@ -105,6 +122,13 @@ export interface VoiceInputButtonProps {
 }
 export interface RecordingBarProps {
     isConnecting: boolean;
+    /** The existing authoritative recorder stream; never opens another mic. */
+    stream?: MediaStream | null;
+    /**
+     * Live final plus interim transcript shown next to the waveform. It is
+     * never written into the editor before Stop.
+     */
+    transcript?: string;
     onCancel: () => void;
     onStop: () => void;
     variant: 'trigger' | 'inline';
@@ -161,7 +185,7 @@ export interface PipelineState {
     totalSteps: number;
     finishReason?: string;
     maxSteps: number;
-    stepLimitSource: 'explicit' | 'module' | 'safety';
+    stepLimitSource: 'explicit' | 'module' | 'safety' | 'runtime-budget';
     updatedAt: string;
     message?: string;
 }
@@ -171,6 +195,16 @@ export interface MentionResult {
     label: string;
     description?: string;
     icon?: string;
+    /** Stable list identity when several providers may return the same id. */
+    key?: string;
+    /** Token text after the trigger; defaults to a slug of `label`. */
+    slug?: string;
+    /** Tool-backed commands: the catalog definition to run (see `CompletionItem`). */
+    definitionId?: string;
+    /** Tool-backed commands: fixed arguments for the definition. */
+    args?: Readonly<Record<string, unknown>>;
+    /** Entity actions offered next to this result (see `CompletionItem.actions`). */
+    actions?: ReadonlyArray<CompletionItemAction>;
 }
 export interface MentionData {
     id: string;
@@ -184,6 +218,73 @@ export interface MentionConfig {
     types: string[];
     serialize?: MentionSerializationConfig;
 }
+/**
+ * What the app UI knows about the signed-in user. Providers use it to hide
+ * entries; it never authorizes anything (the server and the app do).
+ */
+export interface CompletionPermissionContext {
+    readonly roles?: ReadonlyArray<string>;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+export interface CompletionItem {
+    /** The app's own stable id; it reaches the model via the mention marker. */
+    id: string;
+    /** Mention type, e.g. `user`, `task`, `command`. */
+    type: string;
+    label: string;
+    description?: string;
+    slug?: string;
+    /**
+     * Tool-backed commands: the catalog definition to run. Set it when `id` is
+     * not the definition id (several commands share one definition) or `args`
+     * are present; it reaches the model next to the id on send.
+     */
+    definitionId?: string;
+    /** Fixed arguments for `definitionId` (needs `definitionId`), e.g. `{ destination: 'overview' }`. */
+    args?: Readonly<Record<string, unknown>>;
+    /**
+     * Context actions of an `@` entity (e.g. "Open", "Complete"), offered next
+     * to it in the list and reachable by keyboard (ArrowRight/ArrowLeft).
+     */
+    actions?: ReadonlyArray<CompletionItemAction>;
+}
+export interface CompletionItemAction {
+    /** Action id (`[A-Za-z0-9._-]`, max 200). */
+    id: string;
+    label: string;
+}
+export interface CompletionSearchRequest {
+    query: string;
+    trigger: string;
+    /** Aborted when a newer search starts; pass it to `fetch`. */
+    signal: AbortSignal;
+    context: CompletionPermissionContext;
+    limit: number;
+}
+export interface ChatCompletionProvider {
+    /** Stable, unique provider id (`[a-z0-9-]`, max 40). */
+    id: string;
+    trigger: '@' | '/';
+    search(request: CompletionSearchRequest): Promise<ReadonlyArray<CompletionItem>> | ReadonlyArray<CompletionItem>;
+}
+/** A catalog UI tool offered as a `/` command. */
+export interface UiToolCommandSource {
+    readonly definitionId: string;
+    /**
+     * Stable, unique list identity and mention id of this command; defaults to
+     * `definitionId`. One definition can back several commands (a single
+     * `ui.navigate` with a `destination` enum becomes one command per
+     * destination). No `:` or `}`, max 200 characters.
+     */
+    readonly commandId?: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly keywords?: ReadonlyArray<string>;
+    /** Fixed arguments the command passes to the definition, e.g. `{ destination: 'overview' }`. */
+    readonly args?: Readonly<Record<string, unknown>>;
+    /** Empty or omitted: visible to everyone. */
+    readonly allowedRoles?: ReadonlyArray<string>;
+}
 export interface MentionSerializationConfig {
     enabled?: boolean;
     includeContextBlock?: boolean;
@@ -278,12 +379,37 @@ export interface ToolResultDisplayConfig {
     mode?: ToolResultDisplayMode;
     allowlist?: string[];
 }
+export interface VoicePushToTalkConfig {
+    /**
+     * Hold this combo to talk; `mod` is ⌘ on macOS and Ctrl elsewhere.
+     * Default `mod+shift+space`. `false` disables only the hotkey. Only one
+     * visible composer per page owns a combo, so it never opens two microphones.
+     */
+    hotkey?: string | false;
+    /**
+     * Holding the mic button at least this long (default 350 ms) stops on
+     * release; a shorter tap toggles recording on.
+     */
+    holdThresholdMs?: number;
+}
 export interface VoiceInputConfig {
     enabled?: boolean;
     language?: string;
     baseUrl?: string;
     /** Returns the current auth token for WebSocket authentication */
     getToken?: () => string | null | undefined;
+    /**
+     * Speech provider adapter; defaults to the Deepgram speech-stream adapter.
+     * Keep its identity stable: a new adapter restarts the controller.
+     */
+    adapter?: import('./stt/controller.js').SttProviderAdapter;
+    /** Push-to-talk in addition to tap-to-toggle; `false` keeps toggle only. */
+    pushToTalk?: VoicePushToTalkConfig | false;
+    /**
+     * Pass the current route (e.g. `usePathname()`); a change stops recording
+     * and keeps the speech as editable draft. Back/forward is detected too.
+     */
+    routeKey?: string;
     recordingBar?: {
         enabled?: boolean;
         variant?: 'trigger' | 'inline';
@@ -337,6 +463,15 @@ export interface ChatComponents {
     PipelineTimeline?: ComponentType<PipelineTimelineProps>;
     SuggestionChip?: ComponentType<SuggestionChipProps>;
     MentionChip?: ComponentType<MentionChipProps>;
+    ClarificationCard?: ComponentType<ClarificationCardProps>;
+    /** Form for the missing arguments of a `/` command or entity action. */
+    CommandArgumentsForm?: ComponentType<CommandArgumentsFormProps>;
+}
+export interface CommandArgumentsFormProps {
+    pending: PendingChatCommand;
+    /** Values by argument name, and the labels of picked entities. */
+    onSubmit: (values: Readonly<Record<string, string>>, valueLabels: Readonly<Record<string, string>>) => void;
+    onCancel: () => void;
 }
 /**
  * All user-facing strings rendered by the SDK's built-in components.
@@ -360,6 +495,9 @@ export interface ChatLocale {
     cancelButton: string;
     confirmButton: string;
     moreItemsLabel: string;
+    showAllItemsLabel: string;
+    showMoreLabel: string;
+    showLessLabel: string;
     allCountLabel: string;
     pipelineTitle: string;
     pipelineRunningLabel: string;
@@ -369,6 +507,14 @@ export interface ChatLocale {
     pipelineErrorLabel: string;
     pipelineStepLabel: string;
     pipelineApprovalPendingLabel: string;
+    activityWorkingLabel: string;
+    activityWaitingLabel: string;
+    activityDoneLabel: string;
+    activityDoneOneLabel: string;
+    activityFailedLabel: string;
+    planTitle: string;
+    /** Shown when the user sends while an approval card waits for a decision. */
+    approvalPendingHint: string;
     chatTitle: string;
     closeChatAriaLabel: string;
     clearChatAriaLabel: string;
@@ -380,23 +526,63 @@ export interface ChatLocale {
     newChatLabel: string;
     noSessionsLabel: string;
     sessionsLoadingLabel: string;
+    untitledSessionLabel: string;
     deleteSessionAriaLabel: string;
     confirmDeleteSessionPrompt: string;
+    sessionArchiveMessage: string;
     renameSessionAriaLabel: string;
     renameSessionPlaceholder: string;
+    clarificationInputLabel: string;
+    clarificationSubmitButton: string;
+    retryRecordingAriaLabel: string;
+    completionListLabel: string;
+    completionResultsLabel: string;
+    commandArgumentsLabel: string;
+    commandArgumentsSubmit: string;
+    commandArgumentsInvalid: string;
+    commandArgumentsIncomplete: string;
+    commandArgumentsAnyOption: string;
+    commandArgumentsNoMatches: string;
 }
 /** Preprocess message text before sending */
 export type OnBeforeSend = (text: string, mentions: MentionData[]) => string;
 /** Called when a tool produces output — useful for app-specific dispatching */
 export type OnToolResult = (toolName: string, result: unknown) => void;
+/** What the chat knows beyond the arguments of the call to approve. */
+export interface ApprovalDescriptionContext {
+    /** Record names the tool results of this conversation reported, by lower-case record id. */
+    names?: ReadonlyMap<string, string>;
+}
 /** Formats approval display for a given tool call */
-export type ApprovalDescriptionFn = (toolName: string, approvalId: string, args: unknown) => PendingApproval;
+export type ApprovalDescriptionFn = (toolName: string, approvalId: string, args: unknown, context?: ApprovalDescriptionContext) => PendingApproval;
 /** Translates a pipeline state message (e.g. "Stopped by user.") before rendering. */
 export type PipelineMessageTranslator = (message: string) => string;
 /** Formats a pipeline step summary for display. Receives the full step for rich formatting. */
 export type StepSummaryFormatter = (step: PipelineStepReport) => string;
 export interface AiChatProviderConfig {
     mentions?: MentionConfig;
+    /**
+     * Local compact result components per tool `definitionId` and schema
+     * version. Memoize the array. Unknown tools, outputs that fail every
+     * version's schema, and throwing renderers use the default block.
+     */
+    toolRenderers?: ReadonlyArray<AnyToolResultRenderer>;
+    /**
+     * Generic `/` and `@` providers. Memoize the array: a new identity
+     * rebuilds the search. When set, the composer uses provider search with
+     * keyboard navigation and keeps structured ids on send.
+     */
+    completionProviders?: ReadonlyArray<ChatCompletionProvider>;
+    completionContext?: CompletionPermissionContext;
+    onCompletionProviderError?: (providerId: string, error: unknown) => void;
+    /**
+     * Declarative `@` entities and `/` commands: derived `data` (from
+     * `useChatInteractionsData` or the generated module) plus app definitions
+     * (`defineChatEntity`, `defineChatCommand`). Memoize the object. A `/`
+     * command sent alone runs its tool without the model, through the server's
+     * normal authorization and confirmation.
+     */
+    chatInteractions?: ChatInteractionsConfig;
     toolResults?: ToolResultDisplayConfig;
     voice?: VoiceInputConfig;
     session?: SessionConfig;
@@ -425,7 +611,26 @@ export interface AiChatProviderConfig {
      * ```
      */
     theme?: ChatTheme;
+    /**
+     * `inline` (default) writes the theme as inline `--cm-*` variables on
+     * widget roots. `inherit` leaves them to stylesheets and host variables;
+     * `<glirastes-chat>` uses it so page CSS can theme the shadow root.
+     */
+    themeScope?: 'inline' | 'inherit';
+    /**
+     * Bring your own styles. Widget roots render `data-unstyled`, which turns
+     * every rule of the shipped stylesheet off for them and everything inside,
+     * and no theme variables are written. Markup, `data-*` hooks and
+     * `classNames` stay, so the host stylesheet styles the chat on its own.
+     */
+    unstyled?: boolean;
     onToolResult?: OnToolResult;
+    /**
+     * Bus that receives the UI actions of generated tools (`ui.navigate`,
+     * `ui.filter.<view>`, `ui.<actionId>`) after `onToolResult`. Defaults to
+     * the page-wide bus of `glirastes/browser`.
+     */
+    uiActionBus?: UiActionBus;
     onBeforeSend?: OnBeforeSend;
     approvalDescription?: ApprovalDescriptionFn;
     continueMessage?: string;
@@ -516,6 +721,8 @@ export interface PendingApproval {
     description?: string;
     /** Detail lines (e.g. "Title: My Task", "Priority: High") */
     details?: string[];
+    /** Items of array-valued detail lines, by index into `details`. */
+    detailItems?: Array<string[] | undefined>;
     /** Confirm button text override */
     confirmText?: string;
 }
@@ -574,14 +781,24 @@ export interface RichMentionInputHandle {
     focus: () => void;
     clear: () => void;
     getValue: () => string;
-    setValue: (value: string) => void;
+    /** Restore text, optionally retaining the ordered identities of its mention tokens. */
+    setValue: (value: string, mentions?: MentionData[]) => void;
     getMentions: () => MentionData[];
     addMention: (mention: MentionData) => void;
 }
+/** ARIA wiring of one option in the `@`/`/` list; spread it onto the clickable element. */
+export interface MentionDropdownOptionProps {
+    id: string;
+    role: 'option';
+    'aria-selected': boolean;
+    tabIndex: -1;
+}
 export interface MentionDropdownItemProps {
     result: MentionResult;
     isSelected: boolean;
     onClick: () => void;
+    /** Custom items must spread these onto their clickable element for keyboard and screen-reader use. */
+    optionProps?: MentionDropdownOptionProps;
 }
 export interface RichMentionInputComponents {
     DropdownItem?: ComponentType<MentionDropdownItemProps>;
@@ -593,7 +810,8 @@ export interface RichMentionInputProps {
     disabled?: boolean;
     className?: string;
     onChange?: (nextValue: string) => void;
-    onSubmit?: (message: string) => void;
+    /** Receives the text and the structured mentions (chips and commands) still in it. */
+    onSubmit?: (message: string, mentions: MentionData[]) => void;
     /** Search callback for mention autocomplete (BYOS). Return matching results for the given query and trigger character. */
     onSearch?: (query: string, trigger: string) => Promise<MentionResult[]> | MentionResult[];
     /** Mention data to render as inline chips on mount (e.g. pre-filled context from a detail view). */
@@ -602,8 +820,16 @@ export interface RichMentionInputProps {
     triggers?: string[];
     /** Component overrides for the autocomplete dropdown. */
     components?: RichMentionInputComponents;
+    /** An entity action picked next to a result (mouse, or ArrowRight then Enter). */
+    onEntityAction?: (result: MentionResult, actionId: string) => void;
+    /** Accessible name of the suggestion list. Default `Suggestions`. */
+    listLabel?: string;
+    /** Announced result count; `{count}` is replaced. Default `{count} suggestions`. */
+    resultsLabel?: string;
 }
 export interface ChatWindowHeaderRenderProps {
+    /** Insert these controls in a custom header when layoutControls is enabled. */
+    layoutControls?: ReactNode;
     onClose: () => void;
     isDragging: boolean;
     onDragStart: (e: ReactMouseEvent<HTMLElement>) => void;
@@ -629,8 +855,27 @@ export interface ChatWindowProps {
     className?: string;
     headerClassName?: string;
     bodyClassName?: string;
+    /** Keep this stable across mode changes. false reserves space in the host
+     * flex row for a sidebar; true renders an overlay in document.body. */
     portal?: boolean;
+    mode?: 'floating' | 'sidebar';
+    defaultMode?: 'floating' | 'sidebar';
+    onModeChange?: (mode: 'floating' | 'sidebar') => void;
+    /** Opt into common dock/float/collapse buttons. Default false. */
+    layoutControls?: boolean;
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Initial sidebar width; changed props resize it. Echoing onSidebarWidthChange
+     * into this prop is supported. Floating width/height remain independent. */
+    sidebarWidth?: number;
+    minSidebarWidth?: number;
+    maxSidebarWidth?: number;
+    onSidebarWidthChange?: (width: number) => void;
+    layoutLabels?: Partial<Record<'dock' | 'float' | 'collapse' | 'expand' | 'resize', string>>;
     open?: boolean;
+    /** Preserve child state while closed. Hidden content is inert; consumers must
+     * stop owned media and dismiss external portals when closing. Default false. */
+    keepMounted?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
     draggable?: boolean;
@@ -650,6 +895,9 @@ export interface ChatWindowProps {
     snapRadius?: number;
     edgeThreshold?: number;
     persistDimensions?: boolean | string;
+    /** Set false when the app persists sidebarWidth itself. Floating dimension
+     * persistence remains enabled. Default true. */
+    persistSidebarWidth?: boolean;
     onPositionChange?: (pos: {
         x: number;
         y: number;
@@ -693,6 +941,17 @@ export interface SuggestionChipProps {
 export interface SuggestionBarProps {
     className?: string;
 }
+export interface ClarificationCardProps {
+    toolCallId: string;
+    request: ClarificationRequest;
+    /** False once answered or when a newer message exists. */
+    interactive: boolean;
+    onAnswer: (answer: {
+        text: string;
+        optionId?: string;
+    }) => void;
+    className?: string;
+}
 export interface ToolResultBlockProps {
     toolName: string;
     result: unknown;
@@ -723,6 +982,10 @@ export interface AiTriggerButtonProps {
     isRecording?: boolean;
     /** Whether voice connection is being established */
     isConnecting?: boolean;
+    /** The single authoritative stream owned by the STT controller */
+    recordingStream?: MediaStream | null;
+    /** Live final plus interim transcript shown while recording */
+    recordingTranscript?: string;
     /** Called when user stops recording (red circle) */
     onStopRecording?: () => void;
     /** Called when user cancels recording (X) */