@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/journey/from-round.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { roundDir } from "../play/session.js";
+import { fromPlayLog, JOURNEY_LIMITS, parseJourneyStep, stepMs } from "./script.js";
+export function fitSteps(steps, phone) {
+    let ms = 0;
+    for (let i = 0; i < steps.length; i++) {
+        const s = parseJourneyStep(steps[i], phone);
+        ms += typeof s === 'string' ? 0 : stepMs(s);
+        if (i + 1 > JOURNEY_LIMITS.steps || ms > JOURNEY_LIMITS.totalMs) {
+            return { steps: steps.slice(0, i), trimmed: `cut at step ${i + 1} of ${steps.length}: a journey plays up to ${JOURNEY_LIMITS.steps} steps and ${JOURNEY_LIMITS.totalMs / 60_000} minutes` };
+        }
+    }
+    return { steps, trimmed: null };
+}
+export function journeyFromRound(root, round, name, seed, opts = {}) {
+    const dir = roundDir(root, round);
+    if (!existsSync(join(dir, 'log.jsonl')))
+        return `no play round ${round} with a log here`;
+    const report = (() => { try {
+        return JSON.parse(readFileSync(join(dir, 'report.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    } })();
+    const log = readFileSync(join(dir, 'log.jsonl'), 'utf8').split('\n').filter(Boolean).flatMap((l) => { try {
+        return [JSON.parse(l)];
+    }
+    catch {
+        return [];
+    } });
+    const phone = report?.viewport === 'phone';
+    const built = fromPlayLog(log, phone);
+    if (built.steps.filter((s) => !s.startsWith('mark ')).length === 0)
+        return `round ${round} has no control steps before its first jump${built.cut ? ` (${built.cut})` : ''}`;
+    const fitted = opts.fit ? fitSteps(built.steps, phone) : { steps: built.steps, trimmed: null };
+    const size = String(report?.size ?? '');
+    const orientation = phone && /^(\d+)x(\d+)$/.test(size) ? (Number(size.split('x')[0]) > Number(size.split('x')[1]) ? 'landscape' : 'portrait') : undefined;
+    const journey = {
+        name, viewport: phone ? 'phone' : 'desktop', ...(orientation ? { orientation } : {}), seed, steps: fitted.steps,
+        source: `play round ${round}${report?.fingerprint ? ` on ${String(report.fingerprint).slice(0, 19)}` : ''}`,
+    };
+    return { journey, acts: built.acts, cut: built.cut, thinned: built.thinned, trimmed: fitted.trimmed };
+}

package/dist/journey/record.js

@@ -0,0 +1,76 @@
+import { launch, lookPage, viewportUrl } from "../verify/browser.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { load, openTarget } from "../look/look.js";
+import { stepsFromEvents } from "./script.js";
+export const RECORDER = `(() => {
+  if (window.__FPX_JOURNEY_REC__) return;
+  const rec = window.__FPX_JOURNEY_REC__ = [];
+  const now = () => performance.now();
+  const opt = { capture: true, passive: true };
+  addEventListener('pointerdown', (e) => rec.push({ t: now(), type: 'down', id: e.pointerId, x: e.clientX, y: e.clientY }), opt);
+  addEventListener('pointerup', (e) => rec.push({ t: now(), type: 'up', id: e.pointerId, x: e.clientX, y: e.clientY }), opt);
+  addEventListener('pointercancel', (e) => rec.push({ t: now(), type: 'up', id: e.pointerId, x: e.clientX, y: e.clientY }), opt);
+  addEventListener('keydown', (e) => { if (!e.repeat) rec.push({ t: now(), type: 'keydown', code: e.code }); }, opt);
+  addEventListener('keyup', (e) => rec.push({ t: now(), type: 'keyup', code: e.code }), opt);
+})();`;
+const SCREEN = `(() => { try { const s = window.__FPX_STATE__ && window.__FPX_STATE__(); return s && typeof s.screen === 'string' ? s.screen : null; } catch (e) { return null; } })()`;
+export async function record(opts) {
+    const t = await openTarget(opts.root);
+    if (typeof t === 'string')
+        return t;
+    const orientation = opts.viewport !== 'phone' ? '' : opts.orientation ?? (typeof t.manifest.metadata?.orientation === 'string' ? t.manifest.metadata.orientation : '');
+    const { browser } = await launch(false, true, !opts.drive);
+    const events = [];
+    const screens = [];
+    let done = false;
+    const finish = () => { done = true; };
+    process.once('SIGINT', finish);
+    try {
+        const page = await lookPage(browser, opts.viewport, orientation);
+        page.on('close', finish);
+        browser.on('disconnected', finish);
+        await page.addInitScript(`window.__FPX_SEED__ = ${JSON.stringify(opts.seed)};`);
+        await page.addInitScript(RECORDER);
+        await load(page, viewportUrl(t.url, opts.viewport), hookMapOf(t.manifest));
+        const size = page.viewportSize() ?? { width: 1280, height: 720 };
+        const start = Number(await page.evaluate('performance.now()'));
+        const first = await page.evaluate(SCREEN).catch(() => null);
+        if (first)
+            screens.push(first);
+        opts.note?.(opts.drive ? 'recording (driven)' : `recording: play in the window; close it (or Ctrl-C) to keep the journey — at most ${opts.seconds} s`);
+        let last = first;
+        const poll = async () => {
+            const batch = await page.evaluate('(window.__FPX_JOURNEY_REC__ || []).splice(0)').catch(() => null);
+            if (batch)
+                events.push(...batch);
+            const screen = await page.evaluate(SCREEN).catch(() => null);
+            if (screen && screen !== last) {
+                events.push({ t: Number(await page.evaluate('performance.now()').catch(() => NaN)), type: 'screen', screen });
+                screens.push(screen);
+                last = screen;
+            }
+        };
+        const until = Date.now() + opts.seconds * 1000;
+        const driving = opts.drive?.(page).then(finish, finish);
+        while (!done && Date.now() < until) {
+            await poll();
+            await new Promise((r) => setTimeout(r, 150));
+        }
+        await driving;
+        if (!page.isClosed())
+            await poll();
+        const end = events.length ? Math.max(...events.map((e) => e.t)) : start;
+        const { steps, overlapped } = stepsFromEvents(events, size, start);
+        const opening = `mark start${first ? ` screen=${first.replace(/\s+/g, '_')}` : ''}`;
+        const closing = steps.length && steps[steps.length - 1].startsWith('mark ') ? [] : [`mark end${last ? ` screen=${last.replace(/\s+/g, '_')}` : ''}`];
+        return {
+            steps: [opening, ...steps, ...closing], overlapped, events: events.filter((e) => e.type !== 'screen').length,
+            seconds: Math.round((end - start) / 100) / 10, screens, size: `${size.width}x${size.height}`,
+        };
+    }
+    finally {
+        process.removeListener('SIGINT', finish);
+        await browser.close().catch(() => { });
+        await t.close();
+    }
+}

package/dist/journey/run.js

@@ -0,0 +1,139 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { launch, lookPage, viewportUrl, touchSession } from "../verify/browser.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { load, openTarget } from "../look/look.js";
+import { armMoments, drainMoments } from "../look/moments.js";
+import { gesture } from "../play/input.js";
+import { PLAY_CLOCK } from "../play/clock.js";
+import { PLAY_POINTER } from "../play/pointer.js";
+import { counters, judgeExpect, JOURNEY_RUNS } from "./script.js";
+import { rendererOf, timingVoid } from "../verify/gpu.js";
+export const scriptHash = (j) => createHash('sha256').update(JSON.stringify({ viewport: j.viewport, orientation: j.orientation ?? '', seed: j.seed, steps: j.steps })).digest('hex').slice(0, 16);
+export const runsDir = (root, name) => join(root, JOURNEY_RUNS, name);
+export function runsOf(root, name) {
+    const dir = runsDir(root, name);
+    return existsSync(dir) ? readdirSync(dir).filter((d) => /^\d+$/.test(d) && existsSync(join(dir, d, 'run.json'))).map(Number).sort((a, b) => a - b) : [];
+}
+export function readRun(root, name, n) {
+    try {
+        return JSON.parse(readFileSync(join(runsDir(root, name), String(n), 'run.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function runVerdict(r) {
+    const all = r.marks.flatMap((m) => m.expect.map((e) => ({ mark: m.name, ...e })));
+    const failed = all.filter((e) => e.verdict === 'fail');
+    if (r.step_errors.length)
+        return { verdict: 'fail', why: `step ${r.step_errors[0].n} (${r.step_errors[0].step}) did not play: ${r.step_errors[0].error}` };
+    if (failed.length) {
+        const f = failed[0];
+        return { verdict: 'fail', why: `at ${f.mark}: ${f.field} ${f.op} ${f.want} expected, ${f.got === undefined ? 'nothing' : JSON.stringify(f.got)} found` };
+    }
+    const unseen = all.filter((e) => e.verdict === 'not_observed');
+    if (!all.length)
+        return { verdict: 'not_observed', why: 'no mark expects anything: the frames and counters are kept, nothing was judged' };
+    if (unseen.length) {
+        const u = unseen[0];
+        return { verdict: 'not_observed', why: `at ${u.mark}: ${u.field} could not be read${r.marks.some((m) => m.state_observed) ? '' : ' (the page answers no __FPX_STATE__)'}` };
+    }
+    return { verdict: 'pass', why: `${all.length} expectation(s) held at ${new Set(all.map((e) => e.mark)).size} mark(s)` };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const STATE = `(() => { try { const s = window.__FPX_STATE__ && window.__FPX_STATE__(); return s === undefined ? null : JSON.parse(JSON.stringify(s)); } catch (e) { return null; } })()`;
+export async function replay(opts) {
+    const { root, journey: j } = opts;
+    const t = await openTarget(root);
+    if (typeof t === 'string')
+        return t;
+    const n = (runsOf(root, j.name).at(-1) ?? 0) + 1;
+    const dir = join(runsDir(root, j.name), String(n));
+    await mkdir(dir, { recursive: true });
+    const orientation = j.viewport !== 'phone' ? '' : j.orientation ?? (typeof t.manifest.metadata?.orientation === 'string' ? t.manifest.metadata.orientation : '');
+    const fp = await fingerprint(root).then((f) => f.fingerprint).catch(() => null);
+    const t0 = Date.now();
+    const { browser } = await launch(false, true);
+    const errors = [];
+    let lost = '';
+    try {
+        const page = await lookPage(browser, j.viewport, orientation);
+        page.on('pageerror', (e) => errors.push(String(e.message ?? e).slice(0, 300)));
+        page.on('console', (m) => { if (m.type() === 'error')
+            errors.push(m.text().slice(0, 300)); });
+        page.on('crash', () => { lost ||= 'the browser tab crashed (renderer)'; });
+        page.on('close', () => { lost ||= 'the browser tab closed'; });
+        browser.on('disconnected', () => { lost ||= 'the browser went away'; });
+        await page.addInitScript(`window.__FPX_SEED__ = ${JSON.stringify(j.seed)};`);
+        await page.addInitScript(PLAY_CLOCK);
+        await page.addInitScript(PLAY_POINTER);
+        await load(page, viewportUrl(t.url, j.viewport), hookMapOf(t.manifest));
+        await armMoments(page);
+        const phone = j.viewport === 'phone';
+        let cdp = null;
+        const touch = async () => (cdp ??= await touchSession(page));
+        const clock = (op) => page.evaluate(`window.__FPX_PLAY_CLOCK__ && window.__FPX_PLAY_CLOCK__.${op}()`).catch(() => { });
+        const size = page.viewportSize() ?? { width: 1280, height: 720 };
+        const renderer = await rendererOf(page);
+        const marks = [];
+        const step_errors = [];
+        let errorsSeen = 0, stepNo = 0, playedMs = 0;
+        const markAt = async (m) => {
+            await clock('pause');
+            const frame = join(dir, `${String(marks.length).padStart(2, '0')}-${m.name}.png`);
+            await page.screenshot({ path: frame, scale: 'css' });
+            const state = await page.evaluate(STATE).catch(() => null);
+            const moments = (await drainMoments(page)).map((x) => x.name);
+            marks.push({
+                name: m.name, step: stepNo, at_ms: playedMs, frame, state_observed: state !== null, counters: counters(state),
+                expect: m.expect.map((e) => judgeExpect(e, state)), moments, page_errors: errors.slice(errorsSeen),
+            });
+            errorsSeen = errors.length;
+            await clock('resume');
+        };
+        const paired = opts.steps.map((s, i) => ({ s, text: j.steps[i] ?? '' }));
+        if (opts.steps[0]?.kind !== 'mark')
+            paired.unshift({ s: { kind: 'mark', name: 'loaded', expect: [] }, text: 'mark loaded' });
+        for (const { s, text } of paired) {
+            if (lost)
+                break;
+            if (s.kind === 'mark') {
+                await markAt(s);
+                continue;
+            }
+            stepNo++;
+            const began = Date.now();
+            try {
+                if (s.kind === 'wait' || s.kind === 'clip')
+                    await sleep(s.ms);
+                else
+                    await gesture(page, touch, phone, s.kind === 'together' ? s.parts : [s]);
+            }
+            catch (e) {
+                step_errors.push({ n: stepNo, step: text, error: String(e?.message ?? e).split('\n')[0] });
+                break;
+            }
+            playedMs += Date.now() - began;
+        }
+        const result = {
+            journey: j.name, run: n, at: new Date().toISOString(), viewport: j.viewport, orientation, size: `${size.width}x${size.height}`,
+            seed: j.seed, script: scriptHash(j), fingerprint: fp, steps: stepNo, step_errors, marks, page_errors: errors.slice(0, 20),
+            browser_lost: lost, ms: Date.now() - t0, renderer,
+        };
+        let v = lost ? { verdict: 'not_observed', why: `${lost} at step ${stepNo}: not evidence about the game; replay again` } : runVerdict(result);
+        const slow = timingVoid(renderer);
+        if (v.verdict === 'fail' && slow)
+            v = { verdict: 'not_observed', why: `VOID fail (${v.why}): ${slow}` };
+        const run = { ...result, ...v };
+        await writeFile(join(dir, 'run.json'), JSON.stringify(run, null, 2) + '\n');
+        return run;
+    }
+    finally {
+        await browser.close().catch(() => { });
+        await t.close();
+    }
+}

package/dist/journey/script.js

@@ -0,0 +1,223 @@
+import { fixedSteps, parseStep, STEP_LIMITS } from "../play/steps.js";
+import { parseExpect } from "../play/condition.js";
+export { fieldOf, judgeExpect } from "../play/condition.js";
+export const JOURNEY_DIR = 'test/journeys';
+export const JOURNEY_RUNS = '.funtools/journeys';
+export const JOURNEY_LIMITS = { steps: 600, marks: 40, totalMs: 10 * 60_000 };
+const NAME = /^[a-z0-9][a-z0-9-]{0,47}$/;
+export function parseJourneyStep(text, phone) {
+    const t = text.trim();
+    if (/^mark\b/.test(t)) {
+        const [, name, ...rest] = t.split(/\s+/);
+        if (!name || !NAME.test(name))
+            return `${t}: mark NAME [field op value …] (a name in lower case, digits and -)`;
+        const expect = [];
+        for (const r of rest) {
+            const e = parseExpect(r);
+            if (!e)
+                return `${t}: "${r}" is not an expectation (field=value, field>3, score>=1, screen!=title)`;
+            expect.push(e);
+        }
+        return { kind: 'mark', name, expect };
+    }
+    const s = parseStep(t, phone);
+    if (typeof s === 'string')
+        return s;
+    if (s.kind === 'view' || s.kind === 'verb') {
+        return `${t}: a journey plays the controls only — "${s.kind}" reaches a state without them (that is a diagnostic scene: funtools capture --view)`;
+    }
+    if (s.kind === 'shot')
+        return `${t}: a journey keeps frames at its marks — write "mark NAME" instead of "shot"`;
+    if (s.kind === 'until')
+        return `${t}: a journey replays fixed times — write the hold or wait with the time it took (journey from-play does this from the round's log)`;
+    return s;
+}
+export function stepMs(s) {
+    switch (s.kind) {
+        case 'wait':
+        case 'drag':
+        case 'hold_at':
+        case 'hold_key':
+        case 'look': return s.ms;
+        case 'press': return s.times * 60;
+        case 'together': return Math.max(...s.parts.map(stepMs));
+        case 'tap': return 60;
+        default: return 0;
+    }
+}
+export function checkJourney(raw) {
+    const problems = [];
+    const j = raw;
+    if (!j || typeof j !== 'object')
+        return { problems: ['a journey is a JSON object'] };
+    if (typeof j.name !== 'string' || !NAME.test(j.name))
+        problems.push('name: lower case, digits and -, up to 48');
+    if (j.viewport !== 'desktop' && j.viewport !== 'phone')
+        problems.push('viewport: desktop or phone');
+    if (j.orientation !== undefined && j.orientation !== 'portrait' && j.orientation !== 'landscape')
+        problems.push('orientation: portrait or landscape');
+    if (j.orientation !== undefined && j.viewport !== 'phone')
+        problems.push('orientation turns a phone: the viewport is phone');
+    if (!Number.isInteger(j.seed))
+        problems.push('seed: a whole number (window.__FPX_SEED__)');
+    if (!Array.isArray(j.steps) || !j.steps.length)
+        problems.push('steps: a list of steps');
+    if (problems.length)
+        return { problems };
+    if (j.steps.length > JOURNEY_LIMITS.steps)
+        problems.push(`${j.steps.length} steps: a journey holds ${JOURNEY_LIMITS.steps}; split it at a mark`);
+    const steps = [];
+    j.steps.forEach((text, i) => {
+        const s = typeof text === 'string' ? parseJourneyStep(text, j.viewport === 'phone') : `step ${i + 1} is not text`;
+        if (typeof s === 'string')
+            problems.push(`step ${i + 1}: ${s}`);
+        else
+            steps.push(s);
+    });
+    const marks = steps.filter((s) => s.kind === 'mark');
+    if (marks.length > JOURNEY_LIMITS.marks)
+        problems.push(`${marks.length} marks: a journey keeps ${JOURNEY_LIMITS.marks} frames`);
+    const names = marks.map((m) => m.name);
+    const twice = names.filter((n, i) => names.indexOf(n) !== i);
+    if (twice.length)
+        problems.push(`marks named twice: ${[...new Set(twice)].join(', ')} (runs compare mark by name)`);
+    const total = steps.reduce((t, s) => t + stepMs(s), 0);
+    if (total > JOURNEY_LIMITS.totalMs)
+        problems.push(`${Math.round(total / 1000)} s of play: a journey runs up to ${JOURNEY_LIMITS.totalMs / 60_000} minutes`);
+    return problems.length ? { problems } : { journey: j, steps, problems };
+}
+export function counters(state) {
+    const out = {};
+    if (!state || typeof state !== 'object')
+        return out;
+    const put = (k, v, depth) => {
+        if (v === null || typeof v === 'number' || typeof v === 'boolean')
+            out[k] = v;
+        else if (typeof v === 'string')
+            out[k] = v.length > 80 ? `${v.slice(0, 77)}…` : v;
+        else if (Array.isArray(v))
+            out[`${k}.length`] = v.length;
+        else if (typeof v === 'object' && depth < 1)
+            for (const [kk, vv] of Object.entries(v))
+                put(`${k}.${kk}`, vv, depth + 1);
+    };
+    for (const [k, v] of Object.entries(state))
+        put(k, v, 0);
+    return out;
+}
+export function fromPlayLog(lines, phone) {
+    const steps = [];
+    let cut = null;
+    let acts = 0;
+    for (const l of lines) {
+        if (typeof l.step === 'string') {
+            if (!l.ok)
+                continue;
+            if (/^(view|verb)\b/.test(l.step.trim())) {
+                cut = `step ${l.n}: "${l.step}" jumped past the controls; the journey stops before it`;
+                break;
+            }
+            if (l.step.trim() === 'shot')
+                continue;
+            const u = parseStep(l.step, phone);
+            if (typeof u !== 'string' && u.kind === 'until') {
+                if (typeof l.ms === 'number')
+                    steps.push(...fixedSteps(u, l.ms));
+                continue;
+            }
+            const s = parseJourneyStep(l.step, phone);
+            if (typeof s !== 'string')
+                steps.push(l.step.trim());
+            continue;
+        }
+        if (l.shot && l.state !== undefined) {
+            const screen = l.state && typeof l.state === 'object' && typeof l.state.screen === 'string' ? ` screen=${l.state.screen.replace(/\s+/g, '_')}` : '';
+            steps.push(l.n === 0 ? `mark start${screen}` : `mark act-${++acts}${screen}`);
+        }
+    }
+    const thinned = thinMarks(steps, JOURNEY_LIMITS.marks);
+    return { steps, cut, acts, thinned };
+}
+function thinMarks(steps, cap) {
+    const at = steps.map((s, i) => (s.startsWith('mark ') ? i : -1)).filter((i) => i >= 0);
+    if (at.length <= cap)
+        return 0;
+    const screenOf = (i) => /screen=(\S+)/.exec(steps[i])?.[1] ?? '';
+    const keep = new Set([at[0], at[at.length - 1]]);
+    for (let k = 1; k < at.length && keep.size < cap; k++)
+        if (screenOf(at[k]) !== screenOf(at[k - 1]))
+            keep.add(at[k]);
+    const rest = at.filter((i) => !keep.has(i));
+    const room = cap - keep.size;
+    for (let k = 0; k < room; k++)
+        keep.add(rest[Math.floor(((k + 0.5) * rest.length) / room)]);
+    const drop = at.filter((i) => !keep.has(i));
+    for (const i of drop.reverse())
+        steps.splice(i, 1);
+    return drop.length;
+}
+const KEY = /^(?:Space|Enter|Escape|Tab|Backspace|(?:Shift|Control|Alt)(?:Left|Right)?|Arrow(?:Up|Down|Left|Right)|Key[A-Z]|Digit[0-9]|F[1-9]|F1[0-2])$/;
+const TAP_PX = 8, TAP_MS = 250, KEY_TAP_MS = 150;
+const frac = (v, size) => Math.min(1, Math.max(0, v / size)).toFixed(4);
+export function stepsFromEvents(events, size, startT) {
+    const items = [];
+    const downs = new Map();
+    const keys = new Map();
+    let overlapped = 0;
+    const seen = new Set(['start', 'end', 'loaded']);
+    for (const e of [...events].sort((a, b) => a.t - b.t)) {
+        if (e.type === 'down' && e.id !== undefined) {
+            if (downs.size)
+                overlapped++;
+            downs.set(e.id, e);
+        }
+        else if (e.type === 'up' && e.id !== undefined) {
+            const d = downs.get(e.id);
+            downs.delete(e.id);
+            if (!d || d.x === undefined || d.y === undefined || e.x === undefined || e.y === undefined)
+                continue;
+            const ms = Math.max(0, Math.round(e.t - d.t));
+            const moved = Math.hypot(e.x - d.x, e.y - d.y);
+            const [x1, y1, x2, y2] = [frac(d.x, size.width), frac(d.y, size.height), frac(e.x, size.width), frac(e.y, size.height)];
+            const text = moved <= TAP_PX
+                ? (ms <= TAP_MS ? `tap ${x1} ${y1}` : `hold ${x1} ${y1} ${Math.min(ms, STEP_LIMITS.maxMs)}`)
+                : `drag ${x1} ${y1} ${x2} ${y2} ${Math.min(Math.max(ms, 30), STEP_LIMITS.maxMs)}`;
+            items.push({ t0: d.t, t1: e.t, text });
+        }
+        else if (e.type === 'keydown' && e.code && KEY.test(e.code)) {
+            if (!keys.has(e.code)) {
+                if (keys.size || downs.size)
+                    overlapped++;
+                keys.set(e.code, e.t);
+            }
+        }
+        else if (e.type === 'keyup' && e.code && keys.has(e.code)) {
+            const t0 = keys.get(e.code);
+            keys.delete(e.code);
+            const ms = Math.round(e.t - t0);
+            items.push({ t0, t1: e.t, text: ms <= KEY_TAP_MS ? `press ${e.code}` : `hold ${e.code} ${Math.min(ms, STEP_LIMITS.maxMs)}` });
+        }
+        else if (e.type === 'screen' && e.screen) {
+            const base = e.screen.replace(/[^a-z0-9-]+/gi, '-').toLowerCase().replace(/^-|-$/g, '') || 'screen';
+            let name = base, i = 2;
+            while (seen.has(name))
+                name = `${base}-${i++}`;
+            seen.add(name);
+            items.push({ t0: e.t, t1: e.t, text: `mark ${name} screen=${e.screen.replace(/\s+/g, '_')}` });
+        }
+    }
+    items.sort((a, b) => a.t0 - b.t0);
+    const steps = [];
+    let clock = startT ?? (items.length ? items[0].t0 : 0);
+    for (const it of items) {
+        let gap = Math.round(it.t0 - clock);
+        while (gap >= 20) {
+            const w = Math.min(gap, STEP_LIMITS.maxMs);
+            steps.push(`wait ${w}`);
+            gap -= w;
+        }
+        steps.push(it.text);
+        clock = Math.max(clock, it.t1);
+    }
+    return { steps, overlapped };
+}

package/dist/judge/common.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export const JUDGE_DIR = join('.funtools', 'judge');
+export const PANEL = new URL('../../panel/', import.meta.url);
+const MAGIC = [
+    ['png', (b) => b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))],
+    ['jpeg', (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff],
+    ['webp', (b) => b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP'],
+];
+export function pictureKind(bytes) {
+    return MAGIC.find(([, is]) => is(bytes))?.[0] ?? null;
+}
+export const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+export function readPic(label, file) {
+    if (!existsSync(file) || !statSync(file).isFile())
+        return { missing: `no picture at ${file}` };
+    const bytes = readFileSync(file);
+    if (!pictureKind(bytes))
+        return { bad: `${file} is not a PNG, JPEG or WebP picture` };
+    return { label, file, sha256: sha256(bytes) };
+}
+export function picturesIn(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [];
+    return readdirSync(dir)
+        .filter((f) => /\.(png|jpe?g|webp)$/i.test(f) && !/^(contact[_-]?sheet|grid_|sheet\b)/i.test(f))
+        .sort()
+        .map((f) => join(dir, f));
+}
+export function spread(xs, n) {
+    if (xs.length <= n)
+        return xs;
+    return Array.from({ length: n }, (_, i) => xs[Math.round((i * (xs.length - 1)) / (n - 1))]);
+}
+export function changed(p) {
+    try {
+        return sha256(readFileSync(p.file)) !== p.sha256;
+    }
+    catch {
+        return true;
+    }
+}
+export function runs(root) {
+    const d = join(root, JUDGE_DIR);
+    return existsSync(d) ? readdirSync(d).filter((x) => /^\d+$/.test(x)).map(Number).sort((a, b) => a - b) : [];
+}
+export function readAnswer(file) {
+    if (!existsSync(file))
+        return { problem: 'not filed' };
+    const raw = readFileSync(file, 'utf8');
+    try {
+        return { answer: JSON.parse(raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1)) };
+    }
+    catch {
+        return { problem: 'no JSON in the answer' };
+    }
+}
+export const hasEvidence = (e) => typeof e === 'string' && e.replace(/[.…\s]/g, '').length >= 4;
+export const filing = (answer) => `\n## Filing\n\nWrite your JSON answer, and nothing else, to this file with your file-writing tool:\n${answer}\nThen reply with one line: \`filed\`. You read nothing but the pictures named above.\n`;

package/dist/judge/identity.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+import { filing, hasEvidence, PANEL } from "./common.js";
+export const IDENTITY_RUBRIC = 1;
+export const TRAITS = [
+    { id: 'silhouette', ask: 'the outline filled black: the shapes that stick out (ears, horns, hat, weapon, tail, cape) and the overall mass.' },
+    { id: 'palette', ask: 'the main colours and where each sits (red coat, gold trim, blue eyes), by hue family under the view\'s light.' },
+    { id: 'features', ask: 'the key features you listed: each one present, on the right side, the right shape and colour.' },
+    { id: 'proportions', ask: 'head to body, limb length, build (stocky, lanky), the size of signature parts against the body.' },
+];
+export const LEVELS = ['none', 'minor', 'major'];
+const MEDIUM = {
+    model: 'The views are renders of the 3D model from around it (a turntable), under neutral light. The concept is usually one front view: a part it shows from the front is judged in the views that face it, and the back of the model is judged only for what the concept implies (a cape that runs to the back, a tail).',
+    sprites: 'The views are the frames or poses of one character\'s sprite set. The pose changes by design; the character must not. An expression or a limb position the pose asks for is animation, not drift.',
+};
+export function identityPrompt(concept, views, medium, answer) {
+    const keys = TRAITS.map((t, i) => `        "${t.id}": { "level": "none|minor|major|unseen", "evidence": "…"${t.id === 'features' ? ', "lost": [], "gained": [], "changed": []' : ''} }${i < TRAITS.length - 1 ? ',' : ''}`).join('\n');
+    return readFileSync(new URL('asset-identity.md', PANEL), 'utf8')
+        .replaceAll('{{WHAT}}', medium === 'model' ? 'a 3D model, seen in several views,' : 'a character\'s sprite set')
+        .replaceAll('{{CONCEPT}}', `- CONCEPT: ${concept.file}`)
+        .replaceAll('{{VIEWS}}', views.map((v) => `- ${v.label}: ${v.file}`).join('\n'))
+        .replaceAll('{{MEDIUM}}', MEDIUM[medium])
+        .replaceAll('{{TRAITS}}', TRAITS.map((t) => `- **${t.id}**: ${t.ask}`).join('\n'))
+        .replaceAll('{{ANSWER_KEYS}}', keys) + filing(answer);
+}
+const rank = (l) => (l === 'unseen' ? -1 : LEVELS.indexOf(l));
+const strings = (x) => (Array.isArray(x) ? x.filter((s) => typeof s === 'string' && !!s.trim()) : []);
+export function judgeIdentity(views, answer) {
+    const list = Array.isArray(answer?.views) ? answer.views : [];
+    const features = strings(answer?.features);
+    const entries = views.map((v, i) => ({ v, e: list.find((x) => String(x?.view ?? '').trim() === v.label) ?? (list.every((x) => !x?.view) ? list[i] : undefined) }));
+    const unanswered = entries.filter((x) => !x.e).map((x) => x.v.label);
+    const traits = TRAITS.map(({ id }) => {
+        const out = { trait: id, state: 'not_observed', worst: null, levels: [], lost: [], gained: [], changed: [] };
+        for (const { v, e } of entries) {
+            if (!e)
+                continue;
+            const raw = e.traits?.[id];
+            const evidence = typeof raw?.evidence === 'string' ? raw.evidence.trim() : '';
+            let level = String(raw?.level ?? '').trim().toLowerCase();
+            let why;
+            if (!LEVELS.includes(level) && level !== 'unseen') {
+                why = raw ? `level "${String(raw.level).slice(0, 30)}"` : 'not answered';
+                level = 'unseen';
+            }
+            else if (level !== 'unseen' && !hasEvidence(evidence)) {
+                why = 'no evidence given';
+                level = 'unseen';
+            }
+            out.levels.push({ view: v.label, level, evidence, ...(why ? { why } : {}) });
+            if (id === 'features' && level !== 'unseen') {
+                out.lost.push(...strings(raw?.lost).map((s) => `${v.label}: ${s}`));
+                out.gained.push(...strings(raw?.gained).map((s) => `${v.label}: ${s}`));
+                out.changed.push(...strings(raw?.changed).map((s) => `${v.label}: ${s}`));
+            }
+            if (level !== 'unseen' && (!out.worst || rank(level) > rank(out.worst.level)))
+                out.worst = { level, view: v.label, file: v.file, evidence };
+        }
+        if (id === 'features' && !features.length) {
+            out.worst = null;
+            return out;
+        }
+        out.state = !out.worst ? 'not_observed' : out.worst.level === 'major' ? 'fail' : out.worst.level === 'minor' ? 'warn' : 'pass';
+        return out;
+    });
+    const states = traits.map((t) => t.state);
+    const state = states.includes('fail') ? 'fail' : states.includes('not_observed') || unanswered.length === views.length ? 'not_observed' : 'pass';
+    return { state, features, traits, unanswered };
+}

package/dist/judge/sources.js

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { readAssetManifest, targetOf } from "../assets/manifest.js";
+import { keyOf } from "../gen/record.js";
+import { picturesIn, spread } from "./common.js";
+export const MAX_VIEWS = 8;
+function itemFor(root, file) {
+    const key = keyOf(root, file);
+    if (!key)
+        return null;
+    let items;
+    try {
+        items = readAssetManifest(root);
+    }
+    catch {
+        return null;
+    }
+    const item = items.find((it) => targetOf(it) === key);
+    return item ? { item, items } : null;
+}
+export function subjectFor(root, file) {
+    const it = itemFor(root, file)?.item;
+    return it?.subject?.trim() || it?.prompt?.trim() || null;
+}
+export function conceptFor(root, model) {
+    const found = itemFor(root, model);
+    const src = found?.item.from ? found.items.find((it) => it.name === found.item.from) : undefined;
+    const path = src ? join(root, targetOf(src)) : null;
+    return path && existsSync(path) ? path : null;
+}
+export function renderedViews(root, model) {
+    const dir = join(root, '.funtools', 'renders', basename(model, extname(model)));
+    const all = picturesIn(dir);
+    const turn = all.filter((f) => /^turn_\d+\./i.test(basename(f)));
+    const named = all.filter((f) => /^view_/i.test(basename(f)));
+    return { dir, files: spread(turn.length ? turn : named.length ? named : all, MAX_VIEWS) };
+}