@superatomai/application-react 0.0.1 → 0.0.2-dev

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import React, { Component as Component$1, ReactNode } from 'react';
+import * as React from 'react';
+import React__default, { Component as Component$1, ReactNode, CSSProperties } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare const ExpressionSchema$1: z.ZodObject<{
@@ -185,7 +186,7 @@ type MessageParticipant = z.infer<typeof MessageParticipantSchema>;
  * Synced with sdk-nodejs/src/types.ts
  */
 declare const MessageSchema: z.ZodObject<{
-    id: z.ZodString;
+    id: z.ZodDefault<z.ZodString>;
     type: z.ZodString;
     from: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
@@ -202,6 +203,16 @@ type Message = z.infer<typeof MessageSchema>;
  * User prompt request payload schema
  * Synced with sdk-nodejs: UserPromptRequestPayloadSchema
  */
+/**
+ * Where a question was asked from. Synced with sdk-web / sdk-nodejs.
+ *
+ * A backend that does not know the field drops it, so sending one is always safe.
+ */
+declare const PromptContextSchema: z.ZodObject<{
+    dashboardId: z.ZodOptional<z.ZodString>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type PromptContext = z.infer<typeof PromptContextSchema>;
 declare const UserPromptRequestPayloadSchema: z.ZodObject<{
     prompt: z.ZodString;
     userId: z.ZodOptional<z.ZodString>;
@@ -213,6 +224,17 @@ declare const UserPromptRequestPayloadSchema: z.ZodObject<{
         component: "component";
         text: "text";
     }>>;
+    agentId: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodObject<{
+        dashboardId: z.ZodOptional<z.ZodString>;
+        filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        fileName: z.ZodString;
+        size: z.ZodNumber;
+        contentType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type UserPromptRequestPayload = z.infer<typeof UserPromptRequestPayloadSchema>;
 /**
@@ -241,9 +263,63 @@ declare const UserPromptRequestMessageSchema: z.ZodObject<{
             component: "component";
             text: "text";
         }>>;
+        agentId: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodObject<{
+            dashboardId: z.ZodOptional<z.ZodString>;
+            filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            fileName: z.ZodString;
+            size: z.ZodNumber;
+            contentType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 type UserPromptRequestMessage = z.infer<typeof UserPromptRequestMessageSchema>;
+/**
+ * Narrator progress while an answer is being worked out — "reading the schema",
+ * "running the query". Arrives on its own message type as the work happens, in
+ * any response mode. Synced with sdk-web: UserPromptNarrationSchema.
+ */
+declare const UserPromptNarrationSchema: z.ZodObject<{
+    uiBlockId: z.ZodString;
+    threadId: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    elapsedMs: z.ZodNumber;
+    text: z.ZodString;
+}, z.core.$strip>;
+type UserPromptNarration = z.infer<typeof UserPromptNarrationSchema>;
+/**
+ * User prompt abort request payload schema
+ * Synced with sdk-nodejs: UserPromptAbortRequestPayloadSchema
+ */
+declare const UserPromptAbortRequestPayloadSchema: z.ZodObject<{
+    uiBlockId: z.ZodString;
+    threadId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UserPromptAbortRequestPayload = z.infer<typeof UserPromptAbortRequestPayloadSchema>;
+/**
+ * User prompt abort request message schema
+ * Synced with sdk-nodejs: UserPromptAbortRequestMessageSchema
+ */
+declare const UserPromptAbortRequestMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"USER_PROMPT_ABORT_REQ">;
+    from: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    to: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    payload: z.ZodObject<{
+        uiBlockId: z.ZodString;
+        threadId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type UserPromptAbortRequestMessage = z.infer<typeof UserPromptAbortRequestMessageSchema>;
 /**
  * Component schema (from backend)
  * Synced with sdk-nodejs: ComponentSchema
@@ -796,13 +872,21 @@ type UIQueryFilters = z.infer<typeof UIQueryFiltersSchema>;
 /**
  * DBUIBlock schema for database storage
  * Synced with sdk-nodejs: DBUIBlockSchema (from conversation-saver.ts)
+ *
+ * `passthrough`, deliberately, and for the same reason as the copy in
+ * sdk-nodejs. A bookmark stores a copy of the conversation row's `response`;
+ * the four fields below are only what a reader needs, while the row also
+ * carries `attachments`, `generatedFiles`, `narration`, `durationMs`, `error`
+ * and whatever is added next. `createBookmark` parses the outgoing message
+ * through this schema, so a plain object strips those keys *in the browser* —
+ * the request leaves with four fields and nothing downstream can recover them.
  */
 declare const DBUIBlockSchema: z.ZodObject<{
     id: z.ZodString;
     component: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>;
     analysis: z.ZodNullable<z.ZodString>;
     user_prompt: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$loose>;
 type DBUIBlock = z.infer<typeof DBUIBlockSchema>;
 /**
  * Bookmark data schema
@@ -815,7 +899,12 @@ declare const BookmarkDataSchema: z.ZodObject<{
         component: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>;
         analysis: z.ZodNullable<z.ZodString>;
         user_prompt: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$loose>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    threadId: z.ZodOptional<z.ZodString>;
     created_at: z.ZodOptional<z.ZodString>;
     updated_at: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -826,6 +915,7 @@ type BookmarkData = z.infer<typeof BookmarkDataSchema>;
  */
 declare const BookmarkQueryFiltersSchema: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
     threadId: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -1026,8 +1116,17 @@ declare const ClientConfigSchema: z.ZodObject<{
     maxReconnectDelay: z.ZodDefault<z.ZodNumber>;
     defaultTimeout: z.ZodDefault<z.ZodNumber>;
     debug: z.ZodDefault<z.ZodBoolean>;
+    token: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-type ClientConfig = z.input<typeof ClientConfigSchema>;
+type ClientConfig = z.input<typeof ClientConfigSchema> & {
+    /**
+     * Called before every (re)connect for a valid session token, replacing
+     * `token`. Used for SDK sign-in (see SdkSession in auth.ts). Rejecting with an
+     * error whose `fatal` is true stops reconnecting; any other rejection is
+     * retried with the normal back-off.
+     */
+    getAccessToken?: () => Promise<string>;
+};
 type ResolvedClientConfig = z.output<typeof ClientConfigSchema>;
 
 /**
@@ -1045,9 +1144,36 @@ type ResolvedClientConfig = z.output<typeof ClientConfigSchema>;
  * @param responseMode - 'component' for component response (default), 'text' for text streaming
  * @param onStream - Optional callback for streaming text chunks (only for text mode)
  * @param timeout - Request timeout in milliseconds
+ * @param context - Where the question was asked from, e.g. the dashboard on screen
+ * @param onNarration - Optional callback for narrator progress updates (any mode)
  * @returns Server response message
  */
-declare function sendUserPromptRequest(client: SuperatomClient, prompt: string, threadId: string, uiBlockId: string, userId?: string, responseMode?: 'component' | 'text', onStream?: (chunk: string) => void, timeout?: number): Promise<Message>;
+declare function sendUserPromptRequest(client: SuperatomClient, prompt: string, threadId: string, uiBlockId: string, userId?: string, responseMode?: 'component' | 'text', onStream?: (chunk: string) => void, timeout?: number, 
+/** Where the question was asked from, e.g. the dashboard on screen. Omitted when not given. */
+context?: PromptContext, onNarration?: (update: UserPromptNarration) => void, 
+/** The chat agent this question belongs to. A new thread is saved against it. */
+agentId?: string, 
+/** Files this question carries, already uploaded — references only. */
+attachments?: {
+    key: string;
+    fileName: string;
+    size: number;
+    contentType?: string;
+}[]): Promise<Message>;
+/**
+ * Abort an in-flight user prompt request.
+ *
+ * Fire-and-forget: sends a USER_PROMPT_ABORT_REQ identifying the question by its
+ * uiBlockId. The backend cancels the matching in-flight request (LLM stream,
+ * source agents, any running script) and acks with USER_PROMPT_ABORTED. There's
+ * no response to await — the caller has already marked the message "stopped" on
+ * its side; this just stops the server-side work.
+ *
+ * @param client - SuperatomClient instance
+ * @param uiBlockId - The uiBlockId of the question to cancel
+ * @param threadId - The thread the question belongs to (optional context)
+ */
+declare function abortUserPromptRequest(client: SuperatomClient, uiBlockId: string, threadId?: string): void;
 /**
  * Send a user prompt suggestions request
  * @param client - SuperatomClient instance
@@ -1080,6 +1206,61 @@ declare function requestBundle(client: SuperatomClient, options?: {
 }): Promise<string>;
 
 declare function sendComponents(client: SuperatomClient, components: any[]): Promise<void>;
+/**
+ * Register the dashboard contract — every component a generated dashboard may
+ * import, with the metadata describing it.
+ *
+ * The sibling of `sendComponents`, and deliberately the same shape: the browser
+ * bundle is where these components are defined, so the browser is what says what
+ * they are. It replaced a file generated into the backend by a build step, which
+ * meant someone had to remember to run it and the committed copy could disagree
+ * with the bundle a reader was actually running.
+ *
+ * Fire-and-forget: there is nothing useful to do with an acknowledgement, and
+ * the backend refuses a build with no contract registered rather than relying on
+ * this having arrived.
+ *
+ * Ported from sdk-web (dev, 0.0.14-mds) — the message type and payload are its
+ * wire format, not a guess. Note the `_RES` suffix: it is what that SDK sends.
+ */
+declare function sendDashContract(client: SuperatomClient, components: any[]): void;
+
+/**
+ * Workflow Service
+ *
+ * Sends pre-built workflow component descriptors to the backend SDK so the
+ * main agent can route prompts to them. A workflow is a multi-step UI flow
+ * (e.g., transfer review + Agility PO submission) that the LLM can pick when
+ * the user wants to *do* something end-to-end, instead of generating chart
+ * components.
+ */
+
+/**
+ * Workflow descriptor sent over the wire.
+ *
+ * - `id`: unique workflow id (LLM tool name)
+ * - `name`: React component name registered in the bundle (e.g. "OverstockTransferAnalysis")
+ * - `description`: short human-readable summary
+ * - `whenToUse`: 1–2 sentence trigger condition the LLM uses to decide
+ * - `propsSchema`: prop name → type-and-description string. Mirrors the
+ *   `params` shape used for direct tools, e.g. `"string — branch id"`,
+ *   `"number (optional) — minimum ROI"`. Becomes the LLM tool's input_schema.
+ * - `defaultProps`: static prop defaults merged with LLM-extracted props
+ *   before the component is returned (e.g. embedded externalTool config).
+ */
+interface WorkflowDescriptor {
+    id: string;
+    name: string;
+    description: string;
+    whenToUse: string;
+    propsSchema: Record<string, string>;
+    defaultProps?: Record<string, unknown>;
+}
+/**
+ * Send the full set of registered workflows to the backend.
+ * Replaces any previously registered workflows.
+ */
+declare function sendWorkflows(client: SuperatomClient, workflows: WorkflowDescriptor[]): Promise<void>;
 
 /**
  * Data Service
@@ -1303,6 +1484,7 @@ declare function queryReports(client: SuperatomClient, options?: QueryReportsOpt
 interface Bookmark {
     id?: number;
     userId?: string;
+    agentId?: string | null;
     threadId?: string;
     name?: string;
     description?: string;
@@ -1316,6 +1498,7 @@ interface Bookmark {
 interface CreateBookmarkOptions {
     userId: string;
     uiblock: DBUIBlock;
+    agentId?: string;
     threadId?: string;
     name?: string;
     description?: string;
@@ -1401,23 +1584,139 @@ declare function getBookmark(client: SuperatomClient, id: number, timeout?: numb
 interface QueryBookmarksOptions {
     filters?: BookmarkQueryFilters;
     limit?: number;
+    /** Rows to skip — `offset`/`limit` page the list the same way threads do. */
+    offset?: number;
     sort?: 'ASC' | 'DESC';
 }
 /**
  * Query bookmarks with filters, limit, and sort
  * @param client - SuperatomClient instance
- * @param options - Query options with filters, limit, and sort
+ * @param options - Query options with filters, limit, offset and sort
  * @param timeout - Request timeout in milliseconds
- * @returns Server response with list of bookmarks
+ * @returns Server response with a page of bookmarks. `count` is the size of
+ *   this page; `total` is how many match the filters, which is what tells a
+ *   caller whether another page exists.
  */
 declare function queryBookmarks(client: SuperatomClient, options?: QueryBookmarksOptions, timeout?: number): Promise<{
     success: boolean;
     error?: string;
     data?: BookmarkData[];
     count?: number;
+    total?: number;
     message?: string;
 }>;
 
+/**
+ * Answer feedback.
+ *
+ * Whether a particular answer was right, and why not when it was not. Read by
+ * whoever is improving the project's agent, so what matters is that the
+ * snapshot travels with the verdict: the question asked, the answer given, and
+ * the thread it happened in. A verdict without them is unactionable.
+ *
+ * Not to be confused with feedback about Superatom itself — that belongs in
+ * Superatom's own app, not inside a customer's.
+ *
+ * Mirrors runtime-react's `services/wsMessages/feedback.ts`, on the same
+ * `answer-feedback` collection, so both write rows the same reader understands.
+ */
+
+interface SubmitAnswerFeedbackParams extends Record<string, unknown> {
+    /** The answer being judged — the same id the abort registry and bookmarks use. */
+    uiBlockId: string;
+    threadId?: string;
+    userId?: string;
+    userPrompt: string;
+    /** The answer as it stood when judged, so a later edit cannot rewrite history. */
+    answerSnapshot?: unknown;
+    status: 'correct' | 'partial' | 'incorrect' | null;
+    feedbackText?: string;
+}
+/**
+ * Submit a verdict on one answer.
+ *
+ * Resolves `{ success: false, error }` rather than throwing: feedback is never
+ * the thing the user came to do, and a failed send should surface as a quiet
+ * message, not an exception through the chat.
+ */
+declare function submitAnswerFeedback(client: SuperatomClient, params: SubmitAnswerFeedbackParams, timeout?: number): Promise<{
+    success: boolean;
+    error?: string;
+    data?: unknown;
+}>;
+
+/**
+ * What the SDK needs to know about the project it was pointed at.
+ *
+ * Deliberately narrow. The obvious routes return far more than this asks for —
+ * `/auth/me` hands back the user, the organization *and* every app they can
+ * open, and `/my/apps` returns apps across every project. Both are visible in
+ * the network tab of a customer's own application, so the SDK uses neither.
+ *
+ * What it uses instead:
+ *
+ *   orgId                                  a claim in the access token already held
+ *   GET /projects/:projectId/apps          this project's apps, and only this project's
+ *   GET /orgs/:orgId/projects/:projectId   this project
+ *
+ * Two requests, both scoped to the project the host named. Nothing about other
+ * projects, nothing about the user beyond what they already signed in as.
+ */
+/** The app types sa-api stores — `appTypeEnum` in its schema. */
+type SaAppType = 'chat_agent' | 'dashboard' | 'report' | 'app';
+interface SaApp {
+    id: string;
+    /** `chat_agent` is what `agentId` names — not `chat`, which matches nothing. */
+    type?: SaAppType | string;
+    projectId?: string;
+    name?: string;
+    icon?: string | null;
+    description?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface SaProject {
+    id?: string;
+    name?: string;
+    /** The project's logo — an Iconify name (`mdi:factory`) or an image URL. */
+    icon?: string | null;
+    designSystem?: {
+        colors?: {
+            primary?: string;
+            secondary?: string;
+        };
+    } | null;
+    /** `homeDash` here is the dashboard a project shows as its home page. */
+    config?: Record<string, unknown> | null;
+}
+/**
+ * The org this session belongs to, read from the access token's own claims.
+ *
+ * `mintAccessToken` puts `orgId` in every token it signs, so the SDK already
+ * holds the answer and needs no request for it. Not verified here — it is only
+ * used to build a URL, and the server checks the token properly on arrival.
+ */
+declare function getOrgId(): Promise<string | null>;
+/** Forget everything cached — on sign-out, or when the user changes. */
+declare function resetProjectCache(): void;
+/** Every app in this project: its chat agents, dashboards and reports. */
+declare function getProjectApps(projectId: string, force?: boolean): Promise<SaApp[]>;
+/**
+ * The chat agents in this project, which is what `agentId` has to be one of.
+ *
+ * The type is `chat_agent`. This said `chat` at first, which matched nothing —
+ * so the list came back empty, every caller read that as "no session, cannot
+ * tell", and a wrong `agentId` passed in silence.
+ */
+declare function getChatAgents(projectId: string): Promise<SaApp[]>;
+/**
+ * The project itself — its colours, its logo, its config.
+ *
+ * Resolves `null` rather than throwing: every caller is cosmetic or optional,
+ * and a project that cannot be read should leave the chat working.
+ */
+declare function getProject(projectId: string, force?: boolean): Promise<SaProject | null>;
+
 /**
  * Artifacts Service
  * Handles ARTIFACTS message for artifact read operations
@@ -1740,6 +2039,150 @@ declare function queryMenus(client: SuperatomClient, options?: QueryMenusOptions
     message?: string;
 }>;
 
+/**
+ * User Conversations Service
+ * Thread list + thread history via the `user-conversations` data collection
+ * (same calls as Runtime-react's services/wsMessages/userConversations.ts)
+ */
+
+/**
+ * A single conversation thread summary, as returned by getUserThreads.
+ * `title` is the opening question of the thread (its earliest prompt).
+ */
+interface ThreadSummary {
+    threadId: string;
+    title: string;
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+    archived: boolean;
+    config?: {
+        dashboardId?: string;
+    } | null;
+}
+/**
+ * One persisted Q&A row inside a thread (the user_conversations table shape).
+ * The full assistant response lives inside `response`.
+ */
+interface ThreadConversationRow {
+    id: number;
+    userId: string;
+    threadid: string | null;
+    userprompt: string;
+    status?: 'success' | 'error' | 'aborted';
+    response: {
+        id?: string;
+        component?: any;
+        analysis?: string | null;
+        user_prompt?: string;
+        error?: unknown;
+        [key: string]: any;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * List the user's conversation threads, most-recently-active first.
+ * `total` is the user's full thread count (independent of the page window).
+ */
+declare function getUserThreads(client: SuperatomClient, userId: string, agentId: string | undefined, limit?: number, offset?: number, timeout?: number): Promise<{
+    success: boolean;
+    threads: ThreadSummary[];
+    total: number;
+    error?: string;
+}>;
+/**
+ * One thread's title and config, or null when it is not found — and equally when
+ * the backend has no such operation.
+ *
+ * Null for both cases on purpose: a caller only ever asks this to find out what a
+ * thread was started on, and "we cannot tell" and "it was started on nothing" lead
+ * to the same behaviour. So this is safe to call against a backend that has never
+ * heard of it.
+ */
+/**
+ * One thread, as the backend stores it.
+ *
+ * `attachments` is the files already sent in this chat. It is read for the
+ * per-chat limits in ui/stores/attachmentsStore — a chat has a ceiling on how many
+ * files and how many bytes it can hold across all its questions, and that
+ * cannot be known from the tray alone.
+ */
+interface ThreadRecord {
+    threadId: string;
+    title: string;
+    config?: {
+        dashboardId?: string;
+    } | null;
+    attachments?: {
+        key?: string;
+        fileName?: string;
+        size?: number;
+    }[] | null;
+}
+declare function getThread(client: SuperatomClient, userId: string, agentId: string | undefined, threadId: string, timeout?: number): Promise<ThreadRecord | null>;
+/**
+ * Delete a whole thread (all its conversations).
+ */
+declare function deleteThread(client: SuperatomClient, userId: string, threadId: string, clearCache?: boolean, timeout?: number): Promise<{
+    success: boolean;
+    error?: string;
+    message?: string;
+    deletedCount?: number;
+}>;
+/**
+ * Delete one saved question/answer, by the question that produced it.
+ *
+ * `clearCache` also drops what was cached for it (query results and embeddings),
+ * so asking the same thing again is answered from the data, not from the old
+ * result. Same call Runtime-react's trash button makes.
+ */
+declare function deleteUserConversation(client: SuperatomClient, userPrompt: string, userId?: string, clearCache?: boolean, timeout?: number): Promise<{
+    success: boolean;
+    error?: string;
+    message?: string;
+    queriesDeleted?: number;
+}>;
+/**
+ * Rename a thread's title.
+ */
+declare function updateThreadTitle(client: SuperatomClient, userId: string, threadId: string, title: string, timeout?: number): Promise<{
+    success: boolean;
+    error?: string;
+    title?: string;
+}>;
+/**
+ * Fetch a page of conversations within a thread, newest-first (offset 0 = the
+ * most recent `limit` messages). `total` is the thread's full message count.
+ */
+declare function getThreadConversations(client: SuperatomClient, userId: string, agentId: string | undefined, threadId: string, limit?: number, offset?: number, timeout?: number): Promise<{
+    success: boolean;
+    rows: ThreadConversationRow[];
+    total: number;
+    error?: string;
+}>;
+
+/**
+ * Project Sources Service
+ *
+ * The data sources a project is connected to — what the sidebar shows as
+ * "Connected to POSTGRES" with the source's own name under it. Read over the
+ * socket from the project's backend, the same way runtime-react reads it.
+ */
+
+interface ProjectSource {
+    type: string;
+    name: string;
+    /** False when the source is configured but has no running instance. */
+    connected: boolean;
+}
+/**
+ * The project's data sources, or an empty list when there are none — and
+ * equally when the backend has no such operation, since both mean there is
+ * nothing to show. Safe against a backend that has never heard of it.
+ */
+declare function getProjectSources(client: SuperatomClient, projectId: string, timeout?: number): Promise<ProjectSource[]>;
+
 /**
  * Services Index
  * Re-exports all service functions for easy importing
@@ -1752,6 +2195,7 @@ type index_Dashboard = Dashboard;
 type index_Menu = Menu;
 type index_Page = Page;
 declare const index_PageSchema: typeof PageSchema;
+type index_ProjectSource = ProjectSource;
 type index_QueryArtifactsFilters = QueryArtifactsFilters;
 type index_QueryArtifactsOptions = QueryArtifactsOptions;
 type index_QueryBookmarksOptions = QueryBookmarksOptions;
@@ -1761,12 +2205,23 @@ type index_QueryReportsOptions = QueryReportsOptions;
 type index_QueryUIsOptions = QueryUIsOptions;
 type index_QueryUsersOptions = QueryUsersOptions;
 type index_Report = Report;
+type index_SaApp = SaApp;
+type index_SaAppType = SaAppType;
+type index_SaProject = SaProject;
+type index_SubmitAnswerFeedbackParams = SubmitAnswerFeedbackParams;
+type index_ThreadConversationRow = ThreadConversationRow;
+type index_ThreadRecord = ThreadRecord;
+type index_ThreadSummary = ThreadSummary;
 type index_UI = UI;
 type index_UpdateBookmarkOptions = UpdateBookmarkOptions;
 type index_User = User;
+type index_WorkflowDescriptor = WorkflowDescriptor;
+declare const index_abortUserPromptRequest: typeof abortUserPromptRequest;
 declare const index_createBookmark: typeof createBookmark;
 declare const index_deleteArtifact: typeof deleteArtifact;
 declare const index_deleteBookmark: typeof deleteBookmark;
+declare const index_deleteThread: typeof deleteThread;
+declare const index_deleteUserConversation: typeof deleteUserConversation;
 declare const index_getActions: typeof getActions;
 declare const index_getAllArtifacts: typeof getAllArtifacts;
 declare const index_getAllBookmarks: typeof getAllBookmarks;
@@ -1776,13 +2231,21 @@ declare const index_getAllReports: typeof getAllReports;
 declare const index_getAllUIs: typeof getAllUIs;
 declare const index_getArtifact: typeof getArtifact;
 declare const index_getBookmark: typeof getBookmark;
+declare const index_getChatAgents: typeof getChatAgents;
 declare const index_getChildMenus: typeof getChildMenus;
 declare const index_getDashboard: typeof getDashboard;
 declare const index_getMenu: typeof getMenu;
 declare const index_getMenusHierarchy: typeof getMenusHierarchy;
+declare const index_getOrgId: typeof getOrgId;
+declare const index_getProject: typeof getProject;
+declare const index_getProjectApps: typeof getProjectApps;
+declare const index_getProjectSources: typeof getProjectSources;
 declare const index_getReport: typeof getReport;
 declare const index_getRootMenus: typeof getRootMenus;
+declare const index_getThread: typeof getThread;
+declare const index_getThreadConversations: typeof getThreadConversations;
 declare const index_getUI: typeof getUI;
+declare const index_getUserThreads: typeof getUserThreads;
 declare const index_injectBundleStyles: typeof injectBundleStyles;
 declare const index_queryArtifacts: typeof queryArtifacts;
 declare const index_queryBookmarks: typeof queryBookmarks;
@@ -1793,12 +2256,17 @@ declare const index_queryUIs: typeof queryUIs;
 declare const index_queryUsers: typeof queryUsers;
 declare const index_requestBundle: typeof requestBundle;
 declare const index_requestData: typeof requestData;
+declare const index_resetProjectCache: typeof resetProjectCache;
 declare const index_sendComponents: typeof sendComponents;
+declare const index_sendDashContract: typeof sendDashContract;
 declare const index_sendUserPromptRequest: typeof sendUserPromptRequest;
 declare const index_sendUserPromptSuggestionsRequest: typeof sendUserPromptSuggestionsRequest;
+declare const index_sendWorkflows: typeof sendWorkflows;
+declare const index_submitAnswerFeedback: typeof submitAnswerFeedback;
 declare const index_updateBookmark: typeof updateBookmark;
+declare const index_updateThreadTitle: typeof updateThreadTitle;
 declare namespace index {
-  export { type index_Artifact as Artifact, type Binding$1 as Binding, BindingSchema$1 as BindingSchema, type index_Bookmark as Bookmark, type index_CreateBookmarkOptions as CreateBookmarkOptions, type DSLRendererProps$3 as DSLRendererProps, DSLRendererPropsSchema$3 as DSLRendererPropsSchema, type index_Dashboard as Dashboard, type Expression$1 as Expression, ExpressionSchema$1 as ExpressionSchema, type ForDirective$1 as ForDirective, ForDirectiveSchema$1 as ForDirectiveSchema, type index_Menu as Menu, type index_Page as Page, index_PageSchema as PageSchema, type index_QueryArtifactsFilters as QueryArtifactsFilters, type index_QueryArtifactsOptions as QueryArtifactsOptions, type index_QueryBookmarksOptions as QueryBookmarksOptions, type index_QueryDashboardsOptions as QueryDashboardsOptions, type index_QueryMenusOptions as QueryMenusOptions, type index_QueryReportsOptions as QueryReportsOptions, type QuerySpec$1 as QuerySpec, QuerySpecSchema$1 as QuerySpecSchema, type index_QueryUIsOptions as QueryUIsOptions, type index_QueryUsersOptions as QueryUsersOptions, type index_Report as Report, type DSLRendererProps$2 as ReportDSLRendererProps, type index_UI as UI, type UIComponent$1 as UIComponent, UIComponentSchema$1 as UIComponentSchema, type DSLRendererProps$1 as UIDSLRendererProps, type UIElement$1 as UIElement, UIElementSchema$1 as UIElementSchema, type index_UpdateBookmarkOptions as UpdateBookmarkOptions, type index_User as User, index_createBookmark as createBookmark, index_deleteArtifact as deleteArtifact, index_deleteBookmark as deleteBookmark, index_getActions as getActions, index_getAllArtifacts as getAllArtifacts, index_getAllBookmarks as getAllBookmarks, index_getAllDashboards as getAllDashboards, index_getAllMenus as getAllMenus, index_getAllReports as getAllReports, index_getAllUIs as getAllUIs, index_getArtifact as getArtifact, index_getBookmark as getBookmark, index_getChildMenus as getChildMenus, index_getDashboard as getDashboard, index_getMenu as getMenu, index_getMenusHierarchy as getMenusHierarchy, index_getReport as getReport, index_getRootMenus as getRootMenus, index_getUI as getUI, index_injectBundleStyles as injectBundleStyles, index_queryArtifacts as queryArtifacts, index_queryBookmarks as queryBookmarks, index_queryDashboards as queryDashboards, index_queryMenus as queryMenus, index_queryReports as queryReports, index_queryUIs as queryUIs, index_queryUsers as queryUsers, index_requestBundle as requestBundle, index_requestData as requestData, index_sendComponents as sendComponents, index_sendUserPromptRequest as sendUserPromptRequest, index_sendUserPromptSuggestionsRequest as sendUserPromptSuggestionsRequest, index_updateBookmark as updateBookmark };
+  export { type index_Artifact as Artifact, type Binding$1 as Binding, BindingSchema$1 as BindingSchema, type index_Bookmark as Bookmark, type index_CreateBookmarkOptions as CreateBookmarkOptions, type DSLRendererProps$3 as DSLRendererProps, DSLRendererPropsSchema$3 as DSLRendererPropsSchema, type index_Dashboard as Dashboard, type Expression$1 as Expression, ExpressionSchema$1 as ExpressionSchema, type ForDirective$1 as ForDirective, ForDirectiveSchema$1 as ForDirectiveSchema, type index_Menu as Menu, type index_Page as Page, index_PageSchema as PageSchema, type index_ProjectSource as ProjectSource, type index_QueryArtifactsFilters as QueryArtifactsFilters, type index_QueryArtifactsOptions as QueryArtifactsOptions, type index_QueryBookmarksOptions as QueryBookmarksOptions, type index_QueryDashboardsOptions as QueryDashboardsOptions, type index_QueryMenusOptions as QueryMenusOptions, type index_QueryReportsOptions as QueryReportsOptions, type QuerySpec$1 as QuerySpec, QuerySpecSchema$1 as QuerySpecSchema, type index_QueryUIsOptions as QueryUIsOptions, type index_QueryUsersOptions as QueryUsersOptions, type index_Report as Report, type DSLRendererProps$2 as ReportDSLRendererProps, type index_SaApp as SaApp, type index_SaAppType as SaAppType, type index_SaProject as SaProject, type index_SubmitAnswerFeedbackParams as SubmitAnswerFeedbackParams, type index_ThreadConversationRow as ThreadConversationRow, type index_ThreadRecord as ThreadRecord, type index_ThreadSummary as ThreadSummary, type index_UI as UI, type UIComponent$1 as UIComponent, UIComponentSchema$1 as UIComponentSchema, type DSLRendererProps$1 as UIDSLRendererProps, type UIElement$1 as UIElement, UIElementSchema$1 as UIElementSchema, type index_UpdateBookmarkOptions as UpdateBookmarkOptions, type index_User as User, type index_WorkflowDescriptor as WorkflowDescriptor, index_abortUserPromptRequest as abortUserPromptRequest, index_createBookmark as createBookmark, index_deleteArtifact as deleteArtifact, index_deleteBookmark as deleteBookmark, index_deleteThread as deleteThread, index_deleteUserConversation as deleteUserConversation, index_getActions as getActions, index_getAllArtifacts as getAllArtifacts, index_getAllBookmarks as getAllBookmarks, index_getAllDashboards as getAllDashboards, index_getAllMenus as getAllMenus, index_getAllReports as getAllReports, index_getAllUIs as getAllUIs, index_getArtifact as getArtifact, index_getBookmark as getBookmark, index_getChatAgents as getChatAgents, index_getChildMenus as getChildMenus, index_getDashboard as getDashboard, index_getMenu as getMenu, index_getMenusHierarchy as getMenusHierarchy, index_getOrgId as getOrgId, index_getProject as getProject, index_getProjectApps as getProjectApps, index_getProjectSources as getProjectSources, index_getReport as getReport, index_getRootMenus as getRootMenus, index_getThread as getThread, index_getThreadConversations as getThreadConversations, index_getUI as getUI, index_getUserThreads as getUserThreads, index_injectBundleStyles as injectBundleStyles, index_queryArtifacts as queryArtifacts, index_queryBookmarks as queryBookmarks, index_queryDashboards as queryDashboards, index_queryMenus as queryMenus, index_queryReports as queryReports, index_queryUIs as queryUIs, index_queryUsers as queryUsers, index_requestBundle as requestBundle, index_requestData as requestData, index_resetProjectCache as resetProjectCache, index_sendComponents as sendComponents, index_sendDashContract as sendDashContract, index_sendUserPromptRequest as sendUserPromptRequest, index_sendUserPromptSuggestionsRequest as sendUserPromptSuggestionsRequest, index_sendWorkflows as sendWorkflows, index_submitAnswerFeedback as submitAnswerFeedback, index_updateBookmark as updateBookmark, index_updateThreadTitle as updateThreadTitle };
 }
 
 type MessageHandler = (message: Message) => void;
@@ -1823,6 +2291,10 @@ declare class SuperatomClient {
     private config;
     private connectPromise;
     private connectResolve;
+    private lastComponents;
+    private lastWorkflows;
+    private getAccessToken;
+    private fetchingToken;
     private heartbeatInterval;
     private pongDeadline;
     private readonly HEARTBEAT_INTERVAL_MS;
@@ -1839,6 +2311,12 @@ declare class SuperatomClient {
      * Get WebSocket URL with query parameters
      */
     private getWebSocketUrl;
+    /**
+     * Swap the session token used on the next (re)connect.
+     * Deliberately does NOT re-dial a live socket: the relay only checks the
+     * token at handshake, so an open connection stays valid.
+     */
+    setToken(token: string): void;
     /**
      * Calculate reconnection delay with exponential backoff
      */
@@ -1885,6 +2363,14 @@ declare class SuperatomClient {
      * window 'online' / 'visibilitychange' handlers.
      */
     forceReconnect(): Promise<void>;
+    /**
+     * Drop the current socket without triggering its handlers: they are detached
+     * first, so its eventual real close is a no-op (on Linux/Chrome that close
+     * can arrive 30-60s later). Returns whether it was open.
+     */
+    private discardSocket;
+    /** A connection attempt is under way — fetching the session token, or the socket handshake. */
+    private isConnecting;
     /**
      * Attach window-level listeners that catch network changes faster than
      * the socket's own onclose. The browser's onclose for a half-open TCP can
@@ -1908,6 +2394,16 @@ declare class SuperatomClient {
      * The Promise never rejects - failures are logged silently and auto-reconnect is triggered
      */
     connect(): Promise<void>;
+    /**
+     * Get a valid session token, then open the socket. The relay checks the token
+     * only at handshake, so every (re)connect must present one that is still valid.
+     *
+     * A fatal auth failure (see SuperAtomAuthError.fatal) stops reconnecting — the
+     * session reports it to the host, and retrying would only repeat it. Anything
+     * else goes through the normal back-off.
+     */
+    private openWithFreshToken;
+    private openSocket;
     /**
      * Disconnect from WebSocket server
      */
@@ -1992,8 +2488,25 @@ declare class SuperatomClient {
      * @param userId - User ID for the request
      * @param responseMode - 'component' for component response (default), 'text' for text streaming
      * @param onStream - Optional callback for streaming text chunks (only for text mode)
+     * @param onNarration - Optional callback for narrator progress updates (any mode)
      */
-    sendUserPromptRequest(prompt: string, threadId: string, uiBlockId: string, userId?: string, responseMode?: 'component' | 'text', onStream?: (chunk: string) => void, timeout?: number): Promise<Message>;
+    sendUserPromptRequest(prompt: string, threadId: string, uiBlockId: string, userId?: string, responseMode?: 'component' | 'text', onStream?: (chunk: string) => void, timeout?: number, 
+    /** Where the question was asked from — the dashboard on screen, when there is one. */
+    context?: PromptContext, onNarration?: (update: UserPromptNarration) => void, 
+    /** The chat agent this question belongs to. A new thread is saved against it. */
+    agentId?: string, 
+    /** Files this question carries, already uploaded — references only. */
+    attachments?: {
+        key: string;
+        fileName: string;
+        size: number;
+        contentType?: string;
+    }[]): Promise<Message>;
+    /**
+     * Abort an in-flight user prompt request (frontend "Stop" button).
+     * Fire-and-forget — cancels the backend work for the given uiBlockId.
+     */
+    abortUserPromptRequest(uiBlockId: string, threadId?: string): void;
     /**
      * Send a user prompt suggestions request
      * Delegates to user prompt service
@@ -2007,6 +2520,8 @@ declare class SuperatomClient {
     requestBundle(options?: {
         timeout?: number;
         onProgress?: (progress: number) => void;
+        devbundlereq?: boolean;
+        /** @deprecated Use `devbundlereq` */
         devbundle?: boolean;
     }): Promise<string>;
     /**
@@ -2014,6 +2529,22 @@ declare class SuperatomClient {
      * Delegates to component service
      */
     sendComponents(components: any[]): Promise<void>;
+    /**
+     * Register the dashboard contract with the backend.
+     *
+     * Required before a program dashboard can be built: without it the backend has
+     * no record of which components a generated dashboard may import. The project
+     * bundle calls this during its own init, so it has to exist on the client the
+     * bundle is handed.
+     */
+    sendDashContract(components: any[]): void;
+    /**
+     * Send registered workflow descriptors to the backend so the main agent
+     * can route prompts to them. Each descriptor is the routing metadata for a
+     * pre-built workflow component (id, name, description, whenToUse,
+     * propsSchema, defaultProps).
+     */
+    sendWorkflows(workflows: WorkflowDescriptor[]): Promise<void>;
     /**
      * Request data from a collection
      * Delegates to data service
@@ -2330,6 +2861,140 @@ declare class SuperatomClient {
     private log;
 }
 
+/**
+ * SDK sign-in with the customer's own login.
+ *
+ * The host app hands us `getToken()` — a function THEY write that asks their
+ * backend for a short-lived JWT signed with their SDK secret. We exchange it at
+ * sa-api (`POST /auth/sdk/exchange`) for OUR 15-minute access token, which the
+ * WebSocket relay accepts at handshake.
+ *
+ * There is no refresh token in this mode: the customer's own session is the
+ * long-lived one. To renew we simply call `getToken()` again and re-exchange —
+ * before every (re)connect when ours is about to expire, and on a timer a
+ * couple of minutes ahead, so a reconnect never has to wait for it.
+ *
+ * Failures are split in two:
+ *  - fatal (their token rejected, SDK not enabled, user deactivated, or
+ *    `getToken()` itself failing): reported once through `onAuthError`, and
+ *    every later call fails fast with the same error — no loop against their
+ *    backend or ours — until `reset()`.
+ *  - transient (network, sa-api 5xx / 429): thrown to the caller, whose normal
+ *    reconnect back-off retries.
+ */
+declare const DEFAULT_API_URL = "https://sa-api.superatom.ai";
+/** The signed-in user, as returned by the exchange. `id` is OUR user id. */
+interface SdkUser {
+    id: string;
+    email: string;
+    name: string;
+    /** The role this session acts with — always "member" for SDK sessions. */
+    role: string;
+    /** Their own role names, from the `roles` claim. */
+    externalRoles: string[];
+}
+type SuperAtomAuthErrorCode = 
+/** `getToken()` threw or returned no token. */
+'get_token_failed'
+/** sa-api refused the token (400 / 401 / 403). `status` and `message` say why. */
+ | 'exchange_rejected'
+/** sa-api unavailable (5xx / 429). Retried. */
+ | 'exchange_unavailable'
+/** Could not reach sa-api, or it timed out. Retried. */
+ | 'network';
+declare class SuperAtomAuthError extends Error {
+    readonly code: SuperAtomAuthErrorCode;
+    /**
+     * Why Superatom refused it, verbatim — `expired`, `bad_signature`,
+     * `bad_access_filters`, `inactive`, … Present for `exchange_rejected` only.
+     */
+    readonly reason?: string;
+    /** HTTP status from sa-api, when there was a response. */
+    readonly status?: number;
+    /** True when retrying cannot help — see the module comment. */
+    readonly fatal: boolean;
+    constructor(code: SuperAtomAuthErrorCode, message: string, options: {
+        status?: number;
+        reason?: string;
+        fatal: boolean;
+        cause?: unknown;
+    });
+}
+interface SdkSessionOptions {
+    projectId: string;
+    /** Returns the customer-signed JWT. Written by the host app. */
+    getToken: () => Promise<string> | string;
+    /** Called once for each fatal failure. */
+    onAuthError?: (error: SuperAtomAuthError) => void;
+    /** Called after each successful exchange. */
+    onSession?: (user: SdkUser) => void;
+    /**
+     * Sign-in keeps failing for a retryable reason (Superatom unreachable or down),
+     * after a couple of attempts. Called again on each further failure, and with
+     * null once a sign-in succeeds.
+     */
+    onRetrying?: (error: SuperAtomAuthError | null) => void;
+    /** True while an exchange is in flight, false when it finishes either way. */
+    onSigningIn?: (signingIn: boolean) => void;
+    /** sa-api base URL. Default: prod. */
+    apiUrl?: string;
+    debug?: boolean;
+}
+declare class SdkSession {
+    private readonly opts;
+    private readonly apiUrl;
+    private token;
+    private expiresAt;
+    private currentUser;
+    /** The one renewal in flight — every caller shares it. */
+    private inFlight;
+    private fatalError;
+    /** Retryable failures in a row; reset by a successful exchange. */
+    private retries;
+    private renewTimer;
+    private stopped;
+    constructor(opts: SdkSessionOptions);
+    /** The sa-api this session talks to, so callers need not re-derive it. */
+    get baseUrl(): string;
+    get user(): SdkUser | null;
+    /** The fatal error that stopped the session, if any. */
+    get error(): SuperAtomAuthError | null;
+    /**
+     * A token with at least a minute left — the cached one, or a fresh exchange.
+     * Rejects with SuperAtomAuthError.
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Start over: forget the session held and let the next `getAccessToken()`
+     * exchange a brand new one.
+     *
+     * Called by `reconnect()`, and the cached token is dropped deliberately. A
+     * token carries what the host's backend put in it — who the user is, and
+     * what data they may see — and those can change while the tab stays open: a
+     * customer picked from a dropdown, a role granted, an account switched. The
+     * host says so by calling `reconnect()`, and if the cached token were kept
+     * the old claims would stand until it expired, which looks exactly like the
+     * filter not working.
+     *
+     * The cost is one extra round trip to the host's `getToken` and to sa-api.
+     * That is the right price for "sign me in again" meaning what it says.
+     */
+    reset(): void;
+    /** Stop renewing — the host unmounted or disconnected. */
+    stop(): void;
+    private renew;
+    private exchange;
+    /** Record a failure: a fatal one stops the session and is reported once. */
+    private fail;
+    /**
+     * Renew in the background ahead of expiry. Timers are paused while the machine
+     * sleeps and fire on wake; a reconnect after wake also renews first if needed.
+     */
+    private scheduleRenew;
+    private clearRenewTimer;
+    private log;
+}
+
 /**
  * Component mount function type
  */
@@ -3423,13 +4088,13 @@ interface ExtendedDSLRendererProps extends DSLRendererProps {
     onNavigate?: NavigationHandler;
     handlers?: Record<string, Function>;
 }
-declare const DSLRenderer: React.FC<ExtendedDSLRendererProps>;
+declare const DSLRenderer: React__default.FC<ExtendedDSLRendererProps>;
 
 interface ComponentDefinition {
     id: string;
     name: string;
     head: string;
-    COMP: React.ComponentType<any>;
+    COMP: React__default.ComponentType<any>;
     dependencies?: string[];
     version?: string;
 }
@@ -3449,10 +4114,10 @@ declare const useDynamicComponent: (componentType: string) => {
     isLoaded: boolean;
     error: string | null;
 };
-declare const DynamicComponent: React.FC<{
+declare const DynamicComponent: React__default.FC<{
     type: string;
     props?: any;
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
 }>;
 
 interface DSLErrorBoundaryProps {
@@ -3460,7 +4125,7 @@ interface DSLErrorBoundaryProps {
     fallback?: ReactNode;
     elementType?: string;
     elementKey?: string | number;
-    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    onError?: (error: Error, errorInfo: React__default.ErrorInfo) => void;
     skipBoundary?: boolean;
 }
 interface DSLErrorBoundaryState {
@@ -3471,14 +4136,196 @@ interface DSLErrorBoundaryState {
 declare class DSLErrorBoundary extends Component$1<DSLErrorBoundaryProps, DSLErrorBoundaryState> {
     constructor(props: DSLErrorBoundaryProps);
     static getDerivedStateFromError(error: Error): DSLErrorBoundaryState;
-    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
-    render(): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+    componentDidCatch(error: Error, errorInfo: React__default.ErrorInfo): void;
+    render(): string | number | boolean | Iterable<React__default.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
 }
 declare const withConditionalErrorBoundary: (component: ReactNode, elementType: string, elementKey?: string | number, forceWrap?: boolean) => ReactNode;
 
+/**
+ * Register every component exposed on window.SUPERATOM.COMPONENTS into COMP_REGISTRY.
+ * Safe to call repeatedly — each call reflects the currently loaded bundle.
+ */
 declare function registerBundleComponents(): number;
+/**
+ * Remove all bundle components added by registerBundleComponents from COMP_REGISTRY.
+ */
 declare function resetRegistration(): void;
 
+/**
+ * 'dashboard' is a dashboard saved in Superatom (sa-api); 'bundle-dashboard' is
+ * one the project bundle ships as a component (see useBundleDashboards).
+ */
+type AssistantView = 'home' | 'chat' | 'dashboard' | 'report' | 'bundle-dashboard' | 'bookmark';
+interface AssistantNavigation {
+    view: AssistantView;
+    dashboardId: string | null;
+    reportId: string | null;
+    bundleDashboard: string | null;
+    bookmarkId: number | null;
+    setView: (view: AssistantView) => void;
+    /**
+     * Send what is in the composer, from wherever the reader is.
+     *
+     * `sendMessage` from the session only sends; this also decides where the
+     * answer should appear, which depends on the view and is therefore
+     * navigation's business rather than the composer's.
+     */
+    send: () => void;
+    /** Open a thread, and the dashboard it belongs to if it has one. */
+    openThread: (threadId: string) => void;
+    /** Start a new conversation and show it. */
+    newChat: () => void;
+    goHome: () => void;
+    openDashboard: (dashboardId: string) => void;
+    openReport: (reportId: string) => void;
+    openBundleDashboard: (key: string) => void;
+    openBookmark: (bookmarkId: number) => void;
+}
+interface AssistantNavigationProviderProps {
+    children: ReactNode;
+    /** Which view it opens on. Default 'home'. */
+    defaultView?: AssistantView;
+    view?: AssistantView;
+    onViewChange?: (view: AssistantView) => void;
+    dashboardId?: string | null;
+    onDashboardChange?: (dashboardId: string | null) => void;
+    reportId?: string | null;
+    onReportChange?: (reportId: string | null) => void;
+    bundleDashboard?: string | null;
+    onBundleDashboardChange?: (key: string | null) => void;
+}
+/**
+ * Where the assistant is, and how to move it.
+ *
+ * This used to live inside `SuperatomAssistant`, which meant a host composing
+ * the pieces had to write it again: five pieces of state, and a thread click
+ * handler that has to know a thread can belong to a dashboard. That is not
+ * host code — it is how this SDK's screens relate to each other — and every
+ * copy of it was a chance to leave something out. The sidebar lost its
+ * dashboards exactly that way.
+ *
+ * `SuperatomSurface` provides one automatically, so `<Sidebar />` on its own
+ * already navigates. A host that wants to drive navigation itself reads this
+ * hook and ignores the parts it does not want.
+ */
+declare function AssistantNavigationProvider({ children, defaultView, view: viewProp, onViewChange, dashboardId: dashboardIdProp, onDashboardChange, reportId: reportIdProp, onReportChange, bundleDashboard: bundleDashboardProp, onBundleDashboardChange, }: AssistantNavigationProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Where the assistant is. Throws outside a `SuperatomSurface`, which is what
+ * provides it — a navigation that nothing renders from is a bug, not a default.
+ */
+declare function useAssistantNavigation(): AssistantNavigation;
+/** True when a navigation is already above this component. */
+declare function useHasAssistantNavigation(): boolean;
+
+/**
+ * No session options here. `projectId`, `agentId` and `getToken` are given to
+ * the `SuperatomProvider` this component must be rendered under — one session
+ * per app, made in one place. These props are about what the assistant shows.
+ */
+interface SuperatomAssistantProps {
+    className?: string;
+    /** Hidden when the host has navigation of its own. Default true. */
+    showSidebar?: boolean;
+    /**
+     * The project's logo at the top of the sidebar. Default true.
+     *
+     * A host whose own chrome already carries its branding turns this off rather
+     * than showing the customer two logos one above the other.
+     */
+    showSidebarLogo?: boolean;
+    /**
+     * Let a question carry files — the "+" in the composer. Default false.
+     *
+     * Off unless asked for, because an assistant that accepts files is a
+     * decision about the product, not about the SDK: an agent that does nothing
+     * with an attachment should not invite one. Both `projectId` and `agentId`
+     * are needed as well, since an upload is addressed to them.
+     */
+    enableAttachments?: boolean;
+    /**
+     * Which view it opens on. Default 'home' — the landing page, with the
+     * project's dashboards and a composer on it. Pass 'chat' for an assistant
+     * that is only a conversation.
+     */
+    defaultView?: 'home' | 'chat';
+    /** Shown while the connection and the project bundle are still coming up. */
+    connectingText?: string;
+    /** Placeholder for an empty conversation. Nothing is shown unless it is set. */
+    emptyText?: string;
+    /** Replaces the built-in greeting on an empty chat. */
+    emptyState?: ReactNode;
+    /**
+     * Follow-up questions below a dashboard: the dashboard, its thread under it,
+     * the composer below both, scrolling as one page.
+     *
+     * On by default, for every dashboard. Pass false for a dashboard that is
+     * only to be looked at — the page then renders on its own, with the composer
+     * still there to start an ordinary chat.
+     */
+    dashboardFollowUps?: boolean;
+    /**
+     * Render inside a shadow root, so the host page's CSS cannot reach in.
+     *
+     * On by default. Scoping the stylesheet to `.sa-ui` wins the collisions it can
+     * — a bare `.btn` against our `.sa-ui .btn` — but it cannot win against a
+     * host's bare element rules, and a page that styles `button` or `input`
+     * directly reaches our components whatever our selectors say. Only a boundary
+     * stops that, so it is the default rather than something a host has to know
+     * to ask for.
+     *
+     * The escape hatch stays because the boundary has real costs: the document
+     * can no longer see our elements, so a host script doing
+     * `document.querySelector` inside the assistant, an analytics or a11y tool
+     * that walks the DOM, or a listener reading `event.target` on `document` all
+     * see less than they did. A host that hits one of those sets this to `false`
+     * and is back to scoping alone, rather than having to pin an old version.
+     */
+    shadowDom?: boolean;
+    /** Which view is showing. Uncontrolled when absent — see `defaultView`. */
+    view?: AssistantView;
+    onViewChange?: (view: AssistantView) => void;
+    /** The open thread, or null for a new chat. Uncontrolled when absent. */
+    threadId?: string | null;
+    onThreadChange?: (threadId: string | null) => void;
+    /** The open dashboard. Uncontrolled when absent. */
+    dashboardId?: string | null;
+    onDashboardChange?: (dashboardId: string | null) => void;
+    /** The open report. Uncontrolled when absent. */
+    reportId?: string | null;
+    onReportChange?: (reportId: string | null) => void;
+    /**
+     * The open bundle dashboard — the key of a project-bundle component that
+     * declares `Metadata.dashboard`. Uncontrolled when absent.
+     */
+    bundleDashboard?: string | null;
+    onBundleDashboardChange?: (key: string | null) => void;
+}
+
+/**
+ * The whole assistant, composed.
+ *
+ * The SDK has always been a component kit: a host takes `useSuperAtom`,
+ * `Sidebar`, `MessageList` and `ChatInput` and arranges them. That is still the
+ * way to build something of your own shape, and nothing here replaces it.
+ *
+ * What it costs is that every app arranges the same five components the same
+ * way and has to get the same details right — which view is showing, that the
+ * composer is a sibling of the page and not a child of it, that the two boxes
+ * around it all are a row and a column with `min-h-0`. This component is that
+ * arrangement, once, inside the SDK:
+ *
+ *     <SuperatomAssistant />
+ *
+ * It composes the exported components rather than reimplementing them, so
+ * there is one implementation of the chat and two ways to reach it. That now
+ * includes the navigation and the sidebar's wiring: this component used to
+ * hold its own copy of both, and a composed layout had to be written against
+ * the same rules by hand — which is how one lost its dashboards and its
+ * bookmarks without anyone noticing. Both read `AssistantNavigationProvider`
+ * now, so they cannot disagree.
+ */
+declare function SuperatomAssistant({ className, shadowDom, defaultView, view, onViewChange, dashboardId, onDashboardChange, reportId, onReportChange, bundleDashboard, onBundleDashboardChange, ...rest }: SuperatomAssistantProps): react_jsx_runtime.JSX.Element;
+
 interface ChatMessage {
     id: string;
     role: 'user' | 'assistant';
@@ -3491,14 +4338,111 @@ interface ChatMessage {
     isLoading?: boolean;
     isStreaming?: boolean;
     isTextOnlyResponse?: boolean;
-}
+    aborted?: boolean;
+    fromHistory?: boolean;
+    /**
+     * The saved conversation row's `response`, carried as it came off the wire.
+     *
+     * Nothing renders from this — every reader works off the mapped fields above.
+     * It exists so bookmarking can store the response *verbatim* rather than
+     * reassembling it from the parts that happened to be mapped, which silently
+     * dropped whatever the backend had added since. Set only on a message
+     * rehydrated from history, where the saved row is in hand.
+     */
+    rawResponse?: Record<string, unknown>;
+    /**
+     * The narrator's progress while the answer was being worked out — "reading
+     * the schema", "running the query". Shown live under the question, then
+     * collapsed into a "Steps taken" accordion once the answer is in. Absent for
+     * a backend that does not narrate, which renders exactly as before.
+     */
+    narration?: {
+        elapsedMs: number;
+        text: string;
+    }[];
+    /**
+     * Files the answer handed over, as references — the id, the name, and enough
+     * to label the tile. The download link is minted per press, so it is not here;
+     * see ui/components/FileDownloads.
+     */
+    generatedFiles?: {
+        id: string;
+        fileName: string;
+        size?: number;
+        version?: number;
+    }[];
+    /**
+     * Files the question carried up, named on the user's own bubble so it is
+     * clear afterwards what the answer was given to work from.
+     */
+    attachments?: {
+        key: string;
+        fileName: string;
+        size: number;
+        contentType?: string;
+    }[];
+    /** When this was said. ISO 8601; `createdAt` for a message read back from a thread. */
+    timestamp?: string;
+    /**
+     * How long the answer took, saved with it.
+     *
+     * Only for a message read back from history: a response this bubble watched
+     * being generated has its own live timer, and "now − start" on a rehydrated
+     * one would measure its age instead.
+     */
+    durationMs?: number;
+}
 
 interface UseSuperAtomOptions {
+    /** A Superatom session token, passed directly (our own apps). Use `getToken` for SDK sign-in instead. */
     token?: string;
     userId?: string;
     projectId: string;
+    /**
+     * SDK sign-in with your own login: return a short-lived JWT for the signed-in
+     * user, signed by YOUR backend with your Superatom SDK secret. Called at start
+     * and again whenever the session needs renewing — e.g.
+     * `() => fetch('/api/superatom-token').then(r => r.text())`.
+     */
+    getToken?: () => Promise<string> | string;
+    /**
+     * Called when sign-in fails in a way retrying cannot fix: `getToken` threw, or
+     * Superatom refused the token (invalid, SDK not enabled, user deactivated).
+     * The SDK stops reconnecting; call `reconnect()` once the user can sign in again.
+     */
+    onAuthError?: (error: SuperAtomAuthError) => void;
+    /**
+     * Which chat agent this assistant is.
+     *
+     * A project can hold more than one — a shipments agent and an audits agent,
+     * say — and a thread belongs to the one it was asked to. The sidebar lists
+     * only this agent's threads, a new thread is saved against it, and so is a
+     * bookmark.
+     *
+     * Required, and it used to be optional. A project with one agent resolves it
+     * by itself, which made omitting it look safe — and on a project with two it
+     * silently stopped scoping anything: every agent's threads in one list, new
+     * ones tagged with none, bookmarks saved with a null agent. A type that says
+     * "optional" while the runtime quietly misbehaves is the worst of both, so
+     * the resolve stays as a convenience for the single-agent case and the
+     * answer is now always asked for.
+     */
+    agentId: string;
+    /** sa-api URL. Default: prod. For testing against dev / local only. */
+    apiUrl?: string;
+    /** WebSocket URL. Default: prod. For testing against dev / local only. */
+    wsUrl?: string;
     debug?: boolean;
+    /** Stream the answer as it is written. On by default; false waits for the whole reply. */
     streaming?: boolean;
+    /**
+     * Internal. False makes this instance inert: no sign-in, no socket, no
+     * bundle. `useSuperAtom` calls the implementation either way so the hook
+     * order never changes, then returns the provider's session instead of this
+     * one — React forbids calling a hook conditionally, so the switch has to be
+     * in what the hook does, not whether it runs.
+     */
+    enabled?: boolean;
 }
 interface UseSuperAtomReturn {
     bundleReady: boolean;
@@ -3506,9 +4450,127 @@ interface UseSuperAtomReturn {
     input: string;
     setInput: (value: string) => void;
     sendMessage: () => void;
+    /** A question is in flight in the thread on screen. */
     isSending: boolean;
+    /**
+     * Stop the in-flight response in the thread on screen (keeps any partial
+     * answer, labels it "Stopped"). A question answering in another thread is
+     * left running.
+     */
+    abortRequest: () => void;
+    /**
+     * Threads whose answer arrived while the user was looking at something else.
+     * Cleared when the thread is opened — what the sidebar's unread dot reads.
+     */
+    unreadThreadIds: Set<string>;
+    /**
+     * Threads with a question in flight right now — what the sidebar's spinner
+     * reads, so a thread answering in the background is visibly busy.
+     */
+    respondingThreadIds: Set<string>;
+    /** The open thread has older messages on the server than have been loaded. */
+    hasMoreMessages: boolean;
+    /** A page of older messages is being fetched. */
+    isLoadingOlderMessages: boolean;
+    /** Prepend the next page of older messages in the open thread. */
+    loadOlderMessages: () => void;
+    /**
+     * Delete a bookmark by its id. The list itself is read from the bookmarks
+     * store (`useBookmarks`), which this keeps in step.
+     */
+    removeBookmark: (id: number) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** More bookmarks match than have been loaded. */
+    hasMoreBookmarks: boolean;
+    /** A page of bookmarks is being fetched. */
+    isLoadingBookmarks: boolean;
+    /** Append the next page of bookmarks — what the sidebar calls as it scrolls. */
+    loadMoreBookmarks: () => void;
+    /** The user's conversation threads, most recent first */
+    threads: ThreadSummary[];
+    /** More threads exist on the server than have been loaded. */
+    hasMoreThreads: boolean;
+    /** A page of threads is being fetched. */
+    isLoadingThreads: boolean;
+    /** Append the next page of threads — what the sidebar calls as it scrolls. */
+    loadMoreThreads: () => void;
+    /** Thread the chat is currently in */
+    activeThreadId: string;
+    /** Open a saved thread and load its messages */
+    openThread: (threadId: string) => void;
+    /** Start a fresh chat (new thread) */
+    newChat: () => void;
+    /** A saved thread's messages are loading */
+    isLoadingThread: boolean;
+    /**
+     * The chat is ready and empty — show a greeting (e.g. `<NewChatHero>`) instead
+     * of the message list. Saves every app computing the same condition.
+     */
+    isNewChat: boolean;
+    /** Re-fetch the thread list */
+    refreshThreads: () => void;
+    /** Delete a thread and all its messages; if it's the open one, starts a new chat */
+    deleteThread: (threadId: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Rename a thread */
+    renameThread: (threadId: string, title: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** The signed-in user (SDK sign-in with `getToken` only; null until signed in). */
+    user: SdkUser | null;
+    /** The sign-in failure that stopped the SDK, if any (same as passed to `onAuthError`). */
+    authError: SuperAtomAuthError | null;
+    /**
+     * A sign-in attempt is in flight — at start, on renewal, and after
+     * `reconnect()`. The chat already shows "Signing in…" by itself; use this only
+     * if you want your own screen for it.
+     */
+    isSigningIn: boolean;
+    /** Try signing in and connecting again — e.g. after the user signed in again on your side. */
+    reconnect: () => void;
+    /**
+     * The project and chat agent this session is actually on.
+     *
+     * Returned because under a `SuperatomProvider` the ids are given to the
+     * provider, so a component inside it has no other way to know them — and
+     * anything addressed to the project rather than to the socket needs them.
+     * File attachments are uploaded to sa-api by project and app, which is why
+     * the "+" in the composer was never shown: `SuperatomAssistant` was reading
+     * them from its own props, and under a provider it is not given any.
+     *
+     * `agentId` is the one in use, not the raw option: a project with exactly one
+     * chat agent resolves it, so it is set even when the host never passed it.
+     */
+    projectId: string;
+    agentId?: string;
+    /**
+     * Who the session is for, as the SDK resolved it.
+     *
+     * `user.id` with SDK sign-in, and the only answer at all for a host passing
+     * `userId` or a `token` directly — there is no `user` object on that path.
+     * Anything addressed to the person rather than to the socket needs this.
+     */
+    userId: string;
 }
-declare function useSuperAtom({ token, userId, projectId, debug, streaming }: UseSuperAtomOptions): UseSuperAtomReturn;
+
+interface SuperatomProviderProps extends UseSuperAtomOptions {
+    children: ReactNode;
+}
+declare function SuperatomProvider({ children, ...options }: SuperatomProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * The session this part of the tree is on.
+ *
+ * Takes no arguments: the options live on the provider, which is the only
+ * place a session is made.
+ */
+declare function useSuperAtom(): UseSuperAtomReturn;
+/** True when a `SuperatomProvider` is above this component. */
+declare function useHasSuperatomProvider(): boolean;
 
 interface ChatInputProps {
     input: string;
@@ -3518,22 +4580,94 @@ interface ChatInputProps {
     placeholder?: string;
     primaryColor?: string;
     className?: string;
+    /** A response is in flight — swaps Send for Stop and enables Esc-to-stop */
+    isResponding?: boolean;
+    onStop?: () => void;
+    /**
+     * Files. Off unless a host asks for it: a project whose agent does nothing
+     * with files should not show a "+" that leads nowhere.
+     */
+    enableAttachments?: boolean;
+    /** Picked from the file dialog — already filtered by `accept`, not yet checked. */
+    onAttachFiles?: (files: File[]) => void;
+    /** This chat can hold no more. The "+" stays pressable so it can say why. */
+    attachmentsFull?: boolean;
+    onAttachBlocked?: () => void;
+    /** The tray: what is uploading, ready or failed. */
+    attachments?: {
+        id: number;
+        name: string;
+        status: 'uploading' | 'ready' | 'error';
+        error?: string;
+    }[];
+    onRemoveAttachment?: (id: number) => void;
+    /** A file is still going up — the question waits rather than arriving without it. */
+    sendBlocked?: boolean;
+    /**
+     * Speak the question instead of typing it. Off unless a host asks for it,
+     * and even then the microphone only appears once sa-api confirms this
+     * deployment can transcribe — a button that always fails is worse than none.
+     */
+    enableVoice?: boolean;
+    /** Which project the recording belongs to, for the transcriber's vocabulary. */
+    projectId?: string;
 }
-declare function ChatInput({ input, setInput, onSend, disabled, placeholder, primaryColor, className, }: ChatInputProps): react_jsx_runtime.JSX.Element;
+declare function ChatInput({ input, setInput, onSend, disabled, placeholder, primaryColor, className, isResponding, onStop, enableAttachments, onAttachFiles, attachmentsFull, onAttachBlocked, attachments, onRemoveAttachment, sendBlocked, enableVoice, projectId, }: ChatInputProps): react_jsx_runtime.JSX.Element | null;
 
 interface MessageListProps {
     messages: ChatMessage[];
     bundleReady: boolean;
     connectingText?: string;
+    /** Placeholder for an empty conversation. Nothing is shown unless it is set. */
     emptyText?: string;
+    /**
+     * Shown in place of `emptyText` while the chat is empty — e.g. a greeting, or
+     * `<NewChatHero>` with the input inside it. With this, the whole chat is just
+     * <MessageList /> + <ChatInput />; without it, render your own empty screen
+     * using the hook's `isNewChat`.
+     */
+    emptyState?: ReactNode;
     className?: string;
+    /** A response is in flight — shows a Stop button on the latest assistant message */
+    isResponding?: boolean;
+    onStop?: () => void;
+    /** A saved thread is being opened — shows a loading state instead of the empty text */
+    isLoadingThread?: boolean;
+    loadingThreadText?: string;
+    /**
+     * Paging backwards inside the thread — pass `hasMoreMessages`,
+     * `isLoadingOlderMessages` and `loadOlderMessages` from useSuperAtom. Left
+     * out, the list shows whatever `messages` holds and never asks for more.
+     *
+     * The scroll position is kept across a prepend, so the reader stays on the
+     * message they were looking at rather than being pushed down a page.
+     */
+    hasMoreMessages?: boolean;
+    isLoadingOlderMessages?: boolean;
+    onLoadOlderMessages?: () => void;
+    /**
+     * The host owns the scrolling. The list then takes its natural height and
+     * flows inside the host's scroll box — what a dashboard with its thread
+     * underneath needs, so the two scroll as one page rather than two panes.
+     */
+    flow?: boolean;
 }
-declare function MessageList({ messages, bundleReady, connectingText, emptyText, className, }: MessageListProps): react_jsx_runtime.JSX.Element;
+declare function MessageList({ messages, bundleReady, connectingText, emptyText, emptyState, className, isResponding, onStop, isLoadingThread, loadingThreadText, hasMoreMessages, isLoadingOlderMessages, onLoadOlderMessages, flow, }: MessageListProps): react_jsx_runtime.JSX.Element;
 
 interface MessageBubbleProps {
     message: ChatMessage;
+    /** When set, this message's response is in flight and a Stop button is shown */
+    onStop?: () => void;
+    /**
+     * Drop the bookmark, delete and feedback actions, keeping the timing and the
+     * timestamp. For the bookmark page, where the answer on screen is the saved
+     * copy: bookmarking what is already a bookmark means nothing, deleting would
+     * reach for a conversation row this page never loaded, and rating belongs
+     * with the answer in its thread.
+     */
+    hideActions?: boolean;
 }
-declare function MessageBubble({ message }: MessageBubbleProps): react_jsx_runtime.JSX.Element;
+declare function MessageBubble({ message, onStop, hideActions }: MessageBubbleProps): react_jsx_runtime.JSX.Element;
 
 interface MenuV1Item {
     id: string;
@@ -3561,29 +4695,800 @@ interface MenuV1Root {
 }
 
 interface SidebarProps {
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
     className?: string;
     onItemClick?: (item: MenuV1Item) => void;
+    /** Shows the "New chat" button when provided (pass `newChat` from useSuperAtom) */
+    onNewChat?: () => void;
+    /** Conversation threads for the "Chats" section (pass `threads` from useSuperAtom) */
+    threads?: ThreadSummary[];
+    /** Highlighted thread (pass `activeThreadId` from useSuperAtom) */
+    activeThreadId?: string;
+    /**
+     * Threads whose answer landed while the user was elsewhere — each gets a dot
+     * until opened (pass `unreadThreadIds` from useSuperAtom).
+     */
+    unreadThreadIds?: Set<string>;
+    /**
+     * Threads answering right now — each gets a spinner while the user is looking
+     * at something else (pass `respondingThreadIds` from useSuperAtom).
+     */
+    respondingThreadIds?: Set<string>;
+    /** Open a thread (pass `openThread` from useSuperAtom) */
+    onSelectThread?: (threadId: string) => void;
+    /**
+     * Paging for the Chats list — pass `hasMoreThreads`, `isLoadingThreads` and
+     * `loadMoreThreads` from useSuperAtom. Left out, the list shows whatever
+     * `threads` holds and never asks for more.
+     */
+    hasMoreThreads?: boolean;
+    isLoadingThreads?: boolean;
+    onLoadMoreThreads?: () => void;
+    /** The same three for the Bookmarks list, from the same hook. */
+    hasMoreBookmarks?: boolean;
+    isLoadingBookmarks?: boolean;
+    onLoadMoreBookmarks?: () => void;
+    /** Enables "Delete chat" in each thread's menu (pass `deleteThread` from useSuperAtom) */
+    onDeleteThread?: (threadId: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Enables "Rename" in each thread's menu (pass `renameThread` from useSuperAtom) */
+    onRenameThread?: (threadId: string, title: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Shows the "Home" entry when provided. The host decides what Home renders.
+     * Its label is the bundle Home component's `Metadata.homeLabel`, else "Home".
+     */
+    onHome?: () => void;
+    /** Which view the host is showing, so the entry can be highlighted. */
+    activeView?: 'home' | 'chat' | 'dashboard' | 'report' | 'bundle-dashboard' | 'bookmark';
+    /**
+     * Open one of the project bundle's own dashboards — components that declare
+     * `Metadata.dashboard` (see useBundleDashboards). Shows one entry per
+     * dashboard when provided; the list comes from the bundle, so the host
+     * supplies only what to do on click. Receives the component's key.
+     */
+    onSelectBundleDashboard?: (key: string) => void;
+    /** Highlighted bundle dashboard (its key), when `activeView` is 'bundle-dashboard'. */
+    activeBundleDashboard?: string;
+    /** Open a dashboard. Shows the "Dashboards" section when provided. */
+    onSelectDashboard?: (dashboardId: string) => void;
+    /** Highlighted dashboard. */
+    activeDashboardId?: string;
+    /** Open a report. Shows the "Reports" section when provided. */
+    onSelectReport?: (reportId: string) => void;
+    /** Highlighted report. */
+    activeReportId?: string;
+    /**
+     * Open a saved answer. Shows the "Bookmarks" section when provided — the list
+     * itself comes from the SDK, so the host supplies only what to do on click.
+     */
+    onSelectBookmark?: (bookmark: BookmarkData) => void;
+    /** Highlighted bookmark, when `activeView` is 'bookmark'. */
+    activeBookmarkId?: number;
+    /** Remove a bookmark. The trash icon on a row appears only when given. */
+    onDeleteBookmark?: (id: number) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * The project's logo in the header. Default true.
+     *
+     * Off for a host whose own chrome already carries its branding — otherwise
+     * the customer sees two logos stacked. The project's name and its data
+     * sources stay either way; this hides the mark alone.
+     */
+    showLogo?: boolean;
+    primaryColor?: string;
+}
+declare function Sidebar({ children, className, onItemClick, onNewChat: onNewChatProp, threads: threadsProp, activeThreadId: activeThreadIdProp, unreadThreadIds: unreadThreadIdsProp, respondingThreadIds: respondingThreadIdsProp, onSelectThread: onSelectThreadProp, hasMoreThreads: hasMoreThreadsProp, isLoadingThreads: isLoadingThreadsProp, onLoadMoreThreads: onLoadMoreThreadsProp, hasMoreBookmarks: hasMoreBookmarksProp, isLoadingBookmarks: isLoadingBookmarksProp, onLoadMoreBookmarks: onLoadMoreBookmarksProp, onDeleteThread: onDeleteThreadProp, onRenameThread: onRenameThreadProp, onHome: onHomeProp, activeView: activeViewProp, onSelectBundleDashboard: onSelectBundleDashboardProp, activeBundleDashboard: activeBundleDashboardProp, onSelectDashboard: onSelectDashboardProp, activeDashboardId: activeDashboardIdProp, onSelectReport: onSelectReportProp, activeReportId: activeReportIdProp, onSelectBookmark: onSelectBookmarkProp, activeBookmarkId: activeBookmarkIdProp, onDeleteBookmark: onDeleteBookmarkProp, showLogo, primaryColor, }: SidebarProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Opening a dashboard: it shows on its own, whatever was asked on it before.
+ *
+ * Only the thread is touched. `onScreen` has exactly one owner — the mounted
+ * DashboardPage — because anything else that sets it has no matching moment to
+ * clear it, and a stale dashboard here blanks the ordinary chat view.
+ *
+ * The clearing lives here rather than in setDashboardOnScreen because that one
+ * also fires on unmount — in StrictMode a remount would wipe the conversation
+ * the user is reading. Navigating to a dashboard is the deliberate act, and it
+ * is the only thing that resets, so clicking the same dashboard again starts
+ * over exactly like clicking a different one.
+ */
+declare function openDashboard(_dashboardId: string): void;
+/**
+ * Opening a thread that was started on a dashboard: the dashboard comes back
+ * above it, rather than the thread opening on its own.
+ *
+ * runtime-react does this by routing the thread to `/d/:dashboardId/c/:threadId`
+ * instead of `/c/:threadId` — see its `threadPath()`. Here the host switches to
+ * the dashboard view, which mounts DashboardPage and sets `onScreen`; this only
+ * records the thread that belongs under it.
+ */
+declare function openDashboardThread(dashboardId: string, threadId: string): void;
+/** Forgets the thread under the dashboard — it was deleted, so the dashboard is alone again. */
+declare function clearDashboardThread(): void;
+/** The dashboard currently on screen, if any. */
+declare function dashboardOnScreen(): string | null;
+/** The thread to show under the dashboard on screen. null = the dashboard alone. */
+declare function dashboardThread(): string | null;
+/** The latest filter values a dashboard reported. */
+declare function setDashboardFilters(dashboardId: string, values: Record<string, unknown>): void;
+/** The dashboard a thread belongs to, if it is known to belong to one. */
+declare function dashboardForThread(threadId: string): string | undefined;
+/**
+ * A thread's dashboard: already known, or read from the thread's own `config`.
+ *
+ * The map covers a thread started or listed in this session, which is the
+ * common case. The lookup is for the rest — a thread opened by id before any
+ * list has loaded, which is what a URL like /chat/:threadId does on a cold
+ * page. Undefined for a plain chat thread, and equally for a backend that
+ * cannot answer, since both mean "do not open this on a dashboard".
+ */
+declare function resolveThreadDashboard(userId: string, threadId: string, 
+/** The chat agent the thread belongs to, when the host works in agents. */
+agentId?: string): Promise<string | undefined>;
+
+interface ReportPageProps {
+    /** Which report to open. Pass the id the Sidebar handed you. */
+    reportId: string;
+    className?: string;
+}
+/**
+ * A report, rendered the way runtime-react renders it.
+ *
+ * Far simpler than a dashboard: a report is one DSL tree, so there is no grid,
+ * no pages and no layout engine — fetch it, normalise the component names, hand
+ * it to DSLRenderer. The SDK fetches it itself, so a host only says which one.
+ */
+declare function ReportPageInner({ reportId, className }: ReportPageProps): react_jsx_runtime.JSX.Element;
+/** Memoised for the same reason as DashboardPage — see the note there. */
+declare const ReportPage: React.MemoExoticComponent<typeof ReportPageInner>;
+
+interface BookmarkPageProps {
+    /** The bookmark's own id, as listed in the sidebar. */
+    bookmarkId: number;
+    /** Called when the bookmark turns out to be gone, so the host can leave. */
+    onMissing?: () => void;
+    className?: string;
+}
+/**
+ * One saved answer, on its own.
+ *
+ * A bookmark means "this answer, without the conversation around it" — so this
+ * rebuilds what was saved into the same assistant message a live response
+ * produces, and hands it to `MessageBubble`. It therefore renders identically
+ * to the answer it was taken from, actions row and all, without re-running
+ * anything.
+ *
+ * Replaces an earlier shortcut that opened the thread the bookmark came from.
+ * That showed the whole conversation rather than the answer, highlighted the
+ * thread in the sidebar instead of the bookmark, and on a long thread did not
+ * even land on the right message.
+ *
+ * Follows runtime-react's `BookmarkView`, minus its route: the SDK owns no
+ * routing, so the host says which bookmark to show.
+ */
+declare function BookmarkPage({ bookmarkId, onMissing, className }: BookmarkPageProps): react_jsx_runtime.JSX.Element;
+
+interface DashboardPageProps {
+    /** Which dashboard to open. Pass the id the Sidebar handed you. */
+    dashboardId: string;
+    /**
+     * Rendered inside someone else's scroll area — MessageList's `header`, so the
+     * dashboard and the questions about it scroll together.
+     *
+     * Drops this component's own height and scrolling (a scroller inside a
+     * scroller traps the wheel) and pins the title row instead, so it stays
+     * readable once the thread has scrolled the widgets away.
+     */
+    embedded?: boolean;
+    className?: string;
+}
+/**
+ * A dashboard.
+ *
+ * The SDK fetches it through the client, so a host only has to say which one.
+ *
+ * Only program dashboards are drawn. A DSL dashboard — a stored widget tree,
+ * laid out on a grid — is recognised and refused: the GridStack canvas that
+ * drew them is gone, and the page says so rather than rendering an empty
+ * frame. See the note on `isDsl` below.
+ */
+declare function DashboardPageInner({ dashboardId, embedded, className }: DashboardPageProps): react_jsx_runtime.JSX.Element;
+/**
+ * Memoised because the composer is a sibling: the chat's `input` lives in
+ * useSuperAtom, so every keystroke re-renders the assistant and would re-run a
+ * whole dashboard's layout with it. The props here are a dashboard id and two
+ * flags, so a shallow compare is exactly right.
+ */
+declare const DashboardPage: React.MemoExoticComponent<typeof DashboardPageInner>;
+
+interface DashboardConversationProps extends Omit<MessageListProps, 'className' | 'flow'> {
+    /** Which dashboard the conversation is about. Pass the id the Sidebar handed you. */
+    dashboardId: string;
+    /** The composer. Stays below the scroll, always reachable. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * A dashboard with its thread underneath, as one page: the dashboard at its own
+ * height, the conversation flowing below it, and a single scrollbar over both.
+ *
+ * It opens on the dashboard rather than at the end of the thread — the question
+ * is about what is on screen, so the dashboard is what you should see first.
+ */
+declare function DashboardConversation({ dashboardId, children, className, ...messageListProps }: DashboardConversationProps): react_jsx_runtime.JSX.Element;
+
+interface HomePageProps {
+    className?: string;
+    /**
+     * Which bundle component to show — a key in `SUPERATOM.COMPONENTS`. Default
+     * `'Home'`. Any other key renders one of the bundle's own dashboards (those
+     * with `Metadata.dashboard`, listed by useBundleDashboards) as a page.
+     */
+    componentKey?: string;
+}
+/**
+ * The project's own Home dashboard, as a page.
+ *
+ * It renders nothing of its own: `Home` is a component of the project bundle the
+ * server delivers, which `registerBundleComponents` puts in COMP_REGISTRY under
+ * `COMP_HOME` (the key is uppercased there, so `Home` is not a valid type). This
+ * component only gives it a box to live in.
+ *
+ * `SA_RUNTIME` is the one prop that has to be supplied here. Everywhere else it
+ * is built by useSuperAtom and baked into a message's DSL props; none of
+ * DSLRenderer, DynamicComponent or BundleComponentWrapper adds it, they all pass
+ * props straight through. Home is not an answer inside a thread, so there is no
+ * real block or thread to name and a stable synthetic pair stands in. The field
+ * is optional in DataRequestPayloadSchema, so a query carrying this is still
+ * well formed on the wire.
+ */
+declare function HomePageInner({ className, componentKey }: HomePageProps): react_jsx_runtime.JSX.Element;
+/** Memoised for the same reason as DashboardPage — see the note there. */
+declare const HomePage: React.MemoExoticComponent<typeof HomePageInner>;
+
+/**
+ * Dashboards the project bundle ships, and what its Home button is called.
+ *
+ * Both come from the bundle's component metadata, so the SDK never hardcodes
+ * which dashboards a project has:
+ *
+ *   Metadata.dashboard = { label, icon?, order?, placement?, group?, groupIcon? }
+ *       makes a component a top-level dashboard with its own sidebar entry.
+ *   Metadata.homeLabel
+ *       is the Home button's text when that component is registered as `Home`.
+ *
+ * Ported from runtime-react's lib/bundleDashboards.ts so a bundle reads the same
+ * in both hosts; only the refresh trigger differs (see useBundleDashboards).
+ * The convention is documented in a project's frontend/src/modules/DASHBOARDS.md.
+ */
+/** A top-level dashboard entry, discovered from the loaded bundle. */
+interface BundleDashboard {
+    /** Key in SUPERATOM.COMPONENTS; also what HomePage's `componentKey` takes. */
+    key: string;
+    label: string;
+    /** Iconify icon name. */
+    icon: string;
+    /** Ascending sort order among dashboards. */
+    order: number;
+    /**
+     * "footer" pins the entry below everything else, for utility pages like Docs
+     * or Help. Anything else — or nothing — is "main".
+     */
+    placement: 'main' | 'footer';
+    /** Optional heading; dashboards sharing it nest under one entry. */
+    group?: string;
+    /** Icon for that heading, taken from the first dashboard that sets one. */
+    groupIcon?: string;
+}
+/** A sidebar row: a dashboard on its own, or a named group of dashboards. */
+type BundleDashboardEntry = {
+    kind: 'dashboard';
+    dashboard: BundleDashboard;
+} | {
+    kind: 'group';
+    name: string;
+    icon: string;
+    order: number;
+    dashboards: BundleDashboard[];
+};
+/**
+ * Every bundle component with `Metadata.dashboard`, sorted by `order`.
+ *
+ * The component currently serving as Home is left out — Home has its own button
+ * — so a dashboard aliased to `Home` never appears twice, even when it is also
+ * registered under its own key.
+ */
+declare function readBundleDashboards(): BundleDashboard[];
+/**
+ * Nest grouped dashboards under one heading, placed where its first member
+ * would sit. Ungrouped dashboards come back unchanged.
+ */
+declare function groupBundleDashboards(list: BundleDashboard[]): BundleDashboardEntry[];
+/** The Home button's text: the Home component's `Metadata.homeLabel`, else "Home". */
+declare function readHomeLabel(): string;
+/**
+ * The bundle's dashboards, kept current.
+ *
+ * runtime-react re-reads on its own module-loaded events, which the SDK does not
+ * fire. Here the signal is the end of start-up: useSuperAtom marks the chat ready
+ * only after the bundle has loaded and registered its components.
+ */
+declare function useBundleDashboards(): BundleDashboard[];
+/** The Home button's text, kept current the same way. */
+declare function useHomeLabel(): string;
+
+interface NewChatHeroProps {
+    /** The chat input to center, e.g. <ChatInput ... /> */
+    children: React__default.ReactNode;
+    title?: string;
+    subtitle?: string;
+    className?: string;
+}
+/**
+ * Centered "new chat" empty state (like most chat apps): a greeting with the
+ * chat box in the middle of the screen. Same as Runtime-react's NewChatHero.
+ * Render it instead of <MessageList /> + bottom <ChatInput /> while the chat is empty.
+ *
+ * Type and spacing follow the width of its own box rather than the window, so it
+ * reads correctly embedded in a narrow side panel as well as full-page.
+ */
+declare function NewChatHero({ children, title, subtitle, className, }: NewChatHeroProps): react_jsx_runtime.JSX.Element;
+
+type ChatPageProps = NewChatHeroProps;
+/**
+ * The empty chat, as a page.
+ *
+ * It is `NewChatHero` and nothing else — the greeting with the chat box centred
+ * on the screen rather than pinned to the bottom. It exists so the four views
+ * the assistant can show are four pages side by side, instead of three pages and
+ * one component reached a different way.
+ *
+ * Put the composer inside it: that is the whole point of this view.
+ */
+declare function ChatPage(props: ChatPageProps): react_jsx_runtime.JSX.Element;
+
+declare function ThreadRowsSkeleton({ count }: {
+    count: number;
+}): react_jsx_runtime.JSX.Element;
+
+interface ConfirmDeleteModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onConfirm: () => void;
+    isDeleting: boolean;
+    title?: string;
+    message?: string;
+}
+/** Same as Runtime-react's components/chat/ConfirmDeleteModal */
+declare function ConfirmDeleteModal({ isOpen, onClose, onConfirm, isDeleting, title, message, }: ConfirmDeleteModalProps): react_jsx_runtime.JSX.Element | null;
+
+type AnswerVerdict = 'correct' | 'partial' | 'incorrect' | null;
+interface FeedbackModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onSubmit?: (status: AnswerVerdict, feedbackText: string) => void;
+    isSubmitting: boolean;
+    title?: string;
+    submitLabel?: string;
+}
+/**
+ * What was wrong with this answer.
+ *
+ * Both fields are optional, deliberately: a verdict on its own is a signal
+ * worth having, and so is a note without one. Requiring both would mean most
+ * people submit neither.
+ *
+ * Copied from runtime-react's `FeedbackModal`, with its `VoiceTextarea` swapped
+ * for a plain one — voice input is not ported, and a textarea that silently
+ * lacks its microphone is worse than one that never had it.
+ */
+declare function FeedbackModal({ isOpen, onClose, onSubmit, isSubmitting, title, submitLabel, }: FeedbackModalProps): react_jsx_runtime.JSX.Element | null;
+
+interface BookmarkModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onCreate?: (name: string, description: string) => void;
+    isBookmarking: boolean;
+    /** Prefilled from the answer's own title and description, so most saves are one click. */
+    defaults: {
+        name: string;
+        description: string;
+    };
+    title?: string;
+    submitLabel?: string;
+}
+/**
+ * Name an answer so it can be found again.
+ *
+ * The name is required and the description is not: a bookmark list of
+ * "Untitled" is no more use than no list, while a missing description costs
+ * nothing. Both are prefilled from the answer itself where it says what it is.
+ *
+ * Copied from runtime-react's `BookmarkModal`.
+ */
+declare function BookmarkModal({ isOpen, onClose, onCreate, isBookmarking, defaults, title, submitLabel, }: BookmarkModalProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Run a menu item — a quick action, or anything else the project's menu offers.
+ *
+ * It puts a component into the conversation through the bundle's own
+ * `SA.addComponent`, which is what the chat listens to. Shared by the Sidebar's
+ * default handler and by SuperatomAssistant, which wraps it so the chat is on
+ * screen first: added to a conversation nobody is looking at, the action looks
+ * like nothing happened.
+ */
+declare function runMenuItem(item: MenuV1Item): void;
+
+declare function useBookmarks(): BookmarkData[];
+/** Re-reads on every change, so a bubble's icon follows the list. */
+declare function useBookmarkForMessage(messageId: string): BookmarkData | undefined;
+
+/** The configuration mistake, if there is one. Re-renders on change. */
+declare function useConfigError(): Error | null;
+
+/** Detected once at module load — the answer never changes for a given browser. */
+declare const SUPPORTED_MIME: string | null;
+type VoiceState = 'idle' | 'recording' | 'transcribing' | 'error';
+/**
+ * Registers `onToggle` on Ctrl/Cmd+., but only actually invokes it while this
+ * call is the topmost registered voice surface — background surfaces still
+ * register, so the stack stays correct, but no-op on the keypress.
+ */
+declare function useVoiceShortcut(eligible: boolean, onToggle: () => void): void;
+interface UseVoiceInputReturn {
+    state: VoiceState;
+    error: string | null;
+    elapsedMs: number;
+    maxMs: number;
+    start: () => void;
+    stop: () => void;
+    cancel: () => void;
+    toggle: () => void;
+    clearError: () => void;
+}
+declare function useVoiceInput(onTranscript: (text: string) => void, projectId?: string): UseVoiceInputReturn;
+
+/** runtime-react's fallback. Ours was indigo, which is why the two differed. */
+declare const DEFAULT_THEME_COLOR = "#14b8a6";
+/**
+ * The colour to paint with.
+ *
+ * `override` is the component's own `primaryColor` prop and wins outright, so a
+ * host styling one surface by hand still can.
+ */
+declare function useThemeColor(override?: string): string;
+
+/** A file already uploaded, as the question carries it. */
+interface ChatAttachment {
+    key: string;
+    fileName: string;
+    size: number;
+    contentType?: string;
+}
+/** A file an answer handed over. The answer keeps only the id. */
+interface DeliveredFile {
+    id: string;
+    fileName: string;
+    size?: number;
+    version?: number;
+}
+
+interface FileDownloadsProps {
+    files: DeliveredFile[];
+}
+/**
+ * The files an answer hands over, each with a download button.
+ *
+ * The answer carries only the file's id. The link is asked for when the button
+ * is pressed rather than when the answer renders: it lasts minutes and is
+ * minted for the signed-in user, so one fetched up front would be dead by the
+ * time anyone clicked it, and fetching one per file per answer would be a
+ * burst of requests for links mostly never used.
+ */
+declare function FileDownloads({ files }: FileDownloadsProps): react_jsx_runtime.JSX.Element | null;
+
+interface PendingAttachment {
+    id: number;
+    name: string;
+    size: number;
+    status: 'uploading' | 'ready' | 'error';
+    error?: string;
+    /** Set once the upload is confirmed. */
+    uploaded?: ChatAttachment;
+}
+interface AttachTarget {
+    projectId?: string;
+    /** The chat agent — `agentId`. */
+    appId?: string;
+    threadId?: string;
+}
+declare function useAttachments(): PendingAttachment[];
+/** A chat that can take no more — by count or by size, counting the tray. */
+declare function isAttachmentsFull(threadId?: string): boolean;
+/** Said when "+" is pressed on a full chat. */
+declare function notifyAttachmentsFull(threadId?: string): void;
+/**
+ * Takes the picked files and uploads them.
+ *
+ * What the server accepts — types, size — is the server's call, and a file it
+ * turns away comes back with its own message. The count and total-size limits
+ * are checked here, before anything is sent, so an over-limit file costs no
+ * upload at all.
+ */
+declare function addAttachments(files: File[], target: AttachTarget): void;
+/** Takes a file off before sending, and removes its upload. */
+declare function removeAttachment(id: number): void;
+/**
+ * The question is being sent: hands over the confirmed uploads, counts them
+ * against the thread, and empties the tray.
+ */
+declare function consumeAttachments(threadId?: string): ChatAttachment[];
+/** Everything goes — on sign-out, or when a host unmounts the assistant. */
+declare function clearAttachments(): void;
+
+interface ToasterProps {
+    /** Applied to the stack, for a host that needs it somewhere else. */
+    className?: string;
+}
+/**
+ * Where toasts appear.
+ *
+ * Top centre, as runtime-react places them (`<Toaster position="top-center" />`).
+ * The top edge is the one place nothing else in the SDK lives — the composer is
+ * at the bottom, the scroll-to-bottom button floats above it, and a toast over
+ * either covers something the user is using.
+ *
+ * Rendered in place, never portalled. A portal to `document.body` would put the
+ * stack outside `.sa-ui` — so none of our styles would reach it — and outside
+ * the shadow boundary, where the host's CSS could. `position: fixed` needs no
+ * portal here: nothing in the tree above makes itself a containing block.
+ *
+ * One of these belongs in `SuperatomAssistant`, which is why a host composing
+ * their own layout has to place it themselves; `toast.success(...)` from
+ * anywhere is a no-op without it, which is the right failure — silent, not
+ * broken.
+ *
+ * `aria-live="polite"` rather than `assertive`: these confirm something the
+ * user just did, so they should wait for a pause rather than cut in. Errors go
+ * through the same region deliberately — an error toast here is still a
+ * confirmation of an action, not an alert the user must handle.
+ */
+declare function Toaster({ className }: ToasterProps): react_jsx_runtime.JSX.Element | null;
+
+type ToastKind = 'success' | 'error' | 'info' | 'warning';
+interface Toast {
+    id: number;
+    kind: ToastKind;
+    message: string;
+    /** How long before it dismisses itself. `0` means it stays until dismissed. */
+    duration: number;
+}
+/**
+ * Raise one. Returns its id, so a caller holding a long-running toast
+ * (`duration: 0`) can take it down when the work finishes.
+ */
+declare function showToast(message: string, kind?: ToastKind, duration?: number): number;
+declare function dismissToast(id: number): void;
+/** Everything goes — on sign-out, or when a host unmounts the assistant. */
+declare function clearToasts(): void;
+declare function useToasts(): Toast[];
+/**
+ * The shorthands, which is what calling code should use.
+ *
+ * `toast.success('Thread deleted')` reads the way the runtime's does, so moving
+ * code between the two does not mean rewriting its confirmations.
+ */
+declare const toast: {
+    success: (message: string, duration?: number) => number;
+    error: (message: string, duration?: number) => number;
+    info: (message: string, duration?: number) => number;
+    warning: (message: string, duration?: number) => number;
+    dismiss: typeof dismissToast;
+    clear: typeof clearToasts;
+};
+
+/**
+ * The whole assistant, held until the session is back.
+ *
+ * A corner pill is the right weight for a blip nobody needs to act on. It is
+ * the wrong weight for this: between connections the thread on screen belongs
+ * to a session that no longer exists, and anything typed into it goes nowhere.
+ * Covering the surface says that plainly, and stops a question being written
+ * into a socket that is gone.
+ *
+ * Nothing is unmounted underneath — the conversation, the dashboard and the
+ * draft all survive, because this is a layer over them rather than a screen
+ * instead of them. When the session comes back, the overlay goes and what was
+ * on screen is still there.
+ *
+ * Silent until there has been a connection to lose: a first sign-in is not a
+ * reconnection, and the chat already says "Connecting to SuperAtom…" for that.
+ */
+declare function ConnectionOverlay(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * The connection, but only when there is something to say about it.
+ *
+ * Nothing renders while the socket is healthy. The states below are reached on
+ * a timer, not immediately — see useConnectionStatus, where a blip has to last
+ * a second before it is worth a pill and fifteen before it is worth alarm.
+ */
+declare function ConnectionStatusPill(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * `'connecting'` is the SDK's own, and means "never connected yet". Nothing is
+ * shown for it: a first connection is not a reconnection, and the chat already
+ * says "Connecting to SuperAtom…" by itself. The other three are runtime's.
+ */
+type ConnectionStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+/**
+ * Why the socket will not connect.
+ *
+ * The browser never exposes a WebSocket close reason — a failed handshake is
+ * always code 1006 with an empty reason — so this cannot be read off the
+ * socket. runtime-react probes `/auth/me` to tell these apart. The SDK does
+ * not: that route returns the user, their organization and every app they can
+ * open, and `services/project.ts` exists precisely to avoid putting it in a
+ * customer's network tab.
+ *
+ * It does not need to. A host signs in through `getToken`, so a dead session
+ * arrives as a sign-in failure the SDK already handles and already stores —
+ * `authError` is the answer the probe was asking for.
+ *
+ *   'auth'    — sign-in failed in a way retrying cannot fix. The host's token
+ *               is the problem, and the host has already been told through
+ *               `onAuthError`.
+ *   'network' — signed in fine, so the relay or the network is at fault.
+ *
+ * runtime's third reason, 'forbidden' (signed in to the wrong organization for
+ * this project), has no analogue here: the host picks the organization when it
+ * mints the token, and a mismatch surfaces as a sign-in failure, not as a
+ * socket that will not open.
+ */
+type DisconnectReason = 'network' | 'auth';
+declare function useConnectionStatus(): {
+    status: ConnectionStatus;
+    reason: DisconnectReason;
+    retry: () => void;
+};
+
+interface SuperatomSurfaceProps {
+    children: ReactNode;
+    /**
+     * Applied to the element the host's layout sees — the shadow host when the
+     * boundary is on, the root box when it is off. Either way it is what gives
+     * this its size.
+     */
+    className?: string;
+    /**
+     * Render inside a shadow root, so the host page's CSS cannot reach in.
+     *
+     * On by default. Scoping the stylesheet to `.sa-ui` wins the collisions it
+     * can — a bare `.btn` against our `.sa-ui .btn` — but it cannot win against
+     * a host's bare element rules, and a page that styles `button` or `input`
+     * directly reaches our components whatever our selectors say. Only a
+     * boundary stops that.
+     *
+     * The escape hatch stays because the boundary has real costs: the document
+     * can no longer see our elements, so a host script doing
+     * `document.querySelector` inside, an analytics or a11y tool that walks the
+     * DOM, or a listener reading `event.target` on `document` all see less than
+     * they did.
+     */
+    shadowDom?: boolean;
+    /**
+     * Which view the navigation opens on. Default 'home'.
+     *
+     * Ignored when a navigation is already above this — then it belongs to
+     * whoever provided that one.
+     */
+    defaultView?: AssistantView;
+}
+/**
+ * Where the SDK's UI begins.
+ *
+ * Two things, and they belong together: the shadow boundary that keeps the
+ * host's CSS out, and the root box every page inside expects to be laid out
+ * in — a flex row that fills what it is given, with `min-h-0` so the scroll
+ * areas inside size themselves instead of growing the page.
+ *
+ * This is deliberately *not* on `SuperatomProvider`. The provider says which
+ * session the tree is on; that is data, and it has no business deciding how
+ * anything renders. Putting the boundary there would isolate whatever a host
+ * puts inside it — including their own header, which is in there precisely so
+ * it can read the session — and leave them choosing between the two. Session
+ * and pixels are separate questions, so they are separate components.
+ *
+ *     <SuperatomProvider getToken={getToken} projectId={id} agentId={agent}>
+ *       <MyHeader />                 // host markup, host CSS
+ *       <SuperatomSurface>           // SDK territory from here down
+ *         <Sidebar … /><HomePage /><ChatInput … />
+ *       </SuperatomSurface>
+ *     </SuperatomProvider>
+ *
+ * `SuperatomAssistant` renders one of these itself, so a host using the single
+ * import never sees it. A host composing the pieces wraps them in one — once,
+ * around the whole tree, not around each component. Per-component boundaries
+ * would each get their own root, and the layout classes the host writes on the
+ * wrappers between them would have nothing to apply to.
+ */
+declare function SuperatomSurface({ children, className, shadowDom, defaultView, }: SuperatomSurfaceProps): react_jsx_runtime.JSX.Element;
+
+interface ShadowBoundaryProps {
+    children: ReactNode;
+    /** Applied to the host element, which is what the host app's layout sees. */
+    className?: string;
+    /**
+     * `open` lets anything outside reach in through `.shadowRoot`. That includes
+     * our own tests and devtools, so it stays open unless a host asks otherwise.
+     * `closed` hides the tree from the host's scripts — privacy from the page,
+     * not extra style isolation; the two modes are identical to CSS.
+     */
+    mode?: 'open' | 'closed';
+    /**
+     * Overrides the host element's layout, which is set inline — see the element
+     * itself for why it cannot be set with classes.
+     */
+    style?: CSSProperties;
 }
-declare function Sidebar({ children, className, onItemClick }: SidebarProps): react_jsx_runtime.JSX.Element;
+/**
+ * Renders its children inside a shadow root.
+ *
+ * The point is CSS: a rule in the host page cannot match an element inside a
+ * shadow tree, so Bootstrap's `.btn` never reaches ours however it is written
+ * or whenever it loads. Nothing else about the React tree changes — this
+ * portals, so context, state and events all behave as they did.
+ *
+ * What it does *not* do is worth saying plainly, because it is easy to assume
+ * otherwise. The boundary stops rules from matching. It does not stop
+ * inheritance, and it does not scope units: `font-size` and `line-height` set
+ * on the host's `body` inherit straight through, and `rem` still resolves
+ * against the document's `html`. Those are handled before this — by the reset
+ * and the rem conversion in `sa.css` and `scripts/scope-css.mjs` — and both
+ * remain necessary with a shadow root in place.
+ *
+ * Two stylesheets live in here. Ours, compiled when this package was built, and
+ * the project bundle's, compiled when *its* backend was built and sent over the
+ * socket with the bundle itself. Neither is produced in the browser, so nothing
+ * has to read the page to know what to generate — which is what makes a shadow
+ * root safe to use at all. The Tailwind compiler that used to do that could not
+ * see in here, and every widget the bundle rendered came up unstyled.
+ */
+declare function ShadowBoundary({ children, className, mode, style }: ShadowBoundaryProps): react_jsx_runtime.JSX.Element;
+/**
+ * The root to search from, given any element inside the boundary.
+ *
+ * `document.querySelector` cannot see into a shadow tree, so every lookup that
+ * used to start at the document has to start here instead. Returns the document
+ * when there is no shadow root above the node, which is what a host rendering
+ * the components directly gets.
+ */
+declare function searchRootFor(node: Node | null | undefined): Document | ShadowRoot;
 
 interface MenuV1RendererProps {
     items: MenuV1Item[];
     onItemClick: (item: MenuV1Item) => void;
     isCollapsed: boolean;
 }
-declare const MenuV1Renderer: React.FC<MenuV1RendererProps>;
+declare const MenuV1Renderer: React__default.FC<MenuV1RendererProps>;
 
 interface MenuV1RendererCollapsedProps {
     items: MenuV1Item[];
     onItemClick: (item: MenuV1Item) => void;
 }
-declare const MenuV1RendererCollapsed: React.FC<MenuV1RendererCollapsedProps>;
+declare const MenuV1RendererCollapsed: React__default.FC<MenuV1RendererCollapsedProps>;
 
 /**
  * @superatomai/application-sdk
  * SuperAtom Application SDK - WebSocket client, DSL renderer, and pre-built chat UI
  */
-declare const SDK_VERSION = "0.0.1";
+declare const SDK_VERSION = "0.0.3";
 
-export { type ActionsRequestMessage, ActionsRequestMessageSchema, type ActionsRequestPayload, ActionsRequestPayloadSchema, type ActionsResponseMessage, ActionsResponseMessageSchema, type ActionsResponsePayload, ActionsResponsePayloadSchema, type Binding, BindingSchema, type BundleChunkMessage, BundleChunkMessageSchema, type BundleChunkPayload, BundleChunkPayloadSchema, type BundleErrorMessage, BundleErrorMessageSchema, type BundleErrorPayload, BundleErrorPayloadSchema, type BundleRequestMessage, BundleRequestMessageSchema, type BundleRequestPayload, BundleRequestPayloadSchema, COMP_REGISTRY, ChatInput, type ChatInputProps, type ChatMessage, type ClientConfig, ClientConfigSchema, type Component, type ComponentDefinition, type ComponentRegistryType, ComponentSchema, type ComponentsRegistry, type ComponentsSendMessage, ComponentsSendMessageSchema, type ComponentsSendPayload, ComponentsSendPayloadSchema, DSLErrorBoundary, DSLRenderer, type DSLRendererProps, DSLRendererPropsSchema, type DataRequestMessage, DataRequestMessageSchema, type DataRequestPayload, DataRequestPayloadSchema, type DataResponseMessage, DataResponseMessageSchema, type DataResponsePayload, DataResponsePayloadSchema, DynamicComponent, type Expression, ExpressionSchema, type ForDirective, ForDirectiveSchema, type MenuData, MenuDataSchema, type MenuQueryFilters, MenuQueryFiltersSchema, type MenuV1Item, MenuV1Renderer, MenuV1RendererCollapsed, type MenuV1Root, type MenusRequestMessage, MenusRequestMessageSchema, type MenusRequestPayload, MenusRequestPayloadSchema, type MenusResponseMessage, MenusResponseMessageSchema, type MenusResponsePayload, MenusResponsePayloadSchema, type Message, MessageBubble, type MessageBubbleProps, MessageList, type MessageListProps, type MessageParticipant, MessageParticipantSchema, MessageSchema, type MountFunction, type QuerySpec, QuerySpecSchema, type ResolvedClientConfig, SDK_VERSION, Sidebar, type SidebarProps, type SuperAtomGlobal, SuperatomClient, type UIComponent, UIComponentSchema, type UIElement, UIElementSchema, type UILogEntry, UILogEntrySchema, type UILogsMessage, UILogsMessageSchema, type UILogsPayload, UILogsPayloadSchema, type UseSuperAtomOptions, type UseSuperAtomReturn, type UserPromptRequestMessage, UserPromptRequestMessageSchema, type UserPromptRequestPayload, UserPromptRequestPayloadSchema, type UserPromptResponseMessage, UserPromptResponseMessageSchema, type UserPromptResponsePayload, UserPromptResponsePayloadSchema, type UserPromptSuggestionsRequestMessage, UserPromptSuggestionsRequestMessageSchema, type UserPromptSuggestionsRequestPayload, UserPromptSuggestionsRequestPayloadSchema, type UserPromptSuggestionsResponseMessage, UserPromptSuggestionsResponseMessageSchema, type UserPromptSuggestionsResponsePayload, UserPromptSuggestionsResponsePayloadSchema, getComponent, getComponentStates, getComponents, hasComponents, registerBundleComponents, resetAllFailedComponents, resetFailedComponent, resetRegistration, sanitizeDSL, index as services, setup, useDynamicComponent, useSuperAtom, validateDSL, validateUIComponent, validateUIElement, withConditionalErrorBoundary };
+export { type ActionsRequestMessage, ActionsRequestMessageSchema, type ActionsRequestPayload, ActionsRequestPayloadSchema, type ActionsResponseMessage, ActionsResponseMessageSchema, type ActionsResponsePayload, ActionsResponsePayloadSchema, type AnswerVerdict, type AssistantNavigation, AssistantNavigationProvider, type AssistantNavigationProviderProps, type AssistantView, type AttachTarget, type Binding, BindingSchema, BookmarkModal, type BookmarkModalProps, BookmarkPage, type BookmarkPageProps, type BundleChunkMessage, BundleChunkMessageSchema, type BundleChunkPayload, BundleChunkPayloadSchema, type BundleDashboard, type BundleDashboardEntry, type BundleErrorMessage, BundleErrorMessageSchema, type BundleErrorPayload, BundleErrorPayloadSchema, type BundleRequestMessage, BundleRequestMessageSchema, type BundleRequestPayload, BundleRequestPayloadSchema, COMP_REGISTRY, ChatInput, type ChatInputProps, type ChatMessage, ChatPage, type ChatPageProps, type ClientConfig, ClientConfigSchema, type Component, type ComponentDefinition, type ComponentRegistryType, ComponentSchema, type ComponentsRegistry, type ComponentsSendMessage, ComponentsSendMessageSchema, type ComponentsSendPayload, ComponentsSendPayloadSchema, ConfirmDeleteModal, type ConfirmDeleteModalProps, ConnectionOverlay, type ConnectionStatus, ConnectionStatusPill, DEFAULT_API_URL, DEFAULT_THEME_COLOR, DSLErrorBoundary, DSLRenderer, type DSLRendererProps, DSLRendererPropsSchema, DashboardConversation, type DashboardConversationProps, DashboardPage, type DashboardPageProps, type DataRequestMessage, DataRequestMessageSchema, type DataRequestPayload, DataRequestPayloadSchema, type DataResponseMessage, DataResponseMessageSchema, type DataResponsePayload, DataResponsePayloadSchema, type DisconnectReason, DynamicComponent, type Expression, ExpressionSchema, FeedbackModal, type FeedbackModalProps, FileDownloads, type FileDownloadsProps, type ForDirective, ForDirectiveSchema, HomePage, type HomePageProps, type MenuData, MenuDataSchema, type MenuQueryFilters, MenuQueryFiltersSchema, type MenuV1Item, MenuV1Renderer, MenuV1RendererCollapsed, type MenuV1Root, type MenusRequestMessage, MenusRequestMessageSchema, type MenusRequestPayload, MenusRequestPayloadSchema, type MenusResponseMessage, MenusResponseMessageSchema, type MenusResponsePayload, MenusResponsePayloadSchema, type Message, MessageBubble, type MessageBubbleProps, MessageList, type MessageListProps, type MessageParticipant, MessageParticipantSchema, MessageSchema, type MountFunction, NewChatHero, type NewChatHeroProps, type PendingAttachment, type QuerySpec, QuerySpecSchema, ReportPage, type ReportPageProps, type ResolvedClientConfig, SDK_VERSION, SUPPORTED_MIME, SdkSession, type SdkSessionOptions, type SdkUser, ShadowBoundary, type ShadowBoundaryProps, Sidebar, type SidebarProps, SuperAtomAuthError, type SuperAtomAuthErrorCode, type SuperAtomGlobal, SuperatomAssistant, type SuperatomAssistantProps, SuperatomClient, SuperatomProvider, type SuperatomProviderProps, SuperatomSurface, type SuperatomSurfaceProps, type ThreadConversationRow, ThreadRowsSkeleton, type ThreadSummary, type Toast, type ToastKind, Toaster, type ToasterProps, type UIComponent, UIComponentSchema, type UIElement, UIElementSchema, type UILogEntry, UILogEntrySchema, type UILogsMessage, UILogsMessageSchema, type UILogsPayload, UILogsPayloadSchema, type UseSuperAtomOptions, type UseSuperAtomReturn, type UseVoiceInputReturn, type UserPromptAbortRequestMessage, UserPromptAbortRequestMessageSchema, type UserPromptAbortRequestPayload, UserPromptAbortRequestPayloadSchema, type UserPromptNarration, UserPromptNarrationSchema, type UserPromptRequestMessage, UserPromptRequestMessageSchema, type UserPromptRequestPayload, UserPromptRequestPayloadSchema, type UserPromptResponseMessage, UserPromptResponseMessageSchema, type UserPromptResponsePayload, UserPromptResponsePayloadSchema, type UserPromptSuggestionsRequestMessage, UserPromptSuggestionsRequestMessageSchema, type UserPromptSuggestionsRequestPayload, UserPromptSuggestionsRequestPayloadSchema, type UserPromptSuggestionsResponseMessage, UserPromptSuggestionsResponseMessageSchema, type UserPromptSuggestionsResponsePayload, UserPromptSuggestionsResponsePayloadSchema, type VoiceState, type WorkflowDescriptor, addAttachments, clearAttachments, clearDashboardThread, clearToasts, consumeAttachments, dashboardForThread, dashboardOnScreen, dashboardThread, dismissToast, getComponent, getComponentStates, getComponents, groupBundleDashboards, hasComponents, isAttachmentsFull, notifyAttachmentsFull, openDashboard, openDashboardThread, readBundleDashboards, readHomeLabel, registerBundleComponents, removeAttachment, resetAllFailedComponents, resetFailedComponent, resetRegistration, resolveThreadDashboard, runMenuItem, sanitizeDSL, searchRootFor, index as services, setDashboardFilters, setup, showToast, toast, useAssistantNavigation, useAttachments, useBookmarkForMessage, useBookmarks, useBundleDashboards, useConfigError, useConnectionStatus, useDynamicComponent, useHasAssistantNavigation, useHasSuperatomProvider, useHomeLabel, useSuperAtom, useThemeColor, useToasts, useVoiceInput, useVoiceShortcut, validateDSL, validateUIComponent, validateUIElement, withConditionalErrorBoundary };