@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/look/held.js

@@ -0,0 +1,92 @@
+import { pageScript } from '../vendor/verify/src/index.js';
+import { PROBE_SEED } from "../verify/probe.js";
+export const CAPTURE_SEED = PROBE_SEED;
+export const BOOT_MS = 1500;
+const inflight = new WeakMap();
+export const NET_QUIET_MS = 120;
+export const NET_WAIT_MAX_MS = 5000;
+export async function holdClock(page, seed, frameMs) {
+    const net = { n: 0, quietSince: Date.now() };
+    inflight.set(page, net);
+    page.on('request', () => { net.n++; });
+    const done = () => { net.n = Math.max(0, net.n - 1); if (!net.n)
+        net.quietSince = Date.now(); };
+    page.on('requestfinished', done);
+    page.on('requestfailed', done);
+    await page.exposeFunction('__FPX_NET_QUIET__', () => networkQuiet(page));
+    await page.addInitScript({ content: `(${pageScript('step_clock', frameMs ? { seed, frame_ms: frameMs } : { seed })})()` });
+}
+export async function networkQuiet(page, quietMs = NET_QUIET_MS, maxMs = NET_WAIT_MAX_MS) {
+    const net = inflight.get(page);
+    if (!net)
+        return true;
+    for (const until = Date.now() + maxMs;;) {
+        if (!net.n && Date.now() - net.quietSince >= quietMs)
+            return true;
+        if (Date.now() >= until)
+            return false;
+        await new Promise((r) => setTimeout(r, 5));
+    }
+}
+export async function advance(page, ms) {
+    return page.evaluate(`(async () => { const C = window.__FPX_STEP_CLOCK__; if (!C || C.held !== true) return false; await C.advance(${Number(ms) || 0}); return true; })()`)
+        .then((v) => v === true).catch(() => false);
+}
+export async function pause(page, ms, held) {
+    if (held && await advance(page, ms))
+        return;
+    await page.waitForTimeout(ms);
+}
+const READ_FRAMING_JS = `(() => {
+  const out = { clock: null, camera: null };
+  try { const C = window.__FPX_STEP_CLOCK__; if (C && C.held === true) out.clock = C.report(); } catch (e) {}
+  try {
+    const c = typeof window.__FPX_CAMERA__ === 'function' ? window.__FPX_CAMERA__() : null;
+    if (c && typeof c === 'object' && typeof c.shot === 'string' && c.shot) out.camera = { shot: c.shot.slice(0, 40), blending: c.blending === true };
+  } catch (e) {}
+  return JSON.stringify(out);
+})()`;
+export function framingOf(raw, held) {
+    const camera = raw?.camera ?? null;
+    const c = raw?.clock;
+    if (!held || !c || c.held !== true) {
+        return { clock: 'free-running', why: held ? 'the held clock did not install on this page' : 'asked to run free (--free-running)', seed: null, seed_read: null, frame_ms: null, at_ms: null, frames: null, camera };
+    }
+    const base = { seed: Number.isInteger(c.seed) ? c.seed : null, seed_read: Number(c.seed_reads) > 0, frame_ms: Number(c.frame_ms) || null, camera };
+    if (!(Number(c.game_frames) > 0) && !(Number(c.timers) > 0)) {
+        return { clock: 'free-running', why: 'the page asked the held clock for no frame and no timer: its motion, if any, runs on something the clock does not hold (a worker, audio time)', ...base, at_ms: null, frames: null };
+    }
+    return { clock: 'stepped', ...base, at_ms: Number(c.at_ms), frames: Number(c.frames), ...(Array.isArray(c.errors) && c.errors.length ? { errors: c.errors.map(String) } : {}) };
+}
+export async function readFraming(page, held) {
+    const raw = await page.evaluate(READ_FRAMING_JS).catch(() => null);
+    let v = null;
+    try {
+        v = typeof raw === 'string' ? JSON.parse(raw) : null;
+    }
+    catch {
+        v = null;
+    }
+    return framingOf(v, held);
+}
+export function framingLine(f) {
+    if (f.clock === 'free-running') {
+        return ['warn', `free-running: ${f.why ?? 'wall-clock timing'}. Two shots of this view differ by themselves; never read two such frames as comparable`];
+    }
+    const seed = `seed ${f.seed}${f.seed_read ? '' : ' (the game never read __FPX_SEED__: only Math.random followed it)'}`;
+    const cam = f.camera ? `, camera "${f.camera.shot}"${f.camera.blending ? ' mid-blend' : ''}` : '';
+    return ['pass', `repeatable: held clock, ${seed}, ${f.frames} frames of ${f.frame_ms} ms (${Math.round(f.at_ms ?? 0)} ms of game time)${cam}`];
+}
+export function notComparable(a, b) {
+    if (!a || !b)
+        return 'no framing record for one of the two (taken before 8 Oct, or not by capture): framed alike is not known';
+    if (a.clock === 'free-running' || b.clock === 'free-running')
+        return 'free-running: on wall-clock timing the frame moves by itself, so the difference is the clock\'s as well as the game\'s';
+    if (a.seed !== b.seed)
+        return `seeds differ (${a.seed} → ${b.seed})`;
+    if (a.frame_ms !== b.frame_ms || a.at_ms !== b.at_ms)
+        return `shot at different game times (${Math.round(a.at_ms ?? 0)} → ${Math.round(b.at_ms ?? 0)} ms)`;
+    if (a.camera && b.camera && a.camera.shot !== b.camera.shot)
+        return `named cameras differ ("${a.camera.shot}" → "${b.camera.shot}")`;
+    return null;
+}

