@oh-my-pi/pi-tui 18.6.1 → 18.7.0

package/dist/types/space-hold.d.ts

@@ -1,45 +1,60 @@
-/** Max gap (ms) between two spaces for the later one to count as OS key auto-repeat rather than a
- *  deliberate press. OS auto-repeat is fast; a deliberate tap (even a fast one) is slower. */
+import { type KeyId } from "./keys.js";
+/** Printable text a push-to-talk candidate key types (plain or shifted single characters and Space),
+ *  or undefined for non-printable keys and chords, which the gesture reserves instead of typing. */
+export declare function getSpaceHoldText(data: string, canonical: string | undefined): string | undefined;
+/** Max gap (ms) between two configured-key presses for a later one to count as OS key auto-repeat
+ *  rather than a deliberate press. OS auto-repeat is fast; a deliberate tap (even a fast one) is slower. */
 export declare const SPACE_REPEAT_MAX_GAP_MS = 120;
-/** Two consecutive inter-space gaps are "mechanical" (machine-driven auto-repeat) when both are
+/** Two consecutive inter-key gaps are "mechanical" (machine-driven auto-repeat) when both are
  *  within {@link SPACE_REPEAT_MAX_GAP_MS} and differ by no more than this — an absolute jitter floor
  *  or, for slower repeat rates, {@link SPACE_REPEAT_JITTER_RATIO} of the smaller gap. OS key-repeat
- *  is metronomic; a human smashing the bar is fast but irregular, so its deltas never stay this
- *  steady. */
+ *  is metronomic; human typing is irregular, so its deltas do not stay this steady. */
 export declare const SPACE_REPEAT_JITTER_MS = 18;
 export declare const SPACE_REPEAT_JITTER_RATIO = 0.35;
-/** Consecutive mechanical (fast + steady) deltas that confirm the space bar is held and start
- *  recording. Needs a sustained metronomic cadence, so jittery smashing and deliberate taps never
+/** Consecutive mechanical (fast + steady) deltas that confirm a configured key is held and start
+ *  recording. Needs a sustained metronomic cadence, so jittery typing and deliberate taps never
  *  reach it. */
 export declare const SPACE_HOLD_MECHANICAL_RUN = 2;
-/** Idle gap (ms) after the last repeated space that counts as the space bar being released, ending
- *  the push-to-talk recording. Must comfortably exceed the OS key-repeat interval. */
+/** Idle gap (ms) after the last repeated configured-key press that counts as release and ends
+ *  push-to-talk. Must comfortably exceed the OS key-repeat interval. */
 export declare const SPACE_HOLD_RELEASE_MS = 250;
-/** What a recognized space-bar hold drives — the push-to-talk start and stop. */
+/** A release timer firing more than this (ms) past its deadline means the event loop stalled (a
+ *  synchronous microphone open, GC, a heavy render) while the bar may still be held: the repeats
+ *  emitted during the stall are queued but unread, so the stall must not read as a release. */
+export declare const SPACE_HOLD_STALL_SLACK_MS = 100;
+/** What a recognized push-to-talk hold drives — the start and stop callbacks. */
 export interface SpaceHoldHandler {
-    /** Gate for the gesture. Returns false to keep the space bar inserting spaces normally, so
-     *  disabling push-to-talk restores plain space behavior. */
+    /** Gate for the gesture. Returns false to let matching keys behave normally. */
     enabled(): boolean;
-    /** A sustained hold was recognized. The optimistically-typed spaces have already been deleted. */
+    /** A sustained hold was recognized; any safely typed candidate text has already been deleted. */
     onStart(): void;
-    /** The held space bar was released (an idle gap with no further repeated spaces, or any other key). */
+    /** The held key was released (an idle gap with no further repeats, or any other key). */
     onEnd(): void;
 }
 /** What the host must do with a keypress after {@link SpaceHoldGesture.process} has seen it:
- *  `"pass"` — handle it normally; `"type"` — insert the space now (it is tracked back out if the run
- *  turns into a hold); `"swallow"` — drop it, the gesture consumed it. */
+ *  `"pass"` — handle it normally; `"type"` — insert its safely decoded printable text now (it is
+ *  tracked back out if the run turns into a hold); `"swallow"` — drop it, the gesture consumed it. */
 export type SpaceHoldStep = "pass" | "type" | "swallow";
