@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/publish.js

@@ -0,0 +1,165 @@
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { fingerprintOf, stagedEntries } from "../verify/fingerprint.js";
+import { apiKey } from "../keys/store.js";
+import { findBuild, overLimits } from "../publish/build.js";
+import { copyBuild, folderRefusal } from "../publish/folder.js";
+import { butlerPush, itchTarget, LIMITS, pagesProject, runHost, wranglerDeploy } from "../publish/hosts.js";
+import { printVerification, readManifest, upload } from "../publish/funpixel.js";
+import { kb } from "../pack/limits.js";
+import { scanFile } from "../pack/leaks.js";
+import { askYes, ui } from "../ui.js";
+export const TARGETS = ['funpixel', 'itch', 'pages', 'folder'];
+export const LOG = '.funtools/publish.jsonl';
+export async function recordRefusal(dir) {
+    const recordPath = join(dir, 'verify.json');
+    if (!existsSync(recordPath))
+        return 'no verify.json — run `npx @funpixel/tools verify` first';
+    let record;
+    try {
+        record = JSON.parse(await readFile(recordPath, 'utf8'));
+    }
+    catch {
+        return 'verify.json is not valid JSON — verify again';
+    }
+    if (record.fingerprint !== fingerprintOf(await stagedEntries(dir))) {
+        return 'verify.json is stale: the files changed since verify ran — verify again';
+    }
+    if (record.verdict === 'fail')
+        return 'the last verify FAILED — fix what it reported, verify again, then publish';
+    return null;
+}
+async function log(dir, entry) {
+    await mkdir(join(dir, '.funtools'), { recursive: true });
+    await appendFile(join(dir, LOG), JSON.stringify({ at: new Date().toISOString(), ...entry }) + '\n');
+}
+export async function publish(opts, io = console) {
+    const dir = resolve(opts.target ?? '.');
+    const to = opts.to ?? 'funpixel';
+    const u = ui(io, 'publish');
+    const refuse = (what, next) => {
+        if (opts.json)
+            io.log(JSON.stringify({ ok: false, target: to, error: what, next }, null, 2));
+        u.error(what, next);
+        return 3;
+    };
+    const key = to === 'funpixel' ? apiKey() : null;
+    if (to === 'funpixel' && !key)
+        return refuse('no API key', 'run `npx @funpixel/tools login --key fp_live_…` or set FUNPIXEL_API_KEY (Settings › Developers, paid plans)');
+    const refusal = await recordRefusal(dir);
+    if (refusal) {
+        const [what, next] = refusal.split(' — ');
+        return refuse(what, next);
+    }
+    const record = JSON.parse(await readFile(join(dir, 'verify.json'), 'utf8'));
+    if (!opts.json)
+        u.heading(`publish ${to} · ${dir}`);
+    if (to === 'funpixel') {
+        const leak = await firstLeak(dir);
+        if (leak)
+            return refuse(leak, 'remove it (or list it in .harnessignore), verify again, then publish');
+        const res = await upload(dir, key, record, { name: opts.name, gameId: opts.gameId }, opts.json ? null : u);
+        await log(dir, { target: 'funpixel', game_id: res.reply.game_id ?? opts.gameId ?? null, http_status: res.status, code: res.reply.code ?? null, verdict: record.verdict, fingerprint: record.fingerprint, url: res.reply.play_url ?? res.reply.preview_url ?? null, done: res.ok });
+        if (opts.json) {
+            io.log(JSON.stringify({ ...res.reply, ok: res.ok, target: 'funpixel', http_status: res.status }, null, 2));
+            return res.ok ? 0 : 1;
+        }
+        if (!res.ok) {
+            u.error(`the server refused the upload (${res.status}${res.reply.code ? ` ${res.reply.code}` : ''}): ${res.reply.error ?? ''}`.trim(), 'fix what it names, verify again, publish again');
+            return 1;
+        }
+        printVerification(u, res.reply.verification);
+        if (res.reply.live_unchanged)
+            u.item('note', 'players still get the published version — publish it from the game page to ship this build');
+        if (!res.reply.play_url && !res.reply.preview_url)
+            u.item('note', "no address to load yet (a draft's link is on its game page in the app); the server's verify above is the render check, and publishing again will not make one");
+        u.summary('pass', `draft ${res.reply.game_id ?? ''}${res.reply.replaced ? ' (updated in place)' : ''} ${res.reply.play_url ?? res.reply.preview_url ?? ''}`.trim());
+        return 0;
+    }
+    const build = await findBuild(dir);
+    if (typeof build === 'string')
+        return refuse(...build.split(' — '));
+    if (build.problems.length)
+        return refuse(`${build.root} is not a clean build: ${build.problems.slice(0, 3).join('; ')}`, 'publish ships the built dist/ only — rebuild, and keep sources and secrets out of it');
+    return other(to, dir, build, record, opts, io, u, refuse);
+}
+export async function firstLeak(dir) {
+    for (const { path, bytes } of await stagedEntries(dir)) {
+        const leak = scanFile(path, bytes).find((f) => f.level === 'leak');
+        if (leak)
+            return `${leak.path}: ${leak.what}`;
+    }
+    return null;
+}
+async function other(to, dir, build, record, opts, io, u, refuse) {
+    let command = null;
+    let where;
+    if (to === 'itch') {
+        const target = itchTarget(opts.itch);
+        if (!target)
+            return refuse('itch needs the game page', 'pass --itch <user>/<game>[:channel] (make the page once at itch.io/game/new, Kind: HTML)');
+        command = butlerPush(build.root, target);
+        where = `itch.io ${target}`;
+    }
+    else if (to === 'pages') {
+        const manifest = await readManifest(dir);
+        const project = pagesProject(opts.project ?? (typeof manifest?.name === 'string' ? manifest.name : basename(dir)));
+        command = wranglerDeploy(build.root, project);
+        where = `Cloudflare Pages project ${project} (read the address wrangler prints — a taken name gets another)`;
+    }
+    else {
+        if (!opts.out)
+            return refuse('folder needs a destination', 'pass --out <folder> — a new folder outside the game');
+        const why = await folderRefusal(dir, opts.out);
+        if (why)
+            return refuse(why, 'choose a new, empty folder outside the game');
+        where = resolve(opts.out);
+    }
+    const limits = to === 'folder' ? [] : overLimits(build, LIMITS[to]);
+    if (limits.length)
+        return refuse(`the host would refuse this build: ${limits.slice(0, 3).join('; ')}`, 'make the build smaller (funtools pack lists every file)');
+    const entry = { target: to, where, files: build.files.length, bytes: build.bytes, verdict: record.verdict, fingerprint: record.fingerprint, command: command?.shown ?? null };
+    if (!opts.json) {
+        u.item('note', `${build.files.length} file(s), ${kb(build.bytes)} from ${build.root}`);
+        u.item('note', `to ${where}`);
+        if (command)
+            u.line(command.shown, 2);
+    }
+    const handOver = async (why) => {
+        await log(dir, { ...entry, done: false, why });
+        if (opts.json)
+            io.log(JSON.stringify({ ok: false, prepared: true, ...entry, why }, null, 2));
+        else
+            u.summary('skip', `not published — ${why}${command ? `; run it yourself: ${command.shown}` : ''}`);
+        return 2;
+    };
+    if (command?.blocked)
+        return handOver(command.blocked);
+    const approved = opts.yes || (!opts.json && (await askYes(io, u, `publish ${build.files.length} file(s) to ${where}? What is published stays published.`)));
+    if (!approved)
+        return handOver('it needs your approval: rerun with --yes, or answer y at the prompt');
+    if (to === 'folder') {
+        const r = await copyBuild(build, opts.out);
+        if (typeof r === 'string')
+            return refuse(r, 'nothing was written');
+        await log(dir, { ...entry, done: true, removed: r.removed, kept: r.kept });
+        if (opts.json) {
+            io.log(JSON.stringify({ ok: true, ...entry, removed: r.removed, kept: r.kept }, null, 2));
+            return 0;
+        }
+        for (const k of r.kept)
+            u.item('warn', `left ${k}`, 'funtools wrote it once, someone changed it since');
+        u.summary('pass', `copied ${r.written} file(s) to ${r.dest}${r.removed.length ? `, removed ${r.removed.length} stale file(s) it had written` : ''}`);
+        return 0;
+    }
+    const code = runHost(command);
+    await log(dir, { ...entry, done: code === 0, exit: code });
+    if (opts.json)
+        io.log(JSON.stringify({ ok: code === 0, ...entry, exit: code }, null, 2));
+    else if (code === 0)
+        u.summary('pass', `published to ${where}`);
+    else
+        u.error(`${command.program} exited ${code}`, 'read its output above; nothing is retried');
+    return code === 0 ? 0 : 1;
+}

