@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/verify/health.js

@@ -0,0 +1,172 @@
+import { fmtFixed, sweepInputs } from "./judge.js";
+const json = (text) => {
+    try {
+        const v = JSON.parse(String(text).trim());
+        return v && typeof v === 'object' ? v : null;
+    }
+    catch {
+        return null;
+    }
+};
+const str = (v, k) => (typeof v[k] === 'string' ? v[k] : '');
+const int = (v, k, dflt) => (Number.isInteger(v[k]) ? v[k] : dflt);
+const strings = (a) => (Array.isArray(a) ? a.filter((s) => typeof s === 'string') : []);
+export function plannedFonts(manifest) {
+    const m = manifest.metadata ?? {};
+    return [...new Set([m.font, ...(Array.isArray(m.fonts) ? m.fonts : [])].filter((f) => typeof f === 'string' && f.trim() !== '').map((f) => f.trim()))];
+}
+export function playInputs(checks) {
+    const real = sweepInputs(checks).filter((i) => i.kind !== 'verb');
+    const inputs = real.length ? real : ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'Space'].map((value) => ({ kind: 'key', value }));
+    return inputs.map((i) => (i.kind === 'key' ? { kind: 'key', code: i.value } : { kind: 'pointer', sel: i.value }));
+}
+export const playInputLabel = (i) => (i.kind === 'key' ? i.code : `tap ${i.sel}`);
+export function parsePreview(text) {
+    const v = json(text);
+    if (!v)
+        return null;
+    return { status: int(v, 'status', -1), ready_state: str(v, 'ready_state'), canvas: str(v, 'canvas'), frames: int(v, 'frames', 0), waited_ms: int(v, 'waited_ms', 0) };
+}
+export function parsePlay(text, inputs) {
+    const v = json(text);
+    if (!v)
+        return null;
+    const n = (k) => Math.max(0, int(v, k, 0));
+    return {
+        observed: v.observed === true, kind: str(v, 'kind'), samples: n('samples'), idle_changes: n('idle_changes'), input_changes: n('input_changes'),
+        errors_idle: n('errors_idle'), errors_input: n('errors_input'), first_error: str(v, 'first_error'), inputs,
+    };
+}
+export function parseFonts(text) {
+    const v = json(text);
+    if (!v)
+        return null;
+    const fonts = (Array.isArray(v.fonts) ? v.fonts : []).filter((f) => f && typeof f === 'object').map((f) => ({
+        family: str(f, 'family'), source: str(f, 'source'), status: str(f, 'status'), used: f.used === true,
+    }));
+    return { observed: v.observed === true, planned: strings(v.planned), fonts };
+}
+export function parseAudioFiles(text) {
+    const v = json(text);
+    if (!v)
+        return null;
+    return { observed: v.observed === true, files: Math.max(0, int(v, 'files', 0)), checked: Math.max(0, int(v, 'checked', 0)), broken: strings(v.broken), skipped: strings(v.skipped) };
+}
+export function parseRenderer(text) {
+    const v = json(text);
+    if (!v)
+        return null;
+    const n = (k) => Math.max(0, int(v, k, 0));
+    return {
+        observed: v.observed === true, frames: n('frames'), draw_calls_max: n('draw_calls_max'), draw_calls_p50: n('draw_calls_p50'),
+        triangles_max: n('triangles_max'), triangles_p50: n('triangles_p50'),
+    };
+}
+export const DRAW_CALL_BUDGET = 100;
+export const TRIANGLE_BUDGET = 150_000;
+export function rendererNote(r) {
+    if (!r?.observed)
+        return '';
+    const over = [
+        r.draw_calls_max > DRAW_CALL_BUDGET ? `${r.draw_calls_max} draw calls (budget ${DRAW_CALL_BUDGET})` : '',
+        r.triangles_max > TRIANGLE_BUDGET ? `${r.triangles_max} triangles (budget ${TRIANGLE_BUDGET})` : '',
+    ].filter(Boolean);
+    return over.length ? `a frame drew ${over.join(' and ')} — heavy for a phone; batch, instance or decimate. Counted after the checks, wherever they left the game, every render pass included (a portal or mirror view is another pass): \`funtools profile --views a,b\` measures each view` : '';
+}
+export function parseFrontDoor(text, selector) {
+    const v = json(text);
+    if (!v)
+        return { selector, found: false, pressed: false, changed: null, name: '', screen_before: '', screen_after: '', error: 'the page refused the front-door script' };
+    return {
+        selector: str(v, 'selector'), found: v.found === true, pressed: v.pressed === true,
+        changed: typeof v.changed === 'boolean' ? v.changed : null, name: str(v, 'name'),
+        screen_before: str(v, 'screen_before'), screen_after: str(v, 'screen_after'), error: str(v, 'error'),
+    };
+}
+export function frontDoorDeadReason(f) {
+    if (f.screen_before && f.screen_before === f.screen_after) {
+        return `pressed "${f.name}" and the game did not start: __FPX_STATE__().screen stayed "${f.screen_before}" `
+            + '(the button changing its own look is not a start; a countdown counts once the state names it, e.g. phase: "countdown")';
+    }
+    return `pressed "${f.name}" and nothing changed — no state, page or picture change followed`;
+}
+export function parseHookMap(text) {
+    const v = json(text);
+    return v ? { mapped: strings(v.mapped), unresolved: strings(v.unresolved), skipped: strings(v.skipped) } : null;
+}
+export function difficultyCurve(levels) {
+    const moves = levels.filter((l) => l.status === 'solvable' && l.moves >= 0).map((l) => l.moves);
+    if (moves.length < 3)
+        return { curve: '', note: '' };
+    const third = Math.max(1, Math.floor(moves.length / 3));
+    const mean = (a) => a.reduce((s, x) => s + x, 0) / a.length;
+    const first = mean(moves.slice(0, third)), last = mean(moves.slice(moves.length - third));
+    const span = `the first third averages ${fmtFixed(first, 1)} moves, the last ${fmtFixed(last, 1)}`;
+    if (last < first)
+        return { curve: 'inverted', note: `the difficulty curve is inverted: late levels take fewer moves than early ones (${span})` };
+    if (last <= first * 1.1)
+        return { curve: 'flat', note: `the difficulty curve is flat (${span})` };
+    return { curve: 'rising', note: '' };
+}
+export function parseLevels(text) {
+    if (String(text ?? '').trim() === 'none')
+        return { declared: false, count: 0, levels: [], curve: '', note: '' };
+    const v = json(text);
+    if (!v || v.declared !== true)
+        return null;
+    const levels = (Array.isArray(v.levels) ? v.levels : []).filter((l) => l && typeof l === 'object').map((l) => ({
+        index: Math.max(0, int(l, 'index', 0)), status: ['solvable', 'unsolvable'].includes(l.status) ? l.status : 'not_observed',
+        moves: int(l, 'moves', -1), error: str(l, 'error'),
+    }));
+    return { declared: true, count: Math.max(0, int(v, 'count', 0)), levels, ...difficultyCurve(levels) };
+}
+const PLAY_FAILS = {
+    blank: () => 'nothing was drawn for two seconds — the canvas stayed one flat colour (or there is none) and the page shows no text',
+    crashed: (e) => `an uncaught error before any input${e ? ` (${e})` : ''}, and nothing moved after it`,
+    crashedUnderInput: (e) => `an input threw${e ? ` (${e})` : ''}, and the screen froze after it`,
+};
+export function healthGates(report) {
+    const out = [];
+    const f = report.front_door;
+    if (f) {
+        const what = 'the real Play button starts the game';
+        if (!f.found)
+            out.push({ what, pass: false, reason: `nothing visible matches ${f.selector} (${f.error || "mark the title's start control data-fpx-start"})` });
+        else if (!f.pressed)
+            out.push({ what, pass: false, reason: `pressing "${f.name}" failed: ${f.error}` });
+        else if (f.changed === false)
+            out.push({ what, pass: false, reason: frontDoorDeadReason(f) });
+        else if (f.changed === true)
+            out.push({ what, pass: true, reason: '' });
+    }
+    const p = report.preview;
+    if (p && p.status >= 0 && (p.status < 200 || p.status > 299)) {
+        out.push({ what: 'the page loaded', pass: false, reason: `the page answered HTTP ${p.status}` });
+    }
+    const play = report.play;
+    if (play && PLAY_FAILS[play.kind])
+        out.push({ what: 'the game plays for two seconds', pass: false, reason: PLAY_FAILS[play.kind](play.first_error) });
+    const planned = new Set((report.fonts?.planned ?? []).map((f) => f.toLowerCase()));
+    for (const f of report.fonts?.fonts ?? []) {
+        if (f.status === 'loaded' && planned.has(f.family.toLowerCase()))
+            out.push({ what: `the font "${f.family}" loads`, pass: true, reason: '' });
+        else if (f.status === 'error')
+            out.push({ what: `the font "${f.family}" loads`, pass: false, reason: 'its @font-face file failed to load (a 404, or not a font file) — players see a fallback' });
+        else if (f.status === 'missing')
+            out.push({ what: `the font "${f.family}" loads`, pass: false, reason: 'it is planned but no @font-face declares it — players see a fallback unless their device has it' });
+    }
+    const a = report.audio_files;
+    if (a && a.observed && a.broken.length) {
+        out.push({ what: `the sound files are real (${a.checked} checked)`, pass: false, reason: `broken: ${a.broken.join(', ')}` });
+    }
+    const l = report.levels;
+    if (l && l.declared) {
+        const bad = l.levels.filter((x) => x.status === 'unsolvable');
+        const good = l.levels.filter((x) => x.status === 'solvable');
+        if (bad.length)
+            out.push({ what: 'every level is solvable', pass: false, reason: `${bad.map((x) => `solve(${x.index})`).join(', ')} ${bad.length === 1 ? 'says' : 'say'} unsolvable` });
+        else if (good.length)
+            out.push({ what: `every level is solvable (${good.length} solved)`, pass: true, reason: '' });
+    }
+    return out;
+}

