@patleeman/pi-boy 0.1.0

package/src/render/kitty.ts

@@ -0,0 +1,154 @@
+import { Buffer } from "node:buffer";
+import { allocateImageId, deleteKittyImage, getCellDimensions, renderImage, type TUI } from "@mariozechner/pi-tui";
+import pngjs from "pngjs";
+import {
+	GB_HEIGHT,
+	GB_WIDTH,
+	MAX_INTEGER_UPSCALE,
+	MIN_IMAGE_COLUMNS,
+	PNG_DEFLATE_LEVEL,
+	PNG_FILTER_TYPE,
+} from "../constants.js";
+
+const { PNG } = pngjs;
+type PngImage = InstanceType<typeof PNG>;
+
+export class KittyRenderer {
+	private imageId: number | undefined;
+	private cachedVersion = -1;
+	private cachedScale = -1;
+	private cachedBase64: string | null = null;
+	private previousRows = 0;
+
+	invalidate(): void {
+		this.cachedVersion = -1;
+	}
+
+	private computeIntegerScale(targetCols: number, targetRows: number): number {
+		const cell = getCellDimensions();
+		const cellWidthPx = Math.max(1, cell.widthPx);
+		const cellHeightPx = Math.max(1, cell.heightPx);
+		const maxWidthPx = Math.max(GB_WIDTH, Math.floor(targetCols * cellWidthPx));
+		const maxHeightPx = Math.max(GB_HEIGHT, Math.floor(targetRows * cellHeightPx));
+		const widthScale = Math.floor(maxWidthPx / GB_WIDTH);
+		const heightScale = Math.floor(maxHeightPx / GB_HEIGHT);
+		return Math.max(1, Math.min(MAX_INTEGER_UPSCALE, widthScale, heightScale));
+	}
+
+	private computeTargetColumns(width: number, maxRows: number): number {
+		const cell = getCellDimensions();
+		const cellWidthPx = Math.max(1, cell.widthPx);
+		const cellHeightPx = Math.max(1, cell.heightPx);
+		const colsByHeight = Math.floor((maxRows * GB_WIDTH * cellHeightPx) / (GB_HEIGHT * cellWidthPx));
+		return Math.max(1, Math.min(width, Math.max(MIN_IMAGE_COLUMNS, colsByHeight)));
+	}
+
+	private buildUpscaledPng(screen: ArrayLike<number>, scale: number): PngImage {
+		const width = GB_WIDTH * scale;
+		const height = GB_HEIGHT * scale;
+		const png = new PNG({ width, height });
+		const rowBuffer = Buffer.allocUnsafe(width * 4);
+
+		for (let y = 0; y < GB_HEIGHT; y++) {
+			const srcRowOffset = y * GB_WIDTH * 4;
+			let rowOffset = 0;
+
+			for (let x = 0; x < GB_WIDTH; x++) {
+				const srcOffset = srcRowOffset + x * 4;
+				const r = Number(screen[srcOffset] ?? 0);
+				const g = Number(screen[srcOffset + 1] ?? 0);
+				const b = Number(screen[srcOffset + 2] ?? 0);
+				for (let sx = 0; sx < scale; sx++) {
+					rowBuffer[rowOffset] = r;
+					rowBuffer[rowOffset + 1] = g;
+					rowBuffer[rowOffset + 2] = b;
+					rowBuffer[rowOffset + 3] = 255;
+					rowOffset += 4;
+				}
+			}
+
+			for (let sy = 0; sy < scale; sy++) {
+				rowBuffer.copy(png.data, (y * scale + sy) * width * 4);
+			}
+		}
+
+		return png;
+	}
+
+	private encodeFrame(screen: ArrayLike<number>, version: number, targetCols: number, targetRows: number) {
+		const scale = this.computeIntegerScale(targetCols, targetRows);
+		if (this.cachedVersion === version && this.cachedScale === scale && this.cachedBase64) {
+			return {
+				base64: this.cachedBase64,
+				widthPx: GB_WIDTH * scale,
+				heightPx: GB_HEIGHT * scale,
+				scale,
+			};
+		}
+
+		const png = this.buildUpscaledPng(screen, scale);
+		const buffer = PNG.sync.write(png, {
+			colorType: 6,
+			inputColorType: 6,
+			inputHasAlpha: true,
+			deflateLevel: PNG_DEFLATE_LEVEL,
+			filterType: PNG_FILTER_TYPE,
+		});
+
+		this.cachedBase64 = buffer.toString("base64");
+		this.cachedVersion = version;
+		this.cachedScale = scale;
+		return {
+			base64: this.cachedBase64,
+			widthPx: png.width,
+			heightPx: png.height,
+			scale,
+		};
+	}
+
+	render(screen: ArrayLike<number>, version: number, width: number, maxRows: number): { lines: string[]; scale: number } | null {
+		const targetCols = this.computeTargetColumns(width, maxRows);
+		const encoded = this.encodeFrame(screen, version, targetCols, maxRows);
+		if (!this.imageId) {
+			this.imageId = allocateImageId();
+		}
+
+		const result = renderImage(
+			encoded.base64,
+			{ widthPx: encoded.widthPx, heightPx: encoded.heightPx },
+			{
+				maxWidthCells: targetCols,
+				maxHeightCells: maxRows,
+				imageId: this.imageId,
+			},
+		);
+		if (!result) return null;
+		if (result.imageId) {
+			this.imageId = result.imageId;
+		}
+
+		const reserveRows = Math.max(result.rows, this.previousRows);
+		this.previousRows = result.rows;
+		const leftPadCols = Math.max(0, Math.floor((width - targetCols) / 2));
+		const moveToColumn = leftPadCols > 0 ? `\x1b[${leftPadCols + 1}G` : "";
+		const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
+
+		const lines: string[] = [];
+		for (let i = 0; i < result.rows - 1; i++) lines.push("");
+		lines.push(moveUp + moveToColumn + result.sequence);
+		for (let i = result.rows; i < reserveRows; i++) lines.push(" ".repeat(width));
+		return { lines, scale: encoded.scale };
+	}
+
+	dispose(tui: TUI): void {
+		if (this.imageId) {
+			try {
+				tui.terminal?.write(deleteKittyImage(this.imageId));
+			} catch {
+				// ignore
+			}
+			this.imageId = undefined;
+		}
+		this.previousRows = 0;
+	}
+}

