@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/board.js

@@ -0,0 +1,162 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { BOARD_DIR, BOARD_FILE, boardHtml, boardProblems, LENDS, readBoard, relatedUrl, search, searchUrl, shippedCopies, } from "../board/board.js";
+import { ui } from "../ui.js";
+export const BOARD_SUBCOMMANDS = ['show', 'search', 'wander', 'add'];
+function parseLends(v) {
+    const l = (v ?? '').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+    if (!l.length)
+        return `--lends names what the picture lends: one or two of ${LENDS.join(', ')}`;
+    const bad = l.filter((x) => !LENDS.includes(x));
+    if (bad.length)
+        return `--lends ${bad.join(', ')}: use ${LENDS.join(', ')}`;
+    return l;
+}
+async function save(root, refs) {
+    await mkdir(join(root, BOARD_DIR), { recursive: true });
+    await writeFile(join(root, BOARD_FILE), JSON.stringify({ version: 1, refs }, null, 2) + '\n');
+}
+export async function board(opts, io = console) {
+    const u = ui(io, 'board');
+    const root = resolve(opts.dir ?? '.');
+    const now = (opts.now ?? new Date()).toISOString();
+    const b = readBoard(root);
+    const fetcher = opts.fetcher ?? ((url) => fetch(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(15_000) }));
+    const nextId = () => `R${b.refs.reduce((m, r) => Math.max(m, Number(r.id.slice(1)) || 0), 0) + 1}`;
+    if (opts.sub === 'search' || opts.sub === 'wander') {
+        if (!opts.arg) {
+            u.error(opts.sub === 'search' ? 'search needs words' : 'wander needs a kept reference id', opts.sub === 'search' ? 'funtools board search "fog over a harbour at dawn"' : 'funtools board wander R2');
+            return EXIT.error;
+        }
+        let url, foundBy;
+        if (opts.sub === 'wander') {
+            const from = b.refs.find((r) => r.id === opts.arg);
+            if (!from) {
+                u.error(`no reference ${opts.arg} on the board`);
+                return EXIT.error;
+            }
+            if (from.source !== 'openverse' || !from.page) {
+                u.error(`${opts.arg} is not from the open collection: wander follows open-collection pictures only`);
+                return EXIT.error;
+            }
+            const ov = from.openverse_id;
+            if (!ov) {
+                u.error(`${opts.arg} has no open-collection id to wander from`);
+                return EXIT.error;
+            }
+            url = relatedUrl(ov);
+            foundBy = `wander from ${from.id}`;
+        }
+        else {
+            url = searchUrl(opts.arg, { limit: opts.limit, commercial: !opts.anyLicence });
+            foundBy = `search "${opts.arg}"`;
+        }
+        let hits;
+        try {
+            hits = await search(fetcher, url);
+        }
+        catch (e) {
+            u.error(`the open collection could not be reached: ${e.message}`, 'add your own pictures with `board add <file>` instead');
+            return EXIT.error;
+        }
+        if (!hits.length) {
+            if (opts.json)
+                io.log(JSON.stringify({ verdict: 'not_observed', hits: [] }));
+            u.summary('not_observed', 'nothing found: other words, or --any-licence');
+            return EXIT.not_observed;
+        }
+        if (opts.keep) {
+            const lends = parseLends(opts.lends);
+            if (typeof lends === 'string') {
+                u.error(lends);
+                return EXIT.error;
+            }
+            const picks = opts.keep.split(',').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n >= 1 && n <= hits.length);
+            if (!picks.length) {
+                u.error(`--keep ${opts.keep}`, `numbers from the list, 1 to ${hits.length}`);
+                return EXIT.error;
+            }
+            const kept = [];
+            for (const n of picks) {
+                const h = hits[n - 1];
+                if (b.refs.some((r) => r.src === h.url))
+                    continue;
+                const ref = { id: nextId(), src: h.url, title: h.title, by: h.by, licence: h.licence, page: h.page, source: 'openverse', lends, ...(opts.note ? { note: opts.note } : {}), added: now, found_by: `${foundBy} (openverse:${h.id})`, openverse_id: h.id };
+                b.refs.push(ref);
+                kept.push(ref);
+            }
+            await save(root, b.refs);
+            if (opts.json) {
+                io.log(JSON.stringify({ verdict: 'pass', kept }, null, 2));
+                return EXIT.pass;
+            }
+            for (const k of kept)
+                u.item('pass', `${k.id} kept`, `${k.title || k.src} · ${k.licence} · lends ${k.lends.join(', ')}`);
+            u.summary('pass', `${kept.length} kept on the board (${BOARD_FILE}); \`funtools board\` draws it`);
+            return EXIT.pass;
+        }
+        if (opts.json) {
+            io.log(JSON.stringify({ verdict: 'pass', url, hits }, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`board ${opts.sub} · ${hits.length} open-licence picture(s)`);
+        hits.forEach((h, i) => u.item('note', `${i + 1}. ${h.title || h.id}`, `${h.by ? `${h.by} · ` : ''}${h.licence} · ${h.thumb}`));
+        u.summary('pass', `look at them, then keep what lends something: --keep 2,5 --lends light,palette --note "the cold rim light"`);
+        return EXIT.pass;
+    }
+    if (opts.sub === 'add') {
+        if (!opts.arg) {
+            u.error('add needs a link or a file', 'funtools board add design/board/harbour.jpg --lends light --licence "own photo"');
+            return EXIT.error;
+        }
+        const lends = parseLends(opts.lends);
+        if (typeof lends === 'string') {
+            u.error(lends);
+            return EXIT.error;
+        }
+        const isLink = /^https?:\/\//.test(opts.arg);
+        if (!isLink && !existsSync(resolve(root, opts.arg))) {
+            u.error(`no file ${opts.arg}`);
+            return EXIT.error;
+        }
+        if (!opts.licence) {
+            u.error('--licence is required: "own photo", "CC BY 4.0", "permission from …", or "look only" for a picture you may study but not share');
+            return EXIT.error;
+        }
+        const ref = { id: nextId(), src: isLink ? opts.arg : relative(root, resolve(root, opts.arg)), title: opts.title ?? basename(opts.arg), ...(opts.by ? { by: opts.by } : {}), licence: opts.licence, source: isLink ? 'link' : 'file', lends, ...(opts.note ? { note: opts.note } : {}), added: now };
+        b.refs.push(ref);
+        await save(root, b.refs);
+        if (opts.json) {
+            io.log(JSON.stringify({ verdict: 'pass', kept: [ref] }, null, 2));
+            return EXIT.pass;
+        }
+        u.summary('pass', `${ref.id} kept: lends ${lends.join(', ')} (${ref.licence})`);
+        return EXIT.pass;
+    }
+    const problems = boardProblems(b);
+    const ships = shippedCopies(root);
+    if (b.refs.length) {
+        await mkdir(join(root, BOARD_DIR), { recursive: true });
+        await writeFile(join(root, BOARD_DIR, 'board.html'), boardHtml(b, basename(root)));
+    }
+    if (opts.json) {
+        io.log(JSON.stringify({ verdict: ships.length ? 'fail' : b.refs.length ? (problems.length ? 'warn' : 'pass') : 'not_observed', refs: b.refs, problems, ships }, null, 2));
+        return ships.length ? EXIT.fail : b.refs.length ? EXIT.pass : EXIT.not_observed;
+    }
+    if (!b.refs.length) {
+        u.summary('not_observed', 'no reference board yet: `funtools board search "<the feeling of the first look>"`, or `board add` your own pictures');
+        return EXIT.not_observed;
+    }
+    u.heading(`board · ${b.refs.length} reference(s)`);
+    for (const r of b.refs)
+        u.item('note', `${r.id} lends ${(r.lends ?? []).join(', ') || '?'}`, `${r.title ?? r.src} · ${r.licence}${r.note ? ` · ${r.note}` : ''}`);
+    for (const p of problems)
+        u.item('warn', p);
+    for (const s of ships)
+        u.item('fail', `${s.ref} would ship`, `copied to ${s.shipped}: a reference informs, it never ships; draw your own from what it lends`);
+    u.line(join(BOARD_DIR, 'board.html'));
+    u.summary(ships.length ? 'fail' : problems.length ? 'warn' : 'pass', ships.length ? 'remove the shipped copies' : 'draw the first look from what each reference lends, in your own style');
+    return ships.length ? EXIT.fail : EXIT.pass;
+}

