@comma-agents/tui 2.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CloAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @comma-agents/tui
+
+Terminal interface for a running CommaAgents daemon.
+
+```bash
+bun add --global @comma-agents/tui@next
+comma-agents-tui
+```
+
+Requires Bun 1.3 or newer.

package/dist/App/App.d.ts

@@ -0,0 +1,24 @@
+import type React from "react";
+import type { TabDefinition } from "../components/Frame/Frame";
+export interface AppProps {
+    /** Whether to enable developer-specific tabs and tools. @default false */
+    readonly devMode?: boolean;
+}
+export declare function App({ devMode }: AppProps): React.ReactElement;
+export interface AppRenderProps {
+    /** The list of tabs to display in the frame. */
+    readonly tabs: readonly TabDefinition[];
+    /** The path of the currently active tab. */
+    readonly activeTabPath: string;
+    /** Callback invoked when a tab is selected. */
+    readonly onTabSelect: (path: string) => void;
+    /** Whether the command palette modal is currently open. */
+    readonly commandPaletteOpen: boolean;
+    /** Callback invoked to close the command palette. */
+    readonly onCommandPaletteClose: () => void;
+    /** Callback invoked to exit the application. */
+    readonly onExitApp: () => void;
+    /** Callback invoked to reset the chat history. */
+    readonly onResetChat: () => void;
+}
+export declare function AppRender({ tabs, activeTabPath, onTabSelect, commandPaletteOpen, onCommandPaletteClose, onExitApp, onResetChat, }: AppRenderProps): React.ReactElement;

package/dist/App/App.theme.d.ts

@@ -0,0 +1,12 @@
+import type { AppTheme } from "./App.types";
+/**
+ * Hook that returns themed style objects for the App component.
+ * Consumes global tokens via `useTheme()`.
+ *
+ * @example
+ * ```tsx
+ * const theme = useAppTheme();
+ * return <div style={theme.root}>...</div>;
+ * ```
+ */
+export declare function useAppTheme(): AppTheme;

package/dist/App/App.types.d.ts

@@ -0,0 +1,8 @@
+/** Spread-ready style objects for the App component. */
+export interface AppTheme {
+    /** Root container (column layout, full height). */
+    readonly root: {
+        readonly flexDirection: "column";
+        readonly height: "100%";
+    };
+}

package/dist/App/index.d.ts

@@ -0,0 +1,4 @@
+export type { AppProps, AppRenderProps, } from "./App";
+export { App, AppRender } from "./App";
+export { useAppTheme } from "./App.theme";
+export type { AppTheme } from "./App.types";

package/dist/Theme/DefineTheme.d.ts

@@ -0,0 +1,53 @@
+import type { Theme } from "./Theme.types";
+/**
+ * Builder function passed to `defineTheme`. Receives the global theme tokens
+ * and returns the component's spread-ready style objects.
+ *
+ * The returned object's literal shape is preserved by inference, so callers
+ * never have to hand-write a parallel `XTheme` interface — `ThemeOf<typeof
+ * useXTheme>` extracts it.
+ */
+export type ThemeBuilder<ThemeShape> = (tokens: Theme) => ThemeShape;
+/**
+ * Define a memoized component-theme hook with the result type inferred
+ * directly from the builder's return value.
+ *
+ * Per-component theme files used to declare an `XTheme` interface and a
+ * `useXTheme()` hook that returned a parallel object literal — every field
+ * was duplicated between the type and the value. `defineTheme` collapses
+ * the two: write the value once, the type is the value.
+ *
+ * Use `satisfies BoxProps` / `satisfies TextProps` on nested style objects
+ * intended to be spread into Ink `<Box>` / `<Text>`. This gives full
+ * autocomplete on Ink prop names AND keeps literal types narrow without
+ * `as const` — the literal `"column"` is checked against the union
+ * `"row" | "column" | …` so it never widens to `string`.
+ *
+ * @param builder - Pure function that maps global tokens to spread-ready style objects.
+ * @example
+ * ```ts
+ * import type { BoxProps, TextProps } from "ink";
+ *
+ * export const useChatPageTheme = defineTheme((tokens) => ({
+ *   root: { flexDirection: "column", height: "100%" } satisfies BoxProps,
+ *   header: {
+ *     paddingX: tokens.spacing.sm,
+ *     title: {
+ *       bold: tokens.typography.headerBold,
+ *       color: tokens.colors.primary,
+ *     } satisfies TextProps,
+ *   },
+ * }));
+ *
+ * // Components consume the inferred type via `ThemeOf` — no parallel
+ * // interface to maintain.
+ * export type ChatPageTheme = ThemeOf<typeof useChatPageTheme>;
+ * ```
+ */
+export declare function defineTheme<ThemeShape>(builder: ThemeBuilder<ThemeShape>): () => ThemeShape;
+/**
+ * Extract the resolved theme shape from a `useXTheme` hook produced by
+ * `defineTheme`. Lets components type their `theme` prop without a parallel
+ * interface declaration.
+ */
+export type ThemeOf<ThemeHook extends () => unknown> = ReturnType<ThemeHook>;

