@timbal-ai/timbal-react 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,13 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { ReactNode, FC, ComponentType, Dispatch, ComponentPropsWithRef, ElementType } from 'react';
+import React__default, { ReactNode, FC, ComponentType, Dispatch, ElementType } from 'react';
 import { AttachmentAdapter, ToolCallMessagePartComponent } from '@assistant-ui/react';
-export { ActionBarPrimitive, AssistantRuntimeProvider, AttachmentAdapter, ComposerPrimitive, MessagePrimitive, ThreadPrimitive, useComposerRuntime, useMessageRuntime, useThread, useThreadRuntime } from '@assistant-ui/react';
+export { ActionBarPrimitive, AssistantRuntimeProvider, AttachmentAdapter, AuiIf, ComposerPrimitive, MessagePrimitive, ThreadPrimitive, useComposerRuntime, useMessageRuntime, useThread, useThreadRuntime } from '@assistant-ui/react';
 import { WorkforceItem, Session } from '@timbal-ai/timbal-sdk';
 export { parseSSELine } from '@timbal-ai/timbal-sdk';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
-import { SyntaxHighlighterProps } from '@assistant-ui/react-markdown';
 import { Tooltip as Tooltip$1, Avatar as Avatar$1, Dialog as Dialog$1 } from 'radix-ui';
 import { ClassValue } from 'clsx';
 
