@comma-agents/tui 2.0.0-rc.0

package/dist/hooks/useDaemon/useDaemon.d.ts

@@ -0,0 +1,7 @@
+import type { DaemonContextValue } from "./useDaemon.types";
+/**
+ * Access the daemon context.
+ *
+ * Must be called inside a `<DaemonContextProvider>`. Throws if used outside.
+ */
+export declare function useDaemon(): DaemonContextValue;

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

@@ -0,0 +1,62 @@
+import type { ClientMessage, DaemonMessage } from "@comma-agents/daemon";
+import type { WebSocketStatus } from "../useWebSocket/useWebSocket.types";
+/**
+ * Force TypeScript to eagerly expand a mapped/conditional type.
+ *
+ * Without this, utility types like `Omit<Extract<...>>` show as-is
+ * in hover tooltips instead of the resolved object shape.
+ */
+export type Simplify<ObjectType> = {
+    [Key in keyof ObjectType]: ObjectType[Key];
+} & {};
+/** Extracts the `type` literal from a DaemonMessage variant. */
+export type DaemonMessageType = DaemonMessage["type"];
+/** Extracts the `type` literal from a ClientMessage variant. */
+export type ClientMessageType = ClientMessage["type"];
+/**
+ * Narrow a DaemonMessage to the variant matching a specific `type`.
+ *
+ * Example: `DaemonMessageOf<"agent_streaming">` resolves to the
+ * `AgentStreamingMessage` branch of the union.
+ */
+export type DaemonMessageOf<MessageKind extends DaemonMessageType> = Simplify<Extract<DaemonMessage, {
+    type: MessageKind;
+}>>;
+/**
+ * Narrow a ClientMessage to the variant matching a specific `type`.
+ *
+ * Example: `ClientMessageOf<"prepare_run">` resolves to the
+ * `PrepareRunMessage` branch of the union.
+ */
+export type ClientMessageOf<CommandKind extends ClientMessageType> = Simplify<Extract<ClientMessage, {
+    type: CommandKind;
+}>>;
+/**
+ * Callback for a specific daemon message type.
+ * Receives the narrowed message variant — not the full union.
+ */
+export type DaemonMessageListener<MessageKind extends DaemonMessageType> = (message: DaemonMessageOf<MessageKind>) => void;
+/** Props for the DaemonContextProvider component. */
+export interface DaemonContextProviderProps {
+    /** WebSocket URL for the daemon (e.g. "ws://localhost:7422/ws"). */
+    readonly url: string;
+    /** Child elements. */
+    readonly children: React.ReactNode;
+}
+/** Value exposed by the DaemonContext. */
+export interface DaemonContextValue {
+    /** Current connection status. */
+    readonly status: WebSocketStatus;
+    /**
+     * Send a raw client message object to the daemon.
+     * Returns false if the WebSocket is not open.
+     */
+    readonly send: (message: Record<string, unknown>) => boolean;
+    /**
+     * Register a listener for a specific daemon message type.
+     * Returns an unsubscribe function.
+     */
+    readonly on: <MessageKind extends DaemonMessageType>(type: MessageKind, listener: DaemonMessageListener<MessageKind>) => () => void;
+    /** Remove a previously registered listener. */
+    readonly off: <MessageKind extends DaemonMessageType>(type: MessageKind, listener: DaemonMessageListener<MessageKind>) => void;
+}

package/dist/hooks/useDaemon/useDaemonCommand/index.d.ts

@@ -0,0 +1,2 @@
+export { useDaemonCommand } from "./useDaemonCommand";
+export type { DaemonCommandMap, DaemonCommandType, } from "./useDaemonCommand.types";

package/dist/hooks/useDaemon/useDaemonCommand/useDaemonCommand.d.ts

@@ -0,0 +1,20 @@
+import type { DaemonCommandMap, DaemonCommandType } from "./useDaemonCommand.types";
+/**
+ * React hook that returns a function to send a specific command type
+ * to the daemon over the shared WebSocket.
+ *
+ * The returned function auto-injects the `type` discriminant and a
+ * fresh `requestId` (UUID). It returns the `requestId` so the caller
+ * can correlate responses if needed.
+ *
+ * Returns `null` instead of a `requestId` when the send fails
+ * (e.g. WebSocket not connected).
+ *
+ * @param type - The daemon command type to send.
+ * @example
+ * ```tsx
+ * const prepareRun = useDaemonCommand("prepare_run");
+ * const reqId = prepareRun({ strategyPath: "/path/plan.json" });
+ * ```
+ */
+export declare function useDaemonCommand<CommandKind extends DaemonCommandType>(type: CommandKind): (payload: DaemonCommandMap[CommandKind]) => string | null;

