@comma-agents/tui 2.0.0-rc.0

package/dist/hooks/useMouseHover/useMouseHover.d.ts

@@ -0,0 +1,25 @@
+import type { UseMouseHoverOptions, UseMouseHoverResult } from "./useMouseHover.types";
+/**
+ * Track whether the mouse cursor is hovering over a specific element.
+ *
+ * Requires `?1003h` (any-event motion tracking) which {@link MouseProvider}
+ * enables automatically while at least one `useMouseHover` hook is mounted.
+ * Wrap the component tree in `<MouseProvider>` (done by `<Frame>`) before
+ * using this hook.
+ *
+ * AABB hit-testing is performed on every mouse event by walking the Yoga
+ * layout tree. The `isHovered` boolean only triggers a re-render on
+ * enter/leave transitions to minimise unnecessary renders.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<DOMElement>(null);
+ * const { isHovered } = useMouseHover({
+ *   ref,
+ *   onEnter: () => console.log("entered"),
+ *   onLeave: () => console.log("left"),
+ * });
+ * return <Box ref={ref} backgroundColor={isHovered ? "blue" : undefined} />;
+ * ```
+ */
+export declare function useMouseHover({ ref, onEnter, onLeave, onMove, }: UseMouseHoverOptions): UseMouseHoverResult;

package/dist/hooks/useMouseHover/useMouseHover.types.d.ts

@@ -0,0 +1,38 @@
+import type { DOMElement } from "ink";
+import type React from "react";
+import type { MouseEvent } from "../useMouse/useMouse.types";
+/**
+ * Options accepted by {@link useMouseHover}.
+ */
+export interface UseMouseHoverOptions {
+    /**
+     * Ref to the `DOMElement` (Ink `<Box>` or similar) whose bounds are used
+     * for hit-testing. The element must be mounted before hover events fire.
+     */
+    readonly ref: React.RefObject<DOMElement | null>;
+    /**
+     * Called once when the mouse cursor enters the element's bounding box.
+     * Receives the first mouse event that triggered the transition.
+     */
+    readonly onEnter?: (event: MouseEvent) => void;
+    /**
+     * Called once when the mouse cursor leaves the element's bounding box.
+     * Receives the first mouse event that triggered the transition.
+     */
+    readonly onLeave?: (event: MouseEvent) => void;
+    /**
+     * Called for every mouse event while the cursor is inside the bounding box.
+     * This includes the first event that triggered `onEnter`.
+     */
+    readonly onMove?: (event: MouseEvent) => void;
+}
+/**
+ * Result returned by {@link useMouseHover}.
+ */
+export interface UseMouseHoverResult {
+    /**
+     * `true` while the mouse cursor is inside the element's bounding box,
+     * `false` otherwise. Transitions cause a re-render of the consumer.
+     */
+    readonly isHovered: boolean;
+}

package/dist/hooks/useMouseWheelScroll/index.d.ts

@@ -0,0 +1,2 @@
+export { useMouseWheelScroll } from "./useMouseWheelScroll";
+export type { MouseScrollDirection, MouseScrollEvent, UseMouseWheelScrollOptions, } from "./useMouseWheelScroll.types";

package/dist/hooks/useMouseWheelScroll/useMouseWheelScroll.d.ts

@@ -0,0 +1,28 @@
+import type { UseMouseWheelScrollOptions } from "./useMouseWheelScroll.types";
+/**
+ * Subscribe to mouse-wheel scroll events via the global {@link MouseProvider}
+ * event bus.
+ *
+ * Shares the single `useInput` subscription in {@link MouseProvider} with all
+ * other mouse hooks rather than registering its own.
+ *
+ * Optionally accepts a `ref` for AABB hit-testing: when provided, only wheel
+ * ticks whose terminal coordinates fall inside the element's bounding box are
+ * forwarded to `onScroll`. This is useful when multiple scrollable regions
+ * are on screen simultaneously — each can restrict its listener to its own
+ * box without coordinating with siblings.
+ *
+ * Requires `<MouseProvider>` to be mounted (provided by `<Frame>`).
+ *
+ * @example
+ * ```tsx
+ * // Global — any wheel tick triggers onScroll.
+ * useMouseWheelScroll({ onScroll: ({ direction }) => step(direction) });
+ *
+ * // Scoped — only ticks inside this element trigger onScroll.
+ * const ref = useRef<DOMElement>(null);
+ * useMouseWheelScroll({ ref, onScroll: ({ direction }) => step(direction) });
+ * return <Box ref={ref}>...</Box>;
+ * ```
+ */
+export declare function useMouseWheelScroll({ onScroll, ref, }: UseMouseWheelScrollOptions): void;