@@ -217,41 +216,36 @@ interface ComposerProps {
     /** Placeholder shown in the textarea. Default: "Send a message..." */
     placeholder?: string;
     /**
-     * Show the file-attach button. Default: true. Disable when the agent has
-     * no use for attachments to keep the UI clean.
+     * Show the file-attach button. Default: true. Disable when the agent has no
+     * use for attachments to keep the toolbar clean.
      */
     showAttachments?: boolean;
-    /**
-     * Extra content rendered inside the toolbar, to the left of the send
-     * button. Use for custom buttons (voice, model picker, etc).
-     */
+    /** Extra content rendered inside the toolbar, left of the send button. */
     toolbar?: ReactNode;
-    /**
-     * Tooltip on the send button. Default: "Send message".
-     */
+    /** Tooltip shown on the send button. Default: "Send message". */
     sendTooltip?: string;
-    /** Disable autofocus on mount. Default: false (autofocused). */
+    /** Disable autofocus on mount. Default: false. */
     noAutoFocus?: boolean;
     /** Extra className applied to the outer composer wrapper. */
     className?: string;
 }
 /**
- * Composer v2 — auto-resizing textarea, Enter-to-send / Shift+Enter newline,
- * attach button on the left, send/stop on the right. Use as a top-level
- * component inside `<TimbalRuntimeProvider>` (or via `<Thread components={{
- * Composer }}>`).
+ * Default chat composer — auto-resizing textarea with Enter-to-send,
+ * Shift+Enter for newline, attach pill on the left, and a circular send /
+ * cancel button on the right. Wraps `ComposerPrimitive` so consumers can
+ * override individual slots without losing the Studio chrome.
  */
 declare const Composer: FC<ComposerProps>;
 
 interface ThreadSuggestion {
-    /** Title shown on the chip. Also sent verbatim as the user message. */
+    /** Title shown on the row. Also sent verbatim as the user message. */
     title: string;
     /** Optional secondary line. */
     description?: string;
     /** Optional leading icon. */
     icon?: ReactNode;
     /**
-     * Override the prompt sent when the chip is clicked. Useful when the chip
+     * Override the prompt sent when the row is clicked. Useful when the row
      * label is short ("Weekly recap") but the prompt should be longer.
      */
     prompt?: string;
@@ -263,18 +257,14 @@ interface ThreadSuggestion {
 type SuggestionsSource = ThreadSuggestion[] | (() => ThreadSuggestion[] | Promise<ThreadSuggestion[]>);
 interface ThreadSuggestionsProps {
     suggestions?: SuggestionsSource;
-    /**
-     * Compact layout: single row, horizontally scrollable, smaller chips. Use
-     * inline (e.g. above the composer or after a message) where vertical
-     * space is tight.
-     */
-    layout?: "grid" | "row";
     className?: string;
 }
 /**
- * Render suggestion chips. Resolves both static arrays and async sources.
- * On click, appends the suggestion's `prompt` (or `title` if no prompt) as
- * a user message via the thread runtime.
+ * Render suggestions as a stacked column of full-width rows. Each row reads
+ * like a list item rather than a chip, matching the Studio playground.
+ *
+ * On click the row's `prompt` (or `title` if no prompt) is appended as a
+ * user message via the thread runtime.
  */
 declare const Suggestions: FC<ThreadSuggestionsProps>;
 /**
@@ -283,12 +273,9 @@ declare const Suggestions: FC<ThreadSuggestionsProps>;
  * async functions stream in once the promise settles.
  */
 declare function useResolvedSuggestions(source?: SuggestionsSource): ThreadSuggestion[] | undefined;
-/**
- * Props passed to a custom `Suggestions` slot component. Replace the default
- * via `<Thread components={{ Suggestions: MySuggestions }}>`.
- */
 interface SuggestionsSlotProps {
     suggestions?: SuggestionsSource;
+    className?: string;
 }
 type SuggestionsComponent = ComponentType<SuggestionsSlotProps>;
 
@@ -584,6 +571,12 @@ declare function useUiCustomNodeRegistry(): Record<string, UiCustomNodeRenderer>
 interface ThreadWelcomeConfig {
     heading?: string;
     subheading?: string;
+    /**
+     * Optional brand icon rendered above the heading. Pass any ReactNode — the
+     * SDK no longer ships a default sparkle icon so apps can drop in their
+     * own logo or stay minimal.
+     */
+    icon?: ReactNode;
 }
 interface ThreadWelcomeProps {
     config?: ThreadWelcomeConfig;
@@ -596,17 +589,17 @@ interface ThreadWelcomeProps {
     Suggestions?: SuggestionsComponent;
 }
 interface ThreadComponents {
-    /** Replace the user message bubble. Access message content via `MessagePrimitive.Parts`. */
+    /** Replace the user message bubble. Access content via `MessagePrimitive.Parts`. */
     UserMessage?: ComponentType;
-    /** Replace the assistant message bubble. Access message content via `MessagePrimitive.Parts`. */
+    /** Replace the assistant message bubble. Access content via `MessagePrimitive.Parts`. */
     AssistantMessage?: ComponentType;
     /** Replace the inline edit composer. */
     EditComposer?: ComponentType;
     /** Replace the composer (input bar). Receives all `ComposerProps` from the parent. */
     Composer?: ComponentType<ComposerProps>;
-    /** Replace the welcome / empty state. Receives `config` and `suggestions` props. Controls its own visibility — use `useThread(s => s.isEmpty)` to replicate the default behaviour. */
+    /** Replace the welcome / empty state. Renders only while the thread is empty. */
     Welcome?: ComponentType<ThreadWelcomeProps>;
-    /** Replace the suggestion chip block (rendered inside Welcome and inline). */
+    /** Replace the suggestion list (rendered inside Welcome). */
     Suggestions?: SuggestionsComponent;
     /** Replace the scroll-to-bottom button. */
     ScrollToBottom?: ComponentType;
@@ -620,16 +613,16 @@ interface ThreadArtifactsConfig {
 
 interface ThreadProps {
     className?: string;
-    /** Max width of the message column. Default: "44rem" */
+    /** Max width of the message column. Default: "44rem". */
     maxWidth?: string;
-    /** Welcome screen text */
+    /** Welcome screen text + optional brand icon. */
     welcome?: ThreadWelcomeConfig;
     /**
-     * Welcome-screen suggestion chips. Accepts a static array, a thunk, or an
+     * Welcome-screen suggestion rows. Accepts a static array, a thunk, or an
      * async function for per-user suggestions.
      */
     suggestions?: SuggestionsSource;
-    /** Composer input placeholder. Default: "Send a message..." */
+    /** Composer input placeholder. Default: "Send a message...". */
     composerPlaceholder?: string;
     /** Override individual UI slots while keeping the rest as defaults. */
     components?: ThreadComponents;
@@ -642,8 +635,9 @@ interface ThreadProps {
     artifacts?: ThreadArtifactsConfig;
     /**
      * Called when a `ui` artifact fires an `{ kind: "emit" }` action. Use this
-     * to react to slider commits, drag gestures, or other host-side logic beyond
-     * the built-in `message` action (which already appends a user message).
+     * to react to slider commits, drag gestures, or other host-side logic
+     * beyond the built-in `message` action (which already appends a user
+     * message).
      */
     onArtifactEvent?: (event: UiEventEnvelope) => void;
 }
@@ -653,10 +647,234 @@ interface TimbalChatProps extends Omit<TimbalRuntimeProviderProps, "children">,
 }
 declare function TimbalChat({ workforceId, baseUrl, fetch, attachments, attachmentsUploadUrl, attachmentsAccept, debug, ...threadProps }: TimbalChatProps): react_jsx_runtime.JSX.Element;
 
+interface TimbalChatShellProps extends Omit<TimbalChatProps, "workforceId"> {
+    /**
+     * Pre-selected workforce id. When omitted, the shell fetches the workforce
+     * list from `{baseUrl}/workforce` and picks the first agent automatically.
+     */
+    workforceId?: string;
+    /** Branding rendered at the start of the header (logo, etc). */
+    brand?: ReactNode;
+    /** Extra content rendered at the end of the header (theme toggle, logout). */
+    headerActions?: ReactNode;
+    /** Hide the built-in workforce selector. Default: false. */
+    hideWorkforceSelector?: boolean;
+    /** Class for the outer flex container. */
+    className?: string;
+    /** Class for the header bar. */
+    headerClassName?: string;
+}
+/**
+ * Drop-in shell that wraps `TimbalChat` with the Studio playground chrome:
+ * floating topbar with brand + workforce selector + actions, soft gradient
+ * background, and the chat thread filling the remaining vertical space.
+ *
+ * Falls back to picking the first available workforce when `workforceId`
+ * isn't supplied.
+ */
+declare const TimbalChatShell: FC<TimbalChatShellProps>;
+
+interface TimbalStudioShellProps extends Omit<TimbalChatProps, "workforceId"> {
+    /**
+     * Pin the chat to a specific workforce. When omitted, the shell fetches
+     * the workforce list via `useWorkforces()` and lets the sidebar drive
+     * selection.
+     */
+    workforceId?: string;
+    /**
+     * Pre-loaded workforce list. When omitted, the shell fetches it.
+     * Useful for stories / SSR / preview environments.
+     */
+    workforces?: WorkforceItem[];
+    /** Custom fetch for the workforce list (mock fetch in preview mode). */
+    workforcesFetch?: (url: string, options?: RequestInit) => Promise<Response>;
+    /** Base URL for the workforce list. Default: `/api`. */
+    workforcesBaseUrl?: string;
+    /** Brand mark rendered in the sidebar header. Default: `<TimbalMark />`. */
+    brand?: ReactNode;
+    /** Extra actions rendered at the right of the floating top bar. */
+    headerActions?: ReactNode;
+    /** Nodes rendered at the left of the floating top bar (after the menu button). */
+    headerStart?: ReactNode;
+    /** Initial collapse state when no persisted value exists. Default: false. */
+    defaultCollapsed?: boolean;
+    /** localStorage key for persisting the collapse state. Default set. */
+    persistKey?: string | null;
+    /** Pixel breakpoint below which the sidebar becomes a drawer. Default 768. */
+    mobileBreakpointPx?: number;
+    /** Caption shown in the sidebar footer when no user is signed in. */
+    sidebarEmptyCaption?: string | null;
+}
+/**
+ * Opinionated Timbal studio layout — floating sidebar with workforce picker,
+ * top bar with optional mode toggle / actions, and a `<TimbalChat />` filling
+ * the rest. Manages collapse state, mobile drawer, and workforce selection
+ * out of the box. For more control compose `StudioSidebar` + `TimbalChat`
+ * directly.
+ */
+declare const TimbalStudioShell: FC<TimbalStudioShellProps>;
+
 declare const MarkdownText: React.MemoExoticComponent<() => react_jsx_runtime.JSX.Element>;
 
+interface ToolStatus {
+    type: string;
+    reason?: string;
+}
+declare function useToolRunning(props: {
+    status?: ToolStatus;
+    result?: unknown;
+}): boolean;
 declare const ToolFallback: ToolCallMessagePartComponent;
 
+interface WorkforceSelectorProps {
+    /** List of workforces to choose from. */
+    workforces: WorkforceItem[];
+    /** Currently selected workforce id. */
+    value: string;
+    /** Called when the user picks a different workforce. */
+    onChange: (id: string) => void;
+    /** Hide the selector when there's only one option. Default: true. */
+    hideWhenSingle?: boolean;
+    className?: string;
+    placeholder?: string;
+}
+/**
+ * Minimal headless workforce picker. Wraps a styled native `<select>` so
+ * the SDK doesn't need to depend on `@radix-ui/react-select`, while still
+ * matching the Studio chrome (gradient pill, soft border, chevron).
+ *
+ * Apps that want a richer UI (search, descriptions, agent icons) can build
+ * their own using `useWorkforces()`.
+ */
+declare const WorkforceSelector: FC<WorkforceSelectorProps>;
+
+interface StudioSidebarProps {
+    /**
+     * Workforces to display. When omitted, the sidebar fetches them via the
+     * shared `useWorkforces()` hook.
+     */
+    workforces?: WorkforceItem[];
+    selectedId?: string;
+    onSelect?: (id: string) => void;
+    /** Initial collapse state when no persisted value exists. Default: false. */
+    defaultCollapsed?: boolean;
+    /**
+     * localStorage key for persisting the collapse state. Pass `null` to
+     * disable persistence. Default: `"timbal-studio-sidebar-collapsed"`.
+     */
+    persistKey?: string | null;
+    /**
+     * Pixel breakpoint below which the sidebar becomes a drawer.
+     * Default: 768.
+     */
+    mobileBreakpointPx?: number;
+    /** Brand element rendered in the sidebar header. Default: `<TimbalMark />`. */
+    brand?: ReactNode;
+    /** Caption shown in the footer when no user is signed in. */
+    emptyCaption?: string | null;
+    /** External control over the mobile drawer (used by `TimbalStudioShell`). */
+    mobileOpen?: boolean;
+    onMobileOpenChange?: (open: boolean) => void;
+}
+/**
+ * Floating, collapsible workforce sidebar. Manages its own collapse state
+ * (persisted to localStorage by default) and mobile drawer behaviour. For
+ * a fully composed shell with the chat already wired use
+ * `TimbalStudioShell`.
+ */
+declare const StudioSidebar: FC<StudioSidebarProps>;
+
+interface TimbalMarkProps {
+    className?: string;
+    /** Square size in CSS pixels (matches `--studio-chrome-pill-height` at 40). */
+    size?: number;
+    /**
+     * Override the symbol shown inside the shader. Defaults to the embedded
+     * Timbal mark — pass any image URL or data URI to brand the chat with
+     * your own logo while keeping the liquid-metal motion.
+     */
+    src?: string;
+}
+/**
+ * Timbal mark rendered with the Paper Design LiquidMetal shader.
+ *
+ * The Timbal symbol is embedded as a data URI so the library works without
+ * the consumer having to host the asset. Pass `src` to use a custom logo.
+ */
+declare function TimbalMark({ className, size, src, }: TimbalMarkProps): react_jsx_runtime.JSX.Element;
+
+type ModeToggleTheme = "light" | "dark" | "system";
+interface ModeToggleProps {
+    /**
+     * Current theme. When omitted, the toggle reads from / writes to the
+     * `.dark` class on `<html>` directly — useful for apps that don't have
+     * a theme manager yet.
+     */
+    theme?: ModeToggleTheme | string;
+    /** Called when the user clicks the toggle. */
+    setTheme?: (theme: ModeToggleTheme) => void;
+    className?: string;
+    /** ARIA label / tooltip. Default: "Toggle theme". */
+    label?: string;
+}
+/**
+ * Sun/moon theme toggle styled to sit in the studio top bar.
+ *
+ * Two integration modes:
+ *
+ * 1. Pass `theme` + `setTheme` (e.g. from `next-themes`'s `useTheme`).
+ *    The component is then fully controlled.
+ * 2. Omit both. The toggle reads the current state from `.dark` on
+ *    `<html>` and flips it on click. Good enough for prototypes and
+ *    cases where there is no theme manager.
+ */
+declare const ModeToggle: FC<ModeToggleProps>;
+
+interface StudioWelcomeProps extends ThreadWelcomeProps {
+    /** Override the brand mark rendered above the heading. */
+    icon?: ReactNode;
+}
+/**
+ * Welcome screen with the staggered Timbal mark + heading + subheading.
+ * Drop in as the `components.Welcome` slot of `<Thread />` /
+ * `<TimbalChat />` to replace the default sparkle illustration.
+ */
+declare const StudioWelcome: FC<StudioWelcomeProps>;
+
+type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;
+interface UseWorkforcesOptions {
+    /** Base URL for API calls. Default: `/api`. */
+    baseUrl?: string;
+    /** Custom fetch (defaults to `authFetch` for token-auth flows). */
+    fetch?: FetchFn;
+    /**
+     * Pick the initial selected workforce. By default we prefer the first
+     * `type === "agent"` entry, falling back to the first item. Pass a custom
+     * resolver to override (e.g. remember the user's last choice).
+     */
+    pickInitial?: (items: WorkforceItem[]) => WorkforceItem | undefined;
+    /** When false, the hook returns an empty list and skips the network fetch. */
+    enabled?: boolean;
+}
+interface UseWorkforcesResult {
+    workforces: WorkforceItem[];
+    /** Currently selected workforce identifier (id ?? uid ?? name). */
+    selectedId: string;
+    setSelectedId: (id: string) => void;
+    /** The full `WorkforceItem` for `selectedId`, if any. */
+    selected: WorkforceItem | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    /** Re-fetch the list. Resets `error`. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch the list of workforces exposed by the blueprint API and track a
+ * selection. Used to power `<WorkforceSelector />` but exported separately
+ * so apps can drive their own UI (e.g. a sidebar tree).
+ */
+declare function useWorkforces(options?: UseWorkforcesOptions): UseWorkforcesResult;
+
 /**
  * Copy-paste this into a workforce agent system prompt (or append it to your
  * blueprint's tool-result instructions) so the model knows which artifact
@@ -737,13 +955,12 @@ type MarkdownSegment = {
 declare function splitMarkdownByArtifacts(markdown: string): MarkdownSegment[];
 
 /**
- * Drop-in replacement for `ToolFallback` that first tries to render the tool
- * result as an artifact via the registry. Falls back to the standard tool
- * panel when the result isn't artifact-shaped (or while the tool is still
- * running).
+ * Default `tools.Override` for assistant messages.
  *
- * Use this as the `tools.Fallback` in `MessagePrimitive.Parts` to enable
- * artifact rendering for any tool the agent calls.
+ * Renders the tool result as a registered artifact when possible; otherwise
+ * falls back to the timeline `ToolFallback`. Wraps the artifact in
+ * `ToolMotion` so it shares the same rise-from-below polish as the rest of
+ * the chat surface.
  */
 declare const ToolArtifactFallback: ToolCallMessagePartComponent;
 
@@ -773,10 +990,10 @@ declare const ChartArtifactView: FC<{
 }>;
 
 /**
- * Inline choice widget. Single-select submits immediately on click;
- * multi-select shows a confirm button. The answer is sent as a regular user
- * message via the assistant-ui runtime, so the agent treats it like any
- * other reply.
+ * In-thread choice widget. Single-select submits immediately on click;
+ * multi-select shows a confirm button. The answer is sent as a regular
+ * user message via the assistant-ui runtime so the agent treats it like
+ * any other reply.
  */
 declare const QuestionArtifactView: FC<{
     artifact: QuestionArtifact;
@@ -804,103 +1021,6 @@ declare const TableArtifactView: FC<{
     artifact: TableArtifact;
 }>;
 
-declare const UserMessageAttachments: FC;
-declare const ComposerAttachments: FC;
-declare const ComposerAddAttachment: FC;
-
-declare const buttonVariants: (props?: ({
-    variant?: "default" | "outline" | "ghost" | "secondary" | "destructive" | "link" | null | undefined;
-    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
-} & class_variance_authority_types.ClassProp) | undefined) => string;
-declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
-    asChild?: boolean;
-}): react_jsx_runtime.JSX.Element;
-
-type TooltipIconButtonProps = ComponentPropsWithRef<typeof Button> & {
-    tooltip: string;
-    side?: "top" | "bottom" | "left" | "right";
-};
-declare const TooltipIconButton: React.ForwardRefExoticComponent<Omit<TooltipIconButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
-
-declare const ShikiSyntaxHighlighter: FC<SyntaxHighlighterProps>;
-
-type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;
-interface UseWorkforcesOptions {
-    /** Base URL for API calls. Default: `/api`. */
-    baseUrl?: string;
-    /** Custom fetch (defaults to `authFetch` for token-auth flows). */
-    fetch?: FetchFn;
-    /**
-     * Pick the initial selected workforce. By default we prefer the first
-     * `type === "agent"` entry, falling back to the first item. Pass a custom
-     * resolver to override (e.g. remember the user's last choice).
-     */
-    pickInitial?: (items: WorkforceItem[]) => WorkforceItem | undefined;
-}
-interface UseWorkforcesResult {
-    workforces: WorkforceItem[];
-    /** Currently selected workforce identifier (id ?? uid ?? name). */
-    selectedId: string;
-    setSelectedId: (id: string) => void;
-    /** The full `WorkforceItem` for `selectedId`, if any. */
-    selected: WorkforceItem | undefined;
-    isLoading: boolean;
-    error: Error | null;
-    /** Re-fetch the list. Resets `error`. */
-    refresh: () => Promise<void>;
-}
-/**
- * Fetch the list of workforces exposed by the blueprint API and track a
- * selection. Used to power `<WorkforceSelector />` but exported separately
- * so apps can drive their own UI (e.g. a sidebar tree).
- */
-declare function useWorkforces(options?: UseWorkforcesOptions): UseWorkforcesResult;
-
-interface WorkforceSelectorProps {
-    /** List of workforces to choose from. */
-    workforces: WorkforceItem[];
-    /** Currently selected workforce id. */
-    value: string;
-    /** Called when the user picks a different workforce. */
-    onChange: (id: string) => void;
-    /** Hide the selector when there's only one option. Default: true. */
-    hideWhenSingle?: boolean;
-    className?: string;
-    placeholder?: string;
-}
-/**
- * Minimal headless workforce picker — wraps a styled native `<select>` so
- * `timbal-react` doesn't need a Radix dropdown dependency. Apps that want a
- * richer UI (search, descriptions) can build their own using
- * `useWorkforces()`.
- */
-declare const WorkforceSelector: FC<WorkforceSelectorProps>;
-
-interface TimbalChatShellProps extends Omit<TimbalChatProps, "workforceId"> {
-    /**
-     * Pre-selected workforce id. When omitted, the shell fetches the workforce
-     * list from `{baseUrl}/workforce` and picks the first agent automatically.
-     */
-    workforceId?: string;
-    /** Branding rendered at the start of the header (logo, etc). */
-    brand?: ReactNode;
-    /** Extra content rendered at the end of the header (theme toggle, logout). */
-    headerActions?: ReactNode;
-    /** Hide the built-in workforce selector. Default: false. */
-    hideWorkforceSelector?: boolean;
-    /** Class for the outer flex container. */
-    className?: string;
-    /** Class for the header bar. */
-    headerClassName?: string;
-}
-/**
- * Drop-in shell that combines the most common blueprint patterns: a header
- * with brand + workforce selector + actions, plus the chat thread occupying
- * the remaining vertical space. Falls back to `<TimbalChat>` directly when
- * `workforceId` is provided.
- */
-declare const TimbalChatShell: FC<TimbalChatShellProps>;
-
 interface SessionContextType {
     user: Session | null;
     loading: boolean;
@@ -909,6 +1029,12 @@ interface SessionContextType {
     logout: () => void;
 }
 declare const useSession: () => SessionContextType;
+/**
+ * Read the session without throwing when no `SessionProvider` is present.
+ * Returns `null` when auth is not wired into the tree — useful for surfaces
+ * (e.g. sidebar footers) that should gracefully render without auth.
+ */
+declare const useOptionalSession: () => SessionContextType | null;
 interface SessionProviderProps {
     children: React__default.ReactNode;
     /** When false, session is always null and loading is false. Default: true */
@@ -933,6 +1059,14 @@ declare const refreshAccessToken: () => Promise<boolean>;
 declare const authFetch: (url: string, options?: RequestInit) => Promise<Response>;
 declare const fetchCurrentUser: () => Promise<Session | null>;
 
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "outline" | "ghost" | "secondary" | "destructive" | "link" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
 declare function TooltipProvider({ delayDuration, ...props }: React.ComponentProps<typeof Tooltip$1.Provider>): react_jsx_runtime.JSX.Element;
 declare function Tooltip({ ...props }: React.ComponentProps<typeof Tooltip$1.Root>): react_jsx_runtime.JSX.Element;
 declare function TooltipTrigger({ ...props }: React.ComponentProps<typeof Tooltip$1.Trigger>): react_jsx_runtime.JSX.Element;
@@ -963,6 +1097,47 @@ interface TextShimmerProps {
 }
 declare const Shimmer: React.MemoExoticComponent<({ children, as: Component, className, duration, spread, }: TextShimmerProps) => react_jsx_runtime.JSX.Element>;
 
+/**
+ * Timbal V2 button design tokens.
+ *
+ * Mirrors the `timbal-platform` design language (`TimbalV2Button`) so chat
+ * surfaces built with the SDK feel identical to the Timbal Studio. Each record
+ * is keyed by variant or size and ships only Tailwind utility classes — no
+ * runtime JS — so consumers can compose them with `cn(...)` and add their own
+ * overrides without ejecting.
+ *
+ * Every colour is resolved through semantic CSS variables defined in
+ * `styles.css`. There are NO hardcoded palette literals — light/dark mode
+ * flips by swapping the variable values, not by toggling Tailwind classes.
+ */
+type TimbalV2Variant = "primary" | "secondary" | "ghost" | "informative" | "destructive" | "link";
+type TimbalV2Size = "xs" | "sm" | "md" | "lg";
+
+interface TimbalV2ButtonProps extends React.ComponentProps<"button"> {
+    variant?: TimbalV2Variant;
+    size?: TimbalV2Size;
+    isIconOnly?: boolean;
+    isLoading?: boolean;
+    fullWidth?: boolean;
+    /** When true, renders children as the underlying element (Radix Slot pattern). */
+    asChild?: boolean;
+}
+
+interface TooltipIconButtonProps extends Omit<TimbalV2ButtonProps, "isIconOnly"> {
+    /** Visible tooltip + accessible label. Always required. */
+    tooltip: string;
+    /** Tooltip placement. Default: "bottom". */
+    side?: "top" | "bottom" | "left" | "right";
+}
+/**
+ * Icon-only Timbal pill button with a tooltip. Used by every chat-surface
+ * toolbar (composer send/cancel, message action bar, scroll-to-bottom).
+ *
+ * Defaults to a soft `secondary` variant so it sits cleanly inside composers,
+ * message bubbles, and the action bar. Override via `variant`.
+ */
+declare const TooltipIconButton: React.ForwardRefExoticComponent<Omit<TooltipIconButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+
 declare function cn(...inputs: ClassValue[]): string;
 
-export { ARTIFACT_AGENT_INSTRUCTIONS, ARTIFACT_FENCE_LANGUAGES, type AnyArtifact, ArtifactCard, type ArtifactRegistry, ArtifactRegistryProvider, type ArtifactRenderer, type ArtifactRendererProps, ArtifactView, AuthGuard, Avatar, AvatarFallback, AvatarImage, Button, type ChartArtifact, ChartArtifactView, type ChatAttachment, type ChatMessage, Composer, ComposerAddAttachment, ComposerAttachments, type ComposerProps, type ContentPart, type CreateDefaultAttachmentAdapterOptions, type CreateUploadAttachmentAdapterOptions, DEFAULT_UPLOAD_ACCEPT, Dialog, DialogClose, DialogContent, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, type HtmlArtifact, HtmlArtifactView, type JsonArtifact, JsonArtifactView, type MarkdownArtifactMatch, type MarkdownSegment, MarkdownText, type QuestionArtifact, QuestionArtifactView, type QuestionOption, type ResolveAttachmentAdapterOptions, type SendOptions, SessionProvider, Shimmer, Suggestions, type SuggestionsComponent, type SuggestionsSlotProps, type SuggestionsSource, ShikiSyntaxHighlighter as SyntaxHighlighter, type TableArtifact, TableArtifactView, type TextContentPart, type TextShimmerProps, type ThinkingContentPart, Thread, type ThreadArtifactsConfig, type ThreadComponents, type ThreadProps, type ThreadSuggestion, type ThreadSuggestionsProps, type ThreadWelcomeConfig, type ThreadWelcomeProps, type TimbalArtifact, type TimbalAttachmentsConfig, type TimbalAttachmentsProp, TimbalChat, type TimbalChatProps, TimbalChatShell, type TimbalChatShellProps, TimbalRuntimeProvider, type TimbalRuntimeProviderProps, type TimbalStreamApi, ToolArtifactFallback, type ToolCallContentPart, ToolFallback, Tooltip, TooltipContent, TooltipIconButton, type TooltipIconButtonProps, TooltipProvider, TooltipTrigger, type UiAction, type UiArtifact, UiArtifactView, UiCustomNodeRegistryProvider, type UiEventEnvelope, UiEventProvider, type UiNode, UiNodeView, type UploadFetchFn, type UseTimbalStreamOptions, type UseWorkforcesOptions, type UseWorkforcesResult, UserMessageAttachments, WorkforceSelector, type WorkforceSelectorProps, authFetch, buttonVariants, clearTokens, cn, createDefaultAttachmentAdapter, createUploadAttachmentAdapter, defaultArtifactRenderers, fetchCurrentUser, findMarkdownArtifacts, getAccessToken, getPath, getRefreshToken, isArtifact, isArtifactFenceLanguage, isUiBinding, parseArtifactFromToolResult, refreshAccessToken, resolveAttachmentAdapter, resolveBindable, setAccessToken, setPath, setRefreshToken, splitMarkdownByArtifacts, useArtifactRegistry, useResolvedSuggestions, useSession, useTimbalRuntime, useTimbalStream, useUiCustomNodeRegistry, useUiDispatch, useUiEventEmitter, useUiState, useWorkforces };
+export { ARTIFACT_AGENT_INSTRUCTIONS, ARTIFACT_FENCE_LANGUAGES, type AnyArtifact, ArtifactCard, type ArtifactRegistry, ArtifactRegistryProvider, type ArtifactRenderer, type ArtifactRendererProps, ArtifactView, AuthGuard, Avatar, AvatarFallback, AvatarImage, Button, type ChartArtifact, ChartArtifactView, type ChatAttachment, type ChatMessage, Composer, type ComposerProps, type ContentPart, type CreateDefaultAttachmentAdapterOptions, type CreateUploadAttachmentAdapterOptions, DEFAULT_UPLOAD_ACCEPT, Dialog, DialogClose, DialogContent, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, type HtmlArtifact, HtmlArtifactView, type JsonArtifact, JsonArtifactView, type MarkdownArtifactMatch, type MarkdownSegment, MarkdownText, ModeToggle, type ModeToggleProps, type ModeToggleTheme, type QuestionArtifact, QuestionArtifactView, type QuestionOption, type ResolveAttachmentAdapterOptions, type SendOptions, SessionProvider, Shimmer, StudioSidebar, type StudioSidebarProps, StudioWelcome, type StudioWelcomeProps, Suggestions, type SuggestionsComponent, type SuggestionsSlotProps, type SuggestionsSource, type TableArtifact, TableArtifactView, type TextContentPart, type TextShimmerProps, type ThinkingContentPart, Thread, type ThreadArtifactsConfig, type ThreadComponents, type ThreadProps, type ThreadSuggestion, type ThreadSuggestionsProps, type ThreadWelcomeConfig, type ThreadWelcomeProps, type TimbalArtifact, type TimbalAttachmentsConfig, type TimbalAttachmentsProp, TimbalChat, type TimbalChatProps, TimbalChatShell, type TimbalChatShellProps, TimbalMark, type TimbalMarkProps, TimbalRuntimeProvider, type TimbalRuntimeProviderProps, type TimbalStreamApi, TimbalStudioShell, type TimbalStudioShellProps, ToolArtifactFallback, type ToolCallContentPart, ToolFallback, Tooltip, TooltipContent, TooltipIconButton, type TooltipIconButtonProps, TooltipProvider, TooltipTrigger, type UiAction, type UiArtifact, UiArtifactView, UiCustomNodeRegistryProvider, type UiEventEnvelope, UiEventProvider, type UiNode, UiNodeView, type UploadFetchFn, type UseTimbalStreamOptions, type UseWorkforcesOptions, type UseWorkforcesResult, WorkforceSelector, type WorkforceSelectorProps, authFetch, clearTokens, cn, createDefaultAttachmentAdapter, createUploadAttachmentAdapter, defaultArtifactRenderers, fetchCurrentUser, findMarkdownArtifacts, getAccessToken, getPath, getRefreshToken, isArtifact, isArtifactFenceLanguage, isUiBinding, parseArtifactFromToolResult, refreshAccessToken, resolveAttachmentAdapter, resolveBindable, setAccessToken, setPath, setRefreshToken, splitMarkdownByArtifacts, useArtifactRegistry, useOptionalSession, useResolvedSuggestions, useSession, useTimbalRuntime, useTimbalStream, useToolRunning, useUiCustomNodeRegistry, useUiDispatch, useUiEventEmitter, useUiState, useWorkforces };