package/dist/look/hook.js

@@ -0,0 +1,169 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fingerprint } from "../verify/fingerprint.js";
+import { autoLog } from "../feedback/auto.js";
+export const HOOK_RECORD = join('.funtools', 'hook.json');
+export const HOOK_CHECKPOINTS = [3, 20, 60, 120, 180];
+export const HOOK = {
+    sampleMs: 1500,
+    flatSpread: 7,
+    emptyShare: 0.62,
+    sameShare: 0.02,
+    titlePlayShare: 0.4,
+    playFrameAtS: 20,
+};
+export function checkpointsFor(seconds) {
+    const last = HOOK_CHECKPOINTS[HOOK_CHECKPOINTS.length - 1];
+    if (!(seconds > 0) || seconds === last)
+        return [...HOOK_CHECKPOINTS];
+    const scaled = HOOK_CHECKPOINTS.map((t) => Math.max(1, Math.round((t * seconds) / last)));
+    return [...new Set(scaled)].sort((a, b) => a - b);
+}
+const TILES_X = 16, TILES_Y = 9;
+const SUB = 4;
+function tiles(img) {
+    const out = [];
+    const tw = img.width / TILES_X, th = img.height / TILES_Y;
+    const step = Math.max(1, Math.floor(Math.min(tw, th) / 24));
+    for (let ty = 0; ty < TILES_Y; ty++) {
+        for (let tx = 0; tx < TILES_X; tx++) {
+            const means = [];
+            for (let by = 0; by < SUB; by++) {
+                for (let bx = 0; bx < SUB; bx++) {
+                    const x0 = Math.floor(tx * tw + (bx * tw) / SUB), x1 = Math.floor(tx * tw + ((bx + 1) * tw) / SUB);
+                    const y0 = Math.floor(ty * th + (by * th) / SUB), y1 = Math.floor(ty * th + ((by + 1) * th) / SUB);
+                    let sum = 0, n = 0;
+                    for (let y = y0; y < y1; y += step) {
+                        for (let x = x0; x < x1; x += step) {
+                            const i = (y * img.width + x) * 4;
+                            sum += 0.299 * img.data[i] + 0.587 * img.data[i + 1] + 0.114 * img.data[i + 2];
+                            n++;
+                        }
+                    }
+                    if (n)
+                        means.push(sum / n);
+                }
+            }
+            const mean = means.length ? means.reduce((a, b) => a + b, 0) / means.length : 0;
+            out.push({ mean, spread: means.length ? Math.max(...means) - Math.min(...means) : 0 });
+        }
+    }
+    return out;
+}
+export function flatShare(img) {
+    const t = tiles(img);
+    return t.filter((x) => x.spread < HOOK.flatSpread).length / t.length;
+}
+export function changedTiles(a, b) {
+    if (a.width !== b.width || a.height !== b.height)
+        return null;
+    const ta = tiles(a), tb = tiles(b);
+    return ta.filter((x, i) => Math.abs(x.mean - tb[i].mean) > 3).length / ta.length;
+}
+const BINS = 4;
+function histogram(img) {
+    const h = new Float64Array(BINS ** 3);
+    const step = Math.max(1, Math.floor(Math.sqrt((img.width * img.height) / 40_000)));
+    let n = 0;
+    for (let y = 0; y < img.height; y += step)
+        for (let x = 0; x < img.width; x += step) {
+            const i = (y * img.width + x) * 4;
+            const b = (c) => Math.min(BINS - 1, Math.floor((img.data[i + c] * BINS) / 256));
+            h[(b(0) * BINS + b(1)) * BINS + b(2)]++;
+            n++;
+        }
+    if (n)
+        for (let k = 0; k < h.length; k++)
+            h[k] /= n;
+    return h;
+}
+export function frameSimilarity(a, b) {
+    const ha = histogram(a), hb = histogram(b);
+    let s = 0;
+    for (let k = 0; k < ha.length; k++)
+        s += Math.min(ha[k], hb[k]);
+    return Math.round(s * 100) / 100;
+}
+export const counted = (c) => !c.loading && !c.stalled;
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+const lifeMoves = (s) => (s && s.engine !== 'none' ? s.moving + s.crowds.length + s.particles.length : null);
+const PLAY_END = /over|end|lost|lose|fail|dead|result|won|win|credits/i;
+export function hookFindings(r) {
+    const f = [];
+    if (r.front_door && !r.front_door.found)
+        f.push({ level: 'not_observed', text: 'no Play control marked data-fpx-start: the opening was read as loaded', hint: 'mark the title\'s start control data-fpx-start' });
+    if (r.title?.flat != null && r.title.flat >= HOOK.emptyShare)
+        f.push({ level: 'warn', text: `the title is ${Math.round(r.title.flat * 100)}% flat colour: a card, not a scene`, hint: 'the title is the first promise: the world, the hero and the wordmark in one picture (funpixel-art, references/ui.md)' });
+    const all = r.checkpoints;
+    if (!all.length) {
+        f.push({ level: 'not_observed', text: 'no checkpoint was read' });
+        return f;
+    }
+    const loading = all.filter((c) => c.loading);
+    if (loading.length)
+        f.push({ level: 'warn', text: `a loading or splash frame at ${loading.map((c) => mmss(c.at)).join(', ')}: not counted as the opening`, hint: 'a capture of a loading card is never a moment; if it lasts this long, the player waits this long' });
+    const stalled = all.filter((c) => c.stalled);
+    if (stalled.length)
+        f.push({ level: 'warn', text: `STALL: presses changed nothing by ${stalled.map((c) => mmss(c.at)).join(', ')} (the game's state did not move): a dead end, not counted`, hint: 'never a dead end: a disabled control says why and leads to the fix (owner, 1 Oct: "could not pass here")' });
+    const cps = all.filter(counted);
+    if (!cps.length) {
+        f.push({ level: 'not_observed', text: 'no checkpoint showed play: every one was a loading card or a stall' });
+        return f;
+    }
+    const empty = cps.filter((c) => c.flat != null && c.flat >= HOOK.emptyShare);
+    if (empty.length)
+        f.push({ level: 'warn', text: `the opening reads as empty at ${empty.map((c) => mmss(c.at)).join(', ')}: ${Math.round(Math.max(...empty.map((c) => c.flat ?? 0)) * 100)}% of the frame is flat colour`, hint: 'fill the far, middle and near layers: terrain with silhouettes, a backdrop, landmarks, scatter, haze matched to the sky (funpixel-3d, references/painted-target.md)' });
+    const moves = cps.map((c) => lifeMoves(c.life));
+    const read = moves.filter((m) => m !== null);
+    if (!read.length)
+        f.push({ level: 'not_observed', text: 'no scene graph found: ambient movers not counted', hint: 'expose window.__THREEJS_SCENE__ or window.__PIXI_APP__' });
+    else if (read.every((m) => m === 0))
+        f.push({ level: 'warn', text: 'nothing moves but the player in the first minutes: the world reads as a still', hint: 'living things first: a creature, birds, drifting dust, swaying grass, a flickering light, weather (funpixel-world-and-story, references/atmosphere.md)' });
+    else {
+        const still = cps.filter((c, i) => moves[i] === 0);
+        if (still.length)
+            f.push({ level: 'warn', text: `the world goes still at ${still.map((c) => mmss(c.at)).join(', ')}`, hint: 'keep something alive in every stretch of the opening, not only the first seconds' });
+        else
+            f.push({ level: 'note', text: `the world moves at every checkpoint (${read.join(', ')} movers)` });
+    }
+    const same = cps.filter((c) => c.changed != null && c.changed < HOOK.sameShare);
+    if (same.length && same.length === cps.filter((c) => c.changed != null).length)
+        f.push({ level: 'warn', text: 'the picture did not change between checkpoints: an idle player sees one frame for minutes', hint: 'ambient motion, light that shifts, a camera that breathes; or pass --verbs so the read follows play' });
+    if (r.placeholders.length)
+        f.push({ level: 'warn', text: `stand-ins still in the opening: ${r.placeholders.slice(0, 6).join(', ')}${r.placeholders.length > 6 ? ` and ${r.placeholders.length - 6} more` : ''}`, hint: 'the first minutes get the real assets first' });
+    f.push(...wayfinding(cps));
+    if (r.title_vs_play) {
+        const t = r.title_vs_play;
+        if (t.similarity < HOOK.titlePlayShare)
+            f.push({ level: 'warn', text: `the title and play look like different games: colour similarity ${t.similarity} between the title and play at ${mmss(t.play_at)}`, hint: 'the title is the play world: the real world running behind the card, one promise, one button (the Silt bar S1; funpixel-gdd, references/design-note.md)' });
+        else
+            f.push({ level: 'note', text: `title vs play: colour similarity ${t.similarity} (the title frame against play at ${mmss(t.play_at)})` });
+    }
+    const ended = cps.find((c) => c.screen && PLAY_END.test(c.screen));
+    if (ended)
+        f.push({ level: 'note', text: `play reached "${ended.screen}" by ${mmss(ended.at)} with an idle player: later checkpoints read that screen`, hint: 'pass --verbs a,b to keep playing during the read; how soon an idle player dies is a check fact (funtools check, .funtools/idle.json)' });
+    if (!f.some((x) => x.level === 'warn'))
+        f.push({ level: 'note', text: 'the hook holds on these readings: look at the frames too (a mirror, not a judge)' });
+    return f;
+}
+export function wayfinding(cps) {
+    const withObj = cps.filter((c) => c.objective);
+    const hint = 'wayfinding and objectives as data: __FPX_STATE__() returns { objective, goalDistance } (funpixel-world-and-story, references/opening-and-chapters.md)';
+    if (!withObj.length)
+        return [{ level: 'not_observed', text: 'no objective in __FPX_STATE__: the player\'s goal on screen was not measured', hint }];
+    const first = withObj[0];
+    const dists = cps.map((c) => c.goalDistance).filter((d) => typeof d === 'number' && Number.isFinite(d));
+    const shown = [...new Set(withObj.map((c) => c.objective))];
+    const out = [{ level: 'note', text: `objective on screen at ${mmss(first.at)}: "${first.objective}"${typeof first.goalDistance === 'number' ? `, ${Math.round(first.goalDistance)} m to go` : ''}${shown.length > 1 ? `; ${shown.length} objectives over the opening` : ''}` }];
+    if (!dists.length)
+        out.push({ level: 'not_observed', text: 'no goalDistance in __FPX_STATE__: how far the goal is was not measured', hint });
+    else if (dists.length > 1)
+        out.push({ level: 'note', text: `goal distance ${dists.map((d) => Math.round(d)).join(' → ')} m across the checkpoints` });
+    return out;
+}
+export async function recordHook(dir, r) {
+    const path = join(dir, HOOK_RECORD);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify({ ...r, fingerprint: (await fingerprint(dir)).fingerprint, at: new Date().toISOString() }, null, 2) + '\n');
+    autoLog(dir, 'hook', `warnings (${r.viewport})`, r.findings.filter((f) => f.level === 'warn').length, '', HOOK_RECORD);
+}