package/dist/commands/reach.js

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { describe } from "../reach/envelope.js";
+import { readConfig, runReach, DEFAULT_LEVELS } from "../reach/load.js";
+import { gapText } from "../reach/side.js";
+import { ui, verdictWord } from "../ui.js";
+export const REACH_FILE = join('.funtools', 'reach.json');
+const SHOWN = 16;
+export async function reach(opts, io = console) {
+    const u = ui(io, 'reach');
+    const root = resolve(opts.target ?? '.');
+    if (!existsSync(root)) {
+        u.error(`no such folder: ${root}`);
+        return EXIT.error;
+    }
+    let run;
+    const cfg = readConfig(root, opts.levels);
+    try {
+        run = runReach(root, cfg);
+    }
+    catch (e) {
+        u.error(`reach failed: ${e.message}`);
+        return EXIT.error;
+    }
+    const { levels, skipped } = run;
+    const verdict = levels.some((l) => l.verdict === 'fail') ? 'fail' : !levels.length || levels.some((l) => l.verdict === 'not_observed') ? 'not_observed' : 'pass';
+    const record = {
+        tool: 'funtools', command: 'reach', at: new Date().toISOString(), verdict, levels_from: cfg.from,
+        movement: { tiles: run.envelope2d.envelope, metres: run.envelope3d.envelope, why: run.envelope2d.declared ? null : run.envelope2d.why },
+        sealed: cfg.sealed, levels, skipped,
+    };
+    await mkdir(join(root, '.funtools'), { recursive: true });
+    await writeFile(join(root, REACH_FILE), JSON.stringify(record, null, 2) + '\n');
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return EXIT[verdict];
+    }
+    u.heading(`reach · ${root}`);
+    const kinds = new Set(levels.map((l) => l.kind));
+    if (run.envelope2d.envelope && kinds.has('side'))
+        u.item('note', `movement (tiles): ${describe(run.envelope2d.envelope, 'tiles')}`, run.envelope2d.envelope.from.join(', '));
+    if (kinds.has('3d')) {
+        if (run.envelope3d.envelope)
+            u.item('note', `movement (metres): ${describe(run.envelope3d.envelope, 'm')}`, run.envelope3d.envelope.from.join(', '));
+        else
+            u.item('not_observed', 'movement not declared: 3D levels are walked, not jumped', run.envelope3d.declared ? undefined : run.envelope3d.why);
+    }
+    for (const s of skipped)
+        u.item('warn', `${s.file}: ${s.why}`);
+    if (!levels.length) {
+        u.summary('not_observed', `${verdictWord('not_observed')} — no level data: ${cfg.from === 'default' ? `nothing at ${DEFAULT_LEVELS.join(' or ')}` : 'the files named hold no level'}; name them in funpixel.json "reach": { "levels": […] } (skill funpixel-game-logic, references/levels.md)`);
+        return EXIT.not_observed;
+    }
+    for (const l of levels) {
+        u.heading(`${l.file}${l.name !== l.file ? ` · ${l.name}` : ''} (${l.kind === '3d' ? '3D spec' : `${l.kind} view`}, ${l.size}): ${verdictWord(l.verdict)}`);
+        const shown = [...l.findings.filter((f) => f.status !== 'pass'), ...l.findings.filter((f) => f.status === 'pass')];
+        for (const f of shown.slice(0, SHOWN))
+            u.item(f.status, f.what, f.why);
+        if (shown.length > SHOWN)
+            u.line(`… and ${shown.length - SHOWN} more in ${REACH_FILE}`, 2);
+        for (const g of l.gaps)
+            u.line(`gap ${gapText(g, l.kind === '3d' ? 'm' : 'tiles')}`, 2);
+    }
+    const failed = levels.filter((l) => l.verdict === 'fail').length;
+    const unseen = levels.filter((l) => l.verdict === 'not_observed').length;
+    u.summary(verdict, verdict === 'pass' ? `${verdictWord('pass')} — every target in ${levels.length} level${levels.length > 1 ? 's' : ''} reached (${REACH_FILE})`
+        : verdict === 'fail' ? `${verdictWord('fail')} — ${failed} of ${levels.length} level${levels.length > 1 ? 's have' : ' has'} a target the player cannot reach`
+            : `${verdictWord('not_observed')} — ${unseen} of ${levels.length} level${levels.length > 1 ? 's' : ''} could not be judged: not a pass`);
+    return EXIT[verdict];
+}

