jeopi-cli 16.2.14 → 16.2.17

package/dist/types/tts/models.d.ts

@@ -0,0 +1,82 @@
+import type { TinyModelDtype } from "../tiny/dtype";
+/**
+ * Voice exposed by a local TTS model. Kokoro ships a fixed catalog of named
+ * voices; a voice is just a stable id (e.g. `af_heart`) plus a display label.
+ * Selection is purely on-device — generating with a different voice needs no
+ * extra network fetch once the model weights are cached.
+ */
+export interface TtsLocalVoiceSpec {
+    id: string;
+    label: string;
+}
+/**
+ * A local (on-device, ONNX) text-to-speech model the worker can load. `repo` is
+ * the Hugging Face model id loaded through `kokoro-js`
+ * (`KokoroTTS.from_pretrained`), which runs on the same `@huggingface/transformers`
+ * + `onnxruntime` runtime as the rest of the tiny-model stack and bundles the
+ * misaki/espeak phonemizer Kokoro needs. `dtype` is the default ONNX precision
+ * (overridable via `providers.tinyModelDtype`/`PI_TINY_DTYPE`).
+ */
+export interface TtsLocalModelSpec {
+    key: string;
+    repo: string;
+    dtype: TinyModelDtype;
+    /** PCM sample rate the model emits; fallback only — the worker uses the value RawAudio reports. */
+    sampleRate: number;
+    label: string;
+    description: string;
+    /** First entry is the model's default voice. */
+    voices: readonly TtsLocalVoiceSpec[];
+}
+/**
+ * Curated Kokoro-82M voice catalog. Kokoro ships ~28 voices; we surface the
+ * higher-graded ones across American/British × female/male so the picker stays
+ * useful without listing every D/F-grade sample. `af_heart` (grade A) leads and
+ * is the default voice. Grades are Kokoro's own `overallGrade` ratings.
+ */
+export declare const KOKORO_VOICES: readonly TtsLocalVoiceSpec[];
+/** Default voice within the default model — Kokoro's flagship grade-A voice. */
+export declare const DEFAULT_TTS_VOICE = "af_heart";
+/** Default local TTS model used when `tts.localModel` is unset. */
+export declare const DEFAULT_TTS_LOCAL_MODEL_KEY = "kokoro";
+/**
+ * Local TTS model registry. Kokoro-82M is the on-device SoTA tiny TTS (tops the
+ * TTS Arena leaderboard); the `onnx-community` ONNX export runs through
+ * `kokoro-js` on the shared transformers.js/onnxruntime worker. q8 keeps the
+ * weights ~100 MB and CPU inference fast while preserving quality. One model
+ * spans every voice/accent — language selection is a voice choice, not a
+ * separate download.
+ */
+export declare const TTS_LOCAL_MODELS: readonly [{
+    readonly key: "kokoro";
+    readonly repo: "onnx-community/Kokoro-82M-v1.0-ONNX";
+    readonly dtype: "q8";
+    readonly sampleRate: 24000;
+    readonly label: "Kokoro-82M";
+    readonly description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local";
+    readonly voices: readonly TtsLocalVoiceSpec[];
+}];
+export type TtsLocalModelKey = (typeof TTS_LOCAL_MODELS)[number]["key"];
+export declare const TTS_LOCAL_MODEL_VALUES: readonly ["kokoro"];
+export declare const TTS_LOCAL_MODEL_OPTIONS: readonly [{
+    readonly value: "kokoro";
+    readonly label: "Kokoro-82M";
+    readonly description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local";
+}];
+/** Voice options for the `tts.localVoice` setting picker (default model's catalog). */
+export declare const TTS_LOCAL_VOICE_OPTIONS: ReadonlyArray<{
+    value: string;
+    label: string;
+}>;
+/** Accepted `tts.localVoice` values (default model's catalog) for schema validation. */
+export declare const TTS_LOCAL_VOICE_VALUES: readonly string[];
+export declare function getTtsLocalModelSpec(key: string): TtsLocalModelSpec | undefined;
+export declare function isTtsLocalModelKey(value: string): value is TtsLocalModelKey;
+/** Resolve a model key (or the default) to its Hugging Face repo id. */
+export declare function resolveTtsRepo(modelKey: string | undefined): string;
+/**
+ * Resolve a requested voice id to a concrete voice the model supports, falling
+ * back to the model's default voice (first entry) when the id is unknown or the
+ * legacy `"default"` sentinel. The returned id is always a valid Kokoro voice.
+ */
+export declare function resolveTtsVoice(modelKey: string | undefined, voice: string | undefined): string;

