@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/playtest/measure.js

@@ -0,0 +1,181 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { verify } from "../commands/verify.js";
+import { captureAll, loggedBy } from "../commands/capture-all.js";
+import { auditScreens } from "../commands/look.js";
+import { lookHud } from "../commands/look-hud.js";
+import { lookRead } from "../commands/look-read.js";
+import { profile } from "../commands/profile.js";
+import { sim, SIM_SCRIPT } from "../commands/sim.js";
+import { feel as feelCommand } from "../commands/feel.js";
+import { FEEL_SCRIPT } from "../feel/run.js";
+import { changedShare, sideBySide } from "../commands/compare.js";
+import { recordMadeOf } from "../commands/look-3d.js";
+import { madeOf } from "../look/made-of.js";
+import { decodePng, encodePng } from "../look/png.js";
+import { contactSheet, shrink } from "./sheet.js";
+import { rendererLine } from "../verify/gpu.js";
+export function foundBy(m) {
+    if (!m?.by)
+        return {};
+    const how = m.by === 'tag' ? 'role tag' : m.by === 'declared' ? 'the declared pattern' : 'the usual words';
+    return { found: `by ${how}: ${m.names?.length ? m.names.slice(0, 4).join(', ') : 'none on screen'}` };
+}
+export const SAME_PICTURE = 0.02;
+export async function samePicture(shots, viewport = 'desktop', within = SAME_PICTURE) {
+    const mine = shots.filter((s) => s.ok && s.viewport === viewport && existsSync(s.file));
+    const imgs = await Promise.all(mine.map(async (s) => shrink(decodePng(await readFile(s.file)), 320)));
+    const root = mine.map((_, i) => i);
+    const find = (i) => (root[i] === i ? i : (root[i] = find(root[i])));
+    for (let i = 0; i < imgs.length; i++) {
+        for (let j = i + 1; j < imgs.length; j++) {
+            const a = imgs[i], b = imgs[j];
+            if (a.width === b.width && a.height === b.height && changedShare(a, b) < within)
+                root[find(j)] = find(i);
+        }
+    }
+    const groups = new Map();
+    mine.forEach((s, i) => groups.set(find(i), [...(groups.get(find(i)) ?? []), s.view]));
+    return [...groups.values()].filter((g) => g.length > 1);
+}
+async function asJson(run) {
+    const out = [];
+    const code = await run({ log: (m) => out.push(String(m)), error: () => { } });
+    try {
+        return { code, data: JSON.parse(out.join('\n')) };
+    }
+    catch {
+        return { code, data: null };
+    }
+}
+export function build(dir) {
+    if (!existsSync(join(dir, 'package.json')))
+        return { ok: true, ms: 0, tail: 'no package.json: served as it is' };
+    const t0 = Date.now();
+    const r = spawnSync('npm', ['run', 'build'], { cwd: dir, encoding: 'utf8', shell: process.platform === 'win32', timeout: 300_000 });
+    const tail = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim().split('\n').slice(-6).join('\n');
+    return { ok: r.status === 0, ms: Date.now() - t0, tail };
+}
+export async function framesFor(dir, out, shots) {
+    await mkdir(out, { recursive: true });
+    const written = [];
+    for (const s of shots.filter((x) => x.ok && existsSync(x.file))) {
+        const img = decodePng(await readFile(s.file));
+        const name = `${s.view}-${s.viewport}.png`;
+        await writeFile(join(out, name), encodePng(shrink(img, img.width > img.height ? 1024 : 480)));
+        written.push(name);
+        const burst = s.file.replace(/\.png$/i, '') + '.burst';
+        if (s.moment && existsSync(burst)) {
+            const files = (await readdir(burst)).filter((f) => /^\d+\.png$/.test(f)).sort().slice(0, 12);
+            const sheet = contactSheet(await Promise.all(files.map(async (f) => decodePng(await readFile(join(burst, f))))), 4, img.width > img.height ? 320 : 180);
+            await writeFile(join(out, `clip-${s.view}-${s.viewport}.png`), encodePng(sheet));
+            written.push(`clip-${s.view}-${s.viewport}.png`);
+        }
+    }
+    return fitFrames(written, new Set(shots.filter((s) => s.moment).map((s) => s.view)));
+}
+export function fitFrames(frames, moments, cap = 24) {
+    const viewOf = (f) => f.replace(/^clip-/, '').replace(/-(desktop|phone)\.png$/, '');
+    const order = [...new Set(frames.map(viewOf))];
+    const kept = new Set(frames);
+    const cuttable = (vp) => frames.filter((f) => !f.startsWith('clip-') && f.endsWith(`-${vp}.png`) && !moments.has(viewOf(f)) && order.indexOf(viewOf(f)) >= 2);
+    for (const vp of ['desktop', 'phone']) {
+        const pool = cuttable(vp);
+        const over = Math.min(pool.length, kept.size - cap);
+        if (over <= 0)
+            break;
+        for (let k = 0; k < over; k++)
+            kept.delete(pool[Math.floor(((k + 0.5) * pool.length) / over)]);
+    }
+    return frames.filter((f) => kept.has(f)).slice(0, cap);
+}
+export async function compareFrames(before, after, out, names) {
+    const rows = [];
+    if (!existsSync(before))
+        return rows;
+    await mkdir(out, { recursive: true });
+    for (const f of names) {
+        if (!existsSync(join(before, f)))
+            continue;
+        const a = decodePng(await readFile(join(before, f))), b = decodePng(await readFile(join(after, f)));
+        const sheet = join(out, f);
+        await writeFile(sheet, encodePng(sideBySide(a, b)));
+        rows.push({ view: basename(f, '.png'), changed: a.width === b.width && a.height === b.height ? Math.round(changedShare(a, b) * 1000) / 1000 : null, sheet });
+    }
+    return rows;
+}
+export async function measure(dir, opts) {
+    const t0 = Date.now();
+    const built = opts.build ? build(dir) : { ok: true, ms: 0, tail: 'skipped (--no-build)' };
+    opts.note(built.ok ? `built in ${(built.ms / 1000).toFixed(1)} s` : 'the build failed');
+    const v = built.ok ? await asJson((io) => verify({ target: dir, sweep: true, json: true, viewport: 'desktop' }, io)) : { code: 3, data: null };
+    const gates = v.data?.gates ?? [];
+    const vp = v.data?.viewports?.[0];
+    const verdict = v.data ? {
+        verdict: v.data.verdict, failing: gates.filter((g) => !g.pass).map((g) => `${g.what}: ${g.reason}`.slice(0, 200)), gates: { passed: gates.filter((g) => g.pass).length, total: gates.length },
+        ...(vp?.renderer ? { renderer: rendererLine(vp.renderer, !!vp.software_gl) } : {}), ...(vp?.timing_void ? { timing_void: String(vp.timing_void) } : {}),
+    } : null;
+    opts.note(`verify ${verdict?.verdict ?? 'did not run'}`);
+    const c = built.ok ? await asJson((io) => captureAll({ target: dir, json: true, click: null, verbs: [] }, io)) : { code: 3, data: null };
+    const capture = (c.data?.shots ?? []).map((s) => ({ view: s.view, viewport: s.viewport, file: s.file, ok: s.code === 0, moment: !!s.moment, ...(s.errors?.length ? { errors: s.errors } : {}) }));
+    opts.note(`captured ${capture.filter((s) => s.ok).length} of ${capture.length} views`);
+    const evidence = { same: await samePicture(capture).catch(() => []), logged: [...loggedBy(capture)].map(([line, where]) => ({ line, where })) };
+    for (const g of evidence.same)
+        opts.note(`look at the frames first: ${g.join(', ')} show the same picture on desktop (a view that never reached its beat?)`);
+    if (evidence.logged.length)
+        opts.note(`look at the frames first: the page logged ${evidence.logged.length} distinct error(s) while entering views`);
+    const a = built.ok ? await asJson((io) => auditScreens({ target: dir, viewport: 'phone', json: true, click: null, views: [] }, io)) : { code: 3, data: null };
+    const audit = a.data ? {
+        verdict: a.data.verdict,
+        failing: (a.data.views ?? []).filter((x) => x.verdict === 'fail').map((x) => ({
+            view: x.view, failed: x.failed, detail: x.failed.map((k) => `${k.replace('_', ' ')} ${x.layout[k].total}: ${x.layout[k].items.slice(0, 2).map((i) => i.name ?? `${i.a} × ${i.b}`).join(', ')}`).join('; '),
+        })),
+    } : null;
+    const h = built.ok ? await asJson((io) => lookHud({ target: dir, viewport: 'phone', view: null, verbs: [], samples: 8, everyMs: 500, click: null, json: true }, io)) : { code: 3, data: null };
+    const hud = h.data ? { verdict: h.data.verdict, views: (h.data.views ?? []).map((x) => ({ view: x.view, verdict: x.verdict, frame: x.frame, numbers: x.numbers ?? {}, findings: (x.findings ?? []).slice(0, 10), ...(x.phone ? { phone: x.phone } : {}) })), ...(h.data.ui_style ? { ui_style: h.data.ui_style } : {}) } : null;
+    const rd = built.ok ? await asJson((io) => lookRead({ target: dir, viewport: 'phone', view: null, holdMs: 600, click: null, json: true }, io)) : { code: 3, data: null };
+    const read = rd.data ? {
+        verdict: rd.data.verdict, viewport: rd.data.viewport, view: rd.data.view, min_delta_e: rd.data.min_delta_e,
+        roles: (rd.data.roles ?? []).map((r) => ({ role: r.role, delta_e: r.delta_e, pass: !!r.pass, ...(r.weakest ? { weakest: `${r.weakest.name} at ΔE ${r.weakest.delta_e}` } : {}), ...(r.height_px ? { height_px: r.height_px } : {}), ...foundBy(rd.data.matched?.[r.role]) })),
+        ...(rd.data.hidden?.length ? { hidden: rd.data.hidden.length } : {}),
+    } : null;
+    opts.note(`audit-screens ${audit?.verdict ?? '—'} · look --hud ${hud?.verdict ?? '—'} · look --read ${read?.verdict ?? '—'}`);
+    let prof = null;
+    if (built.ok && !opts.quick) {
+        const p = await asJson((io) => profile({ target: dir, viewport: 'phone', views: [], seed: 1, frames: 120, settleMs: 1500, against: null, click: null, json: true }, io));
+        prof = (p.data?.views ?? []).filter((x) => x.sample).map((x) => x.sample.timing_void
+            ? { view: x.view, frame_ms_p95: null, fps: null, long_frames: null, timing_void: String(x.sample.timing_void) }
+            : { view: x.view, frame_ms_p95: x.sample.frame_ms_p95 ?? null, fps: x.sample.fps ?? null, long_frames: x.sample.long_frames ?? null });
+        opts.note(`profiled ${prof?.length ?? 0} play view(s)`);
+    }
+    let simFindings = null;
+    if (existsSync(join(dir, SIM_SCRIPT))) {
+        const r = await asJson((io) => sim({ target: dir, json: true }, io));
+        simFindings = r.data?.findings ?? null;
+        opts.note(`sim ${simFindings ? `${simFindings.filter((f) => f.state === 'warn').length} warn · ${simFindings.filter((f) => f.state === 'note').length} note` : 'did not run'}`);
+    }
+    let feelOut = null;
+    if (built.ok && existsSync(join(dir, FEEL_SCRIPT))) {
+        const r = await asJson((io) => feelCommand({ target: dir, json: true, sweep: !opts.quick }, io));
+        feelOut = Array.isArray(r.data?.findings) ? { script: r.data.script, findings: r.data.findings } : null;
+        opts.note(`feel ${feelOut ? `${feelOut.findings.filter((f) => f.state === 'note').length} note · ${feelOut.findings.filter((f) => f.state === 'ok').length} ok` : 'did not run'}`);
+    }
+    const made = madeOf(dir);
+    const made3d = made.three ? made : null;
+    if (made3d) {
+        await recordMadeOf(dir, made3d).catch(() => { });
+        opts.note(`look --3d ${made3d.verdict}`);
+    }
+    return { build: built, verify: verdict, capture, evidence, audit, hud, read, profile: prof, compare: [], sim: simFindings, feel: feelOut, madeOf: made3d, seconds: Math.round((Date.now() - t0) / 1000) };
+}
+export async function keepHudFrames(m, out) {
+    for (const v of m.hud?.views ?? []) {
+        if (!v.frame || !existsSync(v.frame))
+            continue;
+        const to = join(out, basename(v.frame));
+        await copyFile(v.frame, to);
+        v.frame = to;
+    }
+}