package/dist/hooks/useMouseWheelScroll/useMouseWheelScroll.types.d.ts

@@ -0,0 +1,32 @@
+/** Direction of a mouse-wheel scroll tick. */
+export type MouseScrollDirection = "up" | "down";
+/**
+ * A parsed mouse-scroll event delivered to {@link useMouseWheelScroll}'s
+ * `onScroll` callback.
+ *
+ * Coordinates follow the SGR (1006) protocol: `column` and `row` are
+ * 1-indexed terminal cell coordinates reported by the terminal at the time
+ * the scroll tick was emitted.
+ */
+export interface MouseScrollEvent {
+    readonly direction: MouseScrollDirection;
+    readonly column: number;
+    readonly row: number;
+}
+/**
+ * Options for {@link useMouseWheelScroll}.
+ */
+export interface UseMouseWheelScrollOptions {
+    /**
+     * Invoked for every mouse-wheel tick whose position falls inside the
+     * element's bounding box, or for every tick regardless of position when
+     * `ref` is omitted.
+     */
+    readonly onScroll: (event: MouseScrollEvent) => void;
+    /**
+     * Optional ref to a `DOMElement`. When provided, only wheel ticks whose
+     * terminal coordinates land inside the element's bounding box are
+     * forwarded to `onScroll`. When omitted, all wheel ticks are forwarded.
+     */
+    readonly ref?: React.RefObject<import("ink").DOMElement | null>;
+}

package/dist/hooks/useRegion/index.d.ts

@@ -0,0 +1,3 @@
+export { useRegion } from "./useRegion";
+export type { RegionDimensions, RegionHandle, RegionOptions, RegionPosition, } from "./useRegion.types";
+export { buildRegionOutput, CURSOR_RESTORE, CURSOR_SAVE, cursorTo, fitToWidth, getAbsolutePosition, padToWidth, visibleLength, } from "./useRegion.utils";

package/dist/hooks/useRegion/useRegion.d.ts

@@ -0,0 +1,21 @@
+import type { RegionHandle, RegionOptions } from "./useRegion.types";
+/**
+ * Reserve a rectangular region in Ink's layout and write to it
+ * directly via ANSI cursor positioning, bypassing Ink's renderer.
+ *
+ * Attach the returned `ref` to a placeholder `<Box>` with matching
+ * dimensions. Then call `write(lines)` to paint content into that
+ * region without triggering a React / Ink re-render.
+ *
+ * @example
+ * ```tsx
+ * const region = useRegion({ width: 40, height: 20 });
+ *
+ * useEffect(() => {
+ *   region.write(["Hello, world!"]);
+ * }, [region]);
+ *
+ * return <Box ref={region.ref} width={40} height={20} />;
+ * ```
+ */
+export declare function useRegion(options: RegionOptions): RegionHandle;

package/dist/hooks/useRegion/useRegion.types.d.ts

@@ -0,0 +1,41 @@
+import type { DOMElement } from "ink";
+import type React from "react";
+/** Configuration for a direct-write region. */
+export interface RegionOptions {
+    /**
+     * Width of the region in columns.
+     * Use `"auto"` to measure from the parent Box's Yoga layout.
+     */
+    readonly width: number | "auto";
+    /** Height of the region in rows. */
+    readonly height: number;
+}
+/** Measured dimensions of the region's reserved area. */
+export interface RegionDimensions {
+    /** Width in terminal columns. */
+    readonly width: number;
+    /** Height in terminal rows. */
+    readonly height: number;
+}
+/** Absolute position of the region within the terminal. */
+export interface RegionPosition {
+    /** Row offset from the top of Ink's output (0-indexed). */
+    readonly top: number;
+    /** Column offset from the left edge (0-indexed). */
+    readonly left: number;
+}
+/** Handle returned by `useRegion`. */
+export interface RegionHandle {
+    /** Ref to attach to the placeholder `<Box>`. */
+    readonly ref: React.Ref<DOMElement>;
+    /**
+     * Write lines directly to stdout at the region's position.
+     * Each element in `lines` corresponds to one terminal row.
+     * Lines are truncated or padded to the region width.
+     */
+    readonly write: (lines: readonly string[]) => void;
+    /** Current measured dimensions of the region. */
+    readonly dimensions: RegionDimensions;
+    /** Current absolute position of the region within Ink's output. */
+    readonly position: RegionPosition;
+}

