@linxiraos/pi-tui 1.1.26 → 1.2.0

package/dist/types/tools/native-view.d.ts

@@ -72,6 +72,53 @@ export declare function truncationNotice(meta: OutputMeta | undefined): NativeNo
  * truncation / artifact-capture notice from `meta`; undefined when empty.
  */
 export declare function footnoteText(parts: readonly string[], meta?: OutputMeta): NativeNode | undefined;
+/** Drawn lines of a run's input (command, cell code) before its "N more lines" button. */
+export declare const RUN_INPUT_PREVIEW_LINES = 6;
+/**
+ * What a run's foot names: `running` (live clock), `background` (an async job
+ * outlives the call), and the settled outcomes. A failure with an exit code
+ * reads `exit N`; without one, `Failed`.
+ */
+export type RunState = "running" | "background" | "done" | "failed" | "cancelled" | "timed-out";
+/** Inputs of {@link runFoot}. */
+export interface RunFootInput {
+    readonly state: RunState;
+    /** Exit code of a `failed` run; a non-zero code names the state `exit N`. */
+    readonly exitCode?: number;
+    /** Milliseconds run so far (`running`) or in total; the time is omitted when undefined. */
+    readonly elapsedMs?: number;
+    /** Quiet facts (job id, service state, artifact), muted and ` · `-joined. */
+    readonly facts?: readonly string[];
+    /** Truncation / artifact-capture notices, appended to the facts in `warning`. */
+    readonly meta?: OutputMeta;
+}
+/**
+ * The foot line of a run box (`zeta.run.foot`): the state word in its tone,
+ * the run time (a live clock while running, frozen once settled) and the
+ * quiet facts. Glyphs are the terminal's styling, never text.
+ */
+export declare function runFoot(input: RunFootInput): NativeNode;
+/** A run's input section: the command or cell source, clamped to {@link RUN_INPUT_PREVIEW_LINES}. */
+export declare function runInput(source: string, p: {
+    role: string;
+    lang: string;
+    wrap: boolean;
+}): NativeNode;
+/** A run's terminal output: follows its tail, clamped to the last `previewLines` lines while folded. */
+export declare function runOutput(output: string, p: {
+    role: string;
+    previewLines: number;
+    key?: string;
+}): NativeNode;
+/**
+ * One run as one box (`zeta.run`): input, output, status lines and foot in
+ * order. `tone` tints the box: `error` for a failed run, `warning` for a
+ * timed-out one.
+ */
+export declare function runBox(children: readonly (NativeChild | undefined | false)[], p: {
+    key: string;
+    tone?: TspTone;
+}): NativeNode;
 /** A diagnostic's severity glyph: `x-circle` error, `warn` warning, `info`, `lightbulb` hint, in the severity tone. */
 export declare function diagnosticGlyph(severity: ParsedDiagnostic["severity"]): NativeNode;
 /**

package/dist/types/tools/output-meta.d.ts

@@ -84,12 +84,22 @@ export interface LimitsMeta {
         reached: number;
         suggestion: number;
     };
-    /** `unit` may be absent in sessions persisted before it was recorded. */
+    /**
+     * `unit` may be absent in sessions persisted before it was recorded. `lines` is
+     * the first-to-last range of cut lines, and `selectorBase` the target a
+     * `:raw:<line>-<line>` selector reads one of them whole from (an artifact's
+     * `artifact://<id>` stands in when absent).
+     */
     columnTruncated?: {
         maxColumn: number;
         unit?: "bytes" | "chars";
         artifactId?: string;
         artifactElidedBytes?: number;
+        lines?: {
+            first: number;
+            last: number;
+        };
+        selectorBase?: string;
     };
 }
 /**

package/dist/types/tools/renderer.d.ts

@@ -25,6 +25,14 @@ export interface RenderResultOptions {
      * Streamed `xd://` previews stay queued until this is set.
      */
     executionStarted?: boolean;
