@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/feedback.js

@@ -0,0 +1,496 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { EXIT } from "./verify.js";
+import { parseAb } from "../feedback/ab.js";
+import { ledger, ledgerMarkdown, learnedOf, pipelineOwnerNotes, propose, proposalsMarkdown, rootOfLog } from "../feedback/learn.js";
+import { feedbackPage } from "../feedback/page.js";
+import { ui } from "../ui.js";
+export const VERDICTS = ['worked', 'hurt', 'missing'];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.vite', '.cache']);
+const LOG_NAMES = new Set(['devlog.jsonl', 'kit-feedback.jsonl', 'ab.jsonl']);
+const MAX_DEPTH = 10;
+export function findLogs(dir, depth = 0, out = []) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of names) {
+        const p = join(dir, name);
+        let st;
+        try {
+            st = statSync(p, { throwIfNoEntry: false });
+        }
+        catch {
+            continue;
+        }
+        if (!st)
+            continue;
+        if (st.isDirectory()) {
+            if (!SKIP_DIRS.has(name) && depth < MAX_DEPTH)
+                findLogs(p, depth + 1, out);
+        }
+        else if (st.isFile() && LOG_NAMES.has(name))
+            out.push(p);
+    }
+    return out;
+}
+export function gameOf(file) {
+    let dir = dirname(file);
+    for (;;) {
+        const manifest = join(dir, 'funpixel.json');
+        if (existsSync(manifest)) {
+            try {
+                const m = JSON.parse(readFileSync(manifest, 'utf8'));
+                if (typeof m.name === 'string' && m.name.trim())
+                    return { name: m.name.trim(), named: true };
+            }
+            catch { }
+            return { name: basename(dir), named: false };
+        }
+        const up = dirname(dir);
+        if (up === dir)
+            return { name: basename(basename(dirname(file)) === '.funtools' ? dirname(dirname(file)) : dirname(file)), named: false };
+        dir = up;
+    }
+}
+export const gameKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+const costOf = (e) => {
+    if (typeof e.cost_usd === 'number')
+        return `$${e.cost_usd}`;
+    if (typeof e.credits === 'number')
+        return `${e.credits} credits`;
+    if (typeof e.minutes === 'number')
+        return `${e.minutes} min`;
+    return str(e.cost);
+};
+const isVerdict = (v) => typeof v === 'string' && VERDICTS.includes(v);
+export function parseLine(line, game, file) {
+    let e;
+    try {
+        e = JSON.parse(line);
+    }
+    catch {
+        return [];
+    }
+    if (!e || typeof e !== 'object')
+        return [];
+    const kind = str(e.kind) ?? 'note';
+    if (Array.isArray(e.items)) {
+        return e.items.flatMap((raw) => {
+            if (!raw || typeof raw !== 'object')
+                return [];
+            const i = raw;
+            const text = str(i.text) ?? [str(i.label), str(i.detail)].filter(Boolean).join(': ');
+            if (!text)
+                return [];
+            return [{ game, file, kind, text, cost: str(i.cost), category: str(i.category), verdict: isVerdict(i.kind) ? i.kind : undefined, tool: str(i.tool) }];
+        });
+    }
+    const text = str(e.text) ?? str(e.note);
+    return text ? [{ game, file, kind, text, cost: costOf(e) }] : [];
+}
+export const TOOLS = [
+    [/\bverify --front-door\b|\bfront[- ]door\b/i, 'verify --front-door'],
+    [/\bverify\b/i, 'verify'],
+    [/\baudit-screens\b|\blayout audit\b/i, 'audit-screens'],
+    [/\bcapture --all\b|\bcaptures?\b(?! browser)/i, 'capture'],
+    [/__FPX_MOMENT__|\bmoment views?\b|\bcapture burst\b/i, 'moment views'],
+    [/\bprofiler?\b|\bsoftware[- ]renderer timings\b/i, 'profile'],
+    [/\boptimize compress\b|\bfuntools optimize\b|\boptimize helper\b/i, 'optimize'],
+    [/\breport_feedback\b/i, 'report_feedback'],
+    [/\bgenerate_spritesheet\b|\bgen sheet\b|\bsprite ?sheets?\b|\bsheets?\b.*\b(cycles?|frames?)\b/i, 'generate_spritesheet'],
+    [/\bedit_image\b|\bpose edits?\b/i, 'edit_image'],
+    [/\bgenerate_image\b|\bgenerate_sprite\b|\bgen (image|sprite)\b/i, 'generate_image / generate_sprite'],
+    [/\bkey_sprite\b|\baccept_asset\b|\bimport_asset\b|\bapproved PNGs?\b/i, 'asset import (key_sprite, accept_asset, import_asset)'],
+    [/\bgenerate_sound\b|\bgenerate_music\b|\bsound effects?\b|\bsfx\b|\bmusic\b/i, 'generate_sound / generate_music'],
+    [/\bbuild_level\b|\bBlender\b|\bGLB level\b/i, 'Blender bench (build_level)'],
+    [/\bcritics?\b|\bpanel\b|\bseats?\b/i, 'critic panel'],
+    [/\bblind (phone )?player\b|\bfp:player\b|\bplayer round\b|\bfuntools play\b/i, 'blind player'],
+    [/\bnpm test\b|\bfuntools test\b|\bselftests?\b|\besbuild\b/i, 'test / selftests'],
+    [/\bpack (--)?dry-run\b|\bfuntools pack\b/i, 'pack'],
+    [/\bheredocs?\b|\bsed -i\b|\bfor[- ]loops?\b|\bcompound (shell )?commands?\b|\bshell (loops|refused)\b|\bBash refused\b|\b(sips|python)( and \w+)? (was|were) (denied|refused)\b|\bdenied calls?\b|\bauto-denied\b/i, 'host shell (refused forms)'],
+    [/\bStop (hook|gate)\b|\bnudges?\b/i, 'hooks (Stop gate, nudge)'],
+    [/\bscaffold\b|\bfuntools init\b/i, 'scaffold (funtools init)'],
+    [/\bfuntools sim\b|\bbots?\b/i, 'bots and sims (funtools sim, own bots)'],
+];
+export function toolsIn(text) {
+    const plain = text.replace(/\bverify --front-door\b/gi, '');
+    const out = TOOLS.filter(([re, name]) => (name === 'verify' ? re.test(plain) : re.test(text))).map(([, name]) => name);
+    for (const m of text.matchAll(/\bfunpixel-[a-z0-9-]+\b/g))
+        if (!out.includes(m[0]))
+            out.push(m[0]);
+    return out;
+}
+const MISSING_CATEGORIES = new Set(['tool_gap', 'package_gap', 'knowledge_gap', 'verification_gap', 'built_custom']);
+const HURT_CATEGORIES = new Set(['workaround', 'provider_failure', 'platform_trap', 'prompt_feedback']);
+const MISSING_KINDS = new Set(['missing', 'gap']);
+const HURT_KINDS = new Set(['dead-end', 'dead_end', 'mistake']);
+const MISSING_WORDS = /\btoo \w+ to\b|\b(no (way|route|tool|verify check|check|landscape)|has no|have no|missing|lacks?|cannot (run|verify|see|tell|read)|could not (read|resize|run)|not (run|reachable|auditioned)|unreachable|unavailable)\b/i;
+const HURT_WORDS = /\b(refused|denied|failed|fails|404|not found|false|wrongly|unreliable|broke|wasted|flags?|flagged|clamps?|assumes?|does not|did not|never (was|were)|bit|cost (two|\d+) (wasted )?calls|looped|overflowed|blew)\b/i;
+const WORKED_WORDS = /\b(caught|found by|PASS(ED)?|[Pp]ass(es)?|clean|kept identity|keep identity|fixed it|works?|worked|helped|exposed it)\b|\b(\d+)\/\2\b/;
+export function verdictOf(s) {
+    if (s.verdict)
+        return s.verdict;
+    if (s.category) {
+        if (MISSING_CATEGORIES.has(s.category))
+            return 'missing';
+        if (HURT_CATEGORIES.has(s.category))
+            return 'hurt';
+    }
+    if (MISSING_KINDS.has(s.kind))
+        return 'missing';
+    if (HURT_KINDS.has(s.kind)) {
+        if (HURT_WORDS.test(s.text))
+            return 'hurt';
+        if (MISSING_WORDS.test(s.text))
+            return 'missing';
+        return WORKED_WORDS.test(s.text) ? 'worked' : 'hurt';
+    }
+    if (MISSING_WORDS.test(s.text))
+        return 'missing';
+    if (HURT_WORDS.test(s.text))
+        return 'hurt';
+    if (WORKED_WORDS.test(s.text))
+        return 'worked';
+    return null;
+}
+const norm = (t) => t.toLowerCase().replace(/\s+/g, ' ').trim();
+export function clauses(s) {
+    if (s.tool || s.verdict || s.category)
+        return [s];
+    const parts = s.text.split(/;\s*|\.\s+|,\s+|\s*\(|\)\s*/).map((t) => t.trim()).filter((t) => t.length > 2);
+    return parts.length > 1 ? parts.map((text) => ({ ...s, text, quote: s.text })) : [s];
+}
+export function collect(dirs) {
+    const roots = dirs.map((d) => resolve(d));
+    const files = [...new Set(roots.flatMap((d) => (statSync(d).isFile() ? [d] : findLogs(d))))].sort();
+    const shown = (f) => {
+        const root = roots.find((r) => f === r || f.startsWith(`${r}/`)) ?? dirname(f);
+        return join(basename(root), relative(root, f));
+    };
+    const seen = new Set();
+    const said = [];
+    const names = new Map();
+    const learned = [];
+    const learnedSeen = new Set();
+    const gameRoots = new Map();
+    const ab = [];
+    const evCache = new Map();
+    for (const file of files) {
+        const g = gameOf(file);
+        const key = gameKey(g.name);
+        const known = names.get(key);
+        if (!known || (g.named && !known.named))
+            names.set(key, g);
+        const root = rootOfLog(file);
+        if (!gameRoots.has(key))
+            gameRoots.set(key, root);
+        for (const line of readFileSync(file, 'utf8').split('\n')) {
+            if (!line.trim())
+                continue;
+            const rec = basename(file) === 'ab.jsonl' || /"kind"\s*:\s*"ab"/.test(line) ? parseAb(line) : null;
+            if (rec) {
+                if (!ab.some((x) => x.id === rec.id))
+                    ab.push(rec);
+                continue;
+            }
+            if (basename(file) === 'ab.jsonl')
+                continue;
+            let e = null;
+            try {
+                e = JSON.parse(line);
+            }
+            catch { }
+            const l = e && typeof e === 'object' ? learnedOf(e, key, root, evCache) : null;
+            if (l) {
+                const id = `${key}\u0000${l.kind}\u0000${norm(l.text)}`;
+                if (!learnedSeen.has(id)) {
+                    learnedSeen.add(id);
+                    learned.push(l);
+                }
+            }
+        }
+        for (const line of readFileSync(file, 'utf8').split('\n')) {
+            if (basename(file) === 'ab.jsonl')
+                break;
+            for (const s of parseLine(line, key, file)) {
+                const id = `${key}\u0000${s.tool ?? ''}\u0000${norm(s.text)}`;
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                said.push(s);
+            }
+        }
+    }
+    for (const s of said)
+        s.game = names.get(s.game)?.name ?? s.game;
+    for (const [key, root] of gameRoots)
+        learned.push(...pipelineOwnerNotes(root, key));
+    for (const l of learned)
+        l.game = names.get(l.game)?.name ?? l.game;
+    const rows = new Map();
+    const overall = [];
+    let aboutTheKit = 0;
+    for (const s of said) {
+        if (s.tool?.toLowerCase() === 'kit') {
+            overall.push({ game: s.game, verdict: s.verdict ?? null, text: s.text });
+            aboutTheKit++;
+            continue;
+        }
+        let named = false;
+        for (const part of clauses(s)) {
+            const tools = part.tool ? [part.tool] : toolsIn(part.text);
+            if (!tools.length)
+                continue;
+            named = true;
+            const v = verdictOf(part);
+            if (!v)
+                continue;
+            for (const tool of tools) {
+                const key = `${v}\u0000${tool}`;
+                const row = rows.get(key) ?? { tool, verdict: v, games: [], count: 0, quotes: [] };
+                row.count++;
+                if (!row.games.includes(s.game))
+                    row.games.push(s.game);
+                if (row.quotes.length < 3 && !row.quotes.some((q) => q.game === s.game))
+                    row.quotes.push({ game: s.game, text: part.text, kind: s.kind });
+                rows.set(key, row);
+            }
+        }
+        if (named)
+            aboutTheKit++;
+    }
+    const ranked = [...rows.values()].sort((a, b) => b.games.length - a.games.length || b.count - a.count || a.tool.localeCompare(b.tool));
+    return {
+        files: files.map(shown),
+        games: [...new Set(said.map((s) => s.game))].sort(),
+        entries: said.length,
+        aboutTheKit,
+        aboutTheGame: said.length - aboutTheKit,
+        explicit: said.filter((s) => s.verdict || s.tool).length,
+        rows: ranked,
+        overall,
+        ledger: ledger(learned, ab),
+    };
+}
+const HEADINGS = { worked: 'Kit tools that worked', hurt: 'Kit tools that hurt (in the way, or wrong)', missing: 'What the kit was missing' };
+const clip = (t, n = 220) => (t.length > n ? `${t.slice(0, n - 1)}…` : t);
+export function markdown(c) {
+    const out = [];
+    out.push('# Feedback, collected: what the games taught the kit', '');
+    out.push(`${c.entries} entries from ${c.files.length} log file(s) across ${c.games.length} game(s) (${c.games.join(', ')}); `
+        + `${c.aboutTheKit} name a kit tool (${c.rows.reduce((n, r) => n + r.count, 0)} tool mentions with a verdict), ${c.aboutTheGame} are about the game only; ${c.explicit} came as an explicit kit verdict.`, '');
+    out.push('Ranked by how many games said it, then how often. Verdicts on dev-log lines are read from their kind and words; the quotes are the evidence.', '');
+    out.push(...ledgerMarkdown(c.ledger));
+    out.push('## About the kit\'s own tools', '');
+    if (c.overall.length) {
+        out.push('## Overall verdicts', '');
+        for (const o of c.overall)
+            out.push(`- **${o.game}** (${o.verdict ?? 'no kind'}): ${clip(o.text)}`);
+        out.push('');
+    }
+    for (const v of VERDICTS) {
+        const rows = c.rows.filter((r) => r.verdict === v);
+        out.push(`## ${HEADINGS[v]}`, '');
+        if (!rows.length) {
+            out.push(v === 'worked' && c.ledger.worked.length ? `No line names a kit tool as working; the game's practice that worked (${c.ledger.worked.length}) is ranked above.` : 'Nothing said.', '');
+            continue;
+        }
+        out.push('| Tool | Games | Entries | Evidence |', '|---|---|---|---|');
+        for (const r of rows) {
+            const quotes = r.quotes.map((q) => `${q.game}: “${clip(q.text, 160).replace(/\|/g, '\\|')}”`).join('<br>');
+            out.push(`| ${r.tool} | ${r.games.length} (${r.games.join(', ')}) | ${r.count} | ${quotes} |`);
+        }
+        out.push('');
+    }
+    out.push('## Sources', '', ...c.files.map((f) => `- ${f}`), '');
+    return out.join('\n');
+}
+export const LOG_KINDS = ['step', 'test', 'dead-end', 'lesson', 'decision', 'worked', 'didnt', 'owner', 'measure'];
+export const OWNER_VERDICTS = ['pick', 'reject', 'note'];
+const stampOf = (d) => d.toISOString().replace(/\.\d+Z$/, 'Z');
+export async function feedbackLog(opts, io = console, now = () => new Date()) {
+    const u = ui(io, 'feedback');
+    const text = opts.text?.replace(/\s+/g, ' ').trim();
+    if (!text) {
+        u.error('nothing to log', 'funtools feedback log "what happened" [--kind lesson] [--cost-usd 0.3]');
+        return EXIT.error;
+    }
+    const kind = opts.kind ?? 'step';
+    if (!LOG_KINDS.includes(kind)) {
+        u.error(`unknown kind: ${kind}`, `--kind is ${LOG_KINDS.join(', ')}`);
+        return EXIT.error;
+    }
+    if (opts.verdict && !OWNER_VERDICTS.includes(opts.verdict)) {
+        u.error(`--verdict ${opts.verdict}`, `--verdict is ${OWNER_VERDICTS.join(', ')} (with --kind owner)`);
+        return EXIT.error;
+    }
+    const num = (v, name) => {
+        if (v === undefined)
+            return undefined;
+        const n = Number(v.replace(/^\$/, ''));
+        if (!Number.isFinite(n) || (n < 0 && name !== '--before' && name !== '--after')) {
+            u.error(`${name} is a number, got ${v}`, `e.g. ${name} 0.3`);
+            return null;
+        }
+        return n;
+    };
+    const cost = num(opts.costUsd, '--cost-usd'), minutes = num(opts.minutes, '--minutes'), lost = num(opts.minutesLost, '--minutes-lost');
+    const before = num(opts.before, '--before'), after = num(opts.after, '--after');
+    if ([cost, minutes, lost, before, after].includes(null))
+        return EXIT.error;
+    if ((before === undefined) !== (after === undefined)) {
+        u.error('a measured outcome needs both --before and --after', '--metric "phone p95" --before 34 --after 25.5 --unit ms');
+        return EXIT.error;
+    }
+    const game = resolve(opts.dir ?? '.');
+    const entry = {
+        at: stampOf(now()), kind, text,
+        ...(opts.metric ? { metric: opts.metric } : {}), ...(before !== undefined ? { before, after, ...(opts.unit ? { unit: opts.unit } : {}) } : {}),
+        ...(cost !== undefined ? { cost_usd: cost } : {}), ...(minutes !== undefined ? { minutes } : {}), ...(lost !== undefined ? { minutes_lost: lost } : {}),
+        ...(opts.evidence ? { evidence: opts.evidence } : {}), ...(opts.film ? { film: opts.film } : {}), ...(opts.sha ? { sha: opts.sha } : {}), ...(opts.test ? { test: opts.test } : {}),
+        ...(opts.tool ? { tool: opts.tool } : {}), ...(opts.stage ? { stage: opts.stage } : {}),
+        ...(kind === 'owner' ? { verdict: opts.verdict ?? 'note' } : {}), ...(opts.screenshot ? { screenshot: opts.screenshot } : {}),
+    };
+    const file = join(game, '.funtools', 'devlog.jsonl');
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, JSON.stringify(entry) + '\n');
+    const l = learnedOf(entry, 'this game', game);
+    const missing = l?.evidence.filter((x) => x.exists === false).map((x) => x.ref) ?? [];
+    if (opts.json)
+        io.log(JSON.stringify({ file, entry, evidence_missing: missing }, null, 2));
+    else {
+        if (missing.length)
+            u.item('warn', `evidence not found: ${missing.join(', ')}`, 'the entry is kept and reads as unverified until it exists');
+        if ((kind === 'worked' || kind === 'didnt') && before === undefined && !l?.measure)
+            u.item('note', 'no measured outcome: add --metric --before --after --unit so collect can rank it by the change');
+        u.summary('pass', `${kind} logged in ${relative(process.cwd(), file) || file}`);
+    }
+    return EXIT.pass;
+}
+export async function feedbackAb(opts, io = console, now = () => new Date()) {
+    const u = ui(io, 'feedback');
+    const game = opts.text?.trim();
+    const routes = (opts.routes ?? '').split(',').map((r) => r.trim()).filter(Boolean);
+    if (!game || routes.length < 2) {
+        u.error('an A/B names the game and two routes', 'funtools feedback ab "My Game" --routes gdk,non-gdk --overall 7.0,8.0 --axes "story=7.0/8.7,fun=7.4/7.7" --winner non-gdk --judges "3 blind seats"');
+        return EXIT.error;
+    }
+    const overall = (opts.overall ?? '').split(',').map((x) => (x.trim() ? Number(x) : null));
+    const axes = {};
+    for (const part of (opts.axes ?? '').split(',').map((x) => x.trim()).filter(Boolean)) {
+        const [name, vals] = part.split('=');
+        if (!name || !vals) {
+            u.error(`--axes ${part}`, 'axis=a/b, e.g. "level design=6.3/8.1"');
+            return EXIT.error;
+        }
+        axes[name.trim()] = vals.split('/').map((v) => (v.trim() ? Number(v) : null));
+    }
+    const rec = {
+        id: `${gameKey(game)}-${stampOf(now())}`, game, at: stampOf(now()).slice(0, 10), what: opts.what ?? '', judges: opts.judges ?? '',
+        variants: routes.map((route, i) => ({ route, overall: overall[i] ?? null, axes: Object.fromEntries(Object.entries(axes).map(([a, v]) => [a, v[i] ?? null])) })),
+        winner: opts.winner ?? 'split', evidence: opts.evidence ? [opts.evidence] : [],
+    };
+    const file = join(resolve(opts.dir ?? '.'), '.funtools', 'ab.jsonl');
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, JSON.stringify({ kind: 'ab', ...rec }) + '\n');
+    if (opts.json)
+        io.log(JSON.stringify(rec, null, 2));
+    else
+        u.summary('pass', `A/B recorded in ${relative(process.cwd(), file) || file}`);
+    return EXIT.pass;
+}
+export async function feedbackMerged(opts, io = console) {
+    const u = ui(io, 'feedback');
+    const root = resolve(opts.dir ?? '.');
+    const ref = opts.sha ?? 'HEAD';
+    const vcs = (...args) => spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+    const show = vcs('log', '-1', '--format=%H%x00%s%x00%P%x00%cI', ref);
+    if (show.status !== 0) {
+        u.error(`no commit ${ref} in ${root}`, 'run it in the game\'s repository');
+        return EXIT.error;
+    }
+    const [sha, subject, parents, at] = show.stdout.trim().split('\0');
+    const ps = parents.split(' ').filter(Boolean);
+    if (ps.length < 2) {
+        u.summary('not_observed', `${sha.slice(0, 9)} is not a merge commit`);
+        return EXIT.not_observed;
+    }
+    const base = vcs('merge-base', ps[0], ps[1]).stdout.trim();
+    const since = base ? vcs('log', '-1', '--format=%cI', base).stdout.trim() : '';
+    const moved = new Map();
+    try {
+        for (const line of readFileSync(join(root, '.funtools', 'devlog.jsonl'), 'utf8').split('\n')) {
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (e?.kind !== 'measure' || typeof e.after !== 'number')
+                continue;
+            const t = Date.parse(String(e.at));
+            if ((since && t < Date.parse(since)) || t > Date.parse(at))
+                continue;
+            const k = `${e.tool}\0${e.metric}`;
+            const m = moved.get(k);
+            moved.set(k, m ? { ...m, after: e.after } : { tool: e.tool, metric: e.metric, before: typeof e.before === 'number' ? e.before : e.after, after: e.after, unit: e.unit ?? '' });
+        }
+    }
+    catch { }
+    const share = (c) => Math.abs(c.after - c.before) / Math.max(1e-9, Math.abs(c.before));
+    const changes = [...moved.values()].filter((m) => m.before !== m.after).sort((a, b) => share(b) - share(a));
+    const top = changes[0];
+    return feedbackLog({
+        ...opts, sub: 'log', kind: 'worked', sha, tool: top?.tool ?? 'merge',
+        text: `merged: ${subject}${changes.length ? ` (${changes.map((c) => `${c.tool} ${c.metric} ${c.before} -> ${c.after}${c.unit ? ` ${c.unit}` : ''}`).slice(0, 4).join('; ')})` : ''}`,
+        ...(top ? { metric: `${top.tool} ${top.metric}`, before: String(top.before), after: String(top.after), unit: top.unit } : {}),
+    }, io);
+}
+export async function feedback(opts, io = console) {
+    const u = ui(io, 'feedback');
+    if (opts.sub === 'log')
+        return feedbackLog(opts, io);
+    if (opts.sub === 'ab')
+        return feedbackAb(opts, io);
+    if (opts.sub === 'merged')
+        return feedbackMerged(opts, io);
+    if (opts.sub !== 'collect') {
+        u.error(opts.sub ? `unknown: feedback ${opts.sub}` : 'feedback needs a verb', 'funtools feedback collect <folders…> · log "<what happened>" · ab "<game>" · merged');
+        return EXIT.error;
+    }
+    const dirs = opts.dirs.length ? opts.dirs : ['.'];
+    const missing = dirs.filter((d) => !existsSync(d));
+    if (missing.length) {
+        u.error(`no such folder: ${missing.join(', ')}`, 'give the folders that hold the games');
+        return EXIT.error;
+    }
+    const c = collect(dirs);
+    const proposals = opts.propose || opts.html ? propose(c.ledger) : [];
+    if (opts.html) {
+        writeFileSync(opts.html, feedbackPage(c.ledger, c.rows, proposals));
+        if (!opts.json)
+            u.item('pass', `the page: ${opts.html}`);
+    }
+    const found = c.entries || c.ledger.entries.length;
+    if (opts.json) {
+        io.log(JSON.stringify({ ...c, ...(opts.propose ? { proposals } : {}) }, null, 2));
+        return found ? EXIT.pass : EXIT.not_observed;
+    }
+    const md = markdown(c) + (opts.propose ? `\n${proposalsMarkdown(proposals).join('\n')}` : '');
+    if (opts.out) {
+        writeFileSync(opts.out, md);
+        u.summary(found ? 'pass' : 'not_observed', `${c.ledger.entries.length} entries from ${c.games.length} game(s) → ${opts.out}`);
+    }
+    else if (!opts.html || opts.propose)
+        io.log(md);
+    else
+        u.summary(found ? 'pass' : 'not_observed', `${c.ledger.worked.length} worked, ${c.ledger.deadEnds.length} dead ends, ${c.ledger.owner.length} from the owner`);
+    return found ? EXIT.pass : EXIT.not_observed;
+}

