@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/production/contract.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const READS = {
+    root: 'crates/funpixel-linter/src/game_layout.rs (root-only layout: no client/ nesting)',
+    build: 'the builder: pnpm install --ignore-scripts, then pnpm exec tsc and vite (crates/funpixel-builder)',
+    assets: 'Studio file tree and runtime URLs (game_layout.rs public_assets_prefix, asset_key_for_runtime_url)',
+    hooks: 'verify, capture and the hosted probe (libs/funpixel-tools/src/verify, HOOKS.md: __FPX_STATE__, __FPX_VIEWS__)',
+    three: '@funpixel/inspector and @funpixel/profiler (window.__THREEJS_RENDERER__, __THREEJS_SCENE__, __THREEJS_CAMERA__)',
+    pixi: '@funpixel/inspector and @funpixel/profiler (window.__PIXI_APP__)',
+    engine: 'engine_gate.rs: the preview maps a bundled engine; one loaded from a CDN or an import map shows blank once published',
+    manifest: 'publish and the Studio (funpixel.json: name, game_id, metadata, checks)',
+};
+const BINARY = /\.(png|jpe?g|webp|gif|avif|glb|gltf|mp3|ogg|wav|m4a)$/i;
+export function contractFindings(dir, files) {
+    const out = [];
+    const has = (p) => files.includes(p);
+    const read = (p) => { try {
+        return readFileSync(join(dir, p), 'utf8');
+    }
+    catch {
+        return '';
+    } };
+    const prebuilt = !has('package.json') && has('index.html');
+    if (!prebuilt) {
+        for (const f of ['package.json', 'index.html', 'tsconfig.json'])
+            if (!has(f))
+                out.push({ item: `${f} at the root`, why: `the build reads it: ${READS.build}` });
+        if (!files.some((f) => f.startsWith('src/')))
+            out.push({ item: 'src/ at the root', why: READS.root });
+        const nested = files.find((f) => /^[^/]+\/package\.json$/.test(f) && !f.startsWith('node_modules/'));
+        if (nested)
+            out.push({ item: `one project at the root, not ${nested}`, why: READS.root });
+    }
+    if (!has('funpixel.json'))
+        out.push({ item: 'funpixel.json', why: READS.manifest });
+    const stray = files.filter((f) => BINARY.test(f) && !f.startsWith('public/')).slice(0, 3);
+    if (stray.length)
+        out.push({ item: `generated art and sound under public/assets/ (found ${stray.join(', ')})`, why: READS.assets });
+    const src = files.filter((f) => /^src\/.*\.(ts|tsx|js|jsx|mjs)$/.test(f)).map(read).join('\n') + read('index.html');
+    if (!/__FPX_STATE__|__FPX_VIEWS__|exposeHooks\(/.test(src))
+        out.push({ item: '__FPX_STATE__ and __FPX_VIEWS__ on window', why: READS.hooks });
+    let deps = {};
+    try {
+        const pkg = JSON.parse(read('package.json'));
+        deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    }
+    catch { }
+    if (deps.three || /from ['"]three['"]/.test(src)) {
+        const missing = ['__THREEJS_RENDERER__', '__THREEJS_SCENE__', '__THREEJS_CAMERA__'].filter((g) => !src.includes(g));
+        if (missing.length)
+            out.push({ item: `window.${missing.join(', window.')}`, why: READS.three });
+    }
+    if (deps['pixi.js'] && !src.includes('__PIXI_APP__'))
+        out.push({ item: 'window.__PIXI_APP__', why: READS.pixi });
+    if (/<script[^>]+type=["']importmap["']/i.test(read('index.html')) || /from ['"]https?:\/\/[^'"]*(three|pixi)/.test(src)) {
+        out.push({ item: 'the engine bundled from dependencies (no CDN, no import map)', why: READS.engine });
+    }
+    if (!existsSync(join(dir, '.harnessignore')))
+        out.push({ item: '.harnessignore', why: 'what stays private (notes, tools, raw art, tests): funtools stage reads it before every upload' });
+    return out;
+}

package/dist/production/mirror.js

@@ -0,0 +1,96 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pickTier, TIERS } from "./tier.js";
+import { contentList } from "../gdd/size.js";
+const read = (p) => { try {
+    return readFileSync(p, 'utf8');
+}
+catch {
+    return '';
+} };
+function walk(dir, rel, re, out = []) {
+    let ents = [];
+    try {
+        ents = readdirSync(join(dir, rel));
+    }
+    catch {
+        return out;
+    }
+    for (const e of ents) {
+        if (e.startsWith('.') || e === 'node_modules' || e === 'dist')
+            continue;
+        const r = rel ? `${rel}/${e}` : e;
+        try {
+            if (statSync(join(dir, r)).isDirectory())
+                walk(dir, r, re, out);
+            else if (re.test(e))
+                out.push(r);
+        }
+        catch { }
+    }
+    return out;
+}
+const rank = (t) => TIERS.indexOf(t);
+export function stated(gdd) {
+    const lines = gdd.split('\n').filter((l) => /^\**(pitch|play length)\b/i.test(l.trim()) && !/starter default|<[^>]+>/i.test(l));
+    const rows = (contentList(gdd) ?? []).filter((r) => r.count !== null).map((r) => `${r.count} ${r.what}`);
+    return [...lines, ...rows].join('\n');
+}
+export function productionMirror(dir) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(read(join(dir, 'funpixel.json')));
+    }
+    catch { }
+    const gdd = read(join(dir, 'design', 'GDD.md')) || read(join(dir, 'design', 'plan.md'));
+    const three = manifest?.metadata?.dimension === '3d';
+    const recordedTier = TIERS.includes(manifest?.production?.tier) ? manifest.production.tier : null;
+    const fromGdd = gdd ? pickTier(stated(gdd), { three }).tier : null;
+    const tier = recordedTier ?? fromGdd ?? 'small';
+    const suggested = fromGdd && rank(fromGdd) > rank(tier) ? fromGdd : null;
+    const src = walk(dir, 'src', /\.(ts|tsx|js|jsx)$/).map((f) => read(join(dir, f))).join('\n');
+    const tests = walk(dir, 'test', /\.(ts|js|mjs)$/).map((f) => read(join(dir, f))).join('\n');
+    const lines = [];
+    const add = (level, loop, text, hint) => lines.push({ level, loop, text, hint });
+    if (!/same seed|replay|determinis/i.test(tests))
+        add('warn', 'verify', 'no test replays the rules from a seed', 'a bug you cannot replay you cannot fix; one test: same seed + same inputs = same state (skill funpixel-game-logic)');
+    if (/style\.filter\s*=[^;\n]*brightness|filter\s*:\s*brightness\(\s*[2-9]/.test(src))
+        add('warn', 'verify', 'a full-screen brightness flash in the code', 'the owner\'s rule: never flash the full screen; an edge vignette or a local flash on the struck body reads the hit');
+    if (!/visibilitychange|__FPX_HOLD__/.test(src))
+        add('note', 'verify', 'nothing pauses the game while its tab is hidden', 'a phone call or a tab switch should find the game paused and quiet (the scaffold\'s platform.ts does it)');
+    if (rank(tier) >= 1) {
+        if (!/SaveManager|localStorage\.setItem|storage\.setItem/.test(src))
+            add('warn', 'direct', 'nothing saves progress', 'a game with levels or chapters keeps where the player got to across a reload (SaveManager from @funpixel/sdk/save)');
+        const frames = walk(dir, 'design', /\.(png|jpe?g|webp)$/).filter((f) => !/\/shots\//.test(f));
+        if (!frames.length)
+            add('note', 'direct', 'no target frames in design/ yet', 'one frame per place or level, judged beside the game at fixed framing (capture --all, compare)');
+        if (existsSync(join(dir, 'assets', 'assets.json')) && !existsSync(join(dir, 'assets', 'costs.jsonl')) && existsSync(join(dir, 'public', 'assets')))
+            add('note', 'consistent', 'no assets/costs.jsonl beside generated art', 'assets gen keeps every original in assets/raw/ and a line per job in the ledger');
+    }
+    if (tier === 'deep') {
+        const making = read(join(dir, 'design', 'MAKING.md'));
+        const entries = (making.match(/^## /gm) ?? []).length;
+        if (!making)
+            add('warn', 'direct', 'no design/MAKING.md', 'the making-of log: per lane, the decision, its numbers and the lesson');
+        else if (entries <= 1)
+            add('note', 'direct', 'design/MAKING.md has no lane entry yet', 'write one when a lane lands: decision, numbers, lesson');
+        if (gdd && !/^## Identity lock/m.test(gdd))
+            add('note', 'consistent', 'the GDD has no Identity lock section', 'reference sheets for every recurring design before frames (skill funpixel-gdd, world-and-identity.md)');
+    }
+    return { tier, recorded: !!recordedTier, suggested, lines };
+}
+export function makingLog(name, date) {
+    return `# Making ${name}
+
+A running log, one entry per lane when it lands: what was decided, the numbers that decided it, and the lesson
+for the next lane. Before/after frames at fixed framing (desktop 1280x720, phone 844x390) beside each entry.
+Stays private (/design/ is in .harnessignore).
+
+## ${date} · Lane 0: the plan
+
+- **Decision:** <what was chosen, and what was not>
+- **Numbers:** <the measurement behind it: a profile, a blind player's minutes, a panel score>
+- **Lesson:** <what the next lane should know>
+- **Evidence:** <frames, films or reports, by path>
+`;
+}

package/dist/production/tier.js

@@ -0,0 +1,66 @@
+export const TIERS = ['small', 'mid', 'deep'];
+const STORY = /\b(story|story-led|narrative|dialogue|characters? (?:who )?(?:talk|speak)|campaign|quest|cutscenes?|chapters?|plot|lore|mystery)\b/i;
+const CASUAL = /\b(hybrid[- ]casual|one[- ]thumb|one[- ]tap|one[- ]button|merge|endless|arcade|idle|hyper[- ]casual|match[- ]3|sort|stack)\b/i;
+const THREE = /\b(3d|3-d|three\.js|threejs|first[- ]person|third[- ]person|voxel|low[- ]poly)\b/i;
+const NUM = '(\\d+(?:\\.\\d+)?)(?:\\s*(?:-|–|to)\\s*(\\d+(?:\\.\\d+)?))?';
+const top = (m) => Number(m[2] ?? m[1]);
+const WORD_NUM = { one: '1', two: '2', three: '3', four: '4', five: '5', six: '6', seven: '7', eight: '8', nine: '9', ten: '10', eleven: '11', twelve: '12', fifteen: '15', twenty: '20', thirty: '30', forty: '40', fifty: '50', ninety: '90' };
+export function signals(text, three = false) {
+    const t = text.replace(/[~≈]/g, ' ').replace(/\b(an|a) (hour|half hour)\b/gi, (_m, _a, h) => (h === 'hour' ? '1 hour' : '30 minutes'))
+        .replace(/\b(one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|fifteen|twenty|thirty|forty|fifty|ninety)\b/gi, (w) => WORD_NUM[w.toLowerCase()]);
+    const hours = new RegExp(`${NUM}\\s*-?\\s*(?:h|hr|hrs|hours?)\\b`, 'i').exec(t);
+    const mins = new RegExp(`${NUM}\\s*-?\\s*(?:m|min|mins|minutes?)\\b`, 'i').exec(t);
+    const minutes = hours ? top(hours) * 60 : mins ? top(mins) : null;
+    const lv = new RegExp(`${NUM}\\s+(?:[a-z-]+\\s+)?(?:levels?|stages?|rooms?|worlds?|missions?|areas?|islands?|districts?)\\b`, 'i').exec(t);
+    const ch = new RegExp(`${NUM}\\s+(?:[a-z-]+\\s+)?(?:chapters?|acts?|episodes?)\\b`, 'i').exec(t);
+    return {
+        minutes, levels: lv ? top(lv) : null, chapters: ch ? top(ch) : /\bchapters\b/i.test(t) ? 2 : null,
+        story: STORY.test(t), three: three || THREE.test(t), casual: CASUAL.test(t),
+    };
+}
+export function pickTier(text, opts = {}) {
+    const s = signals(text, opts.three);
+    const deep = [], mid = [];
+    if (s.minutes !== null && s.minutes >= 60)
+        deep.push(`${fmt(s.minutes)} of play`);
+    if (s.chapters !== null && s.chapters >= 3)
+        deep.push(`${s.chapters} chapters`);
+    if (s.three && s.story && ((s.levels ?? 0) >= 5 || (s.minutes ?? 0) >= 30))
+        deep.push(`3D, story-led, ${s.levels ? `${s.levels} levels` : fmt(s.minutes)}`);
+    if (s.minutes !== null && s.minutes >= 15 && s.minutes < 60)
+        mid.push(`${fmt(s.minutes)} of play`);
+    if (s.story)
+        mid.push('a story to tell');
+    if (s.chapters === 2)
+        mid.push('chapters');
+    if (s.levels !== null && s.levels >= 3 && s.levels <= 20 && !s.casual)
+        mid.push(`${s.levels} levels`);
+    if (deep.length)
+        return { tier: 'deep', because: deep, signals: s };
+    if (mid.length)
+        return { tier: 'mid', because: mid, signals: s };
+    const small = s.casual ? ['a one-second mechanic'] : [];
+    if (s.minutes !== null)
+        small.push(`${fmt(s.minutes)} of play`);
+    if (s.levels !== null)
+        small.push(`${s.levels} levels`);
+    return { tier: 'small', because: small.length ? small : ['no length, levels, chapters or story stated'], signals: s };
+}
+const fmt = (m) => (m >= 60 ? `${+(m / 60).toFixed(1)} h` : `${m} min`);
+export const SWITCHES = {
+    small: {
+        direct: 'the GDD and one target frame',
+        consistent: 'one palette and the style block',
+        verify: 'seeded rules tests, verify, look --hud, a blind phone player',
+    },
+    mid: {
+        direct: 'target frames per place or level, progress saved per level or chapter',
+        consistent: 'reference sheets before art, best-of-N draws judged on palette, raw originals and a costs ledger',
+        verify: 'bots on several seeds and a replay test, fixed-framing before/after (capture --all, compare), sim per level',
+    },
+    deep: {
+        direct: 'a making-of log (design/MAKING.md), show first and build behind a flag, one lane per worktree',
+        consistent: 'identity locks for every recurring design, hard-surface models rebuilt rather than shipped decimated',
+        verify: 'blind phone players from the title as a gate, an A/B phone profile on a fixed seed, evidence per lane',
+    },
+};

package/dist/profile/compare.js

@@ -0,0 +1,171 @@
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    if (values.length === 1)
+        return values[0];
+    const sorted = [...values].sort((a, b) => a - b);
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+export const SLO_ERROR_BUDGET = 0.01;
+export function computeBurnRate(samples, targetFrameMs, minSamples = 30) {
+    if (samples.length < minSamples)
+        return 0;
+    let overBudget = 0;
+    for (const s of samples)
+        if (s.frameTime > targetFrameMs)
+            overBudget += 1;
+    return overBudget / samples.length / SLO_ERROR_BUDGET;
+}
+export const NEUTRAL_BAND_PCT = 5;
+export const DEFAULT_BUDGET_MS = 18;
+export function classify(direction, deltaPct) {
+    if (Math.abs(deltaPct) <= NEUTRAL_BAND_PCT)
+        return 'neutral';
+    const better = (direction === 'higher_is_better' && deltaPct > 0) || (direction === 'lower_is_better' && deltaPct < 0);
+    return better ? 'improvement' : 'regression';
+}
+const r2 = (x) => Math.round(x * 100) / 100;
+export function snapshotOf(sample, conditions, meta) {
+    const ft = Array.isArray(sample.frame_ms_samples) ? sample.frame_ms_samples.filter((x) => typeof x === 'number' && x > 0) : [];
+    if (!ft.length)
+        return null;
+    const fps = ft.map((x) => 1000 / x);
+    const buckets = new Array(12).fill(0);
+    for (const x of ft)
+        buckets[Math.min(11, Math.max(0, Math.floor(x / 4)))] += 1;
+    const heap = typeof sample.heap_mb === 'number' ? sample.heap_mb : 0;
+    const burn = computeBurnRate(ft.map((frameTime) => ({ frameTime })), conditions.budget_ms, 1);
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        gameId: meta.gameId,
+        buildId: meta.buildId,
+        capturedAt: meta.now ?? Date.now(),
+        engineKind: sample.engine === 'three' ? 'Three' : sample.engine === 'pixi' ? 'PixiJS' : 'unknown',
+        windowMs: Math.round(ft.reduce((a, b) => a + b, 0)),
+        fps: { p50: r2(percentile(fps, 50)), p95: r2(percentile(fps, 95)), p99: r2(percentile(fps, 99)), min: r2(Math.min(...fps)), max: r2(Math.max(...fps)) },
+        frameTimeMs: { p50: r2(percentile(ft, 50)), p95: r2(percentile(ft, 95)), p99: r2(percentile(ft, 99)), max: r2(Math.max(...ft)) },
+        frameTimeBuckets: buckets,
+        heapMB: { start: heap, end: heap, min: heap, max: heap },
+        scoreOverall: 0, scoreSmooth: 0, scoreMemory: 0,
+        sampleCount: ft.length,
+        local: {
+            burn: r2(burn),
+            over_budget_pct: r2(burn * SLO_ERROR_BUDGET * 100),
+            work_ms_p95: num(sample.work_ms_p95),
+            draw_calls: num(sample.draw_calls),
+            triangles: num(sample.triangles),
+            texture_mb: num(sample.scene?.texture_mb),
+            gpu_ms_p95: num(sample.gpu_ms?.p95),
+            gpu_unavailable: typeof sample.gpu_unavailable === 'string' ? sample.gpu_unavailable : null,
+            dist_kb: num(sample.dist?.kb),
+        },
+        conditions,
+    };
+}
+const ROWS = [
+    { metric: 'frame_time_p95', label: 'frame p95', unit: ' ms', dir: 'lower_is_better', get: (s) => s.frameTimeMs.p95, dp: 1 },
+    { metric: 'fps_p95', label: 'FPS p95', unit: '', dir: 'higher_is_better', get: (s) => s.fps.p95, dp: 1 },
+    { metric: 'heap_max', label: 'heap max', unit: ' MB', dir: 'lower_is_better', get: (s) => s.heapMB.max, dp: 1 },
+    { metric: 'score_overall', label: 'score', unit: '', dir: 'higher_is_better', get: (s) => s.scoreOverall, dp: 0 },
+    { metric: 'frame_time_p50', label: 'frame p50', unit: ' ms', dir: 'lower_is_better', get: (s) => s.frameTimeMs.p50, dp: 1 },
+    { metric: 'work_p95', label: 'JS work p95', unit: ' ms', dir: 'lower_is_better', get: (s) => s.local.work_ms_p95, dp: 2 },
+    { metric: 'gpu_p95', label: 'GPU p95', unit: ' ms', dir: 'lower_is_better', get: (s) => s.local.gpu_ms_p95, dp: 2 },
+    { metric: 'draw_calls', label: 'draw calls', unit: '', dir: 'lower_is_better', get: (s) => s.local.draw_calls, dp: 0 },
+    { metric: 'triangles', label: 'triangles', unit: '', dir: 'lower_is_better', get: (s) => s.local.triangles, dp: 0 },
+    { metric: 'texture_mb', label: 'texture MB', unit: '', dir: 'lower_is_better', get: (s) => s.local.texture_mb, dp: 1 },
+    { metric: 'dist_kb', label: 'dist KB', unit: '', dir: 'lower_is_better', get: (s) => s.local.dist_kb, dp: 0 },
+];
+export function compareSnapshots(current, prior) {
+    const out = [];
+    for (const row of ROWS) {
+        const cur = row.get(current), pr = row.get(prior);
+        if (cur === null || pr === null)
+            continue;
+        if (pr <= 0 && (row.metric === 'score_overall' || cur <= 0))
+            continue;
+        const deltaPct = pr > 0 ? ((cur - pr) / pr) * 100 : 100;
+        out.push({ metric: row.metric, label: row.label, prior: pr, current: cur, change: cur - pr, deltaPct, severity: classify(row.dir, deltaPct), unit: row.unit });
+    }
+    return out;
+}
+const fmt = (x, dp) => (Number.isInteger(x) && dp === 0 ? String(x) : x.toFixed(dp));
+const dpOf = (metric) => ROWS.find((r) => r.metric === metric)?.dp ?? 1;
+export function deltaLine(d) {
+    const dp = dpOf(d.metric);
+    const sign = d.change >= 0 ? '+' : '−';
+    const pct = d.prior > 0 ? `, ${d.deltaPct >= 0 ? '+' : '−'}${Math.abs(Math.round(d.deltaPct))}%` : '';
+    return `${d.label} ${fmt(d.prior, dp)} → ${fmt(d.current, dp)}${d.unit} (${sign}${fmt(Math.abs(d.change), dp)}${d.unit}${pct})${d.severity === 'neutral' ? '' : ` ${d.severity}`}`;
+}
+export function burnLine(current, prior) {
+    const b = current.conditions.budget_ms;
+    const now = `${current.local.burn}× (${current.local.over_budget_pct}% of frames over ${b} ms)`;
+    if (!prior)
+        return `frame budget burn ${now}`;
+    return `frame budget burn ${prior.local.burn}× → ${now}${current.local.burn > prior.local.burn ? ' — spending more of the 1% it may miss' : current.local.burn < prior.local.burn ? ' — spending less' : ''}`;
+}
+export function gpuLine(s) {
+    return s.local.gpu_ms_p95 !== null ? `GPU p95 ${s.local.gpu_ms_p95} ms a frame` : `GPU time not measured: ${s.local.gpu_unavailable ?? 'not asked'}`;
+}
+export const sameConditions = (a, b) => a.view === b.view && a.viewport === b.viewport && a.seed === b.seed && a.throttle === b.throttle
+    && a.software === b.software && a.frames === b.frames && a.budget_ms === b.budget_ms;
+export function conditionsDiffer(a, b) {
+    const out = [];
+    for (const k of ['seed', 'throttle', 'software', 'frames', 'budget_ms'])
+        if (a[k] !== b[k])
+            out.push(`${k} ${b[k]} → ${a[k]}`);
+    return out;
+}
+export function age(ms) {
+    if (ms < 60_000)
+        return 'just now';
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours} hr ago`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? '' : 's'} ago`;
+}
+export function openSnapshotStore(file) {
+    const all = async () => {
+        if (!existsSync(file))
+            return [];
+        const out = [];
+        for (const line of (await readFile(file, 'utf8')).split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const s = JSON.parse(line);
+                if (s && s.conditions && s.frameTimeMs)
+                    out.push(s);
+            }
+            catch { }
+        }
+        return out;
+    };
+    return {
+        async put(snap) {
+            await mkdir(dirname(file), { recursive: true });
+            await appendFile(file, JSON.stringify(snap) + '\n');
+        },
+        async getLast(c) { return (await this.getRecent(c, 1))[0] ?? null; },
+        async getRecent(c, limit) { return (await all()).filter((s) => sameConditions(s.conditions, c)).reverse().slice(0, limit); },
+        async getNewest() { const xs = await all(); return xs[xs.length - 1] ?? null; },
+        async prune(keep) {
+            const xs = await all();
+            if (xs.length <= keep)
+                return;
+            await writeFile(file, xs.slice(-keep).map((s) => JSON.stringify(s)).join('\n') + '\n');
+        },
+    };
+}

package/dist/progress/answers.js

@@ -0,0 +1,35 @@
+import { ensurePipeline, writePipeline } from "../commands/next.js";
+import { evaluate } from "../pipeline/pipeline.js";
+import { appendEntry, BUDGET_TOPIC, readProgress } from "./progress.js";
+export function answerQuestion(root, q, pick, o = {}) {
+    const s = readProgress(root);
+    const question = s.questions.find((x) => x.id === q);
+    if (!question)
+        throw new Error(`no question ${q}${s.questions.length ? ` (${s.questions.map((x) => x.id).join(', ')})` : ''}`);
+    if (!question.options.includes(pick) && !(question.topic === BUDGET_TOPIC && /^\d{1,7}$/.test(pick)))
+        throw new Error(`${q} takes one of: ${question.options.join(', ')}${question.topic === BUDGET_TOPIC ? ', or a whole number of credits' : ''}`);
+    const a = { type: 'answer', q, at: (o.now ?? new Date()).toISOString(), pick, by: o.by ?? 'owner', ...(o.words?.trim() ? { words: o.words.trim().slice(0, 500) } : {}) };
+    appendEntry(root, a);
+    return a;
+}
+export function addOwnerNote(root, text, now = new Date(), screenshot) {
+    const words = text.replace(/\s+/g, ' ').trim().slice(0, 2000);
+    if (!words)
+        throw new Error('nothing to note');
+    const [p] = ensurePipeline(root, now);
+    const last = readProgress(root).last?.stage;
+    let stage = last && p.stages.some((x) => x.id === last) ? last : null;
+    if (!stage) {
+        try {
+            stage = evaluate(root, p, null).current?.stage.id ?? null;
+        }
+        catch { }
+    }
+    const n = {
+        id: `N${p.notes.reduce((m, x) => Math.max(m, Number(/^N(\d+)$/.exec(x.id)?.[1] ?? 0)), 0) + 1}`,
+        stage: stage ?? p.stages[0]?.id ?? 'pitch', text: words, by: 'owner', at: now.toISOString().replace(/\.\d+Z$/, 'Z'), ...(screenshot ? { screenshot } : {}), status: 'open',
+    };
+    p.notes.push(n);
+    writePipeline(root, p);
+    return n;
+}

package/dist/progress/holds.js

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { evaluate, HOLD_LABELS, readPipeline, TIER_STAGES, worldRead } from "../pipeline/pipeline.js";
+import { readProgress } from "./progress.js";
+import { madeOf } from "../look/made-of.js";
+export { HOLD_LABELS };
+const LABEL = new RegExp(`(^|: )(${HOLD_LABELS.join('|')}):`);
+const NO_HERO = /no (player|hero) node found|no hero on screen/i;
+export const ART_OUT = /\b(3d|models?|mesh(es)?|glb|art|sprites?|images?|textures?|pictures?|portraits?|characters?|cut-?outs?|assets?|generated|concepts?)\b/i;
+export const CODE_STANDIN = /\b(code|coded|primitives?|box(es)?|cubes?|capsules?|cylinders?|spheres?|placeholders?|procedural|gr[ae]y ?box(ed)?|shapes?|flat cut-?outs?)\b/i;
+export const ACCEPT_PICK = /^(accept(-?stand-?ins)?|stand-?ins|keep-stand-?ins|2d|2d-cut-?outs|cut-?outs|pause)$/i;
+const ART_WORD = String.raw `(stand-?ins?|primitives?|box(es)?|placeholders?|code[- ]built|shapes?|cut-?outs?|low[- ]?poly|blocky|flat shapes?)`;
+export const ACCEPT_WORDS = new RegExp(String.raw `\baccept\w*\b[^.]*\b${ART_WORD}\b|\b${ART_WORD}\b[^.]*\b(are|is)\b[^.]*\b(fine|ok|okay|good|accepted|the (style|look)|on purpose|intended|what I want)\b`, 'i');
+const ABOUT_ART = /\b(3d|models?|art|stand-?ins?|primitives?|box(es)?|cut-?outs?|sprites?|images?|generat\w*|provider|look)\b/i;
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+const short = (s, n = 160) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`);
+const PLAYABLE = new Set(TIER_STAGES.deep.slice(TIER_STAGES.deep.indexOf('slice')));
+export function builtAndPlays(root, fp) {
+    const v = readJson(join(root, 'verify.json'));
+    if (v?.verdict === 'pass' && (!fp || !v.fingerprint || v.fingerprint === fp))
+        return true;
+    return existsSync(join(root, 'dist', 'index.html'));
+}
+export function isThree(m) {
+    const d = m?.metadata?.dimension;
+    return d === '3d' || (!d && /three/i.test(String(m?.metadata?.framework ?? '')));
+}
+function stageOf(root, fp, s) {
+    const p = readPipeline(root);
+    if (p) {
+        try {
+            const e = evaluate(root, p, fp);
+            if (e.current)
+                return e.current.stage.id;
+            return 'done';
+        }
+        catch { }
+    }
+    return s.last?.stage ?? null;
+}
+export function worldHolds(root, fp) {
+    const w = worldRead(root, fp);
+    const m = readJson(join(root, 'funpixel.json')) ?? {};
+    const three = isThree(m);
+    const out = [];
+    if (three) {
+        let made = null;
+        try {
+            made = madeOf(root, { manifest: m });
+        }
+        catch { }
+        if (made?.verdict === 'fail')
+            out.push({ kind: 'world', line: short(`HERO OBJECTS ARE CODE (look --3d): ${made.says} — take the hero route (generated models, skill funpixel-3d, references/hero-route.md), or declare a procedural style in funpixel.json "art3d" { "heroes": "procedural", "why", "proof": "<frame>" }`, 320) });
+    }
+    if (w.state === 'failing') {
+        for (const x of w.warns)
+            if (LABEL.test(x) || NO_HERO.test(x))
+                out.push({ kind: 'world', line: short(NO_HERO.test(x) && !LABEL.test(x) ? `NO HERO IN THE SCENE: ${x}` : x) });
+    }
+    else if (three && (w.state === 'open' || w.state === 'stale')) {
+        out.push({ kind: 'world', unread: true, line: `the world was never read on these files (${w.says}): run \`npx @funpixel/tools check --world\` (boxes, grounding, life) before handing back` });
+    }
+    return [...new Map(out.map((h) => [h.line, h])).values()].slice(0, 8);
+}
+export function artHolds(s) {
+    const out = [];
+    const outs = [...new Set(s.cards.flatMap((c) => c.out ?? []))].filter((o) => ART_OUT.test(o));
+    const standins = [...new Set(s.cards.flatMap((c) => c.standins ?? []))].filter((x) => CODE_STANDIN.test(x));
+    for (const o of outs)
+        out.push({ kind: 'art', line: `generated art listed as out: "${short(o, 100)}" — retry it, switch provider or tier, make 2D cut-outs from the locked sheets, or ask the person (\`npx @funpixel/tools progress ask "<what failed>: retry / 2D cut-outs from the locked sheets / pause" --kind scope --options retry,cutouts,pause\`)` });
+    for (const x of standins)
+        out.push({ kind: 'art', line: `code stand-in where generated art belongs: "${short(x, 100)}"` });
+    return out;
+}
+export function ownerRelease(root, s, stage) {
+    const ans = [...s.questions].reverse().find((q) => q.answer?.by === 'owner' && ACCEPT_PICK.test(q.answer.pick));
+    if (ans)
+        return `the owner answered ${ans.id}: ${ans.answer.pick}`;
+    const p = readPipeline(root);
+    const note = (p?.notes ?? []).find((n) => n.by === 'owner' && ACCEPT_WORDS.test(n.text));
+    if (note)
+        return `the owner's note ${note.id}: "${short(note.text, 100)}"`;
+    const v = [...(p?.verdicts ?? [])].reverse().find((x) => x.stage === stage);
+    if (v?.says === 'accept')
+        return `the owner accepted ${stage}${v.words ? `: "${short(v.words, 80)}"` : ''}`;
+    return null;
+}
+export function handBackHolds(root, fp, s = readProgress(root)) {
+    const stage = stageOf(root, fp, s);
+    const playable = (stage !== null && (PLAYABLE.has(stage) || stage === 'done')) || builtAndPlays(root, fp);
+    const holds = [...(playable ? worldHolds(root, fp) : []), ...artHolds(s)];
+    if (!holds.length)
+        return { holds, released: null, waiting: null, stage };
+    const released = ownerRelease(root, s, stage);
+    const ask = s.open.find((q) => q.kind === 'scope' && ABOUT_ART.test(q.text));
+    return { holds, released, waiting: ask ? `${ask.id} (scope) waits for the person: "${short(ask.text, 100)}"` : null, stage };
+}
+export const holding = (h) => (h.released || h.waiting ? [] : h.holds);
+export function holdMessage(h) {
+    return `NOT DONE — the hand-back holds on:\n${h.map((x) => `- ${x.line}`).join('\n')}\nFix them (generated art in the world, \`npx @funpixel/tools check --world\` passing), or ask the person (\`npx @funpixel/tools progress ask … --kind scope\`). Only the owner accepts stand-ins.`;
+}