package/dist/Theme/Theme.d.ts

@@ -0,0 +1,11 @@
+import type { Theme } from "./Theme.types";
+/**
+ * Default theme — Material Dark (Material Design 3 palette).
+ *
+ * All colors in the registered themes use absolute hex literals (truecolor
+ * SGR) so rendering is identical across terminals regardless of the user's
+ * palette / theme preferences. Named ANSI colors ({@code "cyan"}, {@code
+ * "red"}, etc.) are re-mapped by every terminal to its current color
+ * scheme — never use them in tokens.
+ */
+export declare const defaultTheme: Theme;

package/dist/Theme/Theme.types.d.ts

@@ -0,0 +1,100 @@
+/** Color palette used throughout the TUI. */
+export interface ThemeColors {
+    /** Primary accent (headers, active elements). */
+    readonly primary: string;
+    /** Secondary accent (descriptions, hints). */
+    readonly secondary: string;
+    /** Success state. */
+    readonly success: string;
+    /** Warning state. */
+    readonly warning: string;
+    /** Error state. */
+    readonly error: string;
+    /** Muted/dim text. */
+    readonly muted: string;
+    /** App background color (the global canvas). */
+    readonly background: string;
+    /** Depth backgrounds for layering multiple widgets */
+    readonly backgroundLayerOne: string;
+    readonly backgroundLayerTwo: string;
+    readonly backgroundLayerThree: string;
+    /**
+     * Elevated surface background (input fields, modals, panels) — sits one
+     * step above {@link ThemeColors.background} so interactive areas read as
+     * distinct from the frame canvas.
+     */
+    readonly surface: string;
+    /** Cursor highlight color. */
+    readonly cursor: string;
+    /** Scrollbar thumb (active region). */
+    readonly scrollThumb: string;
+    /** Scrollbar track (inactive region). */
+    readonly scrollTrack: string;
+    /** User message color. */
+    readonly userMessage: string;
+    /** Agent message color. */
+    readonly agentMessage: string;
+    /** System message color. */
+    readonly systemMessage: string;
+    /** Input prompt color. */
+    readonly prompt: string;
+    /** Waiting-for-input state. */
+    readonly waitingInput: string;
+}
+/** Spacing values (applied to padding/margin). */
+export interface ThemeSpacing {
+    /** No spacing. */
+    readonly none: number;
+    /** Tight spacing (1). */
+    readonly xs: number;
+    /** Standard horizontal padding (1). */
+    readonly sm: number;
+    /** Medium spacing (2). */
+    readonly md: number;
+    /** Large spacing (3). */
+    readonly lg: number;
+}
+/** Typography tokens for text styling. */
+export interface ThemeTypography {
+    /** Whether headers are bold. */
+    readonly headerBold: boolean;
+    /** Whether labels are bold. */
+    readonly labelBold: boolean;
+    /** Whether dim styling is used for secondary text. */
+    readonly secondaryDim: boolean;
+}
+/** Border styling tokens. */
+export interface ThemeBorders {
+    /** Default border style for boxes. */
+    readonly style: string;
+    /** Default border color. */
+    readonly color: string;
+}
+/** Separator configuration. */
+export interface ThemeSeparator {
+    /** Character used for horizontal separators. */
+    readonly char: string;
+    /** Width of the separator (number of characters). */
+    readonly width: number;
+}
+/** Named breakpoint for terminal width thresholds (mobile-first, min-width). */
+export type BreakpointName = "xs" | "sm" | "md" | "lg" | "xl";
+/** Terminal width breakpoints in columns (mobile-first, min-width). */
+export type ThemeBreakpoints = Readonly<Record<BreakpointName, number>>;
+/**
+ * Responsive container width per breakpoint.
+ *
+ * `undefined` means full terminal width (no max constraint).
+ * A number means a fixed column width.
+ */
+export type ThemeContainerWidths = Readonly<Record<BreakpointName, number | undefined>>;
+/** Complete theme token set. */
+export interface Theme {
+    readonly colors: ThemeColors;
+    readonly spacing: ThemeSpacing;
+    readonly typography: ThemeTypography;
+    readonly borders: ThemeBorders;
+    readonly separator: ThemeSeparator;
+    readonly breakpoints: ThemeBreakpoints;
+    readonly containerWidths: ThemeContainerWidths;
+}

