@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/compose-variations.js

@@ -0,0 +1,202 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { projectOf } from "./motion.js";
+import { COMPOSE_FPS, COMPOSE_LIMITS } from "../compose/contract.js";
+import { fixLines, HYPERFRAMES_VERSION, machine, QUALITIES } from "../compose/hyperframes.js";
+import { gameFacts } from "../compose/facts.js";
+import { prepare, renderStaged, shared, shown, stageBase, stagePage, writeRecord } from "../compose/run.js";
+import { ADS_BRIEF, ADS_COMPOSITIONS, ADS_OUT, coverage, ctaCheck, hookAt, planVariations, playableWords, readBrief, SELECTION_RULE, variationHtml, } from "../compose/variations.js";
+import { drawSheet, grabFrame } from "../compose/adsheet.js";
+const CUT_ID = /^\d{2}-h\d+-c\d+-\d+x\d+-[\d.]+s$/;
+export function indexOf(o) {
+    const sizes = [o.b.hooks.length, o.b.ctas.length, o.b.lengths.length, o.b.aspects.length];
+    const cov = coverage(o.plan.picks, sizes);
+    const verdicts = o.cuts.map((c) => c.verdict);
+    return {
+        brief: o.brief, game: o.game, renderer: { name: 'hyperframes', version: HYPERFRAMES_VERSION }, dry_run: o.dryRun,
+        verdict: o.dryRun ? null : verdicts.some((v) => v === 'fail' || v === 'error') ? 'fail' : verdicts.some((v) => v === 'not_observed') ? 'not_observed' : 'pass',
+        rule: SELECTION_RULE, made: o.cuts.length, possible: o.plan.possible, max: o.b.max,
+        coverage: {
+            hooks: o.b.hooks.map((h, i) => ({ line: h.line, cuts: cov.counts[0][i] })),
+            ctas: o.b.ctas.map((c, i) => ({ cta: c, cuts: cov.counts[1][i] })),
+            lengths: o.b.lengths.map((l, i) => ({ seconds: l, cuts: cov.counts[2][i] })),
+            aspects: o.b.aspects.map((a, i) => ({ aspect: a, cuts: cov.counts[3][i] })),
+            pairs: cov.pairs, repeated_pairs: cov.repeats,
+        },
+        playable: o.playable, sheet: o.sheet, warnings: o.warnings, ms: o.ms ?? null, browsers: o.browsers ?? 0, variations: o.cuts,
+    };
+}
+const rel = (dir, f) => (f ? relative(dir, f).split('\\').join('/') : null);
+export async function composeVariations(o, u, io) {
+    const say = (fn) => { if (!o.json)
+        fn(); };
+    const given = o.args[0];
+    const base = resolve(o.dir ?? '.');
+    const briefFile = given ? resolve(given) : [join(base, ADS_BRIEF), join(base, 'ads.json')].find((f) => existsSync(f)) ?? join(base, ADS_BRIEF);
+    if (!existsSync(briefFile)) {
+        u.error(`no brief at ${shown(briefFile)}`, `write ${ADS_BRIEF}: {"hooks": [{"line": "…", "moment": "chain"}], "ctas": ["Play now"], "lengths": [6, 15], "aspects": ["9:16", "1:1"], "end_card": {"title": "…"}, "max": 12}`);
+        return EXIT.error;
+    }
+    const gameDir = resolve(o.dir ?? projectOf(dirname(briefFile)) ?? dirname(briefFile));
+    if (!existsSync(join(gameDir, 'funpixel.json')) && !existsSync(join(gameDir, 'package.json'))) {
+        u.error(`${gameDir} is not a game folder`, '--dir names it');
+        return EXIT.error;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(briefFile, 'utf8'));
+    }
+    catch (e) {
+        u.error(`${shown(briefFile)} is not JSON: ${e.message}`);
+        return EXIT.error;
+    }
+    const max = o.max === undefined ? undefined : Number(o.max);
+    const read = readBrief(raw, max);
+    if ('errors' in read) {
+        for (const e of read.errors)
+            u.error(`${shown(briefFile)}: ${e}`);
+        return EXIT.error;
+    }
+    const b = read.brief;
+    const fps = o.fps === undefined ? COMPOSE_FPS : Number(o.fps);
+    if (!(Number.isInteger(fps) && fps >= COMPOSE_LIMITS.fps[0] && fps <= COMPOSE_LIMITS.fps[1])) {
+        u.error(`--fps is a whole number from ${COMPOSE_LIMITS.fps.join(' to ')}`);
+        return EXIT.error;
+    }
+    const quality = (o.quality ?? 'standard');
+    if (!QUALITIES.includes(quality)) {
+        u.error(`--quality is ${QUALITIES.join(', ')}`);
+        return EXIT.error;
+    }
+    const facts = gameFacts(gameDir);
+    const plan = planVariations(b, facts);
+    const playable = playableWords(gameDir);
+    const warnings = [...read.warnings, ...plan.warnings];
+    for (const c of b.ctas) {
+        const k = ctaCheck(c, playable);
+        if (k.state === 'warn')
+            warnings.push(k.says);
+    }
+    if (playable && playable.words === null)
+        warnings.push(`${playable.source} shows no call to action in its markup (drawn in code?): the end cards' words are not matched against it`);
+    const outDir = resolve(o.out ?? join(gameDir, ADS_OUT));
+    const sizes = [b.hooks.length, b.ctas.length, b.lengths.length, b.aspects.length];
+    const cov = coverage(plan.picks, sizes);
+    say(() => {
+        u.heading(`compose variations · ${shown(briefFile)}${o.dryRun ? ' · dry run' : ''}`);
+        u.item('note', `${plan.variations.length} of ${plan.possible} possible cuts (max ${b.max}): ${b.hooks.length} hook(s) × ${b.ctas.length} call(s) to action × ${b.lengths.length} length(s) × ${b.aspects.length} aspect(s)`);
+        u.item('note', `the rule: ${SELECTION_RULE}`);
+        const allShown = cov.counts.every((d) => d.every((n) => n > 0));
+        u.item(allShown ? 'pass' : 'warn', allShown ? `every hook, call to action, length and aspect is in a cut; ${cov.pairs.shown} of ${cov.pairs.of} pairs shown, ${cov.repeats} repeated` : `max ${b.max} is too few to show every value once`, allShown ? undefined : `--max ${Math.max(...sizes)} shows each at least once`);
+        if (playable?.words)
+            u.item('note', `the playable says "${playable.words}" (${playable.source})`);
+        for (const w of warnings)
+            u.item('warn', w);
+        for (const v of plan.variations)
+            u.line(`${v.id}  ${v.starter} ${v.seconds} s ${v.aspect}  "${v.hook.line}" → "${v.cta}"  opens on ${v.opens}`);
+    });
+    const entryOf = (v, d, extra = []) => ({
+        id: v.id, hook: v.hook.line, moment: v.hook.moment, opens: v.opens, cta: v.cta, length: v.seconds, aspect: v.aspect, starter: v.starter,
+        composition: v.composition, file: rel(gameDir, d?.video), sheet: rel(gameDir, d?.sheet), record: d ? rel(gameDir, join(outDir, v.id, `${v.id}.json`)) : null,
+        verdict: d ? (d.verdict === 'error' ? 'error' : d.verdict) : 'not_observed',
+        checks: [...(d?.checks ?? []), ...extra, ctaCheck(v.cta, playable)],
+        problems: (d?.problems ?? []).filter((p) => p.level === 'error').map((p) => `${p.says} — ${p.fix}`).concat(d?.error ? [d.error] : []),
+    });
+    if (o.dryRun) {
+        const index = indexOf({ brief: rel(gameDir, briefFile), game: gameDir, b, plan, playable, cuts: plan.variations.map((v) => entryOf(v, null)), sheet: null, warnings, dryRun: true });
+        if (o.json)
+            io.log(JSON.stringify(index, null, 2));
+        else
+            u.summary('pass', `the plan only: nothing written, nothing rendered (drop --dry-run to render ${plan.variations.length} cut(s) into ${shown(outDir)})`);
+        return EXIT.pass;
+    }
+    if (!existsSync(join(gameDir, 'dist', 'index.html'))) {
+        u.error('the game has no build (dist/index.html)', 'npm run build, then run variations again');
+        return EXIT.error;
+    }
+    const m = o.machine ?? machine();
+    const fixes = fixLines(m);
+    if (fixes.length) {
+        for (const f of fixes)
+            u.error(f);
+        return EXIT.error;
+    }
+    const compDir = join(gameDir, ADS_COMPOSITIONS);
+    await mkdir(compDir, { recursive: true });
+    for (const f of readdirSync(compDir))
+        if (f.endsWith('.html') && CUT_ID.test(f.slice(0, -5)))
+            await rm(join(compDir, f), { force: true });
+    for (const v of plan.variations)
+        await writeFile(join(gameDir, v.composition), variationHtml(v, facts));
+    await mkdir(outDir, { recursive: true });
+    for (const f of readdirSync(outDir))
+        if (CUT_ID.test(f) || f === 'index.json' || f === 'sheet.png')
+            await rm(join(outDir, f), { recursive: true, force: true });
+    const stage = join(outDir, '.stage');
+    await stageBase(stage, gameDir, true);
+    const s = await shared(gameDir, m, stage);
+    const cuts = [];
+    const cells = [];
+    let aborted = null;
+    const started = Date.now();
+    try {
+        for (const [i, v] of plan.variations.entries()) {
+            const file = join(gameDir, v.composition);
+            const prog = o.json ? null : u.progress();
+            prog?.update(`${i + 1}/${plan.variations.length} ${v.id}: rendering`);
+            const p = prepare(file, await readFile(file, 'utf8'), gameDir);
+            let d;
+            if (typeof p === 'string') {
+                d = { verdict: 'fail', file, name: v.id, comp: { id: '', width: 0, height: 0, duration: v.seconds, aspect: v.aspect, clips: [], games: [], files: [], usesGsap: false, hasGsapScript: false, registersTimeline: false, inline: '' }, problems: [{ level: 'error', says: p, fix: 'the starter wrote it: report it' }] };
+            }
+            else if (p.problems.some((x) => x.level === 'error')) {
+                d = { verdict: 'fail', file, name: v.id, comp: p.comp, problems: p.problems };
+            }
+            else {
+                await stagePage(stage, p, gameDir);
+                d = await renderStaged(p, { work: stage, out: join(outDir, v.id, `${v.id}.mp4`), record: join(outDir, v.id, `${v.id}.json`), fps, quality, software: !!o.software, check: false }, s, u, () => { });
+                if (d.verdict === 'error' && !d.findings)
+                    aborted = d.error ?? 'HyperFrames did not run';
+            }
+            d.record = join(outDir, v.id, `${v.id}.json`);
+            await writeRecord(d);
+            const frame = d.video ? join(outDir, v.id, `${v.id}.hook.jpg`) : null;
+            const grabbed = frame && d.video ? grabFrame(d.video, hookAt(v), frame) : false;
+            const entry = entryOf(v, d);
+            cuts.push(entry);
+            const warn = entry.checks.find((c) => c.state === 'warn');
+            cells.push({
+                id: v.id, frame: grabbed ? frame : null, verdict: entry.verdict, hook: v.hook.line, cta: v.cta, seconds: v.seconds, aspect: v.aspect, opens: v.opens,
+                ...(warn ? { warn: warn.says } : {}), ...(d.video ? {} : { why: entry.problems[0] ?? 'not rendered' }),
+            });
+            const failed = entry.checks.filter((c) => c.state === 'fail').map((c) => `${c.id}: ${c.says}`);
+            prog?.done(entry.verdict === 'pass' ? 'pass' : entry.verdict === 'error' ? 'fail' : entry.verdict, `${v.id}: ${entry.verdict === 'error' ? 'not rendered' : entry.verdict.replace('_', ' ')}${failed.length ? ` — ${failed.join('; ')}` : entry.problems.length ? ` — ${entry.problems[0]}` : ''}${warn ? ` (warn: ${warn.says})` : ''}`);
+            if (aborted)
+                break;
+        }
+        const sheet = join(outDir, 'sheet.png');
+        const title = `${facts.title}: ${cuts.length} ad cut${cuts.length === 1 ? '' : 's'} from ${rel(gameDir, briefFile)}`;
+        const drew = cells.length ? await drawSheet(await s.probes.browser(), title, cells, sheet).catch(() => false) : false;
+        const index = indexOf({ brief: rel(gameDir, briefFile), game: gameDir, b, plan, playable, cuts, sheet: drew ? rel(gameDir, sheet) : null, warnings, dryRun: false, ms: Date.now() - started, browsers: s.probes.launches });
+        await writeFile(join(outDir, 'index.json'), JSON.stringify(index, null, 2) + '\n');
+        if (o.json)
+            io.log(JSON.stringify(index, null, 2));
+        else {
+            if (aborted)
+                u.error(`stopped after ${cuts.length} of ${plan.variations.length}: ${aborted}`);
+            u.line(shown(join(outDir, 'index.json')));
+            if (drew)
+                u.line(`${shown(sheet)} — a labelled frame per cut; look at it, and the person picks which to publish`);
+            const n = (v) => cuts.filter((c) => c.verdict === v).length;
+            u.summary(index.verdict === 'pass' ? 'pass' : index.verdict === 'fail' ? 'fail' : 'not_observed', `${n('pass')} passed, ${n('fail') + n('error')} failed${n('not_observed') ? `, ${n('not_observed')} not observed` : ''} of ${cuts.length}, in ${Math.round((Date.now() - started) / 1000)} s (one stage, ${s.probes.launches} probe browser)`);
+        }
+        if (aborted)
+            return EXIT.error;
+        return index.verdict === 'pass' ? EXIT.pass : index.verdict === 'fail' ? EXIT.fail : EXIT.not_observed;
+    }
+    finally {
+        await s.probes.close();
+    }
+}

