@teaflask/assistant 0.6.0 → 0.7.1

package/dist/components/teaflask-assistant.d.ts

@@ -1,11 +1,44 @@
 import { type AssistantCompanionProps } from "./assistant-companion.js";
 import { type TeaflaskAssistantProviderProps } from "./teaflask-assistant-provider.js";
+/**
+ * The imperative handle you get through a ref on `TeaflaskAssistant`. It exists
+ * only while the component is mounted.
+ */
 export interface TeaflaskAssistantHandle {
+    /**
+     * Opens the ⌘K palette even when the hotkey is disabled or rebound. The
+     * corner widget hides while the palette is open. Call it as
+     * `ref.current?.openPalette()`.
+     */
     openPalette: () => void;
 }
+/**
+ * The props `TeaflaskAssistant` adds on top of the provider's, for the palette
+ * hotkey and the widget's corner.
+ */
 export interface TeaflaskAssistantRootProps {
+    /**
+     * The keyboard shortcut that toggles the palette. It defaults to `"mod+k"`,
+     * where mod is ⌘ on macOS and Ctrl elsewhere, and takes the same syntax for
+     * other keys (`"mod+j"`, `"ctrl+shift+p"`). Pass `false` to disable it. An
+     * unrecognized value also disables it, with a console warning, and a key
+     * press your own handler calls `preventDefault()` on is ignored.
+     */
     hotkey?: string | false;
+    /**
+     * The screen corner where the widget and its drawer sit. The default is
+     * `"bottom-right"`.
+     */
     corner?: AssistantCompanionProps["corner"];
 }
+/**
+ * Props for `TeaflaskAssistant`, which are all the provider props plus `hotkey`
+ * and `corner`.
+ */
 export type TeaflaskAssistantProps = TeaflaskAssistantProviderProps & TeaflaskAssistantRootProps;
+/**
+ * The all-in-one assistant. It contains the provider plus the corner widget
+ * (which opens the chat drawer) and the ⌘K palette, so mount it once in the
+ * layout that wraps every page. Pass a ref to get a `TeaflaskAssistantHandle`.
+ */
 export declare const TeaflaskAssistant: import("react").ForwardRefExoticComponent<TeaflaskAssistantProps & import("react").RefAttributes<TeaflaskAssistantHandle>>;

package/dist/components/tool-views/action-view.js

@@ -6,7 +6,7 @@ const REQUEST_SECTIONS = [
     ["query", "Query"],
     ["body", "Body"],
 ];
