@teaflask/assistant 0.6.0 → 0.7.1

package/dist/appearance/theme.d.ts

@@ -1,29 +1,167 @@
+/**
+ * Which palette the assistant uses. `"light"` and `"dark"` force that palette,
+ * and `"auto"` follows the visitor's operating-system setting.
+ */
 export type AssistantThemeMode = "light" | "dark" | "auto";
+/**
+ * The themable tokens. Each one sets a `--tf-` CSS variable, and you can set
+ * those variables in your own CSS on any ancestor instead of passing them here.
+ * Values are CSS strings (any CSS color for the color tokens), and a token you
+ * omit keeps the default monochrome look.
+ */
 export interface AssistantThemeTokens {
+    /**
+     * Sets `--tf-background`, the base surface color behind the conversation,
+     * the composer and floating controls. Defaults to `#ffffff` in light mode
+     * and `#000000` in dark mode.
+     */
     background?: string;
+    /**
+     * Sets `--tf-foreground`, the main text and icon color. Defaults to
+     * `#171717` in light mode and `#ededed` in dark mode.
+     */
     foreground?: string;
+    /**
+     * Sets `--tf-card`, the fill of approval cards and tool views in the
+     * conversation. Defaults to `#ffffff` in light mode and `#000000` in dark
+     * mode; it does not follow `background`, so set both to change cards too.
+     */
     card?: string;
+    /**
+     * Sets `--tf-card-foreground`, the text color inside approval cards and
+     * tool views: an approval's heading, and the row titles, badges and values
+     * of a tool view, including the request details an approval can show. An
+     * approval's request sentence and the other lines inside these cards use
+     * `mutedForeground`. Defaults to the same value as `foreground`.
+     */
     cardForeground?: string;
+    /**
+     * Sets `--tf-popover`, the fill of the floating menus: the conversation
+     * history menu, the panel-position menu, the model picker, the ChatGPT plan
+     * menu, the command palette and the sub-agent preview. These surfaces are
+     * translucent, so the color is applied as a tint over what sits behind
+     * them; give it the same light or dark polarity as `background`. The
+     * floating panel, the mobile sheet and the sub-agent chip keep
+     * `background`. Defaults to the same value as `background`.
+     */
     popover?: string;
+    /**
+     * Sets `--tf-popover-foreground`, the text color the `popover` surfaces
+     * inherit: a menu's heading, the ChatGPT plan menu's connected standing,
+     * the command palette's heading and the sub-agent preview's text. Menu rows
+     * use `mutedForeground` at rest and `accentForeground` when hovered, the
+     * New conversation row at the top of the history menu keeps `foreground`,
+     * and the conversation shown inside the command palette keeps its own
+     * colors. Defaults to the same value as `foreground`.
+     */
     popoverForeground?: string;
+    /**
+     * Sets `--tf-primary`, the fill of solid buttons such as Send and Stop.
+     * Defaults to `#171717` in light mode and `#ededed` in dark mode.
+     */
     primary?: string;
+    /**
+     * Sets `--tf-primary-foreground`, the text and icon color on `primary`
+     * buttons.
+     */
     primaryForeground?: string;
+    /**
+     * Sets `--tf-secondary`, the fill of the secondary buttons: Deny, Back and
+     * the Approve-for-this-task or Approve-for-this-conversation option on an
+     * approval card, Cancel and Keep editing under a question, and Cancel while
+     * a ChatGPT sign-in is in progress. Hovered, the fill shifts slightly
+     * toward its own text color under a light `accent` wash, so a themed fill
+     * stays visible. Defaults to transparent, so these buttons stay quiet until
+     * you set it.
+     */
     secondary?: string;
+    /**
+     * Sets `--tf-secondary-foreground`, the text color on `secondary` buttons,
+     * at rest and hovered. Defaults to the same value as `foreground`.
+     */
     secondaryForeground?: string;
+    /**
+     * Sets `--tf-muted`, the subtle fill behind the user's own messages, code
+     * blocks and the disabled Send button. Defaults to `#f2f2f2` in light mode
+     * and `#1a1a1a` in dark mode.
+     */
     muted?: string;
+    /**
+     * Sets `--tf-muted-foreground`, the color of secondary text, captions and
+     * quiet icons.
+     */
     mutedForeground?: string;
+    /**
+     * Sets `--tf-accent`, the hover fill of quiet buttons, menu rows and list
+     * rows. Defaults to a 5% black tint in light mode and a 7% white tint in
+     * dark mode.
+     */
     accent?: string;
+    /**
+     * Sets `--tf-accent-foreground`, the text color over the `accent` fill:
+     * hovered menu rows, list rows, answer rows and quiet buttons, the selected
+     * conversation in the history menu, and the title and badge of a hovered
+     * link row in a tool view. Defaults to the same value as `foreground`.
+     */
     accentForeground?: string;
+    /**
+     * Sets `--tf-destructive`, the color of error text, failure icons and
+     * destructive controls.
+     */
     destructive?: string;
+    /**
+     * Sets `--tf-border`, the color of every border and divider inside the
+     * assistant.
+     */
     border?: string;
+    /**
+     * Sets `--tf-input`, the border color of the message box and of keyboard
+     * shortcut hints.
+     */
     input?: string;
+    /**
+     * Sets `--tf-ring`, the focus outline shown when a control is focused from
+     * the keyboard. Defaults to `#0070f7` in light mode and `#50a8ff` in dark
+     * mode.
+     */
     ring?: string;
+    /**
+     * Sets `--tf-radius`, the corner radius for buttons, inputs and panels,
+     * with some elements derived from it. A bare number means pixels, and the
+     * default is `0.5rem`.
+     */
     radius?: string | number;
+    /**
+     * Sets `--tf-font-sans`, the font-family stack for all assistant text.
+     * Defaults to the system UI font.
+     */
     fontSans?: string;
+    /**
+     * Sets `--tf-color-scheme`, the CSS `color-scheme` that native controls
+     * such as scrollbars and the message box draw with (`"light"` or `"dark"`).
+     * By default it follows the active mode. Set it when you build a dark theme
+     * from tokens alone, and note that a value you set applies in both modes.
+     */
     colorScheme?: string;
 }