-/** Space-hold push-to-talk state machine. A held space bar emits OS auto-repeat: a *steady* stream
- *  of spaces at a fixed fast interval. We watch the inter-space deltas and only recognize a hold once
- *  {@link SPACE_HOLD_MECHANICAL_RUN} consecutive deltas are "mechanical" — both auto-repeat-fast and
- *  near-identical (see {@link gapsAreMechanical}). Smashing the bar is fast but jittery and deliberate
- *  taps are too slow, so neither escalates and both keep typing real spaces; the few spaces typed
- *  before a real hold is recognized are tracked back out of the host input. */
+/** Push-to-talk key-hold state machine. A held key emits OS auto-repeat at a steady fast interval.
+ *  We watch inter-key deltas and only recognize a hold once {@link SPACE_HOLD_MECHANICAL_RUN}
+ *  consecutive deltas are mechanical (see {@link gapsAreMechanical}). Deliberate taps and jittery
+ *  runs stay typed; only text typed during the current steady run is removed on recognition. */
 export declare class SpaceHoldGesture {
     #private;
-    /** Unset (the default) keeps the space bar typing spaces. */
+    /** Configured alternative keys. Alternatives are tracked independently and never combine into one run. */
+    get keys(): readonly KeyId[];
+    set keys(keys: readonly KeyId[]);
+    /** Unset (the default) keeps configured keys behaving normally. */
     handler: SpaceHoldHandler | undefined;
     constructor(deleteTyped: (count: number) => void, allowed?: () => boolean);
-    /** Feed one keypress, `isSpace` when it is a plain space bar press. */
-    process(isSpace: boolean): SpaceHoldStep;
+    /** Pure focused-owner preflight on raw input: whether the key must reach the host before
+     *  TUI-wide input listeners. Only non-printable bindings are claimed — they would otherwise
+     *  trigger app shortcuts mid-hold; printable candidates keep the normal listener path so
+     *  raw-input observers (e.g. extensions) still see typed text, as they did before remapping. */
+    shouldRoute(data: string): boolean;
+    /** Feed one canonical keypress and, when safely printable, its decoded text length. The host
+     *  records the actual inserted length with {@link recordTyped} after applying normal typing. */
+    process(key: string | undefined, insertedCharacterLength?: number): SpaceHoldStep;
+    /** Account for text the host actually inserted for the preceding `"type"` step. */
+    recordTyped(insertedCharacterLength: number): void;
 }

package/dist/types/terminal-capabilities.d.ts

@@ -284,6 +284,13 @@ export interface ImageRenderOptions {
     placementId?: number;
     /** When true (Kitty + {@link imageId}), also return the one-time transmit sequence. */
     includeTransmit?: boolean;
+    /**
+     * SIXEL sequence for the target pixel size renderImage computes, so the
+     * caller can encode off the JS thread: answer `undefined` while the encode
+     * is pending (the image's rows stay reserved) and `null` once it failed.
+     * Without a provider, renderImage encodes synchronously.
+     */
+    sixel?: (widthPx: number, heightPx: number) => string | null | undefined;
 }
 export declare function getCellDimensions(): CellDimensions;
 export declare function setCellDimensions(dims: CellDimensions): void;
@@ -381,6 +388,12 @@ export declare function getJpegDimensions(base64Data: string): ImageDimensions |
 export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
 export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
 export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
+/**
+ * SIXEL sequence for `base64Data` at the given pixel size, encoded on the JS
+ * thread; `null` when the encode fails. For output that cannot wait for an
+ * off-thread encode.
+ */
+export declare function encodeSixelNow(base64Data: string, widthPx: number, heightPx: number): string | null;
 export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
     sequence?: string;
     lines?: string[];

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

@@ -12,6 +12,10 @@ export interface GlobToolDetails {
     fileCount?: number;
     files?: string[];
     truncated?: boolean;
+    /** The scan hit the tool deadline, so the listed files are an incomplete
+     * set rather than a complete answer. Distinct from `truncated`, which also
+     * covers result-limit and output truncation. */
+    timedOut?: boolean;
     error?: string;
     /** Working directory at search time. Used by the renderer to resolve relative
      * file paths to absolute paths for OSC 8 hyperlinks. */

package/dist/types/tui.d.ts

@@ -150,6 +150,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
      */

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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.6.1",
+	"version": "18.7.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -41,14 +41,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.6.1",
-		"@oh-my-pi/pi-agent-core": "18.6.1",
-		"@oh-my-pi/pi-ai": "18.6.1",
-		"@oh-my-pi/pi-catalog": "18.6.1",
-		"@oh-my-pi/pi-natives": "18.6.1",
-		"@oh-my-pi/pi-utils": "18.6.1",
-		"@oh-my-pi/pi-wire": "18.6.1",
-		"@oh-my-pi/snapcompact": "18.6.1"
+		"@oh-my-pi/omptype": "18.7.0",
+		"@oh-my-pi/pi-agent-core": "18.7.0",
+		"@oh-my-pi/pi-ai": "18.7.0",
+		"@oh-my-pi/pi-catalog": "18.7.0",
+		"@oh-my-pi/pi-natives": "18.7.0",
+		"@oh-my-pi/pi-utils": "18.7.0",
+		"@oh-my-pi/pi-wire": "18.7.0",
+		"@oh-my-pi/snapcompact": "18.7.0"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/app-keybindings.ts

@@ -60,6 +60,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;
 }
