@comma-agents/tui 2.0.0-rc.0

package/dist/components/MessageList/ToolCallView/ToolCallView.theme.d.ts

@@ -0,0 +1,47 @@
+import { type ThemeOf } from "../../../Theme";
+/**
+ * Memoized themed style objects for the {@link ToolCallView} component.
+ *
+ * Every nested object is a spread-ready literal sized to be applied
+ * directly to an Ink `<Box>` or `<Text>` — the consumer never reaches in
+ * to mutate or re-derive styles, which keeps the render path branch-free
+ * and makes snapshot diffs predictable.
+ */
+export declare const useToolCallViewTheme: () => {
+    /** Outer container — a single column row spaced from the previous segment. */
+    container: {
+        flexDirection: "column";
+        marginTop: number;
+    };
+    /** Glyph color when the call is still in flight. */
+    runningGlyph: {
+        color: string;
+    };
+    /** Glyph color on success. */
+    completedGlyph: {
+        color: string;
+    };
+    /** Glyph color on failure. */
+    errorGlyph: {
+        color: string;
+    };
+    /** Tool name style. */
+    toolName: {
+        bold: boolean;
+        color: string;
+    };
+    /** Args preview style. */
+    args: {
+        dimColor: boolean;
+    };
+    /** Result summary (success path). */
+    resultSummary: {
+        dimColor: boolean;
+    };
+    /** Result summary (error path). */
+    errorSummary: {
+        color: string;
+    };
+};
+/** Resolved style object shape returned by {@link useToolCallViewTheme}. */
+export type ToolCallViewTheme = ThemeOf<typeof useToolCallViewTheme>;

package/dist/components/MessageList/ToolCallView/ToolCallView.types.d.ts

@@ -0,0 +1,60 @@
+import type { ToolCallViewTheme } from "./ToolCallView.theme";
+/**
+ * Visual state of a tool call.
+ *
+ * - `running`   — call sent, no paired result yet (implicit on the
+ *   wire; the result segment simply hasn't arrived).
+ * - `completed` — paired tool-result with `status: "completed"`.
+ * - `error`     — paired tool-result with `status: "error"` (mapped
+ *   from the AI SDK `tool-error` part by `mapStreamPart`).
+ */
+export type ToolCallViewStatus = "running" | "completed" | "error";
+/**
+ * Map a wire-level tool-call/tool-result pairing to the renderer's
+ * status. When `result` is absent the call is still in flight; when
+ * present its `status` field decides between `completed` and `error`.
+ */
+export declare function deriveToolCallViewStatus(result: {
+    readonly status: "completed" | "error";
+} | undefined): ToolCallViewStatus;
+export interface ToolCallViewProps {
+    /** Bare name of the tool that was invoked (e.g. `"read_file"`). */
+    readonly toolName: string;
+    /**
+     * Stringified tool-call arguments. Multi-line / long blobs are
+     * collapsed and clipped to a single visual row by the renderer; pass
+     * the raw value here.
+     */
+    readonly args: string;
+    /** Current visual state. */
+    readonly status: ToolCallViewStatus;
+    /**
+     * Stringified tool-result output. Only used for `status === "completed"`
+     * to derive the trailing `→ N lines` summary. Ignored for `running`
+     * and `error`.
+     */
+    readonly output?: string;
+    /**
+     * Error message, populated when the tool errored. Replaces the
+     * trailing summary with `→ <error>` for `status === "error"`.
+     */
+    readonly error?: string;
+}
+export interface ToolCallViewRenderProps {
+    /** Resolved theme styles. */
+    readonly theme: ToolCallViewTheme;
+    /** Glyph rendered at the head of the row. */
+    readonly leadingGlyph: string;
+    /** Bare name of the tool. */
+    readonly toolName: string;
+    /** Pre-truncated, single-line args preview (may be empty). */
+    readonly argsPreview: string;
+    /**
+     * Pre-formatted result summary (e.g. `"\u2192 12 lines"` or
+     * `"\u2192 ENOENT: no such file"`). Empty string when there is no
+     * result yet.
+     */
+    readonly resultSummary: string;
+    /** Visual status — drives glyph color. */
+    readonly status: ToolCallViewStatus;
+}