package/dist/types/tts/player.d.ts

@@ -0,0 +1,32 @@
+export interface PlayerCommand {
+    cmd: string;
+    args: string[];
+}
+/** Injection seam for {@link playerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface PlayerLookup {
+    which?: (bin: string) => string | null;
+    ffmpeg?: () => string | null;
+}
+/**
+ * Build the ordered list of playback commands to try for `filePath` on the
+ * given platform. Pure + injectable so the selection logic is testable without
+ * spawning anything.
+ *
+ * - darwin: `afplay` (always present on macOS).
+ * - win32: PowerShell `Media.SoundPlayer.PlaySync()` (no extra deps).
+ * - linux/other POSIX: `paplay` (PulseAudio) → `aplay` (ALSA) → the bundled
+ *   static `ffmpeg` (`-f pulse` then `-f alsa`). Empty result means nothing is
+ *   available and the caller should surface an install hint.
+ */
+export declare function playerCommandsFor(platform: NodeJS.Platform, filePath: string, lookup?: PlayerLookup): PlayerCommand[];
+export interface PlayAudioOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Play `filePath` through the speakers, trying each candidate command in order
+ * and returning on the first clean exit. Throws an actionable Error if no
+ * player exists or every candidate fails (with the collected stderr).
+ */
+export declare function playAudioFile(filePath: string, options?: PlayAudioOptions): Promise<void>;
+/** Best-effort temp-file cleanup used by callers after playback. */
+export declare function removeTempFile(filePath: string): Promise<void>;

package/dist/types/tts/runtime.d.ts

@@ -0,0 +1,6 @@
+export declare const KOKORO_PACKAGE = "kokoro-js";
+export declare const KOKORO_VERSION = "1.2.1";
+export declare const ONNXRUNTIME_NODE_PACKAGE = "onnxruntime-node";
+export declare const ONNXRUNTIME_NODE_VERSION = "1.26.0";
+export declare function getTtsRuntimeDir(): string;
+export declare function isTtsRuntimeCached(): Promise<boolean>;

package/dist/types/tts/streaming-player.d.ts

@@ -0,0 +1,41 @@
+import { type PlayerCommand } from "./player";
+/** Output gain applied while ducked (the user is speaking over the assistant). */
+export declare const DUCK_GAIN = 0.25;
+/** Injection seam for {@link streamingPlayerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface StreamingPlayerLookup {
+    which?: (bin: string) => string | null;
+    ffmpeg?: () => string | null;
+}
+/**
+ * Ordered candidate commands for a persistent raw-PCM player on `platform`: each
+ * reads 32-bit-float little-endian mono PCM at `sampleRate` from stdin (`pipe:0`)
+ * and plays it to the default output device. An empty list means no streaming
+ * backend is available and the caller should fall back to per-file playback.
+ *
+ * - darwin: none; `afplay` is file-only, so macOS uses the interruptible
+ *   per-file fallback.
+ * - linux/other POSIX: `ffmpeg` (`-f pulse` then `-f alsa`) → `paplay`/`aplay`
+ *   raw fallbacks.
+ * - win32: none (PowerShell `SoundPlayer` is file-only).
+ */
+export declare function streamingPlayerCommandsFor(platform: NodeJS.Platform, sampleRate: number, lookup?: StreamingPlayerLookup): PlayerCommand[];
+/**
+ * Single-session gapless player. Lifecycle: {@link start} once, {@link write}
+ * chunks in order, then {@link end} to drain or {@link stop} to abort. Not
+ * reusable after stop/end — create a new instance per utterance.
+ */
+export declare class StreamingAudioPlayer {
+    #private;
+    /** Pick a backend and begin draining. Idempotent; the first call's rate wins. */
+    start(sampleRate: number): void;
+    /** Queue a mono float32 PCM chunk for playback in arrival order. */
+    write(pcm: Float32Array): void;
+    /** Scale subsequent output (1 = normal, <1 = ducked). Applies within {@link LEAD_SECONDS}. */
+    setGain(gain: number): void;
+    /** Close the input; resolves once all queued audio has finished playing. */
+    end(): Promise<void>;
+    /** Stop immediately: kill the player, drop everything still queued. */
+    stop(): void;
+}
+/** Factory the vocalizer calls; a function so tests can stub it without spawning a player. */
+export declare function createStreamingPlayer(): StreamingAudioPlayer;

