@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/walk.js

@@ -0,0 +1,449 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pageScript } from '../vendor/verify/src/index.js';
+import { EXIT } from "./verify.js";
+import { withPage } from "./look.js";
+import { evalJson, load } from "../look/look.js";
+import { drainMoments } from "../look/moments.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { sceneReads } from "../verify/reads.js";
+import { parseStep } from "../play/steps.js";
+import { gesture } from "../play/input.js";
+import { touchSession } from "../verify/browser.js";
+import { startFilm, stopFilm } from "../walk/film.js";
+import { chainsOf, isDone, pathFromState, PositionSteer, readWalk, steerKey, field } from "../walk/routes.js";
+import { challengeCount, clipsIn, counterRise, crowdTravel, floatsIn, framingCheck, framingOf, lostNow, scaleMisses, scaleSpread, stallsIn, stateHash, tallyClips, tallyTravel, ACTORS_DOC, CHALLENGE_WORDS, TRAVEL_M, } from "../walk/judge.js";
+import { lifeVerdicts } from "../look/anim.js";
+import { boxFiguresCheck, boxTally, judgeBoxes, tallyBoxes, walkBoxesCheck } from "../look/boxes.js";
+import { readStyleLock } from "./boxes.js";
+import { decodePng } from "../look/png.js";
+import { dressingCheck } from "../look/dressing.js";
+import { crowdChecks, mergedClumps, crowdTally, groundingChecks, groundTally, tallyCrowd, tallyGround } from "../walk/world.js";
+import { ui } from "../ui.js";
+export const WALK_RECORD = join('.funtools', 'walk.json');
+export const WALK_DIR = join('.funtools', 'walk');
+export const WALK_TICK_MS = 250;
+export const WORLD_EVERY_S = 4;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function stateOf(page) {
+    try {
+        const raw = await page.evaluate('(() => { try { const s = window.__FPX_STATE__ && window.__FPX_STATE__(); const j = JSON.stringify(s); return j && j.length < 20000 ? j : null; } catch (e) { return null; } })()');
+        return typeof raw === 'string' ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function startStep(page, text, phone) {
+    const m = /^click\s+(.+)$/.exec(text.trim());
+    if (m) {
+        const box = await page.locator(m[1]).first().boundingBox({ timeout: 3000 }).catch(() => null);
+        if (!box)
+            return `${text}: nothing visible matches`;
+        await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+        return '';
+    }
+    const step = parseStep(text, phone);
+    if (typeof step === 'string')
+        return step;
+    if (step.kind === 'wait' || step.kind === 'clip') {
+        await sleep(step.ms);
+        return '';
+    }
+    if (step.kind === 'view' || step.kind === 'verb')
+        return `${text}: walk plays as a person — no view jumps or verbs`;
+    if (step.kind === 'shot')
+        return '';
+    if (step.kind === 'until')
+        return `${text}: a route plays fixed times — hold KEY ms or wait ms`;
+    await gesture(page, () => touchSession(page), phone, step.kind === 'together' ? step.parts : [step]);
+    return '';
+}
+const readActors = async (page, cfg) => {
+    const r = await evalJson(page, 'world_actors', { max: 800, ...(cfg.actors.player ? { player: cfg.actors.player } : {}), ...(cfg.actors.people ? { people: cfg.actors.people } : {}), ...(cfg.actors.creatures ? { creatures: cfg.actors.creatures } : {}) });
+    return { source: r?.source ?? 'none', actors: Array.isArray(r?.actors) ? r.actors : [] };
+};
+const RETRY = /retry|try again|again|restart|start over|continue|play on|once more/i;
+async function retryAfterLoss(page) {
+    await sleep(1200);
+    let how = 'Enter';
+    const button = page.getByRole('button', { name: RETRY }).first();
+    if (await button.isVisible({ timeout: 800 }).catch(() => false)) {
+        const words = ((await button.textContent({ timeout: 500 }).catch(() => '')) ?? '').trim().slice(0, 30) || 'retry';
+        const box = await button.boundingBox({ timeout: 500 }).catch(() => null);
+        if (box) {
+            await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+            how = `the "${words}" button`;
+        }
+        else
+            await page.keyboard.press('Enter');
+    }
+    else
+        await page.keyboard.press('Enter');
+    for (let i = 0; i < 24; i++) {
+        await sleep(250);
+        const st = await stateOf(page);
+        if (st && !lostNow(st, []))
+            return { retried: true, how };
+    }
+    return { retried: false, how };
+}
+export function legSteps(route, first) {
+    if (first)
+        return { steps: route.start, note: null };
+    const cont = route.continue ?? [];
+    const note = route.start.length || cont.length ? { status: 'note', text: `chained: ${route.name} goes on from where the leg before it arrived; its ${route.start.length} start step(s) (from the title) were skipped${cont.length ? `, its ${cont.length} continue step(s) played` : ''}`, ...(cont.length ? {} : { hint: 'walk.routes[].continue: the steps from where the leg before arrives to control, if it needs any' }) } : null;
+    return { steps: cont, note };
+}
+export const SHORT_LEG_S = 3;
+export function legUnobserved(route, first, outcome, seconds) {
+    if (outcome !== 'arrived' || seconds >= SHORT_LEG_S)
+        return null;
+    const chainedBare = !first && !(route.continue ?? []).length;
+    return {
+        status: 'not_observed',
+        text: `${route.name}: not observed — it arrived in ${seconds} s, before anything was played (its done condition already held${chainedBare ? ' where the leg before it arrived' : ''}); nothing on it was judged`,
+        hint: chainedBare
+            ? `add walk.routes[].continue to ${route.name} in funpixel.json: the steps from where the leg before it arrives into its play (the choice, the cards, the press that starts it) — a chained leg skips its start steps`
+            : `walk.routes[].done for ${route.name} must hold only when the walk is over, and its start steps must reach play`,
+    };
+}
+const filmFile = (name) => `${name.replace(/[^A-Za-z0-9_+.-]+/g, '_')}.webm`;
+async function walkRoute(page, url, hooks, route, cfg, opts, dir, ctx = { film: null, filmStart: null, chain: null, last: true, first: true }) {
+    const phone = opts.viewport === 'phone';
+    const checks = [];
+    if (ctx.first) {
+        await load(page, url, hooks);
+        await sleep(600);
+    }
+    else
+        await sleep(400);
+    const startErrors = [];
+    const leg = legSteps(route, ctx.first);
+    if (leg.note)
+        checks.push(leg.note);
+    for (const s of leg.steps) {
+        const e = await startStep(page, s, phone);
+        if (e)
+            startErrors.push(e);
+    }
+    for (let i = 0; i < 12; i++) {
+        const h = await evalJson(page, 'frame_honesty', {});
+        if (!h?.loading)
+            break;
+        await sleep(500);
+    }
+    const shots = [];
+    const shoot = async (tag) => {
+        if (!dir)
+            return;
+        const rel = join(WALK_DIR, `${route.name}-${tag}.png`);
+        await page.screenshot({ path: join(dir, rel) }).then(() => shots.push(rel)).catch(() => { });
+    };
+    await shoot('start');
+    const film = ctx.first ? (opts.film && dir ? await startFilm(page) : null) : ctx.filmStart;
+    ctx.filmStart = film;
+    if (film && !film.ok && ctx.first)
+        checks.push({ status: 'not_observed', text: `no film: ${film.error}` });
+    await evalJson(page, 'life_anim', { op: 'install', react_m: cfg.reactM, ...(cfg.actors.player ? { player: cfg.actors.player } : { player: 'player|hero|avatar' }), ...(cfg.actors.people ? { people: cfg.actors.people } : {}), ...(cfg.actors.creatures ? { creatures: cfg.actors.creatures } : {}) });
+    await drainMoments(page);
+    const s0 = await stateOf(page);
+    const p0 = route.progress ? field(s0, route.progress) : null;
+    const ticks = [];
+    const clips = new Map();
+    const placement = new Map();
+    const floats = new Map();
+    const latest = new Map();
+    const shares = new Map();
+    const marks = [];
+    let source = 'none';
+    let floatObserved = false;
+    const limit = Math.min(route.maxS, opts.seconds ?? Infinity);
+    const t0 = Date.now();
+    let outcome = 'timed_out';
+    let placed = '';
+    let recovering = 0;
+    const travel = new Map();
+    const losses = [];
+    const boxes = boxTally(), ground = groundTally(), crowd = crowdTally();
+    let barest = null;
+    let worstShot = null, worldAt = -Infinity;
+    const posSteer = route.steer && (!route.steer.field || typeof field(s0, route.steer.field) !== 'number') ? new PositionSteer(route.steer) : null;
+    const pathPts = route.steer?.waypoints ?? pathFromState(s0);
+    for (const k of route.hold)
+        await page.keyboard.down(k);
+    let state = s0;
+    while ((Date.now() - t0) / 1000 < limit) {
+        await sleep(WALK_TICK_MS);
+        const t = (Date.now() - t0) / 1000;
+        state = await stateOf(page);
+        const lost = lostNow(state, []);
+        if (lost) {
+            for (const k of route.hold)
+                await page.keyboard.up(k).catch(() => { });
+            const back = await retryAfterLoss(page);
+            losses.push({ at_s: Math.round(t * 10) / 10, why: lost, ...back });
+            if (!back.retried || losses.length >= 3)
+                break;
+            for (const k of route.hold)
+                await page.keyboard.down(k);
+            continue;
+        }
+        if (isDone(route.done, state)) {
+            outcome = 'arrived';
+            break;
+        }
+        const read = await readActors(page, cfg);
+        tallyTravel(travel, read.actors);
+        tallyCrowd(crowd, read.actors, t, cfg.crowd);
+        if (t - worldAt >= WORLD_EVERY_S) {
+            worldAt = t;
+            const surf = await evalJson(page, 'surfaces', {});
+            if (surf?.engine === 'three') {
+                const shot = await page.screenshot().catch(() => null);
+                const frame = judgeBoxes(surf, shot ? decodePng(shot) : null, page.viewportSize()?.width ?? 0, cfg.style ?? null);
+                if (tallyBoxes(boxes, frame, t) && shot)
+                    worstShot = shot;
+            }
+            tallyGround(ground, await evalJson(page, 'grounding', {}), t);
+            const dr = await evalJson(page, 'dressing', {});
+            if (dr?.engine === 'three' && dr.at && (!barest || (dr.on_road ?? 0) > (barest.on_road ?? 0) || ((dr.on_road ?? 0) === (barest.on_road ?? 0) && dr.per100 < barest.per100)))
+                barest = dr;
+        }
+        source = read.source === 'none' ? source : read.source;
+        const player = read.actors.find((a) => a.kind === 'player') ?? null;
+        tallyClips(clips, clipsIn(read.actors), t);
+        const place = String(field(state, 'level') ?? field(state, 'place') ?? '');
+        if (place !== placed && read.actors.length) {
+            placed = place;
+            tallyClips(placement, new Map([...clipsIn(read.actors.filter((a) => a.kind === 'prop'), true)]), t);
+        }
+        const fl = floatsIn(read.actors);
+        if (fl) {
+            floatObserved = true;
+            for (const f of fl) {
+                const was = floats.get(f.id);
+                if (!was)
+                    floats.set(f.id, { ...f, readings: 1 });
+                else {
+                    was.readings++;
+                    if (Math.abs(f.gap) > Math.abs(was.gap))
+                        was.gap = f.gap;
+                }
+            }
+        }
+        for (const a of read.actors) {
+            latest.set(a.id, a);
+            if (a.screen?.on && (a.kind === 'player' || cfg.framing[a.id])) {
+                const l = shares.get(a.id) ?? [];
+                l.push({ t, share: a.screen.share });
+                shares.set(a.id, l);
+            }
+        }
+        const solidNear = player ? read.actors.filter((a) => a !== player && a.solid && Math.hypot(a.x - player.x, a.z - player.z) < (a.r ?? 1) + 1.2).sort((a, b) => Math.hypot(a.x - player.x, a.z - player.z) - Math.hypot(b.x - player.x, b.z - player.z))[0] : null;
+        const ps = posSteer ? posSteer.next(player ? { x: player.x, z: player.z } : null, pathPts) : null;
+        const prog = route.progress ? field(state, route.progress) : ps?.along ?? null;
+        ticks.push({ t, at: player ? { x: player.x, z: player.z } : null, progress: typeof prog === 'number' ? prog : null, state: stateHash(state), pressing: true, near: solidNear ? solidNear.id : null });
+        const drained = await drainMoments(page);
+        marks.push(...drained);
+        const sk = posSteer ? ps?.key ?? null : steerKey(route.steer, state);
+        if (sk) {
+            await page.keyboard.down(sk);
+            await sleep(90);
+            await page.keyboard.up(sk);
+        }
+        const tail = stallsIn(ticks, cfg.stallS);
+        if (tail.length && tail[tail.length - 1].to_s >= t - WALK_TICK_MS / 1000 - 0.01) {
+            if (recovering >= 3) {
+                outcome = 'dead_end';
+                break;
+            }
+            const key = ['ArrowLeft', 'ArrowRight', 'Enter'][recovering++];
+            await page.keyboard.down(key);
+            await sleep(600);
+            await page.keyboard.up(key);
+            ticks.push({ t: (Date.now() - t0) / 1000, at: null, progress: null, state: `recover-${recovering}`, pressing: false, near: null });
+        }
+    }
+    for (const k of route.hold)
+        await page.keyboard.up(k).catch(() => { });
+    const seconds = Math.round((Date.now() - t0) / 100) / 10;
+    await shoot('end');
+    const s1 = await stateOf(page);
+    const anim = await evalJson(page, 'life_anim', { op: 'stop' });
+    const filmed = ctx.last && film?.ok && dir ? await stopFilm(page, join(dir, WALK_DIR, filmFile(ctx.chain ?? route.name))) : null;
+    if (filmed)
+        ctx.film = filmed;
+    const moved = ticks.some((k) => k.at && ticks[0]?.at && Math.hypot(k.at.x - ticks[0].at.x, k.at.z - ticks[0].at.z) > 1) || (typeof p0 === 'number' && typeof field(s1, route.progress ?? '') === 'number' && Math.abs(field(s1, route.progress) - p0) > 1);
+    if (!moved && outcome !== 'arrived')
+        outcome = ticks.length ? 'no_control' : outcome;
+    const all = [...latest.values()];
+    const clipList = [...clips.values()].sort((a, b) => b.depth - a.depth);
+    const placeList = [...placement.values()].sort((a, b) => b.depth - a.depth);
+    const floatList = floatObserved ? [...floats.values()].filter((f) => f.readings >= 2).sort((a, b) => Math.abs(b.gap) - Math.abs(a.gap)) : null;
+    const sm = Object.keys(cfg.scale).length ? scaleMisses(all, cfg.scale) : null;
+    const scale = sm || all.length ? { misses: sm?.misses ?? [], judged: sm?.judged ?? 0, spread: scaleSpread(all) } : null;
+    const framing = [...shares.entries()].map(([id, l]) => framingOf(id, l, cfg.framing[id] ?? null));
+    const stalls = stallsIn(ticks.filter((k) => !k.state.startsWith('recover-')), cfg.stallS);
+    const words = cfg.challenge ? new RegExp(cfg.challenge.join('|'), 'i') : CHALLENGE_WORDS;
+    const ch = s0 || marks.length ? challengeCount(marks, counterRise(s0, s1), words) : null;
+    if (startErrors.length)
+        checks.push({ status: 'warn', text: `the ${ctx.first ? 'start' : 'continue'} steps did not all play: ${startErrors.join('; ')}` });
+    if (outcome === 'no_control')
+        checks.push({ status: 'warn', text: `${route.name}: the player never moved — the start steps did not reach play, or the held keys do nothing`, hint: `walk.routes[].start / hold in funpixel.json; state at the end: ${JSON.stringify({ screen: field(s1, 'screen') ?? null })}` });
+    if (source === 'none')
+        checks.push({ status: 'not_observed', text: 'no actors read: no __FPX_ACTORS__ contract and no Three scene', hint: `expose window.__FPX_ACTORS__() — ${ACTORS_DOC}` });
+    else if (source === 'scene')
+        checks.push({ status: 'note', text: 'actors read from the scene graph (no __FPX_ACTORS__): ground and footprints are guesses; floating not observed' });
+    if (clipList.length)
+        checks.push({ status: 'warn', text: `CLIPPING: ${clipList.length} pair(s) went through each other`, hint: 'bodies must collide with props, walls and each other (the rules\' obstacles must match what is drawn)', items: clipList.slice(0, 12).map((c) => `${c.a} inside ${c.b} by ${c.depth} m at (${c.at.x}, ${c.at.z}) from ${c.first_s} s, ${c.times} reading(s)`) });
+    else if (source !== 'none' && ticks.length)
+        checks.push({ status: 'pass', text: 'clipping: nothing moving went through anything solid' });
+    if (placeList.length)
+        checks.push({ status: 'warn', text: `PLACEMENT: ${placeList.length} prop(s) placed inside another`, items: placeList.slice(0, 10).map((c) => `${c.a} inside ${c.b} by ${c.depth} m at (${c.at.x}, ${c.at.z})`) });
+    if (floatList === null)
+        checks.push({ status: 'not_observed', text: 'floating: no actor says where the ground is (contract `ground`)' });
+    else if (floatList.length)
+        checks.push({ status: 'warn', text: `FLOATING: ${floatList.length} actor(s) off the ground`, hint: 'feet and shadows on the terrain: place from the ground height, never a fixed y', items: floatList.slice(0, 12).map((f) => `${f.id} (${f.type}) ${f.kind} ${f.gap > 0 ? '+' : ''}${f.gap} m`) });
+    else
+        checks.push({ status: 'pass', text: 'floating: every grounded actor stands on the ground or on something solid' });
+    if (scale) {
+        if (!scale.judged)
+            checks.push({ status: 'not_observed', text: 'scale: no scale sheet (funpixel.json "scale": { "person": 1.75, … } in metres)' });
+        else if (scale.misses.length)
+            checks.push({ status: 'warn', text: `SCALE: ${scale.misses.length} of ${scale.judged} actor(s) off the scale sheet by > 20%`, items: scale.misses.slice(0, 12).map((m) => `${m.id}: ${m.h} m, the sheet says ${m.want} (${m.off > 0 ? '+' : ''}${Math.round(m.off * 100)}%)`) });
+        else
+            checks.push({ status: 'pass', text: `scale: ${scale.judged} actor(s) on the sheet` });
+        if (scale.spread.length)
+            checks.push({ status: 'warn', text: `SCALE: one kind, two sizes: ${scale.spread.map((s) => `${s.type} ${s.min}–${s.max} m (${s.n})`).join('; ')}` });
+    }
+    for (const f of framing) {
+        const c = framingCheck(f);
+        if (c)
+            checks.push(c);
+    }
+    if (stalls.length)
+        checks.push({ status: 'warn', text: `STALLS: ${stalls.length} stretch(es) where presses changed nothing for ≥ ${cfg.stallS} s`, items: stalls.map((s) => `${s.from_s}–${s.to_s} s ${s.kind === 'blocked' ? `blocked${s.by ? ` by ${s.by}` : ''}` : 'dead end: the state did not change'}${s.at ? ` at (${Math.round(s.at.x * 10) / 10}, ${Math.round(s.at.z * 10) / 10})` : ''}`) });
+    if (!ch)
+        checks.push({ status: 'not_observed', text: 'challenge: no state and no moment marks to read' });
+    else if (!ch.total && !losses.length)
+        checks.push({ status: 'warn', text: `NO CHALLENGE: nothing stumbled, detected, timed out or failed along ${route.name} — a walk nobody can lose`, hint: 'the hazards the plan names must fire on a plain walk (mark them with __FPX_MOMENT__(name) and count them in the state)' });
+    else if (ch.total)
+        checks.push({ status: 'pass', text: `challenge: ${Object.entries(ch.by).map(([k, v]) => `${k} ×${v}`).join(', ')}` });
+    if (losses.length) {
+        const stuck = losses.filter((l) => !l.retried);
+        checks.push(stuck.length
+            ? { status: 'warn', text: `LOST WITH NO WAY BACK: the run ended failed (${stuck[0].why}) and ${stuck[0].how} did not bring the player back to play within 6 s`, hint: 'a loss offers a retry a player can find: a button that says so, or Enter/tap, back to the last checkpoint' }
+            : { status: 'pass', text: `loss: the run ended failed ${losses.length} time(s) (${losses[0].why}) and the player came back through ${losses[0].how}` });
+    }
+    else if (ch?.total)
+        checks.push({ status: 'note', text: `penalties only on ${route.name}: nothing ended the run failed — whether a run can be lost is read by funtools sim (the naive bot must lose; a careful one at human pace must win)` });
+    const tv = crowdTravel(travel);
+    if (tv)
+        checks.push(tv);
+    checks.push(...crowdChecks(crowd, cfg.crowd));
+    let boxFrame = null;
+    if (worstShot && dir && boxes.meshes.size) {
+        boxFrame = join(WALK_DIR, `${route.name}-boxes.png`);
+        await writeFile(join(dir, boxFrame), worstShot).catch(() => { boxFrame = null; });
+    }
+    if (boxes.frames)
+        checks.push(walkBoxesCheck(boxes, boxFrame));
+    const figs = boxFiguresCheck([...boxes.figures.values()]);
+    if (figs)
+        checks.push(figs);
+    if (ground.reads)
+        checks.push(...groundingChecks(ground));
+    if (barest)
+        checks.push(dressingCheck(barest, `${route.name} (its barest stop)`, opts.viewport));
+    checks.push(...lifeVerdicts(anim, { hero: cfg.hero ?? null }).filter((c) => !(tv && /^A CROWD THAT NEVER TRAVELS|^people: /.test(c.text))));
+    const unobserved = legUnobserved(route, ctx.first, outcome, seconds);
+    if (unobserved)
+        checks.splice(0, checks.length, ...checks.filter((c) => c === leg.note || /did not all play/.test(c.text)), unobserved);
+    return {
+        name: route.name, from: route.from, outcome, seconds,
+        progress: { start: typeof p0 === 'number' ? p0 : null, end: route.progress && typeof field(s1, route.progress) === 'number' ? field(s1, route.progress) : null, field: route.progress },
+        source, film: filmed, frames: shots, clipping: clipList, placement: placeList, floating: floatList, scale, framing, stalls, challenges: ch,
+        losses, travel: tv ? { people: [...travel.values()].filter((x) => x.kind === 'person').length, moved: [...travel.values()].filter((x) => x.kind === 'person' && x.span >= TRAVEL_M).length } : null,
+        life: anim,
+        boxes: !unobserved && boxes.observed ? { frames: boxes.observed, worst_s: boxes.worst?.t ?? null, frame: boxFrame, meshes: [...boxes.meshes.values()].map((x) => ({ ...x.worst, frames: x.frames })).sort((a, b) => b.flat * b.frames - a.flat * a.frames) } : null,
+        grounding: !unobserved && ground.observed ? [...ground.things.values()].filter((g) => g.verdict === 'hovering' || g.verdict === 'overhang' || g.verdict === 'sunk') : null,
+        crowd: !unobserved && crowd.ids.size ? { people: crowd.ids.size, clumps: mergedClumps(crowd).length, inferred: crowd.inferred.size, gaps: crowd.gaps.map((g) => ({ from_m: g.from_m, length_m: g.length_m })) } : null,
+        ...(ctx.chain ? { chain: ctx.chain } : {}), checks,
+    };
+}
+async function walkChain(page, url, hooks, legs, cfg, opts, dir) {
+    const chain = legs.length > 1 ? legs.map((l) => l.name).join('+') : null;
+    const ctx = { film: null, filmStart: null, chain, last: legs.length === 1, first: true };
+    const out = [];
+    for (const [i, leg] of legs.entries()) {
+        ctx.first = i === 0;
+        ctx.last = i === legs.length - 1;
+        const rec = await walkRoute(page, url, hooks, leg, cfg, opts, dir, ctx);
+        out.push(rec);
+        if (rec.outcome === 'no_control' && !ctx.last) {
+            rec.checks.push({ status: 'warn', text: `the chain ${chain} stopped at ${leg.name}: the player never moved, so ${legs[i + 1].name} was not reached` });
+            if (ctx.filmStart?.ok && dir) {
+                rec.film = await stopFilm(page, join(dir, WALK_DIR, filmFile(chain ?? leg.name)));
+                ctx.film = rec.film;
+            }
+            break;
+        }
+    }
+    if (chain && ctx.film)
+        for (const r of out)
+            r.film = ctx.film;
+    return out;
+}
+export async function walk(opts, io = console) {
+    const u = ui(io, 'walk');
+    const r = await withPage(u, opts, async (page, t) => {
+        const cfg = { ...readWalk(t.manifest), style: await readStyleLock(t.dir, t.manifest), hero: typeof t.manifest.life?.hero === 'string' ? t.manifest.life.hero : null };
+        const { chains, problems } = chainsOf(cfg.routes, opts.routes, opts.chain ?? []);
+        cfg.problems.push(...problems);
+        if (!chains.length)
+            return `no route named ${[...opts.routes, ...(opts.chain ?? [])].join(', ')} (routes: ${cfg.routes.map((x) => x.name).join(', ')})`;
+        if (t.dir)
+            await mkdir(join(t.dir, WALK_DIR), { recursive: true });
+        await page.addInitScript(`(${pageScript('moments', { op: 'install' })})()`);
+        const done = [];
+        for (const legs of chains)
+            done.push(...(await walkChain(page, t.url, hookMapOf(t.manifest), legs, cfg, opts, t.dir)));
+        const record = { tool: 'funtools', command: 'walk', at: new Date().toISOString(), viewport: opts.viewport, problems: cfg.problems, routes: done, ...(t.dir ? { fingerprint: (await fingerprint(t.dir)).fingerprint, reads: sceneReads(t.dir) } : {}) };
+        if (t.dir)
+            await writeFile(join(t.dir, WALK_RECORD), JSON.stringify(record, null, 2) + '\n');
+        return record;
+    });
+    if (typeof r === 'number')
+        return r;
+    if (typeof r === 'string') {
+        u.error(r);
+        return EXIT.error;
+    }
+    const reached = r.routes.some((x) => x.outcome !== 'no_control');
+    const observed = reached && r.routes.some((x) => x.source !== 'none');
+    if (opts.json) {
+        io.log(JSON.stringify(r, null, 2));
+        return observed ? EXIT.pass : EXIT.not_observed;
+    }
+    for (const p of r.problems)
+        u.item('warn', p);
+    let warned = 0;
+    for (const x of r.routes) {
+        u.heading(`walk · ${x.chain ? `${x.chain} › ` : ''}${x.name}${x.from === 'fallback' ? ' (explore: no walk.routes declared)' : ''} · ${x.outcome.replace('_', ' ')} in ${x.seconds} s${x.progress.field ? ` · ${x.progress.field} ${x.progress.start ?? '?'} → ${x.progress.end ?? '?'}` : ''}`);
+        for (const c of x.checks) {
+            if (c.status === 'warn')
+                warned++;
+            u.item(c.status, c.text, c.hint);
+            for (const i of c.items ?? [])
+                u.line(i, 2);
+        }
+        if (x.film?.file)
+            u.line(`film ${x.film.file} (${Math.round(x.film.bytes / 1024)} kB, ${Math.round(x.film.ms / 100) / 10} s, real time, the play camera)`);
+        for (const f of x.frames)
+            u.line(`frame ${f}`);
+    }
+    u.summary(observed ? (warned ? 'warn' : 'pass') : 'not_observed', observed ? `${warned ? `${warned} warning(s)` : 'the world held up'} over ${r.routes.length} route(s) — a mirror, never a gate (${WALK_RECORD})` : 'no route reached play with actors to read: not a pass');
+    return observed ? EXIT.pass : EXIT.not_observed;
+}

package/dist/commands/widen.js

@@ -0,0 +1,133 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { designDoc } from "../gdd/doc.js";
+import { appendLedger, baseline, briefKey, DIALS, draw, freshSeed, GAME_LEDGER, homeLedger, keptFor, readLedger, readWiden, unexpectedness, WIDEN_FILE, WIDEN_MD, writeWiden, } from "../studio/widen.js";
+import { ui } from "../ui.js";
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+export function briefOf(root, given) {
+    if (given?.trim())
+        return given.trim();
+    const doc = designDoc(root)?.text ?? '';
+    const line = /^\s*\**Pitch:\**\s*(.+)$/im.exec(doc)?.[1]?.replace(/\*+/g, '').trim();
+    if (line && !/^<.*>$/.test(line))
+        return line;
+    const m = readJson(join(root, 'funpixel.json')) ?? {};
+    return String(m.description ?? m.metadata?.description ?? m.name ?? '').trim();
+}
+function inventionText(root) {
+    const t = designDoc(root)?.text ?? '';
+    return /^##\s+(the\s+)?invention\b[^\n]*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/im.exec(t)?.[2]?.replace(/<[^<>\n]{2,}>/g, '').trim() ?? '';
+}
+export async function widen(opts, io = console) {
+    const u = ui(io, 'pitch widen');
+    const root = resolve(opts.dir ?? '.');
+    const env = opts.env ?? process.env;
+    const ledgers = [readLedger(join(root, GAME_LEDGER)), readLedger(homeLedger(env))];
+    const genre = (readJson(join(root, 'funpixel.json')) ?? {}).metadata?.genre;
+    try {
+        if (opts.action === 'draw') {
+            const brief = briefOf(root, opts.brief);
+            if (!brief) {
+                u.error('no brief to widen', 'pass --brief "…", or write the GDD\'s **Pitch:** line');
+                return EXIT.error;
+            }
+            const dial = (opts.dial ?? 'open');
+            if (!DIALS.includes(dial)) {
+                u.error(`unknown dial: ${opts.dial}`, 'tight, open or wide');
+                return EXIT.error;
+            }
+            const seed = opts.seed !== undefined ? Number(opts.seed) : freshSeed();
+            if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+                u.error(`--seed must be a whole number from 0 to 4294967295, got ${opts.seed}`);
+                return EXIT.error;
+            }
+            const kept = keptFor(brief, ledgers);
+            const w = draw(brief, seed, dial, kept.values, genre, opts.now);
+            writeWiden(root, w);
+            if (opts.json) {
+                io.log(JSON.stringify(w, null, 2));
+                return EXIT.pass;
+            }
+            u.heading(`pitch widen · seed ${seed} · dial ${dial}`);
+            u.item('note', `the control: ${w.baseline.sentence}`, 'every card has to beat it');
+            for (const c of w.cards)
+                u.item('note', `${c.id} ${c.wildcard ? 'wildcard' : c.distance} · ${c.operator.label} · ${c.domain.thing}`, `${c.facets.verb}, ${c.facets.structure}, ${c.facets.material}, ${c.facets.mood}`);
+            if (w.avoided.length)
+                u.item('note', `steered away from what a ledger already kept for this brief: ${w.avoided.join(', ')}`);
+            u.summary('pass', `${WIDEN_FILE} + ${WIDEN_MD}: answer each card, then \`pitch widen score\`; replay this draw with --seed ${seed} --dial ${dial}`);
+            return EXIT.pass;
+        }
+        const w = readWiden(root);
+        if (opts.action === 'keep') {
+            if (!w) {
+                u.error(`no ${WIDEN_FILE}`, 'run `pitch widen` first');
+                return EXIT.not_observed;
+            }
+            const c = w.cards.find((x) => x.id.toLowerCase() === (opts.card ?? '').toLowerCase());
+            if (!c) {
+                u.error(`no card "${opts.card ?? ''}"`, `cards: ${w.cards.map((x) => x.id).join(', ')}`);
+                return EXIT.error;
+            }
+            const values = [c.domain.thing, ...Object.values(c.facets)];
+            const repeat = values.filter((v) => keptFor(w.brief, ledgers).values.includes(v));
+            const m = readJson(join(root, 'funpixel.json')) ?? {};
+            const entry = { brief: w.brief, briefKey: briefKey(w.brief), seed: w.seed, card: c.id, operator: c.operator.id, values, text: c.answer, ...(m.name ? { game: String(m.name) } : {}), at: (opts.now ?? new Date()).toISOString() };
+            appendLedger(join(root, GAME_LEDGER), entry);
+            appendLedger(homeLedger(env), entry);
+            if (opts.json) {
+                io.log(JSON.stringify({ ok: true, kept: entry, repeat }, null, 2));
+                return EXIT.pass;
+            }
+            if (repeat.length)
+                u.item('warn', `kept for this brief before: ${repeat.join(', ')}`, 'a repeat is allowed; say why it earns its place again');
+            if (!c.answer.trim())
+                u.item('warn', `${c.id} has no answer yet: the ledger keeps its facets only`);
+            u.summary('pass', `${c.id} kept in ${GAME_LEDGER} and ${homeLedger(env)}: the next widen of this brief steers away from it`);
+            return EXIT.pass;
+        }
+        const brief = w?.brief ?? briefOf(root, opts.brief);
+        if (!brief) {
+            u.error('no brief to score against', 'run `pitch widen` first, or pass --brief');
+            return EXIT.error;
+        }
+        const base = w?.baseline ?? baseline(brief, genre);
+        const kept = keptFor(brief, ledgers);
+        const inv = inventionText(root);
+        const candidates = [
+            ...(w?.cards ?? []).filter((c) => c.answer.trim()).map((c) => ({ id: c.id, text: c.answer })),
+            ...(inv ? [{ id: 'GDD ## The invention', text: inv }] : []),
+            ...(opts.text ? [{ id: '--text', text: opts.text }] : []),
+        ];
+        const scored = candidates.map((c) => ({ ...c, ...unexpectedness(c.text, base, brief, kept.texts) }));
+        if (opts.json) {
+            io.log(JSON.stringify({ brief, baseline: base, scored }, null, 2));
+            return scored.length ? EXIT.pass : EXIT.not_observed;
+        }
+        u.heading(`pitch widen score · the control: ${base.sentence}`);
+        if (!scored.length) {
+            u.summary('not_observed', `nothing to score: fill "answer" on the cards in ${WIDEN_FILE}, or pass --text`);
+            return EXIT.not_observed;
+        }
+        for (const s of scored) {
+            const why = s.verdict === 'restates' ? `restates what was kept before (${Math.round(s.archive.overlap * 100)}% the same words): "${s.archive.with}…"`
+                : s.verdict === 'generic' ? `reaches for the generic answer: ${s.generic.slice(0, 6).join(', ')}`
+                    : s.verdict === 'disconnected' ? 'strange, not connected: name what in the brief it answers'
+                        : s.verdict === 'empty' ? 'too short to read'
+                            : `unexpected and connected${s.generic.length ? `; still generic: ${s.generic.slice(0, 4).join(', ')}` : ''}`;
+            u.item(s.verdict === 'unexpected' ? 'pass' : 'warn', `${s.id}: unexpectedness ${s.score}/100 · ${s.verdict}`, why);
+        }
+        const best = [...scored].sort((a, b) => b.score - a.score)[0];
+        u.summary('pass', `furthest from the control: ${best.id} (${best.score}/100). Distance, not quality: pick for the game, then \`pitch widen keep <card>\``);
+        return EXIT.pass;
+    }
+    catch (e) {
+        u.error(e.message, 'funtools pitch --help');
+        return EXIT.error;
+    }
+}