@sayknow-cli/tui 0.6.9 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-09-29
+
+## [0.7.0] - 2026-09-29
+
+### Added
+
+- `renderSayoPose` / `decodePng` (sayo-sprite): Sayo mascot poses and tints rendered from an embedded image; `prepareSayoPlaceholderImages` (sayo-placeholder): kitty Unicode-placeholder images for text lines.
+- Pet skin `orange` (Sayo), now first in `PET_SKIN_IDS`; kitty pet frames draw the Sayo image and are sent with `o=z`.
+
 ## [0.6.9] - 2026-09-29
 
 ### Changed

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

@@ -1,53 +1,9 @@
-/**
- * ┌─ SAYKNOW PET SPRITE SPEC ────────────────────────────────────────────────┐
- * The pet is a 16×16 pixel octopus drawn beside the composer. Everything here
- * is data: no PNGs, no assets — each frame is 16 strings of 16 chars, encoded
- * to a sixel or kitty escape at runtime. Author a new frame by drawing a grid.
- *
- * GRID RULES
- * - Exactly 16 rows × 16 columns. Only PALETTE keys below are valid chars.
- * - `.` = transparent. Keep the outer columns transparent so the sprite sits
- *   snug beside the input box (the widget reserves +1 column of slack).
- *
- * PALETTE (char → role) — see PALETTE for exact RGB:
- *   .=transparent  K=dark outline  R=mantle body  r=body highlight
- *   W=eye white    V=pupil         G=eye sparkle  b=underside
- *   w=tear         H h A=reserved (unused by the octopus art)
- *
- * FRAME CATALOG (SayknowPixelFrameName → PIXEL_GRIDS):
- *   base    idle rest; also the dance "drop/settle" beat
- *   gazeL   eyes glance left    ┐ idle loop (see sayknow-pet-widget IDLE_LOOP)
- *   gazeR   eyes glance right   │
- *   flicker eyes blink          ┘
- *   flex    sparkly "yay" eyes; dance accent + random idle flex burst
- *   danceL  tentacles sway left   ┐ work loop (PARA_PARA_STEPS)
- *   danceR  tentacles sway right  ┘
- *   cry1..3 a tear trails from the outer eye corners (BlueOcto sob)
- *
- * RENDERING: buildSayknowPixelFrames({ protocol, cellWidthPx, cellHeightPx,
- * targetRows: 2 }) scales the art to 2 terminal rows and encodes each frame
- * once. Kitty uses a native `Y=` sub-cell drop (set by the widget) to sit on the
- * composer border; sixel uses transparent top padding.
- *
- * BEHAVIOR (timing, positioning, on/off) lives in
- * packages/coding-agent/src/modes/components/sayknow-pet-widget.ts.
- *
- * ADD A FRAME: draw the grid → add its name to SayknowPixelFrameName → register it in
- * PIXEL_GRIDS → reference it from an idle/work loop or a skin burst.
- *
- * ADD A PET (skin): append one entry to PET_SKINS below — { id, label, description,
- * palette, burst }. The id flows into PetSkinId/PetMode automatically, the settings
- * enum, `/pet` command and both selectors derive their options from PET_SKINS, and the
- * widget reads `burst` to animate — no other file needs editing. Recolor with a palette
- * spread (see BLUE_PALETTE); add frames only for poses the catalog lacks.
- * └────────────────────────────────────────────────────────────────────────┘
- */
 type Rgb = readonly [number, number, number];
 export type Palette = Record<string, Rgb | null>;
-export declare const PET_SKIN_IDS: readonly ["red", "blue"];
+export declare const PET_SKIN_IDS: readonly ["orange", "red", "blue"];
 export type PetSkinId = (typeof PET_SKIN_IDS)[number];
 /** Every pet mode: "off" plus each skin id, in menu order. */
