@teaflask/assistant 0.3.0 → 0.7.0

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/activity.d.ts

@@ -1,6 +1,5 @@
-export { TeaflaskAssistantProvider, type TeaflaskAssistantProviderProps, } from "./components/teaflask-assistant-provider.js";
+export { TeaflaskAssistantProvider, type TeaflaskAssistantAnonymousProps, type TeaflaskAssistantIdentityProps, type TeaflaskAssistantProviderBaseProps, type TeaflaskAssistantProviderProps, } from "./components/teaflask-assistant-provider.js";
 export { useAssistantActivity } from "./components/use-assistant-activity.js";
 export type { AssistantActivityResult, AssistantActivitySnapshot, } from "./core/activity.js";
 export type { PendingDecisionGap } from "./core/pending-decision-gap.js";
 export { AssistantCompanion, type AssistantCompanionProps, } from "./components/assistant-companion.js";
-//# sourceMappingURL=activity.d.ts.map

package/dist/activity.js

@@ -1,15 +1,3 @@
-// The activity-only entry: a consumer that
-// renders presence — a companion, a badge, a doorbell — imports the
-// provider and the feed from here and never pays for the transcript
-// chrome, CopilotKit, or their stylesheets. The root entry exports the
-// same names for convenience, but only THIS subpath's import graph
-// provably excludes the transcript (tests/bundle-closure.test.ts holds
-// it to that).
 export { TeaflaskAssistantProvider, } from "./components/teaflask-assistant-provider.js";
 export { useAssistantActivity } from "./components/use-assistant-activity.js";
-// The companion presence surface lives on this entry: its
-// minimized widget is the corner mark this lean bundle serves, and its
-// chat drawer rides a dynamic import so the transcript exclusion above
-// still holds statically.
 export { AssistantCompanion, } from "./components/assistant-companion.js";
-//# sourceMappingURL=activity.js.map

package/dist/affordances/highlight.js

@@ -1,24 +1,8 @@
-// The spotlight: "it's *this* switch". Scrolls the target into view and
-// draws the package's own overlay ring around it for a few seconds —
-// the host element itself is never touched (no class, no style, no
-// attribute), so a highlight can never fight the page's own rendering.
-// One spotlight at a time: pointing somewhere new dismisses the old one.
-// Geometry goes through the layout probe so the placement logic
-// unit-tests under jsdom.
-// How long the ring dwells before fading — long enough to find, short
-// enough that the page never feels annotated.
 export const HIGHLIGHT_DWELL_MS = 4_000;
-// The fade matches the CSS transition on .tf-highlight-ring.
 const FADE_MS = 300;
-// The ring sits this far outside the target's own box.
 const RING_INSET_PX = 4;
 const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
 let _activeSpotlight = null;
