@funpixel/tools 0.0.0-stage → 0.1.0

package/dist/commands/playtest.js

@@ -0,0 +1,262 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { assemble, planOf, playerRound } from "../playtest/assemble.js";
+import { LONG_MINUTES, PREMISE_FILE, playtests, prepare } from "../playtest/prepare.js";
+import { prepareExperience } from "../playtest/experience-run.js";
+import { playLength, writeReached } from "../playtest/length.js";
+import { afterRound } from "../playtest/after-round.js";
+import { prepareMobileQa, readMobileQa } from "../playtest/mobile-qa.js";
+import { PLAYTEST_DIR } from "../playtest/prepare.js";
+import { roundBudget, STEP_LIMITS } from "../play/steps.js";
+import { beforeRound, milestoneOf } from "../playtest/stop.js";
+import { readHistory } from "../playtest/history.js";
+import { FULL_SEATS, QUICK_SEATS } from "../playtest/seats.js";
+import { ui } from "../ui.js";
+import { carried, dropKeep, KEEP_FILE, lostItems, readKeep, writeKeep } from "../playtest/keep.js";
+export const PLAYTEST_SUBCOMMANDS = ['report', 'status', 'experience', 'keep'];
+export function panelMean(means) {
+    if (typeof means.overall === 'number')
+        return means.overall;
+    const v = Object.values(means).filter((x) => typeof x === 'number');
+    return v.length ? Math.round((v.reduce((a, b) => a + b, 0) / v.length) * 100) / 100 : null;
+}
+export function costLine(quick, long = quick ? 0 : LONG_MINUTES) {
+    const seats = quick ? QUICK_SEATS.length : FULL_SEATS.length;
+    return [
+        `measuring here: about ${quick ? '1–2' : '2–4'} min, free (build, verify, capture --all, audit-screens, look --hud, look --read${quick ? '' : ', profile'}, a WebKit phone shot, key parity at phone size and a five-window sweep (look --fit), sim when test/probes.ts exists, feel when test/feel.json does (its sweeps too, unless --quick), and the saved route replayed at the plan's timed moments once a round has recorded it; the numbers become the facts every seat reads first)`,
+        `then your agent runs ${seats} critic seat(s), the Mobile QA seat (phone-native: touch controls, play area, reach, chrome; from real phone evidence), the fidelity seat when the GDD has target frames, and 1 blind phone round${long ? ` (a long session, about ${long} min of game time, ending with "would you come back tomorrow?")` : ''}${quick ? '' : ` + ${FULL_SEATS.length * 2} head-to-head calls when the genre hit's evidence is here`}, in parallel;`,
+        `after the blind round, \`playtest experience\` keeps its steps as the route (the first time), measures depth for free and writes ${quick ? '1 experience seat' : '2 experience seats'} (depth, content, replay, story, world, arc, originality) and, from the second playtest, the ledger seat for last round's blockers;`,
+        `a seat reads ~20 frames, a player round is 50–${long ? roundBudget(null, long) : STEP_LIMITS.perRound} steps (about ${STEP_LIMITS.perLongMinute} a minute of a long session); about ${quick ? '10' : long ? '30–45' : '15–25'} min in all`,
+        ...(long ? [`the report sets the long round's minutes of real play beside the bots' run lengths (sim) and the plan's Play length line and content list, and fills the list's Reached in play`] : []),
+    ];
+}
+export async function playtest(opts, io = console) {
+    const u = ui(io, 'playtest');
+    const root = resolve(opts.dir);
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'));
+    }
+    catch {
+        u.error(`no funpixel.json in ${root}`, 'run it in the game folder');
+        return EXIT.error;
+    }
+    const latest = playtests(root).at(-1);
+    if (opts.sub === 'report') {
+        if (!latest) {
+            u.error('no playtest here yet', 'run `funtools playtest` first');
+            return EXIT.error;
+        }
+        try {
+            const { summary, file } = await assemble(root, latest, { costUsd: opts.costUsd });
+            const mean = panelMean(summary.means);
+            const below = opts.minScore !== undefined && (mean === null || mean < opts.minScore);
+            const regressed = (summary.keep ?? []).some((k) => k.status === 'lost');
+            if (opts.json) {
+                io.log(JSON.stringify(opts.minScore === undefined ? summary : { ...summary, min_score: { asked: opts.minScore, mean, met: !below } }, null, 2));
+                return below || regressed ? EXIT.fail : EXIT.pass;
+            }
+            u.heading(`playtest ${latest} · report`);
+            summary.steps.forEach((s, i) => u.item('note', `${i + 1}. ${s.text}`, `${s.who} · ${s.number}`));
+            for (const m of summary.seats.missing)
+                u.item('warn', `seat ${m.seat}: ${m.why}`);
+            if (summary.player.round === null)
+                u.item('warn', 'no blind player round was filed after this playtest was prepared');
+            u.line(file);
+            const lost = (summary.keep ?? []).filter((k) => k.status === 'lost');
+            for (const k of summary.keep ?? [])
+                u.item(k.status === 'lost' ? 'fail' : k.status === 'held' || k.status === 'new' ? 'pass' : 'not_observed', `keep ${k.id} ${k.status}: ${k.text}`);
+            if (lost.length) {
+                u.summary('fail', `a regression: ${lost.map((k) => k.id).join(', ')} worked and ${lost.length === 1 ? 'is' : 'are'} lost — put ${lost.length === 1 ? 'it' : 'them'} back first (${KEEP_FILE})`);
+                return EXIT.fail;
+            }
+            if (opts.minScore !== undefined) {
+                u.summary(below ? 'fail' : 'pass', mean === null ? `no panel numbers to hold to ${opts.minScore}` : `panel ${mean} against the ${opts.minScore} you asked for${below ? '' : ': met'}`);
+                return below ? EXIT.fail : EXIT.pass;
+            }
+            u.summary('pass', 'read the report; pick, edit or ignore its steps');
+            return EXIT.pass;
+        }
+        catch (e) {
+            u.error(e.message);
+            return EXIT.error;
+        }
+    }
+    if (opts.sub === 'keep') {
+        const rec = readKeep(root);
+        if (opts.drop) {
+            if (opts.by !== 'owner') {
+                u.error('only the owner takes an item off the do-not-regress list', `playtest keep --drop ${opts.drop} --by owner "<their words>"`);
+                return EXIT.error;
+            }
+            if (!opts.words?.trim()) {
+                u.error('say why, in the owner\'s words', `playtest keep --drop ${opts.drop} --by owner "<their words>"`);
+                return EXIT.error;
+            }
+            const next = rec ? dropKeep(rec, opts.drop, opts.words.trim()) : null;
+            if (!next) {
+                u.error(`no ${opts.drop} on the list`, '`playtest keep` lists it');
+                return EXIT.error;
+            }
+            writeKeep(root, next);
+            if (opts.json) {
+                io.log(JSON.stringify(next, null, 2));
+                return EXIT.pass;
+            }
+            u.summary('pass', `${opts.drop} is off the list (the owner: "${opts.words.trim()}"); no brief carries it and no round judges it again`);
+            return EXIT.pass;
+        }
+        if (opts.json) {
+            io.log(JSON.stringify(rec ?? { items: [] }, null, 2));
+            return rec && carried(rec).length ? EXIT.pass : EXIT.not_observed;
+        }
+        if (!rec || !carried(rec).length) {
+            u.summary('not_observed', 'no do-not-regress list yet: the first `playtest report` names it from what the panel said works');
+            return EXIT.not_observed;
+        }
+        u.heading(`do not regress · after playtest ${rec.playtest}`);
+        for (const k of carried(rec))
+            u.item(k.status === 'lost' ? 'fail' : k.status === 'held' || k.status === 'new' ? 'pass' : 'not_observed', `${k.id} ${k.status}: ${k.text}`, [k.evidence, k.lost_since ? `lost since playtest ${k.lost_since}` : '', k.note].filter(Boolean).join(' · '));
+        const lost = lostItems(rec);
+        u.summary(lost.length ? 'fail' : 'pass', lost.length ? `${lost.map((k) => k.id).join(', ')} lost: a regression; put ${lost.length === 1 ? 'it' : 'them'} back, then playtest (the ledger seat judges ${lost.length === 1 ? 'it' : 'them'} again)` : 'every brief carries this list; the next playtest judges it');
+        return lost.length ? EXIT.fail : EXIT.pass;
+    }
+    if (opts.sub === 'experience') {
+        const plan = latest ? planOf(root, latest) : null;
+        if (!plan) {
+            u.error('no playtest here yet', 'run `funtools playtest` first');
+            return EXIT.error;
+        }
+        const dir = join(root, '.funtools', 'playtest', String(plan.n));
+        const round = playerRound(root, plan.at);
+        try {
+            if (!opts.json)
+                u.heading(`playtest ${plan.n} · experience`);
+            const after = await afterRound(root, plan, dir, manifest, round, (l) => { if (!opts.json)
+                u.item('note', l); });
+            const { prompts, record } = await prepareExperience(root, after.plan, dir);
+            prompts.push(...after.prompts);
+            const length = playLength(root, record.pacing);
+            const filled = writeReached(root, length);
+            if (filled)
+                after.notes.push(`${filled}: the content list's Reached in play filled from the long round and the bots (cells marked (measured); yours are left alone)`);
+            for (const w of length.warnings)
+                after.notes.push(`play length: ${w}`);
+            const mqDir = join(dir, 'mobile');
+            if (round && plan.mobile?.seat && !existsSync(join(mqDir, 'mobile-qa.json'))) {
+                const measures = (() => { try {
+                    return JSON.parse(readFileSync(join(dir, 'measures.json'), 'utf8'));
+                }
+                catch {
+                    return null;
+                } })();
+                const previous = playtests(root).filter((x) => x < plan.n).at(-1);
+                if (measures) {
+                    await prepareMobileQa(root, mqDir, {
+                        manifest, premise: plan.premise.text, measures, frames: { dir: join(dir, 'frames'), names: plan.frames },
+                        facts: existsSync(join(dir, 'frames', 'facts.md')) ? readFileSync(join(dir, 'frames', 'facts.md'), 'utf8') : '', round,
+                        prior: previous ? readMobileQa(join(root, PLAYTEST_DIR, String(previous), 'mobile', 'mobile-qa.json')).verdict ?? null : null,
+                    });
+                    prompts.push(plan.mobile.seat);
+                }
+            }
+            if (opts.json) {
+                io.log(JSON.stringify({ n: plan.n, prompts, facts: record.facts, player_round: round?.round ?? null, loop: after.notes }, null, 2));
+                return EXIT.pass;
+            }
+            for (const l of after.notes)
+                u.item('note', l);
+            if (!round)
+                u.item('warn', 'no blind round was filed since this playtest was prepared: the long session\'s pacing and its come-back answer are missing from the evidence (file the round, then run this again)');
+            for (const f of record.facts)
+                u.item(/not measured|none|not asked|not addressed/.test(f.text) ? 'not_observed' : 'note', `${f.id} ${f.instrument}`, f.text);
+            u.line('experience seats (one fresh agent each, in parallel, handed only its prompt file):');
+            for (const p of prompts)
+                u.line(p, 4);
+            u.summary('pass', 'run the experience seats, then `funtools playtest report`');
+            return EXIT.pass;
+        }
+        catch (e) {
+            u.error(`experience failed: ${e.message}`);
+            return EXIT.error;
+        }
+    }
+    if (opts.sub === 'status') {
+        const plan = latest ? planOf(root, latest) : null;
+        if (!plan) {
+            u.error('no playtest here yet', 'run `funtools playtest` first');
+            return EXIT.error;
+        }
+        const dir = join(root, '.funtools', 'playtest', String(plan.n));
+        const xp = plan.experience?.seats ?? [];
+        const owed = [
+            ...plan.seats.filter((s) => !existsSync(join(dir, 'seats', `${s}.json`))).map((s) => `critic seat ${s}: ${join(dir, 'seats', `${s}.md`)}`),
+            ...plan.versus.calls.filter((c) => !existsSync(join(dir, 'versus', `${c}.json`))).map((c) => `head to head ${c}: ${join(dir, 'versus', `${c}.md`)}`),
+            ...(plan.fidelity?.seat && !existsSync(join(dir, 'fidelity', 'fidelity.json')) ? [`fidelity seat: ${plan.fidelity.seat}`] : []),
+            ...(plan.mobile?.seat && !existsSync(join(dir, 'mobile', 'mobile-qa.json')) ? [`Mobile QA seat: ${plan.mobile.seat}`] : []),
+            ...(existsSync(join(dir, 'fidelity', 'ui.md')) && !existsSync(join(dir, 'fidelity', 'ui.json')) ? [`UI fidelity seat: ${join(dir, 'fidelity', 'ui.md')}`] : []),
+            ...(existsSync(join(dir, 'ledger', 'ledger.md')) && !existsSync(join(dir, 'ledger', 'ledger.json')) ? [`ledger seat (last round's blockers): ${join(dir, 'ledger', 'ledger.md')}`] : []),
+            ...(playerRound(root, plan.at) ? [] : [`blind player round: ${plan.player.brief}`]),
+            ...(xp.length && !existsSync(join(dir, 'experience', 'depth.json')) ? ['experience: run `funtools playtest experience` after the blind round'] : xp.filter((s) => !existsSync(join(dir, 'experience', `${s}.json`))).map((s) => `experience seat ${s}: ${join(dir, 'experience', `${s}.md`)}`)),
+        ];
+        if (opts.json) {
+            io.log(JSON.stringify({ n: plan.n, owed, report: existsSync(join(dir, 'report.md')) }, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`playtest ${plan.n} · ${owed.length ? `${owed.length} owed` : 'every seat filed'}`);
+        for (const o of owed)
+            u.item('not_observed', o);
+        u.summary('pass', owed.length ? 'run the owed seats, then `funtools playtest report`' : '`funtools playtest report` writes the report');
+        return EXIT.pass;
+    }
+    if (!opts.json) {
+        u.heading(`playtest ${(latest ?? 0) + 1} · ${manifest.name ?? root}${opts.quick ? ' · quick' : ''}`);
+        for (const l of costLine(opts.quick, opts.long))
+            u.item('note', l);
+        const third = beforeRound(readHistory(root), milestoneOf(root, null));
+        if (third)
+            u.item('warn', third);
+    }
+    const note = (line) => { if (!opts.json)
+        u.item('note', line); };
+    let r;
+    try {
+        r = await prepare(root, manifest, { quick: opts.quick, build: opts.build, versus: opts.versus, long: opts.long, phone: opts.phone, sim: opts.sim, note });
+    }
+    catch (e) {
+        u.error(`playtest failed: ${e instanceof Error ? e.message : String(e)}`);
+        return EXIT.error;
+    }
+    const { plan, dir, measures } = r;
+    if (opts.json) {
+        io.log(JSON.stringify({ plan, dir, measures }, null, 2));
+        return measures.build.ok ? EXIT.pass : EXIT.fail;
+    }
+    if (!measures.build.ok) {
+        u.item('fail', 'the build failed: nothing to judge', measures.build.tail);
+        u.summary('fail', 'fix the build, then playtest again');
+        return EXIT.fail;
+    }
+    if (plan.premise.draft)
+        u.item('warn', `the store description is a draft from funpixel.json: write 4–6 neutral sentences to ${join(root, PREMISE_FILE)} (what it is and what the player does, no intentions)`);
+    u.item(plan.versus.ran ? 'pass' : 'skip', `head to head: ${plan.versus.note}`);
+    u.line(`seats (one fresh agent each, in parallel, handed only its prompt file):`);
+    for (const s of plan.seats)
+        u.line(`critic ${s}: ${join(dir, 'seats', `${s}.md`)}`, 4);
+    for (const c of plan.versus.calls)
+        u.line(`head to head ${c}: ${join(dir, 'versus', `${c}.md`)}`, 4);
+    if (plan.fidelity?.seat)
+        u.line(`fidelity (the plan's target frames against the game's, ${plan.fidelity.pairs} moment(s)): ${plan.fidelity.seat}`, 4);
+    if (plan.mobile?.seat)
+        u.line(`Mobile QA (the \`mobile-qa\` agent; ${plan.mobile.platforms.filter((p) => p.observed).map((p) => p.id).join(', ') || 'no phone'} observed): ${plan.mobile.seat}`, 4);
+    u.line(`blind player (the player agent, phone${plan.player.long_minutes ? `, a ${plan.player.long_minutes}-minute session` : ''}): ${plan.player.brief}`, 4);
+    if (!plan.fidelity?.seat)
+        u.item('skip', `fidelity: ${plan.fidelity?.facts[0]?.text ?? 'not prepared'}`);
+    if (!plan.mobile?.seat)
+        u.item('skip', `Mobile QA: ${plan.mobile?.facts[0]?.text ?? 'not prepared'}`);
+    else if (!plan.mobile.platforms.some((p) => p.id.startsWith('ios-') && p.observed))
+        u.item('note', 'Mobile QA: no real Mobile Safari run on this build — `funtools phone` (and `--orientation landscape`), or `playtest --phone`, gives the seat iOS Safari');
+    u.summary('pass', `prepared in ${measures.seconds} s — run the seats; after the blind round, \`funtools playtest experience\` and its seats; then \`funtools playtest report\``);
+    return EXIT.pass;
+}

package/dist/commands/profile.js

@@ -0,0 +1,292 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { age, burnLine, compareSnapshots, conditionsDiffer, deltaLine, DEFAULT_BUDGET_MS, gpuLine, NEUTRAL_BAND_PCT, openSnapshotStore, sameConditions, snapshotOf, } from "../profile/compare.js";
+import { launch, lookPage, viewportUrl } from "../verify/browser.js";
+import { drive, evalJson, load, openTarget } from "../look/look.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { rendererFact, timingVoid } from "../verify/gpu.js";
+import { ui } from "../ui.js";
+import { autoLog } from "../feedback/auto.js";
+import { FRAME_BUDGET_MS, patchBoard } from "../status/board.js";
+export const PROFILE_LIMITS = { frames: [30, 600], settleMs: [0, 20_000], throttle: [1, 20], repeat: [1, 9], budgetMs: [4, 100] };
+export const HISTORY_KEEP = 30;
+const TIMED = ['frame_ms_avg', 'frame_ms_p50', 'frame_ms_p95', 'frame_ms_p99', 'frame_ms_max', 'work_ms_p50', 'work_ms_p95', 'fps', 'long_frames', 'heap_mb'];
+export function merge(samples) {
+    if (samples.length === 1)
+        return samples[0];
+    const out = { ...samples[Math.floor(samples.length / 2)] };
+    for (const k of TIMED) {
+        const xs = samples.map((x) => x[k]).filter((x) => typeof x === 'number').sort((a, b) => a - b);
+        if (xs.length)
+            out[k] = xs[Math.floor(xs.length / 2)];
+    }
+    const p95 = samples.map((x) => x.frame_ms_p95).sort((a, b) => a - b);
+    out.repeat = { runs: samples.length, frame_ms_p95_range: [p95[0], p95[p95.length - 1]] };
+    if (samples.every((x) => Array.isArray(x.frame_ms_samples)))
+        out.frame_ms_samples = samples.flatMap((x) => x.frame_ms_samples);
+    return out;
+}
+export const PROFILE_DIR = join('.funtools', 'profile');
+const KINDS = {
+    '.js': 'script', '.mjs': 'script', '.css': 'style', '.html': 'html',
+    '.png': 'image', '.jpg': 'image', '.jpeg': 'image', '.webp': 'image', '.avif': 'image', '.gif': 'image', '.svg': 'image', '.ktx2': 'image',
+    '.mp3': 'audio', '.m4a': 'audio', '.ogg': 'audio', '.wav': 'audio',
+    '.glb': 'model', '.gltf': 'model', '.bin': 'model', '.woff': 'font', '.woff2': 'font', '.ttf': 'font', '.otf': 'font',
+};
+export async function distSize(dir) {
+    const root = join(dir, 'dist');
+    if (!existsSync(root))
+        return null;
+    const out = { kb: 0, by_kind: {}, files: 0 };
+    const walk = async (d) => {
+        for (const e of await readdir(d, { withFileTypes: true })) {
+            const p = join(d, e.name);
+            if (e.isDirectory()) {
+                await walk(p);
+                continue;
+            }
+            const kb = (await stat(p)).size / 1024, kind = KINDS[extname(e.name).toLowerCase()] ?? 'other';
+            out.kb += kb;
+            out.files++;
+            out.by_kind[kind] = (out.by_kind[kind] ?? 0) + kb;
+        }
+    };
+    await walk(root);
+    out.kb = Math.round(out.kb);
+    for (const k of Object.keys(out.by_kind))
+        out.by_kind[k] = Math.round(out.by_kind[k]);
+    return out;
+}
+export function delta(before, now) {
+    const rows = [
+        ['frame p50 ms', (s) => s.frame_ms_p50, 1], ['frame p95 ms', (s) => s.frame_ms_p95, 1],
+        ['frame max ms', (s) => s.frame_ms_max, 1], ['long frames', (s) => s.long_frames, 0],
+        ['JS work p50 ms', (s) => s.work_ms_p50, 2], ['JS work p95 ms', (s) => s.work_ms_p95, 2],
+        ['draw calls', (s) => s.draw_calls, 0], ['triangles', (s) => s.triangles, 0],
+        ['texture MB', (s) => s.scene?.texture_mb, 1], ['heap MB', (s) => s.heap_mb, 1],
+        ['fetched KB', (s) => s.load?.kb, 0], ['dist KB', (s) => s.dist?.kb, 0],
+    ];
+    const out = [];
+    for (const [name, get, dp] of rows) {
+        const a = get(before), b = get(now);
+        if (typeof a !== 'number' || typeof b !== 'number' || a === b)
+            continue;
+        const pct = a ? ` (${b >= a ? '+' : ''}${Math.round(((b - a) / a) * 100)}%)` : '';
+        out.push(`${name} ${a.toFixed(dp)} → ${b.toFixed(dp)}${pct}`);
+    }
+    return out;
+}
+export function describe(s) {
+    const lines = s.timing_void ? [`frame times NOT OBSERVED — ${s.timing_void}`] : [
+        `frame ms p50 ${s.frame_ms_p50} · p95 ${s.frame_ms_p95} · p99 ${s.frame_ms_p99} · max ${s.frame_ms_max} · ${s.long_frames} over 33 ms · ~${s.fps} fps (${s.frames} frames${s.repeat ? `; median of ${s.repeat.runs} runs, p95 ranged ${s.repeat.frame_ms_p95_range.join('–')} ms` : ''})`,
+        `JS work a frame (the game's update + render submit, not capped by the display) p50 ${s.work_ms_p50} ms · p95 ${s.work_ms_p95} ms`,
+    ];
+    const draws = typeof s.draw_calls === 'number' ? `${s.draw_calls} draw calls · ${s.triangles ?? 0} triangles a frame` : 'draw calls not observed';
+    const sc = s.scene ?? {};
+    if (s.engine === 'three')
+        lines.push(`three: ${draws} · ${sc.meshes ?? '–'} meshes (${sc.instances ?? 0} instances) · ${sc.points ?? 0} points · ${sc.lights ?? '–'} lights (${sc.shadow_lights ?? 0} casting shadows) · ${sc.materials ?? '–'} materials · ${s.programs ?? '–'} shader programs`);
+    else if (s.engine === 'pixi')
+        lines.push(`pixi: ${draws} · ${sc.visible ?? '–'} visible of ${s.objects ?? '–'} objects: ${sc.sprites ?? 0} sprites, ${sc.graphics ?? 0} graphics, ${sc.text ?? 0} text, ${sc.particles ?? 0} particles; ${sc.filtered ?? 0} with filters`);
+    else
+        lines.push(`${draws}; no engine globals (window.__PIXI_APP__, or __THREEJS_RENDERER__ + __THREEJS_SCENE__) to read the scene from`);
+    const mem = [`textures ${s.textures ?? '–'}`, typeof sc.texture_mb === 'number' ? `~${sc.texture_mb} MB estimated` : null, typeof s.heap_mb === 'number' ? `JS heap ${s.heap_mb} MB` : null].filter(Boolean);
+    lines.push(mem.join(' · '));
+    if (s.load)
+        lines.push(`fetched ${s.load.requests} requests, ${s.load.kb} KB (${Object.entries(s.load.by_kind ?? {}).map(([k, v]) => `${k} ${v}`).join(', ') || 'none'}) · DOM ready ${s.load.dom_ms} ms · load ${s.load.load_ms} ms`);
+    if (s.dist)
+        lines.push(`dist ${s.dist.kb} KB in ${s.dist.files} files (${Object.entries(s.dist.by_kind).map(([k, v]) => `${k} ${v}`).join(', ')})`);
+    const canvas = s.canvas_px ? `canvas ${s.canvas_px.join('x')} @ DPR ${s.dpr}` : 'no canvas';
+    lines.push(`${canvas} · renderer ${s.gpu}${s.software ? (s.timing_void ? ' (SOFTWARE)' : ' (software, as asked: compare runs, not against a phone)') : ''}`);
+    return lines;
+}
+async function readSample(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function sampleView(browser, url, orientation, opts, view, hooks) {
+    const page = await lookPage(browser, opts.viewport, orientation);
+    try {
+        if (opts.seed !== null)
+            await page.addInitScript(`window.__FPX_SEED__ = ${JSON.stringify(opts.seed)};`);
+        if (opts.throttle && opts.throttle > 1) {
+            const cdp = await page.context().newCDPSession(page);
+            await cdp.send('Emulation.setCPUThrottlingRate', { rate: opts.throttle });
+        }
+        await load(page, url, hooks);
+        await evalJson(page, 'renderer', { op: 'install' });
+        const driven = await drive(page, { view, verbs: [], holdMs: opts.settleMs, freeze: false, click: opts.click });
+        const entered = view === null || driven.view?.entered === true;
+        if (!entered)
+            return { entered, error: driven.view?.error || 'the page refused', sample: null };
+        const sample = await evalJson(page, 'perf', { view: null, frames: opts.frames, warmup: 20, ...(opts.compare ? { samples: true, gpu: true } : {}) });
+        return { entered, error: sample ? '' : 'the page answered nothing', sample, state: driven.view?.state ?? null };
+    }
+    finally {
+        await page.close().catch(() => { });
+    }
+}
+async function compareRun(sample, view, opts, dir, base) {
+    const conditions = {
+        view, viewport: opts.viewport, seed: opts.seed, throttle: opts.throttle ?? 1, software: !!opts.software,
+        frames: opts.frames * (opts.repeat ?? 1), budget_ms: opts.budgetMs ?? DEFAULT_BUDGET_MS,
+    };
+    let buildId = null;
+    if (dir) {
+        try {
+            buildId = (await fingerprint(dir)).fingerprint.slice(0, 19);
+        }
+        catch { }
+    }
+    const snapshot = snapshotOf(sample, conditions, { gameId: dir ? basename(dir) : 'url', buildId });
+    if (!snapshot)
+        return null;
+    const history = join(base, 'history', `${view}-${opts.viewport}.jsonl`);
+    const store = openSnapshotStore(history);
+    const prior = await store.getLast(conditions);
+    const newest = await store.getNewest();
+    const skipped = newest && !sameConditions(newest.conditions, conditions) ? conditionsDiffer(conditions, newest.conditions) : [];
+    await store.put(snapshot);
+    await store.prune(HISTORY_KEEP);
+    return { snapshot, prior, skipped, deltas: prior ? compareSnapshots(snapshot, prior) : [], history };
+}
+export function compareLines(c) {
+    const s = c.snapshot, lines = [];
+    const same = s.buildId && c.prior?.buildId === s.buildId ? ' (the same build: this is the noise between two runs)' : '';
+    if (c.skipped.length)
+        lines.push(`the last run of this view was made another way (${c.skipped.join(', ')}): not compared with it`);
+    if (!c.prior)
+        lines.push('first run under these conditions: the next one compares against it');
+    else {
+        const moved = c.deltas.filter((d) => d.severity !== 'neutral');
+        const kept = c.deltas.filter((d) => d.severity === 'neutral').map((d) => d.label);
+        lines.push(`against the last run under the same conditions (${age(s.capturedAt - c.prior.capturedAt)})${same}:`);
+        lines.push(`  ${moved.length ? moved.map(deltaLine).join(' · ') : `no change beyond ±${NEUTRAL_BAND_PCT}%`}`);
+        if (moved.length && kept.length)
+            lines.push(`  within ±${NEUTRAL_BAND_PCT}%: ${kept.join(', ')}`);
+    }
+    lines.push(burnLine(s, c.prior));
+    lines.push(gpuLine(s));
+    lines.push(`${s.sampleCount} frames · p50 ${s.frameTimeMs.p50} · p95 ${s.frameTimeMs.p95} · p99 ${s.frameTimeMs.p99} ms · history ${c.history}`);
+    return lines;
+}
+export function framePart(views, budget) {
+    const got = views.filter((v) => typeof v.p95 === 'number' && Number.isFinite(v.p95) && v.p95 > 0);
+    if (!got.length)
+        return null;
+    const worst = Math.max(...got.map((v) => v.p95));
+    return { value: Math.round(worst * 10) / 10, by: 'profile', budget, detail: got.sort((a, b) => b.p95 - a.p95).map((v) => `${v.view} p95 ${v.p95} ms${v.p95 > budget ? ` (over ${budget})` : ''}`) };
+}
+export async function profile(opts, io = console) {
+    const u = ui(io, 'profile');
+    const t = await openTarget(opts.target);
+    if (typeof t === 'string') {
+        u.error(t, 'build the game first (npm run build)');
+        return EXIT.error;
+    }
+    const results = [];
+    let browser;
+    try {
+        browser = (await launch(!!opts.software)).browser;
+        const orientation = typeof t.manifest.metadata?.orientation === 'string' ? t.manifest.metadata.orientation : '';
+        const url = viewportUrl(t.url, opts.viewport);
+        const hooks = hookMapOf(t.manifest);
+        let views = opts.views;
+        if (!views.length) {
+            const probe = await lookPage(browser, opts.viewport, orientation);
+            await load(probe, url, hooks);
+            const declared = (await evalJson(probe, 'capture_view', { view: null, verbs: [], verb_gap_ms: 0, hold_ms: 0, freeze: false }))?.views ?? [];
+            await probe.close();
+            const motion = declared.filter((v) => v.motion).map((v) => v.name);
+            views = motion.length ? motion : [null];
+        }
+        const dist = t.dir ? await distSize(t.dir) : null;
+        const base = t.dir ? join(t.dir, PROFILE_DIR) : resolve(PROFILE_DIR);
+        for (const view of views) {
+            const name = view ?? 'as-loaded';
+            let r = await sampleView(browser, url, orientation, opts, view, hooks);
+            if (r.sample && !r.sample.error && (opts.repeat ?? 1) > 1) {
+                const all = [r.sample];
+                for (let i = 1; i < (opts.repeat ?? 1); i++) {
+                    const again = await sampleView(browser, url, orientation, opts, view, hooks);
+                    if (again.sample && !again.sample.error)
+                        all.push(again.sample);
+                }
+                r = { ...r, sample: merge(all) };
+            }
+            const file = join(base, `${name}-${opts.viewport}.json`);
+            const before = opts.against ? await readSample(resolve(opts.against)) : await readSample(file);
+            let sample = null;
+            let cmp = null;
+            if (r.sample && !r.sample.error) {
+                const { frame_ms_samples, work_ms_samples, ...kept } = r.sample;
+                const timing_void = timingVoid(rendererFact(kept.gpu === 'unknown' ? null : kept.gpu), !!opts.software);
+                sample = { ...kept, view: name, viewport: opts.viewport, seed: opts.seed, throttle: opts.throttle ?? 1, state: r.state ?? null, dist, at: new Date().toISOString(), ...(timing_void ? { timing_void } : {}) };
+                await mkdir(base, { recursive: true });
+                if (!timing_void)
+                    await writeFile(file, JSON.stringify(sample, null, 2) + '\n');
+                if (!timing_void && t.dir && opts.viewport && !opts.throttle)
+                    autoLog(t.dir, 'profile', `frame p95 ${name} ${opts.viewport}`, sample.frame_ms_p95, 'ms', file);
+                if (opts.compare && !timing_void)
+                    cmp = await compareRun({ ...sample, frame_ms_samples }, name, opts, t.dir, base);
+            }
+            results.push({ view: name, entered: r.entered, error: r.sample?.error ?? r.error, sample, before, file: sample && !sample.timing_void ? file : null, cmp });
+        }
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        await t.close();
+    }
+    const measured = results.filter((r) => r.sample && !r.sample.timing_void);
+    const voided = results.filter((r) => r.sample?.timing_void);
+    if (t.dir && !opts.software && (opts.throttle ?? 1) <= 1) {
+        const f = framePart(measured.map((r) => ({ view: r.view, p95: r.sample.frame_ms_p95 })), opts.budgetMs ?? FRAME_BUDGET_MS);
+        if (f)
+            patchBoard(t.dir, { frame_ms: { [opts.viewport]: f } });
+    }
+    if (opts.json) {
+        io.log(JSON.stringify({ viewport: opts.viewport, seed: opts.seed, views: results.map((r) => ({
+                view: r.view, entered: r.entered, error: r.error || undefined, file: r.file, sample: r.sample, before: r.before,
+                delta: r.sample && r.before && !r.sample.timing_void ? delta(r.before, r.sample) : [],
+                ...(r.cmp ? { compare: { ...r.cmp, lines: compareLines(r.cmp) } } : {}),
+            })) }, null, 2));
+    }
+    else {
+        u.heading(`profile · ${opts.viewport}${opts.seed !== null ? ` · seed ${opts.seed}` : ''}${opts.software ? ' · software renderer' : ''}${opts.throttle && opts.throttle > 1 ? ` · CPU ÷${opts.throttle}` : ''}`);
+        for (const r of results) {
+            if (!r.sample) {
+                u.item('not_observed', r.view, r.error);
+                continue;
+            }
+            u.item(r.sample.timing_void ? 'not_observed' : 'pass', r.view);
+            for (const l of describe(r.sample))
+                u.line(`  ${l}`);
+            if (r.sample.timing_void) {
+                u.line('  not compared, not kept as the run to compare against');
+            }
+            else if (r.cmp) {
+                for (const l of compareLines(r.cmp))
+                    u.line(`  ${l}`);
+            }
+            else if (r.before) {
+                const d = delta(r.before, r.sample);
+                const same = r.before.seed === r.sample.seed && r.before.viewport === r.sample.viewport
+                    && (r.before.throttle ?? 1) === (r.sample.throttle ?? 1) && r.before.software === r.sample.software;
+                u.line(`  against ${r.before.at}${same ? '' : ' (another seed, viewport, renderer or throttle: not the same test)'}: ${d.length ? d.join(' · ') : 'no change in the numbers'}`);
+            }
+            else
+                u.line('  first run of this view here: the next run compares against it');
+            if (r.file)
+                u.line(`  ${r.file}`);
+        }
+        const voidNote = voided.length ? ` · ${voided.length} view(s) VOID: rendered on software GL, frame times not observed` : '';
+        u.summary(measured.length ? 'pass' : 'not_observed', `${measured.length ? `${measured.length} view(s) measured — numbers, not a verdict` : 'nothing measured'}${voidNote}`);
+    }
+    return measured.length ? EXIT.pass : EXIT.not_observed;
+}