package/dist/commands/boxes.js

@@ -0,0 +1,89 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { EXIT } from "./verify.js";
+import { withPage } from "./look.js";
+import { NOT_PLAY } from "./life.js";
+import { drive, evalJson, load } from "../look/look.js";
+import { boxesCheck, boxFiguresCheck, judgeBoxes, styleLockOf } from "../look/boxes.js";
+import { decodePng } from "../look/png.js";
+import { dressingCheck } from "../look/dressing.js";
+import { groundingChecks, groundTally, tallyGround } from "../walk/world.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { sceneReads } from "../verify/reads.js";
+import { ui } from "../ui.js";
+export const BOXES_RECORD = join('.funtools', 'boxes.json');
+export const BOXES_DIR = join('.funtools', 'boxes');
+export const STYLE_FILES = ['design/style-block.txt', 'design/style.md', 'assets/assets.json', 'design/plan.md', 'design/GDD.md', 'plan.md', 'GDD.md'];
+export async function readStyleLock(dir, manifest) {
+    const texts = [];
+    const meta = manifest?.metadata ?? {};
+    for (const k of ['artStyle', 'style', 'style_lock', 'styleLock']) {
+        const v = meta[k] ?? manifest?.[k];
+        if (typeof v === 'string' && v.trim())
+            texts.push([`funpixel.json ${k}`, v]);
+    }
+    if (dir)
+        for (const f of STYLE_FILES) {
+            const t = await readFile(join(dir, f), 'utf8').catch(() => null);
+            if (t)
+                texts.push([f, t.slice(0, 400_000)]);
+        }
+    return styleLockOf(texts);
+}
+export async function boxes(opts, io = console) {
+    const u = ui(io, 'boxes');
+    const r = await withPage(u, opts, async (page, t) => {
+        await load(page, t.url, hookMapOf(t.manifest));
+        const declared = (await evalJson(page, 'capture_view', { view: null, verbs: [], verb_gap_ms: 0, hold_ms: 0, freeze: false }))?.views ?? [];
+        const views = opts.views.length ? opts.views : declared.filter((v) => !NOT_PLAY.test(v.name)).map((v) => v.name).slice(0, 8);
+        if (t.dir)
+            await mkdir(join(t.dir, BOXES_DIR), { recursive: true });
+        const style = await readStyleLock(t.dir, t.manifest);
+        const out = [];
+        for (const [i, view] of (views.length ? views : ['as loaded']).entries()) {
+            const click = i === 0 ? opts.click : null;
+            const d = view === 'as loaded' ? { view: { entered: true }, ...(click ? await drive(page, { view: null, verbs: [], holdMs: 1200, freeze: false, click }) : {}) } : await drive(page, { view, verbs: [], holdMs: 1200, freeze: false, click });
+            const surf = await evalJson(page, 'surfaces', {});
+            const png = surf?.engine === 'three' ? await page.screenshot().catch(() => null) : null;
+            const frame = judgeBoxes(surf, png ? decodePng(png) : null, page.viewportSize()?.width ?? 0, style);
+            const tally = groundTally();
+            tallyGround(tally, await evalJson(page, 'grounding', {}), 0);
+            let shot = null;
+            if (png && t.dir) {
+                shot = join(BOXES_DIR, `${view.replace(/[^A-Za-z0-9_-]+/g, '_')}.png`);
+                await writeFile(join(t.dir, shot), png);
+            }
+            const figs = boxFiguresCheck(frame.figures ?? []);
+            const dressing = await evalJson(page, 'dressing', {});
+            const checks = [boxesCheck(frame, view), ...(figs ? [figs] : []), ...(tally.reads ? groundingChecks(tally) : []), dressingCheck(dressing, view, opts.viewport)];
+            out.push({ view, entered: d.view?.entered === true, frame, shot, grounding: tally.observed ? [...tally.things.values()].filter((g) => g.off) : null, dressing, checks });
+        }
+        const record = { tool: 'funtools', command: 'boxes', at: new Date().toISOString(), viewport: opts.viewport, views: out, ...(t.dir ? { fingerprint: (await fingerprint(t.dir)).fingerprint, reads: sceneReads(t.dir) } : {}) };
+        if (t.dir)
+            await writeFile(join(t.dir, BOXES_RECORD), JSON.stringify(record, null, 2) + '\n');
+        return record;
+    });
+    if (typeof r === 'number')
+        return r;
+    const observed = r.views.some((v) => v.frame.observed);
+    if (opts.json) {
+        io.log(JSON.stringify(r, null, 2));
+        return observed ? EXIT.pass : EXIT.not_observed;
+    }
+    let warned = 0;
+    for (const v of r.views) {
+        u.heading(`boxes · ${v.view}${v.entered ? '' : ' · VIEW NOT ENTERED'} · ${opts.viewport}`);
+        for (const c of v.checks) {
+            if (c.status === 'warn')
+                warned++;
+            u.item(c.status, c.text, c.hint);
+            for (const i of c.items ?? [])
+                u.line(i, 2);
+        }
+        if (v.shot)
+            u.line(`frame ${v.shot}`);
+    }
+    u.summary(observed ? (warned ? 'warn' : 'pass') : 'not_observed', observed ? `${warned ? `${warned} warning(s)` : 'the world reads as made'} — a mirror, never a gate (${BOXES_RECORD})` : 'no Three scene to read: not a pass');
+    return observed ? EXIT.pass : EXIT.not_observed;
+}

