@usetheo/ui 0.12.0 → 0.13.1

package/dist/components/primitives/pagination/pagination.d.ts

@@ -0,0 +1,44 @@
+import type { HTMLAttributes } from "react";
+/**
+ * Pagination — accessible page-number navigation primitive.
+ *
+ * Renders a `<nav aria-label="Pagination">` containing a button group:
+ * `[<<] [<] 1 ... 5 6 [7] 8 9 ... 42 [>] [>>]`. The active page carries
+ * `aria-current="page"`. Keyboard navigation (ArrowLeft / ArrowRight /
+ * Home / End) is wired on the nav. Ellipses are rendered as
+ * non-interactive `<span>` elements with `aria-hidden`.
+ *
+ * Renders nothing when `totalPages <= 1` (the page is the whole list).
+ *
+ * `siblingCount` controls how many neighbors of the current page are
+ * always visible (default 1 → "5 6 [7] 8 9"). `showJumpButtons`
+ * toggles the first/last `<<` / `>>` buttons.
+ *
+ * Consumers control state (`currentPage`) and are responsible for any
+ * URL routing — the buttons are `<button>`, not `<a>`.
+ *
+ * @example
+ *   <Pagination
+ *     currentPage={page}
+ *     totalPages={42}
+ *     onPageChange={setPage}
+ *   />
+ */
+export interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, "onChange"> {
+    currentPage: number;
+    totalPages: number;
+    onPageChange: (page: number) => void;
+    /** Neighbors of current page that stay visible. Default 1. */
+    siblingCount?: number;
+    /** Render `<<` / `>>` first/last buttons. Default true. */
+    showJumpButtons?: boolean;
+    /** Size variant. Default md. */
+    size?: "sm" | "md";
+}
+/**
+ * Pure helper: compute the visible page-range with ellipses.
+ * Exported for unit testing — most pagination bugs live here.
+ */
+export declare function computePageRange(currentPage: number, totalPages: number, siblingCount?: number): Array<number | "ellipsis-start" | "ellipsis-end">;
+declare const Pagination: import("react").ForwardRefExoticComponent<PaginationProps & import("react").RefAttributes<HTMLElement>>;
+export { Pagination };

package/dist/components/primitives/permission-matrix/index.d.ts

@@ -0,0 +1 @@
+export { PermissionMatrix, type PermissionDecisionKind, type PermissionRule, } from "./permission-matrix.js";

package/dist/components/primitives/permission-matrix/permission-matrix.d.ts

@@ -0,0 +1,43 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export type PermissionDecisionKind = "allow" | "ask" | "deny";
+export interface PermissionRule {
+    id: string;
+    /** Tool the rule applies to. Use "*" for any. */
+    tool: string;
+    /** Glob path it applies to. Use "*" for any. */
+    path: string;
+    decision: PermissionDecisionKind;
+    /** Optional rationale shown as helper text. */
+    note?: string;
+}
+interface PermissionMatrixProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    rules: PermissionRule[];
+    title?: ReactNode;
+    /**
+     * Available tools shown in the add form. Pass `undefined` (or omit) — or an
+     * empty array — to hide the add form entirely. The form only renders when
+     * `onAdd` is provided AND `toolOptions` has at least one entry.
+     */
+    toolOptions?: string[];
+    onAdd?: (rule: Omit<PermissionRule, "id">) => void;
+    onRemove?: (id: string) => void;
+    onDecisionChange?: (id: string, decision: PermissionDecisionKind) => void;
+}
+/**
+ * PermissionMatrix — tool × path × decision grid for fine-grained access
+ * control. Used as the "permissions" tab in the agent settings.
+ *
+ * One PermissionRule per row. Click the decision pill to cycle Allow → Ask → Deny.
+ *
+ * Design decision (2026-05-14): PermissionMatrix stays in `primitives/`
+ * — not `composites/` — even though it renders inputs and a select. The native
+ * `<input>` / `<select>` elements use Theo design tokens directly (border-input,
+ * ring, font-mono) so visual parity with `Input` / `Select` primitives is
+ * preserved. Reason for keeping it primitive: a consumer installing
+ * `permission-matrix` from the registry gets a single self-contained file with
+ * no transitive Theo dependencies — opposite trade-off from `EnvVarEditor`
+ * which is intentionally a composite. Both shapes are valid; we ship one of
+ * each so consumers can pick the dependency profile that fits their app.
+ */
+declare const PermissionMatrix: import("react").ForwardRefExoticComponent<PermissionMatrixProps & import("react").RefAttributes<HTMLDivElement>>;
+export { PermissionMatrix };