-const VALUE_PANE_CLASS = "tf:m-0 tf:whitespace-pre-wrap tf:font-mono tf:text-xs tf:text-tf-foreground";
+const VALUE_PANE_CLASS = "tf:m-0 tf:whitespace-pre-wrap tf:font-mono tf:text-xs tf:text-tf-card-foreground";
 export const actionToolView = statelessToolView(_renderAction);
 function _renderAction({ call }) {
     const root = el("div", "tf:flex tf:flex-col tf:gap-2");

package/dist/components/tool-views/parts-classes.d.ts

@@ -1,17 +1,17 @@
-export declare const CARD_CLASS = "tf:overflow-hidden tf:rounded-lg tf:border tf:border-tf-border tf:bg-tf-card";
+export declare const CARD_CLASS = "tf:overflow-hidden tf:rounded-lg tf:border tf:border-tf-border tf:bg-tf-card tf:text-tf-card-foreground";
 export declare const CARD_TITLE_CLASS = "tf:mb-1 tf:text-tf-label tf:font-medium tf:text-tf-foreground";
 export declare const ROW_CLASS = "tf:flex tf:min-w-0 tf:items-center tf:gap-2.5 tf:border-t tf:border-tf-border tf:px-2.5 tf:py-1.5 tf:first:border-t-0";
-export declare const ROW_LINK_CLASS = "tf:no-underline tf:hover:bg-tf-accent";
+export declare const ROW_LINK_CLASS = "tf:group/row tf:text-inherit tf:no-underline tf:hover:bg-tf-accent";
 export declare const ROW_ICON_CLASS = "tf:flex tf:size-6 tf:shrink-0 tf:items-center tf:justify-center tf:rounded-[5px] tf:bg-tf-muted tf:text-tf-muted-foreground";
 export declare const ROW_TEXT_CLASS = "tf:flex tf:min-w-0 tf:flex-1 tf:flex-col tf:leading-[1.35]";
-export declare const ROW_TITLE_CLASS = "tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-foreground";
+export declare const ROW_TITLE_CLASS = "tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-card-foreground tf:group-hover/row:text-tf-accent-foreground";
 export declare const ROW_SECONDARY_CLASS = "tf:truncate tf:text-xs tf:text-tf-muted-foreground";
 export declare const ROW_TRAIL_CLASS = "tf:ms-auto tf:flex tf:shrink-0 tf:items-center tf:gap-2";
-export declare const BADGE_CLASS = "tf:inline-flex tf:shrink-0 tf:items-center tf:rounded-[3px] tf:border tf:border-tf-border tf:px-1.5 tf:py-px tf:text-[11px] tf:leading-4 tf:font-medium tf:text-tf-foreground";
+export declare const BADGE_CLASS = "tf:inline-flex tf:shrink-0 tf:items-center tf:rounded-[3px] tf:border tf:border-tf-border tf:px-1.5 tf:py-px tf:text-[11px] tf:leading-4 tf:font-medium tf:text-tf-card-foreground tf:group-hover/row:text-tf-accent-foreground";
 export declare const FACT_LIST_CLASS = "tf:m-0 tf:border-t tf:border-tf-border tf:first:border-t-0";
 export declare const FACT_ROW_CLASS = "tf:grid tf:grid-cols-[minmax(6rem,30%)_minmax(0,1fr)] tf:gap-x-3 tf:border-t tf:border-tf-border tf:px-2.5 tf:py-1.5 tf:first:border-t-0";
 export declare const FACT_LABEL_CLASS = "tf:min-w-0 tf:text-xs tf:text-tf-muted-foreground tf:wrap-anywhere";
-export declare const FACT_VALUE_CLASS = "tf:m-0 tf:min-w-0 tf:text-xs tf:text-tf-foreground tf:wrap-anywhere";
+export declare const FACT_VALUE_CLASS = "tf:m-0 tf:min-w-0 tf:text-xs tf:text-tf-card-foreground tf:wrap-anywhere";
 export declare const CAPTION_ROW_CLASS = "tf:flex tf:items-center tf:justify-between tf:gap-3 tf:border-t tf:border-tf-border tf:px-2.5 tf:py-1.5 tf:text-xs tf:text-tf-muted-foreground tf:first:border-t-0";
 export declare const CARD_BLOCK_CLASS = "tf:border-t tf:border-tf-border tf:px-2.5 tf:py-2 tf:first:border-t-0";
 export declare const BODY_REGION_CLASS = "tf:max-h-72 tf:overflow-auto tf:border-t tf:border-tf-border tf:px-2.5 tf:py-2 tf:first:border-t-0";

package/dist/components/tool-views/parts-classes.js

@@ -1,17 +1,17 @@
-export const CARD_CLASS = "tf:overflow-hidden tf:rounded-lg tf:border tf:border-tf-border tf:bg-tf-card";
+export const CARD_CLASS = "tf:overflow-hidden tf:rounded-lg tf:border tf:border-tf-border tf:bg-tf-card tf:text-tf-card-foreground";
 export const CARD_TITLE_CLASS = "tf:mb-1 tf:text-tf-label tf:font-medium tf:text-tf-foreground";
 export const ROW_CLASS = "tf:flex tf:min-w-0 tf:items-center tf:gap-2.5 tf:border-t tf:border-tf-border tf:px-2.5 tf:py-1.5 tf:first:border-t-0";
-export const ROW_LINK_CLASS = "tf:no-underline tf:hover:bg-tf-accent";
+export const ROW_LINK_CLASS = "tf:group/row tf:text-inherit tf:no-underline tf:hover:bg-tf-accent";
 export const ROW_ICON_CLASS = "tf:flex tf:size-6 tf:shrink-0 tf:items-center tf:justify-center tf:rounded-[5px] tf:bg-tf-muted tf:text-tf-muted-foreground";
 export const ROW_TEXT_CLASS = "tf:flex tf:min-w-0 tf:flex-1 tf:flex-col tf:leading-[1.35]";
-export const ROW_TITLE_CLASS = "tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-foreground";
+export const ROW_TITLE_CLASS = "tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-card-foreground tf:group-hover/row:text-tf-accent-foreground";
 export const ROW_SECONDARY_CLASS = "tf:truncate tf:text-xs tf:text-tf-muted-foreground";
 export const ROW_TRAIL_CLASS = "tf:ms-auto tf:flex tf:shrink-0 tf:items-center tf:gap-2";
-export const BADGE_CLASS = "tf:inline-flex tf:shrink-0 tf:items-center tf:rounded-[3px] tf:border tf:border-tf-border tf:px-1.5 tf:py-px tf:text-[11px] tf:leading-4 tf:font-medium tf:text-tf-foreground";
+export const BADGE_CLASS = "tf:inline-flex tf:shrink-0 tf:items-center tf:rounded-[3px] tf:border tf:border-tf-border tf:px-1.5 tf:py-px tf:text-[11px] tf:leading-4 tf:font-medium tf:text-tf-card-foreground tf:group-hover/row:text-tf-accent-foreground";
 export const FACT_LIST_CLASS = "tf:m-0 tf:border-t tf:border-tf-border tf:first:border-t-0";
 export const FACT_ROW_CLASS = "tf:grid tf:grid-cols-[minmax(6rem,30%)_minmax(0,1fr)] tf:gap-x-3 tf:border-t tf:border-tf-border tf:px-2.5 tf:py-1.5 tf:first:border-t-0";
 export const FACT_LABEL_CLASS = "tf:min-w-0 tf:text-xs tf:text-tf-muted-foreground tf:wrap-anywhere";
-export const FACT_VALUE_CLASS = "tf:m-0 tf:min-w-0 tf:text-xs tf:text-tf-foreground tf:wrap-anywhere";
+export const FACT_VALUE_CLASS = "tf:m-0 tf:min-w-0 tf:text-xs tf:text-tf-card-foreground tf:wrap-anywhere";
 export const CAPTION_ROW_CLASS = "tf:flex tf:items-center tf:justify-between tf:gap-3 tf:border-t tf:border-tf-border tf:px-2.5 tf:py-1.5 tf:text-xs tf:text-tf-muted-foreground tf:first:border-t-0";
 export const CARD_BLOCK_CLASS = "tf:border-t tf:border-tf-border tf:px-2.5 tf:py-2 tf:first:border-t-0";
 export const BODY_REGION_CLASS = `tf:max-h-72 tf:overflow-auto ${CARD_BLOCK_CLASS}`;

package/dist/components/tool-views/parts.d.ts

@@ -1,11 +1,25 @@
 import type { ReactNode } from "react";
+/**
+ * The small label shown above a card. Use it on its own above ToolViewBones,
+ * which draw no card.
+ */
 export declare function ToolViewTitle({ children }: {
     children: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * A bordered card holding rows, facts, captions or a body, with an optional
+ * small `title` above it; the base container for a tool view built from these
+ * parts, so it matches the assistant's built-in views.
+ */
 export declare function ToolViewCard({ title, children, ...rest }: {
     title?: string;
     children: ReactNode;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * A list row with an optional icon tile, a title, a muted second line and
+ * trailing content such as a ToolViewBadge. With `href` the row is a plain link
+ * that navigates the whole page, since a view can't reach your app's router.
+ */
 export declare function ToolViewRow({ icon, title, secondary, trailing, href, ...rest }: {
     icon?: ReactNode;
     title: ReactNode;
@@ -13,29 +27,59 @@ export declare function ToolViewRow({ icon, title, secondary, trailing, href, ..
     trailing?: ReactNode;
     href?: string;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * Label and value rows, in the order given, for showing a record's properties.
+ */
 export declare function ToolViewFacts({ facts, ...rest }: {
     facts: readonly {
         label: string;
         value: ReactNode;
     }[];
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * A quiet, muted line inside a card, such as a count or a response status, with
+ * optional `trailing` content on the right.
+ */
 export declare function ToolViewCaption({ children, trailing, ...rest }: {
     children: ReactNode;
     trailing?: ReactNode;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * A labelled scrolling region inside a card, up to 18rem tall, for a document,
+ * a diff or other long content; `label` is its accessible name. Extra `data-*`
+ * attributes pass through to the element.
+ */
 export declare function ToolViewBody({ label, children, ...rest }: {
     label: string;
     children: ReactNode;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * A scrolling area inside a card, up to 18rem tall, for a long list of rows.
+ * Extra `data-*` attributes pass through to the element.
+ */
 export declare function ToolViewScroll({ children, ...rest }: {
     children: ReactNode;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * A small outlined label, usually trailing a ToolViewRow, for a short state
+ * such as "Awaiting approval" or "Not created". Extra `data-*` attributes pass
+ * through to the element.
+ */
 export declare function ToolViewBadge({ children, ...rest }: {
     children: ReactNode;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * One muted sentence, for something absent, degraded or not shown, such as the
+ * text from settledOutcomeNoteOf.
+ */
 export declare function ToolViewNote({ children, ...rest }: {
     children: ReactNode;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;
+/**
+ * Pulsing skeleton lines that hold the place where a result will appear while
+ * the call runs, with no card or border; `lines` defaults to 3. Hidden from
+ * screen readers.
+ */
 export declare function ToolViewBones({ lines, ...rest }: {
     lines?: number;
 } & Record<`data-${string}`, string | number | undefined>): import("react").JSX.Element;

package/dist/components/tool-views/questions-view.js

@@ -27,12 +27,12 @@ function renderQuestions({ call }) {
 function questionSection(question, answer) {
     const section = el("div", "tf:min-w-0 tf:border-t tf:border-tf-border tf:p-4 tf:first:border-t-0");
     const title = el("dt", "");
-    title.append(el("span", "tf:wrap-anywhere tf:text-tf-label tf:font-medium tf:text-tf-foreground", question.heading));
+    title.append(el("span", "tf:wrap-anywhere tf:text-tf-label tf:font-medium tf:text-tf-card-foreground", question.heading));
     const prompt = el("dd", "tf:m-0 tf:mt-1.5 tf:wrap-anywhere tf:whitespace-pre-wrap tf:text-tf-label tf:leading-relaxed tf:text-tf-muted-foreground", question.prompt);
     prompt.dataset.tfElicitationReceiptQuestion = "";
     section.append(title, prompt);
     if (answer !== undefined) {
-        const value = el("dd", "tf:m-0 tf:mt-3 tf:rounded-md tf:bg-tf-muted tf:px-3 tf:py-2.5 tf:wrap-anywhere tf:whitespace-pre-wrap tf:text-tf-label tf:leading-relaxed tf:text-tf-foreground");
+        const value = el("dd", "tf:m-0 tf:mt-3 tf:rounded-md tf:bg-tf-muted tf:px-3 tf:py-2.5 tf:wrap-anywhere tf:whitespace-pre-wrap tf:text-tf-label tf:leading-relaxed tf:text-tf-card-foreground");
         value.dataset.tfElicitationReceiptAnswer = "";
         value.append(el("span", "tf:sr-only", "Answered: "), document.createTextNode(answer));
         section.append(value);

package/dist/components/tool-views/view-dom.d.ts

@@ -2,14 +2,32 @@ import type { ToolViewAdapter, ToolViewCall, ToolViewProps } from "../../core/to
 import { LABEL_CLASS, PANE_CLASS, PANE_WRAPPER_CLASS } from "./parts-classes.js";
 export { LABEL_CLASS, PANE_CLASS, PANE_WRAPPER_CLASS };
 export declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, className: string, text?: string): HTMLElementTagNameMap[K];
+/**
+ * A labelled block of monospace text on a muted background, for raw text such
+ * as output or a diff.
+ */
 export declare function pane(label: string, text: string): HTMLElement;
+/**
+ * A terminal-style block showing `$ command`, then its output, then stderr in a
+ * quieter tone. Pass `command: null` to show output only; empty parts are left
+ * out.
+ */
 export declare function terminal(options: {
     command: string | null;
     output?: string;
     stderr?: string;
 }): HTMLElement;
+/** The plain-DOM version of ToolViewScroll, holding the given elements. */
 export declare function scrollRegion(children: readonly HTMLElement[]): HTMLElement;
+/**
+ * The plain-DOM version of ToolViewCard, holding the given elements under an
+ * optional title.
+ */
 export declare function card(children: readonly HTMLElement[], title?: string): HTMLElement;
+/**
+ * The plain-DOM version of ToolViewRow, without a link; `below` adds an element
+ * under the title and second line.
+ */
 export declare function listRow(options: {
     title: string;
     secondary?: string;
@@ -17,25 +35,73 @@ export declare function listRow(options: {
     icon?: Element;
     below?: HTMLElement;
 }): HTMLElement;
+/**
+ * The plain-DOM version of ToolViewFacts, from `[label, value]` pairs in order.
+ */
 export declare function factRows(facts: readonly (readonly [label: string, value: string | HTMLElement])[]): HTMLElement;
+/**
+ * The plain-DOM version of ToolViewCaption, with optional trailing content on
+ * the right.
+ */
 export declare function captionRow(text: string, trailing?: HTMLElement | string): HTMLElement;
 export declare function badge(text: string): HTMLElement;
+/** The plain-DOM version of ToolViewBones, with `count` skeleton lines. */
 export declare function boneRows(count: number): HTMLElement;
+/** The plain-DOM version of ToolViewNote. */
 export declare function note(text: string): HTMLElement;
+/**
+ * Returns the value if it is a plain object (not null and not an array), else
+ * null. Handy for reading `call.args` or `call.result` safely.
+ */
 export declare function recordOf(value: unknown): Record<string, unknown> | null;
 export declare function stringOf(value: unknown): string | null;
 export declare function statelessToolView(render: (props: ToolViewProps) => HTMLElement): ToolViewAdapter;
+/**
+ * True when the call finished successfully and its own result is available
+ * (status "output-available" and not offloaded). Check it before drawing a
+ * result.
+ */
 export declare function settledWithResult(call: ToolViewCall): boolean;
+/**
+ * The same as settledOutcomeNoteOf, as a list of zero or one note elements
+ * ready to append in a plain-DOM view.
+ */
 export declare function settledOutcomeNotesOf(call: ToolViewCall): HTMLElement[];
+/**
+ * A short sentence for a call that ended without a usable result (failed,
+ * declined, not approved, didn't run, interrupted, or result replaced by a
+ * preview). Null while the call is running or when it finished normally.
+ */
 export declare function settledOutcomeNoteOf(call: ToolViewCall): string | null;
+/** An action's recorded HTTP response, as read by actionEnvelopeOf. */
 export interface ActionEnvelope {
+    /** The HTTP status code your API returned, or null if none was recorded. */
     status: number | null;
+    /** Your API's response body as recorded. */
     body: unknown;
+    /**
+     * True when the body was cut to fit a size limit, so it is not complete.
+     */
     truncated: boolean;
 }
+/**
+ * Reads an action call's `resultText` into your API's HTTP status, response
+ * body and whether the body was cut short. Returns null when the text is not an
+ * action's successful result.
+ */
 export declare function actionEnvelopeOf(resultText: string | undefined): ActionEnvelope | null;
+/** A failed action's reason, as read by actionFailureOf. */
 export interface ActionFailure {
+    /**
+     * The failure sentence as recorded, including wording meant for the agent.
+     * Use humanFailureSentenceOf to show it to a user.
+     */
     message: string;
+    /**
+     * The HTTP status, your API's error code and its per-field problems (`path`
+     * and `message`, in the API's order) when the failure named them, else
+     * null. `fieldsOmitted` counts further problems left out of `fields`.
+     */
     detail: {
         status: number;
         code: string;
@@ -46,6 +112,16 @@ export interface ActionFailure {
         fieldsOmitted?: number;
     } | null;
 }
+/**
+ * Reads a failed action call's `errorText` into its message plus, when the
+ * failure named them, the HTTP status, error code and per-field problems.
+ * Returns null when there is no error text or it is not a failure.
+ */
 export declare function actionFailureOf(errorText: string | undefined): ActionFailure | null;
+/**
+ * Turns a call's `errorText` into a sentence fit to show the user, removing the
+ * HTTP status and code, the field problems and the instructions meant for the
+ * agent. Text that is not an action failure comes back unchanged.
+ */
 export declare function humanFailureSentenceOf(errorText: string): string;
 export declare function fileGlyph(): SVGElement;

package/dist/components/transcript.js

@@ -23,9 +23,9 @@ export function Transcript({ surface }) {
     const { pendingSend } = useConversation();
     const connection = useCell(store.connection);
     const { approvalCards, approvalSurface, elicitationSurface } = useDecisionSurfaces(store);
-    const { rows, displayRows, running, turnOpen, decisionsPending, activity } = useTranscript({ surface });
+    const { displayRows, running, turnOpen, decisionsPending, activity } = useTranscript({ surface });
     const rowIndexByToolCallId = useMemo(() => _rowIndexByToolCallIdOf(displayRows), [displayRows]);
-    const dispatches = useThreadDispatches(session, connection?.threadId ?? null, rows, store.noteDispatchSettled, store.noteDispatchPaused);
+    const dispatches = useThreadDispatches(session, connection?.threadId ?? null);
     const dispatchesJoin = useMemo(() => ({ byOrdinal: dispatches }), [dispatches]);
     const coworkerWork = useCell(store.coworkerWork);
     if (connection === null) {

package/dist/components/use-assistant-activity.d.ts

@@ -1,2 +1,7 @@
 import type { AssistantActivitySnapshot } from "../core/activity.js";
+/**
+ * Returns a live summary of the assistant's state for badges or presence
+ * indicators elsewhere in your UI, updating as the conversation changes on any
+ * surface. Call it inside the provider or `TeaflaskAssistant`.
+ */
 export declare function useAssistantActivity(): AssistantActivitySnapshot;

package/dist/components/use-assistant-conversation.d.ts

@@ -1,23 +1,120 @@
 import type { ServingAssistantThread } from "../contract/threads.js";
-import type { ActiveConversation, ComposerContract } from "../core/conversation-store.js";
+import type { ComposerContract } from "../core/conversation-store.js";
 import type { PendingDecisionGap } from "../core/pending-decision-gap.js";
 import type { ServingApiError } from "../transport/serving-error.js";
+/** The conversation on screen. */
+export interface OpenConversation {
+    /**
+     * The conversation's server record, including its id, title, whether a
+     * reply is running, timestamps and saved model choice.
+     */
+    thread: ServingAssistantThread;
+}
+/**
+ * The open conversation, the visitor's history, the notices worth showing, and
+ * the actions that move between conversations, as returned by
+ * useAssistantConversation().
+ */
 export interface AssistantConversation {
+    /**
+     * Set when the assistant cannot start because of a configuration problem
+     * (code PUBLISHABLE_KEY_INVALID, ORIGIN_NOT_ALLOWED, END_USER_TOKEN_INVALID
+     * or END_USER_ID_MISMATCH); show it instead of the conversation. Null
+     * otherwise, and cleared once a session starts successfully.
+     */
     setupError: ServingApiError | null;
-    conversation: ActiveConversation | null;
+    /**
+     * The conversation on screen, or null when none is open (a fresh
+     * conversation has no record until its first message is sent).
+     */
+    conversation: OpenConversation | null;
+    /**
+     * The visitor's past conversations (up to 200), for a history list. Only
+     * loaded for an identified visitor; empty for anonymous visitors.
+     */
     threads: ServingAssistantThread[];
+    /**
+     * True when the visitor is identified (you passed a userId, or their
+     * session is signed in), so a history list makes sense; false for an
+     * anonymous visitor.
+     */
     historyExpected: boolean;
+    /**
+     * True while a conversation is loading (a stored conversation at startup,
+     * or one picked with openThread); show a loading state rather than the
+     * empty state.
+     */
     threadOpening: boolean;
+    /**
+     * Increases each time the live connection restarts (after each send, a
+     * retry, or an automatic reconnect). Use it with the conversation id as a
+     * React key if you want your transcript subtree to remount on reconnect.
+     */
     reconnectNonce: number;
+    /**
+     * The composer's state and controls for this conversation, the same value
+     * useConversation() returns.
+     */
     composerContract: ComposerContract;
+    /**
+     * A sentence to show the visitor when sending a message, opening a
+     * conversation or stopping a reply failed. Null otherwise; cleared by the
+     * next send, open or new conversation.
+     */
     sendError: string | null;
+    /**
+     * A sentence to show when the newest reply failed. Null when it didn't, and
+     * also once the transcript itself shows that failure as a receipt row, so
+     * you never show it twice.
+     */
     turnFailure: string | null;
+    /**
+     * True when the connection dropped while a reply was in progress; show a
+     * notice with a Retry button that calls retryStream. Never true while the
+     * visitor is stopping a reply.
+     */
     showInterruptionBanner: boolean;
+    /**
+     * Set when the agent is waiting on an approval or question that this page
+     * could not display (after a short grace period). Show a notice with a
+     * Retry button that calls refreshConversation; null otherwise.
+     */
     pendingDecisionGap: PendingDecisionGap | null;
+    /**
+     * Reconnects to the conversation and replays it from the start, clearing
+     * the interruption notice. Use it as the interruption notice's Retry.
+     */
     retryStream: () => void;
+    /**
+     * Re-reads the open conversation from the server and applies what it finds.
+     * Does nothing when no conversation is open; network failures are ignored.
+     */
     refreshConversation: () => Promise<void>;
+    /**
+     * Opens one of the visitor's past conversations (from threads) and makes it
+     * the one resumed next time. While it loads, threadOpening is true; if it
+     * can't be opened, sendError is set, and a conversation that no longer
+     * exists is removed from threads.
+     */
     openThread: (thread: ServingAssistantThread) => void;
+    /**
+     * Leaves the current conversation and shows an empty one. Clears the unsent
+     * draft, staged attachments, unsent question answers and model choice; the
+     * new conversation is created when the first message is sent.
+     */
     startNewConversation: () => void;
+    /**
+     * Re-opens the conversation this browser last used, as saved for this
+     * publishable key; if none is saved, an open conversation is closed. The
+     * provider calls it once at startup; call it again when your UI reopens if
+     * another surface may have switched conversations meanwhile.
+     */
     resumeStoredThread: () => void;
 }
+/**
+ * Returns the live state and controls of the assistant conversation, for
+ * building your own UI. Must be called inside <TeaflaskAssistantProvider> (it
+ * throws otherwise); every component that calls it reads the same conversation
+ * as the widget, drawer, palette and full-page assistant.
+ */
 export declare function useAssistantConversation(): AssistantConversation;

package/dist/components/use-store-cell.d.ts

@@ -1,2 +1,7 @@
 import type { ReadonlyCell } from "../core/observable-cell.js";
+/**
+ * Subscribes a React component to an observable value such as composerInput and
+ * returns its current value, re-rendering when it changes. Server rendering
+ * gets the initial value.
+ */
 export declare function useCell<T>(cell: ReadonlyCell<T>): T;