picopilot 0.1.3 → 0.1.5

package/src/engine/gfx/label.ts

@@ -1,5 +1,6 @@
 /**
- * The `__label__` builder: turn a 128x128 image into the hex a `.p8` cart's
+ * The `__label__` builder: turn a 128x128 image (or a PICO-8 screenshot, an
+ * integer upscale of one) into the hex a `.p8` cart's
  * label section holds, so `picopilot export --label <png>` can give a labelless
  * cart a loading splash WITHOUT an interactive PICO-8 (F7) capture.
  *
@@ -9,10 +10,13 @@
  * palette colour, and emits that hex. It is the inverse direction of the
  * palette-accurate PNG RENDER in `render.ts`/`png.ts` (which goes indices -> RGB).
  *
- * It intentionally supports only the PNG subset a caller realistically produces
- * for a 128x128 label: 8-bit, non-interlaced, colour types 2 (RGB) and 6 (RGBA),
- * and (via the palette map) 0/3 are rejected with a clear error rather than
- * guessed at. Anything else fails loud with a structured {@link LabelError}.
+ * It accepts what a caller realistically hands it: a PICO-8 screenshot exactly as
+ * `picopilot run`/`playtest` captured it (384x384 8-bit RGB by default; any
+ * square integer multiple of 128 is sampled back down), or a 128x128 image from
+ * any tool, including palette-indexed (1/2/4/8-bit, the form image tools write
+ * when shrinking a screenshot) and greyscale PNGs. Interlaced PNGs, sizes that
+ * are not a square multiple of 128, and malformed files are rejected, loud, with
+ * a structured {@link LabelError}.
  */
 
 import {inflateSync} from 'node:zlib';
@@ -42,12 +46,37 @@ interface DecodedPng {
 	readonly rgba: Uint8Array;
 }
 
+/** Samples per pixel for each PNG colour type we decode. */
+const CHANNELS: Readonly<Record<number, number>> = {
+	0: 1, // greyscale
+	2: 3, // RGB
+	3: 1, // palette index
+	4: 2, // greyscale + alpha
+	6: 4, // RGBA
+};
+
+/** The bit depths the PNG spec allows per colour type. */
+const ALLOWED_DEPTHS: Readonly<Record<number, readonly number[]>> = {
+	0: [1, 2, 4, 8, 16],
+	2: [8, 16],
+	3: [1, 2, 4, 8],
+	4: [8, 16],
+	6: [8, 16],
+};
+
 /**
- * Decodes an 8-bit, non-interlaced PNG (colour type 2 RGB or 6 RGBA) to RGBA.
+ * Decodes a non-interlaced PNG of any standard colour type and bit depth to
+ * RGBA: truecolour (2) and truecolour+alpha (6) at 8/16 bits, palette-indexed (3)
+ * at 1/2/4/8 bits via its PLTE chunk, and greyscale (0) / greyscale+alpha (4).
  * Uses `node:zlib` inflate for the IDAT stream and applies the five PNG scanline
- * filters. Throws {@link LabelError} for anything outside this subset.
+ * filters. `checkSize` runs on the IHDR dimensions before any pixel work. 16-bit samples keep their high byte (a label is quantised to 16
+ * colours anyway). Interlaced (Adam7) PNGs are rejected: PICO-8 never writes them.
+ * Throws {@link LabelError} for anything outside this set.
  */
