@oh-my-pi/pi-tui 18.3.0 → 18.3.2

package/src/overlays/rewind-selector.ts

@@ -19,12 +19,15 @@
  *
  * Keys: Up/Down step through rendered items in transcript order (within the
  * active column when a strip is open), Left/Right slide between branch
- * variants at a fork and jump between user turns elsewhere, Enter rewinds to
- * the outlined item, Esc cancels.
+ * variants at a fork and jump between user turns elsewhere, `f` opens a
+ * filter (typing narrows the current path to matching items; Esc leaves the
+ * filter with the selection kept), Enter rewinds to the outlined item, Esc
+ * cancels.
  */
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import {
 	type Component,
+	extractPrintableText,
 	matchesKey,
 	padding,
 	routeSgrMouseInput,
@@ -110,6 +113,13 @@ export class RewindSelectorComponent implements Component {
 	#slide: { from: number; to: number; startedAt: number } | undefined;
 	#slideTimer: NodeJS.Timeout | undefined;
 
+	/** Filter query while the filter prompt is open; undefined shows the full transcript. */
+	#filter: string | undefined;
+	/** Main transcript rows from the last frame; the filter matches what is on screen. */
+	#mainRows: readonly (readonly string[])[] = [];
+	/** Lowercased plain text per rendered child row array (row arrays are cached, so identity is stable). */
+	#rowText = new WeakMap<readonly string[], string>();
+
 	constructor(
 		entries: TranscriptEntry[],
 		private readonly deps: RewindSelectorDeps,
@@ -235,19 +245,26 @@ export class RewindSelectorComponent implements Component {
 			});
 			return;
 		}
+		if (this.#filter !== undefined) {
+			this.#handleFilterInput(data);
+			return;
+		}
 		if (matchesSelectCancel(data) || matchesKey(data, "escape")) {
 			this.deps.onCancel();
 			return;
 		}
-		if (matchesAppToolsExpand(data)) {
-			this.#expanded = !this.#expanded;
-			this.#builder.setExpanded(this.#expanded);
-			for (const columns of this.#variantCache.values()) {
-				for (const column of columns) column.builder.setExpanded(this.#expanded);
-			}
+		if (matchesKey(data, "f")) {
+			this.#filter = "";
+			this.#activeVariant = 0;
+			this.#siblingSelected = 0;
+			this.#stopSlide();
 			this.deps.requestRender();
 			return;
 		}
+		if (matchesAppToolsExpand(data)) {
+			this.#toggleExpanded();
+			return;
+		}
 		if (matchesSelectUp(data)) {
 			this.#moveVertical(-1);
 			return;
@@ -282,6 +299,115 @@ export class RewindSelectorComponent implements Component {
 		}
 	}
 
+	#toggleExpanded(): void {
+		this.#expanded = !this.#expanded;
+		this.#builder.setExpanded(this.#expanded);
+		for (const columns of this.#variantCache.values()) {
+			for (const column of columns) column.builder.setExpanded(this.#expanded);
+		}
+		this.deps.requestRender();
+	}
+
+	// ========================================================================
+	// Filter
+	// ========================================================================
+
+	#handleFilterInput(data: string): void {
+		if (matchesSelectCancel(data) || matchesKey(data, "escape")) {
+			this.#closeFilter();
+			return;
+		}
+		if (matchesKey(data, "enter") || matchesKey(data, "return") || data === "\n") {
+			const target = this.#filterMatches().includes(this.#selected) ? this.#targets[this.#selected] : undefined;
+			if (target) this.deps.onSelect(target.entryId);
+			return;
+		}
+		if (matchesAppToolsExpand(data)) {
+			this.#toggleExpanded();
+			return;
+		}
+		if (matchesSelectUp(data) || matchesKey(data, "left")) {
+			const userTurnsOnly = !matchesSelectUp(data);
+			this.#stepFiltered(-1, userTurnsOnly);
+			return;
+		}
+		if (matchesSelectDown(data) || matchesKey(data, "right")) {
+			const userTurnsOnly = !matchesSelectDown(data);
+			this.#stepFiltered(1, userTurnsOnly);
+			return;
+		}
+		if (matchesKey(data, "backspace")) {
+			if (this.#filter!.length === 0) {
+				this.#closeFilter();
+				return;
+			}
+			this.#setFilter(this.#filter!.slice(0, -1));
+			return;
+		}
+		const printable = extractPrintableText(data);
+		if (printable) {
+			this.#setFilter(this.#filter! + printable);
+			return;
+		}
+		if (this.#browser.handleScrollKey(data)) {
+			this.deps.requestRender();
+		}
+	}
+
+	/** Leave the filter, keeping the selected item outlined in the full transcript. */
+	#closeFilter(): void {
+		this.#filter = undefined;
+		this.deps.requestRender();
+	}
+
+	/** Update the query; keep the selection when it still matches, else rest on the newest match above it. */
+	#setFilter(query: string): void {
+		this.#filter = query;
+		const matches = this.#filterMatches();
+		if (!matches.includes(this.#selected)) {
+			this.#selected = matches.findLast(index => index < this.#selected) ?? matches.at(-1) ?? this.#selected;
+		}
+		this.deps.requestRender();
+	}
+
+	#stepFiltered(delta: -1 | 1, userTurnsOnly: boolean): void {
+		const matches = this.#filterMatches().filter(index => !userTurnsOnly || this.#targets[index]!.isUserTurn);
+		const next =
+			delta < 0 ? matches.findLast(index => index < this.#selected) : matches.find(index => index > this.#selected);
+		if (next === undefined) return;
+		this.#selected = next;
+		this.deps.requestRender();
+	}
+
+	/**
+	 * Visible main-path target indices whose rendered text contains every
+	 * whitespace-separated query word as a whole word (case-insensitive: `ls`
+	 * matches `ls -la` but not `tools`); all visible targets for an empty query.
+	 * Matching the rendered rows keeps results honest: collapsed tool output
+	 * only matches once Ctrl+O expands it.
+	 */
+	#filterMatches(): number[] {
+		const words = (this.#filter ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+		const patterns = words.map(
+			word => new RegExp(`(?<![\\p{L}\\p{N}_])${RegExp.escape(word)}(?![\\p{L}\\p{N}_])`, "u"),
+		);
+		const matches: number[] = [];
+		for (let index = 0; index < this.#targets.length; index++) {
+			if (!this.#isMainSelectable(index)) continue;
+			const target = this.#targets[index]!;
+			const texts = this.#mainRows.slice(target.start, target.end).map(rows => {
+				let text = this.#rowText.get(rows);
+				if (text === undefined) {
+					text = Bun.stripANSI(rows.join("\n")).toLowerCase();
+					this.#rowText.set(rows, text);
+				}
+				return text;
+			});
+			if (patterns.every(pattern => texts.some(text => pattern.test(text)))) matches.push(index);
+		}
+		return matches;
+	}
+
 	/** Up/Down: step within the active column; leaving a sibling column's top exits the strip. */
 	#moveVertical(delta: -1 | 1): void {
 		if (this.#activeVariant > 0) {
@@ -337,6 +463,7 @@ export class RewindSelectorComponent implements Component {
 		const children = this.#builder.container.children;
 		const prepared = this.#browser.prepareOutline(children, this.#targets, this.#selected, contentWidth);
 		this.#mainVisible = prepared.visible;
+		this.#mainRows = prepared.childRows;
 		if (prepared.selected !== this.#selected) {
 			// The current target collapsed (e.g. expansion toggle): rest on the
 			// nearest visible one and leave the strip.
@@ -345,6 +472,8 @@ export class RewindSelectorComponent implements Component {
 			this.#siblingSelected = 0;
 		}
 
+		if (this.#filter !== undefined) return this.#filterFrame(this.#filter, prepared.childRows, contentWidth);
+
 		const columns = this.#stripColumns();
 		const composed =
 			columns.length > 0
@@ -359,14 +488,59 @@ export class RewindSelectorComponent implements Component {
 		const position = this.#targets.length > 0 ? `${this.#selected + 1}/${this.#targets.length}  ` : "";
 		const lateral = columns.length > 0 ? "←/→ branches" : "←/→ user turns";
 		return {
-			header: [
-				`${theme.icon.rewind} ${theme.bold("Rewind")}${theme.sep.dot}${theme.fg("dim", "pick the point to continue from")}`,
-			],
+			header: [this.#header()],
 			body: {
 				lines: composed.lines,
 				anchor: this.#outlineAnchor(composed),
 			},
-			footer: [theme.fg("dim", `${position}↑/↓ step  ${lateral}  enter rewind  ctrl+o expand  esc cancel`)],
+			footer: [
+				theme.fg("dim", `${position}↑/↓ step  ${lateral}  f filter  enter rewind  ctrl+o expand  esc cancel`),
+			],
+		};
+	}
+
+	#header(): string {
+		return `${theme.icon.rewind} ${theme.bold("Rewind")}${theme.sep.dot}${theme.fg("dim", "pick the point to continue from")}`;
+	}
+
+	/** Only the matching items of the current path, concatenated; no branch strip. */
+	#filterFrame(
+		query: string,
+		childRows: readonly (readonly string[])[],
+		contentWidth: number,
+	): TranscriptBrowserFrame {
+		const matches = this.#filterMatches();
+		const rows: (readonly string[])[] = [];
+		const targets: OutlineTarget[] = [];
+		for (const index of matches) {
+			const target = this.#targets[index]!;
+			const start = rows.length;
+			rows.push(...childRows.slice(target.start, target.end));
+			targets.push({ ...target, start, end: rows.length });
+		}
+		const selected = matches.indexOf(this.#selected);
+		const composed = composeOutlineColumn(rows, 0, rows.length, targets, selected, contentWidth, undefined);
+		const lines = matches.length > 0 ? composed.lines : [theme.fg("muted", `  No items match "${query}"`)];
+		const count =
+			matches.length === 0
+				? theme.fg("error", "no matches")
+				: theme.fg("dim", `${selected >= 0 ? selected + 1 : "-"}/${matches.length}`);
+		return {
+			header: [this.#header()],
+			body: {
+				lines,
+				anchor:
+					composed.selStart >= 0
+						? {
+								id: `rewind:filter:${query}:${this.#targets[this.#selected]?.turnId ?? this.#selected}`,
+								start: composed.selStart,
+								end: composed.selEnd,
+							}
+						: undefined,
+			},
+			footer: [
+				`${theme.fg("accent", "filter:")} ${query}${theme.fg("accent", "▏")}  ${count}  ${theme.fg("dim", "↑/↓ step  ←/→ user turns  enter rewind  esc show all")}`,
+			],
 		};
 	}
 

package/src/overlays/settings-defs.ts

@@ -75,6 +75,7 @@ export const TAB_GROUPS: Record<SettingTab, readonly string[]> = {
 		"Todos",
 		"Grep & Browser",
 		"Computer",
+		"IDA Pro",
 		"GitHub",
 		"Output Limits",
 		"Execution",
@@ -131,6 +132,11 @@ export interface SettingsHost {
 	entries: readonly SettingsDisplayEntry[];
 	get(path: string): unknown;
 	set(path: string, value: unknown): void;
+	/**
+	 * Removes the value from the global config: a project or other layer, or an environment
+	 * variable, that configures the setting still applies; otherwise the default does.
+	 */
+	unset(path: string): void;
 	normalizeProviderLimits(value: unknown): Record<string, number>;
 	validateProviderLimits(value: unknown): Record<string, number>;
 }

package/src/overlays/settings-selector.ts

@@ -1100,9 +1100,10 @@ export class SettingsSelectorComponent implements Component {
 			this.#formatTextInputEditValue(def.path, this.#context.settings.get(def.path)),
 			def.secret,
 			value => {
-				// Empty string clears the setting; undefined-typed string settings
-				// store "" which the browser.ts expandPath ignores (no-op fallback).
-				this.#setSettingValue(def.path, value);
+				// An empty field removes the persisted value, so the default (or an
+				// environment fallback) applies again instead of a pinned "".
+				if (value === "") this.#context.settings.unset(def.path);
+				else this.#setSettingValue(def.path, value);
 				this.#callbacks.onChange(def.path, this.#context.settings.get(def.path));
 				wrappedDone(this.#formatTextInputValue(def, this.#context.settings.get(def.path)));
 			},

package/src/prompt/composer.ts

@@ -91,6 +91,18 @@ export interface ComposerOptions {
 	readonly now?: () => number;
 }
 
+/** How {@link Composer.setRuntimeChildren} bills below-transcript roots against transcript retirement. */
+export interface RuntimeChildrenOptions {
+	/**
+	 * Below-transcript roots whose growth is momentary (inline dialogs, a tall
+	 * multi-line editor). They are billed at their smallest height so expansion
+	 * clips the live tail instead of retiring rows a later shrink could not
+	 * reclaim (#11007). Every other root is billed at its current height, so
+	 * settled rows it displaces retire to native scrollback.
+	 */
+	readonly transient?: readonly Component[];
+}
+
 /** Controls the first terminal paint for a composer that does not already own the terminal. */
 export interface ComposerStartOptions {
 	readonly clearScrollback?: boolean;
@@ -253,15 +265,18 @@ export class Composer implements TerminalFrameProvider {
 	#retiredHeaderStart = 0;
 	#resizeRetiredHeaderStart: number | undefined;
 	#lastNormalRows = 0;
-	// Smallest below-transcript chrome height (editor + status + any transient
-	// inline dialog) seen since mount. Retirement is billed against this
-	// persistent baseline, never the transient peak, so a dialog or tall editor
-	// that later shrinks never leaves committed transcript rows the live viewport
-	// cannot reclaim (#11007). The baseline is terminal-height independent — the
-	// editor and status floors do not scale with rows — so it is retained across
-	// resizes rather than rediscovered from whatever chrome is expanded at the
-	// moment the height changes.
-	#retirementBelowFloor: number | undefined;
+	// Roots from `RuntimeChildrenOptions.transient`, and the smallest height
+	// they have rendered at since mount. Retirement bills transient roots at
+	// this floor, never their peak, so a dialog or tall editor that later
+	// shrinks never leaves committed transcript rows the live viewport cannot
+	// reclaim (#11007). Persistent roots (loader, todo/subagent HUDs) bill at
+	// their current height: they stay up for a whole turn, and billing them at
+	// an idle floor hid the settled rows they displaced until the turn ended.
+	// The floor is terminal-height independent — editor and dialog heights do
+	// not scale with rows — so it is retained across resizes rather than
+	// rediscovered from whatever chrome is expanded when the height changes.
+	#transientChrome: ReadonlySet<Component> = new Set();
+	#transientChromeFloor: number | undefined;
 	#lastInterruptAt = 0;
 	#started = false;
 	#stopped = false;
@@ -346,60 +361,24 @@ export class Composer implements TerminalFrameProvider {
 		const afterRoots = roots.slice(transcriptIndex + 1);
 		const after: string[] = [];
 		const afterSpans: ViewportClickSpan[] = [];
+		let transientRows = 0;
 		for (const root of afterRoots) {
 			const start = after.length;
-			// Row targets usually nest one level down: chrome roots are plain
-			// containers (the HUD lives inside `subagentContainer`), and
-			// `Container.render` is a pure concatenation, so child spans tile
-			// the root span exactly. Render those children once and share the
-			// rows for composition and measurement — a second render per frame
-			// would duplicate render-time side effects (image placement
-			// registration). Roots with a custom render keep the composed
-			// output as the source of truth and measure up to the last target.
-			const plainContainer = root instanceof Container && root.render === Container.prototype.render;
-			const targets = root instanceof Container ? root.children : [root];
-			const resolves = targets.map(rowTargetCandidates);
-			const lastTarget = resolves.findLastIndex(resolve => resolve !== undefined);
-			if (plainContainer) {
-				let offset = start;
-				for (let index = 0; index < targets.length; index++) {
-					const childLines = targets[index]!.render(width);
-					after.push(...childLines);
-					if (index > lastTarget) continue;
-					const resolve = resolves[index];
-					if (resolve !== undefined && childLines.length > 0) {
-						afterSpans.push({ start: offset, end: offset + childLines.length, candidates: resolve });
-					}
-					offset += childLines.length;
-				}
-				continue;
-			}
-			after.push(...root.render(width));
-			if (lastTarget === -1) continue;
-			let offset = start;
-			for (let index = 0; index <= lastTarget; index++) {
-				const childLines = targets[index] === root ? after.length - start : targets[index]!.render(width).length;
-				const resolve = resolves[index];
-				if (resolve !== undefined && childLines > 0) {
-					afterSpans.push({ start: offset, end: offset + childLines, candidates: resolve });
-				}
-				offset += childLines;
-			}
+			this.#renderBelowRoot(root, width, after, afterSpans);
+			if (this.#transientChrome.has(root)) transientRows += after.length - start;
 		}
 		// Offer history under capacity pressure only: blocks stay live (and keep
 		// reflowing to the current width) while the screen has room. A batch
 		// leaves the mutable viewport in the same frame it is appended, so its
 		// rows are never painted twice.
 		//
-		// Retirement is billed against the persistent below-transcript chrome
-		// baseline, not the transient peak: a confirmation dialog or a tall
-		// multi-line editor swapped in below the transcript clips the live tail
-		// for its lifetime, but must not permanently commit transcript rows to
-		// native history — otherwise a later shrink cannot refill the freed rows
-		// and the editor drifts up above a band of blank rows (#11007).
-		this.#retirementBelowFloor =
-			this.#retirementBelowFloor === undefined ? after.length : Math.min(this.#retirementBelowFloor, after.length);
-		const belowFloor = this.#retirementBelowFloor;
+		// Retirement bills transient roots at their floor, not their peak: a
+		// confirmation dialog or a tall multi-line editor clips the live tail for
+		// its lifetime, but must not permanently commit transcript rows to native
+		// history — otherwise a later shrink cannot refill the freed rows and the
+		// editor drifts up above a band of blank rows (#11007).
+		this.#transientChromeFloor = Math.min(this.#transientChromeFloor ?? transientRows, transientRows);
+		const belowFloor = after.length - transientRows + this.#transientChromeFloor;
 		const history = this.#offerHistory(transcript, width, rows, preRoots.length + belowFloor);
 		const headerVisible = !this.#headerRetired && this.#offeredHistory?.source !== "header";
 		const headerRows = headerVisible ? this.#header.render(width) : [];
@@ -443,6 +422,52 @@ export class Composer implements TerminalFrameProvider {
 		return { history, viewport: this.#paintHoverBand(mutable, spans) };
 	}
 
+	/**
+	 * Append one below-transcript root's rows to `after`, recording click spans
+	 * for its row targets in `after` coordinates.
+	 *
+	 * Row targets usually nest one level down: chrome roots are plain
+	 * containers (the HUD lives inside `subagentContainer`), and
+	 * `Container.render` is a pure concatenation, so child spans tile the root
+	 * span exactly. Render those children once and share the rows for
+	 * composition and measurement — a second render per frame would duplicate
+	 * render-time side effects (image placement registration). Roots with a
+	 * custom render keep the composed output as the source of truth and measure
+	 * up to the last target.
+	 */
+	#renderBelowRoot(root: Component, width: number, after: string[], spans: ViewportClickSpan[]): void {
+		const start = after.length;
+		const plainContainer = root instanceof Container && root.render === Container.prototype.render;
+		const targets = root instanceof Container ? root.children : [root];
+		const resolves = targets.map(rowTargetCandidates);
+		const lastTarget = resolves.findLastIndex(resolve => resolve !== undefined);
+		if (plainContainer) {
+			let offset = start;
+			for (let index = 0; index < targets.length; index++) {
+				const childLines = targets[index]!.render(width);
+				after.push(...childLines);
+				if (index > lastTarget) continue;
+				const resolve = resolves[index];
+				if (resolve !== undefined && childLines.length > 0) {
+					spans.push({ start: offset, end: offset + childLines.length, candidates: resolve });
+				}
+				offset += childLines.length;
+			}
+			return;
+		}
+		after.push(...root.render(width));
+		if (lastTarget === -1) return;
+		let offset = start;
+		for (let index = 0; index <= lastTarget; index++) {
+			const childLines = targets[index] === root ? after.length - start : targets[index]!.render(width).length;
+			const resolve = resolves[index];
+			if (resolve !== undefined && childLines > 0) {
+				spans.push({ start: offset, end: offset + childLines, candidates: resolve });
+			}
+			offset += childLines;
+		}
+	}
+
 	/**
 	 * Band the hovered click target's current rows. Id-anchored (not
 	 * line-anchored) so the band follows an agent whose rows shift while it
@@ -847,8 +872,10 @@ export class Composer implements TerminalFrameProvider {
 	}
 
 	/** Mount or replace session-aware root children while preserving the header and status hosts. */
-	setRuntimeChildren(children: readonly Component[]): void {
+	setRuntimeChildren(children: readonly Component[], options: RuntimeChildrenOptions = {}): void {
 		if (this.#stopped) return;
+		this.#transientChrome = new Set(options.transient);
+		this.#transientChromeFloor = undefined;
 		this.ui.removeChild(this.#statusHost);
 		if (this.#runtimeMounted) {
 			for (const child of this.#runtimeChildren) this.ui.removeChild(child);

package/src/prompt/custom-editor.ts

@@ -5,6 +5,7 @@ import { BRACKETED_PASTE_END, BRACKETED_PASTE_START } from "../stdin-buffer";
 import { Editor, type EditorTextDecorationContext, type EditorTheme } from "../components/editor";
 import { addKeyAliases, canonicalKeyId, getKeybindings } from "../keybindings";
 import { type KeyId, parseKey, parseKittySequence } from "../keys";
+import { SpaceHoldGesture } from "../space-hold";
 import { TUI } from "../tui";
 import type { AppKeybinding } from "../app-keybindings";
 import { allowsModelMentions, allowsSkillTokens, SKILL_TOKEN_RE } from "./skill-tokens";
@@ -117,34 +118,6 @@ const ABSOLUTE_PATH_PREFIX_REGEX = new RegExp(`^${ABSOLUTE_PATH_PREFIX_SOURCE}`)
  */
 const INTERIOR_PATH_ANCHOR_REGEX = new RegExp(String.raw`(?<!\\)\s(?:${ABSOLUTE_PATH_PREFIX_SOURCE}|\.\.?[\\/])`);
 
-/** 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. */
-export const SPACE_REPEAT_MAX_GAP_MS = 120;
-/** Two consecutive inter-space 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. */
-export const SPACE_REPEAT_JITTER_MS = 18;
-export 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
- *  reach it. */
-export 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. */
-export const SPACE_HOLD_RELEASE_MS = 250;
-
-/** Whether two consecutive inter-space gaps look machine-driven: both within the auto-repeat band
- *  and steady enough (small absolute or proportional difference). OS key-repeat is metronomic, so
- *  its successive deltas match closely; human smashing is fast but irregular and deliberate taps are
- *  too slow, so neither passes. */
-function gapsAreMechanical(gap: number, prevGap: number): boolean {
-	if (gap > SPACE_REPEAT_MAX_GAP_MS || prevGap > SPACE_REPEAT_MAX_GAP_MS) return false;
-	const tolerance = Math.max(SPACE_REPEAT_JITTER_MS, Math.min(gap, prevGap) * SPACE_REPEAT_JITTER_RATIO);
-	return Math.abs(gap - prevGap) <= tolerance;
-}
-
 function isPastedPathSeparator(char: string | undefined): boolean {
 	return char === undefined || char === " " || char === "\t" || char === "\r" || char === "\n";
 }
@@ -902,15 +875,13 @@ export class CustomEditor extends Editor {
 	/** Called when left-arrow is pressed while the editor is empty (cursor necessarily at start). */
 	onLeftAtStart?: () => void;
 
-	/** Fired when a sustained space-bar hold is recognized — the push-to-talk STT start. The
-	 *  optimistically-typed spaces have already been deleted by the time this runs. */
-	onSpaceHoldStart?: () => void;
-	/** Fired when the held space bar is released (detected as an idle gap with no further repeated
-	 *  spaces) — the push-to-talk STT stop. */
-	onSpaceHoldEnd?: () => void;
-	/** Gate for the space-hold gesture. Returns false to keep the space bar inserting spaces
-	 *  normally; wired to `stt.enabled` so disabling STT restores plain space behavior. */
-	sttHoldEnabled?: () => boolean;
+	/** Space-bar push-to-talk; set its `handler` to enable it. It is a text-composition gesture, so it
+	 *  stays out of Vim's Normal/Visual modes (where the space bar is the `l` motion) and away from an
+	 *  open autocomplete menu. */
+	readonly spaceHold = new SpaceHoldGesture(
+		count => this.deleteBeforeCursor(count),
+		() => this.vimMode === "insert" && !this.isShowingAutocomplete(),
+	);
 
 	/** Custom key handlers from extensions and non-built-in app actions. */
 	#customKeyHandlers = new Map<KeyId, () => void>();
@@ -928,18 +899,6 @@ export class CustomEditor extends Editor {
 	/** Input chunks deferred behind an in-flight paste, drained in FIFO order once the paste
 	 *  count returns to zero. */
 	#pendingInput: string[] = [];
-	/** Spaces actually inserted in the current run; tracked back out when a hold is recognized. */
-	#spaceRunInserted = 0;
-	/** Consecutive "mechanical" deltas (fast + steady); a sustained run of these confirms a held bar. */
-	#mechanicalRun = 0;
-	/** Inter-space gap (ms) of the previous space pair, compared against the next to judge steadiness. */
-	#prevSpaceGap: number | undefined;
-	/** Monotonic timestamp (ms) of the last space, to measure the gap to the next one. */
-	#lastSpaceAt = Number.NEGATIVE_INFINITY;
-	/** True while a recognized space-hold push-to-talk recording is in progress. */
-	#spaceHoldActive = false;
-	/** Idle timer that fires `onSpaceHoldEnd` once repeated spaces stop arriving. */
-	#spaceHoldTimer: NodeJS.Timeout | undefined;
 	#actionKeys = new Map<ConfigurableEditorAction, KeyId[]>(
 		Object.entries(DEFAULT_ACTION_KEYS).map(([action, keys]) => [action as ConfigurableEditorAction, [...keys]]),
 	);
@@ -1004,93 +963,6 @@ export class CustomEditor extends Editor {
 		this.#rebuildCustomMatchKeys();
 	}
 
-	#spaceHoldGestureEnabled(): boolean {
-		// Push-to-talk is a text-composition gesture, so it stays out of Vim's Normal/Visual modes
-		// where the space bar is the `l` motion.
-		if (this.vimMode !== "insert") return false;
-		return this.onSpaceHoldStart !== undefined && (this.sttHoldEnabled?.() ?? false) && !this.isShowingAutocomplete();
-	}
-
-	/** Drive the space-hold push-to-talk state machine. Returns true when the gesture consumed the
-	 *  input so it must not reach normal editing. 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. */
-	#handleSpaceHold(data: string, canonical: string | undefined): boolean {
-		const isSpace = canonical === "space";
-		if (this.#spaceHoldActive) {
-			if (isSpace) {
-				// Auto-repeat while held: swallow it and keep the release timer alive.
-				this.#armSpaceHoldReleaseTimer();
-				return true;
-			}
-			// Any non-space means the bar was released — stop recording, then let the key through.
-			this.#endSpaceHold();
-			return false;
-		}
-		if (!isSpace) {
-			this.#resetSpaceRun();
-			return false;
-		}
-		if (!this.#spaceHoldGestureEnabled()) return false;
-		const now = performance.now();
-		const gap = now - this.#lastSpaceAt;
-		const prevGap = this.#prevSpaceGap;
-		this.#lastSpaceAt = now;
-		this.#prevSpaceGap = gap;
-		if (prevGap === undefined || !gapsAreMechanical(gap, prevGap)) {
-			// First space, a deliberate tap, or jittery smashing: not a steady machine cadence yet, so
-			// type a real space and reset the mechanical run.
-			this.#mechanicalRun = 0;
-			this.#forwardInput(data);
-			this.#spaceRunInserted++;
-			return true;
-		}
-		// Steady fast repeat: swallow it. Once the cadence has held for SPACE_HOLD_MECHANICAL_RUN
-		// deltas it's a held bar — track back the few pre-burst spaces already typed and start.
-		if (++this.#mechanicalRun >= SPACE_HOLD_MECHANICAL_RUN) {
-			this.deleteBeforeCursor(this.#spaceRunInserted);
-			this.#resetSpaceRun();
-			this.#beginSpaceHold();
-		}
-		return true;
-	}
-
-	#resetSpaceRun(): void {
-		this.#spaceRunInserted = 0;
-		this.#mechanicalRun = 0;
-		this.#prevSpaceGap = undefined;
-		this.#lastSpaceAt = Number.NEGATIVE_INFINITY;
-	}
-
-	#beginSpaceHold(): void {
-		this.#spaceHoldActive = true;
-		this.#armSpaceHoldReleaseTimer();
-		this.onSpaceHoldStart?.();
-	}
-
-	#armSpaceHoldReleaseTimer(): void {
-		if (this.#spaceHoldTimer) clearTimeout(this.#spaceHoldTimer);
-		this.#spaceHoldTimer = setTimeout(() => {
-			this.#spaceHoldTimer = undefined;
-			this.#endSpaceHold();
-		}, SPACE_HOLD_RELEASE_MS);
-		this.#spaceHoldTimer.unref?.();
-	}
-
-	#endSpaceHold(): void {
-		if (!this.#spaceHoldActive) return;
-		this.#spaceHoldActive = false;
-		this.#resetSpaceRun();
-		if (this.#spaceHoldTimer) {
-			clearTimeout(this.#spaceHoldTimer);
-			this.#spaceHoldTimer = undefined;
-		}
-		this.onSpaceHoldEnd?.();
-	}
-
 	/** Decrement {@link #pasteInFlight} once an async paste settles and, when the count returns
 	 *  to zero, drain {@link #pendingInput} through `handleInput` so requeueing still works if a
 	 *  drained chunk triggers another async paste. Bound member so it can be passed straight to
@@ -1188,7 +1060,13 @@ export class CustomEditor extends Editor {
 		}
 
 		// Space-hold push-to-talk: a sustained space bar starts/stops STT instead of typing spaces.
-		if (this.#handleSpaceHold(data, canonical)) return;
+		switch (this.spaceHold.process(canonical === "space")) {
+			case "type":
+				this.#forwardInput(data);
+				return;
+			case "swallow":
+				return;
+		}
 
 		// One union probe decides whether any per-action interception below can
 		// match — plain typing then skips the ~20 per-action set lookups per key.