picopilot 0.1.4 → 0.2.0

package/src/commands/export.test.ts

@@ -13,11 +13,14 @@ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import {encodePng} from '../engine/gfx/index.js';
 import {PICO8_PALETTE} from '../engine/gfx/index.js';
 import type {
+	DriveCommand,
+	DriveOptions,
 	ExportOptions,
 	Pico8Adapter,
+	Pico8DriveResult,
 	Pico8ExportResult,
 } from '../engine/pico8/index.js';
-import {pico8NotFound} from '../engine/pico8/index.js';
+import {BlockDecoder, pico8NotFound} from '../engine/pico8/index.js';
 import {type Pico8AdapterFactory, registerExport} from './export.js';
 
 /** A trivial valid cart the command reads (existence + a path to hand the adapter). */
@@ -265,6 +268,92 @@ describe('picopilot export: --label (bake a PNG in as the __label__ splash)', ()
 		expect(exitCode).not.toBe(0);
 		expect(stdout).toContain('128x128');
 	});
+
+	it('accepts a PICO-8 screenshot as-is (384x384, as `run` writes it) and bakes it in', async () => {
+		const shot = readFileSync(
+			new URL(
+				'../engine/gfx/fixtures/pico8-screenshot-384.png',
+				import.meta.url,
+			),
+		);
+		const labelFile = join(dir, 'shot.png');
+		writeFileSync(labelFile, shot);
+		let labeledCart = '';
+		const {exitCode} = await runExport(() => {
+			const inner = stubAdapter('writes-bundle');
+			return {
+				...inner,
+				export: async (o: ExportOptions) => {
+					labeledCart = readFileSync(o.cartPath, 'utf8');
+					return inner.export(o);
+				},
+			} as Pico8Adapter;
+		}, ['export', cartPath, join(dir, 'out'), '--label', labelFile, '--json']);
+		expect(exitCode).toBe(0);
+		const label = labeledCart.split('__label__\n')[1]!.split('\n');
+		// The fixture: red (8) top-left quadrant, blue (12) bottom-right, dark blue (1) bg.
+		expect(label[10]![10]).toBe('8');
+		expect(label[100]![100]).toBe('c');
+		expect(label[100]![10]).toBe('1');
+	});
+
+	it('removes the labeled copy even when the export step throws', async () => {
+		const labelFile = join(dir, 'label.png');
+		writeFileSync(labelFile, labelPng());
+		await runExport(
+			() =>
+				({
+					...stubAdapter('writes-bundle'),
+					export: async () => {
+						throw new Error('boom');
+					},
+				}) as Pico8Adapter,
+			['export', cartPath, join(dir, 'out'), '--label', labelFile, '--json'],
+		).catch(() => undefined);
+		expect(
+			readdirSync(dir).filter((f) => f.startsWith('.picopilot-export-')),
+		).toEqual([]);
+	});
+
+	it('points a wrong-size label error at passing a picopilot screenshot directly', async () => {
+		const odd = encodePng({
+			width: 200,
+			height: 200,
+			rgb: new Uint8Array(200 * 200 * 3),
+		});
+		const labelFile = join(dir, 'odd.png');
+		writeFileSync(labelFile, odd);
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle'),
+			['export', cartPath, join(dir, 'out'), '--label', labelFile, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-wrong-size');
+		expect(stdout).toContain('384x384');
+		expect(stdout.toLowerCase()).toContain('screenshot');
+		expect(stdout).toContain('scaled for you');
+	});
+
+	it('points an unsupported-PNG label error at the same fix', async () => {
+		// A valid PNG signature + IHDR claiming an interlaced image: unsupported.
+		const png = encodePng({
+			width: 128,
+			height: 128,
+			rgb: new Uint8Array(128 * 128 * 3),
+		});
+		// IHDR data starts at byte 16; the interlace byte is the 13th (offset 28).
+		png[28] = 1;
+		const labelFile = join(dir, 'interlaced.png');
+		writeFileSync(labelFile, png);
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle'),
+			['export', cartPath, join(dir, 'out'), '--label', labelFile, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-unsupported-png');
+		expect(stdout.toLowerCase()).toContain('screenshot');
+		expect(stdout).toContain('scaled for you');
+	});
 });
 
 describe('picopilot export: labelless cart + failure paths', () => {
@@ -276,7 +365,7 @@ describe('picopilot export: labelless cart + failure paths', () => {
 		expect(exitCode).toBe(0);
 		const out = JSON.parse(stdout);
 		expect(out.labelWarning).toBe(true);
-		expect(stdout.toLowerCase()).toContain('label');
+		expect(stdout).toContain('--label-frame 0');
 	});
 
 	it('errors when PICO-8 produced no js payload (labelless bail)', async () => {
@@ -285,7 +374,7 @@ describe('picopilot export: labelless cart + failure paths', () => {
 			['export', cartPath, join(dir, 'out'), '--json'],
 		);
 		expect(exitCode).not.toBe(0);
-		expect(stdout.toLowerCase()).toContain('label');
+		expect(stdout).toContain('--label-frame 0');
 	});
 });
 
@@ -308,3 +397,238 @@ describe('picopilot export: cart-not-found (picopilot-side error, distinct from
 		expect(called).toBe(false);
 	});
 });
