@timbal-ai/timbal-react 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { ReactNode, FC, ComponentType, Dispatch, CSSProperties, ElementType } from 'react';
+import React__default, { ReactNode, FC, ComponentType, Dispatch, ElementType } from 'react';
 import { AttachmentAdapter, ToolCallMessagePartComponent } from '@assistant-ui/react';
-export { ActionBarMorePrimitive, ActionBarPrimitive, AssistantRuntimeProvider, AttachmentAdapter, AuiIf, ComposerPrimitive, ErrorPrimitive, MessagePartPrimitive, MessagePrimitive, ThreadPrimitive, ToolCallMessagePartComponent, useAuiState, 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 { SyntaxHighlighterProps } from '@assistant-ui/react-markdown';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import { Tooltip as Tooltip$1, Avatar as Avatar$1, Dialog as Dialog$1 } from 'radix-ui';
@@ -648,6 +647,73 @@ 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 {
@@ -660,53 +726,154 @@ declare function useToolRunning(props: {
 }): 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;
+}
 /**
- * Tool-row presence motion shared across the chat surface.
+ * 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).
  *
- * Mirrors `timbal-platform` `StudioToolMotion.js` — a soft "luxury" ease in
- * with optional blur, fast exit, and a grid-row collapsible body. Exit
- * durations stay short so the layout doesn't feel sticky when tools resolve
- * quickly.
+ * Apps that want a richer UI (search, descriptions, agent icons) can build
+ * their own using `useWorkforces()`.
  */
-declare const luxuryEase: readonly [0.16, 1, 0.3, 1];
-declare function toolPresenceTransition(reduced: boolean): {
-    enter: {
-        duration: number;
-        ease: readonly [0.16, 1, 0.3, 1];
-    };
-    exit: {
-        duration: number;
-        ease: readonly [0.4, 0, 1, 1];
-    };
-};
-type ToolMotionVariant = "executing" | "settled";
-interface ToolMotionProps {
-    children: ReactNode;
-    className?: string;
-    /** Stable key for AnimatePresence swaps (e.g. `running` → `complete`). */
-    motionKey: string;
+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;
 }
-/** Single-shot rise-from-below for tool / artifact rows. */
-declare function ToolMotion({ children, className, motionKey }: ToolMotionProps): react_jsx_runtime.JSX.Element;
-interface ToolPresenceProps {
-    presenceKey: string;
-    children: ReactNode;
+/**
+ * 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;
-    /** Executing rows skip blur so the shimmer stays readable. */
-    variant?: ToolMotionVariant;
+    /** 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;
 }
-/** Wraps running ↔ complete (or other) tool states with a short crossfade. */
-declare function ToolPresence({ presenceKey, children, className, variant, }: ToolPresenceProps): react_jsx_runtime.JSX.Element;
-interface ToolBodyPresenceProps {
-    open: boolean;
-    children: ReactNode;
+/**
+ * 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>;
 }
 /**
- * Expanded tool trace — CSS grid row collapse for smooth contract + opacity.
- * Avoids `AnimatePresence` exit lag when the body closes.
+ * 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 ToolBodyPresence({ open, children, className, }: ToolBodyPresenceProps): react_jsx_runtime.JSX.Element;
+declare function useWorkforces(options?: UseWorkforcesOptions): UseWorkforcesResult;
 
 /**
  * Copy-paste this into a workforce agent system prompt (or append it to your
@@ -854,152 +1021,6 @@ declare const TableArtifactView: FC<{
     artifact: TableArtifact;
 }>;
 
-declare const UserMessageAttachments: FC;
-declare const ComposerAttachments: FC;
-declare const ComposerAddAttachment: FC;
-
-/**
- * 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.
- */
-type TimbalV2Variant = "primary" | "secondary" | "ghost" | "informative" | "destructive" | "link";
-type TimbalV2Size = "xs" | "sm" | "md" | "lg";
-declare const TIMBAL_V2_SIZE_HEIGHT: Record<TimbalV2Size, string>;
-declare const TIMBAL_V2_SIZE_ICON: Record<TimbalV2Size, string>;
-declare const TIMBAL_V2_SIZE_LABEL_PX: Record<TimbalV2Size, string>;
-/**
- * Absolute gradient fill layer — scoped to the `group/tbv2` group so the
- * hover/active states can be triggered without wrapping each button in
- * dedicated state classes.
- */
-declare const TIMBAL_V2_FILL: Record<TimbalV2Variant, string>;
-declare const TIMBAL_V2_LABEL: Record<TimbalV2Variant, string>;
-declare const TIMBAL_V2_BORDER: Record<TimbalV2Variant, string>;
-declare const TIMBAL_V2_SHADOW: Record<TimbalV2Variant, string>;
-/** Static pill surface — sidebars, badges, anywhere a button shape is needed without interaction. */
-declare const TIMBAL_V2_PILL_SURFACE = "bg-gradient-to-b from-white to-neutral-50/70 border border-neutral-200/80 shadow-[0_1px_2px_-0.5px_rgba(0,0,0,0.05)] dark:from-white/[0.05] dark:to-white/[0.025] dark:border-white/[0.08] dark:shadow-[0_1px_3px_rgba(0,0,0,0.22)]";
-/** Interactive secondary chrome for native controls beside v2 buttons (selects, search inputs). */
-declare const TIMBAL_V2_SECONDARY_CHROME = "bg-gradient-to-b from-white to-neutral-50/70 border border-neutral-200/80 shadow-[0_1px_2px_-0.5px_rgba(0,0,0,0.05)] transition-[background-color,box-shadow,border-color] duration-200 ease-in-out hover:from-neutral-50/40 hover:to-neutral-100/60 active:from-neutral-100/65 active:to-neutral-200/65 dark:from-white/[0.05] dark:to-white/[0.025] dark:border-white/[0.08] dark:shadow-[0_1px_3px_rgba(0,0,0,0.22)] dark:hover:from-white/[0.07] dark:hover:to-white/[0.045] dark:active:from-white/[0.10] dark:active:to-white/[0.07]";
-
-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;
-}
-/**
- * Canonical Timbal pill button — layered absolute-fill span + relative label
- * row scoped to `group/tbv2`. Mirrors `timbal-platform` `TimbalV2Button` so
- * chat UIs built with the SDK feel identical to the Studio.
- */
-declare const TimbalV2Button: React.ForwardRefExoticComponent<Omit<TimbalV2ButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
-
-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 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
- * 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 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 SessionContextType {
     user: Session | null;
     loading: boolean;
@@ -1008,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 */
@@ -1032,65 +1059,6 @@ declare const refreshAccessToken: () => Promise<boolean>;
 declare const authFetch: (url: string, options?: RequestInit) => Promise<Response>;
 declare const fetchCurrentUser: () => Promise<Session | null>;
 
-/**
- * Shared chrome class names + CSS variables for Timbal chat surfaces.
- *
- * These mirror `timbal-platform` `studioChrome.js` so the SDK ships the same
- * design language out of the box. Class consts are pure strings (no runtime
- * cost) and can be composed with `cn(...)` from `../utils`.
- */
-
-declare const STUDIO_TOPBAR_GAP = "0.5rem";
-declare const STUDIO_TOPBAR_HEIGHT = "3rem";
-declare const STUDIO_PILL_HEIGHT = "2.5rem";
-declare const STUDIO_SIDEBAR_GAP = "0.5rem";
-declare const STUDIO_SIDEBAR_WIDTH = "3rem";
-declare const STUDIO_INSET_LEFT = "calc(0.5rem + 3rem)";
-/**
- * Style object to spread on the chat shell root. Exposes the CSS variables
- * referenced by topbar/sidebar helper classes so layouts stay self-contained.
- */
-declare const studioChromeShellStyle: CSSProperties;
-declare const studioTopbarPillHeightClass = "h-[var(--studio-chrome-pill-height)] min-h-[var(--studio-chrome-pill-height)]";
-declare const studioTopbarIconPillClass = "shrink-0 flex-none size-[var(--studio-chrome-pill-height)] min-h-[var(--studio-chrome-pill-height)] min-w-[var(--studio-chrome-pill-height)]";
-/** Soft playground gradient behind the message column. */
-declare const studioPlaygroundGradientClass = "bg-gradient-to-b from-neutral-200/60 via-neutral-100/30 to-background dark:from-zinc-800 dark:via-zinc-900 dark:to-zinc-950";
-/** Composer outer shell — rounded surface with focus-within affordances. */
-declare const studioComposeInputShellClass = "flex w-full flex-col rounded-2xl border border-neutral-200/60 bg-background shadow-lg shadow-black/5 outline-none transition-[box-shadow,border-color] focus-within:border-neutral-400/80 focus-within:ring-2 focus-within:ring-foreground/5 focus-within:shadow-xl focus-within:shadow-black/10 dark:border-white/12 dark:bg-zinc-900 dark:shadow-black/20 dark:focus-within:border-white/22 dark:focus-within:ring-0";
-/** Resting pill surface — sidebars, badges. */
-declare const studioPillSurfaceClass = "bg-gradient-to-b from-white to-neutral-50/70 border border-neutral-200/80 shadow-[0_1px_2px_-0.5px_rgba(0,0,0,0.05)] dark:from-white/[0.05] dark:to-white/[0.025] dark:border-white/[0.08] dark:shadow-[0_1px_3px_rgba(0,0,0,0.22)]";
-/** Interactive secondary chrome — select triggers, search shells. */
-declare const studioSecondaryChromeClass = "bg-gradient-to-b from-white to-neutral-50/70 border border-neutral-200/80 shadow-[0_1px_2px_-0.5px_rgba(0,0,0,0.05)] transition-[background-color,box-shadow,border-color] duration-200 ease-in-out hover:from-neutral-50/40 hover:to-neutral-100/60 active:from-neutral-100/65 active:to-neutral-200/65 dark:from-white/[0.05] dark:to-white/[0.025] dark:border-white/[0.08] dark:shadow-[0_1px_3px_rgba(0,0,0,0.22)] dark:hover:from-white/[0.07] dark:hover:to-white/[0.045] dark:active:from-white/[0.10] dark:active:to-white/[0.07]";
-/**
- * Solid integration-card surface — used for in-thread tool / artifact cards
- * so they read on the playground gradient.
- */
-declare const studioIntegrationSurfaceSolid = "bg-white bg-gradient-to-b from-white to-neutral-50/70 shadow-[0_1px_2px_-0.5px_rgba(0,0,0,0.05)] dark:bg-zinc-900 dark:from-white/[0.05] dark:to-white/[0.025] dark:shadow-[0_1px_3px_rgba(0,0,0,0.22)]";
-declare const studioIntegrationBorder = "border border-neutral-200/80 dark:border-white/[0.08]";
-declare const studioIntegrationCardClass: string;
-declare const studioIntegrationIconTileClass: string;
-/**
- * Full-width selectable row — used by `Suggestions` and any settings-style
- * list cards. Mirrors `roleListRowSurfaceClass` in timbal-platform.
- */
-declare const studioListRowButtonClass: string;
-/** Compose tool drawer / trace payload well — opaque so JSON reads on the gradient. */
-declare const studioComposerIoWellClass: string;
-/** Collapsible tool-call card shell. */
-declare const studioToolCardShellClass: string;
-declare const studioTimelineRowButtonClass = "group flex w-full min-w-0 cursor-pointer items-center justify-start rounded-md border-0 bg-transparent py-1 text-left shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-foreground/15 focus-visible:ring-offset-2";
-declare const studioTimelineTextClass = "text-xs font-normal leading-snug";
-declare const studioTimelineActionClass: string;
-/** Shimmer action word — text-transparent inherits its colour from the bg clip. */
-declare const studioTimelineShimmerActionClass: string;
-declare const studioTimelineDetailClass: string;
-declare function studioTimelineChevronClass(expanded: boolean): string;
-/** Padding for the expanded payload under a timeline toggle. */
-declare const studioTimelineBodyPadClass = "flex flex-col gap-2 pt-0.5 pb-0.5";
-declare const studioArtifactShellClass: string;
-declare const studioQuestionOptionClass = "flex w-full items-center gap-2 rounded-lg border border-transparent px-2 py-1.5 text-left text-sm transition-[background-color,border-color,box-shadow] duration-200 hover:bg-neutral-100/80 dark:hover:bg-white/[0.05] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-foreground/15 focus-visible:ring-offset-2";
-declare const studioQuestionOptionSelectedClass: string;
-
 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;
@@ -1129,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, STUDIO_INSET_LEFT, STUDIO_PILL_HEIGHT, STUDIO_SIDEBAR_GAP, STUDIO_SIDEBAR_WIDTH, STUDIO_TOPBAR_GAP, STUDIO_TOPBAR_HEIGHT, type SendOptions, SessionProvider, Shimmer, Suggestions, type SuggestionsComponent, type SuggestionsSlotProps, type SuggestionsSource, ShikiSyntaxHighlighter as SyntaxHighlighter, TIMBAL_V2_BORDER, TIMBAL_V2_FILL, TIMBAL_V2_LABEL, TIMBAL_V2_PILL_SURFACE, TIMBAL_V2_SECONDARY_CHROME, TIMBAL_V2_SHADOW, TIMBAL_V2_SIZE_HEIGHT, TIMBAL_V2_SIZE_ICON, TIMBAL_V2_SIZE_LABEL_PX, 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, TimbalV2Button, type TimbalV2ButtonProps, type TimbalV2Size, type TimbalV2Variant, ToolArtifactFallback, ToolBodyPresence, type ToolCallContentPart, ToolFallback, ToolMotion, type ToolMotionVariant, ToolPresence, 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, luxuryEase, parseArtifactFromToolResult, refreshAccessToken, resolveAttachmentAdapter, resolveBindable, setAccessToken, setPath, setRefreshToken, splitMarkdownByArtifacts, studioArtifactShellClass, studioChromeShellStyle, studioComposeInputShellClass, studioComposerIoWellClass, studioIntegrationBorder, studioIntegrationCardClass, studioIntegrationIconTileClass, studioIntegrationSurfaceSolid, studioListRowButtonClass, studioPillSurfaceClass, studioPlaygroundGradientClass, studioQuestionOptionClass, studioQuestionOptionSelectedClass, studioSecondaryChromeClass, studioTimelineActionClass, studioTimelineBodyPadClass, studioTimelineChevronClass, studioTimelineDetailClass, studioTimelineRowButtonClass, studioTimelineShimmerActionClass, studioTimelineTextClass, studioToolCardShellClass, studioTopbarIconPillClass, studioTopbarPillHeightClass, toolPresenceTransition, useArtifactRegistry, useResolvedSuggestions, useSession, useTimbalRuntime, useTimbalStream, useToolRunning, 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 };