package/dist/components/primitives/pin-input/index.d.ts

@@ -0,0 +1 @@
+export { PinInput, type PinInputProps } from "./pin-input.js";

package/dist/components/primitives/pin-input/pin-input.d.ts

@@ -0,0 +1,41 @@
+import type { HTMLAttributes } from "react";
+/**
+ * PinInput — multi-slot OTP / code input primitive.
+ *
+ * Renders N separate boxes (default 6) that auto-advance focus on
+ * input. Paste handling fills all slots from clipboard (whitespace
+ * stripped). Arrow keys navigate; backspace clears current slot
+ * then moves focus back when empty.
+ *
+ * Industry-standard pattern for email verification codes (Apple,
+ * Stripe, Clerk, Auth0, GitHub two-factor).
+ *
+ * @example
+ *   <PinInput
+ *     length={6}
+ *     value={code}
+ *     onChange={setCode}
+ *     onComplete={(v) => verify(v)}
+ *     inputMode="numeric"
+ *     aria-label="Verification code"
+ *   />
+ *
+ * Note: value is treated as controlled. If you pass a complete value
+ * on mount, onComplete will NOT fire — onComplete fires only on
+ * transitions from incomplete → complete.
+ */
+export interface PinInputProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "inputMode"> {
+    length?: number;
+    value?: string;
+    onChange?: (value: string) => void;
+    onComplete?: (value: string) => void;
+    inputMode?: "numeric" | "alphanumeric";
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    error?: boolean;
+    "aria-label": string;
+    autoFocus?: boolean;
+    mask?: boolean;
+}
+declare const PinInput: import("react").ForwardRefExoticComponent<PinInputProps & import("react").RefAttributes<HTMLDivElement>>;
+export { PinInput };

package/dist/components/primitives/plan-badge/index.d.ts

@@ -0,0 +1 @@
+export { PlanBadge, type PlanBadgeProps, type PlanTier } from "./plan-badge.js";

package/dist/components/primitives/plan-badge/plan-badge.d.ts

@@ -0,0 +1,35 @@
+import type { HTMLAttributes } from "react";
+/**
+ * PlanBadge — semantic pricing-tier badge.
+ *
+ * Five canonical tiers (`free` / `hobby` / `pro` / `team` / `enterprise`) with
+ * distinct color tokens. Consumers self-document intent with `plan="hobby"`
+ * instead of mapping a generic `<Badge variant="outline">` to colors per app.
+ * Future rebrand / dark-mode tweaks propagate automatically — no consumer
+ * code change.
+ *
+ * Visual spec (per `theo/docs/handoff/2026-05-23-theo-ui-cloud-dashboard-gaps-brief.md`):
+ *
+ *   | tier         | bg                  | border                   | text                  |
+ *   |--------------|---------------------|--------------------------|-----------------------|
+ *   | free         | bg-muted/40         | border-muted-foreground/20 | text-muted-foreground |
+ *   | hobby        | bg-warning/10       | border-warning/30        | text-warning          |
+ *   | pro          | bg-primary/10       | border-primary/30        | text-primary          |
+ *   | team         | bg-success/10       | border-success/30        | text-success          |
+ *   | enterprise   | bg-foreground/5     | border-foreground/20     | text-foreground       |
+ *
+ * Default label capitalizes the tier (`hobby → "Hobby"`, `enterprise → "Enterprise"`).
+ *
+ * Used by `<AccountMenu>` inline with the user name; usable standalone.
+ */
+export type PlanTier = "free" | "hobby" | "pro" | "team" | "enterprise";
+export interface PlanBadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Plan tier identifier. */
+    plan: PlanTier;
+    /** Override the display label. Defaults to the capitalized tier name. */
+    label?: string;
+    /** Size variant. */
+    size?: "sm" | "md";
+}
+declare const PlanBadge: import("react").ForwardRefExoticComponent<PlanBadgeProps & import("react").RefAttributes<HTMLSpanElement>>;
+export { PlanBadge };