package/dist/components/MessageList/ToolCallView/ToolCallView.utils.d.ts

@@ -0,0 +1,40 @@
+import type { ToolCallViewStatus } from "./ToolCallView.types";
+/**
+ * Collapse a possibly-multiline args blob into a single visual row and
+ * clip it to {@link TOOL_CALL_ARGS_PREVIEW_LENGTH} characters.
+ *
+ * - CR / CRLF / LF are normalized then collapsed (along with tabs and
+ *   runs of spaces) into single spaces, so JSON pretty-printed across
+ *   many lines still renders as one row.
+ * - Empty / all-whitespace input returns an empty string so the
+ *   renderer can omit the args span entirely (no leading separator).
+ * - Truncation appends a single typographic ellipsis (`\u2026`); the
+ *   ellipsis is *not* counted toward the cap so the output is at most
+ *   `cap + 1` characters.
+ *
+ * Exported so the row-height estimator can compute heights against the
+ * exact same string the renderer will draw.
+ */
+export declare function formatArgsPreview(rawArgs: string): string;
+/**
+ * Build the trailing summary fragment for a paired tool-result.
+ *
+ * - `running` → empty string (no result yet).
+ * - `completed` → `\u2192 N lines` where `N` is the line count of the
+ *   raw output (1 for a single line, 0 for an empty string). Using
+ *   line count rather than byte count surfaces the "shape" of the
+ *   result without leaking content.
+ * - `error` → `\u2192 <message>` clipped to
+ *   {@link TOOL_CALL_ERROR_PREVIEW_LENGTH} characters; the leading
+ *   newline is stripped so the message stays on the same row.
+ *
+ * Exported so the row estimator can mirror the rendered row exactly.
+ */
+export declare function formatResultSummary(status: ToolCallViewStatus, output: string | undefined, error: string | undefined): string;
+/**
+ * Resolve the leading status glyph for a given tool-call status. The
+ * `running` case is supplied by the caller because it animates via
+ * {@link useToolSpinner}; the static glyphs live here so the row
+ * estimator can use them without subscribing to the spinner.
+ */
+export declare function staticGlyphForStatus(status: Exclude<ToolCallViewStatus, "running">): string;

package/dist/components/MessageList/ToolCallView/index.d.ts

@@ -0,0 +1,8 @@
+export type { ToolCallViewProps, ToolCallViewRenderProps, } from "./ToolCallView";
+export { ToolCallView, ToolCallViewRender } from "./ToolCallView";
+export { TOOL_CALL_ARGS_PREVIEW_LENGTH, TOOL_CALL_ELLIPSIS, TOOL_CALL_ERROR_PREVIEW_LENGTH, TOOL_CALL_GLYPH_COMPLETED, TOOL_CALL_GLYPH_ERROR, } from "./ToolCallView.constants";
+export type { ToolCallViewTheme } from "./ToolCallView.theme";
+export { useToolCallViewTheme } from "./ToolCallView.theme";
+export type { ToolCallViewStatus } from "./ToolCallView.types";
+export { deriveToolCallViewStatus } from "./ToolCallView.types";
+export { formatArgsPreview, formatResultSummary, staticGlyphForStatus, } from "./ToolCallView.utils";

package/dist/components/MessageList/UserMessage/UserMessage.d.ts

@@ -0,0 +1,25 @@
+import type React from "react";
+import { useMessageListTheme } from "../MessageList.theme";
+export interface UserMessageProps {
+    /** The user-typed body of the message. */
+    readonly text: string;
+    /** Display label for the user (defaults to "you"). */
+    readonly label?: string;
+}
+/**
+ * Renders a single user-authored message inside a bordered panel.
+ *
+ * The panel's top border embeds the user label so the sender is visible
+ * without consuming an extra row, and the prompt body is rendered inside
+ * the panel's body box.
+ */
+export declare function UserMessage({ text, label, }: UserMessageProps): React.ReactElement;
+export interface UserMessageRenderProps {
+    /** Resolved MessageList theme styles. */
+    readonly theme: ReturnType<typeof useMessageListTheme>;
+    /** The user-typed body of the message. */
+    readonly text: string;
+    /** Display label for the user. */
+    readonly label: string;
+}
+export declare function UserMessageRender({ theme, text, label, }: UserMessageRenderProps): React.ReactElement;

