@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/spec/scaffold.js

@@ -0,0 +1,457 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { TEMPLATES } from "../commands/init.js";
+import { MANIFEST, sha } from "../managed.js";
+import { codeHashes, FLOW_FILE } from "../flow/flow.js";
+import { defaultPipeline, PIPELINE_FILE, readPipeline } from "../pipeline/pipeline.js";
+import { playFloor } from "../sim/judge.js";
+import { findNumbers, rewire, settleIds } from "./extract.js";
+import { fitPreset, presetFor } from "./presets.js";
+import { sectionsFor } from "./sections.js";
+import { clock, OPEN_FILE, specRooms } from "./rooms.js";
+import { SPEC_DIR } from "./tunables.js";
+import { unityProject } from "../gen/unity.js";
+const LAYER_SRC = ['src/tune.ts', 'src/chapters.ts', 'src/probe-rooms.ts', 'src/room-map.tsx'];
+const SKIP_SCAN = new Set([...LAYER_SRC, 'src/probe-kit.ts', 'src/probe-human.ts', 'src/levels.ts']);
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+const read = (p) => { try {
+    return readFileSync(p, 'utf8');
+}
+catch {
+    return null;
+} };
+function write(root, rel, text, wrote) {
+    mkdirSync(dirname(join(root, rel)), { recursive: true });
+    writeFileSync(join(root, rel), text);
+    wrote.push(rel);
+}
+export function frameworkOf(root) {
+    const m = readJson(join(root, MANIFEST));
+    if (typeof m?.framework === 'string')
+        return m.framework;
+    return existsSync(join(root, 'src', 'camera-rig.ts')) ? 'three-world' : existsSync(join(root, 'src', 'world-hud.ts')) && /three/.test(read(join(root, 'package.json')) ?? '') ? 'three' : 'pixi';
+}
+function sourceFiles(root) {
+    const out = [];
+    const walk = (rel, depth) => {
+        let names = [];
+        try {
+            names = readdirSync(join(root, rel)).sort();
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = `${rel}/${n}`;
+            let st;
+            try {
+                st = statSync(join(root, p));
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth < 4 && !n.startsWith('.') && n !== 'node_modules')
+                    walk(p, depth + 1);
+            }
+            else if (/\.tsx?$/.test(n) && !/\.d\.ts$/.test(n) && !SKIP_SCAN.has(p))
+                out.push(p);
+        }
+    };
+    walk('src', 0);
+    return out;
+}
+const unitOf = (key) => (/(^|_)seconds$|(^|_)secs?$|Time$|Ms$/.test(key) ? (/Ms$/.test(key) ? 'ms' : 's') : undefined);
+export function tunablesJson(found, name, date) {
+    const groups = {};
+    for (const f of found) {
+        const unit = unitOf(f.key);
+        (groups[f.group] ??= {})[f.key] = { default: f.value, ...(unit ? { unit } : {}), ...(f.why ? { why: f.why } : {}), tests: [], source: `${f.file}:${f.line} ${f.prop ? `${f.name}.${f.prop}` : f.name}` };
+    }
+    return JSON.stringify({ version: 1, date, note: `Every number ${name} plays by, one source of truth: src/tune.ts loads this file (tune('group.name'), group('name')), the rooms in rooms.json lay their own numbers over these defaults, and the spec's files cite ids, never values. Give each a unit, a range and a why; name the tests that pin it. \`funtools spec lint\` checks it against src/.`, groups }, null, 2) + '\n';
+}
+export function roomsJson(chapters, date) {
+    const flat = chapters.flatMap((c) => c.rooms);
+    const exitOf = (id) => { const i = flat.findIndex((r) => r.id === id); return flat[i + 1]?.id ?? 'end'; };
+    return JSON.stringify({
+        version: 1, date,
+        note: 'The game\'s rooms in order: src/chapters.ts loads this file and src/levels.ts saves where the player got to. par is the seconds a good first run takes (the pars add up to the game\'s length; `funtools rooms` measures them with bots); exit is the room this one opens onto; waves is the rounds won in a row to clear it, each from a checkpoint; tune is the room\'s numbers over tunables.json. A room is built only once the room before it passes (`funtools rooms open <id>`); the first is the slice.',
+        chapters: chapters.map((c) => ({ id: c.id, name: c.name, rooms: c.rooms.map((r) => ({ id: r.id, name: r.name, ...(r.slice ? { slice: true } : {}), par: r.par, exit: exitOf(r.id), waves: r.waves, teaches: r.teaches, beat: r.beat, tune: r.tune })) })),
+    }, null, 2) + '\n';
+}
+const cite = (ids) => ids.map((i) => `\`${i}\``).join(', ');
+export function sectionTexts(o) {
+    const rooms = o.chapters.flatMap((c) => c.rooms);
+    const total = rooms.reduce((s, r) => s + r.par, 0);
+    const files = sectionsFor(o.tier);
+    const byGroup = new Map();
+    for (const f of o.found)
+        byGroup.set(f.group, [...(byGroup.get(f.group) ?? []), f]);
+    const ids = (g) => (byGroup.get(g) ?? []).map((f) => `${f.group}.${f.key}`);
+    const ruleGroups = [...byGroup.keys()].filter((g) => !['juice', 'rig', 'budget'].includes(g));
+    const slice = rooms[0];
+    const out = {};
+    const table = (rows) => rows.map((r) => `| ${r.join(' | ')} |`).join('\n');
+    out['README.md'] = `# ${o.name}: the build contract (spec v0.1)
+
+This folder is what a building agent works from (the ${o.tier} tier of the plan, written by \`funtools spec init\` on ${o.date}). The GDD (\`../GDD.md\`) says what the game is and why; this folder says what to build, in numbers and data the game loads. When the two disagree, fix one of them the same day.
+
+## Read this first
+
+1. \`../decisions.md\`: every decision with what it beat and why (\`funtools decide\`). Do not reverse one without a new entry.
+2. \`tunables.json\`: every number the game plays by, by id (\`group.name\`). The game loads it (\`src/tune.ts\`); spec files cite ids and never repeat values.
+3. \`rules.md\`: the simulation, in rules, each citing its tunables.
+4. \`rooms.json\`: every room in order, with its par, its exit and its numbers (\`src/chapters.ts\` loads it).
+5. Then the file for the lane you are in (the table below).
+
+## Slice first
+
+The slice is room \`${slice.id}\` (${slice.name}). **Nothing in a later room is built until the room before it passes its gates**: the slice's (\`funtools check\`: build, tests, verify, the world; \`funtools sim\`: the challenge bites) and every room's own (\`funtools rooms\`: a careful player clears it on 5 seeds within its par). \`funtools rooms open <id>\` opens the next room and refuses while the one before has not passed; only the owner can release a room early (\`funtools rooms open <id> --by owner\`). A room changed before it was opened is named by \`funtools spec lint\` and holds the expand stage.
+
+## The length
+
+The pars add up to ${clock(total)} against the play floor of ${clock(o.floor)} (\`funtools spec lint\` keeps the sum honest; \`funtools rooms\` measures each room).
+
+## The files
+
+${table([['File', 'Covers'], ['---', '---'], ...files.map((s) => [`\`${s.file}\``, s.covers])])}
+
+## Ids
+
+A tunable is \`group.name\` (\`${o.found[0] ? `${o.found[0].group}.${o.found[0].key}` : 'rules.goal'}\`); a room is its id in rooms.json (\`${slice.id}\`). Ids are never reused. A number appears in this folder only in tunables.json: everywhere else, cite the id.
+
+## Integrity
+
+\`funtools spec lint\` checks that every id a file or the code cites exists, that the code reads every tunable and types none of their numbers, that every room has a par and an exit, that the pars reach the floor and that the sections this tier needs are written. Run it after any edit; it runs in the gates.
+`;
+    out['rules.md'] = `# The rules
+
+The simulation, engine-free (\`src/rules.ts\`): the renderer draws its state, the tests and the probes play it. Every number is a tunable; this file cites ids.
+
+## The round
+
+${o.rulesHeader || 'The round as the starter plays it.'}
+
+## The numbers each rule reads
+
+${table([['Group', 'Tunables'], ['---', '---'], ...ruleGroups.map((g) => [g, cite(ids(g))])])}
+
+## Rules to write as the game grows
+
+<!-- write: one rule per line, an id each (RULE-…), the tunables it reads and the test that pins it. -->
+`;
+    const tuneLine = (r) => (Object.keys(r.tune).length ? Object.keys(r.tune).map((k) => `\`${k}\``).join(', ') : 'the defaults');
+    out['difficulty.md'] = `# Fun and difficulty
+
+The curve, room by room: what each room asks that the one before did not. Each room's numbers live in rooms.json (its \`tune\`, over tunables.json's defaults); \`funtools rooms\` plays every room with a careful player at a human rate, the sharp bot, a naive and a novice player over 5 seeds and reports each room's time against its par and who clears it.
+
+${table([['Room', 'Teaches', 'Beat', 'Waves', 'Its numbers'], ['---', '---', '---', '---', '---'], ...rooms.map((r) => [`\`${r.id}\` ${r.name}`, r.teaches, r.beat, String(r.waves), tuneLine(r)])])}
+
+## Who it is for
+
+<!-- write: the player this curve is for, where a newcomer should first fail, and where the game asks for mastery. -->
+`;
+    out['screens-and-tutorial.md'] = `# Screens and the tutorial
+
+Every screen is a declared view (\`src/expose.ts\`), each with a way out: title (a real start control), how to play, settings, playing, paused, won and lost. The endings show the map of progress (\`src/room-map.tsx\`): every chapter's rooms, the one the player resumes at, each cleared room's best time against its par. A reload resumes at the checkpoint, the door of the room the player was in (\`src/levels.ts\`, saved through @funpixel/sdk/save).
+
+## The first minute
+
+The slice room \`${slice.id}\` teaches: ${slice.teaches}.
+
+<!-- write: the teaching script second by second (first input by 0:05), what each line of the how-to says, and where it is taught in play rather than told. -->
+
+## The HUD
+
+<!-- write: every element numbered, where it sits on a phone held the game's way, and what it never covers. -->
+`;
+    if (o.tier === 'deep') {
+        out['rooms.md'] = `# The rooms in words
+
+What rooms.json cannot say: each room's shape, material and light, its set piece, and why it is not the room before. Numbers stay in tunables.json and rooms.json.
+
+${o.chapters.map((c) => `## ${c.name}\n\n${c.rooms.map((r) => `### \`${r.id}\` ${r.name}\n\nTeaches: ${r.teaches}. Beat: ${r.beat}.\n\n<!-- write: shape, material, light, the set piece, what it adds. -->`).join('\n\n')}`).join('\n\n')}
+`;
+        out['cast.md'] = `# The cast
+
+Everyone and everything that acts: what each wants, how it reads by silhouette, its tell, and how it bends the core rule.
+
+${o.actors ? `From the GDD's actors:\n\n${o.actors.trim()}\n` : ''}
+<!-- write: one entry per actor with its want, silhouette, tell (0.6 s or more), and the room it arrives in. -->
+`;
+        out['story.md'] = `# The story
+
+<!-- write: the people by name and what each wants, every beat with the room it lands in, and the endings. -->
+`;
+        out['audio.md'] = `# Sound and music
+
+<!-- write: every cue with its layer, loudness and priority (assets/assets.json holds the files), the music per chapter and how it follows play, and voice. -->
+`;
+        out['juice.md'] = `# Juice
+
+Hitstop, shake, flashes and particles per event, and what is held back. The numbers are tunables: ${byGroup.has('juice') ? cite(ids('juice')) : 'the juice group'}.
+
+<!-- write: one row per event (pickup, hit, loss, a room cleared): what it does on screen and in the hand, and what is held back so the big moments stay big. -->
+`;
+    }
+    return out;
+}
+function headerOf(text) {
+    if (!text)
+        return '';
+    const lines = [];
+    for (const l of text.split('\n')) {
+        if (!/^\s*\/\//.test(l))
+            break;
+        lines.push(l.replace(/^\s*\/\/\s?/, ''));
+    }
+    return lines.join(' ').replace(/\s+/g, ' ').trim();
+}
+function actorsOf(root) {
+    const t = read(join(root, 'design', 'GDD.md'));
+    const m = t ? /^##\s+Actors\b[^\n]*\n([\s\S]*?)(?=^##\s|$(?![\s\S]))/m.exec(t) : null;
+    return m && m[1].trim() ? m[1].trim().slice(0, 1500) : null;
+}
+const STOCK_TEST = 'node --test test/*.test.ts';
+const DESIGN_RULE = /^\/design\/\s*$/m;
+export const SPEC_SHIPS = '/design/*\n!/design/spec/\n/design/spec/*\n# The big tier\'s data the game loads at build (funtools spec init): the numbers and the rooms ship, the spec\'s words do not.\n!/design/spec/tunables.json\n!/design/spec/rooms*.json';
+export function retier(old, tier, now, world) {
+    const fresh = defaultPipeline(tier, now, 'funtools spec init', { world });
+    const kept = new Map(old.stages.map((s) => [s.id, s]));
+    const stages = fresh.stages.map((s) => { const o = kept.get(s.id); return o ? { ...s, status: o.status, ...(o.because ? { because: o.because } : {}), ...(o.found ? { found: o.found } : {}), ...(o.done_at ? { done_at: o.done_at } : {}) } : s; });
+    for (const [i, s] of old.stages.entries())
+        if (!stages.some((x) => x.id === s.id))
+            stages.splice(Math.min(stages.length, i + 1), 0, s);
+    return { ...old, tier, stages, written_by: `${old.written_by}; re-tiered by funtools spec init` };
+}
+export function specInit(root, o = {}) {
+    const now = o.now ?? new Date(), date = now.toISOString().slice(0, 10);
+    const manifest = readJson(join(root, 'funpixel.json'));
+    if (!manifest)
+        return { refused: `${root} has no funpixel.json`, next: 'run it in a game folder (funtools init makes one)' };
+    const had = manifest.production?.tier ?? 'small';
+    const tier = o.tier ?? (had === 'mid' || had === 'deep' ? had : null);
+    if (!tier)
+        return { refused: 'a small game stays one GDD (funpixel.json production.tier is small)', next: 'grow it to the big tier on purpose: funtools spec init --tier mid (or --tier deep for a long, story-led game)' };
+    if (existsSync(join(root, SPEC_DIR, 'tunables.json')))
+        return { refused: `${SPEC_DIR}/tunables.json is already here: the spec is the game's now`, next: 'funtools spec lint checks it' };
+    const unity = unityOf(root, manifest);
+    if (unity)
+        return unitySpecInit(root, { tier, had, manifest, unity, now, date });
+    const framework = frameworkOf(root);
+    const managed = readJson(join(root, MANIFEST)) ?? { files: {} };
+    const asWritten = (rel, text) => managed.files?.[rel] === sha(text);
+    const wrote = [], rewired = [], leftAlone = [], notes = [];
+    const texts = new Map(sourceFiles(root).map((rel) => [rel, read(join(root, rel)) ?? '']));
+    const found = settleIds([...texts].flatMap(([rel, text]) => findNumbers(rel, text, rel.replace(/^.*\/|\.\w+$/g, ''))));
+    write(root, join(SPEC_DIR, 'tunables.json'), tunablesJson(found, manifest.name ?? 'the game', date), wrote);
+    for (const [rel, text] of texts) {
+        const mine = found.filter((f) => f.file === rel);
+        if (!mine.length)
+            continue;
+        if (asWritten(rel, text)) {
+            writeFileSync(join(root, rel), rewire(text, mine));
+            rewired.push(rel);
+        }
+        else
+            leftAlone.push(rel);
+    }
+    const ids = new Set(found.map((f) => `${f.group}.${f.key}`));
+    const fit = fitPreset(presetFor(framework), ids);
+    write(root, join(SPEC_DIR, 'rooms.json'), roomsJson(fit.chapters, date), wrote);
+    const layer = (from) => { const dir = join(TEMPLATES, 'spec', from); return existsSync(dir) ? dir : null; };
+    for (const from of ['common', framework].map(layer).filter((d) => !!d)) {
+        const walk = (rel) => {
+            for (const e of readdirSync(join(from, rel), { withFileTypes: true })) {
+                const child = rel ? `${rel}/${e.name}` : e.name;
+                if (e.isDirectory()) {
+                    walk(child);
+                    continue;
+                }
+                const text = readFileSync(join(from, child), 'utf8');
+                const cur = read(join(root, child));
+                if (cur === null || (child === 'src/levels.ts' && asWritten(child, cur)) || wrote.includes(child))
+                    write(root, child, text, wrote);
+                else if (cur !== text) {
+                    write(root, `${child}.funtools-new`, text, wrote);
+                    notes.push(`${child} is yours: the big tier's version waits at ${child}.funtools-new`);
+                }
+            }
+        };
+        walk('');
+    }
+    if (!existsSync(join(root, 'test', 'resolve.mjs'))) {
+        const hook = read(join(TEMPLATES, 'three-world', 'test', 'resolve.mjs'));
+        if (hook)
+            write(root, 'test/resolve.mjs', hook, wrote);
+    }
+    const screens = read(join(root, 'src', 'screens.tsx'));
+    if (screens && asWritten('src/screens.tsx', screens)) {
+        const anchor = /(\n(\s*)<p class="(?:score|tally)">[^\n]*<\/p>\n)/;
+        if (anchor.test(screens)) {
+            const patched = screens.replace(anchor, (m, line, pad) => `${line}${pad}<RoomMap />\n`).replace(/(\nimport \{ Splash \} from '\.\/splash';)/, `$1\nimport { RoomMap } from './room-map';`);
+            writeFileSync(join(root, 'src', 'screens.tsx'), patched);
+            wrote.push('src/screens.tsx');
+        }
+    }
+    else if (screens)
+        notes.push('src/screens.tsx is yours: show <RoomMap /> (src/room-map.tsx) on the endings yourself');
+    const pkgPath = join(root, 'package.json'), pkg = readJson(pkgPath);
+    if (pkg?.scripts?.test === STOCK_TEST) {
+        pkg.scripts.test = 'node --import ./test/resolve.mjs --test test/*.test.ts';
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        wrote.push('package.json');
+    }
+    const ignore = read(join(root, '.harnessignore'));
+    if (ignore !== null && DESIGN_RULE.test(ignore) && !ignore.includes('!/design/spec/tunables.json')) {
+        writeFileSync(join(root, '.harnessignore'), ignore.replace(DESIGN_RULE, SPEC_SHIPS));
+        wrote.push('.harnessignore');
+    }
+    const rulesText = read(join(root, 'src', 'rules.ts'));
+    const floor = playFloor(root).seconds;
+    for (const [file, text] of Object.entries(sectionTexts({ name: manifest.name ?? 'The game', tier, framework, found, chapters: fit.chapters, floor, date, rulesHeader: headerOf(rulesText), actors: actorsOf(root) }))) {
+        if (!existsSync(join(root, SPEC_DIR, file)))
+            write(root, join(SPEC_DIR, file), text, wrote);
+    }
+    const { rooms } = specRooms(root);
+    write(root, OPEN_FILE, JSON.stringify({ version: 1, planned: Object.fromEntries(rooms.map((r) => [r.id, r.hash])), opened: [] }, null, 2) + '\n', wrote);
+    if (had !== tier) {
+        manifest.production = { ...(manifest.production ?? {}), tier, tierFrom: 'spec', because: [...(manifest.production?.because ?? []), `grown to ${tier} by funtools spec init (${date})`] };
+        writeFileSync(join(root, 'funpixel.json'), JSON.stringify(manifest, null, 2) + '\n');
+        wrote.push('funpixel.json');
+    }
+    const pipe = readPipeline(root);
+    if (pipe && (pipe.tier !== tier || !pipe.stages.some((s) => s.id === 'expand'))) {
+        writeFileSync(join(root, PIPELINE_FILE), JSON.stringify(retier(pipe, tier, now, framework !== 'pixi'), null, 2) + '\n');
+        wrote.push(PIPELINE_FILE);
+    }
+    const flow = readJson(join(root, FLOW_FILE));
+    if (flow && typeof flow === 'object') {
+        flow.scaffold = { ...(flow.scaffold ?? {}), ...codeHashes(root) };
+        writeFileSync(join(root, FLOW_FILE), JSON.stringify(flow, null, 2) + '\n');
+    }
+    if (fit.dropped.length)
+        notes.push(`the preset's rooms set ${fit.dropped.join(', ')}, which this game does not have: dropped from rooms.json`);
+    return { tier, framework, engine: 'web', notWritten: [], wrote: [...new Set(wrote)].map((w) => relative('.', w) || w), rewired, leftAlone, tunables: found.length, rooms: rooms.length, parTotal: fit.chapters.flatMap((c) => c.rooms).reduce((s, r) => s + r.par, 0), floor, dropped: fit.dropped, notes };
+}
+export const WEB_LAYER = ['src/tune.ts', 'src/chapters.ts', 'src/levels.ts', 'src/probe-rooms.ts', 'src/room-map.tsx', 'test/rooms.ts', 'test/resolve.mjs', 'package.json (test script)', '.harnessignore (spec rule)'];
+export function unityOf(root, manifest) {
+    const found = unityProject(root);
+    if ('project' in found)
+        return found.project;
+    return manifest?.metadata?.framework === 'unity' || manifest?.framework === 'unity' ? root : null;
+}
+function unitySpecInit(root, o) {
+    const { tier, manifest, unity, now, date } = o;
+    const shownUnity = relative(root, unity) || '.';
+    const there = (() => { try {
+        return readdirSync(join(root, SPEC_DIR)).filter((n) => !n.startsWith('.'));
+    }
+    catch {
+        return [];
+    } })();
+    if (there.length) {
+        return {
+            refused: `a Unity game, and ${SPEC_DIR}/ already holds its own spec (${there.slice(0, 4).join(', ')}${there.length > 4 ? `, … ${there.length} in all` : ''}): spec init writes a Unity spec only where there is none, and never the web layer (src/tune.ts, the room runner), which a Unity game cannot load`,
+            next: 'funtools spec lint reads the folder as it is',
+        };
+    }
+    const wrote = [];
+    const name = manifest.name ?? 'The game';
+    const copy = `${shownUnity === '.' ? '' : `${shownUnity}/`}Assets/_Game/Resources/Spec`;
+    write(root, join(SPEC_DIR, 'tunables.json'), JSON.stringify({ version: 1, date, note: `Every number ${name} plays by, one source of truth, by id (group.name). The Unity project loads a copy of this file (${copy}/tunables.json, a TextAsset) that an Editor step copies in, and an EditMode test fails when the two differ: edit this file, never the copy. Give each a default, a unit, a range and a why; name the tests that pin it.`, groups: {} }, null, 2) + '\n', wrote);
+    write(root, join(SPEC_DIR, 'rooms.json'), JSON.stringify({ version: 1, date, note: `The game's rooms in order, one per place in the GDD, each with its par (the seconds a good first run takes), its exit (the next room, "end" after the last), what it teaches and its numbers (tune: ids from tunables.json). The Unity project loads a copy (${copy}/rooms.json) the same way as tunables.json. The first room is the slice: build it before any other.`, chapters: [] }, null, 2) + '\n', wrote);
+    const floor = playFloor(root);
+    for (const [file, text] of Object.entries(unitySectionTexts({ name, tier, date, unity: shownUnity, copy, floor: floor.seconds }))) {
+        if (!existsSync(join(root, SPEC_DIR, file)))
+            write(root, join(SPEC_DIR, file), text, wrote);
+    }
+    if (o.had !== tier) {
+        manifest.production = { ...(manifest.production ?? {}), tier, tierFrom: 'spec', because: [...(manifest.production?.because ?? []), `grown to ${tier} by funtools spec init (${date})`] };
+        writeFileSync(join(root, 'funpixel.json'), JSON.stringify(manifest, null, 2) + '\n');
+        wrote.push('funpixel.json');
+    }
+    const pipe = readPipeline(root);
+    if (pipe && (pipe.tier !== tier || !pipe.stages.some((s) => s.id === 'expand'))) {
+        writeFileSync(join(root, PIPELINE_FILE), JSON.stringify(retier(pipe, tier, now, manifest.metadata?.dimension === '3d'), null, 2) + '\n');
+        wrote.push(PIPELINE_FILE);
+    }
+    return { tier, framework: 'unity', engine: 'unity', notWritten: WEB_LAYER, unityProject: shownUnity, wrote, rewired: [], leftAlone: [], tunables: 0, rooms: 0, parTotal: 0, floor: floor.seconds, dropped: [], notes: [] };
+}
+export function unitySectionTexts(o) {
+    const files = sectionsFor(o.tier);
+    const table = (rows) => rows.map((r) => `| ${r.join(' | ')} |`).join('\n');
+    const out = {};
+    out['README.md'] = `# ${o.name}: the build contract (spec v0.1)
+
+This folder is what a building agent works from (the ${o.tier} tier of the plan, written by \`funtools spec init\` on ${o.date} for a Unity game: the Unity project is \`${o.unity}\`). The GDD (\`../GDD.md\`) says what the game is and why; this folder says what to build, in numbers and data the game loads. When the two disagree, fix one of them the same day.
+
+## Read this first
+
+1. \`../decisions.md\`: every decision with what it beat and why (\`funtools decide\`). Do not reverse one without a new entry.
+2. \`tunables.json\`: every number the game plays by, by id (\`group.name\`). Spec files cite ids and never repeat values.
+3. \`rules.md\`: the simulation, in rules, each citing its tunables: written as engine-free C# with its tests (skill funpixel-unity-game).
+4. \`rooms.json\`: every room in order, with its par, its exit and its numbers.
+5. Then the file for the lane you are in (the table below).
+
+## How Unity loads it
+
+The data files live here, outside the Unity project, so the design and the game read one copy:
+- an Editor step copies \`tunables.json\` and \`rooms.json\` into \`${o.copy}/\` (TextAssets the game reads at start);
+- an EditMode test fails when a copy differs from this folder, so a change made here and not carried over is a red test, not a silent drift (one game's tunables changed in design/ while its Unity copy did not);
+- edit this folder, never the copy.
+
+## Slice first
+
+The slice is the first room in \`rooms.json\`. Nothing in a later room is built until the room before it plays to its end in a player build at its par.
+
+## The length
+
+The pars in \`rooms.json\` add up to the game's length against the play floor of ${clock(o.floor)} (\`funtools spec lint\` keeps the sum honest).
+
+## The files
+
+${table([['File', 'Covers'], ['---', '---'], ...files.map((s) => ['`' + s.file + '`', s.covers.replace(/ \((?:src\/tune|src\/chapters)[^)]*\)/, '')])])}
+
+## Ids
+
+A tunable is \`group.name\`; a room is its id in rooms.json. Ids are never reused. A number appears in this folder only in tunables.json: everywhere else, cite the id.
+`;
+    out['rules.md'] = `# The rules
+
+The simulation, engine-free: plain C# the renderer draws and the tests play (CoreTests~ outside the Editor). Every number is a tunable; this file cites ids.
+
+<!-- write: one rule per line, an id each (RULE-…), the tunables it reads and the test that pins it. -->
+`;
+    out['difficulty.md'] = `# Fun and difficulty
+
+The curve, room by room: what each room asks that the one before did not. Each room's numbers live in rooms.json (its \`tune\`, over tunables.json's defaults).
+
+<!-- write: one row per room (teaches, beat, its numbers), the player this curve is for, where a newcomer first fails, and where the game asks for mastery. -->
+`;
+    out['screens-and-tutorial.md'] = `# Screens and the tutorial
+
+Every screen with its way out: title (a real start control), how to play, settings, playing, paused, won and lost, each inside the safe area on a phone held the game's way.
+
+## The first minute
+
+<!-- write: the teaching script second by second (first input by 0:05), and where it is taught in play rather than told. -->
+
+## The HUD
+
+<!-- write: every element numbered, where it sits, and what it never covers. -->
+`;
+    if (o.tier === 'deep') {
+        out['rooms.md'] = '# The rooms in words\n\nWhat rooms.json cannot say: each room\'s shape, material and light, its set piece, and why it is not the room before. Numbers stay in tunables.json and rooms.json.\n\n<!-- write: one section per room in rooms.json. -->\n';
+        out['cast.md'] = '# The cast\n\nEveryone and everything that acts: what each wants, how it reads by silhouette, its tell, and how it bends the core rule.\n\n<!-- write: one entry per actor with its want, silhouette, tell (0.6 s or more), and the room it arrives in. -->\n';
+        out['story.md'] = '# The story\n\n<!-- write: the people by name and what each wants, every beat with the room it lands in, and the endings. -->\n';
+        out['audio.md'] = '# Sound and music\n\n<!-- write: every cue with its layer, loudness and priority, the music per chapter and how it follows play, and voice; the mixer runs at 48 kHz (funtools doctor checks it). -->\n';
+        out['juice.md'] = '# Juice\n\nHitstop, shake, flashes and particles per event, and what is held back. The numbers are tunables.\n\n<!-- write: one row per event (pickup, hit, loss, a room cleared): what it does on screen and in the hand, and what is held back so the big moments stay big. -->\n';
+    }
+    return out;
+}

package/dist/spec/sections.js

@@ -0,0 +1,16 @@
+export const SECTIONS = [
+    { id: 'readme', file: 'README.md', also: [], title: 'The build contract', covers: 'what to read first, the slice-first rule, every file and who owns it', tiers: ['mid', 'deep'] },
+    { id: 'tunables', file: 'tunables.json', also: [], title: 'Every number', covers: 'every number the game plays by: id, default, unit, range, why, tests (src/tune.ts loads it)', tiers: ['mid', 'deep'] },
+    { id: 'rules', file: 'rules.md', also: [], title: 'The rules', covers: 'the simulation in rules, each citing the tunables it reads', tiers: ['mid', 'deep'] },
+    { id: 'rooms', file: 'rooms.json', also: ['*rooms*.json'], title: 'Rooms and chapters', covers: 'every room in order: par, exit, what it teaches, its numbers (src/chapters.ts loads it)', tiers: ['mid', 'deep'] },
+    { id: 'screens', file: 'screens-and-tutorial.md', also: ['screens*.md', 'tutorial*.md'], title: 'Screens and the tutorial', covers: 'every screen and its way out, the HUD element by element, the teaching script, the first minute', tiers: ['mid', 'deep'] },
+    { id: 'difficulty', file: 'difficulty.md', also: ['fun-and-difficulty.md', '*difficulty*.md'], title: 'Fun and difficulty', covers: 'the curve room by room, what each room asks of the player, who it is for', tiers: ['mid', 'deep'] },
+    { id: 'rooms-words', file: 'rooms.md', also: ['levels.md', 'places.md'], title: 'The rooms in words', covers: 'each room\'s shape, material, light, its set piece and why it is not the room before', tiers: ['deep'] },
+    { id: 'cast', file: 'cast.md', also: ['crew.md', 'characters.md', 'actors.md'], title: 'The cast', covers: 'everyone and everything that acts: want, silhouette, tell, how each bends the core rule', tiers: ['deep'] },
+    { id: 'story', file: 'story.md', also: ['story*.md'], title: 'The story', covers: 'the people, every beat, which room it lands in, the endings', tiers: ['deep'] },
+    { id: 'audio', file: 'audio.md', also: ['sfx.md', 'sound.md', 'music.md'], title: 'Sound and music', covers: 'every cue with its layer and loudness, the music per chapter, voice', tiers: ['deep'] },
+    { id: 'juice', file: 'juice.md', also: ['feel.md'], title: 'Juice', covers: 'hitstop, shake, flashes, particles per event, and what is held back', tiers: ['deep'] },
+];
+export const sectionsFor = (tier) => SECTIONS.filter((s) => s.tiers.includes(tier));
+const globRe = (g) => new RegExp(`^${g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')}$`, 'i');
+export const filesFor = (s, names) => names.filter((n) => n.toLowerCase() === s.file.toLowerCase() || s.also.some((g) => globRe(g).test(n)));

package/dist/spec/tunables.js

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const SPEC_DIR = join('design', 'spec');
+export const TUNABLES_FILE = join(SPEC_DIR, 'tunables.json');
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+function rangeOf(v) {
+    return Array.isArray(v) && v.length === 2 && isNum(v[0]) && isNum(v[1]) ? [v[0], v[1]] : undefined;
+}
+const testsOf = (v) => (Array.isArray(v) ? v.filter((t) => typeof t === 'string' && !!t.trim()) : []);
+const textOf = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+function entry(id, group, name, e) {
+    return {
+        id, group, name, default: e.default,
+        ...(textOf(e.type) ? { type: textOf(e.type) } : {}),
+        ...(textOf(e.unit) ? { unit: textOf(e.unit) } : {}),
+        ...(rangeOf(e.range) ? { range: rangeOf(e.range) } : {}),
+        ...(textOf(e.why) ? { why: textOf(e.why) } : {}),
+        tests: testsOf(e.tests),
+    };
+}
+export function parseTunables(raw) {
+    const problems = [];
+    const list = [];
+    const o = raw && typeof raw === 'object' ? raw : null;
+    if (o && o.groups && typeof o.groups === 'object' && !Array.isArray(o.groups)) {
+        for (const [g, entries] of Object.entries(o.groups)) {
+            if (!entries || typeof entries !== 'object' || Array.isArray(entries)) {
+                problems.push(`group "${g}" is not an object of tunables`);
+                continue;
+            }
+            for (const [n, e] of Object.entries(entries)) {
+                if (!e || typeof e !== 'object' || Array.isArray(e)) {
+                    problems.push(`${g}.${n} is not an object ({ default, unit, range, why })`);
+                    continue;
+                }
+                list.push(entry(`${g}.${n}`, g, n, e));
+            }
+        }
+        return { shape: 'groups', list, problems };
+    }
+    if (o && Array.isArray(o.tunables)) {
+        for (const e of o.tunables) {
+            const r = e && typeof e === 'object' ? e : null;
+            if (!r || typeof r.id !== 'string') {
+                problems.push('an entry without an id');
+                continue;
+            }
+            const words = r.id.split('-');
+            list.push(entry(r.id, words[1] ?? r.id, words.slice(2).join('-') || r.id, r));
+        }
+        return { shape: 'list', list, problems };
+    }
+    problems.push('neither { "groups": { … } } nor { "tunables": [ … ] }');
+    return { shape: 'groups', list, problems };
+}
+export function readTunables(root, specDir = SPEC_DIR) {
+    const rel = join(specDir, 'tunables.json');
+    let text;
+    try {
+        text = readFileSync(join(root, rel), 'utf8');
+    }
+    catch {
+        return { missing: true, rel };
+    }
+    try {
+        return { ...parseTunables(JSON.parse(text)), rel };
+    }
+    catch (e) {
+        return { broken: e instanceof Error ? e.message : String(e), rel };
+    }
+}
+export function byId(list) {
+    return new Map(list.map((t) => [t.id, t]));
+}

package/dist/stage/harnessignore.js

@@ -0,0 +1,90 @@
+export function parseHarnessIgnore(text) {
+    return text
+        .replace(/^\uFEFF/, "")
+        .split(/\r?\n/)
+        .flatMap((raw, i) => {
+        const l = raw.trim();
+        if (!l || l.startsWith("#"))
+            return [];
+        return [l.startsWith("!") ? { pattern: l.slice(1), negated: true, line: i + 1 } : { pattern: l, negated: false, line: i + 1 }];
+    });
+}
+const globToRe = (glob) => {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i++;
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (c === "?")
+            re += "[^/]";
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return re;
+};
+export function makeDecider(rules) {
+    const compiled = rules.map((rule) => {
+        const { pattern } = rule;
+        const rooted = pattern.startsWith("/") || pattern.startsWith("./");
+        const dirOnly = pattern.endsWith("/");
+        let p = pattern;
+        if (p.startsWith("./"))
+            p = p.slice(2);
+        else if (rooted)
+            p = p.slice(1);
+        if (dirOnly)
+            p = p.slice(0, -1);
+        const body = globToRe(p);
+        const prefix = rooted ? "^" : "^(?:.*/)?";
+        const re = new RegExp(`${prefix}${body}(?:/.*)?$`);
+        const exactRe = new RegExp(`${prefix}${body}$`);
+        return { re, exactRe, rule, dirOnly };
+    });
+    return (relPath, isDir) => {
+        let decided = null;
+        for (const { re, exactRe, rule, dirOnly } of compiled) {
+            if (dirOnly && !isDir && exactRe.test(relPath))
+                continue;
+            if (re.test(relPath))
+                decided = rule;
+        }
+        return decided;
+    };
+}
+export function makeIgnoreMatcher(rules) {
+    const decide = makeDecider(rules);
+    return (relPath, isDir) => {
+        const rule = decide(relPath, isDir);
+        return rule !== null && !rule.negated;
+    };
+}
+export function makeRuleMatchers(rules) {
+    return rules.map((rule) => ({
+        rule,
+        test: makeIgnoreMatcher([rule]),
+    }));
+}
+export const PROPHYLACTIC = new Set([
+    ".env", ".env.*", "/verify.json", "/design/", "/dist-playable/",
+    "/scripts/", "/tools/", "/assets/", "/reference/", "/test/", "/vitest.config.ts", "/.funtools/", "*.md",
+]);
+export function deadRules(rules, allPaths) {
+    const ruleMatchers = makeRuleMatchers(rules);
+    const matched = new Set();
+    for (const path of allPaths) {
+        for (const { rule, test } of ruleMatchers) {
+            if (test(path, false) || test(path, true)) {
+                matched.add(rule.pattern);
+            }
+        }
+    }
+    return rules
+        .filter((r) => !r.negated && !matched.has(r.pattern) && !PROPHYLACTIC.has(r.pattern))
+        .map((r) => r.pattern);
+}