package/dist/hooks/useRegion/useRegion.utils.d.ts

@@ -0,0 +1,51 @@
+import { getAbsolutePosition } from "../../utils/yogaLayout";
+export { getAbsolutePosition };
+/** ANSI escape: save cursor position. */
+export declare const CURSOR_SAVE = "\u001B7";
+/** ANSI escape: restore cursor position. */
+export declare const CURSOR_RESTORE = "\u001B8";
+/**
+ * ANSI CUP (Cursor Position) escape — moves cursor to an absolute
+ * row and column. Both are 1-indexed per the ANSI spec.
+ */
+export declare function cursorTo(row: number, col: number): string;
+/**
+ * Build a single string that saves the cursor, writes each line at
+ * the correct absolute position, then restores the cursor.
+ *
+ * @param lines  - Array of pre-formatted line strings (may contain ANSI color codes).
+ * @param top    - 0-indexed row offset of the region's first line within Ink output.
+ * @param left   - 0-indexed column offset of the region's left edge.
+ * @param width  - Region width in columns. Lines shorter than this are right-padded
+ *                 with spaces to clear stale content.
+ */
+export declare function buildRegionOutput(lines: readonly string[], top: number, left: number, width: number): string;
+/**
+ * Strip ANSI escape sequences from a string to calculate its
+ * visible character length.
+ */
+export declare function visibleLength(str: string): number;
+/**
+ * Pad a string to at least `width` visible characters.
+ * ANSI escape sequences are not counted toward the width.
+ *
+ * Note: this does not truncate — use {@link fitToWidth} when you need both
+ * padding and clipping.
+ */
+export declare function padToWidth(str: string, width: number): string;
+/**
+ * Pad or truncate a string to exactly `width` visible characters while
+ * preserving ANSI SGR (color/style) escape sequences.
+ *
+ * - If the visible length is less than `width`, the string is right-padded
+ *   with spaces.
+ * - If the visible length exceeds `width`, the string is clipped at the
+ *   `width`-th visible character. Any ANSI SGR escapes encountered before
+ *   the clip point are preserved verbatim, and a reset (`\x1b[0m`) is
+ *   appended if any escape was emitted, to prevent color bleeding into
+ *   subsequent output.
+ *
+ * @param str   - Input string, possibly containing ANSI SGR escapes.
+ * @param width - Target visible width in columns.
+ */
+export declare function fitToWidth(str: string, width: number): string;

package/dist/hooks/useStrategies/useStrategies.d.ts

@@ -0,0 +1,10 @@
+import { type DiscoveredStrategy } from "@comma-agents/core";
+/**
+ * Discover available strategies once on mount.
+ *
+ * `discoverStrategies()` is async (parses & validates each candidate),
+ * so we kick it off in `useEffect` and store the result in state.
+ * Initial value is an empty array; the picker renders empty for a
+ * single frame and then populates.
+ */
+export declare function useDiscoveredStrategies(): readonly DiscoveredStrategy[];

package/dist/hooks/useToolSpinner/index.d.ts

@@ -0,0 +1 @@
+export { TOOL_SPINNER_FRAMES, TOOL_SPINNER_INTERVAL_MS, useToolSpinner, } from "./useToolSpinner";