package/dist/commands/capture-all.js

@@ -0,0 +1,92 @@
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { burstLateAdvice, capture, declaredViews, isSplashView, noSplash, settleLine } from "./look.js";
+import { NOT_PLAY } from "./life.js";
+import { LATE_WAIT_MS } from "../look/moments.js";
+import { EXIT } from "./verify.js";
+import { patchBoard } from "../status/board.js";
+import { ui } from "../ui.js";
+const SIZES = ['desktop', 'phone'];
+export function stillViews(shots) {
+    return shots.filter((s) => s.life && s.life.moving + s.life.crowds + s.life.particles === 0).map((s) => s.view);
+}
+export function loggedBy(shots) {
+    const by = new Map();
+    for (const s of shots)
+        for (const e of s.errors ?? [])
+            by.set(e, [...(by.get(e) ?? []), `${s.view} · ${s.viewport}`]);
+    return by;
+}
+const dirOf = (target) => {
+    const d = resolve(target ?? '.');
+    try {
+        return /^https?:/.test(target ?? '') || !existsSync(d) || !statSync(d).isDirectory() ? null : d;
+    }
+    catch {
+        return null;
+    }
+};
+export async function captureAll(opts, io = console) {
+    const u = ui(io, 'capture');
+    const views = await declaredViews({ ...opts, viewport: 'desktop' }, io);
+    if (typeof views === 'number')
+        return views;
+    if (!views.length) {
+        u.error('the game declares no views', 'declare __FPX_VIEWS__ (skill funpixel-verify), or capture the page as loaded without --all');
+        return EXIT.not_observed;
+    }
+    const quiet = { log: () => { }, error: () => { } };
+    const shots = [];
+    for (const viewport of SIZES) {
+        for (const v of views) {
+            const lines = [];
+            const playView = viewport === 'desktop' && !v.moment && !NOT_PLAY.test(v.name);
+            const code = await capture({ ...opts, view: v.name, viewport, json: true, life: playView }, { ...quiet, log: (s) => lines.push(String(s)) });
+            let file = '', burst = null, logged = null, view = null, life, framing = null;
+            try {
+                ({ file = '', burst = null, console: logged = null, view = null, life, framing = null } = JSON.parse(lines.join('\n')));
+            }
+            catch { }
+            const settle = settleLine(view?.settle);
+            shots.push({ view: v.name, viewport, file, code, moment: v.moment, ...(burst ? { key_mark: burst.key_mark ?? null, late: burstLateAdvice(burst, opts.holdMs) } : {}), ...(logged?.unique?.length ? { errors: logged.unique } : {}), ...(settle?.[0] === 'warn' ? { unsettled: settle[1] } : {}), ...(playView ? { life: life ?? null } : {}), framing });
+        }
+    }
+    const dir = dirOf(opts.target);
+    const absent = (s) => s.code === EXIT.not_observed && isSplashView(s.view) && noSplash(dir);
+    const counted = shots.filter((s) => !absent(s));
+    const worst = counted.some((s) => s.code === EXIT.error) ? EXIT.error : counted.some((s) => s.code !== EXIT.pass) ? EXIT.not_observed : EXIT.pass;
+    if (dir && shots.some((s) => s.code === EXIT.pass)) {
+        const logged = [...loggedBy(shots)];
+        patchBoard(dir, { errors: { capture: { value: logged.length, by: 'capture --all', detail: logged.map(([line, where]) => `${line} (${where[0]}${where.length > 1 ? ` +${where.length - 1}` : ''})`) } } });
+    }
+    if (opts.json) {
+        io.log(JSON.stringify({ ok: worst === EXIT.pass, shots, ...(counted.length < shots.length ? { not_counted: shots.filter(absent).map((s) => `${s.view} · ${s.viewport}: the game has no splash`) } : {}) }, null, 2));
+        return worst;
+    }
+    u.heading(`capture --all · ${views.length} view(s) × desktop, phone`);
+    for (const s of shots) {
+        u.item(s.code === EXIT.pass ? 'pass' : s.code === EXIT.error ? 'fail' : 'not_observed', `${s.view} · ${s.viewport}${s.moment ? ' (moment, burst)' : ''}`, s.file || (s.code === EXIT.error ? 'error' : 'not entered'));
+        if (s.unsettled)
+            u.item('warn', `${s.view} · ${s.viewport}: ${s.unsettled}`);
+        if (s.late)
+            u.item('warn', `${s.view} · ${s.viewport}: ${s.late}`);
+        else if (s.moment && s.code === EXIT.pass && s.key_mark === null)
+            u.item('note', `${s.view} · ${s.viewport}: no __FPX_MOMENT__ mark landed in the burst or ${LATE_WAIT_MS / 1000} s after it, so its middle frame stands for the payoff — look at it`);
+    }
+    for (const s of stillViews(shots))
+        u.item('warn', `nothing moves but the player in ${s}: the world reads as a still`, 'something alive in every play view: a creature, crowd, flags, drifting dust, weather, a light that breathes (funpixel-world-and-story, references/atmosphere.md); `funtools life --view` measures it');
+    const free = shots.filter((s) => s.code === EXIT.pass && s.framing?.clock !== 'stepped');
+    const held = shots.find((s) => s.framing?.clock === 'stepped')?.framing;
+    const passed = shots.filter((s) => s.code === EXIT.pass).length;
+    if (free.length)
+        u.item('warn', `free-running: ${free.length === passed ? 'every shot' : free.map((s) => `${s.view} · ${s.viewport}`).join(', ')} — ${free[0].framing?.why ?? 'no framing record'}`, 'two takes of these differ by themselves: never read them as a before and after');
+    else if (held)
+        u.item('pass', `every shot repeatable: held clock, seed ${held.seed}, fixed ${held.frame_ms} ms frames (a second capture --all draws the same frames, to within the GPU's rounding)`);
+    for (const [line, where] of loggedBy(shots))
+        u.item('warn', `logged while entering ${where.join(', ')}: "${line}"`, 'a view that misses its beat can say so here; look at its frames before the panel does');
+    for (const v of [...new Set(shots.filter(absent).map((s) => s.view))])
+        u.item('note', `${v}: not counted — the game has no splash (funpixel.json "splash": "none")`);
+    const bad = counted.filter((s) => s.code !== EXIT.pass).length;
+    u.summary(worst === EXIT.pass ? 'pass' : worst === EXIT.error ? 'fail' : 'not_observed', bad ? `${counted.length - bad} of ${counted.length} shot; the rest were not entered` : `${counted.length} shot — read them before the panel does`);
+    return worst;
+}