-export declare const PET_MODE_IDS: readonly ["off", "red", "blue"];
+export declare const PET_MODE_IDS: readonly ["off", "orange", "red", "blue"];
 export type PetMode = (typeof PET_MODE_IDS)[number];
 /** Narrow an arbitrary string to a PetMode. */
 export declare function isPetMode(value: string): value is PetMode;
@@ -93,6 +49,12 @@ export declare const __sayknowPetTestHooks: {
 };
 /** Encode a grid as a transparent SIXEL image, optionally bottom-aligned by top padding. */
 export declare function encodeGridSixel(grid: string[], scale: number, topPaddingPx?: number, palette?: Palette): string;
+/**
+ * Kitty escape for a straight-RGBA canvas already laid out to the placement box: delete
+ * the previous image with this id, then transmit and display the new one in `cols`×`rows`
+ * cells. `Y=` drops it by sub-cell pixels; `C=1` keeps the cursor where it was.
+ */
+export declare function encodeRgbaKitty(rgba: Uint8Array, w: number, h: number, imageId: number, cols: number, rows: number, cellYOffsetPx?: number): string;
 /** Encode a bottom-aligned grid as kitty raw RGBA at `scale`. */
 export declare function encodeGridKitty(grid: string[], scale: number, imageId: number, cols: number, rows: number, topPaddingPx?: number, cellYOffsetPx?: number, leftPaddingPx?: number, rightPaddingPx?: number, palette?: Palette): string;
 export interface SayknowPixelFrames {
@@ -122,7 +84,7 @@ export declare function buildSayknowPixelFrames(options: {
     /** Native sub-cell `Y=` pixel offset that drops the kitty sprite within its first cell. */
     kittyCellYOffsetPx?: number;
     kittyImageId?: number;
-    /** Color skin for the sprite palette (default "red"). */
+    /** Color skin (default "orange", Sayo). */
     skin?: PetSkinId;
 }): SayknowPixelFrames;
 /**

package/dist/types/components/sayo-placeholder.d.ts

@@ -0,0 +1,23 @@
+import { type SayoPose, type SayoTint } from "./sayo-sprite";
+/** Largest image this module can address in cells. */
+export declare const SAYO_PLACEHOLDER_MAX_CELLS: number;
+export interface SayoPlaceholderImages {
+    columns: number;
+    rows: number;
+    /** Escape payload that uploads every pose and creates its virtual placement. */
+    upload: string;
+    /** Text row `row` of `pose`: placeholder cells colored with that pose's image id. */
+    line(pose: SayoPose, row: number): string;
+}
+/**
+ * Prepare `poses` of Sayo in `tint`, `rows` cells tall and square in pixels. Image ids
+ * are `idBase + index` and must fit in 24 bits (the id travels as an RGB color).
+ */
+export declare function prepareSayoPlaceholderImages(options: {
+    tint: SayoTint;
+    rows: number;
+    cellWidthPx: number;
+    cellHeightPx: number;
+    poses: readonly SayoPose[];
+    idBase: number;
+}): SayoPlaceholderImages;

package/dist/types/components/sayo-sprite-source.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sayo, the Sayknow octopus mascot (Sayknow Kit `public/sayo-logo.png`), as a 200×200
+ * RGBA PNG. Embedded as text so single-file builds carry it; decoded once at runtime by
+ * sayo-sprite.ts, which draws every pose and color from it.
+ */
+export declare const SAYO_SOURCE_PNG_BASE64: string;

package/dist/types/components/sayo-sprite.d.ts

@@ -0,0 +1,13 @@
+export type SayoPose = "base" | "gazeL" | "gazeR" | "flicker" | "flex" | "danceL" | "danceR" | "cry1" | "cry2" | "cry3";
+export type SayoTint = "orange" | "red" | "blue";
+/** Straight (non-premultiplied) RGBA pixels. */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+export declare function decodePng(bytes: Uint8Array): RgbaImage;
+/** Render one pose, tinted, into a `size`×`size` straight-RGBA image. */
+export declare function renderSayoPose(pose: SayoPose, tint: SayoTint, size: number): RgbaImage;
+/** Every pose the pet state machine names. */
+export declare const SAYO_POSES: SayoPose[];

package/dist/types/index.d.ts

@@ -8,6 +8,8 @@ export * from "./components/input";
 export * from "./components/loader";
 export * from "./components/markdown";
 export * from "./components/sayknow-pet";
+export * from "./components/sayo-placeholder";
+export * from "./components/sayo-sprite";
 export * from "./components/secret-input";
 export * from "./components/select-list";
 export * from "./components/settings-list";

package/package.json

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

package/src/components/sayknow-pet.ts

@@ -1,8 +1,10 @@
 /**
  * ┌─ SAYKNOW PET SPRITE SPEC ────────────────────────────────────────────────┐
- * The pet is a 16×16 pixel octopus drawn beside the composer. Everything here
- * is data: no PNGs, no assets — each frame is 16 strings of 16 chars, encoded
- * to a sixel or kitty escape at runtime. Author a new frame by drawing a grid.
+ * The pet is Sayo, the Sayknow octopus, beside the composer. Kitty-graphics terminals
+ * (Ghostty, kitty, WezTerm) draw the Sayo image itself, one transformed image per pose
+ * (sayo-sprite.ts). Sixel terminals and the half-block text fallback draw the 16×16
+ * pixel octopus below instead: each frame is 16 strings of 16 chars, encoded at runtime.
+ * A new pose needs both: a grid here and a transform in sayo-sprite.ts POSES.
  *
  * GRID RULES
  * - Exactly 16 rows × 16 columns. Only PALETTE keys below are valid chars.
@@ -42,10 +44,13 @@
  * spread (see BLUE_PALETTE); add frames only for poses the catalog lacks.
  * └────────────────────────────────────────────────────────────────────────┘
  */
+import { deflateSync } from "node:zlib";
+import { renderSayoPose } from "./sayo-sprite";
+
 type Rgb = readonly [number, number, number];
 
 export type Palette = Record<string, Rgb | null>;
-export const PET_SKIN_IDS = ["red", "blue"] as const;
+export const PET_SKIN_IDS = ["orange", "red", "blue"] as const;
 export type PetSkinId = (typeof PET_SKIN_IDS)[number];
 /** Every pet mode: "off" plus each skin id, in menu order. */
 export const PET_MODE_IDS = ["off", ...PET_SKIN_IDS] as const;
@@ -69,6 +74,16 @@ const RED_PALETTE: Palette = {
 	A: [196, 60, 30], // reserved
 	w: [200, 230, 255], // tear (BlueOcto sob)
 };
+// Sayo's orange for the dot fallback (sixel and text terminals); kitty terminals draw
+// the Sayo image itself (sayo-sprite.ts).
+const ORANGE_PALETTE: Palette = {
+	...RED_PALETTE,
+	K: [120, 40, 10], // outline
+	R: [255, 122, 30], // mantle body
+	r: [255, 176, 100], // highlight
+	b: [232, 70, 40], // underside
+	A: [214, 80, 20], // reserved
+};
 // BlueOcto recolors the octopus for the blue-octopus theme: ocean outline, a bright
 // mantle, azure highlight and foam tears. Reserved hat keys are shared but unused.
 const BLUE_PALETTE: Palette = {
@@ -194,6 +209,16 @@ export interface PetSkin {
 
 /** Skin registry — the single source for palettes, behavior and selector/command copy. */
 export const PET_SKINS: Record<PetSkinId, PetSkin> = {
+	orange: {
+		id: "orange",
+		label: "Sayo",
+		description: "Sayo, the orange Sayknow octopus.",
+		palette: ORANGE_PALETTE,
+		burst: {
+			intro: PARA_PARA_STEPS,
+			tail: { frames: ["flex", "base"], stepMs: 220, ms: 880 },
+		},
+	},
 	red: {
 		id: "red",
 		label: "RedOctopus",
@@ -306,6 +331,35 @@ export function encodeGridSixel(
 	return `${out}\x1b\\`;
 }
 
+/**
+ * Kitty escape for a straight-RGBA canvas already laid out to the placement box: delete
+ * the previous image with this id, then transmit and display the new one in `cols`×`rows`
+ * cells. `Y=` drops it by sub-cell pixels; `C=1` keeps the cursor where it was.
+ */
+export function encodeRgbaKitty(
+	rgba: Uint8Array,
+	w: number,
+	h: number,
+	imageId: number,
+	cols: number,
+	rows: number,
+	cellYOffsetPx = 0,
+): string {
+	// zlib-compressed (`o=z`): a mostly transparent sprite shrinks several-fold.
+	const data = deflateSync(rgba).toString("base64");
+	const CHUNK = 4000;
+	const yParam = cellYOffsetPx > 0 ? `,Y=${Math.round(cellYOffsetPx)}` : "";
+	let out = `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`;
+	for (let off = 0, first = true; off < data.length; off += CHUNK, first = false) {
+		const chunk = data.slice(off, off + CHUNK);
+		const more = off + CHUNK < data.length ? 1 : 0;
+		out += first
+			? `\x1b_Ga=T,f=32,o=z,s=${w},v=${h},c=${cols},r=${rows},i=${imageId},q=2,C=1${yParam},m=${more};${chunk}\x1b\\`
+			: `\x1b_Gm=${more};${chunk}\x1b\\`;
+	}
+	return out;
+}
+
 /** Encode a bottom-aligned grid as kitty raw RGBA at `scale`. */
 export function encodeGridKitty(
 	grid: string[],
@@ -345,21 +399,36 @@ export function encodeGridKitty(
 			rgba[o + 3] = 255;
 		}
 	}
-	const data = Buffer.from(rgba).toString("base64");
-	const CHUNK = 4000;
-	// `Y=` offsets the sprite down by sub-cell pixels within the first cell — the
-	// kitty analogue of the sixel top-padding drop. `C=1` keeps the placement
-	// cursor-neutral so the overlay never nudges the composer's real cursor.
-	const yParam = cellYOffsetPx > 0 ? `,Y=${Math.round(cellYOffsetPx)}` : "";
-	let out = `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`;
-	for (let off = 0, first = true; off < data.length; off += CHUNK, first = false) {
-		const chunk = data.slice(off, off + CHUNK);
-		const more = off + CHUNK < data.length ? 1 : 0;
-		out += first
-			? `\x1b_Ga=T,f=32,s=${w},v=${h},c=${cols},r=${rows},i=${imageId},q=2,C=1${yParam},m=${more};${chunk}\x1b\\`
-			: `\x1b_Gm=${more};${chunk}\x1b\\`;
+	return encodeRgbaKitty(rgba, w, h, imageId, cols, rows, cellYOffsetPx);
+}
+
+/**
+ * Sayo for kitty: the pose rendered at the sprite size and placed in the padded box the
+ * grid frames use, so placement, the sub-cell drop and cleanup are unchanged.
+ */
+function encodeSayoKitty(
+	pose: SayknowPixelFrameName,
+	skin: PetSkinId,
+	spritePx: number,
+	imageId: number,
+	cols: number,
+	rows: number,
+	topPaddingPx: number,
+	cellYOffsetPx: number,
+	leftPaddingPx: number,
+	rightPaddingPx: number,
+): string {
+	const sprite = renderSayoPose(pose, skin, spritePx);
+	const w = spritePx + leftPaddingPx + rightPaddingPx;
+	const h = spritePx + topPaddingPx;
+	const rgba = new Uint8Array(w * h * 4);
+	for (let y = 0; y < spritePx; y++) {
+		rgba.set(
+			sprite.data.subarray(y * spritePx * 4, (y + 1) * spritePx * 4),
+			((y + topPaddingPx) * w + leftPaddingPx) * 4,
+		);
 	}
-	return out;
+	return encodeRgbaKitty(rgba, w, h, imageId, cols, rows, cellYOffsetPx);
 }
 
 export interface SayknowPixelFrames {
@@ -390,7 +459,7 @@ export function buildSayknowPixelFrames(options: {
 	/** Native sub-cell `Y=` pixel offset that drops the kitty sprite within its first cell. */
 	kittyCellYOffsetPx?: number;
 	kittyImageId?: number;
-	/** Color skin for the sprite palette (default "red"). */
+	/** Color skin (default "orange", Sayo). */
 	skin?: PetSkinId;
 }): SayknowPixelFrames {
 	const targetRows = options.targetRows ?? 2;
@@ -411,15 +480,16 @@ export function buildSayknowPixelFrames(options: {
 	const leftPaddingPx = Math.floor(horizontalPaddingPx / 2);
 	const rightPaddingPx = horizontalPaddingPx - leftPaddingPx;
 	const imageId = options.kittyImageId ?? 0xc0de;
-	const palette = PET_SKINS[options.skin ?? "red"].palette;
+	const palette = PET_SKINS[options.skin ?? "orange"].palette;
 	const frames = {} as Record<SayknowPixelFrameName, string>;
 	for (const name of Object.keys(PIXEL_GRIDS) as SayknowPixelFrameName[]) {
 		frames[name] =
 			options.protocol === "sixel"
 				? encodeGridSixel(PIXEL_GRIDS[name], scale, topPaddingPx, palette)
-				: encodeGridKitty(
-						PIXEL_GRIDS[name],
-						scale,
+				: encodeSayoKitty(
+						name,
+						options.skin ?? "orange",
+						widthPx,
 						imageId,
 						columns,
 						rows,
@@ -427,7 +497,6 @@ export function buildSayknowPixelFrames(options: {
 						options.kittyCellYOffsetPx ?? 0,
 						leftPaddingPx,
 						rightPaddingPx,
-						palette,
 					);
 	}
 
@@ -485,7 +554,7 @@ const COMPACT_PET_ROWS = 5;
  */
 export function renderPetHalfBlocks(
 	frame: SayknowPixelFrameName,
-	skin: PetSkinId = "red",
+	skin: PetSkinId = "orange",
 	colorMode: "truecolor" | "256color" = "truecolor",
 	options: { scale?: "full" | "compact" } = {},
 ): string[] {

package/src/components/sayo-placeholder.ts

@@ -0,0 +1,102 @@
+/**
+ * Sayo in text lines, through kitty graphics Unicode placeholders (Ghostty, kitty).
+ *
+ * Each pose is uploaded once as an image with a virtual placement (`U=1`). A line then
+ * shows it by writing placeholder cells (U+10EEEE plus row/column diacritics) in a
+ * foreground color that encodes the image id. The image lives in ordinary text: it
+ * scrolls, redraws and clears with the transcript, and switching poses is a color change
+ * on those cells rather than a new image.
+ */
+import { deflateSync } from "node:zlib";
+import { renderSayoPose, type SayoPose, type SayoTint } from "./sayo-sprite";
+
+const PLACEHOLDER = String.fromCodePoint(0x10eeee);
+
+/** Kitty's row/column diacritics (rowcolumn-diacritics.txt), enough for small images. */
+const DIACRITICS = [
+	0x0305, 0x030d, 0x030e, 0x0310, 0x0312, 0x033d, 0x033e, 0x033f, 0x0346, 0x034a, 0x034b, 0x034c, 0x0350, 0x0351,
+	0x0352, 0x0357, 0x035b, 0x0363, 0x0364, 0x0365, 0x0366, 0x0367, 0x0368, 0x0369, 0x036a, 0x036b, 0x036c, 0x036d,
+	0x036e, 0x036f,
+].map(code => String.fromCodePoint(code));
+
+/** Largest image this module can address in cells. */
+export const SAYO_PLACEHOLDER_MAX_CELLS = DIACRITICS.length;
+
+export interface SayoPlaceholderImages {
+	columns: number;
+	rows: number;
+	/** Escape payload that uploads every pose and creates its virtual placement. */
+	upload: string;
+	/** Text row `row` of `pose`: placeholder cells colored with that pose's image id. */
+	line(pose: SayoPose, row: number): string;
+}
+
+function kittyChunks(control: string, base64: string): string {
+	const CHUNK = 4096;
+	let out = "";
+	for (let offset = 0, first = true; offset < base64.length || first; offset += CHUNK, first = false) {
+		const chunk = base64.slice(offset, offset + CHUNK);
+		const more = offset + CHUNK < base64.length ? 1 : 0;
+		out += first ? `\x1b_G${control},m=${more};${chunk}\x1b\\` : `\x1b_Gm=${more};${chunk}\x1b\\`;
+	}
+	return out;
+}
+
+/**
+ * Prepare `poses` of Sayo in `tint`, `rows` cells tall and square in pixels. Image ids
+ * are `idBase + index` and must fit in 24 bits (the id travels as an RGB color).
+ */
+export function prepareSayoPlaceholderImages(options: {
+	tint: SayoTint;
+	rows: number;
+	cellWidthPx: number;
+	cellHeightPx: number;
+	poses: readonly SayoPose[];
+	idBase: number;
+}): SayoPlaceholderImages {
+	const rows = Math.max(1, Math.min(SAYO_PLACEHOLDER_MAX_CELLS, Math.round(options.rows)));
+	const side = rows * options.cellHeightPx;
+	const columns = Math.max(1, Math.min(SAYO_PLACEHOLDER_MAX_CELLS, Math.round(side / options.cellWidthPx)));
+	const width = columns * options.cellWidthPx;
+	const height = rows * options.cellHeightPx;
+	const left = Math.max(0, Math.floor((width - side) / 2));
+	const ids = new Map<SayoPose, number>();
+	let upload = "";
+	for (const [index, pose] of options.poses.entries()) {
+		const id = (options.idBase + index) & 0xffffff;
+		ids.set(pose, id);
+		const sprite = renderSayoPose(pose, options.tint, Math.min(side, width));
+		const rgba = new Uint8Array(width * height * 4);
+		const top = height - sprite.height;
+		for (let y = 0; y < sprite.height; y++) {
+			rgba.set(
+				sprite.data.subarray(y * sprite.width * 4, (y + 1) * sprite.width * 4),
+				((y + top) * width + left) * 4,
+			);
+		}
+		const data = deflateSync(rgba).toString("base64");
+		upload += `\x1b_Ga=d,d=I,i=${id},q=2\x1b\\`;
+		upload += kittyChunks(`a=t,f=32,o=z,s=${width},v=${height},i=${id},q=2`, data);
+		upload += `\x1b_Ga=p,U=1,i=${id},c=${columns},r=${rows},q=2\x1b\\`;
+	}
+	const rowCache = new Map<string, string>();
+	return {
+		columns,
+		rows,
+		upload,
+		line(pose, row) {
+			const id = ids.get(pose) ?? ids.values().next().value ?? options.idBase;
+			const key = `${id}:${row}`;
+			let text = rowCache.get(key);
+			if (text === undefined) {
+				const color = `\x1b[38;2;${(id >> 16) & 255};${(id >> 8) & 255};${id & 255}m`;
+				let cells = "";
+				for (let column = 0; column < columns; column++)
+					cells += `${PLACEHOLDER}${DIACRITICS[row]}${DIACRITICS[column]}`;
+				text = `${color}${cells}\x1b[39m`;
+				rowCache.set(key, text);
+			}
+			return text;
+		},
+	};
+}