@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/motion.js

@@ -0,0 +1,305 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { patchBoard } from "../status/board.js";
+import { STATUS_FILE } from "../status/file.js";
+import { decodePng } from "../look/png.js";
+import { ASPECT_NAMES, judgedForBlank, plan } from "../motion/contract.js";
+import { blankCheck, boardParts, frameStats, meanDiff, overlapsCheck, repeatCheck, safeZoneCheck, seamCheck, verdictOf, } from "../motion/checks.js";
+import { renderScene, sceneOf, WRAP_FILE } from "../motion/render.js";
+import { encode, ffmpegBin } from "../motion/encode.js";
+import { starterScene } from "../motion/starter.js";
+import { ui } from "../ui.js";
+export const MOTION_SUBCOMMANDS = ['render', 'check', 'new'];
+export const MOTION_FILE = 'motion.json';
+export const LAYOUT_FILE = 'layout.json';
+export const sceneName = (s) => (s.page.toLowerCase() === 'index.html' ? basename(s.dir) : s.page.replace(/\.html?$/i, '')) || 'scene';
+export function projectOf(sceneDir) {
+    let d = sceneDir;
+    for (let i = 0; i < 6; i++) {
+        if (existsSync(join(d, 'funpixel.json')) || existsSync(join(d, STATUS_FILE)))
+            return d;
+        const up = dirname(d);
+        if (up === d)
+            break;
+        d = up;
+    }
+    return null;
+}
+export const defaultOut = (s) => join(projectOf(s.dir) ?? s.dir, '.funtools', 'motion', sceneName(s));
+const num = (v, what) => {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : `${what} is a number, not "${v}"`;
+};
+export function askedOf(o) {
+    const fps = num(o.fps, '--fps'), seconds = num(o.seconds, '--seconds'), frames = num(o.frames, '--frames');
+    for (const v of [fps, seconds, frames])
+        if (typeof v === 'string')
+            return v;
+    return { fps: fps, seconds: seconds, frames: frames, size: o.size, aspect: o.aspect };
+}
+const shown = (p) => { const r = relative(process.cwd(), p); return r && !r.startsWith('..') ? r : p; };
+const renderHash = (hashes) => createHash('sha256').update(hashes.join('\n')).digest('hex');
+const fileHash = async (p) => createHash('sha256').update(await readFile(p)).digest('hex');
+export function judge(r, prove) {
+    const p = r.plan;
+    const stats = new Map(r.frames.map((f) => [f.frame, { share: f.share, colour: f.colour }]));
+    return [
+        repeatCheck(r.frames.map((f) => f.hash), prove),
+        safeZoneCheck(r.samples, p.fps),
+        overlapsCheck(r.samples, p.fps),
+        seamCheck({ loop: p.loop, wrap: r.wrap, first: r.first, last: r.last, steps: r.steps }),
+        blankCheck(stats, judgedForBlank(p.frames, p.fps), p.fps),
+    ];
+}
+export async function readRender(out) {
+    let record;
+    try {
+        record = JSON.parse(await readFile(join(out, MOTION_FILE), 'utf8'));
+    }
+    catch {
+        return `no ${MOTION_FILE} in ${out}: render first (funtools motion render <scene>)`;
+    }
+    let samples = [];
+    try {
+        samples = JSON.parse(await readFile(join(out, LAYOUT_FILE), 'utf8')).samples ?? [];
+    }
+    catch {
+        samples = [];
+    }
+    const dir = join(out, 'frames');
+    const files = existsSync(dir) ? readdirSync(dir).filter((f) => /^\d{6}\.png$/.test(f)).sort() : [];
+    if (!files.length)
+        return `no frames in ${dir}`;
+    const frames = [], steps = [];
+    let first = null, prev = null;
+    for (let i = 0; i < files.length; i++) {
+        const png = readFileSync(join(dir, files[i]));
+        const s = frameStats(decodePng(png));
+        frames.push({ frame: i, hash: createHash('sha256').update(png).digest('hex'), share: s.share, colour: s.colour });
+        if (prev)
+            steps.push(meanDiff(prev, s));
+        if (i === 0)
+            first = s;
+        prev = s;
+    }
+    const wrapPath = join(out, WRAP_FILE);
+    const wrap = existsSync(wrapPath) ? frameStats(decodePng(readFileSync(wrapPath))) : null;
+    return { record, facts: { plan: record.plan, frames, steps, wrap, first, last: prev, samples } };
+}
+const MARK = { pass: 'pass', fail: 'fail', not_observed: 'not_observed', skip: 'skip' };
+const WORD = { repeatable: 'repeatable', safe_zone: 'safe zone', overlaps: 'overlaps', seam: 'loop seam', blank: 'blank frames' };
+function printChecks(u, checks) {
+    for (const c of checks) {
+        u.item(MARK[c.state], `${WORD[c.id]}: ${c.says}`);
+        for (const d of c.detail)
+            u.line(d, 2);
+    }
+}
+function stampBoard(sceneDir, name, checks) {
+    const project = projectOf(sceneDir);
+    if (!project || !existsSync(join(project, STATUS_FILE)))
+        return null;
+    const parts = boardParts(checks, `motion:${name}`);
+    return patchBoard(project, parts) ? join(project, STATUS_FILE) : null;
+}
+export async function motion(o, io = console) {
+    const u = ui(io, 'motion');
+    if (!o.sub) {
+        u.error(`motion takes ${MOTION_SUBCOMMANDS.join(', ')}`, 'funtools motion render <scene.html>, funtools motion new <name>, funtools motion --help');
+        return EXIT.error;
+    }
+    if (o.sub === 'new')
+        return await motionNew(o, u, io);
+    const path = o.args[0];
+    if (!path) {
+        u.error(`motion ${o.sub} needs ${o.sub === 'check' ? 'a render folder or a scene' : 'a scene (.html, or a folder with index.html)'}`);
+        return EXIT.error;
+    }
+    if (o.sub === 'check' && existsSync(join(resolve(path), MOTION_FILE)))
+        return await checkFolder(resolve(path), o, u, io);
+    return await renderAndJudge(path, o, u, io, o.sub === 'render');
+}
+async function renderAndJudge(path, o, u, io, encodeIt) {
+    const scene = sceneOf(path);
+    if (typeof scene === 'string') {
+        u.error(scene);
+        return EXIT.error;
+    }
+    const asked = askedOf(o);
+    if (typeof asked === 'string') {
+        u.error(asked);
+        return EXIT.error;
+    }
+    const pre = plan(asked);
+    if (typeof pre === 'string') {
+        u.error(pre);
+        return EXIT.error;
+    }
+    const seed = o.seed === undefined ? undefined : Number(o.seed);
+    if (seed !== undefined && !Number.isInteger(seed)) {
+        u.error('--seed is a whole number');
+        return EXIT.error;
+    }
+    const audio = o.audio ? resolve(o.audio) : null;
+    if (audio && !existsSync(audio)) {
+        u.error(`no audio file at ${o.audio}`);
+        return EXIT.error;
+    }
+    if (!encodeIt && (o.webm || audio)) {
+        u.error('--webm and --audio go with motion render (check does not encode)');
+        return EXIT.error;
+    }
+    const out = resolve(o.out ?? defaultOut(scene));
+    await mkdir(out, { recursive: true });
+    const name = sceneName(scene);
+    const progress = !o.json ? u.progress() : null;
+    const r = await renderScene({ scene, asked, out, seed, progress: progress ? (d, n) => { if (d === n || d % Math.max(1, Math.ceil(n / 4)) === 0)
+            progress.update(`frame ${d} of ${n}`); } : undefined });
+    if (r.state !== 'done') {
+        progress?.done(r.state === 'error' ? 'fail' : 'not_observed', r.says);
+        if (o.json)
+            io.log(JSON.stringify({ verdict: r.state === 'error' ? 'error' : 'not_observed', says: r.says, logs: r.logs }, null, 2));
+        else {
+            u.error(r.says);
+            for (const l of r.logs.slice(0, 5))
+                u.line(l, 2);
+        }
+        return r.state === 'error' ? EXIT.error : EXIT.not_observed;
+    }
+    progress?.done('pass', `rendered ${r.says} in ${(r.ms / 1000).toFixed(1)} s`);
+    const p = r.plan;
+    let mp4 = null, webm = null, encodeError = null, noFfmpeg = false;
+    if (encodeIt) {
+        const bin = ffmpegBin();
+        if (!bin)
+            noFfmpeg = true;
+        else {
+            for (const container of (o.webm ? ['mp4', 'webm'] : ['mp4'])) {
+                const file = join(out, `motion.${container}`);
+                const e = encode(bin, { framesDir: join(out, 'frames'), fps: p.fps, seconds: p.seconds, out: file, container, audio });
+                if (!e.ok) {
+                    encodeError = `${container}: ${e.error}`;
+                    break;
+                }
+                if (container === 'mp4')
+                    mp4 = file;
+                else
+                    webm = file;
+            }
+        }
+    }
+    let second = null;
+    if (o.prove) {
+        progress?.update('rendering again to prove it repeats');
+        const again = await renderScene({ scene, asked, out: null, seed, layout: false });
+        second = again.state === 'done' ? again.frames.map((f) => f.hash) : [];
+    }
+    const checks = judge(r, second);
+    const verdict = verdictOf(checks);
+    const board = stampBoard(scene.dir, name, checks);
+    const record = {
+        verdict, scene: scene.file, name, at: (o.now ?? new Date()).toISOString(), plan: p, seek: r.seek, served: r.served, seed: seed ?? 1,
+        files: { frames: 'frames/', mp4: mp4 ? basename(mp4) : null, webm: webm ? basename(webm) : null, audio, wrap: p.loop ? WRAP_FILE : null },
+        render_hash: renderHash(r.frames.map((f) => f.hash)), video_hash: mp4 ? await fileHash(mp4) : null,
+        frames: r.frames.map((f) => f.hash), checks, board, page_errors: r.page_errors, clock: r.clock, ms: r.ms,
+    };
+    await writeFile(join(out, MOTION_FILE), JSON.stringify(record, null, 2) + '\n');
+    await writeFile(join(out, LAYOUT_FILE), JSON.stringify({ safe: p.safe, samples: r.samples }, null, 2) + '\n');
+    if (encodeError) {
+        if (o.json)
+            io.log(JSON.stringify({ ...record, verdict: 'error', error: encodeError }, null, 2));
+        else
+            u.error(`the encode failed (${encodeError})`, `the frames are in ${join(out, 'frames')}`);
+        return EXIT.error;
+    }
+    if (o.json) {
+        io.log(JSON.stringify({ ...record, out }, null, 2));
+        return EXIT[verdict];
+    }
+    report(u, record, out, r, noFfmpeg, encodeIt);
+    return EXIT[verdict];
+}
+function report(u, rec, out, r, noFfmpeg, encoded) {
+    const p = rec.plan;
+    u.heading(`motion · ${rec.name} · ${p.width}x${p.height} · ${p.fps} fps · ${p.frames} frames (${Math.round(p.seconds * 100) / 100} s)${p.loop ? ' · loop' : ''} · ${rec.seek ? '__MOTION_SEEK__' : 'held clock'}`);
+    printChecks(u, rec.checks);
+    if (r?.page_errors.length)
+        u.item('warn', `the page threw ${r.page_errors.length} error(s): ${r.page_errors.slice(0, 2).map((e) => `"${e}"`).join('; ')}`);
+    if (noFfmpeg)
+        u.item('warn', 'no ffmpeg on PATH: frames only, nothing encoded', 'install ffmpeg (brew install ffmpeg) and render again');
+    if (rec.board)
+        u.item('note', `zero board: the motion:${rec.name} part in ${shown(rec.board)}`);
+    u.line(join(out, 'frames') + '/');
+    if (rec.files.mp4)
+        u.line(join(out, rec.files.mp4));
+    if (rec.files.webm)
+        u.line(join(out, rec.files.webm));
+    u.line(join(out, MOTION_FILE));
+    const failed = rec.checks.filter((c) => c.state === 'fail').map((c) => WORD[c.id]);
+    u.summary(rec.verdict, rec.verdict === 'pass'
+        ? `${encoded && rec.files.mp4 ? 'rendered, checked and encoded' : 'rendered and checked'} — render ${rec.render_hash.slice(0, 12)}`
+        : rec.verdict === 'fail' ? `${failed.join(', ')} — fix the scene and render again` : 'nothing could be judged (not observed is never a pass)');
+}
+async function checkFolder(out, o, u, io) {
+    const read = await readRender(out);
+    if (typeof read === 'string') {
+        u.error(read);
+        return EXIT.error;
+    }
+    const { record, facts } = read;
+    let second = null;
+    if (o.prove) {
+        const scene = sceneOf(record.scene);
+        if (typeof scene === 'string') {
+            u.error(`--prove renders the scene again: ${scene}`);
+            return EXIT.error;
+        }
+        const p = record.plan;
+        const again = await renderScene({ scene, asked: { fps: p.fps, frames: p.frames, size: `${p.width}x${p.height}` }, out: null, seed: record.seed, layout: false });
+        second = again.state === 'done' ? again.frames.map((f) => f.hash) : [];
+    }
+    const checks = judge(facts, second);
+    const verdict = verdictOf(checks);
+    const scene = sceneOf(record.scene);
+    const board = typeof scene === 'string' ? null : stampBoard(scene.dir, record.name, checks);
+    const next = { ...record, verdict, checks, board, frames: facts.frames.map((f) => f.hash), render_hash: renderHash(facts.frames.map((f) => f.hash)) };
+    await writeFile(join(out, MOTION_FILE), JSON.stringify(next, null, 2) + '\n');
+    if (o.json)
+        io.log(JSON.stringify({ ...next, out }, null, 2));
+    else
+        report(u, next, out, null, false, false);
+    return EXIT[verdict];
+}
+async function motionNew(o, u, io) {
+    const name = o.args[0];
+    if (!name || !/^[a-z0-9][a-z0-9-]{0,63}$/i.test(name)) {
+        u.error('motion new <name>: letters, digits and - (it becomes the folder <name>/index.html)');
+        return EXIT.error;
+    }
+    const aspect = (o.aspect ?? '9:16');
+    if (!ASPECT_NAMES.includes(aspect)) {
+        u.error(`--aspect is ${ASPECT_NAMES.join(', ')}`);
+        return EXIT.error;
+    }
+    const folder = resolve(o.dir ?? '.', name);
+    const file = join(folder, 'index.html');
+    if (existsSync(file)) {
+        u.error(`${file} exists: pick another name, or render it (funtools motion render ${name})`);
+        return EXIT.error;
+    }
+    await mkdir(folder, { recursive: true });
+    await writeFile(file, starterScene(name, aspect));
+    if (o.json) {
+        io.log(JSON.stringify({ file, aspect }, null, 2));
+        return EXIT.pass;
+    }
+    u.item('pass', `wrote ${shown(file)} (${aspect}, a 4 s loop: a title, a subtitle, CSS only)`);
+    u.line(`funtools motion render ${shown(folder)} --prove`);
+    u.summary('pass', 'a starter scene that passes every check; make it yours, then render');
+    return EXIT.pass;
+}

