@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/claude/hooks/floors.mjs

@@ -0,0 +1,181 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { declaredActors, judgeMotion, recordProblems } from './vendor/look/roles.mjs';
+import { readsUnchanged } from './vendor/verify/reads.mjs';
+const FLOOR_VIEWS = [
+    { what: 'win', re: /win|won|victor|clear|complete|success|result/i, unless: /\bendless\b|\bno win\b/i,
+        fix: 'the screen a won round ends on (or say "endless" in the design note when no round is won)' },
+    { what: 'how-to', re: /how|help|tutorial|controls|guide|learn/i,
+        fix: 'the objective and the real controls on keyboard and touch, in pictures, reachable from the title and pause' },
+    { what: 'settings', re: /setting|option/i,
+        fix: 'at least sound on or off and screen shake and flashes on or off (reduced motion), reachable from the title and pause' },
+];
+export function declaredViews(index, fingerprint) {
+    const names = new Set();
+    for (const c of Object.values(index ?? {})) {
+        if (c && c.fingerprint === fingerprint && Array.isArray(c.views))
+            for (const v of c.views)
+                names.add(String(v));
+    }
+    return [...names];
+}
+export function viewFloors(views, note) {
+    if (!views.length)
+        return [];
+    return FLOOR_VIEWS.filter((f) => !views.some((v) => f.re.test(v)) && !(f.unless && f.unless.test(note)))
+        .map((f) => `The game declares no ${f.what} view in __FPX_VIEWS__ (declared: ${views.join(', ')}). Add ${f.fix}, declare it, and capture it (skill funpixel-gdd, floors).`);
+}
+export function momentFloor(index, fingerprint) {
+    const fresh = Object.values(index ?? {}).filter((c) => c && c.fingerprint === fingerprint && c.entered === true);
+    const listed = fresh.filter((c) => Array.isArray(c.moments));
+    if (!listed.length)
+        return [];
+    const moments = [...new Set(listed.flatMap((c) => c.moments.map(String)))];
+    if (!moments.length) {
+        return ['The game declares no signature moment: add one __FPX_VIEWS__ entry marked `moment: true` whose enter() drives the game into its payoff through its own rules (the swarm mid-fight, the chain popping, the boss hit), call __FPX_MOMENT__ where the payoff plays, and capture it at both sizes (skill funpixel-verify).'];
+    }
+    const shotAt = (vp) => fresh.some((c) => moments.includes(c.view) && c.viewport === vp);
+    return shotAt('desktop') && shotAt('phone') ? [] : [
+        `The signature moment (${moments.join(', ')}) was not captured at both sizes on this build: run \`npx @funpixel/tools capture --view ${moments[0]} --viewport desktop|phone\` (it plays as a burst) before the panel.`,
+    ];
+}
+const MOTION_RUN = 'npx @funpixel/tools scene --motion --view playing';
+export function motionFloor(record, fingerprint, note, root = null) {
+    if (!record || (record.fingerprint !== fingerprint && !(root && readsUnchanged(root, record)))) {
+        return { items: [`No motion check on this build: run \`${MOTION_RUN}\` (it judges each actor against the Motion column of the design document's ## Actors).`], unseen: [] };
+    }
+    const problems = recordProblems(record);
+    if (problems.length) {
+        return { items: [`The motion check is unreadable (${problems.slice(0, 3).join('; ')}): run \`${MOTION_RUN}\` again. An unreadable sample is not evidence.`], unseen: [] };
+    }
+    const { defects, unobserved } = judgeMotion(record, declaredActors(note ?? ''));
+    return {
+        items: defects.length ? [`Motion by role: ${defects.join('; ')}. Give each the motion its role declares, or mark it \`still\` in the ## Actors table if it should rest (skill funpixel-art, references/animation.md).`] : [],
+        unseen: unobserved,
+        fault: defects.length > 0,
+    };
+}
+const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+export function playerFloor(root, fingerprint) {
+    const { item, findings } = playerState(root, fingerprint);
+    return item ? { items: [item], findings: findings ?? [] } : { items: [], findings: [] };
+}
+function playerState(root, fingerprint) {
+    const dir = join(root, '.funtools', 'play');
+    const retry = 'Run the blind player through `npx @funpixel/tools play --viewport phone` on the game folder for this build, then file its report (skill funpixel-verify).';
+    const rounds = existsSync(dir) ? readdirSync(dir).filter((s) => /^round-\d+$/.test(s))
+        .sort((a, b) => Number(b.slice(6)) - Number(a.slice(6))) : [];
+    let report;
+    for (const round of rounds) {
+        const path = join(dir, round, 'report.json');
+        if (!existsSync(path))
+            continue;
+        try {
+            const r = JSON.parse(readFileSync(path, 'utf8'));
+            if (r?.viewport === 'desktop')
+                continue;
+            report = r;
+            break;
+        }
+        catch {
+            return { item: `The latest player report is unreadable. ${retry}` };
+        }
+    }
+    if (report && report.viewport === 'phone' && typeof report.fingerprint !== 'string') {
+        return { item: `The latest phone round played a URL (${report.target ?? 'unknown'}) with no local source identity, so it cannot stand for this build. ${retry}` };
+    }
+    if (!report || report.viewport !== 'phone' || report.fingerprint !== fingerprint || report.source_changed !== false) {
+        return { item: `No fresh phone player report tied to the build actually played. ${retry}` };
+    }
+    if (!Number.isInteger(report.steps) || report.steps < 1 || !Array.isArray(report.defects) || !Array.isArray(report.criteria)) {
+        return { item: `The phone player report is incomplete. ${retry}` };
+    }
+    const unresolved = ['start', 'goal', 'act'].filter((k) => report[k]?.answer !== 'yes');
+    const high = report.defects.filter((d) => d?.severity === 'high');
+    const failed = report.criteria.filter((c) => c?.verdict === 'fail');
+    if (report.blocked === true || unresolved.length || high.length || failed.length) {
+        const named = [...unresolved, ...high.map((d) => String(d.title ?? '')), ...failed.map((c) => String(c.id ?? ''))].filter(Boolean);
+        const said = [...unresolved.map((k) => `${k} not understood or working`), ...high.map((d) => d.title),
+            ...failed.map((c) => `${c.id}: ${c.note || 'criterion failed'}`)].filter(Boolean).join('; ');
+        return {
+            item: `The phone player still has open findings: ${said || report.blocking || 'see its report'}. Fix them, verify and replay; to hand back before they are fixed, record each in the design note's \`## Fix round\` table (skill funpixel-verify).`,
+            findings: named.length ? named : ['blocked'],
+        };
+    }
+    return {};
+}
+function hasTestFile(dir, depth = 0) {
+    if (depth > 4 || !existsSync(dir))
+        return false;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (e.name === 'node_modules' || e.name.startsWith('.') || e.name === 'dist')
+            continue;
+        if (e.isDirectory() ? hasTestFile(join(dir, e.name), depth + 1) : TEST_FILE.test(e.name))
+            return true;
+    }
+    return false;
+}
+const TEST_RUN = 'npx @funpixel/tools test';
+export function testSuiteItem(root, fingerprint) {
+    let script = '';
+    try {
+        script = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).scripts?.test ?? '';
+    }
+    catch { }
+    if (!script || /no test specified/.test(script) || !hasTestFile(root)) {
+        return `No test suite for the rules: add test/*.test.ts (a test named after each rule, run under Node) and "test": "node --test test/*.test.ts" in package.json, then run \`${TEST_RUN}\` (skill funpixel-game-logic).`;
+    }
+    let run = null;
+    try {
+        run = JSON.parse(readFileSync(join(root, '.funtools', 'tests.json'), 'utf8'));
+    }
+    catch { }
+    if (!run || !Number.isInteger(run.exit) || run.fingerprint !== fingerprint) {
+        return `The rules suite has no recorded run on these files: run \`${TEST_RUN}\` (it runs npm test and records its exit with the build fingerprint).`;
+    }
+    return run.exit === 0 ? null : `The rules suite FAILED on these files (npm test exit ${run.exit}): fix the failing rules or tests, then run \`${TEST_RUN}\` again (skill funpixel-game-logic).`;
+}
+const AUDIT = 'npx @funpixel/tools audit-screens --viewport phone';
+export function phoneLayoutFloor(record, fingerprint) {
+    const out = { items: [], unseen: [] };
+    for (const [surface, how, flag] of [['phone-portrait', 'portrait', ''], ['phone-landscape', 'landscape', ' --orientation landscape']]) {
+        const r = record?.[surface];
+        if (!r || r.fingerprint !== fingerprint) {
+            out.unseen.push(`${how} layout (never measured on this build: \`${AUDIT}${flag}\`)`);
+            continue;
+        }
+        if (r.verdict !== 'fail')
+            continue;
+        const where = (r.failing ?? []).map((f) => `${f.view} (${(f.failed ?? []).join(', ').replace(/_/g, ' ')})`).join('; ');
+        out.items.push(`audit-screens on the phone held ${how} (${r.size}) fails on this build: ${where}. Fix the layout (skill funpixel-mobile-ui: safe areas, tap targets, text) and run \`${AUDIT}${flag}\` again.`);
+    }
+    return out;
+}
+const LOOK_3D = 'npx @funpixel/tools look --3d';
+export function isThreeGame(root) {
+    try {
+        const m = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).metadata ?? {};
+        return m.dimension === '3d' || m.framework === 'threejs';
+    }
+    catch {
+        return false;
+    }
+}
+export function heroMakeFloor(root, record, fingerprint, said) {
+    const out = { items: [], unseen: [] };
+    if (!isThreeGame(root))
+        return out;
+    if (!record || record.fingerprint !== fingerprint) {
+        out.unseen.push(`3D heroes (what they are made of was not read on this build: \`${LOOK_3D}\`)`);
+        return out;
+    }
+    if (record.verdict !== 'fail' || said === null)
+        return out;
+    const text = said.toLowerCase();
+    const stem = (f) => String(f).replace(/\.[^.]+$/, '').toLowerCase();
+    const missing = (record.unnamed ?? []).filter((f) => (f === 'the scene' ? !/scene|everything/.test(text) : !text.includes(stem(f))));
+    if (/stand-?ins?\b/.test(text) && !missing.length)
+        return out;
+    out.items.push(`${LOOK_3D} says ${record.says ?? 'the heroes are code primitives'}. Name each as a stand-in in the hand-back (${missing.length ? `not named: ${missing.join(', ')}` : 'say "stand-in"'}) with what will replace it, or take the hero route (skill funpixel-3d, references/hero-route.md), or declare the style in funpixel.json "art3d" with its reason and a proof frame.`);
+    return out;
+}