package/dist/components/primitives/progress/index.d.ts

@@ -0,0 +1 @@
+export { Progress, type ProgressProps } from "./progress.js";

package/dist/components/primitives/progress/progress.d.ts

@@ -0,0 +1,44 @@
+import type { HTMLAttributes } from "react";
+/**
+ * Progress — accessible progress bar primitive.
+ *
+ * Built on `<div role="progressbar">` (NOT native `<progress>`) so Tailwind
+ * classes can style the track + fill cross-browser (Chrome/Safari/Firefox
+ * shadow-DOM hooks for `<progress>` diverge). Matches Radix / shadcn /
+ * Mantine convention.
+ *
+ * Variants:
+ *   - intent: `default` | `success` | `warning` | `destructive` — controls fill color
+ *   - height: `h-1` (4px, default) | `h-1.5` | `h-2` | `h-3`
+ *   - indeterminate: animated bar, no value (e.g. "uploading…", "building…")
+ *
+ * Composition:
+ *   <Progress value={42} max={100} intent="success" aria-label="Upload" />
+ *   <Progress indeterminate aria-label="Building" />
+ *
+ * A11y:
+ *   - role="progressbar"
+ *   - aria-valuenow / aria-valuemin / aria-valuemax (determinate)
+ *   - aria-busy="true" when indeterminate
+ *   - Respects `prefers-reduced-motion` (no animation when set)
+ *
+ * Used by `<UsageMeter>` to render each metric's fill bar, but ships as a
+ * standalone primitive for direct consumer use (deploy phase, file upload,
+ * build progress, quota fill).
+ */
+export interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
+    /** Current value (0..max). Values outside the range are clamped. */
+    value?: number;
+    /** Maximum value. Defaults to 100. */
+    max?: number;
+    /** Visual intent — controls fill color. */
+    intent?: "default" | "success" | "warning" | "destructive";
+    /** Bar height in tailwind units. Defaults to `"h-1"` (4px). */
+    height?: "h-1" | "h-1.5" | "h-2" | "h-3";
+    /** When true, animated bar with no value. Omits `aria-valuenow`, adds `aria-busy`. */
+    indeterminate?: boolean;
+    /** Accessible label. Required if not preceded by an `aria-labelledby` element. */
+    "aria-label"?: string;
+}
+declare const Progress: import("react").ForwardRefExoticComponent<ProgressProps & import("react").RefAttributes<HTMLDivElement>>;
+export { Progress };

package/dist/components/primitives/progress-checklist/index.d.ts

@@ -0,0 +1 @@
+export { ProgressChecklist } from "./progress-checklist.js";

package/dist/components/primitives/progress-checklist/progress-checklist.d.ts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { TaskStep } from "../../../types/task.js";
+interface ProgressChecklistProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    title?: ReactNode;
+    steps: TaskStep[];
+    /**
+     * If true, shows percentage bar for running steps with `progress`.
+     */
+    showProgressBars?: boolean;
+}
+/**
+ * ProgressChecklist — right-inspector checklist.
+ *
+ * Visual: vertical list of steps with status dot, label, optional progress bar.
+ * Matches WIREMOCKS §3 / §4 ("Progresso") with checkmarks and pulse on running.
+ */
+declare const ProgressChecklist: import("react").ForwardRefExoticComponent<ProgressChecklistProps & import("react").RefAttributes<HTMLDivElement>>;
+export { ProgressChecklist };

package/dist/components/primitives/project-switcher/index.d.ts

@@ -0,0 +1 @@
+export { ProjectSwitcher, type ProjectStatus } from "./project-switcher.js";

package/dist/components/primitives/project-switcher/project-switcher.d.ts

