@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/playtest/assemble.js

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { roundDir, roundsFiled } from "../play/session.js";
+import { PLAYTEST_DIR, playtests } from "./prepare.js";
+import { rank } from "./rank.js";
+import { renderReport } from "./report.js";
+import { axisMeans, phoneMeans, readPick, readVerdict, winRate } from "./seats.js";
+import { citations } from "./facts.js";
+import { experienceMeans, readExperience } from "./experience.js";
+import { readFidelity } from "./fidelity.js";
+import { readUiFidelity } from "./mockups.js";
+import { readRecord } from "./experience-run.js";
+import { counts, mergedText, readMobileQa } from "./mobile-qa.js";
+import { blockersOf, carryForward, judgeLedger, readLedger } from "./ledger.js";
+import { carried as keptItems, keepBefore, lostItems, mergeKeep, readKeep, writeKeep } from "./keep.js";
+import { historyRow, saveRound } from "./history.js";
+import { milestoneOf, stopRule } from "./stop.js";
+import { momentScores } from "./moments.js";
+import { playLength } from "./length.js";
+import { designDoc } from "../gdd/doc.js";
+import { planHookCells } from "../gdd/world.js";
+export const STEPS = 4;
+const readJson = (f) => { try {
+    return JSON.parse(readFileSync(f, 'utf8'));
+}
+catch {
+    return null;
+} };
+export function playerRound(root, since) {
+    for (const n of [...roundsFiled(root)].reverse()) {
+        const r = readJson(join(roundDir(root, n), 'report.json'));
+        if (!r || r.at < since)
+            continue;
+        return { round: n, dir: roundDir(root, n), blocked: !!r.blocked, start: r.start, goal: r.goal, act: r.act, end: r.end, defects: r.defects ?? [], confusions: r.confusions ?? [], ...(r.come_back ? { come_back: r.come_back } : {}), ...(Array.isArray(r.screens) ? { screens: r.screens } : {}), ...(typeof r.played_minutes === 'number' ? { played_minutes: r.played_minutes } : {}) };
+    }
+    return null;
+}
+export function hostedPlayer(dir) {
+    const r = readJson(join(dir, 'player-hosted.json'));
+    if (!r?.start)
+        return null;
+    const frames = Array.isArray(r.frames) ? r.frames : [];
+    const defects = (r.defects ?? []).map((d) => ({ ...d, shot: frames.find((f) => d.shot && f.includes(d.shot)) ?? d.shot ?? '' }));
+    return { round: 0, dir, blocked: !!r.blocked, start: r.start, goal: r.goal, act: r.act, end: r.end, defects, confusions: r.confusions ?? [] };
+}
+function distinct(steps) {
+    const seen = new Set();
+    return steps.filter((s) => { const k = s.text.toLowerCase().slice(0, 48); if (seen.has(k))
+        return false; seen.add(k); return true; });
+}
+export async function assemble(root, n, opts) {
+    const dir = join(root, PLAYTEST_DIR, String(n));
+    const plan = readJson(join(dir, 'plan.json'));
+    const measures = readJson(join(dir, 'measures.json'));
+    if (!plan || !measures)
+        throw new Error(`playtest ${n} was not prepared (no plan.json): run \`funtools playtest\` first`);
+    const verdicts = [], missing = [];
+    for (const s of plan.seats) {
+        const r = readVerdict(join(dir, 'seats', `${s}.json`));
+        if (r.verdict)
+            verdicts.push({ ...r.verdict, critic: s });
+        else
+            missing.push({ seat: s, why: r.problem ?? 'not filed' });
+    }
+    const picks = plan.versus.ran ? plan.versus.calls.flatMap((c) => {
+        const [persona, ...rest] = c.split('-');
+        const p = readPick(join(dir, 'versus', `${c}.json`), persona, rest.join('-'));
+        return p ? [p] : [];
+    }) : [];
+    const wr = winRate(picks);
+    const player = hostedPlayer(dir) ?? playerRound(root, plan.at);
+    const means = axisMeans(verdicts);
+    const xVerdicts = [], xMissing = [];
+    for (const s of plan.experience?.seats ?? []) {
+        const r = readExperience(join(dir, 'experience', `${s}.json`));
+        if (r.verdict)
+            xVerdicts.push({ ...r.verdict, critic: s });
+        else
+            xMissing.push({ seat: s, why: r.problem ?? 'not filed' });
+    }
+    const xMeans = experienceMeans(xVerdicts);
+    const depthRecord = readRecord(dir);
+    const fid = plan.fidelity?.seat ? readFidelity(join(dir, 'fidelity', 'fidelity.json')) : null;
+    const ui = plan.fidelity?.ui?.pairs ? readUiFidelity(join(dir, 'fidelity', 'ui.json')) : null;
+    const mq = plan.mobile?.seat ? readMobileQa(join(dir, 'mobile', 'mobile-qa.json')) : null;
+    const mqEvidence = readJson(join(dir, 'mobile', 'evidence.json'));
+    const mqObserved = (plan.mobile?.platforms ?? []).filter((p) => p.observed).map((p) => p.id);
+    const mobileIn = mq?.verdict ? { verdict: mq.verdict, images: Array.isArray(mqEvidence?.images) ? mqEvidence.images : [], observed: mqObserved, primary: !!plan.mobile?.target.primary } : null;
+    const ranked = distinct(rank({ verdicts, means, hit: plan.hit, player, measures, picks, winRate: wr.win_rate, frames: plan.frames, framesDir: join(dir, 'frames'),
+        experience: xVerdicts.length ? { verdicts: xVerdicts, means: xMeans, hit: plan.hit.experience ?? null } : undefined, fidelity: fid?.verdict ?? null, ui: ui?.verdict ?? null, mobile: mobileIn }));
+    const previousN = playtests(root).filter((x) => x < n).at(-1);
+    const before = previousN !== undefined ? readJson(join(root, PLAYTEST_DIR, String(previousN), 'report.json')) : null;
+    const ledgerFile = join(dir, 'ledger', 'ledger.json');
+    const seat = existsSync(ledgerFile) ? readLedger(ledgerFile) : null;
+    const ledger = judgeLedger(blockersOf(before), seat, ranked);
+    const keep = mergeKeep(keepBefore(readKeep(root), n), seat?.keep ?? null, verdicts.map((v) => ({ who: v.critic, lines: v.best ?? [] })), n);
+    const regressions = lostItems(keep).map((i) => ({ source: 'panel', text: `Regression: ${i.text} — it worked (playtest ${i.since}) and is lost: put it back first`, quote: i.evidence ?? '', who: `the ledger seat (do-not-regress ${i.id})`, frame: null, number: `${i.id}, lost since playtest ${i.lost_since ?? n}`, score: 10_000 }));
+    const carried = [...regressions, ...carryForward(ranked, ledger)];
+    const mqBefore = previousN !== undefined ? readMobileQa(join(root, PLAYTEST_DIR, String(previousN), 'mobile', 'mobile-qa.json')).verdict ?? null : null;
+    const defects = { high: 0, medium: 0, low: 0 };
+    for (const d of player?.defects ?? [])
+        defects[d.severity] = (defects[d.severity] ?? 0) + 1;
+    const hud = measures.hud;
+    const summary = {
+        length: playLength(root, depthRecord?.pacing ?? []),
+        n, at: plan.at, game: plan.game, fingerprint: plan.fingerprint, quick: plan.quick,
+        hit: { slug: plan.hit.slug, name: plan.hit.name, panel: plan.hit.panel },
+        seats: { filed: verdicts.map((v) => v.critic), missing }, means,
+        versus: { ran: plan.versus.ran && wr.pairs > 0, note: plan.versus.ran && !wr.pairs ? 'prepared, but no pair of answers was filed' : plan.versus.note, win_rate: wr.win_rate, wins: wr.wins, losses: wr.losses, ties: wr.ties },
+        player: { round: player?.round ?? null, blocked: player ? player.blocked : null, defects, note: player ? `${player.start.answer}/${player.goal.answer}/${player.act.answer}/${player.end.answer}` : 'no round filed since this playtest was prepared' },
+        measured: {
+            verify: measures.verify?.verdict ?? (measures.build.ok ? 'did not run' : 'build failed'),
+            captures: `${measures.capture.filter((c) => c.ok).length} of ${measures.capture.length}`,
+            audit: measures.audit ? `${measures.audit.verdict}${measures.audit.failing.length ? ` (${measures.audit.failing.map((a) => a.view).join(', ')})` : ''}` : 'did not run',
+            hud: hud ? `${hud.verdict}${hud.views.some((v) => v.verdict === 'fail') ? ` (${hud.views.filter((v) => v.verdict === 'fail').map((v) => v.view).join(', ')})` : ''}` : 'did not run',
+            hud_numbers: Object.fromEntries(Object.entries(hud?.views.find((v) => v.verdict === 'fail')?.numbers ?? hud?.views[0]?.numbers ?? {})),
+            profile_p95: measures.profile?.some((p) => p.frame_ms_p95 !== null) ? Math.max(...measures.profile.map((p) => p.frame_ms_p95 ?? 0)) : null,
+            ...(measures.profile?.some((p) => p.timing_void) ? { profile_void: measures.profile.find((p) => p.timing_void).timing_void } : {}),
+            seconds: measures.seconds,
+        },
+        facts: { given: plan.facts?.length ?? 0, cited: Object.fromEntries(verdicts.map((v) => [v.critic, citations({ why: v.why, best: v.best, worst: v.worst, fixFirst: v.fixFirst })])) },
+        ...(measures.evidence && (measures.evidence.same.length || measures.evidence.logged.length) ? { evidence: measures.evidence } : {}),
+        experience: {
+            prepared: !!depthRecord, filed: xVerdicts.map((v) => v.critic), missing: depthRecord ? xMissing : [{ seat: 'experience', why: 'not prepared: run `funtools playtest experience` after the blind round' }],
+            means: xMeans, hit: plan.hit.experience ?? null, facts: depthRecord?.facts.length ?? 0,
+            come_back: player?.come_back ?? null, played_minutes: player?.played_minutes ?? null,
+            quotes: xVerdicts.map((v) => ({ seat: v.critic, comeBack: v.comeBack ?? '', claimed: v.claimed ?? [] })),
+            hook: { plan: planHookCells(designDoc(root)?.text ?? ''), player: player?.screens ?? [] },
+        },
+        fidelity: {
+            ran: !!fid?.verdict, pairs: plan.fidelity?.pairs ?? 0, unpaired: plan.fidelity?.unpaired ?? [], facts: plan.fidelity?.facts ?? [],
+            moments: momentScores(plan.fidelity?.moments ?? [], fid?.verdict ?? null, ui?.verdict ?? null, readJson(join(dir, 'fidelity', 'ui-pairs.json'))?.pairs ?? []),
+            art: fid?.verdict?.artDirection ?? null, creative: fid?.verdict?.creativeDirection ?? null, rules: fid?.verdict?.rules ?? {},
+            verdict: fid?.verdict?.verdict ?? (plan.fidelity?.seat ? (fid?.problem ?? 'not filed') : plan.fidelity?.facts[0]?.text ?? 'not prepared'),
+            ui: plan.fidelity?.ui ? {
+                mockups: plan.fidelity.ui.mockups, pairs: plan.fidelity.ui.pairs, unpaired: plan.fidelity.ui.unpaired,
+                ui: ui?.verdict?.uiFidelity ?? null, ux: ui?.verdict?.uxFidelity ?? null,
+                elements: ui?.verdict?.elements ?? [], additions: ui?.verdict?.additions ?? [], title: ui?.verdict?.title ?? null,
+                verdict: ui?.verdict?.verdict ?? (plan.fidelity.ui.pairs ? (ui?.problem ?? 'not filed') : 'no mockup paired with a game screen'),
+            } : undefined,
+        },
+        mobile: {
+            prepared: !!plan.mobile, ran: !!mq?.verdict, target: plan.mobile?.target.why ?? 'not prepared (the build failed, or a playtest from before Mobile QA)',
+            primary: !!plan.mobile?.target.primary, platforms: plan.mobile?.platforms ?? [],
+            phone_native: mq?.verdict?.phoneNative ?? null, before: mqBefore?.phoneNative ?? null, ...counts(mq?.verdict),
+            findings: (mq?.verdict?.findings ?? []).map((f) => ({ severity: f.severity, area: f.area, text: mergedText(f, mqObserved), number: f.evidence?.number ?? '', fix: f.fix ?? '' })),
+            verdict: mq?.verdict?.verdict ?? (plan.mobile?.seat ? (mq?.problem ?? 'not filed') : plan.mobile?.facts[0]?.text ?? 'not prepared'),
+        },
+        steps: carried.slice(0, Math.max(STEPS, regressions.length)), others: carried.slice(Math.max(STEPS, regressions.length)),
+        ...(ledger.length ? { ledger } : {}),
+        ...(keptItems(keep).length ? { keep: keptItems(keep) } : {}),
+        ...(plan.route ? { route: { filmed: plan.route.filmed, why: plan.route.why, run: plan.route.run ?? null, script: plan.route.script ?? null, void: plan.route.void ?? null } } : {}),
+        cost: { local_usd: 0, agent_runs: verdicts.length + picks.length + (player ? 1 : 0) + (mq?.verdict ? 1 : 0), creator_reported_usd: opts.costUsd, hosted_credits: opts.hostedCredits ?? null },
+    };
+    summary.milestone = milestoneOf(root, plan.fingerprint);
+    if (verdicts.some((v) => v.phone))
+        summary.phone = phoneMeans(verdicts);
+    const history = await saveRound(root, historyRow(summary));
+    summary.stop = stopRule(history) ?? undefined;
+    const md = renderReport(summary, before, verdicts, measures.compare, history);
+    if (keep.items.length)
+        writeKeep(root, keep);
+    await writeFile(join(dir, 'report.json'), JSON.stringify(summary, null, 2) + '\n');
+    await writeFile(join(dir, 'report.md'), md);
+    return { summary, md, file: join(dir, 'report.md') };
+}
+export const planOf = (root, n) => (existsSync(join(root, PLAYTEST_DIR, String(n), 'plan.json')) ? readJson(join(root, PLAYTEST_DIR, String(n), 'plan.json')) : null);