package/plugins/claude/hooks/flow.mjs

@@ -0,0 +1,154 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentFingerprint, readState, sessionStartMs, writeState } from './lib.mjs';
+import { pipelineEval } from './pipeline.mjs';
+import { FLOW_FILE, beat, flowAtStop, flowBlock, flowView, ownerFirst, planAgreement, readFlow } from './vendor/flow/flow.mjs';
+import { OPENING_STAGES, readPipeline } from './vendor/pipeline/pipeline.mjs';
+export function flowBeat(root, kind) {
+    try {
+        if (root && readFlow(root))
+            beat(root, kind, { by: 'gdk' });
+    }
+    catch { }
+}
+export async function flowStart(root, input) {
+    if (input && flowQuiet(input, root))
+        return { block: adoptionOffer(input, root, await flowNow(root, input).catch(() => null)), first: null, quiet: true };
+    const v = await flowNow(root, input);
+    if (!v)
+        return { block: null, first: null };
+    const line = ownerFirst(v);
+    return { block: flowBlock(v), first: line ? `## The owner first\n- ${line}` : null };
+}
+export const BUILT_FILES = 10;
+export function builtGame(root) {
+    const f = readFlow(root);
+    if (!f || f.dropped)
+        return null;
+    const p = readPipeline(root);
+    if (p?.stages.some((st) => OPENING_STAGES.includes(st.id)))
+        return null;
+    const files = Object.keys(f.scaffold ?? {}).length;
+    if (files < BUILT_FILES)
+        return null;
+    let verdict = null;
+    try {
+        verdict = JSON.parse(readFileSync(join(root, 'verify.json'), 'utf8')).verdict;
+    }
+    catch {
+        return null;
+    }
+    if (verdict !== 'pass')
+        return null;
+    try {
+        if (planAgreement(root).agreed)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { files };
+}
+export function flowQuiet(input, root) {
+    if (!root || !readFlow(root))
+        return false;
+    if (readState(input).flowBuilt) {
+        try {
+            return !planAgreement(root).agreed;
+        }
+        catch {
+            return true;
+        }
+    }
+    const b = builtGame(root);
+    if (b)
+        writeState(input, { ...readState(input), flowBuilt: b.files });
+    return Boolean(b);
+}
+export function adoptionOffer(input, root, v = null) {
+    const state = readState(input);
+    if (state.flowOffered)
+        return null;
+    writeState(input, { ...state, flowOffered: Date.now() });
+    const at = v?.stage ? `"stage ${v.stage.n} of ${v.stage.of}: ${v.stage.title}"` : 'its first stage';
+    return [
+        '## The flow (`npx @funpixel/tools flow` · .funtools/flow.json)',
+        `- this game was built before its flow began (verify passed; ${state.flowBuilt ? `${state.flowBuilt} code files` : 'its code'} when the flow started; its path has no first look or first playable), so the flow's ${at} does not describe it. The flow stays silent on this game: work on what the owner asks.`,
+        '- offer the owner once, in one line, to put the game on the flow from where it stands. On their yes: `npx @funpixel/tools note verdict <stage> accept "<their words>"` for each stage the game already has, then `npx @funpixel/tools flow agree --by owner "<their words>"`; the flow then runs its rounds from the first stage still open.',
+    ].join('\n');
+}
+export const FLOW_MAX_BLOCKS = 12;
+export const FLOW_MAX_HOLDS = 4;
+export async function flowNow(root, input) {
+    const f = readFlow(root);
+    if (!f)
+        return null;
+    const { e } = await pipelineEval(root);
+    return flowView(root, e, f, { sessionStart: input ? sessionStartMs(input) : 0 });
+}
+export async function flowContext(root, input) {
+    const v = await flowNow(root, input);
+    return v ? flowBlock(v) : null;
+}
+const CODE = /(^|\/)(src\/.+\.(ts|tsx|js|jsx|mjs|css|html|glsl|wgsl)|index\.html)$/;
+export async function flowEditLine(input, root) {
+    if (!/^(Write|Edit|MultiEdit)$/.test(String(input.tool_name ?? '')))
+        return null;
+    const file = String(input.tool_input?.file_path ?? input.tool_input?.path ?? '');
+    if (!CODE.test(file) || !readFlow(root) || flowQuiet(input, root))
+        return null;
+    if (readState(input).flowEditSaid)
+        return null;
+    const v = await flowNow(root, input);
+    if (!v || v.agreement.agreed || !v.builtEarly.length)
+        return null;
+    writeState(input, { ...readState(input), flowEditSaid: Date.now() });
+    const where = v.stage ? `the current stage (${v.stage.title})` : 'the flow';
+    return `Funpixel flow: the plan is not agreed yet (${v.agreement.says}) and ${where} builds no game code, so game code waits for the owner's yes: finish the plan and put it to them once (\`npx @funpixel/tools flow ask\`). Code written before then is not held at the Stop; it is named there.`;
+}
+async function signature(root) {
+    const t = (rel) => { try {
+        return statSync(join(root, rel)).mtimeMs;
+    }
+    catch {
+        return 0;
+    } };
+    const fp = await currentFingerprint(root).catch(() => '');
+    return [fp, t(FLOW_FILE), t(join('.funtools', 'progress.jsonl')), t(join('design', 'pipeline.json')), t(join('design', 'GDD.md')), t(join('design', 'plan-notes.json'))].join(':');
+}
+export async function flowStop(input, root) {
+    const f = readFlow(root);
+    if (!f || flowQuiet(input, root))
+        return null;
+    const state = readState(input);
+    const start = sessionStartMs(input);
+    const fp = await currentFingerprint(root).catch(() => null);
+    const worked = fp !== state.startFingerprint || Date.parse(f.at?.said_at ?? '') >= start || (f.rounds ?? []).some((r) => Date.parse(r.closed_at ?? '') >= start);
+    if (!worked)
+        return null;
+    const v = await flowNow(root, input);
+    if (!v)
+        return null;
+    const verdict = flowAtStop(v);
+    if (verdict.hold) {
+        const n = state.flowHolds ?? 0;
+        if (n >= FLOW_MAX_HOLDS)
+            return { warn: `Funpixel flow: held ${n} times — ending with game code past the scaffold and the plan NOT agreed.` };
+        writeState(input, { ...readState(input), flowHolds: n + 1 });
+        return { block: verdict.hold };
+    }
+    if (verdict.block) {
+        const sig = `${verdict.key}|${await signature(root)}`;
+        const n = state.flowBlocks ?? 0;
+        if (state.flowLast === sig || n >= FLOW_MAX_BLOCKS)
+            return { warn: `Funpixel flow: ${v.step}. Nothing moved since the last Stop, so the session hands back here; resume with /fp:flow.` };
+        writeState(input, { ...readState(input), flowBlocks: n + 1, flowLast: sig });
+        return { block: verdict.block };
+    }
+    if (verdict.once) {
+        if (state.flowOnce === verdict.key)
+            return null;
+        writeState(input, { ...readState(input), flowOnce: verdict.key });
+    }
+    return verdict.warn ? { warn: verdict.warn } : null;
+}

package/plugins/claude/hooks/front-door.mjs

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+const START_PATH = /(^|\/)(index\.html|(main|app)\.[cm]?[jt]sx?|[^/]*(title|menu|screen|start|input|control|touch|sound|audio)[^/]*\.[cm]?[jt]sx?)$/i;
+const START_CODE = /data-fpx-start|\bunlock\w*\s*\(|new\s+(webkit)?AudioContext|\.resume\s*\(\s*\)|addEventListener\(\s*['"`](key|pointer|touch|click|mouse)/;
+const NO_START = /\bno (dom |html )?(start|play|title)( screen| button| control)?\b|\bstarts? (straight|directly) (in|into) play\b/i;
+const SOURCE = /\.(m?[jt]sx?|html)$/i;
+const sha = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
+export function sourceHashes(root) {
+    const out = {};
+    if (!root)
+        return out;
+    const walk = (dir) => {
+        if (!existsSync(dir))
+            return;
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (SOURCE.test(e.name))
+                out[relative(root, p).split(sep).join('/')] = sha(readFileSync(p, 'utf8'));
+        }
+    };
+    walk(join(root, 'src'));
+    if (existsSync(join(root, 'index.html')))
+        out['index.html'] = sha(readFileSync(join(root, 'index.html'), 'utf8'));
+    return out;
+}
+export function startFlowEdits(root, state) {
+    if (!state.startedAt || !state.startSources)
+        return [];
+    const before = state.startSources;
+    return Object.entries(sourceHashes(root))
+        .filter(([path, hash]) => before[path] !== hash)
+        .map(([path]) => path)
+        .filter((path) => START_PATH.test(path) || START_CODE.test(readFileSync(join(root, path), 'utf8')));
+}
+export function frontDoor(root, fingerprint) {
+    let record;
+    try {
+        record = JSON.parse(readFileSync(join(root, 'verify.json'), 'utf8'));
+    }
+    catch {
+        return 'not run';
+    }
+    const f = record?.report?.front_door;
+    if (record?.fingerprint !== fingerprint || !f)
+        return 'not run';
+    return f.found && f.pressed && f.changed === true ? 'passed' : 'failed';
+}
+const source = (root) => Object.keys(sourceHashes(root)).map((p) => readFileSync(join(root, p), 'utf8')).join('\n');
+const marksStart = (root) => source(root).includes('data-fpx-start');
+const hasTitle = (root) => { const s = source(root); return s.includes('data-fpx-start') || /\btitle\s*:\s*\{[^}]*\benter\b/.test(s); };
+export function frontDoorItem(root, state, fingerprint, said = '') {
+    const edits = startFlowEdits(root, state);
+    if (!edits.length || !hasTitle(root))
+        return null;
+    const door = frontDoor(root, fingerprint);
+    if (door === 'passed')
+        return null;
+    if (NO_START.test(said) && !marksStart(root))
+        return null;
+    const why = door === 'failed' ? 'the last front-door verify FAILED: the real start control did nothing' : 'no verify on the current files pressed the real start control';
+    return `This session changed the start flow (${edits.slice(0, 4).join(', ')}${edits.length > 4 ? ', …' : ''}) and ${why}. ` +
+        'Mark the start control data-fpx-start (a start drawn in the canvas gets a transparent DOM button over it carrying the attribute) and run ' +
+        '`npm run build`, then `npx @funpixel/tools verify --front-door` (or `npx @funpixel/tools check --front-door`), until it passes (skill funpixel-verify). ' +
+        'A game with no start control at all says so in the hand-back ("no start screen: it opens in play").';
+}

package/plugins/claude/hooks/guidance.json

@@ -0,0 +1,3 @@
+{
+  "hash": "47443d9a284e95f9"
+}

package/plugins/claude/hooks/hints.mjs

@@ -0,0 +1,183 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { completeGameScope } from './scope.mjs';
+import { is3d, targetFrames } from './reach.mjs';
+const mcp = (names) => new RegExp(`(?:^|[_:.])(?:${names.join('|')})$`);
+const cli = (verbs) => new RegExp(`(?:@funpixel/tools|funtools)\\s+(?:${verbs})\\b`);
+const DEPTH = /\b(run length|per minute|score attack|endless|best score|high score|leaderboard|daily (seed|board|challenge))\b/i;
+const noteOf = (root) => {
+    for (const name of ['GDD.md', 'README.md']) {
+        try {
+            return readFileSync(join(root, 'design', name), 'utf8');
+        }
+        catch { }
+    }
+    return null;
+};
+const STORY = /(^|[/\\])src[/\\](.*[/\\])?(story|stories|dialog(ue)?s?|lines|script|chapters?|narrative|cast)\.(ts|tsx|js|json)$/i;
+const OWN_IMAGE = /(^|[\s/;&|(])(gen-?image|generate[-_]image|image-?gen|imagegen)\b|gpt-image|images\/generations/i;
+const written = (input) => String(input?.tool_input?.content ?? input?.tool_input?.new_string ?? (input?.tool_input?.edits ?? []).map((e) => e.new_string ?? '').join('\n'));
+const LINES = /\b(speaker|who|says?|line|lines|dialog(ue)?|caption|subtitle|bark)\s*:\s*['"`][^'"`\n]{14,}/gi;
+const spokenLines = (text) => (text.match(LINES) ?? []).length >= 2;
+const LIFE_PATH = /(^|[/\\])src[/\\](.*[/\\])?[^/\\]*(folk|npcs?|crowd|people|villagers?|townsfolk|pedestrians?|citizens?|creatures?|animals?|wildlife|critters?|birds?|flock|herd|fauna|actors|life)[^/\\]*\.(ts|tsx|js)$/i;
+const LIFE_CODE = /\b(npcs?|townsfolk|villagers?|crowd|pedestrians?|creatures?|wildlife|flock|herd|SkeletonUtils|AnimationMixer)\b/;
+const LOOK3D_PATH = /(^|[/\\])src[/\\](.*[/\\])?[^/\\]*(camera|terrain|ground|world|scene|sky|light|lighting|env|environment|level|backdrop|rig)[^/\\]*\.(ts|tsx|js)$/i;
+const LOOK3D_CODE = /\b(PerspectiveCamera|Fog(Exp2)?|HemisphereLight|DirectionalLight|PointLight|SpotLight|toneMapping|heightmap|terrain|skydome|sky ?dome|backdrop)\b/;
+const CAPTURE = /(?:@funpixel\/tools|funtools)\s+(capture|look|compare|hook)\b/;
+const HELP = /\s(--help|-h)\b/;
+const NOT_PLAY = /--view[ =]+["']?(title|menu|splash|intro|pause|over|end|won|win|lost|lose|result|credit|settings|help)/i;
+const RULES = /(^|[/\\])src[/\\](rules\.ts|sim[/\\]|logic[/\\]|rules[/\\])/;
+const probeOnDemo = (root) => {
+    try {
+        return /\b(bestStep|TELL_SECONDS|inReach)\b/.test(readFileSync(join(root, 'test', 'probes.ts'), 'utf8'));
+    }
+    catch {
+        return true;
+    }
+};
+const tierOf = (root) => {
+    try {
+        const t = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).production?.tier;
+        return t === 'mid' || t === 'deep' ? t : null;
+    }
+    catch {
+        return null;
+    }
+};
+const verdict = (root) => {
+    try {
+        return JSON.parse(readFileSync(join(root, 'verify.json'), 'utf8')).verdict;
+    }
+    catch {
+        return null;
+    }
+};
+export const HINTS = [
+    {
+        id: 'art',
+        when: ({ tool, cmd }) => mcp(['generate_image', 'generate_sprite', 'edit_image', 'key_sprite', 'generate_batch']).test(tool) || cli('gen\\s+(?:image|sprite|edit)|assets\\s+gen').test(cmd)
+            || (tool === 'Bash' && OWN_IMAGE.test(cmd)),
+        text: 'The first picture: lock identity before the second (skill funpixel-gdd, references/first-look.md and world-and-identity.md; GDD ## Identity lock; the look\'s rules: skill funpixel-art). '
+            + 'One reference sheet per character and place, made first and passed as a reference to every later draw; the style block verbatim in every prompt; '
+            + 'best of a few draws judged at play size against the target; the raw originals kept. A sheet cuts into parts, poses or items with '
+            + '`npx @funpixel/tools parts`; skill funpixel-art has poses (`edit_image`), cycles (`generate_spritesheet`) and the accept-or-redo check.',
+    },
+    {
+        id: 'sound',
+        when: ({ tool, cmd }) => mcp(['generate_sound', 'generate_music']).test(tool) || cli('gen\\s+(?:sound|music)').test(cmd),
+        text: 'On the shelf for sound (skill funpixel-audio): one musical identity across tracks, a calm and a tense take mixed by threat, '
+            + 'loudness classes so a pickup never covers the payoff, loops cut on the bar, and the SDK AudioEngine wiring. '
+            + 'Save each file with `npx @funpixel/tools job <id> --wait --out public/assets/<file>`.',
+    },
+    {
+        id: 'model3d',
+        when: ({ tool, cmd }) => mcp(['generate_3d_model', 'generate_skybox']).test(tool) || cli('gen\\s+model3d').test(cmd),
+        text: 'On the shelf for 3D: skill funpixel-3d (concept image first, rigged or static, the loading contract; then '
+            + 'the bench: inspect, rig check, optimize to a phone budget, a proof render before a model is called fixed).',
+    },
+    {
+        id: 'depth',
+        when: ({ tool, path, root }) => /^(Write|Edit|MultiEdit)$/.test(tool) && /(^|[/\\])design[/\\](GDD|README)\.md$/.test(path)
+            && !DEPTH.test(noteOf(root) ?? 'run length'),
+        text: 'Depth, on the shelf (skill funpixel-game-logic, references/depth.md): a run length for the genre, how much happens per minute, '
+            + 'pressure inside the first 30 seconds, a score attack or endless mode after the level, a local best. In every head to head so far '
+            + 'the critics\' player seat chose the genre hit for its depth ("a dense ten-minute score attack against a 1:38 run").',
+    },
+    {
+        id: 'world',
+        when: ({ tool, path, cmd, input }) => (/^(Write|Edit|MultiEdit)$/.test(tool) && (STORY.test(path) || (/\.(ts|tsx|js|json)$/.test(path) && spokenLines(written(input)))))
+            || (tool === 'Bash' && /(^|[\s;&|])(say|piper)\s|voice/i.test(cmd)),
+        text: 'On the shelf for a place with a story (skill funpixel-world-and-story): story-at-size (a want said by a person, chapters, a turn, an ending; '
+            + 'the GDD\'s ## Story beat table, and __FPX_STATE__.beat so `npx @funpixel/tools depth` shows which beats play reached); atmosphere (ambient life, '
+            + 'a sound bed, the world answering a big moment; `npx @funpixel/tools life` shows what moves, what plays and what answered); voice (captions advance '
+            + 'on the clip\'s end or a timeout; the creator\'s own text-to-speech is recorded, never billed).',
+    },
+    {
+        id: 'look3d',
+        when: ({ tool, path, input, root }) => /^(Write|Edit|MultiEdit)$/.test(tool) && is3d(root)
+            && (LOOK3D_PATH.test(path) || (/\.(ts|tsx|js)$/.test(path) && LOOK3D_CODE.test(written(input)))),
+        text: 'A 3D scene that holds up beside its painted target (skill funpixel-3d, references/painted-target.md): measure the target first '
+            + '(horizon line, hero height, layers, light, haze colour); a 35 to 50 degree lens placed so the hero is the target\'s size; fog the exact sky colour '
+            + 'at the horizon; ground with height in near, middle and far bands plus a backdrop; hemisphere + key + rim + one warm accent; three things moving '
+            + 'before any input. A walk that reads as a person, not a robot: weight shifting, a gentle bob, hips and shoulders counter-rotating, '
+            + 'planted feet that never slide, eased starts and stops; a cut-out rig with pivots at the joints and overlap (only the root faces the camera) '
+            + 'or a rigged 3D character with real walk clips, and a test that every part stays attached. '
+            + 'Camera-near geometry is the most detailed, never the plainest: every structure the player passes reads as made (shape detail + a texture or decals '
+            + 'in the palette), matched to the best-painted asset in the scene; landed vehicles and big props rest on the ground under their whole footprint '
+            + '(skill funpixel-world-and-story, references/living-world.md "Made, not boxes"; `npx @funpixel/tools boxes` names what reads unfinished or floats).',
+    },
+    {
+        id: 'life',
+        when: ({ tool, path, input }) => /^(Write|Edit|MultiEdit)$/.test(tool) && /\.(ts|tsx|js)$/.test(path)
+            && (LIFE_PATH.test(path) || LIFE_CODE.test(written(input))) && !RULES.test(path),
+        text: 'People and creatures in the world (skill funpixel-world-and-story, references/living-world.md): every person a body that animates, '
+            + 'a task loop that moves them through space (haul, patrol, errand), an idle and a reaction to the player (head turn, wave, step aside); '
+            + 'a crowd is a few focused scenes along the player\'s path, each one purpose and spaced to read on its own, not many people; '
+            + 'it shares a rig, never the hero\'s face (a face, hair and tint pool, heights 1.55 to 1.90 m); creatures with a gait whose rate follows '
+            + 'ground speed, flyers that flap and bank, reactions with distance and hysteresis (flee, follow, watch); feet from the ground height, never inside a prop. '
+            + 'Rig clones with clip sets near, an instanced gait in the shader far. Expose them in window.__FPX_ACTORS__ (skill funpixel-verify, references/actors.md); '
+            + '`npx @funpixel/tools life` and `walk` say who slides, who stays in place, who wears the hero\'s face, who clumps.',
+    },
+    {
+        id: 'probe',
+        when: ({ tool, path, root }) => /^(Write|Edit|MultiEdit)$/.test(tool) && RULES.test(path) && probeOnDemo(root),
+        text: 'The rules changed; test/probes.ts still plays the scaffold\'s demo (or is missing). The rules and their probe are one piece: '
+            + 'rewrite its game and five players on your rules now, and `npx @funpixel/tools sim` measures play length against 15 minutes and an ending (ended(run)) and '
+            + 'your design doc\'s Play length line, standing still, the skill ceiling and a stalled bot; with level(run) and a humanRate twin of the '
+            + 'sharp player it reads the curve per level too: flat levels, walls for people, a run nothing loses (skill funpixel-game-logic, references/probes.md).',
+    },
+    {
+        id: 'production',
+        when: ({ tool, root }) => /^(Write|Edit|MultiEdit)$/.test(tool) && tierOf(root) !== null,
+        text: 'This plan is a bigger game (funpixel.json production.tier). On the shelf: skill funpixel-gdd, references/production-tiers.md, '
+            + 'how far directing, keeping it consistent and the QA loop turn up at this size, each with the game that did it (target frames per place, '
+            + 'progress saved, reference sheets and best-of-N art with the raw originals kept, bots on seeds and a replay test, fixed-framing before/after; '
+            + 'at deep, a making-of log in design/MAKING.md, one lane per worktree, blind phone players and an A/B phone profile). Inspiration, not a recipe; '
+            + '`npx @funpixel/tools check` prints what it means for this game today.',
+    },
+    {
+        id: 'target',
+        when: ({ tool, cmd, root }) => targetFrames(root).length > 0
+            && ((tool === 'Bash' && CAPTURE.test(cmd) && !NOT_PLAY.test(cmd) && !HELP.test(cmd)) || mcp(['capture_view', 'screenshot']).test(tool)),
+        text: 'Put it beside its target: `npx @funpixel/tools compare --target <design/first-look/frame> --view <view>` writes today | target at phone '
+            + 'landscape 852x393 and desktop 1280x720. Judge mood, light, value steps, the hero\'s size and how full the frame is; work the largest gap, '
+            + 'keep each strip as the before for the next pass (skill funpixel-verify, references/fidelity.md).',
+    },
+    {
+        id: 'hook',
+        when: ({ tool, cmd }) => tool === 'Bash' && cli('verify|capture|check').test(cmd) && !HELP.test(cmd),
+        text: 'The hook: the title and the first minutes of play decide whether people keep playing. Environment, living things, animation, the real assets, '
+            + 'the HUD, collisions and the controls this device needs land there first. `npx @funpixel/tools hook` reads the title and about three minutes '
+            + 'after Play and warns when the opening is still, empty or still on stand-ins.',
+    },
+    {
+        id: 'verified',
+        when: ({ tool, cmd, root, complete }) => complete && tool === 'Bash' && cli('verify').test(cmd) && verdict(root) === 'pass',
+        text: 'A green verify is the slice. What turns it into a complete game, on the shelf: `npx @funpixel/tools verify --front-door` presses the real Play; '
+            + '`capture --all` shoots every view at both sizes; three critic seats judge those frames blind, each on the phone and the desktop shots (skill funpixel-verify); '
+            + '`play --viewport phone` puts a blind first-time player on it (the player agent). The seats and the player run on your own agent, '
+            + 'in parallel, about 15 to 25 minutes in all; `/fp:playtest` runs the lot and ranks what to do next.',
+    },
+    {
+        id: 'panel',
+        when: ({ tool, input }) => /^(Task|Agent)$/.test(tool) && /critic/i.test(String(input.tool_input?.subagent_type ?? '')),
+        text: 'The panel is three blind seats on one capture set: veteran player, UX designer and skeptic, each scoring the same rubric on the '
+            + 'phone shots and the desktop shots (skill funpixel-verify). A seat run in the background answers later, in a notification: read all three verdicts before acting on them or stopping.',
+    },
+];
+export function shelfHints(input, state, root) {
+    const shown = new Set(state.hints ?? []);
+    const ctx = {
+        input, root,
+        tool: String(input.tool_name ?? ''),
+        cmd: String(input.tool_input?.command ?? ''),
+        path: String(input.tool_input?.file_path ?? input.tool_input?.path ?? ''),
+        complete: Boolean(completeGameScope(state, root)),
+    };
+    if (!root || !existsSync(root))
+        return null;
+    const due = HINTS.filter((h) => !shown.has(h.id) && h.when(ctx));
+    if (!due.length)
+        return null;
+    return { text: due.map((h) => h.text).join('\n'), state: { ...state, hints: [...shown, ...due.map((h) => h.id)] } };
+}

package/plugins/claude/hooks/hooks.json

@@ -0,0 +1,62 @@
+{
+  "description": "Funpixel: brief and project state at session start; a lane worker's write outside its lane's files is refused; at Stop, lists what is open (verify, filed feedback, and for a complete game its evidence and panel). The Stop is advisory by default and blocks only under funpixel.json gdk.gate \"block\".",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/prompt.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/fence.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash|Task|Agent|mcp__.*(report_feedback|generate_\\w+|edit_image|key_sprite|capture_view|screenshot)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/nudge.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/stop-gate.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}