@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/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/cursor/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/session-start.mjs\""
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/prompt.mjs\""
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/nudge.mjs\""
+      }
+    ],
+    "stop": [
+      {
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/stop-gate.mjs\"",
+        "loop_limit": 1
+      }
+    ]
+  }
+}

package/plugins/cursor/hooks/lib.mjs

@@ -0,0 +1,362 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fingerprintOfDigests, HashBudgetExceeded, stagedDigests } from './vendor/verify/fingerprint.mjs';
+import { toClaudeNames } from './vendor/find/names.mjs';
+import { frontDoorItem } from './front-door.mjs';
+import { completeGameScope } from './scope.mjs';
+import { isGraybox, lastAssistantText, qualityReport } from './quality.mjs';
+let hostNames;
+export function skillNames() {
+    if (hostNames === undefined) {
+        try {
+            hostNames = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'skill-names.json'), 'utf8')).names ?? null;
+        }
+        catch {
+            hostNames = null;
+        }
+    }
+    return hostNames;
+}
+export const forHost = (text) => {
+    const names = skillNames();
+    return names && typeof text === 'string' ? toClaudeNames(text, names) : text;
+};
+export function skillNamesLine() {
+    const names = skillNames();
+    if (!names)
+        return null;
+    const odd = Object.entries(names).filter(([long, short]) => long !== `funpixel-${short}`)
+        .map(([long, short]) => `\`.agents/skills/${long}/\` is \`fp:${short}\``);
+    return '- skill names: in Claude Code a kit skill is `fp:<name>`; funtools, AGENTS.md and the folders under '
+        + '.agents/skills say `funpixel-<name>` for the same skill'
+        + (odd.length ? `. Named apart because a command has the short name: ${odd.join(', ')}` : '');
+}
+export function isMain(metaUrl) {
+    try {
+        return Boolean(process.argv[1]) && realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+}
+export async function readInput() {
+    let raw = '';
+    for await (const chunk of process.stdin)
+        raw += chunk;
+    try {
+        return raw.trim() ? JSON.parse(raw) : {};
+    }
+    catch {
+        return {};
+    }
+}
+const KIRO_EVENTS = /^(agentSpawn|userPromptSubmit|preToolUse|postToolUse|stop)$/;
+export function client(input) {
+    if (input.cursor_version || input.conversation_id)
+        return 'cursor';
+    return KIRO_EVENTS.test(String(input.hook_event_name ?? '')) ? 'kiro' : 'claude';
+}
+export function deferForKiro(input, key, text) {
+    writeState(input, { ...readState(input), [key]: text });
+}
+export function takeDeferred(input) {
+    const state = readState(input);
+    const out = [state.pendingGate ?? state.pendingNudge].filter(Boolean);
+    if (out.length)
+        writeState(input, { ...state, pendingGate: undefined, pendingNudge: undefined });
+    return out;
+}
+export const ANONYMOUS_TTL_MS = 6 * 60 * 60 * 1000;
+export function sessionId(input) {
+    const id = input.session_id || input.conversation_id || process.env.KIRO_SESSION_ID;
+    if (id)
+        return String(id).replace(/[^\w.-]/g, '_');
+    return `anon-${createHash('sha256').update(String(startDir(input))).digest('hex').slice(0, 16)}`;
+}
+export function startDir(input) {
+    return input.cwd || (Array.isArray(input.workspace_roots) && input.workspace_roots[0]) || process.cwd();
+}
+export function findGameRoot(from) {
+    let dir = from;
+    for (;;) {
+        if (existsSync(join(dir, 'funpixel.json')))
+            return dir;
+        const up = dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}
+export function gatePolicy(root) {
+    const env = process.env.FUNPIXEL_GDK_GATE;
+    if (env === 'off' || env === 'warn' || env === 'block')
+        return env;
+    try {
+        const g = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).gdk?.gate;
+        if (g === 'off' || g === 'warn' || g === 'block')
+            return g;
+    }
+    catch {
+    }
+    return 'warn';
+}
+function stateFile(input) {
+    const base = process.env.CLAUDE_PLUGIN_DATA || process.env.PLUGIN_DATA || join(tmpdir(), 'funpixel-gdk');
+    mkdirSync(base, { recursive: true });
+    return join(base, `session-${sessionId(input)}.json`);
+}
+export function readState(input) {
+    try {
+        const file = stateFile(input);
+        if (sessionId(input).startsWith('anon-') && Date.now() - statSync(file).mtimeMs > ANONYMOUS_TTL_MS)
+            return {};
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeState(input, state) {
+    writeFileSync(stateFile(input), JSON.stringify(state));
+}
+function digestCacheFile(root) {
+    const base = process.env.CLAUDE_PLUGIN_DATA || process.env.PLUGIN_DATA || join(tmpdir(), 'funpixel-gdk');
+    mkdirSync(base, { recursive: true });
+    return join(base, `digests-${createHash('sha256').update(resolve(root)).digest('hex').slice(0, 16)}.json`);
+}
+const digestsByRoot = new Map();
+const HASH_BUDGET_MS = 8000;
+export function gameDigests(root) {
+    if (!digestsByRoot.has(root)) {
+        digestsByRoot.set(root, (async () => {
+            const file = digestCacheFile(root);
+            let cache = {};
+            try {
+                cache = JSON.parse(readFileSync(file, 'utf8'));
+            }
+            catch { }
+            try {
+                return await stagedDigests(root, cache, Date.now() + HASH_BUDGET_MS);
+            }
+            finally {
+                try {
+                    writeFileSync(file, JSON.stringify(cache));
+                }
+                catch { }
+            }
+        })());
+    }
+    return digestsByRoot.get(root);
+}
+export async function currentFingerprint(root) {
+    try {
+        return fingerprintOfDigests(await gameDigests(root));
+    }
+    catch (e) {
+        if (e instanceof HashBudgetExceeded)
+            return null;
+        throw e;
+    }
+}
+export function verifyStatus(root, now) {
+    const file = join(root, 'verify.json');
+    if (!existsSync(file))
+        return 'missing';
+    let record;
+    try {
+        record = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return 'missing';
+    }
+    if (record.fingerprint !== now)
+        return 'stale';
+    if (record.verdict === 'fail')
+        return 'fail';
+    if (record.verdict !== 'pass')
+        return 'not_observed';
+    return 'pass';
+}
+export const DEVLOG = () => join(homedir(), '.funpixel', 'devlog.jsonl');
+export const GAME_DEVLOG = (root) => join(root, '.funtools', 'devlog.jsonl');
+export const KIT_FEEDBACK = (root) => join(root, '.funtools', 'kit-feedback.jsonl');
+export const KIT_KINDS = ['worked', 'hurt', 'missing'];
+export function isFeedbackCall(input) {
+    const r = input.tool_response;
+    const failed = r && typeof r === 'object' && (r.isError === true || r.is_error === true);
+    return /report_feedback$/.test(input.tool_name ?? '') && !failed;
+}
+const hasKitItems = (items) => Array.isArray(items) && items.some((i) => KIT_KINDS.includes(i?.kind));
+export const isKitVerdictCall = (input) => isFeedbackCall(input) && hasKitItems(input.tool_input?.items);
+function linesSince(file, sinceMs) {
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try {
+            const e = JSON.parse(line);
+            const at = Date.parse(e.at ?? e.t ?? e.date ?? '');
+            if (Number.isNaN(at) || at >= sinceMs)
+                out.push(e);
+        }
+        catch {
+        }
+    }
+    return out;
+}
+export function kitVerdictFiled(input, root, sinceMs) {
+    if (readState(input).kitVerdictAt)
+        return true;
+    const t = input.transcript_path;
+    if (t && existsSync(t)) {
+        for (const line of readFileSync(t, 'utf8').split('\n')) {
+            if (!line.includes('report_feedback'))
+                continue;
+            try {
+                const blocks = JSON.parse(line).message?.content;
+                if (Array.isArray(blocks) && blocks.some((b) => b?.type === 'tool_use' && /report_feedback$/.test(b.name ?? '') && hasKitItems(b.input?.items)))
+                    return true;
+            }
+            catch {
+            }
+        }
+    }
+    if (linesSince(KIT_FEEDBACK(root), sinceMs).some((e) => e.kind === 'kit-verdict' || hasKitItems(e.items)))
+        return true;
+    return linesSince(GAME_DEVLOG(root), sinceMs).some((e) => e.kind === 'feedback' && hasKitItems(e.items));
+}
+export function kitVerdictOn(root) {
+    if (process.env.FUNPIXEL_GDK_KIT_VERDICT === 'off')
+        return false;
+    try {
+        return JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).gdk?.kitVerdict !== false;
+    }
+    catch {
+        return true;
+    }
+}
+export const KIT_ASK = 'One question before you hand back, asked once (answer it or skip it; nothing depends on it): how did the Funpixel kit do for you in this session? '
+    + 'In one report_feedback call (skill funpixel-feedback, "The kit verdict"), give items with `kind` worked, hurt or missing and the `tool` each is about (a tool, skill, hook or command): '
+    + 'what in the kit helped, what got in the way or was wrong, what was missing, and one overall line with `tool` "kit" saying whether the kit did well or let you down, and why. '
+    + 'About the kit, not the game. If the call fails, write the same items as one line with "kind": "kit-verdict" in .funtools/kit-feedback.jsonl with your file tools.';
+export function feedbackFiled(input, root, sinceMs) {
+    if (readState(input).feedbackAt)
+        return true;
+    const t = input.transcript_path;
+    if (t && existsSync(t) && /"name"\s*:\s*"[^"]*report_feedback"/.test(readFileSync(t, 'utf8')))
+        return true;
+    if (linesSince(KIT_FEEDBACK(root), sinceMs).length)
+        return true;
+    for (const [log, own] of [[GAME_DEVLOG(root), true], [DEVLOG(), false]]) {
+        if (!existsSync(log))
+            continue;
+        for (const line of readFileSync(log, 'utf8').split('\n').reverse()) {
+            try {
+                const e = JSON.parse(line);
+                if (e.kind === 'feedback' && (e.game === root || (own && e.game === undefined)) && Date.parse(e.at) >= sinceMs)
+                    return true;
+            }
+            catch {
+            }
+        }
+    }
+    return false;
+}
+export function sessionStartMs(input) {
+    const s = readState(input);
+    if (s.startedAt)
+        return s.startedAt;
+    const t = input.transcript_path;
+    if (t && existsSync(t)) {
+        const st = statSync(t);
+        return st.birthtimeMs || st.ctimeMs;
+    }
+    return 0;
+}
+export const VERIFY = '`npm run build`, then `npx @funpixel/tools verify` (or `npx @funpixel/tools check`: both and the rules suite in one call)';
+const GAME_CODE = /^(src|public)\/|^index\.html$|^package(-lock)?\.json$|^vite\.config|^tsconfig/;
+export function changedSince(snapshot, hashes) {
+    if (!snapshot)
+        return [];
+    const out = [];
+    for (const [p, h] of Object.entries(hashes))
+        if (snapshot[p] !== h)
+            out.push(snapshot[p] ? p : `${p} (new)`);
+    for (const p of Object.keys(snapshot))
+        if (!(p in hashes))
+            out.push(`${p} (removed)`);
+    return out.sort();
+}
+export function staleDetail(changed) {
+    if (!changed.length)
+        return '';
+    const names = changed.slice(0, 5).join(', ') + (changed.length > 5 ? ` and ${changed.length - 5} more` : '');
+    const outside = changed.every((c) => !GAME_CODE.test(c.replace(/ \((new|removed)\)$/, '')));
+    return ` Changed since the last pass: ${names}.` + (outside
+        ? ' None of these is game code: if they are notes, captures or logs, they would ship with the game — list them in .harnessignore (that also keeps verify fresh).'
+        : '');
+}
+export async function openItems(input, root, atStop = false) {
+    return (await openReport(input, root, atStop)).items;
+}
+export async function openReport(input, root, atStop = false) {
+    const state = readState(input);
+    let digests;
+    try {
+        digests = await gameDigests(root);
+    }
+    catch (e) {
+        if (e instanceof HashBudgetExceeded)
+            return { items: [], quality: null, tags: new Map() };
+        throw e;
+    }
+    const now = fingerprintOfDigests(digests);
+    const hashes = Object.fromEntries(digests.map((e) => [e.path, e.digest.slice(0, 16)]));
+    const v = verifyStatus(root, now);
+    if (v === 'pass' && state.verifiedFingerprint !== now)
+        writeState(input, { ...readState(input), verifiedFingerprint: now, verifiedFiles: hashes });
+    if (state.startFingerprint && state.startFingerprint === now)
+        return { items: [], quality: null, tags: new Map() };
+    const items = [];
+    const tags = new Map();
+    const add = (text, kind, fault = false) => { items.push(text); tags.set(text, { kind, fault }); };
+    const detail = v === 'stale' ? staleDetail(changedSince(state.verifiedFiles, hashes)) : '';
+    const existing = state.startGame === true && !completeGameScope(state, root);
+    const scoped = ' Validate the requested change and fix regressions it caused. Report unrelated or pre-existing failures and unobserved coverage explicitly; do not expand the task or call those gaps passing.';
+    if (v === 'missing')
+        add(`The game changed and was never verified. Run ${VERIFY}.${existing ? scoped : ' Each FAIL line names what broke.'}`, 'verify');
+    else if (v === 'stale')
+        add(`verify.json is stale: the files that ship changed after it ran.${detail} Run ${VERIFY}.${existing ? scoped : ''}`, 'verify', lastVerdict(root) === 'fail');
+    else if (v === 'fail')
+        add(existing
+            ? `The last verify FAILED.${scoped} After a fix, run ${VERIFY} again.`
+            : `The last verify FAILED. Fix what its FAIL lines name, then run ${VERIFY} again.`, 'verify', true);
+    else if (v === 'not_observed')
+        add(existing
+            ? `The last verify measured nothing (exit 2).${scoped} Add instrumentation needed for the requested check (skill funpixel-verify); whole-game coverage remains unproved.`
+            : `The last verify measured nothing (exit 2): declare the __FPX_* hooks (skill funpixel-verify), then run ${VERIFY}.`, 'verify');
+    if (v === 'pass' && !isGraybox(input, root, state)) {
+        const door = frontDoorItem(root, state, now, atStop ? lastAssistantText(input) : '');
+        if (door)
+            add(door, 'verify', /front-door verify FAILED/.test(door));
+    }
+    const quality = qualityReport(input, root, state, now, v === 'pass', atStop);
+    for (const t of quality.items)
+        add(t, quality.tags.get(t)?.kind ?? 'quality', quality.tags.get(t)?.fault === true);
+    if (!feedbackFiled(input, root, sessionStartMs(input))) {
+        add('File this session\'s feedback: one report_feedback call (skill funpixel-feedback) with what the kit was missing, what you worked around and which tool or skill helped or got in the way, plus the dev-log entries (steps, dead ends, lessons, decisions, with cost). ' +
+            'Without the Funpixel MCP, or when the call fails, write them to .funtools/devlog.jsonl in the game folder with your file tools, as that skill shows.', 'feedback');
+    }
+    return { items, quality, tags };
+}
+function lastVerdict(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, 'verify.json'), 'utf8')).verdict ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/plugins/cursor/hooks/memory.mjs

