@sayknow-cli/tui 0.6.7 → 0.6.9

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.6.9] - 2026-09-29
+
+### Changed
+
+- `TUI.setPostRenderEmitter` passes `PostRenderFrameInfo` (line count, full-redraw count, terminal size) so an overlay can skip re-emitting when nothing that could move or erase it changed.
+- The fast animation cadence is 33 ms (~30 fps) instead of 16 ms; `AnimationCadence` is `33 | 80`.
+
+### Added
+
+- `TUI.isChildLineVisible(child, line)`: whether a line of a click-tracked top-level child was on screen in the last frame, so animations can stop before they would force a full redraw.
+
+## [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

package/dist/types/animation-scheduler.d.ts

@@ -1,4 +1,8 @@
-export type AnimationCadence = 16 | 80;
+/**
+ * Shared timer cadences. 33 ms (~30 fps) drives colors that change over time (the
+ * working-message shimmer); 80 ms drives frame-stepped animations (spinners, the pet).
+ */
+export type AnimationCadence = 33 | 80;
 type AnimationCallback = (now: number) => void;
 export interface AnimationRegistration {
     unregister(): void;

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

@@ -129,10 +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. `scale: "half"`
- * draws the small octopus (8 columns, 4 rows); frames it has no pose for use its base.
+ * 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", options?: {
-    scale?: "full" | "half";
+    scale?: "full" | "compact";
 }): string[];
 export {};

package/dist/types/tui.d.ts