package/dist/look/hud.js

@@ -0,0 +1,189 @@
+import { feedbackFindings, placeholderFindings } from "./feedback.js";
+export function desktopTouchFindings(samples) {
+    const i = samples.findIndex((s) => (s.touch_controls ?? []).length > 0);
+    if (i < 0)
+        return [];
+    const shown = samples[i].touch_controls ?? [];
+    return [{ kind: 'touch_on_desktop', severity: 'warn', what: `${shown.length} on-screen touch control(s) show on a desktop with no touch (1280x720): show them for touch only, last input wins (a touch shows them, a key or a mouse hides them; skill funpixel-mobile-ui)`, where: shown.map((c) => c.name).slice(0, 3).join(', '), number: shown.length, sample: i }];
+}
+export const HUD_BARS = {
+    maxCover: 0.25,
+    maxCentreCover: 0.08,
+    minTextPx: 12,
+    contrast: 4.5,
+    contrastLarge: 3,
+    largePx: 24,
+    maxTransient: 3,
+    repeats: 3,
+    actorCover: 0.2,
+};
+const overlap = (a, b) => Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+export function cover(pieces, area) {
+    const N = 60;
+    let hit = 0, centre = 0, centreN = 0;
+    for (let i = 0; i < N; i++) {
+        for (let j = 0; j < N; j++) {
+            const fx = (i + 0.5) / N, fy = (j + 0.5) / N;
+            const x = area.x + area.w * fx, y = area.y + area.h * fy;
+            const inCentre = fx > 0.2 && fx < 0.8 && fy > 0.2 && fy < 0.8;
+            const on = pieces.some((p) => x >= p.x && x <= p.x + p.w && y >= p.y && y <= p.y + p.h);
+            if (on)
+                hit++;
+            if (inCentre) {
+                centreN++;
+                if (on)
+                    centre++;
+            }
+        }
+    }
+    return { share: hit / (N * N), centre: centreN ? centre / centreN : 0 };
+}
+const lum = (c) => {
+    const l = (v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+    return 0.2126 * l(c[0]) + 0.7152 * l(c[1]) + 0.0722 * l(c[2]);
+};
+export const ratio = (a, b) => {
+    const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p);
+    return (x + 0.05) / (y + 0.05);
+};
+export function textContrast(img, p, scale = 1) {
+    if (!p.colour || !p.text)
+        return null;
+    const edge = p.outline ? Math.round(ratio(p.colour, p.outline) * 100) / 100 : null;
+    const ground = groundContrast(img, p, p.colour, scale);
+    return ground === null ? edge : edge === null ? ground : Math.max(edge, ground);
+}
+function groundContrast(img, p, ink, scale) {
+    const x0 = Math.max(0, Math.floor(p.x * scale)), y0 = Math.max(0, Math.floor(p.y * scale));
+    const x1 = Math.min(img.width, Math.ceil((p.x + p.w) * scale)), y1 = Math.min(img.height, Math.ceil((p.y + p.h) * scale));
+    const ground = [], all = [];
+    const step = Math.max(1, Math.floor(Math.sqrt(((x1 - x0) * (y1 - y0)) / 4000)));
+    for (let y = y0; y < y1; y += step) {
+        for (let x = x0; x < x1; x += step) {
+            const i = (y * img.width + x) * 4, c = [img.data[i], img.data[i + 1], img.data[i + 2]];
+            all.push(lum(c));
+            if (Math.hypot(c[0] - ink[0], c[1] - ink[1], c[2] - ink[2]) > 24)
+                ground.push(lum(c));
+        }
+    }
+    if (!all.length)
+        return null;
+    const pool = ground.length >= all.length * 0.2 ? ground : all;
+    pool.sort((a, b) => a - b);
+    const g = pool[pool.length >> 1];
+    const t = lum(ink);
+    return Math.round((Math.max(t, g) + 0.05) / (Math.min(t, g) + 0.05) * 100) / 100;
+}
+export const STANDING_SHARE = 0.75;
+const slot = (p) => `${p.layer}|${p.name.split(' "')[0]}|${Math.round((p.x + p.w / 2) / 24)}|${Math.round((p.y + p.h / 2) / 24)}`;
+export function settle(samples) {
+    if (samples.length < 4)
+        return samples;
+    const seen = new Map();
+    for (const s of samples)
+        for (const k of new Set(s.pieces.map(slot)))
+            seen.set(k, (seen.get(k) ?? 0) + 1);
+    const standing = (p) => (seen.get(slot(p)) ?? 0) >= STANDING_SHARE * samples.length;
+    return samples.map((s) => ({ ...s, pieces: s.pieces.map((p) => (p.transient && standing(p) ? { ...p, transient: false } : p)) }));
+}
+const word = (t) => t.toLowerCase().replace(/[×x]\s?\d+|[+-]?\d[\d,.\u202f\u00a0]*|[!.:]/g, '').trim();
+export function pinnedAtOrigin(p, viewport) {
+    return Math.abs(p.x) < 0.5 && Math.abs(p.y) < 0.5 && p.w > 0 && p.h > 0 && p.w < viewport.w / 2 && p.h < viewport.h / 2;
+}
+export const FADING = 0.9;
+export function sampleFindings(s, i, contrasts) {
+    const f = [];
+    const area = s.play ?? { x: 0, y: 0, w: s.viewport.w, h: s.viewport.h };
+    const c = cover(s.pieces, area);
+    if (c.share > HUD_BARS.maxCover)
+        f.push({ kind: 'cover', severity: 'fail', what: `the HUD paints ${Math.round(c.share * 100)}% of the play area (bar ${HUD_BARS.maxCover * 100}%)`, where: s.view, number: c.share, sample: i });
+    if (c.centre > HUD_BARS.maxCentreCover)
+        f.push({ kind: 'centre', severity: 'warn', what: `${Math.round(c.centre * 100)}% of the middle of the play is under HUD`, where: s.pieces.filter((p) => overlap(p, { x: area.x + area.w * 0.2, y: area.y + area.h * 0.2, w: area.w * 0.6, h: area.h * 0.6 }) > 0).map((p) => p.name).slice(0, 3).join(', '), number: c.centre, sample: i });
+    for (const p of s.pieces) {
+        if (p.text && p.px > 0 && p.px < HUD_BARS.minTextPx)
+            f.push({ kind: 'small_text', severity: 'fail', what: `text at ${p.px} px (bar ${HUD_BARS.minTextPx})`, where: p.name, number: p.px, sample: i });
+        const r = p.transient && (p.fade ?? 1) < FADING ? null : contrasts.get(p);
+        const need = p.px >= HUD_BARS.largePx ? HUD_BARS.contrastLarge : HUD_BARS.contrast;
+        if (typeof r === 'number' && r < need)
+            f.push({ kind: 'contrast', severity: r < HUD_BARS.contrastLarge ? 'fail' : 'warn', what: `contrast ${r}:1 against the frame behind it (needs ${need}:1)`, where: p.name, number: r, sample: i });
+        if (p.control && (p.x < -1 || p.y < -1 || p.x + p.w > s.viewport.w + 1 || p.y + p.h > s.viewport.h + 1))
+            f.push({ kind: 'control_off_screen', severity: 'fail', what: 'a control is pushed past the screen edge', where: p.name, number: 0, sample: i });
+        if (pinnedAtOrigin(p, s.viewport))
+            f.push({ kind: 'pinned_origin', severity: 'warn', what: `${p.text ? `"${p.text.slice(0, 32)}"` : 'a piece'} sits at the exact screen origin (0, 0): if it follows something in the world, its anchor may have projected off screen or behind the camera`, where: p.name, number: 0, sample: i });
+    }
+    for (const a of s.actors) {
+        const over = s.pieces.filter((p) => !p.control && overlap(p, a) > HUD_BARS.actorCover * a.w * a.h);
+        const standing = over.some((p) => !p.transient);
+        if (over.length)
+            f.push({ kind: a.role === 'player' ? 'over_player' : 'over_threat', severity: a.role === 'player' && standing ? 'fail' : 'warn', what: `HUD over the ${a.role} (${a.name})`, where: over.map((p) => p.name).slice(0, 2).join(', '), number: Math.round((Math.max(...over.map((p) => overlap(p, a))) / (a.w * a.h)) * 100) / 100, sample: i });
+    }
+    const transient = s.pieces.filter((p) => p.transient);
+    if (transient.length > HUD_BARS.maxTransient)
+        f.push({ kind: 'pile_up', severity: 'fail', what: `${transient.length} transient pieces on screen at once (bar ${HUD_BARS.maxTransient})`, where: transient.map((p) => p.name).slice(0, 3).join(', '), number: transient.length, sample: i });
+    const counts = new Map();
+    for (const p of s.pieces)
+        if (p.text && word(p.text))
+            counts.set(word(p.text), (counts.get(word(p.text)) ?? 0) + 1);
+    for (const [w, n] of counts)
+        if (n >= HUD_BARS.repeats && s.pieces.some((p) => p.transient && word(p.text) === w))
+            f.push({ kind: 'repeats', severity: 'fail', what: `"${w}" shown ${n} times at once: merge repeats into one badge`, where: w, number: n, sample: i });
+    const tt = transient.filter((p) => p.text);
+    for (let a = 0; a < tt.length; a++)
+        for (let b = a + 1; b < tt.length; b++) {
+            const o = overlap(tt[a], tt[b]);
+            if (o > 0.25 * Math.min(tt[a].w * tt[a].h, tt[b].w * tt[b].h)) {
+                f.push({ kind: 'toast_overlap', severity: 'fail', what: 'two transient texts drawn over each other', where: `${tt[a].name} × ${tt[b].name}`, number: Math.round(o), sample: i });
+                break;
+            }
+        }
+    return [...f, ...feedbackFindings(s, i), ...placeholderFindings(s.pieces, i)];
+}
+export function judgeHud(samples, findings) {
+    if (!samples.length || samples.every((s) => !s.pieces.length))
+        return { verdict: 'not_observed', findings: [], numbers: {} };
+    const worst = new Map();
+    for (const f of findings.flat()) {
+        const k = `${f.kind}|${f.where}`, w = worst.get(k);
+        const worse = !w || (f.kind === 'contrast' ? f.number < w.number : f.number > w.number);
+        worst.set(k, { ...(worse ? f : w), seen: (w?.seen ?? new Set()).add(f.sample) });
+    }
+    const out = [...worst.values()].map(({ seen, ...f }) => ({ ...f, what: samples.length > 1 ? `${f.what} (in ${seen.size} of ${samples.length} samples)` : f.what }))
+        .sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'fail' ? -1 : 1));
+    const covers = samples.map((s) => cover(s.pieces, s.play ?? { x: 0, y: 0, w: s.viewport.w, h: s.viewport.h }).share);
+    const texts = samples.flatMap((s) => s.pieces.filter((p) => p.text && p.px > 0).map((p) => p.px));
+    const withPlayer = samples.filter((s) => s.actors.some((a) => a.role === 'player'));
+    const numbers = {
+        cover_max: Math.round(Math.max(...covers) * 1000) / 1000,
+        smallest_text_px: texts.length ? Math.min(...texts) : null,
+        worst_contrast: findings.flat().filter((f) => f.kind === 'contrast').reduce((m, f) => (m === null || f.number < m ? f.number : m), null),
+        player_covered_share: withPlayer.length ? Math.round((findings.filter((fs, i) => samples[i].actors.some((a) => a.role === 'player') && fs.some((f) => f.kind === 'over_player')).length / withPlayer.length) * 100) / 100 : null,
+        transient_max: Math.max(...samples.map((s) => s.pieces.filter((p) => p.transient).length)),
+    };
+    return { verdict: out.some((f) => f.severity === 'fail') ? 'fail' : 'pass', findings: out, numbers };
+}
+export function outline(img, boxes, scale = 1) {
+    const data = new Uint8Array(img.data);
+    const put = (x, y, c) => {
+        if (x < 0 || y < 0 || x >= img.width || y >= img.height)
+            return;
+        const i = (y * img.width + x) * 4;
+        data[i] = c[0];
+        data[i + 1] = c[1];
+        data[i + 2] = c[2];
+        data[i + 3] = 255;
+    };
+    for (const b of boxes) {
+        const x0 = Math.round(b.x * scale), y0 = Math.round(b.y * scale), x1 = Math.round((b.x + b.w) * scale), y1 = Math.round((b.y + b.h) * scale);
+        for (let t = 0; t < 2; t++) {
+            for (let x = x0; x <= x1; x++) {
+                put(x, y0 + t, b.rgb);
+                put(x, y1 - t, b.rgb);
+            }
+            for (let y = y0; y <= y1; y++) {
+                put(x0 + t, y, b.rgb);
+                put(x1 - t, y, b.rgb);
+            }
+        }
+    }
+    return { width: img.width, height: img.height, data };
+}

