@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/render/composite.ts

@@ -0,0 +1,64 @@
+import { TERMINAL } from "../terminal-capabilities";
+import { extractSegments, sliceByColumn, sliceWithWidth, visibleWidth } from "../utils";
+
+const SEGMENT_RESET = "\x1b[0m";
+
+/** Splice overlay content into a base line at a specific column. Single-pass optimized. */
+export function compositeLineAt(
+	baseLine: string,
+	overlayLine: string,
+	startCol: number,
+	overlayWidth: number,
+	totalWidth: number,
+): string {
+	// A full-width image row owns its terminal row; the writer must see its exact placement shape.
+	if (startCol === 0 && overlayWidth >= totalWidth && TERMINAL.isImageLine(overlayLine)) return overlayLine;
+	if (TERMINAL.isImageLine(baseLine)) {
+		// Full-width overlays such as /switch are opaque: replace the
+		// Unicode placeholder cells so the image cannot cover the modal.
+		// Partial overlays cannot safely splice placement control sequences.
+		if (startCol !== 0 || overlayWidth < totalWidth) return baseLine;
+		const overlay = sliceWithWidth(overlayLine, 0, totalWidth, true);
+		return SEGMENT_RESET + overlay.text + " ".repeat(Math.max(0, totalWidth - overlay.width));
+	}
+
+	// Single pass through baseLine extracts both before and after segments
+	const afterStart = startCol + overlayWidth;
+	const base = extractSegments(baseLine, startCol, afterStart, totalWidth - afterStart, true);
+
+	// Extract overlay with width tracking (strict=true to exclude wide chars at boundary)
+	const overlay = sliceWithWidth(overlayLine, 0, overlayWidth, true);
+
+	// Pad segments to target widths
+	const beforePad = Math.max(0, startCol - base.beforeWidth);
+	const overlayPad = Math.max(0, overlayWidth - overlay.width);
+	const actualBeforeWidth = Math.max(startCol, base.beforeWidth);
+	const actualOverlayWidth = Math.max(overlayWidth, overlay.width);
+	const afterTarget = Math.max(0, totalWidth - actualBeforeWidth - actualOverlayWidth);
+	const afterPad = Math.max(0, afterTarget - base.afterWidth);
+
+	// Compose result
+	const r = SEGMENT_RESET;
+	const result =
+		base.before +
+		" ".repeat(beforePad) +
+		r +
+		overlay.text +
+		" ".repeat(overlayPad) +
+		r +
+		base.after +
+		" ".repeat(afterPad);
+
+	// CRITICAL: Always verify and truncate to terminal width.
+	// This is the final safeguard against width overflow which would crash the TUI.
+	// Width tracking can drift from actual visible width due to:
+	// - Complex ANSI/OSC sequences (hyperlinks, colors)
+	// - Wide characters at segment boundaries
+	// - Edge cases in segment extraction
+	const resultWidth = visibleWidth(result);
+	if (resultWidth <= totalWidth) {
+		return result;
+	}
+	// Truncate with strict=true to ensure we don't exceed totalWidth
+	return sliceByColumn(result, 0, totalWidth, true);
+}

package/src/render/output-pane.d.ts

@@ -92,6 +92,7 @@ export declare class OutputPane implements Component {
     describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
     invalidate(): void;
+    releaseRenderCaches(): void;
 }
 /** Default styling for plain tool output while preserving existing ANSI. */
 export declare function styleToolOutputLine(line: string, theme: Theme): string;

package/src/render/output-pane.ts

@@ -302,6 +302,12 @@ export class OutputPane implements Component {
 		this.#text.invalidate();
 	}
 
