@gajae-code/coding-agent 0.9.6 → 0.10.0

package/src/modes/acp/acp-mode.ts

@@ -5,19 +5,46 @@ import { AcpAgent } from "./acp-agent";
 
 export type AcpSessionFactory = (cwd: string) => Promise<AgentSession>;
 
+export interface AcpConnectionHandle {
+	connection: AgentSideConnection;
+	agent: AcpAgent;
+}
+
 export function createAcpConnection(
 	transport: Stream,
 	createSession: AcpSessionFactory,
 	initialSession?: AgentSession,
 ): AgentSideConnection {
-	return new AgentSideConnection(conn => new AcpAgent(conn, createSession, initialSession), transport);
+	return createAcpConnectionWithAgent(transport, createSession, initialSession).connection;
+}
+
+/**
+ * Create an ACP connection and return both the {@link AgentSideConnection} and the
+ * underlying {@link AcpAgent}. Callers that need to await agent shutdown (terminal
+ * delete/dispose work) after transport closure should use this instead of
+ * {@link createAcpConnection}.
+ */
+export function createAcpConnectionWithAgent(
+	transport: Stream,
+	createSession: AcpSessionFactory,
+	initialSession?: AgentSession,
+): AcpConnectionHandle {
+	let agent: AcpAgent | undefined;
+	const connection = new AgentSideConnection(conn => {
+		agent = new AcpAgent(conn, createSession, initialSession);
+		return agent;
+	}, transport);
+	return { connection, agent: agent! };
 }
 
 export async function runAcpMode(createSession: AcpSessionFactory, initialSession?: AgentSession): Promise<never> {
 	const input = stream.Writable.toWeb(process.stdout);
 	const output = stream.Readable.toWeb(process.stdin);
 	const transport = ndJsonStream(input, output);
-	const connection = createAcpConnection(transport, createSession, initialSession);
+	const { connection, agent } = createAcpConnectionWithAgent(transport, createSession, initialSession);
 	await connection.closed;
+	// Await connection-local terminal work (active deletes, disposal) so
+	// `process.exit` never kills in-flight deletion/cleanup.
+	await agent.shutdownPromise;
 	process.exit(0);
 }

package/src/modes/components/assistant-message.ts

@@ -1,5 +1,16 @@
 import type { AssistantMessage, ImageContent, Usage } from "@gajae-code/ai";
-import { type Component, Container, Image, ImageProtocol, Markdown, Spacer, TERMINAL, Text } from "@gajae-code/tui";
+import {
+	type Component,
+	Container,
+	Image,
+	ImageProtocol,
+	isViewportAnchorSourceRenderer,
+	Markdown,
+	Spacer,
+	TERMINAL,
+	Text,
+	type ViewportAnchorSource,
+} from "@gajae-code/tui";
 import { formatNumber } from "@gajae-code/utils";
 import { settings } from "../../config/settings";
 import { renderDeepInterviewAssistantText } from "../../deep-interview/render-middleware";