package/dist/hooks/useDaemon/useDaemonCommand/useDaemonCommand.types.d.ts

@@ -0,0 +1,28 @@
+import type { ClientMessage } from "@comma-agents/daemon";
+import type { Simplify } from "../useDaemon.types";
+/**
+ * Maps each client command type to its payload shape.
+ *
+ * Auto-derived from the `ClientMessage` discriminated union — stays in
+ * sync with daemon protocol changes. The `type` and `requestId` fields
+ * are stripped because they are auto-injected by `useDaemonCommand`.
+ *
+ * @example
+ * ```ts
+ * DaemonCommandMap["prepare_run"]
+ * // → { strategyPath: string; input?: string | undefined }
+ *
+ * DaemonCommandMap["ping"]
+ * // → {}
+ *
+ * DaemonCommandMap["user_input"]
+ * // → { runId: string; agentName: string; text: string }
+ * ```
+ */
+export type DaemonCommandMap = {
+    [CommandKind in ClientMessage["type"]]: Simplify<Omit<Extract<ClientMessage, {
+        type: CommandKind;
+    }>, "type" | "requestId">>;
+};
+/** All valid daemon command names. */
+export type DaemonCommandType = keyof DaemonCommandMap;

package/dist/hooks/useDaemon/useDaemonSubscription/index.d.ts

@@ -0,0 +1 @@
+export { useDaemonSubscription } from "./useDaemonSubscription";

package/dist/hooks/useDaemon/useDaemonSubscription/useDaemonSubscription.d.ts

@@ -0,0 +1,18 @@
+import type { DaemonMessageListener, DaemonMessageType } from "../useDaemon.types";
+/**
+ * React hook that registers a listener for a specific daemon message type.
+ *
+ * The callback receives the narrowed message variant (not the full union).
+ * When `runId` is provided, only messages matching that `runId` are
+ * forwarded — messages without a `runId` field are always forwarded.
+ *
+ * The listener is automatically removed on unmount or when dependencies
+ * change. The callback ref is kept stable so consumers don't need to
+ * wrap their handler in `useCallback`.
+ *
+ * @param type    - Daemon message type to listen for (e.g. "agent_streaming").
+ * @param callback - Handler invoked per matching message.
+ * @param runId   - Optional run ID filter. When set, only messages whose
+ *                  `runId` matches are forwarded.
+ */
+export declare function useDaemonSubscription<MessageKind extends DaemonMessageType>(type: MessageKind, callback: DaemonMessageListener<MessageKind>, runId?: string | null, enabled?: boolean): void;

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

@@ -0,0 +1,2 @@
+export { useDebugRender } from "./useDebugRender";
+export type { BoundingBox, DebugRenderColors, DebugRenderOptions, DebugRenderRef, RenderReason, } from "./useDebugRender.types";

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

@@ -0,0 +1,18 @@
+import type { RenderReason } from "./useDebugRender.types";
+/** How long the colored highlight stays visible before being cleared. */
+export declare const FLASH_DURATION_MS = 200;
+/** ANSI reset sequence. */
+export declare const ANSI_RESET = "\u001B[0m";
+/** ANSI SGR foreground color codes for the border outline. */
+export declare const DEFAULT_BG_COLORS: Record<RenderReason, string>;
+/** ANSI SGR codes for each label pill (background + contrasting foreground). */
+export declare const DEFAULT_LABEL_COLORS: Record<RenderReason, string>;
+/** Unicode box-drawing characters for the border outline. */
+export declare const BORDER_CHARS: {
+    readonly topLeft: "┌";
+    readonly topRight: "┐";
+    readonly bottomLeft: "└";
+    readonly bottomRight: "┘";
+    readonly horizontal: "─";
+    readonly vertical: "│";
+};

package/dist/hooks/useDebugRender/useDebugRender.d.ts

