@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/compare-takes.js

@@ -0,0 +1,204 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { walk, WALK_RECORD } from "./walk.js";
+import { score, SCORES_FILE } from "./score.js";
+import { launch } from "../verify/browser.js";
+import { imageType } from "../look/image-io.js";
+import { ui } from "../ui.js";
+export const TAKES_DIR = join('.funtools', 'takes');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+export function takeMetrics(walkRec, scoresRec) {
+    const routes = Array.isArray(walkRec?.routes) ? walkRec.routes : [];
+    const lifeActors = routes.flatMap((r) => (Array.isArray(r.life?.actors) ? r.life.actors : [])).filter((a) => a.role !== 'player');
+    const flyers = lifeActors.filter((a) => a.flies);
+    const travelRoutes = routes.filter((r) => r.travel);
+    const floats = routes.filter((r) => Array.isArray(r.floating));
+    const scales = routes.filter((r) => r.scale?.judged);
+    const shares = routes.flatMap((r) => (Array.isArray(r.framing) ? r.framing : [])).map((f) => num(f.share?.mean)).filter((v) => v !== null);
+    const ch = routes.filter((r) => r.challenges);
+    const moments = Array.isArray(scoresRec?.moments) ? scoresRec.moments : [];
+    const scored = moments.filter((m) => typeof m.score === 'number');
+    const axes = {};
+    for (const a of ['composition', 'hero', 'identity', 'palette_light', 'density', 'life']) {
+        const v = scored.map((m) => num(m.axes?.[a]?.score)).filter((x) => x !== null);
+        axes[a] = v.length ? Math.round(sum(v) / v.length) : null;
+    }
+    const films = [...new Set(routes.map((r) => r.film?.file).filter((f) => typeof f === 'string'))];
+    return {
+        routes: routes.length,
+        arrived: routes.filter((r) => r.outcome === 'arrived').length,
+        clipping: sum(routes.map((r) => (Array.isArray(r.clipping) ? r.clipping.length : 0))),
+        placement: sum(routes.map((r) => (Array.isArray(r.placement) ? r.placement.length : 0))),
+        floating: floats.length ? sum(floats.map((r) => r.floating.length)) : null,
+        scaleMisses: scales.length ? sum(scales.map((r) => r.scale.misses.length)) : null,
+        stalls: sum(routes.map((r) => (Array.isArray(r.stalls) ? r.stalls.length : 0))),
+        challenges: ch.length ? sum(ch.map((r) => r.challenges.total ?? 0)) : null,
+        losses: sum(routes.map((r) => (Array.isArray(r.losses) ? r.losses.length : 0))),
+        animated: lifeActors.length ? { n: lifeActors.filter((a) => a.verdict === 'animated').length, of: lifeActors.length } : null,
+        travel: travelRoutes.length ? { moved: sum(travelRoutes.map((r) => r.travel.moved)), people: sum(travelRoutes.map((r) => r.travel.people)) } : null,
+        heroClones: routes.some((r) => r.life?.crowd) ? sum(routes.map((r) => r.life?.crowd?.hero_clones ?? 0)) : null,
+        flyers: flyers.length ? { flap: flyers.filter((a) => a.verdict === 'animated').length, of: flyers.length } : null,
+        reactions: routes.some((r) => r.life?.reactions) ? sum(routes.map((r) => r.life?.reactions?.near ?? 0)) : null,
+        heroShare: shares.length ? Math.round((sum(shares) / shares.length) * 1000) / 1000 : null,
+        score: scored.length ? Math.round(sum(scored.map((m) => m.score)) / scored.length) : null,
+        axes,
+        moments: Object.fromEntries(moments.map((m) => [String(m.moment), num(m.score)])),
+        films,
+        frames: routes.flatMap((r) => (Array.isArray(r.frames) ? r.frames : [])),
+        captures: Object.fromEntries(moments.filter((m) => m.capture).map((m) => [String(m.moment), String(m.capture)])),
+    };
+}
+const share = (x) => (x && x.of ? x.n / x.of : null);
+const show = (v, unit = '') => (v === null || v === undefined ? '—' : `${v}${unit}`);
+const frac = (x) => (x ? `${x.n}/${x.of}` : '—');
+export function bestOfBoth(A, B, names = ['A', 'B']) {
+    const rows = [];
+    const add = (area, metric, a, b, better, as, keep) => {
+        const ahead = a === null || b === null ? (a === null && b === null ? '—' : a === null ? 'B' : 'A') : a === b ? 'tie' : (better === 'higher' ? a > b : a < b) ? 'A' : 'B';
+        rows.push({ area, metric, a: as[0], b: as[1], ahead, keep: ahead === '—' || ahead === 'tie' ? '' : `${ahead === 'A' ? names[0] : names[1]}'s ${keep}` });
+    };
+    add('environment', 'clipping pairs on the walk', A.clipping, B.clipping, 'lower', [show(A.clipping), show(B.clipping)], 'collisions');
+    add('environment', 'props placed inside props', A.placement, B.placement, 'lower', [show(A.placement), show(B.placement)], 'placement');
+    add('environment', 'floating or buried actors', A.floating, B.floating, 'lower', [show(A.floating), show(B.floating)], 'grounding');
+    add('environment', 'off the scale sheet', A.scaleMisses, B.scaleMisses, 'lower', [show(A.scaleMisses), show(B.scaleMisses)], 'scale');
+    add('environment', 'stalls (blocked or dead ends)', A.stalls, B.stalls, 'lower', [show(A.stalls), show(B.stalls)], 'paths');
+    add('dynamics', 'people and creatures animated', share(A.animated), share(B.animated), 'higher', [frac(A.animated), frac(B.animated)], 'animation');
+    add('dynamics', 'people moving through space', share(A.travel ? { n: A.travel.moved, of: A.travel.people } : null), share(B.travel ? { n: B.travel.moved, of: B.travel.people } : null), 'higher', [A.travel ? `${A.travel.moved}/${A.travel.people}` : '—', B.travel ? `${B.travel.moved}/${B.travel.people}` : '—'], 'task loops');
+    add('dynamics', 'people wearing the hero\'s face', A.heroClones, B.heroClones, 'lower', [show(A.heroClones), show(B.heroClones)], 'crowd variety');
+    add('dynamics', 'flyers that flap', share(A.flyers ? { n: A.flyers.flap, of: A.flyers.of } : null), share(B.flyers ? { n: B.flyers.flap, of: B.flyers.of } : null), 'higher', [A.flyers ? `${A.flyers.flap}/${A.flyers.of}` : '—', B.flyers ? `${B.flyers.flap}/${B.flyers.of}` : '—'], 'flyers');
+    add('dynamics', 'reactions to the player', A.reactions, B.reactions, 'higher', [show(A.reactions), show(B.reactions)], 'reactions');
+    add('challenge', 'hazards fired on the walk', A.challenges, B.challenges, 'higher', [show(A.challenges), show(B.challenges)], 'challenge');
+    add('challenge', 'runs lost (then retried)', A.losses, B.losses, 'higher', [show(A.losses), show(B.losses)], 'loss and retry');
+    add('accuracy', 'mean score vs the targets', A.score, B.score, 'higher', [show(A.score), show(B.score)], 'look overall');
+    for (const [k, label] of [['composition', 'composition (camera)'], ['palette_light', 'palette and light'], ['density', 'density and detail'], ['life', 'life on screen'], ['hero', 'hero size']]) {
+        add('accuracy', label, A.axes[k] ?? null, B.axes[k] ?? null, 'higher', [show(A.axes[k]), show(B.axes[k])], label);
+    }
+    for (const m of [...new Set([...Object.keys(A.moments), ...Object.keys(B.moments)])]) {
+        add('moments', m, A.moments[m] ?? null, B.moments[m] ?? null, 'higher', [show(A.moments[m]), show(B.moments[m])], `${m} moment`);
+    }
+    return rows;
+}
+export function takesMarkdown(rows, names, takes) {
+    const out = [`# Two takes: ${names[0]} vs ${names[1]}`, '', `${names[0]}: \`${takes[0]}\` · ${names[1]}: \`${takes[1]}\``, '', `| area | measure | ${names[0]} | ${names[1]} | ahead |`, '|---|---|---|---|---|'];
+    for (const r of rows)
+        out.push(`| ${r.area} | ${r.metric} | ${r.a} | ${r.b} | ${r.ahead === 'A' ? names[0] : r.ahead === 'B' ? names[1] : r.ahead} |`);
+    out.push('', '## Best of both', '');
+    const areas = [...new Set(rows.map((r) => r.area))];
+    for (const area of areas) {
+        const inArea = rows.filter((r) => r.area === area && (r.ahead === 'A' || r.ahead === 'B'));
+        const a = inArea.filter((r) => r.ahead === 'A').length, b = inArea.filter((r) => r.ahead === 'B').length;
+        if (!inArea.length) {
+            out.push(rows.some((r) => r.area === area && r.ahead === 'tie') ? `- **${area}**: even (both the same on every measure)` : `- **${area}**: not measured in either take`);
+            continue;
+        }
+        out.push(`- **${area}**: ${names[0]} ahead on ${a}, ${names[1]} on ${b} — keep ${inArea.map((r) => r.keep).join(', ')}`);
+    }
+    out.push('', 'Numbers are mirrors: watch both films before choosing, and play the mix from the title.');
+    return out.join('\n') + '\n';
+}
+const quiet = { log: () => { }, error: () => { } };
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+function filmFrames(film, outDir, tag) {
+    const probe = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', film], { encoding: 'utf8', timeout: 20_000 });
+    const dur = Number((probe.stdout ?? '').trim());
+    if (!(dur > 0))
+        return [];
+    const out = [];
+    for (const f of [0.25, 0.5, 0.75]) {
+        const file = join(outDir, `${tag}-${Math.round(f * 100)}.png`);
+        const r = spawnSync('ffmpeg', ['-y', '-loglevel', 'error', '-ss', String(dur * f), '-i', film, '-frames:v', '1', '-vf', 'scale=640:-2', file], { stdio: 'ignore', timeout: 30_000 });
+        if (r.status === 0 && existsSync(file))
+            out.push(file);
+    }
+    return out;
+}
+async function dataUri(file) {
+    const t = imageType(file);
+    if (!t || !existsSync(file))
+        return null;
+    return `data:${t};base64,${(await readFile(file)).toString('base64')}`;
+}
+async function contactSheet(rows, names, file) {
+    const cell = async (list) => (await Promise.all(list.slice(0, 4).map(dataUri))).filter(Boolean).map((u) => `<img src="${u}">`).join('');
+    let html = `<!doctype html><meta charset="utf-8"><style>body{margin:0;background:#15161a;color:#e8e6e1;font:14px system-ui}h1{font-size:18px;margin:12px 16px}table{border-collapse:collapse;margin:0 16px 16px}td,th{vertical-align:top;padding:6px;border-top:1px solid #333}th{text-align:left;font-weight:600}img{width:300px;display:block;margin-bottom:4px;border-radius:4px}</style><h1>${names[0]} | ${names[1]}${rows.some((r) => r.target) ? ' | target' : ''}</h1><table><tr><th></th><th>${names[0]}</th><th>${names[1]}</th>${rows.some((r) => r.target) ? '<th>target</th>' : ''}</tr>`;
+    for (const r of rows)
+        html += `<tr><th>${r.label}</th><td>${await cell(r.a)}</td><td>${await cell(r.b)}</td>${rows.some((x) => x.target) ? `<td>${r.target ? await cell([r.target]) : ''}</td>` : ''}</tr>`;
+    html += '</table>';
+    let browser;
+    try {
+        browser = (await launch()).browser;
+        const page = await browser.newPage({ viewport: { width: 1100, height: 800 } });
+        await page.setContent(html, { waitUntil: 'load' });
+        await page.screenshot({ path: file, fullPage: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await browser?.close().catch(() => { });
+    }
+}
+export async function compareTakes(opts, io = console) {
+    const u = ui(io, 'compare-takes');
+    const dirs = opts.takes.map((t) => resolve(t));
+    for (const d of dirs)
+        if (!existsSync(join(d, 'funpixel.json'))) {
+            u.error(`${d} is not a game folder (no funpixel.json)`, 'funtools compare-takes <takeA> <takeB>: two folders of the same game');
+            return EXIT.error;
+        }
+    const names = opts.names ?? [basename(dirs[0]), basename(dirs[1]) === basename(dirs[0]) ? `${basename(dirs[1])} (2)` : basename(dirs[1])];
+    const out = resolve(opts.out ?? TAKES_DIR);
+    await mkdir(out, { recursive: true });
+    const metrics = [];
+    for (const [i, dir] of dirs.entries()) {
+        const manifest = readJson(join(dir, 'funpixel.json')) ?? {};
+        const scoring = opts.score && Array.isArray(manifest.moments) && manifest.moments.length > 0;
+        u.line(`${names[i]}: walking from the title${scoring ? ', then scoring its moments' : ''}…`);
+        await walk({ target: dir, viewport: opts.viewport, json: true, click: null, routes: opts.routes, seconds: opts.seconds, film: true }, quiet).catch(() => EXIT.error);
+        if (scoring)
+            await score({ target: dir, moments: [], viewport: opts.viewport, json: true, noJudge: true }, quiet).catch(() => EXIT.error);
+        metrics.push(takeMetrics(readJson(join(dir, WALK_RECORD)), readJson(join(dir, SCORES_FILE))));
+    }
+    const [A, B] = metrics;
+    const rows = bestOfBoth(A, B, names);
+    const sheetRows = [];
+    const films = await Promise.all(metrics.map(async (m, i) => m.films.flatMap((f) => filmFrames(f, out, `${i ? 'b' : 'a'}-${basename(f, '.webm')}`))));
+    sheetRows.push({ label: 'walk (start, end)', a: A.frames.map((f) => join(dirs[0], f)), b: B.frames.map((f) => join(dirs[1], f)) });
+    if (films[0].length || films[1].length)
+        sheetRows.push({ label: 'from the films', a: films[0], b: films[1] });
+    const manifestA = readJson(join(dirs[0], 'funpixel.json')) ?? {};
+    for (const m of [...new Set([...Object.keys(A.captures), ...Object.keys(B.captures)])]) {
+        const target = (Array.isArray(manifestA.moments) ? manifestA.moments : []).find((x) => (x.name ?? x.view) === m)?.target;
+        sheetRows.push({ label: `${m} (${show(A.moments[m])} | ${show(B.moments[m])})`, a: A.captures[m] ? [join(dirs[0], A.captures[m])] : [], b: B.captures[m] ? [join(dirs[1], B.captures[m])] : [], target: target ? join(dirs[0], target) : null });
+    }
+    const sheet = join(out, 'sheet.png');
+    const drew = await contactSheet(sheetRows, names, sheet);
+    const md = takesMarkdown(rows, names, opts.takes);
+    await writeFile(join(out, 'takes.md'), md);
+    const record = { tool: 'funtools', command: 'compare-takes', at: new Date().toISOString(), viewport: opts.viewport, names, takes: dirs, metrics: { [names[0]]: A, [names[1]]: B }, rows, sheet: drew ? relative(process.cwd(), sheet) : null };
+    await writeFile(join(out, 'takes.json'), JSON.stringify(record, null, 2) + '\n');
+    const measured = A.routes + B.routes > 0 || A.score !== null || B.score !== null;
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return measured ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`two takes · ${names[0]} vs ${names[1]} · ${opts.viewport}`);
+    for (const r of rows)
+        if (r.ahead !== '—')
+            u.item(r.ahead === 'tie' ? 'note' : 'pass', `${r.area} · ${r.metric}: ${names[0]} ${r.a} · ${names[1]} ${r.b}${r.ahead === 'tie' ? ' (tie)' : ` → ${r.ahead === 'A' ? names[0] : names[1]}`}`);
+    u.heading('best of both');
+    for (const l of md.split('\n').filter((x) => x.startsWith('- **')))
+        u.line(l.replace(/\*\*/g, ''));
+    u.summary(measured ? 'note' : 'not_observed', measured ? `${relative(process.cwd(), join(out, 'takes.md'))}${drew ? ` · ${relative(process.cwd(), sheet)}` : ' (no contact sheet: the browser did not start)'} — a mirror for choosing what the mix keeps` : 'neither take was walked or scored: not a comparison');
+    return measured ? EXIT.pass : EXIT.not_observed;
+}

package/dist/commands/compare-target.js

@@ -0,0 +1,149 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { launch, lookPage, viewportUrl } from "../verify/browser.js";
+import { drive, load, openTarget } from "../look/look.js";
+import { CAPTURE_SEED, framingLine, holdClock, readFraming } from "../look/held.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { dataUrl, imageType } from "../look/image-io.js";
+import { ui } from "../ui.js";
+export const TARGET_FRAMINGS = {
+    phone: { width: 852, height: 393 },
+    desktop: { width: 1280, height: 720 },
+};
+export function targetFraming(vp, manifest) {
+    const size = TARGET_FRAMINGS[vp];
+    if (vp !== 'phone')
+        return { size, orientation: '' };
+    const said = manifest?.metadata?.orientation;
+    const upright = typeof said === 'string' && said.trim().toLowerCase() === 'portrait';
+    return upright ? { size: { width: size.height, height: size.width }, orientation: 'portrait' } : { size, orientation: 'landscape' };
+}
+export const STRIP = { band: 30, gap: 12, ground: '#141418' };
+export function pairTargets(images, views) {
+    if (!images.length)
+        return 'no target picture';
+    if (!views.length) {
+        if (images.length > 1)
+            return 'several targets need as many --view names (title,walk with a.png,b.png)';
+        return [{ view: null, image: images[0] }];
+    }
+    if (images.length === 1)
+        return views.map((view) => ({ view, image: images[0] }));
+    if (images.length !== views.length)
+        return `${images.length} targets for ${views.length} views: give one target, or one per view in the same order`;
+    return views.map((view, i) => ({ view, image: images[i] }));
+}
+export function stripPath(dir, view, viewport, out, strips) {
+    const name = `${view ?? 'as-loaded'}-${viewport}.png`;
+    if (out === undefined)
+        return join(dir, 'design', 'look', name);
+    if (extname(out).toLowerCase() === '.png')
+        return strips === 1 ? resolve(out) : null;
+    return join(resolve(out), name);
+}
+export function fitRect(w, h, W, H, fit) {
+    const s = fit === 'cover' ? Math.max(W / w, H / h) : Math.min(W / w, H / h);
+    const width = Math.round(w * s), height = Math.round(h * s);
+    return { x: Math.round((W - width) / 2), y: Math.round((H - height) / 2), width, height };
+}
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+export function stripHtml(today, target, size, labels, fit) {
+    const { width: W, height: H } = size;
+    const half = (src, label, fitTo) => `<figure><figcaption>${esc(label)}</figcaption><div class="box"><img src="${src}" style="object-fit:${fitTo}"></div></figure>`;
+    return `<!doctype html><html><head><meta charset="utf-8"><style>
+html,body{margin:0;background:${STRIP.ground}}
+body{display:flex;gap:${STRIP.gap}px;width:${2 * W + STRIP.gap}px}
+figure{margin:0;width:${W}px}
+figcaption{height:${STRIP.band}px;line-height:${STRIP.band}px;padding:0 10px;box-sizing:border-box;font:600 15px/${STRIP.band}px -apple-system,system-ui,"Segoe UI",sans-serif;color:#eee;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.box{width:${W}px;height:${H}px;background:#000;overflow:hidden}
+img{display:block;width:100%;height:100%}
+</style></head><body>${half(today, labels[0], 'fill')}${half(target, labels[1], fit)}</body></html>`;
+}
+export async function composeStrip(browser, todayPng, targetBytes, targetType, size, labels, fit) {
+    const width = 2 * size.width + STRIP.gap, height = size.height + STRIP.band;
+    const context = await browser.newContext({ viewport: { width, height }, deviceScaleFactor: 1 });
+    try {
+        const page = await context.newPage();
+        await page.setContent(stripHtml(dataUrl(todayPng, 'image/png'), dataUrl(targetBytes, targetType), size, labels, fit), { waitUntil: 'load' });
+        await page.evaluate('Promise.all([...document.images].map((i) => i.decode().catch(() => {})))');
+        return await page.screenshot({ type: 'png', clip: { x: 0, y: 0, width, height } });
+    }
+    finally {
+        await context.close().catch(() => { });
+    }
+}
+export async function compareTarget(opts, io = console) {
+    const u = ui(io, 'compare');
+    const strips = opts.pairs.length * opts.viewports.length;
+    for (const p of opts.pairs) {
+        if (!existsSync(p.image)) {
+            u.error(`no such picture: ${p.image}`, 'name the target frame, e.g. --target design/first-look/f3_walk.png');
+            return EXIT.error;
+        }
+        if (!imageType(p.image)) {
+            u.error(`${p.image}: not a picture funtools reads`, 'png, jpg, webp, gif or avif');
+            return EXIT.error;
+        }
+    }
+    if (opts.out !== undefined && extname(opts.out).toLowerCase() === '.png' && strips > 1) {
+        u.error(`--out ${opts.out} names one file for ${strips} strips`, 'give a folder, or one --view and one --viewport');
+        return EXIT.error;
+    }
+    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 rows = [];
+    let browser;
+    try {
+        browser = (await launch()).browser;
+        for (const vp of opts.viewports) {
+            const { size, orientation } = targetFraming(vp, t.manifest);
+            const page = await lookPage(browser, vp, orientation);
+            await page.setViewportSize(size);
+            const held = opts.freeRunning !== true;
+            if (held)
+                await holdClock(page, opts.seed ?? CAPTURE_SEED);
+            for (const pair of opts.pairs) {
+                await load(page, viewportUrl(t.url, vp), hookMapOf(t.manifest), held);
+                const driven = await drive(page, { view: pair.view, verbs: opts.verbs, holdMs: opts.holdMs ?? 600, freeze: true, click: opts.click });
+                const entered = pair.view === null || driven.view?.entered === true;
+                const today = await page.screenshot({ type: 'png', scale: 'css' });
+                const framing = await readFraming(page, held);
+                const label = `${size.width}×${size.height}`;
+                const strip = await composeStrip(browser, today, await readFile(pair.image), imageType(pair.image), size, [`today · ${pair.view ?? 'as loaded'} · ${vp} ${label}${entered ? '' : ' · NOT ENTERED'}`, `target · ${basename(pair.image)}`], opts.fit);
+                const out = stripPath(dir, pair.view, vp, opts.out, strips);
+                await mkdir(dirname(out), { recursive: true });
+                await writeFile(out, strip);
+                rows.push({ view: pair.view, viewport: vp, target: pair.image, strip: out, entered, ...(entered ? {} : { error: driven.view?.error || 'the page refused' }), framing });
+            }
+            await page.context().close().catch(() => { });
+        }
+    }
+    catch (e) {
+        u.error(`compare --target failed: ${e instanceof Error ? e.message : String(e)}`);
+        return EXIT.error;
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        await t.close();
+    }
+    const missed = rows.filter((r) => !r.entered);
+    if (opts.json)
+        io.log(JSON.stringify({ strips: rows, fit: opts.fit, framings: TARGET_FRAMINGS }, null, 2));
+    else {
+        u.heading(`compare · today | target · ${rows.length} strip(s)`);
+        for (const r of rows) {
+            u.item(r.entered ? 'pass' : 'warn', `${r.view ?? 'as loaded'} · ${r.viewport}${r.entered ? '' : ` — not entered (${r.error}): the strip shows the page as it stood`}`, r.strip);
+            const [level, framed] = framingLine(r.framing);
+            if (level === 'warn')
+                u.item('warn', `${r.view ?? 'as loaded'} · ${r.viewport}: ${framed}`);
+        }
+        u.summary(missed.length ? 'not_observed' : 'pass', 'read each strip for mood, light, the hero\'s size and what lives in the world; the numbers that matter are in the picture, not here');
+    }
+    return missed.length ? EXIT.not_observed : EXIT.pass;
+}

package/dist/commands/compare.js

@@ -0,0 +1,117 @@
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { decodePng, encodePng } from "../look/png.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { notComparable } from "../look/held.js";
+import { CAPTURE_INDEX } from "./look.js";
+import { EXIT } from "./verify.js";
+import { ui } from "../ui.js";
+export const UNCHANGED = 0.005;
+const NOISE = 24;
+export function changedShare(a, b) {
+    let changed = 0;
+    for (let i = 0; i < a.data.length; i += 4) {
+        if (Math.abs(a.data[i] - b.data[i]) > NOISE || Math.abs(a.data[i + 1] - b.data[i + 1]) > NOISE || Math.abs(a.data[i + 2] - b.data[i + 2]) > NOISE)
+            changed++;
+    }
+    return changed / (a.width * a.height);
+}
+export function sideBySide(a, b, gap = 12) {
+    const width = a.width + gap + b.width, height = Math.max(a.height, b.height);
+    const data = new Uint8Array(width * height * 4).fill(255);
+    const blit = (img, x0) => {
+        for (let y = 0; y < img.height; y++)
+            data.set(img.data.subarray(y * img.width * 4, (y + 1) * img.width * 4), (y * width + x0) * 4);
+    };
+    blit(a, 0);
+    blit(b, a.width + gap);
+    return { width, height, data };
+}
+const pngs = async (dir) => (existsSync(dir) ? (await readdir(dir)).filter((f) => f.endsWith('.png')).sort() : []);
+async function framings(root) {
+    try {
+        const index = JSON.parse(await readFile(join(root, CAPTURE_INDEX), 'utf8'));
+        return Object.fromEntries(Object.values(index).filter((e) => e?.file && e.framing).map((e) => [basename(e.file), e.framing]));
+    }
+    catch {
+        return {};
+    }
+}
+export async function compare(opts, io = console) {
+    const u = ui(io, 'compare');
+    const root = resolve(opts.target);
+    const shots = join(root, '.funtools', 'capture'), before = join(root, '.funtools', 'capture-before'), out = join(root, '.funtools', 'compare');
+    try {
+        if (opts.baseline) {
+            const files = await pngs(shots);
+            if (!files.length) {
+                u.error('no captures to keep', 'run `funtools capture --all` first');
+                return EXIT.not_observed;
+            }
+            await rm(before, { recursive: true, force: true });
+            await mkdir(before, { recursive: true });
+            for (const f of files)
+                await copyFile(join(shots, f), join(before, f));
+            const fp = (await fingerprint(root)).fingerprint;
+            const framed = await framings(root);
+            await writeFile(join(before, 'baseline.json'), JSON.stringify({ at: new Date().toISOString(), fingerprint: fp, views: files, framing: Object.fromEntries(files.filter((f) => framed[f]).map((f) => [f, framed[f]])) }, null, 2) + '\n');
+            if (opts.json)
+                io.log(JSON.stringify({ baseline: files.length, dir: before }, null, 2));
+            else
+                u.summary('pass', `kept ${files.length} capture(s) as the before — change the game, \`capture --all\` again, then \`compare\``);
+            return EXIT.pass;
+        }
+        const kept = await pngs(before);
+        if (!kept.length) {
+            u.error('no baseline', 'run `funtools capture --all` then `funtools compare --baseline` before the change');
+            return EXIT.not_observed;
+        }
+        const now = new Set(await pngs(shots));
+        const both = kept.filter((f) => now.has(f));
+        if (!both.length) {
+            u.error('no view was captured both before and after', 'run `funtools capture --all` after the change');
+            return EXIT.not_observed;
+        }
+        await mkdir(out, { recursive: true });
+        let was = {};
+        try {
+            was = JSON.parse(await readFile(join(before, 'baseline.json'), 'utf8')).framing ?? {};
+        }
+        catch { }
+        const is = await framings(root);
+        const rows = [];
+        for (const f of both) {
+            const a = decodePng(await readFile(join(before, f))), b = decodePng(await readFile(join(shots, f)));
+            const sheet = join(out, f);
+            await writeFile(sheet, encodePng(sideBySide(a, b)));
+            const same = a.width === b.width && a.height === b.height;
+            const why = notComparable(was[f], is[f]);
+            rows.push({ view: f.replace(/\.png$/, ''), changed: same ? changedShare(a, b) : null, sheet, ...(same ? {} : { note: `size ${a.width}x${a.height} → ${b.width}x${b.height}` }), comparable: why === null, ...(why ? { not_comparable: why } : {}) });
+        }
+        const missing = kept.filter((f) => !now.has(f)).map((f) => f.replace(/\.png$/, ''));
+        if (opts.json) {
+            io.log(JSON.stringify({ compared: rows, missing, unchanged_below: UNCHANGED }, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`compare · ${rows.length} view(s), before | after in ${out}`);
+        for (const r of rows) {
+            const pct = r.changed === null ? r.note : `${(r.changed * 100).toFixed(1)}% of pixels changed`;
+            const word = r.comparable && r.changed === 0 ? 'identical' : r.changed !== null && r.changed < UNCHANGED ? `unchanged (${pct})` : pct;
+            u.item(r.changed !== null && r.changed < UNCHANGED ? 'warn' : 'pass', `${r.view}: ${word}`, r.sheet);
+            if (!r.comparable)
+                u.item('note', `${r.view}: not comparable frame for frame — ${r.not_comparable}`, 'capture both sides on the held clock (the default since 8 Oct): `capture --all`, `compare --baseline`, change, `capture --all`, `compare`');
+        }
+        if (missing.length)
+            u.item('note', `not captured after: ${missing.join(', ')}`);
+        const loose = rows.filter((r) => !r.comparable).length;
+        u.summary('pass', loose
+            ? `${rows.length - loose} of ${rows.length} framed alike; on the rest a moving view changes by itself, so read the sheet, not only the number`
+            : 'every pair framed alike (held clock, one seed, one game time): what changed is the game; a view you say you fixed should show it in its sheet');
+        return EXIT.pass;
+    }
+    catch (e) {
+        u.error(`compare failed: ${e instanceof Error ? e.message : String(e)}`);
+        return EXIT.error;
+    }
+}