package/dist/look/image-io.js

@@ -0,0 +1,50 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { decodePng, encodePng } from "./png.js";
+import { launch } from "../verify/browser.js";
+export const IMAGE_TYPES = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.avif': 'image/avif',
+};
+export const imageType = (path) => IMAGE_TYPES[extname(path).toLowerCase()] ?? null;
+export const dataUrl = (bytes, type) => `data:${type};base64,${Buffer.from(bytes).toString('base64')}`;
+async function onPage(browser, fn) {
+    const own = browser ? null : (await launch()).browser;
+    try {
+        const context = await (browser ?? own).newContext({ deviceScaleFactor: 1 });
+        try {
+            return await fn(await context.newPage());
+        }
+        finally {
+            await context.close().catch(() => { });
+        }
+    }
+    finally {
+        await own?.close().catch(() => { });
+    }
+}
+const redraw = (src, type) => `(async () => {
+  const img = new Image(); img.src = ${JSON.stringify(src)}; await img.decode();
+  const c = document.createElement('canvas'); c.width = img.naturalWidth; c.height = img.naturalHeight;
+  c.getContext('2d').drawImage(img, 0, 0);
+  return c.toDataURL(${JSON.stringify(type)}, 1);
+})()`;
+export async function decodeImageFile(path, browser = null) {
+    const bytes = await readFile(path);
+    const type = imageType(path);
+    if (!type)
+        throw new Error(`${path}: not an image funtools reads (png, jpg, webp, gif, avif)`);
+    if (type === 'image/png')
+        return decodePng(bytes);
+    return onPage(browser, async (page) => {
+        const png = await page.evaluate(redraw(dataUrl(bytes, type), 'image/png'));
+        return decodePng(Buffer.from(png.slice(png.indexOf(',') + 1), 'base64'));
+    });
+}
+export async function encodeWebp(img, browser = null) {
+    return onPage(browser, async (page) => {
+        const webp = await page.evaluate(redraw(dataUrl(encodePng(img), 'image/png'), 'image/webp'));
+        if (!webp.startsWith('data:image/webp'))
+            throw new Error('this browser cannot encode WebP');
+        return Buffer.from(webp.slice(webp.indexOf(',') + 1), 'base64');
+    });
+}