package/dist/types/tts/tts-client.d.ts

@@ -0,0 +1,68 @@
+import { type RefCountedWorkerHandle, type SpawnedSubprocess } from "../subprocess/worker-client";
+import type { TtsProgressEvent, TtsWorkerInbound, TtsWorkerOutbound } from "./tts-protocol";
+/** Decoded PCM returned by a local synthesis request. */
+export interface TtsAudio {
+    pcm: Float32Array;
+    sampleRate: number;
+}
+export interface TtsSynthesizeOptions {
+    voice?: string;
+    signal?: AbortSignal;
+}
+export interface TtsDownloadOptions {
+    signal?: AbortSignal;
+    onProgress?: (event: TtsProgressEvent) => void;
+}
+export interface TtsStreamOptions {
+    voice?: string;
+    signal?: AbortSignal;
+}
+/** One synthesized sentence of a streaming session, in emission order. */
+export interface TtsAudioChunk {
+    index: number;
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+}
+/**
+ * A live streaming-synthesis session. Feed text incrementally with {@link push}
+ * and close the input with {@link end}; `chunks` yields each synthesized
+ * sentence's audio as soon as it is ready, then completes once the worker
+ * finishes draining the closed input.
+ */
+export interface TtsStreamHandle {
+    push(text: string): void;
+    end(): void;
+    chunks: AsyncIterableIterator<TtsAudioChunk>;
+}
+/**
+ * Hidden subcommand on the main CLI that boots the TTS worker in the spawned
+ * subprocess. Kept in sync with the dispatch in `cli.ts` (Main-owned).
+ */
+export declare const TTS_WORKER_ARG = "__omp_worker_tts";
+/**
+ * Spawn the TTS worker as a subprocess. Exported for tests and the smoke probe;
+ * production callers go through {@link spawnTtsWorker}.
+ */
+export declare function createTtsSubprocess(): SpawnedSubprocess<TtsWorkerOutbound>;
+export declare class TtsClient {
+    #private;
+    constructor(spawnWorker?: () => RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound>);
+    onProgress(listener: (event: TtsProgressEvent) => void): () => void;
+    synthesize(modelKey: string, text: string, options?: TtsSynthesizeOptions): Promise<TtsAudio | null>;
+    /**
+     * Open a streaming-synthesis session. Text is fed incrementally through the
+     * returned handle's `push`/`end`; audio is emitted one synthesized sentence at
+     * a time via `chunks`, so playback can begin before the full text is known.
+     * Returns an inert handle (immediately-ended `chunks`) for unknown models or
+     * an already-aborted signal, and fails the iterator if the worker cannot spawn.
+     */
+    synthesizeStream(modelKey: string, options?: TtsStreamOptions): TtsStreamHandle;
+    downloadModel(modelKey: string, options?: TtsDownloadOptions): Promise<boolean>;
+    terminate(): Promise<void>;
+}
+export declare const ttsClient: TtsClient;
+export declare function shutdownTtsClient(): Promise<void>;
+export declare function smokeTestTtsWorker({ timeoutMs, }?: {
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/types/tts/tts-protocol.d.ts

@@ -0,0 +1,95 @@
+import type { TtsLocalModelKey } from "./models";
+export type TtsProgressStatus = "initiate" | "download" | "progress" | "progress_total" | "done" | "ready" | "error";
+export interface TtsProgressFileState {
+    loaded: number;
+    total: number;
+}
+export interface TtsProgressEvent {
+    modelKey: TtsLocalModelKey;
+    status: TtsProgressStatus;
+    name?: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+    files?: Record<string, TtsProgressFileState>;
+    task?: string;
+    model?: string;
+}
+export type TtsWorkerInbound = {
+    type: "ping";
+    id: string;
+} | {
+    type: "synthesize";
+    id: string;
+    modelKey: TtsLocalModelKey;
+    text: string;
+    voice?: string;
+} | {
+    type: "download";
+    id: string;
+    modelKey: TtsLocalModelKey;
+} | {
+    type: "stream-start";
+    id: string;
+    modelKey: TtsLocalModelKey;
+    voice?: string;
+} | {
+    type: "stream-push";
+    id: string;
+    text: string;
+} | {
+    type: "stream-end";
+    id: string;
+} | {
+    type: "stream-cancel";
+    id: string;
+};
+export type TtsWorkerOutbound = {
+    type: "pong";
+    id: string;
+} | {
+    type: "audio";
+    id: string;
+    pcm: Float32Array;
+    sampleRate: number;
+} | {
+    type: "downloaded";
+    id: string;
+} | {
+    type: "error";
+    id: string;
+    error: string;
+} | {
+    type: "progress";
+    id: string;
+    event: TtsProgressEvent;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: "audio-chunk";
+    id: string;
+    index: number;
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+} | {
+    type: "stream-done";
+    id: string;
+};
+/**
+ * Wire transport between the parent (`TtsClient`) and the local TTS subprocess.
+ * The parent owns the subprocess lifecycle (graceful work, hard SIGKILL on
+ * shutdown); the protocol carries no explicit close handshake — once the parent
+ * decides to terminate, it signals the OS to reap the child so
+ * `onnxruntime-node`'s NAPI finalizer never runs in the main agent address
+ * space (it segfaults Bun on shutdown — issue #1606). See `tts-client.ts` for
+ * the spawn/kill glue.
+ */
+export interface TtsTransport {
+    send(message: TtsWorkerOutbound): void;
+    onMessage(handler: (message: TtsWorkerInbound) => void): () => void;
+}

package/dist/types/tts/tts-worker.d.ts

@@ -0,0 +1,2 @@
+import type { TtsTransport } from "./tts-protocol";
+export declare function startTtsWorker(transport: TtsTransport): void;

package/dist/types/tts/vocalizer.d.ts

@@ -0,0 +1,41 @@
+export interface VocalizerPlayer {
+    start(sampleRate: number): void;
+    write(pcm: Float32Array): void;
+    setGain(gain: number): void;
+    end(): Promise<void>;
+    stop(): void;
+}
+export declare class Vocalizer {
+    #private;
+    constructor(createPlayer?: () => VocalizerPlayer);
+    /**
+     * Stream a delta of assistant text into the engine. No-op when vocalization
+     * is disabled. The engine buffers the running text and emits audio for each
+     * complete sentence; the trailing partial is flushed by {@link flush}.
+     */
+    pushDelta(text: string): void;
+    /**
+     * Close the current input stream (call at message/turn end). The engine
+     * flushes its trailing partial as a final chunk; the player keeps draining
+     * queued audio until it completes.
+     */
+    flush(): void;
+    /**
+     * Speak a complete piece of text in one shot (ask questions, yield-mode final
+     * message): stream it in and immediately close the input. No-op when disabled.
+     */
+    speak(text: string): void;
+    /**
+     * Interrupt and drop the current session, killing in-flight playback and
+     * synthesis (new turn / user message / Esc interrupt). Audio stops at once.
+     */
+    clear(): void;
+    /** Lower the volume while the user is speaking (push-to-talk), so speech doesn't drown them out. */
+    duck(): void;
+    /** Restore full volume once the user stops speaking. */
+    unduck(): void;
+    /** Resolve once the playback chain has drained (tests / shutdown). */
+    idle(): Promise<void>;
+}
+/** Process-level vocalizer shared by the event controller and the ask tool. */
+export declare const vocalizer: Vocalizer;

package/dist/types/tts/wav.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Assemble a mono PCM16 WAV byte buffer from Float32 PCM samples (the shape
+ * transformers.js `RawAudio` emits: normalized [-1, 1] amplitudes plus a sample
+ * rate). No external encoder is involved — we write a canonical 44-byte RIFF/
+ * WAVE header followed by little-endian signed 16-bit samples. Samples are
+ * clamped before quantization so out-of-range float values do not wrap.
+ */
+export declare function encodeWav(samples: Float32Array, sampleRate: number): Uint8Array;

package/dist/types/tui/code-cell.d.ts

@@ -0,0 +1,47 @@
+import { type Theme } from "../modes/theme/theme";
+export interface CodeCellOptions {
+    code: string;
+    language?: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    codeMaxLines?: number;
+    /**
+     * Show the LAST `codeMaxLines` rows (the live streaming edge) instead of the
+     * first, with a "… N earlier lines" marker on top. Lets a pending preview
+     * follow code as it is written while staying bounded. Ignored when `expanded`.
+     */
+    codeTail?: boolean;
+    expanded?: boolean;
+    /**
+     * Prefix the header with the cell's language icon (resolved through the
+     * active symbol preset: nerd-font devicon, unicode emoji, or ascii
+     * shorthand). Opt-in so only the eval kernel renderer labels each cell;
+     * read/write/browser code cells stay icon-free.
+     */
+    showLanguage?: boolean;
+    width: number;
+    codeStartLine?: number;
+    codeLineNumbers?: Array<number | null>;
+}
+export declare function renderCodeCell(options: CodeCellOptions, theme: Theme): string[];
+export interface MarkdownCellOptions {
+    content: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    contentMaxLines?: number;
+    expanded?: boolean;
+    width: number;
+}
+export declare function renderMarkdownCell(options: MarkdownCellOptions, theme: Theme): string[];

package/dist/types/tui/file-list.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Render file listings with optional icons and metadata.
+ */
+import type { Theme } from "../modes/theme/theme";
+export interface FileEntry {
+    path: string;
+    /** Absolute filesystem path. When provided together with {@link FileListOptions.hyperlinkFn}, the
+     * rendered path text is wrapped in an OSC 8 hyperlink. */
+    absPath?: string;
+    isDirectory?: boolean;
+    meta?: string;
+}
+export interface FileListOptions {
+    files: FileEntry[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    showIcons?: boolean;
+    /** When provided, called with the entry's absolute path and the ANSI-styled display string to
+     * optionally wrap the path in an OSC 8 hyperlink. Only invoked when {@link FileEntry.absPath} is set. */
+    hyperlinkFn?: (absPath: string, displayText: string) => string;
+}
+export declare function renderFileList(options: FileListOptions, theme: Theme): string[];

package/dist/types/tui/hyperlink.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Returns true when OSC 8 hyperlinks should be emitted.
+ *
+ * Respects `tui.hyperlinks` setting:
+ * - `"off"`: never
+ * - `"auto"`: when `process.stdout.isTTY`, `NO_COLOR` is unset, and the detected terminal reports hyperlink support
+ * - `"always"`: unconditionally (useful for viewers that support OSC 8 without advertising it)
+ * Before settings initialization, returns false so early render paths stay plain text.
+ */
+export declare function isHyperlinkEnabled(): boolean;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at `uri`.
+ *
+ * Returns `displayText` unchanged when hyperlinks are disabled, `uri` contains
+ * terminal control bytes, or `displayText` already contains an OSC 8 sequence.
+ */
+export declare function uriHyperlink(uri: string, displayText: string): string;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL.
+ * `www.example.com` inputs are linked as `https://www.example.com`.
+ */
+export declare function urlHyperlink(url: string, displayText: string): string;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL,
+ * bypassing terminal capability auto-detection. Used for auth prompts where
+ * an inert "click" label blocks login on terminals whose capabilities are
+ * not advertised. Still returns plain text before settings initialization or
+ * when the user has explicitly opted out via `tui.hyperlinks=off`.
+ */
+export declare function urlHyperlinkAlways(url: string, displayText: string): string;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at a filesystem path.
+ *
+ * Returns `displayText` unchanged when hyperlinks are disabled or when
+ * the text already contains an OSC 8 sequence (prevents double-wrapping).
+ * Relative paths resolve against the current working directory before URI
+ * encoding so the OSC 8 target is always a valid `file://` URL.
+ *
+ * @param filePath - Filesystem path
+ * @param displayText - Text to render as the hyperlink anchor (may contain ANSI codes)
+ * @param opts - Optional line/col position appended as `?line=N&col=M` query params
+ */
+export declare function fileHyperlink(filePath: string, displayText: string, opts?: {
+    line?: number;
+    col?: number;
+}): string;
+/**
+ * Synchronously resolve a filesystem-backed internal URL (e.g. `local://foo.md`,
+ * `memory://root/notes.md`) to its absolute filesystem path. Returns `undefined`
+ * for inputs that aren't fs-backed, aren't resolvable in the current session
+ * registry, or fail to parse.
+ *
+ * Used by renderers to wrap fs-backed internal URLs in OSC 8 hyperlinks even
+ * when the resolved path isn't yet available from tool result details (e.g.
+ * during the call/streaming phase before a result lands).
+ *
+ * Async-resolved schemes (`artifact://`, `agent://`, `skill://`, `rule://`,
+ * `omp://`) are not handled here — those rely on `details.resolvedPath` set
+ * by the read tool's router resolution.
+ */
+export declare function tryResolveInternalUrlSync(input: string): string | undefined;

package/dist/types/tui/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public exports for shared TUI components.
+ */
+export * from "./code-cell";
+export * from "./file-list";
+export * from "./hyperlink";
+export * from "./output-block";
+export * from "./status-line";
+export * from "./tree-list";
+export * from "./types";
+export * from "./utils";
+export * from "./width-aware-text";

package/dist/types/tui/output-block.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Bordered output container with optional header and sections.
+ */
+import type { Component } from "jeopi-tui";
+import type { Theme, ThemeColor } from "../modes/theme/theme";
+import type { State } from "./types";
+export interface OutputBlockOptions {
+    header?: string;
+    headerMeta?: string;
+    state?: State;
+    sections?: Array<{
+        label?: string;
+        lines: readonly string[];
+        separator?: boolean;
+    }>;
+    width: number;
+    applyBg?: boolean;
+    contentPaddingLeft?: number;
+    /** Override the state-derived border color. Used for muted "legacy" tool
+     * frames that should not visually compete with framed-output tools. */
+    borderColor?: ThemeColor;
+}
+declare const FRAMED_BLOCK_COMPONENT: unique symbol;
+export type FramedBlockComponent = Component & {
+    [FRAMED_BLOCK_COMPONENT]?: true;
+};
+export declare function markFramedBlockComponent<T extends Component>(component: T): T & FramedBlockComponent;
+export declare function isFramedBlockComponent(component: Component): boolean;
+/**
+ * Inner content width that {@link renderOutputBlock} wraps its body to, for a
+ * given outer `width`: both vertical borders (1 cell each) plus the left
+ * content padding. Renderers that size a tail window MUST budget visual rows
+ * against this, not the outer width — otherwise the block re-wraps their lines
+ * into more rows than they counted and the box overflows its intended height.
+ */
+export declare function outputBlockContentWidth(width: number, contentPaddingLeft?: number): number;
+export declare function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[];
+/**
+ * Cached wrapper around `renderOutputBlock`.
+ *
+ * Since output blocks are re-rendered on every frame (via `render(width)` closures),
+ * but their content rarely changes, this cache avoids redundant `visibleWidth()` and
+ * `padding()` computations on ~99% of render calls.
+ */
+export declare class CachedOutputBlock {
+    #private;
+    /** Render with caching. Returns the cached (shared, caller-immutable) lines if options haven't changed. */
+    render(options: OutputBlockOptions, theme: Theme): readonly string[];
+    /** Invalidate the cache, forcing a rebuild on next render. */
+    invalidate(): void;
+}
+/**
+ * Build a self-framing tool component backed by a cached output block. The
+ * `build` callback returns the block options for a given width; the cache
+ * dedupes re-renders. Pass `borderColor: "borderMuted"` for the dim "legacy"
+ * look that does not compete with the state-colored framed tools.
+ */
+export declare function framedBlock(theme: Theme, build: (width: number) => OutputBlockOptions): Component;
+export {};

package/dist/types/tui/status-line.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Standardized status header rendering for tool output.
+ */
+import type { Theme, ThemeColor } from "../modes/theme/theme";
+import type { ToolUIStatus } from "../tools/render-utils";
+export interface StatusLineOptions {
+    icon?: ToolUIStatus;
+    /** Pre-rendered glyph that replaces the status icon (e.g. a magnifier for
+     * search-family tools). Takes precedence over `icon`. */
+    iconOverride?: string;
+    spinnerFrame?: number;
+    title: string;
+    titleColor?: ThemeColor;
+    description?: string;
+    badge?: {
+        label: string;
+        color: ThemeColor;
+    };
+    meta?: string[];
+}
+export declare function renderStatusLine(options: StatusLineOptions, theme: Theme): string;

package/dist/types/tui/tree-list.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hierarchical tree list rendering helper.
+ */
+import type { Theme } from "../modes/theme/theme";
+import type { TreeContext } from "./types";
+export interface TreeListOptions<T> {
+    items: T[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    /** Strict total-line budget for collapsed mode. When set (and not expanded),
+     *  rendered item lines plus the trailing summary line must fit within this budget.
+     */
+    maxCollapsedLines?: number;
+    itemType?: string;
+    truncateFrom?: "start" | "end";
+    /** Called once per item with `isLast: false` during budget calculation;
+     *  line count MUST NOT vary based on `isLast`. */
+    renderItem: (item: T, context: TreeContext) => string | string[];
+}
+export declare function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): string[];

package/dist/types/tui/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared types for TUI rendering components.
+ */
+import type { Theme } from "../modes/theme/theme";
+export type State = "pending" | "running" | "success" | "error" | "warning";
+export interface TreeContext {
+    index: number;
+    isLast: boolean;
+    depth: number;
+    theme: Theme;
+    prefix: string;
+    continuePrefix: string;
+}