@@ -62,6 +73,7 @@ interface AssistantMessageUpdateOptions {
 type AssistantChildDescriptor = {
 	key: string;
 	component: Component;
+	anchorSource?: ViewportAnchorSource;
 };
 
 /**
@@ -81,15 +93,16 @@ export class AssistantMessageComponent extends Container {
 	#contentBlockKeys = new WeakMap<object, string>();
 	#nextContentBlockKey = 0;
 	#reusableChildren = new WeakSet<Component>();
-
+	#viewportAnchorId?: string;
 	constructor(
 		message?: AssistantMessage,
 		private hideThinkingBlock = false,
 		private readonly onImageUpdate?: () => void,
+		viewportAnchorId?: string,
 	) {
 		super();
+		this.#viewportAnchorId = viewportAnchorId;
 
-		// Container for text/thinking content
 		this.#contentContainer = new Container();
 		this.addChild(this.#contentContainer);
 
@@ -98,6 +111,13 @@ export class AssistantMessageComponent extends Container {
 		}
 	}
 
+	#contentAnchorSource(
+		index: number,
+		kind: "text" | "thinking" | "thinking-hidden",
+	): ViewportAnchorSource | undefined {
+		return this.#viewportAnchorId ? { id: `${this.#viewportAnchorId}:content:${index}:${kind}` } : undefined;
+	}
+
 	override invalidate(): void {
 		super.invalidate();
 		if (this.#lastMessage) {
@@ -288,6 +308,12 @@ export class AssistantMessageComponent extends Container {
 	}
 
 	#reconcileChildren(descriptors: AssistantChildDescriptor[]): void {
+		for (const child of this.#contentContainer.children) this.#contentContainer.setViewportAnchorSource(child, null);
+		for (const descriptor of descriptors) {
+			if (descriptor.anchorSource && isViewportAnchorSourceRenderer(descriptor.component)) {
+				this.#contentContainer.setViewportAnchorSource(descriptor.component, descriptor.anchorSource);
+			}
+		}
 		const nextChildren = descriptors.map(descriptor => descriptor.component);
 		if (
 			nextChildren.length === this.#contentContainer.children.length &&
@@ -346,6 +372,7 @@ export class AssistantMessageComponent extends Container {
 				descriptors.push({
 					key: `${blockKey}:text`,
 					component: this.#renderTextBlock(content, streaming && i === activeContentIndex),
+					anchorSource: this.#contentAnchorSource(i, "text"),
 				});
 			} else if (content.type === "thinking" && content.thinking.trim()) {
 				// Add spacing only when another visible assistant content block follows.
@@ -358,11 +385,13 @@ export class AssistantMessageComponent extends Container {
 							`${blockKey}:thinking-hidden`,
 							() => new Text(theme.italic(theme.fg("thinkingText", "Thinking...")), 1, 0),
 						),
+						anchorSource: this.#contentAnchorSource(i, "thinking-hidden"),
 					});
 				} else {
 					descriptors.push({
 						key: `${blockKey}:thinking`,
 						component: this.#renderThinkingBlock(content, streaming && i === activeContentIndex),
+						anchorSource: this.#contentAnchorSource(i, "thinking"),
 					});
 				}
 				if (visibleContentAfter[i]) {

package/src/modes/components/bash-execution.ts

@@ -6,6 +6,7 @@ import {
 	Container,
 	Ellipsis,
 	ImageProtocol,
+	isTerminalGraphicsFallbackActive,
 	type Loader,
 	TERMINAL,
 	Text,
@@ -16,7 +17,12 @@ import {
 import { sanitizeText } from "@gajae-code/utils";
 import { theme } from "../../modes/theme/theme";
 import type { TruncationMeta } from "../../tools/output-meta";
-import { getSixelLineMask, isSixelPassthroughEnabled, sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
+import {
+	containsSixelSequence,
+	getSixelLineMask,
+	isSixelPassthroughEnabled,
+	sanitizeWithOptionalSixelPassthrough,
+} from "../../utils/sixel";
 import {
 	buildExecutionFrame,
 	buildStatusFooter,
@@ -41,6 +47,7 @@ export class BashExecutionComponent extends Container {
 	#truncation?: TruncationMeta;
 	#expanded = false;
 	#displayDirty = false;
+	#displayBuiltWithGraphicsFallback: boolean | undefined;
 	#chunkGate = false;
 	#contentContainer: Container;
 	#headerText: Text;
@@ -135,7 +142,8 @@ export class BashExecutionComponent extends Container {
 	}
 
 	override render(width: number): string[] {
-		if (this.#displayDirty) {
+		const fallbackActive = isTerminalGraphicsFallbackActive();
+		if (this.#displayDirty || this.#displayBuiltWithGraphicsFallback !== fallbackActive) {
 			this.#displayDirty = false;
 			this.#updateDisplay();
 		}
@@ -143,16 +151,16 @@ export class BashExecutionComponent extends Container {
 	}
 
 	#updateDisplay(): void {
+		const fallbackActive = isTerminalGraphicsFallbackActive();
 		const availableLines = this.#outputLines;
-
-		// Apply preview truncation based on expanded state
-		const previewLogicalLines = availableLines.slice(-PREVIEW_LINES);
-		const hiddenLineCount = availableLines.length - previewLogicalLines.length;
 		const sixelLineMask =
-			TERMINAL.imageProtocol === ImageProtocol.Sixel && isSixelPassthroughEnabled()
+			fallbackActive || (TERMINAL.imageProtocol === ImageProtocol.Sixel && isSixelPassthroughEnabled())
 				? getSixelLineMask(availableLines)
 				: undefined;
 		const hasSixelOutput = sixelLineMask?.some(Boolean) ?? false;
+		const selectedLines =
+			this.#expanded || (hasSixelOutput && !fallbackActive) ? availableLines : availableLines.slice(-PREVIEW_LINES);
+		const hiddenLineCount = availableLines.length - selectedLines.length;
 
 		// Rebuild content container
 		// Detach (not dispose): #headerText and the running #loader are persistent,
@@ -165,15 +173,36 @@ export class BashExecutionComponent extends Container {
 		this.#contentContainer.addChild(this.#headerText);
 
 		// Output
-		if (availableLines.length > 0) {
-			if (this.#expanded || hasSixelOutput) {
-				const displayText = availableLines
-					.map((line, index) => (sixelLineMask?.[index] ? line : theme.fg("muted", line)))
+		if (selectedLines.length > 0) {
+			if (fallbackActive && hasSixelOutput) {
+				const displayLines: string[] = [];
+				const selectedStart = availableLines.length - selectedLines.length;
+				for (const [selectedIndex, line] of selectedLines.entries()) {
+					const index = selectedStart + selectedIndex;
+					if (sixelLineMask?.[index]) {
+						// Emit one placeholder per visible SIXEL block: at a true sequence
+						// start, at the top of a collapsed slice that begins mid-sequence,
+						// or when the line itself opens a new sequence.
+						const isBlockStart = selectedIndex === 0 || !sixelLineMask[index - 1] || containsSixelSequence(line);
+						if (isBlockStart) {
+							displayLines.push(theme.fg("muted", "[SIXEL image hidden while IRC sidebar is visible]"));
+						}
+					} else {
+						displayLines.push(theme.fg("muted", line));
+					}
+				}
+				this.#contentContainer.addChild(new Text(`\n${displayLines.join("\n")}`, 1, 0));
+			} else if (this.#expanded || hasSixelOutput) {
+				const displayText = selectedLines
+					.map((line, selectedIndex) => {
+						const index = availableLines.length - selectedLines.length + selectedIndex;
+						return sixelLineMask?.[index] ? line : theme.fg("muted", line);
+					})
 					.join("\n");
 				this.#contentContainer.addChild(new Text(`\n${displayText}`, 1, 0));
 			} else {
 				// Use shared visual truncation utility, recomputed per render width
-				const styledOutput = previewLogicalLines.map(line => theme.fg("muted", line)).join("\n");
+				const styledOutput = selectedLines.map(line => theme.fg("muted", line)).join("\n");
 				this.#contentContainer.addChild(createCollapsedPreview(`\n${styledOutput}`, PREVIEW_LINES));
 			}
 		}
@@ -187,10 +216,11 @@ export class BashExecutionComponent extends Container {
 				exitCode: this.#exitCode,
 				truncation: this.#truncation,
 				hiddenLineCount,
-				suppressHiddenCount: hasSixelOutput,
+				suppressHiddenCount: hasSixelOutput && !fallbackActive,
 			});
 			if (footer) this.#contentContainer.addChild(footer);
 		}
+		this.#displayBuiltWithGraphicsFallback = fallbackActive;
 	}
 
 	#clampDisplayLine(line: string): string {

package/src/modes/components/custom-editor.ts

@@ -123,6 +123,11 @@ export class CustomEditor extends Editor {
 		this.#actionKeys.set(action, [...keys]);
 	}
 
+	/** Returns whether a built-in editor action consumes this configured key before custom handlers. */
+	hasActionKey(key: KeyId): boolean {
+		return [...this.#actionKeys.values()].some(keys => keys.includes(key));
+	}
+
 	#matchesAction(data: string, action: ConfigurableEditorAction): boolean {
 		const keys = this.#actionKeys.get(action);
 		if (!keys) return false;

package/src/modes/components/gajae-pet-widget.ts

@@ -0,0 +1,360 @@
+import {
+	type AnimationRegistration,
+	buildGajaePixelFrames,
+	type Component,
+	type Container,
+	type GajaePixelFrameName,
+	type GajaePixelFrames,
+	getCellDimensions,
+	ImageProtocol,
+	PARA_PARA_STEPS,
+	PET_SKINS,
+	type PetMode,
+	type PetSkinId,
+	petBurstDurationMs,
+	petBurstFrame,
+	registerAnimationCallback,
+	TERMINAL,
+	type TUI,
+} from "@gajae-code/tui";
+import type { CustomEditor } from "./custom-editor";
+
+/** Re-exported from the tui skin registry so widget-relative imports stay valid. */
+export type { PetMode, PetSkinId };
+
+/**
+ * Empty columns on each side of the pet: an explicit inset from the right edge,
+ * with the composer's own right gutter (setRightGutterWidth(1)) as the left gap.
+ */
+const PET_SIDE_MARGIN = 1;
+/** Sub-cell drop after the one-row safety lift, preserving a small bottom gap. */
+const PET_SIXEL_DROP_PX = 9;
+/**
+ * Kitty sub-cell drop below the one-row safety lift, as a fraction of the live cell
+ * height so it scales with the font. `floor` keeps it inside the cell; the value is
+ * clamped to the cell height.
+ */
+const KITTY_DROP_FRACTION = 0.45;
+const petKittyDropPx = (cellHeightPx: number): number =>
+	Math.min(Math.max(0, cellHeightPx - 1), Math.floor(cellHeightPx * KITTY_DROP_FRACTION));
+const PET_RAISE_ROWS = 1;
+/** Working animation: the shared para-para beats looped end to end. */
+const WORK_LOOP_TOTAL = PARA_PARA_STEPS.reduce((sum, [, ms]) => sum + ms, 0);
+/** Random gap between automatic claw flexes (fires while idle AND working). */
+const AUTO_FLEX_MIN_GAP_MS = 12_000;
+const AUTO_FLEX_MAX_GAP_MS = 40_000;
+// Deterministic idle loop: gaze around with a rare visor flicker.
+const IDLE_LOOP: Array<[GajaePixelFrameName, number]> = [
+	["base", 1100],
+	["gazeL", 350],
+	["base", 500],
+	["gazeR", 350],
+	["base", 800],
+	["flicker", 150],
+];
+const IDLE_LOOP_TOTAL = IDLE_LOOP.reduce((sum, [, ms]) => sum + ms, 0);
+
+/**
+ * Selector preview: fire the first burst this soon after a skin is previewed, so the
+ * pet shows one idle eye-roll (base -> gazeL -> base -> gazeR) and then its signature
+ * flex/cry. Live use keeps the random AUTO_FLEX gap; only preview forces this demo.
+ */
+const PREVIEW_INTRO_MS = 2300;
+
+/**
+ * Wraps the composer editor, reserving a right-side area beside it where the
+ * real-pixel pet is drawn. The editor just renders narrower; the pet pixels
+ * are emitted separately as an absolute-positioned overlay.
+ */
+export class PetFramedEditor implements Component {
+	#editor: CustomEditor;
+	#reserve = 0;
+
+	constructor(editor: CustomEditor) {
+		this.#editor = editor;
+	}
+
+	setReserve(columns: number): void {
+		this.#reserve = columns;
+	}
+
+	canFit(width: number): boolean {
+		return this.#reserve > 0 && width > this.#reserve + 8;
+	}
+
+	invalidate(): void {
+		this.#editor.invalidate?.();
+	}
+
+	render(width: number): string[] {
+		if (!this.canFit(width)) {
+			return this.#editor.render(width);
+		}
+		return this.#editor.render(width - this.#reserve);
+	}
+}
+
+/**
+ * The gajae pet: a 16x16 real-pixel sprite living in a reserved area beside
+ * the composer. It is nearest-neighbor scaled to the two terminal rows occupied
+ * by an empty one-line composer and lifted one row so its feet meet the input
+ * box's bottom edge.
+ *
+ * Rendering has two paths that share one payload builder:
+ * - a post-render emitter re-draws the sprite after every TUI write (line
+ *   renders clear the pet cells, so the overlay must be re-applied), and
+ * - frame advances write the payload directly to the terminal, because the
+ *   TUI skips writes entirely when no component line changed.
+ *
+ * Requires a sixel- or kitty-graphics terminal (`pixelProtocol()`).
+ */
+export class GajaePetWidget {
+	#ui: TUI;
+	#editor: CustomEditor;
+	#editorContainer: Container;
+	#floorContainer: Container;
+	#framedEditor: PetFramedEditor;
+	#isWorking: () => boolean;
+	#getComposerBottomOffset: () => number;
+	#mode: PetMode = "off";
+	#pixel: GajaePixelFrames | undefined;
+	#frame: GajaePixelFrameName = "base";
+	#animation: AnimationRegistration | undefined;
+	#flexUntil = 0;
+	#nextAutoFlexAt = 0;
+	#autoFlexGapMs: [number, number] | null;
+	#forcedProtocol: "sixel" | "kitty" | undefined;
+	/** Cell metrics the current frames were built for; a change triggers a rebuild. */
+	#builtCellW = 0;
+	#builtCellH = 0;
+
+	constructor(options: {
+		ui: TUI;
+		editor: CustomEditor;
+		editorContainer: Container;
+		floorContainer: Container;
+		isWorking: () => boolean;
+		/** Rows rendered below the composer box (pet floor + hook widgets). */
+		getComposerBottomOffset: () => number;
+		forcePixelProtocol?: "sixel" | "kitty";
+		/** Random [min, max] ms between auto-flexes; null disables. */
+		autoFlexGapMs?: [number, number] | null;
+	}) {
+		this.#ui = options.ui;
+		this.#editor = options.editor;
+		this.#editorContainer = options.editorContainer;
+		this.#floorContainer = options.floorContainer;
+		this.#framedEditor = new PetFramedEditor(options.editor);
+		this.#isWorking = options.isWorking;
+		this.#getComposerBottomOffset = options.getComposerBottomOffset;
+		this.#forcedProtocol = options.forcePixelProtocol;
+		this.#autoFlexGapMs =
+			options.autoFlexGapMs === undefined ? [AUTO_FLEX_MIN_GAP_MS, AUTO_FLEX_MAX_GAP_MS] : options.autoFlexGapMs;
+	}
+
+	/** Protocol available for the real-pixel pet, if any. */
+	static pixelProtocol(): "sixel" | "kitty" | null {
+		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) return "kitty";
+		if (TERMINAL.imageProtocol === ImageProtocol.Sixel) return "sixel";
+		return null;
+	}
+
+	get mode(): PetMode {
+		return this.#mode;
+	}
+
+	get isFlexing(): boolean {
+		return performance.now() < this.#flexUntil;
+	}
+
+	setMode(mode: PetMode): void {
+		this.#applyMode(mode, true);
+	}
+
+	/** Live preview during a selector: change the sprite without re-mounting the
+	 *  composer editor (that would tear down the open overlay). After a short idle
+	 *  eye-roll it fires the signature burst once (RedGajae flex, BlueGajae para-para
+	 *  then sob) so the selector demos the animation instead of waiting the random gap. */
+	previewMode(mode: PetMode): void {
+		this.#applyMode(mode, false);
+		if (mode !== "off" && this.#autoFlexGapMs) {
+			this.#nextAutoFlexAt = performance.now() + PREVIEW_INTRO_MS;
+		}
+	}
+
+	#applyMode(mode: PetMode, mountComposer: boolean): void {
+		if (mode === this.#mode) return;
+
+		if (mode === "off") {
+			this.#mode = "off";
+			this.#animation?.unregister();
+			this.#animation = undefined;
+			this.#ui.setPostRenderEmitter(undefined);
+			this.#floorContainer.clear();
+			this.#pixel = undefined;
+			this.#framedEditor.setReserve(0);
+			if (mountComposer) this.#mountEditor(false);
+			this.#ui.requestRender(true);
+			return;
+		}
+
+		const protocol = this.#forcedProtocol ?? GajaePetWidget.pixelProtocol();
+		if (!protocol) return;
+		this.#mode = mode;
+		this.#frame = "base";
+		this.#flexUntil = 0;
+		this.#nextAutoFlexAt = 0;
+		this.#buildPixel(protocol);
+		if (mountComposer) this.#mountEditor(true);
+		// The pet overlays the composer's bottom rows; no floor row is reserved, so
+		// the composer stays pinned to the terminal bottom.
+		this.#floorContainer.clear();
+		this.#ui.setPostRenderEmitter(() => this.#overlayPayload());
+		this.#animation ??= registerAnimationCallback(now => this.#tick(now), 80);
+		this.#ui.requestRender(true);
+	}
+
+	/** (Re)build the encoded frames for the current terminal cell metrics. */
+	#buildPixel(protocol: "sixel" | "kitty"): void {
+		const cell = getCellDimensions();
+		this.#builtCellW = cell.widthPx;
+		this.#builtCellH = cell.heightPx;
+		const skin: PetSkinId = this.#mode === "off" ? "red" : this.#mode;
+		this.#pixel = buildGajaePixelFrames({
+			protocol,
+			skin,
+			cellWidthPx: cell.widthPx,
+			cellHeightPx: cell.heightPx,
+			targetRows: 2,
+			sixelTopPaddingPx: protocol === "sixel" ? PET_SIXEL_DROP_PX : 0,
+			kittyCellYOffsetPx: protocol === "kitty" ? petKittyDropPx(cell.heightPx) : 0,
+		});
+		this.#framedEditor.setReserve(this.#pixel.columns + PET_SIDE_MARGIN);
+	}
+
+	dispose(): void {
+		this.#animation?.unregister();
+		this.#animation = undefined;
+		this.#ui.setPostRenderEmitter(undefined);
+		this.#floorContainer.clear();
+		this.#framedEditor.setReserve(0);
+		this.#mountEditor(false);
+	}
+
+	#mountEditor(framed: boolean): void {
+		this.#editorContainer.clear();
+		this.#editorContainer.addChild(framed ? this.#framedEditor : this.#editor);
+	}
+
+	/** Re-mount the composer editor (framed when a skin is active) after an overlay. */
+	remountComposer(): void {
+		this.#mountEditor(this.#mode !== "off");
+	}
+
+	#pickFrame(now: number): GajaePixelFrameName {
+		const mode = this.#mode;
+		if (mode === "off") return "base";
+		// Random idle burst → the skin's own animation, driven by its burst descriptor
+		// (RedGajae holds a flex; BlueGajae dances the para-para then sobs).
+		if (now < this.#flexUntil) {
+			const burst = PET_SKINS[mode].burst;
+			const elapsed = now - (this.#flexUntil - petBurstDurationMs(burst));
+			return petBurstFrame(burst, elapsed, now);
+		}
+		// Working → loop the shared para-para beats.
+		if (this.#isWorking()) {
+			let d = now % WORK_LOOP_TOTAL;
+			for (const [frame, ms] of PARA_PARA_STEPS) {
+				if (d < ms) return frame;
+				d -= ms;
+			}
+			return "base";
+		}
+		let t = now % IDLE_LOOP_TOTAL;
+		for (const [frame, ms] of IDLE_LOOP) {
+			if (t < ms) return frame;
+			t -= ms;
+		}
+		return "base";
+	}
+
+	#scheduleAutoFlex(now: number): void {
+		if (!this.#autoFlexGapMs) return;
+		const [min, max] = this.#autoFlexGapMs;
+		this.#nextAutoFlexAt = now + min + Math.random() * Math.max(0, max - min);
+	}
+
+	#tick(now: number): void {
+		if (this.#mode === "off" || !this.#pixel) return;
+		// A font/zoom change resizes the terminal cells; rebuild the frames so the
+		// kitty image and its sub-cell drop match the new cell metrics.
+		const cell = getCellDimensions();
+		if (cell.widthPx !== this.#builtCellW || cell.heightPx !== this.#builtCellH) {
+			const protocol = this.#forcedProtocol ?? GajaePetWidget.pixelProtocol();
+			if (protocol) {
+				this.#buildPixel(protocol);
+				this.#mountEditor(true);
+				this.#ui.requestRender(true);
+			}
+		}
+		// Random show-off, both while idle and while working. Each skin's burst runs for
+		// its own length (RedGajae a brief flex; BlueGajae a para-para cycle plus sob).
+		if (this.#autoFlexGapMs && now >= this.#flexUntil) {
+			if (this.#nextAutoFlexAt === 0) {
+				this.#scheduleAutoFlex(now);
+			} else if (now >= this.#nextAutoFlexAt) {
+				const burstMs = petBurstDurationMs(PET_SKINS[this.#mode].burst);
+				this.#flexUntil = now + burstMs;
+				this.#scheduleAutoFlex(now + burstMs);
+			}
+		}
+		const frame = this.#pickFrame(now);
+		if (frame === this.#frame) return;
+		this.#frame = frame;
+		// Write directly: a frame swap changes no component line, so the TUI
+		// would skip the render write (and with it the post-render emitter).
+		const payload = this.#overlayPayload(true) ?? "";
+		if (payload && this.#ui.terminalAvailable) {
+			this.#ui.terminal.write(`\x1b[?2026h\x1b7${payload}\x1b8\x1b[?2026l`);
+		}
+	}
+
+	#petPosition(): { x: number; y: number } | null {
+		const pixel = this.#pixel;
+		if (!pixel) return null;
+		const columns = this.#ui.terminal.columns;
+		if (!this.#framedEditor.canFit(columns)) return null;
+		const rows = this.#ui.terminal.rows;
+		// The sprite is lifted one safety row above the scrolling edge, then dropped
+		// back onto the composer's bottom border per protocol (sixel via transparent
+		// top padding, kitty via a sub-cell Y offset baked into the frames).
+		const composerBottom = rows - this.#getComposerBottomOffset();
+		const y = composerBottom - pixel.rows - PET_RAISE_ROWS;
+		const x = columns - pixel.columns - PET_SIDE_MARGIN;
+		if (y < 0 || x < 0) return null;
+		return { x, y };
+	}
+
+	#clearPetPayload(x: number, y: number): string {
+		const pixel = this.#pixel;
+		if (pixel?.protocol !== "sixel") return "";
+		let out = "\x1b[0m";
+		for (let row = 0; row < pixel.rasterRows; row++) {
+			out += `\x1b[${y + row + 1};${x + 1}H\x1b[${pixel.columns}X`;
+		}
+		return out;
+	}
+
+	/** Draw escape payload at the pet's absolute position. */
+	#overlayPayload(clearPet = false): string | null {
+		const pixel = this.#pixel;
+		if (!pixel) return null;
+		const pos = this.#petPosition();
+		if (!pos) return null;
+		const { x, y } = pos;
+
+		let out = clearPet ? this.#clearPetPayload(x, y) : "";
+		out += `\x1b[${y + 1};${x + 1}H${pixel.frames[this.#frame]}`;
+		return out;
+	}
+}