package/dist/verify/hooks.js

@@ -0,0 +1,34 @@
+export const HOOK_NAMES = ['state', 'verbs', 'views', 'keys', 'audio', 'selftest', 'levels'];
+const PATH = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/;
+export function hookMapProblems(raw) {
+    if (raw === undefined)
+        return [];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['"hooks" must be an object: { "state": "__MYGAME__.state", … }'];
+    const out = [];
+    for (const [k, v] of Object.entries(raw)) {
+        if (!HOOK_NAMES.includes(k)) {
+            out.push(`"hooks.${k}" is not a hook (${HOOK_NAMES.join(', ')})`);
+            continue;
+        }
+        if (typeof v === 'string') {
+            if (!PATH.test(v))
+                out.push(`"hooks.${k}": "${v}" is not a dotted path from window`);
+            continue;
+        }
+        if (k === 'state' && v && typeof v === 'object' && !Array.isArray(v)) {
+            for (const [f, p] of Object.entries(v))
+                if (typeof p !== 'string' || !PATH.test(p))
+                    out.push(`"hooks.state.${f}" is not a dotted path from window`);
+            continue;
+        }
+        out.push(`"hooks.${k}" must be a dotted path${k === 'state' ? ', or { field: path }' : ''}`);
+    }
+    return out;
+}
+export function hookMapOf(manifest) {
+    const raw = manifest.hooks;
+    if (raw === undefined || hookMapProblems(raw).length)
+        return null;
+    return Object.keys(raw).length ? raw : null;
+}