package/dist/look/life.js

@@ -0,0 +1,96 @@
+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 { autoLog } from "../feedback/auto.js";
+import { PLAYER_WORDS, playerHint, playerSaid } from "./player.js";
+export const LIFE_RECORD = join('.funtools', 'life.json');
+export const LIFE = { playMs: 3000, afterMs: 2000, everyMs: 100, maxNodes: 3000, markWaitMs: 4000, travelMs: 10000, jumpStarts: 24 };
+const starts = (a) => (a ? (a.sources_started || 0) + (a.media_plays || 0) : 0);
+export function windowOf(s, audioBefore, audioAfter, ms) {
+    const cues = !audioBefore && audioAfter?.by_cue ? { cues: audioAfter.by_cue } : {};
+    if (!s || s.engine === 'none')
+        return audioAfter?.observed ? { ms, moving: 0, crowds: 0, particles: 0, lights: 0, starts: starts(audioAfter) - starts(audioBefore), ...cues } : null;
+    return {
+        ms, moving: s.moving, crowds: s.crowds.reduce((n, c) => n + c.updates, 0), particles: s.particles.reduce((n, p) => n + p.updates, 0),
+        lights: s.lights, starts: starts(audioAfter) - starts(audioBefore), ...cues,
+    };
+}
+export const jumped = (after) => after.starts > LIFE.jumpStarts;
+export function reactionTo(before, after) {
+    const what = [];
+    const rate = (n, w) => (w.ms > 0 ? n / w.ms : 0);
+    const fresh = before.cues && after.cues ? Object.keys(after.cues).filter((c) => !(c in before.cues)) : [];
+    if (after.starts > 0 && !jumped(after) && rate(after.starts, after) > rate(before.starts, before) * 1.25)
+        what.push(`${after.starts} sound(s) started (a sting or a roar; ${before.starts} in ${Math.round(before.ms / 1000)} s of play before)`);
+    else if (fresh.length && !jumped(after))
+        what.push(`a sound play never made started: ${fresh.slice(0, 3).join(', ')}`);
+    if (after.moving > before.moving)
+        what.push(`${after.moving} pieces moved or changed (${before.moving} in play before)`);
+    if (after.crowds > before.crowds)
+        what.push('a crowd of instances was rewritten');
+    if (after.particles > before.particles)
+        what.push('particles burst');
+    if (after.lights > before.lights)
+        what.push('lights changed');
+    return what;
+}
+export function judgeReaction(before, after) {
+    const what = reactionTo(before, after);
+    if (what.length)
+        return { reacted: 'yes', what, after };
+    if (jumped(after))
+        return { reacted: 'not_observed', what, after, jump: after.starts };
+    if (after.starts > 0)
+        return { reacted: 'not_observed', what, after, ambient: after.starts };
+    return { reacted: 'no', what, after };
+}
+const top = (s) => [...s.groups.map((g) => `${g.name} ${g.moving}`), ...s.crowds.map((c) => `${c.name} (crowd of ${c.instances})`), ...s.particles.map((p) => `${p.name} (${p.count} particles)`)].slice(0, 6).join(', ');
+export function lifeFindings(r, ctx = {}) {
+    const f = [];
+    const s = r.play;
+    const who = ctx.player ?? { pattern: PLAYER_WORDS, from: 'default', name: null };
+    if (!s || s.engine === 'none')
+        f.push({ level: 'not_observed', text: 'no scene graph found: ambient movers not counted', hint: 'expose it as window.__PIXI_APP__, or window.__THREEJS_SCENE__' });
+    else if (!s.moving && !s.crowds.length && !s.particles.length)
+        f.push({ level: 'warn', text: `NOTHING MOVES: nothing moves but the player in ${r.view ?? 'play'}: the world reads as a still`, hint: 'a crowd of cards that waves, flags, birds, traffic, weather, lights (funpixel-world-and-story, atmosphere)' });
+    else
+        f.push({ level: 'note', text: `${s.moving} piece(s) move or change besides the player${s.crowds.length ? `, ${s.crowds.length} crowd(s)` : ''}${s.particles.length ? `, ${s.particles.length} particle system(s)` : ''}`, hint: top(s) || undefined });
+    if (s && s.engine !== 'none' && !s.player_found) {
+        f.push(ctx.three
+            ? { level: 'warn', text: `NO HERO: no player node in ${r.view ?? 'play'} (a 3D game with no hero to drive, or one the checks cannot find; looked for ${playerSaid(who)})`, hint: `${playerHint(who)} (skill funpixel-3d, references/hero-route.md)` }
+            : { level: 'note', text: `no node matched the player (looked for ${playerSaid(who)}): the player may be counted as ambient life`, hint: playerHint(who) });
+    }
+    else if (s && s.engine !== 'none' && who.from === 'subject') {
+        f.push({ level: 'note', text: `the player is ${playerSaid(who)}`, hint: playerHint(who) });
+    }
+    if (!r.audio?.observed)
+        f.push({ level: 'not_observed', text: 'sound not observed on this page' });
+    else if (!r.bed)
+        f.push({ level: 'warn', text: 'no ambient sound bed: no looping source started', hint: 'one bed per place (a crowd murmur, wind, rain, a room tone) under the stings, ducked and swelled by events (funpixel-audio)' });
+    else
+        f.push({ level: 'note', text: `a sound bed plays (${r.audio.loop_starts} looping start(s))` });
+    if (!r.reactions.length)
+        f.push({ level: 'not_observed', text: 'no big moment to watch: declare a view with moment: true in __FPX_VIEWS__ (or pass --moment)' });
+    for (const x of r.reactions) {
+        if (x.jump)
+            f.push({ level: 'note', text: `the big moment ${x.moment}: ${x.jump} sound(s) started in ${Math.round((x.after?.ms ?? LIFE.afterMs) / 1000)} s — a jump through the moment fired every cue at once; not read as the world answering`, hint: 'the moment view replays its payoff; to hear the answer, play up to the moment and mark it (__FPX_MOMENT__), or let the view stage it at play speed' });
+        if (x.reacted === 'yes')
+            f.push({ level: 'note', text: `the big moment ${x.moment}: the world answered`, hint: x.what.join('; ') });
+        else if (x.reacted === 'no')
+            f.push({ level: 'warn', text: `the big moment ${x.moment}: nothing in the world reacted`, hint: 'a crowd that cheers, a sting, lights, confetti, a line from someone watching' });
+        else if (x.ambient)
+            f.push({ level: 'not_observed', text: `the big moment ${x.moment}: ${x.ambient} sound(s) started in the ${Math.round((x.after?.ms ?? LIFE.afterMs) / 1000)} s after its mark, no more than play makes on its own (${r.baseline?.starts ?? '?'} in ${Math.round((r.baseline?.ms ?? LIFE.playMs) / 1000)} s): an answer cannot be told from the ambient, not judged`, hint: 'a sting of its own (a sound play never makes), a crowd that cheers, lights or confetti at the mark reads as an answer' });
+        else if (!x.jump)
+            f.push({ level: 'not_observed', text: `the big moment ${x.moment}: ${x.mark ? 'no scene graph or sound log to compare' : 'never marked (call __FPX_MOMENT__(name) at the payoff)'}` });
+    }
+    return f;
+}
+export async function recordLife(dir, r) {
+    const path = join(dir, LIFE_RECORD);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify({ ...r, fingerprint: (await fingerprint(dir)).fingerprint, reads: sceneReads(dir), at: new Date().toISOString() }, null, 2) + '\n');
+    if (r.play && r.play.engine !== 'none')
+        autoLog(dir, 'life', `moving besides the player${r.view ? ` (${r.view})` : ''}`, r.play.moving, '', LIFE_RECORD);
+    autoLog(dir, 'life', 'warnings', r.findings.filter((f) => f.level === 'warn').length, '', LIFE_RECORD);
+}