package/src/modes/components/hook-selector.ts

@@ -69,6 +69,11 @@ export interface HookSelectorOptions {
 	 * completion behavior as the main prompt editor.
 	 */
 	autocompleteProvider?: AutocompleteProvider;
+	/**
+	 * Maps raw single-key accelerators to option labels. Unset maps preserve
+	 * the legacy selector key handling exactly.
+	 */
+	acceleratorMap?: Readonly<Record<string, string>>;
 }
 
 class OutlinedList extends Container {
@@ -351,6 +356,7 @@ export class HookSelectorComponent extends Container {
 	#baseHelpText: string;
 	#tui: TUI | undefined;
 	#autocompleteProvider: AutocompleteProvider | undefined;
+	#acceleratorMap: Readonly<Record<string, string>> | undefined;
 	constructor(
 		title: string,
 		options: string[],
@@ -375,6 +381,7 @@ export class HookSelectorComponent extends Container {
 		this.#clarificationInput = opts?.clarificationInput;
 		this.#tui = opts?.tui;
 		this.#autocompleteProvider = opts?.autocompleteProvider;
+		this.#acceleratorMap = opts?.acceleratorMap;
 
 		this.addChild(new DynamicBorder());
 		this.addChild(new Spacer(1));
@@ -502,6 +509,11 @@ export class HookSelectorComponent extends Container {
 			this.#handleInputModeKey(keyData, this.#inlineEditor);
 			return;
 		}
+		const acceleratedOption = this.#acceleratorMap?.[keyData.toLowerCase()];
+		if (acceleratedOption && this.#options.includes(acceleratedOption)) {
+			this.#onSelectCallback(acceleratedOption);
+			return;
+		}
 		if (matchesKey(keyData, "up") || keyData === "k") {
 			this.#selectedIndex = Math.max(0, this.#selectedIndex - 1);
 			this.#updateList();