package/dist/hooks/useToolSpinner/useToolSpinner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Spinner glyph rotation used to indicate an in-flight tool call.
+ *
+ * Four-frame Braille-style rotation chosen for legibility on dark and
+ * light terminals while staying single-cell wide so it can sit at the
+ * head of a tool-call row without disturbing column alignment.
+ */
+export declare const TOOL_SPINNER_FRAMES: readonly ["◜", "◝", "◞", "◟"];
+/**
+ * Animation interval in milliseconds. 120ms gives a perceptibly active
+ * spin without burning frames or causing terminals to drop redraws.
+ */
+export declare const TOOL_SPINNER_INTERVAL_MS = 120;
+/**
+ * Returns the current tool-spinner frame.
+ *
+ * - When `running` is `false`, the hook returns `null` and never
+ *   subscribes to the shared tick — components rendering completed or
+ *   errored tool calls pay zero re-render cost.
+ * - When `running` is `true`, the hook subscribes to the shared tick
+ *   and re-renders the consuming component every {@link
+ *   TOOL_SPINNER_INTERVAL_MS} ms with the next frame from {@link
+ *   TOOL_SPINNER_FRAMES}.
+ *
+ * The shared interval is reference-counted: it starts when the first
+ * subscriber mounts and stops when the last one unmounts.
+ */
+export declare function useToolSpinner(running: boolean): string | null;

package/dist/hooks/useUserConfig/index.d.ts

@@ -0,0 +1,4 @@
+export { useUserConfig } from "./useUserConfig";
+export { CONFIG_FILE_NAME, CONFIG_SUBDIRECTORY, DEFAULT_USER_CONFIG, resolveConfigRoot, resolveDefaultConfigFilePath, } from "./useUserConfig.constants";
+export { UserConfigContextProvider } from "./useUserConfig.context";
+export type { UserConfig, UserConfigContextProviderProps, UserConfigContextType, } from "./useUserConfig.types";

package/dist/hooks/useUserConfig/useUserConfig.constants.d.ts

@@ -0,0 +1,17 @@
+import type { UserConfig } from "./useUserConfig.types";
+/** Subdirectory under the OS config dir that holds all comma-agents files. */
+export declare const CONFIG_SUBDIRECTORY = "comma-agents";
+/** Filename of the persisted TUI configuration. */
+export declare const CONFIG_FILE_NAME = "tui-config.json";
+/** Defaults applied when no config file exists or fields are missing. */
+export declare const DEFAULT_USER_CONFIG: UserConfig;
+/**
+ * Resolve the platform-appropriate config directory root.
+ *
+ * - macOS: `~/Library/Application Support`
+ * - Windows: `%APPDATA%` (falls back to `~/AppData/Roaming`)
+ * - Linux/other: `$XDG_CONFIG_HOME` or `~/.config`
+ */
+export declare function resolveConfigRoot(): string;
+/** Absolute path to the TUI config file for this user. */
+export declare function resolveDefaultConfigFilePath(): string;

package/dist/hooks/useUserConfig/useUserConfig.context.d.ts

@@ -0,0 +1,9 @@
+import type React from "react";
+import type { UserConfigContextProviderProps, UserConfigContextType } from "./useUserConfig.types";
+export declare const UserConfigContext: React.Context<UserConfigContextType | null>;
+/**
+ * Loads the persisted user config synchronously on first render so the
+ * initial paint already uses the correct theme. Subsequent updates flush
+ * to disk asynchronously via `setConfig` / `updateConfig`.
+ */
+export declare function UserConfigContextProvider({ configFilePath: configFilePathProp, children, }: UserConfigContextProviderProps): React.ReactElement;

package/dist/hooks/useUserConfig/useUserConfig.d.ts

@@ -0,0 +1,9 @@
+import type { UserConfigContextType } from "./useUserConfig.types";
+/**
+ * Access the current user configuration and mutators.
+ *
+ * Must be called from within a `<UserConfigContextProvider>`. Throws when
+ * no provider is present so a missing wiring fails loudly at the call site
+ * rather than surfacing as a confusing `undefined` deeper in rendering.
+ */
+export declare function useUserConfig(): UserConfigContextType;

package/dist/hooks/useUserConfig/useUserConfig.types.d.ts