package/dist/look/light.js

@@ -0,0 +1,42 @@
+export const LIGHT_KEYS = {
+    preset: { kind: 'preset' },
+    exposure: { kind: 'number', min: 0.2, max: 3 },
+    key: { kind: 'colour' }, keyIntensity: { kind: 'number', min: 0, max: 10 }, keyElevation: { kind: 'number', min: -10, max: 90 }, keyAzimuth: { kind: 'number', min: -360, max: 360 },
+    fill: { kind: 'colour' }, fillIntensity: { kind: 'number', min: 0, max: 5 }, rim: { kind: 'colour' }, rimIntensity: { kind: 'number', min: 0, max: 5 },
+    sky: { kind: 'colour' }, bounce: { kind: 'colour' }, ambient: { kind: 'number', min: 0.15, max: 4 },
+    fogNear: { kind: 'number', min: 0, max: 500 }, fogFar: { kind: 'number', min: 1, max: 1000 }, shadow: { kind: 'shadow' },
+    spots: { kind: 'number', min: 0, max: 8 }, spot: { kind: 'colour' }, spotIntensity: { kind: 'number', min: 0, max: 400 },
+    saturation: { kind: 'number', min: 0, max: 2 }, contrast: { kind: 'number', min: 0.5, max: 1.6 }, tint: { kind: 'colour' }, tintAmount: { kind: 'number', min: 0, max: 0.4 },
+    vignette: { kind: 'number', min: 0, max: 0.9 }, bloom: { kind: 'number', min: 0, max: 3 }, bloomThreshold: { kind: 'number', min: 0, max: 1.5 },
+};
+export const LIGHT_PRESETS = ['dusk', 'moonlit-spot', 'overcast', 'studio', 'noon', 'dawn'];
+export function lightProblems(block) {
+    if (!block || typeof block !== 'object' || Array.isArray(block))
+        return [{ token: 'light', what: 'the light block is an object of keys ({ "preset": "dusk", "exposure": 0.9 })', suggest: [] }];
+    const out = [];
+    for (const [k, v] of Object.entries(block)) {
+        if (k.startsWith('$'))
+            continue;
+        const spec = LIGHT_KEYS[k], token = `light.${k}`;
+        if (!spec) {
+            out.push({ token, what: 'not a light key', suggest: Object.keys(LIGHT_KEYS).filter((n) => n.toLowerCase().includes(k.toLowerCase().slice(0, 4))).slice(0, 3) });
+            continue;
+        }
+        if (spec.kind === 'preset' && !LIGHT_PRESETS.includes(String(v)))
+            out.push({ token, what: `${JSON.stringify(v)} is not a preset`, suggest: [...LIGHT_PRESETS] });
+        if (spec.kind === 'shadow' && !['soft', 'hard', 'off'].includes(String(v)))
+            out.push({ token, what: `${JSON.stringify(v)} is not soft, hard or off`, suggest: [] });
+        if (spec.kind === 'colour' && !(typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v)))
+            out.push({ token, what: `${JSON.stringify(v)} is not a #rrggbb colour`, suggest: [] });
+        if (spec.kind === 'number') {
+            if (typeof v !== 'number' || !Number.isFinite(v))
+                out.push({ token, what: `${JSON.stringify(v)} is not a number`, suggest: [] });
+            else if (v < (spec.min ?? -Infinity))
+                out.push({ token, what: `${v} is under ${spec.min}${k === 'ambient' ? ': a black floor is unreadable, not moody' : ''}`, suggest: [] });
+            else if (v > (spec.max ?? Infinity))
+                out.push({ token, what: `${v} is over ${spec.max}`, suggest: [] });
+        }
+    }
+    return out;
+}
+export const lightValue = (key, raw) => (LIGHT_KEYS[key]?.kind === 'number' && raw !== '' && Number.isFinite(Number(raw)) ? Number(raw) : raw);