package/dist/components/MessageList/UserMessage/index.d.ts

@@ -0,0 +1,2 @@
+export type { UserMessageProps, UserMessageRenderProps } from "./UserMessage";
+export { UserMessage, UserMessageRender } from "./UserMessage";

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

@@ -0,0 +1,14 @@
+export type { AgentMessageProps, AgentMessageRenderProps, } from "./AgentMessage";
+export { AgentMessage, AgentMessageRender } from "./AgentMessage";
+export type { ContextUsageModalPayload, ContextUsageModalRenderProps, } from "./ContextUsageModal";
+export { CONTEXT_USAGE_MODAL_ID, ContextUsageModal, ContextUsageModalRender, } from "./ContextUsageModal";
+export { findSubStrategyName, groupSubStrategyMessages, MessageList, MessageListRender, selectSubStrategyMessages, } from "./MessageList";
+export type { GroupedChatMessage, MessageListProps, MessageListRenderProps, } from "./MessageList.types";
+export type { OutputModalKind, OutputModalPayload, OutputModalRenderProps, } from "./OutputModal";
+export { OUTPUT_MODAL_ID, OutputModal, OutputModalRender, } from "./OutputModal";
+export type { SpawnedStrategyViewProps, SpawnedStrategyViewRenderProps, } from "./SpawnedStrategyView";
+export { SpawnedStrategyView, SpawnedStrategyViewRender, } from "./SpawnedStrategyView";
+export type { SystemMessageProps, SystemMessageRenderProps, } from "./SystemMessage";
+export { SystemMessage, SystemMessageRender } from "./SystemMessage";
+export type { UserMessageProps, UserMessageRenderProps } from "./UserMessage";
+export { UserMessage, UserMessageRender } from "./UserMessage";

package/dist/components/Modal/Modal.d.ts

@@ -0,0 +1,64 @@
+import type React from "react";
+/** Size as absolute columns/rows (number) or a percentage of the terminal. */
+export type ModalSize = number | `${number}%`;
+export interface ModalProps {
+    /** Unique identifier that ties this modal to `useModal(id)` controls. */
+    readonly modalId: string;
+    /** Optional title displayed at the top of the modal. */
+    readonly title?: string;
+    /** Content rendered inside the modal body. */
+    readonly children: React.ReactNode;
+    /**
+     * Close the modal when Esc is pressed. Only triggers when this modal is
+     * topmost. @default true
+     */
+    readonly closeOnEsc?: boolean;
+    /** Override the theme's default minHeight on the content box. */
+    readonly minHeight?: ModalSize;
+    /** Override the theme's default maxHeight on the content box. */
+    readonly maxHeight?: ModalSize;
+}
+/**
+ * Full-screen overlay modal for the TUI.
+ *
+ * Renders the modal content box when open. The backdrop dimming and overlay
+ * centering are handled externally by {@link AlphaDim} — `Modal` is
+ * responsible only for its content box and Esc-to-close behaviour.
+ *
+ * Visibility is controlled via `useModal(modalId)`. When `closeOnEsc` is
+ * true (the default), the modal listens for Esc — but only when it is the
+ * topmost open modal, so nested modals don't all dismiss on one keystroke.
+ *
+ * @param props - Modal configuration and children.
+ * @example
+ * ```tsx
+ * const confirm = useModal("confirm");
+ *
+ * <AlphaDim
+ *   isActive={confirm.isOpen}
+ *   background={<AppContent />}
+ *   overlay={
+ *     <Modal modalId="confirm" title="Are you sure?" width="60%">
+ *       <Text>This action cannot be undone.</Text>
+ *     </Modal>
+ *   }
+ * />
+ *
+ * // open from anywhere:
+ * confirm.open();
+ * ```
+ */
+export declare function Modal({ modalId, title, children, closeOnEsc, minHeight, maxHeight, }: ModalProps): React.ReactElement | null;
+export interface ModalRenderProps {
+    /** Optional title displayed at the top of the modal. */
+    readonly title?: string;
+    /** Content rendered inside the modal body. */
+    readonly children: React.ReactNode;
+    /** Debug render ref to attach to the root Box. */
+    readonly debugRef?: React.Ref<import("ink").DOMElement>;
+    /** Override the theme's default minHeight on the content box. */
+    readonly minHeight?: ModalSize;
+    /** Override the theme's default maxHeight on the content box. */
+    readonly maxHeight?: ModalSize;
+}
+export declare function ModalRender({ title, children, minHeight, maxHeight, }: ModalRenderProps): React.ReactElement;

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

