@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/frame/behaviour.js

@@ -0,0 +1,53 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const PROBE = (url) => `
+const out = (o) => { process.stdout.write(JSON.stringify(o)); process.exit(0); };
+setTimeout(() => out({ state: 'not_observed', says: 'the lane did not answer in 4 s' }), 4000).unref();
+let m;
+try { m = await import(${JSON.stringify(url)}); } catch (e) { out({ state: 'not_observed', says: 'src/toasts.ts does not load on its own (' + String(e && e.message || e).slice(0, 120) + ')' }); }
+if (typeof m.toast !== 'function') out({ state: 'not_observed', says: 'src/toasts.ts exports no toast(): another lane, measured by its words only' });
+const visible = () => Array.isArray(m.toasts) ? m.toasts.map((t) => t && t.text) : null;
+const A = 'Wave 3: beetles from the north gate', B = '+10';
+let a, b;
+try { a = m.toast(A, { at: 1000 }); b = m.toast(B, { at: 1100 }); } catch (e) { out({ state: 'lost', says: 'toast() throws: ' + String(e && e.message || e).slice(0, 120) }); }
+const v = visible();
+const life = a && typeof a === 'object' ? (typeof a.until === 'number' ? a.until - 1000 : typeof a.life === 'number' ? a.life : null) : null;
+if (v === null && life === null) out({ state: 'lost', says: 'toast() keeps no message: it returns nothing and the module shows no lane (toasts), so nothing is shown or timed' });
+if (v !== null && !v.length) out({ state: 'lost', says: 'toast() shows nothing: the lane is empty right after a message' });
+if (v !== null && v.length > 1) out({ state: 'lost', says: 'two messages on screen at once (' + v.length + '): news stacks over the play' });
+if (v !== null && v[0] !== A) out({ state: 'lost', says: 'the second message replaced the first before it was read' });
+const words = A.split(/\\s+/).length;
+if (life !== null && life < 300 * words * 0.8) out({ state: 'lost', says: 'a ' + words + '-word message stays ' + Math.round(life) + ' ms: too short to read (about 300 ms a word)' });
+if (typeof m.expire === 'function' && v !== null && life !== null) {
+  try { m.expire(1000 + life + 1); } catch (e) { /* an expire with its own clock */ }
+  const after = visible();
+  if (after && after.length && after[0] !== B) out({ state: 'lost', says: 'the waiting message never came after the first was read' });
+}
+out({ state: 'holds', says: 'a message shows one at a time, stays ' + (life !== null ? Math.round(life) + ' ms' : 'its read time') + ' for ' + words + ' words, and the next waits its turn' });
+`;
+export function laneBehaviour(dir) {
+    const file = join(dir, 'src', 'toasts.ts');
+    if (!existsSync(file))
+        return null;
+    const r = spawnSync(process.execPath, ['--input-type=module', '-e', PROBE(pathToFileURL(file).href)], { encoding: 'utf8', timeout: 8000, cwd: dir });
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        return { state: 'not_observed', says: `the lane could not be run (${(r.stderr || r.error?.message || 'no answer').toString().trim().split('\n').pop()?.slice(0, 120)})` };
+    }
+}
+export function withBehaviour(rows, dir, lane = laneBehaviour) {
+    return rows.map((row) => {
+        if (row.id !== 'message-lane' || row.state === 'kit' || row.state === 'n/a')
+            return row;
+        const b = lane(dir);
+        if (!b || b.state === 'not_observed')
+            return b ? { ...row, measured: b.says } : row;
+        if (b.state === 'lost')
+            return { ...row, state: 'lost', measured: b.says, hint: row.hint ?? 'one lane: a queue that shows one message for at least its read time, in the band (skill funpixel-mobile-ui, hud-genres.md)' };
+        return { ...row, state: 'own', measured: b.says, hint: undefined };
+    });
+}

package/dist/frame/clock.js

