@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/rooms.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { crashLine, nodeScript, parseProbe, stderrLines } from "./sim.js";
+import { ui } from "../ui.js";
+import { clock, isOpened, OPEN_FILE, PAR_BAND, readOpen, readRoomsRecord, ROOM_SEEDS, ROOMS_RECORD, sliceRoom, specRooms, uniqueRooms } from "../spec/rooms.js";
+import { playFloor } from "../sim/judge.js";
+import { evaluate, readPipeline } from "../pipeline/pipeline.js";
+import { planAgreement } from "../flow/flow.js";
+export const ROOMS_SCRIPT = join('test', 'rooms.ts');
+export const ROOMS_SUBCOMMANDS = ['run', 'open', 'plan'];
+const statOf = (c, i) => {
+    if (!c)
+        return null;
+    const l = c.levels?.find((x) => x.level === i + 1);
+    return { policy: c.policy, seeds: c.seeds, reached: l?.reached ?? 0, cleared: l?.cleared ?? 0, seconds: l && l.reached ? l.meanSeconds : null };
+};
+export function judgeRoom(r, i, cohorts) {
+    const careful = statOf(cohorts.find((c) => c.human && c.role === 'skilled'), i);
+    const skilled = statOf(cohorts.find((c) => !c.human && c.role === 'skilled'), i);
+    const naive = statOf(cohorts.find((c) => c.role === 'naive'), i), novice = statOf(cohorts.find((c) => c.role === 'novice'), i);
+    const problems = [];
+    if (!careful)
+        problems.push('no careful player played it (a humanRate twin of the sharp bot in test/rooms.ts)');
+    else if (careful.cleared < careful.seeds)
+        problems.push(careful.reached < careful.seeds ? `a careful player reached it on ${careful.reached} of ${careful.seeds} seeds` : `a careful player cleared it on ${careful.cleared} of ${careful.seeds} seeds (a wall for people)`);
+    if (skilled && skilled.reached === skilled.seeds && skilled.cleared < skilled.seeds)
+        problems.push(`the sharp bot cleared it on ${skilled.cleared} of ${skilled.seeds}: a broken bot or a broken room`);
+    if (r.par === null)
+        problems.push('no par');
+    else if (careful?.seconds != null && Math.abs(careful.seconds - r.par) > r.par * PAR_BAND)
+        problems.push(`a careful player takes ${clock(careful.seconds)} against a par of ${clock(r.par)}: more than ${Math.round(PAR_BAND * 100)}% off, the par is a guess (move it, or the room)`);
+    const time = careful?.seconds != null ? `${clock(careful.seconds)} against par ${r.par === null ? '—' : clock(r.par)}` : 'not timed';
+    return { id: r.id, name: r.name, par: r.par, careful, skilled, naive, novice, verdict: problems.length ? 'fail' : 'pass', says: problems.length ? problems.join('; ') : `a careful player clears it on ${careful.cleared} of ${careful.seeds} seeds, ${time}` };
+}
+const pct = (s) => (s && s.reached ? `${s.cleared}/${s.seeds} ${s.seconds != null ? clock(s.seconds) : ''}`.trim() : '—');
+async function run(opts, io, runner) {
+    const u = ui(io, 'rooms');
+    const root = resolve(opts.dir ?? '.');
+    const rooms = uniqueRooms(specRooms(root).rooms);
+    const script = opts.script ?? ROOMS_SCRIPT;
+    if (!rooms.length || !existsSync(join(root, script))) {
+        const why = !rooms.length ? 'no rooms as data (design/spec/rooms.json)' : `no ${script}`;
+        if (opts.json)
+            io.log(JSON.stringify({ tool: 'funtools', command: 'rooms', exit: EXIT.not_observed, says: why }, null, 2));
+        else
+            u.summary('not_observed', `${why} — the big tier writes both: npx @funpixel/tools spec init`);
+        return EXIT.not_observed;
+    }
+    const fp = (await fingerprint(root)).fingerprint;
+    const timeout = opts.timeout && opts.timeout > 0 ? opts.timeout : 300;
+    const res = await runner(root, script, timeout * 1000);
+    if (res.code !== 0 || res.timedOut) {
+        if (!opts.json)
+            for (const l of stderrLines(res.stderr))
+                u.line(`stderr: ${l}`, 2);
+        u.error(res.timedOut ? `${script} ran past ${timeout} s` : `${script} exited ${res.code}: ${crashLine(res.stderr)}`, res.timedOut ? `--timeout ${timeout * 2}` : `run it yourself: node --import ./test/resolve.mjs ${script}`);
+        return EXIT.error;
+    }
+    const out = parseProbe(res.stdout);
+    if (!out || !Array.isArray(out.cohorts)) {
+        u.error(`${script} printed no cohorts`, `run it yourself: node --import ./test/resolve.mjs ${script}`);
+        return EXIT.error;
+    }
+    const order = Array.isArray(out.rooms) ? out.rooms.map((x) => rooms.find((r) => r.id === x.id)).filter((r) => !!r) : rooms;
+    const rows = order.map((r, i) => judgeRoom(r, i, out.cohorts));
+    const floor = playFloor(root);
+    const parTotal = rooms.reduce((s, r) => s + (r.par ?? 0), 0);
+    const played = rows.every((r) => r.careful?.seconds != null) ? rows.reduce((s, r) => s + (r.careful.seconds ?? 0), 0) : null;
+    const failing = rows.filter((r) => r.verdict === 'fail');
+    const exit = failing.length ? EXIT.fail : EXIT.pass;
+    const seeds = out.cohorts[0]?.seeds ?? ROOM_SEEDS;
+    const record = { tool: 'funtools', command: 'rooms', script, exit, fingerprint: fp, at: (opts.now ?? new Date()).toISOString(), seeds, rooms: rows, par_total: parTotal, floor, played_total: played };
+    mkdirSync(dirname(join(root, ROOMS_RECORD)), { recursive: true });
+    writeFileSync(join(root, ROOMS_RECORD), JSON.stringify(record, null, 2) + '\n');
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return exit;
+    }
+    u.heading(`rooms · ${rows.length} rooms · ${seeds} seeds each · careful / sharp / naive / novice: cleared, mean time`);
+    for (const r of rows)
+        u.item(r.verdict === 'pass' ? 'pass' : 'warn', `${r.id} ${r.name} (par ${r.par === null ? '—' : clock(r.par)}): careful ${pct(r.careful)} · sharp ${pct(r.skilled)} · naive ${pct(r.naive)} · novice ${pct(r.novice)}`, r.verdict === 'pass' ? undefined : r.says);
+    u.heading('length');
+    u.item(parTotal >= floor.seconds ? 'pass' : 'warn', `the pars add up to ${clock(parTotal)} against the play floor of ${clock(floor.seconds)} (${floor.where})`, parTotal >= floor.seconds ? undefined : 'more rooms, or bigger ones');
+    if (played !== null)
+        u.item('note', `a careful player's whole campaign: ${clock(played)} (retries included)`);
+    u.summary(failing.length || parTotal < floor.seconds ? 'warn' : 'pass', `${rows.length - failing.length} of ${rows.length} rooms pass (${ROOMS_RECORD})`);
+    return exit;
+}
+async function sliceGates(root) {
+    const p = readPipeline(root);
+    if (!p)
+        return [];
+    const e = evaluate(root, p, (await fingerprint(root)).fingerprint);
+    return e.stages.filter((s) => (s.stage.id === 'core-test' || s.stage.id === 'slice') && !s.done).map((s) => `${s.stage.title}: ${s.gates.find((g) => g.state !== 'met')?.says ?? 'open'}`);
+}
+async function open(opts, io) {
+    const u = ui(io, 'rooms open');
+    const root = resolve(opts.dir ?? '.');
+    const rooms = uniqueRooms(specRooms(root).rooms);
+    const i = rooms.findIndex((r) => r.id === opts.room);
+    if (!opts.room || i < 0) {
+        u.error(opts.room ? `no room "${opts.room}" in design/spec/rooms.json` : 'which room?', `rooms: ${rooms.map((r) => r.id).join(', ') || 'none (spec init writes them)'}`);
+        return EXIT.error;
+    }
+    const rec = readOpen(root), room = rooms[i];
+    const say = (ok, text, next) => {
+        if (opts.json)
+            io.log(JSON.stringify({ ok, room: room.id, says: text, ...(next ? { next } : {}) }, null, 2));
+        else
+            u.summary(ok ? 'pass' : 'fail', next ? `${text} — ${next}` : text);
+        return ok ? EXIT.pass : EXIT.fail;
+    };
+    if (isOpened(rec, rooms, room.id))
+        return say(true, `${room.id} is already open${sliceRoom(rooms)?.id === room.id ? ' (the slice)' : ''}`);
+    const why = [];
+    const closed = rooms.slice(0, i).filter((r) => !isOpened(rec, rooms, r.id)).map((r) => r.id);
+    if (closed.length)
+        why.push(`open in turn: ${closed.join(', ')} ${closed.length === 1 ? 'is' : 'are'} not open yet`);
+    const prev = rooms[i - 1];
+    if (prev) {
+        const record = readRoomsRecord(root);
+        const fp = (await fingerprint(root)).fingerprint;
+        const row = record?.rooms.find((r) => r.id === prev.id);
+        if (!record)
+            why.push('the bots never played the rooms (npx @funpixel/tools rooms)');
+        else if (record.fingerprint && record.fingerprint !== fp)
+            why.push('the rooms were played on older files (npx @funpixel/tools rooms)');
+        else if (!row)
+            why.push(`${prev.id} was not played`);
+        else if (row.verdict !== 'pass')
+            why.push(`${prev.id} does not pass: ${row.says}`);
+        if (sliceRoom(rooms)?.id === prev.id)
+            why.push(...(await sliceGates(root)).map((s) => `the slice: ${s}`));
+    }
+    const now = (opts.now ?? new Date()).toISOString();
+    const owner = opts.by === 'owner';
+    if (why.length && !owner)
+        return say(false, `${room.id} stays closed: ${why.join('; ')}`, `make ${prev?.id ?? 'the slice'} pass first (slice first); only the owner can release it early: npx @funpixel/tools rooms open ${room.id} --by owner "why"`);
+    rec.opened.push({ room: room.id, at: now, by: owner && why.length ? 'owner' : 'gates', says: why.length ? `released by the owner past: ${why.join('; ')}${opts.words ? ` — "${opts.words}"` : ''}` : `${prev?.id ?? 'the slice'} passes` });
+    mkdirSync(dirname(join(root, OPEN_FILE)), { recursive: true });
+    writeFileSync(join(root, OPEN_FILE), JSON.stringify(rec, null, 2) + '\n');
+    if (why.length && !opts.json)
+        u.item('warn', `released by the owner past its gates: ${why.join('; ')}`);
+    return say(true, `${room.id} ${room.name} is open: build it, then npx @funpixel/tools rooms`);
+}
+async function plan(opts, io) {
+    const u = ui(io, 'rooms plan');
+    const root = resolve(opts.dir ?? '.');
+    const rooms = uniqueRooms(specRooms(root).rooms);
+    if (!rooms.length) {
+        u.summary('not_observed', 'no rooms as data (design/spec/rooms.json) — npx @funpixel/tools spec init');
+        return EXIT.not_observed;
+    }
+    const agreed = planAgreement(root).agreed;
+    if (agreed && opts.by !== 'owner') {
+        if (opts.json)
+            io.log(JSON.stringify({ ok: false, says: 'the plan is agreed' }, null, 2));
+        else
+            u.summary('fail', 'the plan is agreed: a room changed now is built, not planned — open rooms in turn (npx @funpixel/tools rooms open <id>), or the owner re-plans: rooms plan --by owner');
+        return EXIT.fail;
+    }
+    const rec = readOpen(root);
+    rec.planned = Object.fromEntries(rooms.map((r) => [r.id, r.hash]));
+    mkdirSync(dirname(join(root, OPEN_FILE)), { recursive: true });
+    writeFileSync(join(root, OPEN_FILE), JSON.stringify(rec, null, 2) + '\n');
+    if (opts.json)
+        io.log(JSON.stringify({ ok: true, planned: Object.keys(rec.planned) }, null, 2));
+    else
+        u.summary('pass', `${rooms.length} rooms recorded as planned (${OPEN_FILE})${agreed ? ' by the owner, past the agreed plan' : ''}`);
+    return EXIT.pass;
+}
+export async function roomsCommand(opts, io = console, runner = nodeScript) {
+    if (!existsSync(resolve(opts.dir ?? '.'))) {
+        ui(io, 'rooms').error(`no such folder: ${opts.dir}`, 'run it in the game folder');
+        return EXIT.error;
+    }
+    return opts.sub === 'open' ? open(opts, io) : opts.sub === 'plan' ? plan(opts, io) : run(opts, io, runner);
+}