package/dist/Theme/index.d.ts

@@ -0,0 +1,9 @@
+export type { BoxProps, TextProps } from "ink";
+export type { ThemeBuilder, ThemeOf } from "./DefineTheme";
+export { defineTheme } from "./DefineTheme";
+export { defaultTheme } from "./Theme";
+export type { BreakpointName, Theme, ThemeBorders, ThemeBreakpoints, ThemeColors, ThemeContainerWidths, ThemeSeparator, ThemeSpacing, ThemeTypography, } from "./Theme.types";
+export type { ThemeName, ThemeRegistryEntry } from "./themes";
+export { DEFAULT_THEME_NAME, darkTheme, draculaTheme, lightTheme, resolveThemeByName, solarizedDarkTheme, THEME_REGISTRY, } from "./themes";
+export type { ThemeContextProviderProps } from "./useTheme";
+export { ThemeContextProvider, useTheme } from "./useTheme";

package/dist/Theme/themes/dark.d.ts

@@ -0,0 +1,14 @@
+import type { Theme } from "../Theme.types";
+/**
+ * Material Dark — Material Design 3 dark palette with a clear elevation-based
+ * depth system and minimal spacing.
+ *
+ * Depth layers ascend from the deepest background through progressively
+ * lighter surfaces, creating a visual hierarchy: `background` (canvas) ←
+ * `surface` (cards) ← `backgroundLayerOne` (panels) ←
+ * `backgroundLayerTwo` (inputs, modals) ← `backgroundLayerThree` (dialogs).
+ *
+ * All colors are absolute hex literals (truecolor SGR) for consistent
+ * rendering across terminals.
+ */
+export declare const darkTheme: Theme;

package/dist/Theme/themes/dracula.d.ts

@@ -0,0 +1,9 @@
+import type { Theme } from "../Theme.types";
+/**
+ * Dracula — dark palette with purple/cyan/pink accents.
+ *
+ * Background layers ascend from deepest to lightest, creating a consistent
+ * elevation gradient: `background` (canvas) ← `backgroundLayerOne` ←
+ * `backgroundLayerTwo` ← `backgroundLayerThree` ← `surface` (interactive).
+ */
+export declare const draculaTheme: Theme;

package/dist/Theme/themes/index.d.ts