-function decodePng(bytes: Uint8Array): DecodedPng {
+function decodePng(
+	bytes: Uint8Array,
+	checkSize: (width: number, height: number) => void = () => {},
+): DecodedPng {
 	for (let i = 0; i < PNG_SIGNATURE.length; i++) {
 		if (bytes[i] !== PNG_SIGNATURE[i]) {
 			throw new LabelError('not-a-png', 'not a PNG file (bad signature)');
@@ -60,6 +89,7 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 	let bitDepth = 0;
 	let colourType = 0;
 	let interlace = 0;
+	let palette: Uint8Array | undefined;
 	const idat: Uint8Array[] = [];
 
 	const readU32 = (p: number): number =>
@@ -88,6 +118,8 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 			bitDepth = bytes[dataStart + 8]!;
 			colourType = bytes[dataStart + 9]!;
 			interlace = bytes[dataStart + 12]!;
+		} else if (type === 'PLTE') {
+			palette = bytes.subarray(dataStart, dataEnd);
 		} else if (type === 'IDAT') {
 			idat.push(bytes.subarray(dataStart, dataEnd));
 		} else if (type === 'IEND') {
@@ -96,18 +128,28 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 		off = dataEnd + 4; // skip the 4-byte CRC
 	}
 
+	const channels = CHANNELS[colourType];
 	if (
-		bitDepth !== 8 ||
-		interlace !== 0 ||
-		(colourType !== 2 && colourType !== 6)
+		channels === undefined ||
+		!ALLOWED_DEPTHS[colourType]!.includes(bitDepth) ||
+		interlace !== 0
 	) {
 		throw new LabelError(
 			'unsupported-png',
-			`unsupported PNG: need 8-bit non-interlaced RGB or RGBA (got bitDepth=${bitDepth}, colourType=${colourType}, interlace=${interlace})`,
+			`unsupported PNG: need a non-interlaced greyscale, RGB, RGBA or palette-indexed image (got bitDepth=${bitDepth}, colourType=${colourType}, interlace=${interlace})`,
 		);
 	}
+	if (colourType === 3 && (palette === undefined || palette.length < 3)) {
+		throw new LabelError(
+			'unsupported-png',
+			'palette-indexed PNG has no PLTE chunk',
+		);
+	}
+
+	// Reject a wrong-sized image from its header alone, before inflating and
+	// decoding pixels we would throw away.
+	checkSize(width, height);
 
-	const channels = colourType === 6 ? 4 : 3;
 	const compressed = Buffer.concat(idat.map((c) => Buffer.from(c)));
 	let raw: Buffer;
 	try {
@@ -119,33 +161,57 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 		);
 	}
 
-	const stride = width * channels;
+	const bitsPerPixel = channels * bitDepth;
+	const stride = Math.ceil((width * bitsPerPixel) / 8);
+	// Filter byte distance: bytes per complete pixel, at least 1 (sub-byte depths).
+	const bpp = Math.max(1, bitsPerPixel >> 3);
+	if (raw.length < height * (stride + 1)) {
+		throw new LabelError(
+			'truncated-png',
+			`PNG image data too short for ${width}x${height}`,
+		);
+	}
+
+	// Reads sample `i` (0-based within the scanline) scaled to 0..255.
+	const maxSample = (1 << Math.min(bitDepth, 8)) - 1;
+	const sampleAt = (line: Uint8Array, i: number): number => {
+		if (bitDepth === 16) return line[i * 2]!;
+		if (bitDepth === 8) return line[i]!;
+		const bit = i * bitDepth;
+		const v = (line[bit >> 3]! >> (8 - bitDepth - (bit & 7))) & maxSample;
+		return v;
+	};
+	// Palette indices must stay raw; greyscale samples are scaled to 0..255.
+	const scaleGrey = (v: number): number =>
+		bitDepth >= 8 ? v : Math.round((v * 255) / maxSample);
+
 	const rgba = new Uint8Array(width * height * 4);
-	const prev = new Uint8Array(stride);
+	let prev = new Uint8Array(stride);
+	let line = new Uint8Array(stride);
 	let src = 0;
 	for (let y = 0; y < height; y++) {
 		const filter = raw[src++]!;
-		const line = new Uint8Array(stride);
 		for (let x = 0; x < stride; x++) {
 			const rawByte = raw[src++]!;
-			const a = x >= channels ? line[x - channels]! : 0; // left
+			const a = x >= bpp ? line[x - bpp]! : 0; // left
 			const b = prev[x]!; // up
-			const c = x >= channels ? prev[x - channels]! : 0; // up-left
-			let val = rawByte;
+			const c = x >= bpp ? prev[x - bpp]! : 0; // up-left
+			let val: number;
 			switch (filter) {
 				case 0:
+					val = rawByte;
 					break; // None
 				case 1:
-					val = (rawByte + a) & 0xff;
+					val = rawByte + a;
 					break; // Sub
 				case 2:
-					val = (rawByte + b) & 0xff;
+					val = rawByte + b;
 					break; // Up
 				case 3:
-					val = (rawByte + ((a + b) >> 1)) & 0xff;
+					val = rawByte + ((a + b) >> 1);
 					break; // Average
 				case 4:
-					val = (rawByte + paeth(a, b, c)) & 0xff;
+					val = rawByte + paeth(a, b, c);
 					break; // Paeth
 				default:
 					throw new LabelError(
@@ -153,18 +219,38 @@ function decodePng(bytes: Uint8Array): DecodedPng {
 						`unsupported PNG scanline filter ${filter}`,
 					);
 			}
-			line[x] = val;
+			line[x] = val & 0xff;
 		}
 		// Expand this decoded scanline into RGBA.
 		for (let x = 0; x < width; x++) {
 			const s = x * channels;
 			const d = (y * width + x) * 4;
-			rgba[d] = line[s]!;
-			rgba[d + 1] = line[s + 1]!;
-			rgba[d + 2] = line[s + 2]!;
-			rgba[d + 3] = channels === 4 ? line[s + 3]! : 255;
+			if (colourType === 3) {
+				const p = sampleAt(line, s) * 3;
+				if (p + 2 >= palette!.length) {
+					throw new LabelError(
+						'unsupported-png',
+						`palette index ${p / 3} is outside the PLTE chunk`,
+					);
+				}
+				rgba[d] = palette![p]!;
+				rgba[d + 1] = palette![p + 1]!;
+				rgba[d + 2] = palette![p + 2]!;
+				rgba[d + 3] = 255;
+			} else if (colourType === 0 || colourType === 4) {
+				const g = scaleGrey(sampleAt(line, s));
+				rgba[d] = g;
+				rgba[d + 1] = g;
+				rgba[d + 2] = g;
+				rgba[d + 3] = colourType === 4 ? sampleAt(line, s + 1) : 255;
+			} else {
+				rgba[d] = sampleAt(line, s);
+				rgba[d + 1] = sampleAt(line, s + 1);
+				rgba[d + 2] = sampleAt(line, s + 2);
+				rgba[d + 3] = colourType === 6 ? sampleAt(line, s + 3) : 255;
+			}
 		}
-		prev.set(line);
+		[prev, line] = [line, prev];
 	}
 
 	return {width, height, rgba};
@@ -201,26 +287,46 @@ export function nearestPaletteIndex(r: number, g: number, b: number): number {
 
 const HEX = '0123456789abcdef';
 
+/**
+ * The integer scale of a PICO-8-shaped screenshot: `k` when the image is exactly
+ * `(128*k)x(128*k)` (128x128 is `k = 1`), else `undefined`. PICO-8's
+ * `extcmd("screen")` writes a pixel-exact upscale (3x by default, 384x384; the
+ * factor follows its `screenshot_scale` config), so any square integer multiple
+ * is a screenshot we can sample straight back down.
+ */
+function labelScale(width: number, height: number): number | undefined {
+	if (width !== height || width < LABEL_SIZE || width % LABEL_SIZE !== 0) {
+		return undefined;
+	}
+	return width / LABEL_SIZE;
+}
+
 /**
  * Builds the `__label__` hex body (128 rows of 128 nibbles, newline-joined, with
- * a trailing newline) from a 128x128 PNG. Each pixel is mapped to its nearest
- * PICO-8 palette colour. The PNG MUST be exactly 128x128 ({@link LABEL_SIZE});
- * anything else is a {@link LabelError} (`wrong-size`) so a mis-sized image fails
- * loud instead of being silently cropped or stretched.
+ * a trailing newline) from a PNG. Each pixel is mapped to its nearest PICO-8
+ * palette colour. The PNG must be 128x128 ({@link LABEL_SIZE}) or an exact square
+ * integer multiple of it (256x256, 384x384, ...: a PICO-8 screenshot), which is
+ * downscaled by nearest-neighbour sampling (the centre of each `k x k` block).
+ * Any other size is a {@link LabelError} (`wrong-size`) so a mis-sized image
+ * fails loud instead of being silently cropped or stretched.
  */
 export function labelHexFromPng(pngBytes: Uint8Array): string {
-	const {width, height, rgba} = decodePng(pngBytes);
-	if (width !== LABEL_SIZE || height !== LABEL_SIZE) {
-		throw new LabelError(
-			'wrong-size',
-			`label image must be ${LABEL_SIZE}x${LABEL_SIZE}, got ${width}x${height}`,
-		);
-	}
+	const {width, height, rgba} = decodePng(pngBytes, (w, h) => {
+		if (labelScale(w, h) === undefined) {
+			throw new LabelError(
+				'wrong-size',
+				`label image must be ${LABEL_SIZE}x${LABEL_SIZE} or an exact multiple of it (256x256, 384x384, 512x512, ...), got ${w}x${h}`,
+			);
+		}
+	});
+	const scale = labelScale(width, height)!;
+	const centre = scale >> 1;
 	const rows: string[] = [];
 	for (let y = 0; y < LABEL_SIZE; y++) {
 		let row = '';
+		const sy = y * scale + centre;
 		for (let x = 0; x < LABEL_SIZE; x++) {
-			const d = (y * LABEL_SIZE + x) * 4;
+			const d = (sy * width + x * scale + centre) * 4;
 			row += HEX[nearestPaletteIndex(rgba[d]!, rgba[d + 1]!, rgba[d + 2]!)];
 		}
 		rows.push(row);

package/src/engine/pico8/session-daemon-entry.ts

@@ -1,5 +1,5 @@
 /**
- * The detached daemon process ENTRY (ADR-0011, prd US #6). `playtest start`
+ * The detached daemon process ENTRY (ADR-0011, spec US #6). `playtest start`
  * spawns this file (via `process.execPath [+ execArgv] <this> <configJson>`, so
  * it re-uses the exact loader the parent ran under, dev `tsx` or built `dist`) as
  * a DETACHED background process that owns the live driven PICO-8 for the session's

package/src/engine/pico8/session-daemon-main.ts

@@ -1,5 +1,5 @@
 /**
- * The playtest session DAEMON ENTRYPOINT (ADR-0011, prd US #6): the small
+ * The playtest session DAEMON ENTRYPOINT (ADR-0011, spec US #6): the small
  * detached process `playtest start` spawns to OWN a live driven PICO-8 for a
  * session's lifetime. It is invoked via the hidden `playtest __daemon` verb (so it
  * re-uses the exact same executable/loader the parent ran under, dev `tsx` or

package/src/engine/pico8/session-daemon.test.ts

@@ -1,4 +1,10 @@
-import {existsSync, mkdtempSync, readFileSync, rmSync} from 'node:fs';
+import {
+	existsSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
@@ -90,6 +96,31 @@ async function waitSocket(): Promise<void> {
 }
 
 describe('session daemon: verb round-trip over the socket (fake process)', () => {
+	it('shot waits for the PNG PICO-8 writes AFTER the ACK, and never returns an older shot', async () => {
+		// Real PICO-8 acks the SHOT (printh) before extcmd("screen") lands on disk.
+		const proc = new FakeDriven();
+		let n = 0;
+		const realWrite = proc.writeStdin.bind(proc);
+		proc.writeStdin = (bytes: Uint8Array) => {
+			realWrite(bytes);
+			if (bytes[0] === OPCODE.shot) {
+				const file = join(paths.shotDir, `play${n++}.png`);
+				setTimeout(() => writeFileSync(file, 'png'), 150);
+			}
+		};
+		startFakeDaemon(proc);
+		await waitSocket();
+		const client = new SessionClient(paths.socket);
+		const first = await client.send({verb: 'shot'});
+		expect(first.ok && first.value.screenshot).toBe(
+			join(paths.shotDir, 'play0.png'),
+		);
+		const second = await client.send({verb: 'shot'});
+		expect(second.ok && second.value.screenshot).toBe(
+			join(paths.shotDir, 'play1.png'),
+		);
+	});
+
 	it('step advances frames and returns the structured result', async () => {
 		startFakeDaemon(new FakeDriven());
 		await waitSocket();

package/src/engine/pico8/session-daemon.ts

@@ -1,5 +1,5 @@
 /**
- * The playtest session DAEMON runtime + CLIENT (ADR-0011, prd US #6). This is the
+ * The playtest session DAEMON runtime + CLIENT (ADR-0011, spec US #6). This is the
  * IO half of the supervisor: the daemon LISTENS on a session's Unix domain socket
  * and drives a live {@link DriveSession} on behalf of each verb sub-invocation;
  * the {@link SessionClient} CONNECTS to that socket to send a verb and read back
@@ -14,7 +14,7 @@
 
 import {spawn} from 'node:child_process';
 import {createConnection, createServer, type Socket} from 'node:net';
-import {existsSync, readdirSync, rmSync, writeFileSync} from 'node:fs';
+import {existsSync, rmSync, writeFileSync} from 'node:fs';
 import {dirname, join} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {
@@ -206,7 +206,10 @@ export function serveSession(options: ServeSessionOptions): {
 				}
 				case 'shot': {
 					const r: ShotResult = await session.shot();
-					const screenshot = collectShot(options.paths.shotDir, r.shotName);
+					const screenshot = await collectShot(
+						options.paths.shotDir,
+						r.shotName,
+					);
 					return ok(options.id, {
 						frame: r.frame,
 						ack: r.ack,
@@ -285,22 +288,27 @@ function ok(
 	return {ok: true, value: {id, ...partial}};
 }
 
+/** How long `shot` waits for PICO-8 to write the PNG after acking the SHOT. */
+const SHOT_FILE_TIMEOUT_MS = 3000;
+const SHOT_FILE_POLL_MS = 20;
+
 /**
- * Resolves the absolute path of the screenshot a SHOT just produced in the
- * `-desktop` dir. The cart named it `<shotName>` (basename) and PICO-8 appends
- * `.png`; if the exact file is not yet visible (a filesystem race) it falls back
- * to the most-recent PNG, so the caller still gets a path to read.
+ * Resolves the screenshot the cart just took: `<shotDir>/<shotName>.png`. The
+ * cart's SHOT ACK is printed BEFORE `extcmd("screen")` lands on disk (verified
+ * on PICO-8 0.2.7), so poll briefly for that exact file. It deliberately never
+ * falls back to "the most recent PNG": that returned the PREVIOUS shot (or
+ * nothing) whenever the new file was still being written. `undefined` only if
+ * the file never appears within {@link SHOT_FILE_TIMEOUT_MS}.
  */
-function collectShot(shotDir: string, shotName: string): string | undefined {
+async function collectShot(
+	shotDir: string,
+	shotName: string,
+): Promise<string | undefined> {
 	const exact = join(shotDir, `${shotName}.png`);
-	if (existsSync(exact)) return exact;
-	try {
-		const pngs = readdirSync(shotDir)
-			.filter((f) => f.toLowerCase().endsWith('.png'))
-			.sort();
-		const last = pngs.at(-1);
-		return last !== undefined ? join(shotDir, last) : undefined;
-	} catch {
-		return undefined;
+	const deadline = Date.now() + SHOT_FILE_TIMEOUT_MS;
+	while (!existsSync(exact)) {
+		if (Date.now() >= deadline) return undefined;
+		await new Promise((r) => setTimeout(r, SHOT_FILE_POLL_MS));
 	}
+	return exact;
 }

package/src/engine/pico8/session.test.ts

@@ -5,7 +5,7 @@ import type {Pico8Process} from './shell.js';
 
 /**
  * The RESUMABLE session HANDSHAKE core is tested WITHOUT the paid PICO-8 binary
- * (ADR-0011, prd US #6): a FAKE driven process lets us assert the load-bearing
+ * (ADR-0011, spec US #6): a FAKE driven process lets us assert the load-bearing
  * transport contract, each verb WRITES its fixed-size command block and WAITS for
  * the cart's ACK before returning (send -> wait-ack -> return), and the failure
  * paths (a lost/late ack, a process that dies mid-command) surface as STRUCTURED

package/src/engine/pico8/session.ts

@@ -1,5 +1,5 @@
 /**
- * The RESUMABLE playtest SESSION handshake core (ADR-0011, prd US #6): the pure,
+ * The RESUMABLE playtest SESSION handshake core (ADR-0011, spec US #6): the pure,
  * CI-testable half of the "A" live model. It keeps a single driven PICO-8 process
  * ALIVE and PAUSED between the agent's turns and drives it one command at a time
  * over the verified transport: write a FIXED-SIZE command block, WAIT for the

package/src/engine/pico8/shell.test.ts

@@ -144,7 +144,7 @@ describe('ShellPico8Adapter: sentinel-driven termination', () => {
 		proc.emit(`${DONE_SENTINEL}\n`);
 		await resultP;
 		expect(spawnArgs).toContain('-home');
-		const home = spawnArgs[spawnArgs.indexOf('-home') + 1];
+		const home = spawnArgs[spawnArgs.indexOf('-home') + 1]!;
 		// Points at an isolated temp dir, NOT the process CWD.
 		expect(home.startsWith(tmpdir())).toBe(true);
 		expect(home).not.toBe(process.cwd());

package/src/engine/pico8/supervisor.ts

@@ -1,5 +1,5 @@
 /**
- * The playtest SESSION SUPERVISOR (ADR-0011, prd US #6): the daemon that keeps a
+ * The playtest SESSION SUPERVISOR (ADR-0011, spec US #6): the daemon that keeps a
  * driven PICO-8 process ALIVE + PAUSED across the agent's separate CLI turns, and
  * the client the per-verb sub-invocations use to address it BY ID.
  *

package/src/engine/scaffold/scaffold.ts

@@ -150,6 +150,21 @@ Two checks that catch the bugs models ship most:
   losing, meaning it is too easy)? does it escalate? is it fair (no unavoidable
   loss)? If you drove a full round and nothing threatened you, tune it before
   calling it done. (The \`game-design-reference\` skill carries these self-checks.)
+- **JUDGE the frame, do not just confirm it drew.** When you look at a gameplay
+  screenshot, actively hunt for what is WRONG, do not narrate that it rendered.
+  "It renders" is NOT "it is good". Ask concretely:
+  - **Readability / contrast:** can you tell EVERY entity apart, from the
+    background AND from each other, at a glance? If a hazard or pickup blends
+    into the scenery (same or near colour), that is a bug, recolour it. Every
+    thing the player must react to has to be instantly distinguishable.
+  - **Layout fairness:** are hazards spaced and placed so a HUMAN can actually
+    clear them (react in ~250ms, not frame-perfect)? Gaps too tight to pass, or
+    an obstacle you cannot see coming, are fairness defects, not difficulty.
+  - **Honest quality:** does it look intentional, or just non-broken? If a
+    player saw this, would the visuals read as deliberate?
+  These are the \`game-design-reference\` readability + fairness lenses applied to
+  the IMAGE you are looking at, not only to the logic. Apply them to the actual
+  frame; fix what fails before calling it done.
 
 A green \`verify\`, a bare \`timeout\`, or a nice-looking title is NOT done.
 

package/src/engine/shrinko/adapter.ts

@@ -26,7 +26,7 @@ export const SHRINKO_NEEDS = ['python>=3.8'] as const;
 
 /**
  * The structured "shrinko is not installed" failure (ADR-0002). Its shape is
- * fixed by the prd's two-tier contract (US #17): `ok:false`, a machine-readable
+ * fixed by the spec's two-tier contract (US #17): `ok:false`, a machine-readable
  * `reason`, the EXACT `remedy` string, and the `needs` list. A command turns
  * this into an incur `error({ code: reason, ... })` with a nonzero exit.
  */

package/src/engine/skills/skills.test.ts

@@ -68,6 +68,12 @@ describe('picopilot skills: generation output (the authored discipline skills)',
 		expect(md).toContain('frame-perfect');
 		// Visibility (draw what you spr()).
 		expect(md).toContain('spr(');
+		// Readability judged on the RENDERED FRAME, not just the code: the
+		// contrast/spacing lens a large model skipped (it confirmed "renders" but
+		// never asked if entities were distinguishable or gaps clearable).
+		expect(md.toLowerCase()).toContain('rendered frame');
+		expect(md.toLowerCase()).toContain('contrast');
+		expect(md.toLowerCase()).toMatch(/distinguish|tell every entity apart/);
 		// Originality is a METHOD with a self-check, and lists NO concrete
 		// mechanics (the answer-menu trap). Assert the caveat that guards it.
 		expect(md.toLowerCase()).toContain('self-check');
@@ -179,6 +185,16 @@ describe('picopilot skills: generation output (the authored discipline skills)',
 		expect(md.toLowerCase()).toContain('offline export');
 	});
 
+	it('picopilot-debug documents a run/playtest screenshot as the export label, as-is', () => {
+		const md = readSkill('picopilot-debug');
+		expect(md).toContain('--label');
+		expect(md).toContain('384x384');
+		expect(md.toLowerCase()).toContain('no image tool');
+		// The zero-image path: capture a frame of the running cart as the label.
+		expect(md).toContain('--label-frame 0');
+		expect(md).toContain('label-frame-not-captured');
+	});
+
 	it('picopilot-debug carries the static-gate + run loop and the dependency boundaries', () => {
 		const md = readSkill('picopilot-debug');
 		expect(md).toContain('picopilot verify');

package/src/skills/game-design-reference/SKILL.md

@@ -41,6 +41,8 @@ If you `spr(n)` an entity, sprite n must actually be DRAWN (a non-empty sprite),
 
 The player must be able to READ the game state at a glance and get FEEDBACK for every action: what am I, what is a hazard, what is a goal, did my input register, did I score or get hit. Motion trails, colour contrast, a HUD, particles/shake/sfx on events, these are not polish for its own sake, they are how the player perceives the state they must act on.
 
+**The self-check (apply it to the RENDERED FRAME, not just the code).** When you look at a gameplay screenshot, judge it, do not just confirm it drew. Looking for what is WRONG: can you tell EVERY entity apart from the background and from each other at a glance (a hazard the same colour as the scenery is a readability bug, recolour it)? is every hazard telegraphed and spaced so a human can react in ~250ms rather than by frame-perfect timing (a gap too tight to pass, or an off-screen hazard, is a fairness defect, not difficulty)? does it look intentional, or merely non-broken? "It renders" is not "it is readable and fair". Apply these lenses to the actual image and fix what fails before calling the game done.
+
 ## Difficulty curve and progression
 
 A good game GOES SOMEWHERE: it escalates. Ramp difficulty by introducing or combining MECHANICS (a new hazard type, a new interaction) over the playthrough, not merely by piling more of the same obstacle. More-of-the-same reads as samey and does not deepen; a new wrinkle does. Aim for a difficulty ARC with a satisfying peak, not a flat loop. Keep the first contact with each new mechanic gentle enough to learn it before it is tested under pressure.

package/src/skills/picopilot-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: picopilot-debug
-description: Close the run-test loop for a PICO-8 cart with picopilot. Run the cart headless and read printh output, use the static verify gate honestly (well-formed is not proven-to-run), and understand the structured pico8-not-found / shrinko-not-found boundaries. Use when a cart misbehaves or you need to confirm it boots.
+description: Close the run-test loop for a PICO-8 cart with picopilot. Run the cart headless and read printh output, use the static verify gate honestly (well-formed is not proven-to-run), understand the structured pico8-not-found / shrinko-not-found boundaries, and export with a screenshot as the label splash. Use when a cart misbehaves, you need to confirm it boots, or you are exporting it.
 ---
 
 # picopilot debug
@@ -181,6 +181,23 @@ NON-deterministic source (wall-clock/entropy) mid-run and so cannot be replayed
 from frame 0. Both drive the SAME cart-side transform; only the host lifecycle
 differs.
 
+## Ship it: `picopilot export` and the label splash
+
+`picopilot export <cart> [dest]` writes a playable `index.html` + `index.js` bundle (requires PICO-8). PICO-8 needs a `__label__` (the loading splash) to export well; a labelless cart gives a blank splash or no bundle at all. Give it one from the game itself, with no image tool. The simplest way captures a frame for you:
+
+```sh
+picopilot export main.p8 out --label-frame 0    # run the cart with no input, use frame 0 (the title screen)
+```
+
+`--label-frame <n>` runs any cart headlessly through the playtest harness with NO input and bakes frame `n` in (0-based: 0 is the first drawn frame); the cart does not need to screenshot itself. Use 0 for the title screen, or a later frame if the title fades in or animates. Check the result: the output's `labelSource` is `frame`, and a cart that never reaches frame `n` fails as `label-frame-not-captured`. To look at a frame BEFORE baking it, a session reproduces it exactly: `playtest start main.p8`, `playtest step <id> --frames <n+1>`, `playtest shot <id>` (not `playtest run`, which presses buttons). With no input it cannot get past the title, so for a GAMEPLAY splash, drive the cart and pass the screenshot you want:
+
+```sh
+picopilot playtest run main.p8 --input "..."     # or: picopilot run main.p8 --shot-dir shots
+picopilot export main.p8 out --label shots/<name>.png   # <name>: a path listed under `screenshots`
+```
+
+Pass the screenshot unchanged. `run` and `playtest` write PICO-8's pixel-exact upscale (384x384 at the default 3x `screenshot_scale`), and `--label` accepts any square multiple of 128 (128x128, 256x256, 384x384, ...) and samples it back down to 128x128. Any 128x128 PNG works too, including palette-indexed and greyscale ones. Do NOT resize or convert it with ImageMagick first: that is never needed, and a resize that is not an exact multiple is rejected (`label-wrong-size`). An existing `__label__` in the cart always wins; `--label` only fills a missing one. `--label` and `--label-frame` never write into your cart (they export a labeled copy), so pass one on every export; passing both is an error. `picopilot serve` (play the build in a browser) takes the same two flags for the same reason, e.g. `picopilot serve main.p8 --label-frame 0`.
+
 ## The two structured boundaries
 
 Both dependency boundaries are soft and well-signposted, so read the result, do