@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/check.js

@@ -0,0 +1,404 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, writeSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { constants } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT, verify } from "./verify.js";
+import { npmTest, test } from "./test.js";
+import { nodeTest } from "../suite/node-run.js";
+import { typecheckTests } from "../suite/test-types.js";
+import { ui } from "../ui.js";
+import { productionMirror } from "../production/mirror.js";
+import { frameContract } from "../frame/contract.js";
+import { withBehaviour } from "../frame/behaviour.js";
+import { idleRun, recordIdle, isFallbackLine } from "../frame/idle.js";
+import { contrastReport, lenient, readLook, LOOK_FILE } from "../look/theme.js";
+import { auditScreens } from "./look.js";
+import { lookHud, HUD_SAMPLING } from "./look-hud.js";
+import { FRONT_DOOR } from "../look/look.js";
+import { boxes } from "./boxes.js";
+import { life } from "./life.js";
+import { look3d, MADE_OF_RECORD } from "./look-3d.js";
+import { walk } from "./walk.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { isWorldGame, worldRead } from "../pipeline/pipeline.js";
+export const CHECK_RECORD = join('.funtools', 'check.json');
+const WORD = { 0: 'passed', 1: 'failed', 2: 'observed nothing', 3: 'could not run' };
+export function measuredLine(r) {
+    const parts = [...r.steps.map((s) => `${s.step} ${WORD[s.exit] ?? `exited ${s.exit}`}`), ...r.measured];
+    return parts.length ? parts.join('; ') : 'nothing yet';
+}
+export function cutShortLine(r, how) {
+    return `check was cut short (${how})${r.now ? ` during ${r.now}` : ''}. Kept, measured before it stopped: ${measuredLine(r)}. Not measured: ${r.now ?? 'the rest'} and what comes after it; run check again (or the step on its own) when the machine is less loaded.`;
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+export function killedRun(dir, alive = pidAlive) {
+    try {
+        const r = JSON.parse(readFileSync(join(dir, CHECK_RECORD), 'utf8'));
+        return r?.state === 'running' && Number.isInteger(r.pid) && r.pid !== process.pid && !alive(r.pid) ? r : null;
+    }
+    catch {
+        return null;
+    }
+}
+function runRecord(dir) {
+    const at = new Date().toISOString();
+    const run = { tool: 'funtools', command: 'check', pid: process.pid, started_at: at, at, state: 'running', now: null, steps: [], measured: [] };
+    const save = () => {
+        run.at = new Date().toISOString();
+        try {
+            mkdirSync(dirname(join(dir, CHECK_RECORD)), { recursive: true });
+            writeFileSync(join(dir, CHECK_RECORD), JSON.stringify(run, null, 2) + '\n');
+        }
+        catch { }
+    };
+    return {
+        run, save,
+        doing: (now) => { run.now = now; save(); },
+        step: (st) => { run.steps.push(st); save(); },
+        world: ((check, done, record) => { if (done) {
+            run.measured.push(record ? `${check} (${record})` : check);
+            run.now = null;
+        }
+        else
+            run.now = check; save(); }),
+        end: () => { run.state = 'done'; run.now = null; save(); },
+    };
+}
+const SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+function onSignals(rec, toStderr) {
+    const handlers = SIGNALS.map((sig) => {
+        const h = () => {
+            rec.run.state = 'cut_short';
+            rec.run.signal = sig;
+            rec.save();
+            try {
+                writeSync(toStderr ? 2 : 1, `funtools check: ${cutShortLine(rec.run, `stopped by ${sig}`)} The record: ${CHECK_RECORD}.\n`);
+            }
+            catch { }
+            process.exit(128 + (constants.signals[sig] ?? 15));
+        };
+        process.on(sig, h);
+        return [sig, h];
+    });
+    return () => { for (const [sig, h] of handlers)
+        process.off(sig, h); };
+}
+const quietIo = { log: () => { }, error: () => { } };
+export const WALK_PEOPLE = 4;
+export const CHECK_WALK_S = 30;
+export function contractPeople(dir) {
+    try {
+        const n = JSON.parse(readFileSync(join(dir, '.funtools', 'life.json'), 'utf8'))?.contract_people;
+        return typeof n === 'number' ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function worldChecks(dir, frontDoor, three, mark = () => { }) {
+    const click = frontDoor ?? FRONT_DOOR;
+    const one = async (name, record, run) => { mark(name, false); await run().catch(() => 3); mark(name, true, record); };
+    if (three)
+        await one('boxes', '.funtools/boxes.json', () => boxes({ target: dir, viewport: 'desktop', json: true, click, views: [] }, quietIo));
+    await one('life', '.funtools/life.json', () => life({ target: dir, viewport: 'desktop', json: true, click, view: null, moment: null }, quietIo));
+    if (three)
+        await one('look --3d', MADE_OF_RECORD, () => look3d({ target: dir, static: true, view: null, click, json: true }, quietIo));
+    if (contractPeople(dir) >= WALK_PEOPLE)
+        await one('walk', '.funtools/walk.json', () => walk({ target: dir, viewport: 'desktop', json: true, click, routes: [], seconds: CHECK_WALK_S, film: false }, quietIo));
+}
+const CUT_HINT = 'a control the player must press, shown whole: a clip-path or overflow on its card cuts what sits at the card\'s edge (inset the buttons, or clip a backdrop layer instead of the card); `funtools audit-screens` names every view';
+export function cutFacts(audit, surface) {
+    if (!audit?.views)
+        return [{ id: 'cut-controls', level: 'not_observed', text: `the screens could not be audited on ${surface} (no build or no browser)` }];
+    const rows = audit.views.flatMap((v) => (v.layout?.clipped?.items ?? []).map((i) => `${v.view}: ${i.name} ${i.side === 'clip' ? `cut by ${i.by ?? 'what it sits in'} (${i.shown}% shown)` : `cut by the ${i.side} edge of the screen`}`));
+    const entered = audit.views.filter((v) => v.verdict !== 'not_observed').length;
+    if (rows.length)
+        return [{ id: 'cut-controls', level: 'warn', text: `${rows.length} control(s) or label(s) cut on ${surface}: ${rows.slice(0, 4).join('; ')}${rows.length > 4 ? '; …' : ''}`, hint: CUT_HINT }];
+    return [entered
+            ? { id: 'cut-controls', level: 'pass', text: `nothing cut or off the screen on ${surface} (${entered} view(s))` }
+            : { id: 'cut-controls', level: 'not_observed', text: `no view could be entered on ${surface} to look for cut controls` }];
+}
+export async function screenFacts(dir) {
+    return cutFacts(await captured((io) => auditScreens({ target: dir, viewport: 'desktop', json: true, click: null, views: [] }, io)), 'desktop');
+}
+function installed(dir) {
+    if (existsSync(join(dir, 'node_modules')))
+        return true;
+    const req = createRequire(join(dir, 'package.json'));
+    return ['typescript/package.json', 'vite/package.json'].some((m) => { try {
+        req.resolve(m);
+        return true;
+    }
+    catch {
+        return false;
+    } });
+}
+export function npmBuild(dir) {
+    if (!installed(dir))
+        return { exit: 127, tail: 'no node_modules: run `npm install` first', notInstalled: true };
+    const r = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', 'build'], { cwd: dir, encoding: 'utf8', timeout: 300_000 });
+    const tail = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim().split('\n').slice(-8).join('\n');
+    return { exit: r.error ? 127 : (r.status ?? 1), tail: r.error ? r.error.message : tail };
+}
+const quiet = { log: () => { }, error: () => { } };
+const DEPS = { build: npmBuild, test, verify, idle: (dir) => idleRun(ui(quiet, 'check'), dir), phoneFacts, world: worldChecks, testTypes: typecheckTests, screens: screenFacts };
+async function captured(run) {
+    const out = [];
+    await run({ log: (m) => out.push(m), error: () => { } }).catch(() => { });
+    try {
+        return JSON.parse(out.join('\n'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function phoneFacts(dir, frontDoor) {
+    const click = frontDoor ?? FRONT_DOOR;
+    const out = [];
+    const audit = await captured((io) => auditScreens({ target: dir, viewport: 'phone', json: true, click: null, views: [] }, io));
+    out.push(...cutFacts(audit, 'phone').filter((f) => f.level === 'warn'));
+    if (!audit?.views)
+        out.push({ id: 'notch-cover', level: 'not_observed', text: 'the phone audit could not run (no build or no browser)' });
+    else {
+        const unsafe = audit.views.flatMap((v) => (v.layout?.unsafe?.items ?? []).map((i) => `${v.view}: ${i.name}${i.side ? ` (${i.side})` : ''}`));
+        out.push(unsafe.length
+            ? { id: 'notch-cover', level: 'warn', text: `${unsafe.length} piece(s) under the notch, the status bar or the home bar on a phone (${audit.viewport}): ${unsafe.slice(0, 4).join('; ')}`, hint: 'inset them by the band: var(--band-top|right|bottom|left), or env(safe-area-inset-*) with the phone floors' }
+            : { id: 'notch-cover', level: 'pass', text: `nothing under the notch or the home bar on a phone (${audit.views.length} view(s), ${audit.viewport})` });
+    }
+    const hud = await captured((io) => lookHud({ target: dir, viewport: 'phone', view: null, verbs: [], samples: 4, everyMs: HUD_SAMPLING.everyMs, click, json: true }, io));
+    if (!hud?.views)
+        out.push({ id: 'safe-band', level: 'not_observed', text: 'the HUD on a phone could not be sampled (no playing view entered)' });
+    else {
+        const cover = hud.views.flatMap((v) => (v.findings ?? []).filter((f) => f.kind === 'cover' || f.kind === 'centre').map((f) => `${v.view}: ${f.what}`));
+        out.push(cover.length
+            ? { id: 'safe-band', level: 'warn', text: `the HUD leaves the band on a phone: ${cover.slice(0, 2).join('; ')}`, hint: 'one slim row in the band; numbers on the actors; the rest behind a tap (skill funpixel-mobile-ui, hud-genres.md)' }
+            : { id: 'safe-band', level: 'pass', text: `the HUD stays in the band on a phone (${hud.viewport})` });
+        if (hud.controls_duplicate_gesture === true)
+            out.push({ id: 'gesture-input', level: 'warn', text: 'an on-screen pad repeats the play\'s own swipe on a phone', hint: 'the swipe is the control; a pad is a setting, off by default' });
+    }
+    return out;
+}
+export function overall(steps) {
+    const exits = steps.map((s) => s.exit);
+    if (exits.includes(EXIT.error) || exits.some((e) => e > 3))
+        return EXIT.error;
+    if (exits.includes(EXIT.fail))
+        return EXIT.fail;
+    if (exits.includes(EXIT.not_observed))
+        return EXIT.not_observed;
+    return EXIT.pass;
+}
+export async function check(opts, io = console, deps = {}) {
+    const dir = resolve(opts.target ?? '.');
+    const u = ui(io, 'check');
+    if (!opts.json)
+        u.heading(`check · ${dir}`);
+    const killed = killedRun(dir);
+    if (killed && !opts.json)
+        u.item('warn', cutShortLine(killed, 'killed: no ending was written, as when the system stops it under load, exit 137'), `its records are kept (${CHECK_RECORD}); this run measures again`);
+    const rec = runRecord(dir);
+    rec.save();
+    const off = onSignals(rec, !!opts.json);
+    try {
+        const exit = await checkRun(opts, io, deps, dir, u, rec, killed);
+        rec.end();
+        return exit;
+    }
+    catch (e) {
+        rec.run.state = 'cut_short';
+        rec.run.signal = 'an error';
+        rec.save();
+        throw e;
+    }
+    finally {
+        off();
+    }
+}
+async function checkRun(opts, io, deps, dir, u, rec, killed) {
+    const d = { ...DEPS, ...deps };
+    const steps = [];
+    let testTypesSeen = null;
+    const say = (s) => { steps.push(s); rec.step(s); if (!opts.json)
+        u.item(s.exit === 0 ? 'pass' : s.exit === EXIT.not_observed ? 'not_observed' : 'fail', `${s.step}: ${s.detail}`); };
+    const cutShort = killed ? { cut_short: { started_at: killed.started_at, during: killed.now, measured: measuredLine(killed) } } : {};
+    rec.doing('build');
+    if (existsSync(join(dir, 'package.json'))) {
+        const b = d.build(dir);
+        if (b.notInstalled) {
+            say({ step: 'build', exit: EXIT.error, detail: 'no node_modules: the dependencies are not installed' });
+            return finish(u, io, opts, steps, `run \`npm install\` in ${dir} first, then check again`);
+        }
+        say({ step: 'build', exit: b.exit === 0 ? 0 : b.exit === 127 ? EXIT.error : EXIT.fail, detail: b.exit === 0 ? 'npm run build passed' : `npm run build exited ${b.exit}` });
+        if (b.exit !== 0) {
+            if (!opts.json)
+                for (const l of b.tail.split('\n'))
+                    u.line(l, 2);
+            return finish(u, io, opts, steps, 'the build failed: fix it, then run check again (verify would judge an old build)');
+        }
+    }
+    else
+        say({ step: 'build', exit: 0, detail: 'no package.json: served as it is' });
+    if (!opts.noTest) {
+        rec.doing('the rules suite');
+        let script = '';
+        try {
+            script = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).scripts?.test ?? '';
+        }
+        catch { }
+        const types = d.testTypes ? d.testTypes(dir) : null;
+        const stale = types?.state === 'fail' ? `; ${types.says}` : '';
+        if (!script || /no test specified/.test(script))
+            say({ step: 'test', exit: stale ? EXIT.fail : 0, detail: `no test script: skipped (skill funpixel-game-logic has the rules suite)${stale}` });
+        else {
+            const t = await d.test({ target: dir, json: true }, quiet, { npm: (g) => npmTest(g, true, true), node: (g) => nodeTest(g, true, true) });
+            say({ step: 'test', exit: stale && t !== EXIT.error ? EXIT.fail : t, detail: `${t === 0 ? 'the rules suite passed (.funtools/tests.json)' : t === EXIT.fail ? 'the rules suite failed: `funtools test` shows which' : 'the rules suite could not run: `funtools test` says why'}${stale}` });
+        }
+        if (types?.state === 'fail' && !opts.json)
+            for (const e of types.errors.slice(0, 6))
+                u.line(e, 2);
+        if (types)
+            testTypesSeen = types;
+    }
+    const lines = [];
+    const viewport = opts.phone && (opts.viewport ?? 'desktop') === 'desktop' ? 'both' : opts.viewport ?? 'desktop';
+    rec.doing('verify');
+    const v = await d.verify({ target: dir, sweep: true, viewport, frontDoor: opts.frontDoor ?? null }, opts.json ? quiet : { log: (m) => lines.push(m), error: (m) => lines.push(m) });
+    say({ step: 'verify', exit: v, detail: ['passed (verify.json)', 'failed', 'observed nothing: not a pass', 'could not run'][v] ?? `exited ${v}` });
+    if (!opts.json && v !== 0)
+        for (const l of lines.slice(-12))
+            u.line(l, 2);
+    const m = productionMirror(dir);
+    if (!opts.json)
+        printMirror(u, m);
+    const frame = withBehaviour(frameContract(dir), dir);
+    const look = lookFacts(dir);
+    let idle = null;
+    if (!opts.noIdle && v !== EXIT.error) {
+        rec.doing('the idle run');
+        const r = await d.idle(dir);
+        if (typeof r !== 'number') {
+            idle = r;
+            await recordIdle(dir, r).catch(() => { });
+        }
+    }
+    let screens = [];
+    if (v !== EXIT.error && d.screens) {
+        rec.doing('the screens');
+        screens = await d.screens(dir);
+    }
+    if (opts.phone && v !== EXIT.error)
+        rec.doing('the phone measures');
+    const phone = opts.phone && v !== EXIT.error ? await d.phoneFacts(dir, opts.frontDoor ?? null) : [];
+    const kind = isWorldGame(dir);
+    let world = null;
+    let heroes = null;
+    if ((opts.world ?? kind.world) && opts.world !== false && v !== EXIT.error && d.world) {
+        await d.world(dir, opts.frontDoor ?? null, kind.three, rec.world);
+        const fp = (await fingerprint(dir).catch(() => null))?.fingerprint ?? null;
+        world = worldRead(dir, fp);
+        if (kind.three)
+            heroes = heroesRead(dir, fp);
+    }
+    const facts = { frame, look: { ...look, page_fallbacks: idle?.frame_lines.filter(isFallbackLine) ?? [] }, idle, phone, world, heroes, test_types: testTypesSeen, screens };
+    if (!opts.json)
+        printFacts(u, facts, !!opts.noIdle);
+    return finish(u, io, opts, steps, undefined, m, { ...facts, ...cutShort });
+}
+export function heroesRead(dir, fp) {
+    try {
+        const r = JSON.parse(readFileSync(join(dir, MADE_OF_RECORD), 'utf8'));
+        if (fp && r?.fingerprint && r.fingerprint !== fp)
+            return null;
+        return { verdict: String(r?.verdict ?? 'not_observed'), says: String(r?.says ?? '') };
+    }
+    catch {
+        return null;
+    }
+}
+export function lookFacts(dir) {
+    const f = readLook(dir);
+    if (!f.exists)
+        return { file: null, fallbacks: [], pairs: [] };
+    if (f.parseError)
+        return { file: LOOK_FILE, fallbacks: [`[frame] look fallback: ${LOOK_FILE} does not parse (${f.parseError}); the stylesheet renders every token`], pairs: [] };
+    const { applied, fallbacks } = lenient(f.look);
+    return { file: LOOK_FILE, fallbacks, pairs: contrastReport(applied) };
+}
+function printFacts(u, f, noIdle) {
+    u.heading('frame · needs → systems');
+    const kit = f.frame.filter((r) => r.state === 'kit');
+    if (kit.length)
+        u.item('pass', `${kit.length} part(s) as the starter wrote them: ${kit.map((r) => r.id).join(', ')}`);
+    for (const r of f.frame.filter((x) => x.state === 'own'))
+        u.item('pass', `${r.id}: your own part keeps it — ${r.measured ? `measured: ${r.measured}` : r.need}`);
+    for (const r of f.frame.filter((x) => x.state === 'lost'))
+        u.item('warn', `${r.id}: ${r.replaced.length ? `the replacement (${r.replaced.join(', ')}) lost a basic` : 'missing'} — ${r.measured ? `measured: ${r.measured}` : r.need}`, r.hint);
+    for (const p of f.screens ?? [])
+        u.item(p.level, `${p.id}: ${p.text}`, p.hint);
+    for (const p of f.phone)
+        u.item(p.level, `${p.id} (phone): ${p.text}`, p.hint);
+    if (f.look.file) {
+        u.heading(`look · ${f.look.file}`);
+        const token = (l) => l.slice(l.indexOf(':') + 1).trim().split(':')[0];
+        const named = new Set(f.look.fallbacks.map(token));
+        for (const l of [...f.look.fallbacks, ...f.look.page_fallbacks.filter((l) => !named.has(token(l)))])
+            u.item('warn', l, 'funtools look report names the closest token; look set refuses it');
+        for (const p of f.look.pairs.filter((x) => x.pass === false))
+            u.item('warn', `${p.pair} ${p.ratio}:1, needs ${p.need} — ${p.what}`, p.ink ? `propose ${p.ink} (${p.ink_ratio}:1): funtools look set ${p.pair.split(' on ')[0]}=${p.ink}` : p.note);
+        const good = f.look.pairs.filter((x) => x.pass === true).length;
+        if (good)
+            u.item('pass', `${good} text/background pair(s) read`);
+    }
+    else if (f.look.page_fallbacks.length)
+        for (const l of f.look.page_fallbacks)
+            u.item('warn', l);
+    u.heading('idle run · no input after Play');
+    if (noIdle)
+        u.item('skip', 'skipped (--no-idle)');
+    else if (!f.idle)
+        u.item('not_observed', 'the idle run could not run (no build or no browser)');
+    else
+        for (const x of f.idle.findings)
+            u.item(x.level, x.text, x.hint);
+    if (f.world) {
+        u.heading('world · made, grounded, alive (boxes + life; the slice gate reads this)');
+        if (f.world.state === 'met')
+            u.item('pass', f.world.says);
+        else if (!f.world.warns.length)
+            u.item('not_observed', f.world.says, 'funtools boxes / funtools life say why; funtools walk films a route from the title');
+        for (const w of f.world.warns.slice(0, 8))
+            u.item('warn', w);
+        if (f.world.warns.length > 8)
+            u.item('warn', `…and ${f.world.warns.length - 8} more: .funtools/life.json, .funtools/boxes.json`);
+    }
+    if (f.heroes) {
+        const m = f.heroes.verdict === 'pass' ? 'pass' : f.heroes.verdict === 'fail' ? 'warn' : 'not_observed';
+        u.item(m, `heroes (look --3d): ${f.heroes.says}`, f.heroes.verdict === 'fail' ? 'holds the hand-back: the hero route (skill funpixel-3d, references/hero-route.md), or funpixel.json "art3d" { "heroes": "procedural", "why", "proof" }' : undefined);
+    }
+}
+function printMirror(u, m) {
+    u.heading(`production · ${m.tier}${m.recorded ? '' : ' (from the GDD)'}`);
+    if (m.suggested)
+        u.item('note', `the GDD now reads as a ${m.suggested} game`, 'set funpixel.json production.tier if so: the dial turns up direct, keep consistent and verify (references/production-tiers.md)');
+    for (const l of m.lines)
+        u.item(l.level, `${l.loop}: ${l.text}`, l.hint);
+    if (!m.lines.length)
+        u.item('pass', 'nothing to note at this tier');
+}
+function finish(u, io, opts, steps, why, production, facts) {
+    const exit = overall(steps);
+    if (opts.json)
+        io.log(JSON.stringify({ exit, steps, ...(production ? { production } : {}), ...(facts ?? {}) }, null, 2));
+    else
+        u.summary(exit === 0 ? 'pass' : exit === EXIT.not_observed ? 'not_observed' : 'fail', why ?? (exit === 0 ? 'built, tested and verified' : `${steps.filter((s) => s.exit !== 0).map((s) => s.step).join(', ')} did not pass`));
+    return exit;
+}

package/dist/commands/clip.js

@@ -0,0 +1,112 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { decodePng, encodePng } from "../look/png.js";
+import { contactSheet } from "../playtest/sheet.js";
+import { premiseOf } from "../playtest/prepare.js";
+import { CLIP_AXES, CLIP_PERSONAS, CLIP_SEATS, clipMeans, clipPrompt, framesIn, readClipVerdict, reelMarks, windows, } from "../clip/clip.js";
+import { ui } from "../ui.js";
+export const CLIP_DIR = join('.funtools', 'clip');
+const runs = (root) => (existsSync(join(root, CLIP_DIR)) ? readdirSync(join(root, CLIP_DIR)).filter((d) => /^\d+$/.test(d)).map(Number).sort((a, b) => a - b) : []);
+export async function clip(opts, io = console) {
+    return opts.sub === 'report' ? report(opts, io) : prepare(opts, io);
+}
+async function prepare(opts, io) {
+    const u = ui(io, 'clip');
+    const root = resolve(opts.dir);
+    const src = resolve(opts.frames ?? join(root, '.funtools', 'reel', 'frames'));
+    const files = framesIn(src);
+    if (!files.length) {
+        const why = `no frames in ${src}`;
+        if (opts.json)
+            io.log(JSON.stringify({ ready: false, reason: why }, null, 2));
+        else
+            u.summary('not_observed', `${why} — film some play first: npx @funpixel/tools reel --frames-only (or --frames <dir of PNGs>)`);
+        return EXIT.not_observed;
+    }
+    const seats = opts.seats?.length ? opts.seats : CLIP_SEATS;
+    const unknown = seats.filter((s) => !CLIP_PERSONAS[s]);
+    if (unknown.length) {
+        u.error(`unknown seat: ${unknown.join(', ')}`, `the seats are ${CLIP_SEATS.join(', ')}`);
+        return EXIT.error;
+    }
+    const { fps: reelFps, marks } = reelMarks(src);
+    const fps = opts.fps ?? reelFps ?? 12;
+    const ws = windows(files.length, marks);
+    const n = (runs(root).at(-1) ?? 0) + 1;
+    const out = join(root, CLIP_DIR, String(n));
+    await mkdir(out, { recursive: true });
+    const strips = [];
+    for (const [i, w] of ws.entries()) {
+        const frames = [];
+        for (let f = w.from; f <= w.to; f++)
+            frames.push(decodePng(await readFile(join(src, files[f]))));
+        const file = join(out, `strip-${i + 1}.png`);
+        await writeFile(file, encodePng(contactSheet(frames, 4, 360)));
+        strips.push({ file, why: `${w.why}; frames ${w.from + 1}–${w.to + 1} of ${files.length}`, frames: [w.from + 1, w.to + 1] });
+    }
+    let manifest = {};
+    try {
+        manifest = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'));
+    }
+    catch { }
+    const premise = premiseOf(root, manifest);
+    const prompts = [];
+    for (const s of seats) {
+        const file = join(out, `seat-${s}.md`);
+        await writeFile(file, clipPrompt(s, premise.text, strips, 1000 / fps, join(out, `answer-${s}.json`)));
+        prompts.push(file);
+    }
+    const plan = { n, at: new Date().toISOString(), source: src, fps, frames: files.length, marks: marks.length, strips, seats, prompts, premise };
+    await writeFile(join(out, 'plan.json'), JSON.stringify(plan, null, 2) + '\n');
+    if (opts.json) {
+        io.log(JSON.stringify({ ready: true, dir: out, ...plan }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`clip ${n} · ${files.length} frames at ${fps} fps · ${marks.length} payoff mark(s)`);
+    for (const [i, s] of strips.entries())
+        u.item('pass', `strip-${i + 1}`, s.why);
+    if (premise.draft)
+        u.item('warn', 'premise', `a draft from funpixel.json — write the store description in ${join('.funtools', 'playtest', 'premise.txt')}`);
+    u.item('note', 'seats', `run each prompt in a fresh agent (no other context), then \`funtools clip report\`: ${prompts.join(' · ')}`);
+    u.summary('pass', `ready — ${seats.length} seat(s), no model called`);
+    return EXIT.pass;
+}
+async function report(opts, io) {
+    const u = ui(io, 'clip');
+    const root = resolve(opts.dir);
+    const n = runs(root).at(-1);
+    if (!n) {
+        u.summary('not_observed', 'no clip here yet — funtools clip first');
+        return EXIT.not_observed;
+    }
+    const out = join(root, CLIP_DIR, String(n));
+    const plan = JSON.parse(readFileSync(join(out, 'plan.json'), 'utf8'));
+    const got = [], missing = [];
+    for (const s of plan.seats) {
+        const r = readClipVerdict(join(out, `answer-${s}.json`), s);
+        if (r.verdict)
+            got.push(r.verdict);
+        else
+            missing.push(`${s}: ${r.problem}`);
+    }
+    const means = clipMeans(got);
+    if (opts.json) {
+        io.log(JSON.stringify({ n, means, verdicts: got, missing }, null, 2));
+        return got.length ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`clip ${n} · ${got.length} of ${plan.seats.length} seat(s) filed`);
+    if (got.length)
+        u.item('pass', 'means', CLIP_AXES.map((a) => `${a} ${means[a]}`).join(' · '));
+    for (const v of got) {
+        u.item('note', v.critic, CLIP_AXES.map((a) => `${a} ${v.scores[a]}`).join(' · '));
+        for (const k of ['best', 'worst', 'fixFirst'])
+            for (const l of (v[k] ?? []).slice(0, 2))
+                u.line(`  ${k}: ${l}`);
+    }
+    for (const m of missing)
+        u.item('not_observed', m);
+    u.summary(got.length ? 'pass' : 'not_observed', got.length ? 'the seats\' words on motion — evidence, not a verdict' : 'nothing filed');
+    return got.length ? EXIT.pass : EXIT.not_observed;
+}