@@ -0,0 +1,32 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+/**
+ * ProjectSwitcher — sidebar header for a code agent app.
+ *
+ * Shows the active workspace (folder name) + branch + status dot + a tiny
+ * `ChevronsUpDown` hint when clickable. Used in Sidebar.Header to anchor the
+ * current project context for the session list below.
+ *
+ *   <Sidebar.Header className="p-0">
+ *     <ProjectSwitcher
+ *       workspace="acme-web"
+ *       branch="claude/alignment-grid"
+ *       status="running"
+ *       onClick={openProjectPicker}
+ *     />
+ *   </Sidebar.Header>
+ *
+ * If `onClick` is omitted, renders as a static `<div>` (no chevron, not focusable).
+ */
+export type ProjectStatus = "idle" | "running" | "error" | "offline";
+interface ProjectSwitcherProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> {
+    /** Workspace / folder name (e.g. "acme-web"). */
+    workspace: ReactNode;
+    /** Optional git branch. Renders inline with a GitBranch icon. */
+    branch?: ReactNode;
+    /** Optional status dot. Defaults to "idle". */
+    status?: ProjectStatus;
+    /** Brand letter / icon shown in the violet tile. Default: first char of workspace if string. */
+    brand?: ReactNode;
+}
+declare const ProjectSwitcher: import("react").ForwardRefExoticComponent<ProjectSwitcherProps & import("react").RefAttributes<HTMLButtonElement>>;
+export { ProjectSwitcher };

package/dist/components/primitives/quick-action-chips/index.d.ts

@@ -0,0 +1 @@
+export { QuickActionChips, type QuickAction } from "./quick-action-chips.js";

package/dist/components/primitives/quick-action-chips/quick-action-chips.d.ts

@@ -0,0 +1,22 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { IconComponent } from "../../../lib/types.js";
+export interface QuickAction {
+    id: string;
+    label: ReactNode;
+    /** Icon component (e.g. from lucide-react). */
+    icon?: IconComponent;
+    /** When true, the chip is highlighted as the suggested next action. */
+    primary?: boolean;
+}
+interface QuickActionChipsProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    actions: QuickAction[];
+    onSelect?: (id: string) => void;
+}
+/**
+ * QuickActionChips — row of intent chips below a hero composer.
+ *
+ * Used in Chat Home ("Escrever / Aprender / Código / Assuntos pessoais")
+ * and the Files panel.
+ */
+declare const QuickActionChips: import("react").ForwardRefExoticComponent<QuickActionChipsProps & import("react").RefAttributes<HTMLDivElement>>;
+export { QuickActionChips };

package/dist/components/primitives/radio-group/index.d.ts

@@ -0,0 +1 @@
+export { RadioGroup } from "./radio-group.js";

package/dist/components/primitives/radio-group/radio-group.d.ts

@@ -0,0 +1,5 @@
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
+declare const RadioGroup: import("react").ForwardRefExoticComponent<Omit<RadioGroupPrimitive.RadioGroupProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>> & {
+    Item: import("react").ForwardRefExoticComponent<Omit<RadioGroupPrimitive.RadioGroupItemProps & import("react").RefAttributes<HTMLButtonElement>, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+};
+export { RadioGroup };

package/dist/components/primitives/recent-folders-list/index.d.ts

@@ -0,0 +1 @@
+export { RecentFoldersList, type RecentFolder } from "./recent-folders-list.js";

package/dist/components/primitives/recent-folders-list/recent-folders-list.d.ts

@@ -0,0 +1,21 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export interface RecentFolder {
+    id: string;
+    name: ReactNode;
+    path: string;
+    /** When true, the row is highlighted as selected. */
+    active?: boolean;
+}
+interface RecentFoldersListProps extends Omit<HTMLAttributes<HTMLDivElement>, "title" | "onSelect"> {
+    title?: ReactNode;
+    folders: RecentFolder[];
+    onSelect?: (id: string) => void;
+}
+/**
+ * RecentFoldersList — recently-used folders for the Files picker.
+ *
+ * Visual: a stack of rows with folder icon + name + path (smaller, muted),
+ * active row highlighted with violet bg.
+ */
+declare const RecentFoldersList: import("react").ForwardRefExoticComponent<RecentFoldersListProps & import("react").RefAttributes<HTMLDivElement>>;
+export { RecentFoldersList };

package/dist/components/primitives/rule-card/index.d.ts

@@ -0,0 +1 @@
+export { RuleCard } from "./rule-card.js";

package/dist/components/primitives/rule-card/rule-card.d.ts