@@ -0,0 +1,25 @@
+import type { Theme } from "../Theme.types";
+import { darkTheme } from "./dark";
+import { draculaTheme } from "./dracula";
+import { lightTheme } from "./light";
+import { solarizedDarkTheme } from "./solarized-dark";
+/** Stable identifier for a built-in theme. */
+export type ThemeName = "dark" | "light" | "dracula" | "solarized-dark";
+/** Display metadata for a theme registry entry. */
+export interface ThemeRegistryEntry {
+    /** Stable identifier persisted in the user config. */
+    readonly name: ThemeName;
+    /** Human-readable label shown in pickers. */
+    readonly label: string;
+    /** One-line description shown next to the label. */
+    readonly description: string;
+    /** Resolved theme tokens. */
+    readonly theme: Theme;
+}
+/** All built-in themes, keyed for the settings dropdown. */
+export declare const THEME_REGISTRY: ReadonlyMap<ThemeName, ThemeRegistryEntry>;
+/** Default theme name when none is configured. */
+export declare const DEFAULT_THEME_NAME: ThemeName;
+/** Resolve a theme by name, falling back to the default if unknown. */
+export declare function resolveThemeByName(themeName: ThemeName): Theme;
+export { darkTheme, lightTheme, draculaTheme, solarizedDarkTheme };

package/dist/Theme/themes/light.d.ts

@@ -0,0 +1,10 @@
+import type { Theme } from "../Theme.types";
+/**
+ * Light — bright background with dark text, suitable for light terminals.
+ *
+ * Background layers descend from bright canvas to progressively darker
+ * elevation steps, mimicking shadow depth in a light environment:
+ * `background` (canvas) ← `backgroundLayerOne` ← `backgroundLayerTwo` ←
+ * `backgroundLayerThree` ← `surface` (interactive).
+ */
+export declare const lightTheme: Theme;

package/dist/Theme/themes/solarized-dark.d.ts

@@ -0,0 +1,9 @@
+import type { Theme } from "../Theme.types";
+/**
+ * Solarized Dark — low-contrast balanced palette popular for terminals.
+ *
+ * Background layers ascend from deepest to lightest, creating a consistent
+ * elevation gradient: `background` (canvas) ← `backgroundLayerOne` ←
+ * `backgroundLayerTwo` ← `backgroundLayerThree` ← `surface` (interactive).
+ */
+export declare const solarizedDarkTheme: Theme;

package/dist/Theme/useTheme/index.d.ts

@@ -0,0 +1,3 @@
+export { useTheme } from "./useTheme";
+export { ThemeContextProvider } from "./useTheme.context";
+export type { ThemeContextProviderProps } from "./useTheme.types";

package/dist/Theme/useTheme/useTheme.context.d.ts

