@oh-my-pi/pi-tui 18.2.4 → 18.2.6

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [18.2.5] - 2026-09-17
+
+### Added
+
+- Added the full coding-agent terminal UI to the package, including themed rendering primitives, shared chrome, tool renderers, chat transcripts, overlays and hubs, status lines, prompt and autocomplete controls, setup flows, and standalone utilities such as the Git TUI, process viewer, debug viewers, boards, and pickers.
+- Added reusable terminal UI components for forms, menus, split layouts, disclosures, tree views, tool cards, data widgets, fullscreen hubs, scrollable overlay navigation, and interactive footer chips.
+- Added live viewer counts to the status line and exposed paint observers through `TUIOptions.onPaint` and `TUI.setPaintListener` for hosts that need to track committed scrollback and viewport rows.
+- Added details and notes fields to todo items, plus an interactive task-list renderer for managing subtasks.
+- Added inline summaries for structured task outputs.
+- Added image input validation with automatic conversion of unsupported formats and support for video previews in chat.
+- Added the MCP Add Wizard for streamlined server configuration.
+- Added an `autoresearch` tool renderer for tracking experiments.
+- Added side-by-side diff rendering for merge conflicts and improved presentation of GitHub Actions workflow jobs and runs.
+- Added the `dark-celestial` built-in theme with a twilight palette and pink, coral, purple, cyan, and peach accents.
+
+### Changed
+
+- Overhauled JSON tree visualization with syntax highlighting, item counts, clearer indentation, and a simplified layout.
+- Improved agent task, evaluation, hub, and model displays with clearer layouts, better truncation, and metric support.
+- Standardized form labels, descriptions, and overlay styling, and improved overlay text rendering by collapsing newlines consistently.
+- Updated spinner animations to use theme-consistent frames and refined tool-output notice stripping for more consistent display.
+- Improved performance and responsiveness when rendering long-running Bash streams and large or continuously updating terminal content.
+
 ## [18.2.4] - 2026-09-17
 
 ### Fixed

package/README.md