package/dist/commands/next.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { adoptExisting, defaultPipeline, evaluate, existingEvidence, PIPELINE_FILE, planSig, readPipeline, rulesFor } from "../pipeline/pipeline.js";
+import { ui } from "../ui.js";
+import { growFromShelf, STAGE_SECTIONS } from "../gdd/tiers.js";
+import { gddTemplate } from "./pitch.js";
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+export function tierOf(root) {
+    const t = readJson(join(root, 'funpixel.json'))?.production?.tier;
+    return t === 'mid' || t === 'deep' ? t : 'small';
+}
+export function writePipeline(root, p) {
+    const file = join(root, PIPELINE_FILE);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(p, null, 2) + '\n');
+}
+export function ensurePipeline(root, now = new Date()) {
+    const have = readPipeline(root);
+    if (have) {
+        const raw = readJson(join(root, PIPELINE_FILE));
+        const moved = have.stages.some((st) => { const was = raw?.stages?.find((x) => x?.id === st.id); return was && (was.status !== st.status || was.found_sig !== st.found_sig); });
+        if (moved)
+            writePipeline(root, have);
+        return [have, false];
+    }
+    const p = defaultPipeline(tierOf(root), now, 'funtools next (none was there)');
+    adoptExisting(p, existingEvidence(root), now, planSig(root));
+    writePipeline(root, p);
+    return [readPipeline(root) ?? p, true];
+}
+export function growForStage(root, stage) {
+    const want = stage ? STAGE_SECTIONS[stage] : undefined;
+    if (!want?.length)
+        return [];
+    const file = join(root, 'design', 'GDD.md');
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const template = gddTemplate(root);
+    if (!template)
+        return [];
+    const g = growFromShelf(text, template, { sections: want });
+    if (g.grown.length)
+        writeFileSync(file, g.text);
+    return g.grown;
+}
+export function markDone(root, p, e, now = new Date()) {
+    let changed = false;
+    for (const s of e.stages) {
+        if (s.skipped || s.stage.status === 'done' || !s.gates.length || !s.gates.every((g) => g.state === 'met'))
+            continue;
+        const st = p.stages[s.index];
+        st.status = 'done';
+        st.done_at = now.toISOString();
+        changed = true;
+    }
+    if (changed)
+        writePipeline(root, p);
+    return changed;
+}
+const MARK = { met: 'pass', open: 'warn', stale: 'warn', failing: 'fail', not_observed: 'not_observed' };