@@ -0,0 +1,35 @@
+import type { DebugRenderOptions, DebugRenderRef } from "./useDebugRender.types";
+/**
+ * Attach a cursor-drawn debug overlay to a component that briefly
+ * highlights the entire bounding box with a colored background tint
+ * and draws a label showing all detected render reasons as pills.
+ *
+ * Returns a `ref` callback to attach to the component's root `<Box>`.
+ * When `DEBUG_RENDER` is `false` the ref is a no-op and no effects run.
+ *
+ * Default color legend:
+ * - **Cyan**    — mount (first render)
+ * - **Red**     — unmount
+ * - **Magenta** — props changed
+ * - **Green**   — state changed (no prop diff detected)
+ * - **White**   — context changed (no prop/state diff)
+ * - **Yellow**  — generic re-render (always present)
+ *
+ * @param label   - Component name shown in the overlay.
+ * @param options - Props for diffing, custom colors, flash duration.
+ *
+ * @example
+ * ```tsx
+ * const debug = useDebugRender("MyComponent", { props: { count, name } });
+ * return <Box ref={debug.ref}>content</Box>;
+ *
+ * const debug = useDebugRender("HotPath", {
+ *   props: { data },
+ *   colors: {
+ *     bg:    { props: "\x1b[48;5;208m" },
+ *     label: { props: "\x1b[48;5;208;30m" },
+ *   },
+ * });
+ * ```
+ */
+export declare function useDebugRender(label: string, options?: DebugRenderOptions): DebugRenderRef;

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

@@ -0,0 +1,60 @@
+import type { DOMElement } from "ink";
+export type { BoundingBox } from "../../utils/yogaLayout";
+/**
+ * Every detectable reason a component rendered.
+ * Multiple can be true simultaneously (e.g. props changed *and* rerender).
+ */
+export type RenderReason = "mount" | "unmount" | "props" | "state" | "context" | "rerender";
+/**
+ * Custom ANSI SGR color strings keyed by render reason.
+ * Any reason not specified falls back to the built-in default.
+ *
+ * Each value should be a raw SGR sequence like `"\x1b[48;5;208m"` (bg only)
+ * or `"\x1b[48;5;208;30m"` (bg + fg).
+ */
+export interface DebugRenderColors {
+    /** Background-only SGR for the full-region tint. */
+    readonly bg?: Partial<Record<RenderReason, string>>;
+    /** Background + foreground SGR for the label pill. */
+    readonly label?: Partial<Record<RenderReason, string>>;
+}
+/** Configuration for `useDebugRender`. */
+export interface DebugRenderOptions {
+    /**
+     * The component's current props object.
+     * Passed each render so the hook can shallow-diff to detect prop changes.
+     */
+    readonly props?: Record<string, unknown>;
+    /**
+     * Override the default color palette for this component.
+     * Useful for distinguishing specific components at a glance.
+     */
+    readonly colors?: DebugRenderColors;
+    /**
+     * Flash duration override in milliseconds. @default 200
+     */
+    readonly flashMs?: number;
+    /**
+     * Toggle individual render-reason overlays on or off.
+     * Any reason not specified defaults to `true` (enabled).
+     *
+     * @example
+     * ```ts
+     * // Only show mount and props flashes, suppress everything else
+     * useDebugRender("MyComponent", {
+     *   enabled: { mount: true, props: true, unmount: false, state: false, context: false, rerender: false },
+     * });
+     * ```
+     */
+    readonly enabled?: Partial<Record<RenderReason, boolean>>;
+    /**
+     * Whether to draw the colored border outline around the component's
+     * bounding box. When `false`, only the label pills are shown.
+     * @default true
+     */
+    readonly showBackground?: boolean;
+}
+/** Ref handle returned by `useDebugRender`. Attach to the root `<Box>`. */
+export interface DebugRenderRef {
+    readonly ref: React.RefCallback<DOMElement>;
+}

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