package/dist/commands/reel.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pageScript } from '../vendor/verify/src/index.js';
+import { EXIT, servedRoot } from "./verify.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { serveDir } from "../verify/serve.js";
+import { launch, lookPage, viewportUrl, webglAvailable } from "../verify/browser.js";
+import { evalJson } from "../look/look.js";
+import { armMoments, drainMoments, pageNow, placeMarks } from "../look/moments.js";
+import { Touch } from "../look/touch.js";
+import { encode, ffmpegBin, frameName } from "../reel/encode.js";
+import { checkedVerbs, enterView, inputAt, planTour, press, readDeclared } from "../reel/tour.js";
+import { ui } from "../ui.js";
+export const REEL_LIMITS = { seconds: [3, 60], fps: [5, 30] };
+const BOOT_MS = 1500;
+const sleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
+async function film(page, url, hooks, checkVerbs, opts, viewport, framesDir) {
+    if (opts.cues)
+        await page.addInitScript(`(${pageScript('audio_cues', { op: 'install' })})()`);
+    await page.goto(viewportUrl(url, viewport), { waitUntil: 'load' });
+    await page.evaluate(`(${pageScript('first_paint')})()`).catch(() => { });
+    if (hooks)
+        await page.evaluate(`(${pageScript('hooks', { map: hooks })})()`).catch(() => { });
+    await sleep(BOOT_MS);
+    await armMoments(page);
+    const total = Math.round(opts.seconds * opts.fps);
+    const tour = planTour(await readDeclared(page), checkVerbs, total, opts.fps);
+    const touch = viewport === 'phone' && tour.driven === 'keys' ? await Touch.open(page) : null;
+    const size = page.viewportSize() ?? { width: 1280, height: 720 };
+    const interval = 1000 / opts.fps;
+    const seen = new Set();
+    const times = [];
+    let n = 0;
+    for (const seg of tour.segments) {
+        if (seg.view) {
+            await enterView(page, seg.view);
+            await sleep(250);
+        }
+        for (let i = 0; i < seg.frames; i++, n++) {
+            const started = Date.now();
+            const input = seg.play ? inputAt(tour, i, opts.fps) : null;
+            if (input)
+                await press(page, tour, input, touch);
+            times.push(await pageNow(page));
+            const png = await page.screenshot({ type: 'png' });
+            seen.add(createHash('sha1').update(png).digest('hex'));
+            await writeFile(join(framesDir, frameName(n)), png);
+            await sleep(interval - (Date.now() - started));
+        }
+    }
+    await touch?.release();
+    const marks = placeMarks(times, await drainMoments(page));
+    await writeFile(join(framesDir, 'moments.json'), JSON.stringify({ frames: n, fps: opts.fps, marks }, null, 2) + '\n');
+    const cues = opts.cues ? await drainCues(page) : [];
+    return { frames: n, distinct: seen.size, landscape: size.width > size.height, width: size.width, height: size.height, tour, marks, touch: !!touch, frameTimes: times, cues };
+}
+async function drainCues(page) {
+    const j = await evalJson(page, 'audio_cues', { op: 'drain' });
+    return Array.isArray(j?.cues) ? j.cues : [];
+}
+export async function filmWithRetry(url, hooks, checkVerbs, opts, viewport, orientation, framesDir) {
+    for (const software of [false, true]) {
+        let browser;
+        try {
+            browser = (await launch(software)).browser;
+            const page = await lookPage(browser, viewport, orientation);
+            if (!software && !(await webglAvailable(page)))
+                continue;
+            return { ...(await film(page, url, hooks, checkVerbs, opts, viewport, framesDir)), softwareGl: software };
+        }
+        finally {
+            await browser?.close().catch(() => { });
+        }
+    }
+    throw new Error('no browser could film the game');
+}
+export async function openGame(target, viewportOpt) {
+    const isUrl = /^https?:\/\//.test(target);
+    const dir = isUrl ? null : resolve(target);
+    let url = target;
+    let served = null;
+    if (dir) {
+        const root = servedRoot(dir);
+        if (!root)
+            return null;
+        served = await serveDir(root);
+        url = served.url;
+    }
+    const manifestPath = dir && join(dir, 'funpixel.json');
+    let manifest = {};
+    if (manifestPath && existsSync(manifestPath)) {
+        try {
+            manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+        }
+        catch { }
+    }
+    const orientation = typeof manifest.metadata?.orientation === 'string' ? manifest.metadata.orientation : '';
+    const viewport = viewportOpt ?? (orientation.trim().toLowerCase() === 'portrait' ? 'phone' : 'desktop');
+    const checkVerbs = checkedVerbs(manifest.checks);
+    return { dir, url, served, manifest, orientation, viewport, checkVerbs };
+}
+export async function reel(opts, io = console) {
+    const u = ui(io, 'reel');
+    const target = opts.target ?? '.';
+    const game = await openGame(target, opts.viewport);
+    if (!game) {
+        u.error(`no dist/index.html in ${resolve(target)}`, 'build the game first (npm run build)');
+        return EXIT.error;
+    }
+    const { dir, url, served, manifest, orientation, viewport, checkVerbs } = game;
+    const work = dir ? join(dir, '.funtools', 'reel') : resolve('.funtools', 'reel');
+    const framesDir = join(work, 'frames');
+    const out = resolve(opts.out ?? join(work, 'reel.mp4'));
+    await rm(framesDir, { recursive: true, force: true });
+    await mkdir(framesDir, { recursive: true });
+    const bin = opts.framesOnly ? null : ffmpegBin();
+    let filmed;
+    try {
+        filmed = await filmWithRetry(url, hookMapOf(manifest), checkVerbs, opts, viewport, orientation, framesDir);
+    }
+    finally {
+        await served?.close();
+    }
+    let video = null, encodeError = '';
+    if (bin) {
+        const r = encode(bin, framesDir, opts.fps, out, filmed.landscape);
+        if (r.ok) {
+            video = out;
+            await rm(framesDir, { recursive: true, force: true });
+        }
+        else
+            encodeError = r.error;
+    }
+    const still = filmed.distinct <= 1;
+    const result = {
+        video, frames_dir: video ? null : framesDir, frames: filmed.frames, seconds: opts.seconds, fps: opts.fps,
+        viewport, driven: filmed.touch ? 'touch' : filmed.tour.driven, inputs: filmed.tour.inputs, skipped: filmed.tour.skipped, moments: filmed.marks,
+        views: filmed.tour.segments.map((s) => s.view).filter((v) => !!v),
+        distinct_frames: filmed.distinct, software_gl: filmed.softwareGl,
+        ...(video ? { bytes: (await stat(video)).size } : {}),
+        ...(!video ? { ffmpeg: opts.framesOnly ? 'skipped' : bin ? `failed: ${encodeError}` : 'not found' } : {}),
+    };
+    if (encodeError && !opts.json)
+        u.error(`ffmpeg could not encode the reel: ${encodeError}`, `the frames are in ${framesDir}`);
+    if (opts.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return encodeError ? EXIT.error : EXIT.pass;
+    }
+    u.heading(`reel · ${dir ?? target}`);
+    const how = filmed.tour.driven === 'passive'
+        ? ['note', 'passive: the game declares no __FPX_VERBS__ or __FPX_KEYS__, so the reel shows what it does on its own (funtools doctor --add-hooks)']
+        : ['pass', `driven by its ${filmed.tour.driven}${filmed.touch ? ' as touches on their on-screen controls' : ''}: ${filmed.tour.inputs.join(', ')}`];
+    u.item(how[0], how[1]);
+    if (filmed.tour.skipped.length)
+        u.item('note', `not pressed: ${filmed.tour.skipped.join(', ')} — no check ties them to a key or tap, so they read as setups that stage a state (a full board, a boss), not play`, 'tie a verb that is real play to its input in funpixel.json (key or pointer) to film it');
+    if (result.views.length)
+        u.item('pass', `views toured: ${result.views.join(' → ')}`);
+    if (filmed.marks.length)
+        u.item('pass', `moments: ${filmed.marks.map((m) => `${m.name} (frame ${m.frame})`).join(', ')}`);
+    if (filmed.softwareGl)
+        u.item('note', 'filmed on software GL (SwiftShader): this browser has no WebGL');
+    if (still)
+        u.item('warn', 'every frame is the same picture', 'the reel shows a still screen — is the game stuck on a loading or title screen?');
+    if (video) {
+        u.line(video);
+        u.summary(still ? 'warn' : 'pass', `${opts.seconds}s at ${opts.fps} fps, 1080x1920 (${((result.bytes ?? 0) / 1_048_576).toFixed(2)} MB)`);
+    }
+    else if (!encodeError) {
+        if (!opts.framesOnly)
+            u.item('warn', 'ffmpeg is not on PATH, so no MP4 was cut', 'install ffmpeg (brew install ffmpeg · apt install ffmpeg · winget install ffmpeg) and run reel again');
+        u.line(framesDir);
+        u.summary('pass', `${filmed.frames} PNG frames (${opts.fps} fps)`);
+    }
+    return encodeError ? EXIT.error : EXIT.pass;
+}