@@ -0,0 +1,15 @@
+import type { HTMLAttributes } from "react";
+import type { Rule, RuleState } from "../../../types/rule.js";
+interface RuleCardProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "onSelect" | "onToggle"> {
+    rule: Rule;
+    /** Click on the card body — typically opens detail/edit view. */
+    onSelect?: (id: string) => void;
+    /** Click on the edit pencil. Defaults to onSelect if omitted. */
+    onEdit?: (id: string) => void;
+    /** Click on the trash icon. Renders the icon only when provided. */
+    onDelete?: (id: string) => void;
+    /** Toggle enabled/disabled. Renders the switch-like dot only when provided. */
+    onToggle?: (id: string, next: RuleState) => void;
+}
+declare const RuleCard: import("react").ForwardRefExoticComponent<RuleCardProps & import("react").RefAttributes<HTMLElement>>;
+export { RuleCard };

package/dist/components/primitives/run-stats/index.d.ts

@@ -0,0 +1 @@
+export { RunStats } from "./run-stats.js";

package/dist/components/primitives/run-stats/run-stats.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes } from "react";
+interface RunStatsProps extends HTMLAttributes<HTMLDivElement> {
+    duration?: string;
+    /** Formatted token count, e.g. "35.7k". */
+    tokens?: string;
+    /** Number of files changed in the run. */
+    filesChanged?: number;
+}
+/**
+ * RunStats — inline metric row shown after an agent run.
+ *
+ * Visual: muted bullet-separated row with clock + tokens + files-changed icons.
+ * All optional — the component skips entries that aren't provided.
+ */
+declare const RunStats: import("react").ForwardRefExoticComponent<RunStatsProps & import("react").RefAttributes<HTMLDivElement>>;
+export { RunStats };

package/dist/components/primitives/run-status-pill/index.d.ts

@@ -0,0 +1 @@
+export { RunStatusPill, type RunStatus, type RunStatusPillProps, } from "./run-status-pill.js";

package/dist/components/primitives/run-status-pill/run-status-pill.d.ts

@@ -0,0 +1,13 @@
+import { type HTMLAttributes } from "react";
+/**
+ * RunStatusPill — compact status indicator for Run/Task lifecycle states.
+ * Mirrors OpenClaw's `Run status: In progress | Done | Interrupted` pill.
+ * Closed enum mirrors SDK `Task` state (D362).
+ */
+export type RunStatus = "queued" | "in_progress" | "finished" | "error" | "cancelled" | "interrupted";
+export interface RunStatusPillProps extends Omit<HTMLAttributes<HTMLSpanElement>, "title"> {
+    status: RunStatus;
+    detail?: string;
+    "data-testid"?: string;
+}
+export declare const RunStatusPill: import("react").ForwardRefExoticComponent<RunStatusPillProps & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/components/primitives/running-tasks-panel/index.d.ts

@@ -0,0 +1 @@
+export { RunningTasksPanel, type RunningTaskItem, type RunningTaskStatus, type TaskSource, } from "./running-tasks-panel.js";

package/dist/components/primitives/running-tasks-panel/running-tasks-panel.d.ts

@@ -0,0 +1,20 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export type TaskSource = "agent" | "bash" | "tool";
+export type RunningTaskStatus = "running" | "completed" | "failed";
+export interface RunningTaskItem {
+    id: string;
+    label: ReactNode;
+    source: TaskSource;
+    status: RunningTaskStatus;
+}
+interface RunningTasksPanelProps extends HTMLAttributes<HTMLElement> {
+    tasks: RunningTaskItem[];
+}
+/**
+ * RunningTasksPanel — split list of Running vs Completed tasks.
+ *
+ * Used in the Code workspace right rail to give operational visibility into
+ * what the agent is executing (foreground/background) vs what already finished.
+ */
+declare const RunningTasksPanel: import("react").ForwardRefExoticComponent<RunningTasksPanelProps & import("react").RefAttributes<HTMLElement>>;
+export { RunningTasksPanel };

package/dist/components/primitives/scroll-area/index.d.ts

@@ -0,0 +1,2 @@
+export { ScrollArea } from "./scroll-area.js";
+export { isNearBottom, type StickToBottomMetrics, useStickToBottom, type UseStickToBottomOptions, type UseStickToBottomReturn, } from "./use-stick-to-bottom.js";

package/dist/components/primitives/scroll-area/scroll-area.d.ts

