picopilot 0.1.4 → 0.1.5

package/src/commands/label-cart.ts

@@ -0,0 +1,304 @@
+import {
+	existsSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {Cart, CartParseError} from '../engine/cart/index.js';
+import {labelHexFromPng, LabelError} from '../engine/gfx/index.js';
+import {
+	buildDriveHarness,
+	DriveError,
+	type DriveOptions,
+	type Pico8DriveResult,
+} from '../engine/pico8/index.js';
+import {makeReadInclude} from './cart-includes.js';
+
+/**
+ * The remedy for both label-image errors (`label-wrong-size`,
+ * `label-unsupported-png`): the screenshot `run`/`playtest` already wrote is a
+ * valid label as-is, so point at that rather than at an external image tool.
+ */
+export const LABEL_FIX_CTA = {
+	description:
+		'Pass a picopilot screenshot directly; it is scaled for you (any 128*k square: 128x128, 256x256, 384x384, ...). No image tool needed:',
+	commands: [
+		{
+			command: 'run <cart> --shot-dir shots',
+			description:
+				'Capture a frame (the cart calls extcmd("screen")), then pass shots/<name>.png to --label unchanged.',
+		},
+		{
+			command: 'export <cart> <dest> --label shots/<name>.png',
+			description:
+				'Bake that screenshot in as the label splash (`serve --label` takes it the same way). playtest screenshots work too.',
+		},
+	],
+};
+
+/** Where the exported cart's `__label__` came from. */
+export type LabelSource = 'cart' | 'image' | 'frame' | 'none';
+
+/** A cart ready to hand to PICO-8's export, plus how to tidy up after it. */
+export interface LabeledCart {
+	readonly ok: true;
+	/** The cart to export: the original, or a labeled throwaway copy. */
+	readonly cartPath: string;
+	/**
+	 * Where the label comes from: the cart's own (`cart`), `--label` (`image`),
+	 * `--label-frame` (`frame`), or nowhere (`none`, the cart stays labelless).
+	 */
+	readonly labelSource: LabelSource;
+	/** Removes the throwaway copy (if one was made). Best-effort, idempotent. */
+	readonly cleanup: () => void;
+}
+
+/** A label-preparation failure, shaped for incur's `error({...})`. */
+export interface LabelCartFailure {
+	readonly ok: false;
+	readonly code: string;
+	readonly message: string;
+	readonly cta?: {
+		description: string;
+		commands: {command: string; description: string}[];
+	};
+}
+
+/** The label flags `export` and `serve` share. */
+export interface LabelOptions {
+	/** `--label <png>`: an image (a run/playtest screenshot as-is, or 128x128). */
+	readonly label?: string;
+	/** `--label-frame <n>`: capture frame `n` of the running cart, no input. */
+	readonly labelFrame?: number;
+	/** The backstop for the `--label-frame` capture run. */
+	readonly backstopMs: number;
+}
+
+/** The base filename the `--label-frame` capture names its screenshot. */
+const LABEL_FRAME_BASENAME = 'label';
+
+/**
+ * The `--label` / `--label-frame` step shared by `export` and `serve` (ADR-0013,
+ * ADR-0015, ADR-0016): give a labelless cart a `__label__` (the export splash)
+ * without an interactive F7 capture.
+ *
+ *  - `--label <png>`: decode an image (a `run`/`playtest` screenshot as-is, any
+ *    square integer multiple of 128x128, or any 128x128 PNG).
+ *  - `--label-frame <n>`: RUN the cart headlessly through the playtest drive
+ *    harness (ADR-0011) with NO input, advance `n` frames, screenshot that frame,
+ *    and decode it. Needs PICO-8 (`drive`); an arbitrary cart does not have to
+ *    cooperate, since the harness owns its frame loop.
+ *
+ * The two flags are mutually exclusive (`label-flags-conflict`). The user's cart
+ * is NEVER mutated: a labeled copy is written NEXT TO it (same dir, so
+ * `#include main.lua` still resolves) and the caller exports that, then calls
+ * `cleanup()`. A cart that ALREADY has a label wins (the flags are a fallback,
+ * not an override): it is returned untouched and nothing is run.
+ *
+ * @param drive the adapter's `drive`, only called for `--label-frame`.
+ */
+export async function prepareLabeledCart(
+	cartPath: string,
+	options: LabelOptions,
+	drive: (options: DriveOptions) => Promise<Pico8DriveResult>,
+): Promise<LabeledCart | LabelCartFailure> {
+	const keep = (labelSource: LabelSource): LabeledCart => ({
+		ok: true,
+		cartPath,
+		labelSource,
+		cleanup: () => {},
+	});
+
+	if (options.label !== undefined && options.labelFrame !== undefined) {
+		return {
+			ok: false,
+			code: 'label-flags-conflict',
+			message:
+				'pass either --label <png> (an image) or --label-frame <n> (capture a frame of the running cart), not both',
+		};
+	}
+
+	// With no label flag the cart is only read to REPORT `labelSource`; anything
+	// odd about it (unreadable, unparseable) is left for PICO-8 to judge, exactly
+	// as before the label flags existed.
+	const noFlag =
+		options.label === undefined && options.labelFrame === undefined;
+	let cart: Cart;
+	try {
+		cart = Cart.parse(readFileSync(cartPath, 'utf8'));
+	} catch (e) {
+		if (noFlag) return keep('none');
+		if (e instanceof CartParseError) {
+			return {
+				ok: false,
+				code: `cart-${e.code}`,
+				message: `could not parse the cart to inject a label: ${e.message}`,
+			};
+		}
+		throw e;
+	}
+
+	const existingLabel = cart.getSection('label');
+	if (existingLabel !== undefined && existingLabel.trim() !== '') {
+		return keep('cart');
+	}
+
+	let png: Uint8Array;
+	let labelSource: LabelSource;
+	if (options.label !== undefined) {
+		const labelPath = isAbsolute(options.label)
+			? options.label
+			: resolve(process.cwd(), options.label);
+		if (!existsSync(labelPath)) {
+			return {
+				ok: false,
+				code: 'label-not-found',
+				message: `no label image at ${labelPath}`,
+			};
+		}
+		png = readFileSync(labelPath);
+		labelSource = 'image';
+	} else if (options.labelFrame !== undefined) {
+		const captured = await captureFrame(
+			cartPath,
+			options.labelFrame,
+			options.backstopMs,
+			drive,
+		);
+		if (!captured.ok) return captured;
+		png = captured.png;
+		labelSource = 'frame';
+	} else {
+		return keep('none');
+	}
+
+	let hex: string;
+	try {
+		hex = labelHexFromPng(png);
+	} catch (e) {
+		if (e instanceof LabelError) {
+			return {
+				ok: false,
+				code: `label-${e.code}`,
+				message: e.message,
+				cta: LABEL_FIX_CTA,
+			};
+		}
+		throw e;
+	}
+
+	cart.setSection('label', hex);
+	const copy = join(
+		dirname(cartPath),
+		`.picopilot-export-${process.pid}-${Date.now()}.p8`,
+	);
+	writeFileSync(copy, cart.serialize());
+	return {
+		ok: true,
+		cartPath: copy,
+		labelSource,
+		cleanup: () => {
+			try {
+				rmSync(copy, {force: true});
+			} catch {
+				// A leftover dotfile is not fatal.
+			}
+		},
+	};
+}
+
+/**
+ * Runs the cart through the playtest drive harness with NO input for `frame + 1`
+ * frames, screenshotting after frame `frame` (0 = the first drawn frame), and
+ * returns that PNG. The driven cart and PICO-8's screenshot dir live in a temp
+ * dir that is removed before returning.
+ */
+async function captureFrame(
+	cartPath: string,
+	frame: number,
+	backstopMs: number,
+	drive: (options: DriveOptions) => Promise<Pico8DriveResult>,
+): Promise<{ok: true; png: Uint8Array} | LabelCartFailure> {
+	let harness;
+	try {
+		harness = buildDriveHarness(readFileSync(cartPath, 'utf8'), {
+			presses: [],
+			frames: frame + 1,
+			shotFrames: [frame],
+			shotBasename: LABEL_FRAME_BASENAME,
+			readInclude: makeReadInclude(cartPath),
+		});
+	} catch (e) {
+		if (e instanceof DriveError) {
+			return {ok: false, code: e.code, message: e.message};
+		}
+		throw e;
+	}
+
+	const shotDir = mkdtempSync(join(tmpdir(), 'picopilot-label-frame-'));
+	try {
+		const drivenCart = join(shotDir, 'driven.p8');
+		writeFileSync(drivenCart, harness.cartText);
+		const result = await drive({
+			cartPath: drivenCart,
+			shotDir,
+			blocks: harness.blocks,
+			backstopMs,
+		});
+		if (!result.ok) {
+			return {
+				ok: false,
+				code: result.reason,
+				message: `PICO-8 is not installed, so --label-frame cannot capture a frame. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+			};
+		}
+		const shot = result.value.screenshots[0];
+		if (shot === undefined) {
+			const {exitReason} = result.value;
+			const tail = result.value.printh.trim().split('\n').slice(-5).join('\n');
+			const commands = [
+				{
+					command: 'verify',
+					description: 'Run the static gate (tokens + lint + integrity).',
+				},
+				{
+					command: 'playtest start <cart>',
+					description:
+						'Reproduce the SAME no-input frame to look at it: start a paused session (nothing held), then step and shoot.',
+				},
+				{
+					command: `playtest step <id> --frames ${frame + 1}`,
+					description: `Advance to frame ${frame}, as --label-frame ${frame} does.`,
+				},
+				{
+					command: 'playtest shot <id>',
+					description:
+						'Screenshot it; if it looks right, pass that PNG with --label <png> (then `playtest stop <id>`).',
+				},
+			];
+			if (exitReason === 'timeout') {
+				commands.push({
+					command: `export <cart> --label-frame ${frame} --backstop-ms <more>`,
+					description:
+						'The capture hit the backstop (it runs about one frame per PICO-8 tick): allow more time, or pick an earlier frame.',
+				});
+			}
+			return {
+				ok: false,
+				code: 'label-frame-not-captured',
+				message: `the cart produced no frame ${frame} screenshot (exit: ${exitReason}).${tail === '' ? '' : ` Last output:\n${tail}`}`,
+				cta: {
+					description:
+						'The cart did not reach that frame. Check it boots, or look at the frame first:',
+					commands,
+				},
+			};
+		}
+		return {ok: true, png: readFileSync(shot)};
+	} finally {
+		rmSync(shotDir, {recursive: true, force: true});
+	}
+}

package/src/commands/lint.test.ts

@@ -34,6 +34,12 @@ afterEach(() => {
 /** A stub adapter whose `lint` returns whatever the test wires; `count`/`minify` unused here. */
 function stubAdapter(result: ShrinkoResult<LintReport>): ShrinkoAdapter {
 	return {
+		async exportSpritesheet() {
+			throw new Error('exportSpritesheet not used');
+		},
+		async importSpritesheet() {
+			throw new Error('importSpritesheet not used');
+		},
 		async count() {
 			throw new Error('not used');
 		},

package/src/commands/minify.test.ts

@@ -41,6 +41,12 @@ function stubAdapter(
 	seen?: {outPath?: string},
 ): ShrinkoAdapter {
 	return {
+		async exportSpritesheet() {
+			throw new Error('exportSpritesheet not used');
+		},
+		async importSpritesheet() {
+			throw new Error('importSpritesheet not used');
+		},
 		async count() {
 			throw new Error('not used');
 		},

package/src/commands/playtest.test.ts

@@ -58,6 +58,9 @@ function stubAdapter(
 	seen?: {options?: DriveOptions},
 ): Pico8Adapter {
 	return {
+		async export() {
+			throw new Error('export not used');
+		},
 		async run() {
 			throw new Error('run not used by playtest');
 		},

package/src/commands/playtest.ts

@@ -6,7 +6,7 @@ import {
 	writeFileSync,
 } from 'node:fs';
 import {tmpdir} from 'node:os';
-import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {isAbsolute, join, resolve} from 'node:path';
 import {type Cli, Cli as IncurCli, z} from 'incur';
 import {
 	buildDriveHarness,
@@ -28,6 +28,7 @@ import {
 	type SessionResponse,
 	type SessionResponseValue,
 } from '../engine/pico8/index.js';
+import {makeReadInclude} from './cart-includes.js';
 
 /**
  * Injects the PICO-8 adapter `playtest` uses (defaults to the shell adapter over
@@ -57,28 +58,6 @@ function resolvePath(p: string): string {
 	return isAbsolute(p) ? p : resolve(process.cwd(), p);
 }
 
-/**
- * A `#include` resolver for the drive-transform, bound to the SOURCE cart's dir:
- * picopilot's standard scaffold is `main.p8` = `#include main.lua`, and the
- * driven cart runs from a throwaway temp dir where `main.lua` is absent, so the
- * transform inlines includes to be self-contained. Reads the included file
- * relative to the cart (absolute paths honoured); returns `undefined` if it
- * cannot be read (the directive is then left verbatim).
- */
-function makeReadInclude(cartPath: string): (p: string) => string | undefined {
-	const base = dirname(cartPath);
-	return (includePath) => {
-		const full = isAbsolute(includePath)
-			? includePath
-			: join(base, includePath);
-		try {
-			return readFileSync(full, 'utf8');
-		} catch {
-			return undefined;
-		}
-	};
-}
-
 /** A small sleep for the `start` readiness poll. */
 function sleep(ms: number): Promise<void> {
 	return new Promise((r) => setTimeout(r, ms));

package/src/commands/run.test.ts

@@ -47,6 +47,12 @@ function stubAdapter(
 	recordResult?: Pico8RecordResult,
 ): Pico8Adapter {
 	return {
+		async drive() {
+			throw new Error('drive not used');
+		},
+		async export() {
+			throw new Error('export not used');
+		},
 		async run(options) {
 			if (seen !== undefined) seen.options = options;
 			return result;

package/src/commands/serve.test.ts

@@ -1,12 +1,21 @@
 import {execFileSync} from 'node:child_process';
-import {existsSync, mkdtempSync, writeFileSync} from 'node:fs';
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {Cli} from 'incur';
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {encodePng} from '../engine/gfx/index.js';
 import type {
+	DriveOptions,
 	ExportOptions,
 	Pico8Adapter,
+	Pico8DriveResult,
 	Pico8ExportResult,
 } from '../engine/pico8/index.js';
 import {pico8NotFound} from '../engine/pico8/index.js';
@@ -211,7 +220,12 @@ describe('picopilot serve: failure paths', () => {
 		const lower = stdout.toLowerCase();
 		expect(lower).toContain('picopilot run');
 		expect(lower).toContain('playtest');
-		expect(lower).toContain('export --label');
+		// The remedy must be one that WORKS: `export --label` never writes the label
+		// into the cart, so "export --label, then re-serve" would fail again. serve
+		// takes the label itself.
+		expect(lower).toMatch(/picopilot serve [^`]*--label/);
+		expect(lower).toContain('--label-frame 0');
+		expect(lower).not.toContain('then re-serve');
 		expect(lower).toContain('do not hand-edit main.p8');
 	});
 
@@ -225,3 +239,125 @@ describe('picopilot serve: failure paths', () => {
 		expect(stdout).toContain('no cart at');
 	});
 });
+
+describe('picopilot serve: --label (bake a screenshot in for a labelless cart)', () => {
+	const shotPath = new URL(
+		'../engine/gfx/fixtures/pico8-screenshot-384.png',
+		import.meta.url,
+	);
+
+	it('exports a labeled COPY (the screenshot as-is), leaves the cart untouched, and cleans the copy up', async () => {
+		const labelFile = join(dir, 'shot.png');
+		writeFileSync(labelFile, readFileSync(shotPath));
+		let exportedCart = '';
+		const exportSeen: {options?: ExportOptions} = {};
+		const {exitCode} = await runServe(
+			() => {
+				const inner = stubAdapter('writes-bundle', exportSeen);
+				return {
+					...inner,
+					export: async (o: ExportOptions) => {
+						exportedCart = readFileSync(o.cartPath, 'utf8');
+						return inner.export(o);
+					},
+				} as Pico8Adapter;
+			},
+			fakeServer(),
+			['serve', cartPath, '--label', labelFile, '--json'],
+		);
+		expect(exitCode).toBe(0);
+		expect(exportSeen.options!.cartPath).not.toBe(cartPath);
+		const label = exportedCart.split('__label__\n')[1]!.split('\n');
+		expect(label[10]![10]).toBe('8');
+		expect(label[100]![100]).toBe('c');
+		expect(readFileSync(cartPath, 'utf8')).not.toContain('__label__');
+		// Only the cart and the label image remain: the labeled copy is gone.
+		expect(readdirSync(dir).sort()).toEqual(['main.p8', 'shot.png']);
+	});
+
+	it('removes the labeled copy even when the export step throws', async () => {
+		const labelFile = join(dir, 'shot.png');
+		writeFileSync(labelFile, readFileSync(shotPath));
+		await runServe(
+			() =>
+				({
+					...stubAdapter('writes-bundle'),
+					export: async () => {
+						throw new Error('boom');
+					},
+				}) as Pico8Adapter,
+			fakeServer(),
+			['serve', cartPath, '--label', labelFile, '--json'],
+		).catch(() => undefined);
+		expect(readdirSync(dir).sort()).toEqual(['main.p8', 'shot.png']);
+	});
+
+	it('surfaces a bad label image as label-wrong-size with the screenshot CTA, before exporting', async () => {
+		const labelFile = join(dir, 'odd.png');
+		writeFileSync(
+			labelFile,
+			encodePng({width: 200, height: 200, rgb: new Uint8Array(200 * 200 * 3)}),
+		);
+		const exportSeen: {options?: ExportOptions} = {};
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter('writes-bundle', exportSeen),
+			fakeServer(),
+			['serve', cartPath, '--label', labelFile, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-wrong-size');
+		expect(stdout).toContain('scaled for you');
+		expect(exportSeen.options).toBeUndefined();
+	});
+});
+
+describe('picopilot serve: --label-frame (capture the label from the game)', () => {
+	it('captures frame N with no input and serves the export of a labeled copy', async () => {
+		let drive: DriveOptions | undefined;
+		let exportedCart = '';
+		const {exitCode} = await runServe(
+			() => ({
+				...stubAdapter('writes-bundle'),
+				async drive(o: DriveOptions): Promise<Pico8DriveResult> {
+					drive = o;
+					const shot = join(o.shotDir, 'label0.png');
+					writeFileSync(
+						shot,
+						readFileSync(
+							new URL(
+								'../engine/gfx/fixtures/pico8-screenshot-384.png',
+								import.meta.url,
+							),
+						),
+					);
+					return {
+						ok: true,
+						value: {screenshots: [shot], printh: '', exitReason: 'sentinel'},
+					};
+				},
+				async export(o: ExportOptions) {
+					exportedCart = readFileSync(o.cartPath, 'utf8');
+					return stubAdapter('writes-bundle').export(o);
+				},
+			}),
+			fakeServer(),
+			['serve', cartPath, '--label-frame', '2', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		expect(drive).toBeDefined();
+		expect(exportedCart.split('__label__\n')[1]!.split('\n')[10]![10]).toBe(
+			'8',
+		);
+		expect(readdirSync(dir)).toEqual(['main.p8']);
+	});
+
+	it('rejects --label with --label-frame', async () => {
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter('writes-bundle'),
+			fakeServer(),
+			['serve', cartPath, '--label', 'x.png', '--label-frame', '1', '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-flags-conflict');
+	});
+});

package/src/commands/serve.ts

@@ -12,8 +12,10 @@ import {type Cli, z} from 'incur';
 import {
 	EXPORT_HTML_NAME,
 	type Pico8Adapter,
+	type Pico8ExportResult,
 	ShellPico8Adapter,
 } from '../engine/pico8/index.js';
+import {prepareLabeledCart} from './label-cart.js';
 
 /**
  * Injects the PICO-8 adapter `serve` uses (defaults to the shell adapter). Same
@@ -174,6 +176,20 @@ export function registerServe(
 				),
 		}),
 		options: z.object({
+			label: z
+				.string()
+				.optional()
+				.describe(
+					'PNG to bake in as the __label__ (the export splash) for a cart that has none: a `run`/`playtest` screenshot as-is, or any 128x128 PNG. The cart itself is not modified. Ignored if the cart already has a label.',
+				),
+			labelFrame: z
+				.number()
+				.int()
+				.min(0)
+				.optional()
+				.describe(
+					'Capture the label from the game itself: run the cart headlessly with NO input and use frame N (0-based: 0 = the first drawn frame, usually the title screen) as the __label__. Needs PICO-8; the cart need not cooperate. Exclusive with --label; ignored if the cart already has a label.',
+				),
 			port: z
 				.number()
 				.int()
@@ -186,7 +202,9 @@ export function registerServe(
 				.int()
 				.positive()
 				.default(DEFAULT_BACKSTOP_MS)
-				.describe('Safety backstop for the export step.'),
+				.describe(
+					'Safety backstop for the export step (and the --label-frame capture run).',
+				),
 		}),
 		env: z.object({
 			PICO8_PATH: z
@@ -210,6 +228,18 @@ export function registerServe(
 				args: {cart: 'game.p8'},
 				options: {port: 8080},
 			},
+			{
+				description:
+					'Serve a labelless cart, using a `run` screenshot as the splash',
+				args: {cart: 'game.p8'},
+				options: {label: './shots/<name>.png'},
+			},
+			{
+				description:
+					'Serve a labelless cart, using its title screen (frame 0) as the splash',
+				args: {cart: 'game.p8'},
+				options: {labelFrame: 0},
+			},
 		],
 		async run({args, options, env, error, ok}) {
 			const cartPath = isAbsolute(args.cart)
@@ -224,16 +254,48 @@ export function registerServe(
 				});
 			}
 
-			// Always export first, into an isolated temp dir (never a user path or
-			// ~/Desktop). The bundle is the standalone pair the static server plays.
-			const serveDir = mkdtempSync(join(tmpdir(), 'picopilot-serve-'));
+			// --label / --label-frame: export a labeled throwaway copy (shared with
+			// `export`; the cart is never mutated). A bad image or a failed capture
+			// fails before anything is exported.
 			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
-			const result = await adapter.export({
+			const labeled = await prepareLabeledCart(
 				cartPath,
-				outDir: serveDir,
-				htmlName: EXPORT_HTML_NAME,
-				backstopMs: options.backstopMs,
-			});
+				{
+					label: options.label,
+					labelFrame: options.labelFrame,
+					backstopMs: options.backstopMs,
+				},
+				(o) => adapter.drive(o),
+			);
+			if (!labeled.ok) {
+				return error({
+					code: labeled.code,
+					message: labeled.message,
+					exitCode: 1,
+					...(labeled.cta ? {cta: labeled.cta} : {}),
+				});
+			}
+
+			// Always export first, into an isolated temp dir (never a user path or
+			// ~/Desktop). The bundle is the standalone pair the static server plays.
+			// The labeled copy (in the user's cart dir) is removed on every path; a
+			// throw also reaps the temp dir, since nothing will be served from it.
+			let result: Pico8ExportResult;
+			let serveDir: string | undefined;
+			try {
+				serveDir = mkdtempSync(join(tmpdir(), 'picopilot-serve-'));
+				result = await adapter.export({
+					cartPath: labeled.cartPath,
+					outDir: serveDir,
+					htmlName: EXPORT_HTML_NAME,
+					backstopMs: options.backstopMs,
+				});
+			} catch (e) {
+				if (serveDir !== undefined) removeDir(serveDir);
+				throw e;
+			} finally {
+				labeled.cleanup();
+			}
 
 			if (!result.ok) {
 				// Nothing is being served: remove the temp dir now, not on exit.
@@ -250,7 +312,7 @@ export function registerServe(
 				return error({
 					code: 'export-failed',
 					message: result.value.labelWarning
-						? 'PICO-8 produced no bundle: this cart has no __label__ (the export splash), which the browser export needs. To just SEE your own build work, use `picopilot run` or `picopilot playtest` (no label needed) instead of serve. If you genuinely want a browser build to SHARE, bake a label first with `picopilot export --label <128x128.png>` (do NOT hand-edit main.p8), then re-serve.'
+						? 'PICO-8 produced no bundle: this cart has no __label__ (the export splash), which the browser export needs. To just SEE your own build work, use `picopilot run` or `picopilot playtest` (no label needed) instead of serve. If you genuinely want a browser build to SHARE, give it a splash: `picopilot serve <cart> --label-frame 0` captures the title screen for you, or `picopilot serve <cart> --label <screenshot.png>` takes any path `run`/`playtest` lists under `screenshots` as-is (do NOT hand-edit main.p8).'
 						: 'PICO-8 produced no export bundle. Check the cart runs without a boot error (via `picopilot run`).',
 					exitCode: 1,
 				});