@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/depth/fill.js

@@ -0,0 +1,102 @@
+import { normBeat, seenCell, shortSource } from "./story.js";
+const cells = (row) => row.split('|').slice(1, -1).map((c) => c.trim());
+const isRow = (l) => /^\s*\|.*\|\s*$/.test(l);
+const isRule = (l) => /^\s*\|[\s:|-]+\|\s*$/.test(l);
+const PLACE_ROW = /level|area|world|room|stage|wave|garden|chapter|zone|track|place|district|island|floor|region|biome|map/i;
+const STORY_ROW = /story|beat/i;
+export function simLevels(sim) {
+    const skilled = (sim?.cohorts ?? []).find((c) => c?.role === 'skilled');
+    const levels = Array.isArray(skilled?.levels) ? skilled.levels.filter((l) => (l?.reached ?? 0) > 0) : [];
+    return levels.length ? levels.length : null;
+}
+export function contentReached(text, pacing, story, sim = null) {
+    if (!text)
+        return [];
+    const rows = [];
+    let header = null;
+    const places = new Map();
+    for (const p of pacing)
+        for (const v of p.places) {
+            const k = normBeat(v);
+            if (!places.has(k))
+                places.set(k, new Set());
+            places.get(k).add(shortSource(p.source));
+        }
+    const played = pacing.filter((p) => p.placeField && p.places.length);
+    const most = played.reduce((b, p) => (!b || p.places.length > b.places.length ? p : b), null);
+    for (const l of text.replace(/\r/g, '').split('\n')) {
+        if (!isRow(l)) {
+            header = null;
+            continue;
+        }
+        if (isRule(l))
+            continue;
+        const c = cells(l);
+        if (!header) {
+            header = c.map((h) => h.toLowerCase());
+            continue;
+        }
+        const col = header.findIndex((h) => /reached in play/.test(h));
+        if (col < 0 || /<[^<>]{2,}>|…/.test(l))
+            continue;
+        const content = (c[0] ?? '').replace(/`/g, '').trim();
+        const countCell = c[header.findIndex((h) => /count/.test(h))] ?? '';
+        const count = /\d+/.test(countCell) ? Number(/\d+/.exec(countCell)[0]) : null;
+        const names = (c[header.findIndex((h) => /names?/.test(h))] ?? '').split(/[,;]|\band\b/).map((n) => n.trim()).filter(Boolean);
+        const of = count ?? (names.length || null);
+        let reached = null;
+        if (STORY_ROW.test(content) && story.state === 'measured')
+            reached = `${story.seen.length} of ${story.declared} (${[...new Set(story.seen.map((s) => shortSource(s.source)))].slice(0, 2).join(', ') || 'play'})`;
+        else if (names.length && places.size) {
+            const hits = names.filter((n) => places.has(normBeat(n)));
+            if (hits.length)
+                reached = `${hits.length} of ${of ?? names.length} (${[...new Set(hits.flatMap((n) => [...places.get(normBeat(n))]))].slice(0, 2).join(', ')})`;
+        }
+        if (!reached && PLACE_ROW.test(content)) {
+            if (most)
+                reached = `${most.places.length}${of ? ` of ${of}` : ''} (${shortSource(most.source)}, ${most.placeField})`;
+            else {
+                const n = simLevels(sim);
+                if (n)
+                    reached = `${n}${of ? ` of ${of}` : ''} (sim, skilled bot)`;
+            }
+        }
+        rows.push({ content, count, names, reached });
+    }
+    return rows;
+}
+export function fillColumn(text, column, valueOf) {
+    let header = null;
+    let filled = 0;
+    const out = text.split('\n').map((l) => {
+        if (!isRow(l)) {
+            header = null;
+            return l;
+        }
+        if (isRule(l))
+            return l;
+        const c = cells(l);
+        if (!header) {
+            header = c.map((h) => h.toLowerCase());
+            return l;
+        }
+        const col = header.findIndex((h) => column.test(h));
+        if (col < 0 || /<[^<>]{2,}>|…/.test(l))
+            return l;
+        const v = valueOf(c[0].replace(/`/g, '').trim());
+        if (v === null || c[col] === v)
+            return l;
+        while (c.length <= col)
+            c.push('');
+        c[col] = v;
+        filled++;
+        const lead = /^\s*/.exec(l)[0];
+        return `${lead}| ${c.join(' | ')} |`;
+    });
+    return { text: out.join('\n'), filled };
+}
+export function fillDesign(text, rows, story) {
+    const reached = fillColumn(text, /reached in play/, (first) => rows.find((r) => r.content === first)?.reached ?? null);
+    const seen = fillColumn(reached.text, /seen in play/, (first) => seenCell(story, first));
+    return { text: seen.text, filled: reached.filled + seen.filled };
+}