@@ -0,0 +1,29 @@
+import { type BoxProps, type ThemeOf } from "../../Theme";
+/**
+ * Returns themed style objects for the Modal component.
+ * Consumes global tokens via `useTheme()`.
+ */
+export declare const useModalTheme: () => {
+    overlay: {
+        position: "absolute";
+        width: string;
+        height: string;
+        justifyContent: "center";
+        alignItems: "center";
+    };
+    content: {
+        flexDirection: "column";
+        borderStyle: BoxProps["borderStyle"];
+        borderColor: string;
+        paddingX: number;
+        paddingY: number;
+        backgroundColor: string;
+        maxHeight: string;
+        maxWidth: string;
+    };
+    title: {
+        bold: boolean;
+        color: string;
+    };
+};
+export type ModalTheme = ThemeOf<typeof useModalTheme>;

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

@@ -0,0 +1,4 @@
+export type { ModalProps, ModalRenderProps, ModalSize, } from "./Modal";
+export { Modal, ModalRender } from "./Modal";
+export type { ModalTheme } from "./Modal.theme";
+export { useModalTheme } from "./Modal.theme";

package/dist/components/MouseProvider/MouseContext.d.ts

@@ -0,0 +1,36 @@
+import type { MouseEvent } from "../../hooks/useMouse/useMouse.types";
+/**
+ * Function signature for a mouse-event listener registered with
+ * {@link MouseContextValue.subscribe}.
+ */
+export type MouseListener = (event: MouseEvent) => void;
+/**
+ * Value provided by {@link MouseProvider} via React context.
+ *
+ * Consumers should not use this directly — prefer the purpose-built hooks
+ * {@link useMouseHover} and {@link useMouseClick}.
+ */
+export interface MouseContextValue {
+    /**
+     * Subscribe to all parsed mouse events. The returned function unsubscribes
+     * the listener; call it in a `useEffect` cleanup.
+     *
+     * @param listener - Called once for every {@link MouseEvent} received.
+     * @returns Unsubscribe function.
+     */
+    subscribe: (listener: MouseListener) => () => void;
+    /**
+     * Register a hover consumer. The provider ref-counts these registrations
+     * and enables SGR any-event tracking (`?1003h`) while the count is > 0,
+     * then disables it again when the count drops back to zero.
+     *
+     * @returns Unregister function — call it in a `useEffect` cleanup.
+     */
+    registerHoverConsumer: () => () => void;
+}
+/**
+ * React context for the global mouse event bus.
+ * `null` when no {@link MouseProvider} is mounted — consumer hooks
+ * should gracefully degrade (e.g. return a disabled state).
+ */
+export declare const MouseContext: import("react").Context<MouseContextValue | null>;

package/dist/components/MouseProvider/MouseProvider.d.ts

@@ -0,0 +1,20 @@
+import type React from "react";
+export interface MouseProviderProps {
+    /** Content that will have access to mouse events via context. */
+    readonly children: React.ReactNode;
+}
+/**
+ * Provides a global mouse-event bus to the subtree.
+ *
+ * Mount this component once, high in the tree (e.g. inside `Frame`).
+ * It:
+ * - Subscribes a single `useInput` listener that parses all SGR mouse
+ *   chunks and fans them out to registered listeners.
+ * - Ref-counts hover consumers: the first call to `registerHoverConsumer`
+ *   writes `\x1b[?1003h` (any-event motion tracking); the last cleanup
+ *   writes `\x1b[?1003l` to restore the previous mode.
+ *
+ * Consumer hooks ({@link useMouseHover}, {@link useMouseClick}) use the
+ * context provided here rather than subscribing to `useInput` individually.
+ */
+export declare function MouseProvider({ children, }: MouseProviderProps): React.ReactElement;

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