package/dist/commands/compose.js

@@ -0,0 +1,163 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { projectOf } from "./motion.js";
+import { COMPOSE_ASPECTS, COMPOSE_ASPECT_NAMES, COMPOSE_DIR, COMPOSE_FPS, COMPOSE_LIMITS } from "../compose/contract.js";
+import { fixLines, HYPERFRAMES_VERSION, machine, QUALITIES } from "../compose/hyperframes.js";
+import { gameFacts } from "../compose/facts.js";
+import { starter, STARTER_DEFAULTS, STARTERS } from "../compose/starters.js";
+import { COMPOSE_SEED, prepare, recordOf, renderStaged, shared, shown, stageBase, stagePage, writeRecord } from "../compose/run.js";
+import { composeVariations } from "./compose-variations.js";
+import { ui } from "../ui.js";
+export { COMPOSE_DIR };
+export const COMPOSE_SUBCOMMANDS = ['new', 'check', 'render', 'variations'];
+export { COMPOSE_SEED };
+export async function compose(o, io = console) {
+    const u = ui(io, 'compose');
+    if (!o.sub) {
+        u.error(`compose takes ${COMPOSE_SUBCOMMANDS.join(', ')}`, 'funtools compose new trailer, then funtools compose render design/compose/trailer.html');
+        return EXIT.error;
+    }
+    const aspect = o.aspect === undefined ? undefined : o.aspect.replace('x', ':');
+    if (aspect !== undefined && !COMPOSE_ASPECT_NAMES.includes(aspect)) {
+        u.error(`--aspect ${o.aspect}`, `--aspect is ${COMPOSE_ASPECT_NAMES.join(', ')}`);
+        return EXIT.error;
+    }
+    const seconds = o.seconds === undefined ? undefined : Number(o.seconds);
+    if (seconds !== undefined && !(seconds >= COMPOSE_LIMITS.seconds[0] && seconds <= COMPOSE_LIMITS.seconds[1])) {
+        u.error(`--seconds is a number from ${COMPOSE_LIMITS.seconds.join(' to ')}`);
+        return EXIT.error;
+    }
+    if (o.sub === 'new')
+        return composeNew(o, u, io, aspect, seconds);
+    if (o.sub === 'variations')
+        return composeVariations(o, u, io);
+    return composeRun(o, u, io, aspect, seconds);
+}
+async function composeNew(o, u, io, aspect, seconds) {
+    const kind = o.args[0];
+    if (!kind || !STARTERS.includes(kind)) {
+        u.error(`compose new takes a starter: ${STARTERS.join(', ')}`, 'funtools compose new trailer');
+        return EXIT.error;
+    }
+    const dir = resolve(o.args[1] ?? o.dir ?? '.');
+    if (!existsSync(join(dir, 'funpixel.json')) && !existsSync(join(dir, 'package.json'))) {
+        u.error(`${dir} is not a game folder`, 'run it in the game folder, or name it: funtools compose new trailer path/to/game');
+        return EXIT.error;
+    }
+    const name = o.name ?? kind;
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/i.test(name)) {
+        u.error('--name: letters, digits and - (it becomes design/compose/<name>.html)');
+        return EXIT.error;
+    }
+    const file = join(dir, COMPOSE_DIR, `${name}.html`);
+    if (existsSync(file) && !o.force) {
+        u.error(`${shown(file)} is there already`, 'edit it, pick another --name, or --force to start over');
+        return EXIT.error;
+    }
+    const facts = gameFacts(dir);
+    const html = starter(kind, facts, { aspect, seconds });
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, html);
+    const a = aspect ?? STARTER_DEFAULTS[kind].aspect, s = seconds ?? STARTER_DEFAULTS[kind].seconds;
+    if (o.json) {
+        io.log(JSON.stringify({ composition: file, starter: kind, aspect: a, seconds: s, facts }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`compose new ${kind} · ${shown(file)}`);
+    u.item('pass', `${s} s at ${a} (${COMPOSE_ASPECTS[a].join('x')}), the game live${facts.playView ? ` in its "${facts.playView}" view` : ' (no view known: capture --all names them)'}, driven by its own verbs ("auto")`);
+    u.item(facts.keyArt ? 'pass' : 'warn', facts.keyArt ? `key art: ${facts.keyArt}` : 'no key art found (design/key-art.png): the cards fall back to the palette', facts.keyArt ? undefined : 'funtools gen image "key art …" --out design/key-art.png');
+    u.item(facts.captures.length ? 'pass' : 'note', facts.captures.length ? `captures: ${facts.captures.length} (.funtools/capture/)` : 'no captures yet: the trailer\'s strip of real frames is left out', facts.captures.length ? undefined : 'funtools capture --all, then compose new again --force');
+    u.item(facts.music ? 'pass' : 'note', facts.music ? `music bed: ${facts.music}` : 'no music found: the video is silent unless you add an <audio> clip');
+    if (facts.moment)
+        u.item('pass', `payoff moment: the "${facts.moment}" view, live`);
+    u.line('Fill in the words (data-composition-variables: title, tagline, caption1, caption2, cta), move clips by their data-start / data-duration, then:');
+    u.line(`funtools compose render ${shown(file)}`);
+    return EXIT.pass;
+}
+async function composeRun(o, u, io, aspect, seconds) {
+    const say = (fn) => { if (!o.json)
+        fn(); };
+    const arg = o.args[0];
+    if (!arg) {
+        u.error(`compose ${o.sub} needs a composition`, `funtools compose ${o.sub} design/compose/trailer.html`);
+        return EXIT.error;
+    }
+    const file = resolve(arg);
+    if (!existsSync(file) || !/\.html?$/i.test(file)) {
+        u.error(`no composition at ${arg}`, 'funtools compose new trailer writes one');
+        return EXIT.error;
+    }
+    const gameDir = resolve(o.dir ?? projectOf(dirname(file)) ?? dirname(file));
+    const fps = o.fps === undefined ? COMPOSE_FPS : Number(o.fps);
+    if (!(Number.isInteger(fps) && fps >= COMPOSE_LIMITS.fps[0] && fps <= COMPOSE_LIMITS.fps[1])) {
+        u.error(`--fps is a whole number from ${COMPOSE_LIMITS.fps.join(' to ')}`);
+        return EXIT.error;
+    }
+    const quality = (o.quality ?? 'standard');
+    if (!QUALITIES.includes(quality)) {
+        u.error(`--quality is ${QUALITIES.join(', ')}`);
+        return EXIT.error;
+    }
+    const p = prepare(file, await readFile(file, 'utf8'), gameDir, { aspect, seconds });
+    if (typeof p === 'string') {
+        u.error(p);
+        return EXIT.fail;
+    }
+    const { comp, problems, name } = p;
+    say(() => {
+        u.heading(`compose ${o.sub} · ${shown(file)}`);
+        u.item('note', `${comp.width}x${comp.height}${comp.aspect ? ` (${comp.aspect})` : ''}, ${comp.duration} s, ${comp.clips.length} clips${comp.games.length ? `, ${comp.games.length} live game clip${comp.games.length > 1 ? 's' : ''}` : ''}`);
+        for (const x of problems)
+            u.item(x.level === 'error' ? 'fail' : 'warn', x.says, x.fix);
+    });
+    if (problems.some((x) => x.level === 'error'))
+        return finish(o, io, u, { verdict: 'fail', file, name, comp, problems });
+    const m = o.machine ?? machine();
+    const fixes = fixLines(m);
+    if (fixes.length) {
+        say(() => { for (const f of fixes)
+            u.error(f); });
+        if (o.json)
+            io.log(JSON.stringify({ verdict: 'error', composition: file, fixes }, null, 2));
+        return EXIT.error;
+    }
+    const base = join(gameDir, '.funtools', 'compose');
+    const work = join(base, name);
+    await stageBase(work, gameDir, comp.games.length > 0);
+    await stagePage(work, p, gameDir);
+    const s = await shared(gameDir, m, work);
+    let d;
+    try {
+        d = await renderStaged(p, { work, out: resolve(o.out ?? join(base, `${name}.mp4`)), fps, quality, software: !!o.software, check: o.sub === 'check' }, s, u, say);
+    }
+    finally {
+        await s.probes.close();
+    }
+    if (d.verdict === 'error') {
+        if (o.json)
+            io.log(JSON.stringify({ verdict: 'error', composition: file, error: d.error }, null, 2));
+        return EXIT.error;
+    }
+    return finish(o, io, u, d);
+}
+async function finish(o, io, u, d) {
+    await writeRecord(d);
+    if (o.json) {
+        io.log(JSON.stringify(recordOf(d), null, 2));
+        return d.verdict === 'pass' ? EXIT.pass : d.verdict === 'fail' ? EXIT.fail : EXIT.not_observed;
+    }
+    for (const c of d.checks ?? [])
+        u.item(c.state, `${c.id}: ${c.says}`);
+    if (d.video) {
+        u.line(shown(d.video));
+        if (d.sheet)
+            u.line(`${shown(d.sheet)} — 12 frames at ${(d.times ?? []).map((t) => `${t}s`).join(' ')}; look at it before you use the video`);
+        u.summary(d.verdict === 'pass' ? 'pass' : 'fail', `${d.comp.duration} s, ${d.comp.width}x${d.comp.height} at ${d.fps} fps (${((d.bytes ?? 0) / 1_048_576).toFixed(2)} MB), rendered by HyperFrames ${HYPERFRAMES_VERSION}`);
+    }
+    else if (d.verdict !== 'pass') {
+        u.summary(d.verdict === 'fail' ? 'fail' : 'not_observed', d.verdict === 'fail' ? 'fix the composition and run it again' : 'nothing rendered');
+    }
+    return d.verdict === 'pass' ? EXIT.pass : d.verdict === 'fail' ? EXIT.fail : EXIT.not_observed;
+}

package/dist/commands/cut.js

@@ -0,0 +1,13 @@
+import { basename, dirname, extname, join } from 'node:path';
+import { parts, PARTS_DEFAULTS } from "./parts.js";
+export function cutDefaults(o) {
+    return {
+        sheet: o.sheet, grid: o.grid, boxes: o.boxes, names: o.names ?? [],
+        out: o.out ?? join(dirname(o.sheet), `${basename(o.sheet, extname(o.sheet))}-cut`),
+        key: o.key ?? { kind: 'paper' }, pivot: o.pivot ?? 'bottom', pad: o.pad ?? PARTS_DEFAULTS.pad, merge: o.merge ?? PARTS_DEFAULTS.merge,
+        webp: !!o.webp, json: !!o.json, clean: true, keepShadows: !!o.keepShadows, as: 'cut',
+    };
+}
+export async function cut(opts, io = console) {
+    return parts(cutDefaults(opts), io);
+}

package/dist/commands/decide.js

@@ -0,0 +1,90 @@
+import { resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { addDecision, DECISIONS_FILE, decisionLine, liveDecisions, readDecisions } from "../memory/decisions.js";
+import { readPipeline } from "../pipeline/pipeline.js";
+import { touchesOfWords } from "../lanes/lanes.js";
+import { ui } from "../ui.js";
+export async function decide(opts, io = console, now = new Date()) {
+    const u = ui(io, 'decide');
+    const root = resolve(opts.dir ?? '.');
+    if (opts.from)
+        return fromNote(root, opts, u, io, now);
+    const choice = opts.text?.replace(/\s+/g, ' ').trim();
+    if (!choice) {
+        const all = readDecisions(root);
+        const live = liveDecisions(all);
+        if (opts.json) {
+            io.log(JSON.stringify({ file: DECISIONS_FILE, live, superseded: all.filter((d) => d.supersededBy) }, null, 2));
+            return all.length ? EXIT.pass : EXIT.not_observed;
+        }
+        u.heading(`decisions · ${live.length} live, ${all.length - live.length} superseded`);
+        if (!all.length) {
+            u.item('note', `none in ${DECISIONS_FILE} yet`, 'funtools decide "tap to jump" --over "swipe up" --because "one thumb on a bus"');
+            return EXIT.not_observed;
+        }
+        for (const d of live)
+            u.line(decisionLine(d).slice(2));
+        for (const d of all.filter((x) => x.supersededBy))
+            u.line(`${d.id} ${d.choice} — superseded by ${d.supersededBy}`, 1);
+        return EXIT.pass;
+    }
+    const because = opts.because?.replace(/\s+/g, ' ').trim();
+    if (!because) {
+        u.error('a decision carries its reason', 'funtools decide "tap to jump" --over "swipe up" --because "one thumb on a bus"');
+        return EXIT.error;
+    }
+    const supersedes = (opts.supersedes ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    if (supersedes.some((s) => !/^D?\d+$/i.test(s))) {
+        u.error(`--supersedes takes ids like D3, got "${opts.supersedes}"`, 'funtools decide lists them');
+        return EXIT.error;
+    }
+    let d;
+    try {
+        d = addDecision(root, { choice, because, ...(opts.over?.trim() ? { over: opts.over } : {}), supersedes }, now);
+    }
+    catch (e) {
+        u.error(e instanceof Error ? e.message : String(e), 'funtools decide lists the ids and what replaced what');
+        return EXIT.error;
+    }
+    if (opts.json) {
+        io.log(JSON.stringify({ file: DECISIONS_FILE, decision: d }, null, 2));
+        return EXIT.pass;
+    }
+    if (!d.over)
+        u.item('note', 'no alternative named', 'a decision reads best against what it was chosen over (--over); later sessions re-argue the ones that name none');
+    u.summary('pass', `${d.id} recorded in ${DECISIONS_FILE}${d.supersedes.length ? `; ${d.supersedes.join(', ')} marked superseded` : ''}`);
+    return EXIT.pass;
+}
+function fromNote(root, opts, u, io, now) {
+    const id = /^n?\d+$/i.test(opts.from ?? '') ? `N${opts.from.replace(/^n/i, '')}` : opts.from;
+    const n = readPipeline(root)?.notes.find((x) => x.id === id);
+    if (!n) {
+        u.error(`no note ${id} in design/pipeline.json`, 'funtools note lists them');
+        return EXIT.error;
+    }
+    if (n.by !== 'owner') {
+        u.error(`${id} is an agent's note`, 'a decision from a note cites the owner\'s words; record an agent\'s choice with `funtools decide "…" --because "…"`');
+        return EXIT.error;
+    }
+    const had = readDecisions(root).find((d) => d.from === id);
+    if (had) {
+        if (opts.json)
+            io.log(JSON.stringify({ file: DECISIONS_FILE, decision: had, existing: true }, null, 2));
+        else
+            u.summary('pass', `${id} is already ${had.id}: ${had.choice}`);
+        return EXIT.pass;
+    }
+    const touches = opts.touches ? opts.touches.split(',').map((s) => s.trim()).filter(Boolean) : touchesOfWords(n.text);
+    const d = addDecision(root, {
+        choice: opts.text?.replace(/\s+/g, ' ').trim() || n.text,
+        ...(opts.over?.trim() ? { over: opts.over } : {}),
+        because: opts.because?.replace(/\s+/g, ' ').trim() || `the owner said so (${id}, ${n.at.slice(0, 10)})`,
+        owner: n.text, from: id, ...(n.screenshot ? { shot: n.screenshot } : {}), touches, status: 'open',
+    }, now);
+    if (opts.json) {
+        io.log(JSON.stringify({ file: DECISIONS_FILE, decision: d }, null, 2));
+        return EXIT.pass;
+    }
+    u.summary('pass', `${d.id} from the owner's ${id} in ${DECISIONS_FILE}: open until a lane builds it${touches.length ? `; it touches ${touches.join(', ')}` : '; it names nothing, so every lane brief carries it'}`);
+    return EXIT.pass;
+}

package/dist/commands/depth.js

@@ -0,0 +1,171 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { designDoc } from "../gdd/doc.js";
+import { scoreExperience } from "../gdd/rubric.js";
+import { designInventory, shippedInventory, textMarkdown } from "../depth/inventory.js";
+import { pacingOf, samplesFromJourney, samplesFromPlayLog } from "../depth/pacing.js";
+import { declaredStory, storyLine, tellsAStory, storyReport, storySeen } from "../depth/story.js";
+import { contentReached, fillDesign } from "../depth/fill.js";
+import { byEvidence, DIMENSION_NAME, DIMENSIONS, experienceFacts, experienceText } from "../depth/experience.js";
+import { PLAY_DIR } from "../play/session.js";
+import { JOURNEY_RUNS } from "../journey/script.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { decodePng, encodePng } from "../look/png.js";
+import { contactSheet } from "../playtest/sheet.js";
+import { ui } from "../ui.js";
+export const DEPTH_DIR = join('.funtools', 'depth');
+const readJson = (f) => { try {
+    return JSON.parse(readFileSync(f, 'utf8'));
+}
+catch {
+    return null;
+} };
+function playSessions(root, fields) {
+    const base = join(root, PLAY_DIR);
+    const pacing = [];
+    const comeBack = [];
+    const story = [];
+    if (!existsSync(base))
+        return { pacing, comeBack, story };
+    const rounds = readdirSync(base).map((d) => /^round-(\d+)$/.exec(d)).filter((m) => !!m).map((m) => Number(m[1])).sort((a, b) => a - b);
+    for (const n of rounds) {
+        const dir = join(base, `round-${n}`);
+        let lines = [];
+        try {
+            lines = readFileSync(join(dir, 'log.jsonl'), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+        }
+        catch {
+            continue;
+        }
+        const report = readJson(join(dir, 'report.json'));
+        const samples = samplesFromPlayLog(lines, report?.viewport !== 'desktop');
+        const source = `blind round ${n}${report ? (report.viewport ? ` (${report.viewport})` : '') : ' (no report filed)'}`;
+        if (samples.length >= 2) {
+            pacing.push({ ...pacingOf(source, samples, fields), dir });
+            story.push(storySeen(source, samples));
+        }
+        const cb = report?.come_back;
+        if (cb && typeof cb.answer === 'string')
+            comeBack.push({ round: n, answer: cb.answer, why: String(cb.why ?? ''), first: String(cb.first ?? ''), played_minutes: typeof report.played_minutes === 'number' ? report.played_minutes : null });
+    }
+    return { pacing, comeBack, story };
+}
+function journeySessions(root, fields) {
+    const base = join(root, JOURNEY_RUNS);
+    const out = [];
+    const story = [];
+    if (!existsSync(base))
+        return { pacing: out, story };
+    for (const name of readdirSync(base)) {
+        const runs = existsSync(join(base, name)) ? readdirSync(join(base, name)).filter((d) => /^\d+$/.test(d)).map(Number).sort((a, b) => a - b) : [];
+        const last = runs.at(-1);
+        if (last === undefined)
+            continue;
+        const run = readJson(join(base, name, String(last), 'run.json'));
+        if (!run?.marks)
+            continue;
+        const samples = samplesFromJourney(run.marks);
+        if (samples.length >= 2) {
+            out.push({ ...pacingOf(`journey ${name} run ${last}`, samples, fields), dir: join(base, name, String(last)) });
+            story.push(storySeen(`journey ${name} run ${last}`, samples));
+        }
+    }
+    return { pacing: out, story };
+}
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+function beatsMarkdown(p) {
+    if (!p)
+        return 'No real play with the game\'s state was found: nothing to lay out (funtools play, funtools journey).\n';
+    const rows = p.beats.map((b) => `| ${mmss(b.t)} | ${b.step} | ${b.kind} | ${b.says} | ${b.shot ? join(p.dir, b.shot) : '—'} |`);
+    return [`# Beat strip: ${p.source}`, '', `${mmss(p.seconds)} of game time; ${p.beats.length} beats. Game time counts only the steps played (the clock is held while the player thinks).`, '',
+        '| Game time | Step | Beat | What changed | Frame |', '|---|---|---|---|---|', ...rows, ''].join('\n');
+}
+async function stripOf(p, out) {
+    if (!p)
+        return null;
+    const order = { outcome: 0, place: 1, 'tension-peak': 2, payoff: 3, 'tension-release': 4, first: 5, screen: 6 };
+    const seen = new Set();
+    const withShot = p.beats.filter((b) => b.shot && !seen.has(b.shot) && (seen.add(b.shot), existsSync(join(p.dir, b.shot))));
+    const picked = [...withShot].sort((a, b) => order[a.kind] - order[b.kind]).slice(0, 12).sort((a, b) => a.t - b.t);
+    if (picked.length < 2)
+        return null;
+    const frames = await Promise.all(picked.map(async (b) => decodePng(await readFile(join(p.dir, b.shot)))));
+    const file = join(out, 'beats.png');
+    await writeFile(file, encodePng(contactSheet(frames, 4, 240)));
+    return file;
+}
+export async function depth(opts, io = console) {
+    const u = ui(io, 'depth');
+    const root = resolve(opts.target ?? '.');
+    if (!existsSync(root)) {
+        u.error(`no such folder: ${root}`);
+        return EXIT.error;
+    }
+    const out = resolve(opts.out ?? join(root, DEPTH_DIR));
+    const fields = { place: opts.place, tension: opts.tension, progress: opts.progress };
+    try {
+        const doc = designDoc(root);
+        const design = designInventory(doc?.text ?? null, doc?.rel ?? null);
+        const shipped = shippedInventory(root);
+        const plays = playSessions(root, fields);
+        const journeys = journeySessions(root, fields);
+        const pacing = [...plays.pacing, ...journeys.pacing];
+        const sim = readJson(join(root, '.funtools', 'sim.json'));
+        const story = storyReport(declaredStory(doc?.text ?? null), [...plays.story, ...journeys.story]);
+        const content_reached = contentReached(doc?.text ?? null, pacing, story, sim);
+        let filled = 0;
+        if (opts.fill && doc) {
+            const file = join(root, doc.rel);
+            const filledDoc = fillDesign(readFileSync(file, 'utf8'), content_reached, story);
+            if (filledDoc.filled)
+                await writeFile(file, filledDoc.text);
+            filled = filledDoc.filled;
+        }
+        const gdd = doc ? scoreExperience(doc.text) : null;
+        const facts = experienceFacts({
+            sim, feel: readJson(join(root, '.funtools', 'feel.json')),
+            design, shipped, pacing, comeBack: plays.comeBack, gdd: gdd?.addressed ?? null, story: storyLine(story, shipped.text.length),
+        });
+        await mkdir(out, { recursive: true });
+        const longest = byEvidence(pacing)[0];
+        const files = { facts: join(out, 'facts.md'), text: join(out, 'text.md'), beats: join(out, 'beats.md'), strip: await stripOf(longest, out) };
+        await writeFile(files.facts, `# Experience facts\n\n${experienceText(facts)}\n`);
+        await writeFile(files.text, `# What a player can read\n\n${textMarkdown(shipped)}`);
+        await writeFile(files.beats, beatsMarkdown(longest));
+        const { text, ...counts } = shipped;
+        const record = {
+            tool: 'funtools', command: 'depth', at: new Date().toISOString(), fingerprint: existsSync(join(root, 'funpixel.json')) ? (await fingerprint(root).catch(() => null))?.fingerprint ?? null : null,
+            design, shipped: { ...counts, lines: text.length }, pacing, come_back: plays.comeBack, gdd, story, content_reached, filled, facts, files,
+        };
+        await writeFile(join(out, 'depth.json'), JSON.stringify(record, null, 2) + '\n');
+        if (opts.json) {
+            io.log(JSON.stringify(record, null, 2));
+            return EXIT.pass;
+        }
+        u.heading('experience facts (X…, what the experience seats read first)');
+        for (const f of facts)
+            u.item(/not measured|none|not asked|not addressed/.test(f.text) ? 'not_observed' : 'note', `${f.id} ${f.instrument}`, f.text);
+        if (gdd) {
+            u.heading(`the design document on the experience dimensions (${gdd.score.toFixed(1)}/10, ${gdd.version})`);
+            for (const k of DIMENSIONS)
+                u.item(gdd.addressed[k] === 2 ? 'pass' : gdd.addressed[k] ? 'note' : 'warn', DIMENSION_NAME[k], gdd.why[k] || undefined);
+        }
+        u.heading('story and content, declared against played');
+        u.item(story.state === 'measured' && !story.never.length ? 'pass' : story.state === 'measured' || story.state === 'no-field' || tellsAStory(story, shipped.text.length) ? 'warn' : 'note', `story: ${storyLine(story, shipped.text.length)}`);
+        for (const r of content_reached)
+            u.item(r.reached ? 'note' : 'not_observed', `${r.content}${r.count !== null ? ` (${r.count})` : ''}: ${r.reached ? `reached ${r.reached}` : 'not measured in play'}`);
+        if (opts.fill)
+            u.line(filled ? `wrote ${filled} cell(s) into ${doc?.rel} (Reached in play, Seen in play)` : 'nothing to write into the design document', 1);
+        else if (content_reached.some((r) => r.reached) || story.state === 'measured')
+            u.line('--fill writes these into the design document\'s Reached in play / Seen in play columns', 1);
+        u.line(`${out}: depth.json, facts.md, text.md (${shipped.text.length} lines), beats.md${files.strip ? ', beats.png' : ''}`, 0);
+        u.summary('pass', 'a mirror of depth, content, replay and pacing — the experience seats judge them (funtools playtest)');
+        return EXIT.pass;
+    }
+    catch (e) {
+        u.error(`depth failed: ${e.message}`);
+        return EXIT.error;
+    }
+}