+
+/** The real PICO-8 384x384 screenshot fixture: red (8) top-left, blue (12) bottom-right, dark blue (1) bg. */
+const SHOT_FIXTURE = new URL(
+	'../engine/gfx/fixtures/pico8-screenshot-384.png',
+	import.meta.url,
+);
+
+/**
+ * Wraps {@link stubAdapter} with a `drive` that plays the label-frame capture:
+ * records the {@link DriveOptions} and the driven cart text, then (by default)
+ * writes the screenshot fixture into `shotDir` as PICO-8 would and reports it.
+ * Also records the cart text handed to `export`.
+ */
+function frameAdapter(
+	seen: {
+		drive?: DriveOptions;
+		drivenCart?: string;
+		exportedCart?: string;
+		exportCalled?: boolean;
+	},
+	driveResult: 'captures' | Pico8DriveResult = 'captures',
+	labelWarning = false,
+): Pico8Adapter {
+	const inner = stubAdapter('writes-bundle', undefined, labelWarning);
+	return {
+		...inner,
+		async drive(o: DriveOptions): Promise<Pico8DriveResult> {
+			seen.drive = o;
+			seen.drivenCart = readFileSync(o.cartPath, 'utf8');
+			if (driveResult !== 'captures') return driveResult;
+			const shot = join(o.shotDir, 'label0.png');
+			writeFileSync(shot, readFileSync(SHOT_FIXTURE));
+			return {
+				ok: true,
+				value: {screenshots: [shot], printh: '', exitReason: 'sentinel'},
+			};
+		},
+		async export(o: ExportOptions) {
+			seen.exportCalled = true;
+			seen.exportedCart = readFileSync(o.cartPath, 'utf8');
+			return inner.export(o);
+		},
+	};
+}
+
+/** Decodes the command blocks a drive call was handed. */
+function decodeScript(blocks: Uint8Array): DriveCommand[] {
+	return new BlockDecoder().push(blocks);
+}
+
+describe('picopilot export: --label-frame (capture the label from the game itself)', () => {
+	it('advances N frames with NO input, shoots once, and bakes that frame in as the label', async () => {
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		const {stdout, exitCode} = await runExport(
+			() => frameAdapter(seen),
+			['export', cartPath, join(dir, 'out'), '--label-frame', '5', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		// The script: 6 single-frame steps (frames 0..5), a SHOT after the 6th,
+		// then QUIT; the only input is "nothing held".
+		const script = decodeScript(seen.drive!.blocks);
+		expect(script.filter((c) => c.op === 'step').length).toBe(6);
+		expect(script.filter((c) => c.op === 'shot').length).toBe(1);
+		const shotAt = script.findIndex((c) => c.op === 'shot');
+		expect(script.slice(0, shotAt).filter((c) => c.op === 'step').length).toBe(
+			6,
+		);
+		expect(
+			script
+				.filter((c) => c.op === 'input')
+				.every((c) => c.op === 'input' && c.held === 0),
+		).toBe(true);
+		expect(script[script.length - 1]!.op).toBe('quit');
+		// The exported cart carries the captured frame as its label.
+		const label = seen.exportedCart!.split('__label__\n')[1]!.split('\n');
+		expect(label[10]![10]).toBe('8');
+		expect(label[100]![100]).toBe('c');
+		expect(label[100]![10]).toBe('1');
+		expect(JSON.parse(stdout).labelSource).toBe('frame');
+		// The user's cart is untouched and no temp files are left beside it.
+		expect(readFileSync(cartPath, 'utf8')).not.toContain('__label__');
+		expect(readdirSync(dir).filter((f) => f.startsWith('.'))).toEqual([]);
+		// The capture dir (PICO-8's -desktop) is removed after reading the frame.
+		expect(existsSync(seen.drive!.shotDir)).toBe(false);
+	});
+
+	it('--label-frame 0 shoots right after the first step (the first drawn frame)', async () => {
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		await runExport(
+			() => frameAdapter(seen),
+			['export', cartPath, join(dir, 'out'), '--label-frame', '0', '--json'],
+		);
+		const ops = decodeScript(seen.drive!.blocks).map((c) => c.op);
+		expect(ops).toEqual(['input', 'step', 'shot', 'quit']);
+	});
+
+	it("inlines the cart's #include so the throwaway driven cart is self-contained", async () => {
+		writeFileSync(join(dir, 'main.lua'), 'function _draw() cls(9) end\n');
+		writeFileSync(
+			cartPath,
+			'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\n#include main.lua\n',
+		);
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		await runExport(
+			() => frameAdapter(seen),
+			['export', cartPath, join(dir, 'out'), '--label-frame', '3', '--json'],
+		);
+		expect(seen.drivenCart).toContain('cls(9)');
+		// The driven cart is NOT the one exported: the export copy keeps the include.
+		expect(seen.exportedCart).toContain('#include main.lua');
+		expect(seen.exportedCart).not.toContain('serial(');
+	});
+
+	it("does not run the cart when it already has a label (the cart's label wins)", async () => {
+		const labeled = join(dir, 'labeled.p8');
+		writeFileSync(labeled, `${CART_TEXT}__label__\n${'0'.repeat(128)}\n`);
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		const {stdout, exitCode} = await runExport(
+			() => frameAdapter(seen),
+			['export', labeled, join(dir, 'out'), '--label-frame', '5', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		expect(seen.drive).toBeUndefined();
+		expect(JSON.parse(stdout).labelSource).toBe('cart');
+	});
+
+	it('rejects --label together with --label-frame, before running anything', async () => {
+		const labelFile = join(dir, 'label.png');
+		writeFileSync(labelFile, labelPng());
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		const {stdout, exitCode} = await runExport(
+			() => frameAdapter(seen),
+			[
+				'export',
+				cartPath,
+				join(dir, 'out'),
+				'--label',
+				labelFile,
+				'--label-frame',
+				'5',
+				'--json',
+			],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-flags-conflict');
+		expect(seen.drive).toBeUndefined();
+		expect(seen.exportCalled).toBeUndefined();
+	});
+
+	it('returns pico8-not-found when PICO-8 is absent for the capture (no export attempted)', async () => {
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		const {stdout, exitCode} = await runExport(
+			() => frameAdapter(seen, pico8NotFound()),
+			['export', cartPath, join(dir, 'out'), '--label-frame', '5', '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('pico8-not-found');
+		expect(seen.exportCalled).toBeUndefined();
+		expect(existsSync(seen.drive!.shotDir)).toBe(false);
+	});
+
+	it('removes the capture dir and leaves no copy when the capture run throws', async () => {
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		await runExport(
+			() => ({
+				...frameAdapter(seen),
+				async drive(o: DriveOptions): Promise<Pico8DriveResult> {
+					seen.drive = o;
+					throw new Error('boom');
+				},
+			}),
+			['export', cartPath, join(dir, 'out'), '--label-frame', '5', '--json'],
+		).catch(() => undefined);
+		expect(existsSync(seen.drive!.shotDir)).toBe(false);
+		expect(readdirSync(dir).filter((f) => f.startsWith('.'))).toEqual([]);
+		expect(seen.exportCalled).toBeUndefined();
+	});
+
+	it('errors as label-frame-not-captured (with a CTA) when no frame was captured', async () => {
+		const seen: Parameters<typeof frameAdapter>[0] = {};
+		const {stdout, exitCode} = await runExport(
+			() =>
+				frameAdapter(seen, {
+					ok: true,
+					value: {
+						screenshots: [],
+						printh: 'runtime error line 3',
+						exitReason: 'timeout',
+					},
+				}),
+			['export', cartPath, join(dir, 'out'), '--label-frame', '5', '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-frame-not-captured');
+		expect(stdout).toContain('timeout');
+		expect(stdout).toContain('runtime error line 3');
+		// The CTA reproduces the SAME no-input frame via a session (not
+		// `playtest run`, whose generic input and fixed shot frames differ).
+		expect(stdout).toContain('playtest step <id> --frames 6');
+		expect(stdout).toContain('playtest shot <id>');
+		expect(stdout).not.toContain('playtest run');
+		// A timeout also points at the backstop.
+		expect(stdout).toContain('--backstop-ms');
+		expect(seen.exportCalled).toBeUndefined();
+		expect(existsSync(seen.drive!.shotDir)).toBe(false);
+		expect(readdirSync(dir).filter((f) => f.startsWith('.'))).toEqual([]);
+	});
+
+	it('leaves an unreadable cart to PICO-8 when no label flag is passed (no throw)', async () => {
+		const dirCart = join(dir, 'weird.p8');
+		execFileSync('mkdir', [dirCart]);
+		const seen: {options?: ExportOptions} = {};
+		const {exitCode} = await runExport(
+			() => stubAdapter('writes-bundle', seen),
+			['export', dirCart, join(dir, 'out'), '--json'],
+		);
+		expect(exitCode).toBe(0);
+		expect(seen.options!.cartPath).toBe(dirCart);
+	});
+
+	it('reports labelSource for the other paths (image / none)', async () => {
+		const labelFile = join(dir, 'label.png');
+		writeFileSync(labelFile, labelPng());
+		const withImage = await runExport(
+			() => stubAdapter('writes-bundle'),
+			['export', cartPath, join(dir, 'a'), '--label', labelFile, '--json'],
+		);
+		expect(JSON.parse(withImage.stdout).labelSource).toBe('image');
+		const none = await runExport(
+			() => stubAdapter('writes-bundle', undefined, true),
+			['export', cartPath, join(dir, 'b'), '--json'],
+		);
+		expect(JSON.parse(none.stdout).labelSource).toBe('none');
+	});
+});

package/src/commands/export.ts

@@ -1,33 +1,27 @@
-import {
-	existsSync,
-	mkdirSync,
-	mkdtempSync,
-	readdirSync,
-	readFileSync,
-	rmSync,
-	writeFileSync,
-} from 'node:fs';
+import {existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync} 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, z} from 'incur';
-import {Cart, CartParseError} from '../engine/cart/index.js';
-import {labelHexFromPng, LabelError} from '../engine/gfx/index.js';
 import {
 	EXPORT_HTML_NAME,
 	type Pico8Adapter,
-	ShellPico8Adapter,
+	type Pico8ExportResult,
 } from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
+import {prepareLabeledCart} from './label-cart.js';
 
 /**
  * Injects the PICO-8 adapter `export` uses (defaults to the shell adapter over
  * native `pico8 <cart> -export <name>.html -x`). Mirrors the `run` seam: a test
- * passes a stub to drive the present/absent paths without the paid binary, and
- * to isolate the child `env` (its `PICO8_PATH`/`PATH`).
+ * passes a stub to drive the present/absent paths without the paid binary, (the child env is the parent env + PICO8_PATH/PATH).
  */
-export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+export type {Pico8AdapterFactory} from './pico8-env.js';
 
-const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
-	new ShellPico8Adapter({env});
+const defaultAdapterFactory: Pico8AdapterFactory = createShellAdapterFactory();
 
 /** The default backstop: kill an export that never completes/exits after this many ms. */
 const DEFAULT_BACKSTOP_MS = 30_000;
@@ -83,7 +77,15 @@ export function registerExport(
 				.string()
 				.optional()
 				.describe(
-					'Path to a 128x128 PNG to bake in as the cart __label__ (the export splash), for a cart that has none. Ignored if the cart already has a label.',
+					'PNG to bake in as the cart __label__ (the export splash), for a cart that has none: a `run`/`playtest` screenshot as-is (any 128*k square, e.g. 384x384, is scaled down for you) or any 128x128 PNG. 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.',
 				),
 			payloadOnly: z
 				.boolean()
@@ -97,18 +99,12 @@ export function registerExport(
 				.positive()
 				.default(DEFAULT_BACKSTOP_MS)
 				.describe(
-					'Safety backstop: kill PICO-8 after this many ms if the export never completes.',
+					'Safety backstop: kill PICO-8 after this many ms if the export (or the --label-frame capture run) never completes.',
 				),
 		}),
 		// incur resolves these from the (test-overridable) env source and hands
 		// them to the child, so PICO8_PATH/PATH locate the binary in isolation.
-		env: z.object({
-			PICO8_PATH: z
-				.string()
-				.optional()
-				.describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
-			PATH: z.string().optional().describe('Used to locate `pico8`.'),
-		}),
+		env: PICO8_ENV,
 		output: z.object({
 			outDir: z
 				.string()
@@ -123,6 +119,11 @@ export function registerExport(
 			files: z
 				.array(z.string())
 				.describe('Absolute paths of every file the bundle contains.'),
+			labelSource: z
+				.enum(['cart', 'image', 'frame', 'none'])
+				.describe(
+					"Where the bundle's label came from: the cart's own __label__, --label, --label-frame, or none.",
+				),
 			labelWarning: z
 				.boolean()
 				.describe(
@@ -136,9 +137,16 @@ export function registerExport(
 				args: {cart: 'game.p8', dest: './website/static/games/my-game'},
 			},
 			{
-				description: 'Bake a PNG as the label splash for a labelless cart',
+				description:
+					'Bake a `run` screenshot in as the label splash for a labelless cart',
 				args: {cart: 'game.p8', dest: './website/static/games/my-game'},
-				options: {label: './label.png'},
+				options: {label: './shots/<name>.png'},
+			},
+			{
+				description:
+					'Capture the title screen (frame 0) as the label splash, no image needed',
+				args: {cart: 'game.p8', dest: './website/static/games/my-game'},
+				options: {labelFrame: 0},
 			},
 			{
 				description:
@@ -161,56 +169,27 @@ export function registerExport(
 				});
 			}
 
-			// --label <png>: bake a 128x128 PNG in as the cart's __label__ so a
-			// labelless cart gets a splash without an interactive F7 capture. We do
-			// NOT mutate the user's cart: we write a labeled copy NEXT TO it (same dir,
-			// so `#include main.lua` still resolves) and export that, then clean it up.
-			// A cart that ALREADY has a label wins (the flag is a fallback, not an
-			// override), matching the export precedence PICO-8 itself uses.
-			let exportCartPath = cartPath;
-			let labeledCopy: string | undefined;
-			if (options.label !== undefined) {
-				const labelPath = isAbsolute(options.label)
-					? options.label
-					: resolve(process.cwd(), options.label);
-				if (!existsSync(labelPath)) {
-					return error({
-						code: 'label-not-found',
-						message: `no label image at ${labelPath}`,
-						exitCode: 1,
-					});
-				}
-				try {
-					const cart = Cart.parse(readFileSync(cartPath, 'utf8'));
-					const existingLabel = cart.getSection('label');
-					if (existingLabel === undefined || existingLabel.trim() === '') {
-						const hex = labelHexFromPng(readFileSync(labelPath));
-						cart.setSection('label', hex);
-						labeledCopy = join(
-							dirname(cartPath),
-							`.picopilot-export-${process.pid}-${Date.now()}.p8`,
-						);
-						writeFileSync(labeledCopy, cart.serialize());
-						exportCartPath = labeledCopy;
-					}
-					// else: cart already has a label; keep it, ignore --label.
-				} catch (e) {
-					if (e instanceof LabelError) {
-						return error({
-							code: `label-${e.code}`,
-							message: e.message,
-							exitCode: 1,
-						});
-					}
-					if (e instanceof CartParseError) {
-						return error({
-							code: `cart-${e.code}`,
-							message: `could not parse the cart to inject a label: ${e.message}`,
-							exitCode: 1,
-						});
-					}
-					throw e;
-				}
+			// --label <png> / --label-frame <n>: bake an image, or a captured frame of
+			// the running cart, in as the __label__ of a throwaway copy (the user's
+			// cart is never mutated; an existing label wins). Shared with `serve`,
+			// see label-cart.ts.
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const labeled = await prepareLabeledCart(
+				cartPath,
+				{
+					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} : {}),
+				});
 			}
 
 			// Output dir: a user-given dest (point it at the showcase), else an
@@ -221,24 +200,21 @@ export function registerExport(
 						? args.dest
 						: resolve(process.cwd(), args.dest)
 					: mkdtempSync(join(tmpdir(), 'picopilot-export-'));
-			if (!existsSync(outDir)) mkdirSync(outDir, {recursive: true});
-
-			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
-			const result = await adapter.export({
-				cartPath: exportCartPath,
-				outDir,
-				htmlName: EXPORT_HTML_NAME,
-				backstopMs: options.backstopMs,
-			});
 
-			// Remove the temporary labeled copy now that PICO-8 has read it (on every
-			// path below); best-effort, a leftover dotfile is not fatal.
-			if (labeledCopy !== undefined) {
-				try {
-					rmSync(labeledCopy);
-				} catch {
-					// ignore
-				}
+			// The labeled copy lives in the user's cart dir, so remove it on EVERY
+			// path once PICO-8 has read it, including a throw from the dir setup or
+			// the adapter.
+			let result: Pico8ExportResult;
+			try {
+				if (!existsSync(outDir)) mkdirSync(outDir, {recursive: true});
+				result = await adapter.export({
+					cartPath: labeled.cartPath,
+					outDir,
+					htmlName: EXPORT_HTML_NAME,
+					backstopMs: options.backstopMs,
+				});
+			} finally {
+				labeled.cleanup();
 			}
 
 			if (!result.ok) {
@@ -259,7 +235,7 @@ export function registerExport(
 				return error({
 					code: 'export-failed',
 					message: labelWarning
-						? 'PICO-8 produced no bundle (the cart has no __label__ to embed). Give it one with --label <128x128.png>, or capture a label in PICO-8 (F7), then re-export.'
+						? 'PICO-8 produced no bundle (the cart has no __label__ to embed). Give it one with --label-frame 0 (captures the title screen for you), or --label <screenshot.png> (a `picopilot run`/`playtest` screenshot works as-is), then re-export.'
 						: 'PICO-8 produced no export bundle. Check the cart runs without a boot error.',
 					exitCode: 1,
 				});
@@ -285,9 +261,14 @@ export function registerExport(
 								'The cart has no __label__, so the export splash is blank. Add one for a nicer bundle:',
 							commands: [
 								{
-									command: 'export --label <128x128.png>',
+									command: 'export <cart> <dest> --label-frame 0',
+									description:
+										'Capture the title screen (frame 0) of the running cart as the label, no image needed.',
+								},
+								{
+									command: 'export --label <screenshot.png>',
 									description:
-										'Bake a PNG in as the label splash, or capture one in PICO-8 (F7) before exporting.',
+										'Bake a `run`/`playtest` screenshot in as the label splash (passed as-is, it is scaled for you), or capture one in PICO-8 (F7) before exporting.',
 								},
 							],
 						}
@@ -299,6 +280,7 @@ export function registerExport(
 					html: htmlPath,
 					js: jsPath,
 					files: [...files],
+					labelSource: labeled.labelSource,
 					labelWarning,
 				},
 				cta === undefined ? undefined : {cta},

package/src/commands/gfx.ts

@@ -20,16 +20,17 @@ import {
 	SHEET_RENDER_SCALE,
 	SPRITE_RENDER_SCALE,
 } from '../engine/gfx/index.js';
+import {type ShrinkoAdapter} from '../engine/shrinko/index.js';
 import {
-	type ShrinkoAdapter,
-	ShellShrinkoAdapter,
-} from '../engine/shrinko/index.js';
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
 
 /** Injects the shrinko adapter `gfx import`/`gfx export` use (the spritesheet round-trip). */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultShrinkoFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultShrinkoFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * The exit code for the `map-overlap` refusal. Chosen as 1 (a plain failure),