@@ -0,0 +1,34 @@
+import type { DOMElement } from "ink";
+import { getBoundingBox } from "../../utils/yogaLayout";
+import type { RenderReason } from "./useDebugRender.types";
+export { getBoundingBox };
+/** Build one ANSI-colored pill for a single reason. */
+export declare function buildPill(reason: RenderReason, labelSgr: string): string;
+/**
+ * Build the full label line: component name, render count, then a
+ * colored pill for every detected reason.
+ */
+export declare function buildLabelLine(name: string, count: number, reasons: readonly RenderReason[], labelColors: Record<RenderReason, string>): string;
+/** Visible character width of the full label line (for clearing). */
+export declare function labelLineVisibleWidth(name: string, count: number, reasons: readonly RenderReason[]): number;
+/**
+ * Draw a colored border outline around the bounding box and overlay
+ * the label line on the top edge. The border is drawn with Unicode
+ * box-drawing characters so existing content inside is preserved.
+ */
+export declare function paintHighlight(stdout: NodeJS.WriteStream, node: DOMElement, reasons: readonly RenderReason[], labelLine: string, bgColors: Record<RenderReason, string>, showBackground: boolean): void;
+/** Clear just the label text on the first row. */
+export declare function clearLabelLine(stdout: NodeJS.WriteStream, node: DOMElement, visibleWidth: number): void;
+/** Clear the border outline by overwriting border cells with spaces. */
+export declare function clearHighlight(stdout: NodeJS.WriteStream, node: DOMElement): void;
+/**
+ * Collect all applicable reasons for this render cycle.
+ * Returns them sorted by priority (most specific first).
+ */
+export declare function detectReasons(isMounted: boolean, props: Record<string, unknown> | undefined, previousProps: Record<string, unknown> | undefined): RenderReason[];
+/** Remove reasons that the caller has explicitly disabled. */
+export declare function filterReasons(reasons: readonly RenderReason[], enabled?: Partial<Record<RenderReason, boolean>>): RenderReason[];
+/** Merge user-provided background color overrides with defaults. */
+export declare function mergeBackgroundColors(overrides?: Partial<Record<RenderReason, string>>): Record<RenderReason, string>;
+/** Merge user-provided label color overrides with defaults. */
+export declare function mergeLabelColors(overrides?: Partial<Record<RenderReason, string>>): Record<RenderReason, string>;

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

@@ -0,0 +1,3 @@
+export { createLogStore, logStore } from "./logStore";
+export { useLogs } from "./useLogs";
+export type { LogEntry, LogLevel, LogStore, LogStoreListener, LogsState, } from "./useLogs.types";

package/dist/hooks/useLogs/logStore.d.ts

@@ -0,0 +1,18 @@
+import type { LogStore } from "./useLogs.types";
+/**
+ * Create a log store that hijacks global console methods immediately.
+ *
+ * The store starts in **pass-through mode**: every console call is buffered
+ * into the store AND forwarded to the original terminal output (stderr/stdout).
+ * This ensures that startup errors — import failures, TTY errors, etc. — are
+ * still visible in the terminal if the app crashes before the UI renders.
+ *
+ * Once the app has successfully rendered, call {@link LogStore.commit} to
+ * switch to **capture mode**. After that point all console output is captured
+ * exclusively into the store; the Logs tab is the only place to view it.
+ *
+ * @param maxEntries - Maximum number of entries to retain. @default 500
+ */
+export declare function createLogStore(maxEntries?: number): LogStore;
+/** Singleton log store, created at module load time so no console calls are missed. */
+export declare const logStore: LogStore;

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

@@ -0,0 +1,2 @@
+/** Maximum number of log entries to retain in memory. */
+export declare const MAX_LOG_ENTRIES = 500;

package/dist/hooks/useLogs/useLogs.d.ts

@@ -0,0 +1,15 @@
+import type { LogsState } from "./useLogs.types";
+/**
+ * Subscribe to the global log store that captures console output.
+ *
+ * The store is shared across the whole app and is created once at module
+ * load time. Every component that calls this hook re-renders whenever a new
+ * log entry is appended.
+ *
+ * @example
+ * ```tsx
+ * const { logs, clearLogs } = useLogs();
+ * return <Text>{logs.length} entries</Text>;
+ * ```
+ */
+export declare function useLogs(): LogsState;

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