-/**
- * Scroll the element into view and spotlight it. Fire-and-forget on
- * purpose: the tool's result reports that the spotlight was shown, and
- * the dwell/fade play out after the handler has answered.
- */
 export function spotlightElement(element, probe) {
     _activeSpotlight?.dismiss();
     _scrollIntoViewRespectingMotion(element);
@@ -28,9 +12,6 @@ export function spotlightElement(element, probe) {
         _placeRingAround(ring, element, probe);
     };
     track();
-    // Capture-phase scroll hears every scroll container (scroll events do
-    // not bubble), so the ring rides along while scrollIntoView animates
-    // and while the user keeps scrolling.
     window.addEventListener("scroll", track, { capture: true, passive: true });
     window.addEventListener("resize", track);
     const dismiss = _dismisserOf(ring, track);
@@ -57,8 +38,6 @@ function _dismisserOf(ring, track) {
 }
 function _ringElement() {
     const ring = document.createElement("div");
-    // The data-tf-assistant attribute is the package stylesheet's scope
-    // marker (never an API); the class carries the ring's look.
     ring.setAttribute("data-tf-assistant", "");
     ring.className = "tf-highlight-ring";
     ring.setAttribute("aria-hidden", "true");
@@ -72,8 +51,6 @@ function _placeRingAround(ring, element, probe) {
     ring.style.height = `${String(rect.height + 2 * RING_INSET_PX)}px`;
 }
 function _scrollIntoViewRespectingMotion(element) {
-    // jsdom has no scrollIntoView; the ring still places, so a missing
-    // scroll degrades to an unscrolled spotlight rather than a crash.
     if (typeof element.scrollIntoView !== "function") {
         return;
     }
@@ -84,12 +61,7 @@ function _scrollIntoViewRespectingMotion(element) {
     });
 }
 function _reducedMotionIsOn() {
-    // Both switches, like every motion in the package: the OS preference
-    // and the host's own kill switch. Walked from where the ring mounts
-    // (a <body> child), so the scroll agrees with the ring's own CSS
-    // about which ancestors can carry the switch.
     return ((typeof window.matchMedia === "function" &&
         window.matchMedia(REDUCED_MOTION_QUERY).matches) ||
         document.body.closest('[data-reduce-motion="true"]') !== null);
 }
-//# sourceMappingURL=highlight.js.map

package/dist/affordances/prefill.js

@@ -1,11 +1,3 @@
-// Filling without submitting: the reversible half of a form. Each field
-// is resolved by the reader's ref, guarded (secrets, files, disabled
-// controls are refused with no way to opt out — the write-side twin of
-// the snapshot's redaction), written through the element's own prototype
-// setter with real input/change events (a React-controlled input ignores
-// a bare .value assignment), and then read back: a value the page's own
-// scripts rejected is reported as refused, never claimed as filled.
-// Nothing here ever submits, clicks a button, or focuses past the field.
 import { theFieldHoldsASecret } from "../reader/redaction.js";
 import { resolvedElementOfRef } from "../reader/snapshot.js";
 import { isContentEditableElement } from "../reader/roles.js";
@@ -25,11 +17,6 @@ const VALUE_DID_NOT_LAND_REASON = "The page's own scripts rejected this value
     "field.";
 const EDITOR_UNAVAILABLE_REASON = "This editor cannot be filled on this page — tell the user what to " +
     "type instead.";
-/**
- * Fill every requested field, one report entry per field — a batch is
- * never all-or-nothing: the fields that landed stay landed, and each
- * refusal carries its own actionable reason.
- */
 export function prefilledFieldsReport(fields) {
     const report = { filled: [], refused: [] };
     for (const field of fields) {
@@ -43,7 +30,6 @@ export function prefilledFieldsReport(fields) {
     }
     return report;
 }
-/** Fill one field; the refusal reason, or null when the value landed. */
 function _filledFieldRefusalOf(field) {
     const resolved = resolvedElementOfRef(field.refId);
     if (resolved.error !== null) {
@@ -64,7 +50,6 @@ function _filledFieldRefusalOf(field) {
     }
     return NOT_FILLABLE_REASON;
 }
-// --- inputs ------------------------------------------------------------------
 const _NOT_A_FIELD_INPUT_TYPES = new Set([
     "hidden",
     "submit",
@@ -79,10 +64,6 @@ function _inputRefusalOf(input, value) {
     if (input.type === "file") {
         return FILE_FIELD_REASON;
     }
-    // Hidden inputs hold machine state the user never sees — writing one
-    // would change what the form submits with nothing to review. The
-    // button family is not a field at all: its value IS the visible
-    // caption, so "filling" one would relabel a button.
     if (_NOT_A_FIELD_INPUT_TYPES.has(input.type)) {
         return NOT_FILLABLE_REASON;
     }
@@ -105,14 +86,10 @@ function _checkedRefusalOf(input, value) {
     }
     const desired = value === "true";
     if (input.checked !== desired) {
-        // A real click, not a checked assignment: it is the one event shape
-        // every framework's change handling hears, and on a checkbox it is
-        // still reversible prep — the user can click it right back.
         input.click();
     }
     return input.checked === desired ? null : VALUE_DID_NOT_LAND_REASON;
 }
-// --- textareas ----------------------------------------------------------------
 function _textAreaRefusalOf(textArea, value) {
     if (theFieldHoldsASecret(textArea)) {
         return SECRET_FIELD_REASON;
@@ -124,7 +101,6 @@ function _textAreaRefusalOf(textArea, value) {
     _announceTheEdit(textArea);
     return textArea.value === value ? null : VALUE_DID_NOT_LAND_REASON;
 }
-// --- selects --------------------------------------------------------------------
 function _selectRefusalOf(select, value) {
     if (select.disabled) {
         return INERT_FIELD_REASON;
@@ -139,23 +115,14 @@ function _selectRefusalOf(select, value) {
 }
 function _optionMatching(select, value) {
     const options = Array.from(select.options);
-    // The model quotes what it saw: sometimes the option's value,
-    // sometimes its visible label.
     return (options.find((option) => option.value === value) ??
         options.find((option) => option.label.trim() === value.trim()) ??
         null);
 }
-// --- contenteditable editors ----------------------------------------------------
 function _editorRefusalOf(element, value) {
-    // The caller established contenteditable; this narrows for focus().
     if (!(element instanceof HTMLElement)) {
         return EDITOR_UNAVAILABLE_REASON;
     }
-    // execCommand is deprecated but is the one path that speaks a rich
-    // editor's own language: it fires the beforeinput/input sequence the
-    // editor's model listens to. jsdom has neither it nor selections.
-    /* eslint-disable @typescript-eslint/no-deprecated -- no substitute
-       fires an editor's own input pipeline; see the comment above. */
     if (typeof document.execCommand !== "function") {
         return EDITOR_UNAVAILABLE_REASON;
     }
@@ -166,15 +133,10 @@ function _editorRefusalOf(element, value) {
     }
     selection.selectAllChildren(element);
     document.execCommand("insertText", false, value);
-    /* eslint-enable @typescript-eslint/no-deprecated -- back to the rule
-       for everything below the editor write. */
     const landed = element.textContent.includes(value);
     return landed ? null : VALUE_DID_NOT_LAND_REASON;
 }
 function _setThroughThePrototype(control, value) {
-    // React tracks a control's value on the instance to dedupe its own
-    // synthetic events; writing through the prototype setter bypasses the
-    // tracker so the input event below is heard as a real user edit.
     const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(control), "value");
     if (descriptor?.set !== undefined) {
         descriptor.set.call(control, value);
@@ -187,4 +149,3 @@ function _announceTheEdit(control) {
     control.dispatchEvent(new Event("input", { bubbles: true }));
     control.dispatchEvent(new Event("change", { bubbles: true }));
 }
-//# sourceMappingURL=prefill.js.map

package/dist/appearance/theme.d.ts

@@ -1,49 +1,169 @@
+/**
+ * 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;
-    /** A bare number means pixels. */
+    /**
+     * 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;
-    /** The UA scheme native form controls draw their indicators from
-     *  ("light" or "dark") — for hosts that dark-theme with tokens alone,
-     *  so native control chrome stays legible. The mode prop and the
-     *  data-tf-theme attribute already flip the default; a set value wins
-     *  in both modes, like every --tf-* token. */
+    /**
+     * 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 {
     /**
-     * Values that take over whenever dark is active — via the provider's
-     * `mode` prop or a `data-tf-theme="dark"` attribute on any ancestor.
+     * 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)[];
 export declare const DARK_THEME_TOKEN_KEYS: readonly (keyof AssistantThemeDarkTokens)[];
-/**
- * Maps a theme config to the CSS variables the widget roots carry
- * inline. Base values set the public `--tf-*` tokens — inline beats any
- * ambient host CSS, which is the prop-wins precedence. Dark values set
- * the private `--_tf-dark-*` mechanism variables the stylesheet's dark
- * blocks read first, so they stay out of the public token contract.
- */
 export declare function themeToStyleVars(theme: AssistantTheme): Record<string, string>;
-//# sourceMappingURL=theme.d.ts.map