@@ -237,9 +238,13 @@ export const KEYBINDINGS = {
 		defaultKeys: "ctrl+r",
 		description: "Search history",
 	},
+	"app.stt.pushToTalk": {
+		defaultKeys: "space",
+		description: "Hold to record speech-to-text",
+	},
 	"app.stt.toggle": {
 		defaultKeys: [],
-		description: "Toggle speech-to-text (default gesture: hold Space)",
+		description: "Toggle speech-to-text recording",
 	},
 	"app.live.toggle": {
 		defaultKeys: "ctrl+l",

package/src/apps/git/diff-pane.ts

@@ -601,6 +601,12 @@ export class DiffPane {
 	#layoutCache: { key: string; visuals: Visual[] } | undefined;
 	/** Per visible row: clickable hunk-button ranges recorded during render. */
 	#hits: ({ hunk: number; primary?: [number, number]; discard?: [number, number] } | undefined)[] = [];
+	/**
+	 * Asset images from the last render, by placement and size. Reusing them
+	 * lets a SIXEL image show the sequence its off-thread encode delivers on a
+	 * later render; a fresh `Image` per render would restart the encode forever.
+	 */
+	#assetImages = new Map<string, Image>();
 	constructor(imageBudget?: ImageBudget) {
 		this.#imageBudget = imageBudget;
 	}
@@ -1103,8 +1109,16 @@ export class DiffPane {
 		const leftWidth = Math.max(1, Math.floor((width - 1) / 2));
 		const rightWidth = Math.max(1, width - leftWidth - 1);
 		const bodyHeight = Math.max(0, height - 1);
-		const oldLines = this.#renderAssetSide(asset.old, leftWidth, bodyHeight, `old:${asset.filePath}`);
-		const newLines = this.#renderAssetSide(asset.new, rightWidth, bodyHeight, `new:${asset.filePath}`);
+		const previousImages = this.#assetImages;
+		this.#assetImages = new Map();
+		const oldLines = this.#renderAssetSide(asset.old, leftWidth, bodyHeight, `old:${asset.filePath}`, previousImages);
+		const newLines = this.#renderAssetSide(
+			asset.new,
+			rightWidth,
+			bodyHeight,
+			`new:${asset.filePath}`,
+			previousImages,
+		);
 		const border = theme.fg("borderMuted", "│");
 		const lines: string[] = [];
 		for (let index = 0; index < height; index++) {
@@ -1125,24 +1139,36 @@ export class DiffPane {
 		return lines;
 	}
 
-	#renderAssetSide(side: FileAssetSide, width: number, height: number, placementKey: string): readonly string[] {
+	#renderAssetSide(
+		side: FileAssetSide,
+		width: number,
+		height: number,
+		placementKey: string,
+		previousImages: ReadonlyMap<string, Image>,
+	): readonly string[] {
 		if (height <= 0) return [];
 		let content: readonly string[];
 		if (side.kind === "image") {
 			const image = side.image;
-			content = new Image(
-				image.data,
-				image.mimeType,
-				{ fallbackColor: text => theme.fg("dim", text) },
-				{
-					maxWidthCells: Math.max(1, width - 2),
-					maxHeightCells: height,
-					filename: this.#asset?.filePath,
-					budget: this.#imageBudget,
-					imageKey: `git-review:${placementKey}:${image.key}`,
-				},
-				{ widthPx: image.widthPx, heightPx: image.heightPx },
-			).render(width);
+			const imageKey = `git-review:${placementKey}:${image.key}`;
+			const cacheKey = `${imageKey}:${width}x${height}`;
+			const component =
+				previousImages.get(cacheKey) ??
+				new Image(
+					image.data,
+					image.mimeType,
+					{ fallbackColor: text => theme.fg("dim", text) },
+					{
+						maxWidthCells: Math.max(1, width - 2),
+						maxHeightCells: height,
+						filename: this.#asset?.filePath,
+						budget: this.#imageBudget,
+						imageKey,
+					},
+					{ widthPx: image.widthPx, heightPx: image.heightPx },
+				);
+			this.#assetImages.set(cacheKey, component);
+			content = component.render(width);
 		} else {
 			let details: string[];
 			switch (side.kind) {

package/src/apps/git/git-tui.ts

@@ -26,7 +26,7 @@
  */
 
 import type { TspSpan } from "@oh-my-pi/pi-wire";
-import { formatKeyHint, formatKeyHints } from "../../app-keybindings";
+import { formatKeyHint, formatKeyHints, formatTooltipKey } from "../../app-keybindings";
 import { SplitPane } from "../../components/layout/split-pane";
 import { Stack } from "../../components/layout/stack";
 import { matchesKey } from "../../keys";
@@ -1030,8 +1030,8 @@ class GitTuiComponent implements Component {
 		const right: NativeNode[] = [
 			row(
 				[
-					iconButton("chev-up", "prev-hunk", `Previous change (${formatKeyHint("alt+up")})`),
-					iconButton("chev", "next-hunk", `Next change (${formatKeyHint("alt+down")})`),
+					iconButton("chev-up", "prev-hunk", `Previous change (${formatTooltipKey("alt+up")})`),
+					iconButton("chev", "next-hunk", `Next change (${formatTooltipKey("alt+down")})`),
 				],
 				{ gap: "none", align: "center" },
 			),
@@ -1052,13 +1052,13 @@ class GitTuiComponent implements Component {
 					"type",
 					"whitespace",
 					this.#whitespace === "off"
-						? `Ignore whitespace (${formatKeyHint("b")})`
+						? `Ignore whitespace (${formatTooltipKey("b")})`
 						: this.#whitespace === "whitespace"
-							? `Ignoring whitespace; also ignore formatting (${formatKeyHint("b")})`
-							: `Ignoring formatting and imports; show all (${formatKeyHint("b")})`,
+							? `Ignoring whitespace; also ignore formatting (${formatTooltipKey("b")})`
+							: `Ignoring formatting and imports; show all (${formatTooltipKey("b")})`,
 					this.#whitespace !== "off",
 				),
-				iconButton("corner-down-right", "wrap", `Wrap lines (${formatKeyHint("w")})`, this.#pane.wrap),
+				iconButton("corner-down-right", "wrap", `Wrap lines (${formatTooltipKey("w")})`, this.#pane.wrap),
 			);
 		}
 		if (file?.area === "unstaged" || file?.area === "staged") {
@@ -1070,8 +1070,8 @@ class GitTuiComponent implements Component {
 			);
 		}
 		right.push(
-			iconButton("keyboard", "help", `Keyboard shortcuts (${formatKeyHint("?")})`),
-			iconButton("x", "close", `Close (${formatKeyHint("q")})`),
+			iconButton("keyboard", "help", `Keyboard shortcuts (${formatTooltipKey("?")})`),
+			iconButton("x", "close", `Close (${formatTooltipKey("q")})`),
 		);
 		return keyed(
 			row(

package/src/apps/git/sidebar.ts

@@ -1699,7 +1699,12 @@ export class Sidebar {
 					png,
 					"image/png",
 					{ fallbackColor: text => theme.fg("dim", text) },
-					{ maxHeightCells: 3, budget: this.#imageBudget, imageKey: `git-avatar:${email}` },
+					{
+						maxHeightCells: 3,
+						budget: this.#imageBudget,
+						imageKey: `git-avatar:${email}`,
+						requestRender: this.#requestRender,
+					},
 				),
 			};
 		}

package/src/autocomplete.ts

@@ -263,8 +263,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 } | null;
 	/**
 	 * Synchronously try to expand text immediately before the cursor (no async I/O).
@@ -806,7 +809,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 			};
 		}
 
-		// Slash command suggestions can be accepted before the debounced refresh
+		// Slash command suggestions can be accepted before an async refresh
 		// catches up to newly typed characters. Replace the live command token,
 		// not only the prefix captured when the suggestion list was rendered.
 		// Absolute-path completions share the leading-slash prefix shape but
@@ -1300,19 +1303,14 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		const slashStart = findLeadingSlashCommandStart(textBeforeCursor);
 		if (slashStart === null) return null;
 		const commandText = textBeforeCursor.slice(slashStart);
-		if (commandText.length <= 1) return null; // Bare "/" alone, don't auto-complete
 		if (commandText.includes(" ")) return null; // Only complete command name, not args
 
-		const prefix = commandText.slice(1);
-		const lowerPrefix = prefix.toLowerCase();
-
-		// The `/skill:` namespace row is excluded here: the sync path submits
-		// immediately after applying, and the bare namespace is not a command.
+		const lowerPrefix = commandText.slice(1).toLowerCase();
 		const matches = buildSlashCommandCompletions(
 			collapseSkillNamespace(this.#commands, lowerPrefix),
 			lowerPrefix,
 			this.#commandUsage,
-		).filter(item => item.value !== SKILL_NAMESPACE);
+		);
 
 		if (matches.length === 0) return null;
 		// Mirror `getSuggestions`: preserve leading whitespace so the editor's