package/dist/commands/cast.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { decodePng } from "../look/png.js";
+import { addMember, CAST_KINDS, masterUnchanged, readCast } from "../cast/library.js";
+import { identityFacts } from "../cast/measure.js";
+import { ui } from "../ui.js";
+export const CAST_SUBCOMMANDS = ['add', 'list', 'check'];
+const MARK = { pass: 'pass', minor: 'warn', drift: 'fail', not_observed: 'note' };
+export async function cast(o, io = console) {
+    const u = ui(io, `cast ${o.sub}`);
+    const game = resolve(o.dir ?? '.');
+    try {
+        if (o.sub === 'add') {
+            const [id] = o.args;
+            if (!id)
+                throw new Error('name the cast id — funtools cast add ren --master <png> --pins "…"');
+            if (!o.master)
+                throw new Error('--master is the accepted picture of this design (a PNG)');
+            const m = addMember(game, id, { master: resolve(o.master), turnaround: o.turnaround ? resolve(o.turnaround) : undefined, pins: o.pins ?? '', name: o.name, kind: o.kind, features: o.features?.split(';'), mayChange: o.mayChange, moves: o.moves, by: o.by });
+            if (o.json) {
+                io.log(JSON.stringify({ ok: true, member: m }, null, 2));
+                return 0;
+            }
+            u.summary('pass', `${m.card.name} accepted — ${m.master}${m.turnaround ? ` + ${m.turnaround}` : ''}, palette ${m.palette.slice(0, 5).join(' ')}; every later picture named ${id} or ${id}_… is drawn with it attached first, then held to it`);
+            return 0;
+        }
+        const all = readCast(game);
+        if (o.sub === 'list') {
+            if (o.json) {
+                io.log(JSON.stringify({ ok: true, cast: [...all.values()].map((m) => ({ ...m.card, master: m.master, turnaround: m.turnaround ?? null, palette: m.palette, changed: !masterUnchanged(game, m) })) }, null, 2));
+                return 0;
+            }
+            u.heading(`cast · ${all.size} member(s)`);
+            for (const m of all.values())
+                u.item(masterUnchanged(game, m) ? 'pass' : 'warn', `${m.card.id} — ${m.card.name} (${m.card.kind})`, `${m.card.pins.slice(0, 120)}${masterUnchanged(game, m) ? '' : ' · master.png changed since it was accepted: accept it again (cast add) or restore it'}`);
+            u.summary(all.size ? 'pass' : 'note', all.size ? `${all.size} accepted` : `no cast yet — accept a master at the first look: funtools cast add <id> --master <png> --pins "…" (kinds: ${CAST_KINDS.join(', ')})`);
+            return 0;
+        }
+        if (o.sub === 'check') {
+            const [id, ...files] = o.args;
+            const m = id ? all.get(id) : undefined;
+            if (!m)
+                throw new Error(`${id ?? '(none)'} is not in design/cast/ — funtools cast list names them`);
+            if (!files.length)
+                throw new Error(`name the pictures to hold to ${id}'s master — funtools cast check ${id} public/assets/sprites/${id}_walk.png`);
+            if (o.mode !== undefined && o.mode !== 'same' && o.mode !== 'pose')
+                throw new Error('--mode is same (a redraw of the master view) or pose (another pose)');
+            const master = decodePng(readFileSync(join(game, m.master)));
+            const rows = files.map((f) => {
+                const p = resolve(f);
+                if (!existsSync(p))
+                    return { file: f, facts: { verdict: 'not_observed', iou: null, palette: null, lost: [], aspect: null, mode: 'pose', why: [`${f} is not on disk`] } };
+                const mode = o.mode ?? 'pose';
+                try {
+                    return { file: f, facts: identityFacts(master, decodePng(readFileSync(p)), mode) };
+                }
+                catch {
+                    return { file: f, facts: { verdict: 'not_observed', iou: null, palette: null, lost: [], aspect: null, mode, why: [`${f} is not a PNG this reader decodes`] } };
+                }
+            });
+            const drift = rows.filter((r) => r.facts.verdict === 'drift').length;
+            const seen = rows.filter((r) => r.facts.verdict !== 'not_observed').length;
+            if (o.json)
+                io.log(JSON.stringify({ ok: true, cast: id, results: rows }, null, 2));
+            else {
+                u.heading(`cast check · ${m.card.name} · ${rows.length} picture(s)`);
+                for (const r of rows)
+                    u.item(MARK[r.facts.verdict], `${r.file} — ${r.facts.verdict}`, r.facts.iou === null ? r.facts.why.join('; ') : `silhouette ${Math.round(r.facts.iou * 100)}% · colour ${r.facts.palette}% on the master's${r.facts.why.length ? ` · ${r.facts.why.join('; ')}` : ''}`);
+                u.item('note', `numbers only: the features (${m.card.features.slice(0, 3).join(', ') || 'from the card'}) are the identity seat's — funtools judge identity --concept ${m.master} ${files.join(' ')}`);
+                u.summary(drift ? 'fail' : seen ? 'pass' : 'note', drift ? `${drift} of ${rows.length} drifted from ${id}'s master` : seen ? `${seen} on model` : 'not observed');
+            }
+            return drift ? 1 : seen ? 0 : 2;
+        }
+        u.error(`unknown: cast ${o.sub}`, `use one of ${CAST_SUBCOMMANDS.join(', ')}`);
+        return 3;
+    }
+    catch (e) {
+        const m = e instanceof Error ? e.message : String(e), dash = m.indexOf(' — ');
+        if (o.json)
+            io.log(JSON.stringify({ ok: false, error: m }, null, 2));
+        u.error(dash < 0 ? m : m.slice(0, dash), dash < 0 ? 'fix it and run again' : m.slice(dash + 3));
+        return 3;
+    }
+}

