@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/playtest/mockups.js

@@ -0,0 +1,198 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { sections } from "./fidelity.js";
+import { BIBLE_FILE, readBible } from "../greenlight/bible.js";
+import { clockLabel, timeOf } from "./route.js";
+const PANEL = new URL('../../panel/', import.meta.url);
+const SKIP = new Set(['node_modules', 'dist', '.funtools', 'raw', 'history']);
+export function mockupPages(root) {
+    const out = [];
+    const walk = (dir, depth) => {
+        let names = [];
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = join(dir, n);
+            if (SKIP.has(n) || n.startsWith('.'))
+                continue;
+            let st;
+            try {
+                st = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory() && depth < 3)
+                walk(p, depth + 1);
+            else if (/\.html?$/i.test(n) && !(n === 'index.html' && /first-look$/.test(dir))) {
+                if (/class="[^"]*\bphone\b|data-mockup/.test(readFileSync(p, 'utf8')))
+                    out.push(p);
+            }
+        }
+    };
+    walk(join(root, 'design'), 0);
+    return out.sort();
+}
+export function imageMockups(root, gdd) {
+    const IMAGE = /[\w./-]+\.(png|jpe?g|webp)/i;
+    const bible = readBible(root);
+    const words = bible ? sections(readFileSync(join(root, BIBLE_FILE), 'utf8')).filter((x) => /^(the )?(ui|user interface|interface)\b/i.test(x.title)).map((x) => x.body.trim()).join('\n').slice(0, 2000) : '';
+    const out = [];
+    const put = (name, path, spec, source) => {
+        if (!IMAGE.test(path) || !existsSync(join(root, path)) || out.some((m) => m.source === path))
+            return;
+        out.push({ name, file: join(root, path), source: path, spec, image: join(root, path) });
+    };
+    for (const sc of bible?.screens ?? [])
+        put(`${sc.screen} target`, sc.path, words, sc.path);
+    for (const l of gdd.split('\n')) {
+        const c = l.trim().replace(/^\||\|$/g, '').split('|').map((x) => x.trim().replace(/`/g, ''));
+        const path = c.length >= 3 ? IMAGE.exec(c[1])?.[0] : undefined;
+        if (path && /^view\s+\S+/i.test(c[2]))
+            put(c[0], path, [c.slice(3).join(' '), words].filter(Boolean).join('\n'), path);
+    }
+    return out;
+}
+export async function renderMockups(root, pages, out) {
+    if (!pages.length)
+        return [];
+    await mkdir(out, { recursive: true });
+    const { launch } = await import("../verify/browser.js");
+    const { browser } = await launch();
+    const found = [];
+    try {
+        const page = await (await browser.newContext({ viewport: { width: 1280, height: 900 }, deviceScaleFactor: 1 })).newPage();
+        for (const file of pages) {
+            await page.goto(pathToFileURL(file).href, { waitUntil: 'load', timeout: 30_000 }).catch(() => { });
+            const list = (await page.evaluate(`(() => {
+        const els = [...document.querySelectorAll('[data-mockup], .phone')].filter((e) => !e.parentElement?.closest('[data-mockup], .phone'));
+        return els.map((el, i) => {
+          el.setAttribute('data-fpx-mockup', String(i));
+          let h = el.previousElementSibling, lead = '';
+          while (h && !/^H[1-4]$/.test(h.tagName)) { if (h.tagName === 'P' && !lead) lead = h.innerText; h = h.previousElementSibling; }
+          const screen = el.querySelector('[data-screen], .scr') || el;
+          screen.setAttribute('data-fpx-screen', String(i));
+          const sel = '.legends, .legend, ol, ul, dl, figcaption';
+          const legend = [...el.querySelectorAll(sel)].filter((x) => !x.parentElement?.closest(sel) || !el.contains(x.parentElement.closest(sel)))
+            .map((x) => x.innerText.trim().replace(/^(\\d+)\\n/gm, '$1 ')).filter(Boolean);
+          const own = legend.length ? [...new Set(legend)].join('\\n') : (el.innerText || '').trim();
+          return { name: el.getAttribute('data-mockup') || (h ? h.innerText.trim() : 'mockup ' + (i + 1)), spec: [lead, own].filter(Boolean).join('\\n').slice(0, 3000) };
+        });
+      })()`));
+            for (let i = 0; i < list.length; i++) {
+                const image = join(out, `mockup-${found.length + 1}.png`);
+                const el = await page.$(`[data-fpx-screen="${i}"]`);
+                if (!el)
+                    continue;
+                await el.scrollIntoViewIfNeeded().catch(() => { });
+                await el.screenshot({ path: image }).catch(() => { });
+                if (existsSync(image))
+                    found.push({ name: list[i].name, file, source: relative(root, file).split('\\').join('/'), spec: list[i].spec, image });
+            }
+        }
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    return found;
+}
+export function pairMockups(gdd, mockups, shots, film = null) {
+    const phone = shots.filter((s) => s.ok).sort((a, b) => (a.viewport === 'phone' ? -1 : 0) - (b.viewport === 'phone' ? -1 : 0));
+    const table = new Map();
+    for (const l of gdd.split('\n')) {
+        const c = l.trim().replace(/^\||\|$/g, '').split('|').map((x) => x.trim().replace(/`/g, ''));
+        if (c.length >= 3 && /mockup|\.html|\.png/i.test(c[1]) && (/^view\s+\S+/i.test(c[2]) || timeOf(c[2]) !== null))
+            table.set(c[0].toLowerCase(), c[2].replace(/^view\s+/i, ''));
+    }
+    const pairs = [], unpaired = [];
+    for (const m of mockups) {
+        const named = [...table.entries()].find(([k]) => m.name.toLowerCase().includes(k) || k.includes(m.name.toLowerCase()))?.[1];
+        const at = named ? timeOf(named) : null;
+        if (at !== null) {
+            const f = film?.moments.find((x) => x.ms === at);
+            if (f?.frame)
+                pairs.push({ screen: m.name, spec: m.spec, plan: m.image, game: f.frame, at: clockLabel(at) });
+            else
+                unpaired.push({ screen: m.name, why: film ? f?.why || `the route has no frame at ${clockLabel(at)}` : `pinned to ${clockLabel(at)} on the route, and no route is filmed yet` });
+            continue;
+        }
+        const words = (m.name.toLowerCase().match(/[a-z]{4,}/g) ?? []).filter((w) => !/^(screen|phone|mockup|view|page|with|over|this|that|game)$/.test(w));
+        const view = named ?? (/hud|in play|playing|controls|touch/i.test(m.name) ? phone.find((s) => /^play(ing)?$/.test(s.view))?.view : undefined)
+            ?? phone.find((s) => words.some((w) => s.view.toLowerCase().includes(w)))?.view;
+        const shot = view ? phone.find((s) => s.view === view) : undefined;
+        if (shot)
+            pairs.push({ screen: m.name, spec: m.spec, plan: m.image, game: shot.file });
+        else
+            unpaired.push({ screen: m.name, why: view ? `view ${view} was not captured` : 'no view shows this screen: name one in the GDD (| Screen | Mockup | Game frame: view NAME |), opened through a view so a still does not press past it' });
+    }
+    return { pairs, unpaired };
+}
+export function playFacts(report) {
+    if (!report?.start)
+        return 'No blind phone round was filed: how the interface plays is not observed.';
+    const a = (k) => `${k[0].toUpperCase()}${k.slice(1)}: ${report[k]?.answer ?? '—'}${report[k]?.note ? ` (${report[k].note})` : ''}`;
+    return [
+        `A blind player's round on this build${report.viewport ? `, ${report.viewport}` : ''}${typeof report.steps === 'number' ? `, ${report.steps} steps` : ''}.`,
+        `- ${a('start')}`, `- ${a('goal')}`, `- ${a('act')}`, `- ${a('end')}`,
+        ...(report.confusions ?? []).slice(0, 5).map((c) => `- Confused: ${c}`),
+        ...(report.defects ?? []).slice(0, 3).map((d) => `- Defect (${d.severity}): ${d.title}${d.actual ? ` — ${d.actual}` : ''}`),
+    ].join('\n').slice(0, 2500);
+}
+export function dressingOf(style) {
+    if (!style)
+        return '';
+    const lines = Object.entries(style).flatMap(([where, st]) => st.findings.map((f) => `- ${where}: ${f.what}`));
+    return lines.length ? lines.join('\n') : `Measured on ${Object.keys(style).join(' and ')}: none of the scaffold's clothes found.`;
+}
+export function hitTitle(dir) {
+    if (!dir)
+        return null;
+    try {
+        const f = readdirSync(dir).sort().find((n) => /(title|opening|menu|start)[^/]*\.(png|jpe?g|webp)$/i.test(n));
+        return f ? join(dir, f) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function titleBlock(t) {
+    if (!t?.game)
+        return 'No title screen was captured (no view named title, menu or start): the title is not judged. Leave `title` out of your answer.';
+    return [`- GAME TITLE ${t.game}`, t.hit ? `- ${t.hitName.toUpperCase()} OPENING ${t.hit}` : `- ${t.hitName}'s opening screen is not on this machine: score ours alone and set \`title.hit\` to null.`].join('\n');
+}
+export function uiPrompt(pairs, rules, play, answer, title, dressing = '') {
+    const screens = pairs.map((p) => `### ${p.screen}\n\n${p.spec || '(no words beside this mockup)'}`).join('\n\n') || '(The plan draws no screen: judge the title below only; `screens` and `elements` stay empty and `uiFidelity` and `uxFidelity` are null.)';
+    const list = pairs.map((p) => `- ${p.screen}: PLAN ${p.plan} · GAME ${p.game}`).join('\n') || '(none)';
+    return readFileSync(new URL('fidelity-ui.md', PANEL), 'utf8')
+        .replaceAll('{{SCREENS}}', screens).replaceAll('{{RULES}}', rules || 'The document states no interface rules beyond the screens\' own words.')
+        .replaceAll('{{PAIRS}}', list).replaceAll('{{PLAY}}', play).replaceAll('{{TITLE}}', titleBlock(title))
+        .replaceAll('{{DRESSING}}', dressing || 'Not measured.') +
+        `\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 readUiFidelity(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' };
+    }
+    const score = (x) => (x && ['look', 'readability', 'wantToPlay'].every((k) => typeof x[k] === 'number' && x[k] >= 0 && x[k] <= 10) ? { look: x.look, readability: x.readability, wantToPlay: x.wantToPlay } : null);
+    const own = score(v.title);
+    const title = own ? { ...own, hit: score(v.title.hit), ...(typeof v.title.why === 'string' ? { why: v.title.why } : {}) } : undefined;
+    const titleOnly = !!title && v?.uiFidelity == null && v?.uxFidelity == null;
+    if (!titleOnly)
+        for (const k of ['uiFidelity', 'uxFidelity'])
+            if (typeof v?.[k] !== 'number' || v[k] < 0 || v[k] > 10)
+                return { problem: `no ${k} score from 0 to 10` };
+    return { verdict: { screens: v.screens ?? [], elements: Array.isArray(v.elements) ? v.elements : [], additions: Array.isArray(v.additions) ? v.additions : [], uiFidelity: titleOnly ? null : v.uiFidelity, uxFidelity: titleOnly ? null : v.uxFidelity, fixFirst: v.fixFirst, verdict: v.verdict, ...(title ? { title } : {}) } };
+}

package/dist/playtest/moments.js

@@ -0,0 +1,28 @@
+import { norm } from "./route.js";
+export function momentScores(moments, fid, ui, uiPairs) {
+    return moments.map((m, i) => {
+        const v = fid?.moments.find((x) => norm(String(x.moment)) === norm(m.moment)) ?? (fid?.moments.length === moments.length ? fid.moments[i] : undefined);
+        const screen = m.at ? uiPairs.find((p) => p.at === m.at)?.screen : undefined;
+        const s = screen ? ui?.screens.find((x) => norm(x.screen) === norm(screen)) : undefined;
+        return {
+            moment: m.moment, ...(m.at ? { at: m.at } : {}), ...(m.source ? { source: m.source } : {}), target: m.target, game: m.game, ...(m.staged ? { staged: m.staged } : {}), ...(m.unplayed ? { unplayed: m.unplayed } : {}),
+            art: typeof v?.art === 'number' ? v.art : null, creative: typeof v?.creative === 'number' ? v.creative : null,
+            ui: typeof s?.ui === 'number' ? s.ui : null, ux: typeof s?.ux === 'number' ? s.ux : null, misses: (v?.misses ?? []).slice(0, 3),
+        };
+    });
+}
+export function momentsMd(ms) {
+    if (!ms.length)
+        return [];
+    const out = ['### Target beside game, moment by moment', '', '| Moment | Game frame | Art / creative | UI / UX | Staged frame |', '|---|---|---|---|---|'];
+    for (const m of ms) {
+        const from = m.source === 'route' ? `played, the route at ${m.at}` : m.source === 'view' ? `a staged view${m.unplayed ? ` (${m.unplayed})` : ''}` : m.source === 'journey' ? 'a journey mark' : m.source === 'file' ? 'a file' : '—';
+        const staged = !m.staged ? '—' : m.staged.reached === false ? `**never reached in play**: ${m.staged.why}` : m.staged.reached ? `reached in play (${m.staged.why})` : 'not observed (no route)';
+        out.push(`| ${m.moment} | ${from} | ${m.art ?? '—'} / ${m.creative ?? '—'} | ${m.ui ?? '—'} / ${m.ux ?? '—'} | ${staged} |`);
+    }
+    const unreached = ms.filter((m) => m.staged?.reached === false);
+    if (unreached.length)
+        out.push('', `Staged frames the played route never reached: ${unreached.map((m) => `${m.moment} (\`${m.staged.frame}\`)`).join('; ')}. A frame that looks right only when staged is a finding (one game's diver: showcase art in its lane, "a few coral points" in play).`);
+    out.push('');
+    return out;
+}

package/dist/playtest/prepare.js

@@ -0,0 +1,162 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fingerprint } from "../verify/fingerprint.js";
+import { findHitEvidence, nearestHit, usableEvidence } from "./hits.js";
+import { compareFrames, framesFor, keepHudFrames, measure } from "./measure.js";
+import { FULL_SEATS, imagesIn, QUICK_SEATS, seatPrompt, versusPrompt } from "./seats.js";
+import { factsOf, factsText } from "./facts.js";
+import { EXPERIENCE_SEATS, QUICK_EXPERIENCE_SEATS } from "./experience.js";
+import { fidelityPrompt, pairsOf, readFidelity, rulesOf } from "./fidelity.js";
+import { filmRoute, readRoute, routeTimes } from "./route.js";
+import { dressingOf, hitTitle, imageMockups, mockupPages, pairMockups, renderMockups } from "./mockups.js";
+import { prepareMobileQa, readMobileQa, runPhone, swipesFor } from "./mobile-qa.js";
+import { designDoc } from "../gdd/doc.js";
+import { lockedPlan, withMatch } from "../greenlight/match.js";
+export async function prepareFidelity(root, dir, m, orientation, extras) {
+    const doc = designDoc(root);
+    if (!doc)
+        return { seat: null, pairs: 0, unpaired: [{ moment: 'target frames', why: 'no design document (design/GDD.md)' }], source: '', facts: [{ id: 'P1', instrument: 'fidelity', text: 'not measured: no design document, so nothing planned to hold the game against' }] };
+    const locked = lockedPlan(root, doc.text);
+    const planText = locked?.text ?? doc.text;
+    const { pairs, unpaired, source } = pairsOf(root, planText, m.capture, orientation, extras.film ?? null);
+    const rules = (rulesOf(doc.text).match(/^\s*(\|\s*)?(AD-?\d+|\d+\.)/gm) ?? []).length;
+    const facts = [{ id: 'P1', instrument: `fidelity (${doc.rel}: target frames against the game's frames of the same moments)`, text: `${pairs.length} moment(s) paired from ${locked ? `the targets locked at ${locked.lock.version} (${locked.lock.date})${locked.moved.length ? `; changed since the lock: ${locked.moved.join(', ')}` : ''}` : source}${unpaired.length ? `; not paired: ${unpaired.map((u) => `${u.moment} (${u.why})`).join('; ')}` : ''}; ${rules} AD rule(s) stated` }];
+    const played = pairs.filter((p) => p.source === 'route').length, unreached = pairs.filter((p) => p.staged?.reached === false);
+    if (extras.film)
+        facts.push({ id: 'P2', instrument: `the saved route (test/journeys/playtest-route.json, run ${extras.film.run}, ${extras.film.viewport} ${extras.film.size}, seed ${extras.film.seed})`, text: `${played} moment(s) shot in play on the same route as every round${unreached.length ? `; staged frames the played route never reached: ${unreached.map((p) => `${p.moment} (${p.staged.view ?? 'a file'})`).join(', ')}` : ''}${extras.film.void ? `; VOID: ${extras.film.void}` : ''}` });
+    if (!pairs.length)
+        return { seat: null, pairs: 0, unpaired, source, facts };
+    for (const p of pairs) {
+        const strip = p.view && p.viewport ? join(dir, 'frames', `clip-${p.view}-${p.viewport}.png`) : '';
+        if (strip && existsSync(strip))
+            p.strip = strip;
+    }
+    const prior = extras.previous ? readFidelity(join(extras.previous, 'fidelity', 'fidelity.json')).verdict ?? null : null;
+    const factLines = [extras.facts, ...facts.map((f) => `- ${f.id} · ${f.instrument}: ${f.text}`)].filter(Boolean).join('\n');
+    await mkdir(join(dir, 'fidelity'), { recursive: true });
+    await writeFile(join(dir, 'fidelity', 'fidelity.md'), withMatch(fidelityPrompt(planText, pairs, join(dir, 'fidelity', 'fidelity.json'), { facts: factLines, prior, artStyle: extras.artStyle, stripMs: 33 }), locked));
+    await writeFile(join(dir, 'fidelity', 'pairs.json'), JSON.stringify(pairs, null, 2) + '\n');
+    const moments = pairs.map(({ moment, at, source: from, staged, unplayed, game, target }) => ({ moment, at, source: from, staged, unplayed, game, target }));
+    return { seat: join(dir, 'fidelity', 'fidelity.md'), pairs: pairs.length, unpaired, source, facts, moments };
+}
+export async function film(root, dir, note) {
+    const r = readRoute(root);
+    if (typeof r === 'string')
+        return { film: null, route: { filmed: false, why: r } };
+    const times = routeTimes(designDoc(root)?.text ?? '');
+    note(`filming the saved route (${r.journey.steps.length} steps, ${r.journey.viewport}${r.journey.orientation ? ` ${r.journey.orientation}` : ''}, seed ${r.journey.seed})${times.length ? ` with ${times.length} timed moment(s)` : ''}`);
+    const f = await filmRoute(root, dir, times).catch((e) => `the route could not be replayed: ${e.message}`);
+    if (typeof f === 'string')
+        return { film: null, route: { filmed: false, why: f } };
+    return { film: f, route: { filmed: true, why: f.why, script: f.script, run: f.run, moments: f.moments.map(({ moment, frame, why }) => ({ moment, frame, why })), void: f.void } };
+}
+export const PLAYTEST_DIR = join('.funtools', 'playtest');
+export const PREMISE_FILE = join(PLAYTEST_DIR, 'premise.txt');
+export function playtests(root) {
+    const dir = join(root, PLAYTEST_DIR);
+    return existsSync(dir) ? readdirSync(dir).filter((d) => /^\d+$/.test(d)).map(Number).sort((a, b) => a - b) : [];
+}
+export function premiseOf(root, manifest) {
+    const file = join(root, PREMISE_FILE);
+    if (existsSync(file)) {
+        const text = readFileSync(file, 'utf8').trim();
+        if (text.split(/[.!?](\s|$)/).filter((s) => s.trim()).length >= 2)
+            return { text, draft: false };
+    }
+    const m = manifest.metadata ?? {};
+    const bits = [`${manifest.name ?? 'This game'} is a ${m.dimension ?? ''} ${m.genre ?? ''} browser game${m.orientation ? ` played ${m.orientation} on phones` : ''}.`.replace(/\s+/g, ' '), m.tagline, m.artStyle ? `Art: ${m.artStyle}.` : ''];
+    return { text: bits.filter(Boolean).join(' ').trim(), draft: true };
+}
+export const playerBrief = (premise, orientation, long = 0) => `# Blind player round
+
+Play this game ${long ? `for a long session of about ${long} minutes of game time` : 'once'}, blind, as a first-time player, at phone size${orientation === 'landscape' ? ' held sideways (landscape)' : ''}.
+Open the round with \`npx @funpixel/tools play . --viewport phone${long ? ` --long ${long}` : ''}\` in the game folder, play through it with
+\`play act\`, note what you see with \`play note\`, and file the report with \`play report\`
+(the \`player\` agent's procedure). You know the game only from this store description and its screens:
+
+${premise}
+
+Judge start, goal, act and end, each criterion \`play\` prints, and the three worst defects with the
+step whose screenshot shows each. ${long ? `Keep playing past the first win or loss (go again, go on, explore) until each act says about ${long} minutes of game time are played, and note what changes and what stays the same. ` : ''}End the report with \`come_back\`: would you come back tomorrow (yes, maybe or no), why, and the first thing you would do. Never read the game's files.
+`;
+export const LONG_MINUTES = 10;
+export async function prepare(root, manifest, opts) {
+    const n = (playtests(root).at(-1) ?? 0) + 1;
+    const dir = join(root, PLAYTEST_DIR, String(n));
+    await mkdir(join(dir, 'seats'), { recursive: true });
+    const measures = await measure(root, { quick: opts.quick, build: opts.build, note: opts.note });
+    const frames = await framesFor(root, join(dir, 'frames'), measures.capture);
+    await keepHudFrames(measures, dir);
+    const previous = playtests(root).filter((x) => x < n).at(-1);
+    measures.compare = previous ? await compareFrames(join(root, PLAYTEST_DIR, String(previous), 'frames'), join(dir, 'frames'), join(dir, 'compare'), frames) : [];
+    await writeFile(join(dir, 'measures.json'), JSON.stringify(measures, null, 2) + '\n');
+    const premise = premiseOf(root, manifest);
+    const facts = factsOf(measures);
+    const summary = factsText(facts);
+    await writeFile(join(dir, 'facts.json'), JSON.stringify(facts, null, 2) + '\n');
+    if (summary)
+        await writeFile(join(dir, 'frames', 'facts.md'), summary + '\n');
+    const seats = [...(opts.quick ? QUICK_SEATS : FULL_SEATS)];
+    const framesDir = join(dir, 'frames');
+    for (const s of seats)
+        await writeFile(join(dir, 'seats', `${s}.md`), seatPrompt(s, premise.text, framesDir, frames, summary, join(dir, 'seats', `${s}.json`)));
+    const hit = nearestHit(manifest.metadata?.genre, manifest.metadata?.dimension);
+    const versus = { ran: false, note: '', calls: [] };
+    const given = opts.versus && opts.versus !== 'none' && opts.versus !== 'auto' ? resolve(opts.versus) : null;
+    const hitDir = opts.versus === 'none' ? null : given ?? findHitEvidence(hit.slug);
+    if (opts.quick)
+        versus.note = 'skipped: --quick runs no head to head';
+    else if (opts.versus === 'none')
+        versus.note = 'skipped: --versus none';
+    else if (given && !usableEvidence(given))
+        versus.note = `skipped: ${given} has no premise.txt and three captures`;
+    else if (!hitDir)
+        versus.note = `skipped: no ${hit.name} evidence on this machine. The hits' store media never ship with the kit; point --versus (or FUNPIXEL_HITS_DIR/${hit.slug}/) at a folder with premise.txt and captures to run it`;
+    else {
+        await mkdir(join(dir, 'versus'), { recursive: true });
+        const theirs = { premise: readFileSync(join(hitDir, 'premise.txt'), 'utf8').trim(), dir: hitDir, files: imagesIn(hitDir) };
+        const mine = { premise: premise.text, dir: framesDir, files: frames };
+        for (const s of FULL_SEATS)
+            for (const order of ['candidate-first', 'hit-first']) {
+                const name = `${s}-${order}`;
+                await writeFile(join(dir, 'versus', `${name}.md`), versusPrompt(s, order, mine, theirs, join(dir, 'versus', `${name}.json`)));
+                versus.calls.push(name);
+            }
+        Object.assign(versus, { ran: true, dir: hitDir, note: `against ${given ? hitDir : hit.name}, ${versus.calls.length} calls` });
+    }
+    const orientation = typeof manifest.metadata?.orientation === 'string' ? manifest.metadata.orientation : 'portrait';
+    const route = measures.build.ok ? await film(root, dir, opts.note) : { film: null, route: { filmed: false, why: 'the build failed' } };
+    const fidelity = await prepareFidelity(root, dir, measures, orientation, {
+        facts: summary, artStyle: typeof manifest.metadata?.artStyle === 'string' ? manifest.metadata.artStyle : undefined,
+        previous: previous ? join(root, PLAYTEST_DIR, String(previous)) : undefined, film: route.film,
+    });
+    const pages = mockupPages(root);
+    const gddText = designDoc(root)?.text ?? '';
+    const pictures = imageMockups(root, gddText);
+    const titleShot = measures.capture.filter((c) => c.ok && /^(title|menu|start)$/i.test(c.view)).sort((a, b) => (a.viewport === 'phone' ? -1 : 0) - (b.viewport === 'phone' ? -1 : 0))[0];
+    const title = { game: titleShot?.file ?? null, hit: hitTitle(hitDir), hitName: hit.name };
+    if ((pages.length || pictures.length || title.game) && measures.build.ok) {
+        const rendered = await renderMockups(root, pages, join(dir, 'fidelity', 'mockups')).catch(() => []);
+        const mocks = [...rendered, ...pictures];
+        const ui = pairMockups(gddText, mocks, measures.capture, route.film);
+        await mkdir(join(dir, 'fidelity'), { recursive: true });
+        await writeFile(join(dir, 'fidelity', 'ui-pairs.json'), JSON.stringify({ ...ui, title, dressing: dressingOf(measures.hud?.ui_style) }, null, 2) + '\n');
+        fidelity.ui = { mockups: mocks.length, pairs: ui.pairs.length, unpaired: ui.unpaired, pages: [...pages.map((p) => p.slice(root.length + 1)), ...pictures.map((p) => p.source)] };
+        opts.note(`ui fidelity: ${mocks.length} mockup(s) rendered, ${ui.pairs.length} paired with the game's screens`);
+    }
+    if (opts.phone && measures.build.ok)
+        await runPhone(root, { sim: opts.sim, note: opts.note, swipes: swipesFor(measures) });
+    const mq = measures.build.ok ? await prepareMobileQa(root, join(dir, 'mobile'), { manifest, premise: premise.text, measures, frames: { dir: framesDir, names: frames }, facts: summary, note: opts.note,
+        prior: previous ? readMobileQa(join(root, PLAYTEST_DIR, String(previous), 'mobile', 'mobile-qa.json')).verdict ?? null : null }) : null;
+    const mobile = mq ? { seat: mq.seat, target: mq.target, platforms: mq.platforms.map(({ id, observed, why }) => ({ id, observed, why })), facts: mq.facts } : undefined;
+    const long = opts.long ?? (opts.quick ? 0 : LONG_MINUTES);
+    await writeFile(join(dir, 'player.md'), playerBrief(premise.text, orientation, long));
+    const plan = {
+        n, at: new Date().toISOString(), game: manifest.name ?? 'this game', fingerprint: (await fingerprint(root)).fingerprint, quick: opts.quick,
+        seats, hit, versus, premise, frames, facts, player: { brief: join(dir, 'player.md'), viewport: 'phone', orientation, ...(long ? { long_minutes: long } : {}) },
+        experience: { seats: [...(opts.quick ? QUICK_EXPERIENCE_SEATS : EXPERIENCE_SEATS)] }, route: route.route, fidelity, ...(mobile ? { mobile } : {}),
+    };
+    await writeFile(join(dir, 'plan.json'), JSON.stringify(plan, null, 2) + '\n');
+    return { plan, dir, measures };
+}

package/dist/playtest/rank.js

@@ -0,0 +1,184 @@
+import { basename, extname, join } from 'node:path';
+import { dimensionOf } from "./experience.js";
+import { frameOf, mergedText } from "./mobile-qa.js";
+import { DIMENSION_NAME } from "../depth/experience.js";
+const STOP = new Set('that this with from they them their there which would could should about into than then what when where while more most less your have been only each every make made more over under very much also just like the and for are but not was its it\'s'.split(' '));
+export const words = (t) => new Set(t.toLowerCase().match(/[a-z]{4,}/g)?.filter((w) => !STOP.has(w)) ?? []);
+export const jaccard = (a, b) => { let n = 0; for (const w of a)
+    if (b.has(w))
+        n++; return n / Math.max(1, a.size + b.size - n); };
+export function axisOf(t) {
+    const s = t.toLowerCase().replace(/[\w-]+-(phone|desktop)[\w-]*/g, ' ');
+    const table = [
+        ['hud', /\bhud\b|banner|toast|counter|label|score (text|readout)|lives|pause button|readout/],
+        ['mobile', /phone|thumb|notch|safe.?area|portrait|landscape|mobile|tap target|touch/],
+        ['juice', /juice|impact|hitstop|flash|shake|particle|punch|feedback|squash|pop\b/],
+        ['readability', /read|contrast|tell (them )?apart|distinct|clutter|legib|silhouette|at a glance/],
+        ['intuitiveness', /teach|tutorial|onboard|first (minute|screen|wave)|understand|how to|intuit|hint/],
+        ['fun', /fun|depth|escalat|replay|variety|wave|combo|chain|score.?attack|reward|progress|upgrade|boss/],
+        ['lookAndFeel', /art|style|palette|colou?r|look|coheren|backdrop|world/],
+    ];
+    return table.find(([, re]) => re.test(s))?.[0] ?? 'overall';
+}
+function frameNamed(t, frames, dir) {
+    const hit = frames.map((f) => basename(f, extname(f))).sort((a, b) => b.length - a.length).find((stem) => t.includes(stem));
+    return hit ? join(dir, `${hit}.png`) : null;
+}
+const firstSentence = (t) => (t.match(/^[^.;]{8,}?[.;](\s|$)/)?.[0] ?? t).trim().replace(/[.;]$/, '').slice(0, 160);
+export const MOBILE_WEIGHT = { high: 140, medium: 70, low: 25 };
+export function mobileSteps(m) {
+    return m.verdict.findings.slice(0, 5).map((f, i) => ({
+        source: 'mobile', text: firstSentence(mergedText(f, m.observed)), quote: [f.finding, f.fix && `Fix: ${f.fix}`].filter(Boolean).join(' — '),
+        who: `Mobile QA seat (${f.severity}${f.area ? `, ${f.area}` : ''})`, frame: frameOf(f.evidence?.frame, m.images),
+        number: `${f.evidence?.number ? `${f.evidence.number}; ` : ''}phone-native ${m.verdict.phoneNative}/10`,
+        score: MOBILE_WEIGHT[f.severity] - i + (m.primary && f.severity !== 'low' ? 10 : 0),
+    }));
+}
+export function rank(input) {
+    const { verdicts, means, hit, player, measures: m, frames, framesDir } = input;
+    const out = [];
+    const gap = (a) => (means[a] === null ? 0 : Math.max(0, hit.panel[a] - means[a]));
+    const axisNumber = (a) => (means[a] === null ? 'not scored' : `${a} ${means[a].toFixed(2)} (${hit.name} ${hit.panel[a].toFixed(2)})`);
+    const play = join(framesDir, frames.find((f) => /^playing-phone/.test(f)) ?? frames[0] ?? '');
+    if (!m.build.ok)
+        out.push({ source: 'build', text: 'Make the build pass', quote: m.build.tail.split('\n').pop() ?? '', who: 'npm run build', frame: null, number: `build failed after ${(m.build.ms / 1000).toFixed(1)} s`, score: 300 });
+    if (m.verify?.verdict === 'fail')
+        out.push({ source: 'measure', text: `Make verify pass: ${m.verify.failing[0]?.split(':')[0] ?? 'a failing gate'}`, quote: m.verify.failing[0] ?? '', who: 'verify', frame: null, number: `${m.verify.failing.length} gate(s) failing`, score: 200 });
+    for (const d of player?.defects ?? []) {
+        out.push({
+            source: 'player', text: firstSentence(d.title), quote: d.actual || d.title, who: `blind player (${d.severity})`, frame: d.shot || null,
+            number: `step ${d.step} of the round`, score: d.severity === 'high' ? 150 : d.severity === 'medium' ? 90 : 35,
+        });
+    }
+    const clusters = [];
+    for (const v of verdicts) {
+        (v.fixFirst ?? []).slice(0, 5).forEach((t, i) => {
+            const bag = words(t);
+            const c = clusters.find((x) => jaccard(x.bag, bag) >= 0.22);
+            const item = { text: t, seat: v.critic, w: 5 - i };
+            if (c) {
+                c.items.push(item);
+                for (const w of bag)
+                    c.bag.add(w);
+            }
+            else
+                clusters.push({ items: [item], bag });
+        });
+    }
+    for (const c of clusters) {
+        const lead = [...c.items].sort((a, b) => b.w - a.w)[0];
+        const seats = [...new Set(c.items.map((i) => i.seat))];
+        const axis = axisOf(c.items.map((i) => i.text).join(' '));
+        out.push({
+            source: 'panel', text: firstSentence(lead.text), quote: lead.text, who: `${seats.join(', ')} seat${seats.length > 1 ? 's' : ''}`,
+            frame: c.items.map((i) => frameNamed(i.text, frames, framesDir)).find(Boolean) ?? null, number: axisNumber(axis),
+            score: c.items.reduce((s, i) => s + i.w * 4, 0) + 12 * seats.length + Math.round(gap(axis) * 20),
+        });
+    }
+    for (const v of m.hud?.views ?? []) {
+        for (const f of v.findings.filter((x) => x.severity === 'fail').slice(0, 2)) {
+            out.push({ source: 'measure', text: `HUD in play (${v.view}): ${f.kind.replace('_', ' ')} at ${f.where}`, quote: f.what, who: 'look --hud', frame: v.frame ?? null, number: `${f.kind} ${f.number}`, score: 50 + (/pile_up|over_player|repeats/.test(f.kind) ? 15 : 0) });
+        }
+    }
+    for (const v of m.hud?.views ?? []) {
+        for (const f of v.findings.filter((x) => x.kind === 'play_area_small' || x.kind === 'controls_duplicate_gesture' || x.kind === 'swipe_moves_nothing' || x.kind === 'empty_band')) {
+            out.push({ source: 'measure', text: f.kind === 'play_area_small' ? `The play is small on a phone (${v.view})` : f.kind === 'swipe_moves_nothing' ? `A swipe on the play moves nothing, and there is no pad (${v.view})` : f.kind === 'empty_band' ? `A dead band on the phone: rows with neither play nor HUD (${v.view})` : `On-screen controls repeat the swipe (${v.view})`, quote: f.what, who: 'look --hud', frame: v.frame ?? null, number: `${f.kind === 'play_area_small' ? 'play_fill' : 'pad_band_share'} ${f.number}`, score: 48 });
+        }
+    }
+    for (const a of m.audit?.failing ?? [])
+        out.push({ source: 'measure', text: `Phone layout of ${a.view}: ${a.failed.join(', ').replaceAll('_', ' ')}`, quote: a.detail, who: 'audit-screens', frame: frames.includes(`${a.view}-phone.png`) ? join(framesDir, `${a.view}-phone.png`) : null, number: a.detail.match(/\d+/)?.[0] ? `${a.detail.match(/\d+/)[0]} item(s)` : 'see detail', score: 45 });
+    for (const p of m.profile ?? []) {
+        if (p.frame_ms_p95 !== null && p.frame_ms_p95 > 33.4)
+            out.push({ source: 'measure', text: `Frame time on ${p.view}`, quote: `p95 ${p.frame_ms_p95} ms on a headless phone view (compare runs made the same way)`, who: 'profile', frame: frames.includes(`${p.view}-phone.png`) ? join(framesDir, `${p.view}-phone.png`) : null, number: `p95 ${p.frame_ms_p95} ms, ${p.long_frames ?? '?'} long frames`, score: 35 });
+    }
+    for (const f of m.sim ?? []) {
+        if (f.state === 'warn')
+            out.push({ source: 'measure', text: `Rules: ${firstSentence(f.says)}`, quote: [f.says, f.next].filter(Boolean).join(' — '), who: 'sim', frame: null, number: f.says.match(/\d+(\.\d+)?(\/\d+|%)?/)?.[0] ?? 'see sim', score: 55 });
+        else if (f.state === 'note' && f.id === 'skill-ceiling')
+            out.push({ source: 'measure', text: 'Own or raise the skill ceiling', quote: [f.says, f.next].filter(Boolean).join(' — '), who: 'sim', frame: null, number: axisNumber('fun'), score: 25 + Math.round(gap('fun') * 20) });
+    }
+    const FEEL_WEIGHT = { telegraph: 60, death: 55, verb: 45, feedback: 40, animation: 35 };
+    for (const f of (m.feel?.findings ?? []).filter((x) => x.state === 'note')) {
+        out.push({ source: 'measure', text: `Feel: ${firstSentence(f.says)}`, quote: [f.says, f.next].filter(Boolean).join(' — '), who: 'feel', frame: null, number: f.says.match(/measured (-?\d+(\.\d+)? \w+)/)?.[1] ?? f.says.match(/-?\d+(\.\d+)?\s?(s|body|%)/)?.[0] ?? 'see feel', score: FEEL_WEIGHT[f.area] });
+    }
+    const ours = (t) => t.replace(/\bGame [AB]\b/g, 'this game').replace(/\b[AB]'s\b/g, "this game's");
+    const flips = input.picks.filter((p) => p.prefer_candidate === false && p.flip).map((p) => ({ ...p, flip: ours(p.flip) }));
+    const fc = [];
+    for (const p of flips) {
+        const bag = words(p.flip);
+        const c = fc.find((x) => jaccard(x.bag, bag) >= 0.22);
+        if (c) {
+            c.texts.push(p.flip);
+            c.who.add(p.persona);
+            for (const w of bag)
+                c.bag.add(w);
+        }
+        else
+            fc.push({ texts: [p.flip], bag, who: new Set([p.persona]) });
+    }
+    for (const c of fc)
+        out.push({ source: 'versus', text: firstSentence(c.texts[0]), quote: c.texts[0], who: `head to head vs ${hit.name} (${[...c.who].join(', ')})`, frame: null, number: `win rate ${input.winRate ?? 'n/a'} vs ${hit.name}`, score: 30 + 14 * c.who.size });
+    const xp = input.experience;
+    if (xp) {
+        const xc = [];
+        for (const v of xp.verdicts)
+            (v.fixFirst ?? []).slice(0, 4).forEach((t, i) => {
+                const bag = words(t);
+                const c = xc.find((x) => jaccard(x.bag, bag) >= 0.22);
+                const item = { text: t, seat: v.critic, w: 4 - i };
+                if (c) {
+                    c.items.push(item);
+                    for (const w of bag)
+                        c.bag.add(w);
+                }
+                else
+                    xc.push({ items: [item], bag });
+            });
+        for (const c of xc) {
+            const lead = [...c.items].sort((a, b) => b.w - a.w)[0];
+            const d = dimensionOf(c.items.map((i) => i.text).join(' '));
+            const mine = xp.means[d], theirs = xp.hit?.[d];
+            const gapX = typeof mine === 'number' && typeof theirs === 'number' ? Math.max(0, theirs - mine) : 0;
+            const seats = [...new Set(c.items.map((i) => i.seat))];
+            out.push({
+                source: 'experience', text: firstSentence(lead.text), quote: lead.text, who: `experience ${seats.join(', ')} seat${seats.length > 1 ? 's' : ''}`,
+                frame: c.items.map((i) => frameNamed(i.text, frames, framesDir)).find(Boolean) ?? null,
+                number: `${DIMENSION_NAME[d]} ${typeof mine === 'number' ? mine.toFixed(1) : 'not scored'}${typeof theirs === 'number' ? ` (${hit.name} ${theirs.toFixed(1)})` : ''}`,
+                score: 20 + c.items.reduce((s, i) => s + i.w * 3, 0) + 8 * seats.length + Math.round(gapX * 6),
+            });
+        }
+    }
+    if (player?.come_back && player.come_back.answer !== 'yes') {
+        out.push({ source: 'player', text: `Give a reason to come back: ${firstSentence(player.come_back.why)}`, quote: player.come_back.why, who: `blind player, long session (${player.come_back.answer})`, frame: null, number: `come back tomorrow: ${player.come_back.answer}`, score: player.come_back.answer === 'no' ? 95 : 50 });
+    }
+    const fid = input.fidelity;
+    if (fid) {
+        const broken = Object.entries(fid.rules ?? {}).filter(([, v]) => /broken/i.test(String(v))).map(([k]) => k);
+        const gap = Math.max(0, 7 - Math.min(fid.artDirection, fid.creativeDirection));
+        (fid.fixFirst ?? []).slice(0, 3).forEach((t, i) => out.push({
+            source: 'fidelity', text: firstSentence(t), quote: t, who: 'fidelity seat (the plan against the game)', frame: null,
+            number: `art direction ${fid.artDirection} · creative direction ${fid.creativeDirection}${broken.length ? ` · broken: ${broken.join(', ')}` : ''}`,
+            score: 28 + (3 - i) * 6 + Math.round(gap * 4) + (i === 0 ? 4 * broken.length : 0),
+        }));
+    }
+    const ui = input.ui;
+    if (ui && ui.uiFidelity !== null && ui.uxFidelity !== null) {
+        const missing = ui.elements.filter((e) => /missing/i.test(e.verdict)).length;
+        const fights = ui.additions.filter((a) => a.serves === false).length;
+        (ui.fixFirst ?? []).slice(0, 3).forEach((t, i) => out.push({
+            source: 'fidelity', text: firstSentence(t), quote: t, who: 'UI fidelity seat (the plan\'s interface against the game)', frame: null,
+            number: `ui ${ui.uiFidelity} · ux ${ui.uxFidelity}${missing ? ` · ${missing} planned element(s) missing` : ''}${fights ? ` · ${fights} addition(s) fight the plan` : ''}`,
+            score: 28 + (3 - i) * 6 + Math.round(Math.max(0, 7 - Math.min(ui.uiFidelity, ui.uxFidelity)) * 4) + (i === 0 ? 3 * missing : 0),
+        }));
+    }
+    const t = ui?.title;
+    if (t && (t.wantToPlay < 7 || (t.hit && t.hit.wantToPlay - t.wantToPlay > 1)))
+        out.push({
+            source: 'fidelity', text: 'Make the title the game\'s first promise', quote: t.why ?? '', who: 'UI seat (the title as a player meets it)', frame: null,
+            number: `title look ${t.look} · want to play ${t.wantToPlay}${t.hit ? ` (the hit's opening ${t.hit.wantToPlay})` : ''}`,
+            score: 30 + Math.round(Math.max(0, 8 - t.wantToPlay) * 5),
+        });
+    if (input.mobile)
+        out.push(...mobileSteps(input.mobile));
+    return out.map((s) => ({ ...s, cited: !!s.frame, frame: s.frame ?? (play.endsWith('.png') ? play : null) })).sort((a, b) => b.score - a.score);
+}