@sayknow-cli/tui 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.6.8] - 2026-09-29
+
+### Changed
+
+- `renderPetHalfBlocks(..., { scale: "compact" })` draws the pet's own sprite downscaled to 12×5 (eyes kept by feature-first pixel merging), replacing the redrawn `"half"` octopus. Every pose has the same height.
+
+## [0.6.7] - 2026-09-28
+
+### Added
+
+- `Component.handleClick(line, column)`: top-level children that are not focused can take left clicks, hit-tested against the rows they rendered in the last frame; returning true consumes the click before selection and the focused component.
+- `TUI.setMouseEnabled(enabled)`, `TUI.mouseEnabled` and `TUI.getFocusedComponent()`: switch terminal mouse reporting at runtime and ask which component has keyboard focus.
+- `Editor.setInputBackground(sgr)` paints a background band under every borderless input row (held across colored spans and the cursor); `Editor.isBrowsingHistory()`.
+- `renderPetHalfBlocks(..., { scale: "half" })` draws the small 8×4 octopus.
+
 ## [0.6.6] - 2026-09-28
 
 ### Added

package/dist/types/components/editor.d.ts

@@ -76,6 +76,14 @@ export declare class Editor implements Component, Focusable {
      * precedence over `setPromptGutter` and is ignored while the border is visible.
      */
     setRailGutter(glyph: string | undefined): void;
+    /**
+     * Paint a background band (an SGR sequence such as `\x1b[48;2;36;30;24m`) under
+     * every input row of a borderless editor, so the line being typed stands out from
+     * the transcript. Undefined removes it. Ignored while the border is visible.
+     */
+    setInputBackground(background: string | undefined): void;
+    /** True while Up/Down are walking prompt history rather than editing. */
+    isBrowsingHistory(): boolean;
     setInputPrefix(inputPrefix: string | undefined): void;
     setPlaceholder(placeholder: string | undefined): void;
     /**

package/dist/types/components/sayknow-pet.d.ts

@@ -129,7 +129,10 @@ export declare function buildSayknowPixelFrames(options: {
  * Draw a pet frame as text with half blocks, one terminal row per two pixel rows,
  * so the same octopus shows up where no pixel protocol is available (the launch
  * card). Fully transparent pixel rows at the top and bottom are cropped; columns
- * are kept so every frame of the animation keeps the same width.
+ * are kept so every frame of the animation keeps the same width. `scale: "compact"`
+ * draws the same sprite at three quarters size (12 columns, 5 rows).
  */
-export declare function renderPetHalfBlocks(frame: SayknowPixelFrameName, skin?: PetSkinId, colorMode?: "truecolor" | "256color"): string[];
+export declare function renderPetHalfBlocks(frame: SayknowPixelFrameName, skin?: PetSkinId, colorMode?: "truecolor" | "256color", options?: {
+    scale?: "full" | "compact";
+}): string[];
 export {};

package/dist/types/tui.d.ts

@@ -44,6 +44,13 @@ export interface Component {
     handleInput?(data: string): void;
     /** Optional handler for terminal mouse events when component has focus. */
     handleMouse?(event: MouseEvent): void;
+    /**
+     * Optional click hook for a top-level child that is not focused: called with the
+     * row (within this component's last rendered lines) and column of a left click.
+     * Return true to consume the click. Needs mouse reporting (`enableMouse` or
+     * {@link TUI.setMouseEnabled}).
+     */
+    handleClick?(line: number, column: number): boolean;
     /**
      * If true, component receives key release events (Kitty protocol).
      * Default is false - release events are filtered out.
@@ -298,6 +305,15 @@ export declare class TUI extends Container {
     /** Check if there are any visible overlays */
     hasOverlay(): boolean;
     invalidate(): void;
+    /**
+     * Turn terminal mouse reporting on or off while running. With it on, the terminal
+     * sends clicks and the wheel to the app instead of doing its own selection (most
+     * terminals still select with Shift held).
+     */
+    setMouseEnabled(enabled: boolean): void;
+    get mouseEnabled(): boolean;
+    /** The component that currently receives keyboard input. */
+    getFocusedComponent(): Component | null;
     start(): void;
     /**
      * Wait for a specific render request generation to be written successfully.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.6.6",
+	"version": "0.6.8",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.6.6",
-		"@sayknow-cli/utils": "0.6.6",
+		"@sayknow-cli/natives": "0.6.8",
+		"@sayknow-cli/utils": "0.6.8",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/editor.ts

@@ -428,6 +428,8 @@ export class Editor implements Component, Focusable {
 	cursorOverrideWidth: number | undefined;
 	#promptGutter: string | undefined;
 	#railGutter: string | undefined;
+	/** SGR background painted under every borderless input row (the composer band). */
+	#inputBackground: string | undefined;
 	#inputPrefix: string | undefined;
 	#inputPrefixWidth = 0;
 	#placeholder: string | undefined;
@@ -578,6 +580,21 @@ export class Editor implements Component, Focusable {
 		this.#invalidateLayoutCache();
 	}
 
+	/**
+	 * Paint a background band (an SGR sequence such as `\x1b[48;2;36;30;24m`) under
+	 * every input row of a borderless editor, so the line being typed stands out from
+	 * the transcript. Undefined removes it. Ignored while the border is visible.
+	 */
+	setInputBackground(background: string | undefined): void {
+		this.#inputBackground = background || undefined;
+		this.#invalidateLayoutCache();
+	}
+
+	/** True while Up/Down are walking prompt history rather than editing. */
+	isBrowsingHistory(): boolean {
+		return this.#historyIndex !== -1;
+	}
+
 	setInputPrefix(inputPrefix: string | undefined): void {
 		this.#inputPrefix = inputPrefix;
 		this.#inputPrefixWidth = inputPrefix ? visibleWidth(inputPrefix) : 0;
@@ -935,6 +952,7 @@ export class Editor implements Component, Focusable {
 		}
 
 		// Render each layout line
+		const inputRowsStart = result.length;
 		// Emit hardware cursor marker only when focused and not showing autocomplete
 		const emitCursorMarker = this.focused && !this.#autocompleteState;
 		const lineContentWidth = Math.max(0, contentAreaWidth - inputPrefixWidth);
@@ -1123,6 +1141,13 @@ export class Editor implements Component, Focusable {
 			}
 		}
 
+		const background = this.#inputBackground;
+		if (background && !borderVisible) {
+			for (let row = inputRowsStart; row < result.length; row++) {
+				result[row] = paintBackground(result[row]!, background, renderWidth);
+			}
+		}
+
 		if (borderVisible && this.#closedBorderBox) {
 			const bottomFillWidth = Math.max(0, renderWidth - borderWidth * 2);
 			const bottomLeftClosed = this.borderColor(`${box.bottomLeft}${box.horizontal.repeat(paddingX)}`);
@@ -1582,6 +1607,7 @@ export class Editor implements Component, Focusable {
 				placeholder: this.#placeholder,
 				promptGutter: this.#promptGutter,
 				railGutter: this.#railGutter,
+				inputBackground: this.#inputBackground,
 				useTerminalCursor: this.#useTerminalCursor,
 				cursorOverride: this.cursorOverride,
 				cursorOverrideWidth: this.cursorOverrideWidth,
@@ -3105,3 +3131,13 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 		return null;
 	}
 }
+
+/**
+ * Hold a background under a whole row: re-assert it after every reset inside the row
+ * (cursor, ghost text and colored spans all end with one) and pad to `width`.
+ */
+function paintBackground(line: string, background: string, width: number): string {
+	const fill = Math.max(0, width - visibleWidth(line));
+	const held = line.replace(/\x1b\[(?:0)?m|\x1b\[49m/g, match => `${match}${background}`);
+	return `${background}${held}${padding(fill)}\x1b[0m`;
+}

package/src/components/sayknow-pet.ts

@@ -434,24 +434,76 @@ export function buildSayknowPixelFrames(options: {
 	return { frames, protocol: options.protocol, widthPx, heightPx, columns, rows, rasterRows };
 }
 
+/**
+ * Pixel priority when several pixels merge into one on downscale: features first, so
+ * the eyes survive (a block holding a pupil stays a pupil), then outline over body.
+ */
+const DOWNSCALE_PRIORITY = "VWGwKrRbHhA";
+
+/**
+ * The pet's own sprite, scaled to `size` columns (rows in proportion; nearest block, feature-first),
+ * so compact surfaces show the same octopus rather than a redraw. A block becomes
+ * transparent only when most of it is.
+ */
+function downscaleGrid(grid: readonly string[], size: number, palette: Palette, rowCount?: number): string[] {
+	const sourceRows = grid.length;
+	const source = grid[0]?.length ?? 0;
+	// Rows in proportion to columns unless a height is asked for.
+	const rows = rowCount ?? Math.round((sourceRows * size) / source);
+	const out: string[] = [];
+	for (let row = 0; row < rows; row++) {
+		const rowStart = Math.floor((row * sourceRows) / rows);
+		const rowEnd = Math.floor(((row + 1) * sourceRows) / rows);
+		let line = "";
+		for (let col = 0; col < size; col++) {
+			const colStart = Math.floor((col * source) / size);
+			const colEnd = Math.floor(((col + 1) * source) / size);
+			const cells: string[] = [];
+			for (let y = rowStart; y < rowEnd; y++) for (let x = colStart; x < colEnd; x++) cells.push(grid[y]![x] ?? ".");
+			const opaque = cells.filter(ch => palette[ch] != null);
+			line +=
+				opaque.length * 2 < cells.length
+					? "."
+					: ([...DOWNSCALE_PRIORITY].find(ch => opaque.includes(ch)) ?? opaque[0]!);
+		}
+		out.push(line);
+	}
+	return out;
+}
+
+/** Pixel size of the compact pet: three quarters of the 16×16 sprite (12 columns, 5 rows). */
+const COMPACT_PET_PIXELS = 12;
+/** Terminal rows of the compact pet (two pixel rows each). */
+const COMPACT_PET_ROWS = 5;
+
 /**
  * Draw a pet frame as text with half blocks, one terminal row per two pixel rows,
  * so the same octopus shows up where no pixel protocol is available (the launch
  * card). Fully transparent pixel rows at the top and bottom are cropped; columns
- * are kept so every frame of the animation keeps the same width.
+ * are kept so every frame of the animation keeps the same width. `scale: "compact"`
+ * draws the same sprite at three quarters size (12 columns, 5 rows).
  */
 export function renderPetHalfBlocks(
 	frame: SayknowPixelFrameName,
 	skin: PetSkinId = "red",
 	colorMode: "truecolor" | "256color" = "truecolor",
+	options: { scale?: "full" | "compact" } = {},
 ): string[] {
-	const grid = PIXEL_GRIDS[frame];
 	const palette = PET_SKINS[skin].palette;
+	const compact = options.scale === "compact";
+	// Compact: the sprite's own pixel rows without its empty top and bottom margins (the
+	// same for every pose), scaled to 12×10 pixels = 12 columns × 5 rows. Cropping per pose
+	// would change the height while the tentacles move and make the card jump.
+	const grid = compact
+		? downscaleGrid(PIXEL_GRIDS[frame].slice(1, 15), COMPACT_PET_PIXELS, palette, COMPACT_PET_ROWS * 2)
+		: PIXEL_GRIDS[frame];
 	const opaque = (row: string): boolean => [...row].some(ch => palette[ch] != null);
 	let top = 0;
-	while (top < grid.length && !opaque(grid[top]!)) top++;
 	let bottom = grid.length - 1;
-	while (bottom > top && !opaque(grid[bottom]!)) bottom--;
+	if (!compact) {
+		while (top < grid.length && !opaque(grid[top]!)) top++;
+		while (bottom > top && !opaque(grid[bottom]!)) bottom--;
+	}
 	const format = colorMode === "truecolor" ? "ansi-16m" : "ansi-256";
 	const fg = (rgb: Rgb): string => Bun.color(`rgb(${rgb[0]},${rgb[1]},${rgb[2]})`, format) ?? "";
 	const bg = (rgb: Rgb): string => fg(rgb).replace("\x1b[38;", "\x1b[48;");

package/src/tui.ts

@@ -132,6 +132,14 @@ export interface Component {
 	/** Optional handler for terminal mouse events when component has focus. */
 	handleMouse?(event: MouseEvent): void;
 
+	/**
+	 * Optional click hook for a top-level child that is not focused: called with the
+	 * row (within this component's last rendered lines) and column of a left click.
+	 * Return true to consume the click. Needs mouse reporting (`enableMouse` or
+	 * {@link TUI.setMouseEnabled}).
+	 */
+	handleClick?(line: number, column: number): boolean;
+
 	/**
 	 * If true, component receives key release events (Kitty protocol).
 	 * Default is false - release events are filtered out.
@@ -760,6 +768,9 @@ export class TUI extends Container {
 	#mouseSelectionStart: MouseSelectionPoint | null = null;
 	#mouseSelectionEnd: MouseSelectionPoint | null = null;
 	#mouseSelectionDragged = false;
+	/** Rows each top-level child occupied in the last frame, for click hit-testing. */
+	#childRows = new Map<Component, { start: number; count: number }>();
+	#mouseEnabled = false;
 	#viewportOutputSource: ViewportOutputSource | null = null;
 	#manualOutputNotice = false;
 	#manualTranscriptLineCount = 0;
@@ -828,6 +839,7 @@ export class TUI extends Container {
 		} = {},
 	) {
 		super();
+		this.#mouseEnabled = options.enableMouse === true;
 		this.terminal = terminal;
 		if (showHardwareCursor !== undefined) {
 			this.#showHardwareCursor = showHardwareCursor;
@@ -1315,13 +1327,34 @@ export class TUI extends Container {
 		for (const overlay of this.overlayStack) overlay.mouseBounds = undefined;
 	}
 
+	/**
+	 * Turn terminal mouse reporting on or off while running. With it on, the terminal
+	 * sends clicks and the wheel to the app instead of doing its own selection (most
+	 * terminals still select with Shift held).
+	 */
+	setMouseEnabled(enabled: boolean): void {
+		if (this.#mouseEnabled === enabled) return;
+		this.#mouseEnabled = enabled;
+		if (!enabled) this.#clearMouseSelection();
+		if (!this.#stopped) this.terminal.setMouseEnabled?.(enabled);
+	}
+
+	get mouseEnabled(): boolean {
+		return this.#mouseEnabled;
+	}
+
+	/** The component that currently receives keyboard input. */
+	getFocusedComponent(): Component | null {
+		return this.#focusedComponent;
+	}
+
 	start(): void {
 		this.#stopped = false;
 		this.#terminalUnavailable = false;
 		// Seed the observed width so a spurious post-start resize event (iTerm2 tab
 		// activation, the self-sent SIGWINCH after resume) is not read as a reflow.
 		this.#lastObservedWidth = this.terminal.columns;
-		this.terminal.setMouseEnabled?.(this.options.enableMouse === true);
+		this.terminal.setMouseEnabled?.(this.#mouseEnabled);
 		this.terminal.start(
 			data => this.#handleInput(data),
 			() => {
@@ -2022,6 +2055,10 @@ export class TUI extends Container {
 				this.#clearMouseSelection();
 				this.scrollViewportBy(mouse.direction! * DEFAULT_WHEEL_LINES, { pin: "stable" });
 			} else if (mouse.kind === "click") {
+				if (this.#dispatchChildClick(mouse)) {
+					this.requestRender(false, "mouse");
+					return;
+				}
 				this.#beginMouseSelection(mouse);
 				const focusedOverlay = this.overlayStack.find(o => o.component === this.#focusedComponent);
 				if (focusedOverlay) {
@@ -2096,6 +2133,22 @@ export class TUI extends Container {
 		}
 	}
 
+	/** Give a click to the top-level child under it, if that child takes clicks and no overlay is focused. */
+	#dispatchChildClick(mouse: MouseEvent): boolean {
+		if (this.#childRows.size === 0) return false;
+		if (this.overlayStack.some(overlay => overlay.component === this.#focusedComponent)) return false;
+		const point = this.#mouseSelectionPoint(mouse);
+		if (point === null) return false;
+		for (const [child, rows] of this.#childRows) {
+			if (point.line < rows.start || point.line >= rows.start + rows.count) continue;
+			if (child.handleClick?.(point.line - rows.start, point.column)) {
+				this.#clearMouseSelection();
+				return true;
+			}
+		}
+		return false;
+	}
+
 	#mouseSelectionPoint(mouse: MouseEvent): MouseSelectionPoint | null {
 		if (this.#manualViewportTop === undefined) {
 			return { line: this.#viewportTopRow + mouse.y - 1, column: mouse.x - 1 };
@@ -2919,9 +2972,14 @@ export class TUI extends Container {
 		const renderedChildren = new Map<Component, string[]>();
 		let anchorFrame: ViewportAnchorFrame | null = null;
 		const anchorRenderFailureCountBefore = viewportAnchorRenderFailureCount;
+		this.#childRows.clear();
 		for (const child of this.children) {
 			const rendered = safeRenderComponentWithViewportAnchors(child, width, "tui-child");
 			renderedChildren.set(child, rendered.lines);
+			// Children above the pinned suffix keep these rows: padding and suffix trimming
+			// only touch the pinned tail.
+			if (child.handleClick)
+				this.#childRows.set(child, { start: renderedLines.length, count: rendered.lines.length });
 			if (child === this.#viewportAnchorComponent && rendered.anchors.some(anchor => anchor !== null)) {
 				anchorFrame = { startRow: renderedLines.length, anchors: rendered.anchors };
 			}