+    /**
+     * Milliseconds since this call began executing (`tool_execution_start`),
+     * or its total once settled; undefined before it starts. Native describe
+     * hooks only.
+     */
+    elapsedMs?: number;
+    /** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
+    cancelled?: boolean;
 }
 /** Render options for a result, plus the tool-specific context the transcript threads through. */
 export type RenderResultContextOptions = RenderResultOptions & {
@@ -39,6 +47,18 @@ export interface ToolRenderResult<TDetails = unknown> {
     details?: TDetails;
     isError?: boolean;
 }
+/**
+ * A fence a tool call draws under its card, as assistant Markdown draws that
+ * fence. Any fence language may be named (`svg`, `mermaid`, `obj`); the
+ * transcript draws only those it draws as figures in assistant text.
+ */
+export interface ToolFigure {
+    readonly lang: string;
+    /** The body so far. */
+    readonly source: string;
+    /** No more of the body arrives. */
+    readonly closed: boolean;
+}
 /**
  * Per-renderer opt-in for a full viewport replay when the first result
  * replaces a painted pending-call render. A predicate receives the painted
@@ -73,6 +93,8 @@ export interface NativeToolHead {
     readonly targetKind?: TspToolProps["targetKind"];
     /** Language for `command` targets. */
     readonly lang?: string;
+    /** The raw command line the head's Copy command button copies (set implicitly by a `command` target). */
+    readonly command?: string;
     /** `file://` link for path targets. */
     readonly href?: string;
     /** Short facts after the target (`+8 −1`, `5 matches · 2 files`). */
@@ -99,10 +121,15 @@ export interface NativeToolView {
     readonly body?: readonly NativeChild[];
     /** Tone override; the frame otherwise derives it from the call status. */
     readonly tone?: TspTone;
-    /** Body clamp while collapsed; `{tail}` keeps the end (terminal output). Defaults to the transcript's preview size. */
+    /**
+     * Body clamp while collapsed; `{tail}` keeps the end (terminal output). Defaults to the transcript's preview size.
+     * `children`: the body stays whole while collapsed and its own `ansi`/`code` previews clamp instead.
+     */
     readonly preview?: TspPreview | {
         readonly tail: number;
-    } | "none";
+    } | "none" | "children";
+    /** Starts expanded whatever the transcript's expand state (the todo checklist); the user can still fold it. */
+    readonly open?: boolean;
     /** Render frameless (`frame:"inline"`): a head line plus a disclosed body. */
     readonly inline?: boolean;
     /** Head actions offered on hover (`copy`, `retry`). */
@@ -125,6 +152,14 @@ export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
     /** Semantic result view for TSP terminals; merged with the call view when {@link mergeCallAndResult}. */
     describeResult?(result: ToolRenderResult<TDetails>, options: RenderResultContextOptions, args?: TArgs): NativeToolView | undefined;
     mergeCallAndResult?: boolean;
+    /**
+     * The fence a call draws under its card (a `.svg` being written, as its
+     * image): growing while the args stream, closed once they are final; none
+     * after an error. `result` is undefined until the call has one. Rendered
+     * TUI only, and only fences the terminal draws as figures; native views put
+     * their drawing in their describe hooks.
+     */
+    figure?(args: TArgs, result: ToolRenderResult<TDetails> | undefined, options: RenderResultOptions): ToolFigure | undefined;
     /** Describes current activity without coupling a renderer to terminal layout. */
     activitySummary?(args: TArgs, context: ToolActivityContext): ToolActivitySummary;
     /** Render without background box, inline in the response flow */

package/dist/types/tools/streaming-output.d.ts

@@ -31,6 +31,15 @@ export interface OutputSummary {
     columnDroppedBytes?: number;
     /** Number of distinct lines that hit the per-line column cap. */
     columnTruncatedLines?: number;
+    /**
+     * 1-indexed first and last lines the column cap cut, numbered as in the
+     * artifact. Absent when the numbering cannot match the artifact (an inline
+     * substitute was capped, or `replace()` rewrote the buffer).
+     */
+    columnTruncatedRange?: {
+        first: number;
+        last: number;
+    };
     /** Configured per-line column cap in effect (UTF-8 bytes), when > 0. */
     columnMax?: number;
     /** Artifact ID for internal URL access (artifact://<id>) when truncated */
@@ -236,7 +245,8 @@ export declare class OutputSink {
     constructor(options?: OutputSinkOptions);
     /**
      * Push a chunk of output. The buffer management and onChunk callback run
-     * synchronously. File sink writes are deferred and serialized internally.
+     * synchronously; onChunk fires after the chunk is stored, so {@link preview}
+     * already includes it. File sink writes are deferred and serialized internally.
      *
      * `inline` substitutes a bounded representation for the in-memory buffer and
      * live preview while the complete chunk is mirrored to the artifact.
@@ -260,6 +270,15 @@ export declare class OutputSink {
      * branch in `dump()` against stale totals.
      */
     replace(text: string): void;
+    /**
+     * Current inline view without finalizing: the body {@link dump} would
+     * return right now (head + elision marker + rolling tail), minus any notice
+     * and minus the newline `dump()` appends after output that ends in a bare
+     * carriage return. Each call trims the rolling tail to its budget (a copy
+     * of the tail window once it overflowed), so call it from a throttled
+     * onChunk (`chunkThrottleMs`), not once per raw chunk.
+     */
+    preview(): string;
     dump(notice?: string): Promise<OutputSummary>;
     /**
      * Release the artifact spill descriptor on an exit path that skips

package/dist/types/tools/task.d.ts

@@ -1,10 +1,9 @@
 import type { Usage } from "@linxiraos/pi-ai";
 import type { ThemeColor } from "../theme/theme.js";
 import type { ConfiguredThinkingLevel } from "../render/render-utils.js";
+import type { RenderResultOptions, NativeToolView, ToolRenderResult } from "./renderer.js";
 import { type Component } from "../tui.js";
-import type { RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
-import type { NativeToolView, ToolRenderResult } from "./renderer.js";
 /** Render context threaded in from `ToolExecutionComponent.#buildRenderContext`. */
 interface TaskRenderContext {
     hasResult?: boolean;
@@ -255,7 +254,7 @@ export interface AgentProgress {
     resolvedModelRoute?: string;
     /** True when a live advisor was attached to this run's session, not merely enabled in settings. */
     advisor?: boolean;
-    /** The agent's latest self-estimate of task completion (0–100), from the periodic `task.completionProbeMs` side request. */
+    /** The agent's latest self-estimate of task completion (0–100), from the periodic `task.completionProbe` side request. */
     completionPercent?: number;
     /** Data extracted by registered subprocess tool handlers (keyed by tool name) */
     extractedToolData?: Record<string, unknown[]>;

package/dist/types/tools/write.d.ts

@@ -6,7 +6,7 @@ import { type ProcWriteDetails } from "./proc-render.js";
 import { type CfgWriteDetails } from "./cfg-render.js";
 import type { FileDiagnosticsResult } from "./lsp.js";
 import type { OutputMeta } from "./output-meta.js";
-import type { NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary, ToolFigure } from "./renderer.js";
 import { type XdevRenderDispatch, type XdevMountedRenderer } from "./xdev.js";
 /** Details returned by the write tool for transcript rendering. */
 export interface WriteToolDetails {
@@ -37,6 +37,12 @@ interface WriteResult {
     details?: WriteToolDetails;
     isError?: boolean;
 }
+/**
+ * The fence a file write draws as while its content streams and after: its
+ * extension names a figure language and it has content, closed once the args
+ * are final. None for URL-card writes, or after an error.
+ */
+declare function writeFigure(args: WriteRenderArgs | undefined, result: WriteResult | undefined, options: RenderResultOptions): ToolFigure | undefined;
 declare const writeStreamingPreviewStateKey: unique symbol;
 /**
  * Per-component state for incrementally rendering a streamed write.
@@ -75,7 +81,7 @@ export declare const writeToolRenderer: {
     renderCall(args: WriteRenderArgs, options: RenderResultOptions & WriteStreamingPreviewStateCarrier & {
         renderContext?: WriteRenderContext;
     }, uiTheme: Theme): Component | undefined;
-    renderResult(result: WriteResult, options: RenderResultOptions & {
+    renderResult(result: WriteResult, options: RenderResultOptions & WriteStreamingPreviewStateCarrier & {
         renderContext?: WriteRenderContext;
     }, uiTheme: Theme, args?: WriteRenderArgs): Component;
     describeCall(args: WriteRenderArgs, options: RenderResultOptions & {
@@ -84,6 +90,7 @@ export declare const writeToolRenderer: {
     describeResult(result: WriteResult, options: RenderResultOptions & {
         renderContext?: WriteRenderContext;
     }, args?: WriteRenderArgs): NativeToolView | undefined;
+    figure: typeof writeFigure;
     mergeCallAndResult: true;
     forceFirstResultViewportRepaint: (args: unknown, options: RenderResultOptions) => boolean;
 };

package/dist/types/tools/yield.d.ts

@@ -0,0 +1,22 @@
+import type { Theme } from "../theme/theme.js";
+import type { Component } from "../tui.js";
+import type { NativeToolView, RenderResultContextOptions, RenderResultOptions, ToolRenderResult } from "./renderer.js";
+import type { YieldItem } from "./task.js";
+/** `yield` arguments as sent; strict-mode providers send omitted optionals as `null`. */
+interface YieldRenderArgs {
+    type?: string | string[] | null;
+    data?: unknown;
+    error?: string | null;
+    /** 1-based workpool item number. */
+    key?: number;
+}
+/** Shows a `yield` call's submitted data instead of its model-facing acknowledgement. */
+export declare const yieldToolRenderer: {
+    renderCall(args: YieldRenderArgs, options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: ToolRenderResult<YieldItem>, options: RenderResultContextOptions, theme: Theme, args?: YieldRenderArgs): Component;
+    describeCall(args: YieldRenderArgs, options: RenderResultOptions): NativeToolView;
+    describeResult(result: ToolRenderResult<YieldItem>, _options: RenderResultContextOptions, args?: YieldRenderArgs): NativeToolView;
+    mergeCallAndResult: true;
+    animatedPendingPreview: true;
+};
+export {};

package/dist/types/tui.d.ts

@@ -78,6 +78,10 @@ export interface TUIStartOptions {
      * Paint without owning stdin: the terminal stays in cooked mode (kernel
      * echo + line editing at the hardware cursor) until {@link TUI.enableInput}
      * switches to raw input and replays the kernel-buffered keystrokes.
+     *
+     * A terminal expected to speak TSP needs raw input from the start, so it
+     * gets it; its keystrokes are held instead (TSP events and the cell-size
+     * reply still apply) until {@link TUI.releaseHeldInput} replays them.
      */
     deferInput?: boolean;
 }
@@ -150,6 +154,11 @@ export interface Component {
     describeScreen?(cx: DescribeContext): NativeScreen;
     /** User actions on nodes this component described (toggle, select, activate, custom). */
     handleNativeEvent?(event: NativeUiEvent): void;
+    /**
+     * Pure preflight for focused input that must precede TUI-wide input listeners
+     * and debug shortcuts. A true result routes the event to this component first.
+     */
+    capturesInput?(data: string): boolean;
     /**
      * Optional handler for keyboard input when component has focus
      */
@@ -164,6 +173,16 @@ export interface Component {
      * Called when theme changes or when component needs to re-render from scratch.
      */
     invalidate?(): void;
+    /**
+     * Optional hook to drop memoized render output (rows, parse and wrap state)
+     * that the next `render()` can rebuild from state the component keeps.
+     * Unlike {@link invalidate}, it must not rebuild anything eagerly: no
+     * renderer or extension callbacks, no image conversions, and no child
+     * replacement or disposal. The next render must return the same rows it
+     * would have returned without the release. Components without it are
+     * simply not released.
+     */
+    releaseRenderCaches?(): void;
     /**
      * Optional hook to set whether this component ignores tight layout mode.
      */
@@ -303,6 +322,7 @@ export declare class Container implements Component {
     /** Dispose every child, then detach it from this container. */
     disposeChildren(): void;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * Propagate teardown to children. Call when the container's children are
      * being permanently discarded (not when they are detached for reuse — use
@@ -471,6 +491,22 @@ export declare class TUI extends Container {
      * path. Idempotent; no-op when input was never deferred.
      */
     enableInput(): void;
+    /**
+     * Replay the keystrokes held since a TSP `deferInput` start through the
+     * normal input path, then deliver input live. Call once the app's key
+     * handlers are installed so a hotkey pressed during startup still fires.
+     * Only keys typed while the start-time focus owner had focus are held. The
+     * hold survives a stop/start until released. Idempotent; no-op when nothing
+     * is held.
+     */
+    releaseHeldInput(): void;
+    /**
+     * Hand held-key ownership from `previous` to `next` when the app replaces
+     * the component focused at start (a swapped-in custom editor), so keys
+     * typed into the replacement stay queued behind the held ones instead of
+     * overtaking them. No-op unless `previous` owns the held keys.
+     */
+    replaceHeldFocus(previous: Component, next: Component): void;
     addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;

package/dist/types/utils.d.ts

@@ -26,6 +26,12 @@ export interface TextSizingOptions {
  */
 export declare function encodeTextSized(text: string, options?: TextSizingOptions): string;
 export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
+/**
+ * Hard-wrap one literal terminal row without trimming spaces or splitting graphemes.
+ * An oversized grapheme is emitted intact even when it exceeds the requested width.
+ * Zero-cell rows remain one empty row, matching restored-terminal reflow.
+ */
+export declare function wrapLiteralLine(line: string, width: number): string[];
 export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null | "", pad?: boolean | null): string;
 export declare function wrapTextWithAnsi(text: string, width: number): string[];
 export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean): ExtractSegmentsResult;

package/dist/types/vim.d.ts

@@ -8,8 +8,8 @@
  * This is a usable subset of Vim, not a reimplementation of it (see issue #3299): Normal and Visual
  * modes, the common motions, and operators built from those motions.
  */
-export type VimMode = "insert" | "normal" | "visual" | "visual-line";
-export type VimOperator = "d" | "y" | "c";
+export type VimMode = "insert" | "normal" | "visual" | "visual-line" | "replace";
+export type VimOperator = "d" | "y" | "c" | ">" | "<";
 export interface VimPosition {
     line: number;
     col: number;
@@ -50,6 +50,20 @@ export type VimCommand = {
     count: number;
 } | {
     kind: "undo";
+} | {
+    kind: "replace";
+    from: VimPosition;
+    to: VimPosition;
+    text: string;
+} | {
+    kind: "join";
+    fromLine: number;
+    lines: number;
+} | {
+    kind: "indent";
+    fromLine: number;
+    toLine: number;
+    out: boolean;
 };
 /** Start offset of the grapheme after `col`, clamped to `text.length`. */
 export declare function nextGraphemeStart(text: string, col: number): number;
@@ -62,11 +76,11 @@ export declare class VimState {
     mode: VimMode;
     /** Fixed end of a Visual selection; the cursor is the moving end. */
     anchor: VimPosition | null;
-    /** True while a count, operator, `g`, or text-object prefix is half-typed — Escape cancels it. */
+    /** True while a count, operator, `g`, text-object, find, or `r` prefix is half-typed — Escape cancels it. */
     get pending(): boolean;
     /**
-     * The half-typed command as Vim would echo it (`"2"`, `"d"`, `"2d"`, `"di"`) — empty when
-     * nothing is pending. Hosts render this next to the mode so a partially entered operator is
+     * The half-typed command as Vim would echo it (`"2"`, `"d"`, `"2d"`, `"di"`, `"df"`, `"r"`) — empty
+     * when nothing is pending. Hosts render this next to the mode so a partially entered operator is
      * visible instead of silently swallowing the next keystroke.
      */
     get pendingText(): string;

package/dist/types/windows-input-mode.d.ts

@@ -16,10 +16,26 @@
  * terminal sends; chords legacy encoding loses (modified Enter/Tab/Escape,
  * Ctrl+Shift+letter, …) translate to kitty CSI-u, which key matching already
  * parses.
+ *
+ * A host terminal that writes VT instead of key records (any ConPTY host
+ * besides Windows Terminal's native path) reaches us as one `Vk = 0` text
+ * record per byte: Alt+Up arrives as `ESC`, `[`, `1`, `;`, `3`, `A`. Those
+ * bytes are reassembled into the escape sequence they spell; delivering them
+ * one at a time turns every such key into a bare Escape plus typed garbage.
+ */
+/**
+ * Stateful decoder: joins UTF-16 surrogate halves that arrive as separate
+ * records, and reassembles VT escape sequences relayed as text records.
  */
-/** Stateful decoder: joins UTF-16 surrogate halves that arrive as separate records. */
 export declare class Win32InputModeDecoder {
     #private;
+    /** Whether relayed VT text is held waiting for the rest of its sequence. */
+    get hasPendingSequence(): boolean;
+    /**
+     * Release held VT text as-is. The caller invokes this once no further bytes
+     * arrived in time, so a lone relayed ESC still acts as the Escape key.
+     */
+    flushPendingSequence(): string[];
     /**
      * Translate one stdin sequence. Returns `undefined` when `data` is not a
      * win32-input-mode record (pass it through unchanged), otherwise the key
@@ -35,3 +51,19 @@ export declare class Win32InputModeDecoder {
      */
     decodePaste(content: string): string;
 }
+/**
+ * Restores paste delimiters that a Windows console host emitted as individual
+ * win32-input-mode key records before StdinBuffer searches for the delimiters.
+ * Non-matching records remain untouched for normal key and paste decoding.
+ */
+export declare class Win32PasteMarkerNormalizer {
+    #private;
+    /**
+     * `onExpired` runs after held records are released because their wait timed
+     * out, so a downstream holder can treat the same wait as already elapsed.
+     */
+    constructor(onInput: (data: string) => void, onExpired?: () => void);
+    process(data: string): void;
+    /** Release an incomplete marker as its original key records. */
+    flush(): void;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-tui",
-	"version": "1.1.26",
+	"version": "1.2.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Linxira-OS",
@@ -38,14 +38,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@linxiraos/pi-omptype": "1.1.26",
-		"@linxiraos/pi-agent-core": "1.1.26",
-		"@linxiraos/pi-ai": "1.1.26",
-		"@linxiraos/pi-catalog": "1.1.26",
-		"@linxiraos/pi-natives": "1.1.26",
-		"@linxiraos/pi-utils": "1.1.26",
-		"@linxiraos/pi-wire": "1.1.26",
-		"@linxiraos/pi-snapcompact": "1.1.26"
+		"@linxiraos/pi-omptype": "1.2.0",
+		"@linxiraos/pi-agent-core": "1.2.0",
+		"@linxiraos/pi-ai": "1.2.0",
+		"@linxiraos/pi-catalog": "1.2.0",
+		"@linxiraos/pi-natives": "1.2.0",
+		"@linxiraos/pi-utils": "1.2.0",
+		"@linxiraos/pi-wire": "1.2.0",
+		"@linxiraos/pi-snapcompact": "1.2.0"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"
@@ -102,6 +102,10 @@
 			"types": "./dist/types/components/*.d.ts",
 			"import": "./src/components/*.ts"
 		},
+		"./native/*": {
+			"types": "./dist/types/native/*.d.ts",
+			"import": "./src/native/*.ts"
+		},
 		"./*.js": "./src/*.ts"
 	}
 }

package/src/active-terminal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ownership of stdout by a started {@link ProcessTerminal}, kept in a leaf
+ * module so writers that `terminal.ts` itself imports (terminal capabilities,
+ * notifications) can route through the active terminal without an import cycle.
+ */
+import type { ProcessTerminal } from "./terminal";
+/** The started terminal that owns stdout in this thread, if any. */
+export declare function getActiveTerminal(): ProcessTerminal | null;
+/** Record the terminal that owns stdout (`ProcessTerminal.start`), or release it with `null` (`stop`). */
+export declare function setActiveTerminal(terminal: ProcessTerminal | null): void;
+/** Observe stdout errors through the shared listener. Returns the unregister callback. */
+export declare function registerStdoutErrorHandler(handler: (err: Error) => void): () => void;
+/**
+ * Hand `data` to the active terminal's ordered output path. Returns false when
+ * no terminal in this thread has started. On the main thread that means the
+ * caller owns stdout; a worker thread never sees the main thread's terminal, so
+ * there `false` is not permission to write. Prefer {@link writeTerminalSequence}.
+ */
+export declare function writeThroughActiveTerminal(data: string): boolean;
+/**
+ * Write an out-of-band escape sequence (window title, OSC 52 clipboard,
+ * notification). While a TUI owns stdout, its frames go through an off-thread
+ * pump in chunks that ignore escape boundaries; a direct `process.stdout.write`
+ * can land between two chunks and split a frame's escape sequence, and the host
+ * terminal then prints its tail as text. So the sequence takes the active
+ * terminal's ordered output path, and goes straight to stdout, best-effort, only
+ * when no terminal owns it. A worker thread cannot reach the main thread's
+ * terminal and would write around its pump, so it writes nothing.
+ */
+export declare function writeTerminalSequence(data: string): void;

package/src/active-terminal.ts

@@ -0,0 +1,80 @@
+/**
+ * Ownership of stdout by a started {@link ProcessTerminal}, kept in a leaf
+ * module so writers that `terminal.ts` itself imports (terminal capabilities,
+ * notifications) can route through the active terminal without an import cycle.
+ */
+import type { ProcessTerminal } from "./terminal";
+
+// The started terminal that owns stdout in this thread; also consulted by the
+// emergency restore on crash.
+let activeTerminal: ProcessTerminal | null = null;
+
+/** The started terminal that owns stdout in this thread, if any. */
+export function getActiveTerminal(): ProcessTerminal | null {
+	return activeTerminal;
+}
+
+/** Record the terminal that owns stdout (`ProcessTerminal.start`), or release it with `null` (`stop`). */
+export function setActiveTerminal(terminal: ProcessTerminal | null): void {
+	activeTerminal = terminal;
+}
+
+const stdoutErrorHandlers = new Set<(err: Error) => void>();
+let stdoutErrorListenerInstalled = false;
+
+function onStdoutError(err: Error): void {
+	for (const handler of stdoutErrorHandlers) handler(err);
+}
+
+/**
+ * Install the one shared `process.stdout` `error` listener. Its presence alone
+ * keeps a stdout error (EPIPE on a closed pipe, EIO on a revoked PTY) from
+ * crashing the process as an unhandled `error` event.
+ */
+function installStdoutErrorListener(): void {
+	if (stdoutErrorListenerInstalled) return;
+	process.stdout.on("error", onStdoutError);
+	stdoutErrorListenerInstalled = true;
+}
+
+/** Observe stdout errors through the shared listener. Returns the unregister callback. */
+export function registerStdoutErrorHandler(handler: (err: Error) => void): () => void {
+	stdoutErrorHandlers.add(handler);
+	installStdoutErrorListener();
+	return () => {
+		stdoutErrorHandlers.delete(handler);
+	};
+}
+
+/**
+ * Hand `data` to the active terminal's ordered output path. Returns false when
+ * no terminal in this thread has started. On the main thread that means the
+ * caller owns stdout; a worker thread never sees the main thread's terminal, so
+ * there `false` is not permission to write. Prefer {@link writeTerminalSequence}.
+ */
+export function writeThroughActiveTerminal(data: string): boolean {
+	if (!activeTerminal) return false;
+	activeTerminal.write(data);
+	return true;
+}
+
+/**
+ * Write an out-of-band escape sequence (window title, OSC 52 clipboard,
+ * notification). While a TUI owns stdout, its frames go through an off-thread
+ * pump in chunks that ignore escape boundaries; a direct `process.stdout.write`
+ * can land between two chunks and split a frame's escape sequence, and the host
+ * terminal then prints its tail as text. So the sequence takes the active
+ * terminal's ordered output path, and goes straight to stdout, best-effort, only
+ * when no terminal owns it. A worker thread cannot reach the main thread's
+ * terminal and would write around its pump, so it writes nothing.
+ */
+export function writeTerminalSequence(data: string): void {
+	if (!Bun.isMainThread) return;
+	if (writeThroughActiveTerminal(data)) return;
+	installStdoutErrorListener();
+	try {
+		process.stdout.write(data);
+	} catch {
+		// Best-effort: a closed stdout must not fail the caller.
+	}
+}

package/src/app-keybindings.d.ts

@@ -40,6 +40,7 @@ interface AppKeybindings {
     "app.tree.unfoldOrDown": true;
     "app.plan.toggle": true;
     "app.history.search": true;
+    "app.stt.pushToTalk": true;
     "app.stt.toggle": true;
     "app.live.toggle": true;
 }
@@ -118,7 +119,7 @@ export declare const KEYBINDINGS: {
         readonly description: "Delete word backward";
     };
     readonly "tui.editor.deleteWordForward": {
-        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
+        readonly defaultKeys: ["alt+delete", "alt+d", "ctrl+delete", "super+alt+delete", "super+alt+d"];
         readonly description: "Delete word forward";
     };
     readonly "tui.editor.deleteToLineStart": {
@@ -329,9 +330,13 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: "ctrl+r";
         readonly description: "Search history";
     };
+    readonly "app.stt.pushToTalk": {
+        readonly defaultKeys: "space";
+        readonly description: "Hold to record speech-to-text";
+    };
     readonly "app.stt.toggle": {
         readonly defaultKeys: [];
-        readonly description: "Toggle speech-to-text (default gesture: hold Space)";
+        readonly description: "Toggle speech-to-text recording";
     };
     readonly "app.live.toggle": {
         readonly defaultKeys: "ctrl+l";