package/dist/playtest/experience-run.js

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { depth } from "../commands/depth.js";
+import { designDoc } from "../gdd/doc.js";
+import { experienceText } from "../depth/experience.js";
+import { experiencePrompt } from "./experience.js";
+import { rulesOf } from "./fidelity.js";
+import { playFacts, uiPrompt } from "./mockups.js";
+import { PLAY_DIR } from "../play/session.js";
+import { existsSync, readdirSync } from 'node:fs';
+export function spreadFrames(frames, n = 8) {
+    const stills = frames.filter((f) => !f.startsWith('clip-'));
+    const phone = stills.filter((f) => f.endsWith('-phone.png'));
+    const pool = phone.length >= Math.min(n, stills.length) ? phone : stills;
+    if (pool.length <= n)
+        return pool;
+    return Array.from({ length: n }, (_, k) => pool[Math.floor(((k + 0.5) * pool.length) / n)]);
+}
+export async function prepareExperience(root, plan, dir) {
+    const out = join(dir, 'experience');
+    await mkdir(out, { recursive: true });
+    const lines = [];
+    const code = await depth({ target: root, out, json: true }, { log: (m) => lines.push(String(m)), error: () => { } });
+    if (code !== 0)
+        throw new Error('depth could not measure this game');
+    const record = JSON.parse(lines.join('\n'));
+    const doc = designDoc(root);
+    const evidence = {
+        facts: experienceText(record.facts), textFile: record.files.text, beatsFile: record.files.beats, strip: record.files.strip,
+        frames: spreadFrames(plan.frames).map((f) => ({ name: f, path: join(dir, 'frames', f) })),
+        design: doc ? { file: doc.rel, text: doc.text } : null,
+    };
+    const prompts = [];
+    for (const seat of plan.experience?.seats ?? []) {
+        const file = join(out, `${seat}.md`);
+        await writeFile(file, experiencePrompt(seat, plan.premise.text, evidence, join(out, `${seat}.json`)));
+        prompts.push(file);
+    }
+    const pairsFile = join(dir, 'fidelity', 'ui-pairs.json');
+    if (existsSync(pairsFile)) {
+        const { pairs, title, dressing } = JSON.parse(readFileSync(pairsFile, 'utf8'));
+        if (pairs.length || title?.game) {
+            const file = join(dir, 'fidelity', 'ui.md');
+            await writeFile(file, uiPrompt(pairs, doc ? rulesOf(doc.text) : '', playFacts(latestRound(root)), join(dir, 'fidelity', 'ui.json'), title, dressing));
+            prompts.push(file);
+        }
+    }
+    return { prompts, record };
+}
+function latestRound(root) {
+    const base = join(root, PLAY_DIR);
+    if (!existsSync(base))
+        return null;
+    const n = readdirSync(base).map((d) => /^round-(\d+)$/.exec(d)?.[1]).filter(Boolean).map(Number).sort((a, b) => b - a)
+        .find((r) => existsSync(join(base, `round-${r}`, 'report.json')));
+    try {
+        return n === undefined ? null : JSON.parse(readFileSync(join(base, `round-${n}`, 'report.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export const readRecord = (dir) => { try {
+    return JSON.parse(readFileSync(join(dir, 'experience', 'depth.json'), 'utf8'));
+}
+catch {
+    return null;
+} };

package/dist/playtest/experience.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { DIMENSION_NAME, DIMENSIONS } from "../depth/experience.js";
+const PANEL = new URL('../../panel/', import.meta.url);
+const text = (f) => readFileSync(new URL(f, PANEL), 'utf8');
+export const EXPERIENCE_PERSONAS = JSON.parse(text('experience-personas.json'));
+export const EXPERIENCE_SEATS = ['designer', 'storyteller'];
+export const QUICK_EXPERIENCE_SEATS = ['designer'];
+export const DESIGN_MAX_CHARS = 12_000;
+export const EXPERIENCE_FACTS_HEADING = 'Experience facts (free instruments on this build; read them first and cite by id):';
+const stem = (f) => basename(f, extname(f));
+function evidenceText(e) {
+    const parts = [`${EXPERIENCE_FACTS_HEADING}\n\n${e.facts || '- none measured'}`];
+    if (e.textFile)
+        parts.push(`**What a player can read** (every sentence in the game's source, in source order): open ${e.textFile}`);
+    if (e.beatsFile)
+        parts.push(`**The beat strip** (the longest real session, on game time: screens, places, firsts, payoffs, endings): open ${e.beatsFile}${e.strip ? `; the frames at those beats, 4 across in time order: ${e.strip}` : ''}`);
+    if (e.frames.length)
+        parts.push(`**Frames** (open each by its full path; the name reads \`<view>-<viewport>\`):\n${e.frames.map((f) => `- ${stem(f.name)}: ${f.path}`).join('\n')}`);
+    if (e.design) {
+        const cut = e.design.text.length > DESIGN_MAX_CHARS ? `${e.design.text.slice(0, DESIGN_MAX_CHARS)}\n\n[… the rest of ${e.design.file} was cut]` : e.design.text;
+        parts.push(`**The design document** (${e.design.file}; the maker's intentions — credit only what the evidence above shows):\n\n~~~markdown\n${cut}\n~~~`);
+    }
+    else
+        parts.push('**The design document**: none.');
+    return parts.join('\n\n');
+}
+const fileNote = (answer) => `\n\n## Filing\n\nWrite your JSON answer, and nothing else, to this file with your file-writing tool:\n${answer}\nThen reply with one line: \`filed\`. You read nothing but the files named above: no source, no other seat's answer.\n`;
+export function experiencePrompt(persona, premise, evidence, answer) {
+    return text('experience.md')
+        .replaceAll('{{PREMISE}}', premise)
+        .replaceAll('{{EVIDENCE}}', evidenceText(evidence))
+        .replaceAll('{{PERSONA}}', persona)
+        .replaceAll('{{PERSONA_TEXT}}', EXPERIENCE_PERSONAS[persona]) + fileNote(answer);
+}
+const jsonIn = (raw) => JSON.parse(raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1));
+export function readExperience(file) {
+    if (!existsSync(file))
+        return { problem: 'not filed' };
+    let v;
+    try {
+        v = jsonIn(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { problem: 'no JSON in the answer' };
+    }
+    const scores = {};
+    for (const d of DIMENSIONS) {
+        const s = v?.scores?.[d];
+        if (s === null || s === undefined)
+            scores[d] = null;
+        else if (typeof s === 'number' && s >= 0 && s <= 10)
+            scores[d] = s;
+        else
+            return { problem: `${d} is not a score from 0 to 10 (or null)` };
+    }
+    if (DIMENSIONS.every((d) => scores[d] === null))
+        return { problem: 'no dimension scored' };
+    return { verdict: { ...v, critic: stem(file), scores } };
+}
+const mean = (xs) => (xs.length ? Math.round((xs.reduce((a, b) => a + b, 0) / xs.length) * 100) / 100 : null);
+export function experienceMeans(verdicts) {
+    return Object.fromEntries(DIMENSIONS.map((d) => [d, mean(verdicts.map((v) => v.scores[d]).filter((x) => typeof x === 'number'))]));
+}
+export function dimensionOf(t) {
+    const s = t.toLowerCase();
+    for (const d of DIMENSIONS)
+        if (s.includes(`(${d})`) || s.includes(`${d}:`) || s.includes(DIMENSION_NAME[d]))
+            return d;
+    const table = [
+        ['story', /story|want|payoff|character|dialog|narrat|ending/], ['world', /world|place|region|landmark|biome|area/],
+        ['replay', /replay|come back|daily|seed|unlock|leaderboard|mode/], ['arc', /arc|pacing|tension|release|climax|rest|finale/],
+        ['content', /content|level|stage|enem|debut|roster|variety/], ['depth', /depth|mastery|skill|ceiling|combo|risk/],
+        ['originality', /original|signature|twist|distinct/],
+    ];
+    return table.find(([, re]) => re.test(s))?.[0] ?? 'depth';
+}

package/dist/playtest/facts.js

@@ -0,0 +1,90 @@
+export const FACTS_MAX_CHARS = 4000;
+const pct = (x) => `${Math.round(Number(x ?? 0) * 100)}%`;
+export function factsOf(m) {
+    const out = [];
+    if (m.verify) {
+        const g = m.verify.gates;
+        const counts = g ? `${g.passed} of ${g.total} checks passed` : 'checks not counted';
+        out.push({ instrument: 'verify (desktop, the game played by its hooks)', text: `${m.verify.verdict}: ${counts}${m.verify.failing.length ? `; failing: ${m.verify.failing.slice(0, 3).join('; ')}` : ''}` });
+    }
+    else
+        out.push({ instrument: 'verify', text: 'did not run (the build failed or was skipped): nothing about the mechanics is measured' });
+    if (m.verify?.renderer)
+        out.push({ instrument: 'renderer (WEBGL_debug_renderer_info, this machine\'s headless Chromium)', text: m.verify.timing_void ? `${m.verify.renderer} — every time and the pace of motion are NOT OBSERVED (void): judge what is drawn, never how smoothly it moves` : m.verify.renderer });
+    if (m.audit) {
+        if (!m.audit.failing.length)
+            out.push({ instrument: 'audit-screens (phone, every declared view)', text: `${m.audit.verdict}: no text under 12 px, hit area under 44 px, overlap, clipping or piece in the safe area found` });
+        for (const a of m.audit.failing.slice(0, 4))
+            out.push({ instrument: `audit-screens (phone, \`${a.view}\`)`, text: a.detail });
+    }
+    if (!m.hud)
+        out.push({ instrument: 'look --hud', text: 'did not run: the HUD in play is not measured' });
+    for (const v of m.hud?.views ?? []) {
+        const n = v.numbers;
+        const worst = v.findings.filter((f) => f.severity === 'fail').slice(0, 2).map((f) => f.what).join('; ');
+        out.push({
+            instrument: `look --hud (phone, \`${v.view}\` sampled in play)`,
+            text: v.verdict === 'not_observed' ? 'no HUD found to measure'
+                : `up to ${pct(n.cover_max)} of the play area covered, smallest text ${n.smallest_text_px ?? '—'} px, lowest text contrast ${n.worst_contrast ?? '—'}:1, up to ${n.transient_max ?? 0} transient pieces at once${worst ? `; ${worst}` : ''}`,
+        });
+    }
+    for (const v of m.hud?.views ?? []) {
+        const p = v.phone;
+        if (!p)
+            continue;
+        const page = p.measured_at ? `${p.measured_at.w}x${p.measured_at.h}` : 'phone';
+        out.push({
+            instrument: `look --hud (phone, \`${v.view}\`: the play on the page Safari leaves, ${page}; a swipe tried on the play)`,
+            text: `play_area_share ${p.play_area_share == null ? 'not measured' : pct(p.play_area_share)}, play_fill ${p.play_fill == null ? 'not measured' : pct(p.play_fill)} of the largest box of its shape that fits (from the ${p.board_source ?? '—'}); `
+                + (p.pad_keys.length ? `a direction pad (${p.pad_keys.join(' ')}) claims ${pct(p.pad_band_share)} of the height; controls_duplicate_gesture ${p.controls_duplicate_gesture === null ? 'not observed' : p.controls_duplicate_gesture} (${p.swipe.claimed_by_play ? 'the play claims those keys' : p.swipe.note})` : 'no on-screen direction pad'),
+        });
+    }
+    if (m.read) {
+        out.push({
+            instrument: `look --read (${m.read.viewport}, \`${m.read.view ?? 'as loaded'}\`, ΔE of each actor to the ground around it; the bar games all read at ${m.read.min_delta_e} or more)`,
+            text: m.read.roles.length
+                ? m.read.roles.map((r) => `${r.role} ΔE ${r.delta_e}${r.pass ? '' : ` (under ${m.read.min_delta_e}; weakest ${r.weakest ?? ''})`}${r.height_px ? `, ${r.height_px} px tall` : ''}${r.found ? `, found ${r.found}` : ''}`).join('; ')
+                : m.read.hidden ? 'no player or threat in view to measure' : 'no player or threat found to measure',
+        });
+        if (m.read.hidden)
+            out[out.length - 1].text += `; ${m.read.hidden} actor(s) hidden from the camera (behind walls or doors), not measured`;
+    }
+    if (m.read === null)
+        out.push({ instrument: 'look --read', text: 'did not run: how the actors stand out from the ground is not measured' });
+    if (m.madeOf)
+        out.push({ instrument: 'look --3d (the source the game runs and its shipped models; heroes = player, rivals, enemies, vehicles by file and node name)', text: m.madeOf.says });
+    const sim = (m.sim ?? []).filter((f) => f.state === 'warn' || f.state === 'note');
+    if (sim.length)
+        for (const f of sim.slice(0, 4))
+            out.push({ instrument: `sim (bots on the rules over seeds, ${f.state})`, text: f.says });
+    const AREAS = [['verb', 'the verb against the design'], ['telegraph', 'tell to strike, the defensive verb'], ['death', 'death beat and restart'], ['animation', 'looks by state']];
+    for (const [area, what] of m.feel ? AREAS : []) {
+        const fs = m.feel.findings.filter((f) => f.area === area);
+        if (!fs.length)
+            continue;
+        const order = { note: 0, ok: 1, 'not measured': 2 };
+        const text = [...fs].sort((a, b) => order[a.state] - order[b.state]).map((f) => (f.state === 'note' ? `GAP ${f.says}` : f.state === 'not measured' ? `not measured: ${f.says}` : f.says)).join('; ');
+        out.push({ instrument: `feel (${what}; a scripted run through the real controls, __FPX_STATE__ traced every frame)`, text: text.length > 420 ? `${text.slice(0, 417)}…` : text });
+    }
+    if (m.feel === null)
+        out.push({ instrument: 'feel', text: 'did not run (no test/feel.json): the verb\'s numbers, tells, the death beat and looks by state are not measured' });
+    for (const p of (m.profile ?? []).slice(0, 3)) {
+        out.push({ instrument: `profile (\`${p.view}\`, phone viewport on this machine, not a phone)`, text: p.timing_void
+                ? `frame time NOT OBSERVED: ${p.timing_void.split(' (')[0]} (software GL) — how fast the game runs is unknown, not slow`
+                : `frame time p95 ${p.frame_ms_p95 ?? '—'} ms, ${p.fps ?? '—'} fps, ${p.long_frames ?? '—'} long frames` });
+    }
+    return out.map((f, i) => ({ id: `F${i + 1}`, ...f }));
+}
+export function factsText(facts) {
+    const lines = facts.map((f) => `- ${f.id} · ${f.instrument}: ${f.text}`);
+    let text = lines.join('\n');
+    while (text.length > FACTS_MAX_CHARS && lines.length > 1) {
+        lines.pop();
+        text = `${lines.join('\n')}\n- (more facts cut to fit)`;
+    }
+    return text.slice(0, FACTS_MAX_CHARS);
+}
+export function citations(verdict) {
+    const text = JSON.stringify(verdict ?? '');
+    return [...new Set([...text.matchAll(/\bF(\d{1,2})\b/g)].map((m) => `F${m[1]}`))];
+}

package/dist/playtest/fidelity.js

@@ -0,0 +1,179 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { clockLabel, norm, timeOf } from "./route.js";
+import { isVision } from "../gdd/doc.js";
+const PANEL = new URL('../../panel/', import.meta.url);
+const HEADING = /^\s{0,3}(#{1,4})\s+(.+?)\s*#*\s*$/;
+const cells = (row) => row.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+export function sections(text) {
+    const lines = text.replace(/\r/g, '').split('\n');
+    const heads = lines.flatMap((l, at) => { const m = HEADING.exec(l); return m ? [{ at, level: m[1].length, title: m[2] }] : []; });
+    return heads.map((h, i) => {
+        const end = heads.slice(i + 1).find((n) => n.level <= h.level)?.at ?? lines.length;
+        return { title: h.title, level: h.level, body: lines.slice(h.at + 1, end).join('\n').trim() };
+    });
+}
+const cap = (t, n) => (t.length > n ? `${t.slice(0, n)}\n[… cut]` : t);
+export function directionOf(gdd) {
+    const labels = gdd.split('\n').filter((l) => /^\s*\*\*(pitch|the 6-second ad|premise|promise)[^*]*:\*\*/i.test(l)).map((l) => l.trim());
+    const secs = sections(gdd).filter((s) => /pitch|promise|thesis|6-second|six-second|premise|fantasy|signature|^the game$/i.test(s.title) && !isVision(s.title) && s.body);
+    const vision = sections(gdd).find((s) => s.level === 2 && isVision(s.title) && s.body);
+    const text = [...labels, ...secs.map((s) => `### ${s.title}\n\n${s.body}`)].join('\n\n');
+    const grow = vision ? `\n\n### The vision (where the game grows; it is not owed yet: a step toward it may be a fix, its absence is no miss)\n\n${cap(vision.body, 1200)}` : '';
+    return `${cap(text, 4000 - grow.length)}${grow}`.trim();
+}
+export function styleOf(gdd, artStyle) {
+    const s = sections(gdd).find((x) => /^(the )?look\b|art direction|art style|art bible/i.test(x.title) && x.body);
+    const first = s?.body.split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^\s*(\||\d+\.|[-*] )/.test(p));
+    return cap(first ?? (artStyle ? `Art: ${artStyle}` : ''), 800);
+}
+export function rulesOf(gdd) {
+    const secs = sections(gdd);
+    const numbered = (b) => /AD-?\d/.test(b) || (b.match(/^\s*\d+\.\s/gm) ?? []).length >= 3;
+    const s = secs.find((x) => /\bAD rules\b|art rules/i.test(x.title) && x.body) ?? secs.find((x) => /art direction|\bart\b|\blook\b/i.test(x.title) && numbered(x.body));
+    return s ? cap(s.body, 4000) : '';
+}
+export function targetsOf(gdd) {
+    const lines = gdd.replace(/\r/g, '').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (!/^\s*\|.*\|\s*$/.test(lines[i]) || !/^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1] ?? ''))
+            continue;
+        const head = cells(lines[i]).map((c) => c.toLowerCase());
+        const col = (re) => head.findIndex((c) => re.test(c));
+        const target = col(/target/), intent = col(/intent|carr(y|ies)|must show/), moment = col(/moment|when|beat/);
+        if (target < 0 || (intent < 0 && moment < 0))
+            continue;
+        const game = col(/game|view|capture|journey|shot/), pins = col(/pins?|rules?/);
+        const rows = [];
+        for (let j = i + 1; j < lines.length && /^\s*\|.*\|\s*$/.test(lines[j]); j++) {
+            if (/^\s*\|[\s:|-]+\|\s*$/.test(lines[j]) || /<[^<>]{2,}>|…/.test(lines[j]))
+                continue;
+            const c = cells(lines[j]);
+            const at = (k) => (k >= 0 ? (c[k] ?? '').replace(/`/g, '').trim() : '');
+            rows.push({ moment: at(moment) || at(target), target: at(target), game: at(game), intent: at(intent), pins: at(pins) });
+        }
+        if (rows.length)
+            return rows;
+    }
+    return [];
+}
+function targetFile(root, cell) {
+    const m = /[\w./-]+\.(png|jpe?g|webp)/i.exec(cell);
+    if (!m)
+        return null;
+    const p = isAbsolute(m[0]) ? m[0] : join(root, m[0]);
+    return existsSync(p) ? p : null;
+}
+function gameFile(root, cell, shots, prefer) {
+    const c = cell.trim().replace(/^(?:at|route)\s+\d{1,2}:[0-5]\d\b[\s,;·+]*|^(?:at|route)\s+\d{1,4}\s?s\b[\s,;·+]*/i, '').replace(/^(?:and|or|,|·|\+)\s*/i, '');
+    const journey = /^journey\s+(\S+)\s+(\S+)/i.exec(c);
+    if (journey) {
+        const base = join(root, '.funtools', 'journeys', journey[1]);
+        const runs = existsSync(base) ? readdirSync(base).filter((d) => /^\d+$/.test(d)).map(Number).sort((a, b) => a - b) : [];
+        if (!runs.length)
+            return { file: null, why: `journey ${journey[1]} has no run (funtools journey replay ${journey[1]})` };
+        let run = null;
+        try {
+            run = JSON.parse(readFileSync(join(base, String(runs.at(-1)), 'run.json'), 'utf8'));
+        }
+        catch { }
+        const mark = run?.marks?.find((m) => m.name === journey[2]);
+        const frame = mark?.frame ? (isAbsolute(mark.frame) ? mark.frame : join(base, String(runs.at(-1)), mark.frame)) : null;
+        return frame && existsSync(frame) ? { file: frame, why: '', source: 'journey' } : { file: null, why: `journey ${journey[1]}'s latest run has no frame at mark ${journey[2]}` };
+    }
+    const view = /^(?:view\s+)?([A-Za-z][\w-]*)$/.exec(c)?.[1];
+    if (view) {
+        const shot = shots.filter((s) => s.ok && s.view === view).sort((a, b) => (a.viewport === prefer ? -1 : 0) - (b.viewport === prefer ? -1 : 0))[0];
+        return shot ? { file: shot.file, why: '', view: shot.view, viewport: shot.viewport, source: 'view' } : { file: null, why: `view ${view} was not captured (declare it in __FPX_VIEWS__)` };
+    }
+    const f = targetFile(root, c);
+    return f ? { file: f, why: '', source: 'file' } : { file: null, why: c ? `no game frame found for "${c.slice(0, 60)}"` : 'no game frame named (a view, a journey mark or a file)' };
+}
+export function pairsOf(root, gdd, shots, orientation, film = null) {
+    const prefer = orientation === 'portrait' ? 'phone' : 'desktop';
+    const rows = targetsOf(gdd);
+    const pairs = [], unpaired = [];
+    if (!rows.length) {
+        const t = join(root, 'design', 'target.png');
+        const play = shots.filter((s) => s.ok && /^play(ing)?$/.test(s.view)).sort((a, b) => (a.viewport === prefer ? -1 : 0) - (b.viewport === prefer ? -1 : 0))[0];
+        if (existsSync(t) && play)
+            pairs.push({ moment: 'the play view', intent: 'the look the design pinned in design/target.png', pins: '', target: t, game: play.file, view: play.view, viewport: play.viewport });
+        else
+            unpaired.push({ moment: 'target frames', why: existsSync(t) ? 'no play view was captured' : 'the design has no target-frames table and no design/target.png' });
+        return { pairs, unpaired, source: 'design/target.png' };
+    }
+    for (const r of rows) {
+        const target = targetFile(root, r.target);
+        if (!target) {
+            unpaired.push({ moment: r.moment, why: `target frame not found (${r.target || 'no path'})` });
+            continue;
+        }
+        const at = timeOf(r.game) ?? timeOf(r.moment, true);
+        const played = at !== null ? film?.moments.find((m) => m.ms === at) : undefined;
+        const g = /^\s*(at|route)\s+[\d:]+s?\s*$/i.test(r.game) ? { file: null, why: '' } : gameFile(root, r.game, shots, prefer);
+        const staged = g.file && g.source !== 'journey' ? { frame: g.file, ...(g.view ? { view: g.view } : {}), ...reachOf(g, film) } : undefined;
+        const base = { moment: r.moment, intent: r.intent, pins: r.pins, target, ...(at !== null ? { at: clockLabel(at) } : {}) };
+        if (played?.frame) {
+            pairs.push({ ...base, game: played.frame, source: 'route', ...(staged ? { staged } : {}) });
+            continue;
+        }
+        const unplayed = at !== null && film ? played?.why || `the route has no frame at ${clockLabel(at)}` : undefined;
+        if (g.file) {
+            pairs.push({ ...base, game: g.file, source: g.source, ...(g.view ? { view: g.view, viewport: g.viewport } : {}), ...(staged ? { staged } : {}), ...(unplayed ? { unplayed } : {}) });
+            continue;
+        }
+        const why = at === null || (!film && g.why) ? g.why : !film ? `pinned to ${clockLabel(at)} on the route, and no route is filmed yet (the first playtest records one from its blind round)` : played?.why || `the route has no frame at ${clockLabel(at)}`;
+        unpaired.push({ moment: r.moment, why });
+    }
+    return { pairs, unpaired, source: film ? `the target-frames table, timed moments from the route (run ${film.run})` : 'the target-frames table' };
+}
+function reachOf(g, film) {
+    if (!film)
+        return { reached: null, why: 'no route filmed: not observed whether play reaches it' };
+    if (g.source === 'file')
+        return { reached: false, why: 'a file (a lane or showcase frame), not a frame of play' };
+    const hit = g.view ? film.reached.find((x) => norm(x) === norm(g.view)) : undefined;
+    return hit ? { reached: true, why: `the route reached ${hit}` } : { reached: false, why: `the played route never reached view ${g.view} (no moment, screen or beat by that name in ${film.total_ms ? clockLabel(film.total_ms) : 'its run'})` };
+}
+function pairLine(p, stripMs) {
+    const where = p.source === 'route' ? ` (PLAYED: the saved route at ${p.at})` : p.staged?.reached === false ? ` (STAGED: ${p.staged.why})` : p.source === 'view' ? ` (a staged view${p.staged?.reached ? ', reached in play' : ''}${p.unplayed ? `; ${p.unplayed}` : ''})` : '';
+    return `- ${p.moment}: TARGET ${p.target} · GAME ${p.game}${where}${p.strip ? ` · STRIP ${p.strip} (12 consecutive frames${stripMs ? `, ${stripMs} ms apart` : ''}, left to right, top to bottom)` : ''}`;
+}
+function priorText(p) {
+    if (!p)
+        return '';
+    const misses = p.moments.flatMap((m) => (m.misses ?? []).slice(0, 2).map((x) => `- ${m.moment}: ${x}`)).slice(0, 12);
+    const broken = Object.entries(p.rules ?? {}).filter(([, v]) => /broken|partly/i.test(String(v))).map(([k, v]) => `${k} ${v}`);
+    return ['## The last round (read last)', '', `It gave art direction ${p.artDirection} and creative direction ${p.creativeDirection}${broken.length ? `, rules ${broken.join(', ')}` : ''}. Its findings:`, '', ...misses, '',
+        'For each finding, say in `prior` whether it is fixed, unchanged or worse in these frames. Move a score only where the frames changed; a score whose evidence did not change stays where it was.'].join('\n');
+}
+export function fidelityPrompt(gdd, pairs, answer, extras = {}) {
+    const rules = rulesOf(gdd);
+    const targets = pairs.map((p) => `- **${p.moment}**${p.pins ? ` (pins ${p.pins})` : ''}: ${p.intent || 'no intent written'}`).join('\n');
+    const list = pairs.map((p) => pairLine(p, extras.stripMs)).join('\n');
+    return readFileSync(new URL('fidelity.md', PANEL), 'utf8')
+        .replaceAll('{{DIRECTION}}', directionOf(gdd) || 'The document states no pitch or thesis: judge creative direction from each moment\'s intent alone.')
+        .replaceAll('{{STYLE}}', styleOf(gdd, extras.artStyle) || 'The document declares no style in words: take the target frames\' medium as the declared style.')
+        .replaceAll('{{RULES}}', rules || 'The document states no AD rules: judge art against the target frames alone and give an empty rules map.')
+        .replaceAll('{{TARGETS}}', targets)
+        .replaceAll('{{FACTS}}', extras.facts?.trim() || 'None measured for this round.')
+        .replaceAll('{{PAIRS}}', list)
+        .replaceAll('{{PRIOR}}', priorText(extras.prior)) +
+        `\n\n## Filing\n\nWrite your JSON answer, and nothing else, to this file with your file-writing tool:\n${answer}\nThen reply with one line: \`filed\`. You read nothing but the images named above.\n`;
+}
+export function readFidelity(file) {
+    if (!existsSync(file))
+        return { problem: 'not filed' };
+    let v;
+    try {
+        const raw = readFileSync(file, 'utf8');
+        v = JSON.parse(raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1));
+    }
+    catch {
+        return { problem: 'no JSON in the answer' };
+    }
+    for (const k of ['artDirection', 'creativeDirection'])
+        if (typeof v?.[k] !== 'number' || v[k] < 0 || v[k] > 10)
+            return { problem: `no ${k} score from 0 to 10` };
+    return { verdict: { moments: Array.isArray(v.moments) ? v.moments : [], artDirection: v.artDirection, creativeDirection: v.creativeDirection, rules: v.rules && typeof v.rules === 'object' ? v.rules : {}, ...(Array.isArray(v.prior) ? { prior: v.prior } : {}), fixFirst: v.fixFirst, verdict: v.verdict } };
+}