@@ -0,0 +1,31 @@
+import type { Theme } from "../Theme.types";
+import type { ThemeContextProviderProps } from "./useTheme.types";
+/**
+ * Default context value is `defaultTheme` so components rendered outside a
+ * live `<ThemeContextProvider>` — most importantly inside the detached tree
+ * Ink builds for `measureLayout` calls — still resolve a usable theme.
+ *
+ * Provider-aware consumers (the running app) override this via
+ * `<ThemeContextProvider>` higher up.
+ */
+export declare const ThemeContext: import("react").Context<Theme>;
+/**
+ * Provides design tokens to descendant components and theme hooks.
+ *
+ * When `theme` is supplied, it wins. Otherwise the active theme is read
+ * from `useUserConfig` so the dropdown in the command palette settings
+ * page can switch themes globally without prop drilling. Must therefore
+ * be mounted *inside* a `<UserConfigContextProvider>` when no explicit
+ * `theme` is passed.
+ *
+ * @param props - Theme provider configuration including optional theme override.
+ * @example
+ * ```tsx
+ * <UserConfigContextProvider>
+ *   <ThemeContextProvider>
+ *     <App />
+ *   </ThemeContextProvider>
+ * </UserConfigContextProvider>
+ * ```
+ */
+export declare function ThemeContextProvider({ theme, children, }: ThemeContextProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/Theme/useTheme/useTheme.d.ts

@@ -0,0 +1,11 @@
+import type { Theme } from "../Theme.types";
+/**
+ * Access the current theme tokens.
+ *
+ * Returns the `Theme` object from the nearest `<ThemeContextProvider>`,
+ * or `defaultTheme` when called outside any provider. The fallback exists
+ * primarily so components remain renderable inside the detached
+ * `measureLayout` tree, which has no provider chain of its own. Within
+ * the live app the provider always wins.
+ */
+export declare function useTheme(): Theme;

package/dist/Theme/useTheme/useTheme.types.d.ts

@@ -0,0 +1,10 @@
+import type { Theme } from "../Theme.types";
+/** Shape of the theme context value. */
+export type ThemeContextType = Theme;
+/** Props for `ThemeContextProvider`. */
+export interface ThemeContextProviderProps {
+    /** Optional theme override. Defaults to `defaultTheme`. */
+    readonly theme?: Theme;
+    /** Child components that can consume the theme. */
+    readonly children: React.ReactNode;
+}

package/dist/components/BorderedPanel/BorderedPanel.d.ts

@@ -0,0 +1,70 @@
+import { type DOMElement } from "ink";
+import type React from "react";
+import type { BorderedPanelTheme } from "./BorderedPanel.theme";
+export interface BorderedPanelProps {
+    /**
+     * Label embedded into the top border, e.g. an agent name or sender role.
+     *
+     * Rendered inline in the top border row by overlaying the label text on
+     * top of Ink's built-in border via an absolutely-positioned child.
+     */
+    readonly header: React.ReactNode;
+    /** Optional ref attached to the header overlay for mouse hit testing. */
+    readonly headerRef?: React.RefObject<DOMElement | null>;
+    /**
+     * Color applied to every border glyph (top, left, right, bottom).
+     * Defaults to the theme's neutral border color when omitted.
+     */
+    readonly borderColor?: string;
+    /**
+     * Background color for the panel body. Also painted behind the header
+     * label so the underlying top border is masked out where the label sits.
+     */
+    readonly backgroundColor?: string;
+    /**
+     * Color applied to the header label text. Defaults to the theme's
+     * primary foreground color when omitted; callers typically pass a
+     * role-specific color so the label matches the message owner.
+     */
+    readonly headerColor?: string;
+    /** Body content rendered inside the panel. */
+    readonly children: React.ReactNode;
+}
+/**
+ * A column-shaped panel whose top border embeds a text label.
+ *
+ * Implementation: the body uses Ink's built-in `borderStyle: "single"` so
+ * Yoga draws the entire frame (top, sides, bottom). The header label is
+ * then painted over the top border via an absolutely-positioned child
+ * with `marginTop: -1`, offset one column from the left corner so the
+ * `┌` glyph stays visible. The label `<Text>` carries the panel's
+ * background color so the dashes underneath are masked out — visually
+ * indistinguishable from a hand-drawn `┌─ label ─...─┐` line, but with
+ * **zero measurement**: no `useBoxMetrics`, no stdout listener, no
+ * dash-fill math. Yoga handles the border and clipping for free.
+ *
+ * @example
+ * ```tsx
+ * <BorderedPanel header="planner" borderColor={colors.agentMessage}>
+ *   <Text>...</Text>
+ * </BorderedPanel>
+ * ```
+ */
+export declare function BorderedPanel({ header, headerRef, borderColor, headerColor, backgroundColor, children, }: BorderedPanelProps): React.ReactElement;
+export interface BorderedPanelRenderProps {
+    /** Resolved BorderedPanel theme. */
+    readonly theme: BorderedPanelTheme;
+    /** Header label embedded into the top border. */
+    readonly header: React.ReactNode;
+    /** Optional ref attached to the header overlay for mouse hit testing. */
+    readonly headerRef?: React.RefObject<DOMElement | null>;
+    /** Resolved border color (no fallback handling here). */
+    readonly borderColor: string;
+    /** Resolved header label color (no fallback handling here). */
+    readonly headerColor: string;
+    /** Resolved background color (also masks the border behind the label). */
+    readonly backgroundColor: string;
+    /** Body content. */
+    readonly children: React.ReactNode;
+}
+export declare function BorderedPanelRender({ theme, header, headerRef, borderColor, headerColor, backgroundColor, children, }: BorderedPanelRenderProps): React.ReactElement;

package/dist/components/BorderedPanel/BorderedPanel.theme.d.ts

@@ -0,0 +1,59 @@
+import { type ThemeOf } from "../../Theme";
+/**
+ * Memoized themed style objects for the `BorderedPanel` component.
+ *
+ * The header line is drawn manually (so we can embed a label inside the
+ * top-border characters); the body's left/right/bottom borders use Ink's
+ * built-in border rendering. Both must use the same glyph set or the
+ * panel will look mismatched.
+ */
+export declare const useBorderedPanelTheme: () => {
+    /** Outer column wrapping the header line and the body. */
+    container: {
+        flexDirection: "column";
+        width: string;
+        borderStyle: "round";
+        borderBottom: false;
+        borderRight: false;
+        paddingX: number;
+    };
+    /** Single-row header line: `┌─ label ──...──┐`. */
+    header: {
+        position: "absolute";
+        marginTop: number;
+        marginLeft: number;
+        flexDirection: "row";
+        text: {
+            bold: true;
+        };
+    };
+    /**
+     * Glyphs used to compose the manual header line. Must match the
+     * `borderStyle` of the body so the corners line up with the body's
+     * left/right border characters.
+     */
+    glyphs: {
+        /** Top-left corner: `┌`. */
+        cornerLeft: string;
+        /** Top-right corner: `┐`. */
+        cornerRight: string;
+        /** Horizontal fill character: `─`. */
+        horizontal: string;
+    };
+    /**
+     * Default color applied to every part of the panel border (header
+     * glyphs + body border). Callers override per-message via the
+     * `borderColor` prop.
+     */
+    borderColor: string;
+    /**
+     * Default color for the header label text. Callers override per
+     * message via `headerColor`.
+     */
+    headerColor: string;
+    backgroundColor: string;
+    /** Whether the header label is bold by default. */
+    headerBold: boolean;
+};
+/** Resolved style object shape returned by {@link useBorderedPanelTheme}. */
+export type BorderedPanelTheme = ThemeOf<typeof useBorderedPanelTheme>;

package/dist/components/BorderedPanel/index.d.ts

@@ -0,0 +1,4 @@
+export type { BorderedPanelProps, BorderedPanelRenderProps, } from "./BorderedPanel";
+export { BorderedPanel, BorderedPanelRender, } from "./BorderedPanel";
+export type { BorderedPanelTheme } from "./BorderedPanel.theme";
+export { useBorderedPanelTheme } from "./BorderedPanel.theme";

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,69 @@
+import { type DOMElement } from "ink";
+import type React from "react";
+import { type RefObject } from "react";
+import { type ButtonTheme } from "./Button.theme";
+import type { ButtonVariant } from "./Button.types";
+export interface ButtonProps {
+    /** Ink focus id. When supplied the button participates in Ink's global focus cycle. When omitted the button manages its own internal focus zone. */
+    readonly id?: string;
+    /** Text label rendered inside the button. */
+    readonly label: string;
+    /** Visual variant that controls border and text coloring. @default "primary" */
+    readonly variant?: ButtonVariant;
+    /** Callback invoked when the button is activated (Enter key or left/right click). */
+    readonly onPress: () => void;
+    /** When `true` the button is rendered as disabled: it does not respond to clicks or key presses and is visually dimmed. @default false */
+    readonly disabled?: boolean;
+}
+/**
+ * Interactive button with focus, hover, and click support.
+ *
+ * Responds to:
+ * - **Enter** key when focused → triggers `onPress`.
+ * - **Left click** (button 0) → focuses the button then triggers `onPress`.
+ * - **Right click** (button 2) → triggers `onPress` without stealing focus.
+ *
+ * Visual states:
+ * - `variant` controls the color scheme (`primary`, `secondary`, `danger`, `ghost`).
+ * - Focus and hover both highlight the button using an `inverse` text style.
+ * - `disabled` dims the button and suppresses all interactions.
+ *
+ * Must be rendered inside a `<Frame>` (which mounts `<MouseProvider>`) for
+ * mouse events to work.
+ *
+ * @param props - The button properties including label, variant, and activation callback.
+ * @example
+ * ```tsx
+ * <Button label="Confirm" variant="primary" onPress={() => submit()} />
+ * <Button label="Delete" variant="danger"  onPress={() => remove()} />
+ * <Button label="Cancel" variant="ghost"   onPress={() => close()} />
+ * ```
+ */
+export declare function Button({ id, label, variant, onPress, disabled, }: ButtonProps): React.ReactElement;
+export interface ButtonRenderProps {
+    /** Resolved Button theme. */
+    readonly theme: ButtonTheme;
+    /** Text label rendered inside the button. */
+    readonly label: string;
+    /** Active visual variant. */
+    readonly variant: ButtonVariant;
+    /** Whether the button currently has keyboard focus. */
+    readonly isFocused: boolean;
+    /** Whether the mouse cursor is hovering over the button. */
+    readonly isHovered: boolean;
+    /** Whether the button is disabled. */
+    readonly disabled: boolean;
+    /** Ref attached to the root `<Box>` for AABB hit-testing. */
+    readonly boxRef: RefObject<DOMElement | null>;
+    /** Node rendered inside the box (supplied by the container). */
+    readonly children?: React.ReactNode;
+}
+/**
+ * Pure render function for the `Button` component.
+ *
+ * Accepts fully-resolved props — no theme fallback logic, no hooks.
+ * Useful for isolated visual testing and Storybook stories.
+ *
+ * @param props - The resolved rendering properties for the button.
+ */
+export declare function ButtonRender({ theme, label, variant, isFocused, isHovered, disabled, boxRef, }: ButtonRenderProps): React.ReactElement;

package/dist/components/Button/Button.theme.d.ts

@@ -0,0 +1,50 @@
+import { type ThemeOf } from "../../Theme";
+/**
+ * Memoized themed style objects for the `Button` component.
+ *
+ * Each variant gets its own resolved color set so the render function only
+ * needs to index by `ButtonVariant` — no conditional logic inside JSX.
+ *
+ * @example
+ * ```ts
+ * const theme = useButtonTheme();
+ * const styles = theme.variants.primary;
+ * ```
+ */
+export declare const useButtonTheme: () => {
+    buttonContainer: {
+        flexDirection: "row";
+        paddingX: number;
+    };
+    /**
+     * Per-variant color pairs used to style the border and label text.
+     * Both `color` and `focusColor` are terminal color strings passed
+     * directly to Ink `<Text>` / `<Box>` props.
+     */
+    variants: {
+        primary: {
+            /** Normal (unfocused, unhovered) border and label color. */
+            color: string;
+            /** Color when focused or hovered. */
+            focusColor: string;
+        };
+        secondary: {
+            color: string;
+            focusColor: string;
+        };
+        danger: {
+            color: string;
+            focusColor: string;
+        };
+        ghost: {
+            color: string;
+            focusColor: string;
+        };
+    };
+    /** Label is bold when the button has focus. */
+    labelBold: boolean;
+    /** Color applied to the entire button when disabled. */
+    disabledColor: string;
+};
+/** Resolved style object shape returned by {@link useButtonTheme}. */
+export type ButtonTheme = ThemeOf<typeof useButtonTheme>;