@teaflask/assistant 0.6.0 → 0.7.0

package/README.md

@@ -156,7 +156,7 @@ Next, [connect actions to your API](https://docs.teaflask.com/adapters), [identi
 - [Assistant UI](https://docs.teaflask.com/assistant-ui)
 - [Trust](https://docs.teaflask.com/trust)
 
-Requires `react` and `react-dom` 18.3 or 19, and `use-stick-to-bottom` (npm installs peers for you; the script tag needs none of them). The package is pre-1.0: a breaking change bumps the minor version, and the [changelog](https://github.com/teaflask/assistant/blob/main/CHANGELOG.md) lists what changed in every release. You can inspect the published code on [npm](https://www.npmjs.com/package/@teaflask/assistant?activeTab=code) or [unpkg](https://unpkg.com/@teaflask/assistant/).
+Requires `react` and `react-dom` 18.3 or 19 (the script tag needs neither). The package is pre-1.0: a breaking change bumps the minor version, and the [changelog](https://github.com/teaflask/assistant/blob/main/CHANGELOG.md) lists what changed in every release. Every public export and field is described in the package's types, and the script tag's attributes and properties in its `custom-elements.json`, so your editor and coding agent can read what each one means. You can inspect the published code on [npm](https://www.npmjs.com/package/@teaflask/assistant?activeTab=code) or [unpkg](https://unpkg.com/@teaflask/assistant/).
 
 ## License
 

package/custom-elements.json

@@ -0,0 +1,264 @@
+{
+  "schemaVersion": "2.1.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "https://app.teaflask.com/assistant/v1/assistant.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "TeaflaskAssistantPageElement",
+          "customElement": true,
+          "tagName": "teaflask-assistant-page",
+          "description": "The full-page assistant for any page, loaded with a script tag: the conversation with a header, a history menu and a new-conversation button. It fills its container, so give the element a height.",
+          "attributes": [
+            {
+              "name": "publishable-key",
+              "type": {
+                "text": "string"
+              },
+              "description": "Your agent's publishable key from Teaflask. Nothing renders until it is set, and requests are accepted only from your allowed origins. Changing it starts a separate session."
+            },
+            {
+              "name": "base-url",
+              "type": {
+                "text": "string"
+              },
+              "description": "The Teaflask API origin, which defaults to https://api.teaflask.com. Changing it starts a separate session."
+            },
+            {
+              "name": "mode",
+              "type": {
+                "text": "string"
+              },
+              "description": "The color palette: \"light\", \"dark\", or \"auto\" to follow the visitor's operating-system setting. Any other value warns in the console and uses the default."
+            },
+            {
+              "name": "heading",
+              "type": {
+                "text": "string"
+              },
+              "description": "The name shown in the page's header, which defaults to \"Assistant\". It is called heading, not title, so it doesn't show a native tooltip over the page."
+            },
+            {
+              "name": "frameless",
+              "type": {
+                "text": "string"
+              },
+              "description": "Removes the page's own border and rounded corners so it sits flush inside a frame you already draw. Present with no value, or \"true\", turns it on; \"false\" turns it off."
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "onNavigate",
+              "type": {
+                "text": "((path: string) => void | Promise<void>) | null | undefined"
+              },
+              "description": "Called with an app-relative path when the agent takes the user to a page. Leave it unset and the page does a full-page load to that path; set a function to use your own router, or null to tell the agent this page cannot navigate."
+            },
+            {
+              "kind": "field",
+              "name": "userId",
+              "type": {
+                "text": "string | null | undefined"
+              },
+              "description": "Your stable id for the signed-in user, set together with getEndUserToken. It must equal the user_id claim in the token; setting only one of the two runs the session anonymously, with a console warning."
+            },
+            {
+              "kind": "field",
+              "name": "getEndUserToken",
+              "type": {
+                "text": "(() => string | Promise<string | null> | null) | null | undefined"
+              },
+              "description": "Returns a short-lived token from your backend proving who the user is: an HS256 JWT with user_id and exp (and optionally email), signed with the JWT secret from Settings → Keys in Teaflask. Set it together with userId; returning null continues anonymously."
+            },
+            {
+              "kind": "field",
+              "name": "actionsAdapter",
+              "type": {
+                "text": "ActionsAdapter | null | undefined"
+              },
+              "description": "How this page calls your API when the agent runs an action: { kind: \"cookies\", baseUrl }, { kind: \"headers\", baseUrl, getHeaders }, or { kind: \"request\", execute }. Without one, or with an unrecognized kind (which warns), the agent cannot run actions here and tells the user to do the step themselves."
+            },
+            {
+              "kind": "field",
+              "name": "onError",
+              "type": {
+                "text": "((error: Error) => void) | null | undefined"
+              },
+              "description": "Called with errors for your error reporting, such as a failed send, a dropped stream or a failed session-token request."
+            },
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "AssistantTheme | null | undefined"
+              },
+              "description": "Theme tokens and dark-mode overrides, the same object as the React theme prop. Under a strict Content Security Policy this needs inline styles allowed; otherwise set the --tf- CSS variables in your own CSS."
+            },
+            {
+              "kind": "field",
+              "name": "suggestions",
+              "type": {
+                "text": "readonly AssistantSuggestionInput[] | null | undefined"
+              },
+              "description": "Opening prompts shown under the message box before the first message, as strings or { prompt, kind } objects. The full-page assistant shows none unless you set them."
+            },
+            {
+              "kind": "field",
+              "name": "toolViews",
+              "type": {
+                "text": "Readonly<Record<string, ToolViewRegistration>> | null | undefined"
+              },
+              "description": "Your own components for displaying specific tools and actions, keyed by tool name (action__<slug> for an action), the same registry as the React toolViews prop. It can be set before or after the element loads and reaches calls already on screen; keys starting with teaflask. and malformed entries are dropped one by one with a console warning."
+            }
+          ]
+        },
+        {
+          "kind": "class",
+          "name": "TeaflaskAssistantElement",
+          "customElement": true,
+          "tagName": "teaflask-assistant",
+          "description": "The all-in-one assistant for any page, loaded with a script tag: the corner widget, which opens the chat drawer, and the ⌘K palette. React is bundled inside. Use one per page, in markup that every page shares.",
+          "attributes": [
+            {
+              "name": "publishable-key",
+              "type": {
+                "text": "string"
+              },
+              "description": "Your agent's publishable key from Teaflask. Nothing renders until it is set, and requests are accepted only from your allowed origins. Changing it starts a separate session."
+            },
+            {
+              "name": "base-url",
+              "type": {
+                "text": "string"
+              },
+              "description": "The Teaflask API origin, which defaults to https://api.teaflask.com. Changing it starts a separate session."
+            },
+            {
+              "name": "mode",
+              "type": {
+                "text": "string"
+              },
+              "description": "The color palette: \"light\", \"dark\", or \"auto\" to follow the visitor's operating-system setting. Any other value warns in the console and uses the default."
+            },
+            {
+              "name": "corner",
+              "type": {
+                "text": "string"
+              },
+              "description": "The screen corner where the widget and its drawer sit: \"bottom-right\" (the default) or \"bottom-left\"."
+            },
+            {
+              "name": "hotkey",
+              "type": {
+                "text": "string"
+              },
+              "description": "The keyboard shortcut that toggles the palette, which defaults to \"mod+k\" (⌘ on macOS, Ctrl elsewhere); for example \"mod+j\" or \"ctrl+shift+p\". Set \"false\" to disable it; an unrecognized value also disables it, with a console warning."
+            },
+            {
+              "name": "companion-mark-src",
+              "type": {
+                "text": "string"
+              },
+              "description": "The URL of your own logo or mascot image, shown on the corner widget and on the drawer's welcome screen. If the image fails to load, the Teaflask flask is shown instead."
+            }
+          ],
+          "members": [
+            {
+              "kind": "method",
+              "name": "openPalette",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Opens the ⌘K palette, even when the hotkey is disabled or rebound. Does nothing before the element has a publishable key."
+            },
+            {
+              "kind": "field",
+              "name": "onNavigate",
+              "type": {
+                "text": "((path: string) => void | Promise<void>) | null | undefined"
+              },
+              "description": "Called with an app-relative path when the agent takes the user to a page. Leave it unset and the page does a full-page load to that path; set a function to use your own router, or null to tell the agent this page cannot navigate."
+            },
+            {
+              "kind": "field",
+              "name": "userId",
+              "type": {
+                "text": "string | null | undefined"
+              },
+              "description": "Your stable id for the signed-in user, set together with getEndUserToken. It must equal the user_id claim in the token; setting only one of the two runs the session anonymously, with a console warning."
+            },
+            {
+              "kind": "field",
+              "name": "getEndUserToken",
+              "type": {
+                "text": "(() => string | Promise<string | null> | null) | null | undefined"
+              },
+              "description": "Returns a short-lived token from your backend proving who the user is: an HS256 JWT with user_id and exp (and optionally email), signed with the JWT secret from Settings → Keys in Teaflask. Set it together with userId; returning null continues anonymously."
+            },
+            {
+              "kind": "field",
+              "name": "actionsAdapter",
+              "type": {
+                "text": "ActionsAdapter | null | undefined"
+              },
+              "description": "How this page calls your API when the agent runs an action: { kind: \"cookies\", baseUrl }, { kind: \"headers\", baseUrl, getHeaders }, or { kind: \"request\", execute }. Without one, or with an unrecognized kind (which warns), the agent cannot run actions here and tells the user to do the step themselves."
+            },
+            {
+              "kind": "field",
+              "name": "onError",
+              "type": {
+                "text": "((error: Error) => void) | null | undefined"
+              },
+              "description": "Called with errors for your error reporting, such as a failed send, a dropped stream or a failed session-token request."
+            },
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "AssistantTheme | null | undefined"
+              },
+              "description": "Theme tokens and dark-mode overrides, the same object as the React theme prop. Under a strict Content Security Policy this needs inline styles allowed; otherwise set the --tf- CSS variables in your own CSS."
+            },
+            {
+              "kind": "field",
+              "name": "suggestions",
+              "type": {
+                "text": "readonly AssistantSuggestionInput[] | null | undefined"
+              },
+              "description": "Opening prompts for the drawer's welcome screen, as strings or { prompt, kind } objects. Leave it unset to use the prompts configured for your agent in Teaflask; any value, even an empty list, replaces them."
+            },
+            {
+              "kind": "field",
+              "name": "toolViews",
+              "type": {
+                "text": "Readonly<Record<string, ToolViewRegistration>> | null | undefined"
+              },
+              "description": "Your own components for displaying specific tools and actions, keyed by tool name (action__<slug> for an action), the same registry as the React toolViews prop. It can be set before or after the element loads and reaches calls already on screen; keys starting with teaflask. and malformed entries are dropped one by one with a console warning."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "teaflask-assistant-page",
+          "declaration": {
+            "name": "TeaflaskAssistantPageElement"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "teaflask-assistant",
+          "declaration": {
+            "name": "TeaflaskAssistantElement"
+          }
+        }
+      ]
+    }
+  ]
+}

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") {