@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/look/look.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pageScript } from '../vendor/verify/src/index.js';
+import { errors } from 'playwright-core';
+import { servedRoot } from "../commands/verify.js";
+import { kaptureScript } from "../dev/devtools.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { NETWORK_IDLE_MS } from "../verify/probe.js";
+import { serveDir } from "../verify/serve.js";
+import { advance, BOOT_MS } from "./held.js";
+export const FRONT_DOOR = '[data-fpx-start]';
+export const FRONT_DOOR_ARGS = { timeout_ms: 3000, press_ms: 80, settle_ms: 800 };
+export const LAYOUT = { min_text_px: 12, min_target: 44, max_items: 12 };
+export const SAFE_PORTRAIT = { top: 47, right: 0, bottom: 34, left: 0 };
+export const SAFE_LANDSCAPE = { top: 0, right: 47, bottom: 21, left: 47 };
+export const NO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
+export const SCENE_ARGS = { max_nodes: 20_000, max_listed: 20, phone_max_side: 2048 };
+export async function openTarget(target = '.', root = null) {
+    if (/^https?:\/\//.test(target))
+        return { url: target, dir: null, manifest: {}, close: async () => { } };
+    const dir = resolve(target);
+    root ??= servedRoot(dir);
+    if (!root)
+        return `no dist/index.html in ${dir}`;
+    const served = await serveDir(root);
+    let manifest = {};
+    const path = join(dir, 'funpixel.json');
+    if (existsSync(path)) {
+        try {
+            manifest = JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch { }
+    }
+    return { url: served.url, dir, manifest, close: () => served.close() };
+}
+export async function evalJson(page, name, args) {
+    try {
+        const raw = await page.evaluate(`(${pageScript(name, args)})()`);
+        return typeof raw === 'string' ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function load(page, url, hooks, held = false) {
+    const late = (e) => { if (!(e instanceof errors.TimeoutError))
+        throw e; };
+    await page.goto(url, { waitUntil: 'load', timeout: 30_000 }).catch(late);
+    await page.waitForLoadState('networkidle', { timeout: NETWORK_IDLE_MS }).catch(late);
+    if (held) {
+        await advance(page, BOOT_MS);
+    }
+    else
+        await page.evaluate(`(${pageScript('first_paint')})()`).catch(() => { });
+    if (hooks)
+        await page.evaluate(`(${pageScript('hooks', { map: hooks })})()`).catch(() => { });
+}
+export async function drive(page, d) {
+    const front_door = d.click ? await evalJson(page, 'front_door', { selector: d.click, ...FRONT_DOOR_ARGS }) : null;
+    const view = await evalJson(page, 'capture_view', { view: d.view, verbs: d.verbs, verb_gap_ms: 150, hold_ms: d.holdMs, freeze: d.freeze, ...(d.settleMs ? { settle_ms: d.settleMs } : {}) });
+    return { front_door, view };
+}
+export const KAPTURE_SETTLE_MS = 3000;
+export async function armKapture(page) {
+    const k = kaptureScript();
+    if (!k)
+        return false;
+    await page.addInitScript({ content: `${readFileSync(k.file, 'utf8')}\n;window.FunpixelKapture = FunpixelKapture;` });
+    return true;
+}
+export const LAYOUT_GATES = ['small_targets', 'small_text', 'overlaps', 'clipped', 'unsafe'];
+export function auditVerdict(entered, layout) {
+    if (!entered || !layout)
+        return { verdict: 'not_observed', failed: [] };
+    const failed = LAYOUT_GATES.filter((k) => (layout[k]?.total ?? 0) > 0);
+    return { verdict: failed.length ? 'fail' : 'pass', failed };
+}
+export function combine(verdicts) {
+    if (verdicts.includes('fail'))
+        return 'fail';
+    if (verdicts.includes('pass'))
+        return 'pass';
+    return 'not_observed';
+}

package/dist/look/loops.js

@@ -0,0 +1,108 @@
+import { crop } from "./sheet.js";
+export const SAME_POSE = 0.02;
+export const SEAM_POP_RATIO = 2;
+const PIXEL_STEP = 24;
+const LOOPS_BY_NAME = /^(idle|walk|run|fly|swim|hover|breathe)(\b|_|$)/i;
+function cellOf(sheet, f) {
+    const cut = crop(sheet, f.frame.x, f.frame.y, f.frame.w, f.frame.h);
+    const w = f.sourceSize?.w ?? cut.width, h = f.sourceSize?.h ?? cut.height;
+    const ox = Math.max(0, f.spriteSourceSize?.x ?? 0), oy = Math.max(0, f.spriteSourceSize?.y ?? 0);
+    if (w === cut.width && h === cut.height && !ox && !oy)
+        return cut;
+    const data = new Uint8Array(w * h * 4);
+    const cols = Math.max(0, Math.min(cut.width, w - ox));
+    for (let y = 0; y < cut.height && oy + y < h; y++)
+        data.set(cut.data.subarray(y * cut.width * 4, (y * cut.width + cols) * 4), ((oy + y) * w + ox) * 4);
+    return { width: w, height: h, data };
+}
+export function frameDelta(a, b) {
+    const w = Math.max(a.width, b.width), h = Math.max(a.height, b.height);
+    const px = (img, x, y, c) => (x < img.width && y < img.height ? img.data[(y * img.width + x) * 4 + c] : 0);
+    let visible = 0, changed = 0;
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++) {
+            const aa = px(a, x, y, 3), ab = px(b, x, y, 3);
+            if (aa <= 8 && ab <= 8)
+                continue;
+            visible++;
+            for (let c = 0; c < 4; c++) {
+                const va = c === 3 ? aa : (px(a, x, y, c) * aa) / 255, vb = c === 3 ? ab : (px(b, x, y, c) * ab) / 255;
+                if (Math.abs(va - vb) > PIXEL_STEP) {
+                    changed++;
+                    break;
+                }
+            }
+        }
+    return visible ? changed / visible : 0;
+}
+const median = (xs) => { const s = [...xs].sort((p, q) => p - q), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+const round = (n) => Math.round(n * 1000) / 1000;
+export function judgeCycle(cycle, frames, loop) {
+    const why = [];
+    const n = frames.length;
+    let distinct = null;
+    if (n >= 2) {
+        const kept = [];
+        for (const f of frames)
+            if (kept.every((k) => frameDelta(k, f) >= SAME_POSE))
+                kept.push(f);
+        distinct = kept.length;
+    }
+    const steps = frames.slice(1).map((f, i) => frameDelta(frames[i], f));
+    const med = steps.length >= 2 ? median(steps) : null;
+    const seam = loop && n >= 3 ? frameDelta(frames[n - 1], frames[0]) : null;
+    let verdict = 'pass';
+    let join = null;
+    const worse = (v) => { if (v === 'fail' || (v === 'warn' && verdict === 'pass'))
+        verdict = v; };
+    if (distinct === 1) {
+        worse('fail');
+        why.push(`all ${n} frames are one pose: it will not read as moving`);
+    }
+    else if (distinct !== null && distinct * 2 < n) {
+        worse('warn');
+        why.push(`${distinct} distinct poses in ${n} frames: repeats hold still`);
+    }
+    if (seam !== null && med !== null && distinct !== 1) {
+        join = 'meets';
+        if (seam > SEAM_POP_RATIO * med && seam > Math.max(...steps) && seam >= SAME_POSE) {
+            join = 'pops';
+            worse('fail');
+            why.push(`the loop pops: last → first changes ${round(seam * 100)}% of the pixels, ${round(seam / Math.max(med, 1e-6))}x the cycle's median step (${round(med * 100)}%)`);
+        }
+        else if (seam < SAME_POSE) {
+            join = 'hitch';
+            worse('warn');
+            why.push('the last frame repeats the first: the loop holds that pose twice (a hitch)');
+        }
+    }
+    if (distinct === null && seam === null) {
+        verdict = 'not_observed';
+        why.push(n < 2 ? 'one frame: nothing to compare' : 'not measured');
+    }
+    else if (loop && seam === null)
+        why.push('a loop of two frames: no in-cycle step to hold the seam to (not observed)');
+    if (!loop)
+        why.push('plays once: seam not judged');
+    return { cycle, loop, frames: n, distinct_poses: distinct, seam_delta: seam === null ? null : round(seam), median_delta: med === null ? null : round(med), seam: join, verdict, why };
+}
+export const loops = (name, meta) => {
+    const said = meta?.funpixel?.animations?.[name]?.loop;
+    return typeof said === 'boolean' ? said : LOOPS_BY_NAME.test(name);
+};
+export function sheetLoops(sheet, manifest) {
+    const m = manifest;
+    if (!m || typeof m.animations !== 'object' || !m.animations || !Object.keys(m.animations).length)
+        return null;
+    const table = Array.isArray(m.frames)
+        ? Object.fromEntries(m.frames.map((f) => [String(f.filename), f]))
+        : (m.frames ?? {});
+    return Object.entries(m.animations).map(([cycle, keys]) => {
+        const loop = loops(cycle, m.meta);
+        const rects = Array.isArray(keys) ? keys.map((k) => table[String(k)]) : [];
+        if (!rects.length || rects.some((r) => !r?.frame || r.rotated)) {
+            return { cycle, loop, frames: rects.length, distinct_poses: null, seam_delta: null, median_delta: null, seam: null, verdict: 'not_observed', why: ['the manifest does not carry this cycle\'s frames unrotated'] };
+        }
+        return judgeCycle(cycle, rects.map((r) => cellOf(sheet, r)), loop);
+    });
+}

package/dist/look/made-of.js

@@ -0,0 +1,242 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+export const PRIMITIVES = [
+    'Box', 'Sphere', 'Cylinder', 'Cone', 'Capsule', 'Torus', 'TorusKnot', 'Plane', 'Circle', 'Ring',
+    'Octahedron', 'Icosahedron', 'Dodecahedron', 'Tetrahedron', 'Polyhedron', 'Lathe', 'Extrude', 'Shape', 'Tube',
+];
+const PRIMITIVE = new RegExp(`\\bnew\\s+(?:THREE\\.)?(${PRIMITIVES.join('|')})(?:Buffer)?Geometry\\s*\\(`, 'g');
+const BUFFER = /\bnew\s+(?:THREE\.)?BufferGeometry\s*\(/g;
+const MODEL_SIGNS = [
+    [/\b(GLTFLoader|useGLTF|FBXLoader|OBJLoader|ColladaLoader)\b/, 'a model loader'],
+    [/['"`][^'"`\n]*\.(glb|gltf)\b/i, 'a .glb/.gltf path'],
+    [/findAsset\(\s*['"]models['"]/, "findAsset('models', …)"],
+    [/\b(loadCharacter|loadModel|loadGlb|loadGLB|loadGltf)\s*\(/, 'a model-loading helper'],
+    [/\bcloneSkinned|SkeletonUtils\.clone\b/, 'a skinned clone'],
+];
+export const HERO_WORDS = [
+    'player', 'hero', 'avatar', 'character', 'rival', 'rivals', 'enemy', 'enemies', 'boss', 'opponent', 'npc', 'creature',
+    'monster', 'mob', 'vehicle', 'car', 'cars', 'kart', 'ship', 'boat', 'skiff', 'bike', 'plane', 'craft', 'racer', 'mech',
+    'robot', 'pet', 'knight', 'drone', 'tank',
+];
+const SRC_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs']);
+const SKIP_DIR = new Set(['node_modules', 'dist', '.funtools', '.git', 'test', 'tests', '__tests__']);
+const IMAGE = /\.(png|jpe?g|webp)$/i;
+export function readSources(dir) {
+    const out = [];
+    const walk = (at) => {
+        let names = [];
+        try {
+            names = readdirSync(at);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = join(at, n);
+            let s;
+            try {
+                s = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                if (!SKIP_DIR.has(n))
+                    walk(p);
+                continue;
+            }
+            if (SRC_EXT.has(extname(n)) && !/\.(test|spec)\.[cm]?[jt]sx?$/.test(n) && !n.endsWith('.d.ts'))
+                out.push({ path: relative(dir, p), text: readFileSync(p, 'utf8') });
+        }
+    };
+    walk(join(dir, 'src'));
+    return out;
+}
+export function entryOf(dir, files) {
+    const have = new Set(files.map((f) => f.path));
+    try {
+        const html = readFileSync(join(dir, 'index.html'), 'utf8');
+        for (const m of html.matchAll(/<script[^>]*\bsrc=["'](?:\.?\/)?([^"']+)["']/g))
+            if (have.has(m[1]))
+                return m[1];
+    }
+    catch { }
+    return ['main.tsx', 'main.ts', 'main.jsx', 'main.js', 'index.tsx', 'index.ts', 'index.js'].map((n) => join('src', n)).find((p) => have.has(p)) ?? null;
+}
+const IMPORT = /(?:\bimport\s[^'"]*?from\s*|\bimport\s*\(\s*|\bexport\s[^'"]*?from\s*|\bimport\s+)['"](\.{1,2}\/[^'"]+)['"]/g;
+export function reachable(files, entry) {
+    const byPath = new Map(files.map((f) => [f.path, f]));
+    if (!entry)
+        return new Set(byPath.keys());
+    const resolveImport = (from, spec) => {
+        const base = join(dirname(from), spec);
+        const tries = [base, ...[...SRC_EXT].map((e) => base.replace(/\.(js|jsx|mjs)$/, '') + e), ...[...SRC_EXT].map((e) => join(base, `index${e}`))];
+        return tries.find((t) => byPath.has(t)) ?? null;
+    };
+    const seen = new Set();
+    const stack = [entry];
+    while (stack.length) {
+        const p = stack.pop();
+        if (seen.has(p))
+            continue;
+        seen.add(p);
+        for (const m of byPath.get(p).text.matchAll(IMPORT)) {
+            const r = resolveImport(p, m[1]);
+            if (r && !seen.has(r))
+                stack.push(r);
+        }
+    }
+    return seen;
+}
+const wordsIn = (s) => s.toLowerCase().split(/[^a-z]+/).filter(Boolean);
+export function rolesOf(file, extra = []) {
+    const hits = new Set();
+    const stem = basename(file.path).replace(/\.[^.]+$/, '');
+    for (const w of wordsIn(stem))
+        if (HERO_WORDS.includes(w))
+            hits.add(w);
+    for (const m of file.text.matchAll(/\.name\s*=\s*[`'"]([^`'"]+)[`'"]|\bname\s*:\s*[`'"]([^`'"]+)[`'"]/g)) {
+        const n = m[1] ?? m[2];
+        for (const w of wordsIn(n))
+            if (HERO_WORDS.includes(w))
+                hits.add(w);
+        for (const r of extra)
+            if (r.test(n))
+                hits.add(n);
+    }
+    return [...hits];
+}
+export function makeOf(file, extra = []) {
+    const primitives = {};
+    for (const m of file.text.matchAll(PRIMITIVE))
+        primitives[m[1]] = (primitives[m[1]] ?? 0) + 1;
+    const built = [...file.text.matchAll(BUFFER)].length;
+    const model = MODEL_SIGNS.find(([re]) => re.test(file.text))?.[1] ?? null;
+    return { file: file.path, roles: rolesOf(file, extra), primitives, built, model };
+}
+const count = (p) => Object.values(p).reduce((a, b) => a + b, 0);
+export function shippedModels(dir, reachedText) {
+    const out = [];
+    const walk = (at) => {
+        let names = [];
+        try {
+            names = readdirSync(at);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = join(at, n);
+            let s;
+            try {
+                s = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                if (!SKIP_DIR.has(n))
+                    walk(p);
+                continue;
+            }
+            if (/\.(glb|gltf)$/i.test(n)) {
+                const stem = n.replace(/\.(glb|gltf)$/i, '');
+                out.push({ file: relative(dir, p), bytes: s.size, used: reachedText.includes(n) || new RegExp(`['"\`]${stem.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"\`]`).test(reachedText) });
+            }
+        }
+    };
+    walk(join(dir, 'public'));
+    return out;
+}
+export function declaredOf(dir, manifest) {
+    const a = manifest?.art3d && typeof manifest.art3d === 'object' ? manifest.art3d : {};
+    const proof = typeof a.proof === 'string' && a.proof.trim() ? a.proof.trim() : null;
+    const at = proof ? resolve(dir, proof) : null;
+    return {
+        procedural: a.heroes === 'procedural',
+        why: typeof a.why === 'string' && a.why.trim() ? a.why.trim() : null,
+        proof,
+        proof_exists: !!at && at.startsWith(resolve(dir)) && IMAGE.test(at) && existsSync(at),
+        stand_ins: Array.isArray(a.stand_ins) ? a.stand_ins.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim()) : [],
+    };
+}
+function actorPatterns(manifest) {
+    return ['player', 'threats'].flatMap((k) => {
+        const v = manifest?.actors?.[k];
+        try {
+            return typeof v === 'string' && v ? [new RegExp(v, 'i')] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+const kinds = (p) => Object.entries(p).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ${n}`).join(', ');
+const mb = (b) => (b >= 1_048_576 ? `${(b / 1_048_576).toFixed(1)} MB` : `${Math.max(1, Math.round(b / 1024))} KB`);
+export function heroLine(h) {
+    const bits = [count(h.primitives) ? `${count(h.primitives)} primitive${count(h.primitives) > 1 ? 's' : ''} (${kinds(h.primitives)})` : '', h.built ? `${h.built} hand-built mesh${h.built > 1 ? 'es' : ''}` : ''].filter(Boolean);
+    const what = h.model ? `loads a model (${h.model})${bits.length ? ` beside ${bits.join(' and ')}` : ''}` : bits.join(' and ');
+    return `${basename(h.file)}${h.roles.length ? ` (${h.roles.slice(0, 4).join(', ')})` : ''}: ${what}`;
+}
+const namedIn = (h, standIns) => {
+    const said = standIns.join(' ').toLowerCase();
+    return [basename(h.file).replace(/\.[^.]+$/, ''), ...h.roles].some((w) => said.includes(w.toLowerCase()));
+};
+export function madeOf(dir, given) {
+    let manifest = given?.manifest;
+    if (!manifest) {
+        try {
+            manifest = JSON.parse(readFileSync(join(dir, 'funpixel.json'), 'utf8'));
+        }
+        catch {
+            manifest = {};
+        }
+    }
+    const files = given?.files ?? readSources(dir);
+    const entry = entryOf(dir, files);
+    const reached = reachable(files, entry);
+    const live = files.filter((f) => reached.has(f.path));
+    const three = live.some((f) => /from\s+['"]three['"]|require\(\s*['"]three['"]\s*\)|from\s+['"]@react-three\/fiber['"]/.test(f.text));
+    const extra = actorPatterns(manifest);
+    const makes = live.map((f) => makeOf(f, extra));
+    const totals = { primitives: {}, primitive_count: 0, built: 0, model_files: makes.filter((m) => m.model).map((m) => m.file) };
+    for (const m of makes) {
+        for (const [k, n] of Object.entries(m.primitives))
+            totals.primitives[k] = (totals.primitives[k] ?? 0) + n;
+        totals.built += m.built;
+    }
+    totals.primitive_count = count(totals.primitives);
+    const heroes = makes.filter((m) => m.roles.length && (m.model || count(m.primitives) || m.built));
+    const models = shippedModels(dir, live.map((f) => f.text).join('\n'));
+    const declared = declaredOf(dir, manifest);
+    const base = { three, files: files.length, reached: reached.size, entry, heroes, totals, models, declared };
+    const style = declared.procedural && declared.why && declared.proof_exists;
+    if (!three)
+        return { ...base, verdict: 'not_observed', says: 'not a Three.js game (no source imports three): nothing to judge', unnamed: [] };
+    const codeHeroes = heroes.filter((h) => !h.model);
+    const shipped = models.filter((m) => m.used);
+    const inventory = models.length
+        ? `${models.length} model file${models.length > 1 ? 's' : ''} shipped (${models.slice(0, 4).map((m) => `${basename(m.file)} ${mb(m.bytes)}${m.used ? '' : ', never named in code'}`).join('; ')})`
+        : 'no model file shipped under public/';
+    const declaredWords = style
+        ? `declared a deliberate procedural style ("${declared.why}"), proof ${declared.proof}`
+        : declared.procedural
+            ? `art3d declares a procedural style but ${!declared.why ? 'gives no reason' : `its proof ${declared.proof ? `${declared.proof} is missing` : 'frame is not given'}`}, so it is not proven`
+            : 'no deliberate procedural style declared (funpixel.json art3d)';
+    const allCode = !totals.model_files.length && !shipped.length && totals.primitive_count + totals.built >= 8;
+    if (!heroes.length && !allCode) {
+        return { ...base, verdict: 'not_observed', says: `no player, rival or enemy found by file or node name (${totals.primitive_count} primitives, ${totals.model_files.length} file(s) loading a model; ${inventory}): name the hero nodes, or give funpixel.json "actors"`, unnamed: [] };
+    }
+    if (!codeHeroes.length && !(allCode && !heroes.length)) {
+        return { ...base, verdict: 'pass', says: `hero objects load models: ${heroes.map(heroLine).join('; ')}; ${inventory}`, unnamed: [] };
+    }
+    const subjects = codeHeroes;
+    const unnamed = style ? []
+        : subjects.length ? subjects.filter((h) => !namedIn(h, declared.stand_ins)).map((h) => basename(h.file))
+            : declared.stand_ins.length ? [] : ['the scene'];
+    const what = subjects.length
+        ? `hero objects are code primitives: ${subjects.map(heroLine).join('; ')}`
+        : `everything drawn is code: ${totals.primitive_count} primitives (${kinds(totals.primitives)}) and ${totals.built} hand-built meshes, no model loaded`;
+    const named = style ? '' : declared.stand_ins.length ? `; stand-ins named: ${declared.stand_ins.join('; ')}${unnamed.length ? ` (not named: ${unnamed.join(', ')})` : ''}` : '; not named as stand-ins';
+    return { ...base, verdict: style ? 'pass' : 'fail', says: `${what}; ${inventory}; ${declaredWords}${named}`, unnamed };
+}

package/dist/look/moments.js

@@ -0,0 +1,32 @@
+import { evalJson } from "./look.js";
+export const MOMENT_LAG_MS = 60;
+export async function armMoments(page) {
+    await evalJson(page, 'moments', { op: 'install' });
+    await evalJson(page, 'moments', { op: 'drain' });
+}
+export async function drainMoments(page) {
+    const r = await evalJson(page, 'moments', { op: 'drain' });
+    return Array.isArray(r?.moments) ? r.moments : [];
+}
+export const pageNow = (page) => page.evaluate('performance.now()').then(Number).catch(() => NaN);
+export const EARLY_MS = 150;
+export const isEarly = (frameTimes, m) => frameTimes.length > 0 && m.t < frameTimes[0] - EARLY_MS;
+export const earlyMarks = (frameTimes, marks) => marks.filter((m) => isEarly(frameTimes, m));
+export const LATE_WAIT_MS = 4000;
+export const lateMarks = (frameTimes, marks) => frameTimes.length ? marks.filter((m) => m.t + MOMENT_LAG_MS > frameTimes[frameTimes.length - 1]) : [];
+export function placeMarks(frameTimes, marks) {
+    const placed = [];
+    for (const m of marks) {
+        if (isEarly(frameTimes, m))
+            continue;
+        const frame = frameTimes.findIndex((t) => t >= m.t + MOMENT_LAG_MS);
+        if (frame >= 0)
+            placed.push({ ...m, frame });
+    }
+    return placed;
+}
+export function keyFrame(frameTimes, marks) {
+    const placed = placeMarks(frameTimes, marks);
+    const best = placed.reduce((b, m) => (!b || m.weight >= b.weight ? m : b), null);
+    return best ? { frame: best.frame, mark: best } : { frame: Math.floor(Math.max(0, frameTimes.length - 1) / 2), mark: null };
+}

package/dist/look/motion.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fingerprint } from "../verify/fingerprint.js";
+import { sceneReads } from "../verify/reads.js";
+import { declaredActors, judgeMotion } from "./roles.js";
+export const MOTION_RECORD = join('.funtools', 'scene', 'motion.json');
+export const MOTION = { ms: 1000, everyMs: 100, max: 24 };
+export function declaredIn(dir) {
+    if (!dir)
+        return [];
+    const doc = existsSync(join(dir, 'design', 'GDD.md')) ? 'GDD.md' : 'README.md';
+    for (const f of [doc, 'gameplay.md']) {
+        try {
+            const found = declaredActors(readFileSync(join(dir, 'design', f), 'utf8'));
+            if (found.length)
+                return found;
+        }
+        catch { }
+    }
+    return [];
+}
+export function motionArgs(decl) {
+    const s = (k) => (typeof decl?.[k] === 'string' ? decl[k] : '');
+    return { player: s('player'), threats: s('threats'), pickups: s('pickups'), ms: MOTION.ms, every_ms: MOTION.everyMs, max: MOTION.max };
+}
+export function motionVerdict(m, declared = []) {
+    if (!m)
+        return 'not_observed';
+    const j = judgeMotion(m, declared, MOTION.ms / 1000);
+    return j.defects.length ? 'fail' : j.unobserved.length ? 'not_observed' : 'pass';
+}
+export function motionFindings(m, declared = []) {
+    const j = judgeMotion(m, declared, MOTION.ms / 1000);
+    const unnamed = m.engine !== 'none' && !m.actors.length
+        ? [`no actor found: name the nodes (label) or set funpixel.json "actors" — nodes seen: ${m.names.slice(0, 8).join(', ') || 'none named'}`] : [];
+    return [...j.defects, ...unnamed, ...j.unobserved.map((u) => `not observed: ${u}`)];
+}
+export async function recordMotion(dir, view, m) {
+    const path = join(dir, MOTION_RECORD);
+    await mkdir(dirname(path), { recursive: true });
+    const record = { ...m, view, verdict: motionVerdict(m, declaredIn(dir)), fingerprint: (await fingerprint(dir)).fingerprint, reads: sceneReads(dir), at: new Date().toISOString() };
+    await writeFile(path, JSON.stringify(record, null, 2) + '\n');
+}

package/dist/look/phone-play.js

@@ -0,0 +1,142 @@
+import { SAFARI_PAGE, touchSession } from "../verify/browser.js";
+export const PHONE_PLAY_BARS = {
+    minFill: 0.7,
+    padMin: 2,
+    bandPieceWidth: 0.5,
+    maxIdleRows: 0.15,
+};
+export function idleRows(s, board) {
+    const vh = s.viewport.h;
+    if (!vh)
+        return null;
+    const spans = [[board.y, board.y + board.h], ...s.pieces.filter((p) => !p.control && !p.transient && p.w > 0 && p.h > 0).map((p) => [p.y, p.y + p.h])]
+        .map(([a, b]) => [Math.max(0, a), Math.min(vh, b)]).filter(([a, b]) => b > a).sort((x, y) => x[0] - y[0]);
+    let used = 0, end = 0;
+    for (const [a, b] of spans) {
+        if (b <= end)
+            continue;
+        used += b - Math.max(a, end);
+        end = b;
+    }
+    return Math.round((1 - used / vh) * 1000) / 1000;
+}
+export const SAFARI_PORTRAIT = { w: SAFARI_PAGE.portrait.width, h: SAFARI_PAGE.portrait.height };
+const clip = (b, w, h) => {
+    const x = Math.max(0, b.x), y = Math.max(0, b.y);
+    return { x, y, w: Math.max(0, Math.min(w, b.x + b.w) - x), h: Math.max(0, Math.min(h, b.y + b.h) - y) };
+};
+const median = (xs) => { const s = [...xs].sort((a, b) => a - b); return s[s.length >> 1]; };
+export function bandBoard(s) {
+    const vw = s.viewport.w, vh = s.viewport.h;
+    const play = s.play ? clip(s.play, vw, vh) : null;
+    if (!play || !play.w || !play.h)
+        return null;
+    const blocks = s.pieces.filter((p) => !p.transient && (p.control || p.w >= PHONE_PLAY_BARS.bandPieceWidth * play.w))
+        .map((p) => [Math.max(play.y, p.y), Math.min(play.y + play.h, p.y + p.h)]).filter(([a, b]) => b > a).sort((a, b) => a[0] - b[0]);
+    let best = { y: play.y, h: 0 }, at = play.y;
+    for (const [a, b] of [...blocks, [play.y + play.h, play.y + play.h]]) {
+        if (a - at > best.h)
+            best = { y: at, h: a - at };
+        at = Math.max(at, b);
+    }
+    return best.h > 0 ? { x: play.x, y: best.y, w: play.w, h: best.h, source: 'band' } : null;
+}
+export function playArea(samples, phone) {
+    const boxes = samples.map((s, i) => {
+        const b = phone[i]?.board ?? bandBoard(s);
+        if (!b || !s.viewport.w || !s.viewport.h)
+            return null;
+        const c = clip(b, s.viewport.w, s.viewport.h);
+        if (c.w < 8 || c.h < 8)
+            return null;
+        const k = Math.min(s.viewport.w / c.w, s.viewport.h / c.h);
+        return { share: (c.w * c.h) / (s.viewport.w * s.viewport.h), fill: 1 / (k * k), source: b.source, board: c };
+    }).filter((x) => x !== null);
+    if (!boxes.length)
+        return null;
+    const share = median(boxes.map((b) => b.share));
+    const pick = boxes.find((b) => b.share === share);
+    return { share: Math.round(share * 1000) / 1000, fill: Math.round(median(boxes.map((b) => b.fill)) * 1000) / 1000, source: pick.source, board: pick.board };
+}
+export function judgePhonePlay(samples, phone, swipe, safari = null) {
+    const area = safari ? playArea([safari.sample], [safari.phone]) : playArea(samples, phone);
+    const measuredAt = safari ? safari.sample.viewport : samples[samples.length - 1]?.viewport ?? null;
+    const last = phone[phone.length - 1] ?? { board: null, pad: [], gestures: [] };
+    const vp = samples[samples.length - 1]?.viewport ?? { w: 0, h: 0 };
+    const pad = last.pad;
+    const keys = [...new Set(pad.map((p) => p.key))];
+    const isPad = keys.length >= PHONE_PLAY_BARS.padMin;
+    const claimed = isPad && last.gestures.some((g) => keys.some((k) => g.keys.includes(k)));
+    const gestureOnly = !isPad && last.gestures.length > 0;
+    const padShare = isPad && vp.h ? Math.round(((Math.max(...pad.map((p) => p.y + p.h)) - Math.min(...pad.map((p) => p.y))) / vp.h) * 1000) / 1000 : null;
+    const at = safari ? safari.sample : samples[samples.length - 1];
+    const idle = area && at && at.viewport.h > at.viewport.w ? idleRows(at, area.board) : null;
+    const duplicate = !isPad ? null : claimed || swipe?.moved === true ? true : swipe?.moved === false ? false : null;
+    const facts = {
+        play_area_share: area?.share ?? null, play_fill: area?.fill ?? null, measured_at: area ? measuredAt : null, board_source: area?.source ?? null,
+        pad_keys: keys, pad_band_share: padShare, controls_duplicate_gesture: duplicate, idle_rows_share: idle,
+        swipe: { tried: !!swipe, moved: swipe?.moved ?? null, direction: swipe?.direction ?? null, claimed_by_play: claimed, note: swipe?.note ?? (isPad || gestureOnly ? 'not tried' : 'no direction controls on screen') },
+    };
+    const findings = [];
+    const view = samples[0]?.view ?? '';
+    if (area && area.fill < PHONE_PLAY_BARS.minFill) {
+        findings.push({ kind: 'play_area_small', severity: 'warn', what: `the play takes ${Math.round(area.share * 100)}% of the ${safari ? `page Safari leaves (${measuredAt?.w}x${measuredAt?.h})` : 'screen'}, ${Math.round(area.fill * 100)}% of the largest ${area.board.w >= area.board.h ? 'box' : 'column'} of its shape that fits (bar ${PHONE_PLAY_BARS.minFill * 100}%; measured from the ${area.source === 'band' ? 'band the HUD leaves, an upper bound' : area.source === 'scene' ? 'scene around the player' : area.source === 'gesture' ? 'element that takes the swipe' : 'data-fpx-play element'})`, where: view, number: area.fill, sample: 0 });
+    }
+    if (duplicate) {
+        findings.push({ kind: 'controls_duplicate_gesture', severity: 'warn', what: `${keys.length} on-screen direction controls (${keys.join(', ')}) repeat ${claimed ? 'the swipe the play claims' : `a swipe on the play (${swipe?.direction} moved the game)`} and claim ${Math.round((padShare ?? 0) * 100)}% of the screen's height: the genre's phone hits keep such a pad as an accessibility setting`, where: view, number: padShare ?? 0, sample: 0 });
+    }
+    if (idle !== null && idle > PHONE_PLAY_BARS.maxIdleRows && !isPad) {
+        findings.push({ kind: 'empty_band', severity: 'warn', what: `${Math.round(idle * 100)}% of the height of the ${safari ? 'page Safari leaves' : 'screen'} holds neither the play nor a readout (bar ${PHONE_PLAY_BARS.maxIdleRows * 100}%): a taller play shape for portrait (more rows), or the HUD moved into that band so the play sits larger, would use it`, where: view, number: idle, sample: 0 });
+    }
+    if (gestureOnly && swipe?.moved === false) {
+        findings.push({ kind: 'swipe_moves_nothing', severity: 'warn', what: `the play claims a swipe (data-fpx-gesture ${last.gestures[0].keys.join(' ')}) and has no pad, but a ${swipe.direction ?? ''} swipe on it moved nothing: a phone player has no way to move`, where: view, number: 0, sample: 0 });
+    }
+    return { facts, findings };
+}
+function flatten(v, at = '', out = new Map(), depth = 0) {
+    if (depth > 6 || out.size > 2000)
+        return out;
+    if (v && typeof v === 'object') {
+        for (const [k, x] of Object.entries(v))
+            flatten(x, at ? `${at}.${k}` : k, out, depth + 1);
+    }
+    else
+        out.set(at, typeof v === 'number' ? String(Math.round(v * 100) / 100) : JSON.stringify(v));
+    return out;
+}
+const readState = (page) => page.evaluate(() => {
+    const s = window.__FPX_STATE__;
+    try {
+        return typeof s === 'function' ? s() : s ?? null;
+    }
+    catch {
+        return null;
+    }
+}).catch(() => null);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function probeSwipe(page, board) {
+    const first = await readState(page);
+    if (first === null || first === undefined)
+        return { moved: null, direction: null, note: 'the game declares no __FPX_STATE__, so a swipe cannot be seen to move it' };
+    const cdp = await touchSession(page);
+    const cx = board.x + board.w / 2, cy = board.y + board.h / 2, reach = Math.max(48, 0.25 * Math.min(board.w, board.h));
+    for (const [dir, dx, dy] of [['right', 1, 0], ['left', -1, 0], ['down', 0, 1], ['up', 0, -1]]) {
+        const a = flatten(await readState(page));
+        await sleep(450);
+        const b = flatten(await readState(page));
+        const noisy = new Set([...b.keys()].filter((k) => a.get(k) !== b.get(k)));
+        const touch = (type, x, y) => cdp.send('Input.dispatchTouchEvent', { type, touchPoints: type === 'touchEnd' ? [] : [{ x, y, id: 1, radiusX: 8, radiusY: 8, force: 1 }] }).catch(() => { });
+        await touch('touchStart', cx, cy);
+        for (let i = 1; i <= 6; i++) {
+            await sleep(25);
+            await touch('touchMove', cx + dx * reach * (i / 6), cy + dy * reach * (i / 6));
+        }
+        await touch('touchEnd', cx + dx * reach, cy + dy * reach);
+        await sleep(800);
+        const c = flatten(await readState(page));
+        const changed = [...c.keys()].filter((k) => !noisy.has(k) && b.get(k) !== c.get(k));
+        if (changed.length)
+            return { moved: true, direction: dir, note: `a ${dir} swipe on the play changed ${changed.slice(0, 4).join(', ')}` };
+    }
+    return { moved: false, direction: null, note: 'four swipes on the play moved nothing in __FPX_STATE__' };
+}