@@ -0,0 +1,4 @@
+export type { MouseContextValue, MouseListener } from "./MouseContext";
+export { MouseContext } from "./MouseContext";
+export type { MouseProviderProps } from "./MouseProvider";
+export { MouseProvider } from "./MouseProvider";

package/dist/components/PermissionPrompt/PermissionPrompt.d.ts

@@ -0,0 +1,33 @@
+import type { RequestPermissionMessage } from "@comma-agents/daemon";
+import type React from "react";
+/** Decision option presented to the user. */
+export type PermissionDecision = "allow" | "deny" | "allow-session" | "deny-session";
+export interface PermissionPromptProps {
+    /** The daemon's `request_permission` message to display. */
+    readonly request: RequestPermissionMessage;
+    /** Called when the user makes a decision. */
+    readonly onDecide: (decision: PermissionDecision) => void;
+}
+export interface PermissionPromptRenderProps {
+    readonly actor: string;
+    readonly verb: string;
+    readonly resource: string;
+    readonly onDecide: (decision: PermissionDecision) => void;
+    readonly colors: {
+        readonly warning: string;
+        readonly secondary: string;
+        readonly primary: string;
+    };
+}
+/**
+ * Renders a permission-request prompt with a row of tabbable action buttons.
+ *
+ * Focus starts on "Allow once" when the prompt mounts. Tab / Shift+Tab cycle
+ * through all four options; Enter (or a mouse click) confirms the focused
+ * choice.
+ *
+ * The background is provided by the Frame's global flood-fill (driven by
+ * `tokens.colors.background`), so no per-component fill is needed here.
+ */
+export declare function PermissionPrompt({ request, onDecide, }: PermissionPromptProps): React.ReactElement;
+export declare function PermissionPromptRender({ actor, verb, resource, onDecide, colors, }: PermissionPromptRenderProps): React.ReactElement;

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

@@ -0,0 +1,2 @@
+export type { PermissionDecision, PermissionPromptProps, PermissionPromptRenderProps, } from "./PermissionPrompt";
+export { PermissionPrompt, PermissionPromptRender } from "./PermissionPrompt";

package/dist/components/QuestionPrompt/QuestionPrompt.d.ts

@@ -0,0 +1,4 @@
+import type React from "react";
+import type { QuestionPromptProps, QuestionPromptRenderProps } from "./QuestionPrompt.types";
+export declare function QuestionPrompt({ request, onSubmit, }: QuestionPromptProps): React.ReactElement;
+export declare function QuestionPromptRender({ actor, question, onSubmit, inputValue, onInputValueChange, colors, }: QuestionPromptRenderProps): React.ReactElement;

package/dist/components/QuestionPrompt/QuestionPrompt.types.d.ts

@@ -0,0 +1,18 @@
+import type { RequestQuestionMessage } from "@comma-agents/daemon";
+export interface QuestionPromptProps {
+    /** The daemon's `request_question` message to display. */
+    readonly request: RequestQuestionMessage;
+    /** Called when the user submits their answer. */
+    readonly onSubmit: (response: string) => void;
+}
+export interface QuestionPromptRenderProps {
+    readonly actor: string;
+    readonly question: string;
+    readonly onSubmit: (response: string) => void;
+    readonly inputValue: string;
+    readonly onInputValueChange: (val: string) => void;
+    readonly colors: {
+        readonly primary: string;
+        readonly secondary: string;
+    };
+}

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

@@ -0,0 +1,2 @@
+export { QuestionPrompt, QuestionPromptRender } from "./QuestionPrompt";
+export type { QuestionPromptProps, QuestionPromptRenderProps, } from "./QuestionPrompt.types";

package/dist/components/ScrollableList/ScrollableList.d.ts