package/src/roms.ts

@@ -0,0 +1,163 @@
+import { readdirSync } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+import { resolveInputPath } from "./config.js";
+
+const ROM_EXTENSIONS = new Set([".gb", ".gbc"]);
+const DEFAULT_ROM_SCAN_LIMIT = 500;
+
+export function isRomFilePath(filePath: string): boolean {
+	return ROM_EXTENSIONS.has(extname(filePath).toLowerCase());
+}
+
+function stripWrappingQuotes(value: string): string {
+	const trimmed = value.trim();
+	if (trimmed.length < 2) return trimmed;
+	const first = trimmed[0];
+	const last = trimmed[trimmed.length - 1];
+	if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+		return trimmed.slice(1, -1);
+	}
+	return trimmed;
+}
+
+function quoteIfNeeded(value: string): string {
+	return /\s/.test(value) ? JSON.stringify(value) : value;
+}
+
+export function listRomFiles(romDirectory: string, maxResults = DEFAULT_ROM_SCAN_LIMIT): string[] {
+	const root = resolveInputPath(romDirectory, process.cwd());
+	const files: string[] = [];
+	const stack = [root];
+
+	while (stack.length > 0) {
+		const dirPath = stack.pop();
+		if (!dirPath) continue;
+
+		let entries;
+		try {
+			entries = readdirSync(dirPath, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+
+		entries.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+
+		for (const entry of entries) {
+			const fullPath = join(dirPath, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(fullPath);
+				continue;
+			}
+
+			if (!entry.isFile() || !isRomFilePath(fullPath)) continue;
+			files.push(fullPath);
+			if (files.length >= maxResults) {
+				return files.sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
+			}
+		}
+	}
+
+	return files.sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
+}
+
+function collectDirectoryCompletions(searchDir: string, namePrefix: string, maxResults: number): AutocompleteItem[] {
+	let entries;
+	try {
+		entries = readdirSync(searchDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	const lowerPrefix = namePrefix.toLowerCase();
+	const completions: AutocompleteItem[] = [];
+
+	entries.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+	for (const entry of entries) {
+		if (!entry.name.toLowerCase().startsWith(lowerPrefix)) continue;
+		const fullPath = join(searchDir, entry.name);
+		if (entry.isDirectory()) {
+			completions.push({ value: quoteIfNeeded(`${fullPath}/`), label: `${entry.name}/` });
+		} else if (entry.isFile() && isRomFilePath(fullPath)) {
+			completions.push({ value: quoteIfNeeded(fullPath), label: entry.name });
+		}
+
+		if (completions.length >= maxResults) break;
+	}
+
+	return completions;
+}
+
+function splitPathPrefix(prefix: string): { basePath: string; namePrefix: string } {
+	if (prefix.endsWith("/")) {
+		return { basePath: prefix, namePrefix: "" };
+	}
+
+	const slash = prefix.lastIndexOf("/");
+	if (slash < 0) {
+		return { basePath: ".", namePrefix: prefix };
+	}
+
+	return {
+		basePath: slash === 0 ? "/" : prefix.slice(0, slash),
+		namePrefix: prefix.slice(slash + 1),
+	};
+}
+
+export function getRomPathCompletions(
+	argumentPrefix: string,
+	cwd: string,
+	romDirectory?: string,
+	maxResults = 50,
+): AutocompleteItem[] | null {
+	const strippedPrefix = stripWrappingQuotes(argumentPrefix);
+	const normalizedPrefix = strippedPrefix.trim();
+	const seen = new Map<string, AutocompleteItem>();
+
+	const add = (item: AutocompleteItem): void => {
+		if (seen.has(item.value) || seen.size >= maxResults) return;
+		seen.set(item.value, item);
+	};
+
+	const resolvedRomDirectory = romDirectory ? resolveInputPath(romDirectory, cwd) : undefined;
+
+	if (normalizedPrefix.length === 0) {
+		if (resolvedRomDirectory) {
+			for (const romPath of listRomFiles(resolvedRomDirectory, maxResults)) {
+				const rel = relative(resolvedRomDirectory, romPath);
+				add({ value: quoteIfNeeded(romPath), label: rel });
+			}
+		}
+
+		if (seen.size === 0) {
+			for (const item of collectDirectoryCompletions(cwd, "", maxResults)) add(item);
+		}
+
+		return seen.size > 0 ? [...seen.values()] : null;
+	}
+
+	const isPathPrefix =
+		normalizedPrefix.includes("/") || normalizedPrefix.startsWith("~") || normalizedPrefix.startsWith(".");
+
+	if (isPathPrefix) {
+		const { basePath, namePrefix } = splitPathPrefix(normalizedPrefix);
+		const searchDir = resolveInputPath(basePath, cwd);
+		for (const item of collectDirectoryCompletions(searchDir, namePrefix, maxResults)) add(item);
+		return seen.size > 0 ? [...seen.values()] : null;
+	}
+
+	const lowerPrefix = normalizedPrefix.toLowerCase();
+	if (resolvedRomDirectory) {
+		for (const romPath of listRomFiles(resolvedRomDirectory, maxResults * 4)) {
+			const rel = relative(resolvedRomDirectory, romPath);
+			const relLower = rel.toLowerCase();
+			const nameLower = basename(romPath).toLowerCase();
+			if (!relLower.startsWith(lowerPrefix) && !nameLower.startsWith(lowerPrefix)) continue;
+			add({ value: quoteIfNeeded(romPath), label: rel });
+			if (seen.size >= maxResults) break;
+		}
+	}
+
+	for (const item of collectDirectoryCompletions(cwd, normalizedPrefix, maxResults)) add(item);
+	return seen.size > 0 ? [...seen.values()] : null;
+}

package/src/runtime.ts

@@ -0,0 +1,36 @@
+export type RenderBackend = "kitty" | "ansi";
+export type AnsiBlockMode = "half" | "quarter";
+export type AudioBackendPreference = "auto" | "speaker" | "ffplay";
+
+export interface RuntimeOptions {
+	forceAnsi: boolean;
+	forceOverlay: boolean;
+	audioBackendPreference: AudioBackendPreference;
+	ansiBlockMode: AnsiBlockMode;
+	romPathFromEnv?: string;
+}
+
+function isTruthy(value: string | undefined): boolean {
+	if (!value) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+function parseAudioBackendPreference(value: string | undefined): AudioBackendPreference {
+	if (value === "speaker" || value === "ffplay") return value;
+	return "auto";
+}
+
+function parseAnsiBlockMode(value: string | undefined): AnsiBlockMode {
+	return value?.trim().toLowerCase() === "quarter" ? "quarter" : "half";
+}
+
+export function loadRuntimeOptions(env: NodeJS.ProcessEnv = process.env): RuntimeOptions {
+	return {
+		forceAnsi: isTruthy(env.PI_BOY_FORCE_ANSI),
+		forceOverlay: isTruthy(env.PI_BOY_FORCE_OVERLAY),
+		audioBackendPreference: parseAudioBackendPreference(env.PI_BOY_AUDIO_BACKEND),
+		ansiBlockMode: parseAnsiBlockMode(env.PI_BOY_ANSI_BLOCK_MODE),
+		romPathFromEnv: env.PI_BOY_ROM_PATH,
+	};
+}

package/src/save-state.ts

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { SAVE_STATE_DIR } from "./constants.js";
+
+const SAVE_STATE_EXT = ".state";
+
+export interface SaveStateEntry {
+	name: string;
+	path: string;
+	sizeBytes: number;
+	modifiedMs: number;
+}
+
+function sanitizeFilenamePart(value: string): string {
+	const normalized = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+	return normalized.replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+
+function getRomStateBasename(romPath: string): string {
+	const base = basename(romPath, extname(romPath));
+	const safeBase = sanitizeFilenamePart(base) || "rom";
+	const digest = createHash("sha1").update(romPath).digest("hex").slice(0, 12);
+	return `${safeBase}-${digest}${SAVE_STATE_EXT}`;
+}
+
+export function getSaveStatePath(romPath: string): string {
+	return join(SAVE_STATE_DIR, getRomStateBasename(romPath));
+}
+
+export function loadSaveState(romPath: string): Buffer | null {
+	const statePath = getSaveStatePath(romPath);
+	if (!existsSync(statePath)) return null;
+	try {
+		const data = readFileSync(statePath);
+		return data.length > 0 ? data : null;
+	} catch {
+		return null;
+	}
+}
+
+export function writeSaveState(romPath: string, state: Buffer): string {
+	const statePath = getSaveStatePath(romPath);
+	mkdirSync(SAVE_STATE_DIR, { recursive: true });
+	writeFileSync(statePath, state);
+	return statePath;
+}
+
+export function removeSaveState(romPath: string): boolean {
+	const statePath = getSaveStatePath(romPath);
+	return removeSaveStateByPath(statePath);
+}
+
+export function removeSaveStateByPath(statePath: string): boolean {
+	if (!existsSync(statePath)) return false;
+	try {
+		unlinkSync(statePath);
+		return !existsSync(statePath);
+	} catch {
+		return false;
+	}
+}
+
+export function listSaveStates(): SaveStateEntry[] {
+	if (!existsSync(SAVE_STATE_DIR)) return [];
+
+	let entries: string[] = [];
+	try {
+		entries = readdirSync(SAVE_STATE_DIR);
+	} catch {
+		return [];
+	}
+
+	const states: SaveStateEntry[] = [];
+	for (const name of entries) {
+		if (!name.endsWith(SAVE_STATE_EXT)) continue;
+		const path = join(SAVE_STATE_DIR, name);
+		try {
+			const stat = statSync(path);
+			if (!stat.isFile()) continue;
+			states.push({
+				name,
+				path,
+				sizeBytes: stat.size,
+				modifiedMs: stat.mtimeMs,
+			});
+		} catch {
+			// skip unreadable entries
+		}
+	}
+
+	states.sort((a, b) => b.modifiedMs - a.modifiedMs);
+	return states;
+}

package/src/terminal.ts

@@ -0,0 +1,18 @@
+import { getCapabilities, type TUI } from "@mariozechner/pi-tui";
+import type { RenderBackend, RuntimeOptions } from "./runtime.js";
+
+export function isITermSession(env: NodeJS.ProcessEnv = process.env): boolean {
+	const termProgram = (env.TERM_PROGRAM ?? "").toLowerCase();
+	const lcTerminal = (env.LC_TERMINAL ?? "").toLowerCase();
+	return Boolean(env.ITERM_SESSION_ID) || termProgram === "iterm.app" || lcTerminal === "iterm2";
+}
+
+export function getRenderBackend(options: RuntimeOptions): RenderBackend {
+	if (options.forceAnsi) return "ansi";
+	if (isITermSession()) return "ansi";
+	return getCapabilities().images === "kitty" ? "kitty" : "ansi";
+}
+
+export function supportsHeldKeys(tui: TUI): boolean {
+	return Boolean(tui.terminal?.kittyProtocolActive);
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["index.ts", "src/**/*.ts", "types/**/*.d.ts"]
+}

package/types/shims.d.ts

@@ -0,0 +1,121 @@
+declare module "@mariozechner/pi-coding-agent" {
+	export type NotifyLevel = "info" | "warning" | "error";
+
+	type DialogOptions = {
+		timeout?: number;
+		signal?: AbortSignal;
+	};
+
+	export interface CommandContext {
+		hasUI: boolean;
+		cwd: string;
+		ui: {
+			notify: (message: string, level: NotifyLevel) => void;
+			select: (title: string, options: string[], opts?: DialogOptions) => Promise<string | undefined>;
+			confirm: (title: string, message: string, opts?: DialogOptions) => Promise<boolean>;
+			input: (title: string, initialValue?: string, opts?: DialogOptions) => Promise<string | undefined>;
+			custom: <T>(
+				factory: (
+					tui: import("@mariozechner/pi-tui").TUI,
+					theme: unknown,
+					keybindings: unknown,
+					done: (value: T) => void,
+				) => unknown,
+				options?: {
+					overlay?: boolean;
+					overlayOptions?: {
+						width?: string;
+						maxHeight?: string;
+						anchor?: string;
+						margin?: number;
+					};
+				},
+			) => Promise<T>;
+		};
+	}
+
+	export interface ExtensionAPI {
+		on: (
+			event: "session_start",
+			handler: (event: unknown, ctx: CommandContext) => void | Promise<void>,
+		) => void;
+		registerCommand: (
+			name: string,
+			definition: {
+				description: string;
+				getArgumentCompletions?: (
+					argumentPrefix: string,
+				) => import("@mariozechner/pi-tui").AutocompleteItem[] | null;
+				handler: (args: string, ctx: CommandContext) => void | Promise<void>;
+			},
+		) => void;
+	}
+}
+
+declare module "@mariozechner/pi-tui" {
+	export type AutocompleteItem = {
+		value: string;
+		label?: string;
+	};
+
+	export const Key: {
+		left: string;
+		right: string;
+		up: string;
+		down: string;
+		enter: string;
+		tab: string;
+		backspace: string;
+		escape: string;
+		space: string;
+		shift: (key: string) => string;
+	};
+
+	export function matchesKey(data: string, key: string): boolean;
+	export function isKeyRelease(data: string): boolean;
+	export function visibleWidth(text: string): number;
+	export function truncateToWidth(text: string, width: number, ellipsis?: string, preferEnd?: boolean): string;
+	export function getCapabilities(): { images?: "kitty" | "iterm2" };
+	export function getCellDimensions(): { widthPx: number; heightPx: number };
+	export function renderImage(
+		base64: string,
+		size: { widthPx: number; heightPx: number },
+		options: { maxWidthCells: number; maxHeightCells: number; imageId?: number },
+	): { sequence: string; rows: number; imageId?: number } | null;
+	export function allocateImageId(): number;
+	export function deleteKittyImage(id: number): string;
+
+	export interface TUI {
+		terminal?: {
+			rows: number;
+			kittyProtocolActive?: boolean;
+			write: (data: string) => void;
+		};
+		requestRender: (full?: boolean) => void;
+		getClearOnShrink: () => boolean;
+		setClearOnShrink: (value: boolean) => void;
+	}
+}
+
+declare module "pngjs" {
+	export interface PngWriteOptions {
+		colorType?: number;
+		inputHasAlpha?: boolean;
+		inputColorType?: number;
+		deflateLevel?: number;
+		filterType?: number;
+	}
+
+	export class PNG {
+		constructor(options: { width: number; height: number });
+		data: Buffer;
+		width: number;
+		height: number;
+		static sync: {
+			write: (png: PNG, options?: PngWriteOptions) => Buffer;
+		};
+	}
+
+	const pngjs: { PNG: typeof PNG };
+	export default pngjs;
+}