@linxiraos/pi-tui 1.1.26 → 1.2.0

package/README.md

@@ -66,14 +66,16 @@ interface Component {
 	render(width: number): readonly string[];
 	handleInput?(data: string): void;
 	invalidate?(): void;
+	releaseRenderCaches?(): void;
 }
 ```
 
-| Method               | Description                                                                                                                                                        |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `render(width)`      | Returns an array of strings, one per line. Each line **must not exceed `width`** or the TUI will error. Use `truncateToWidth()` or manual wrapping to ensure this. The result is component-owned and immutable to callers; return the same array reference when unchanged (enables renderer memoization) and a new array when content changed. |
-| `handleInput?(data)` | Called when the component has focus and receives keyboard input. The `data` string contains raw terminal input (may include ANSI escape sequences).                |
-| `invalidate?()`      | Called to clear any cached render state. Components should re-render from scratch on the next `render()` call.                                                     |
+| Method                   | Description                                                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `render(width)`          | Returns an array of strings, one per line. Each line **must not exceed `width`** or the TUI will error. Use `truncateToWidth()` or manual wrapping to ensure this. The result is component-owned and immutable to callers; return the same array reference when unchanged (enables renderer memoization) and a new array when content changed. |
+| `handleInput?(data)`     | Called when the component has focus and receives keyboard input. The `data` string contains raw terminal input (may include ANSI escape sequences).                |
+| `invalidate?()`          | Called to clear any cached render state. Components should re-render from scratch on the next `render()` call.                                                     |
+| `releaseRenderCaches?()` | Drops only derived render caches. The next `render()` must return the same rows without eager rebuilds, renderer callbacks, image conversions, or child replacement. |
 
 ## Built-in Components
 
@@ -455,7 +457,7 @@ const spacer = new Spacer(2); // 2 empty lines (default: 1)
 
 ### Image
 
-Renders images inline for terminals that support the Kitty graphics protocol (Kitty, Ghostty, WezTerm, and Warp on macOS/Linux) or iTerm2 inline images. Falls back to a text placeholder on unsupported terminals.
+Renders images inline for terminals that support the Kitty graphics protocol (Kitty, Ghostty, WezTerm, and Warp on macOS/Linux), iTerm2 inline images or SIXEL. Falls back to a text placeholder on unsupported terminals.
 
 ```typescript
 interface ImageTheme {
@@ -466,17 +468,21 @@ interface ImageOptions {
 	maxWidthCells?: number;
 	maxHeightCells?: number;
 	filename?: string;
+	budget?: ImageBudget; // usually tui.imageBudget
+	requestRender?: () => void; // repaint once a SIXEL encode lands; defaults to the budget's
 }
 
 const image = new Image(
 	base64Data, // base64-encoded image data
 	"image/png", // MIME type
 	theme, // ImageTheme
-	options, // optional ImageOptions
+	{ ...options, budget: tui.imageBudget }, // optional ImageOptions
 );
 tui.addChild(image);
 ```
 
+SIXEL images encode off the JavaScript thread: the first render reserves the image's rows and the image appears on the repaint `budget` or `requestRender` triggers once the encode lands. Without either, it waits for an unrelated repaint.
+
 Supported formats: PNG, JPEG, GIF, WebP. Dimensions are parsed from the image headers automatically.
 
 ## Autocomplete

package/dist/types/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.js";
+/** 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/dist/types/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";

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

@@ -25,7 +25,7 @@ export interface CleanseAgentOutcome {
     error?: string;
     resolvedModel?: string;
 }
-/** Rendering surface for one `omp cleanse` run. */
+/** Rendering surface for one `zetacode cleanse` run. */
 export interface CleanseStatusBoard {
     readonly interactive: boolean;
     /** Print a permanent line above the live area (plain write when non-TTY). */

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

@@ -15,6 +15,8 @@ type DebugLogViewerModelOptions = {
     processPid?: number;
     hasOlderLogs?: () => boolean;
     loadOlderLogs?: (limitDays?: number) => Promise<string>;
+    /** Most entries kept; older history beyond it is not loaded. Defaults to {@link MAX_LOG_ENTRIES}. */
+    maxLogEntries?: number;
 };
 type ViewerRow = {
     kind: "warning";
@@ -33,6 +35,8 @@ export declare class DebugLogViewerModel {
     #private;
     constructor(logText: string, options?: DebugLogViewerModelOptions);
     get logCount(): number;
+    /** True once the entry cap is reached, so older history no longer loads. */
+    get historyLimitReached(): boolean;
     get visibleLogCount(): number;
     get rows(): readonly ViewerRow[];
     get cursorRowIndex(): number | undefined;

package/dist/types/apps/debug/raw-sse-buffer.d.ts

@@ -41,6 +41,8 @@ export declare function rawSseRecordLines(record: RawSseDebugRecord): string[];
 /** Bounded, observable capture of raw provider responses and SSE frames. */
 export declare class RawSseDebugBuffer {
     #private;
+    /** Bumped on every change to the captured window (append, eviction, clear); equal revisions mean equal snapshots. */
+    get revision(): number;
     subscribe(listener: () => void): () => void;
     recordResponse(response: ProviderResponseMetadata, model?: Model): void;
     recordEvent(event: RawSseEvent, model?: Model): void;

package/dist/types/apps/git/git-tui.d.ts

@@ -1,5 +1,5 @@
 /**
- * `omp git` — fullscreen repository TUI.
+ * `zetacode git` — fullscreen repository TUI.
  *
  * Layout: header (file path, encoding, stage-file button, close), toolbar
  * (scope chip, file/diff toggle, hunk navigation, hunk/inline/split view
@@ -13,8 +13,9 @@
  * arrows/PgUp/PgDn, vim motions (`j`/`k`/`h`/`l`/`g`/`G`), and mouse
  * clicks/wheel. All toolbar buttons are clickable and mirrored by keys:
  * `v` cycles the view (`1`–`4` pick one), `alt+↓`/`alt+↑` jump hunks and roll
- * into the adjacent file at the edges, `]`/`[` switch files, `s`/`u`
- * stage/unstage (hunk-aware), `x` discards a hunk, `delete` discards the
+ * into the adjacent file at the edges, `space` stages/unstages the focused
+ * diff row (the focused hunk in hunk view), `s`/`u` stage/unstage
+ * (hunk-aware), `x` discards a hunk, `delete` discards the
  * whole file (press twice to confirm), `w` wraps, `b` cycles
  * whitespace handling (exact → ignore whitespace → ignore
  * formatting/import-only changes), `c` jumps to the commit form, `r`
@@ -62,5 +63,5 @@ export interface GitTuiHost {
  * slash command). Resolves when the user closes it; the caller restores focus.
  */
 export declare function showGitOverlay(ui: TUI, host: GitTuiHost): Promise<void>;
-/** Run the fullscreen git TUI standalone (`omp git`) until the user quits. */
+/** Run the fullscreen git TUI standalone (`zetacode git`) until the user quits. */
 export declare function runGitTui(host: GitTuiHost): Promise<void>;

package/dist/types/apps/git/help.d.ts

@@ -1,4 +1,4 @@
-import type { NativeNode } from "../../native/node.js";
+import type { NativeNode, NativeUiEvent } from "../../native/node.js";
 import type { Component } from "../../tui.js";
 /** The shortcuts overlay; any of `?`, escape or `q` closes it. */
 export declare class GitHelpSheet implements Component {
@@ -10,6 +10,8 @@ export declare class GitHelpSheet implements Component {
     };
     constructor(close: () => void);
     handleInput(data: string): void;
+    /** Close runs what Esc runs. */
+    handleNativeEvent(event: NativeUiEvent): void;
     describe(): NativeNode;
     render(width: number): readonly string[];
     invalidate(): void;

package/dist/types/apps/if-bench-board.d.ts

@@ -1,5 +1,5 @@
 /**
- * Live board and scoreboard for `omp if-bench`.
+ * Live board and scoreboard for `zetacode if-bench`.
  *
  * Interactive terminals get one repainted row per model — a turn ladder that
  * fills as turns pass, the in-flight turn as a spinner cell, and the live
@@ -47,7 +47,7 @@ export interface IfBenchObserver<Turn extends IfBenchTurnRecord = IfBenchTurnRec
     turnFinished?(label: string, record: Turn): void;
     modelFinished?(report: Report): void;
 }
-/** Rendering surface for one `omp if-bench` run. */
+/** Rendering surface for one `zetacode if-bench` run. */
 export interface IfBenchBoard extends IfBenchObserver {
     readonly interactive: boolean;
     /** Print a permanent line above the live rows (plain write when non-TTY). */

package/dist/types/apps/setup-model-picker.d.ts

@@ -1,5 +1,5 @@
 /**
- * Standalone TUI model picker used by `omp setup speech`.
+ * Standalone TUI model picker used by `zetacode setup speech`.
  *
  * One-shot {@link selectStandaloneItem} prompt: resolve on select/cancel and
  * let the adapter tear the UI down. The standalone TUI auto-renders on input,

package/dist/types/autocomplete.d.ts

@@ -77,8 +77,11 @@ export interface AutocompleteProvider {
     };
     /** Get inline hint text to show as dim ghost text after the cursor */
     getInlineHint?(lines: string[], cursorLine: number, cursorCol: number): string | null;
-    /** Synchronously try to complete a slash command at the start of a line (no async I/O). */
-    /** Returns matched items and the full prefix, or null if not applicable. */
+    /**
+     * Synchronously list slash command-name completions for a leading slash token (no async I/O).
+     * Mirrors the command-name branch of {@link getSuggestions}, including the bare `/` listing and
+     * the collapsed `/skill:` namespace row. Returns null outside a command-name token or with no match.
+     */
     trySyncSlashCompletion?(textBeforeCursor: string): {
         items: AutocompleteItem[];
         prefix: string;