@@ -0,0 +1,33 @@
+import type React from "react";
+import type { ScrollableListProps, ScrollableListRenderProps } from "./ScrollableList.types";
+/**
+ * Generic single-selection list with arrow-key navigation and a row-aware
+ * vertical scrollbar. Built as a thin selection layer over
+ * {@link ScrollableView} — measurement, mouse-wheel handling, and the
+ * absolute-positioned viewport all live there. This component adds:
+ *
+ * - Up/Down arrow keys to move the selection (clamped at the edges).
+ * - Enter to invoke the optional `onSelected` callback.
+ * - `scrollToRow` plumbed to the view so the selected row is always visible.
+ *
+ * Mouse-wheel ticks scroll the underlying view independently of the
+ * selection — familiar GUI behavior.
+ *
+ * @example
+ * ```tsx
+ * const [selected, setSelected] = useState(0);
+ * <ScrollableList
+ *   id="my-list"
+ *   items={commands}
+ *   getKey={(c) => c.id}
+ *   selectedIndex={selected}
+ *   onSelectedIndexChange={setSelected}
+ *   onSelected={(c) => run(c)}
+ *   renderItem={(c, isSelected) => (
+ *     <Text inverse={isSelected}>{c.label}</Text>
+ *   )}
+ * />
+ * ```
+ */
+export declare function ScrollableList<ItemType>(props: ScrollableListProps<ItemType>): React.ReactElement;
+export declare function ScrollableListRender<ItemType>({ items, getKey, renderItem, clampedSelected, emptyText, }: ScrollableListRenderProps<ItemType>): React.ReactElement;

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

@@ -0,0 +1,33 @@
+import { type ThemeOf } from "../../Theme";
+/**
+ * Memoized themed style objects for {@link ScrollableList}.
+ *
+ * The theme intentionally exposes only structural/empty-state styles —
+ * row visual treatment is the caller's responsibility (delivered via the
+ * `isSelected` flag passed to `renderItem`).
+ */
+export declare const useScrollableListTheme: () => {
+    /**
+     * Root viewport. `overflow: "hidden"` clips the absolutely-positioned
+     * inner content to the measured height, while `flexGrow: 1` lets the
+     * viewport claim whatever vertical space the parent layout offers.
+     */
+    viewport: {
+        flexDirection: "column";
+        width: string;
+        flexGrow: number;
+        overflow: "hidden";
+    };
+    /** Empty-state container. */
+    empty: {
+        flexDirection: "column";
+        width: string;
+    };
+    /** Empty-state text style. */
+    emptyText: {
+        color: string;
+        dimColor: boolean;
+    };
+};
+/** Resolved style shape returned by {@link useScrollableListTheme}. */
+export type ScrollableListTheme = ThemeOf<typeof useScrollableListTheme>;

package/dist/components/ScrollableList/ScrollableList.types.d.ts

@@ -0,0 +1,66 @@
+import type React from "react";
+/**
+ * Props for {@link ScrollableList}.
+ *
+ * `ScrollableList` is a focused, single-selection list with arrow-key
+ * navigation, mouse-wheel scrolling, and a row-aware vertical scrollbar.
+ * Row heights are measured automatically by the underlying
+ * {@link ScrollableView} via Ink's headless layout — multi-line rows
+ * (text that wraps on narrow terminals) need no special handling from
+ * the caller.
+ */
+export interface ScrollableListProps<ItemType> {
+    /** The full list of items to render. */
+    readonly items: readonly ItemType[];
+    /** Stable key for each item. */
+    readonly getKey: (item: ItemType, index: number) => string;
+    /**
+     * Renders a single row. Receives the item and a flag indicating whether
+     * this row is currently selected — the caller is responsible for any
+     * visual selection treatment (typically `inverse` text).
+     */
+    readonly renderItem: (item: ItemType, isSelected: boolean) => React.ReactNode;
+    /** Currently selected index (controlled). Clamped to `[0, items.length-1]`. */
+    readonly selectedIndex: number;
+    /** Invoked when Up/Down moves the selection. */
+    readonly onSelectedIndexChange: (next: number) => void;
+    /** Invoked when Enter is pressed on the selected item. */
+    readonly onSelected?: (item: ItemType, index: number) => void;
+    /** Text shown when `items` is empty. Defaults to "No items." */
+    readonly emptyText?: string;
+    /**
+     * Stable focus ID. When omitted the list still participates in tab order
+     * but cannot be focused programmatically by name.
+     */
+    readonly id?: string;
+    /**
+     * External focus override. When provided, the list does NOT register its
+     * own focus zone via `useFocus` — the parent owns the focus state and
+     * passes `true` to enable arrow-key + mouse-wheel input. This lets a
+     * larger surrounding region (e.g. a sidebar) act as a single focus zone
+     * containing the list, instead of forcing the user to tab into the list
+     * separately.
+     */
+    readonly isFocused?: boolean;
+}
+/**
+ * Props for {@link ScrollableListRender}.
+ *
+ * Pure render props — all hook-derived values are computed by the
+ * container and passed down.
+ */
+export interface ScrollableListRenderProps<ItemType> {
+    /** The full list of items to render. */
+    readonly items: readonly ItemType[];
+    /** Stable key for each item. */
+    readonly getKey: (item: ItemType, index: number) => string;
+    /**
+     * Renders a single row. Receives the item and a flag indicating whether
+     * this row is currently selected.
+     */
+    readonly renderItem: (item: ItemType, isSelected: boolean) => React.ReactNode;
+    /** Clamped selected index. */
+    readonly clampedSelected: number;
+    /** Text shown when `items` is empty. */
+    readonly emptyText?: string;
+}

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