@@ -0,0 +1,47 @@
+/** Severity level for a captured log entry. */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "log";
+/** A single captured console log entry. */
+export interface LogEntry {
+    /** Unique identifier for the log entry. */
+    readonly id: string;
+    /** Timestamp when the log was captured. */
+    readonly timestamp: number;
+    /** The severity level of the log. */
+    readonly level: LogLevel;
+    /** The stringified log message. */
+    readonly message: string;
+}
+/** Callback invoked when the log store contents change. */
+export type LogStoreListener = () => void;
+/** Module-level log store that captures console output. */
+export interface LogStore {
+    /** Returns the current snapshot of all log entries. */
+    readonly getSnapshot: () => readonly LogEntry[];
+    /** Registers a listener notified on every log change. Returns an unsubscribe function. */
+    readonly subscribe: (listener: LogStoreListener) => () => void;
+    /** Push a log entry directly into the store (bypasses console interception). */
+    readonly push: (level: LogLevel, message: string) => void;
+    /** Clears all captured logs. */
+    readonly clear: () => void;
+    /**
+     * Switches from pass-through mode to full capture mode.
+     *
+     * During startup the store buffers log entries AND forwards them to the
+     * original terminal output so that errors are visible if the app crashes
+     * before the UI renders. Call `commit()` once the app is ready — after that
+     * point all console output is captured exclusively into the store and the
+     * Logs tab is the only place to view it.
+     */
+    readonly commit: () => void;
+    /** Whether the store has been committed (true) or is still in pass-through mode. */
+    readonly isCommitted: () => boolean;
+    /** Restores original console methods and stops capturing. */
+    readonly destroy: () => void;
+}
+/** Return value of the useLogs hook. */
+export interface LogsState {
+    /** All captured log entries, oldest first. */
+    readonly logs: readonly LogEntry[];
+    /** Clears all captured logs. */
+    readonly clearLogs: () => void;
+}

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

@@ -0,0 +1,13 @@
+/** Generate a unique sequential log entry ID. */
+export declare function nextLogId(): string;
+/**
+ * Stringify console arguments into a single space-separated message.
+ *
+ * Strings are passed through verbatim. Everything else is rendered with
+ * `util.inspect`, which handles `Error` instances, circular references,
+ * `Symbol`, `BigInt`, and class instances cleanly — JSON.stringify would
+ * either throw or strip these.
+ */
+export declare function formatArgs(args: readonly unknown[]): string;
+/** @internal Reset the log id counter. Test-only. */
+export declare function _resetLogIdCounterForTests(): void;

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

@@ -0,0 +1,3 @@
+export { useModal } from "./useModal";
+export { ModalContextProvider } from "./useModal.context";
+export type { ModalContextProviderProps, ModalContextType, ModalControls, ModalEntry, ModalId, } from "./useModal.types";

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

@@ -0,0 +1,20 @@
+import type React from "react";
+import type { ModalContextProviderProps, ModalContextType } from "./useModal.types";
+export declare const ModalContext: React.Context<ModalContextType>;
+/**
+ * Provides a shared modal registry so any descendant can open, close,
+ * or query modals by id without prop-drilling.
+ *
+ * Tracks an ordered stack of open modals — the last id in the stack is the
+ * topmost modal and is the only one that should receive input and respond
+ * to Esc.
+ *
+ * @param props - Provider props containing children.
+ * @example
+ * ```tsx
+ * <ModalContextProvider>
+ *   <App />
+ * </ModalContextProvider>
+ * ```
+ */
+export declare function ModalContextProvider(props: ModalContextProviderProps): React.ReactElement;

package/dist/hooks/useModal/useModal.d.ts

@@ -0,0 +1,22 @@
+import type { ModalControls, ModalId } from "./useModal.types";
+/**
+ * Programmatic controls for a specific modal identified by its id.
+ *
+ * Reads from the nearest `<ModalContextProvider>`. When called outside any
+ * provider — most notably inside the detached `measureLayout` tree — the
+ * context falls back to an inert no-op API so components render
+ * structurally without crashing. In the live app the provider always wins.
+ *
+ * @param modalId - Unique identifier for the modal to control.
+ * @example
+ * ```tsx
+ * const confirmModal = useModal("confirm-delete");
+ *
+ * // Open with data
+ * confirmModal.open({ itemId: 42 });
+ *
+ * // Close
+ * confirmModal.close();
+ * ```
+ */
+export declare function useModal(modalId: ModalId): ModalControls;

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