package/dist/commands/character.js

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto';
+import { followJob, submit } from "../api/jobs.js";
+import { ui } from "../ui.js";
+import { fail, gen, GEN_EXIT, needKey } from "./gen.js";
+export const CHARACTER_SUBCOMMANDS = ['list', 'get', 'restyle'];
+export async function character(opts, io = console) {
+    const [sub, ...rest] = opts.positionals;
+    const r = { u: ui(io, 'character'), json: opts.json, io };
+    switch (sub) {
+        case 'list': return list(r, opts.flags);
+        case 'get': {
+            if (!rest[0])
+                return fail(r, new Error('get needs a character id — funtools character list shows them'));
+            return gen({ ...opts, positionals: ['character', rest[0]], name: rest[0] }, io);
+        }
+        case 'restyle': {
+            const [id, ...words] = rest;
+            if (!id || !words.length)
+                return fail(r, new Error('restyle needs an id and the new look — funtools character restyle fox-2d "an arctic fox in blue"'));
+            return gen({ ...opts, positionals: ['restyle-character', ...words], flags: { ...opts.flags, '--id': id }, name: id }, io);
+        }
+        default:
+            return fail(r, new Error(`${sub ? `unknown: character ${sub}` : 'no subcommand'} — use character list, get <id> or restyle <id> "look"`));
+    }
+}
+async function list(r, flags) {
+    const api = needKey(r);
+    if (!api)
+        return GEN_EXIT.error;
+    const input = {};
+    for (const [flag, field] of [['--medium', 'medium'], ['--body', 'body']]) {
+        if (typeof flags[flag] === 'string')
+            input[field] = flags[flag];
+    }
+    let rows;
+    try {
+        const { job } = await submit(api, 'list_characters', input, { idempotencyKey: randomUUID(), confirm: false });
+        const done = await followJob(api, job.job_id);
+        if (done.status !== 'succeeded')
+            throw new Error(`the shelf did not answer: ${done.error?.message ?? done.status}`);
+        rows = (done.result?.characters ?? []);
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    if (r.json) {
+        r.io.log(JSON.stringify({ ok: true, characters: rows }, null, 2));
+        return GEN_EXIT.done;
+    }
+    r.u.heading('the character library — animated already; get is free, restyle keeps every motion');
+    for (const c of rows) {
+        const clips = c.clips.map((x) => (typeof x === 'string' ? x : x.name)).join(' ');
+        r.u.item(c.stocked ? 'pass' : 'skip', `${c.id}  ${c.medium} ${c.body}`, c.stocked ? c.summary : `${c.summary} (not stocked on this server)`);
+        r.u.line(clips, 2);
+    }
+    r.u.summary('pass', `${rows.filter((c) => c.stocked).length} of ${rows.length} ready — funtools character get <id>`);
+    return GEN_EXIT.done;
+}