@@ -0,0 +1,92 @@
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { lessonLines, rankLessons } from './vendor/lessons/store.mjs';
+import { MOTIF_HEADING, motifLines, recentMotifs, recordMotif } from './vendor/lessons/motifs.mjs';
+import { explained, journalLine, noticeOutsideChanges, readJournal, recordAgentFile, trackedHashes, writeAgentFiles } from './vendor/memory/journal.mjs';
+import { decisionLine, liveDecisions, readDecisions } from './vendor/memory/decisions.mjs';
+import { gameDigests } from './lib.mjs';
+import { completeGameScope } from './scope.mjs';
+const genreOf = (root) => {
+    try {
+        return JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).metadata?.genre || 'any';
+    }
+    catch {
+        return 'any';
+    }
+};
+const motifBlock = (root) => {
+    const lines = motifLines(recentMotifs(root, 5));
+    return lines.length ? `## ${MOTIF_HEADING}\n${lines.join('\n')}` : '';
+};
+export function memoryContext(root) {
+    const genre = genreOf(root);
+    const lessons = lessonLines(rankLessons(root, genre), 3);
+    return [
+        lessons.length ? `## Lessons from earlier games (${genre})\n${lessons.join('\n')}` : '',
+        motifBlock(root),
+    ].filter(Boolean).join('\n\n');
+}
+export function motifReminder(root, state) {
+    if (state.motifsShown || !completeGameScope(state, root))
+        return null;
+    const block = motifBlock(root);
+    return block ? { text: `${block}\nUse this context when it helps the brief (skill funpixel-art).`, state: { ...state, motifsShown: true } } : null;
+}
+export function rememberMotif(root) {
+    try {
+        recordMotif(root);
+    }
+    catch { }
+}
+export const JOURNAL_SHOWN = 5;
+export const DECISIONS_SHOWN = 8;
+export function creatorContext(root) {
+    const parts = [];
+    const entries = explained(readJournal(root));
+    if (entries.length) {
+        const recent = entries.slice(-JOURNAL_SHOWN);
+        const earlier = entries.length - recent.length;
+        parts.push(`## What the person changed (.funtools/journal.jsonl, newest last${earlier ? `; ${earlier} earlier: \`npx @funpixel/tools journal\`` : ''})\n${recent.map(journalLine).join('\n')}\n`
+            + 'Keep these unless the person asks otherwise; re-read a file before you edit it. A detected entry is a fact about the files, not about intent: ask when it matters.');
+    }
+    const all = readDecisions(root);
+    const live = liveDecisions(all);
+    if (live.length) {
+        const shown = live.slice(-DECISIONS_SHOWN);
+        const more = live.length - shown.length;
+        parts.push(`## Decisions in force (design/decisions.md${more ? `; ${more} older live ones there` : ''})\n${shown.map(decisionLine).join('\n')}\n`
+            + 'Changing one is allowed: record the new choice with `npx @funpixel/tools decide "…" --because "…" --supersedes D<n>`, so the change is a decision and not a drift.');
+    }
+    return parts.join('\n\n');
+}
+export async function outsideChanges(root) {
+    try {
+        const e = await noticeOutsideChanges(root, new Date(), await gameDigests(root));
+        return e ? `## Changed since the last agent turn\n${journalLine(e)}\nRead these files before editing them; keep what looks deliberate, and ask the person when unsure. Recorded in .funtools/journal.jsonl.` : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function rememberAgentFiles(root) {
+    try {
+        writeAgentFiles(root, await trackedHashes(root, await gameDigests(root)));
+    }
+    catch { }
+}
+const EDIT_TOOLS = /^(Write|Edit|MultiEdit|NotebookEdit|write|fs_write|edit_file|write_file)$/;
+export function rememberAgentEdit(root, input) {
+    try {
+        if (!EDIT_TOOLS.test(String(input.tool_name ?? '')))
+            return;
+        const ti = input.tool_input ?? {};
+        const path = ti.file_path ?? ti.path ?? ti.notebook_path;
+        if (typeof path !== 'string' || !path)
+            return;
+        const abs = isAbsolute(path) ? path : join(input.cwd ?? root, path);
+        const rel = relative(root, abs).split(sep).join('/');
+        if (rel && !rel.startsWith('..'))
+            recordAgentFile(root, rel);
+    }
+    catch { }
+}