@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/goals/goals.js

@@ -0,0 +1,204 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseJourneyStep, stepMs } from "../journey/script.js";
+export const GOAL_VERDICTS = ['met', 'not met', 'blocked', 'not observed'];
+export const GOALS_DIR = join('test', 'goals');
+export const GOALS_RECORD = join('.funtools', 'goals.json');
+export const GOAL_SEATS = join('.funtools', 'goals');
+export const GOAL_DEFAULTS = { steps: 30, seconds: 120, loop: 6 };
+export const GOAL_MAX_STEPS = 38;
+const PLAYER_GOAL = /\b(player|players|you|newcomer|first[- ]time)\b|\b(reach(es)?|wins?|clears?|finish(es)?|escapes?|delivers?|collects?|survives?|beats?|finds?|gets? to|completes?|arrives?|solves?|first (input|control|tap|win|score|goal|move|press))\b/i;
+export const statesAPlayerGoal = (sentence) => PLAYER_GOAL.test(sentence);
+export function timeCapOf(sentence) {
+    const by = /\bby (\d+):(\d\d)\b/i.exec(sentence);
+    if (by)
+        return Number(by[1]) * 60 + Number(by[2]);
+    const m = /\b(?:within|in(?: under)?|under|before)\s+(\d+(?:\.\d+)?)\s*(ms|s|secs?|seconds?|min|mins?|minutes?)\b/i.exec(sentence);
+    if (!m)
+        return null;
+    const n = Number(m[1]), u = m[2].toLowerCase();
+    return u === 'ms' ? n / 1000 : u.startsWith('m') ? n * 60 : n;
+}
+export function goalId(sentence) {
+    const slug = sentence.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
+    return slug || 'goal';
+}
+export function goalsFrom(named) {
+    return named.filter(statesAPlayerGoal).map((sentence) => {
+        const t = timeCapOf(sentence);
+        return {
+            id: goalId(sentence), sentence, observe: [], route: [],
+            caps: { steps: GOAL_DEFAULTS.steps, seconds: t !== null ? Math.max(1, t) : GOAL_DEFAULTS.seconds },
+            loop: GOAL_DEFAULTS.loop, viewport: 'desktop', seed: 1,
+        };
+    });
+}
+export function checkGoal(raw) {
+    const problems = [];
+    if (!raw || typeof raw !== 'object')
+        return { problems: ['a goal is a JSON object'] };
+    if (typeof raw.id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,42}$/.test(raw.id))
+        problems.push('id: lower case, digits and -, up to 43');
+    if (typeof raw.sentence !== 'string' || !raw.sentence.trim())
+        problems.push('sentence: the GDD\'s behaviour test, verbatim');
+    const viewport = raw.viewport === 'phone' ? 'phone' : 'desktop';
+    const observe = Array.isArray(raw.observe) ? raw.observe.map(String) : [];
+    const routeText = Array.isArray(raw.route) ? raw.route.map(String) : [];
+    const expect = [];
+    if (observe.length) {
+        const m = parseJourneyStep(`mark goal ${observe.join(' ')}`, viewport === 'phone');
+        if (typeof m === 'string')
+            problems.push(`observe: ${m.replace(/^mark goal /, '')}`);
+        else if (m.kind === 'mark')
+            expect.push(...m.expect);
+    }
+    const route = [];
+    routeText.forEach((t, i) => {
+        const s = parseJourneyStep(t, viewport === 'phone');
+        if (typeof s === 'string')
+            problems.push(`route step ${i + 1}: ${s}`);
+        else if (s.kind === 'mark')
+            problems.push(`route step ${i + 1}: no marks in a route (a mark follows every step on its own)`);
+        else
+            route.push(s);
+    });
+    const steps = Math.min(GOAL_MAX_STEPS, Math.max(1, Number(raw.caps?.steps) || GOAL_DEFAULTS.steps));
+    const seconds = Math.min(600, Math.max(1, Number(raw.caps?.seconds) || GOAL_DEFAULTS.seconds));
+    const loop = Math.max(2, Number(raw.loop) || GOAL_DEFAULTS.loop);
+    if (problems.length)
+        return { problems };
+    return {
+        goal: { id: raw.id, sentence: raw.sentence.trim(), observe, route: routeText, ...(raw.repeat ? { repeat: true } : {}), caps: { steps, seconds }, loop, viewport, seed: Number.isInteger(raw.seed) ? raw.seed : 1 },
+        expect, route, problems,
+    };
+}
+export function readGoals(root) {
+    const dir = join(root, GOALS_DIR);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).sort().map((f) => {
+        const file = join(GOALS_DIR, f);
+        try {
+            return { file, ...checkGoal(JSON.parse(readFileSync(join(root, file), 'utf8'))) };
+        }
+        catch (e) {
+            return { file, problems: [`not JSON: ${e.message}`] };
+        }
+    });
+}
+export function goalJourney(g, route) {
+    const want = g.observe.join(' ');
+    const steps = [`mark s0${want ? ` ${want}` : ''}`];
+    if (!route.length)
+        return { steps, played: 0 };
+    let played = 0, ms = 0;
+    for (let i = 0; played < g.caps.steps && ms < g.caps.seconds * 1000; i++) {
+        if (i >= g.route.length && !g.repeat)
+            break;
+        const k = i % g.route.length;
+        played++;
+        ms += stepMs(route[k]);
+        steps.push(g.route[k], `mark s${played}${want ? ` ${want}` : ''}`);
+    }
+    return { steps, played };
+}
+const CLOCKS = /^(t|time|ms|now|frame|frames|tick|ticks|elapsed|clock|fps|dt|seconds?|played)(\.|$)|\.(t|time|ms|frame|elapsed|dt)$/i;
+export function signatureOf(counters) {
+    return JSON.stringify(Object.entries(counters).filter(([k]) => !CLOCKS.test(k)).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function classify(g, obs, run = {}) {
+    if (run.lost)
+        return { verdict: 'not observed', why: `${run.lost}: not evidence about the game` };
+    if (!g.observe.length)
+        return { verdict: 'not observed', why: 'the goal says nothing about how met is seen: write observe (e.g. "screen=won") in its file' };
+    if (run.routeless)
+        return { verdict: 'not observed', why: 'no route for the scripted player: write route steps, or let the agent seat play it' };
+    const capMs = g.caps.seconds * 1000;
+    const hit = obs.find((o) => o.observed && o.verdicts.length > 0 && o.verdicts.every((v) => v === 'pass'));
+    if (hit) {
+        const at = Math.round(hit.at_ms / 100) / 10;
+        return hit.at_ms <= capMs
+            ? { verdict: 'met', why: `met after step ${hit.step}, ${at} s of play (cap ${g.caps.seconds} s)`, step: hit.step, at_s: at }
+            : { verdict: 'not met', why: `met only after the cap: ${at} s, the sentence allows ${g.caps.seconds} s`, step: hit.step, at_s: at };
+    }
+    if (run.stepError)
+        return { verdict: 'blocked', why: `the player could not act: ${run.stepError}` };
+    let same = 1;
+    for (let i = 1; i < obs.length; i++) {
+        const a = obs[i - 1], b = obs[i];
+        same = a.observed && b.observed && a.signature === b.signature ? same + 1 : 1;
+        if (same >= g.loop)
+            return { verdict: 'blocked', why: `stuck: the state did not change for ${same} steps (steps ${b.step - same + 1}–${b.step}); a loop, not progress`, step: b.step };
+    }
+    const read = obs.filter((o) => o.observed && o.verdicts.length > 0 && o.verdicts.every((v) => v !== 'not_observed'));
+    if (read.length) {
+        const last = read.at(-1);
+        return { verdict: 'not met', why: `never met in ${last.step} step(s), ${Math.round(last.at_ms / 100) / 10} s (caps ${g.caps.steps} steps, ${g.caps.seconds} s)${last.got ? `; last read ${last.got}` : ''}`, step: last.step };
+    }
+    return { verdict: 'not observed', why: obs.some((o) => o.observed) ? `the state never carried ${g.observe.map((x) => x.split(/[<>=!]/)[0]).join(', ')}` : 'the page answers no __FPX_STATE__' };
+}
+export function combine(vs) {
+    const seen = vs.filter((v) => !!v && v !== 'not observed');
+    return seen.includes('blocked') ? 'blocked' : seen.includes('not met') ? 'not met' : seen.includes('met') ? 'met' : 'not observed';
+}
+export const seatDir = (id) => join(GOAL_SEATS, id);
+export const answerFile = (id) => join(seatDir(id), 'answer.json');
+export function goalSeatPrompt(g, gameDir, answer) {
+    return [
+        '# One goal, one bounded player',
+        '',
+        'You are a new player. You know only this goal, from the game\'s design document:',
+        '',
+        `> ${g.sentence}`,
+        '',
+        `Play it as a person would, through the screen alone: \`npx @funpixel/tools play ${gameDir} --viewport ${g.viewport}\` opens a round, \`npx @funpixel/tools play act "<step>"\` plays steps (tap, drag, press, hold, wait) and saves the screen; open each screenshot before the next step. Read no source, no design notes, no other file.`,
+        '',
+        '## The caps',
+        '',
+        `- at most ${g.caps.steps} acts and ${g.caps.seconds} s of play; stop at the first that runs out;`,
+        `- the same screen ${Math.min(g.loop, 3)} acts in a row while you try different things: you are stuck, stop;`,
+        '- stop as soon as the goal is met.',
+        '',
+        '## Your verdict (one of four)',
+        '',
+        '- **met**: you saw the goal happen inside the caps; name the screenshot that shows it;',
+        '- **not met**: you played to a cap and it never happened;',
+        '- **blocked**: you could not act, or were stuck (what you tried, the screenshot where it stopped);',
+        '- **not observed**: the game never got far enough to tell (it did not load, the round broke).',
+        '',
+        'A verdict names its evidence (screenshot files). A met with no screenshot is read as not observed.',
+        '',
+        '## Filing',
+        '',
+        `Write this JSON, and nothing else, to ${answer} with your file-writing tool, then reply \`filed\`:`,
+        '',
+        '```json',
+        `{ "goal": "${g.id}", "verdict": "met", "acts": 7, "seconds": 41, "evidence": ["005.png"], "why": "one sentence: what you did and what showed it" }`,
+        '```',
+        '',
+    ].join('\n');
+}
+const VERDICT_WORDS = { met: 'met', pass: 'met', 'not met': 'not met', not_met: 'not met', 'not-met': 'not met', fail: 'not met', blocked: 'blocked', stuck: 'blocked', 'not observed': 'not observed', not_observed: 'not observed', inconclusive: 'not observed', error: 'not observed' };
+export function readGoalAnswer(g, raw) {
+    if (raw === null)
+        return null;
+    let v;
+    try {
+        v = JSON.parse(raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1));
+    }
+    catch {
+        return { verdict: 'not observed', why: 'the seat filed no readable JSON' };
+    }
+    const verdict = VERDICT_WORDS[String(v?.verdict ?? '').toLowerCase().trim()];
+    if (!verdict)
+        return { verdict: 'not observed', why: `the seat's verdict "${v?.verdict}" is not one of ${GOAL_VERDICTS.join(' / ')}` };
+    const evidence = Array.isArray(v.evidence) ? v.evidence.map(String).filter(Boolean) : [];
+    const why = String(v.why ?? '').slice(0, 300);
+    const acts = Number(v.acts), secs = Number(v.seconds);
+    if (verdict !== 'not observed' && !evidence.length)
+        return { verdict: 'not observed', why: `the seat said ${verdict} and named no screenshot: a claim, not evidence` };
+    if (verdict === 'met' && ((Number.isFinite(acts) && acts > g.caps.steps) || (Number.isFinite(secs) && secs > g.caps.seconds))) {
+        return { verdict: 'not met', why: `met only past the caps (${Number.isFinite(acts) ? `${acts} acts` : ''}${Number.isFinite(secs) ? ` ${secs} s` : ''}; caps ${g.caps.steps} acts, ${g.caps.seconds} s): ${why}` };
+    }
+    return { verdict, why: `${why}${evidence.length ? ` (${evidence.slice(0, 3).join(', ')})` : ''}`, ...(Number.isFinite(acts) ? { step: acts } : {}), ...(Number.isFinite(secs) ? { at_s: secs } : {}) };
+}

package/dist/goals/run.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { designDoc } from "../gdd/doc.js";
+import { namedTests } from "../gdd/design.js";
+import { checkJourney } from "../journey/script.js";
+import { replay } from "../journey/run.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { answerFile, classify, combine, goalJourney, goalSeatPrompt, goalsFrom, GOALS_DIR, GOALS_RECORD, readGoalAnswer, readGoals, seatDir, signatureOf, } from "./goals.js";
+const defaultBot = async (root, j) => {
+    const c = checkJourney(j);
+    if (!c.journey)
+        return c.problems.join('; ');
+    return replay({ root, journey: c.journey, steps: c.steps });
+};
+export function observationsOf(run) {
+    return run.marks.map((m) => ({
+        step: m.step, at_ms: m.at_ms, observed: m.state_observed, verdicts: m.expect.map((e) => e.verdict), signature: signatureOf(m.counters),
+        got: m.expect.length ? m.expect.map((e) => `${e.field}=${e.got === undefined ? '—' : JSON.stringify(e.got)}`).join(' ') : undefined,
+    }));
+}
+export async function seedGoals(root) {
+    const named = namedTests(designDoc(root)?.text ?? '');
+    const have = new Set(readGoals(root).map((r) => r.goal?.sentence ?? ''));
+    const haveIds = new Set(readGoals(root).map((r) => r.goal?.id ?? ''));
+    const written = [];
+    for (const g of goalsFrom(named)) {
+        if (have.has(g.sentence) || haveIds.has(g.id))
+            continue;
+        const file = join(GOALS_DIR, `${g.id}.json`);
+        if (existsSync(join(root, file)))
+            continue;
+        await mkdir(join(root, GOALS_DIR), { recursive: true });
+        await writeFile(join(root, file), JSON.stringify({ ...g, observe: [], route: [], _write: 'observe: how met is seen in __FPX_STATE__ ("screen=won"); route: journey steps a scripted player tries ("tap 0.5 0.6", "wait 500"); repeat: true replays it to the caps' }, null, 2) + '\n');
+        written.push(file);
+    }
+    return written;
+}
+export async function runGoals(root, opts = {}) {
+    const written = await seedGoals(root);
+    const bot = opts.bot === undefined ? defaultBot : opts.bot;
+    const fp = await fingerprint(root).then((f) => f.fingerprint).catch(() => null);
+    const goals = [];
+    for (const r of readGoals(root)) {
+        if (!r.goal) {
+            goals.push({ id: r.file, file: r.file, sentence: '', caps: { steps: 0, seconds: 0 }, bot: null, agent: null, verdict: 'not observed', problems: r.problems });
+            continue;
+        }
+        const g = r.goal;
+        const seat = join(root, seatDir(g.id));
+        await mkdir(seat, { recursive: true });
+        await writeFile(join(seat, 'seat.md'), goalSeatPrompt(g, opts.gameDir ?? root, join(root, answerFile(g.id))));
+        const ans = join(root, answerFile(g.id));
+        const agent = readGoalAnswer(g, existsSync(ans) ? readFileSync(ans, 'utf8') : null);
+        let botR = null;
+        if (!g.observe.length)
+            botR = classify(g, []);
+        else if (!r.route.length)
+            botR = null;
+        else if (bot) {
+            const j = goalJourney(g, r.route);
+            const run = await bot(root, { name: `goal-${g.id}`.slice(0, 48), viewport: g.viewport, seed: g.seed, steps: j.steps });
+            if (typeof run === 'string')
+                botR = { verdict: 'not observed', why: `the scripted player could not run: ${run}` };
+            else {
+                const stepError = run.step_errors[0] ? `step ${run.step_errors[0].n} (${run.step_errors[0].step}): ${run.step_errors[0].error}` : undefined;
+                botR = { ...classify(g, observationsOf(run), { stepError, lost: run.browser_lost || undefined }), run: `.funtools/journeys/${run.journey}/${run.run}` };
+            }
+        }
+        goals.push({ id: g.id, file: r.file, sentence: g.sentence, caps: g.caps, bot: botR, agent, verdict: combine([botR?.verdict, agent?.verdict]) });
+    }
+    const record = { at: new Date().toISOString(), fingerprint: fp, goals, written };
+    await mkdir(dirname(join(root, GOALS_RECORD)), { recursive: true });
+    await writeFile(join(root, GOALS_RECORD), JSON.stringify(record, null, 2) + '\n');
+    return record;
+}
+export function goalCounts(rec) {
+    const out = { met: 0, 'not met': 0, blocked: 0, 'not observed': 0 };
+    for (const g of rec.goals)
+        out[g.verdict]++;
+    return out;
+}
+export function readGoalsRecord(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, GOALS_RECORD), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/greenlight/ambition.js

@@ -0,0 +1,42 @@
+import { designDoc, section } from "../gdd/doc.js";
+import { contentLine, contentList, oneLevelScope } from "../gdd/size.js";
+import { readBible } from "./bible.js";
+import { readLock } from "./lock.js";
+const CODE_BUILT = /code mesh|built in code|code-built|in code \(|primitives?\b|placeholder|stand-?ins?\b|references only|shapes for now|for now\b/i;
+const REFUSED = /\b(not|never|no|avoid|instead of)\b[^.;:]{0,12}["'“`]?\s*(primitives?|placeholder|stand-?ins?|shapes for now|code-built)/i;
+export function ambitionOf(root) {
+    const flags = [], read = [];
+    const bible = readBible(root);
+    const lock = readLock(root);
+    const doc = designDoc(root);
+    if (bible) {
+        const standIns = bible.routes.filter((r) => r.route === 'stand-in' || r.route === 'unknown' || (r.route === 'procedural' && !r.proof));
+        read.push(`style bible: ${bible.routes.length} asset route(s), ${bible.targets.filter((t) => t.exists).length} target frame(s) on disk`);
+        for (const r of standIns)
+            flags.push(`${r.asset}${r.hero ? ' (a hero)' : ''}: ${r.note}`);
+        if (bible.targets.filter((t) => t.exists).length < 2)
+            flags.push('fewer than two real target frames');
+    }
+    else if (doc) {
+        const track = section(doc.text, 'Track');
+        const hits = doc.text.split('\n').filter((l) => CODE_BUILT.test(l) && !/^\s*#/.test(l) && !(track && track.includes(l)) && !REFUSED.test(l)).map((l) => l.replace(/^\s*[-*|]\s*/, '').trim().slice(0, 140));
+        read.push(`no style bible; read ${doc.rel}'s own words on how assets are made`);
+        for (const h of hits.slice(0, 4))
+            flags.push(`made from code or left as a reference, with nothing proving the style: "${h}"`);
+    }
+    const content = doc ? contentList(doc.text) : null;
+    if (content?.length) {
+        read.push(`content list: ${contentLine(content)}`);
+        if (oneLevelScope(doc.text, content))
+            flags.push('the content list sizes the game at one area or level: a full game names its areas, kinds, a climax and endings (if one level is the choice, say so in the list)');
+    }
+    else if (doc)
+        read.push('no content list yet (the GDD\'s `## Content list`): nothing names what play must reach');
+    if (lock)
+        read.push(`locked at ${lock.version} on ${lock.date}${lock.override ? ` (${lock.override})` : ''}`);
+    if (!read.length)
+        return { state: 'not_observed', flags, read: ['no style bible, no design document'] };
+    if (flags.length)
+        return { state: 'not_yet', flags, read };
+    return lock ? { state: 'ambitious', flags, read } : { state: 'not_observed', flags, read: [...read, 'the owner has not locked the plan yet'] };
+}

package/dist/greenlight/bible.js

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sections, targetsOf } from "../playtest/fidelity.js";
+import { GREENLIGHT_DIR } from "./pitches.js";
+export const BIBLE_FILE = join(GREENLIGHT_DIR, 'style-bible.md');
+const STAND_IN = /\bprimitives?\b|placeholder|stand-?ins?\b|for now\b|\btemporary\b|\btodo\b|gr[ae]y-?box|\bboxes and\b|\bcapsules?\b|\bcubes? (for|as)\b/i;
+const PROCEDURAL = /procedural|shader|\bsdf\b|built in code|code[- ]built|code mesh|in code\b|instanced|generated in code|noise|l-system|voxel/i;
+const GEN_3D = /generate_3d_model|generated 3d|\.glb\b|hunyuan|meshy|model3d|character library|get_character|restyle_character/i;
+const GEN_2D = /generate_image|generate_sprite|generate_spritesheet|generated (2d|sprite|image|art|texture|sheet)|sprite ?sheet|gpt-image/i;
+const AUTHORED = /authored|hand-?made|hand-?drawn|blender|modell?ed by|kitbash|poly ?haven|cc0|kenney|asset pack|drawn\b/i;
+const HERO = /hero|player|vehicle|character|rival|enemy|enemies|boss|mount|avatar|racer|skiff|kart|ship|cast/i;
+const IMAGE = /[\w./-]+\.(png|jpe?g|webp)/i;
+const cells = (row) => row.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+const prose = (body) => (body.split('\n').filter((l) => !/^\s*\|/.test(l)).join(' ').match(/[A-Za-zÀ-ÿ0-9'’#-]+/g) ?? []).length;
+export function routeOf(how) {
+    if (STAND_IN.test(how))
+        return 'stand-in';
+    if (GEN_3D.test(how))
+        return 'generated-3d';
+    if (GEN_2D.test(how))
+        return 'generated-2d';
+    if (AUTHORED.test(how))
+        return 'authored';
+    if (PROCEDURAL.test(how))
+        return 'procedural';
+    return 'unknown';
+}
+function routesOf(root, text) {
+    const lines = text.replace(/\r/g, '').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (!/^\s*\|.*\|\s*$/.test(lines[i]) || !/^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1] ?? ''))
+            continue;
+        const head = cells(lines[i]).map((c) => c.toLowerCase());
+        const col = (re) => head.findIndex((c) => re.test(c));
+        const asset = col(/asset|actor|piece|what/), how = col(/route|made|how|source/);
+        if (asset < 0 || how < 0)
+            continue;
+        const role = col(/role|kind|class/), proof = col(/proof|study|evidence/);
+        const out = [];
+        for (let j = i + 1; j < lines.length && /^\s*\|.*\|\s*$/.test(lines[j]); j++) {
+            if (/^\s*\|[\s:|-]+\|\s*$/.test(lines[j]))
+                continue;
+            const c = cells(lines[j]);
+            const at = (k) => (k >= 0 ? (c[k] ?? '').replace(/`/g, '').trim() : '');
+            const words = at(how);
+            const proofCell = at(proof) || words;
+            const file = IMAGE.exec(proofCell)?.[0] ?? null;
+            const proven = !!file && existsSync(join(root, file));
+            const route = routeOf(words);
+            const hero = HERO.test(`${at(role)} ${at(asset)}`) && !/background|sky|ground|terrain|scenery|prop|ui|hud|font|icon/i.test(at(role));
+            let note;
+            if (route === 'procedural' && !proven)
+                note = file ? `its proof ${file} is not in the game` : 'procedural with no proof: render a study from the engine and name it in the Proof column';
+            if (route === 'procedural' && proven && hero)
+                note = 'a procedural hero, proven: the creator\'s call (environments procedural from one source, heroes as models on the same simulation, is the other option)';
+            if (route === 'stand-in')
+                note = 'a stand-in, not a route: name how the finished asset is made';
+            if (route === 'unknown')
+                note = 'say how it is made: generated (2D or 3D), authored, or procedural with a proof';
+            out.push({ asset: at(asset), role: at(role), route, how: words, proof: proven ? file : null, hero, ...(note ? { note } : {}) });
+        }
+        if (out.length)
+            return out;
+    }
+    return [];
+}
+const UI_HEADING = /^(the )?(ui|user interface|interface)\b/i;
+function screensOf(root, text) {
+    const out = [];
+    for (const m of text.matchAll(/^\s*[-*]?\s*\**([a-z][a-z -]{1,24}?)\s+(?:mock-?up|target)\**\s*:\**\s*(.+)$/gim)) {
+        const screen = m[1].trim().toLowerCase().replace(/^the\s+/, '');
+        const path = /[\w./-]+\.(png|jpe?g|webp|html)/i.exec(m[2])?.[0];
+        if (!path || out.some((x) => x.screen === screen))
+            continue;
+        out.push({ screen, path, exists: existsSync(join(root, path)) });
+    }
+    return out;
+}
+export function parseBible(root, text, file = BIBLE_FILE) {
+    const secs = sections(text);
+    const sec = (re) => secs.filter((s) => new RegExp(re.source, 'i').test(s.title));
+    const words = (re) => Math.max(0, ...sec(re).map((s) => prose(s.body)));
+    const direction = /^\s*\**direction\**\s*:\**\s*(.+)$/im.exec(text)?.[1].replace(/\*+/g, '').trim() ?? '';
+    const paletteSec = sec(/palette|colou?r/).map((s) => s.body).join('\n');
+    const palette = new Set((paletteSec || text).match(/#[0-9a-f]{6}\b/gi) ?? []).size;
+    const dirSec = sec(/directions? (tried|explored)|explorations?|visual directions?/);
+    const directionsTried = Math.max(0, ...dirSec.map((s) => Math.max(s.body.split('\n').filter((l) => /^\s*\|/.test(l) && !/^\s*\|[\s:|-]+\|\s*$/.test(l)).length - 1, (s.body.match(/^\s*(?:[-*]|\d+[.)])\s+\S/gm) ?? []).length)));
+    const routes = routesOf(root, text);
+    const targets = targetsOf(text).map((t) => { const f = IMAGE.exec(t.target)?.[0]; return { ...t, exists: !!f && existsSync(join(root, f)) }; });
+    const screens = screensOf(root, text);
+    const hudPath = screens.find((x) => x.screen === 'hud')?.path ?? '';
+    const s = { shape: words(/shape/), material: words(/material|light/), hud: words(/\bhud\b|interface|\bui\b/), ui: Math.max(0, ...secs.filter((x) => UI_HEADING.test(x.title)).map((x) => prose(x.body))), directions: dirSec.length ? words(/directions? (tried|explored)|explorations?|visual directions?/) || directionsTried : 0 };
+    const problems = [], notes = [];
+    if (!direction)
+        problems.push('no named direction (`**Direction:** <name> — one sentence`)');
+    if (palette < 3)
+        problems.push(`palette: ${palette} colour(s) with a hex; name at least three, each with the role it plays`);
+    if (s.shape < 12)
+        problems.push('shape language: missing or under a sentence (silhouettes, corners, proportions, what reads at play size)');
+    if (s.material < 12)
+        problems.push('material and light: missing or under a sentence (surfaces, the light, the grade)');
+    if (s.hud < 12)
+        problems.push('HUD direction: missing or under a sentence (how it sits in the world, the type, how dense)');
+    if (!routes.length)
+        problems.push('no asset-routes table (| Asset | Role | Route | Proof |): how every asset gets made is the bible\'s one binding line');
+    for (const r of routes)
+        if (r.route === 'stand-in' || r.route === 'unknown' || (r.route === 'procedural' && !r.proof))
+            problems.push(`${r.asset || 'an asset'}: ${r.note}`);
+    for (const r of routes)
+        if (r.route === 'procedural' && r.proof && r.hero)
+            notes.push(`${r.asset}: ${r.note}`);
+    if (directionsTried < 2)
+        notes.push(`${directionsTried} visual direction(s) recorded: try several and push a plain one up with a concrete note before accepting the first image`);
+    const real = targets.filter((t) => t.exists);
+    if (!targets.length)
+        problems.push('no target-frames table (| Moment | Target | Intent | Game frame |): one frame per phase of play');
+    else if (real.length < targets.length)
+        problems.push(`${targets.length - real.length} of ${targets.length} target frame(s) not found on disk`);
+    const all = targets.map((t) => `${t.moment} ${t.intent}`).join(' ');
+    if (targets.length && !/establish|wide|vista|overview|whole (track|level|world)/i.test(all))
+        notes.push('no establishing (wide) frame among the targets: reference-match rounds compare that one first');
+    if (targets.length && !/player[- ]eye|player'?s view|chase|play view|in play|over the shoulder|cockpit|first[- ]person/i.test(all))
+        notes.push('no player-eye frame among the targets: the view the player actually holds is the second comparison');
+    if (!hudPath)
+        notes.push('no HUD mockup named (`**HUD mockup:** design/greenlight/hud.png`)');
+    for (const x of screens)
+        if (!x.exists)
+            problems.push(`${x.screen === 'hud' ? 'HUD mockup' : `${x.screen} target`} ${x.path} not found`);
+    if (s.ui < 12)
+        notes.push('no UI section: an offer — without one the HUD and screens tend to keep the scaffold\'s dark plates; `## UI` names the panel material and edge from the world, a display and a body face, one icon family, colour roles and motion (skill funpixel-art, references/ui.md)');
+    if (!screens.some((x) => x.screen === 'title'))
+        notes.push('no title target: an offer — a title drawn in the game\'s style (`**Title target:** design/first-look/ui-title.png`) gives the UI fidelity seat something to hold the title to');
+    return { file, direction, palette, sections: s, directionsTried, routes, targets, hudMockup: hudPath ? { path: hudPath, exists: existsSync(join(root, hudPath)) } : null, screens, problems, notes };
+}
+export function readBible(root) {
+    const f = join(root, BIBLE_FILE);
+    return existsSync(f) ? parseBible(root, readFileSync(f, 'utf8')) : null;
+}

package/dist/greenlight/lock.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { designDoc, sha256, withoutLiving, withoutVision } from "../gdd/doc.js";
+import { addDecision } from "../memory/decisions.js";
+import { BIBLE_FILE, readBible } from "./bible.js";
+import { GREENLIGHT_DIR, PITCHES_FILE } from "./pitches.js";
+import { pickProblems, wowPicks } from "../wow/picks.js";
+import { MOVES } from "../wow/catalogue.js";
+export const LOCK_FILE = join(GREENLIGHT_DIR, 'lock.json');
+const hashOf = (p) => (existsSync(p) ? sha256(readFileSync(p, 'latin1')) : '');
+const isDoc = (root, f) => /^design\/(GDD|README)\.md$/.test(f) && existsSync(join(root, f));
+const lockedHash = (root, f) => (isDoc(root, f) ? sha256(withoutLiving(readFileSync(join(root, f), 'latin1'))) : hashOf(join(root, f)));
+const matches = (root, f, h) => lockedHash(root, f) === h || (isDoc(root, f) && sha256(withoutVision(readFileSync(join(root, f), 'latin1'))) === h);
+export function readLock(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, LOCK_FILE), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function drift(root, lock) {
+    return Object.entries(lock.files).filter(([f, h]) => !matches(root, f, h)).map(([f]) => f);
+}
+export function lockDesign(root, o, now = new Date()) {
+    if (!/^v\d+(\.\d+)*$/i.test(o.version))
+        throw new Error(`--version ${o.version}: a version like v1.0`);
+    const doc = designDoc(root);
+    if (!doc)
+        throw new Error('no design document (design/GDD.md) to lock');
+    const bible = readBible(root);
+    const targets = (bible?.targets ?? []).filter((t) => t.exists).map((t) => ({ moment: t.moment, file: /[\w./-]+\.(png|jpe?g|webp)/i.exec(t.target)[0] }));
+    const files = { [doc.rel]: lockedHash(root, doc.rel) };
+    for (const f of [BIBLE_FILE, PITCHES_FILE, ...targets.map((t) => t.file)])
+        if (existsSync(join(root, f)))
+            files[f] = hashOf(join(root, f));
+    const lock = {
+        version: o.version, date: now.toISOString().slice(0, 10), files, targets,
+        ...(o.override?.trim() ? { override: o.override.trim() } : {}),
+        wow: (() => { const picks = wowPicks(doc.text); return { picks, problems: pickProblems(picks, (id) => MOVES.has(id)).filter((p) => p.level === 'warn').map((p) => p.text) }; })(),
+    };
+    const because = o.override?.trim() ? `the owner agreed the plan: ${o.override.trim()}` : 'the owner agreed the plan';
+    const d = addDecision(root, { choice: `Design locked at ${o.version} (${targets.length} target frame(s))`, over: 'building on a plan nobody agreed', because }, now);
+    lock.decision = d.id;
+    mkdirSync(dirname(join(root, LOCK_FILE)), { recursive: true });
+    writeFileSync(join(root, LOCK_FILE), JSON.stringify(lock, null, 2) + '\n');
+    return lock;
+}

package/dist/greenlight/match.js

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BIBLE_FILE } from "./bible.js";
+import { drift, readLock } from "./lock.js";
+const PANEL = new URL('../../panel/', import.meta.url);
+export function lockedPlan(root, gdd) {
+    const lock = readLock(root);
+    const bible = join(root, BIBLE_FILE);
+    if (!lock || !existsSync(bible))
+        return null;
+    const section = readFileSync(new URL('reference-match.md', PANEL), 'utf8').replaceAll('{{VERSION}}', lock.version).replaceAll('{{DATE}}', lock.date);
+    return { text: `${readFileSync(bible, 'utf8')}\n\n${gdd}`, lock, moved: drift(root, lock), section };
+}
+export function withMatch(prompt, locked) {
+    if (!locked)
+        return prompt;
+    const at = prompt.lastIndexOf('\n\n## Filing');
+    return at < 0 ? `${prompt}\n\n${locked.section}` : `${prompt.slice(0, at)}\n\n${locked.section.trim()}${prompt.slice(at)}`;
+}

package/dist/greenlight/md.js

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export const anchor = (s) => s.toLowerCase().replace(/<[^>]+>/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60);
+export const fromDesign = (p) => (p.startsWith('design/') ? p.slice('design/'.length) : `../${p.replace(/^\.\//, '')}`);
+const PIC = /(?<![\w/("])((?:design|assets|public|src)\/[\w./-]+\.(?:png|jpe?g|webp))/g;
+const ONE_PIC = /^(?:design|assets|public|src)\/[\w./-]+\.(?:png|jpe?g|webp)$/;
+function inline(s, root) {
+    let t = esc(s);
+    t = t.replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g, (_, alt, src) => `<img src="${src.startsWith('http') ? src : fromDesign(src)}" alt="${alt}" loading="lazy">`);
+    t = t.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, txt, href) => `<a href="${/^(https?:|#)/.test(href) ? href : fromDesign(href)}">${txt}</a>`);
+    t = t.replace(/`([^`]+)`/g, (_, c) => (ONE_PIC.test(c) && existsSync(join(root, c)) ? picture(c) : `<code>${c}</code>`));
+    t = t.replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>').replace(/(?<![*\w])\*([^*\n]+)\*(?![*\w])/g, '<i>$1</i>');
+    t = t.replace(PIC, (m) => (existsSync(join(root, m)) ? picture(m) : m));
+    return t;
+}
+const picture = (p) => `<a class="pic" href="${fromDesign(p)}"><img src="${fromDesign(p)}" alt="${esc(p.replace(/^.*\//, ''))}" loading="lazy"></a>`;
+export function markdown(md, root, o = {}) {
+    const lines = md.replace(/\r/g, '').split('\n');
+    const out = [], toc = [];
+    const shift = o.shift ?? 0;
+    const cells = (l) => l.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+    let i = 0;
+    while (i < lines.length) {
+        const l = lines[i];
+        if (/^```/.test(l)) {
+            const body = [];
+            for (i++; i < lines.length && !/^```/.test(lines[i]); i++)
+                body.push(lines[i]);
+            out.push(`<pre><code>${esc(body.join('\n'))}</code></pre>`);
+            i++;
+            continue;
+        }
+        const h = /^(#{1,6})\s+(.+?)\s*#*$/.exec(l);
+        if (h) {
+            const level = Math.min(6, h[1].length + shift), title = inline(h[2], root), id = anchor(h[2]);
+            toc.push({ id, title: h[2], level: h[1].length });
+            out.push(`<h${level} id="${id}">${title}</h${level}>`);
+            i++;
+            continue;
+        }
+        if (/^\s*\|.*\|\s*$/.test(l)) {
+            const rows = [];
+            for (; i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i]); i++)
+                if (!/^\s*\|[\s:|-]+\|\s*$/.test(lines[i]))
+                    rows.push(cells(lines[i]));
+            const [head, ...body] = rows;
+            out.push(`<div class="table"><table><thead><tr>${head.map((c) => `<th>${inline(c, root)}</th>`).join('')}</tr></thead><tbody>${body.map((r) => `<tr>${r.map((c) => `<td>${inline(c, root)}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`);
+            continue;
+        }
+        if (/^\s*([-*+]|\d+[.)])\s+/.test(l)) {
+            const ordered = /^\s*\d/.test(l), items = [];
+            for (; i < lines.length && /^\s*([-*+]|\d+[.)])\s+/.test(lines[i]); i++) {
+                let item = lines[i].replace(/^\s*([-*+]|\d+[.)])\s+/, '');
+                while (i + 1 < lines.length && /^\s{2,}\S/.test(lines[i + 1]) && !/^\s*([-*+]|\d+[.)])\s+/.test(lines[i + 1]))
+                    item += ` ${lines[++i].trim()}`;
+                items.push(`<li>${inline(item, root)}</li>`);
+            }
+            out.push(ordered ? `<ol>${items.join('')}</ol>` : `<ul>${items.join('')}</ul>`);
+            continue;
+        }
+        if (/^>\s?/.test(l)) {
+            const q = [];
+            for (; i < lines.length && /^>\s?/.test(lines[i]); i++)
+                q.push(lines[i].replace(/^>\s?/, ''));
+            out.push(`<blockquote>${inline(q.join(' '), root)}</blockquote>`);
+            continue;
+        }
+        if (!l.trim()) {
+            i++;
+            continue;
+        }
+        const para = [];
+        for (; i < lines.length && lines[i].trim() && !/^(#{1,6}\s|```|\s*\||\s*([-*+]|\d+[.)])\s|>)/.test(lines[i]); i++)
+            para.push(lines[i].trim());
+        if (para.length)
+            out.push(`<p>${inline(para.join(' '), root)}</p>`);
+        else
+            i++;
+    }
+    return { html: out.join('\n'), toc };
+}