@arbidocs/blocks 0.4.2 → 0.4.4

package/dist/agents/index.js

@@ -1,6 +1,6 @@
 "use client";
-export { ACTION_LABELS, AgentAvatarField, AgentBar, AgentBarIconButton, AgentBarMenu, AgentBarNotes, AgentBarProbeAnswer, AgentBarQueuedNote, AgentBarStatus, AgentCard, AgentCreateView, AgentCreatedView, AgentCreator, AgentEditView, AgentGallery, AgentMainView, AgentSelect, AgentTypeSelector, CapabilityGrid, CapabilityTile, ConfigField, ConfigForm, ConsentActions, ConsentBulletList, ConsentCard, ConsentFootnote, ConsentHeader, ConsentMessage, ConsentNotice, ConsentPage, ConsentPermissionList, ConsentSection, ConsentStrong, ConsentText, CopyableUrl, DEFAULT_AGENT_AVATAR_FIELD_LABELS, DEFAULT_AGENT_BAR_LABELS, DEFAULT_AGENT_CARD_LABELS, DEFAULT_AGENT_CREATOR_LABELS, DEFAULT_AGENT_GALLERY_LABELS, DEFAULT_AGENT_SELECT_LABELS, DEFAULT_AGENT_STEPS_LABELS, DEFAULT_AGENT_TYPE_SELECTOR_LABELS, DEFAULT_AUTHORIZE_AGENT_LABELS, DEFAULT_CONFIG_FIELD_LABELS, DEFAULT_CONFIG_FORM_LABELS, DEFAULT_CONSENT_ACTIONS_LABELS, DEFAULT_COPYABLE_URL_LABELS, DEFAULT_LIVE_RUNS_BANNER_LABELS, DEFAULT_RECURRENCE, DEFAULT_RECURRENCE_BUILDER_LABELS, DEFAULT_SCHEMA_FORM_LABELS, DEFAULT_SKILL_CARD_LABELS, DEFAULT_SKILL_EDIT_FORM_LABELS, DEFAULT_SKILL_GENERATE_FORM_LABELS, DEFAULT_SKILL_GLOBAL_BADGE_LABELS, DEFAULT_SKILL_ROW_LABELS, DEFAULT_SKILL_VIEW_TOGGLE_LABELS, DEFAULT_SUBAGENT_ROSTER_LABELS, DEFAULT_TASKS_CHROME_LABELS, DEFAULT_TASK_COLUMN_LABELS, DEFAULT_TASK_COMPOSER_LABELS, DEFAULT_TASK_PLAN_LABELS, DEFAULT_TASK_ROW_ACTIONS_LABELS, DEFAULT_TASK_RUNS_DIALOG_LABELS, DEFAULT_TUPLE_ARRAY_FIELD_LABELS, DEFAULT_UPLOAD_TASK_ITEM_LABELS, DEFAULT_UPLOAD_TASK_LIST_LABELS, DEFAULT_WORKFLOW_CONFIG_DIALOG_LABELS, EMPTY_WORKFLOW_SCOPE, GoalCriteria, LiveRunsBanner, NewTaskEmptyAction, RecurrenceBuilder, SKILL_PROMPT_FALLBACK_PLACEHOLDER, SKILL_PROMPT_LABEL, STATUS_LABELS, SchemaForm, SkillActionButton, SkillCard, SkillDetail, SkillDetailSection, SkillEditForm, SkillFilterChips, SkillGenerateForm, SkillGlobalBadge, SkillRow, SkillTile, SkillTypeBadge, SkillViewToggle, StepDetail, StepNarration, StepOutcome, StepParams, StepRow, StepSummary, StepTrace, StepTraceSummary, SubAgentLane, SubStepGroup, SubagentRoster, TRIGGER_LABELS, TaskComposer, TaskPlan, TaskRowActions, TaskRunsDialog, TasksBulkBar, TasksToolbar, TupleArrayField, UploadTaskItem, UploadTaskList, WEEKDAYS, WorkflowConfigDialog, WorkflowLauncher, buildLaunch, buildRRule, composeWorkflowPrompt, createTaskColumns, defaultInputs, defaultTaskComposerValues, deriveAgentName, describeRRule, formatElapsed, goalProgress, humanizeSection, inferType, inputsFromContext, isEmptyWorkflowScope, isOutOfBounds, isValidAgentName, isWorkflowScope, nextCriterionId, parseRRule, prettifyKey, promptFieldName, skillToWorkflow, statusBadgeVariant, summarizeAgent, summarizeCapabilities, validateInputs, workflowAccepts, workflowFromFrontmatter, workflowsAccepting, workflowsForHost } from '../chunk-ITGHMJOM.js';
-import '../chunk-WTNMWEBC.js';
+export { ACTION_LABELS, AgentAvatarField, AgentBar, AgentBarIconButton, AgentBarMenu, AgentBarNotes, AgentBarProbeAnswer, AgentBarQueuedNote, AgentBarStatus, AgentCard, AgentCreateView, AgentCreatedView, AgentCreator, AgentEditView, AgentGallery, AgentMainView, AgentSelect, AgentTypeSelector, CapabilityGrid, CapabilityTile, ConfigField, ConfigForm, ConsentActions, ConsentBulletList, ConsentCard, ConsentFootnote, ConsentHeader, ConsentMessage, ConsentNotice, ConsentPage, ConsentPermissionList, ConsentSection, ConsentStrong, ConsentText, CopyableUrl, DEFAULT_AGENT_AVATAR_FIELD_LABELS, DEFAULT_AGENT_BAR_LABELS, DEFAULT_AGENT_CARD_LABELS, DEFAULT_AGENT_CREATOR_LABELS, DEFAULT_AGENT_GALLERY_LABELS, DEFAULT_AGENT_SELECT_LABELS, DEFAULT_AGENT_STEPS_LABELS, DEFAULT_AGENT_TYPE_SELECTOR_LABELS, DEFAULT_AUTHORIZE_AGENT_LABELS, DEFAULT_CONFIG_FIELD_LABELS, DEFAULT_CONFIG_FORM_LABELS, DEFAULT_CONSENT_ACTIONS_LABELS, DEFAULT_COPYABLE_URL_LABELS, DEFAULT_LIVE_RUNS_BANNER_LABELS, DEFAULT_RECURRENCE, DEFAULT_RECURRENCE_BUILDER_LABELS, DEFAULT_SCHEMA_FORM_LABELS, DEFAULT_SKILL_CARD_LABELS, DEFAULT_SKILL_EDIT_FORM_LABELS, DEFAULT_SKILL_GENERATE_FORM_LABELS, DEFAULT_SKILL_GLOBAL_BADGE_LABELS, DEFAULT_SKILL_ROW_LABELS, DEFAULT_SKILL_VIEW_TOGGLE_LABELS, DEFAULT_SUBAGENT_ROSTER_LABELS, DEFAULT_TASKS_CHROME_LABELS, DEFAULT_TASK_COLUMN_LABELS, DEFAULT_TASK_COMPOSER_LABELS, DEFAULT_TASK_PLAN_LABELS, DEFAULT_TASK_ROW_ACTIONS_LABELS, DEFAULT_TASK_RUNS_DIALOG_LABELS, DEFAULT_TUPLE_ARRAY_FIELD_LABELS, DEFAULT_UPLOAD_TASK_ITEM_LABELS, DEFAULT_UPLOAD_TASK_LIST_LABELS, DEFAULT_WORKFLOW_CONFIG_DIALOG_LABELS, EMPTY_WORKFLOW_SCOPE, GoalCriteria, LiveRunsBanner, NewTaskEmptyAction, RecurrenceBuilder, SKILL_PROMPT_FALLBACK_PLACEHOLDER, SKILL_PROMPT_LABEL, STATUS_LABELS, SchemaForm, SkillActionButton, SkillCard, SkillDetail, SkillDetailSection, SkillEditForm, SkillFilterChips, SkillGenerateForm, SkillGlobalBadge, SkillRow, SkillTile, SkillTypeBadge, SkillViewToggle, StepDetail, StepNarration, StepOutcome, StepParams, StepRow, StepSummary, StepTrace, StepTraceSummary, SubAgentLane, SubStepGroup, SubagentRoster, TRIGGER_LABELS, TaskComposer, TaskPlan, TaskRowActions, TaskRunsDialog, TasksBulkBar, TasksToolbar, TupleArrayField, UploadTaskItem, UploadTaskList, WEEKDAYS, WorkflowConfigDialog, WorkflowLauncher, agentConfigSectionToValues, agentCreatorToConfigSection, authModeFor, buildLaunch, buildRRule, composePersona, composeWorkflowPrompt, createTaskColumns, defaultInputs, defaultTaskComposerValues, deriveAgentName, describeRRule, formatElapsed, goalProgress, humanizeSection, inferType, inputsFromContext, isAgenticWorkflow, isEmptyWorkflowScope, isOutOfBounds, isValidAgentName, isWorkflowScope, isoToLocalInput, localInputToIso, nextCriterionId, parseRRule, prettifyKey, promptFieldName, skillToWorkflow, statusBadgeVariant, stripPersonaPreamble, summarizeAgent, summarizeCapabilities, taskComposerToCreateRequest, taskComposerToUpdateRequest, taskNeedsAccess, taskToComposerValues, validateInputs, workflowAccepts, workflowFromFrontmatter, workflowTaskFields, workflowsAccepting, workflowsForHost } from '../chunk-BBEMPS6C.js';
+import '../chunk-NJL4LIXX.js';
 import '../chunk-CQCC7LE7.js';
 import '../chunk-P6GHJSLR.js';
 import '../chunk-S7PSMMRG.js';