@@ -0,0 +1,49 @@
+import type React from "react";
+/** Unique identifier for a registered modal. */
+export type ModalId = string;
+/** State of a single modal instance. */
+export interface ModalEntry {
+    /** Whether this modal is currently visible. */
+    readonly isOpen: boolean;
+    /** Arbitrary data passed when opening the modal. */
+    readonly data: unknown;
+}
+/** Controls returned by the `useModal` consumer hook. */
+export interface ModalControls {
+    /** Whether this modal is currently visible. */
+    readonly isOpen: boolean;
+    /** Whether this modal is the topmost currently open modal. */
+    readonly isTopmost: boolean;
+    /** Arbitrary data passed via `open(data)`. */
+    readonly data: unknown;
+    /** Show the modal, optionally passing data to it. */
+    readonly open: (data?: unknown) => void;
+    /** Hide the modal and clear its data. */
+    readonly close: () => void;
+    /** Toggle visibility. */
+    readonly toggle: (data?: unknown) => void;
+}
+/** Shape of the modal registry context value. */
+export interface ModalContextType {
+    /** Map of all registered modal states keyed by id. */
+    readonly modals: ReadonlyMap<ModalId, ModalEntry>;
+    /** Ordered stack of currently open modal ids; last element is topmost. */
+    readonly openStack: readonly ModalId[];
+    /** Open a modal by id, optionally passing data. */
+    readonly open: (modalId: ModalId, data?: unknown) => void;
+    /** Close a modal by id. */
+    readonly close: (modalId: ModalId) => void;
+    /** Toggle a modal by id. */
+    readonly toggle: (modalId: ModalId, data?: unknown) => void;
+    /** Check whether a modal is open. */
+    readonly isOpen: (modalId: ModalId) => boolean;
+    /** Check whether a modal is the topmost open modal. */
+    readonly isTopmost: (modalId: ModalId) => boolean;
+    /** Retrieve the data for a modal. */
+    readonly getData: (modalId: ModalId) => unknown;
+}
+/** Props for the ModalContextProvider component. */
+export interface ModalContextProviderProps {
+    /** Child components that can consume the modal context. */
+    readonly children: React.ReactNode;
+}

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

@@ -0,0 +1,2 @@
+export type { MouseEvent, MouseEventKind, MouseModifiers, } from "./useMouse.types";
+export { isInsideRef, isMouseEscape, parseMouseEvents, SGR_MOUSE_PREFIX, SGR_MOUSE_TAIL_PATTERN, } from "./useMouse.utils";

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

@@ -0,0 +1,43 @@
+/**
+ * The kind of SGR mouse event received from the terminal.
+ *
+ * - `"press"`      — button pressed (terminator `M`, non-wheel, non-motion).
+ * - `"release"`    — button released (terminator `m`, non-wheel).
+ * - `"move"`       — cursor motion with no button held (requires `?1003h`).
+ * - `"drag"`       — cursor motion while a button is held (`?1002h`/`?1003h`).
+ * - `"wheel-up"`   — mouse wheel scrolled up (button 64).
+ * - `"wheel-down"` — mouse wheel scrolled down (button 65).
+ */
+export type MouseEventKind = "press" | "release" | "move" | "drag" | "wheel-up" | "wheel-down";
+/**
+ * Keyboard modifier keys held at the time of a mouse event.
+ * Encoded in the SGR button byte: shift=bit2, meta=bit3, ctrl=bit4.
+ */
+export interface MouseModifiers {
+    readonly shift: boolean;
+    readonly meta: boolean;
+    readonly ctrl: boolean;
+}
+/**
+ * A single parsed SGR (1006) mouse event.
+ *
+ * Coordinates are **1-indexed absolute terminal cells**, matching the
+ * values emitted by the terminal. Column 1 is the leftmost column;
+ * row 1 is the topmost row.
+ */
+export interface MouseEvent {
+    /** What kind of event this is. */
+    readonly kind: MouseEventKind;
+    /**
+     * Which mouse button triggered the event.
+     * `0` = left, `1` = middle, `2` = right.
+     * `null` for motion-without-button and wheel events.
+     */
+    readonly button: 0 | 1 | 2 | null;
+    /** 1-indexed column (horizontal position) in terminal cells. */
+    readonly column: number;
+    /** 1-indexed row (vertical position) in terminal cells. */
+    readonly row: number;
+    /** Keyboard modifiers held at the time of the event. */
+    readonly modifiers: MouseModifiers;
+}

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

