@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/hook.js

@@ -0,0 +1,171 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { EXIT } from "./verify.js";
+import { withPage } from "./look.js";
+import { evalJson, load } from "../look/look.js";
+import { decodePng } from "../look/png.js";
+import { LIFE } from "../look/life.js";
+import { changedTiles, checkpointsFor, counted, flatShare, frameSimilarity, HOOK, hookFindings, recordHook } from "../look/hook.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { playerOf } from "../look/player.js";
+import { stateHash } from "../walk/judge.js";
+import { touchSession } from "../verify/browser.js";
+import { FRONT_DOOR_ARGS } from "../look/look.js";
+import { ui } from "../ui.js";
+import { CLOCK_JS, judgeFirstMinute, MARK_PLAY_JS, parseClock, READ_CLOCK_JS } from "../frame/clock.js";
+import { firstMinuteOf, plannedHook } from "../frame/genre.js";
+import { idleLine } from "../frame/idle.js";
+import { designDoc } from "../gdd/doc.js";
+import { judgeOpening, openingPlan, OPENING_JS, parseOpening, READ_OPENING_JS, stagedBeats } from "../frame/opening.js";
+const STUCK_SCREEN = /title|menu|card|intro|scene|pack|map|brief|tutorial|story/i;
+const TAP_EVERY_S = 3;
+const sample = (page, manifest) => evalJson(page, 'life', {
+    player: playerOf(manifest).pattern, ms: HOOK.sampleMs, every_ms: LIFE.everyMs, max_nodes: LIFE.maxNodes,
+});
+const NOTHING_SAID = { screen: null, placeholders: [], objective: null, goalDistance: null };
+async function stateOf(page) {
+    try {
+        const raw = await page.evaluate(`(() => { try { const s = typeof window.__FPX_STATE__ === 'function' ? window.__FPX_STATE__() : null; if (!s || typeof s !== 'object') return null;
+      const screen = [s.screen, s.phase, s.view, s.mode].find((x) => typeof x === 'string') ?? null;
+      const p = s.art && Array.isArray(s.art.placeholders) ? s.art.placeholders : [];
+      const o = s.objective; const objective = typeof o === 'string' ? o : o && typeof o === 'object' ? [o.title, o.text, o.name, o.label].find((x) => typeof x === 'string') ?? null : null;
+      const d = typeof s.goalDistance === 'number' ? s.goalDistance : o && typeof o === 'object' && typeof o.distance === 'number' ? o.distance : null;
+      return JSON.stringify({ screen, placeholders: p.map((x) => typeof x === 'string' ? x : (x && (x.name || x.id)) || '').filter(Boolean).slice(0, 40), objective: objective ? String(objective).slice(0, 120) : null, goalDistance: Number.isFinite(d) ? d : null }); } catch { return null; } })()`);
+        return typeof raw === 'string' ? { ...NOTHING_SAID, ...JSON.parse(raw) } : NOTHING_SAID;
+    }
+    catch {
+        return NOTHING_SAID;
+    }
+}
+async function fullStateHash(page) {
+    try {
+        const raw = await page.evaluate('(() => { try { const s = window.__FPX_STATE__ && window.__FPX_STATE__(); return s ? JSON.stringify(s) : null; } catch (e) { return null; } })()');
+        return typeof raw === 'string' ? stateHash(JSON.parse(raw)) : '';
+    }
+    catch {
+        return '';
+    }
+}
+const press = (page, verb) => page.evaluate(`(async () => { const v = window.__FPX_VERBS__ || {}; if (typeof v[${JSON.stringify(verb)}] === 'function') { try { await v[${JSON.stringify(verb)}](); } catch {} } })()`).catch(() => { });
+export async function hook(opts, io = console) {
+    const u = ui(io, 'hook');
+    const marks = checkpointsFor(opts.seconds);
+    const r = await withPage(u, opts, async (page, t) => {
+        const dir = t.dir ? join(t.dir, '.funtools', 'hook') : null;
+        if (dir)
+            await mkdir(dir, { recursive: true });
+        const shoot = async (name) => {
+            try {
+                const png = await page.screenshot({ type: 'png' });
+                const file = dir ? join('.funtools', 'hook', `${opts.viewport}-${name}.png`) : null;
+                if (dir && t.dir)
+                    await writeFile(join(t.dir, file), png);
+                return { img: decodePng(png), file };
+            }
+            catch {
+                return { img: null, file: null };
+            }
+        };
+        await page.addInitScript(CLOCK_JS).catch(() => { });
+        await page.addInitScript(OPENING_JS).catch(() => { });
+        await load(page, t.url, hookMapOf(t.manifest));
+        await page.evaluate(CLOCK_JS).catch(() => { });
+        await page.evaluate(OPENING_JS).catch(() => { });
+        await page.waitForTimeout(600);
+        const titleShot = await shoot('title');
+        const title = { frame: titleShot.file, flat: titleShot.img ? flatShare(titleShot.img) : null, life: await sample(page, t.manifest) };
+        await page.evaluate(MARK_PLAY_JS).catch(() => { });
+        const fd = opts.click ? await evalJson(page, 'front_door', { selector: opts.click, ...FRONT_DOOR_ARGS }) : null;
+        const front_door = fd ? { found: !!fd.found, changed: typeof fd.changed === 'boolean' ? fd.changed : null, name: String(fd.name ?? '') } : null;
+        const started = Date.now();
+        const checkpoints = [];
+        let previous = null;
+        const placeholders = new Set();
+        const frames = new Map();
+        let turn = 0, tappedAt = 0, lastHash = '', inputs = 0;
+        const touch = opts.viewport === 'phone' ? await touchSession(page).catch(() => null) : null;
+        const tapMiddle = async () => {
+            const vp = page.viewportSize() ?? { width: 800, height: 400 };
+            const p = { x: Math.round(vp.width / 2), y: Math.round(vp.height / 2) };
+            try {
+                if (touch) {
+                    await touch.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: [p] });
+                    await touch.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] });
+                }
+                else
+                    await page.mouse.click(p.x, p.y);
+            }
+            catch { }
+        };
+        for (const at of marks) {
+            while (Date.now() - started < at * 1000) {
+                if (opts.verbs.length) {
+                    await press(page, opts.verbs[turn++ % opts.verbs.length]);
+                    inputs++;
+                }
+                else if (!opts.idle && Date.now() - tappedAt >= TAP_EVERY_S * 1000) {
+                    tappedAt = Date.now();
+                    await tapMiddle();
+                    inputs++;
+                }
+                await page.waitForTimeout(Math.min(1000, Math.max(50, at * 1000 - (Date.now() - started))));
+            }
+            const honest = await evalJson(page, 'frame_honesty', {});
+            const shot = await shoot(`t${String(at).padStart(3, '0')}`);
+            const life = await sample(page, t.manifest);
+            const state = await stateOf(page);
+            for (const p of state.placeholders)
+                placeholders.add(p);
+            const hash = await fullStateHash(page);
+            const stalled = !!hash && hash === lastHash && inputs > 0 && (opts.verbs.length > 0 || (!opts.idle && !!state.screen && STUCK_SCREEN.test(state.screen)));
+            lastHash = hash;
+            inputs = 0;
+            checkpoints.push({
+                at, frame: shot.file, flat: shot.img ? flatShare(shot.img) : null,
+                changed: shot.img && previous ? changedTiles(previous, shot.img) : null, life, screen: state.screen,
+                loading: honest ? !!honest.loading : null, ...(stalled ? { stalled } : {}),
+                ...(state.objective ? { objective: state.objective } : {}), ...(state.goalDistance !== null ? { goalDistance: state.goalDistance } : {}),
+            });
+            if (shot.img) {
+                previous = shot.img;
+                frames.set(at, { img: shot.img, file: shot.file });
+            }
+            io.error(`  hook: read ${at} s of ${marks[marks.length - 1]} s`);
+        }
+        const clock = parseClock(await page.evaluate(READ_CLOCK_JS).catch(() => null));
+        const openingRead = parseOpening(await page.evaluate(READ_OPENING_JS).catch(() => null));
+        const fm = firstMinuteOf(t.manifest);
+        const first_minute = judgeFirstMinute(clock, { card: fm.story ? `${fm.card}, a story line` : fm.card, controlS: fm.controlS, successS: fm.successS, hookS: fm.hookS, playing: opts.verbs.length > 0, windowEndS: marks[marks.length - 1], planned: t.dir ? plannedHook(designDoc(t.dir)?.text ?? '') : null });
+        const playable = checkpoints.filter((c) => counted(c) && frames.has(c.at));
+        const pick = playable.find((c) => c.at >= HOOK.playFrameAtS) ?? playable[playable.length - 1];
+        const title_vs_play = titleShot.img && pick ? { similarity: frameSimilarity(titleShot.img, frames.get(pick.at).img), play_at: pick.at, play_frame: frames.get(pick.at).file } : null;
+        const gddText = t.dir ? designDoc(t.dir)?.text ?? '' : '';
+        const oplan = gddText ? openingPlan(gddText) : null;
+        const playS = first_minute.play_pressed_s;
+        const controlAtS = first_minute.control_s !== null ? Math.round((first_minute.control_s - (playS ?? 0)) * 10) / 10 : null;
+        const openingFindings = judgeOpening(openingRead, oplan, { controlS: fm.controlS, card: fm.story ? `${fm.card} (story)` : fm.card, controlAtS, playMs: playS !== null ? playS * 1000 : null });
+        const opening_plan = { planned: oplan, read: openingRead ? { objective: openingRead.objective, distance: openingRead.distance, shots: openingRead.shots, beats: stagedBeats(openingRead, playS !== null ? playS * 1000 : null), camera: openingRead.camera, marks: openingRead.marks ?? [] } : null, control_after_play_s: controlAtS };
+        const partial = { viewport: opts.viewport, seconds: marks[marks.length - 1], title, front_door, checkpoints, placeholders: [...placeholders], first_minute, title_vs_play, opening: opening_plan };
+        const opening = [...hookFindings(partial), ...openingFindings], clocked = first_minute.findings;
+        const findings = clocked.some((x) => x.level === 'warn') ? opening.filter((x) => !/^the hook holds/.test(x.text)) : opening;
+        const record = { ...partial, findings: [...clocked, ...findings] };
+        if (t.dir)
+            await recordHook(t.dir, record);
+        return record;
+    });
+    if (typeof r === 'number')
+        return r;
+    const observed = r.checkpoints.some((c) => c.frame !== null || c.flat !== null || (c.life && c.life.engine !== 'none'));
+    if (opts.json) {
+        io.log(JSON.stringify(r, null, 2));
+        return observed ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`The hook · title and the first ${Math.round(r.seconds / 60 * 10) / 10} min after Play · ${opts.viewport}`);
+    for (const f of r.findings)
+        u.item(f.level, f.text, f.hint);
+    if (!/^https?:/.test(opts.target ?? '.'))
+        u.item('note', idleLine(opts.target ?? '.'));
+    const warned = r.findings.filter((f) => f.level === 'warn').length;
+    u.summary(observed ? (warned ? 'warn' : 'pass') : 'not_observed', observed ? `${warned ? `the hook: ${warned} warning(s)` : 'the hook holds on these readings'} — frames in .funtools/hook/; a mirror, never a gate` : 'nothing to read: no frame and no scene graph');
+    return observed ? EXIT.pass : EXIT.not_observed;
+}

