@patleeman/pi-boy 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patleeman/pi-boy",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "pi-boy: embedded Game Boy emulator inside pi",
   "license": "MIT",

package/src/constants.ts

@@ -9,6 +9,9 @@ export const GB_HEIGHT = 144;
 
 export const EMULATOR_FRAME_MS = 1000 / 60;
 export const MAX_CATCHUP_STEPS = 64;
+export const MAX_TIMER_DELTA_MS = 250;
+// Treat long timer gaps like a temporary pause (e.g. app backgrounded / terminal stalled).
+export const BACKGROUND_STALL_MS = 200;
 
 export const IMAGE_RENDER_FPS = 30;
 export const ANSI_RENDER_FPS = 30;

package/src/extension.ts

@@ -6,7 +6,7 @@ import { type PiBoyConfig, loadConfig, pickRomPath, resolveInputPath, resolveRom
 import { runSelfTest } from "./gameboy.js";
 import { notify } from "./notify.js";
 import { PiBoyComponent, type PiBoyExitResult } from "./pi-boy-component.js";
-import { type RuntimeOptions, loadRuntimeOptions } from "./runtime.js";
+import { type RuntimeOptions, getLaunchRuntimeOptions, loadRuntimeOptions } from "./runtime.js";
 import { getRomPathCompletions, isRomFilePath, listRomFiles } from "./roms.js";
 import {
 	getSaveStatePath,
@@ -530,20 +530,23 @@ export default function (pi: ExtensionAPI) {
 
 			const config = loadConfig();
 			const runtimeOptions = getEffectiveRuntimeOptions(config);
+			const launchOptions = getLaunchRuntimeOptions(runtimeOptions, ctx.isIdle());
 			const resumeState = loadSaveState(romResult.romPath);
 			if (resumeState) {
 				notify(ctx, "pi-boy: found suspended state, attempting resume.", "info");
 			}
 
-			if (!runtimeOptions.forceOverlay) {
+			if (!runtimeOptions.forceOverlay && launchOptions.forceOverlay) {
+				notify(ctx, "pi-boy: agent is busy, using overlay mode for stable rendering.", "info");
+			} else if (!launchOptions.forceOverlay) {
 				notify(ctx, "pi-boy: inline mode enabled.", "info");
 			}
 
 			try {
 				const exitResult = await ctx.ui.custom<PiBoyExitResult | undefined>(
 					(tui, _theme, _keybindings, done) =>
-						new PiBoyComponent(tui, romResult.rom, (result) => done(result), runtimeOptions, resumeState ?? undefined),
-					runtimeOptions.forceOverlay
+						new PiBoyComponent(tui, romResult.rom, (result) => done(result), launchOptions, resumeState ?? undefined),
+					launchOptions.forceOverlay
 						? {
 								overlay: true,
 								overlayOptions: {

package/src/game-loop.ts

@@ -0,0 +1,71 @@
+import {
+	ANSI_RENDER_FPS,
+	BACKGROUND_STALL_MS,
+	EMULATOR_FRAME_MS,
+	IMAGE_RENDER_FPS,
+	MAX_CATCHUP_STEPS,
+	MAX_TIMER_DELTA_MS,
+} from "./constants.js";
+import type { RenderBackend } from "./runtime.js";
+
+export interface GameLoopState {
+	frameAccumulatorMs: number;
+	renderAccumulatorMs: number;
+	pausedForStall: boolean;
+}
+
+export interface GameLoopAdvanceResult {
+	frameAccumulatorMs: number;
+	renderAccumulatorMs: number;
+	emulatorSteps: number;
+	shouldRender: boolean;
+	pausedForStall: boolean;
+	enteredStall: boolean;
+	resumedFromStall: boolean;
+}
+
+export function advanceGameLoop(state: GameLoopState, rawDeltaMs: number, renderBackend: RenderBackend): GameLoopAdvanceResult {
+	const deltaMs = Number.isFinite(rawDeltaMs) && rawDeltaMs > 0 ? rawDeltaMs : 0;
+	if (deltaMs >= BACKGROUND_STALL_MS) {
+		// Once timers stretch this far, smooth catch-up usually looks worse than
+		// pausing the loop and forcing a clean redraw when normal cadence returns.
+		return {
+			frameAccumulatorMs: 0,
+			renderAccumulatorMs: 0,
+			emulatorSteps: 0,
+			shouldRender: false,
+			pausedForStall: true,
+			enteredStall: !state.pausedForStall,
+			resumedFromStall: false,
+		};
+	}
+
+	let frameAccumulatorMs = state.frameAccumulatorMs + Math.min(MAX_TIMER_DELTA_MS, deltaMs);
+	let renderAccumulatorMs = state.renderAccumulatorMs + Math.min(MAX_TIMER_DELTA_MS, deltaMs);
+	let emulatorSteps = 0;
+
+	while (frameAccumulatorMs >= EMULATOR_FRAME_MS && emulatorSteps < MAX_CATCHUP_STEPS) {
+		frameAccumulatorMs -= EMULATOR_FRAME_MS;
+		emulatorSteps++;
+	}
+
+	if (emulatorSteps === MAX_CATCHUP_STEPS) {
+		frameAccumulatorMs = 0;
+	}
+
+	const renderFrameMs = 1000 / (renderBackend === "ansi" ? ANSI_RENDER_FPS : IMAGE_RENDER_FPS);
+	const shouldRender = renderAccumulatorMs >= renderFrameMs;
+	if (shouldRender) {
+		renderAccumulatorMs %= renderFrameMs;
+	}
+
+	return {
+		frameAccumulatorMs,
+		renderAccumulatorMs,
+		emulatorSteps,
+		shouldRender,
+		pausedForStall: false,
+		enteredStall: false,
+		resumedFromStall: state.pausedForStall,
+	};
+}

package/src/pi-boy-component.ts

@@ -2,18 +2,15 @@ import { isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth, type TUI
 import {
 	ANSI_MAX_COLUMNS,
 	ANSI_MAX_ROWS,
-	ANSI_RENDER_FPS,
-	EMULATOR_FRAME_MS,
 	GB_HEIGHT,
 	GB_WIDTH,
-	IMAGE_RENDER_FPS,
-	MAX_CATCHUP_STEPS,
 	TAP_FRAMES_ACTION,
 	TAP_FRAMES_DIRECTION,
 	VIEWPORT_SAFETY_ROWS,
 } from "./constants.js";
 import { AudioOutput } from "./audio-output.js";
 import { KEYMAP, type GameboyInstance, type GameboyKey, createGameboy } from "./gameboy.js";
+import { advanceGameLoop } from "./game-loop.js";
 import { renderAnsiFrame } from "./render/ansi.js";
 import { KittyRenderer } from "./render/kitty.js";
 import { getRenderBackend, supportsHeldKeys } from "./terminal.js";
@@ -47,6 +44,7 @@ export class PiBoyComponent {
 	private version = 0;
 	private frameAccumulatorMs = 0;
 	private renderAccumulatorMs = 0;
+	private pausedForStall = false;
 	private lastTickMs = performance.now();
 	private previousClearOnShrink: boolean | null = null;
 	private cachedWidth = 0;
@@ -86,39 +84,50 @@ export class PiBoyComponent {
 			if (this.coreError) return;
 
 			const now = performance.now();
-			const deltaMs = Math.min(250, now - this.lastTickMs);
+			const renderBackend = getRenderBackend(this.options);
+			const loopState = advanceGameLoop(
+				{
+					frameAccumulatorMs: this.frameAccumulatorMs,
+					renderAccumulatorMs: this.renderAccumulatorMs,
+					pausedForStall: this.pausedForStall,
+				},
+				now - this.lastTickMs,
+				renderBackend,
+			);
 			this.lastTickMs = now;
-			this.frameAccumulatorMs += deltaMs;
-			this.renderAccumulatorMs += deltaMs;
+			this.frameAccumulatorMs = loopState.frameAccumulatorMs;
+			this.renderAccumulatorMs = loopState.renderAccumulatorMs;
+			this.pausedForStall = loopState.pausedForStall;
+
+			if (loopState.enteredStall) {
+				this.kittyRenderer.reset();
+				this.invalidate();
+				return;
+			}
 
-			let stepsRun = 0;
-			while (this.frameAccumulatorMs >= EMULATOR_FRAME_MS && stepsRun < MAX_CATCHUP_STEPS) {
+			if (loopState.resumedFromStall) {
+				this.invalidate();
+				this.requestRender(true);
+			}
+
+			for (let step = 0; step < loopState.emulatorSteps; step++) {
 				try {
 					this.runEmulatorStep();
 				} catch (error) {
 					this.failCore(error);
 					return;
 				}
-				this.frameAccumulatorMs -= EMULATOR_FRAME_MS;
-				stepsRun++;
 			}
 
-			if (stepsRun === MAX_CATCHUP_STEPS) {
-				this.frameAccumulatorMs = 0;
-			}
-
-			const renderBackend = getRenderBackend(this.options);
-			const renderFrameMs = 1000 / (renderBackend === "ansi" ? ANSI_RENDER_FPS : IMAGE_RENDER_FPS);
-			if (this.renderAccumulatorMs >= renderFrameMs) {
-				this.renderAccumulatorMs %= renderFrameMs;
+			if (loopState.shouldRender && !loopState.resumedFromStall) {
 				this.requestRender();
 			}
 		}, 8);
 	}
 
-	private requestRender(): void {
+	private requestRender(force = false): void {
 		this.version++;
-		this.tui.requestRender();
+		this.tui.requestRender(force);
 	}
 
 	private failCore(error: unknown): void {

package/src/render/kitty.ts

@@ -24,6 +24,14 @@ export class KittyRenderer {
 		this.cachedVersion = -1;
 	}
 
+	reset(): void {
+		this.imageId = undefined;
+		this.cachedVersion = -1;
+		this.cachedScale = -1;
+		this.cachedBase64 = null;
+		this.previousRows = 0;
+	}
+
 	private computeIntegerScale(targetCols: number, targetRows: number): number {
 		const cell = getCellDimensions();
 		const cellWidthPx = Math.max(1, cell.widthPx);
@@ -147,8 +155,7 @@ export class KittyRenderer {
 			} catch {
 				// ignore
 			}
-			this.imageId = undefined;
 		}
-		this.previousRows = 0;
+		this.reset();
 	}
 }

package/src/runtime.ts

@@ -34,3 +34,13 @@ export function loadRuntimeOptions(env: NodeJS.ProcessEnv = process.env): Runtim
 		romPathFromEnv: env.PI_BOY_ROM_PATH,
 	};
 }
+
+export function getLaunchRuntimeOptions(options: RuntimeOptions, agentIsIdle: boolean): RuntimeOptions {
+	if (agentIsIdle || options.forceOverlay) {
+		return options;
+	}
+	return {
+		...options,
+		forceOverlay: true,
+	};
+}

package/types/shims.d.ts

@@ -9,6 +9,7 @@ declare module "@mariozechner/pi-coding-agent" {
 	export interface CommandContext {
 		hasUI: boolean;
 		cwd: string;
+		isIdle: () => boolean;
 		ui: {
 			notify: (message: string, level: NotifyLevel) => void;
 			select: (title: string, options: string[], opts?: DialogOptions) => Promise<string | undefined>;