package/dist/verify/judge.js

@@ -0,0 +1,303 @@
+import { healthGates } from "./health.js";
+const TRACE_MOVE_EPS = 0.5;
+export const TRACE_MIN_FRAMES = 8;
+export const TRACE_MAX_FRAMES = 120;
+export const f32 = (x) => Math.fround(x);
+export function fmtFixed(x, digits) {
+    const scaled = x * 10 ** digits;
+    if (Number.isInteger(scaled * 2) && !Number.isInteger(scaled)) {
+        const lo = Math.floor(scaled);
+        const even = lo % 2 === 0 ? lo : lo + 1;
+        return (even / 10 ** digits).toFixed(digits);
+    }
+    return x.toFixed(digits);
+}
+export function keyForCode(code) {
+    if (code.startsWith('Key') && code.length === 4)
+        return code.slice(3).toLowerCase();
+    if (code.startsWith('Digit') && code.length === 6)
+        return code.slice(5);
+    if (code === 'Space')
+        return ' ';
+    return code;
+}
+export function drivenBy(c) {
+    if (c.key.trim())
+        return `key:${c.key.trim()}`;
+    if (c.pointer.trim())
+        return `pointer:${c.pointer.trim()}`;
+    return 'verb';
+}
+export const screenAxis = (c) => (c.axis.trim().toLowerCase() === 'y' ? 'y' : 'x');
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+export function mechanicCheckArgs(c, times, settleMs) {
+    const mode = drivenBy(c);
+    let drive = 'verb', code = '', selector = '';
+    if (mode.startsWith('key:')) {
+        drive = 'key';
+        code = mode.slice(4);
+    }
+    else if (mode.startsWith('pointer:')) {
+        drive = 'pointer';
+        selector = mode.slice(8);
+    }
+    return {
+        drive,
+        key: keyForCode(code),
+        code,
+        selector,
+        verb: c.verb,
+        mode: mode === 'verb' ? 'verb' : 'input',
+        subject: c.subject.trim(),
+        axis: screenAxis(c),
+        field: c.field,
+        times,
+        hold: clamp(settleMs, 100, 1000),
+        trace: c.trace === 0 ? 0 : clamp(c.trace, TRACE_MIN_FRAMES, TRACE_MAX_FRAMES),
+        settle: clamp(settleMs, 50, 2000),
+    };
+}
+const numbers = (series) => series.filter((v) => typeof v === 'number');
+export function summarizeTrace(series) {
+    const frames = Math.max(0, series.length - 1);
+    const origin = numbers(series)[0];
+    let firstMoved = null, maxJump = 0, prev = null;
+    series.forEach((v, i) => {
+        if (typeof v !== 'number')
+            return;
+        if (origin !== undefined && firstMoved === null && i > 0 && Math.abs(v - origin) > TRACE_MOVE_EPS) {
+            firstMoved = i;
+        }
+        if (prev !== null)
+            maxJump = Math.max(maxJump, Math.abs(v - prev));
+        prev = v;
+    });
+    return { frames, firstMoved, maxJump };
+}
+export function seriesSupports(expect, series) {
+    const nums = numbers(series);
+    if (nums.length === 0)
+        return false;
+    const origin = nums[0];
+    const lo = Math.min(...nums), hi = Math.max(...nums);
+    switch (expect.trim().toLowerCase()) {
+        case 'increases': return hi - origin > TRACE_MOVE_EPS;
+        case 'decreases': return origin - lo > TRACE_MOVE_EPS;
+        default: return hi - lo > TRACE_MOVE_EPS;
+    }
+}
+export function renderTrace(series) {
+    const MAX = 40;
+    const parts = series.slice(0, MAX).map((v) => (typeof v === 'number' ? fmtFixed(v, 1) : '-'));
+    if (series.length > MAX)
+        parts.push(`… (${series.length - MAX} more)`);
+    return parts.join(',');
+}
+const jsonNumber = (s) => {
+    try {
+        const v = JSON.parse(s.trim());
+        return typeof v === 'number' ? v : null;
+    }
+    catch {
+        return null;
+    }
+};
+export function judgeMechanicChange(before, after, expect) {
+    const e = expect.trim().toLowerCase();
+    if (e === 'increases' || e === 'decreases') {
+        const b = jsonNumber(before), a = jsonNumber(after);
+        if (b !== null && a !== null) {
+            const up = e === 'increases';
+            if (up ? a > b : a < b)
+                return [true, ''];
+            return [false, `the field did not ${up ? 'increase' : 'decrease'} (${b} → ${a})`];
+        }
+    }
+    return before !== after ? [true, ''] : [false, 'field did not change'];
+}
+export function judgeScreenMove(before, after, expect, axis) {
+    const num = (s) => (s.trim() === '' || Number.isNaN(Number(s)) ? null : Number(s));
+    const b = num(before), a = num(after);
+    if (b === null || a === null)
+        return [false, "the player's screen position could not be read"];
+    const e = expect.trim().toLowerCase();
+    const [ok, word] = e === 'increases' ? [a > b, 'increase'] : e === 'decreases' ? [a < b, 'decrease'] : [a !== b, 'move'];
+    if (ok)
+        return [true, ''];
+    return [false, `the player's SCREEN-space ${axis.toUpperCase()} did not ${word} (${fmtFixed(b, 0)} → ${fmtFixed(a, 0)})`];
+}
+export function judgeCheckOutcome(c, before, after, screenBefore, screenAfter) {
+    let [reached, reason] = judgeMechanicChange(before, after, c.expect);
+    const subject = c.subject.trim();
+    if (!subject)
+        return [reached, reason];
+    if (!screenBefore || !screenAfter) {
+        return [false, `no object \`${subject}\` on the stage/scene/page — give the player that exact Pixi \`.label\` / Three \`.name\` (or a CSS selector for a DOM element) so the platform can read where it is on screen`];
+    }
+    const [sOk, sWhy] = judgeScreenMove(screenBefore, screenAfter, c.expect, screenAxis(c));
+    if (!sOk) {
+        const b = Number(screenBefore.trim()), a = Number(screenAfter.trim());
+        const still = screenBefore.trim() !== '' && screenAfter.trim() !== '' && Number.isFinite(b) && Number.isFinite(a) && b === a;
+        reason = reached && still
+            ? `${sWhy} — the field \`${c.field}\` went the way the Plan promised, but \`${subject}\` did not move on SCREEN at all: it is not the thing that moves (a container whose children move, or a node the game never repositions); name the moving node as the subject`
+            : reached
+                ? `${sWhy} — the field \`${c.field}\` went the way the Plan promised, the player on SCREEN went the other way: the camera or the render mirrors this axis`
+                : reason === '' ? sWhy : `${reason}; ${sWhy}`;
+        reached = false;
+    }
+    return [reached, reason];
+}
+export function judgeSound(expectSound, sounds) {
+    if (!expectSound || sounds !== 0)
+        return null;
+    return 'no sound started while it ran — this mechanic promises one';
+}
+export function climbFraction(series) {
+    const nums = numbers(series);
+    if (nums.length === 0)
+        return null;
+    let best = nums[0], lastRise = null;
+    series.forEach((v, i) => {
+        if (typeof v !== 'number')
+            return;
+        if (v > best) {
+            best = v;
+            lastRise = i;
+        }
+    });
+    if (lastRise === null)
+        return null;
+    return (lastRise + 1) / Math.max(1, series.length);
+}
+export const LEAVES_PLAY = ['win', 'lose', 'end', 'finish', 'reset', 'restart', 'retry', 'quit', 'exit', 'pause', 'resume', 'menu'];
+const leavesPlay = (c) => c.field.trim() === 'screen' || LEAVES_PLAY.some((p) => c.verb.trim().toLowerCase().startsWith(p));
+export function sweepInputs(checks) {
+    const out = [];
+    const push = (i) => { if (!out.some((o) => o.kind === i.kind && o.value === i.value))
+        out.push(i); };
+    for (const c of checks)
+        if (c.key.trim())
+            push({ kind: 'key', value: c.key.trim() });
+    for (const c of checks)
+        if (c.pointer.trim())
+            push({ kind: 'pointer', value: c.pointer.trim() });
+    for (const c of checks) {
+        if (c.verb.trim() && !c.key.trim() && !c.pointer.trim() && !leavesPlay(c))
+            push({ kind: 'verb', value: c.verb.trim() });
+    }
+    if (out.length === 0)
+        for (const k of ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'Space'])
+            out.push({ kind: 'key', value: k });
+    return out;
+}
+export const sweepInputJson = (i) => i.kind === 'key' ? { kind: 'key', code: i.value } : i.kind === 'pointer' ? { kind: 'pointer', sel: i.value } : { kind: 'verb', name: i.value };
+export const sweepInputLabel = (i) => (i.kind === 'key' ? i.value : i.kind === 'pointer' ? `tap ${i.value}` : `${i.value}()`);
+export function parseSweepRun(text) {
+    let v;
+    try {
+        v = JSON.parse(String(text).trim());
+    }
+    catch {
+        return null;
+    }
+    if (!v || v.ran !== true)
+        return null;
+    const u = (k) => (Number.isInteger(v[k]) && v[k] >= 0 ? v[k] : 0);
+    const i = (k) => (Number.isInteger(v[k]) ? v[k] : -1);
+    const s = (k) => (typeof v[k] === 'string' ? v[k] : '');
+    const series = Array.isArray(v.scoreSeries) ? v.scoreSeries.map((x) => (typeof x === 'number' ? x : null)) : [];
+    const climb = climbFraction(series);
+    return {
+        windows: u('windows'), softlock: u('softlock'), firstScoreStep: i('firstScore'), firstFailMs: i('firstFail'),
+        scoreField: s('scoreField'), failField: s('failField'), distinctStates: u('distinct'),
+        scoreClimbFraction: f32(climb === null ? -1 : climb),
+    };
+}
+export function parseSelfTests(text) {
+    const t = String(text ?? '').trim();
+    if (t === 'none' || t === '')
+        return null;
+    let v;
+    try {
+        v = JSON.parse(t);
+    }
+    catch {
+        return null;
+    }
+    if (!v || v.declared !== true || !Array.isArray(v.results))
+        return null;
+    return v.results.map((r) => ({
+        name: typeof r.name === 'string' ? r.name : 'test',
+        pass: r.pass === true,
+        error: typeof r.error === 'string' ? r.error : '',
+    }));
+}
+export function parseRenderHealth(text) {
+    let v;
+    try {
+        v = JSON.parse(String(text).trim());
+    }
+    catch {
+        return null;
+    }
+    if (!v || typeof v !== 'object')
+        return null;
+    const b = (k) => v[k] === true;
+    const n = (k) => (Number.isInteger(v[k]) ? v[k] : -1);
+    return {
+        canvas_observed: b('canvas_observed'), canvas_claimed: b('canvas_claimed'),
+        canvas_width: n('canvas_width'), canvas_height: n('canvas_height'),
+        context_loss_observed: b('context_loss_observed'), context_lost: b('context_lost'),
+        key_parity_observed: b('key_parity_observed'),
+        unreachable_keys: Array.isArray(v.unreachable_keys) ? v.unreachable_keys.filter((s) => typeof s === 'string') : [],
+        touch_controls_found: Number.isInteger(v.touch_controls_found) && v.touch_controls_found >= 0 ? v.touch_controls_found : 0,
+    };
+}
+export function parseAudio(text, driven) {
+    let v;
+    try {
+        v = JSON.parse(String(text).trim());
+    }
+    catch {
+        return null;
+    }
+    if (!v || typeof v !== 'object')
+        return null;
+    const n = (k) => (Number.isInteger(v[k]) && v[k] >= 0 ? v[k] : 0);
+    const s = (k) => (typeof v[k] === 'string' ? v[k] : '');
+    return {
+        observed: v.observed === true, declared: v.declared === true, driven,
+        contexts: n('contexts'), context_state: s('context_state'), resumes: n('resumes'),
+        sources_started: n('sources_started'), media_plays: n('media_plays'),
+        destination_connections: n('destination_connections'), cues: s('cues'),
+    };
+}
+export function gateVerdicts(report) {
+    const out = report.results.map((r) => ({ what: r.mechanic, pass: r.reached, reason: r.reason }));
+    for (const t of report.self_tests)
+        out.push({ what: `self-test \`${t.name}\``, pass: t.pass, reason: t.error });
+    const h = report.render_health;
+    if (h && h.canvas_observed && !h.canvas_claimed) {
+        out.push({ what: 'the canvas was claimed by a renderer', pass: false, reason: `the canvas is still at the ${h.canvas_width}x${h.canvas_height} HTML default — no renderer ever sized it, so nothing was ever drawn into it` });
+    }
+    if (h && h.context_loss_observed && h.context_lost) {
+        out.push({ what: 'the graphics context survived the run', pass: false, reason: 'the page fired a context-lost event — the renderer is dead while the loop keeps running' });
+    }
+    const a = report.audio;
+    if (a && a.observed && a.declared && a.driven) {
+        const played = (a.sources_started ?? 0) + (a.media_plays ?? 0) > 0;
+        out.push({
+            what: 'the game made sound', pass: played,
+            reason: played ? '' : 'it declares sound (__FPX_AUDIO__) but started none while the probe played it — nothing was created, started or played (a context never resumed on the first input, a muted master, sounds never wired to the events)',
+        });
+    }
+    return [...out, ...healthGates(report)];
+}
+export function overallVerdict(report) {
+    const gates = gateVerdicts(report);
+    if (gates.some((g) => !g.pass))
+        return 'fail';
+    if (gates.length === 0)
+        return 'not_observed';
+    return 'pass';
+}