package/dist/commands/init.js

@@ -0,0 +1,234 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sha, writeManaged } from "../managed.js";
+import { ui } from "../ui.js";
+import { apiOptions, ApiError } from "../api/http.js";
+import { mintDraft } from "../publish/funpixel.js";
+import { guidanceHash } from "../guidance.js";
+import { SCAFFOLD_PALETTE } from "../smoke/palette.js";
+import { pickStarter, RECIPE, seedGdd, templateOf } from "../init/starter.js";
+import { assetManifest, fillGdd } from "../init/starters.js";
+import { pickTier, SWITCHES } from "../production/tier.js";
+import { adoptExisting, defaultPipeline, TIER_NAME, ownerPlan, PIPELINE_FILE, planSig } from "../pipeline/pipeline.js";
+import { makingLog } from "../production/mirror.js";
+import { bareFiles, demoLeftOut } from "../init/bare.js";
+import { gitInit } from "../init/git.js";
+import { startFlow } from "../flow/flow.js";
+import { appendEntry, nextCard, nextQuestion, readProgress } from "../progress/progress.js";
+export const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
+const ENGINES = {
+    pixi: { label: 'Pixi 8', framework: 'pixi', dimension: '2d', deps: { 'pixi.js': '^8.22.0' }, layers: ['pixi'] },
+    three: { label: 'Three.js', framework: 'threejs', dimension: '3d', deps: { three: '^0.186.0' }, layers: ['three'] },
+    'three-world': {
+        label: 'Three.js 3D world starter', framework: 'threejs', dimension: '3d', layers: ['three', 'three-world'],
+        deps: { three: '^0.186.0', '@fontsource/lilita-one': '^5.2.0', '@fontsource/nunito': '^5.2.0' },
+        test: 'node --import ./test/resolve.mjs --test test/*.test.ts', fonts: ['Lilita One', 'Nunito'],
+    },
+};
+const CHECKS = {
+    round: [
+        { mechanic: 'right arrow moves the player right', verb: 'moveRight', key: 'ArrowRight', field: 'x', expect: 'increases', subject: 'player', times: 2 },
+        { mechanic: 'left arrow moves the player left', verb: 'moveLeft', key: 'ArrowLeft', field: 'x', expect: 'decreases', subject: 'player', times: 2 },
+        { mechanic: 'stepping onto a gem scores', verb: 'moveRight', field: 'score', expect: 'increases', times: 2 },
+        { mechanic: 'a sharp player collecting every gem wins the round', verb: 'winRound', field: 'wins', expect: 'increases', times: 1 },
+        { mechanic: 'a spike or the clock ends the round lost', verb: 'loseRound', field: 'losses', expect: 'increases', times: 1 },
+    ],
+    'three-world': [
+        { mechanic: 'right arrow runs the hero right', verb: 'moveRight', key: 'ArrowRight', field: 'x', expect: 'increases', times: 2 },
+        { mechanic: 'left arrow runs the hero left', verb: 'moveLeft', key: 'ArrowLeft', field: 'x', expect: 'decreases', times: 2 },
+        { mechanic: 'up arrow runs the hero away from the camera', verb: 'moveAway', key: 'ArrowUp', field: 'z', expect: 'decreases', times: 2 },
+        { mechanic: 'space jumps', verb: 'jump', key: 'Space', field: 'jumps', expect: 'increases', times: 1 },
+        { mechanic: 'reaching a light collects it', verb: 'collect', field: 'score', expect: 'increases', times: 1 },
+        { mechanic: 'a sharp player collecting every light wins the round', verb: 'winRound', field: 'wins', expect: 'increases', times: 1 },
+        { mechanic: 'a flare or the clock ends the round lost', verb: 'loseRound', field: 'losses', expect: 'increases', times: 1 },
+    ],
+};
+const SDK_VERSION = '0.7.0';
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'game';
+export async function renderTree(from, vars, rel = '', out = {}) {
+    for (const e of await readdir(join(from, rel), { withFileTypes: true })) {
+        const child = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory())
+            await renderTree(from, vars, child, out);
+        else
+            out[child] = (await readFile(join(from, child), 'utf8')).replace(/\{\{(\w+)\}\}/g, (m, k) => vars[k] ?? m);
+    }
+    return out;
+}
+export async function scaffoldFiles(framework, name, orientation = 'landscape') {
+    const engine = ENGINES[framework];
+    if (!engine)
+        throw new Error(`unknown framework: ${framework}`);
+    const vars = { name, engine: engine.label, orientation };
+    let files = await renderTree(join(TEMPLATES, 'common'), vars);
+    for (const layer of engine.layers)
+        files = { ...files, ...(await renderTree(join(TEMPLATES, layer), vars)) };
+    return files;
+}
+async function mint(name, u) {
+    const api = apiOptions({ retries: 1 });
+    if (!api) {
+        u.item('note', 'no API key — the game id is minted at the first publish');
+        return null;
+    }
+    try {
+        const id = await mintDraft(api, name);
+        u.item('pass', `game id ${id}`, 'a draft you own on Funpixel; publish updates it in place');
+        return id;
+    }
+    catch (e) {
+        const why = e instanceof ApiError ? `${e.message} (${e.code})` : e instanceof Error ? e.message : String(e);
+        u.item('warn', `could not mint the game id: ${why}`, 'the first publish mints it');
+        return null;
+    }
+}
+export const UI_BLOCK = {
+    framework: '', material: '', never: '',
+    type: { display: { family: '', case: '', mood: '' }, body: { family: '', case: '', mood: '' } },
+    icons: { stroke: null, corner: null, fill: '', motif: '' },
+    roles: {}, motion: '', art: {}, targets: {},
+};
+export async function init(opts, io = console) {
+    const u = ui(io, 'init');
+    const idea = opts.idea?.replace(/\s+/g, ' ').trim();
+    if (opts.idea !== undefined && !idea) {
+        u.error('the idea is empty', 'funtools init --idea "a one-line game idea"');
+        return 3;
+    }
+    const pick = idea ? pickStarter(idea) : null;
+    const dir = resolve(opts.target ?? pick?.folder ?? '.');
+    const framework = opts.framework ?? (pick?.engine === 'three' ? 'three-world' : pick?.engine) ?? 'pixi';
+    const engine = ENGINES[framework];
+    if (!engine) {
+        u.error(`unknown framework: ${opts.framework}`, 'use --framework pixi, three or three-world');
+        return 3;
+    }
+    if (existsSync(join(dir, 'package.json')) || existsSync(join(dir, 'funpixel.json'))) {
+        u.error(`${dir} already has a package.json or funpixel.json`, 'init writes new games only; `funtools doctor --add-hooks` adapts an existing one');
+        return 3;
+    }
+    const name = opts.name ?? (pick ? pick.title : basename(dir));
+    const planText = (() => { try {
+        return readFileSync(join(dir, 'design', 'plan.md'), 'utf8');
+    }
+    catch {
+        return '';
+    } })();
+    const fromPlan = !idea && planText ? pickTier(planText.slice(0, 60_000), { three: engine.dimension === '3d' }) : null;
+    const tierFromPlan = !!fromPlan && fromPlan.tier !== 'small';
+    const tier = fromPlan && tierFromPlan ? { ...fromPlan, because: [...fromPlan.because, 'from the owner\'s design/plan.md'] } : pickTier(idea ?? '', { three: engine.dimension === '3d' });
+    const full = await scaffoldFiles(framework, name, pick?.orientation ?? 'landscape');
+    const files = opts.bare ? bareFiles(full, framework) : full;
+    const managed = { framework, name, files: {} };
+    for (const [rel, text] of Object.entries(files)) {
+        await mkdir(dirname(join(dir, rel)), { recursive: true });
+        await writeFile(join(dir, rel), text);
+        managed.files[rel] = sha(text);
+    }
+    await writeManaged(dir, managed);
+    const pkg = {
+        name: slug(name),
+        private: true,
+        type: 'module',
+        scripts: { dev: 'vite --host localhost', build: 'node src/art/files.mjs && tsc --noEmit && vite build', check: 'tsc --noEmit', test: engine.test ?? 'node --test test/*.test.ts' },
+        dependencies: { ...engine.deps, preact: '^10.19.0', '@funpixel/sdk': SDK_VERSION },
+        devDependencies: { vite: '^5.4.0', typescript: '5.9.3' },
+    };
+    await writeFile(join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+    const gameId = opts.offline ? null : await mint(name, u);
+    const manifest = {
+        name,
+        ...(gameId ? { game_id: gameId } : {}),
+        guidance_hash: guidanceHash(join(TEMPLATES, 'common')),
+        splash: opts.bare ? 'none' : 'own',
+        metadata: {
+            genre: pick?.card ?? 'arcade', tagline: pick ? pick.line.slice(0, 200) : '', artStyle: '', dimension: engine.dimension, mode: pick?.multiplayer ? 'multiplayer' : 'single',
+            orientation: pick?.orientation ?? 'landscape', framework: engine.framework,
+            palette: { ...SCAFFOLD_PALETTE },
+            fonts: opts.bare ? [] : engine.fonts ?? [],
+        },
+        checks: opts.bare ? [] : CHECKS[framework] ?? CHECKS.round,
+        production: { tier: tier.tier, because: tier.because },
+        ...(opts.flow && Object.keys(opts.flow).length ? { flow: opts.flow } : {}),
+    };
+    await writeFile(join(dir, 'funpixel.json'), JSON.stringify(manifest, null, 2) + '\n');
+    if (!existsSync(join(dir, 'assets', 'style.json'))) {
+        await mkdir(join(dir, 'assets'), { recursive: true });
+        await writeFile(join(dir, 'assets', 'style.json'), JSON.stringify({ ui: UI_BLOCK }, null, 2) + '\n');
+    }
+    const starter = framework === 'three-world' ? 'world3d' : pick ? pick.card : null;
+    if (starter && !existsSync(join(dir, 'assets', 'assets.json')))
+        await writeFile(join(dir, 'assets', 'assets.json'), assetManifest(starter, idea));
+    await mkdir(join(dir, '.funtools'), { recursive: true });
+    await writeFile(join(dir, '.funtools', 'complete-game'), 'funtools init\n');
+    await mkdir(join(dir, 'design'), { recursive: true });
+    const planned = [];
+    if (!existsSync(join(dir, PIPELINE_FILE))) {
+        const pipe = defaultPipeline(tier.tier, new Date(), 'funtools init', { world: engine.dimension === '3d', opening: true });
+        planned.push(...adoptExisting(pipe, ownerPlan(dir), new Date(), planSig(dir)));
+        await writeFile(join(dir, PIPELINE_FILE), JSON.stringify(pipe, null, 2) + '\n');
+    }
+    if (pick) {
+        const date = new Date().toISOString().slice(0, 10);
+        await mkdir(join(dir, 'design'), { recursive: true });
+        const gdd = seedGdd(pick, name, templateOf(files['.agents/skills/funpixel-gdd/references/gdd-template.md']), date, tier.tier);
+        const sw = SWITCHES[tier.tier];
+        const line = `**Production:** ${TIER_NAME[tier.tier]} (from the line: ${tier.because.join(', ')}; yours to change: funpixel.json \`production.tier\`, now ${tier.tier}) · direct: ${sw.direct} · keep consistent: ${sw.consistent} · verify: ${sw.verify} (\`.agents/skills/funpixel-gdd/references/production-tiers.md\`)`;
+        const seeded = (starter ? fillGdd(gdd, starter) : gdd).replace('\n\n## Where we are', `\n${line}\n\n## Where we are`);
+        if (!existsSync(join(dir, 'design', 'GDD.md')))
+            await writeFile(join(dir, 'design', 'GDD.md'), seeded);
+        if (tier.tier === 'deep' && !existsSync(join(dir, 'design', 'MAKING.md')))
+            await writeFile(join(dir, 'design', 'MAKING.md'), makingLog(name, date));
+        await writeFile(join(dir, '.funtools', 'idea.json'), JSON.stringify({ at: new Date().toISOString(), ...pick, framework: opts.framework ?? null, name: opts.name ?? null }, null, 2) + '\n');
+    }
+    startFlow(dir, { ...(idea ? { idea } : {}) });
+    let asked = null;
+    let decidedRecipe = null;
+    if (pick?.unsure?.weak) {
+        decidedRecipe = `genre recipe: none — ${pick.unsure.why}; the GDD's own design (not ${pick.unsure.candidates.join(' or ')}). A recipe can still be picked later in design/GDD.md`;
+        appendEntry(dir, { type: 'card', n: nextCard(readProgress(dir)), at: new Date().toISOString(), kind: 'decided', stage: 'pitch', line: 'Genre recipe: none, decided from the line (not asked)', observed: false, why_not: 'a decision, not a frame', decisions: [decidedRecipe] });
+    }
+    else if (pick?.unsure) {
+        asked = { type: 'ask', id: nextQuestion(readProgress(dir)), at: new Date().toISOString(), kind: 'scope', stage: 'pitch', topic: 'genre-recipe',
+            text: `Which genre recipe is closest to "${pick.line.slice(0, 160)}"? The line was not enough to pick one: ${pick.unsure.why}. "none" keeps the scaffold's own round and the GDD's own design.`,
+            options: [...pick.unsure.candidates, 'none'] };
+        appendEntry(dir, asked);
+    }
+    const repo = gitInit(dir, name, { skip: opts.noGit });
+    u.summary('pass', `created ${name} (${engine.label}) in ${dir}`);
+    if (pick) {
+        const q = (w) => w.map((x) => `"${x}"`).join(', ');
+        u.heading('from your line (every pick is yours to change)');
+        u.item('note', `engine: ${engine.label}${opts.framework ? ' (--framework)' : ` — ${pick.engineBecause}`}`, opts.framework ? undefined : framework === 'three-world' ? 'camera rig, lit world, controller and phone stick to build on (skill funpixel-game-spine, references/three.md); the small fixed-camera round: --framework three' : 'in 3D instead: --framework three-world on a fresh folder (three for the small fixed-camera round)');
+        if (decidedRecipe)
+            u.item('note', decidedRecipe, 'decided, not asked: a weak match is no question for the owner (it is on the page as a decision)');
+        else if (asked)
+            u.item('warn', `genre recipe: not sure from the line — ${pick.unsure.why}; asked the owner (${asked.id}, scope: ${asked.options.join(' / ')})`, 'the answer comes back in the chat (`funtools progress wait`); read its recipe once they answer');
+        else
+            u.item('note', pick.card === 'arcade' ? `genre recipe: none picked${pick.because.length ? ` (arcade words: ${q(pick.because)})` : ' (no genre word in the line)'}; the scaffold's arcade round` : `genre recipe: ${pick.card} — from ${q(pick.because)}`, pick.card === 'arcade' ? 'skill funpixel-gdd lists every recipe' : RECIPE[pick.card]);
+        if (pick.also)
+            u.item('note', `next closest: ${pick.also.card} (${q(pick.also.because)})`, RECIPE[pick.also.card]);
+        u.item('note', `held ${pick.orientation} on a phone — ${pick.orientationBecause}`, 'funpixel.json metadata.orientation');
+        u.item('note', `${opts.name ? 'title' : pick.titleFromLine ? 'title from the line' : 'working title (a placeholder from the line\'s first noun)'}: ${name}`, opts.name || pick.titleFromLine ? undefined : 'the real name comes with the pitch: rename it in funpixel.json and design/GDD.md');
+        if (pick.multiplayer)
+            u.item('note', `multiplayer: the line says ${q(pick.multiplayerBecause)}`, 'funpixel.json metadata.mode; rooms on the relay, host-owned state: skill funpixel-game-spine (funtools dev --relay plays it locally)');
+        u.item('pass', `design/GDD.md seeded at a ${TIER_NAME[tier.tier]} game's size: the core the creator owns (invention, studio pitch, core loop, the hook) and what a ${tier.tier} game needs; the pitch is your line; the ${starter === 'world3d' ? '3D world' : pick.card} starter's defaults are written in, marked "(starter default)"`, 'the rest of the template stays on the shelf until the game calls for it (skill funpixel-gdd)');
+        u.item('pass', 'assets/assets.json: the starter\'s cast, places and UI to generate (reference sheets first); its subjects are the starter\'s placeholders, written for its demo round, not your line: rewrite each for this game before generating', 'npx @funpixel/tools assets gen --dry-run (it names every subject still left as the starter wrote it)');
+        const sw = SWITCHES[tier.tier];
+        u.item('note', `size: ${TIER_NAME[tier.tier]} — ${tier.because.join(', ')}`, `turns up direct (${sw.direct}), keep consistent (${sw.consistent}) and verify (${sw.verify}); a dial, not a ceiling: .agents/skills/funpixel-gdd/references/production-tiers.md${tier.tier === 'deep' ? '; design/MAKING.md seeded' : ''}`);
+    }
+    u.item('pass', `${PIPELINE_FILE}: a ${TIER_NAME[tier.tier]} game's stages, each gate named evidence${tierFromPlan ? ' (tier from the owner\'s plan)' : ''}`, 'npx @funpixel/tools flow: the one next step and the evidence that closes it');
+    if (opts.bare)
+        u.item('pass', `--bare: the spine only (hooks, safe band, platform, save, sound, store, look, probes); the demo round's ${demoLeftOut(full).length} files left out`, 'src/game.ts opens the engine and wires the hooks; build the game there');
+    else if (planText)
+        u.item('note', `the owner's plan is here: the starter's demo round (${demoLeftOut(full).length} files: rules, session, world, HUD, screens, bot) is an example to replace, not the game`, 'on a fresh folder, `funtools init --bare` writes the spine only (keep design/ and run it there)');
+    u.item(repo.state === 'committed' ? 'pass' : 'note', repo.says, repo.next);
+    if (planned.length)
+        u.item('pass', `the owner's plan answers ${planned.join(', ')}: those stages start done (never invented twice)`, 'design/plan.md is the design; the GDD skill grows it, it does not replace it');
+    u.heading('next');
+    for (const step of [`cd ${dir}`, 'npm install', 'npx @funpixel/tools flow     (where the run is and the one next step: the plan, the owner\'s agreement, then round after round)', 'npx @funpixel/tools check    (or: npm run build, then npx @funpixel/tools verify)'])
+        u.line(step);
+    return 0;
+}

package/dist/commands/inspect.js

@@ -0,0 +1,161 @@
+import { EXIT } from "./verify.js";
+import { launch, lookPage, viewportOptions, viewportUrl } from "../verify/browser.js";
+import { drive } from "../look/look.js";
+import { startDevServer } from "../inspect/devserver.js";
+import { describeError, describeHit, givenNames, mergeErrors, parseAt, sourceOf, sourceRefFromStack, treeLines, } from "../inspect/describe.js";
+import { ui } from "../ui.js";
+const READY_MS = 8000;
+async function waitForAgent(page) {
+    const t0 = Date.now();
+    let last = { has: false, agent: false, ready: false, engine: null };
+    while (Date.now() - t0 < READY_MS) {
+        last = await page.evaluate(() => {
+            const i = window.__funpixelInspector;
+            return { has: !!i, agent: !!i?.agent, ready: !!i?.agent?.ready?.(), engine: i?.agent?.engine ?? null };
+        }).catch(() => last);
+        if (last.ready)
+            break;
+        await page.waitForTimeout(200);
+    }
+    const missing = !last.has
+        ? 'the page has no inspector (a built dist carries none: inspect starts the dev server; with --url, point it at `funtools dev`)'
+        : !last.agent
+            ? 'this inspector build has no agent API — rebuild it: npm run build:all in libs/funpixel-inspector'
+            : null;
+    return { engine: last.engine, ready: last.ready, missing };
+}
+export async function inspect(opts, io = console) {
+    const u = ui(io, 'inspect');
+    const size = viewportOptions(opts.viewport, opts.orientation).viewport;
+    const at = opts.at ? parseAt(opts.at, size) : null;
+    if (opts.at && !at) {
+        u.error(`--at ${opts.at} is not a point on the ${size.width}x${size.height} page`, 'x,y in CSS pixels, or percents like 50%,80%');
+        return EXIT.error;
+    }
+    let server = null;
+    let browser;
+    const pageErrors = [];
+    let answer;
+    try {
+        let base = opts.url;
+        if (!base) {
+            const s = await startDevServer(opts.target ?? '.');
+            if (typeof s === 'string') {
+                if (opts.json)
+                    io.log(JSON.stringify({ observed: false, reason: s }, null, 2));
+                else
+                    u.summary('not_observed', s);
+                return EXIT.not_observed;
+            }
+            server = s;
+            base = s.url;
+        }
+        browser = (await launch()).browser;
+        const page = await lookPage(browser, opts.viewport, opts.orientation ?? '');
+        page.on('pageerror', (e) => pageErrors.push({ type: 'error', message: String(e.message ?? e), stack: e.stack }));
+        const url = viewportUrl(base, opts.viewport);
+        await page.goto(url, { waitUntil: 'load', timeout: 60_000 });
+        const agent = await waitForAgent(page);
+        let view = null;
+        if (opts.view || opts.click || opts.verbs.length) {
+            const d = await drive(page, { view: opts.view, verbs: opts.verbs, holdMs: opts.settleMs, freeze: false, click: opts.click });
+            if (opts.view)
+                view = { name: opts.view, entered: d.view?.entered === true, error: d.view?.entered ? undefined : d.view?.error || 'the page refused' };
+        }
+        else
+            await page.waitForTimeout(opts.settleMs);
+        const asked = await page.evaluate(async (q) => {
+            const a = window.__funpixelInspector?.agent;
+            let state = null;
+            try {
+                state = typeof window.__FPX_STATE__ === 'function' ? window.__FPX_STATE__() : null;
+            }
+            catch { }
+            if (!a)
+                return { state, at: null, named: null, tree: null, errors: [] };
+            return {
+                state,
+                at: q.at ? await a.at(q.at.x, q.at.y, 6) : null,
+                named: q.name ? await a.named(q.name, 10) : null,
+                tree: a.tree(),
+                errors: await a.errors(),
+            };
+        }, { at, name: opts.name ?? null });
+        const late = [];
+        for (const e of pageErrors) {
+            const ref = sourceRefFromStack(e.stack);
+            const r = ref && agent.missing === null ? await page.evaluate((x) => window.__funpixelInspector.agent.resolve(x), ref).catch(() => null) : null;
+            late.push(r ? { ...e, originalSource: r.source, originalLine: r.line, originalSourceLine: r.sourceLine } : e);
+        }
+        answer = {
+            url: base, viewport: opts.viewport, engine: agent.engine, ready: agent.ready, view,
+            at: at ? { ...at, hits: (asked.at ?? []) } : null,
+            named: opts.name ? { query: opts.name, hits: (asked.named ?? []) } : null,
+            tree: asked.tree,
+            names: givenNames(asked.tree),
+            errors: mergeErrors(asked.errors, late),
+            state: asked.state,
+            missing: agent.missing,
+        };
+    }
+    catch (e) {
+        u.error(e instanceof Error ? e.message : String(e));
+        return EXIT.error;
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        await server?.close().catch(() => { });
+    }
+    return report(answer, opts, io);
+}
+function report(a, opts, io) {
+    const u = ui(io, 'inspect');
+    const observed = a.missing === null && (!a.at || a.at.hits.length > 0) && (!a.named || a.named.hits.length > 0) && (!a.view || a.view.entered);
+    if (opts.json) {
+        const hits = (hs) => hs.map((h) => ({ made_at: sourceOf(h.metadata), ...h }));
+        const { tree, ...rest } = a;
+        io.log(JSON.stringify({
+            observed, ...rest,
+            at: a.at && { ...a.at, hits: hits(a.at.hits) },
+            named: a.named && { ...a.named, hits: hits(a.named.hits) },
+            errors: a.errors.map((e) => ({ at: sourceOf({ originalSource: e.originalSource, originalLine: e.originalLine, sourceFile: e.filename, sourceLine: e.line }), ...e })),
+            tree: opts.tree ? tree : undefined,
+        }, null, 2));
+        return observed ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`inspect · ${a.viewport}${a.engine ? ` · ${a.engine}` : ''}${a.view ? ` · view ${a.view.name}` : ''}`);
+    if (a.missing)
+        u.item('not_observed', 'inspector', a.missing);
+    else if (!a.ready)
+        u.item('note', 'scene', `the ${a.engine} inspector found no scene in ${READY_MS / 1000} s (no __PIXI_APP__ / __THREEJS_SCENE__ yet?): HUD and errors only`);
+    if (a.view && !a.view.entered)
+        u.item('not_observed', `view ${a.view.name}`, a.view.error);
+    if (a.at) {
+        u.item(a.at.hits.length ? 'pass' : 'not_observed', `at ${a.at.x},${a.at.y}`, a.at.hits.length ? `${a.at.hits.length} thing(s), top first` : 'nothing the inspector tracks is there');
+        for (const h of a.at.hits)
+            for (const l of describeHit(h))
+                u.line(`  ${l}`);
+    }
+    if (a.named) {
+        u.item(a.named.hits.length ? 'pass' : 'not_observed', `named "${a.named.query}"`, a.named.hits.length ? `${a.named.hits.length} match(es)` : `no object by that name${a.names.length ? ` — the game named: ${a.names.slice(0, 12).join(', ')}` : ''}`);
+        for (const h of a.named.hits)
+            for (const l of describeHit(h))
+                u.line(`  ${l}`);
+    }
+    if (opts.tree) {
+        u.item(a.tree ? 'pass' : 'not_observed', 'scene tree');
+        for (const l of treeLines(a.tree))
+            u.line(`  ${l}`);
+    }
+    else if (!a.at && !a.named && a.names.length) {
+        u.item('note', 'names', `${a.names.join(', ')} — ask with --name, or point with --at x,y`);
+    }
+    if (a.state !== null && a.state !== undefined)
+        u.item('note', 'state', JSON.stringify(a.state).slice(0, 300));
+    u.item(a.errors.length ? 'warn' : 'pass', 'runtime errors', a.errors.length ? `${a.errors.length}` : 'none while it ran');
+    for (const e of a.errors.slice(0, 12))
+        for (const l of describeError(e))
+            u.line(`  ${l}`);
+    u.summary(observed ? 'pass' : 'not_observed', observed ? 'answered — evidence, not a verdict' : 'not observed');
+    return observed ? EXIT.pass : EXIT.not_observed;
+}

package/dist/commands/job.js

@@ -0,0 +1,41 @@
+import { getJob } from "../api/jobs.js";
+import { kindOfTool } from "../gen/kinds.js";
+import { fail, finish, GEN_EXIT, needKey } from "./gen.js";
+import { ui } from "../ui.js";
+export async function job(opts, io = console) {
+    const r = { u: ui(io, 'job'), json: opts.json, io };
+    if (!opts.id)
+        return fail(r, new Error('no job id — funtools job <id> (gen --no-wait prints it)'));
+    const api = needKey(r);
+    if (!api)
+        return GEN_EXIT.error;
+    let j;
+    try {
+        j = await getJob(api, opts.id);
+    }
+    catch (e) {
+        return fail(r, e, opts.id);
+    }
+    if (opts.wait) {
+        const kind = kindOfTool(j.tool);
+        if (!kind)
+            return fail(r, new Error(`funtools does not know the tool ${j.tool} — update funtools`), j.job_id);
+        if (!r.json)
+            r.u.heading(`job ${j.job_id} · ${j.tool}`);
+        return finish(r, api, j.job_id, kind, typeof j.input.prompt === 'string' ? j.input.prompt : '', opts.out, opts.dir);
+    }
+    const bad = j.status === 'failed' || j.status === 'cancelled';
+    if (r.json) {
+        io.log(JSON.stringify({ ok: !bad, ...j }, null, 2));
+    }
+    else {
+        r.u.heading(`job ${j.job_id} · ${j.tool}`);
+        for (const o of j.outputs)
+            r.u.item('note', o.name, `${o.size_bytes} bytes, ${o.content_type}`);
+        if (j.error)
+            r.u.item('fail', j.error.code, j.error.message);
+        const status = j.status === 'succeeded' ? 'pass' : bad ? 'fail' : 'note';
+        r.u.summary(status, `${j.status}${j.status === 'succeeded' ? ` — charged ${j.charged_credits} credit(s); --wait saves the files` : bad ? '' : ' — --wait follows it to the end'}`);
+    }
+    return bad ? GEN_EXIT.failed : GEN_EXIT.done;
+}