@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/feel/judge.js

@@ -0,0 +1,420 @@
+import { MEASURES, unitName } from "./spec.js";
+import { judgeFeedback } from "./feedback.js";
+export const TARGET = { tellMin: 0.5, beat: [0.3, 0.6], restartMax: 2, noBeat: 0.1 };
+export const TOLERANCE = 0.15;
+const TELL = /tell|wind|warn|telegraph|charge|aim|crack|glow|shadow|mark/i;
+const STRIKE = /strike|attack|active|hit|fire|slam|shoot|burst|fall|land|bite|swing/i;
+const DASH = /dash|roll|dodge|evade|blink|lunge/i;
+const DEAD = /dead|die|dying|death|\bko\b|killed/i;
+const LOSS = /lost|lose|over|dead|fail|died|defeat|retry/i;
+const PLAYER = /player|hero|avatar/i;
+const r2 = (n) => Math.round(n * 100) / 100;
+const r3 = (n) => Math.round(n * 1000) / 1000;
+const median = (xs) => { const s = [...xs].sort((a, b) => a - b); return s.length ? s[Math.floor((s.length - 1) / 2)] : NaN; };
+const secs = (ms) => ms / 1000;
+const num = (x) => typeof x === 'number' && Number.isFinite(x);
+export function segments(samples, on) {
+    const out = [];
+    let start = -1;
+    samples.forEach((x, i) => {
+        const yes = !!x.s && on(x.s);
+        if (yes && start < 0)
+            start = i;
+        if (!yes && start >= 0) {
+            out.push({ from: x.t, to: x.t, i0: start, i1: i });
+            start = -1;
+        }
+    });
+    if (start >= 0)
+        out.push({ from: samples[start].t, to: samples.at(-1).t, i0: start, i1: samples.length - 1 });
+    return out.map((g) => ({ ...g, from: samples[g.i0].t }));
+}
+const airborne = (s) => {
+    const h = s.hero;
+    if (!h)
+        return false;
+    if (typeof h.grounded === 'boolean')
+        return !h.grounded;
+    return typeof h.state === 'string' && /jump|hop|air|fall|leap/i.test(h.state);
+};
+export function gameClock(trace) {
+    const S = trace.samples;
+    const withT = S.filter((x) => num(x.s?.t));
+    if (!withT.length)
+        return { trace, clock: 'wall' };
+    if (withT.length < S.filter((x) => x.s).length * 0.9)
+        return { trace, clock: 'wall', note: 'state t is missing on some frames: the page\'s clock is used' };
+    const out = [];
+    let g = 0, lastT = null, odd = 0;
+    for (let i = 0; i < S.length; i++) {
+        const t = S[i].s?.t, wall = i ? S[i].t - S[i - 1].t : 0;
+        const d = num(t) && lastT !== null ? (t - lastT) * 1000 : NaN;
+        const fits = d >= 0 && d <= Math.max(250, 4 * wall);
+        if (i && !fits)
+            odd++;
+        g += i === 0 ? 0 : fits ? d : Math.min(wall, 100);
+        if (num(t))
+            lastT = t;
+        out.push({ ...S[i], t: Math.round(g * 10) / 10 });
+    }
+    const wallSpan = S.at(-1).t - S[0].t, gameSpan = out.at(-1).t;
+    if (wallSpan > 500 && (odd > S.length * 0.1 || gameSpan < wallSpan * 0.2 || gameSpan > wallSpan * 5))
+        return { trace, clock: 'wall', note: `state t moved ${Math.round(gameSpan)} ms over ${Math.round(wallSpan)} ms of the page's clock: not seconds, so the page's clock is used` };
+    const onGame = (wallT) => { const k = S.findIndex((x) => x.t >= wallT); return k < 0 ? out.at(-1).t : out[k].t; };
+    const inputs = trace.inputs.map((x) => ({ ...x, t: onGame(x.t), ...(x.t1 !== undefined ? { t1: onGame(x.t1) } : {}) }));
+    return { trace: { ...trace, samples: out, inputs }, clock: 'game' };
+}
+export function measure(trace) {
+    const S = trace.samples;
+    const heroes = S.map((x) => x.s?.hero).filter((h) => !!h);
+    const body = heroes.map((h) => h.body).find((b) => num(b) && b > 0) ?? null;
+    const unit = body ? 'body' : unitName(heroes.map((h) => h.unit).find((u) => typeof u === 'string')) ?? 'unit';
+    const scale = (d) => (body ? d / body : d);
+    const long_frames = S.slice(1).map((x, i) => ({ at: r2(secs(S[i].t - S[0].t)), ms: Math.round(x.t - S[i].t) })).filter((f) => f.ms > 50);
+    const jumps = [];
+    for (const g of segments(S, airborne)) {
+        const y0 = S[Math.max(0, g.i0 - 1)].s?.hero?.y;
+        if (!num(y0))
+            continue;
+        const pts = S.slice(g.i0, g.i1 + 1).map((x) => ({ t: x.t, y: x.s?.hero?.y })).filter((p) => num(p.y));
+        const first = pts.find((p) => Math.abs(p.y - y0) > 1e-6);
+        if (!first)
+            continue;
+        const sgn = Math.sign(first.y - y0);
+        const rise = pts.map((p) => sgn * (p.y - y0));
+        const peak = Math.max(...rise), at = rise.indexOf(peak);
+        if (!(peak > 0) || !rise.slice(at).some((r) => r <= 0.75 * peak))
+            continue;
+        let hang = 0;
+        for (let i = 0; i + 1 < pts.length; i++)
+            if (rise[i] >= 0.9 * peak)
+                hang += pts[i + 1].t - pts[i].t;
+        jumps.push({ at: r2(secs(g.from - S[0].t)), height: r3(scale(peak)), airtime: r3(secs(g.to - g.from)), apex_hang: r3(secs(hang)) });
+    }
+    let run = null;
+    const bursting = (s) => !!s?.hero && ((typeof s.hero.state === 'string' && DASH.test(s.hero.state)) || s.hero.invulnerable === true);
+    const vs = S.filter((x) => !bursting(x.s)).map((x) => ({ t: x.t, v: x.s?.hero?.vx })).filter((p) => num(p.v));
+    if (vs.length >= 10) {
+        const abs = vs.map((p) => Math.abs(p.v)).sort((a, b) => a - b);
+        const top = abs[Math.floor(0.95 * (abs.length - 1))];
+        const times = [];
+        let rest = null;
+        for (const p of vs) {
+            const a = Math.abs(p.v);
+            if (a < 0.05 * top)
+                rest = p.t;
+            else if (rest !== null && a >= 0.9 * top) {
+                times.push(secs(p.t - rest));
+                rest = null;
+            }
+        }
+        if (top > 0)
+            run = { top_speed: r3(scale(top)), time_to_top: times.length ? r3(median(times)) : null };
+    }
+    const dashSegs = segments(S, (s) => typeof s.hero?.state === 'string' && DASH.test(s.hero.state));
+    const pos = (i) => S[i].s?.hero;
+    const dashes = dashSegs.map((g) => {
+        const a = pos(g.i0), b = pos(Math.min(g.i1, S.length - 1));
+        const d = a && b && num(a.x) && num(b.x) ? Math.hypot(b.x - a.x, (num(b.y) && num(a.y) ? b.y - a.y : 0)) : NaN;
+        const time = secs(g.to - g.from);
+        return { at: r2(secs(g.from - S[0].t)), distance: r3(scale(d)), time: r3(time), speed: time > 0 ? r3(scale(d) / time) : NaN };
+    });
+    const verbSegs = dashSegs.length >= 2 ? dashSegs : segments(S, airborne);
+    let cooldown = null;
+    for (let k = 0; k + 1 < verbSegs.length; k++) {
+        const gap = secs(verbSegs[k + 1].from - verbSegs[k].to);
+        const input = trace.inputs.find((i) => i.t < verbSegs[k + 1].from - 20 && (i.t1 ?? i.t) > verbSegs[k].to);
+        const times = Number(/\bpress \S+ (\d+)/.exec(input?.label ?? '')?.[1] ?? 0);
+        const resolution = input && input.t1 !== undefined && times > 1 ? r3(secs(input.t1 - input.t) / times) : 0.1;
+        const pressed = !!input;
+        if (!cooldown || (pressed && !cooldown.pressed) || (pressed === cooldown.pressed && gap < cooldown.gap))
+            cooldown = { verb: dashSegs.length >= 2 ? 'dash' : 'jump', gap: r3(gap), pressed, resolution };
+    }
+    const exposed = heroes.some((h) => typeof h.invulnerable === 'boolean');
+    const inv = segments(S, (s) => s.hero?.invulnerable === true);
+    const verbStarts = [...dashSegs, ...segments(S, airborne)].map((g) => g.from);
+    const at_verb = [], after_hit = [];
+    let tail = null;
+    for (const g of inv) {
+        const d = r3(secs(g.to - g.from));
+        const v = verbStarts.find((t) => Math.abs(t - g.from) <= 50);
+        if (v !== undefined) {
+            at_verb.push(d);
+            const seg = [...dashSegs, ...segments(S, airborne)].find((x) => x.from === v);
+            tail ??= r3(Math.max(0, secs(seg.to - seg.from) - d));
+        }
+        else
+            after_hit.push(d);
+    }
+    const tells = [];
+    let untold = 0, strikes = 0;
+    const phase = new Map(), tellAt = new Map();
+    for (const x of S) {
+        for (const th of x.s?.threats ?? []) {
+            const p = th.phase ?? '', was = phase.get(th.id);
+            if (p === was)
+                continue;
+            phase.set(th.id, p);
+            if (TELL.test(p))
+                tellAt.set(th.id, x.t);
+            else if (STRIKE.test(p)) {
+                strikes++;
+                const t0 = tellAt.get(th.id);
+                if (t0 === undefined)
+                    untold++;
+                else
+                    tells.push({ kind: th.kind ?? th.id.replace(/[-_#]?\d+$/, ''), tell: r3(secs(x.t - t0)) });
+                tellAt.delete(th.id);
+            }
+            else
+                tellAt.delete(th.id);
+        }
+    }
+    const isDead = (s) => s.dead === true || (typeof s.hero?.state === 'string' && DEAD.test(s.hero.state));
+    const screens = S.filter((x) => x.s && x.s.hero && !isDead(x.s) && typeof x.s.screen === 'string').map((x) => x.s.screen);
+    const count = new Map();
+    for (const sc of screens)
+        count.set(sc, (count.get(sc) ?? 0) + 1);
+    const play = [...count].sort((a, b) => b[1] - a[1])[0]?.[0];
+    const control = (s) => (typeof s.control === 'boolean' ? s.control && !isDead(s) : !isDead(s) && (play === undefined || s.screen === play));
+    const deaths = [];
+    const playerNames = trace.names.filter((n) => PLAYER.test(n));
+    for (let i = 1; i < S.length; i++) {
+        const a = S[i - 1].s, b = S[i].s;
+        if (!a || !b)
+            continue;
+        const flagged = isDead(b) && !isDead(a);
+        const cutToCard = !isDead(a) && !isDead(b) && play !== undefined && a.screen === play && typeof b.screen === 'string' && b.screen !== play && LOSS.test(b.screen);
+        if (!flagged && !cutToCard)
+            continue;
+        const onset = S[i].t;
+        let cutAt = null, cut = null, back = null;
+        for (let j = i; j < S.length; j++) {
+            const s = S[j].s;
+            if (!s)
+                continue;
+            if (cutAt === null && play !== undefined && typeof s.screen === 'string' && s.screen !== play) {
+                cutAt = S[j].t;
+                cut = 'card';
+            }
+            if (j > i && control(s)) {
+                back = S[j].t;
+                if (cutAt === null) {
+                    cutAt = back;
+                    cut = 'in place';
+                }
+                break;
+            }
+        }
+        const lastInput = back === null ? undefined : [...trace.inputs].reverse().find((x) => x.t <= back && x.t >= onset);
+        let hero_changed = null;
+        const who = playerNames.find((n) => S.some((x) => x.v[n]));
+        if (flagged && who && cutAt !== null) {
+            const before = new Set(S.filter((x) => x.t >= onset - 1000 && x.t < onset).map((x) => x.v[who]).filter(Boolean));
+            const during = S.filter((x) => x.t >= onset && x.t < cutAt).map((x) => x.v[who]).filter(Boolean);
+            if (before.size && during.length)
+                hero_changed = during.some((k) => !before.has(k));
+        }
+        deaths.push({
+            at: r2(secs(onset - S[0].t)), beat: flagged && cutAt !== null ? r3(secs(cutAt - onset)) : cutToCard ? 0 : null, cut,
+            restart: back === null ? null : r3(secs(back - onset)), after_input: lastInput ? r3(secs(back - lastInput.t)) : null, hero_changed,
+        });
+        while (i < S.length && !(S[i].s && control(S[i].s) && S[i].t >= (back ?? Infinity)))
+            i++;
+    }
+    const looks = new Map();
+    for (const x of S) {
+        if (!x.s)
+            continue;
+        const named = { ...(x.s.actors ?? {}) };
+        if (!x.s.actors && typeof x.s.hero?.state === 'string')
+            for (const n of Object.keys(x.v))
+                if (PLAYER.test(n))
+                    named[n] = x.s.hero.state;
+        for (const [name, st] of Object.entries(named)) {
+            const key = x.v[name];
+            if (!key)
+                continue;
+            const byState = looks.get(name) ?? new Map();
+            const keys = byState.get(st) ?? new Map();
+            keys.set(key, (keys.get(key) ?? 0) + 1);
+            byState.set(st, keys);
+            looks.set(name, byState);
+        }
+    }
+    const actors = [...looks].map(([name, byState]) => ({
+        name,
+        states: Object.fromEntries([...byState].map(([st, keys]) => {
+            const main = [...keys].sort((a, b) => b[1] - a[1])[0][0];
+            return [st, { samples: [...keys.values()].reduce((a, b) => a + b, 0), looks: keys.size, main }];
+        })),
+    }));
+    return { unit, body, clock: 'wall', windows: {}, long_frames, jumps, run, dashes, cooldown, invulnerable: { at_verb, after_hit, tail, exposed }, tells, untold, strikes, deaths, actors };
+}
+export function actual(m, id, label = '') {
+    const med = (xs) => (xs.length ? r3(median(xs)) : null);
+    switch (id) {
+        case 'jump_height': return med(m.jumps.map((j) => j.height));
+        case 'airtime': return med(m.jumps.map((j) => j.airtime));
+        case 'apex_hang': return med(m.jumps.map((j) => j.apex_hang));
+        case 'top_speed': return m.run?.top_speed ?? null;
+        case 'time_to_top_speed': return m.run?.time_to_top ?? null;
+        case 'dash_distance': return med(m.dashes.map((d) => d.distance).filter(Number.isFinite));
+        case 'dash_time': return med(m.dashes.map((d) => d.time));
+        case 'dash_speed': return med(m.dashes.map((d) => d.speed).filter(Number.isFinite));
+        case 'invulnerable': return /hit|hurt|damage|after/i.test(label) ? med(m.invulnerable.after_hit) : med(m.invulnerable.at_verb) ?? med(m.invulnerable.after_hit);
+        case 'cooldown': return m.cooldown?.pressed ? m.cooldown.gap : null;
+        case 'tell': return med(m.tells.map((t) => t.tell));
+        case 'death_beat': return med(m.deaths.map((d) => d.beat).filter(num));
+        case 'restart': return med(m.deaths.map((d) => d.restart).filter(num));
+        case 'coyote':
+        case 'buffer': return m.windows[id]?.window ?? null;
+        default: return null;
+    }
+}
+const fmt = (v, dim, unit) => (dim === 'time' ? `${r3(v)} s` : `${r3(v)} ${unit}${dim === 'speed' ? '/s' : ''}`);
+export function judgeSpec(m, rows) {
+    return rows.map((r) => {
+        const id = `spec:${r.id}`, area = r.id === 'tell' ? 'telegraph' : r.id === 'death_beat' || r.id === 'restart' ? 'death' : 'verb';
+        const said = `${r.label} (${r.source}: ${r.text})`;
+        if ((r.id === 'coyote' || r.id === 'buffer') && !m.windows[r.id])
+            return { id, area, state: 'not measured', says: `${said}: one run cannot read a forgiveness window back, and the script has no sweeps.${r.id}`, next: `add sweeps.${r.id} to test/feel.json (timed attempts across runs; skill funpixel-game-feel, references/measure.md), or pin it in the rules tests` };
+        if (!r.value)
+            return { id, area, state: 'not measured', says: `${said}: no number with a unit to compare (s, ms, frames, body heights, px…)` };
+        if (r.value.dim !== MEASURES[r.id].dim)
+            return { id, area, state: 'not measured', says: `${said}: a ${r.value.dim}, where ${MEASURES[r.id].says} is a ${MEASURES[r.id].dim}` };
+        const got = actual(m, r.id, r.label);
+        if (got === null) {
+            const why = r.id === 'cooldown' && m.cooldown ? `the script did not press during the gap (the next came ${m.cooldown.gap} s later)` : 'the trace shows none';
+            return { id, area, state: 'not measured', says: `${said}: ${why}` };
+        }
+        if (r.value.dim !== 'time' && r.value.unit !== m.unit)
+            return { id, area, state: 'not measured', says: `${said}: measured ${fmt(got, r.value.dim, m.unit)} — the state reports ${m.unit}, the design ${r.value.unit}`, next: r.value.unit === 'body' ? 'expose hero.body (the hero\'s height in the state\'s units) to read it in body heights' : `expose hero.unit: '${r.value.unit}'` };
+        const slack = r.value.dim === 'time' ? ((r.id === 'coyote' || r.id === 'buffer') ? 2 : 1) / 60 : r.value.unit === 'body' ? 0.05 : 0;
+        const w = r.id === 'coyote' || r.id === 'buffer' ? m.windows[r.id] : undefined;
+        const late = r.id === 'cooldown' && m.cooldown ? Math.max(slack, m.cooldown.resolution) : w?.fails_from !== null && w?.fails_from !== undefined ? Math.max(slack, w.fails_from - w.window) : slack;
+        const lo = r.value.lo * (1 - TOLERANCE) - slack, hi = r.value.hi * (1 + TOLERANCE) + late;
+        const want = r.value.hi === Infinity ? `≥ ${fmt(r.value.lo, r.value.dim, r.value.unit)}` : r.value.lo === 0 && r.value.hi > 0 && r.text.match(/≤|<|under|below|at most|up to|less/) ? `≤ ${fmt(r.value.hi, r.value.dim, r.value.unit)}` : r.value.lo === r.value.hi ? fmt(r.value.lo, r.value.dim, r.value.unit) : `${fmt(r.value.lo, r.value.dim, r.value.unit)}–${fmt(r.value.hi, r.value.dim, r.value.unit)}`;
+        const range = w ? ` (${w.took ? `took at ${w.window} s` : 'no offset took'}, ${w.fails_from === null ? 'every offset tried took' : `missed from ${w.fails_from} s`}, ${w.attempts.length} runs on the ${w.clock === 'game' ? 'game\'s' : 'page\'s'} clock${w.gaps ? '; not one stretch: a later offset took again' : ''})` : '';
+        if (got >= lo && got <= hi)
+            return { id, area, state: 'ok', says: `${MEASURES[r.id].says}: design ${want}, measured ${fmt(got, r.value.dim, m.unit)}${range}` };
+        const edge = got < lo ? r.value.lo : r.value.hi, gap = got - edge;
+        return {
+            id, area, state: 'note',
+            says: `${MEASURES[r.id].says}: design ${want}, measured ${fmt(got, r.value.dim, m.unit)} (${gap > 0 ? '+' : ''}${fmt(gap, r.value.dim, m.unit)}${edge ? `, ${gap > 0 ? '+' : ''}${Math.round((100 * gap) / edge)}%` : ''})${range}`,
+            next: `change the code or the design so they agree; the number the player feels is the measured one${hitch(m)}`,
+        };
+    });
+}
+const hitch = (m) => {
+    if (!m.long_frames.length || m.clock === 'game')
+        return '';
+    const worst = m.long_frames.reduce((a, b) => (b.ms > a.ms ? b : a));
+    return ` (this trace has ${m.long_frames.length} frame(s) over 50 ms, the longest ${worst.ms} ms at ${worst.at} s: a time window holding one reads long; run it again)`;
+};
+export function judgeTelegraph(m, sawThreats) {
+    const out = [];
+    if (!sawThreats)
+        return [{ id: 'tell', area: 'telegraph', state: 'not measured', says: '__FPX_STATE__ listed no threats on any frame, so no tell, strike or defensive window could be read', next: THREATS_NEXT }];
+    if (!m.strikes)
+        out.push({ id: 'tell', area: 'telegraph', state: 'not measured', says: 'threats seen, none struck during the script: tell to strike never measured', next: 'let the script stand in a threat\'s path until it strikes' });
+    else {
+        const kinds = [...new Set(m.tells.map((t) => t.kind))];
+        for (const k of kinds) {
+            const ts = m.tells.filter((t) => t.kind === k).map((t) => t.tell), lo = Math.min(...ts), md = r3(median(ts));
+            const says = `${k}: tell to strike ${md} s (shortest ${lo} s over ${ts.length})`;
+            out.push(lo < TARGET.tellMin
+                ? { id: `tell:${k}`, area: 'telegraph', state: 'note', says: `${says} — under ${TARGET.tellMin} s, research 18's target (ours: 0.5–0.8 s)`, next: 'a longer or louder wind-up (shape, sound, pose), or a slower strike; for reference Slay the Spire shows every enemy\'s next action and damage a whole turn ahead' }
+                : { id: `tell:${k}`, area: 'telegraph', state: 'ok', says });
+        }
+        if (m.untold)
+            out.push({ id: 'tell:untold', area: 'telegraph', state: 'note', says: `${m.untold} of ${m.strikes} strikes came with no tell phase before them`, next: 'give every hit a readable warning, or name its tell phase in threats[].phase' });
+    }
+    const safe = m.invulnerable.at_verb, dash = m.dashes.length;
+    if (safe.length) {
+        out.push({ id: 'defence', area: 'telegraph', state: 'ok', says: `defensive verb: invulnerable ${r3(median(safe))} s from its start${m.invulnerable.tail !== null ? `, then ${m.invulnerable.tail} s committed and open` : ''} (for reference Gungeon's dodge roll lasts about 0.7 s, invulnerable for its first half)` });
+    }
+    else if (dash && !m.invulnerable.exposed) {
+        out.push({ id: 'defence', area: 'telegraph', state: 'not measured', says: `${dash} dash(es) seen; the state has no hero.invulnerable, so the safe window is not measured` });
+    }
+    else if (m.strikes) {
+        out.push({ id: 'defence', area: 'telegraph', state: 'note', says: `no defensive verb seen: ${dash ? 'the dash opened no invulnerable window' : 'no dash or roll state, and no invulnerable window opened at a verb'} while threats struck`, next: 'a verb with a safe window and a committed tail (a roll, a hop, a parry) turns a hit into a choice; or say in the design why stepping away is the whole answer' });
+    }
+    return out;
+}
+export const THREATS_NEXT = 'expose threats: [{ id, kind, phase }] in __FPX_STATE__ (phase names the tell and the strike, e.g. "windup" then "strike"), then let the script stand in one\'s path and retry';
+export function judgeDeath(m, sawState, sawThreats = true) {
+    if (!sawState)
+        return [{ id: 'death', area: 'death', state: 'not measured', says: 'no __FPX_STATE__: death and restart never measured' }];
+    if (!m.deaths.length && !sawThreats)
+        return [{ id: 'death', area: 'death', state: 'not measured', says: 'no death in the script, and __FPX_STATE__ listed no threats on any frame: nothing the trace could see could end the run, so the death beat and the time back to control were not measured', next: THREATS_NEXT }];
+    if (!m.deaths.length)
+        return [{ id: 'death', area: 'death', state: 'not measured', says: 'no death in the script (state dead: true, hero.state "dead", or the play screen cutting to a lost card)', next: 'let the script lose once (stand in a threat\'s path), then retry' }];
+    const d = m.deaths[0], out = [];
+    const of = m.deaths.length > 1 ? ` (first of ${m.deaths.length})` : '';
+    if (d.beat === null)
+        out.push({ id: 'death:beat', area: 'death', state: 'not measured', says: `death at ${d.at} s${of}: the trace ends before the cut` });
+    else if (d.beat < TARGET.noBeat)
+        out.push({ id: 'death:beat', area: 'death', state: 'note', says: `no death beat${of}: the hit cuts straight to the ${d.cut ?? 'card'} (${d.beat} s)`, next: `a readable beat of ${TARGET.beat[0]}–${TARGET.beat[1]} s (research 18's target, ours): the hero's death pose, a freeze, the cause shown; then the card` });
+    else if (d.hero_changed === false)
+        out.push({ id: 'death:beat', area: 'death', state: 'note', says: `a ${d.beat} s pause before the ${d.cut}${of}, but the hero looks as it did the second before`, next: 'a pause is not a beat: a death pose, a flash or a topple so the player sees what happened' });
+    else
+        out.push({ id: 'death:beat', area: 'death', state: 'ok', says: `death beat ${d.beat} s before the ${d.cut}${of}${d.hero_changed ? ', the hero changes pose' : ''}` });
+    if (d.restart === null)
+        out.push({ id: 'death:restart', area: 'death', state: 'not measured', says: 'control never came back during the script', next: 'end the script with a retry step (retry press Space) so the time back to control is measured' });
+    else {
+        const wait = d.after_input !== null ? `; ${d.after_input} s after the last input` : '';
+        out.push(d.restart > TARGET.restartMax
+            ? { id: 'death:restart', area: 'death', state: 'note', says: `death to control again ${d.restart} s${wait} — over ${TARGET.restartMax} s (research 18's target, ours; Celeste respawns in about a second, estimated)`, next: 'a retry that accepts input at once, fewer screens between death and play, a quick fade instead of a long one' }
+            : { id: 'death:restart', area: 'death', state: 'ok', says: `death to control again ${d.restart} s${wait}` });
+    }
+    return out;
+}
+export function judgeLooks(m) {
+    if (!m.actors.length)
+        return [{ id: 'looks', area: 'animation', state: 'not measured', says: 'no actor both named in the state and found in the scene (actors: { nodeName: stateName }, or hero.state for a node named player)' }];
+    return m.actors.map((a) => {
+        const id = `looks:${a.name}`;
+        const all = Object.entries(a.states), seen = all.filter(([, v]) => v.samples >= 3), brief = all.filter(([, v]) => v.samples < 3).map(([k]) => k);
+        const also = brief.length ? `; seen too briefly to judge: ${brief.join(', ')}` : '';
+        if (seen.length < 2)
+            return { id, area: 'animation', state: 'not measured', says: `${a.name}: seen in ${seen.length ? `one state (${seen[0][0]})` : 'no state for long enough'}${also}`, next: 'let the script take it through its states (move, act, get hurt)' };
+        const mains = new Set(seen.map(([, v]) => v.main));
+        const names = seen.map(([k]) => k).join(', ');
+        if (mains.size === 1)
+            return { id, area: 'animation', state: 'note', says: `${a.name}: one look across ${seen.length} states (${names})${also}`, next: 'a pose or frame per state, fewest keys that read (Dead Cells\' pose-to-pose; Celeste stretches its hero to 0.6×1.4 on a jump)' };
+        const shared = seen.filter(([k, v]) => seen.some(([k2, v2]) => k2 !== k && v2.main === v.main)).map(([k]) => k);
+        return { id, area: 'animation', state: 'ok', says: `${a.name}: ${mains.size} looks across ${seen.length} states${shared.length ? ` (${shared.join(', ')} share one)` : ''}${also}` };
+    });
+}
+export function judgeVerb(m, rows) {
+    const out = [];
+    const u = m.unit === 'body' ? 'body' : m.unit;
+    if (m.jumps.length) {
+        const j = m.jumps;
+        out.push({ id: 'verb:jump', area: 'verb', state: 'ok', says: `${j.length} jump(s): height ${r3(median(j.map((x) => x.height)))} ${u}, ${r3(median(j.map((x) => x.airtime)))} s in the air, apex hang ${r3(median(j.map((x) => x.apex_hang)))} s` });
+    }
+    if (m.run)
+        out.push({ id: 'verb:run', area: 'verb', state: 'ok', says: `top speed ${m.run.top_speed} ${u}/s (dash and invulnerable frames left out)${m.run.time_to_top !== null ? `, reached in ${m.run.time_to_top} s from rest (Celeste: about 0.09 s, 90 px/s at 1000 px/s²)` : ''}` });
+    if (m.dashes.length) {
+        const sp = m.dashes.map((d) => d.speed).filter(Number.isFinite);
+        out.push({ id: 'verb:dash', area: 'verb', state: 'ok', says: `${m.dashes.length} dash(es): ${r3(median(m.dashes.map((d) => d.distance).filter(Number.isFinite)))} ${u} in ${r3(median(m.dashes.map((d) => d.time)))} s${sp.length ? `, ${r3(median(sp))} ${u}/s` : ''} (Celeste: 0.15 s at 240 px/s, 0.2 s cooldown)` });
+    }
+    if (m.cooldown)
+        out.push({ id: 'verb:cooldown', area: 'verb', state: m.cooldown.pressed ? 'ok' : 'not measured', says: m.cooldown.pressed ? `shortest gap between two ${m.cooldown.verb}s with the key pressed through it: ${m.cooldown.gap} s (to within the script's ${m.cooldown.resolution} s between presses)` : `no press during the gaps between ${m.cooldown.verb}s: the cooldown is not measured` });
+    if (!out.length)
+        out.push({ id: 'verb', area: 'verb', state: 'not measured', says: 'no jump (hero.y with hero.grounded), speed (hero.vx) or dash (hero.state "dash") in the trace', next: 'expose hero { x, y, grounded, state } in __FPX_STATE__ and let the script use the verb' });
+    if (!rows.length)
+        out.push({ id: 'spec', area: 'verb', state: 'not measured', says: 'no design numbers to compare (design/GDD.md "## The numbers": jump height, apex hang, dash distance, invulnerable window, cooldown, tell, restart…)' });
+    return out;
+}
+export function judge(trace, rows, windows = {}) {
+    const clocked = gameClock(trace);
+    const m = { ...measure(clocked.trace), clock: clocked.clock, ...(clocked.note ? { clock_note: clocked.note } : {}), windows };
+    if (clocked.clock === 'game')
+        m.long_frames = measure({ ...trace, inputs: [] }).long_frames;
+    const states = trace.samples.filter((x) => x.s);
+    const sawThreats = states.some((x) => Array.isArray(x.s.threats) && x.s.threats.length > 0);
+    const findings = [...judgeSpec(m, rows), ...judgeVerb(m, rows), ...judgeTelegraph(m, sawThreats), ...judgeDeath(m, states.length > 0, sawThreats), ...judgeLooks(m), ...judgeFeedback(trace)];
+    return { measured: m, findings };
+}

package/dist/feel/run.js

@@ -0,0 +1,185 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { launch, lookPage, viewportUrl, touchSession } from "../verify/browser.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { playerOf } from "../look/player.js";
+import { evalJson, load, openTarget } from "../look/look.js";
+import { gesture } from "../play/input.js";
+import { fieldOf, JOURNEY_DIR, judgeExpect, parseJourneyStep, stepMs } from "../journey/script.js";
+import { rendererOf } from "../verify/gpu.js";
+export const FEEL_SCRIPT = join('test', 'feel.json');
+export const FEEL_LIMITS = { steps: 200, totalMs: 3 * 60_000, untilMs: 10_000, retryMs: 8_000, retryEveryMs: 150 };
+const EXPECT = /^([A-Za-z_][\w.]*)(>=|<=|!=|=|>|<)(.+)$/;
+const lit = (s) => (s === 'true' || s === 'false' ? s === 'true' : /^-?\d+(\.\d+)?$/.test(s) ? Number(s) : s);
+export function parseFeelStep(text, phone) {
+    const t = text.trim();
+    const [head, ...rest] = t.split(/\s+/);
+    if (head === 'until') {
+        const m = EXPECT.exec(rest[0] ?? '');
+        const ms = rest[1] === undefined ? 5000 : Number(rest[1]);
+        if (!m)
+            return `${t}: until FIELD OP VALUE [ms] (screen=playing, dead=true, lives<3)`;
+        if (!Number.isInteger(ms) || ms < 0 || ms > FEEL_LIMITS.untilMs)
+            return `${t}: ms is 0 to ${FEEL_LIMITS.untilMs}`;
+        return { kind: 'until', expect: { field: m[1], op: m[2], value: lit(m[3]) }, ms };
+    }
+    if (head === 'retry') {
+        const s = parseJourneyStep(rest.join(' '), phone);
+        if (typeof s === 'string')
+            return `${t}: retry STEP — ${s}`;
+        if (s.kind === 'mark' || s.kind === 'wait')
+            return `${t}: retry repeats an input (press, tap, hold)`;
+        return { kind: 'retry', step: s, ms: FEEL_LIMITS.retryMs };
+    }
+    return parseJourneyStep(t, phone);
+}
+const NAME = /^[a-z0-9][a-z0-9-]{0,47}$/;
+export function checkFeel(raw, root) {
+    const j = raw;
+    if (!j || typeof j !== 'object')
+        return { problems: ['a feel script is a JSON object'] };
+    let base = j;
+    if (typeof j.journey === 'string') {
+        const file = join(root, JOURNEY_DIR, `${j.journey}.json`);
+        if (!existsSync(file))
+            return { problems: [`journey: no ${file}`] };
+        let journey;
+        try {
+            journey = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            return { problems: [`journey: ${file} is not JSON`] };
+        }
+        base = { ...journey, ...j, steps: [...(journey.steps ?? []), ...(j.steps ?? [])] };
+    }
+    const problems = [];
+    if (base.name !== undefined && (typeof base.name !== 'string' || !NAME.test(base.name)))
+        problems.push('name: lower case, digits and -');
+    if (base.viewport !== 'desktop' && base.viewport !== 'phone')
+        problems.push('viewport: desktop or phone');
+    if (!Number.isInteger(base.seed))
+        problems.push('seed: a whole number (window.__FPX_SEED__)');
+    if (!Array.isArray(base.steps) || !base.steps.length)
+        problems.push('steps: a list of steps');
+    if (base.expect !== undefined && (typeof base.expect !== 'object' || Array.isArray(base.expect)))
+        problems.push('expect: { "jump height": "0.8 body", … }');
+    if (problems.length)
+        return { problems };
+    if (base.steps.length > FEEL_LIMITS.steps)
+        problems.push(`${base.steps.length} steps: a feel script holds ${FEEL_LIMITS.steps}`);
+    const steps = [];
+    base.steps.forEach((text, i) => {
+        const s = typeof text === 'string' ? parseFeelStep(text, base.viewport === 'phone') : `step ${i + 1} is not text`;
+        if (typeof s === 'string')
+            problems.push(`step ${i + 1}: ${s}`);
+        else
+            steps.push(s);
+    });
+    const total = steps.reduce((a, s) => a + (s.kind === 'until' || s.kind === 'retry' ? s.ms : stepMs(s)), 0);
+    if (total > FEEL_LIMITS.totalMs)
+        problems.push(`up to ${Math.round(total / 1000)} s of play: a feel script runs up to ${FEEL_LIMITS.totalMs / 60_000} minutes`);
+    return problems.length ? { problems } : { script: { name: 'feel', ...base }, steps, problems };
+}
+const STATE = `(() => { try { const s = window.__FPX_STATE__ && window.__FPX_STATE__(); return s === undefined ? null : JSON.parse(JSON.stringify(s)); } catch (e) { return null; } })()`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function openFeelPage(browser, t, script, orientation) {
+    const page = await lookPage(browser, script.viewport, orientation);
+    await page.addInitScript(`window.__FPX_SEED__ = ${JSON.stringify(script.seed)};`);
+    await load(page, viewportUrl(t.url, script.viewport), hookMapOf(t.manifest));
+    return page;
+}
+export const orientationOf = (t, script) => script.viewport !== 'phone' ? '' : script.orientation ?? (typeof t.manifest.metadata?.orientation === 'string' ? t.manifest.metadata.orientation : '');
+export async function playSteps(page, script, steps, notes, lost = () => '') {
+    const phone = script.viewport === 'phone';
+    let cdp = null;
+    const touch = async () => (cdp ??= await touchSession(page));
+    const state = () => page.evaluate(STATE).catch(() => null);
+    const play = async (s, label) => {
+        if (s.kind === 'mark') {
+            await evalJson(page, 'feel', { op: 'input', label: `mark ${s.name}` });
+            return;
+        }
+        if (s.kind === 'wait') {
+            await sleep(s.ms);
+            return;
+        }
+        await evalJson(page, 'feel', { op: 'input', label });
+        await gesture(page, touch, phone, s.kind === 'together' ? s.parts : [s]);
+        await evalJson(page, 'feel', { op: 'input', label: 'end' });
+    };
+    let playScreen;
+    for (const [i, s] of steps.entries()) {
+        if (lost())
+            break;
+        const text = (script.steps[i] ?? '').trim();
+        try {
+            if (s.kind === 'until') {
+                const t0 = Date.now();
+                let held = false;
+                while (Date.now() - t0 <= s.ms && !(held = judgeExpect(s.expect, await state()).verdict === 'pass'))
+                    await sleep(40);
+                if (!held)
+                    notes.push(`step ${i + 1} (${text}): never held in ${s.ms} ms; the script went on`);
+                if (held && s.expect.field === 'screen' && s.expect.op === '=')
+                    playScreen ??= s.expect.value;
+            }
+            else if (s.kind === 'retry') {
+                const t0 = Date.now();
+                const back = (st) => st && (typeof st.control === 'boolean' ? st.control : playScreen !== undefined ? fieldOf(st, 'screen') === playScreen : fieldOf(st, 'screen') === 'playing');
+                let tries = 0;
+                while (Date.now() - t0 <= s.ms && !back(await state())) {
+                    await play(s.step, `retry ${text}`);
+                    tries++;
+                    await sleep(FEEL_LIMITS.retryEveryMs);
+                }
+                if (!back(await state()))
+                    notes.push(`step ${i + 1} (${text}): control never came back in ${s.ms} ms (${tries} tries)`);
+            }
+            else
+                await play(s, text);
+        }
+        catch (e) {
+            notes.push(`step ${i + 1} (${text}) did not play: ${String(e?.message ?? e).split('\n')[0]}`);
+            break;
+        }
+    }
+}
+export async function playFeel(root, script, steps) {
+    const t = await openTarget(root);
+    if (typeof t === 'string')
+        return t;
+    const orientation = orientationOf(t, script);
+    const { browser } = await launch(false, true);
+    const errors = [], notes = [];
+    let lost = '';
+    try {
+        browser.on('disconnected', () => { lost ||= 'the browser went away'; });
+        const page = await openFeelPage(browser, t, script, orientation);
+        page.on('pageerror', (e) => errors.push(String(e.message ?? e).slice(0, 300)));
+        page.on('crash', () => { lost ||= 'the browser tab crashed (renderer)'; });
+        const renderer = await rendererOf(page);
+        await evalJson(page, 'feel', { op: 'install', player: playerOf(t.manifest).pattern });
+        await playSteps(page, script, steps, notes, () => lost);
+        await sleep(300);
+        const trace = (await evalJson(page, 'feel', { op: 'drain' }));
+        if (!trace)
+            return 'the page refused the trace recorder';
+        const inputs = [];
+        for (const x of trace.inputs) {
+            if (x.label === 'end') {
+                const last = inputs.at(-1);
+                if (last && last.t1 === undefined)
+                    last.t1 = x.t;
+                continue;
+            }
+            if (!x.label.startsWith('mark '))
+                inputs.push({ t: x.t, label: x.label });
+        }
+        const size = page.viewportSize() ?? { width: 0, height: 0 };
+        return { trace: { ...trace, inputs }, notes, page_errors: errors.slice(0, 20), browser_lost: lost, size: `${size.width}x${size.height}`, orientation, renderer };
+    }
+    finally {
+        await browser.close().catch(() => { });
+        await t.close();
+    }
+}