package/dist/commands/feel.js

@@ -0,0 +1,144 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { checkFeel, FEEL_SCRIPT, playFeel } from "../feel/run.js";
+import { judge } from "../feel/judge.js";
+import { checkSweeps, sweepFeel } from "../feel/sweep.js";
+import { specOf } from "../feel/spec.js";
+import { ui } from "../ui.js";
+import { NO_RENDERER, rendererLine, timingVoid } from "../verify/gpu.js";
+export const FEEL_RECORD = join('.funtools', 'feel.json');
+export const FEEL_TRACE = join('.funtools', 'feel', 'trace.json');
+export function designOf(dir) {
+    for (const f of ['GDD.md', 'README.md']) {
+        const p = join(dir, 'design', f);
+        if (existsSync(p)) {
+            try {
+                return { md: readFileSync(p, 'utf8'), source: `design/${f}` };
+            }
+            catch { }
+        }
+    }
+    return null;
+}
+export function judgeRun(trace, dir, script, windows = {}) {
+    const spec = specOf(designOf(dir), script.expect ?? {});
+    return { spec, ...judge(trace, spec, windows) };
+}
+const MARK = { note: 'note', ok: 'pass', 'not measured': 'not_observed' };
+const AREA = {
+    verb: 'the verb against the design', telegraph: 'telegraph and dodge', death: 'death beat and restart', animation: 'looks by state', feedback: 'feedback on key events',
+};
+export async function feel(opts, io = console, play = playFeel, sweep = sweepFeel) {
+    const dir = resolve(opts.target ?? '.');
+    const u = ui(io, 'feel');
+    const rel = opts.script ?? FEEL_SCRIPT;
+    const raw = opts.journey ? { journey: opts.journey } : null;
+    if (!raw && !existsSync(join(dir, rel))) {
+        if (opts.json)
+            io.log(JSON.stringify({ tool: 'funtools', command: 'feel', exit: EXIT.not_observed, script: rel, findings: [] }, null, 2));
+        else
+            u.summary('not_observed', `no ${rel}: nothing played the verbs — the scaffold's test/feel.json shows the shape (skill funpixel-game-feel, references/measure.md), or --journey <name> plays a journey`);
+        return EXIT.not_observed;
+    }
+    let parsed = raw;
+    if (!parsed) {
+        try {
+            parsed = JSON.parse(readFileSync(join(dir, rel), 'utf8'));
+        }
+        catch (e) {
+            u.error(`${rel} is not JSON: ${e.message}`);
+            return EXIT.error;
+        }
+    }
+    const c = checkFeel(parsed, dir);
+    if (c.problems.length) {
+        for (const p of c.problems)
+            u.item('fail', p);
+        u.error(`${opts.journey ? `journey ${opts.journey}` : rel} is not a feel script yet`, 'fix the lines above');
+        return EXIT.error;
+    }
+    const script = c.script;
+    const sw = checkSweeps(script.sweeps);
+    if (sw.problems.length) {
+        for (const p of sw.problems)
+            u.item('fail', p);
+        u.error(`${rel} has a sweep that cannot run`, 'fix the lines above');
+        return EXIT.error;
+    }
+    const fp = await fingerprint(dir).then((f) => f.fingerprint).catch(() => null);
+    const played = await play(dir, script, c.steps);
+    if (typeof played === 'string') {
+        u.error(played, 'build first (npm run build): feel plays dist/');
+        return EXIT.error;
+    }
+    if (played.browser_lost) {
+        u.summary('not_observed', `${played.browser_lost}: not evidence about the game; run it again`);
+        return EXIT.not_observed;
+    }
+    const renderer = played.renderer ?? NO_RENDERER;
+    const timing_void = timingVoid(renderer);
+    let windows = {};
+    const sweepNotes = [];
+    const sweeps = opts.sweep === false || timing_void ? [] : sw.sweeps;
+    if (sweeps.length) {
+        if (!opts.json)
+            u.item('note', `sweeping ${sweeps.map((x) => x.id).join(' and ')}: a fresh load an attempt, up to ${Math.max(...sweeps.map((x) => x.offsets.length))} each`);
+        const got = await sweep(dir, script, sweeps, opts.json ? undefined : (line) => u.line(`  ${line}`));
+        if (typeof got === 'string')
+            sweepNotes.push(`sweeps: ${got}`);
+        else {
+            windows = got.windows;
+            sweepNotes.push(...got.notes);
+        }
+    }
+    else if (sw.sweeps.length)
+        sweepNotes.push(`--no-sweep: ${sw.sweeps.map((x) => x.id).join(' and ')} not measured`);
+    const judged = judgeRun(played.trace, dir, script, windows);
+    const { spec, measured } = judged;
+    const findings = timing_void ? [{ id: 'renderer', area: 'verb', state: 'not measured', says: `VOID — ${timing_void}` }] : judged.findings;
+    const measuredAny = played.trace.observed && findings.some((f) => f.state !== 'not measured');
+    const exit = measuredAny ? EXIT.pass : EXIT.not_observed;
+    const S = played.trace.samples;
+    const record = {
+        tool: 'funtools', command: 'feel', exit, script: opts.journey ? `journey ${opts.journey}` : rel, fingerprint: fp, at: new Date().toISOString(),
+        viewport: script.viewport, size: played.size, seed: script.seed, samples: S.length, seconds: S.length ? Math.round((S.at(-1).t - S[0].t) / 100) / 10 : 0,
+        clock: measured.clock, spec, measured, findings, notes: [...played.notes, ...sweepNotes, ...(measured.clock_note ? [measured.clock_note] : [])], page_errors: played.page_errors,
+        renderer, ...(timing_void ? { timing_void } : {}),
+    };
+    await mkdir(dirname(join(dir, FEEL_TRACE)), { recursive: true });
+    await writeFile(join(dir, FEEL_TRACE), JSON.stringify(played.trace) + '\n');
+    await writeFile(join(dir, FEEL_RECORD), JSON.stringify(record, null, 2) + '\n');
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return exit;
+    }
+    u.heading(`${record.script} · ${script.viewport} ${played.size} · seed ${script.seed} · ${record.samples} frames over ${record.seconds} s · ${measured.clock === 'game' ? 'on the game\'s clock (state t)' : 'on the page\'s clock'}`);
+    if (timing_void)
+        u.item('not_observed', `VOID: ${timing_void}`);
+    else
+        u.item('note', rendererLine(renderer));
+    if (!played.trace.observed)
+        u.item('not_observed', 'the page answered no __FPX_STATE__ while the script played');
+    const longest = measured.long_frames.length ? Math.max(...measured.long_frames.map((f) => f.ms)) : 0;
+    if (!timing_void && measured.long_frames.length)
+        u.item('note', measured.clock === 'game'
+            ? `${measured.long_frames.length} frame(s) over 50 ms (longest ${longest} ms): a stutter the player would see; the windows are on the game's clock, so it does not lengthen them`
+            : `${measured.long_frames.length} frame(s) over 50 ms (longest ${longest} ms): a game that clamps dt loses time there, so a window holding one reads long in wall time (expose state t, the game's clock in seconds, to read windows in game time)`);
+    for (const n of record.notes)
+        u.item('note', n);
+    for (const area of ['verb', 'telegraph', 'death', 'animation', 'feedback']) {
+        const fs = findings.filter((f) => f.area === area);
+        if (!fs.length)
+            continue;
+        u.heading(AREA[area]);
+        for (const f of fs)
+            u.item(MARK[f.state], f.says, f.state === 'ok' ? undefined : f.next);
+    }
+    const count = (s) => findings.filter((f) => f.state === s).length;
+    const tally = `${count('note')} note · ${count('ok')} ok · ${count('not measured')} not measured`;
+    u.summary(count('note') ? 'note' : measuredAny ? 'pass' : 'not_observed', `${tally} — a mirror: change the game or own the number in the design (${FEEL_RECORD})`);
+    return exit;
+}