@@ -238,6 +238,18 @@ type TuiRenderCounterSnapshot = {
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
+/**
+ * What the frame about to be written looks like, for a post-render overlay to decide
+ * whether it must redraw: a new line count means the screen may have scrolled, a new
+ * full-redraw count means it was cleared or replayed.
+ */
+export interface PostRenderFrameInfo {
+    totalLines: number;
+    fullRedraws: number;
+    columns: number;
+    rows: number;
+}
+export type PostRenderEmitter = (frame: PostRenderFrameInfo) => string | null;
 export declare class TUI extends Container {
     #private;
     private readonly options;
@@ -312,6 +324,13 @@ export declare class TUI extends Container {
      */
     setMouseEnabled(enabled: boolean): void;
     get mouseEnabled(): boolean;
+    /**
+     * Whether `line` of a top-level child was on screen in the last frame. Only children
+     * with a `handleClick` hook are tracked; others report false. A line scrolled above
+     * the viewport is not visible — and changing it would force a full redraw, so
+     * animations should stop there.
+     */
+    isChildLineVisible(child: Component, line: number): boolean;
     /** The component that currently receives keyboard input. */
     getFocusedComponent(): Component | null;
     start(): void;
@@ -369,5 +388,5 @@ export declare class TUI extends Container {
      * Used for absolute-positioned overlays such as pixel-image pets that live
      * outside the line-based component model. Return null to emit nothing.
      */
-    setPostRenderEmitter(emitter: (() => string | null) | undefined): void;
+    setPostRenderEmitter(emitter: PostRenderEmitter | undefined): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.6.7",
+	"version": "0.6.9",
 	"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.7",
-		"@sayknow-cli/utils": "0.6.7",
+		"@sayknow-cli/natives": "0.6.9",
+		"@sayknow-cli/utils": "0.6.9",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/animation-scheduler.ts

@@ -1,4 +1,8 @@
-export type AnimationCadence = 16 | 80;
+/**
+ * Shared timer cadences. 33 ms (~30 fps) drives colors that change over time (the
+ * working-message shimmer); 80 ms drives frame-stepped animations (spinners, the pet).
+ */
+export type AnimationCadence = 33 | 80;
 
 type TimerHandle = ReturnType<typeof setInterval>;
 type AnimationCallback = (now: number) => void;

package/src/components/loader.ts

@@ -70,7 +70,10 @@ export class Loader extends Text {
 				}
 				this.#updateDisplay();
 			},
-			this.#timeDependentColor ? 16 : 80,
+			// Time-dependent colors (the working-message shimmer) at ~30 fps: every tick
+			// redraws the whole UI, which in a long session costs as much as the rest of
+			// the turn. 60 fps doubled that cost for motion the eye cannot tell apart.
+			this.#timeDependentColor ? 33 : 80,
 		);
 	}
 

package/src/components/sayknow-pet.ts

@@ -434,49 +434,76 @@ export function buildSayknowPixelFrames(options: {
 	return { frames, protocol: options.protocol, widthPx, heightPx, columns, rows, rasterRows };
 }
 
-// 8x8 small octopus for compact surfaces (the launch card): the same palette and
-// features — rounded mantle with a highlight, white eyes over dark pupils, a row of
-// tentacles — drawn for the size rather than downsampled, which turns the dome blocky.
-// biome-ignore format: pixel grid stays one row per line
-const SMALL_BASE = [
-	"..KKKK..",
-	".KRrrRK.",
-	"KRRRRRRK",
-	"KRWRRWRK",
-	"KRVRRVRK",
-	"KRRRRRRK",
-	"KRKRRKRK",
-	"K.K..K.K",
-];
-const SMALL_GRIDS: Partial<Record<SayknowPixelFrameName, string[]>> = {
-	base: SMALL_BASE,
-	danceL: mix(SMALL_BASE, { 6: "RKRRKRK.", 7: ".K..K.K." }),
-	danceR: mix(SMALL_BASE, { 6: ".KRKRRKR", 7: ".K.K..K." }),
-	gazeL: mix(SMALL_BASE, { 3: "KWRRWRRK", 4: "KVRRVRRK" }),
-	gazeR: mix(SMALL_BASE, { 3: "KRRWRRWK", 4: "KRRVRRVK" }),
-	flicker: mix(SMALL_BASE, { 3: "KRRRRRRK", 4: "KRKRRKRK" }),
-};
+/**
+ * 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. `scale: "half"`
- * draws the small octopus (8 columns, 4 rows); frames it has no pose for use its base.
+ * 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" | "half" } = {},
+	options: { scale?: "full" | "compact" } = {},
 ): string[] {
 	const palette = PET_SKINS[skin].palette;
-	const grid = options.scale === "half" ? (SMALL_GRIDS[frame] ?? SMALL_BASE) : PIXEL_GRIDS[frame];
+	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

@@ -673,6 +673,20 @@ type RenderCommitWaiter = {
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
+/**
+ * What the frame about to be written looks like, for a post-render overlay to decide
+ * whether it must redraw: a new line count means the screen may have scrolled, a new
+ * full-redraw count means it was cleared or replayed.
+ */
+export interface PostRenderFrameInfo {
+	totalLines: number;
+	fullRedraws: number;
+	columns: number;
+	rows: number;
+}
+
+export type PostRenderEmitter = (frame: PostRenderFrameInfo) => string | null;
+
 export class TUI extends Container {
 	terminal: Terminal;
 	#previousLines: string[] = [];
@@ -1343,6 +1357,22 @@ export class TUI extends Container {
 		return this.#mouseEnabled;
 	}
 
+	/**
+	 * Whether `line` of a top-level child was on screen in the last frame. Only children
+	 * with a `handleClick` hook are tracked; others report false. A line scrolled above
+	 * the viewport is not visible — and changing it would force a full redraw, so
+	 * animations should stop there.
+	 */
+	isChildLineVisible(child: Component, line: number): boolean {
+		const rows = this.#childRows.get(child);
+		if (!rows || line < 0 || line >= rows.count) return false;
+		const absolute = rows.start + line;
+		if (this.#manualViewportTop === undefined) {
+			return absolute >= this.#viewportTopRow && absolute < this.#viewportTopRow + this.terminal.rows;
+		}
+		return this.#committedTranscriptRows.includes(absolute);
+	}
+
 	/** The component that currently receives keyboard input. */
 	getFocusedComponent(): Component | null {
 		return this.#focusedComponent;
@@ -3699,11 +3729,11 @@ export class TUI extends Container {
 	 * Used for absolute-positioned overlays such as pixel-image pets that live
 	 * outside the line-based component model. Return null to emit nothing.
 	 */
-	setPostRenderEmitter(emitter: (() => string | null) | undefined): void {
+	setPostRenderEmitter(emitter: PostRenderEmitter | undefined): void {
 		this.#postRenderEmitter = emitter;
 	}
 
-	#postRenderEmitter: (() => string | null) | undefined;
+	#postRenderEmitter: PostRenderEmitter | undefined;
 
 	#writeRenderBufferAndReanchorImeCursor(
 		buffer: string,
@@ -3711,7 +3741,12 @@ export class TUI extends Container {
 		totalLines: number,
 		onBufferWritten?: () => void,
 	): boolean {
-		const overlay = this.#postRenderEmitter?.();
+		const overlay = this.#postRenderEmitter?.({
+			totalLines,
+			fullRedraws: this.#fullRedrawCount,
+			columns: this.terminal.columns,
+			rows: this.terminal.rows,
+		});
 		if (overlay) {
 			// DECSC/DECRC keep the hardware cursor stable; the dedicated
 			// synchronized block prevents visible tearing while the overlay