package/dist/depth/inventory.js

@@ -0,0 +1,161 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+const HEADING = /^\s{0,3}(#{1,4})\s+(.+?)\s*#*\s*$/;
+const PLACES = /world|area|region|biome|place|chapter|garden|room|level|stage|map|zone|island|track|floor|act\b|district|maze|course/i;
+const KINDS = /roster|enem|kinds|cast|critter|creature|piece|threat|foe|monster|boss|actor|character|unit|weapon|upgrade|card|joker|item/i;
+const STAGES = /stages?|waves?|progression|ramp|schedule|escalat/i;
+const STORY = /story|beats?|narrative|script|dialog|lines|chapters?/i;
+const AMBIENT = /living world|atmosphere|ambient/i;
+export function designInventory(text, file) {
+    if (!text)
+        return { file, tables: [], places: 0, kinds: 0, debutColumn: false };
+    const tables = [];
+    const headers = [];
+    let heading = '';
+    let rows = [];
+    let header = [];
+    const flush = () => {
+        if (rows.length) {
+            const kind = AMBIENT.test(heading) ? 'other' : STORY.test(heading) && !PLACES.test(heading) ? 'story' : KINDS.test(heading) ? 'kinds' : PLACES.test(heading) ? 'places' : STAGES.test(heading) ? 'stages' : 'other';
+            tables.push({ heading, kind, rows: rows.length, items: rows.map((r) => r.split('|').map((c) => c.trim()).filter(Boolean)[0] ?? '').filter(Boolean).slice(0, 40) });
+            headers.push(header);
+        }
+        rows = [];
+        header = [];
+    };
+    for (const raw of text.replace(/\r/g, '').split('\n')) {
+        const h = HEADING.exec(raw);
+        if (h) {
+            flush();
+            heading = h[2];
+            continue;
+        }
+        if (/^\s*\|.*\|\s*$/.test(raw)) {
+            if (/^\s*\|[\s:|-]+\|\s*$/.test(raw))
+                continue;
+            if (/<[^<>]{2,}>|…/.test(raw))
+                continue;
+            if (!header.length) {
+                header = raw.split('|').map((c) => c.trim().toLowerCase()).filter(Boolean);
+                continue;
+            }
+            rows.push(raw);
+        }
+        else if (rows.length || header.length)
+            flush();
+    }
+    flush();
+    const sum = (k) => tables.filter((t) => t.kind === k).reduce((n, t) => n + t.rows, 0);
+    const debutColumn = headers.some((h) => h.some((c) => /debut|arrives|introduc|unlock|first seen/.test(c)));
+    return { file, tables, places: sum('places') + sum('stages'), kinds: sum('kinds'), debutColumn };
+}
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.funtools', '.git', '.agents', 'test', 'tests', 'design', 'scripts', 'tools', 'shots', 'evidence']);
+const IMAGE = new Set(['.png', '.jpg', '.jpeg', '.webp', '.svg', '.gif', '.avif', '.ktx2']);
+const AUDIO = new Set(['.mp3', '.ogg', '.wav', '.m4a', '.aac', '.flac', '.opus']);
+const MODEL = new Set(['.glb', '.gltf', '.fbx', '.obj']);
+const CODE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs']);
+const PLUMBING = /(^|\/)(probe-kit|probe-human|selftests?|fpx-hooks|expose|hud-kit|markers|pin|toasts|world-hud|feel|splash-funpixel\/.*)\.[jt]sx?$/;
+function walk(dir, root, out = []) {
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const n of names) {
+        if (SKIP_DIRS.has(n) || n.startsWith('.'))
+            continue;
+        const p = join(dir, n);
+        let st;
+        try {
+            st = statSync(p);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            walk(p, root, out);
+        else
+            out.push(relative(root, p).split('\\').join('/'));
+    }
+    return out;
+}
+export function playerText(s) {
+    const t = s.trim();
+    if (t.length < 12 || t.length > 400)
+        return false;
+    if (/[{};<>=]|=>|\$\{|\\n|https?:|\.\/|\.(png|mp3|glb|webp|json|ts|css)\b|#[0-9a-f]{3,8}\b|\brgba?\(|\bvar\(|\d+px\b|\bcalc\(|^[a-z-]+:\s/i.test(t))
+        return false;
+    if (/\w\.\w+\(|[\[\]]|sans-serif|\bserif\b|monospace|system-ui/i.test(t))
+        return false;
+    const words = t.match(/[A-Za-zÀ-ÿ'’]{2,}/g) ?? [];
+    if (words.length < 3)
+        return false;
+    if (/^[a-z0-9_-]+(\s+[a-z0-9_:-]+)+$/.test(t) && !/\b(the|a|an|to|of|and|your|you|is|it|in|on)\b/.test(t))
+        return false;
+    const letters = (t.match(/[A-Za-zÀ-ÿ]/g) ?? []).length;
+    return letters / t.length > 0.6;
+}
+export function textLines(src, file) {
+    const out = [];
+    const lines = src.split('\n');
+    lines.forEach((l, i) => {
+        if (/^\s*(\/\/|\*|\/\*|import\b|export \* from)/.test(l))
+            return;
+        const found = [];
+        for (const m of l.matchAll(/(['"`])((?:\\.|(?!\1).){12,400})\1/g))
+            found.push(m[2].replace(/\\(['"`])/g, '$1'));
+        for (const m of l.matchAll(/>\s*([^<>{}]{12,400}?)\s*</g))
+            found.push(m[1]);
+        for (const f of found)
+            if (playerText(f))
+                out.push({ file, line: i + 1, text: f.trim().replace(/\s+/g, ' ') });
+    });
+    return out;
+}
+export function shippedInventory(root) {
+    const files = walk(root, root);
+    const inv = { images: 0, sounds: 0, music: 0, models: 0, text: [], words: 0 };
+    const seen = new Set();
+    for (const f of files) {
+        const ext = extname(f).toLowerCase();
+        if (IMAGE.has(ext) && !/(^|\/)(favicon|icon|apple-touch|og|splash-funpixel)/i.test(f))
+            inv.images++;
+        else if (AUDIO.has(ext))
+            (/music|bgm|theme|loop|track|song|score|ambien/i.test(f) ? inv.music++ : inv.sounds++);
+        else if (MODEL.has(ext))
+            inv.models++;
+        else if (CODE.has(ext) && f.startsWith('src/') && !PLUMBING.test(f)) {
+            let src = '';
+            try {
+                src = readFileSync(join(root, f), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            for (const t of textLines(src, f)) {
+                if (seen.has(t.text))
+                    continue;
+                seen.add(t.text);
+                inv.text.push(t);
+            }
+        }
+    }
+    inv.words = inv.text.reduce((n, t) => n + (t.text.match(/[A-Za-zÀ-ÿ'’]+/g) ?? []).length, 0);
+    return inv;
+}
+export function textMarkdown(inv) {
+    if (!inv.text.length)
+        return 'No sentence a player can read was found in the source (three or more words in a literal or JSX text).\n';
+    const out = [`${inv.text.length} lines, ${inv.words} words a player can read, from the game's source (literals and JSX text; kit plumbing left out). Order is source order, not play order.`, ''];
+    let file = '';
+    for (const t of inv.text) {
+        if (t.file !== file) {
+            file = t.file;
+            out.push('', `## ${file}`, '');
+        }
+        out.push(`- ${t.text}`);
+    }
+    return out.join('\n') + '\n';
+}

package/dist/depth/pacing.js

@@ -0,0 +1,173 @@
+import { parseStep } from "../play/steps.js";
+export const PLACE_FIELDS = ['place', 'area', 'region', 'biome', 'world', 'zone', 'chapter', 'room', 'level', 'stage', 'garden', 'floor', 'act', 'map', 'wave'];
+export const TENSION_FIELDS = ['tension', 'intensity', 'threat', 'danger', 'pressure', 'heat', 'alarm', 'musicTense', 'music_tense', 'board_fill', 'fill'];
+export const PROGRESS_FIELDS = ['score', 'points', 'lit', 'merges', 'fish', 'flowers', 'dusted', 'cleared', 'folds', 'kills', 'coins', 'gems', 'stars'];
+const OUTCOME = /^(won|win|victory|clear(ed)?|complete(d)?|lost|lose|over|game ?over|dead|death|fail(ed)?|results?|end)$/i;
+const PLAY = /^(play(ing)?|game|run|level|flight|aim)$/i;
+const NOISE = /^(x|y|z|t|dt|time|clock|seed|aim\w*|yaw|pitch|roll|angle|dist\w*|vx|vy|vz|speed|frames?|\w*Frames|particles?|fps|ms|\w*ratio|\w*total|\w*Total|sounds?|queued|runs|best\w*|max\w*|wins|losses|resets|retries|deaths|current|next|mode|muted|volume)$/i;
+export function stepMs(step) {
+    switch (step.kind) {
+        case 'wait': return step.ms;
+        case 'hold_at':
+        case 'hold_key':
+        case 'look': return step.ms;
+        case 'drag': return step.ms;
+        case 'tap': return 80;
+        case 'press': return 60 * step.times;
+        case 'together': return Math.max(0, ...step.parts.map(stepMs));
+        default: return 0;
+    }
+}
+export function lineMs(l, phone = true) {
+    if (typeof l.step !== 'string')
+        return 0;
+    const s = parseStep(l.step, phone);
+    const parsed = typeof s === 'string' ? parseStep(l.step, !phone) : s;
+    if (typeof parsed === 'string')
+        return 0;
+    return parsed.kind === 'until' ? (typeof l.ms === 'number' ? l.ms : 0) : stepMs(parsed);
+}
+export function gameSeconds(lines, phone = true) {
+    const ms = lines.reduce((a, l) => a + lineMs(l, phone), 0);
+    return Math.round(ms / 100) / 10;
+}
+export function samplesFromPlayLog(lines, phone = true) {
+    let t = 0;
+    const out = [];
+    const shots = new Map();
+    for (const l of lines)
+        if (l.shot)
+            shots.set(l.n, l.shot);
+    for (const l of lines) {
+        t += lineMs(l, phone) / 1000;
+        if (l.state && typeof l.state === 'object')
+            out.push({ t: Math.round(t * 10) / 10, step: l.n, state: l.state, shot: l.shot ?? shots.get(l.n) });
+    }
+    return out;
+}
+export function samplesFromJourney(marks) {
+    return marks.filter((m) => m.counters && Object.keys(m.counters).length).map((m) => ({ t: Math.round(m.at_ms / 100) / 10, step: m.step, state: m.counters, shot: m.frame }));
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : typeof v === 'boolean' ? Number(v) : null);
+const firstField = (samples, names, wanted) => {
+    if (wanted)
+        return samples.some((s) => wanted in s.state) ? wanted : null;
+    return names.find((f) => samples.some((s) => f in s.state && s.state[f] !== null)) ?? null;
+};
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+export function pacingOf(source, samples, fields = {}) {
+    const placeField = firstField(samples, PLACE_FIELDS, fields.place);
+    const progressField = firstField(samples, PROGRESS_FIELDS, fields.progress);
+    const tensionField = firstField(samples, TENSION_FIELDS, fields.tension);
+    const beats = [];
+    const outcomes = {};
+    const places = [];
+    const seenNonZero = new Set();
+    const deltas = [];
+    for (let i = 1; i < samples.length; i++) {
+        const a = num(samples[i - 1].state[progressField ?? '']), b = num(samples[i].state[progressField ?? '']);
+        if (a !== null && b !== null && b > a)
+            deltas.push(b - a);
+    }
+    const sorted = [...deltas].sort((x, y) => x - y);
+    const big = sorted.length >= 4 ? Math.max(sorted[Math.floor(sorted.length * 0.75)] * 2, sorted[sorted.length - 1] * 0.6) : Infinity;
+    const tv = tensionField ? samples.map((s) => num(s.state[tensionField])).filter((v) => v !== null) : [];
+    const tMin = tv.length ? Math.min(...tv) : 0, tMax = tv.length ? Math.max(...tv) : 0;
+    const band = (tMax - tMin) * 0.3;
+    let rising = null, extreme = tv[0] ?? 0, peaks = 0, releases = 0;
+    let playSeconds = 0, anyScreen = false;
+    samples.forEach((s, i) => {
+        const prev = samples[i - 1];
+        const at = (kind, says) => beats.push({ t: s.t, step: s.step, kind, says, ...(s.shot ? { shot: s.shot } : {}) });
+        const screen = typeof s.state.screen === 'string' ? s.state.screen : typeof s.state.phase === 'string' ? s.state.phase : null;
+        const before = prev ? (typeof prev.state.screen === 'string' ? prev.state.screen : typeof prev.state.phase === 'string' ? prev.state.phase : null) : null;
+        if (screen !== null)
+            anyScreen = true;
+        if (prev && before !== null && !OUTCOME.test(before) && !/^(title|menu|splash|howto|help|pause|settings|levels?)$/i.test(before))
+            playSeconds += s.t - prev.t;
+        if (screen !== null && screen !== before) {
+            if (OUTCOME.test(screen)) {
+                outcomes[screen] = (outcomes[screen] ?? 0) + 1;
+                at('outcome', `${before ?? 'start'} → ${screen}`);
+            }
+            else if (before !== null)
+                at('screen', `${before} → ${screen}`);
+        }
+        if (placeField && s.state[placeField] !== undefined && s.state[placeField] !== null) {
+            const p = String(s.state[placeField]);
+            if (!places.includes(p)) {
+                places.push(p);
+                if (places.length > 1)
+                    at('place', `${placeField} ${p} (new)`);
+            }
+        }
+        for (const [k, v] of Object.entries(s.state)) {
+            if (k === placeField || k === tensionField || NOISE.test(k))
+                continue;
+            const n = num(v);
+            if (n !== null && n > 0 && !seenNonZero.has(k)) {
+                seenNonZero.add(k);
+                if (prev && num(prev.state[k]) === 0)
+                    at('first', `first ${k} (${n})`);
+            }
+            else if (n !== null && n > 0)
+                seenNonZero.add(k);
+        }
+        if (prev && progressField) {
+            const a = num(prev.state[progressField]), b = num(s.state[progressField]);
+            if (a !== null && b !== null && b - a >= big && b - a > 0)
+                at('payoff', `${progressField} +${b - a} (to ${b})`);
+        }
+        if (tensionField && band > 0) {
+            const v = num(s.state[tensionField]);
+            if (v !== null) {
+                if (rising !== false && v < extreme - band) {
+                    if (rising === true) {
+                        peaks++;
+                        at('tension-peak', `${tensionField} peaked at ${extreme}`);
+                    }
+                    rising = false;
+                    extreme = v;
+                }
+                else if (rising !== true && v > extreme + band) {
+                    if (rising === false) {
+                        releases++;
+                        at('tension-release', `${tensionField} eased to ${extreme}`);
+                    }
+                    rising = true;
+                    extreme = v;
+                }
+                else
+                    extreme = rising === false ? Math.min(extreme, v) : Math.max(extreme, v);
+            }
+        }
+    });
+    const seconds = samples.length ? samples[samples.length - 1].t - samples[0].t : 0;
+    const play = anyScreen ? playSeconds : seconds;
+    const minutes = play / 60;
+    const times = [samples[0]?.t ?? 0, ...beats.map((b) => b.t), samples.at(-1)?.t ?? 0].sort((a, b) => a - b);
+    let flat = null;
+    for (let i = 1; i < times.length; i++) {
+        const gap = times[i] - times[i - 1];
+        if (!flat || gap > flat.seconds)
+            flat = { from: times[i - 1], to: times[i], seconds: Math.round(gap * 10) / 10 };
+    }
+    const debuts = beats.filter((b) => b.kind === 'place' || b.kind === 'first').length;
+    return {
+        source, seconds: Math.round(seconds * 10) / 10, playSeconds: anyScreen ? Math.round(playSeconds * 10) / 10 : null, samples: samples.length, beats,
+        beatsPerMinute: minutes > 0 ? Math.round((beats.length / minutes) * 10) / 10 : 0,
+        debutsPerMinute: minutes > 0 ? Math.round((debuts / minutes) * 10) / 10 : 0,
+        longestFlat: flat && flat.seconds > 0 ? flat : null, placeField, places, progressField, tensionField,
+        tension: tensionField && tv.length ? { min: tMin, max: tMax, peaks, releases } : null, outcomes,
+    };
+}
+export function pacingLine(p) {
+    const parts = [
+        `${p.source}: ${mmss(p.seconds)} of game time${p.playSeconds !== null ? ` (${mmss(p.playSeconds)} in play)` : ''}, ${p.beats.length} beats (${p.beatsPerMinute}/min), ${p.debutsPerMinute} places or firsts a minute`,
+        p.placeField ? `${p.places.length} ${p.placeField}(s) seen (${p.places.slice(0, 8).join(', ')})` : 'no place field in the state (place, level, room, world, garden, wave…): places not measured',
+        p.longestFlat ? `longest stretch with nothing new ${p.longestFlat.seconds} s (${mmss(p.longestFlat.from)}–${mmss(p.longestFlat.to)})` : '',
+        Object.keys(p.outcomes).length ? `outcomes ${Object.entries(p.outcomes).map(([k, v]) => `${v} ${k}`).join(', ')}` : 'no run ended on screen',
+        p.tension ? `${p.tensionField} ranged ${p.tension.min}–${p.tension.max} with ${p.tension.peaks} peak(s) and ${p.tension.releases} release(s)` : 'no tension field in the state (tension, intensity, threat, danger…): the arc of tension is not measured',
+    ];
+    return parts.filter(Boolean).join('; ');
+}

package/dist/depth/story.js

@@ -0,0 +1,97 @@
+export const BEAT_FIELDS = ['beat', 'line', 'scene', 'story'];
+export const normBeat = (s) => s.toLowerCase().replace(/`/g, '').replace(/[^a-z0-9]+/g, '');
+const cells = (row) => row.split('|').slice(1, -1).map((c) => c.trim());
+export function declaredStory(text) {
+    if (!text)
+        return null;
+    if (/^\s*[*_]*story[*_]*\s*:\s*[*_]*\s*declined/im.test(text))
+        return { declined: true, beats: [] };
+    const lines = text.replace(/\r/g, '').split('\n');
+    const start = lines.findIndex((l) => /^##\s+story\b/i.test(l.trim()));
+    if (start < 0)
+        return null;
+    const beats = [];
+    let header = null;
+    for (const l of lines.slice(start + 1)) {
+        if (/^#{1,2}\s/.test(l.trim()))
+            break;
+        if (!/^\s*\|.*\|\s*$/.test(l)) {
+            header = null;
+            continue;
+        }
+        if (/^\s*\|[\s:|-]+\|\s*$/.test(l))
+            continue;
+        const c = cells(l);
+        if (!header) {
+            header = c.map((h) => h.toLowerCase());
+            continue;
+        }
+        if (!/beat/.test(header[0] ?? '') || /<[^<>]{2,}>|…/.test(l))
+            continue;
+        const at = (re) => { const i = header.findIndex((h) => re.test(h)); return i >= 0 ? c[i] ?? '' : ''; };
+        const id = c[0].replace(/`/g, '').trim();
+        if (id)
+            beats.push({ id, when: at(/when/), who: at(/who/), line: at(/line/) });
+    }
+    return { declined: false, beats };
+}
+export function storySeen(source, samples) {
+    const field = BEAT_FIELDS.find((f) => samples.some((s) => typeof s.state[f] === 'string' || typeof s.state[f] === 'number')) ?? null;
+    const values = [];
+    const chapters = new Set();
+    for (const s of samples) {
+        const v = field ? s.state[field] : undefined;
+        if ((typeof v === 'string' && v) || typeof v === 'number') {
+            const value = String(v);
+            if (!values.some((x) => x.value === value))
+                values.push({ value, t: s.t });
+        }
+        const ch = s.state.chapter;
+        if (typeof ch === 'string' || typeof ch === 'number')
+            chapters.add(String(ch));
+    }
+    return { source, field, values, chapters: chapters.size };
+}
+export function storyReport(d, sessions) {
+    const base = { declared: d?.beats.length ?? 0, seen: [], never: [], field: null, chapters: Math.max(0, ...sessions.map((s) => s.chapters)) };
+    if (d?.declined)
+        return { ...base, state: 'declined' };
+    if (!d || !d.beats.length)
+        return { ...base, state: 'none' };
+    if (!sessions.length)
+        return { ...base, state: 'not-played', never: d.beats.map((b) => b.id) };
+    const withField = sessions.filter((s) => s.field);
+    if (!withField.length)
+        return { ...base, state: 'no-field', never: d.beats.map((b) => b.id) };
+    const seen = [];
+    const never = [];
+    for (const b of d.beats) {
+        const hit = withField.map((s) => ({ s, v: s.values.find((x) => normBeat(x.value) === normBeat(b.id)) })).find((h) => h.v);
+        if (hit)
+            seen.push({ id: b.id, source: hit.s.source, t: hit.v.t });
+        else
+            never.push(b.id);
+    }
+    return { ...base, state: 'measured', seen, never, field: withField[0].field };
+}
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+export const shortSource = (s) => s.replace(/^blind round (\d+).*$/, 'blind r$1').replace(/^journey (.+?) run \d+$/, 'journey $1');
+export const tellsAStory = (r, shippedLines) => r.state === 'none' && (shippedLines >= 20 || r.chapters > 1);
+export function storyLine(r, shippedLines = 0) {
+    const ch = r.chapters > 1 ? `; ${r.chapters} chapters passed in play` : '';
+    switch (r.state) {
+        case 'declined': return `story declined on purpose (fine for an arcade game)${ch}`;
+        case 'none': return tellsAStory(r, shippedLines)
+            ? `no ## Story beat table, yet the game ships ${shippedLines} readable line(s)${ch}: declare its beats (want, turn, ending) so play can be held to them, or write "Story: declined"`
+            : `no story declared (no ## Story beat table; fine for an arcade game)${ch}`;
+        case 'not-played': return `${r.declared} beat(s) declared, none measured: no real play with the game's state (funtools play, funtools journey)`;
+        case 'no-field': return `${r.declared} beat(s) declared, but the state names no beat field: set __FPX_STATE__.beat to the beat's id when it plays${ch}`;
+        default: return `${r.declared} beat(s) declared, ${r.seen.length} seen in play${r.never.length ? `; never seen: ${r.never.join(', ')}` : ''}${ch}`;
+    }
+}
+export function seenCell(r, id) {
+    if (r.state !== 'measured')
+        return null;
+    const s = r.seen.find((x) => x.id === id);
+    return s ? `seen (${shortSource(s.source)}, ${mmss(s.t)})` : 'never seen';
+}

package/dist/dev/devtools.js

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function detectEngine(pkg) {
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    if (['three', '@react-three/fiber', '@react-three/drei'].some((p) => p in deps))
+        return { suffix: 'threejs', importName: 'three' };
+    if (['pixi.js', '@pixi/core', '@pixi/display', 'pixijs'].some((p) => p in deps))
+        return { suffix: 'pixi', importName: 'pixi.js' };
+    return null;
+}
+const LIBS = fileURLToPath(new URL('../../../', import.meta.url));
+const BUNDLED = fileURLToPath(new URL('../devtools/', import.meta.url));
+export function distDir(name, bundled = BUNDLED) {
+    const env = process.env[`FUNPIXEL_${name.toUpperCase()}_DIR`];
+    if (env)
+        return env;
+    const own = join(bundled, name);
+    return existsSync(own) ? own : join(LIBS, `funpixel-${name}`, 'dist');
+}
+const firstIn = (dir, files) => files.find((f) => existsSync(join(dir, f))) ?? null;
+export function kaptureScript() {
+    if (['0', 'off', 'false'].includes(process.env.FUNPIXEL_KAPTURE ?? ''))
+        return null;
+    const dir = distDir('kapture');
+    const name = firstIn(dir, ['funpixel-kapture.min.js', 'funpixel-kapture.js']);
+    return name ? { name, file: join(dir, name) } : null;
+}
+export function hookedVersion(hookedEngine, engine) {
+    const re = engine.suffix === 'threejs' ? /REVISION\s*=\s*['"](\d+)['"]/ : /VERSION\s*=\s*['"](\d+\.\d+\.\d+)['"]/;
+    for (const f of [hookedEngine.replace(/\.min\.js$/, '.js'), hookedEngine]) {
+        try {
+            const m = readFileSync(f, 'utf8').match(re);
+            if (m)
+                return m[1];
+        }
+        catch { }
+    }
+    return null;
+}
+export function gameVersion(dir, engine) {
+    try {
+        const v = String(JSON.parse(readFileSync(join(dir, 'node_modules', engine.importName, 'package.json'), 'utf8')).version ?? '');
+        return engine.suffix === 'threejs' ? (v.match(/^0\.(\d+)\./)?.[1] ?? null) : (v.match(/^\d+\.\d+\.\d+/)?.[0] ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+export function engineMismatch(engine, hooked, game) {
+    if (!hooked || !game)
+        return null;
+    const same = engine.suffix === 'threejs' ? hooked === game : hooked.split('.')[0] === game.split('.')[0];
+    if (same)
+        return null;
+    const unit = engine.suffix === 'threejs' ? 'r' : '';
+    return `the game's ${engine.importName} is ${unit}${game} and the inspector's hooked engine is ${unit}${hooked}, so the game runs on its own engine without the inspector (the hooked one would break its ${engine.suffix === 'threejs' ? 'add-ons, e.g. KTX2Loader,' : 'plugins'} at load) — rebuild the inspector against ${unit}${game} (libs/funpixel-inspector: npm run build:hooked-all)`;
+}
+export function findDevtools(pkg, dir) {
+    const engine = detectEngine(pkg);
+    if (!engine)
+        return 'no pixi.js or three dependency, so there is no engine to hook';
+    const inspector = distDir('inspector');
+    const hookedEngine = join(inspector, 'hooked-engines', `${engine.suffix}.min.js`);
+    const ui = firstIn(inspector, [`funpixel-inspector.${engine.suffix}.js`, `funpixel-inspector.${engine.suffix}.min.js`]);
+    if (!existsSync(hookedEngine) || !ui) {
+        return `the inspector is not built (${inspector}) — npm run build:all && npm run build:hooked-all in libs/funpixel-inspector, or set FUNPIXEL_INSPECTOR_DIR`;
+    }
+    const mismatch = dir ? engineMismatch(engine, hookedVersion(hookedEngine, engine), gameVersion(dir, engine)) : null;
+    if (mismatch)
+        return mismatch;
+    const files = {};
+    const scripts = [];
+    const kapture = kaptureScript();
+    if (kapture) {
+        files[`/${kapture.name}`] = kapture.file;
+        scripts.push({ src: `/${kapture.name}` });
+    }
+    files[`/${ui}`] = join(inspector, ui);
+    scripts.push({ src: `/${ui}` });
+    const profiler = distDir('profiler');
+    const prof = firstIn(profiler, [`funpixel-profiler.${engine.suffix}.min.js`, `funpixel-profiler.${engine.suffix}.js`]);
+    if (prof) {
+        files[`/${prof}`] = join(profiler, prof);
+        scripts.push({ src: `/${prof}`, defer: true });
+    }
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const preact = join(inspector, 'hooked-engines', 'preact.min.js');
+    return { engine, hookedEngine, files, scripts, ...('preact' in deps && existsSync(preact) ? { hookedPreact: preact } : {}) };
+}
+export function devtoolsPlugin(tools, allow) {
+    const escaped = tools.engine.importName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return {
+        name: 'funpixel-devtools',
+        enforce: 'pre',
+        config: () => ({
+            resolve: {
+                alias: [
+                    { find: new RegExp(`^${escaped}$`), replacement: tools.hookedEngine },
+                    ...(tools.hookedPreact ? [{ find: /^preact$/, replacement: tools.hookedPreact }] : []),
+                ],
+            },
+            server: { fs: { allow: [...allow, join(tools.hookedEngine, '..')] } },
+            optimizeDeps: { exclude: [tools.engine.importName, ...(tools.hookedPreact ? ['preact', 'preact/hooks', 'preact/jsx-runtime'] : [])] },
+        }),
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                const file = tools.files[String(req.url ?? '').split('?')[0]];
+                if (!file)
+                    return next();
+                res.setHeader('Content-Type', 'text/javascript');
+                res.end(readFileSync(file));
+            });
+        },
+        transformIndexHtml: () => tools.scripts.map(({ src, defer }) => ({
+            tag: 'script', attrs: defer ? { src, defer: true } : { src }, injectTo: 'head',
+        })),
+    };
+}