@@ -0,0 +1,40 @@
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
+import type { ComponentPropsWithoutRef } from "react";
+/**
+ * ScrollArea — custom scroller with Violet Forge styling.
+ *
+ * Built on Radix ScrollArea so the native scrollbar is always hidden and the
+ * custom thumb stays consistent across Chrome/Firefox/Safari/macOS-trackpad.
+ *
+ * Visual:
+ *   - track is transparent, only the thumb is visible.
+ *   - thumb is `--primary` at 25% opacity by default; on hover, 45% with violet glow.
+ *   - active drag bumps to 60%.
+ *   - the rounded full pill thumb plays well with the brutalist border language
+ *     but stays subtle (1.5px wide on rest, 3px on hover).
+ *
+ * Modes (via `type`):
+ *   - "hover" (default)  — scrollbar fades in on hover/focus, otherwise hidden.
+ *   - "always"           — scrollbar always visible.
+ *   - "auto"             — scrollbar visible only when content overflows.
+ *   - "scroll"           — Radix-managed: visible only while scrolling.
+ */
+interface ScrollAreaProps extends ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root> {
+    /**
+     * Optional override for which scrollbar(s) to render.
+     * Defaults: vertical only. Set to "both" for grids/tables with overflow-x.
+     */
+    orientation?: "vertical" | "horizontal" | "both";
+    /**
+     * Thickness of the scrollbar. Default "thin" (2.5px → 3.5px on hover).
+     * Use "regular" (8px) for content where the scrollbar should be a more prominent target.
+     */
+    size?: "thin" | "regular";
+}
+interface ScrollBarProps extends ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar> {
+    size?: "thin" | "regular";
+}
+declare const ScrollArea: import("react").ForwardRefExoticComponent<ScrollAreaProps & import("react").RefAttributes<HTMLDivElement>> & {
+    Bar: import("react").ForwardRefExoticComponent<ScrollBarProps & import("react").RefAttributes<HTMLDivElement>>;
+};
+export { ScrollArea };

package/dist/components/primitives/scroll-area/use-stick-to-bottom.d.ts