package/dist/verify/players.js

@@ -0,0 +1,123 @@
+import { pageScript } from '../vendor/verify/src/index.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const JOIN_MS = 10_000;
+export function gameFrame(page) {
+    return page.frames().find((f) => f !== page.mainFrame()) ?? page.mainFrame();
+}
+export async function openPlayer(browser, url, player) {
+    const page = await (await browser.newContext({ viewport: { width: 1280, height: 720 } })).newPage();
+    const tab = { page, userId: '', room: '', host: false, data: [], hostChanged: [], errors: [] };
+    page.on('websocket', (ws) => ws.on('framereceived', ({ payload }) => {
+        let m;
+        try {
+            m = JSON.parse(String(payload));
+        }
+        catch {
+            return;
+        }
+        if (m.type === 'Authenticated')
+            tab.userId = m.user_id;
+        else if (m.type === 'RoomJoined' || m.type === 'RoomCreated') {
+            tab.room = m.room_code;
+            tab.host = !!m.is_host;
+        }
+        else if (m.type === 'Data')
+            tab.data.push({ from: m.sender_id, data: m.data, t: Date.now() });
+        else if (m.type === 'HostChanged')
+            tab.hostChanged.push(m.player_id);
+        else if (m.type === 'Error')
+            tab.errors.push(`${m.code}: ${m.message}`);
+    }));
+    await page.goto(`${url}?player=${player}`, { waitUntil: 'load' });
+    await gameFrame(page).evaluate(`(${pageScript('enter_view')})()`).catch(() => { });
+    for (let t = 0; t < JOIN_MS && !tab.room && !tab.errors.length; t += 100)
+        await sleep(100);
+    return tab;
+}
+async function numbers(tab) {
+    return gameFrame(tab.page).evaluate(`(() => { try { const s = window.__FPX_STATE__?.(); if (!s || typeof s !== 'object') return null;
+    const o = {}; for (const [k, v] of Object.entries(s)) if (typeof v === 'number' && isFinite(v)) o[k] = v; return o; } catch { return null; } })()`).catch(() => null);
+}
+async function act(tab) {
+    const game = gameFrame(tab.page);
+    const verbs = (await game.evaluate('Object.keys(window.__FPX_VERBS__ ?? {})').catch(() => []));
+    const keys = (await game.evaluate('Object.keys(window.__FPX_KEYS__ ?? {})').catch(() => []));
+    for (let i = 0; i < 3; i++) {
+        if (verbs.length)
+            await game.evaluate(`(() => { for (const v of Object.values(window.__FPX_VERBS__)) try { v(); } catch {} })()`);
+        else if (keys.length)
+            for (const k of keys.slice(0, 4))
+                await tab.page.keyboard.press(k).catch(() => { });
+        else
+            await tab.page.mouse.click(640, 360);
+        await sleep(300);
+    }
+    return verbs.length ? `verbs ${verbs.join(', ')}` : keys.length ? `keys ${keys.slice(0, 4).join(', ')}` : 'a tap';
+}
+const fromHost = (tab, host, since) => tab.data.filter((d) => d.from === host && d.t >= since && !String(d.data?._evt ?? '').startsWith('_state'));
+export async function twoPlayers(browser, playUrl) {
+    const steps = [];
+    const step = (what, verdict, reason = '') => steps.push({ what, verdict, reason });
+    const tabs = [];
+    try {
+        const host = await openPlayer(browser, playUrl, 'host');
+        tabs.push(host);
+        const guest = await openPlayer(browser, playUrl, 'guest');
+        tabs.push(guest);
+        const refused = [...host.errors, ...guest.errors];
+        if (!host.room || !guest.room) {
+            step('both players join', refused.length ? 'fail' : 'not_observed', refused.length ? `the relay refused: ${refused[0]}`
+                : `${!host.room ? 'the first' : 'the second'} tab opened no room in ${JOIN_MS / 1000} s — the game must join on load or in its play view (Room.autoJoin(getGameKey()))`);
+            return steps;
+        }
+        if (host.room !== guest.room) {
+            step('both players join', 'not_observed', `they landed in different rooms (${host.room}, ${guest.room}) — verify pairs players through quick-match (Room.autoJoin), not room codes`);
+            return steps;
+        }
+        step('both players join', host.host && !guest.host ? 'pass' : 'fail', host.host && !guest.host ? `room ${host.room}` : 'the room does not have exactly one host');
+        const idle0 = await numbers(guest);
+        await sleep(1500);
+        const idle1 = await numbers(guest);
+        const quiet = idle0 && idle1 ? Object.keys(idle1).filter((k) => idle0[k] === idle1[k]) : [];
+        const since = Date.now();
+        const pressed = await act(host);
+        await sleep(1500);
+        const after = await numbers(guest);
+        const got = fromHost(guest, host.userId, since);
+        const moved = idle1 && after ? quiet.filter((k) => k in after && after[k] !== idle1[k]) : [];
+        if (!got.length)
+            step('the guest sees the host act', 'fail', `the host pressed ${pressed}; the guest received nothing from it`);
+        else if (!idle1)
+            step('the guest sees the host act', 'not_observed', `${got.length} message(s) arrived, but the guest has no __FPX_STATE__ to show a change`);
+        else if (!moved.length)
+            step('the guest sees the host act', 'fail', `${got.length} message(s) arrived after the host pressed ${pressed}, and nothing in the guest's __FPX_STATE__ changed`);
+        else
+            step('the guest sees the host act', 'pass', `${moved.join(', ')} changed on the guest after the host pressed ${pressed}`);
+        const late = await openPlayer(browser, playUrl, 'late');
+        tabs.push(late);
+        if (late.room !== host.room)
+            step('a late joiner gets the state', 'not_observed', late.room ? `it landed in another room (${late.room})` : 'it opened no room');
+        else {
+            for (let t = 0; t < 5000 && !late.data.some((d) => d.data?._evt === '_state_snap' && d.data?.to === late.userId); t += 100)
+                await sleep(100);
+            const snap = late.data.some((d) => d.data?._evt === '_state_snap' && d.data?.to === late.userId);
+            const sync = late.data.some((d) => d.from === host.userId && d.data?._sync);
+            step('a late joiner gets the state', snap || sync ? 'pass' : 'fail', snap ? "the host's snapshot arrived" : sync ? 'by the host\'s sync stream (no snapshot)' : 'no snapshot in 5 s — the host must call room.provideState(() => world)');
+        }
+        await host.page.context().close();
+        tabs.shift();
+        for (let t = 0; t < 5000 && !guest.hostChanged.length; t += 100)
+            await sleep(100);
+        step('the room survives the host leaving', guest.hostChanged.length ? 'pass' : 'fail', guest.hostChanged.length ? `the relay handed host to ${guest.hostChanged[0] === guest.userId ? 'the guest' : 'the late joiner'}` : 'the guest was never told of a new host');
+        return steps;
+    }
+    finally {
+        for (const t of tabs)
+            await t.page.context().close().catch(() => { });
+    }
+}
+export function playersVerdict(steps) {
+    if (steps.some((s) => s.verdict === 'fail'))
+        return 'fail';
+    return steps.length && steps.every((s) => s.verdict === 'pass') ? 'pass' : 'not_observed';
+}