@@ -77,6 +77,49 @@ interface Component {
 
 ## Built-in Components
 
+### Composition
+
+Build screens from persistent components and update their data, selection, expansion, or size through setters. Layouts own child bounds and mouse-coordinate translation; controllers retain domain workflows and asynchronous operations. Propagate `invalidate()` after theme changes and `dispose()` when removing an owned component tree.
+
+| Family | Components | Import |
+| --- | --- | --- |
+| Layout | `Stack`, `Row`, `SplitPane` | package root |
+| Panels | `OverlayPanel`, `PanelRows`, `PanelDivider` | `/chrome` |
+| Menus | `SelectList`, `MenuSelection` | package root |
+| Forms | `Form`, `FormField`, `TextFormField`, `SelectFormField`, `SettingsFormField` | package root |
+| Wizard steps | `WizardStep` | package root |
+| Viewports | `ScrollView`, including child rendering, follow-tail, and keyed range anchoring | package root |
+| Trees | `TreeView` | package root |
+| Disclosure | `Disclosure`, with lazy summary/detail children | package root |
+| Messages | `FramedMessageComponent`, `MessageNoticeComponent`, `MessageDividerComponent` | `/chrome` |
+| Tool output | `ToolCard`, `framedToolCard`, `plainToolCard`, `OutputPane` | `/render` |
+| Transcripts | `TranscriptBrowser` | package root |
+| Data | `MetricRow`, `ProgressBar`, `Table`, `KeyValueList`, `Section` | package root |
+
+```typescript
+import { Disclosure, SplitPane, Text } from "@oh-my-pi/pi-tui";
+
+const diagnostics = new Disclosure({
+	summary: new Text("2 build diagnostics", 0, 0),
+	body: () => new Text("src/index.ts:12 — unused import\nsrc/config.ts:8 — missing property", 0, 0),
+});
+
+const view = new SplitPane({
+	left: new Text("Build diagnostics", 0, 0),
+	right: diagnostics,
+	leftSize: { fixed: 24 },
+	rightMinWidth: 30,
+	splitAt: 60,
+	narrowPane: "right",
+	height: 12,
+});
+
+diagnostics.setExpanded(true);
+view.setHeight(16);
+```
+
+`ScrollView.revealRange()` preserves manual scrolling while a selection is unchanged; `mode: "once"` supports asynchronously arriving initial selections. `OutputPane.append()` accepts incremental terminal output, including carriage-return updates; call `finish()` when the stream ends.
+
 ### Container
 
 Groups child components.

package/dist/types/app-keybindings.d.ts

@@ -0,0 +1,395 @@
+import { type Keybinding, type KeybindingsConfig, type KeyId, KeybindingsManager as TuiKeybindingsManager } from "./keybindings.js";
+/**
+ * Application-level keybindings (coding agent specific).
+ * Values are always `true` — used for declaration merging.
+ */
+interface AppKeybindings {
+    "app.interrupt": true;
+    "app.clear": true;
+    "app.exit": true;
+    "app.suspend": true;
+    "app.display.reset": true;
+    "app.thinking.cycle": true;
+    "app.thinking.toggle": true;
+    "app.model.cycleForward": true;
+    "app.model.cycleBackward": true;
+    "app.model.select": true;
+    "app.model.selectTemporary": true;
+    "app.tools.expand": true;
+    "app.tools.toggleVisibility": true;
+    "app.editor.external": true;
+    "app.message.followUp": true;
+    "app.retry": true;
+    "app.message.dequeue": true;
+    "app.clipboard.pasteImage": true;
+    "app.clipboard.pasteTextRaw": true;
+    "app.clipboard.copyLine": true;
+    "app.clipboard.copyPrompt": true;
+    "app.agents.hub": true;
+    "app.session.new": true;
+    "app.session.tree": true;
+    "app.session.fork": true;
+    "app.session.resume": true;
+    "app.session.observe": true;
+    "app.session.togglePath": true;
+    "app.session.toggleSort": true;
+    "app.session.rename": true;
+    "app.session.delete": true;
+    "app.session.deleteNoninvasive": true;
+    "app.tree.foldOrUp": true;
+    "app.tree.unfoldOrDown": true;
+    "app.plan.toggle": true;
+    "app.history.search": true;
+    "app.stt.toggle": true;
+    "app.live.toggle": true;
+}
+/** Application action identifier registered alongside the base TUI keybindings. */
+export type AppKeybinding = keyof AppKeybindings;
+declare module "./keybindings.js" {
+    interface Keybindings extends AppKeybindings {
+    }
+}
+/**
+ * Resolve default image-paste shortcuts for the current terminal platform.
+ */
+export declare function getDefaultPasteImageKeys(platform?: NodeJS.Platform): KeyId[];
+/**
+ * All keybindings definitions: TUI + app-specific.
+ */
+export declare const KEYBINDINGS: {
+    readonly "tui.editor.cursorUp": {
+        readonly defaultKeys: "up";
+        readonly description: "Move cursor up";
+    };
+    readonly "tui.editor.cursorDown": {
+        readonly defaultKeys: "down";
+        readonly description: "Move cursor down";
+    };
+    readonly "tui.editor.cursorLeft": {
+        readonly defaultKeys: ["left", "ctrl+b"];
+        readonly description: "Move cursor left";
+    };
+    readonly "tui.editor.cursorRight": {
+        readonly defaultKeys: ["right", "ctrl+f"];
+        readonly description: "Move cursor right";
+    };
+    readonly "tui.editor.cursorWordLeft": {
+        readonly defaultKeys: ["alt+left", "ctrl+left", "alt+b"];
+        readonly description: "Move cursor word left";
+    };
+    readonly "tui.editor.cursorWordRight": {
+        readonly defaultKeys: ["alt+right", "ctrl+right", "alt+f"];
+        readonly description: "Move cursor word right";
+    };
+    readonly "tui.editor.cursorLineStart": {
+        readonly defaultKeys: ["home", "ctrl+a"];
+        readonly description: "Move to line start";
+    };
+    readonly "tui.editor.cursorLineEnd": {
+        readonly defaultKeys: ["end", "ctrl+e"];
+        readonly description: "Move to line end";
+    };
+    readonly "tui.editor.jumpForward": {
+        readonly defaultKeys: "ctrl+]";
+        readonly description: "Jump forward to character";
+    };
+    readonly "tui.editor.jumpBackward": {
+        readonly defaultKeys: "ctrl+alt+]";
+        readonly description: "Jump backward to character";
+    };
+    readonly "tui.editor.pageUp": {
+        readonly defaultKeys: "pageUp";
+        readonly description: "Page up";
+    };
+    readonly "tui.editor.pageDown": {
+        readonly defaultKeys: "pageDown";
+        readonly description: "Page down";
+    };
+    readonly "tui.editor.deleteCharBackward": {
+        readonly defaultKeys: "backspace";
+        readonly description: "Delete character backward";
+    };
+    readonly "tui.editor.deleteCharForward": {
+        readonly defaultKeys: ["delete", "ctrl+d"];
+        readonly description: "Delete character forward";
+    };
+    readonly "tui.editor.deleteWordBackward": {
+        readonly defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"];
+        readonly description: "Delete word backward";
+    };
+    readonly "tui.editor.deleteWordForward": {
+        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
+        readonly description: "Delete word forward";
+    };
+    readonly "tui.editor.deleteToLineStart": {
+        readonly defaultKeys: "ctrl+u";
+        readonly description: "Delete to line start";
+    };
+    readonly "tui.editor.deleteToLineEnd": {
+        readonly defaultKeys: "ctrl+k";
+        readonly description: "Delete to line end";
+    };
+    readonly "tui.editor.yank": {
+        readonly defaultKeys: "ctrl+y";
+        readonly description: "Yank";
+    };
+    readonly "tui.editor.yankPop": {
+        readonly defaultKeys: "alt+y";
+        readonly description: "Yank pop";
+    };
+    readonly "tui.editor.undo": {
+        readonly defaultKeys: ["ctrl+-", "ctrl+_"];
+        readonly description: "Undo";
+    };
+    readonly "tui.editor.spellingSuggestions": {
+        readonly defaultKeys: "ctrl+.";
+        readonly description: "Show spelling replacements";
+    };
+    readonly "tui.input.newLine": {
+        readonly defaultKeys: ["shift+enter", "ctrl+j"];
+        readonly description: "Insert newline";
+    };
+    readonly "tui.input.submit": {
+        readonly defaultKeys: "enter";
+        readonly description: "Submit input";
+    };
+    readonly "tui.input.tab": {
+        readonly defaultKeys: "tab";
+        readonly description: "Tab / autocomplete";
+    };
+    readonly "tui.input.copy": {
+        readonly defaultKeys: "ctrl+c";
+        readonly description: "Copy selection";
+    };
+    readonly "tui.select.up": {
+        readonly defaultKeys: "up";
+        readonly description: "Move selection up";
+    };
+    readonly "tui.select.down": {
+        readonly defaultKeys: "down";
+        readonly description: "Move selection down";
+    };
+    readonly "tui.select.pageUp": {
+        readonly defaultKeys: "pageUp";
+        readonly description: "Selection page up";
+    };
+    readonly "tui.select.pageDown": {
+        readonly defaultKeys: "pageDown";
+        readonly description: "Selection page down";
+    };
+    readonly "tui.select.confirm": {
+        readonly defaultKeys: "enter";
+        readonly description: "Confirm selection";
+    };
+    readonly "tui.select.cancel": {
+        readonly defaultKeys: ["escape", "ctrl+c"];
+        readonly description: "Cancel selection";
+    };
+    readonly "app.interrupt": {
+        readonly defaultKeys: "escape";
+        readonly description: "Interrupt current operation";
+    };
+    readonly "app.clear": {
+        readonly defaultKeys: "ctrl+c";
+        readonly description: "Clear screen or cancel";
+    };
+    readonly "app.exit": {
+        readonly defaultKeys: "ctrl+d";
+        readonly description: "Exit application";
+    };
+    readonly "app.suspend": {
+        readonly defaultKeys: "ctrl+z";
+        readonly description: "Suspend application";
+    };
+    readonly "app.display.reset": {
+        readonly defaultKeys: "alt+l";
+        readonly description: "Reset terminal display";
+    };
+    readonly "app.thinking.cycle": {
+        readonly defaultKeys: "shift+tab";
+        readonly description: "Cycle thinking level";
+    };
+    readonly "app.thinking.toggle": {
+        readonly defaultKeys: "ctrl+t";
+        readonly description: "Toggle thinking mode";
+    };
+    readonly "app.model.cycleForward": {
+        readonly defaultKeys: "ctrl+p";
+        readonly description: "Cycle to next model";
+    };
+    readonly "app.model.cycleBackward": {
+        readonly defaultKeys: "shift+ctrl+p";
+        readonly description: "Cycle to previous model";
+    };
+    readonly "app.model.select": {
+        readonly defaultKeys: "alt+m";
+        readonly description: "Select model";
+    };
+    readonly "app.model.selectTemporary": {
+        readonly defaultKeys: "alt+p";
+        readonly description: "Select temporary model for current session";
+    };
+    readonly "app.tools.expand": {
+        readonly defaultKeys: "ctrl+o";
+        readonly description: "Expand tools";
+    };
+    readonly "app.tools.toggleVisibility": {
+        readonly defaultKeys: "ctrl+shift+o";
+        readonly description: "Show or hide tool activity";
+    };
+    readonly "app.editor.external": {
+        readonly defaultKeys: "ctrl+g";
+        readonly description: "Open external editor";
+    };
+    readonly "app.message.followUp": {
+        readonly defaultKeys: ["ctrl+q", "ctrl+enter"];
+        readonly description: "Send follow-up message";
+    };
+    readonly "app.retry": {
+        readonly defaultKeys: ["f5", "alt+r"];
+        readonly description: "Retry last failed assistant turn";
+    };
+    readonly "app.message.dequeue": {
+        readonly defaultKeys: ["alt+up", "shift+up"];
+        readonly description: "Dequeue message";
+    };
+    readonly "app.clipboard.pasteImage": {
+        readonly defaultKeys: KeyId[];
+        readonly description: "Paste image or text from clipboard";
+    };
+    readonly "app.clipboard.pasteTextRaw": {
+        readonly defaultKeys: ["ctrl+shift+v", "alt+shift+v"];
+        readonly description: "Paste text from clipboard as raw text (no collapse)";
+    };
+    readonly "app.clipboard.copyLine": {
+        readonly defaultKeys: "alt+shift+l";
+        readonly description: "Copy current line";
+    };
+    readonly "app.clipboard.copyPrompt": {
+        readonly defaultKeys: "alt+shift+c";
+        readonly description: "Copy prompt";
+    };
+    readonly "app.session.new": {
+        readonly defaultKeys: [];
+        readonly description: "Create new session";
+    };
+    readonly "app.session.tree": {
+        readonly defaultKeys: [];
+        readonly description: "Show session tree";
+    };
+    readonly "app.session.fork": {
+        readonly defaultKeys: [];
+        readonly description: "Fork session";
+    };
+    readonly "app.session.resume": {
+        readonly defaultKeys: [];
+        readonly description: "Resume session";
+    };
+    readonly "app.agents.hub": {
+        readonly defaultKeys: "alt+a";
+        readonly description: "Open the agent hub";
+    };
+    readonly "app.session.observe": {
+        readonly defaultKeys: "ctrl+s";
+        readonly description: "Open the agent hub";
+    };
+    readonly "app.session.togglePath": {
+        readonly defaultKeys: "ctrl+p";
+        readonly description: "Toggle session path display";
+    };
+    readonly "app.session.toggleSort": {
+        readonly defaultKeys: "ctrl+s";
+        readonly description: "Toggle session sort order";
+    };
+    readonly "app.session.rename": {
+        readonly defaultKeys: "ctrl+r";
+        readonly description: "Rename session";
+    };
+    readonly "app.session.delete": {
+        readonly defaultKeys: "ctrl+d";
+        readonly description: "Delete session";
+    };
+    readonly "app.session.deleteNoninvasive": {
+        readonly defaultKeys: "ctrl+backspace";
+        readonly description: "Delete session (non-invasive)";
+    };
+    readonly "app.tree.foldOrUp": {
+        readonly defaultKeys: ["ctrl+left", "alt+left"];
+        readonly description: "Fold or move up";
+    };
+    readonly "app.tree.unfoldOrDown": {
+        readonly defaultKeys: ["ctrl+right", "alt+right"];
+        readonly description: "Unfold or move down";
+    };
+    readonly "app.plan.toggle": {
+        readonly defaultKeys: "alt+shift+p";
+        readonly description: "Toggle plan mode";
+    };
+    readonly "app.history.search": {
+        readonly defaultKeys: "ctrl+r";
+        readonly description: "Search history";
+    };
+    readonly "app.stt.toggle": {
+        readonly defaultKeys: [];
+        readonly description: "Toggle speech-to-text (default gesture: hold Space)";
+    };
+    readonly "app.live.toggle": {
+        readonly defaultKeys: "ctrl+l";
+        readonly description: "Start or stop live voice mode (/live)";
+    };
+};
+/** Controls inherited keybinding lookup when creating a manager for a named profile. */
+export interface KeybindingsCreateOptions {
+    /** Default-profile agent directory whose keybindings are merged before profile-specific bindings. */
+    inheritedAgentDir?: string;
+}
+/** Migrate legacy keybinding names and JSON configuration in an agent directory. */
+declare function migrateKeybindingsConfigFile(agentDir: string): void;
+/**
+ * Manages all keybindings (app + TUI).
+ * Extends the TUI KeybindingsManager with app-specific functionality.
+ */
+export declare class KeybindingsManager extends TuiKeybindingsManager {
+    #private;
+    constructor(userBindings?: KeybindingsConfig, configPath?: string, inheritedConfigPath?: string);
+    /**
+     * Create from config files at agentDir/keybindings.yml and the default profile.
+     * Legacy keybindings.json is migrated to keybindings.yml on load.
+     */
+    static create(agentDir?: string, options?: KeybindingsCreateOptions): KeybindingsManager;
+    /**
+     * Create an in-memory keybindings manager without file persistence.
+     */
+    static inMemory(userBindings?: KeybindingsConfig): KeybindingsManager;
+    /**
+     * Reload keybindings from the config files.
+     */
+    reload(): void;
+    setUserBindings(userBindings: KeybindingsConfig): void;
+    getKeys(keybinding: Keybinding): KeyId[];
+    getResolvedBindings(): KeybindingsConfig;
+    /**
+     * Get the effective resolved bindings (defaults + user overrides).
+     */
+    getEffectiveConfig(): KeybindingsConfig;
+    /**
+     * Get display string for a keybinding (e.g., "ctrl+c/escape").
+     */
+    getDisplayString(keybinding: Keybinding): string;
+}
+/** Pin the platform used to render modifier labels (test seam). */
+export declare function setKeyHintPlatform(platform: NodeJS.Platform | undefined): void;
+/** Platform currently used for key-hint rendering. */
+export declare function keyHintPlatform(): NodeJS.Platform;
+type Modifier = "ctrl" | "shift" | "alt" | "super";
+/**
+ * Human label for a modifier, using each platform's own key names. `ctrl` and
+ * `shift` are the same everywhere; `alt`/`super` become `Option`/`Cmd` on macOS.
+ */
+export declare function modifierLabel(mod: Modifier, platform?: NodeJS.Platform): string;
+/** Format a key chord with human-readable, platform-aware modifier labels. */
+export declare function formatKeyHint(key: KeyId): string;
+/** Format alternative key chords as slash-separated human-readable hints. */
+export declare function formatKeyHints(keys: KeyId | KeyId[]): string;
+export type { Keybinding, KeybindingsConfig, KeyId };
+export { migrateKeybindingsConfigFile };

package/dist/types/apps/autoresearch-dashboard.d.ts

@@ -0,0 +1,43 @@
+import type { Component } from "../tui.js";
+import type { Theme } from "../theme/theme.js";
+import { type ExperimentState } from "../tools/autoresearch.js";
+/** Experiment runtime fields rendered by the dashboard. */
+export interface AutoresearchDashboardRuntime {
+    autoresearchMode: boolean;
+    dashboardExpanded: boolean;
+    state: ExperimentState;
+    lastRunSummary: {
+        runNumber: number;
+        passed: boolean;
+        parsedPrimary: number | null;
+    } | null;
+    runningExperiment: {
+        startedAt: number;
+        command: string;
+    } | null;
+}
+/** Widget and overlay capabilities supplied by an extension context. */
+export interface AutoresearchDashboardHost {
+    hasUI: boolean;
+    ui: {
+        setWidget(key: string, content: ((tui: {
+            requestRender(): void;
+        }, theme: Theme) => Component) | undefined): void;
+        custom<T>(factory: (tui: {
+            requestRender(): void;
+        }, theme: Theme, keybindings: unknown, done: (result: T) => void) => Component, options?: {
+            overlay: boolean;
+        }): Promise<T>;
+    };
+}
+/** Dashboard lifecycle and rendering controls. */
+export interface DashboardController {
+    clear(ctx: AutoresearchDashboardHost): void;
+    requestRender(): void;
+    showOverlay(ctx: AutoresearchDashboardHost, runtime: AutoresearchDashboardRuntime): Promise<void>;
+    updateWidget(ctx: AutoresearchDashboardHost, runtime: AutoresearchDashboardRuntime): void;
+}
+/** Create a dashboard backed by the host's widget and overlay surfaces. */
+export declare function createDashboardController(): DashboardController;
+/** Render experiment progress and result rows at the requested width. */
+export declare function renderDashboardLines(runtime: AutoresearchDashboardRuntime, width: number, theme: Theme, maxRows: number): string[];

package/dist/types/apps/autoresearch-data.d.ts

@@ -0,0 +1,15 @@
+import type { ExperimentResult, MetricDef, MetricDirection, NumericMetricMap } from "../tools/autoresearch.js";
+/** Format an experiment duration for display. */
+export declare function formatElapsed(milliseconds: number): string;
+/** Compare metrics using the configured optimization direction. */
+export declare function isBetter(current: number, best: number, direction: MetricDirection): boolean;
+/** Select results belonging to the active experiment segment. */
+export declare function currentResults(results: ExperimentResult[], segment: number): ExperimentResult[];
+/** Find the first unflagged kept experiment in a segment. */
+export declare function findBaselineResult(results: ExperimentResult[], segment: number): ExperimentResult | null;
+/** Read the baseline primary metric for a segment. */
+export declare function findBaselineMetric(results: ExperimentResult[], segment: number): number | null;
+/** Resolve a baseline run number, including legacy unnumbered results. */
+export declare function findBaselineRunNumber(results: ExperimentResult[], segment: number): number | null;
+/** Collect secondary baselines from the earliest unflagged metric samples. */
+export declare function findBaselineSecondary(results: ExperimentResult[], segment: number, knownMetrics: MetricDef[]): NumericMetricMap;

package/dist/types/apps/cleanse-board.d.ts

@@ -0,0 +1,66 @@
+import { type LiveBoardOutput } from "../chrome/live-board.js";
+import type { AgentProgress } from "../tools/task.js";
+/** Checker identity shown in live rows and verdicts. */
+export interface CleanseCheckerDescriptor {
+    id: string;
+    label: string;
+}
+/** Checker result fields consumed by the verdict line. */
+export interface CleanseCheckResult extends CleanseCheckerDescriptor {
+    diagnostics: readonly unknown[];
+}
+/** Repair workload fields displayed in agent rows. */
+export interface CleanseAssignment {
+    index: number;
+    groups: readonly {
+        file?: string;
+    }[];
+    weight: number;
+}
+/** Completion fields displayed when a repair agent settles. */
+export interface CleanseAgentOutcome {
+    name: string;
+    success: boolean;
+    error?: string;
+    resolvedModel?: string;
+}
+/** Rendering surface for one `omp cleanse` run. */
+export interface CleanseStatusBoard {
+    readonly interactive: boolean;
+    /** Print a permanent line above the live area (plain write when non-TTY). */
+    log(text: string): void;
+    /** Show a transient spinner line; `undefined` clears it. Non-TTY prints the text once. */
+    phase(text: string | undefined): void;
+    checkerStarted(checker: CleanseCheckerDescriptor): void;
+    checkerFinished(check: CleanseCheckResult, durationMs: number): void;
+    /** End the repair phase and drop its live rows before verification. */
+    repairFinished(): void;
+    agentStarted(name: string, assignment: CleanseAssignment): void;
+    agentProgress(name: string, progress: AgentProgress): void;
+    agentFinished(outcome: CleanseAgentOutcome, assignment: CleanseAssignment): void;
+    /** Clear the live area and restore the cursor. Idempotent. */
+    close(): void;
+}
+/**
+ * Live-view state for one cleanse run, shared by the CLI stdout board and the
+ * interactive-mode overlay panel so both surfaces render identical rows.
+ *
+ * Mutators mirror {@link CleanseStatusBoard}; the finish mutators return the
+ * permanent line the surface should log above the live area.
+ */
+export declare class CleanseBoardModel {
+    #private;
+    phase(text: string | undefined): void;
+    checkerStarted(checker: CleanseCheckerDescriptor): void;
+    /** Drop the checker's live row and build its permanent verdict line. */
+    checkerFinished(check: CleanseCheckResult, durationMs: number): string;
+    repairFinished(): void;
+    agentStarted(name: string, assignment: CleanseAssignment): void;
+    agentProgress(name: string, progress: AgentProgress): void;
+    /** Drop the agent's live row, advance the repair bar, and build its permanent outcome line. */
+    agentFinished(outcome: CleanseAgentOutcome, assignment: CleanseAssignment): string;
+    /** Render the transient live rows for the current spinner frame. */
+    renderLive(spinner: string): string[];
+}
+/** Create the cleanse status board bound to `output` (default `process.stdout`). */
+export declare function createCleanseStatusBoard(output?: LiveBoardOutput, errors?: LiveBoardOutput): CleanseStatusBoard;

package/dist/types/apps/cleanse-picker.d.ts

@@ -0,0 +1,23 @@
+/** Checker metadata presented by the target picker. */
+export interface CleanseCheckerChoice {
+    id: string;
+    label: string;
+    language: string;
+    command: string;
+}
+/** Selected checker scope or free-form repair request. */
+export type CleanseTargetChoice = {
+    kind: "all";
+} | {
+    kind: "checker";
+    id: string;
+} | {
+    kind: "request";
+    request: string;
+} | {
+    kind: "cancel";
+};
+/** Pick between running every discovered checker, one specific checker, or a free-form request. */
+export declare function pickCleanseTarget(checkers: readonly CleanseCheckerChoice[]): Promise<CleanseTargetChoice>;
+/** One-shot text prompt for a free-form cleanse request; `null` when cancelled or left empty. */
+export declare function promptCleanseRequest(): Promise<string | null>;

package/dist/types/apps/debug/log-formatting.d.ts

@@ -0,0 +1,6 @@
+/** Sanitize and wrap an expanded log entry into display rows. */
+export declare function formatDebugLogExpandedLines(line: string, maxWidth: number): string[];
+/** Read a valid timestamp from a structured log entry. */
+export declare function parseDebugLogTimestampMs(line: string): number | undefined;
+/** Read a finite process identifier from a structured log entry. */
+export declare function parseDebugLogPid(line: string): number | undefined;