@@ -0,0 +1,117 @@
+export const CLOCK_JS = `(() => {
+  if (window.__FPX_CLOCK__) return true;
+  const DEAD = /dead|die|dying|death|\\bko\\b|killed/i, LOST = /^(lost|lose|over|game ?over|dead|fail(ed)?|defeat(ed)?|retry)$/i, WON = /^(won|win|victory|clear(ed)?|complete(d)?)$/i;
+  const c = { installed_ms: performance.now(), samples: 0, has_state: false, play_ms: null, first_control_ms: null, first_success_ms: null, success_by: null,
+    moment_ms: null, moment: null, deaths: [], ended: null, screens: [], last: null };
+  window.__FPX_CLOCK__ = c;
+  // The moment marks (HOOKS.md "Signature moments"): the same recorder @funpixel/verify's moments.js installs.
+  if (!Array.isArray(window.__FPX_MOMENTS__)) window.__FPX_MOMENTS__ = [];
+  if (typeof window.__FPX_MOMENT__ !== 'function') window.__FPX_MOMENT__ = (name, weight) => { const log = window.__FPX_MOMENTS__; if (!Array.isArray(log)) return; if (log.length >= 64) log.shift(); log.push({ name: String(name || 'moment'), weight: weight === undefined ? 1 : Number(weight), t: performance.now() }); };
+  let prev = null, baseScore = null, baseWins = null;
+  const tick = () => {
+    let s = null;
+    try { s = typeof window.__FPX_STATE__ === 'function' ? window.__FPX_STATE__() : null; } catch (e) { s = null; }
+    const t = Math.round(performance.now());
+    if (!s || typeof s !== 'object') return;
+    c.samples++; c.has_state = true;
+    const screen = [s.screen, s.phase, s.view, s.mode].find((x) => typeof x === 'string') ?? null;
+    if (screen && c.screens[c.screens.length - 1]?.screen !== screen) c.screens.push({ at_ms: t, screen });
+    const inControl = s.control === true || (s.control === undefined && screen === 'playing');
+    if (inControl && c.first_control_ms === null) { c.first_control_ms = t; baseScore = typeof s.score === 'number' ? s.score : null; baseWins = typeof s.wins === 'number' ? s.wins : null; }
+    if (c.first_control_ms !== null && c.first_success_ms === null) {
+      const by = s.success === true ? 'success' : (typeof s.score === 'number' && baseScore !== null && s.score > baseScore) ? 'score' : (typeof s.wins === 'number' && baseWins !== null && s.wins > baseWins) ? 'wins' : (screen && WON.test(screen)) ? 'screen' : null;
+      if (by) { c.first_success_ms = t; c.success_by = by; }
+    }
+    const moment = typeof s.moment === 'string' && s.moment.trim() ? s.moment.trim() : (s.moment && typeof s.moment === 'object' && typeof s.moment.name === 'string' ? s.moment.name : null);
+    if (moment && c.moment_ms === null && c.first_control_ms !== null) { c.moment_ms = t; c.moment = moment.slice(0, 60); }
+    const marks = Array.isArray(window.__FPX_MOMENTS__) ? window.__FPX_MOMENTS__ : [];
+    const mark = c.first_control_ms === null ? null : marks.find((m) => m && Number(m.t) >= c.first_control_ms);
+    if (mark && (c.moment_ms === null || Number(mark.t) < c.moment_ms)) { c.moment_ms = Math.round(Number(mark.t)); c.moment = String(mark.name || 'moment').slice(0, 60); }
+    const isDead = (x) => x && (x.dead === true || (x.hero && typeof x.hero.state === 'string' && DEAD.test(x.hero.state)));
+    if (prev && c.first_control_ms !== null) {
+      const kinds = [];
+      if (isDead(s) && !isDead(prev)) kinds.push('dead');
+      if (typeof s.lives === 'number' && typeof prev.lives === 'number' && s.lives < prev.lives) kinds.push('life lost');
+      if (typeof s.losses === 'number' && typeof prev.losses === 'number' && s.losses > prev.losses) kinds.push('loss');
+      if (screen && LOST.test(screen) && !(prev.screen && LOST.test(prev.screen))) kinds.push('lost screen');
+      const last = c.deaths[c.deaths.length - 1];
+      if (kinds.length) { if (last && t - last.at_ms < 400) last.kinds = [...new Set([...last.kinds, ...kinds])]; else c.deaths.push({ at_ms: t, kinds }); }
+    }
+    if (!c.ended && c.first_control_ms !== null && screen && (LOST.test(screen) || WON.test(screen))) c.ended = { at_ms: t, screen, how: WON.test(screen) ? 'won' : 'lost' };
+    prev = { dead: s.dead, hero: s.hero && typeof s.hero === 'object' ? { state: s.hero.state } : null, lives: s.lives, losses: s.losses, screen };
+    c.last = { at_ms: t, screen };
+  };
+  tick();
+  setInterval(tick, 100);
+  return true;
+})()`;
+export const MARK_PLAY_JS = `(() => { if (window.__FPX_CLOCK__ && window.__FPX_CLOCK__.play_ms === null) window.__FPX_CLOCK__.play_ms = Math.round(performance.now()); return true; })()`;
+export const READ_CLOCK_JS = `(() => { try { return JSON.stringify(window.__FPX_CLOCK__ || null); } catch (e) { return null; } })()`;
+export function parseClock(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    try {
+        const v = JSON.parse(raw);
+        return v && typeof v === 'object' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+const s1 = (ms) => Math.round(ms / 100) / 10;
+export function judgeIdle(c, opts) {
+    const base = { window_s: opts.windowS, floor_s: opts.floorS, card: opts.card };
+    if (!c || !c.has_state) {
+        return { ...base, observed: false, first_control_s: null, alive_s: null, deaths: [], ended: 'no state', ended_at_s: null,
+            findings: [{ level: 'not_observed', text: 'the idle run read nothing: the game exposes no __FPX_STATE__', hint: 'expose screen, control and dead (HOOKS.md); then time alive and deaths are measured' }] };
+    }
+    if (c.first_control_ms === null) {
+        return { ...base, observed: false, first_control_s: null, alive_s: null, deaths: [], ended: 'never in control', ended_at_s: null,
+            findings: [{ level: 'not_observed', text: `the idle run never saw the player in control (screens: ${c.screens.map((x) => x.screen).join(' → ') || 'none'})`, hint: 'report control: true (or screen "playing") once Play hands over; mark the start data-fpx-start' }] };
+    }
+    const ctl = c.first_control_ms;
+    const deaths = c.deaths.map((d) => ({ at_s: s1(d.at_ms), after_control_s: s1(d.at_ms - ctl), kinds: d.kinds }));
+    const ended = c.ended ? c.ended.how : 'still playing';
+    const alive = deaths.length ? deaths[0].after_control_s : s1(opts.endMs - ctl);
+    const run = { ...base, observed: true, first_control_s: s1(ctl), alive_s: alive, deaths, ended, ended_at_s: c.ended ? s1(c.ended.at_ms - ctl) : null, findings: [] };
+    const f = run.findings;
+    const early = deaths.filter((d) => d.after_control_s < opts.floorS);
+    if (early.length) {
+        f.push({ level: 'warn', text: `an idle player dies ${early[0].after_control_s} s after the first control (${early[0].kinds.join(', ')}); the ${opts.card} floor is ${opts.floorS} s`, hint: 'a phone player idles while reading the screen: give the opening a grace (no threat in reach, a slow first wave, a timer that starts on the first input), or name the choice in funpixel.json firstMinute.idleFloorS' });
+    }
+    if (deaths.length >= 3)
+        f.push({ level: 'warn', text: `${deaths.length} deaths in ${opts.windowS} s of no input: the game kills a player who is not playing, over and over`, hint: 'after a death, hold the next one until the player acts (a respawn shield, a pause on the lost card)' });
+    if (ended === 'won')
+        f.push({ level: 'warn', text: `standing still wins: the idle run reached "${c.ended?.screen}" ${run.ended_at_s} s after the first control`, hint: 'progress should come from the verb (sim measures the same over seeds)' });
+    if (!f.length)
+        f.push({ level: 'note', text: deaths.length ? `an idle player lives ${alive} s after the first control (floor ${opts.floorS} s), then ${ended === 'lost' ? `the run ends on "${c.ended?.screen}"` : 'play goes on'}` : `an idle player is alive after ${alive} s with no input (${ended})` });
+    return run;
+}
+export function judgeFirstMinute(c, opts) {
+    const read = {
+        control_s: c?.first_control_ms != null ? s1(c.first_control_ms) : null, play_pressed_s: c?.play_ms != null ? s1(c.play_ms) : null,
+        success_s: c?.first_success_ms != null ? s1(c.first_success_ms) : null, success_by: c?.success_by ?? null,
+        moment_s: c?.moment_ms != null ? s1(c.moment_ms) : null, moment: c?.moment ?? null, planned_hook: opts.planned, findings: [],
+    };
+    const f = read.findings;
+    if (!c || !c.has_state) {
+        f.push({ level: 'not_observed', text: 'the first minute was not timed: the game exposes no __FPX_STATE__', hint: 'expose screen and control (HOOKS.md)' });
+        return read;
+    }
+    const hookAt = opts.planned?.at ?? opts.hookS;
+    const line = `the first minute: control at ${read.control_s ?? '—'} s · first success ${read.success_s !== null ? `${read.success_s} s (${read.success_by})` : '—'} · hook moment ${read.moment_s !== null ? `${read.moment_s} s ("${read.moment}")` : '—'} (from load)`;
+    f.push({ level: 'note', text: line, hint: `${opts.card} defaults: control ≤ ${opts.controlS} s, success ≤ ${opts.successS} s, hook ≤ ${hookAt} s${opts.planned ? ` (the GDD plans "${opts.planned.what}" at ${opts.planned.at} s)` : ''}` });
+    if (read.control_s === null)
+        f.push({ level: 'warn', text: 'the player never had control in the window', hint: 'report control: true once Play hands over, and keep the way in short' });
+    else if (read.control_s > opts.controlS)
+        f.push({ level: 'warn', text: `${read.control_s} s from load to the first control (the ${opts.card} default is ${opts.controlS} s)`, hint: 'cut what stands before the first press: the splash, a long intro, a menu chain (the promise → one beat → control)' });
+    if (read.success_s !== null && read.success_s > opts.successS)
+        f.push({ level: 'warn', text: `${read.success_s} s from load to the first success (default ${opts.successS} s)`, hint: 'a first win inside the first half-minute: a pickup in reach, a first target that cannot be missed' });
+    else if (read.success_s === null && read.control_s !== null)
+        f.push({ level: opts.playing ? 'warn' : 'note', text: opts.playing ? `no first success in ${opts.windowEndS} s of play` : 'no first success with the light player (it only taps): pass --verbs to play', hint: opts.playing ? 'name a first success the game reports (score up, a clear, success: true)' : undefined });
+    if (read.moment_s !== null && read.moment_s > hookAt)
+        f.push({ level: 'warn', text: `the hook moment "${read.moment}" lands at ${read.moment_s} s (${opts.planned ? 'the GDD plans it' : `the ${opts.card} default is`} ${hookAt} s)`, hint: 'bring the wow forward: the first minutes decide whether people keep playing' });
+    else if (read.moment_s === null)
+        f.push({ level: 'note', text: 'the hook moment was not reported', hint: 'call window.__FPX_MOMENT__?.(\'name\') at the payoff (HOOKS.md, signature moments), and hook times it' });
+    return read;
+}

package/dist/frame/contract.js

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { contentList } from "../gdd/size.js";
+import { designDoc } from "../gdd/doc.js";
+const rx = (re) => (t) => re.test(t);
+const SAVE = /SaveManager|\.setItem\(\s*['"`][^'"`]*(progress|save|level|best|reached|unlock|chapter|stage)/i;
+export const NEEDS = [
+    { id: 'message-lane', need: 'news is read, one message at a time, never over the middle of the play', system: 'the message lane (toast(), one at a time in the HUD band, a read-time floor)', files: ['src/toasts.ts', 'src/hud-kit.tsx'],
+        holds: (g) => rx(/\btoast\(|readTime|aria-live|message[- ]lane/i)(g.src), hint: 'one lane: a queue that shows one message for at least its read time, in the band (skill funpixel-mobile-ui, hud-genres.md)' },
+    { id: 'title-scene', need: 'a title that is a scene, with a real Play the player can find', system: 'the title screen (WORDMARK, the start control marked data-fpx-start)', files: ['src/screens.tsx'],
+        holds: (g) => rx(/data-fpx-start/)(g.src + g.html), hint: 'mark the real start control data-fpx-start, so verify, hook and the idle run press it as a player would' },
+    { id: 'gesture-input', need: 'the play takes a gesture on a phone, and keys on a desktop, for every verb', system: 'input.ts (gesture-first on touch, data-fpx-gesture, keys from one table)', files: ['src/input.ts'],
+        holds: (g) => /data-fpx-gesture|pointerdown|touchstart|onPointerDown|swipe/i.test(g.src) && /keydown|onKeyDown|__FPX_KEYS__/.test(g.src), hint: 'both doors to every verb: pointer or touch on the play, and keys (skill funpixel-mobile-ui, step 6)' },
+    { id: 'save', need: 'progress survives a reload, and the game boots where storage is blocked', system: 'save.ts (SaveManager progress, storage that never throws)', files: ['src/save.ts'],
+        holds: (g) => SAVE.test(g.src), applies: (g) => g.saves || g.levels, hint: 'keep where the player got to (SaveManager from @funpixel/sdk/save); wrap storage so a blocked one never throws' },
+    { id: 'lost-save', need: 'an old or corrupt save falls back to the defaults, never a crash', system: 'save.ts (a versioned record with defaults and a migration)', files: ['src/save.ts'],
+        holds: (g) => /SaveManager|\bversion\s*:\s*\d|migrat/i.test(g.src), applies: (g) => SAVE.test(g.src), hint: 'version the save and give it defaults: a change of shape migrates, a corrupt one starts fresh (test/platform.test.ts)' },
+    { id: 'platform', need: 'a phone call or a tab switch finds the game paused and quiet', system: 'platform.ts (hold on visibilitychange, __FPX_HOLD__)', files: ['src/platform.ts'],
+        holds: (g) => rx(/visibilitychange|__FPX_HOLD__/)(g.src), hint: 'pause and suspend sound on document.hidden; give hosts __FPX_HOLD__' },
+    { id: 'safe-band', need: 'the HUD sits in the safe band: clear of the notch, the status bar and the home bar', system: 'frame.ts (the band from the safe-area insets and the phone floors, as --band-* and __FPX_FRAME__)', files: ['src/frame.ts', 'src/styles.css'],
+        holds: (g) => rx(/safe-area-inset|--band-|__FPX_FRAME__|safeArea/)(g.src), hint: 'inset every edge piece by the band (var(--band-top) …) or env(safe-area-inset-*); `check --phone` measures it' },
+    { id: 'notch-cover', need: 'the page reaches under the notch so the band can step around it', system: 'index.html (viewport-fit=cover)', files: ['index.html'],
+        holds: (g) => /viewport-fit\s*=\s*cover/.test(g.html), hint: 'add viewport-fit=cover to the viewport meta; without it env(safe-area-inset-*) reads 0 on an iPhone' },
+    { id: 'budget', need: 'the 3D world keeps its frame rate on a phone', system: 'budget.ts (a frame BUDGET that sheds detail, a capped pixel ratio)', files: ['src/budget.ts'],
+        holds: (g) => rx(/\bBUDGET\b|setPixelRatio|devicePixelRatio/)(g.src), applies: (g) => g.three, hint: 'cap the pixel ratio and shed detail under a frame budget (funtools profile measures it)' },
+    { id: 'levels', need: 'a level list: where the player got to, and what opens next', system: 'levels.ts (LEVELS as data, unlocked from the save)', files: ['src/levels.ts'],
+        holds: (g) => rx(/\bLEVELS\b|levels\.json|\b(levels|chapters|stages)\s*:\s*\[/)(g.src), applies: (g) => g.levels, hint: 'keep the levels as data (id, name, unlock) and the furthest reached in the save; reach reads level files' },
+    { id: 'look', need: 'the look is one value; a token that cannot apply falls back and says so', system: 'look.ts + look.json (applied at load, one "[frame] look fallback" line per dropped token)', files: ['src/look.ts', 'src/look.json'],
+        holds: (g) => rx(/look\.json|applyLook|\[frame\] look fallback/)(g.src), hint: 'read the look from one value (src/look.json) and log a line when a token falls back; `funtools look report` checks it' },
+];
+const read = (p) => { try {
+    return readFileSync(p, 'utf8');
+}
+catch {
+    return '';
+} };
+function walk(dir, rel, out = []) {
+    let ents = [];
+    try {
+        ents = readdirSync(join(dir, rel));
+    }
+    catch {
+        return out;
+    }
+    for (const e of ents) {
+        if (e.startsWith('.') || e === 'node_modules' || e === 'dist')
+            continue;
+        const r = rel ? `${rel}/${e}` : e;
+        try {
+            if (statSync(join(dir, r)).isDirectory())
+                walk(dir, r, out);
+            else if (/\.(ts|tsx|js|jsx|css|json|html)$/.test(e))
+                out.push(r);
+        }
+        catch { }
+    }
+    return out;
+}
+export function gameText(dir) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(read(join(dir, 'funpixel.json')));
+    }
+    catch { }
+    const src = walk(dir, 'src').filter((f) => !f.startsWith('src/splash-funpixel/')).map((f) => read(join(dir, f)).replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`\\])\/\/.*$/gm, '$1')).join('\n');
+    const gdd = designDoc(dir)?.text ?? '';
+    const rows = gdd ? contentList(gdd) ?? [] : [];
+    const levelRows = rows.filter((r) => /level|chapter|stage|world|room|puzzle/i.test(r.what) && (r.count ?? 0) > 1);
+    const levels = levelRows.length > 0 || (Array.isArray(manifest?.reach?.levels) && manifest.reach.levels.length > 1);
+    return { src, html: read(join(dir, 'index.html')), three: manifest?.metadata?.dimension === '3d', levels, saves: SAVE.test(src) || ['mid', 'deep'].includes(manifest?.production?.tier) };
+}
+export function replacedFiles(dir) {
+    let files = {};
+    try {
+        files = JSON.parse(read(join(dir, '.funtools', 'managed.json'))).files ?? {};
+    }
+    catch {
+        return { managed: false, replaced: new Set() };
+    }
+    const replaced = new Set();
+    for (const [rel, hash] of Object.entries(files)) {
+        const p = join(dir, rel);
+        if (!existsSync(p)) {
+            replaced.add(rel);
+            continue;
+        }
+        const now = createHash('sha256').update(readFileSync(p)).digest('hex');
+        if (now !== hash)
+            replaced.add(rel);
+    }
+    return { managed: Object.keys(files).length > 0, replaced };
+}
+export function frameContract(dir, g = gameText(dir), r = replacedFiles(dir)) {
+    let managedFiles = {};
+    try {
+        managedFiles = JSON.parse(read(join(dir, '.funtools', 'managed.json'))).files ?? {};
+    }
+    catch { }
+    return NEEDS.map((n) => {
+        const base = { id: n.id, need: n.need, system: n.system };
+        if (n.applies && !n.applies(g))
+            return { ...base, state: 'n/a', replaced: [] };
+        const shipped = n.files.filter((f) => f in managedFiles);
+        const replaced = r.managed ? n.files.filter((f) => r.replaced.has(f) || (!(f in managedFiles) && !shipped.length)) : n.files;
+        if (r.managed && shipped.length && !shipped.some((f) => r.replaced.has(f)))
+            return { ...base, state: 'kit', replaced: [] };
+        const holds = n.holds(g);
+        return { ...base, state: holds ? 'own' : 'lost', replaced, ...(holds ? {} : { hint: n.hint }) };
+    });
+}

package/dist/frame/genre.js

@@ -0,0 +1,65 @@
+import { CARD_WORDS } from "../init/starter.js";
+export const IDLE_WINDOW_S = 20;
+export const FIRST_MINUTE = {
+    arcade: { idleFloorS: 8, controlS: 10, successS: 30, hookS: 60 },
+    shooter: { idleFloorS: 8, controlS: 10, successS: 30, hookS: 60 },
+    survival: { idleFloorS: 10, controlS: 15, successS: 30, hookS: 60 },
+    platformer: { idleFloorS: 10, controlS: 10, successS: 30, hookS: 60 },
+    racing: { idleFloorS: 15, controlS: 15, successS: 30, hookS: 60 },
+    puzzle: { idleFloorS: IDLE_WINDOW_S, controlS: 10, successS: 45, hookS: 90 },
+    card: { idleFloorS: IDLE_WINDOW_S, controlS: 15, successS: 45, hookS: 90 },
+    strategy: { idleFloorS: IDLE_WINDOW_S, controlS: 20, successS: 60, hookS: 90 },
+    simulation: { idleFloorS: IDLE_WINDOW_S, controlS: 20, successS: 60, hookS: 90 },
+    rpg: { idleFloorS: IDLE_WINDOW_S, controlS: 30, successS: 60, hookS: 120 },
+};
+export function cardOf(genre) {
+    const g = String(genre ?? '').toLowerCase();
+    const words = new Set(g.split(/[^a-z0-9-]+/).filter(Boolean));
+    for (const c of Object.keys(FIRST_MINUTE))
+        if (words.has(c))
+            return c;
+    for (const [c, ws] of Object.entries(CARD_WORDS)) {
+        if (ws.some((w) => (w.includes(' ') ? g.includes(w) : words.has(w))))
+            return c;
+    }
+    return 'arcade';
+}
+export const STORY_CONTROL_S = 12;
+export const STORY_WORDS = /\b(story|stories|story-led|adventure|narrative|chapters?|tale|saga|visual novel)\b/i;
+export function firstMinuteOf(manifest) {
+    const card = cardOf(manifest?.metadata?.genre ?? manifest?.genre);
+    const base = { ...FIRST_MINUTE[card] };
+    const story = STORY_WORDS.test(`${manifest?.metadata?.genre ?? manifest?.genre ?? ''} ${manifest?.metadata?.tagline ?? ''}`);
+    if (story)
+        base.controlS = Math.min(base.controlS, STORY_CONTROL_S);
+    const own = [];
+    const stated = manifest?.firstMinute;
+    if (stated && typeof stated === 'object') {
+        for (const k of Object.keys(base)) {
+            if (typeof stated[k] === 'number' && stated[k] >= 0) {
+                base[k] = stated[k];
+                own.push(k);
+            }
+        }
+    }
+    return { ...base, card, own, story };
+}
+export function clockSeconds(text) {
+    const m = /^\s*(\d{1,2}):(\d{2})\s*$/.exec(text) ?? null;
+    if (m)
+        return Number(m[1]) * 60 + Number(m[2]);
+    const s = /^\s*(\d+(?:\.\d+)?)\s*s\s*$/.exec(text);
+    return s ? Number(s[1]) : null;
+}
+export function plannedHook(gdd) {
+    const sec = /^## The hook\b[\s\S]*?(?=^## |(?![\s\S]))/m.exec(gdd)?.[0] ?? '';
+    for (const line of sec.split('\n')) {
+        if (!line.trim().startsWith('|'))
+            continue;
+        const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+        const at = cells[0] ? clockSeconds(cells[0]) : null;
+        if (at !== null && cells[1] && !/^<.*>$/.test(cells[1]))
+            return { at, what: cells[1] };
+    }
+    return null;
+}

package/dist/frame/idle.js

@@ -0,0 +1,58 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { withPage } from "../commands/look.js";
+import { evalJson, FRONT_DOOR, FRONT_DOOR_ARGS, load } from "../look/look.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { CLOCK_JS, judgeIdle, MARK_PLAY_JS, parseClock, READ_CLOCK_JS } from "./clock.js";
+import { firstMinuteOf, IDLE_WINDOW_S } from "./genre.js";
+import { FALLBACK_PREFIX } from "../look/theme.js";
+export const IDLE_RECORD = join('.funtools', 'idle.json');
+export async function idleRun(u, dir, windowS = IDLE_WINDOW_S) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(readFileSync(join(dir, 'funpixel.json'), 'utf8'));
+    }
+    catch { }
+    const fm = firstMinuteOf(manifest);
+    return await withPage(u, { target: dir, viewport: 'desktop', json: true, click: FRONT_DOOR }, async (page, t) => {
+        const lines = [];
+        page.on('console', (m) => { const x = m.text(); if (x.startsWith('[frame]') && !lines.includes(x))
+            lines.push(x.slice(0, 240)); });
+        await page.addInitScript(CLOCK_JS).catch(() => { });
+        await load(page, t.url, hookMapOf(t.manifest));
+        await page.evaluate(CLOCK_JS).catch(() => { });
+        await page.waitForTimeout(400);
+        await page.evaluate(MARK_PLAY_JS).catch(() => { });
+        const fd = await evalJson(page, 'front_door', { selector: FRONT_DOOR, ...FRONT_DOOR_ARGS }).catch(() => null);
+        const started = Date.now();
+        await page.waitForTimeout(windowS * 1000);
+        const clock = parseClock(await page.evaluate(READ_CLOCK_JS).catch(() => null));
+        const endMs = (clock?.last?.at_ms ?? 0) || (clock ? clock.installed_ms + (Date.now() - started) : 0);
+        const run = judgeIdle(clock, { windowS, floorS: Math.min(fm.idleFloorS, windowS), card: fm.card, endMs });
+        return { ...run, frame_lines: lines, front_door: fd ? { found: !!fd.found, changed: typeof fd.changed === 'boolean' ? fd.changed : null } : null };
+    });
+}
+export async function recordIdle(dir, r) {
+    const path = join(dir, IDLE_RECORD);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify({ ...r, fingerprint: (await fingerprint(dir)).fingerprint, at: new Date().toISOString() }, null, 2) + '\n');
+}
+export function readIdle(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, IDLE_RECORD), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function idleLine(dir) {
+    const r = readIdle(dir);
+    if (!r)
+        return 'the idle run in the real page is a check fact: `funtools check` records time alive, deaths and how it ended (.funtools/idle.json)';
+    if (!r.observed)
+        return `the last idle run (check, ${r.at?.slice(0, 16) ?? 'earlier'}) observed nothing: ${r.findings[0]?.text ?? r.ended}`;
+    return `the last idle run (check): alive ${r.alive_s} s after the first control, ${r.deaths.length} death(s) in ${r.window_s} s, ${r.ended}${r.findings.some((f) => f.level === 'warn') ? ' — warned' : ''}`;
+}
+export const isFallbackLine = (l) => l.startsWith(FALLBACK_PREFIX);

package/dist/frame/opening.js

@@ -0,0 +1,171 @@
+import { clockSeconds } from "./genre.js";
+const PLACEHOLDER = /^<.*>$|^…$/;
+const clean = (v) => { const t = (v ?? '').trim().replace(/^\*+|\*+$/g, '').trim(); return !t || PLACEHOLDER.test(t) ? '' : t; };
+const sectionOf = (gdd, title) => {
+    const m = new RegExp(`^## ${title.source}[^\\n]*\\n([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(gdd);
+    return m ? m[1] : null;
+};
+const tableRows = (body) => body.split('\n').filter((l) => /^\s*\|.*\|\s*$/.test(l) && !/^\s*\|[\s:|-]+\|\s*$/.test(l)).map((l) => l.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim()));
+const field = (body, name) => { const m = new RegExp(`(?:^|[·\\n])\\s*\\**${name.source}\\**\\s*:\\s*([^·\\n]+)`, 'im').exec(body); return m ? clean(m[1]) : ''; };
+const num = (s) => { const m = /(-?\d+(?:\.\d+)?)/.exec(s); return m ? Number(m[1]) : null; };
+export function openingPlan(gdd) {
+    const body = sectionOf(gdd, /Opening\b/);
+    if (body === null)
+        return null;
+    const cold = field(body, /Cold open/), ctl = field(body, /First control/), obj = field(body, /Objective(?: on screen)?/), dist = field(body, /Distance/);
+    const rows = tableRows(body);
+    const head = rows[0]?.map((h) => h.toLowerCase()) ?? [];
+    const col = (re, d) => { const i = head.findIndex((h) => re.test(h)); return i < 0 ? d : i; };
+    const cw = col(/when|time/, 0), cs = col(/shot|camera/, 1), cwhat = col(/sees|what/, 2), ccan = col(/can|player/, 3), cp = col(/proven|proof|check/, 4);
+    const out = rows.slice(1).map((r) => ({ when: clean(r[cw]), at: clockSeconds(clean(r[cw])), shot: clean(r[cs]).split(/[\s(]/)[0] || null, what: clean(r[cwhat]), can: clean(r[ccan]), proof: clean(r[cp]) })).filter((r) => r.when || r.what);
+    const ctlS = ctl ? clockSeconds(ctl.split(/[\s(]/)[0]) ?? num(ctl) : null;
+    return { coldOpen: cold && !/^none\b/i.test(cold) ? cold : null, noColdOpen: /^none\b/i.test(cold), controlS: ctlS, objective: obj && !/^none\b/i.test(obj) ? obj.replace(/^["“]|["”]$/g, '') : null, distance: dist && !/^none\b/i.test(dist) ? dist.replace(/^["“]|["”]$/g, '') : null, rows: out };
+}
+export function shotPlan(gdd) {
+    const body = sectionOf(gdd, /Shots\b/);
+    if (body === null)
+        return [];
+    const rows = tableRows(body);
+    const head = rows[0]?.map((h) => h.toLowerCase()) ?? [];
+    const col = (re, d) => { const i = head.findIndex((h) => re.test(h)); return i < 0 ? d : i; };
+    const cm = col(/moment|beat/, 0), cs = col(/^shot/, 1), cl = col(/lens|fov/, 2), ch = col(/height|distance/, 3), cmo = col(/motion|move/, 4), ct = col(/target|frame/, 5);
+    return rows.slice(1).map((r) => {
+        const hd = clean(r[ch]);
+        const up = /(-?\d+(?:\.\d+)?)\s*m?\s*(?:up|high|above)/i.exec(hd), out = /(-?\d+(?:\.\d+)?)\s*m?\s*(?:out|behind|back|away)/i.exec(hd);
+        return { moment: clean(r[cm]), shot: clean(r[cs]).split(/[\s(]/)[0], fov: num(clean(r[cl])), height: up ? Number(up[1]) : null, distance: out ? Number(out[1]) : null, motion: clean(r[cmo]), target: clean(r[ct]) };
+    }).filter((r) => r.moment && r.shot);
+}
+export const OPENING_JS = `(() => {
+  if (window.__FPX_OPENING__) return true;
+  const o = { t0: null, samples: 0, objective_at: null, objective: null, distance_at: null, distance: null, on_screen_at: null, shots: [], beats: [], fovs: [], camera: false };
+  window.__FPX_OPENING__ = o;
+  const DIST = /\\b\\d+(?:[.,]\\d+)?\\s?(?:m|km|metres|meters|yd|ft)\\b/i;
+  const captions = () => {
+    const out = []; let n = 0;
+    const canvas = document.querySelector('canvas'); const cr = canvas ? canvas.getBoundingClientRect() : { left: 0, top: 0, right: innerWidth, bottom: innerHeight };
+    for (const el of document.querySelectorAll('body *')) {
+      if (++n > 1500) break;
+      if (el.tagName === 'CANVAS' || el.tagName === 'SCRIPT' || el.tagName === 'STYLE' || el.tagName === 'BUTTON' || el.closest('button')) continue;
+      const own = [...el.childNodes].filter((c) => c.nodeType === 3).map((c) => c.textContent).join(' ').trim();
+      if (own.split(/\\s+/).length < 3 || own.length > 240) continue;
+      const r = el.getBoundingClientRect(); if (r.width < 40 || r.height < 10) continue;
+      if (r.right < cr.left || r.left > cr.right || r.bottom < cr.top || r.top > cr.bottom) continue;
+      const cs = getComputedStyle(el); if (cs.visibility === 'hidden' || cs.display === 'none' || Number(cs.opacity) < 0.15) continue;
+      let p = el.parentElement, hidden = false; while (p) { const ps = getComputedStyle(p); if (ps.display === 'none' || ps.visibility === 'hidden' || Number(ps.opacity) < 0.15) { hidden = true; break; } p = p.parentElement; }
+      if (!hidden) out.push({ el, text: own.slice(0, 80) });
+      if (out.length >= 4) break;
+    }
+    return out;
+  };
+  let lastBeat = null, lastShot = null, pendingBeat = null, standing = new WeakSet();
+  // An element that is always there (the HUD's rows, whose numbers change) is not a beat's caption: only elements new since the last look count.
+  const fresh = () => captions().filter((c) => !standing.has(c.el)).map((c) => c.text);
+  const tick = () => {
+    let s = null; try { s = typeof window.__FPX_STATE__ === 'function' ? window.__FPX_STATE__() : null; } catch (e) {}
+    const t = Math.round(performance.now());
+    const screen = s ? [s.screen, s.phase, s.view, s.mode].find((x) => typeof x === 'string') : null;
+    if (o.t0 === null && screen && !/title|menu|splash|load/i.test(screen)) o.t0 = t;
+    o.samples++;
+    let cam = null; try { cam = typeof window.__FPX_CAMERA__ === 'function' ? window.__FPX_CAMERA__() : null; } catch (e) {}
+    if (cam) { o.camera = true; const shot = typeof cam.shot === 'string' ? cam.shot : null; if (shot !== lastShot) { o.shots.push({ at_ms: t, shot }); lastShot = shot; if (o.shots.length > 60) o.shots.shift(); }
+      if (typeof cam.fov === 'number' && (!o.fovs.length || Math.abs(o.fovs[o.fovs.length - 1].fov - cam.fov) > 3)) { o.fovs.push({ at_ms: t, fov: Math.round(cam.fov * 10) / 10 }); if (o.fovs.length > 60) o.fovs.shift(); } }
+    if (s) {
+      const ob = s.objective; const text = typeof ob === 'string' ? ob : ob && typeof ob === 'object' ? [ob.title, ob.text, ob.name, ob.label].find((x) => typeof x === 'string') : null;
+      if (text && o.objective_at === null) { o.objective_at = t; o.objective = String(text).slice(0, 120); }
+      const d = typeof s.goalDistance === 'number' ? s.goalDistance : ob && typeof ob === 'object' && typeof ob.distance === 'number' ? ob.distance : null;
+      if (d !== null && o.distance_at === null) { o.distance_at = t; o.distance = d; }
+      const beat = typeof s.beat === 'string' ? s.beat : s.beat && typeof s.beat === 'object' && typeof (s.beat.id || s.beat.name) === 'string' ? (s.beat.id || s.beat.name) : null;
+      if (!beat && o.samples % 8 === 0) for (const c of captions()) standing.add(c.el);
+      if (beat && beat !== lastBeat) { pendingBeat = { id: String(beat).slice(0, 60), at_ms: t, shot: lastShot, captions: fresh(), later: null }; o.beats.push(pendingBeat); if (o.beats.length > 40) o.beats.shift(); }
+      lastBeat = beat;
+      if (pendingBeat && pendingBeat.later === null && t - pendingBeat.at_ms >= 1200) { pendingBeat.later = fresh(); pendingBeat.shot_after = lastShot; }
+    }
+    if (o.on_screen_at === null && o.samples % 4 === 0) {
+      const body = (document.body && document.body.innerText) || '';
+      const want = o.objective ? o.objective.toLowerCase().split(/\\s+/).filter((w) => w.length > 3).slice(0, 3) : [];
+      if (DIST.test(body) && (!want.length || want.some((w) => body.toLowerCase().includes(w)))) o.on_screen_at = t;
+    }
+  };
+  setInterval(tick, 250);
+  return true;
+})()`;
+export const READ_OPENING_JS = `(() => { const o = window.__FPX_OPENING__; if (!o) return null; const marks = Array.isArray(window.__FPX_MOMENTS__) ? window.__FPX_MOMENTS__.map((m) => ({ name: String(m && m.name || 'moment').slice(0, 60), t: Math.round(Number(m && m.t) || 0) })) : []; return JSON.stringify({ ...o, marks }); })()`;
+export function parseOpening(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    try {
+        const o = JSON.parse(raw);
+        return o && typeof o === 'object' && Array.isArray(o.shots) ? o : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const BEAT_WINDOW_MS = { before: 500, after: 2500 };
+export function stagedBeats(r, playMs = null) {
+    const zero = playMs ?? r.t0 ?? 0;
+    return r.beats.map((b) => {
+        const inWin = (at) => at >= b.at_ms - BEAT_WINDOW_MS.before && at <= b.at_ms + BEAT_WINDOW_MS.after;
+        const shot = r.shots.find((x) => inWin(x.at_ms) && x.at_ms > (r.shots[0]?.at_ms ?? -1));
+        const lens = r.fovs.find((x, i) => i > 0 && inWin(x.at_ms));
+        const said = [...b.captions, ...(b.later ?? [])];
+        const at_s = Math.round((b.at_ms - zero) / 100) / 10;
+        if (shot || lens || (b.shot_after && b.shot_after !== b.shot))
+            return { id: b.id, at_s, staging: 'staged', why: shot ? `the camera cut or blended to "${shot.shot}"` : lens ? `the lens moved to ${lens.fov}°` : `the shot changed to "${b.shot_after}"` };
+        if (said.length)
+            return { id: b.id, at_s, staging: 'hud-only', why: `only text changed: "${said[0]}"${r.camera ? '' : ' (the game reports no camera: __FPX_CAMERA__)'}` };
+        return { id: b.id, at_s, staging: 'not-seen', why: 'neither the camera nor a caption answered it' };
+    });
+}
+export function judgeOpening(r, plan, o) {
+    const f = [];
+    if (!plan)
+        f.push({ level: 'note', text: 'no `## Opening` in the GDD: the cold open, the first control and the objective are not planned', hint: 'add it from the template (skill funpixel-gdd, gdd-template.md): second by second from Play, with the shot for each row' });
+    if (plan?.controlS != null && plan.controlS > o.controlS)
+        f.push({ level: 'warn', text: `the plan hands over control at ${plan.controlS} s; the ${o.card} bar is ${o.controlS} s`, hint: 'shorten the cold open (Silt: three voiced lines, then control at 12 s)' });
+    if (plan?.controlS != null && o.controlAtS !== null && o.controlAtS > plan.controlS + 3)
+        f.push({ level: 'warn', text: `control came at ${o.controlAtS} s; the plan says ${plan.controlS} s`, hint: 'the opening runs long against its own plan' });
+    if (!r || !r.samples) {
+        f.push({ level: 'not_observed', text: 'the opening was not recorded (no __FPX_STATE__ samples)' });
+        return f;
+    }
+    const zero = o.playMs ?? r.t0 ?? 0, s = (ms) => (ms === null ? null : Math.round((ms - zero) / 100) / 10);
+    const ctl = o.controlAtS;
+    const objS = s(r.objective_at), distS = s(r.distance_at), screenS = s(r.on_screen_at);
+    if (ctl !== null) {
+        const late = (x) => x === null || x > ctl + 2;
+        if (late(objS))
+            f.push({ level: 'warn', text: objS === null ? 'no objective in the game\'s state by the end of the read (`__FPX_STATE__.objective`)' : `the objective arrives at ${objS} s, after control at ${ctl} s`, hint: plan?.objective ? `the plan's objective: "${plan.objective}" — put it on screen at the hand-over` : 'a goal the player can read at the first control (the Silt bar S2)' });
+        if (plan?.distance && late(distS))
+            f.push({ level: 'warn', text: distS === null ? 'the plan shows a distance; the game reports none (`goalDistance`)' : `the distance arrives at ${distS} s, after control at ${ctl} s`, hint: `the plan: "${plan.distance}" to go, on the HUD when control comes` });
+        if ((plan?.distance || r.distance !== null) && late(screenS))
+            f.push({ level: 'warn', text: 'no distance in metres on screen at the first control (the page\'s text has no "N m")', hint: 'the objective and its metres on the HUD, not only in the state' });
+        if (!late(objS) && (!plan?.distance || !late(distS)))
+            f.push({ level: 'note', text: `objective "${r.objective ?? '?'}"${r.distance !== null ? ` and ${r.distance} m to go` : ''} by ${Math.max(objS ?? 0, distS ?? 0)} s, control at ${ctl} s` });
+    }
+    if (plan?.coldOpen && ctl !== null) {
+        const atControl = [...r.shots].reverse().find((x) => s(x.at_ms) <= ctl)?.shot ?? null, title = r.shots[0]?.shot ?? null;
+        const before = r.shots.filter((x) => s(x.at_ms) > 0 && s(x.at_ms) < ctl && x.shot !== atControl && x.shot !== title);
+        if (r.camera && !before.length)
+            f.push({ level: 'warn', text: `the plan's cold open ("${plan.coldOpen.slice(0, 80)}") was not seen: no shot between Play and control`, hint: 'stage it as a shot (src/shots.ts) that hands over to play' });
+    }
+    if (plan && r.camera) {
+        for (const row of plan.rows.filter((x) => x.at !== null && x.shot)) {
+            const at = zero + row.at * 1000;
+            const inEffect = (ms) => [...r.shots].reverse().find((x) => x.at_ms <= ms)?.shot ?? null;
+            const seen = new Set([inEffect(at - 1500), inEffect(at + 1500), ...r.shots.filter((x) => Math.abs(x.at_ms - at) <= 1500).map((x) => x.shot)]);
+            const live = inEffect(at + 1500);
+            if (live && !seen.has(row.shot))
+                f.push({ level: 'warn', text: `${row.when}: the plan's shot is "${row.shot}", the camera was in "${live}"`, hint: 'name the shot in src/shots.ts and shoot() it at that beat' });
+        }
+    }
+    else if (plan?.rows.some((x) => x.shot))
+        f.push({ level: 'not_observed', text: 'the plan names shots, the game reports no camera (`__FPX_CAMERA__`)', hint: 'the starters ship it (src/shots.ts)' });
+    for (const b of stagedBeats(r, o.playMs)) {
+        if (b.staging === 'hud-only')
+            f.push({ level: 'warn', text: `beat "${b.id}" at ${b.at_s} s was delivered only as a HUD panel: ${b.why}`, hint: 'stage it in the engine: a shot (shoot("reveal")), bodies that act it, the line as a caption over that shot (the Silt bar J2)' });
+        else if (b.staging === 'staged')
+            f.push({ level: 'note', text: `beat "${b.id}" at ${b.at_s} s staged: ${b.why}` });
+    }
+    return f;
+}