@@ -9,6 +9,7 @@ import '../chunk-NUNKSZKU.js';
 import '../chunk-UBNVIIBT.js';
 import '../chunk-NPLYHR2E.js';
 import '../chunk-76JDDMSP.js';
+import '../chunk-OXF2IFXG.js';
 import '../chunk-7F6CBP3Z.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/agents/tasks/TaskRunsDialog.d.ts

@@ -5,7 +5,7 @@ export interface TaskRunView {
     /** Formatted finish (or start) time; empty for none. */
     when?: string;
     error?: string | null;
-    /** The conversation the run's messages landed in; enables Open. */
+    /** The run's `conversation_ext_id`; enables Open. See `TaskRunsDialogProps.onOpenRun`. */
     conversationId?: string | null;
 }
 /** Fixed strings of the run-history dialog. */
@@ -31,9 +31,21 @@ export interface TaskRunsDialogProps {
     taskName?: string;
     runs: TaskRunView[];
     isLoading: boolean;
-    /** Jump into a run's conversation (the dialog closes afterwards). */
+    /**
+     * Jump into a run's conversation (the dialog closes afterwards).
+     *
+     * Deep-link contract: `conversationId` is the run's `conversation_ext_id` (`con-xxxxxxxx`, from
+     * `useTaskRuns` / `TaskRunResponse`). ARBI defines no URL for it: the HOST decides where a
+     * conversation lives (`/chat/${id}`, a dock, a modal). The conversation belongs to the task's
+     * workspace (`TaskResponse.workspace_ext_id`), so a host whose route needs the workspace open
+     * must switch to it first, then navigate. A run with no `conversationId` gets no Open button.
+     */
     onOpenRun: (conversationId: string) => void;
-    /** Destination of a run's conversation; makes Open a real link. */
+    /**
+     * The same destination as an href, so Open is a real link (middle-click, copy address, new tab).
+     * Return the URL for `run.conversationId`; `onOpenRun` still fires on a plain click for SPA
+     * navigation. Leave unset for a button-only Open.
+     */
     getRunHref?: (run: TaskRunView) => string | undefined;
     testIds?: Partial<TaskRunsDialogTestIds>;
     labels?: Partial<TaskRunsDialogLabels>;

package/dist/agents/tasks/index.d.ts

@@ -11,3 +11,4 @@ export { createTaskColumns, DEFAULT_TASK_COLUMN_LABELS, type TaskColumnSlots, ty
 export { TaskRunsDialog, DEFAULT_TASK_RUNS_DIALOG_LABELS, type TaskRunsDialogProps, type TaskRunsDialogLabels, type TaskRunsDialogTestIds, type TaskRunView, } from './TaskRunsDialog';
 export { TasksToolbar, NewTaskEmptyAction, TasksBulkBar, DEFAULT_TASKS_CHROME_LABELS, type TasksChromeLabels, type TasksToolbarProps, type TasksBulkBarProps, } from './TasksChrome';
 export { TaskComposer, DEFAULT_TASK_COMPOSER_LABELS, defaultTaskComposerValues, type TaskComposerProps, type TaskComposerLabels, type TaskComposerValues, type TaskWhen, type TaskAccessMode, } from './TaskComposer';
+export { authModeFor, workflowTaskFields, isAgenticWorkflow, taskComposerToCreateRequest, taskComposerToUpdateRequest, taskToComposerValues, taskNeedsAccess, isoToLocalInput, localInputToIso, type TaskAuthMode, type TaskActionKind, type WorkflowTaskFields, type TaskRequestContext, type TaskValuesWorkflows, } from './taskRequest';

package/dist/agents/tasks/taskRequest.d.ts

@@ -0,0 +1,61 @@
+/**
+ * TaskComposer values to API requests (and back): the pure mapping every host would write the same
+ * way. No SDK call is made here; hand the result to `useCreateTask` / `useUpdateTask` from
+ * `@arbidocs/react`.
+ */
+import type { components } from '@arbidocs/client';
+import type { WorkflowDefinition, WorkflowInputs } from '../workflows/types';
+import type { TaskComposerValues } from './TaskComposer';
+type CreateTaskRequest = components['schemas']['CreateTaskRequest'];
+type UpdateTaskRequest = components['schemas']['UpdateTaskRequest'];
+type TaskResponse = components['schemas']['TaskResponse'];
+export type TaskAuthMode = NonNullable<CreateTaskRequest['auth_mode']>;
+export type TaskActionKind = NonNullable<CreateTaskRequest['action_type']>;
+/**
+ * The plain-language access choice becomes the backend authorisation tier: a run-now task is
+ * authorised for that one run, a scheduled one either keeps standing access or asks each run.
+ */
+export declare function authModeFor(values: Pick<TaskComposerValues, 'when' | 'access'>): TaskAuthMode;
+/** `datetime-local` value (no zone) to an ISO instant. Throws on an empty or invalid value. */
+export declare function localInputToIso(local: string): string;
+/** An ISO instant to the `datetime-local` value the composer edits; empty for none or invalid. */
+export declare function isoToLocalInput(iso: string | null | undefined): string;
+export interface WorkflowTaskFields {
+    name: string;
+    action_type: TaskActionKind;
+    prompt: string;
+    skill_ref: string | null;
+}
+/**
+ * How a workflow becomes the body of a task:
+ * - `options.agent === false` is a reminder (`notify`): the composed text is the notification;
+ * - a workflow with a `skill` runs that skill, its `args` input being the arguments;
+ * - anything else is an agent prompt, the composed workflow prompt.
+ * `name` (typed by the user) wins over the derived one.
+ */
+export declare function workflowTaskFields(workflow: WorkflowDefinition, inputs: WorkflowInputs, name?: string): WorkflowTaskFields;
+/** Does this workflow need a workspace to run (everything except a plain reminder)? */
+export declare const isAgenticWorkflow: (workflow: WorkflowDefinition) => boolean;
+export interface TaskRequestContext {
+    workflow: WorkflowDefinition;
+    values: TaskComposerValues;
+}
+/**
+ * The create request for a composer submission. An agent task is bound to `workspaceId` (throws
+ * when there is none); a reminder is not. A run-now task is a one-time task due immediately: the
+ * host starts it explicitly with `useRunTask` after creating it.
+ */
+export declare function taskComposerToCreateRequest({ workflow, values }: TaskRequestContext, workspaceId: string | undefined): CreateTaskRequest;
+/** The patch for editing a task (the trigger kind, workspace and agent stay as created). */
+export declare function taskComposerToUpdateRequest({ workflow, values, }: TaskRequestContext): UpdateTaskRequest;
+/** Does the task need the owner to authorise workspace access before it can run? */
+export declare const taskNeedsAccess: (task: Pick<TaskResponse, "pending_auth_request_id">) => boolean;
+export interface TaskValuesWorkflows {
+    /** The workflow that stands for an instruction task (its first input is `instruction`). */
+    customWorkflowId: string;
+    /** The workflow that stands for a reminder (its first input is `message`). */
+    reminderWorkflowId: string;
+}
+/** What an existing task looks like when reopened in the composer. */
+export declare function taskToComposerValues(task: TaskResponse, workflows: TaskValuesWorkflows): Partial<TaskComposerValues>;
+export {};

package/dist/chat/AssistantDock.d.ts

@@ -0,0 +1,39 @@
+import type { ChatPageController, ChatPageProps } from './chat-page-types';
+declare function set(next: boolean): void;
+export declare function useAssistantDock(): {
+    isOpen: boolean;
+    setOpen: typeof set;
+    toggle: () => void;
+};
+export interface AssistantDockToggleProps {
+    /** Accessible name. Default "Open assistant chat". */
+    label?: string;
+    testId?: string;
+}
+/** Topbar button that opens and closes the dock. Renders nothing while a page chat is mounted. */
+export declare function AssistantDockToggle({ label, testId, }: AssistantDockToggleProps): import("react").JSX.Element | null;
+export interface AssistantDockProps extends Omit<ChatPageProps, 'chat' | 'surface'> {
+    chat: ChatPageController;
+    /** Phone layout: the dock covers the screen as a modal. */
+    isMobile?: boolean;
+    /** Desktop width. Default 380. */
+    width?: number | string;
+    /** Accessible name of the dock. Default "Assistant chat". */
+    label?: string;
+    closeLabel?: string;
+}
+/**
+ * The assistant as a right-hand dock: `Shell.Dock` around the same `ChatPage` as the full page
+ * (`surface="dock"`), with its open state in `useAssistantDock`. It yields to a mounted page chat
+ * (`useChatSurface`), so the host only mounts it once, next to `Shell.Root`'s `aside`:
+ *
+ * ```tsx
+ * <Shell.Root aside={<AssistantDock chat={chat} isMobile={isMobile} />} ... />
+ * <AssistantDockToggle />   // in the topbar
+ * ```
+ *
+ * Keep the `chat` controller in a component that stays mounted (the layout), so the conversation
+ * survives closing the dock.
+ */
+export declare function AssistantDock({ chat, isMobile, width, label, closeLabel, headerActions, ...pageProps }: AssistantDockProps): import("react").JSX.Element | null;
+export {};

package/dist/chat/ChatDocuments.d.ts

@@ -0,0 +1,17 @@
+import type { ChatPageController, ChatPageLabels } from './chat-page-types';
+interface ChatDocumentsProps {
+    chat: Pick<ChatPageController, 'documents' | 'isUploading' | 'toggleDocument' | 'selectAllDocuments'>;
+    labels: ChatPageLabels;
+    onPickFiles: () => void;
+    testIds?: Partial<{
+        documents: string;
+        upload: string;
+    }>;
+}
+/**
+ * The document context chip of the composer: how many documents the questions are grounded on,
+ * and a popover to pick them or upload more. The count is on the chip, the names are in the list,
+ * so the same part reads in a dock (no room) and on a page.
+ */
+export declare function ChatDocuments({ chat, labels, onPickFiles, testIds }: ChatDocumentsProps): import("react").JSX.Element;
+export {};

package/dist/chat/ChatPage.d.ts

@@ -0,0 +1,16 @@
+import { type ChatPageProps } from './chat-page-types';
+/**
+ * A complete assistant chat, composed from the same parts as the dock: conversation list with
+ * auto-titles, message list, composer with the document chip and upload, empty state, error and
+ * retry. Drive it with `useArbiChat()` from `@arbidocs/react` (or fill `ChatPageController`).
+ *
+ * It sizes to its container, not the viewport (container queries on the root), so it holds up in
+ * a card, beside an open dock or on a phone: the conversation list is a column from 48rem and a
+ * select below; the `aside` slot (workflow launcher) is a column from 72rem and a collapsible
+ * panel below. Give it a height (`h-full` of a sized parent, or a `className`). Colours come from
+ * the tokens only; the user bubble has two optional ones (see `USER_BUBBLE`).
+ *
+ * With `surface="page"` it claims the page-chat slot, so `useChatSurface()` tells the host's dock
+ * to yield: one chat on screen, never two.
+ */
+export declare function ChatPage({ chat, surface, header, headerActions, aside, prompts, emptyTitle, emptyDescription, identity, renderContent, accept, labels, className, testIds, }: ChatPageProps): import("react").JSX.Element;

package/dist/chat/ChatThreads.d.ts

@@ -0,0 +1,28 @@
+import type { ChatPageLabels, ChatPageThread } from './chat-page-types';
+interface ThreadProps {
+    threads: ReadonlyArray<ChatPageThread>;
+    activeId: string;
+    labels: ChatPageLabels;
+    onSelect: (id: string) => void;
+    onNew: () => void;
+    onDelete?: (id: string) => void;
+    testIds?: Partial<{
+        list: string;
+        row: string;
+        delete: string;
+        new: string;
+        select: string;
+    }>;
+}
+/**
+ * The conversation list as a column (wide containers): New chat on top, one row per thread with a
+ * delete action. The active row is `aria-current`. Rows are real buttons, so keyboard and touch
+ * work; delete is always visible on touch and appears on hover/focus elsewhere.
+ */
+export declare function ChatThreadList({ threads, activeId, labels, onSelect, onNew, onDelete, testIds, }: ThreadProps): import("react").JSX.Element;
+/**
+ * The conversation list as one native select (narrow containers, the dock). Native on purpose:
+ * the platform picker on a phone, a label for screen readers, text at least 16px on touch.
+ */
+export declare function ChatThreadSelect({ threads, activeId, labels, onSelect, testIds, }: Pick<ThreadProps, 'threads' | 'activeId' | 'labels' | 'onSelect' | 'testIds'>): import("react").JSX.Element;
+export {};

package/dist/chat/chat-page-types.d.ts

@@ -0,0 +1,121 @@
+import type { ReactNode } from 'react';
+/**
+ * The view-model of a chat page. It is the shape `useArbiChat()` from `@arbidocs/react` returns,
+ * so `<ChatPage chat={useArbiChat(...)} />` works without an adapter; any other source (a demo,
+ * another backend) can fill it in. Plain data and callbacks: no SDK, store or router.
+ */
+export interface ChatPageMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    /** Markdown for an assistant message, plain text for a user message. */
+    content: string;
+    status: 'streaming' | 'complete' | 'error';
+    /** Why an assistant message failed. */
+    error?: string;
+    /** Agent steps the answer took so far. */
+    stepCount?: number;
+}
+export interface ChatPageThread {
+    id: string;
+    /** Empty until the first question titles it. */
+    title: string;
+}
+export interface ChatPageDocument {
+    id: string;
+    name: string;
+    isSelected: boolean;
+}
+export interface ChatPageController {
+    threads: ReadonlyArray<ChatPageThread>;
+    activeThreadId: string;
+    messages: ReadonlyArray<ChatPageMessage>;
+    isRunning: boolean;
+    /** The last turn failed. */
+    error: string | null;
+    documents: ReadonlyArray<ChatPageDocument>;
+    isLoadingDocuments: boolean;
+    isUploading: boolean;
+    uploadError: string | null;
+    send: (text: string) => void | Promise<void>;
+    retry: () => void | Promise<void>;
+    selectThread: (id: string) => void;
+    newThread: () => void;
+    /** Omit to hide the delete action. */
+    deleteThread?: (id: string) => void;
+    toggleDocument: (id: string) => void;
+    selectAllDocuments: () => void;
+    upload: (files: File[]) => void | Promise<void>;
+}
+/** Every fixed string of the chat page. Pass a partial `labels` to translate or reword. */
+export interface ChatPageLabels {
+    /** Accessible name of the whole chat. */
+    chat: string;
+    conversations: string;
+    newChat: string;
+    untitled: string;
+    deleteConversation: (title: string) => string;
+    /** Assistant name on the answer's byline. */
+    assistant: string;
+    thinking: string;
+    steps: (count: number) => string;
+    responseFailed: string;
+    answerFailedTitle: string;
+    uploadFailedTitle: string;
+    placeholder: string;
+    composerAriaLabel: string;
+    documentsInChat: (selected: number, total: number) => string;
+    documentsHeading: string;
+    selectAllDocuments: string;
+    noDocuments: string;
+    uploadDocuments: string;
+    uploading: string;
+    emptyTitle: string;
+    emptyDescription: string;
+    emptyUploadTitle: string;
+    emptyUploadDescription: string;
+    workflows: string;
+    loadingDocuments: string;
+}
+export declare const DEFAULT_CHAT_PAGE_LABELS: ChatPageLabels;
+export interface ChatPageProps {
+    chat: ChatPageController;
+    /**
+     * `page` (default): a full-page chat; while it is mounted the dock yields (see
+     * `useChatSurface`). `dock`: the same chat in the dock, which does not claim the page slot.
+     */
+    surface?: 'page' | 'dock';
+    /** Replaces the heading (default: the active conversation's title). */
+    header?: ReactNode;
+    /** Actions at the right of the header bar. */
+    headerActions?: ReactNode;
+    /**
+     * The workflow launcher column. A column beside the chat when the container is wide, a
+     * collapsible panel under the header when it is not (so an open dock never squeezes it).
+     */
+    aside?: ReactNode;
+    /** Starter questions on the empty conversation; clicking one fills the composer. */
+    prompts?: ReadonlyArray<string>;
+    /** Heading of the empty state; wins over `labels.emptyTitle`. */
+    emptyTitle?: string;
+    /** Sub-heading of the empty state; wins over `labels.emptyDescription`. */
+    emptyDescription?: string;
+    /** Identity chip on the answer's byline (default: the assistant label). */
+    identity?: ReactNode;
+    /** Renders an answer. Default: the shared markdown renderer (lists, tables, cited words). */
+    renderContent?: (message: ChatPageMessage) => ReactNode;
+    /** Accepted upload types for the file picker. */
+    accept?: string;
+    labels?: Partial<ChatPageLabels>;
+    className?: string;
+    testIds?: Partial<{
+        root: string;
+        transcript: string;
+        input: string;
+        send: string;
+        documents: string;
+        upload: string;
+        alert: string;
+        asideToggle: string;
+        aside: string;
+    }>;
+}

package/dist/chat/chat-surface.d.ts

@@ -0,0 +1,9 @@
+/** Claims the page-chat slot while `enabled` and the caller is mounted. `ChatPage` calls this. */
+export declare function useRegisterEmbeddedChat(enabled?: boolean): void;
+export interface ChatSurface {
+    /** A full-page chat is mounted. */
+    hasEmbeddedChat: boolean;
+    /** The dock (and its topbar button) may be offered: false while a page chat is mounted. */
+    isDockAvailable: boolean;
+}
+export declare function useChatSurface(): ChatSurface;