package/dist/commands/schema.js

@@ -0,0 +1,29 @@
+import { resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { validateGame } from "../schema/game.js";
+import { ui } from "../ui.js";
+export async function schema(opts, io = console) {
+    const u = ui(io, 'schema');
+    const root = resolve(opts.target ?? '.');
+    let report;
+    try {
+        report = validateGame(root, { strict: !!opts.strict });
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+    if (opts.json) {
+        io.log(JSON.stringify({ verdict: report.errors ? 'fail' : 'pass', ...report }, null, 2));
+        return report.errors ? EXIT.fail : EXIT.pass;
+    }
+    u.heading(`schema · ${report.files.length} file(s): ${report.files.join(', ') || 'none'}`);
+    for (const f of report.findings) {
+        const where = `${f.file}${f.path ? ` ${f.path}` : ''}`;
+        u.item(f.level === 'error' ? 'fail' : 'warn', where, `${f.what}${f.suggest?.length ? ` (did you mean ${f.suggest.join(' or ')}?)` : ''}`);
+    }
+    u.summary(report.errors ? 'fail' : report.warnings ? 'warn' : 'pass', report.errors
+        ? `${report.errors} error(s), ${report.warnings} warning(s): fix the errors; a reader drops what it cannot read and says so`
+        : report.warnings ? `no errors, ${report.warnings} warning(s)` : 'every file holds its shape');
+    return report.errors ? EXIT.fail : EXIT.pass;
+}

package/dist/commands/score.js

@@ -0,0 +1,326 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { targetFraming } from "./compare-target.js";
+import { launch, lookPage, viewportUrl } from "../verify/browser.js";
+import { drive, evalJson, load, openTarget } from "../look/look.js";
+import { CAPTURE_SEED, framingLine, holdClock, pause, readFraming } from "../look/held.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { imageType } from "../look/image-io.js";
+import { lightMoves, lightRead } from "../score/light.js";
+import { AXES, axis, cameraDelta, changedShare, densityScore, heroScore, layoutScore, lifeScore, overall, paletteScore } from "../score/measure.js";
+import { visionJudge } from "../score/vision.js";
+import { comfortRead, comfortVerdict } from "../score/comfort.js";
+import { decodePng } from "../look/png.js";
+import { decodePicture } from "../review/picture.js";
+import { patchBoard } from "../status/board.js";
+import { fixesFor, moveLine } from "../direct/moves.js";
+import { parseCamera, READ_CAMERA_JS } from "../direct/read.js";
+import { appendHistory, BAR_DEFAULT, fixLine, fixList, STRETCH_DEFAULT } from "../direct/round.js";
+import { ui } from "../ui.js";
+import { playerOf } from "../look/player.js";
+export const SCORES_FILE = join('design', 'look', 'scores.json');
+export const DEFAULT_BAR = BAR_DEFAULT;
+const SMALL = { width: 160, height: 90 };
+export function smallFor(frame, small = SMALL) {
+    const upright = frame.height > frame.width, long = Math.max(small.width, small.height), short = Math.min(small.width, small.height);
+    return upright ? { width: short, height: long } : { width: long, height: short };
+}
+export function comfortOfPicture(bytes, type, path) {
+    try {
+        if (type === 'image/png')
+            return comfortRead(decodePng(bytes));
+        if (!path)
+            return 'not a PNG and no file to decode';
+        return comfortRead(decodePicture(path).img);
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
+export function runComfort(moments) {
+    const read = moments.filter((m) => m.counted && m.comfort?.capture);
+    const v = comfortVerdict(read.map((m) => ({ name: m.moment, read: m.comfort.capture })), moments.map((m) => m.comfort?.target).filter((r) => !!r));
+    for (const m of read)
+        m.comfort.warnings = v.warnings.filter((w) => w.startsWith(`${m.moment}: `));
+    return v;
+}
+export function momentsOf(manifest) {
+    const list = Array.isArray(manifest?.moments) ? manifest.moments : [];
+    return list.filter((m) => m && typeof m.target === 'string').map((m, i) => ({
+        name: typeof m.name === 'string' ? m.name : m.view ?? `moment-${i + 1}`, view: typeof m.view === 'string' ? m.view : null, target: m.target,
+        hero: typeof m.hero === 'string' ? m.hero : null, heroShare: typeof m.hero_share === 'number' ? m.hero_share : null,
+    }));
+}
+async function raster(browser, bytes, type, w, h) {
+    const ctx = await browser.newContext({ viewport: { width: 200, height: 120 } });
+    try {
+        const page = await ctx.newPage();
+        const b64 = await page.evaluate(async ([src, W, H]) => {
+            const img = new Image();
+            img.src = src;
+            await img.decode();
+            const c = document.createElement('canvas');
+            c.width = W;
+            c.height = H;
+            const g = c.getContext('2d');
+            const s = Math.max(W / img.width, H / img.height);
+            g.imageSmoothingQuality = 'high';
+            g.drawImage(img, (W - img.width * s) / 2, (H - img.height * s) / 2, img.width * s, img.height * s);
+            const d = g.getImageData(0, 0, W, H).data;
+            let bin = '';
+            for (let i = 0; i < d.length; i += 0x8000)
+                bin += String.fromCharCode.apply(null, Array.from(d.subarray(i, i + 0x8000)));
+            return btoa(bin);
+        }, [`data:${type};base64,${Buffer.from(bytes).toString('base64')}`, w, h]);
+        return { width: w, height: h, data: new Uint8Array(Buffer.from(b64, 'base64')) };
+    }
+    finally {
+        await ctx.close().catch(() => { });
+    }
+}
+export function currentLight(world) {
+    const l = world?.light, g = world?.post?.grade;
+    if (!l || typeof l !== 'object')
+        return null;
+    const n = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+    return { exposure: n(l.exposure), ambient: n(l.ambient), spots: n(l.spots), preset: typeof l.preset === 'string' ? l.preset : null, place: typeof world.place === 'string' ? world.place : null, contrast: n(g?.contrast), saturation: n(g?.saturation), vignette: n(g?.vignette) };
+}
+async function shoot(page, url, manifest, m, viewport, frame, held) {
+    await load(page, viewportUrl(url, viewport), hookMapOf(manifest), held);
+    const driven = m.view ? await drive(page, { view: m.view, verbs: [], holdMs: 900, freeze: false, click: null }) : null;
+    if (m.view && driven?.view?.entered !== true)
+        return { png: await page.screenshot({ type: 'png' }), counted: false, why: `the view ${m.view} was not entered (${driven?.view?.error || 'refused'})`, heroShare: null, changed: null, animated: null };
+    let honest = await evalJson(page, 'frame_honesty', {});
+    for (let i = 0; i < 10 && honest?.loading; i++) {
+        await pause(page, 500, held);
+        honest = await evalJson(page, 'frame_honesty', {});
+    }
+    await evalJson(page, 'life_anim', { op: 'install', player: playerOf(manifest).pattern });
+    const png = await page.screenshot({ type: 'png' });
+    const framing = await readFraming(page, held);
+    const cam = parseCamera(await page.evaluate(READ_CAMERA_JS).catch(() => null));
+    const actors = await evalJson(page, 'world_actors', { max: 800 });
+    const heroId = m.hero ?? null;
+    const hero = Array.isArray(actors?.actors) ? actors.actors.find((a) => (heroId ? a.id === heroId || a.node === heroId : a.kind === 'player') && a.screen?.on) : null;
+    await pause(page, 3000, held);
+    const later = await page.screenshot({ type: 'png' });
+    const anim = await evalJson(page, 'life_anim', { op: 'stop' });
+    const living = Array.isArray(anim?.actors) ? anim.actors.filter((a) => a.role !== 'player') : [];
+    const tiny = smallFor(frame, { width: 64, height: 36 });
+    const pics = await Promise.all([png, later].map((b) => raster(page.context().browser(), b, 'image/png', tiny.width, tiny.height)));
+    return {
+        png, counted: !honest?.loading, why: honest?.loading ? `a loading or splash frame: ${(honest.why ?? []).join('; ')}` : null,
+        heroShare: hero?.screen?.share ?? null, changed: changedShare(pics[0], pics[1]),
+        light: currentLight(await page.evaluate('(() => { try { return window.__FPX_STATE__?.()?.world ?? null; } catch { return null; } })()').catch(() => null)),
+        animated: living.length ? { n: living.filter((a) => a.verdict === 'animated').length, of: living.length } : null, cam, framing,
+    };
+}
+export function heroWhy(today, m) {
+    if (today.heroShare === null)
+        return today.still ? 'not read: a still has no actors contract (score the live view to measure the hero)' : 'no hero on screen in the actors contract';
+    return m.heroShare === null ? `hero at ${Math.round(today.heroShare * 100)}% of the frame height; the target's hero_share is not set` : `hero at ${Math.round(today.heroShare * 100)}% of the frame height, the target's ${Math.round(m.heroShare * 100)}%`;
+}
+export function compositionScore(layout, camera) {
+    if (!camera.vanish)
+        return layout;
+    const d = Math.hypot(camera.vanish.target.x - camera.vanish.capture.x, camera.vanish.target.y - camera.vanish.capture.y);
+    return Math.round((layout + Math.max(0, 100 * (1 - d / 0.25))) / 2);
+}
+export async function scoreMoment(browser, m, today, target, bar, judge, frame = SMALL) {
+    const small = smallFor(frame);
+    const [c, t] = await Promise.all([raster(browser, today.png, 'image/png', small.width, small.height), raster(browser, target.bytes, target.type, small.width, small.height)]);
+    const pal = paletteScore(c, t), lay = layoutScore(c, t), den = densityScore(c, t);
+    const hero = today.heroShare !== null && m.heroShare !== null ? heroScore(today.heroShare, m.heroShare) : null;
+    const life = lifeScore(today.changed, today.animated);
+    const camera = cameraDelta(c, t, { capture: today.heroShare, target: m.heroShare });
+    const lc = lightRead(c), lt = lightRead(t), now = today.light ?? null;
+    const place = now?.place ?? null;
+    const light = { capture: lc, target: lt, now, moves: lightMoves(lc, lt, now ?? {}, place ? `${place}.light` : 'light') };
+    const j = (k) => judge?.axes[k] ?? null;
+    const axes = {
+        composition: axis(compositionScore(lay.score, camera), j('composition'), `layout r ${lay.luminance_r} (light), ${lay.edge_r} (edges)${camera.vanish ? `; the lines meet ${Math.round(camera.vanish.capture.x * 100)}%, ${Math.round(camera.vanish.capture.y * 100)}% (target ${Math.round(camera.vanish.target.x * 100)}%, ${Math.round(camera.vanish.target.y * 100)}%)` : ''}${camera.moves.length ? `; move: ${camera.moves[0]}` : '; the camera sits where the target\'s does'}`),
+        hero: axis(hero, j('hero'), heroWhy(today, m)),
+        identity: axis(null, j('identity'), 'a judge reads identity; no number does'),
+        palette_light: axis(pal.score, j('palette_light'), `palette ΔE ${pal.delta_e}, lightness gap ${pal.light_gap}`),
+        density: axis(den.score, j('density'), `detail in ${Math.round(den.capture * 100)}% of the frame, the target ${Math.round(den.target * 100)}%`),
+        life: axis(Number.isFinite(life) ? life : null, j('life'), `${today.changed === null ? 'motion not read' : `${Math.round(today.changed * 100)}% of the frame changed over 3 s`}${today.animated ? `; ${today.animated.n} of ${today.animated.of} people and creatures animated` : ''}`),
+    };
+    const o = overall(axes, bar);
+    const camFixes = fixesFor({ delta: camera, capture: c, target: t, cam: today.cam ?? null, gaps: o.gaps });
+    const lightScope = place ? `${place}.light` : 'light';
+    const fixes = now && light.moves.length
+        ? [...camFixes.filter((f) => f.param !== 'renderer.toneMappingExposure'), ...light.moves.map((mv) => ({ param: `${lightScope}.${mv.key}`, from: now[mv.key] ?? '', to: mv.set, closes: 'palette_light', why: mv.say }))]
+        : camFixes;
+    const cc = comfortOfPicture(today.png, 'image/png'), ct = comfortOfPicture(target.bytes, target.type, target.path);
+    const comfortWhy = [typeof cc === 'string' ? `the frame: ${cc}` : '', typeof ct === 'string' ? `the target: ${ct}` : ''].filter(Boolean).join('; ');
+    return {
+        comfort: { capture: typeof cc === 'string' ? null : cc, target: typeof ct === 'string' ? null : ct, warnings: [], ...(comfortWhy ? { why: comfortWhy } : {}) },
+        axes, measured: { palette: pal, layout: lay, density: den, hero_share: today.heroShare, target_hero_share: m.heroShare, changed: today.changed, animated: today.animated },
+        judge: judge ? { model: judge.model, gaps: judge.gaps, ...(judge.error ? { error: judge.error } : {}) } : null,
+        score: o.score, observed: o.observed, bar, gaps: o.gaps, verdict: o.score === null ? 'not_observed' : o.score >= bar ? 'pass' : 'below',
+        camera, camera_read: today.cam ?? null, fixes, light,
+    };
+}
+export async function score(opts, io = console) {
+    const u = ui(io, 'score');
+    const t = await openTarget(opts.target);
+    if (typeof t === 'string') {
+        u.error(t, 'build the game first (npm run build)');
+        return EXIT.error;
+    }
+    const dir = t.dir ?? resolve('.');
+    const moments = opts.moments.length ? opts.moments : momentsOf(t.manifest);
+    if (!moments.length) {
+        await t.close();
+        u.error('no moment to score', 'funtools score --target design/first-look/walk.jpg --view walk, or funpixel.json "moments": [{ "name", "view", "target", "hero", "hero_share" }]');
+        return EXIT.not_observed;
+    }
+    for (const m of moments) {
+        const p = resolve(dir, m.target);
+        if (!existsSync(p) || !imageType(p)) {
+            await t.close();
+            u.error(`no picture at ${m.target}`, 'png, jpg, webp');
+            return EXIT.error;
+        }
+    }
+    const bar = typeof t.manifest.accuracy_min === 'number' ? t.manifest.accuracy_min : DEFAULT_BAR;
+    const stretch = typeof t.manifest.accuracy_stretch === 'number' ? t.manifest.accuracy_stretch : STRETCH_DEFAULT;
+    const { size, orientation } = targetFraming(opts.viewport, t.manifest);
+    const out = [];
+    let browser;
+    try {
+        browser = (await launch()).browser;
+        const page = await lookPage(browser, opts.viewport, orientation);
+        await page.setViewportSize(size);
+        const held = opts.freeRunning !== true && moments.some((m) => !m.capture);
+        if (held)
+            await holdClock(page, opts.seed ?? CAPTURE_SEED);
+        for (const m of moments) {
+            const tp = resolve(dir, m.target);
+            const target = { bytes: new Uint8Array(await readFile(tp)), type: imageType(tp), path: tp };
+            const today = m.capture
+                ? { png: await readFile(resolve(m.capture)), counted: true, why: null, heroShare: null, changed: null, animated: null, still: true }
+                : await shoot(page, t.url, t.manifest, m, opts.viewport, size, held);
+            const shot = m.capture ? resolve(m.capture) : join(dir, '.funtools', 'score', `${m.name.replace(/[^\w-]+/g, '_')}-${opts.viewport}.png`);
+            if (!m.capture) {
+                await mkdir(dirname(shot), { recursive: true });
+                await writeFile(shot, today.png);
+            }
+            const base = { moment: m.name, view: m.view, target: m.target, capture: relative(dir, shot), viewport: opts.viewport, counted: today.counted, why_not: today.why, ...('framing' in today && today.framing ? { framing: today.framing } : {}) };
+            if (!today.counted) {
+                const none = Object.fromEntries(AXES.map((a) => [a, axis(null, null, 'not counted')]));
+                out.push({ ...base, axes: none, measured: {}, judge: null, score: null, observed: 0, bar, gaps: [], verdict: 'not_observed', camera: null });
+                continue;
+            }
+            const judge = opts.noJudge ? null : await visionJudge({ bytes: target.bytes, type: target.type }, { bytes: new Uint8Array(today.png), type: 'image/png' });
+            out.push({ ...base, ...(await scoreMoment(browser, m, today, target, bar, judge, size)), stretch });
+        }
+    }
+    catch (e) {
+        u.error(`score failed: ${e instanceof Error ? e.message : String(e)}`);
+        return EXIT.error;
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        await t.close();
+    }
+    const comfort = runComfort(out);
+    if (comfort.verdict !== 'not_observed' && t.dir)
+        patchBoard(t.dir, { comfort: { [opts.viewport]: { value: comfort.warned.length, by: 'score', detail: comfort.warnings } } });
+    const file = join(dir, SCORES_FILE);
+    let previous = undefined;
+    try {
+        const was = JSON.parse(await readFile(file, 'utf8'));
+        previous = was?.tool === 'funtools score' ? was.previous : was;
+    }
+    catch { }
+    const record = {
+        tool: 'funtools score', at: new Date().toISOString(), bar, stretch, viewport: opts.viewport, framing: size,
+        how: 'Each axis 0-100: measured numbers (src/score/measure.ts) and, when reachable, a blind vision judge, averaged per axis; an axis neither observes is left out of the mean and named. A frame on a loading or splash screen is not counted.',
+        judge: out.some((m) => m.judge) ? 'vision judge reached' : 'not observed (no OPENROUTER_API_KEY, or --no-judge)',
+        comfort: { verdict: comfort.verdict, frames: comfort.frames, targets: comfort.targets, busy_line: comfort.busyLine, warnings: comfort.warnings, why: comfort.why },
+        moments: out, ...(previous !== undefined ? { previous } : {}),
+    };
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(record, null, 2) + '\n');
+    appendHistory(dir, record);
+    const scored = out.filter((m) => m.score !== null);
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return scored.length ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`score · ${out.length} moment(s) · ${opts.viewport} ${size.width}×${size.height} · bar ${bar}`);
+    if (!out.some((m) => m.judge))
+        u.item('not_observed', 'vision judge: not observed (set OPENROUTER_API_KEY to add a blind judge; identity is judged only by it)');
+    for (const m of out) {
+        if (!m.counted) {
+            u.item('not_observed', `${m.moment}: not counted — ${m.why_not}`);
+            continue;
+        }
+        if (m.framing) {
+            const [level, framed] = framingLine(m.framing);
+            u.line(`${level === 'warn' ? '! ' : ''}${framed}`, 2);
+        }
+        const words = AXES.map((a) => `${a.replace('_light', '')} ${m.axes[a].score ?? '—'}`).join(' · ');
+        u.item(m.verdict === 'pass' ? 'pass' : m.verdict === 'below' ? 'warn' : 'not_observed', `${m.moment}: ${m.score ?? '—'}/100 (${m.observed} of 6 axes observed)${m.verdict === 'below' ? ` — under ${bar}: ${m.gaps.join(', ')}` : ''}`, words);
+        for (const a of AXES)
+            if (m.gaps.includes(a))
+                u.line(`${a}: ${m.axes[a].why}`, 2);
+        if (m.camera?.moves.length) {
+            const hz = (v) => (v === null ? 'not observed' : `${Math.round(v * 100)}%`);
+            u.line(`camera vs target (horizon ${hz(m.camera.horizon.capture)} → ${hz(m.camera.horizon.target)}, zoom ×${m.camera.zoom}, pan ${m.camera.pan.x}, ${m.camera.pan.y}):`, 2);
+            for (const mv of m.camera.moves.slice(0, 4))
+                u.line(`- ${mv}`, 3);
+        }
+        if (m.camera?.horizon.why)
+            u.line(m.camera.horizon.why, 2);
+        if (m.fixes?.length) {
+            u.line(`the fix list (${m.camera_read ? `numbers from ${m.camera_read.source}${m.camera_read.shot ? `, shot ${m.camera_read.shot}` : ''}` : 'no camera read in the page: colour, light and dressing only'}):`, 2);
+            for (const f of m.fixes.slice(0, 6))
+                u.line(`- ${moveLine(f)}`, 3);
+        }
+        if (m.light?.moves.length && !m.fixes?.some((f) => f.closes === 'palette_light' && /\.light\./.test(`.${f.param}`))) {
+            u.line(`light vs target (L* ${m.light.capture.meanL} → ${m.light.target.meanL}, pools ${m.light.capture.pools} → ${m.light.target.pools}${m.light.now?.preset ? `, preset ${m.light.now.preset}` : ''}):`, 2);
+            for (const mv of m.light.moves.slice(0, 5))
+                u.line(`- ${mv.say}`, 3);
+        }
+        if (m.judge?.gaps.length)
+            u.line(`judge: ${m.judge.gaps.join('; ')}`, 2);
+    }
+    if (comfort.verdict === 'not_observed')
+        u.item('not_observed', `comfort: not observed — ${comfort.why}`);
+    else {
+        const clip = out.filter((m) => m.comfort?.capture).map((m) => m.comfort.capture.clipped);
+        u.item(comfort.verdict === 'warn' ? 'warn' : 'pass', `comfort: ${comfort.verdict === 'warn' ? `${comfort.warned.length} frame(s) to calm (a warning; the owner decides)` : 'calm'}`, `${comfort.why}; clipped up to ${Math.max(...clip)}%`);
+        for (const w of comfort.warnings)
+            u.line(w, 2);
+    }
+    const below = scored.filter((m) => m.verdict === 'below').length;
+    u.summary(scored.length ? (below ? 'warn' : 'pass') : 'not_observed', scored.length ? `${scored.length - below} of ${scored.length} moment(s) at or over ${bar} — ${SCORES_FILE}` : 'nothing scored: not a pass');
+    return scored.length ? EXIT.pass : EXIT.not_observed;
+}
+export function printFixes(target, json, io = console) {
+    const u = ui(io, 'score');
+    const dir = resolve(target);
+    const fl = fixList(dir);
+    if (json) {
+        io.log(JSON.stringify(fl, null, 2));
+        return fl.mean === null ? EXIT.not_observed : EXIT.pass;
+    }
+    if (fl.mean === null) {
+        u.summary('not_observed', `nothing scored yet (${SCORES_FILE}): funtools score`);
+        return EXIT.not_observed;
+    }
+    u.heading(`the fix list · ${fl.at ?? ''} · mean ${fl.mean} · bar ${fl.bar} (stretch ${fl.stretch})`);
+    for (const a of fl.atBar)
+        u.item('pass', `${a}: at the bar`);
+    for (const m of fl.below) {
+        u.item('warn', `${m.moment}: ${m.score}/${m.bar}${m.gaps.length ? ` — ${m.gaps.join(', ')}` : ''}`, m.source ? `numbers from ${m.source}` : 'no camera read in the page');
+        for (const f of m.fixes.slice(0, 8))
+            u.line(`- ${fixLine(f)}`, 2);
+    }
+    u.summary(fl.below.length ? 'warn' : 'pass', fl.below.length ? 'apply the moves, rebuild, then score again at the same framing (the round closes at the bar or on the owner\'s accept)' : 'every moment at the bar');
+    return EXIT.pass;
+}

package/dist/commands/serve.js

@@ -0,0 +1,67 @@
+import { lanAddress } from "../dev/lan.js";
+import { qr, qrLines } from "../dev/qr.js";
+import { brotliBuild, buildDir, DEFAULT_PORT, isWebglBuild, startWebglServer } from "../serve/webgl.js";
+import { ui } from "../ui.js";
+export async function serve(opts, io = console) {
+    const u = ui(io, 'serve');
+    const root = buildDir(opts.target ?? '.');
+    if (!root) {
+        u.error(`no index.html in ${opts.target ?? '.'} (nor in its Builds/WebGL)`, 'build the WebGL player first (File > Build Profiles > Web, or your build method), then serve the folder it wrote');
+        return 3;
+    }
+    const port = opts.port === undefined ? DEFAULT_PORT : Number(opts.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        u.error(`--port ${opts.port}`, '--port is a whole number from 0 to 65535');
+        return 3;
+    }
+    const host = opts.host ?? '0.0.0.0';
+    let started;
+    try {
+        started = await startWebglServer(root, port, host, { compress: !opts.noCompress });
+    }
+    catch (e) {
+        const code = e.code;
+        u.error(code === 'EADDRINUSE' ? `port ${port} is in use` : `could not listen on ${host}:${port} (${code ?? e})`, code === 'EADDRINUSE' ? `another server has it: stop that one, or pass --port ${port + 1}` : 'pass another --host or --port');
+        return 3;
+    }
+    const { server, stats } = started;
+    const br = brotliBuild(root);
+    u.heading(`serve · ${root}`);
+    if (!isWebglBuild(root))
+        u.item('warn', 'no Build/*.loader.js here: this does not look like a Unity WebGL build (served anyway)');
+    u.item('pass', `this Mac: http://localhost:${started.port}/${br ? ' (Brotli, as built)' : ''}`);
+    const lan = host === '0.0.0.0' ? lanAddress() : /^(127\.|localhost$|::1$)/.test(host) ? null : host;
+    if (lan) {
+        const url = `http://${lan}:${started.port}/`;
+        u.item('pass', `a phone on the same Wi-Fi: ${url}${br ? ' (gzip: a browser takes Brotli only on https or localhost, so the .br files go to it re-encoded)' : ''}`);
+        const code = qr(url);
+        if (code)
+            for (const line of qrLines(code))
+                io.log(`  ${line}`);
+        u.item('note', 'this build is served to everyone on your local network; use it on a network you trust and stop it (Ctrl-C) when you are done');
+    }
+    else if (host === '0.0.0.0')
+        u.item('note', 'no local-network address found (no Wi-Fi or Ethernet): this Mac only');
+    else
+        u.item('note', `bound to ${host}: this Mac only (drop --host to reach it from a phone)`);
+    if (opts.noCompress)
+        u.item('note', 'plain files go as stored (--no-compress): what a page fetches here is the build\'s raw weight, not what a CDN sends');
+    else
+        u.item('note', 'plain files (Addressables bundles, .wasm/.json/.data with no .br/.gz beside them, .js, .css, .html) are compressed on the fly, as a CDN would: Brotli where the browser takes it, else gzip; images, audio and video go as they are (--no-compress sends everything as stored)');
+    u.line('Ctrl-C stops it');
+    await (opts.until ?? new Promise((done) => {
+        process.once('SIGINT', done);
+        process.once('SIGTERM', done);
+    }));
+    const closed = new Promise((done) => server.close(() => done()));
+    server.closeAllConnections();
+    await closed;
+    if (stats.files)
+        u.item('note', sentLine(stats, !opts.noCompress));
+    return 0;
+}
+const mb = (n) => `${(n / 1e6).toFixed(1)} MB`;
+export function sentLine(s, compress) {
+    const how = !compress ? 'as stored: --no-compress' : s.compressed ? `${s.compressed} compressed on the fly` : 'none needed compressing on the fly';
+    return `sent ${s.files} file${s.files === 1 ? '' : 's'}: ${mb(s.wire)} on the wire for ${mb(s.stored)} as stored (${how})`;
+}