@@ -0,0 +1,30 @@
+import type { DOMElement } from "ink";
+import type React from "react";
+import { isMouseEscape, SGR_MOUSE_PREFIX, SGR_MOUSE_TAIL_PATTERN } from "../../utils/mouseEscape";
+import type { MouseEvent } from "./useMouse.types";
+/**
+ * Parse all SGR (1006) mouse events bundled into a single `useInput` chunk.
+ *
+ * Node's stdin decoder can group several rapid mouse events into one string.
+ * This function walks the chunk and returns every event found, in order.
+ * Non-mouse input yields an empty array (fast-path via prefix check).
+ */
+export declare function parseMouseEvents(input: string): readonly MouseEvent[];
+/**
+ * Return `true` when the terminal cell (`column`, `row`) falls inside the
+ * bounding box of the element referenced by `ref`.
+ *
+ * Coordinates follow SGR convention: **1-indexed**. The Yoga layout values
+ * from `getBoundingBox` are **0-indexed**, so we convert: a SGR column of 1
+ * corresponds to Yoga left of 0.
+ *
+ * The test is inclusive-low / exclusive-high on both axes, matching standard
+ * AABB convention:
+ * ```
+ * left <= col0 < left + width
+ * top  <= row0 < top  + height
+ * ```
+ * Returns `false` when the ref is not yet mounted (`ref.current` is `null`).
+ */
+export declare function isInsideRef(ref: React.RefObject<DOMElement | null>, column: number, row: number): boolean;
+export { isMouseEscape, SGR_MOUSE_PREFIX, SGR_MOUSE_TAIL_PATTERN };

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

@@ -0,0 +1,2 @@
+export { useMouseClick } from "./useMouseClick";
+export type { UseMouseClickOptions } from "./useMouseClick.types";

package/dist/hooks/useMouseClick/useMouseClick.d.ts

@@ -0,0 +1,23 @@
+import type { UseMouseClickOptions } from "./useMouseClick.types";
+/**
+ * Fire a callback when the user clicks inside a specific element.
+ *
+ * Works under the existing `?1000h` / `?1006h` mouse mode that {@link Frame}
+ * enables by default — no motion tracking (`?1003h`) required.
+ * Wrap the component tree in `<MouseProvider>` (done by `<Frame>`) before
+ * using this hook.
+ *
+ * Only `press` events are surfaced (not release or drag). AABB hit-testing
+ * runs on every press event by walking the Yoga layout tree.
+ *
+ * **Click-to-focus pattern:**
+ * ```tsx
+ * const ref = useRef<DOMElement>(null);
+ * const { focus } = useFocusManager();
+ * useMouseClick({ ref, onClick: () => focus(myId) });
+ * return <Box ref={ref}>...</Box>;
+ * ```
+ *
+ * @param options - See {@link UseMouseClickOptions}.
+ */
+export declare function useMouseClick({ ref, onClick, buttons, }: UseMouseClickOptions): void;

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

@@ -0,0 +1,28 @@
+import type { DOMElement } from "ink";
+import type React from "react";
+import type { MouseEvent } from "../useMouse/useMouse.types";
+/**
+ * Options accepted by {@link useMouseClick}.
+ */
+export interface UseMouseClickOptions {
+    /**
+     * Ref to the `DOMElement` (Ink `<Box>` or similar) whose bounds are used
+     * for hit-testing. The element must be mounted before click events fire.
+     */
+    readonly ref: React.RefObject<DOMElement | null>;
+    /**
+     * Called when a mouse button press event hits the element's bounding box.
+     * Receives the full {@link MouseEvent} so the caller can inspect which
+     * button was pressed and what modifier keys were held.
+     */
+    readonly onClick: (event: MouseEvent) => void;
+    /**
+     * Which button indices trigger `onClick`. Defaults to `[0]` (left button
+     * only). Pass `[0, 1, 2]` to react to any button.
+     *
+     * `0` = left, `1` = middle, `2` = right.
+     *
+     * @default [0]
+     */
+    readonly buttons?: readonly (0 | 1 | 2)[];
+}

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

@@ -0,0 +1,2 @@
+export { useMouseHover } from "./useMouseHover";
+export type { UseMouseHoverOptions, UseMouseHoverResult, } from "./useMouseHover.types";