@@ -0,0 +1,4 @@
+export { ScrollableList, ScrollableListRender } from "./ScrollableList";
+export type { ScrollableListTheme } from "./ScrollableList.theme";
+export { useScrollableListTheme } from "./ScrollableList.theme";
+export type { ScrollableListProps, ScrollableListRenderProps, } from "./ScrollableList.types";

package/dist/components/ScrollableView/ScrollableView.d.ts

@@ -0,0 +1,34 @@
+import type React from "react";
+import type { ScrollableViewProps, ScrollableViewRenderProps } from "./ScrollableView.types";
+/**
+ * Variable-height, virtualized scrollable container.
+ *
+ * Lays out a list of items inside a measured viewport and clips with
+ * `overflow: hidden`. Row heights are measured automatically via Ink's
+ * headless `measureLayout` — no callback required from the caller — and
+ * cached by `(getKey(item), viewportWidth)`. Only items inside the
+ * visible window plus a small overscan are mounted in the live render
+ * tree, so a list of thousands of rows still renders cheap.
+ *
+ * Measurement runs in a `useLayoutEffect` immediately after commit, so
+ * the rendered frame the user sees always reflects the post-measurement
+ * geometry. The cache survives across renders via `useRef`; when an item
+ * reference changes, the previous height is reused until the replacement
+ * object is re-measured, keeping streaming chat updates from briefly
+ * collapsing the scroll geometry.
+ *
+ * The view does **not** handle keyboard input. Use {@link ScrollableList}
+ * for keyboard-driven single-selection lists.
+ *
+ * @example
+ * ```tsx
+ * <ScrollableView
+ *   items={messages}
+ *   getKey={(message) => message.id}
+ *   renderItem={(message) => <MessageRow message={message} />}
+ *   stickToBottom
+ * />
+ * ```
+ */
+export declare function ScrollableView<ItemType>(props: ScrollableViewProps<ItemType>): React.ReactElement;
+export declare function ScrollableViewRender<ItemType>({ items, getKey, renderItem, totalCount, viewportHeight, totalRows, rowOffset, topClipRows, renderStart, renderEnd, showScrollbar, emptyText, theme, viewportRef, }: ScrollableViewRenderProps<ItemType>): React.ReactElement;

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

@@ -0,0 +1,34 @@
+import { type ThemeOf } from "../../Theme";
+/** Memoized themed style objects for {@link ScrollableView}. */
+export declare const useScrollableViewTheme: () => {
+    /**
+     * Outer row container — holds the viewport column and the scrollbar
+     * column side-by-side.
+     */
+    outer: {
+        flexDirection: "row";
+        width: string;
+        flexGrow: number;
+        overflow: "hidden";
+    };
+    /**
+     * Viewport column. `overflow: "hidden"` clips the absolutely-positioned
+     * inner content; `flexGrow: 1` claims the available width.
+     */
+    viewport: {
+        flexDirection: "column";
+        flexGrow: number;
+        overflow: "hidden";
+    };
+    /** Empty-state container. */
+    empty: {
+        flexDirection: "column";
+        width: string;
+    };
+    /** Empty-state text. */
+    emptyText: {
+        color: string;
+        dimColor: boolean;
+    };
+};
+export type ScrollableViewTheme = ThemeOf<typeof useScrollableViewTheme>;