@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/world.js

@@ -0,0 +1,175 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { freshSeed } from "../studio/widen.js";
+import { kindOfGame, readBrief } from "../world/brief.js";
+import { checkWorld } from "../world/check.js";
+import { fingerprintOf, forge, MAX_ROOMS } from "../world/forge.js";
+import { WORLD_DIR, WORLD_FILE } from "../world/format.js";
+import { varietyOf, PARTS, TWIN_BELOW } from "../world/variety.js";
+import { ui } from "../ui.js";
+export const WORLD_ACTIONS = ['forge', 'check'];
+export const CHECK_RECORD = join('.funtools', 'world-check.json');
+export const VARIETY_RECORD = join('.funtools', 'world-variety.json');
+const whole = (raw, lo, hi) => {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= lo && n <= hi ? n : null;
+};
+export function sidecarReader(root) {
+    const base = join(root, WORLD_DIR);
+    return (rel) => {
+        if (typeof rel !== 'string' || isAbsolute(rel) || normalize(rel).startsWith('..'))
+            return null;
+        try {
+            return JSON.parse(readFileSync(join(base, rel), 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    };
+}
+export async function world(opts, io = console) {
+    const u = ui(io, `world ${opts.action}`);
+    const root = resolve(opts.dir ?? '.');
+    if (!existsSync(root)) {
+        u.error(`no such folder: ${root}`);
+        return EXIT.error;
+    }
+    return opts.action === 'check' ? check(root, opts, io) : forgeCmd(root, opts, io);
+}
+async function forgeCmd(root, opts, io) {
+    const u = ui(io, 'world forge');
+    const seed = whole(opts.seed, 0, 0xffffffff);
+    if (seed === null) {
+        u.error(`--seed must be a whole number from 0 to 4294967295, got ${opts.seed}`);
+        return EXIT.error;
+    }
+    const rooms = whole(opts.rooms, 1, MAX_ROOMS);
+    if (rooms === null) {
+        u.error(`--rooms is a whole number from 1 to ${MAX_ROOMS}, got ${opts.rooms}`);
+        return EXIT.error;
+    }
+    if (opts.kind !== undefined && opts.kind !== '2d' && opts.kind !== '3d') {
+        u.error(`--kind ${opts.kind}`, '--kind is 2d (tile rooms) or 3d (heightfield rooms)');
+        return EXIT.error;
+    }
+    const brief = readBrief(root, opts.from);
+    if (typeof brief === 'string') {
+        u.error(brief, '--from takes a GDD (markdown) or a JSON brief');
+        return EXIT.error;
+    }
+    const kind = opts.kind ?? brief.kind ?? kindOfGame(root) ?? '2d';
+    const s = seed ?? freshSeed();
+    if (opts.variety !== undefined) {
+        const count = whole(opts.variety, 2, 50);
+        if (!count) {
+            u.error(`--variety is how many seeds to compare, 2 to 50, got ${opts.variety}`);
+            return EXIT.error;
+        }
+        const rep = varietyOf(s, count, kind, brief, rooms);
+        await mkdir(join(root, '.funtools'), { recursive: true });
+        await writeFile(join(root, VARIETY_RECORD), JSON.stringify({ tool: 'funtools', command: 'world forge --variety', brief: brief.from, ...rep }, null, 2) + '\n');
+        if (opts.json) {
+            io.log(JSON.stringify(rep, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`world forge --variety · ${count} seeds from ${s} · ${kind} · ${rep.pairs} pairs`);
+        u.line(`apart, 0 (the same) to 1 (nothing alike): ${PARTS.map((p) => `${p} ${rep.mean[p]}`).join(' · ')}`, 1);
+        if (rep.closest)
+            u.item('note', `closest pair: seeds ${rep.closest.a} and ${rep.closest.b} (${rep.closest.overall})`);
+        for (const t of rep.twins.slice(0, 8))
+            u.item('warn', `seeds ${t.a} and ${t.b} forge near-twins (${t.overall} < ${TWIN_BELOW})`);
+        u.summary(rep.verdict, `mean ${rep.mean.overall} apart${rep.twins.length ? `, ${rep.twins.length} near-twin pair(s)` : ', no near-twins'} (${VARIETY_RECORD}); nothing written to ${WORLD_DIR}`);
+        return EXIT.pass;
+    }
+    const target = join(root, WORLD_FILE);
+    if (existsSync(target) && !opts.force) {
+        let kept = null;
+        try {
+            kept = JSON.parse(readFileSync(target, 'utf8'));
+        }
+        catch { }
+        if (!kept || typeof kept.fingerprint !== 'string' || fingerprintOf(kept) !== kept.fingerprint) {
+            u.error(`${WORLD_FILE} was changed by hand since it was forged`, 'keep it, or forge over it with --force');
+            return EXIT.error;
+        }
+    }
+    const f = forge({ seed: s, kind, brief, rooms });
+    const dir = join(root, WORLD_DIR);
+    const roomsDir = join(dir, 'rooms');
+    if (existsSync(roomsDir))
+        for (const name of readdirSync(roomsDir))
+            if (/^r\d+(\.heights)?\.json$/.test(name))
+                rmSync(join(roomsDir, name));
+    for (const [rel, text] of Object.entries(f.files)) {
+        await mkdir(dirname(join(dir, rel)), { recursive: true });
+        await writeFile(join(dir, rel), text);
+    }
+    const self = checkWorld(f.world, (rel) => (f.files[rel] ? JSON.parse(f.files[rel]) : null));
+    if (opts.json) {
+        io.log(JSON.stringify({ seed: s, kind, files: Object.keys(f.files).map((r) => `${WORLD_DIR}/${r}`), check: self.verdict, world: f.world }, null, 2));
+        return self.verdict === 'fail' ? EXIT.error : EXIT.pass;
+    }
+    const w = f.world;
+    u.heading(`world forge · seed ${s} · ${kind} · ${w.rooms.length} room(s) in ${w.chapters.length} chapter(s)${brief.from ? ` · brief ${brief.from}` : ''}`);
+    if (!brief.props.length)
+        u.item('note', `no kit declared: props are role names (${w.props.map((p) => p.kind).join(', ')})`, 'name the game\'s own in the GDD as **Kit:** pine (cover), rock, lamp (light), or "props" in a JSON brief');
+    for (const c of w.chapters) {
+        u.line(`${c.id} ${c.name}${c.landmark ? ` · landmark ${c.landmark}` : ''}`, 1);
+        for (const id of c.rooms) {
+            const r = w.rooms.find((x) => x.id === id);
+            u.item('pass', `${r.id} ${r.role} · ${r.shape} ${r.size.join('×')} · ${r.doors.length} door(s) · ${r.instances.length} instance(s), ~${r.estimate.draw_calls} draw calls${r.estimate.lod ? `, ${r.estimate.lod.far} past LOD` : ''}`);
+        }
+    }
+    u.line(`critical path: ${w.critical_path.join(' → ')}${w.edges.some((e) => e.kind === 'loop') ? ` · loops ${w.edges.filter((e) => e.kind === 'loop').length}` : ''}${w.edges.some((e) => e.kind === 'secret') ? ' · a secret room' : ''}`, 1);
+    if (self.verdict === 'fail') {
+        for (const x of self.findings.filter((y) => y.status === 'fail'))
+            u.item('fail', x.what, x.room);
+        u.summary('fail', 'the forger wrote a world its own check refuses: a bug, please report the seed');
+        return EXIT.error;
+    }
+    u.summary('pass', `${WORLD_FILE}${Object.keys(f.files).length > 1 ? ` + ${Object.keys(f.files).length - 1} room file(s)` : ''}; the same world again: --seed ${s}${opts.rooms ? ` --rooms ${rooms}` : ''} --kind ${kind}; then \`world check\` after any edit`);
+    return EXIT.pass;
+}
+async function check(root, opts, io) {
+    const u = ui(io, 'world check');
+    const file = join(root, WORLD_FILE);
+    if (!existsSync(file)) {
+        if (opts.json)
+            io.log(JSON.stringify({ verdict: 'not_observed', reason: `no ${WORLD_FILE}` }, null, 2));
+        else
+            u.summary('not_observed', `no ${WORLD_FILE} — nothing to check (forge one: funtools world forge --seed 1)`);
+        return EXIT.not_observed;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        u.error(`${WORLD_FILE} is not JSON: ${e.message}`);
+        return EXIT.error;
+    }
+    const res = checkWorld(raw, sidecarReader(root));
+    await mkdir(join(root, '.funtools'), { recursive: true });
+    await writeFile(join(root, CHECK_RECORD), JSON.stringify({ tool: 'funtools', command: 'world check', at: new Date().toISOString(), ...res }, null, 2) + '\n');
+    if (opts.json) {
+        io.log(JSON.stringify(res, null, 2));
+        return res.verdict === 'fail' ? EXIT.fail : EXIT.pass;
+    }
+    u.heading(`world check · ${WORLD_FILE} · ${res.kind} · ${res.rooms.length} room(s)`);
+    for (const f of res.findings.filter((x) => !x.room))
+        u.item(f.status, f.what, f.why);
+    for (const r of res.rooms) {
+        const mine = res.findings.filter((f) => f.room === r.id);
+        u.item(r.verdict, `${r.id} · ${r.size} · ${r.reached} of ${r.open} open cell(s) reached${r.estimate ? ` · ${r.estimate.instances} instance(s), ~${r.estimate.draw_calls} draw calls` : ''}`);
+        for (const f of mine)
+            u.line(`${f.status === 'fail' ? 'FAIL' : f.status}: ${f.what}${f.why ? ` — ${f.why}` : ''}`, 2);
+    }
+    const fails = res.findings.filter((f) => f.status === 'fail').length, warns = res.findings.filter((f) => f.status === 'warn').length;
+    u.summary(res.verdict === 'fail' ? 'fail' : res.verdict === 'warn' ? 'warn' : 'pass', res.verdict === 'fail' ? `${fails} problem(s): a player cannot cross this world as written (${CHECK_RECORD})`
+        : `every door, goal and place reached from the arrival${warns ? `; ${warns} warning(s)` : ''} (${CHECK_RECORD})`);
+    return res.verdict === 'fail' ? EXIT.fail : EXIT.pass;
+}

package/dist/commands/wow.js

@@ -0,0 +1,143 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { CATALOGUE, MOVES } from "../wow/catalogue.js";
+import { parseCheck, pickProblems, sameExpression, wowPicks, writePick } from "../wow/picks.js";
+import { cardOf } from "../frame/genre.js";
+import { allMotifs, motifOf, recordMotif } from "../lessons/motifs.js";
+import { designDoc } from "../gdd/doc.js";
+import { ui } from "../ui.js";
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+const T = 'npx @funpixel/tools';
+export function ledgerClashes(root, pick, home = homedir()) {
+    if (pick.role !== 'signature')
+        return [];
+    const me = resolve(root), title = (motifOf(root)?.title ?? '').toLowerCase();
+    return allMotifs(home).filter((m) => resolve(m.game) !== me && m.title.toLowerCase() !== title && m.wow?.signature === pick.id).map((m) => ({ title: m.title, expression: m.wow.expression, same: sameExpression(pick.expression, m.wow.expression) }));
+}
+export function wowEvidence(root, picks) {
+    const hook = readJson(join(root, '.funtools', 'hook.json'));
+    const marks = (hook?.opening?.read?.marks ?? []).map((m) => String(m.name));
+    const hookMoment = hook?.first_minute?.moment ? String(hook.first_minute.moment) : null;
+    const scores = readJson(join(root, 'design', 'look', 'scores.json'));
+    const manifest = readJson(join(root, 'funpixel.json')) ?? {};
+    const moments = Array.isArray(manifest.moments) ? manifest.moments : [];
+    return picks.map((p) => {
+        if (!p.check)
+            return { id: p.id, role: p.role, state: 'missing', says: 'no check named: an event (`__FPX_MOMENT__`) or a frame of a view' };
+        if (p.check.kind === 'event') {
+            if (!hook)
+                return { id: p.id, role: p.role, state: 'not_observed', says: `no hook read yet: ${T} hook --verbs … (it records every __FPX_MOMENT__ mark)` };
+            const hit = marks.includes(p.check.name) || hookMoment === p.check.name;
+            return hit ? { id: p.id, role: p.role, state: 'seen', says: `the game fired "${p.check.name}" in the hook read` } : { id: p.id, role: p.role, state: 'missing', says: `"${p.check.name}" never fired in the hook read (${marks.length ? `fired: ${[...new Set(marks)].slice(0, 6).join(', ')}` : 'no mark at all'}): call window.__FPX_MOMENT__?.('${p.check.name}') at its peak, and play far enough to reach it (hook --verbs)` };
+        }
+        const planned = moments.find((m) => m?.view === p.check.name || m?.name === p.check.name);
+        if (!planned)
+            return { id: p.id, role: p.role, state: 'missing', says: `no target frame for the view "${p.check.name}": add a moment to funpixel.json ("moments": [{ "name", "view": "${p.check.name}", "target" }])` };
+        const scored = (scores?.moments ?? []).find((m) => m.moment === planned.name || m.view === p.check.name);
+        if (!scored || typeof scored.score !== 'number')
+            return { id: p.id, role: p.role, state: 'not_observed', says: `the moment "${planned.name}" is planned, not scored yet: ${T} score` };
+        const bar = typeof scores.bar === 'number' ? scores.bar : 75;
+        return { id: p.id, role: p.role, state: scored.score >= bar ? 'seen' : 'missing', says: `the moment "${planned.name}" scores ${scored.score}/${bar} beside its target${scored.score >= bar ? '' : ` — ${T} score --fixes`}` };
+    });
+}
+const moveLine = (x) => `${x.id} · ${x.family} · ${x.name} (${x.hit}) — ${x.build}; checked by ${x.check.kind} ${x.check.name}`;
+export async function wow(opts, io = console) {
+    const u = ui(io, 'wow');
+    const root = resolve(opts.dir);
+    const manifest = readJson(join(root, 'funpixel.json')) ?? {};
+    const card = cardOf(opts.genre ?? manifest.metadata?.genre ?? manifest.genre);
+    const doc = designDoc(root);
+    const picks = doc ? wowPicks(doc.text) : [];
+    const home = opts.home ?? homedir();
+    if (opts.sub === 'list') {
+        const cat = CATALOGUE[card];
+        const problems = doc ? pickProblems(picks, (id) => MOVES.has(id)) : [];
+        if (opts.json) {
+            io.log(JSON.stringify({ card, catalogue: cat, picks, problems }, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`wow · the ${card} card's catalogue · ${cat.length} moves`);
+        for (const fam of ['signature', 'juice', 'feel', 'presentation'])
+            for (const x of cat.filter((y) => y.family === fam))
+                u.line(`- ${moveLine(x)}`, 1);
+        u.line('', 0);
+        if (!doc)
+            u.item('note', 'no design/GDD.md yet: the picks are recorded there');
+        else if (picks.length)
+            for (const p of picks)
+                u.item('note', `picked: ${p.role} ${p.id}${p.expression ? ` — "${p.expression}"` : ''}${p.check ? ` (${p.check.kind} ${p.check.name})` : ''}`);
+        for (const p of problems)
+            u.item(p.level, p.text);
+        u.summary('pass', `pick: ${T} wow pick <id> --signature --expression "what this game makes of it" --why "how it pays off the pitch"; other genres: --genre <card>`);
+        return EXIT.pass;
+    }
+    if (opts.sub === 'pick') {
+        if (!doc) {
+            u.error('no design/GDD.md to record the pick in', `${T} init, or write the GDD first`);
+            return EXIT.error;
+        }
+        const id = (opts.id ?? '').trim();
+        if (!id) {
+            u.error('wow pick needs a move id', `${T} wow (the card's catalogue), or custom-<name> for one you invent`);
+            return EXIT.error;
+        }
+        const move = MOVES.get(id);
+        if (!move && !/^custom-[\w-]+$/.test(id)) {
+            const near = [...MOVES.keys()].filter((k) => k.includes(id) || id.includes(k.split('-').slice(1).join('-'))).slice(0, 3);
+            u.error(`${id} is not in the catalogue`, near.length ? `did you mean ${near.join(', ')}? An invented move is custom-<name>` : 'an invented move is custom-<name>');
+            return EXIT.error;
+        }
+        const check = opts.check ? parseCheck(opts.check) : move ? move.check : null;
+        if (opts.check && !check) {
+            u.error(`--check "${opts.check}" is not "event <name>" or "frame <view>"`);
+            return EXIT.error;
+        }
+        const p = { role: opts.signature ? 'signature' : 'also', id, expression: opts.expression ?? '', why: opts.why ?? '', check };
+        const gddPath = join(root, doc.rel);
+        const text = writePick(readFileSync(gddPath, 'utf8'), p);
+        writeFileSync(gddPath, text);
+        const after = wowPicks(text);
+        const clashes = ledgerClashes(root, after.find((x) => x.id === id), home);
+        recordMotif(root, home);
+        const problems = pickProblems(after, (x) => MOVES.has(x));
+        if (opts.json) {
+            io.log(JSON.stringify({ picked: p, picks: after, clashes, problems }, null, 2));
+            return EXIT.pass;
+        }
+        u.item('pass', `${p.role} ${id} recorded in ${doc.rel} ## Wow${move ? ` (${move.name}, from ${move.hit})` : ''}`);
+        for (const c of clashes)
+            u.item(c.same ? 'warn' : 'note', c.same ? `${c.title} already used ${id} as its signature${c.expression ? `, expressed "${c.expression}"` : ''}: change the subject, the axis or the payoff (--expression)` : `${c.title} used ${id} too, expressed apart ("${c.expression}")`);
+        for (const x of problems)
+            u.item(x.level, x.text);
+        if (move && move.card !== card)
+            u.item('note', `${id} comes from the ${move.card} card; this game reads as ${card}: a cross-genre pick is fine, say why`);
+        return EXIT.pass;
+    }
+    if (!doc) {
+        u.summary('not_observed', 'no design/GDD.md: nothing picked');
+        return EXIT.not_observed;
+    }
+    if (!picks.length) {
+        u.summary('not_observed', `no ## Wow in the GDD: ${T} wow`);
+        return EXIT.not_observed;
+    }
+    const ev = wowEvidence(root, picks);
+    if (opts.json) {
+        io.log(JSON.stringify({ picks, evidence: ev }, null, 2));
+        return ev.some((e) => e.state === 'missing') ? EXIT.fail : ev.every((e) => e.state === 'seen') ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`wow check · ${picks.length} pick(s)`);
+    for (const e of ev)
+        u.item(e.state === 'seen' ? 'pass' : e.state === 'missing' ? 'warn' : 'not_observed', `${e.role} ${e.id}: ${e.says}`);
+    const missing = ev.filter((e) => e.state === 'missing').length;
+    u.summary(missing ? 'warn' : ev.every((e) => e.state === 'seen') ? 'pass' : 'not_observed', missing ? `${missing} pick(s) without their evidence — a planned wow that play never shows is a finding` : ev.every((e) => e.state === 'seen') ? 'every pick shows in play' : 'some picks not observed yet');
+    return missing ? EXIT.fail : ev.every((e) => e.state === 'seen') ? EXIT.pass : EXIT.not_observed;
+}
+export const WOW_SUBCOMMANDS = ['pick', 'check'];

package/dist/commands/zero.js

@@ -0,0 +1,71 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { boardVerdict, byTrade, COUNTER_IDS, counterState, readBoard, tradeOf, TRADES, trend, valueWord, WARN_ONLY } from "../status/board.js";
+import { STATUS_FILE } from "../status/file.js";
+import { ui } from "../ui.js";
+export const MEASURE_WITH = {
+    errors: 'funtools verify (or check), funtools capture --all; media files: funtools review <file|folder>',
+    overlaps: 'funtools check (audit-screens on desktop; --phone adds the phone), or funtools audit-screens; a video\'s captions: funtools review',
+    seams: 'funtools look --sheet (looping sprite cycles), funtools loudness (looping music and beds), funtools review (loop videos, loops, tiles); a code-drawn game with no sheets or loops has none to measure',
+    frame_ms: 'funtools profile (phone by default; --viewport desktop); a file has none',
+    comfort: 'funtools score (each moment\'s frame against its target: busyness and the clipped share); a warning, never a fail',
+};
+const ago = (iso, now) => {
+    if (!iso)
+        return '';
+    const s = Math.max(0, Math.round((now.getTime() - Date.parse(iso)) / 1000));
+    return s < 90 ? `${s} s ago` : s < 5400 ? `${Math.round(s / 60)} min ago` : s < 129_600 ? `${Math.round(s / 3600)} h ago` : `${Math.round(s / 86_400)} d ago`;
+};
+export async function zero(opts, io = console) {
+    const u = ui(io, 'zero');
+    const root = resolve(opts.target ?? '.');
+    if (!existsSync(root)) {
+        u.error(`no folder ${root}`);
+        return EXIT.error;
+    }
+    const now = opts.now ?? new Date();
+    const b = readBoard(root);
+    const verdict = boardVerdict(b);
+    if (opts.json) {
+        io.log(JSON.stringify({ verdict, file: STATUS_FILE, board: b, trades: byTrade(b) }, null, 2));
+        return EXIT[verdict];
+    }
+    u.heading(`zero board · ${b.round !== null ? `round ${b.round} · ` : ''}${b.at ? `stamped ${ago(b.at, now)}` : 'nothing stamped yet'} · ${join(STATUS_FILE)}`);
+    for (const id of COUNTER_IDS) {
+        const c = b.counters[id];
+        const state = counterState(id, c);
+        const t = trend(b, id);
+        const head = `${id} ${valueWord(id, c)}${t && b.history.length > 1 ? `  (${t})` : ''}`;
+        if (state === 'not_observed') {
+            u.item('not_observed', head, `nothing measured it: ${MEASURE_WITH[id]}`);
+            continue;
+        }
+        const part = ([k, p]) => `${k} ${id === 'frame_ms' ? `${p.value} ms` : p.value} (${p.by}, ${ago(p.at, now)})`;
+        const groups = TRADES.map((t) => [t, Object.entries(c.parts).filter(([k]) => tradeOf(k) === t)]).filter(([, ps]) => ps.length);
+        const parts = groups.map(([t, ps]) => `${t === 'game' && groups.length > 1 ? 'game: ' : ''}${ps.map(part).join(' · ')}`).join(' | ');
+        u.item(state, head, `${c.of} — ${parts}`);
+        for (const d of c.detail)
+            u.line(d, 2);
+    }
+    const trades = byTrade(b);
+    if (Object.keys(trades).some((t) => t !== 'game')) {
+        u.line('by trade:');
+        for (const t of TRADES) {
+            const row = trades[t];
+            if (!row)
+                continue;
+            u.line(`${t.padEnd(8)} ${COUNTER_IDS.filter((id) => row[id]).map((id) => `${id === 'frame_ms' ? 'frame p95' : id} ${row[id].value}${id === 'frame_ms' ? ' ms' : ''}`).join(' · ')}  (${[...new Set(COUNTER_IDS.flatMap((id) => row[id]?.by ?? []))].join(', ')})`, 2);
+        }
+    }
+    const off = COUNTER_IDS.filter((id) => counterState(id, b.counters[id]) === 'fail');
+    const unseen = COUNTER_IDS.filter((id) => !WARN_ONLY.has(id) && counterState(id, b.counters[id]) === 'not_observed');
+    const warned = COUNTER_IDS.filter((id) => counterState(id, b.counters[id]) === 'warn');
+    const warning = warned.length ? `; warning: ${warned.map((id) => `${id} ${valueWord(id, b.counters[id])}`).join(', ')} (the owner decides)` : '';
+    u.summary(verdict, verdict === 'not_observed'
+        ? 'nothing observed: run check, verify or profile first, or review a media file or folder (not observed is never a zero)'
+        : verdict === 'fail'
+            ? `not zero: ${off.map((id) => `${id} ${valueWord(id, b.counters[id])}`).join(', ')} — fix, measure again, repeat${warning}${unseen.length ? `; not observed: ${unseen.join(', ')}` : ''}`
+            : `${warned.length ? 'every observed counter that can fail is zero' : 'every observed counter is zero'}${warning}${unseen.length ? `; not observed: ${unseen.join(', ')} (not a zero)` : ''}`);
+    return EXIT[verdict];
+}

package/dist/compose/adsheet.js

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+export const SHEET_COLS = 4;
+export const CELL = 300;
+export function grabFrame(video, t, out) {
+    const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', '-ss', String(t), '-i', video, '-frames:v', '1',
+        '-vf', `scale='if(gt(iw,ih),${CELL},-2)':'if(gt(iw,ih),-2,${CELL})'`, '-q:v', '4', out], { encoding: 'utf8' });
+    return r.status === 0 && existsSync(out);
+}
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+const WORD = { pass: 'PASS', fail: 'FAIL', not_observed: 'NOT OBSERVED', error: 'NOT RENDERED' };
+export function sheetHtml(title, cells) {
+    const cols = Math.max(1, Math.min(SHEET_COLS, cells.length));
+    const cell = (c) => {
+        const img = c.frame && existsSync(c.frame) ? `<img src="data:image/jpeg;base64,${readFileSync(c.frame).toString('base64')}" alt="">` : `<div class="none">${esc(c.why ?? 'no frame')}</div>`;
+        return `<figure class="${c.verdict}"><div class="frame">${img}</div><figcaption>
+  <div class="row"><b>${esc(c.id.split('-')[0])}</b><span>${esc(c.aspect)} · ${c.seconds} s</span><i>${WORD[c.verdict]}</i></div>
+  <div class="hook">“${esc(c.hook)}”</div>
+  <div class="cta">→ ${esc(c.cta)}${c.warn ? ' <em>≠ playable</em>' : ''}</div>
+  <div class="opens">opens on ${esc(c.opens)}</div></figcaption></figure>`;
+    };
+    return `<!doctype html><html><head><meta charset="utf-8"><style>
+  * { box-sizing: border-box; margin: 0; }
+  body { background: #111317; color: #eef0f3; font: 13px/1.35 -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; padding: 18px; width: ${cols * (CELL + 16) + 20}px; }
+  h1 { font-size: 16px; font-weight: 700; margin: 0 0 14px 2px; }
+  main { display: grid; grid-template-columns: repeat(${cols}, ${CELL}px); gap: 16px; }
+  figure { background: #1b1e24; border-radius: 10px; overflow: hidden; border: 2px solid #2a2e36; }
+  figure.fail, figure.error { border-color: #c2412d; }
+  .frame { width: ${CELL - 4}px; height: ${CELL - 4}px; display: flex; align-items: center; justify-content: center; background: #08090b; }
+  .frame img { max-width: 100%; max-height: 100%; display: block; }
+  .none { color: #e88; padding: 20px; text-align: center; }
+  figcaption { padding: 8px 10px 10px; }
+  .row { display: flex; gap: 8px; align-items: baseline; }
+  .row span { color: #9aa3b0; flex: 1; }
+  .row i { font-style: normal; font-weight: 700; font-size: 11px; padding: 1px 6px; border-radius: 4px; background: #24563a; color: #c8f5d6; }
+  .fail .row i, .error .row i { background: #6b2419; color: #ffd9d2; }
+  .not_observed .row i { background: #4a4a2a; color: #f2eec4; }
+  .hook { margin-top: 4px; font-weight: 600; }
+  .cta { color: #ffd23f; margin-top: 2px; }
+  .cta em { color: #f39a6b; font-style: normal; font-size: 11px; }
+  .opens { color: #8a93a0; font-size: 11px; margin-top: 2px; }
+</style></head><body><h1>${esc(title)}</h1><main>
+${cells.map(cell).join('\n')}
+</main></body></html>`;
+}
+export async function drawSheet(browser, title, cells, out) {
+    const cols = Math.max(1, Math.min(SHEET_COLS, cells.length));
+    const ctx = await browser.newContext({ viewport: { width: cols * (CELL + 16) + 20, height: 400 }, deviceScaleFactor: 1 });
+    try {
+        const page = await ctx.newPage();
+        await page.setContent(sheetHtml(title, cells), { waitUntil: 'load' });
+        await page.screenshot({ path: out, fullPage: true, type: 'png' });
+        return existsSync(out);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await ctx.close().catch(() => { });
+    }
+}