package/dist/commands/note.js

@@ -0,0 +1,294 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { EXIT } from "./verify.js";
+import { ensurePipeline, writePipeline } from "./next.js";
+import { readPipeline } from "../pipeline/pipeline.js";
+import { designNote, designPath, evaluate, evaluateGate, holdsStage, LOOK_NOTE, openNotes, worldRead } from "../pipeline/pipeline.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { CAPTURE_INDEX } from "./look.js";
+import { ui } from "../ui.js";
+import { chapterStage, readChapters } from "../gdd/chapters.js";
+export { LOOK_NOTE };
+export const NOTE_SUBCOMMANDS = ['list', 'add', 'close', 'verdict'];
+const stamp = (d) => d.toISOString().replace(/\.\d+Z$/, 'Z');
+export function evidenceKind(root, ev) {
+    if (existsSync(resolve(root, ev)))
+        return 'file';
+    if (/^[0-9a-f]{7,40}$/i.test(ev)) {
+        const r = spawnSync('git', ['-C', root, 'cat-file', '-e', `${ev}^{commit}`], { stdio: 'ignore' });
+        if (r.status === 0)
+            return 'commit';
+    }
+    if (ev.length >= 6 && testFiles(root).some((f) => { try {
+        return readFileSync(f, 'utf8').includes(ev);
+    }
+    catch {
+        return false;
+    } }))
+        return 'test';
+    return null;
+}
+function testFiles(root) {
+    const out = [];
+    const walk = (d, depth) => {
+        let names = [];
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            if (n === 'node_modules' || n.startsWith('.'))
+                continue;
+            const p = join(d, n);
+            let st;
+            try {
+                st = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory() && depth < 4)
+                walk(p, depth + 1);
+            else if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(n) || /probes\.ts$/.test(n))
+                out.push(p);
+        }
+    };
+    walk(join(root, 'test'), 0);
+    walk(join(root, 'src'), 0);
+    return out;
+}
+const nextId = (p) => `N${p.notes.reduce((m, n) => Math.max(m, Number(/^N(\d+)$/.exec(n.id)?.[1] ?? 0)), 0) + 1}`;
+export async function note(opts, io = console) {
+    const u = ui(io, 'note');
+    const root = resolve(opts.dir ?? '.');
+    if (!existsSync(join(root, 'funpixel.json'))) {
+        u.error(`${root} is not a game folder (no funpixel.json)`, '--dir <game>');
+        return EXIT.error;
+    }
+    const now = opts.now ?? new Date();
+    const [p] = ensurePipeline(root, now);
+    const ids = p.stages.map((s) => s.id);
+    const show = (n) => `${n.id} [${n.stage}] ${n.by === 'agent' ? '(agent) ' : ''}${holdsStage(n) && n.status === 'open' ? '(holds the stage) ' : ''}${n.text}`;
+    if (opts.sub === 'list') {
+        if (opts.json) {
+            io.log(JSON.stringify({ notes: p.notes, open: openNotes(p).map((n) => n.id) }, null, 2));
+            return p.notes.length ? EXIT.pass : EXIT.not_observed;
+        }
+        if (!p.notes.length) {
+            u.summary('not_observed', 'no notes yet: `funtools note add "<the owner\'s words>" --stage <stage>`');
+            return EXIT.not_observed;
+        }
+        const open = openNotes(p);
+        u.heading(`open (${open.length})`);
+        for (const n of open)
+            u.item('warn', show(n), [n.screenshot, n.verdict?.says === 'reject' ? `the owner rejected the fix: ${n.verdict.words ?? ''}` : ''].filter(Boolean).join(' · ') || undefined);
+        const closed = p.notes.filter((n) => !open.includes(n));
+        if (closed.length)
+            u.heading(`closed (${closed.length})`);
+        for (const n of closed)
+            u.item('pass', show(n), n.verdict?.says === 'accept' ? 'the owner accepted' : n.closed_by ? `${n.closed_by.kind}: ${n.closed_by.evidence}` : undefined);
+        u.summary(open.length ? 'warn' : 'pass', `${open.length} open of ${p.notes.length}`);
+        return EXIT.pass;
+    }
+    if (opts.sub === 'add') {
+        const text = opts.args.join(' ').replace(/\s+/g, ' ').trim();
+        if (!text) {
+            u.error('nothing to note', 'funtools note add "<the owner\'s words>" --stage <stage>');
+            return EXIT.error;
+        }
+        let stage = opts.stage ?? '';
+        if (!opts.stage) {
+            try {
+                stage = evaluate(root, p, null).current?.stage.id ?? ids[ids.length - 1] ?? '';
+            }
+            catch {
+                stage = ids[0] ?? '';
+            }
+        }
+        if (!ids.includes(stage)) {
+            u.error(`no stage ${stage} in design/pipeline.json`, `--stage one of ${ids.join(', ')}`);
+            return EXIT.error;
+        }
+        const by = opts.by === 'agent' ? 'agent' : 'owner';
+        if (opts.by && opts.by !== 'agent' && opts.by !== 'owner') {
+            u.error(`--by ${opts.by}`, '--by owner (default) or agent');
+            return EXIT.error;
+        }
+        if (opts.hold && by !== 'owner') {
+            u.error('only the owner holds the stage', 'funtools note add "<the owner\'s words>" --hold (the owner\'s note)');
+            return EXIT.error;
+        }
+        if (opts.screenshot && !existsSync(resolve(root, opts.screenshot)))
+            u.item('warn', `${opts.screenshot} does not exist in the game folder`, 'keep the owner\'s screenshot in the game (design/shots/) as the named before-frame');
+        const n = { id: nextId(p), stage, text, by, at: stamp(now), ...(opts.screenshot ? { screenshot: opts.screenshot } : {}), ...(opts.hold ? { hold: true } : {}), status: 'open' };
+        p.notes.push(n);
+        writePipeline(root, p);
+        if (opts.json)
+            io.log(JSON.stringify(n, null, 2));
+        else if (holdsStage(n))
+            u.summary('pass', `${n.id} on ${stage}: the owner holds the stage${opts.hold ? '' : ' (read from its words; `--hold` says so outright)'}. Shown as waiting on the owner, never a step; only they release it (\`funtools note close ${n.id} --by owner --force "<their words>"\`, when they say so)`);
+        else
+            u.summary('pass', `${n.id} on ${stage}: open until evidence closes it (\`funtools note close ${n.id} --evidence <path|sha|test>\`)`);
+        return EXIT.pass;
+    }
+    if (opts.sub === 'close') {
+        const id = /^n?\d+$/i.test(opts.args[0] ?? '') ? `N${opts.args[0].replace(/^n/i, '')}` : opts.args[0];
+        const n = p.notes.find((x) => x.id === id);
+        if (!n) {
+            u.error(id ? `no note ${id}` : 'which note?', 'funtools note lists them');
+            return EXIT.error;
+        }
+        const words = opts.args.slice(1).join(' ').replace(/\s+/g, ' ').trim();
+        const ev = opts.evidence?.trim();
+        const forced = !!opts.force && opts.by === 'owner';
+        if (opts.force && !forced) {
+            u.error('only the owner forces a close', ownerClose(n.id));
+            return EXIT.error;
+        }
+        if (forced && !ev) {
+            n.status = 'closed';
+            n.closed_by = { evidence: words ? `closed by the owner: ${words}` : 'closed by the owner', kind: 'owner', at: stamp(now), by: 'owner', forced: true, ...(words ? { words } : {}) };
+            writePipeline(root, p);
+            u.summary('pass', `${n.id} closed by the owner${words ? `: "${words}"` : ''}`);
+            return EXIT.pass;
+        }
+        if (!ev) {
+            u.error('a note closes with evidence', `funtools note close ${n.id} --evidence <a film or still, a commit sha, or a test name>${n.by === 'owner' ? `; or the owner's own word: ${ownerClose(n.id)}` : ''}`);
+            return EXIT.error;
+        }
+        if (holdsStage(n) && n.status === 'open') {
+            u.summary('fail', `${n.id} holds the stage: it is the owner's to release, never closed on evidence. When they say so, record their word: \`${ownerClose(n.id)}\``);
+            return EXIT.fail;
+        }
+        const kind = evidenceKind(root, ev);
+        if (!kind) {
+            u.summary('fail', `${ev} is not a file in the game, a commit or a test name in test/: ${n.id} stays open`);
+            return EXIT.fail;
+        }
+        let proof = { refused: [] };
+        if (n.by === 'owner' && !forced) {
+            proof = await closingProof(root, n, ev, kind);
+            if (proof.refused.length) {
+                for (const r of proof.refused)
+                    u.item('fail', r);
+                u.summary('fail', `${n.id} stays open: the owner's note closes on evidence that shows the fix (or on the owner's own word: \`${ownerClose(n.id)}\`)`);
+                return EXIT.fail;
+            }
+        }
+        n.status = 'closed';
+        n.closed_by = { evidence: ev, kind, at: stamp(now), by: opts.by === 'owner' ? 'owner' : 'agent', ...(forced ? { forced: true } : {}), ...(forced && words ? { words } : {}), ...(proof.world ? { world: proof.world } : {}), ...(proof.score ? { score: proof.score } : {}) };
+        if (n.verdict?.says === 'reject' && n.closed_by.by === 'agent' && n.verdict.at <= n.closed_by.at)
+            delete n.verdict;
+        writePipeline(root, p);
+        u.summary('pass', `${n.id} closed by ${kind} ${ev}${n.by === 'owner' ? ' — the owner\'s verdict still outranks it (`funtools note verdict ' + n.id + ' reject "…"` reopens it)' : ''}`);
+        return EXIT.pass;
+    }
+    const [given, says, ...words] = opts.args;
+    const what = /^n?\d+$/i.test(given ?? '') ? `N${given.replace(/^n/i, '')}` : given;
+    if (says !== 'accept' && says !== 'reject') {
+        u.error('a verdict is accept or reject', 'funtools note verdict <N|stage> accept|reject ["the owner\'s words"]');
+        return EXIT.error;
+    }
+    const v = { says, ...(words.length ? { words: words.join(' ') } : {}), at: stamp(now) };
+    const n = p.notes.find((x) => x.id === what);
+    if (n) {
+        n.verdict = v;
+        n.status = says === 'accept' ? 'closed' : 'open';
+        writePipeline(root, p);
+        u.summary(says === 'accept' ? 'pass' : 'warn', `${n.id}: the owner ${says === 'accept' ? 'accepts' : 'rejects'}${says === 'reject' ? ' — open again, first in `funtools flow`' : ''}`);
+        return EXIT.pass;
+    }
+    const chapter = /^chapter:/.test(what ?? '') && readChapters(root).some((c) => chapterStage(c.id) === what);
+    if (!ids.includes(what ?? '') && !chapter) {
+        u.error(`no note or stage ${what ?? ''}`, `a note id (N1…) or a stage: ${ids.join(', ')}`);
+        return EXIT.error;
+    }
+    p.verdicts = [...(p.verdicts ?? []), { stage: what, ...v }];
+    writePipeline(root, p);
+    u.summary(says === 'accept' ? 'pass' : 'warn', `the owner ${says === 'accept' ? 'accepts' : 'rejects'} ${what}${words.length ? `: "${words.join(' ')}"` : ''}`);
+    return EXIT.pass;
+}
+export const ownerClose = (id) => `funtools note close ${id} --by owner --force ["the owner's words"]`;
+export function designProof(root, n, ev, kind) {
+    const at = Date.parse(n.at);
+    const before = (t) => Number.isFinite(at) && t > 0 && t < at - 1000;
+    if (kind === 'test')
+        return [`${ev} is a test name: a design note closes on the design, a commit that changes the GDD or design/ (\`funtools note close ${n.id} --evidence <commit sha>\`)`];
+    if (kind === 'commit') {
+        const when = Number(spawnSync('git', ['-C', root, 'log', '-1', '--format=%ct', ev], { encoding: 'utf8' }).stdout?.trim()) * 1000;
+        const files = (spawnSync('git', ['-C', root, 'diff-tree', '--no-commit-id', '--name-only', '-r', '--root', '--relative', ev], { encoding: 'utf8' }).stdout ?? '').split('\n').filter(Boolean);
+        const design = files.filter(designPath);
+        const out = [];
+        if (!design.length)
+            out.push(`commit ${ev.slice(0, 10)} changes no design file (${files.slice(0, 3).join(', ') || 'nothing in this game'}): a design note closes on a commit that changes the GDD or design/`);
+        if (before(when))
+            out.push(`commit ${ev.slice(0, 10)} was made before the note (${new Date(when).toISOString().slice(0, 16)} < ${n.at.slice(0, 16)}): it cannot be its answer`);
+        return out;
+    }
+    const rel = relative(root, resolve(root, ev)).split(sep).join('/');
+    const out = [];
+    if (!designPath(rel))
+        out.push(`${rel} is not a design file: a design note closes on the GDD or a file in design/ (or a commit that changes them)`);
+    let mtime = 0;
+    try {
+        mtime = statSync(resolve(root, ev)).mtimeMs;
+    }
+    catch { }
+    if (before(mtime))
+        out.push(`${rel} was made before the note (${new Date(mtime).toISOString().slice(0, 16)} < ${n.at.slice(0, 16)}): it cannot be its answer`);
+    return out;
+}
+const BUILD_EVIDENCE = /^(\.funtools\/|design\/look\/scores\.json$)/;
+export async function closingProof(root, n, ev, kind) {
+    if (designNote(n))
+        return { refused: designProof(root, n, ev, kind) };
+    const refused = [];
+    const at = Date.parse(n.at);
+    if (kind !== 'file')
+        refused.push(`${ev} is a ${kind}: the owner's note closes on what the build shows — a capture (\`funtools capture\`), a walk/life/boxes record, or a score`);
+    else {
+        const abs = resolve(root, ev);
+        const rel = relative(root, abs).split(sep).join('/');
+        let index = {};
+        try {
+            index = JSON.parse(readFileSync(join(root, CAPTURE_INDEX), 'utf8')) ?? {};
+        }
+        catch { }
+        const captured = Object.values(index).some((x) => x?.file && resolve(root, x.file) === abs);
+        if (!captured && !BUILD_EVIDENCE.test(rel))
+            refused.push(`${rel} is not evidence of the build (a picture is not the game): capture the built game (\`funtools capture\`) or run walk/life/boxes/score, then close with that file`);
+        let mtime = 0;
+        try {
+            mtime = statSync(abs).mtimeMs;
+        }
+        catch { }
+        if (Number.isFinite(at) && mtime && mtime < at)
+            refused.push(`${rel} was made before the note (${new Date(mtime).toISOString().slice(0, 16)} < ${n.at.slice(0, 16)}): it cannot show the fix`);
+    }
+    if (!LOOK_NOTE.test(n.text))
+        return { refused };
+    const fp = (await fingerprint(root).catch(() => null))?.fingerprint ?? null;
+    const w = worldRead(root, fp);
+    if (w.state === 'failing')
+        refused.push(`the world read fails on the current files: ${w.warns.slice(0, 3).join('; ')} — fix it, then \`funtools check --world\``);
+    else if (w.state !== 'met')
+        refused.push(`the world was not read on the current files (${w.says}): \`funtools check --world\` (walk, or life + boxes)`);
+    let score;
+    try {
+        const p = readPipeline(root);
+        if (p) {
+            const g = evaluateGate(root, { kind: 'score' }, fp, p, n.stage);
+            if (g.state !== 'met')
+                refused.push(`the look against the plan's target: ${g.says} — \`funtools score --target\` (funpixel.json moments name the target frames)`);
+            else
+                score = g.says;
+        }
+    }
+    catch {
+        refused.push('the target score could not be read: `funtools score --target`');
+    }
+    return { refused, ...(w.state === 'met' ? { world: w.says } : {}), ...(score ? { score } : {}) };
+}