@@ -0,0 +1,20 @@
+export interface StickToBottomMetrics {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+/** Pure: is the scroll position within `threshold` px of the bottom? */
+export declare function isNearBottom(metrics: StickToBottomMetrics, threshold: number): boolean;
+export interface UseStickToBottomOptions {
+    /** Px distance from the bottom under which the view is considered pinned. */
+    threshold?: number;
+}
+export interface UseStickToBottomReturn<T extends HTMLElement = HTMLElement> {
+    /** Attach to the `<ScrollArea>` root (or any element). */
+    scrollRef: (node: T | null) => void;
+    /** Whether the view is currently pinned near the bottom. */
+    isPinned: boolean;
+    /** Force-scroll to the bottom and re-pin. */
+    scrollToBottom: () => void;
+}
+export declare function useStickToBottom<T extends HTMLElement = HTMLElement>(options?: UseStickToBottomOptions): UseStickToBottomReturn<T>;

package/dist/components/primitives/select/index.d.ts

@@ -0,0 +1 @@
+export { Select } from "./select.js";

package/dist/components/primitives/select/select.d.ts

@@ -0,0 +1,50 @@
+import * as SelectPrimitive from "@radix-ui/react-select";
+import { type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithoutRef } from "react";
+/**
+ * Trigger size variant (theming-and-sizes plan T1.9).
+ * Items inside Select.Content stay md-equivalent regardless — the floating
+ * menu is isolated from the trigger context (documented decision).
+ *
+ * EC-2 guard: `<Select.Trigger>` is a Radix `<button>` — no SelectHTMLAttributes
+ * conflict to Omit. Verified before implementation.
+ */
+declare const selectTriggerVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * Select — styled wrapper around Radix Select.
+ *
+ * Composition:
+ *   <Select value={value} onValueChange={setValue}>
+ *     <Select.Trigger>
+ *       <Select.Value placeholder="Pick…" />
+ *     </Select.Trigger>
+ *     <Select.Content>
+ *       <Select.Group>
+ *         <Select.Label>Group</Select.Label>
+ *         <Select.Item value="a">A</Select.Item>
+ *       </Select.Group>
+ *     </Select.Content>
+ *   </Select>
+ *
+ * Trigger matches Input height + violet focus ring. Content uses popover
+ * surface with check on the selected item.
+ */
+interface SelectTriggerProps extends ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>, VariantProps<typeof selectTriggerVariants> {
+}
+declare const SelectTrigger: import("react").ForwardRefExoticComponent<SelectTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+declare const SelectContent: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectContentProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const SelectLabel: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectLabelProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const SelectItem: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectItemProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const SelectSeparator: import("react").ForwardRefExoticComponent<Omit<SelectPrimitive.SelectSeparatorProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const Select: typeof SelectPrimitive.Root & {
+    Trigger: typeof SelectTrigger;
+    Value: typeof SelectPrimitive.Value;
+    Content: typeof SelectContent;
+    Group: typeof SelectPrimitive.Group;
+    Label: typeof SelectLabel;
+    Item: typeof SelectItem;
+    Separator: typeof SelectSeparator;
+};
+export { Select };

package/dist/components/primitives/session-list-item/index.d.ts

@@ -0,0 +1 @@
+export { SessionListItem, type SessionRunStatus, type SessionMode, } from "./session-list-item.js";

package/dist/components/primitives/session-list-item/session-list-item.d.ts

@@ -0,0 +1,35 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+/**
+ * SessionListItem — single row in the sidebar's Sessions list for a code agent
+ * app. Richer than the generic `Sidebar.Item`: shows a status dot, the agent
+ * mode last used (chat/code/infra), and a relative timestamp.
+ *
+ *   <SessionListItem
+ *     title="Build the alignment grid demo"
+ *     status="running"
+ *     mode="code"
+ *     timestamp="2m ago"
+ *     active
+ *     onClick={() => navigate(`/session/${id}`)}
+ *   />
+ *
+ * The status dot maps to the agent run state and animates while running.
+ */
+export type SessionRunStatus = "running" | "queued" | "completed" | "failed" | "cancelled";
+export type SessionMode = "chat" | "code" | "infra";
+interface SessionListItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children" | "title"> {
+    /** Session title (truncated). */
+    title: ReactNode;
+    /** Agent run state. Drives the status dot. */
+    status: SessionRunStatus;
+    /** Last mode the user was viewing this session in. Optional pill. */
+    mode?: SessionMode;
+    /** Relative timestamp string ("2m ago", "yesterday"). */
+    timestamp?: ReactNode;
+    /** Optional unread count (pending agent events, new outputs). */
+    unread?: number;
+    /** Whether this is the currently selected session. */
+    active?: boolean;
+}
+declare const SessionListItem: import("react").ForwardRefExoticComponent<SessionListItemProps & import("react").RefAttributes<HTMLButtonElement>>;
+export { SessionListItem };

package/dist/components/primitives/session-timeline/index.d.ts

@@ -0,0 +1 @@
+export { SessionTimeline, type SessionStatus, type SessionSummary, } from "./session-timeline.js";

package/dist/components/primitives/session-timeline/session-timeline.d.ts

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export type SessionStatus = "active" | "completed" | "failed" | "aborted";
+export interface SessionSummary {
+    id: string;
+    /** Friendly title (often the first user message). */
+    title: string;
+    /** ISO timestamp / friendly date label. */
+    startedAt: string;
+    duration?: string;
+    status: SessionStatus;
+    /** Agent/model that ran the session. */
+    model?: string;
+    /** Total tokens consumed (formatted, e.g. "35.7k"). */
+    tokens?: string;
+    /** Total cost (USD). */
+    cost?: number;
+    /** Number of messages in the session. */
+    messageCount?: number;
+}
+interface SessionTimelineProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    sessions: SessionSummary[];
+    /** Title above the list. */
+    title?: ReactNode;
+    /** Fires when a row is clicked. */
+    onOpen?: (id: string) => void;
+}
+/**
+ * SessionTimeline — historical view of past agent sessions with per-row
+ * tokens / cost / duration / status. Click a row to open the full session.
+ */
+declare const SessionTimeline: import("react").ForwardRefExoticComponent<SessionTimelineProps & import("react").RefAttributes<HTMLDivElement>>;
+export { SessionTimeline };

package/dist/components/primitives/sheet/index.d.ts

@@ -0,0 +1 @@
+export { Sheet, sheetVariants } from "./sheet.js";