package/dist/playtest/mobile-qa.js

@@ -0,0 +1,391 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, extname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fitLine } from "../look/fit.js";
+export const AREAS = ['controls', 'play-share', 'reach', 'targets', 'chrome', 'safe-area', 'orientation', 'readability', 'first-touch'];
+export const SEVERITIES = ['high', 'medium', 'low'];
+export const PLATFORMS = {
+    'chromium-phone': 'Chromium phone',
+    'webkit-phone': 'WebKit phone',
+    'ios-portrait': 'iOS Safari portrait',
+    'ios-landscape': 'iOS Safari landscape',
+};
+export function phoneTarget(manifest) {
+    const p = String(manifest?.metadata?.platform ?? '').trim().toLowerCase();
+    if (p === 'desktop')
+        return { target: false, primary: false, why: 'funpixel.json declares "platform": "desktop"' };
+    if (p === 'phone' || p === 'mobile')
+        return { target: true, primary: true, why: 'funpixel.json declares the phone its primary platform' };
+    if (p === 'both')
+        return { target: true, primary: false, why: 'funpixel.json declares phone and desktop' };
+    const o = String(manifest?.metadata?.orientation ?? '').trim();
+    return { target: true, primary: false, why: o ? `declares a ${o} phone orientation; no primary platform declared` : 'played on phones by default; no platform or orientation declared' };
+}
+export function readMobileQa(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' };
+    }
+    if (typeof v?.phoneNative !== 'number' || v.phoneNative < 0 || v.phoneNative > 10)
+        return { problem: 'no phoneNative score from 0 to 10' };
+    if (!Array.isArray(v.findings))
+        return { problem: 'no findings list (an empty list says none)' };
+    const findings = v.findings
+        .filter((f) => f && typeof f.finding === 'string' && SEVERITIES.includes(String(f.severity).toLowerCase()))
+        .map((f) => ({ ...f, severity: String(f.severity).toLowerCase(), area: String(f.area ?? '') }));
+    return { verdict: { phoneNative: v.phoneNative, findings, fixFirst: Array.isArray(v.fixFirst) ? v.fixFirst.map(String) : [], verdict: typeof v.verdict === 'string' ? v.verdict : undefined } };
+}
+export function mergedText(f, observed) {
+    const named = (f.platforms ?? []).filter((p) => p in PLATFORMS);
+    const all = !named.length || observed.every((o) => named.includes(o));
+    return all ? f.finding : `[${named.map((p) => PLATFORMS[p]).join(', ')}] ${f.finding}`;
+}
+export const counts = (v) => ({
+    high: v?.findings.filter((f) => f.severity === 'high').length ?? 0,
+    medium: v?.findings.filter((f) => f.severity === 'medium').length ?? 0,
+    low: v?.findings.filter((f) => f.severity === 'low').length ?? 0,
+});
+export function phoneRuns(root) {
+    const base = join(root, '.funtools', 'phone');
+    const out = {};
+    if (!existsSync(base))
+        return out;
+    for (const d of readdirSync(base).sort()) {
+        const f = join(base, d, 'phone.json');
+        if (!existsSync(f))
+            continue;
+        let answer;
+        try {
+            answer = JSON.parse(readFileSync(f, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const o = answer.orientation === 'landscape' ? 'landscape' : 'portrait';
+        out[o] = { dir: join(base, d), at: statSync(f).mtimeMs, answer };
+    }
+    return out;
+}
+function builtAt(root) {
+    const f = join(root, 'dist', 'index.html');
+    return existsSync(f) ? statSync(f).mtimeMs : null;
+}
+const pt = (c) => `${c.label || c.role || 'control'} ${Math.round(c.width)}x${Math.round(c.height)}`;
+export function iosFact(o, run, built) {
+    const again = `run \`funtools phone${o === 'landscape' ? ' --orientation landscape' : ''}\` on the built game (it boots an iPhone simulator, opens real Mobile Safari, shuts it down)`;
+    if (!run)
+        return { text: `not observed: no ${o} run on this machine — ${again}`, observed: false, images: [] };
+    const a = run.answer;
+    if (!a.observed)
+        return { text: `not observed: ${a.reason ?? 'the run saw nothing'} — ${again}`, observed: false, images: [] };
+    const stale = built !== null && run.at < built ? ' (taken BEFORE the last build: it may show an older game)' : '';
+    const page = a.page ? `page ${a.page.w}x${a.page.h} CSS px at DPR ${a.page.dpr}, safe area ${a.page.insets ? a.page.insets.join('/') : 'not read'} (top/right/bottom/left)` : 'the page never reported (no size, no frames)';
+    const screens = [a.state_before, a.state_after_start, a.state_end].map((s) => (s && typeof s === 'object' && 'screen' in s ? String(s.screen) : '–')).join(' → ');
+    const play = a.frames?.play ?? a.frames?.['after-start'];
+    const bits = [
+        `${a.device?.name ?? 'iPhone'} (${a.device?.runtime ?? 'iOS'})${stale}`, page,
+        a.start ? `start "${a.start.label}" tapped${a.start_taps === 2 ? ' twice' : ''}; screens ${screens}` : 'no start control found by name',
+        `pressed: ${a.start ? 'the start control' : 'nothing by name'}${(a.taps_made ?? 0) > 0 ? ` and ${a.taps_made} point tap(s)` : ''}; ${a.swipes_made?.length ? `swiped ${a.swipes_made.map((s) => `${s.dir} (${s.changed.length ? `changed ${s.changed.slice(0, 4).join(', ')}` : 'moved nothing'})`).join(', ')}` : 'no swipe, drag or hold was made, so the play screenshots show the game idle after start (whether a verb works is verify\'s and the blind player\'s to say)'}`,
+        a.controls?.length ? `controls on the first screen: ${a.controls.slice(0, 6).map(pt).join(', ')}` : 'no controls found by the accessibility sweep',
+        a.small_controls?.length ? `under 44 pt: ${a.small_controls.slice(0, 4).map(pt).join(', ')}` : '',
+        play ? `play frames p95 ${play.p95} ms (WebKit's pacing on the Mac, not the phone's speed)` : '',
+        a.errors?.length ? `${a.errors.length} page error(s): ${String(a.errors[0].message).slice(0, 120)}` : '',
+        ...(a.notes ?? []).slice(0, 2).map((n) => `note: ${n.slice(0, 160)}`),
+    ].filter(Boolean);
+    const shots = (a.shots ?? []).filter((s) => existsSync(s));
+    const images = [...new Set([shots.find((s) => /loaded/.test(s)), ...shots.filter((s) => /play-|after-start/.test(s)).slice(-2)].filter(Boolean))];
+    return { text: bits.join('; '), observed: true, images };
+}
+export function actsOf(dir) {
+    const out = { drags: 0, taps: 0, holds: 0, jumps: 0, keys: 0 };
+    const f = join(dir, 'log.jsonl');
+    if (!existsSync(f))
+        return out;
+    for (const line of readFileSync(f, 'utf8').split('\n')) {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        for (const s of String(e?.step ?? '').split('&').map((x) => x.trim())) {
+            if (/^drag\b/.test(s))
+                out.drags++;
+            else if (/^tap\b/.test(s))
+                out.taps++;
+            else if (/^hold\s+\d/.test(s))
+                out.holds++;
+            else if (/^(hold|press)\s+[A-Za-z]/.test(s))
+                out.keys++;
+            else if (/^(view|verb)\b/.test(s))
+                out.jumps++;
+        }
+    }
+    return out;
+}
+export function roundFact(round) {
+    if (!round)
+        return { text: 'not filed: no blind phone round to read (in a playtest, `playtest experience` refreshes this seat once the round is filed)', images: [] };
+    const a = actsOf(round.dir);
+    const d = round.defects.slice(0, 3).map((x) => `${x.severity}: ${x.title}${x.step !== undefined ? ` (step ${x.step})` : ''}`).join('; ');
+    const images = round.defects.map((x) => x.shot && (existsSync(x.shot) ? x.shot : join(round.dir, basename(x.shot)))).filter((s) => !!s && existsSync(s)).slice(0, 3);
+    return {
+        text: `round ${round.round}: ${a.drags} drag(s), ${a.holds} touch hold(s), ${a.taps} tap(s)${a.keys ? `, ${a.keys} key press(es)` : ''}${a.jumps ? `, ${a.jumps} view/verb jump(s)` : ''}; ${d ? `defects — ${d}` : 'no defects filed'}${round.confusions.length ? `; confused by: ${round.confusions.slice(0, 2).join('; ')}` : ''}`,
+        images,
+    };
+}
+export const GESTURE_KEYS = /duplicat|gesture_?(dup|repeat|twin)|play_?(area_?)?share|board_?share/i;
+export function gestureFacts(sources) {
+    const out = [];
+    const walk = (v, path, depth) => {
+        if (depth > 6 || v === null || typeof v !== 'object')
+            return;
+        for (const [k, x] of Object.entries(v)) {
+            const p = path ? `${path}.${k}` : k;
+            if (GESTURE_KEYS.test(k))
+                out.push(`${p}: ${JSON.stringify(x).slice(0, 300)}`);
+            else
+                walk(x, p, depth + 1);
+        }
+    };
+    for (const [name, v] of sources)
+        walk(v, name, 0);
+    return [...new Set(out)].slice(0, 6);
+}
+export async function phoneParity(root, manifest) {
+    const { servedRoot } = await import("../commands/verify.js");
+    const dist = servedRoot(root);
+    if (!dist)
+        return { observed: false, unreachable: [], controls: 0, why: 'no dist/index.html (build first)' };
+    const { serveDir } = await import("../verify/serve.js");
+    const { browserPool, runUrl } = await import("../verify/run.js");
+    const { hookMapOf } = await import("../verify/hooks.js");
+    const { plannedFonts } = await import("../verify/health.js");
+    const served = await serveDir(dist);
+    const pool = browserPool();
+    try {
+        const { runs } = await runUrl(pool, served.url, {
+            checks: [], sweepMs: 0, viewports: ['phone'],
+            orientation: typeof manifest.metadata?.orientation === 'string' ? manifest.metadata.orientation : '',
+            hooks: hookMapOf(manifest), fonts: plannedFonts(manifest), frontDoor: null,
+        });
+        const h = runs[0]?.report?.render_health ?? {};
+        return h.key_parity_observed ? { observed: true, unreachable: h.unreachable_keys ?? [], controls: h.touch_controls_found ?? 0 } : { observed: false, unreachable: [], controls: h.touch_controls_found ?? 0, why: 'the game declares no key table (__FPX_KEYS__)' };
+    }
+    catch (e) {
+        return { observed: false, unreachable: [], controls: 0, why: `the phone page did not run: ${e.message.slice(0, 120)}` };
+    }
+    finally {
+        await pool.close();
+        await served.close();
+    }
+}
+export function swipesFor(measures) {
+    return (measures.hud?.views ?? []).some((v) => v.phone?.swipe?.moved || v.phone?.swipe?.claimed_by_play) ? ['right', 'up', 'left', 'down'] : [];
+}
+export async function runPhone(root, opts = {}) {
+    const { phone } = await import("../commands/phone.js");
+    const out = [];
+    for (const orientation of ['portrait', 'landscape']) {
+        const log = [];
+        const code = await phone({ target: root, orientation, seconds: 6, taps: [], swipes: orientation === 'portrait' ? opts.swipes : [], json: true, ...(opts.sim ? { sim: opts.sim } : {}) }, { log: (m) => log.push(String(m)), error: () => { } });
+        let a = null;
+        try {
+            a = JSON.parse(log.join('\n'));
+        }
+        catch { }
+        const line = `phone ${orientation}: ${code === 0 ? `observed (${a?.device?.name ?? 'iPhone'})` : code === 1 && a?.findings?.length ? `FAIL: ${a.findings.join('; ')}` : `not observed (${a?.reason ?? 'see funtools phone'})`}`;
+        out.push(line);
+        opts.note?.(line);
+        if (code !== 0 && !a?.device)
+            break;
+    }
+    return out;
+}
+const BIN = fileURLToPath(new URL(`../bin${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
+export async function webkitShot(root, view, out) {
+    try {
+        const { webkitBuild } = await import("../verify/browser.js");
+        const w = webkitBuild();
+        if (!w.installed)
+            return { file: null, why: `WebKit is not installed (optional: ${w.install})` };
+    }
+    catch {
+        return { file: null, why: 'playwright-core is not available' };
+    }
+    return new Promise((done) => {
+        execFile(process.execPath, [BIN, 'capture', root, '--view', view, '--viewport', 'phone', '--engine', 'webkit', '--out', out, '--json'], { timeout: 120_000, maxBuffer: 8 << 20 }, (err) => {
+            done(existsSync(out) ? { file: out, why: '' } : { file: null, why: `the WebKit capture failed${err ? `: ${err.message.split('\n')[0].slice(0, 120)}` : ''}` });
+        });
+    });
+}
+export function pickPhoneFrames(names, play, cap = 6) {
+    const full = names.filter((n) => !n.startsWith('clip-'));
+    const first = [full.find((n) => /^title-/.test(n)), play ? full.find((n) => n === `${play}-phone.png`) : undefined].filter((n) => !!n);
+    const rest = full.filter((n) => !first.includes(n));
+    const room = Math.max(0, cap - first.length - 1);
+    const spread = rest.length <= room ? rest : Array.from({ length: room }, (_, k) => rest[Math.floor(((k + 0.5) * rest.length) / room)]);
+    const clip = names.find((n) => n.startsWith('clip-'));
+    return [...first, ...spread, ...(clip ? [clip] : [])].slice(0, cap);
+}
+export function playViewOf(views) {
+    return views.find((v) => /^play(ing)?$/i.test(v)) ?? views.find((v) => /play|game|level|run|board/i.test(v)) ?? views[1] ?? views[0] ?? null;
+}
+const PANEL = new URL('../../panel/', import.meta.url);
+export async function prepareMobileQa(root, dir, input) {
+    const target = phoneTarget(input.manifest);
+    const note = input.note ?? (() => { });
+    if (!target.target)
+        return { seat: null, target, platforms: [], facts: [{ id: 'M1', instrument: 'platform', text: `not a phone game: ${target.why}` }], images: [] };
+    await mkdir(dir, { recursive: true });
+    const m = input.measures;
+    const platforms = [];
+    const facts = [];
+    const images = [];
+    const add = (name, file) => { if (!images.some((i) => i.file === file))
+        images.push({ name, file }); };
+    const orientation = typeof input.manifest.metadata?.orientation === 'string' ? input.manifest.metadata.orientation : 'portrait';
+    facts.push({ instrument: 'platform (funpixel.json)', text: `${target.why}; played ${orientation}${target.primary ? '; the phone is primary, so a key with no touch route is high' : ''}` });
+    const views = [...new Set(m.capture.filter((c) => c.ok).map((c) => c.view))];
+    const play = playViewOf(views);
+    const chromium = input.frames?.names.filter((n) => /-phone\.png$/.test(n)) ?? [];
+    const chromiumImgs = pickPhoneFrames(chromium, play).map((n) => join(input.frames.dir, n));
+    for (const f of chromiumImgs)
+        add(`chromium ${basename(f, '.png')}`, f);
+    platforms.push({ id: 'chromium-phone', observed: chromiumImgs.length > 0, why: chromiumImgs.length ? `${chromium.filter((n) => !n.startsWith('clip-')).length} view(s) at ${orientation === 'landscape' ? '844x390' : '390x844'}, touch emulated, DPR 2; ${chromiumImgs.length} shown` : 'no phone frames were captured', images: chromiumImgs });
+    let wk = { file: null, why: input.offline ? 'skipped' : 'no play view was captured' };
+    const wkFile = play ? join(dir, `webkit-${play}-phone.png`) : '';
+    if (wkFile && existsSync(wkFile))
+        wk = { file: wkFile, why: '' };
+    else if (!input.offline && play) {
+        note(`WebKit: shooting ${play} at phone size`);
+        wk = await webkitShot(root, play, wkFile);
+    }
+    if (wk.file)
+        add(`webkit ${play}-phone`, wk.file);
+    platforms.push({ id: 'webkit-phone', observed: !!wk.file, why: wk.file ? `${play} in Playwright's WebKit at phone size` : wk.why, images: wk.file ? [wk.file] : [] });
+    const runs = phoneRuns(root);
+    const built = builtAt(root);
+    for (const o of ['portrait', 'landscape']) {
+        const r = iosFact(o, runs[o], built);
+        facts.push({ instrument: `funtools phone (iOS Safari in the Simulator, ${o})`, text: r.text });
+        r.images.forEach((f) => add(`ios-${o} ${basename(f, '.png')}`, f));
+        platforms.push({ id: o === 'portrait' ? 'ios-portrait' : 'ios-landscape', observed: r.observed, why: r.observed ? `${runs[o].answer.device?.name ?? 'iPhone'}, real Mobile Safari` : 'not run', images: r.images });
+    }
+    const parityFile = join(dir, 'parity.json');
+    let parity;
+    try {
+        parity = JSON.parse(readFileSync(parityFile, 'utf8'));
+    }
+    catch {
+        parity = input.offline ? { observed: false, unreachable: [], controls: 0, why: 'skipped' } : await phoneParity(root, input.manifest);
+        if (!input.offline)
+            await writeFile(parityFile, JSON.stringify(parity, null, 2) + '\n');
+    }
+    facts.push({
+        instrument: 'key parity at phone size (verify\'s render_health: each declared key against the touch controls that name it)',
+        text: !parity.observed ? `not observed: ${parity.why}`
+            : parity.unreachable.length ? `${parity.unreachable.length} declared key(s) with no on-screen control naming them: ${parity.unreachable.join(', ')} (${parity.controls} touch control(s) found). A key the play area's gesture covers (a swipe for the arrows) is reached; say which gesture, or that none does`
+                : `every declared key has an on-screen control (${parity.controls} found)`,
+    });
+    const fitFile = join(dir, 'fit.json');
+    let fit = null;
+    try {
+        fit = JSON.parse(readFileSync(fitFile, 'utf8'));
+    }
+    catch {
+        if (!input.offline) {
+            note('look --fit: five windows, each opened fresh');
+            const { measureFit } = await import("../commands/look-fit.js");
+            const r = await measureFit(root, { view: play, click: null, out: dir }).catch((e) => `look --fit failed: ${e.message}`);
+            if (typeof r !== 'string') {
+                fit = r;
+                await writeFile(fitFile, JSON.stringify(r, null, 2) + '\n');
+            }
+        }
+    }
+    facts.push({
+        instrument: 'look --fit (does it fill the window: five windows opened fresh; content = anything not the ground colour, so a busy backdrop counts as content)',
+        text: fit ? fit.map(fitLine).join(' · ') : 'not observed: the window sweep did not run',
+    });
+    for (const r of fit ?? [])
+        if (r.frame && existsSync(r.frame) && (r.viewport.name === 'wide-short' || r.findings.some((f) => !/after opening/.test(f))))
+            add(`fit ${r.viewport.name}`, r.frame);
+    const verifyRecord = (() => { try {
+        return JSON.parse(readFileSync(join(root, 'verify.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    } })();
+    const g = gestureFacts([['measures', m], ['verify.json', verifyRecord]]);
+    facts.push({ instrument: 'gesture check (on-screen controls that repeat a gesture the play area takes; the share of the screen given to play)', text: g.length ? g.join(' · ') : 'not measured here: estimate the play area\'s share from the frames (its bounds in the frame against the frame) and say it is an estimate' });
+    const hudPlay = (m.hud?.views ?? []).find((v) => v.view === play) ?? m.hud?.views[0];
+    if (hudPlay?.frame && existsSync(hudPlay.frame))
+        add(`hud ${hudPlay.view}`, hudPlay.frame);
+    const rf = roundFact(input.round ?? null);
+    facts.push({ instrument: 'the blind phone player (funtools play, touch only, never the source)', text: rf.text });
+    rf.images.forEach((f) => add(`player ${basename(f, '.png')}`, f));
+    const numbered = facts.map((f, i) => ({ id: `M${i + 1}`, ...f }));
+    const kept = images.slice(0, 16);
+    const answer = join(dir, 'mobile-qa.json');
+    const prompt = mobileQaPrompt({ premise: input.premise, target, orientation, platforms, facts: numbered, images: kept, readFacts: input.facts ?? '', prior: input.prior ?? null, answer });
+    await writeFile(join(dir, 'mobile-qa.md'), prompt);
+    const fp = await (await import("../verify/fingerprint.js")).fingerprint(root).then((x) => x.fingerprint).catch(() => undefined);
+    const prep = { seat: join(dir, 'mobile-qa.md'), target, platforms, facts: numbered, images: kept, ...(fp ? { fingerprint: fp } : {}) };
+    await writeFile(join(dir, 'evidence.json'), JSON.stringify(prep, null, 2) + '\n');
+    note(`mobile QA: ${platforms.filter((p) => p.observed).map((p) => PLATFORMS[p.id]).join(', ') || 'no phone'} observed; ${kept.length} image(s)`);
+    return prep;
+}
+function priorText(p) {
+    if (!p)
+        return '';
+    return ['## The last Mobile QA (settle these first)', '', `It gave phone-native ${p.phoneNative}. Its findings:`, '',
+        ...p.findings.slice(0, 8).map((f) => `- ${f.severity} · ${f.area}: ${f.finding}`), '',
+        'In `prior`, mark each fixed, unchanged or worse from these frames. A finding settled is never filed again in new words.'].join('\n');
+}
+export function mobileQaPrompt(x) {
+    const plat = x.platforms.map((p) => `- ${p.id} (${PLATFORMS[p.id]}): ${p.observed ? 'observed' : 'NOT observed'} — ${p.why}`).join('\n');
+    const facts = [x.readFacts.trim(), ...x.facts.map((f) => `- ${f.id} · ${f.instrument}: ${f.text}`)].filter(Boolean).join('\n');
+    const imgs = x.images.map((i) => `- ${i.name}: ${i.file}`).join('\n');
+    return readFileSync(new URL('mobile-qa.md', PANEL), 'utf8')
+        .replaceAll('{{PREMISE}}', x.premise)
+        .replaceAll('{{TARGET}}', `${x.target.why}; held ${x.orientation}${x.target.primary ? '. The phone is this game\'s primary platform.' : '.'}`)
+        .replaceAll('{{PLATFORMS}}', plat)
+        .replaceAll('{{FACTS}}', facts || 'None measured.')
+        .replaceAll('{{IMAGES}}', imgs || 'No image: say so, file no finding a frame would be needed for, and stop.')
+        .replaceAll('{{PRIOR}}', priorText(x.prior)) +
+        `\n\n## Filing\n\nWrite your JSON answer, and nothing else, to this file with your file-writing tool:\n${x.answer}\nThen reply with one line: \`filed\`. You read nothing but the images named above: no source, no other file in the folder, no other seat's answer.\n`;
+}
+export function latestMobileQa(root) {
+    const files = [];
+    const pt = join(root, '.funtools', 'playtest');
+    if (existsSync(pt))
+        for (const d of readdirSync(pt))
+            files.push(join(pt, d, 'mobile', 'mobile-qa.json'));
+    const mq = join(root, '.funtools', 'mobile-qa');
+    if (existsSync(mq))
+        for (const d of readdirSync(mq))
+            files.push(join(mq, d, 'mobile-qa.json'));
+    const found = files.filter((f) => existsSync(f)).map((f) => ({ f, at: statSync(f).mtimeMs })).sort((a, b) => b.at - a.at)[0];
+    if (!found)
+        return null;
+    const r = readMobileQa(found.f);
+    return r.verdict ? { file: found.f, verdict: r.verdict, at: found.at } : null;
+}
+export function frameOf(name, images) {
+    if (!name)
+        return null;
+    const n = name.toLowerCase();
+    const hit = images.find((i) => i.name.toLowerCase() === n) ?? images.find((i) => n.includes(basename(i.file, '.png').toLowerCase())) ?? images.find((i) => i.name.toLowerCase().includes(n));
+    return hit?.file ?? null;
+}
+export const relTo = (root, f) => (f.startsWith(root) ? relative(root, f) : f);