+	releaseRenderCaches(): void {
+		this.#renderKey = "";
+		this.#text.setText("");
+		this.#text.releaseRenderCaches();
+	}
+
 	#appendToTail(text: string): void {
 		if (!text) return;
 		if (this.#lines.length === 0) this.#lines.push("");

package/src/render/render-utils.d.ts

@@ -298,6 +298,7 @@ export interface RenderedStringCache {
 export declare function createRenderedStringCache(): RenderedStringCache;
 /** Drop the memo so the next lookup re-renders (e.g. the render function identity changed). */
 export declare function invalidateRenderedStringCache(cache: RenderedStringCache): void;
+export declare function releaseRenderedStringCache(cache: RenderedStringCache): void;
 /** Reuse a rendered string while its theme, expansion, content, and salt match. */
 export declare function cachedRenderedString(cache: RenderedStringCache | undefined, theme: Theme, expanded: boolean, salt: string, content: string, render: () => string): string;
 /**

package/src/render/render-utils.ts

@@ -1042,8 +1042,12 @@ export function formatToolWorkingDirectory(workdir: string | undefined, projectD
 		return undefined;
 	}
 	const relativePath = path.relative(resolvedProjectDir, resolvedWorkdir);
+	// On Windows, `path.relative` across drives returns the absolute target, which is not inside the project.
 	const isWithinProject =
-		relativePath.length > 0 && !relativePath.startsWith("..") && !relativePath.startsWith(`..${path.sep}`);
+		relativePath.length > 0 &&
+		!path.isAbsolute(relativePath) &&
+		!relativePath.startsWith("..") &&
+		!relativePath.startsWith(`..${path.sep}`);
 	const displayWorkdir = isWithinProject ? relativePath : shortenPath(resolvedWorkdir);
 	return replaceTabs(displayWorkdir);
 }
@@ -1124,6 +1128,9 @@ export function createCachedComponent(
 		invalidate() {
 			cached = undefined;
 		},
+		releaseRenderCaches() {
+			cached = undefined;
+		},
 	};
 }
 
@@ -1156,6 +1163,14 @@ export function invalidateRenderedStringCache(cache: RenderedStringCache): void
 	cache.theme = null;
 }
 
+export function releaseRenderedStringCache(cache: RenderedStringCache): void {
+	cache.theme = null;
+	cache.expanded = false;
+	cache.salt = "";
+	cache.content = "";
+	cache.value = "";
+}
+
 /** Reuse a rendered string while its theme, expansion, content, and salt match. */
 export function cachedRenderedString(
 	cache: RenderedStringCache | undefined,

package/src/render/tool-card.d.ts

@@ -46,6 +46,11 @@ export interface ToolCardOptions {
     paddingY?: number;
     ignoreTight?: boolean;
     onInvalidate?: () => void;
+    /**
+     * Drop builder-owned memos the next build recomputes. Called by
+     * {@link ToolCard.releaseRenderCaches}, which never calls `onInvalidate`.
+     */
+    onReleaseRenderCaches?: () => void;
     onDispose?: () => void;
 }
 /** Map transcript lifecycle terminology onto the output frame's visual states. */
@@ -71,6 +76,7 @@ export declare class ToolCard implements Component {
     handleInput(data: string): void;
     setIgnoreTight(ignore: boolean): void;
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
 }
 /** Construct a lazy framed tool card. */

package/src/render/tool-card.ts

@@ -69,6 +69,11 @@ export interface ToolCardOptions {
 	paddingY?: number;
 	ignoreTight?: boolean;
 	onInvalidate?: () => void;
+	/**
+	 * Drop builder-owned memos the next build recomputes. Called by
+	 * {@link ToolCard.releaseRenderCaches}, which never calls `onInvalidate`.
+	 */
+	onReleaseRenderCaches?: () => void;
 	onDispose?: () => void;
 }
 
@@ -381,6 +386,16 @@ export class ToolCard implements Component {
 		this.#options.onInvalidate?.();
 	}
 
+	releaseRenderCaches(): void {
+		this.#block.invalidate();
+		this.#lastBlockOptions = undefined;
+		this.#plainKey = "";
+		this.#plainText.setText("");
+		this.#plainText.releaseRenderCaches();
+		for (const child of this.#renderedChildren) child.releaseRenderCaches?.();
+		this.#options.onReleaseRenderCaches?.();
+	}
+
 	dispose(): void {
 		if (this.#disposed) return;
 		this.#disposed = true;

package/src/render/width-aware-text.d.ts

@@ -20,6 +20,8 @@ export declare class WidthAwareText implements Component {
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
+    /** The formatted text stays: the inner `Text` renders from it, so dropping it would free nothing. */
+    releaseRenderCaches(): void;
     /**
      * Re-run the formatter on the next render because its inputs changed.
      * Unlike {@link invalidate}, the inner `Text` keeps its wrap cache, so a

package/src/render/width-aware-text.ts

@@ -51,6 +51,11 @@ export class WidthAwareText implements Component {
 		this.#inner.invalidate();
 	}
 
+	/** The formatted text stays: the inner `Text` renders from it, so dropping it would free nothing. */
+	releaseRenderCaches(): void {
+		this.#inner.releaseRenderCaches();
+	}
+
 	/**
 	 * Re-run the formatter on the next render because its inputs changed.
 	 * Unlike {@link invalidate}, the inner `Text` keeps its wrap cache, so a

package/src/setup/scenes/model.ts

@@ -1,4 +1,5 @@
 import type { Model } from "@linxiraos/pi-ai";
+import { modelKind } from "@linxiraos/pi-catalog/types";
 import type { SgrMouseEvent } from "../../mouse";
 import { Text } from "../../components/text";
 import { WizardStep } from "../../components/wizard-step";
@@ -114,7 +115,7 @@ class ModelSceneController implements SetupSceneController {
 		const { available, all, current } = this.#host.ctx.getModels();
 		const source = this.#host.ctx.modelSource;
 		const roles = resolveRoleAssignments(source, all, available);
-		const items = buildBrowserItems(available);
+		const items = buildBrowserItems(available.filter(model => modelKind(model) === "chat"));
 		sortModelItems(items, { roles, mruOrder: source.mruOrder });
 		this.#browser.setRoles(roles);
 		this.#browser.setMruOrder(source.mruOrder);

package/src/setup/scenes/types.ts

@@ -29,6 +29,7 @@ export interface SetupHost extends SetupUiHost {
 	readonly disabledProviders: readonly string[];
 	readonly authStorage: AuthStorage;
 	readonly modelSource: ModelBrowserSource;
+	/** Available and catalog models of every kind; role chips resolve over all of them, rows list chat models. */
 	getModels(): { available: Model[]; all: Model[]; current: Model | undefined };
 	refreshModels(): Promise<void>;
 	selectModel(model: Model, selector: string): Promise<void>;

package/src/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";
+/** 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/src/space-hold.ts

@@ -1,22 +1,40 @@
-/** 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 { addKeyAliases, canonicalKeyId } from "./keybindings";
+import { extractPrintableText, type KeyId, parseKey } from "./keys";
+
+/** 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 function getSpaceHoldText(data: string, canonical: string | undefined): string | undefined {
+	if (canonical === undefined) return undefined;
+	const shifted = canonical.startsWith("shift+");
+	const base = shifted ? canonical.slice("shift+".length) : canonical;
+	if (base !== "space" && base.length !== 1) return undefined;
+	if (base === "space" && canonical !== "space" && !shifted) return undefined;
+	const text = extractPrintableText(data);
+	return text && (base !== "space" || text === " ") ? text : 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 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 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
+/** 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 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 const SPACE_HOLD_RELEASE_MS = 250;
+/** 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 const SPACE_HOLD_STALL_SLACK_MS = 100;
 
-/** Whether two consecutive inter-space gaps look machine-driven: both within the auto-repeat band
+/** Whether two consecutive inter-key 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. */
@@ -26,46 +44,62 @@ function gapsAreMechanical(gap: number, prevGap: number): boolean {
 	return Math.abs(gap - prevGap) <= tolerance;
 }
 
-/** What a recognized space-bar hold drives — the push-to-talk start and stop. */
+/** 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 class SpaceHoldGesture {
-	/** Unset (the default) keeps the space bar typing spaces. */
+	/** Canonical aliases of {@link keys}, rebuilt only when the bindings change (not per keystroke). */
+	#keyAliases = new Set<string>(["space"]);
+	#keys: readonly KeyId[] = ["space"];
+	/** Configured alternative keys. Alternatives are tracked independently and never combine into one run. */
+	get keys(): readonly KeyId[] {
+		return this.#keys;
+	}
+	set keys(keys: readonly KeyId[]) {
+		this.#keys = keys;
+		const aliases = new Set<string>();
+		for (const key of keys) addKeyAliases(aliases, key);
+		this.#keyAliases = aliases;
+	}
+	/** Unset (the default) keeps configured keys behaving normally. */
 	handler: SpaceHoldHandler | undefined;
 	/** Deletes the given number of characters before the host input's cursor. */
 	readonly #deleteTyped: (count: number) => void;
-	/** Host input state that rules the gesture out, e.g. an editor mode where space is not text. */
+	/** Host input state that rules the gesture out, e.g. an editor mode where keys are not text. */
 	readonly #allowed: () => boolean;
-	/** Spaces the host typed in the current run; tracked back out when a hold is recognized. */
+	/** Safely inserted text units in the current mechanical run; removed if a hold is recognized. */
 	#typed = 0;
-	/** Consecutive "mechanical" deltas (fast + steady); a sustained run of these confirms a held bar. */
+	/** Length of the most recent candidate event actually typed into the host. */
+	#lastTypedLength = 0;
+	/** Canonical key in the current run, preventing alternate bindings from combining. */
+	#runKey: string | undefined;
+	/** Consecutive mechanical (fast + steady) deltas; a sustained run confirms a held key. */
 	#mechanicalRun = 0;
-	/** Inter-space gap (ms) of the previous space pair, compared against the next to judge steadiness. */
+	/** Inter-key gap (ms) of the previous pair, compared against the next to judge steadiness. */
 	#prevGap: 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. */
+	/** Monotonic timestamp (ms) of the last configured keypress. */
+	#lastKeyAt = Number.NEGATIVE_INFINITY;
+	/** Canonical key while a recognized push-to-talk recording is in progress. */
+	#activeKey: string | undefined;
+	/** True while a recognized key-hold push-to-talk recording is in progress. */
 	#active = false;
-	/** Idle timer that ends the hold once repeated spaces stop arriving. */
+	/** Idle timer that ends the hold once repeated keypresses stop arriving. */
 	#releaseTimer: NodeJS.Timeout | undefined;
 
 	constructor(deleteTyped: (count: number) => void, allowed: () => boolean = () => true) {
@@ -73,58 +107,127 @@ export class SpaceHoldGesture {
 		this.#allowed = allowed;
 	}
 
-	/** 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 {
+		if (!(this.handler?.enabled() && this.#allowed())) return false;
+		const parsedKey = parseKey(data);
+		if (parsedKey === undefined) return false;
+		const key = canonicalKeyId(parsedKey);
+		return this.#keyAliases.has(key) && getSpaceHoldText(data, key) === undefined;
+	}
+
+	/** 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 = 0): SpaceHoldStep {
+		const handler = this.handler;
+		if (!(handler?.enabled() && this.#allowed())) {
+			if (this.#active) this.#end();
+			else this.#resetRun();
+			return "pass";
+		}
+
+		const candidateKey = key !== undefined && this.#keyAliases.has(key) ? key : undefined;
+
 		if (this.#active) {
-			if (isSpace) {
-				// Auto-repeat while held: swallow it and keep the release timer alive.
+			if (candidateKey === this.#activeKey) {
+				// Auto-repeat while the same configured key is held: keep the release timer alive.
 				this.#armReleaseTimer();
 				return "swallow";
 			}
-			// Any non-space means the bar was released — stop recording, then let the key through.
+			// Any other key means the active key was released. End this recording, then treat a
+			// different configured alternative as a fresh gesture rather than merging the keys.
 			this.#end();
-			return "pass";
 		}
-		if (!isSpace) {
+
+		if (candidateKey === undefined) {
 			this.#resetRun();
 			return "pass";
 		}
-		if (!(this.handler?.enabled() && this.#allowed())) return "pass";
+
+		if (this.#runKey !== undefined && candidateKey !== this.#runKey) this.#resetRun();
 		const now = performance.now();
-		const gap = now - this.#lastSpaceAt;
+		const hasPreviousKey = this.#lastKeyAt !== Number.NEGATIVE_INFINITY;
+		const gap = now - this.#lastKeyAt;
 		const prevGap = this.#prevGap;
-		this.#lastSpaceAt = now;
+		this.#lastKeyAt = now;
+		this.#runKey = candidateKey;
+		const printable = insertedCharacterLength > 0;
+
+		if (!hasPreviousKey) {
+			this.#mechanicalRun = 0;
+			this.#typed = 0;
+			this.#lastTypedLength = 0;
+			return printable ? "type" : "swallow";
+		}
+
 		this.#prevGap = 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.
+		if (prevGap === undefined) {
+			// The second event establishes the first interval. A fast gap keeps earlier literal
+			// typing eligible for rollback; a slow gap makes that first tap final.
+			this.#mechanicalRun = 0;
+			if (gap > SPACE_REPEAT_MAX_GAP_MS) {
+				this.#typed = 0;
+				this.#lastTypedLength = 0;
+			}
+			return printable ? "type" : "swallow";
+		}
+
+		if (!gapsAreMechanical(gap, prevGap)) {
+			// A fast interval after a slow gap may roll back the previous event and this one.
+			// Slow current gaps and jitter breaks keep prior text final.
 			this.#mechanicalRun = 0;
-			this.#typed++;
-			return "type";
+			if (gap <= SPACE_REPEAT_MAX_GAP_MS && prevGap > SPACE_REPEAT_MAX_GAP_MS) {
+				this.#typed = this.#lastTypedLength;
+			} else {
+				this.#typed = 0;
+				this.#lastTypedLength = 0;
+			}
+			return printable ? "type" : "swallow";
 		}
-		// 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.
+
+		// Steady fast repeat: swallow it. Once the cadence confirms a held key, remove only the
+		// literal candidate text from the current uninterrupted run and start recording.
 		if (++this.#mechanicalRun >= SPACE_HOLD_MECHANICAL_RUN) {
 			this.#deleteTyped(this.#typed);
 			this.#resetRun();
 			this.#active = true;
+			this.#activeKey = candidateKey;
 			this.#armReleaseTimer();
-			this.handler?.onStart();
+			handler.onStart();
 		}
 		return "swallow";
 	}
 
+	/** Account for text the host actually inserted for the preceding `"type"` step. */
+	recordTyped(insertedCharacterLength: number): void {
+		const insertedLength = Math.max(0, insertedCharacterLength);
+		this.#typed += insertedLength;
+		this.#lastTypedLength = insertedLength;
+	}
+
 	#resetRun(): void {
+		this.#lastTypedLength = 0;
 		this.#typed = 0;
+		this.#runKey = undefined;
 		this.#mechanicalRun = 0;
 		this.#prevGap = undefined;
-		this.#lastSpaceAt = Number.NEGATIVE_INFINITY;
+		this.#lastKeyAt = Number.NEGATIVE_INFINITY;
 	}
 
 	#armReleaseTimer(): void {
-		if (this.#releaseTimer) clearTimeout(this.#releaseTimer);
+		clearTimeout(this.#releaseTimer);
+		const armedAt = performance.now();
 		this.#releaseTimer = setTimeout(() => {
 			this.#releaseTimer = undefined;
+			// Late firing means input went unobserved; wait one more window so queued repeats can
+			// re-arm the timer before deciding the key was released.
+			if (performance.now() - armedAt > SPACE_HOLD_RELEASE_MS + SPACE_HOLD_STALL_SLACK_MS) {
+				this.#armReleaseTimer();
+				return;
+			}
 			this.#end();
 		}, SPACE_HOLD_RELEASE_MS);
 		this.#releaseTimer.unref?.();
@@ -133,6 +236,7 @@ export class SpaceHoldGesture {
 	#end(): void {
 		if (!this.#active) return;
 		this.#active = false;
+		this.#activeKey = undefined;
 		this.#resetRun();
 		if (this.#releaseTimer) {
 			clearTimeout(this.#releaseTimer);