package/dist/progress/notify.js

@@ -0,0 +1,25 @@
+export function notifyRequest(target, n) {
+    const text = `${n.title}\n${n.body}${n.url ? `\n${n.url}` : ''}`;
+    if (/hooks\.slack\.com|discord(app)?\.com\/api\/webhooks/.test(target)) {
+        const key = /discord/.test(target) ? 'content' : 'text';
+        return { url: target, init: { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ [key]: text }) } };
+    }
+    const headers = { 'Content-Type': 'text/plain; charset=utf-8', Title: asciiHeader(n.title), Tags: n.kind === 'done' ? 'white_check_mark' : 'raising_hand', Priority: n.kind === 'needs-you' ? 'high' : 'default' };
+    if (n.url)
+        headers.Click = n.url;
+    return { url: target, init: { method: 'POST', headers, body: `${n.body}` } };
+}
+const asciiHeader = (s) => s.replace(/[‘’]/g, "'").replace(/[“”]/g, '"').replace(/[—–]/g, '-').replace(/[^\x20-\x7e]/g, '').slice(0, 200);
+export async function notify(n, env = process.env, timeoutMs = 4000) {
+    const target = env.FUNPIXEL_NOTIFY_URL?.trim();
+    if (!target || !/^https?:\/\//.test(target))
+        return false;
+    const { url, init } = notifyRequest(target, n);
+    try {
+        const r = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+        return r.ok;
+    }
+    catch {
+        return false;
+    }
+}