+/**
+ * The tokens you can override for dark mode: every color token, but not
+ * `radius`, `fontSans` or `colorScheme`, which stay the same in both modes.
+ */
 export type AssistantThemeDarkTokens = Omit<AssistantThemeTokens, "radius" | "fontSans" | "colorScheme">;
+/**
+ * Colors, corner radius and font for every assistant surface, passed as the
+ * `theme` prop; each token sets one `--tf-` CSS variable inline on the
+ * assistant's root elements, so it overrides the same variable set in your own
+ * CSS.
+ */
 export interface AssistantTheme extends AssistantThemeTokens {
+    /**
+     * Color overrides used only while dark mode is active (`mode="dark"`,
+     * `mode="auto"` on a dark OS, or `data-tf-theme="dark"` on an ancestor). A
+     * color you leave out here falls back to the base token if you set one,
+     * otherwise to the built-in dark default.
+     */
     dark?: AssistantThemeDarkTokens;
 }
 export declare const THEME_TOKEN_KEYS: readonly (keyof AssistantThemeTokens)[];

package/dist/components/approval-card.js

@@ -49,7 +49,7 @@ export function ApprovalCard({ card }) {
         setSubmittedForStatus(card.status);
         void submitDecision(card, decision);
     };
-    return (_jsxs("div", { "data-tf-approval-card": "", className: "tf:my-2 tf:rounded-2xl tf:border tf:border-tf-border tf:bg-tf-card tf:p-4", role: "group", "aria-label": "Approval request", children: [_jsx(CardHeader, { card: card }), _jsx("p", { "data-tf-approval-prompt": "", className: "tf:mt-3 tf:m-0 tf:text-tf-label tf:leading-relaxed tf:text-tf-muted-foreground", children: card.prompt.trim() === ""
+    return (_jsxs("div", { "data-tf-approval-card": "", className: "tf:my-2 tf:rounded-2xl tf:border tf:border-tf-border tf:bg-tf-card tf:p-4 tf:text-tf-card-foreground", role: "group", "aria-label": "Approval request", children: [_jsx(CardHeader, { card: card }), _jsx("p", { "data-tf-approval-prompt": "", className: "tf:mt-3 tf:m-0 tf:text-tf-label tf:leading-relaxed tf:text-tf-muted-foreground", children: card.prompt.trim() === ""
                     ? "This tool needs your approval before it can run."
                     : card.prompt }), _jsx("div", { "data-tf-approval-footer": "", children: _jsx(CardFooter, { card: card, denying: denying, submitted: submitted, feedback: feedback, onFeedbackChange: setFeedback, onApprove: () => {
                         submitOnce({ approved: true });
@@ -86,10 +86,10 @@ function DenialForm({ asker, feedback, submitted, onFeedbackChange, onSend, onBa
                     ? "Tell the coworker why (optional)"
                     : "Tell the assistant why (optional)", "aria-label": "Reason for denying", onChange: (event) => {
                     onFeedbackChange(event.target.value);
-                } }), _jsxs("div", { className: "tf:flex tf:gap-2", children: [_jsx(TfButton, { disabled: submitted, onClick: onSend, children: "Send denial" }), _jsx(TfButton, { variant: "ghost", disabled: submitted, onClick: onBack, children: "Back" })] })] }));
+                } }), _jsxs("div", { className: "tf:flex tf:gap-2", children: [_jsx(TfButton, { disabled: submitted, onClick: onSend, children: "Send denial" }), _jsx(TfButton, { variant: "secondary", disabled: submitted, onClick: onBack, children: "Back" })] })] }));
 }
 function DecisionButtons({ card, submitted, onApprove, onApproveAndTrust, onStartDenying, }) {
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "tf:flex tf:flex-wrap tf:gap-2", children: [_jsx(TfButton, { disabled: submitted, onClick: onApprove, children: "Approve" }), _cardOffersTrust(card) ? (_jsx(TfButton, { variant: "ghost", disabled: submitted, onClick: onApproveAndTrust, children: _trustLabelOf(card.asker) })) : null, _jsx(TfButton, { variant: "ghost", disabled: submitted, onClick: onStartDenying, children: "Deny" })] }), card.gated ? (_jsx("p", { className: "tf:m-0 tf:text-xs tf:text-tf-muted-foreground", children: GATED_NOTE })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "tf:flex tf:flex-wrap tf:gap-2", children: [_jsx(TfButton, { disabled: submitted, onClick: onApprove, children: "Approve" }), _cardOffersTrust(card) ? (_jsx(TfButton, { variant: "secondary", disabled: submitted, onClick: onApproveAndTrust, children: _trustLabelOf(card.asker) })) : null, _jsx(TfButton, { variant: "secondary", disabled: submitted, onClick: onStartDenying, children: "Deny" })] }), card.gated ? (_jsx("p", { className: "tf:m-0 tf:text-xs tf:text-tf-muted-foreground", children: GATED_NOTE })) : null] }));
 }
 function _cardOffersTrust(card) {
     return !card.gated && card.trustAvailable;

package/dist/components/approval-context.d.ts

@@ -1,8 +1,28 @@
 import type { ApprovalCardModel, ApprovalDecisionInput } from "../core/approval-inbox.js";
+/**
+ * The approval requests to show and the function that answers them, as returned
+ * by useApprovals().
+ */
 export interface ApprovalSurface {
+    /**
+     * Approval requests in the open conversation, from the assistant and its
+     * sub-agents. Requests already answered or no longer answerable can stay in
+     * the list for a while, so render by each card's status.
+     */
     cards: readonly ApprovalCardModel[];
+    /**
+     * Sends the visitor's decision on one request; the card shows submitting,
+     * then answered. It does not reject on a server error: the card returns to
+     * actionable with an error sentence instead, and repeat submits while one
+     * is in flight are ignored.
+     */
     submitDecision: (card: ApprovalCardModel, decision: ApprovalDecisionInput) => Promise<void>;
 }
 export declare const ApprovalsContext: import("react").Context<ApprovalSurface>;
+/**
+ * Returns the approval requests in the open conversation and the function that
+ * answers them. Live inside <TeaflaskAssistantProvider>; outside it the list is
+ * empty and submitting rejects with an error.
+ */
 export declare function useApprovals(): ApprovalSurface;
 export declare function anchoredCardsFor(cards: readonly ApprovalCardModel[], toolCallId: string): ApprovalCardModel[];

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

@@ -1,5 +1,20 @@
+/** Props for `AssistantCompanion`. */
 export interface AssistantCompanionProps {
+    /**
+     * The screen corner where the widget and its drawer sit. The default is
+     * `"bottom-right"`.
+     */
     corner?: "bottom-right" | "bottom-left";
+    /**
+     * The accessible name of the button that opens the drawer, which defaults
+     * to `"Open assistant"`.
+     */
     "aria-label"?: string;
 }
+/**
+ * The corner widget: your mark in a corner of the screen, which opens the chat
+ * drawer when clicked. On wide screens the user can switch the drawer between a
+ * floating card and a docked sidebar. It hides while a full-page assistant or
+ * the palette is open, and `TeaflaskAssistant` already includes one.
+ */
 export declare function AssistantCompanion(props: AssistantCompanionProps): import("react").JSX.Element;

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

@@ -1,23 +1,84 @@
 import { type ReactNode } from "react";
 import { type AssistantSuggestionInput } from "./conversation-view.js";
+/**
+ * The state and controls `renderChrome` receives, for drawing the full-page
+ * assistant's header controls in your own UI. The history menu itself is still
+ * rendered by the assistant.
+ */
 export interface AssistantChrome {
+    /** The surface title from the `title` prop, `"Assistant"` by default. */
     title: string;
+    /**
+     * The open conversation's title, or the surface title when the conversation
+     * has none yet.
+     */
     conversationTitle: string;
+    /**
+     * True when the user has a conversation history to open, meaning a
+     * signed-in user. False for anonymous visitors, so hide your history
+     * button.
+     */
     historyAvailable: boolean;
+    /** Whether the history menu is currently open. */
     historyOpen: boolean;
+    /**
+     * The element id of the history menu, for `aria-controls` on your history
+     * button.
+     */
     historyMenuId: string;
+    /**
+     * Put this id on your history button. Clicking it then doesn't count as
+     * clicking outside the menu, and Escape returns focus to it.
+     */
     historyTriggerId: string;
+    /** Opens the history menu. */
     openHistory: () => void;
+    /** Opens the history menu if it is closed and closes it if it is open. */
     toggleHistory: () => void;
+    /** Closes the history menu and starts a new, empty conversation. */
     newConversation: () => void;
 }
+/** Props for `AssistantPage`. */
 export interface AssistantPageProps {
+    /**
+     * Removes the page's own border and rounded corners so it sits flush inside
+     * a frame you already draw. The default is false, which keeps the page as a
+     * self-contained card.
+     */
     frameless?: boolean;
+    /**
+     * Opening prompts shown under the message box before the first message;
+     * clicking one sends it as the user's message. The full-page assistant
+     * shows none unless you pass them.
+     */
     suggestions?: readonly AssistantSuggestionInput[];
+    /**
+     * A message sent for the user as soon as the page opens on an empty
+     * conversation, for deep links or first-run flows. It is sent at most once
+     * per mount, never into an existing conversation and never while sign-in is
+     * required. Changing it later has no effect.
+     */
     initialPrompt?: string;
+    /**
+     * The heading above the empty message box, which defaults to `"Where should
+     * we begin?"`.
+     */
     welcomeTitle?: string;
+    /** Your own logo or artwork, shown beside the empty-state heading. */
     welcomeMark?: ReactNode;
+    /** The name shown in the page's header, which defaults to `"Assistant"`. */
     title?: string;
+    /**
+     * Replaces the page's built-in header with your own controls, built from
+     * the `AssistantChrome` it receives. Return a portal to put them in a bar
+     * you already have, in which case nothing renders in the header's place.
+     */
     renderChrome?: (chrome: AssistantChrome) => ReactNode;
 }
+/**
+ * The full-page assistant: the conversation with a header, a history menu and a
+ * new-conversation button, filling the box you give it. Render it inside the
+ * provider or `TeaflaskAssistant`. It shares the same conversation as the other
+ * surfaces, and the corner widget hides while it is mounted.
+ */
 export declare function AssistantPage(props: AssistantPageProps): import("react").JSX.Element;

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

@@ -1,5 +1,17 @@
+/** Props for `AssistantPalette`, which is controlled by its parent. */
 export interface AssistantPaletteProps {
+    /** Whether the palette is shown. */
     open: boolean;
+    /**
+     * Called with the new open state when the palette asks to open or close,
+     * for example on Escape or a backdrop click.
+     */
     onOpenChange: (open: boolean) => void;
 }
+/**
+ * The ⌘K palette: a centered dialog over your page showing the current
+ * conversation, with a way to start a new one. You control whether it is open,
+ * and Escape or a backdrop click closes it. `TeaflaskAssistant` already
+ * includes one, so render this yourself only alongside the provider.
+ */
 export declare function AssistantPalette(props: AssistantPaletteProps): import("react").JSX.Element;

package/dist/components/assistant-palette.js

@@ -13,8 +13,8 @@ export function AssistantPalette(props) {
 function AssistantPaletteInner({ open, onOpenChange }) {
     const { rootProps } = useAssistantAppearance();
     useRegisterAssistantSurface("transient", open);
-    return (_jsx(TfDialog, { open: open, onOpenChange: onOpenChange, "aria-label": "Assistant", "data-tf-assistant": "", "data-tf-glass": "", "data-tf-assistant-palette": "", ...rootProps, className: "tf:m-auto tf:h-[calc(100dvh-2rem)] tf:w-[calc(100vw-2rem)] tf:flex-col " +
+    return (_jsx(TfDialog, { open: open, onOpenChange: onOpenChange, "aria-label": "Assistant", "data-tf-assistant": "", "data-tf-glass": "", "data-tf-popover": "", "data-tf-assistant-palette": "", ...rootProps, className: "tf:m-auto tf:h-[calc(100dvh-2rem)] tf:w-[calc(100vw-2rem)] tf:flex-col " +
             "tf:overflow-hidden tf:rounded-tf tf:border " +
-            "tf:text-tf-foreground tf:backdrop:bg-black/20 " +
+            "tf:backdrop:bg-black/20 " +
             "tf:sm:mt-24 tf:sm:h-[calc(100dvh-12rem)] tf:sm:max-h-144 tf:sm:w-full tf:sm:max-w-2xl", children: open ? (_jsx(LazyBody, { children: _jsx(AssistantPaletteBody, { onOpenChange: onOpenChange }) })) : null }));
 }

package/dist/components/child-transcript.js

@@ -26,7 +26,7 @@ export function ChildTranscriptPreview({ threadId, childSessionId, variantIndex,
     return (_jsx(ChildTranscript, { mode: "preview", threadId: threadId, childSessionId: childSessionId, variantIndex: variantIndex, opener: null, onBack: () => undefined }));
 }
 export function ChildTranscriptPreviewFrame({ label, status, duration, variantIndex, children, }) {
-    return (_jsxs("div", { role: "region", "aria-label": `Conversation preview: ${label}`, "data-tf-glass": "", "data-tf-child-transcript-preview": "", className: "tf:flex tf:h-full tf:w-full tf:min-h-0 tf:min-w-0 tf:flex-col tf:overflow-hidden tf:rounded-2xl tf:border tf:bg-tf-background", children: [_jsxs("div", { className: "tf:flex tf:items-center tf:gap-2 tf:border-b tf:px-3 tf:py-2.5", children: [_jsx("span", { className: "tf:flex tf:h-6 tf:min-w-6 tf:shrink-0 tf:items-center tf:justify-center tf:px-1", children: _jsx(AgentIdentityMark, { register: "subagent", variantIndex: variantIndex }) }), _jsx(ChildStatusMark, { status: status }), status === "running" ? (_jsx(ShimmerText, { className: "tf:min-w-0 tf:flex-1 tf:grid-cols-1 tf:text-tf-label tf:font-medium tf:text-tf-muted-foreground", children: _jsx("span", { className: "tf:block tf:truncate", title: label, children: activityTitleOf(label) }) })) : (_jsx("span", { className: "tf:min-w-0 tf:flex-1 tf:truncate tf:text-tf-label tf:font-medium", title: label, children: activityTitleOf(label) })), status === "running" ? (_jsx(ShimmerText, { className: "tf:shrink-0 tf:text-xs tf:text-tf-muted-foreground", children: "Working" })) : null, duration != null ? (_jsx("span", { className: "tf:shrink-0 tf:text-xs tf:text-tf-muted-foreground", children: duration })) : null] }), children] }));
+    return (_jsxs("div", { role: "region", "aria-label": `Conversation preview: ${label}`, "data-tf-glass": "", "data-tf-popover": "", "data-tf-child-transcript-preview": "", className: "tf:flex tf:h-full tf:w-full tf:min-h-0 tf:min-w-0 tf:flex-col tf:overflow-hidden tf:rounded-2xl tf:border", children: [_jsxs("div", { className: "tf:flex tf:items-center tf:gap-2 tf:border-b tf:px-3 tf:py-2.5", children: [_jsx("span", { className: "tf:flex tf:h-6 tf:min-w-6 tf:shrink-0 tf:items-center tf:justify-center tf:px-1", children: _jsx(AgentIdentityMark, { register: "subagent", variantIndex: variantIndex }) }), _jsx(ChildStatusMark, { status: status }), status === "running" ? (_jsx(ShimmerText, { className: "tf:min-w-0 tf:flex-1 tf:grid-cols-1 tf:text-tf-label tf:font-medium tf:text-tf-muted-foreground", children: _jsx("span", { className: "tf:block tf:truncate", title: label, children: activityTitleOf(label) }) })) : (_jsx("span", { className: "tf:min-w-0 tf:flex-1 tf:truncate tf:text-tf-label tf:font-medium", title: label, children: activityTitleOf(label) })), status === "running" ? (_jsx(ShimmerText, { className: "tf:shrink-0 tf:text-xs tf:text-tf-muted-foreground", children: "Working" })) : null, duration != null ? (_jsx("span", { className: "tf:shrink-0 tf:text-xs tf:text-tf-muted-foreground", children: duration })) : null] }), children] }));
 }
 function ChildStatusMark({ status }) {
     if (status === "running") {

package/dist/components/companion-header-disclosure.js

@@ -47,7 +47,7 @@ export function HeaderDisclosureMenu({ id, onClose, triggerRef, triggerId, "aria
             menuRef.current?.querySelector("button")?.focus();
         }
     }, [autoFocusFirstButton]);
-    return (_jsx("div", { ref: menuRef, id: id, role: "dialog", "aria-label": ariaLabel, "data-tf-glass": "", "data-tf-disclosure": "", "data-tf-surface-inset": insetFromSurfaceTop ? "" : undefined, className: cx("tf:absolute tf:top-14 tf:flex tf:max-h-96 tf:flex-col tf:overflow-hidden tf:rounded-2xl tf:border", className), onKeyDown: (event) => {
+    return (_jsx("div", { ref: menuRef, id: id, role: "dialog", "aria-label": ariaLabel, "data-tf-glass": "", "data-tf-popover": "", "data-tf-disclosure": "", "data-tf-surface-inset": insetFromSurfaceTop ? "" : undefined, className: cx("tf:absolute tf:top-14 tf:flex tf:max-h-96 tf:flex-col tf:overflow-hidden tf:rounded-2xl tf:border", className), onKeyDown: (event) => {
             if (event.key !== "Escape") {
                 return;
             }

package/dist/components/companion-history-menu.js

@@ -11,7 +11,7 @@ export function CompanionHeaderTitle({ menuId, open, onOpenChange, triggerRef, f
     if (!core.historyExpected) {
         return (_jsx("h2", { className: "tf:min-w-0 tf:flex-1 tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-muted-foreground", children: title }));
     }
-    return (_jsx("h2", { className: "tf:flex tf:min-w-0 tf:flex-1 tf:items-center tf:text-tf-label tf:font-medium tf:text-tf-muted-foreground", children: _jsxs(HeaderDisclosureTrigger, { menuId: menuId, open: open, onOpenChange: onOpenChange, triggerRef: triggerRef, variant: "bare", className: "tf:-ml-1.5 tf:min-w-0 tf:px-1.5 tf:py-1 tf:hover:bg-tf-accent tf:hover:text-tf-foreground", children: [_jsx("span", { className: "tf:min-w-0 tf:truncate", children: title }), _jsx(ChevronDownIcon, {})] }) }));
+    return (_jsx("h2", { className: "tf:flex tf:min-w-0 tf:flex-1 tf:items-center tf:text-tf-label tf:font-medium tf:text-tf-muted-foreground", children: _jsxs(HeaderDisclosureTrigger, { menuId: menuId, open: open, onOpenChange: onOpenChange, triggerRef: triggerRef, variant: "bare", className: "tf:-ml-1.5 tf:min-w-0 tf:px-1.5 tf:py-1 tf:hover:bg-tf-accent tf:hover:text-tf-accent-foreground", children: [_jsx("span", { className: "tf:min-w-0 tf:truncate", children: title }), _jsx(ChevronDownIcon, {})] }) }));
 }
 export function CompanionHistoryMenu({ id, onClose, triggerRef, triggerId, insetFromSurfaceTop, }) {
     const core = useAssistantConversation();

package/dist/components/composer.js

@@ -1,8 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState, } from "react";
-import { ASSISTANT_MAX_ATTACHMENTS, ASSISTANT_MESSAGE_MAX_CHARS, } from "../contract/threads.js";
-import { humanFileSize } from "./human-file-size.js";
+import { ASSISTANT_MESSAGE_MAX_CHARS, } from "../contract/threads.js";
 import { attachmentAcceptOf, ComposerAttachmentChip, } from "./composer-attachment-chip.js";
 import { ComposerBanner } from "./composer-banner.js";
 import { useConversation } from "./conversation-context.js";
@@ -13,14 +12,15 @@ import { TfTextarea } from "./primitives/textarea.js";
 import { ModelPickerShelf } from "./model-picker-chip.js";
 import { useOptionalAssistantSession } from "./teaflask-assistant-provider.js";
 import { NO_GATE } from "../core/connect-gate.js";
-import { attachmentDraftFailed, capSlotsSpentBy, CHARACTER_COUNT_VISIBLE_FROM, composerKeyHandlersOf, mintAttachmentDraftId, pickCapOf, } from "../core/composer-policy.js";
+import { attachmentRoomOf } from "../core/composer-attachments.js";
+import { attachmentDraftFailed, capSlotsSpentBy, CHARACTER_COUNT_VISIBLE_FROM, composerKeyHandlersOf, } from "../core/composer-policy.js";
 import { ObservableCell } from "../core/observable-cell.js";
 import { useCell } from "./use-store-cell.js";
 const NO_POLICY = new ObservableCell(null);
 const NO_GATE_CELL = new ObservableCell(NO_GATE);
 const COMPOSER_MAX_HEIGHT_PX = 200;
 export function Composer({ compact = false, surface = "page", }) {
-    const { busy, pendingSend, sendMessage, composerRefocusPending, markComposerRefocusHandled, stopping, stopTurn, composerInput, setDraft, setAttachments, noteComposerFocus, takeComposerCaretReturn, } = useConversation();
+    const { busy, pendingSend, sendMessage, composerRefocusPending, markComposerRefocusHandled, stopping, stopTurn, composerInput, setDraft, setAttachments, addFiles, noteComposerFocus, takeComposerCaretReturn, } = useConversation();
     const { draft, attachments } = useCell(composerInput);
     const session = useOptionalAssistantSession();
     const policy = useCell(session?.attachmentPolicy ?? NO_POLICY);
@@ -37,7 +37,7 @@ export function Composer({ compact = false, surface = "page", }) {
     const attach = useComposerAttachments({
         session,
         policy,
-        attachments,
+        addFiles,
         setAttachments,
     });
     const { textareaRef, onTextareaFocus, onTextareaBlur } = useComposerFocus({
@@ -96,74 +96,20 @@ function useComposerSend({ busy, draft, attachments, composerInput, sendMessage,
     }
     return { sending, sendDisabled, submitDraft };
 }
-function useComposerAttachments({ session, policy, attachments, setAttachments, }) {
+function useComposerAttachments({ session, policy, addFiles, setAttachments, }) {
     useEffect(() => {
         session?.ensureAssistantConfig();
     }, [session]);
-    function addFiles(files) {
-        if (files === null || policy === null || session === null) {
-            return;
-        }
-        const { store } = session;
-        const room = Math.min(policy.max_per_message, ASSISTANT_MAX_ATTACHMENTS);
-        let taken = capSlotsSpentBy(attachments);
-        for (const file of Array.from(files)) {
-            const localId = mintAttachmentDraftId();
-            const entry = {
-                localId,
-                filename: file.name !== "" ? file.name : "attachment",
-                byteSize: file.size,
-                status: "uploading",
-            };
-            if (taken >= room) {
-                setAttachments((current) => [
-                    ...current,
-                    {
-                        ...entry,
-                        status: "failed",
-                        error: `Too many files — the limit is ${String(room)} per message.`,
-                    },
-                ]);
-                continue;
-            }
-            const cap = pickCapOf(file, policy.max_bytes_by_kind);
-            if (file.size > cap.bytes) {
-                setAttachments((current) => [
-                    ...current,
-                    {
-                        ...entry,
-                        status: "failed",
-                        error: `Too large — the limit for ${cap.label} is ${humanFileSize(cap.bytes)}.`,
-                    },
-                ]);
-                continue;
-            }
-            taken += 1;
-            setAttachments((current) => [...current, entry]);
-            store.uploadAttachment(file).then((settled) => {
-                setAttachments((current) => current.map((item) => item.localId === localId
-                    ? { ...item, status: "ready", attachment: settled }
-                    : item));
-            }, (error) => {
-                setAttachments((current) => current.map((item) => item.localId === localId
-                    ? {
-                        ...item,
-                        status: "failed",
-                        error: error instanceof Error
-                            ? error.message
-                            : "The upload failed.",
-                    }
-                    : item));
-            });
+    function pickFiles(files) {
+        if (files !== null) {
+            void addFiles(files);
         }
     }
     function removeAttachment(localId) {
         setAttachments((current) => current.filter((item) => item.localId !== localId));
     }
-    const attachmentRoom = policy === null
-        ? 0
-        : Math.min(policy.max_per_message, ASSISTANT_MAX_ATTACHMENTS);
-    return { attachmentRoom, addFiles, removeAttachment };
+    const attachmentRoom = policy === null ? 0 : attachmentRoomOf(policy);
+    return { attachmentRoom, addFiles: pickFiles, removeAttachment };
 }
 function useComposerFocus({ surface, draft, busy, composerRefocusPending, markComposerRefocusHandled, noteComposerFocus, takeComposerCaretReturn, }) {
     const textareaRef = useRef(null);

package/dist/components/conversation-context.d.ts

@@ -1,4 +1,10 @@
 import type { ComposerContract } from "../core/conversation-store.js";
 export type { ComposerContract };
 export declare const ConversationContext: import("react").Context<ComposerContract | null>;
+/**
+ * Returns the live message-box state and controls for the open conversation
+ * (busy and stopping flags, the draft, `sendMessage`, `stopTurn`), for building
+ * your own composer or send buttons. It must be called inside the provider
+ * (from either entry point) and throws otherwise.
+ */
 export declare function useConversation(): ComposerContract;

package/dist/components/conversation-gate-card.js

@@ -34,7 +34,7 @@ function ConnectBannerRow({ status, gate, refresh, }) {
         session.notePlanSignedIn(status.provider);
     });
     if (connect.flow.kind !== "idle") {
-        return (_jsx(ConnectFlow, { name: name, flow: connect.flow, errorSentence: connect.errorSentence, onBegin: connect.begin, onCancel: connect.cancel, onTabOpened: connect.noteTabOpened }));
+        return (_jsx(ConnectFlow, { name: name, flow: connect.flow, errorSentence: connect.errorSentence, onBegin: connect.begin, onCancel: connect.cancel }));
     }
     const taster = gate.reason === "taster_exhausted";
     return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "tf:flex tf:flex-wrap tf:items-center tf:gap-x-3 tf:gap-y-2", children: [_jsxs("p", { className: "tf:m-0 tf:flex tf:min-w-56 tf:flex-1 tf:items-center tf:gap-2 tf:text-tf-label tf:text-tf-foreground", children: [_jsx(OpenAiMarkIcon, {}), taster

package/dist/components/conversation-view.d.ts

@@ -1,10 +1,21 @@
 import type { ReactNode } from "react";
 import type { AssistantConversation } from "./use-assistant-conversation.js";
+/**
+ * The icon for an opening prompt. `"ask"` shows a magnifying glass, `"review"`
+ * a flag, `"write"` a pencil and `"learn"` a book.
+ */
 export type AssistantSuggestionKind = "ask" | "review" | "write" | "learn";
+/** An opening prompt, with the icon shown beside it. */
 export interface AssistantSuggestion {
+    /** The text shown and, when clicked, sent as the user's message. */
     prompt: string;
+    /** Which icon the prompt shows, and the default is `"ask"`. */
     kind?: AssistantSuggestionKind;
 }
+/**
+ * An opening prompt, given as plain text (shown with the `"ask"` icon) or as an
+ * object with a `kind`.
+ */
 export type AssistantSuggestionInput = string | AssistantSuggestion;
 export declare function ConversationView({ core, surface, suggestions, welcomeTitle, welcomeMark, }: {
     core: AssistantConversation;

package/dist/components/elicitation-context.d.ts

@@ -1,14 +1,53 @@
 import type { ElicitationCardModel, QuestionSetCardModel } from "../core/elicitation-cards.js";
 import { QuestionDraftStore } from "../core/question-drafts.js";
+/**
+ * The question sets to show, how to answer or dismiss them, and their unsent
+ * answers, as returned by useElicitations().
+ */
 export interface ElicitationSurface {
+    /**
+     * Question sets the agent has asked in the open conversation. Sets already
+     * answered or no longer answerable can stay in the list for a while, so
+     * render by each card's status.
+     */
     cards: readonly ElicitationCardModel[];
+    /**
+     * Sends answers to a whole question set in one request, exactly one { id,
+     * text } per question, each text at most 1,900 characters. It does not
+     * reject: on a server error or while the conversation is disconnected the
+     * card's errorSentence explains it, the card stays answerable and the draft
+     * is kept; on success the set's draft is cleared; a set that was already
+     * answered elsewhere or has expired turns stale instead (it can no longer
+     * be answered), and its draft goes with it. Repeat submits while one is in
+     * flight are ignored.
+     */
     submitQuestionAnswers: (card: QuestionSetCardModel, answers: readonly {
         id: string;
         text: string;
     }[]) => Promise<void>;
+    /**
+     * Dismisses a whole question set without answering: the agent is told the
+     * visitor declined and carries on without asking the same questions again.
+     * Like submitQuestionAnswers it does not reject. While the conversation is
+     * disconnected, or on a server error, nothing is dismissed and the card's
+     * errorSentence says so. On success the set's draft is cleared; a set
+     * already answered elsewhere or expired turns stale instead, and its draft
+     * goes with it. Repeat requests while one is in flight are ignored.
+     */
     cancelQuestionSet: (card: QuestionSetCardModel) => Promise<void>;
+    /**
+     * The visitor's unsent answers, kept outside your components so remounts
+     * and reconnects don't lose them. In memory only, so a page reload discards
+     * them.
+     */
     drafts: QuestionDraftStore;
 }
 export declare const ElicitationsContext: import("react").Context<ElicitationSurface>;
+/**
+ * Returns the questions the agent is asking the visitor, the functions that
+ * answer or dismiss them, and the store of unsent answers. Live inside
+ * <TeaflaskAssistantProvider>; outside it the list is empty and submitting or
+ * cancelling rejects with an error.
+ */
 export declare function useElicitations(): ElicitationSurface;
 export declare function anchoredElicitationsFor(cards: readonly ElicitationCardModel[], toolCallId: string): ElicitationCardModel[];

package/dist/components/model-picker-chip.js

@@ -56,7 +56,9 @@ function MountedModelPickerShelf() {
     }
     return (_jsxs("div", { className: "tf:relative tf:mt-1.5 tf:flex tf:items-center tf:justify-end tf:gap-2 tf:px-1", children: [ownsAccountChip ? (_jsx(ProviderChip, { statuses: connectable, open: openChip === "account", onOpenChange: (next) => {
                     setOpenChip(next ? "account" : null);
-                }, fundingNote: "Models your plan serves run on it; other picks run on this site's own funding." })) : null, _jsx(ModelPickerChip, { menu: menu, open: openChip === "picker", onOpenChange: (next) => {
+                }, fundingNote: connectable.some((status) => status.offered)
+                    ? "Models your plan serves run on it; other picks run on this site's own funding."
+                    : undefined })) : null, _jsx(ModelPickerChip, { menu: menu, open: openChip === "picker", onOpenChange: (next) => {
                     setOpenChip(next ? "picker" : null);
                 } })] }));
 }
@@ -64,7 +66,7 @@ function ModelPickerChip({ menu, open, onOpenChange, }) {
     const { modelPick, setModelPick } = useConversation();
     const { panel, setPanel, showPanel, triggerRef, menuRef, rootPanelRef, modelPanelRef, effortPanelRef, } = useModelPickerPanels({ open, onOpenChange });
     const { currentModelId, renderedLadder, currentEffort, currentName } = pickerSelectionOf(menu, modelPick);
-    return (_jsxs(_Fragment, { children: [_jsx(ModelPickerTrigger, { triggerRef: triggerRef, open: open, onOpenChange: onOpenChange, setPanel: setPanel, currentName: currentName, currentEffort: currentEffort }), open ? (_jsxs("div", { ref: menuRef, id: "tf-model-picker-menu", role: "dialog", "aria-label": "Choose model and effort", "data-tf-glass": "", className: "tf:absolute tf:right-0 tf:bottom-full tf:mb-2 tf:flex tf:max-h-[min(32rem,calc(100vh-6rem))] tf:w-80 tf:max-w-full tf:flex-col tf:overflow-y-auto tf:rounded-2xl tf:border tf:p-2", onKeyDown: (event) => {
+    return (_jsxs(_Fragment, { children: [_jsx(ModelPickerTrigger, { triggerRef: triggerRef, open: open, onOpenChange: onOpenChange, setPanel: setPanel, currentName: currentName, currentEffort: currentEffort }), open ? (_jsxs("div", { ref: menuRef, id: "tf-model-picker-menu", role: "dialog", "aria-label": "Choose model and effort", "data-tf-glass": "", "data-tf-popover": "", className: "tf:absolute tf:right-0 tf:bottom-full tf:mb-2 tf:flex tf:max-h-[min(32rem,calc(100vh-6rem))] tf:w-80 tf:max-w-full tf:flex-col tf:overflow-y-auto tf:rounded-2xl tf:border tf:p-2", onKeyDown: (event) => {
                     if (event.key !== "Escape") {
                         return;
                     }