package/dist/commands/review.js

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { boardLine, patchBoard, readBoard } from "../status/board.js";
+import { STATUS_FILE } from "../status/file.js";
+import { hasFfmpeg, MAX_FILES, MEASURED, mediaFiles, projectRoot, tradeOfFile, TRADES, unseen } from "../review/media.js";
+import { reviewVideo } from "../review/video.js";
+import { reviewAudio } from "../review/audio.js";
+import { reviewModel } from "../review/model.js";
+import { reviewPicture } from "../review/picture.js";
+import { modelBudget, readSpecs } from "../review/specs.js";
+import { ledgerPatch, mergeLedger, readLedger, tradeTotals, writeLedger, LEDGER } from "../review/ledger.js";
+import { ui } from "../ui.js";
+export function verdictOf(rs) {
+    const vs = rs.flatMap((r) => MEASURED.map((c) => r[c].value));
+    if (vs.some((v) => v !== null && v > 0))
+        return 'fail';
+    return vs.some((v) => v === 0) ? 'pass' : 'not_observed';
+}
+const slash = (p) => p.split('\\').join('/');
+const WORD = { errors: 'errors', overlaps: 'overlaps', seams: 'seams' };
+export function reviewFile(file, rel, root, o, specs = readSpecs(root)) {
+    const trade = tradeOfFile(file);
+    const blank = (why) => ({ file: rel, trade, errors: unseen(why), overlaps: unseen(why), seams: unseen(why), notes: [] });
+    const ff = hasFfmpeg();
+    try {
+        if (trade === 'video')
+            return ff ? reviewVideo(file, rel, { loop: o.loop, still: o.still, freezeS: o.freezeS }) : blank('no ffmpeg on PATH');
+        if (trade === 'audio')
+            return ff ? reviewAudio(file, rel, { loop: o.loop, lufs: o.lufs, game: existsSync(join(root, 'funpixel.json')) }) : blank('no ffmpeg on PATH');
+        if (trade === 'model') {
+            const b = modelBudget(specs, rel, o.triangles);
+            return reviewModel(file, rel, b ? { triangles: b.n, triangleSource: b.from } : {});
+        }
+        return reviewPicture(file, rel, { specs, size: o.size, alpha: o.alpha });
+    }
+    catch (e) {
+        return blank(`the review stopped: ${e.message}`);
+    }
+}
+export async function review(opts, io = console) {
+    const u = ui(io, 'review');
+    const paths = (opts.paths.length ? opts.paths : ['.']).map((p) => resolve(p));
+    const missing = paths.find((p) => !existsSync(p));
+    if (missing) {
+        u.error(`no file or folder ${missing}`);
+        return EXIT.error;
+    }
+    const root = opts.dir ? resolve(opts.dir) : projectRoot(paths[0]);
+    if (!existsSync(root)) {
+        u.error(`no project folder ${root}`);
+        return EXIT.error;
+    }
+    const { files, capped } = mediaFiles(paths);
+    const named = paths.map((p) => slash(relative(root, p)) || '.').join(', ');
+    if (!files.length) {
+        if (opts.json)
+            io.log(JSON.stringify({ verdict: 'not_observed', reason: 'no media files', root }, null, 2));
+        u.summary('not_observed', `no media in ${named} (video mp4/mov/webm, audio wav/mp3/m4a/flac, models glb/gltf, pictures png/jpg/webp)`);
+        return EXIT.not_observed;
+    }
+    const now = opts.now ?? new Date();
+    const specs = readSpecs(root);
+    const reviews = files.map((f) => reviewFile(f, slash(relative(root, f)), root, opts, specs));
+    const verdict = verdictOf(reviews);
+    const counts = TRADES.map((t) => [t, reviews.filter((r) => r.trade === t).length]).filter(([, n]) => n);
+    const what = `review ${named}: ${files.length} file(s) (${counts.map(([t, n]) => `${n} ${t}`).join(', ')})`;
+    let wrote = false;
+    try {
+        if (reviews.some((r) => MEASURED.some((c) => r[c].value !== null)) || existsSync(join(root, LEDGER)))
+            mkdirSync(join(root, 'design'), { recursive: true });
+        wrote = patchBoard(root, (board) => {
+            const l = mergeLedger(readLedger(root), reviews, now.toISOString(), root);
+            writeLedger(root, l);
+            return ledgerPatch(l, board);
+        }, { now, what, by: 'review' });
+    }
+    catch {
+        wrote = false;
+    }
+    const board = readBoard(root);
+    const totals = tradeTotals(reviews);
+    if (opts.json) {
+        io.log(JSON.stringify({ verdict, root, board_file: STATUS_FILE, wrote, ledger: LEDGER, trades: Object.fromEntries(counts.map(([t]) => [t, totals[t]])), files: reviews, board }, null, 2));
+        return EXIT[verdict];
+    }
+    u.heading(`review · ${named} · ${what.slice(what.indexOf(': ') + 2)}${capped ? ` · the first ${MAX_FILES} only` : ''}`);
+    for (const r of reviews) {
+        const v = verdictOf([r]);
+        const head = MEASURED.map((c) => `${WORD[c]} ${r[c].value ?? '–'}`).join(' · ');
+        u.item(v, r.file, `${r.trade}: ${head}`);
+        for (const c of MEASURED)
+            for (const d of r[c].detail)
+                u.line(`${c}: ${d}`, 2);
+        for (const n of r.notes)
+            u.line(n, 2);
+    }
+    for (const [t] of counts) {
+        const line = MEASURED.map((c) => {
+            const why = reviews.find((r) => r.trade === t && r[c].value === null)?.[c].why;
+            return `${WORD[c]} ${totals[t][c] ?? `not observed${why && totals[t][c] === null ? ` (${why})` : ''}`}`;
+        }).join(' · ');
+        u.line(`${t}: ${line}`);
+    }
+    const bl = boardLine(board);
+    u.line(wrote ? `board (${slash(relative(process.cwd(), join(root, STATUS_FILE))) || STATUS_FILE}): ${bl ?? 'nothing observed'} — funtools zero ${slash(relative(process.cwd(), root)) || '.'}` : 'board: not written (an unreadable design/status.json is never overwritten)');
+    const bad = reviews.filter((r) => verdictOf([r]) === 'fail');
+    u.summary(verdict, verdict === 'fail'
+        ? `${bad.length} of ${reviews.length} file(s) not zero: fix, review again, repeat`
+        : verdict === 'pass' ? `${reviews.length} file(s): every observed counter is zero` : 'nothing observed: no counter could be measured (ffmpeg on PATH for video and audio)');
+    return EXIT[verdict];
+}