@@ -0,0 +1,30 @@
+import type { ThemeName } from "../../Theme";
+/**
+ * Persisted user configuration for the TUI.
+ *
+ * Stored as JSON at `{config_dir}/comma-agents/tui-config.json`. New optional
+ * fields can be added without breaking older config files because
+ * `loadUserConfig` merges any partial input over the defaults.
+ */
+export interface UserConfig {
+    /** Active theme name. */
+    readonly themeName: ThemeName;
+}
+/** Public hook return type / React context value. */
+export interface UserConfigContextType {
+    /** Current resolved user config (defaults merged in). */
+    readonly config: UserConfig;
+    /** Replace the config entirely. Persists to disk asynchronously. */
+    readonly setConfig: (next: UserConfig) => void;
+    /** Patch a subset of the config and persist. */
+    readonly updateConfig: (patch: Partial<UserConfig>) => void;
+    /** Absolute path to the config file on disk. */
+    readonly configFilePath: string;
+}
+/** Props for `UserConfigContextProvider`. */
+export interface UserConfigContextProviderProps {
+    /** Optional override for the config file path (used in tests). */
+    readonly configFilePath?: string;
+    /** Child components that can consume the user config. */
+    readonly children: React.ReactNode;
+}

package/dist/hooks/useUserConfig/useUserConfig.utils.d.ts

@@ -0,0 +1,19 @@
+import type { UserConfig } from "./useUserConfig.types";
+/**
+ * Sanitize a parsed JSON object into a valid `UserConfig`. Unknown or
+ * mistyped fields fall back to defaults so old config files keep working
+ * after schema additions.
+ */
+export declare function normalizeUserConfig(raw: unknown): UserConfig;
+/**
+ * Synchronously load the config file from disk. Returns defaults when the
+ * file does not exist or fails to parse — startup must never crash because
+ * of a corrupt config.
+ */
+export declare function loadUserConfig(filePath: string): UserConfig;
+/**
+ * Persist the config file to disk, creating the parent directory as needed.
+ * Errors are swallowed so a read-only filesystem cannot crash the TUI — the
+ * in-memory state remains correct for the current session.
+ */
+export declare function saveUserConfig(filePath: string, config: UserConfig): void;

package/dist/hooks/useWebSocket/index.d.ts

@@ -0,0 +1,2 @@
+export { useWebSocket } from "./useWebSocket";
+export type { UseWebSocketConfig, WebSocketState, WebSocketStatus, } from "./useWebSocket.types";

package/dist/hooks/useWebSocket/useWebSocket.d.ts

@@ -0,0 +1,17 @@
+import type { UseWebSocketConfig, WebSocketState } from "./useWebSocket.types";
+/**
+ * Generic WebSocket connection hook.
+ *
+ * Connects eagerly on mount, reconnects after dropped connections, and
+ * disconnects on unmount. Reconnects immediately when the `url` changes.
+ *
+ * @param config - Connection configuration including URL and event callbacks.
+ * @example
+ * ```tsx
+ * const { status, send } = useWebSocket({
+ *   url: "ws://localhost:7422/ws",
+ *   onMessage: (data) => console.log("received", data),
+ * });
+ * ```
+ */
+export declare function useWebSocket(config: UseWebSocketConfig): WebSocketState;

package/dist/hooks/useWebSocket/useWebSocket.types.d.ts

@@ -0,0 +1,27 @@
+/** Lifecycle states of a WebSocket connection. */
+export type WebSocketStatus = "disconnected" | "connecting" | "connected" | "error";
+/** Configuration for the `useWebSocket` hook. */
+export interface UseWebSocketConfig {
+    /** WebSocket endpoint URL (e.g. "ws://localhost:7422/ws"). */
+    readonly url: string;
+    /** Delay before reconnecting after a dropped connection. Default: 2000ms. */
+    readonly reconnectDelayMs?: number;
+    /** Called with every incoming message (raw string data). */
+    readonly onMessage: (data: string) => void;
+    /** Called when the connection status changes. */
+    readonly onStatus?: (status: WebSocketStatus) => void;
+    /** Called when a connection attempt reports an error. */
+    readonly onError?: (error: string) => void;
+}
+/** Return value of the `useWebSocket` hook. */
+export interface WebSocketState {
+    /** Current connection lifecycle status. */
+    readonly status: WebSocketStatus;
+    /**
+     * Send a string payload over the socket.
+     * Returns `true` if the message was sent or queued while connecting.
+     */
+    readonly send: (data: string) => boolean;
+    /** Manually close the connection and stop reconnecting. */
+    readonly close: () => void;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { runTui } from "./run-tui";
+export type { RunTuiOptions, TuiInstance } from "./run-tui.types";