@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/assets/steps.js

@@ -0,0 +1,294 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { sendJson } from "../api/http.js";
+import { followJob, submit } from "../api/jobs.js";
+import { recordAssets } from "../gen/record.js";
+import { decodePng } from "../look/png.js";
+import { fixPrompt, identityFacts } from "../cast/measure.js";
+import { fileAssetId } from "./gen.js";
+import { KEEP_DIR, shaOf, shaOfBytes, writeLock } from "./lock.js";
+import { familyOf, isPicture, targetOf } from "./manifest.js";
+import { parts as cutParts, PARTS_DEFAULTS } from "../commands/parts.js";
+import { bakeoff } from "./bakeoff.js";
+const posix = (p) => p.split('\\').join('/');
+const key = (p, step) => `fpx-asset:${p.item.name}:${p.hash}:${step}`.slice(0, 255);
+async function put(path, bytes) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, bytes);
+}
+async function bytesOf(job, ext) {
+    const o = job.outputs.find((x) => ext.test(x.name)) ?? job.outputs[0];
+    if (!o?.url)
+        return null;
+    const res = await fetch(o.url);
+    if (!res.ok)
+        throw new Error(`downloading ${o.name} answered ${res.status} — run assets gen again; the jobs are kept and nothing is paid twice`);
+    return { bytes: Buffer.from(await res.arrayBuffer()), asset_id: o.asset_id, name: o.name };
+}
+async function oneJob(api, game, lock, p, tool, input, step) {
+    const { job, replay } = await submit(api, tool, input, { idempotencyKey: key(p, step), confirm: true });
+    const e = lock.items[p.item.name] ?? blank(p);
+    e.pending = { input_hash: p.hash, job_ids: [...new Set([...(e.pending?.input_hash === p.hash ? e.pending.job_ids : []), job.job_id])], at: new Date().toISOString() };
+    lock.items[p.item.name] = e;
+    await writeLock(game, lock);
+    const done = job.status === 'succeeded' || job.status === 'failed' || job.status === 'cancelled' ? job : await followJob(api, job.job_id);
+    return { job: done, replayed: replay };
+}
+const blank = (p) => ({ kind: p.item.kind, family: familyOf(p.item), input_hash: '', version: 0, credits: 0, verdict: 'failed', at: new Date().toISOString(), history: [] });
+async function land(game, p, lock, job, file, bytes, asset_id, credits, extra = {}) {
+    const name = p.item.name;
+    const prev = lock.items[name];
+    const e = prev ?? blank(p);
+    delete e.pending;
+    if (prev?.verdict === 'accept' && prev.file && existsSync(join(game, prev.file)) && prev.input_hash !== p.hash) {
+        const old = posix(join(KEEP_DIR, 'history', `${name}.v${prev.version}${extname(prev.file)}`));
+        await mkdir(dirname(join(game, old)), { recursive: true });
+        await copyFile(join(game, prev.file), join(game, old)).catch(() => { });
+        e.history.push({ version: prev.version, input_hash: prev.input_hash, job_id: prev.job_id, asset_id: prev.asset_id, file: old, sha256: prev.sha256, credits: prev.credits, at: prev.at });
+        e.credits = 0;
+    }
+    await put(join(game, file), bytes);
+    const raw = posix(join(KEEP_DIR, 'raw', `${name}${extname(file)}`));
+    await put(join(game, raw), bytes);
+    await recordAssets(game, job.job_id, job.tool, [{ path: join(game, file), asset_id, bytes }]).catch(() => { });
+    Object.assign(e, {
+        kind: p.item.kind, family: familyOf(p.item), input_hash: p.hash, tool: job.tool, prompt: typeof p.req.prompt === 'string' ? p.req.prompt : undefined,
+        version: (prev?.input_hash === p.hash ? prev.version : (prev?.version ?? 0) + 1) || 1, job_id: job.job_id, asset_id, file, sha256: shaOf(join(game, file)) ?? undefined,
+        raw, raw_sha256: shaOfBytes(bytes), verdict: 'accept', error: undefined, at: new Date().toISOString(), processed: undefined,
+        references: p.source ? [{ path: p.source.path, sha256: p.source.sha256 }] : undefined, ...extra,
+    });
+    e.credits += credits;
+    lock.items[name] = e;
+    return e;
+}
+async function failed(game, p, lock, job, credits, message) {
+    const e = lock.items[p.item.name] ?? blank(p);
+    delete e.pending;
+    Object.assign(e, { input_hash: p.hash, verdict: job?.error?.code === 'asset_rejected' ? 'reject' : 'failed', error: message, at: new Date().toISOString() });
+    e.credits += credits;
+    lock.items[p.item.name] = e;
+    await writeLock(game, lock);
+    return { name: p.item.name, outcome: 'failed', message, credits, draws: job ? 1 : 0, replayed: 0 };
+}
+async function runPose(api, game, p, lock, o) {
+    const from = p.item.from ? lock.items[p.item.from] : undefined;
+    const asset_id = from?.verdict === 'accept' && from.asset_id ? from.asset_id : p.source ? await fileAssetId(api, game, p.source.path, `${p.item.name}: its master ${p.source.path}`) : undefined;
+    if (!asset_id)
+        return { name: p.item.name, outcome: 'refused', message: 'a pose needs its cast master (design/cast/<id>/master.png) or a made `from` picture', credits: 0, draws: 0, replayed: 0 };
+    const { job, replayed } = await oneJob(api, game, lock, p, 'edit_image', { asset_id, prompt: p.req.prompt, mode: 'pose', ...(p.req.size ? { size: p.req.size } : {}), ...(p.req.quality ? { quality: p.req.quality } : {}), ...(o.gameId ? { game_id: o.gameId } : {}) }, 'pose');
+    if (job.status !== 'succeeded')
+        return failed(game, p, lock, job, job.charged_credits, job.error?.message ?? job.status);
+    const out = await bytesOf(job, /\.(png|webp|jpe?g)$/i);
+    if (!out)
+        return failed(game, p, lock, job, job.charged_credits, 'the job saved no picture');
+    const file = targetOf(p.item);
+    await land(game, p, lock, job, file, out.bytes, out.asset_id, job.charged_credits);
+    await writeLock(game, lock);
+    return { name: p.item.name, outcome: 'made', credits: job.charged_credits, file, draws: 1, replayed: replayed ? 1 : 0 };
+}
+async function runRig(api, game, p, lock) {
+    const from = p.item.from ? lock.items[p.item.from] : undefined;
+    if (from?.verdict !== 'accept' || !from.asset_id)
+        return { name: p.item.name, outcome: 'refused', message: `waits for ${p.item.from}, which was not made`, credits: 0, draws: 0, replayed: 0 };
+    const chain = [
+        { tool: 'rig_model', input: (a) => ({ asset_id: a, ...(p.item.clips ? { clips: p.item.clips } : {}) }) },
+        ...(p.item.motions ? [{ tool: 'author_motion', input: (a) => ({ asset_id: a, motions: p.item.motions }) }] : []),
+        ...(p.item.retarget ? [{ tool: 'retarget_clips', input: (a) => ({ asset_id: a, donor_character: p.item.retarget.character, ...(p.item.retarget.clips ? { clips: p.item.retarget.clips } : {}) }) }] : []),
+    ];
+    let asset = from.asset_id;
+    let last = null;
+    let credits = 0, replayed = 0;
+    const steps = [];
+    for (const s of chain) {
+        const r = await oneJob(api, game, lock, p, s.tool, s.input(asset), s.tool);
+        credits += r.job.charged_credits;
+        if (r.replayed)
+            replayed++;
+        if (r.job.status !== 'succeeded')
+            return failed(game, p, lock, r.job, credits, `${s.tool}: ${r.job.error?.message ?? r.job.status}`);
+        const out = await bytesOf(r.job, /\.glb$/i);
+        if (!out)
+            return failed(game, p, lock, r.job, credits, `${s.tool} saved no model`);
+        steps.push({ tool: s.tool, job_id: r.job.job_id, asset_id: out.asset_id, credits: r.job.charged_credits });
+        asset = out.asset_id;
+        last = { job: r.job, out };
+    }
+    const file = targetOf(p.item);
+    await land(game, p, lock, last.job, file, last.out.bytes, last.out.asset_id, credits, { steps });
+    await writeLock(game, lock);
+    return { name: p.item.name, outcome: 'made', credits, file, draws: chain.length, replayed };
+}
+async function runParts(game, p, lock) {
+    const sheet = join(game, p.item.sheet);
+    if (!existsSync(sheet))
+        return { name: p.item.name, outcome: 'refused', message: `${p.item.sheet} is not on disk`, credits: 0, draws: 0, replayed: 0 };
+    const out = targetOf(p.item);
+    const silent = { log: () => { }, error: () => { } };
+    const grid = p.item.grid ? /^(\d+)x(\d+)$/.exec(p.item.grid) : null;
+    const code = await cutParts({ sheet, out: join(game, out), names: p.item.names ?? [], key: { kind: 'auto' }, pivot: 'bottom', pad: PARTS_DEFAULTS.pad, merge: PARTS_DEFAULTS.merge, webp: false, json: true, clean: true, ...(grid ? { grid: { cols: Number(grid[1]), rows: Number(grid[2]) } } : {}) }, silent);
+    if (code !== 0)
+        return { name: p.item.name, outcome: 'failed', message: `parts could not cut ${p.item.sheet} (funtools parts ${p.item.sheet} says why)`, credits: 0, draws: 0, replayed: 0 };
+    const e = lock.items[p.item.name] ?? blank(p);
+    Object.assign(e, { kind: 'parts', family: familyOf(p.item), input_hash: p.hash, tool: 'parts (local)', version: (e.version ?? 0) + 1, file: out, sha256: shaOf(join(game, out)) ?? undefined, verdict: 'accept', at: new Date().toISOString(), references: p.source ? [{ path: p.source.path, sha256: p.source.sha256 }] : undefined });
+    delete e.pending;
+    lock.items[p.item.name] = e;
+    await writeLock(game, lock);
+    return { name: p.item.name, outcome: 'made', credits: 0, file: out, draws: 0, replayed: 0 };
+}
+export function runSingle(api, game, p, lock, o = {}) {
+    if (p.item.kind === 'pose')
+        return runPose(api, game, p, lock, o);
+    if (p.item.kind === 'rig')
+        return runRig(api, game, p, lock);
+    return runParts(game, p, lock);
+}
+export async function runOptimize(api, game, p, lock) {
+    const e = lock.items[p.item.name];
+    const op = p.item.optimize;
+    if (!op || e?.verdict !== 'accept' || !e.asset_id || !e.file)
+        return { credits: 0 };
+    if (e.steps?.some((s) => s.tool === 'optimize_model'))
+        return { credits: 0 };
+    const { job } = await oneJob(api, game, lock, p, 'optimize_model', { asset_id: e.asset_id, device: op.device, ...(op.budget ? { budget: op.budget } : {}) }, `optimize-${op.device}`);
+    delete lock.items[p.item.name].pending;
+    if (job.status !== 'succeeded')
+        return { credits: job.charged_credits, note: `${p.item.name}: optimize_model ${job.error?.message ?? job.status} — the unoptimized model is kept` };
+    const out = await bytesOf(job, /\.glb$/i);
+    if (!out)
+        return { credits: job.charged_credits, note: `${p.item.name}: optimize_model saved no model` };
+    await put(join(game, e.file), out.bytes);
+    await recordAssets(game, job.job_id, job.tool, [{ path: join(game, e.file), asset_id: out.asset_id, bytes: out.bytes }]).catch(() => { });
+    e.steps = [...(e.steps ?? []), { tool: 'optimize_model', job_id: job.job_id, asset_id: out.asset_id, credits: job.charged_credits }];
+    e.asset_id = out.asset_id;
+    e.sha256 = shaOf(join(game, e.file)) ?? undefined;
+    e.credits += job.charged_credits;
+    await writeLock(game, lock);
+    return { credits: job.charged_credits };
+}
+export const MODEL_COLOUR_FIX = 72;
+export async function refineModel(api, game, p, lock, render, o = {}) {
+    const e = lock.items[p.item.name];
+    const top = e?.bakeoff?.[0];
+    if (!p.cast || !render || !e?.asset_id || !e.file || e.refine || top?.palette == null || top.palette >= MODEL_COLOUR_FIX)
+        return { credits: 0 };
+    const master = readRgba(join(game, p.cast.master));
+    if (!master)
+        return { credits: 0 };
+    const prompt = `Repaint it in the design's own colours (${p.cast.palette.slice(0, 5).join(', ')}): ${p.cast.card.pins}`;
+    const { job } = await oneJob(api, game, lock, p, 'retexture_model', { asset_id: e.asset_id, prompt, palette: p.cast.palette.slice(0, 8), ...(o.gameId ? { game_id: o.gameId } : {}) }, 'refine-retexture');
+    delete lock.items[p.item.name].pending;
+    const out = job.status === 'succeeded' ? await bytesOf(job, /\.glb$/i) : null;
+    let after = null, kept = false;
+    if (out) {
+        const file = posix(join(KEEP_DIR, 'draws', p.item.name, 'retexture.glb'));
+        await put(join(game, file), out.bytes);
+        const [scored] = await bakeoff(master, [{ draw: 0, file: join(game, file) }], render, join(game, KEEP_DIR, 'bakeoff', p.item.name, 'retexture'));
+        after = scored?.score ?? null;
+        if (after !== null && top.score !== null && after > top.score) {
+            kept = true;
+            await put(join(game, e.file), out.bytes);
+            await recordAssets(game, job.job_id, job.tool, [{ path: join(game, e.file), asset_id: out.asset_id, bytes: out.bytes }]).catch(() => { });
+            e.asset_id = out.asset_id;
+            e.sha256 = shaOf(join(game, e.file)) ?? undefined;
+        }
+    }
+    e.refine = { tool: 'retexture_model', job_id: job.job_id, prompt, before: top.score, after, kept, credits: job.charged_credits };
+    e.credits += job.charged_credits;
+    await writeLock(game, lock);
+    return { credits: job.charged_credits, line: `${p.item.name}: colour ${top.palette}% of the master's → one retexture, score ${top.score} → ${after ?? 'not observed'}${kept ? ', kept' : ', the bake-off\'s pick kept'}` };
+}
+const MAX_ROUNDS = 2;
+const rank = (f) => (f.verdict === 'pass' ? 3 : f.verdict === 'minor' ? 2 : f.verdict === 'not_observed' ? 0 : 1) * 1000 + (f.palette ?? 0) + (f.iou ?? 0) * 100;
+export function modeOf(p) {
+    if (p.item.identity === 'same' || p.item.identity === 'pose')
+        return p.item.identity;
+    return p.cast && p.item.name.toLowerCase() === p.cast.card.id ? 'same' : 'pose';
+}
+const readRgba = (path) => { try {
+    return decodePng(readFileSync(path));
+}
+catch {
+    return null;
+} };
+export async function identityPass(api, game, p, lock, o) {
+    const e = lock.items[p.item.name];
+    const m = p.cast;
+    if (!m || p.item.identity === 'off' || !isPicture(p.item.kind) || p.item.kind === 'sheet' || e?.verdict !== 'accept' || !e.file)
+        return null;
+    if (e.identity && e.identity.cast === m.card.id && e.sha256 && e.identity.rounds.length && e.input_hash === p.hash)
+        return null;
+    const master = readRgba(join(game, m.master));
+    const mode = modeOf(p);
+    const first = master && readRgba(join(game, e.file));
+    if (!master || !first) {
+        e.identity = { cast: m.card.id, verdict: 'not_observed', iou: null, palette: null, lost: [], why: [!master ? `${m.master} is not a PNG this reader decodes` : `${e.file} is not a PNG this reader decodes`], rounds: [] };
+        await writeLock(game, lock);
+        return { name: p.item.name, cast: m.card.id, verdict: 'not_observed', rounds: 0, credits: 0, why: e.identity.why };
+    }
+    const facts = identityFacts(master, first, mode);
+    const rounds = [{ round: 'made', job_id: e.job_id, verdict: facts.verdict, iou: facts.iou, palette: facts.palette, credits: 0, file: e.file }];
+    let best = { facts, bytes: readFileSync(join(game, e.file)), asset_id: e.asset_id, file: e.file };
+    let credits = 0;
+    const keepDir = posix(join(KEEP_DIR, 'identity', p.item.name));
+    const tryTake = async (round, job, prompt) => {
+        if (!job)
+            return false;
+        credits += job.charged_credits;
+        if (job.status !== 'succeeded') {
+            rounds.push({ round, job_id: job.job_id, verdict: `failed: ${job.error?.message ?? job.status}`, iou: null, palette: null, credits: job.charged_credits, ...(prompt ? { prompt } : {}) });
+            return false;
+        }
+        const out = await bytesOf(job, /\.(png|webp|jpe?g)$/i);
+        const img = out && (() => { try {
+            return decodePng(out.bytes);
+        }
+        catch {
+            return null;
+        } })();
+        if (!out || !img) {
+            rounds.push({ round, job_id: job.job_id, verdict: 'not observed (not a PNG)', iou: null, palette: null, credits: job.charged_credits });
+            return false;
+        }
+        const file = posix(join(keepDir, `${round}.png`));
+        await put(join(game, file), out.bytes);
+        const f = identityFacts(master, img, mode);
+        rounds.push({ round, job_id: job.job_id, verdict: f.verdict, iou: f.iou, palette: f.palette, credits: job.charged_credits, file, ...(prompt ? { prompt } : {}) });
+        if (rank(f) > rank(best.facts))
+            best = { facts: f, bytes: out.bytes, asset_id: out.asset_id, job, file };
+        return f.verdict === 'pass' || f.verdict === 'minor';
+    };
+    if (facts.verdict === 'drift' && o.allowFix === false)
+        rounds.push({ round: 'edit', verdict: 'skipped: the fix would pass the cap', iou: null, palette: null, credits: 0 });
+    else if (facts.verdict === 'drift') {
+        const prompt = fixPrompt(facts, m.card.pins, m.palette);
+        const edit = e.asset_id ? (await oneJob(api, game, lock, p, 'edit_image', { asset_id: e.asset_id, prompt, mode: 'edit', ...(o.gameId ? { game_id: o.gameId } : {}) }, 'identity-edit')).job : null;
+        const ok = await tryTake('edit', edit, prompt);
+        if (!ok && rounds.length <= MAX_ROUNDS)
+            await tryTake('redraw', await o.redraw(p));
+    }
+    const fin = best.facts;
+    const verdict = fin.verdict === 'drift' ? 'off_model' : fin.verdict;
+    if (best.file !== e.file) {
+        await put(join(game, e.file), best.bytes);
+        if (best.asset_id && best.job)
+            await recordAssets(game, best.job.job_id, best.job.tool, [{ path: join(game, e.file), asset_id: best.asset_id, bytes: best.bytes }]).catch(() => { });
+        e.asset_id = best.asset_id ?? e.asset_id;
+        e.job_id = best.job?.job_id ?? e.job_id;
+        e.sha256 = shaOf(join(game, e.file)) ?? undefined;
+        e.raw_sha256 = createHash('sha256').update(best.bytes).digest('hex');
+        await put(join(game, e.raw ?? posix(join(KEEP_DIR, 'raw', `${p.item.name}.png`))), best.bytes);
+    }
+    delete e.pending;
+    e.credits += credits;
+    e.identity = { cast: m.card.id, verdict, iou: fin.iou, palette: fin.palette, lost: fin.lost, why: fin.why, rounds };
+    await writeLock(game, lock);
+    return { name: p.item.name, cast: m.card.id, verdict, rounds: rounds.length - 1, credits, why: fin.why };
+}
+export async function redrawInBatch(api, game, p, body) {
+    const name = `${p.item.name}.r1`;
+    const { json } = await sendJson(api, 'POST', '/v1/tools/generate_batch', { body: { ...body, items: [{ ...body.item, name }] } });
+    const id = json.items.find((i) => i.name === name)?.job_id;
+    return id ? followJob(api, id) : null;
+}

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+import { startUpdateCheck } from "./update.js";
+const argv = process.argv.slice(2);
+const notice = startUpdateCheck(argv);
+process.exitCode = await main(argv);
+if (notice)
+    console.error(notice);

package/dist/board/board.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+export const BOARD_DIR = join('design', 'board');
+export const BOARD_FILE = join(BOARD_DIR, 'board.json');
+export const LENDS = ['palette', 'shape', 'light', 'composition', 'material', 'motion', 'mood', 'type'];
+export const OPENVERSE = 'https://api.openverse.org/v1/images/';
+export function searchUrl(words, opts = {}) {
+    const q = new URLSearchParams({ q: words, page_size: String(Math.min(20, Math.max(1, opts.limit ?? 12))), mature: 'false' });
+    if (opts.commercial !== false)
+        q.set('license_type', 'commercial');
+    return `${OPENVERSE}?${q}`;
+}
+export const relatedUrl = (id) => `${OPENVERSE}${encodeURIComponent(id)}/related/`;
+const licenceOf = (r) => {
+    const l = String(r.license ?? '').toLowerCase(), v = String(r.license_version ?? '');
+    return l === 'cc0' || l === 'pdm' ? l.toUpperCase() : `CC ${l.toUpperCase()}${v ? ` ${v}` : ''}`;
+};
+export function hitsFrom(body) {
+    const results = body?.results;
+    if (!Array.isArray(results))
+        return [];
+    return results.map((x) => x).filter((r) => typeof r.id === 'string' && typeof r.url === 'string').map((r) => ({
+        id: String(r.id), title: String(r.title ?? ''), by: String(r.creator ?? ''), licence: licenceOf(r),
+        url: String(r.url), thumb: String(r.thumbnail ?? r.url), page: String(r.foreign_landing_url ?? r.url),
+    }));
+}
+export async function search(fetcher, url) {
+    const r = await fetcher(url);
+    if (!r.ok)
+        throw new Error(`the open collection answered ${r.status}`);
+    return hitsFrom(await r.json());
+}
+export function readBoard(root) {
+    const p = join(root, BOARD_FILE);
+    if (!existsSync(p))
+        return { version: 1, refs: [] };
+    const b = JSON.parse(readFileSync(p, 'utf8'));
+    return { version: 1, refs: Array.isArray(b.refs) ? b.refs : [] };
+}
+export function boardProblems(b) {
+    const out = [];
+    for (const r of b.refs) {
+        if (!r.lends?.length)
+            out.push(`${r.id}: lends nothing named (say one of ${LENDS.join(', ')})`);
+        if ((r.lends?.length ?? 0) > 2)
+            out.push(`${r.id}: lends ${r.lends.length} things; a reference that lends everything gets copied, keep one or two`);
+        if (!r.licence)
+            out.push(`${r.id}: no licence recorded`);
+    }
+    if (b.refs.length > 12)
+        out.push(`${b.refs.length} references: past about a dozen a board stops steering; keep the ones that lend something the others do not`);
+    const lent = new Set(b.refs.flatMap((r) => r.lends ?? []));
+    if (b.refs.length >= 3 && lent.size === 1)
+        out.push(`every reference lends ${[...lent][0]}: a board of one idea; add light, shape or composition`);
+    return out;
+}
+const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
+export const SHIPPED = ['public', 'assets', join('src', 'assets')];
+function files(dir, out = [], depth = 0) {
+    if (!existsSync(dir) || depth > 5)
+        return out;
+    for (const f of readdirSync(dir)) {
+        if (f.startsWith('.') || f === 'node_modules')
+            continue;
+        const p = join(dir, f);
+        if (statSync(p).isDirectory())
+            files(p, out, depth + 1);
+        else if (/\.(png|jpe?g|webp|gif|avif)$/i.test(f))
+            out.push(p);
+    }
+    return out;
+}
+export function shippedCopies(root) {
+    const kept = files(join(root, BOARD_DIR));
+    if (!kept.length)
+        return [];
+    const hashes = new Map(kept.map((p) => [sha(p), relative(root, p)]));
+    const out = [];
+    for (const d of SHIPPED)
+        for (const p of files(join(root, d))) {
+            const h = hashes.get(sha(p));
+            if (h)
+                out.push({ ref: h, shipped: relative(root, p) });
+        }
+    return out;
+}
+const esc = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+export function boardHtml(b, title) {
+    const cards = b.refs.map((r) => `<figure><img src="${esc(r.source === 'file' ? `../../${r.src}` : r.src)}" alt="${esc(r.title ?? r.id)}" loading="lazy"><figcaption><b>${esc((r.lends ?? []).join(' · ') || '?')}</b>${r.note ? ` — ${esc(r.note)}` : ''}<br><small>${esc(r.title ?? '')}${r.by ? ` by ${esc(r.by)}` : ''} · ${esc(r.licence)}${r.page ? ` · <a href="${esc(r.page)}">source</a>` : ''}</small></figcaption></figure>`).join('\n');
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)} · reference board</title><style>
+:root{color-scheme:light dark;--bg:#f6f4ef;--ink:#1d1c1a;--card:#fff}@media (prefers-color-scheme:dark){:root{--bg:#141413;--ink:#ecebe7;--card:#1f1e1c}}
+body{margin:0;padding:16px;background:var(--bg);color:var(--ink);font:15px/1.4 system-ui,sans-serif}h1{font-size:20px}
+main{display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:12px}figure{margin:0;background:var(--card);border-radius:10px;overflow:hidden}
+img{width:100%;aspect-ratio:4/3;object-fit:cover;display:block}figcaption{padding:8px 10px}small{opacity:.7}a{color:inherit}
+</style></head><body><h1>${esc(title)}: what each reference lends</h1><p>References inform the first look; none of them ships in the game.</p><main>
+${cards}
+</main></body></html>\n`;
+}

package/dist/cast/library.js

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { decodePng } from "../look/png.js";
+import { colours } from "./measure.js";
+export const CAST_DIR = join('design', 'cast');
+export const CAST_KINDS = ['character', 'creature', 'structure', 'vehicle', 'prop'];
+const ID = /^[a-z][a-z0-9]{0,23}$/;
+const rel = (...p) => p.join('/');
+export const masterPath = (id) => rel('design', 'cast', id, 'master.png');
+export const turnaroundPath = (id) => rel('design', 'cast', id, 'turnaround.png');
+const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
+export function readCast(game) {
+    const out = new Map();
+    const root = join(game, CAST_DIR);
+    if (!existsSync(root))
+        return out;
+    for (const id of readdirSync(root).sort()) {
+        const dir = join(root, id);
+        const cardFile = join(dir, 'card.json');
+        if (!ID.test(id) || !existsSync(cardFile) || !existsSync(join(dir, 'master.png')))
+            continue;
+        let card;
+        try {
+            card = JSON.parse(readFileSync(cardFile, 'utf8'));
+        }
+        catch {
+            throw new Error(`${rel(CAST_DIR, id, 'card.json')} is not JSON — fix it, or accept the master again with funtools cast add`);
+        }
+        let palette = [];
+        try {
+            palette = (JSON.parse(readFileSync(join(dir, 'palette.json'), 'utf8')).colours ?? []).map((c) => c.hex);
+        }
+        catch { }
+        out.set(id, { card: { ...card, id }, dir, master: masterPath(id), ...(existsSync(join(dir, 'turnaround.png')) ? { turnaround: turnaroundPath(id) } : {}), palette });
+    }
+    return out;
+}
+export const masterUnchanged = (game, m) => sha(join(game, m.master)) === m.card.master_sha256;
+export function castOf(name, cast, explicit) {
+    if (explicit)
+        return cast.get(explicit);
+    const n = name.toLowerCase();
+    if (/^(ref|look)-/.test(n))
+        return undefined;
+    const ids = [...cast.keys()].sort((a, b) => b.length - a.length);
+    const id = ids.find((i) => n === i || n.startsWith(`${i}_`) || n.startsWith(`${i}-`) || n.startsWith(`${i}.`) || new RegExp(`^${i}(3d|\\d+)$`).test(n));
+    return id ? cast.get(id) : undefined;
+}
+export function keepLine(m, change) {
+    const may = change?.trim() || m.card.may_change || 'the pose and the expression';
+    return `Keep this design exactly as in the first reference image (${m.card.name}): ${m.card.pins.trim().replace(/\.$/, '')}. Change only ${may.replace(/\.$/, '')}.`;
+}
+export function addMember(game, id, o, now = new Date()) {
+    if (!ID.test(id))
+        throw new Error(`"${id}" is not a cast id — 1–24 of a-z 0-9, a letter first (it starts every file name of this design: ${id}_walk)`);
+    if (!o.pins?.trim() || o.pins.length > 600)
+        throw new Error('--pins is the design in words, 1–600 characters (hair, outfit, silhouette, colours) — it rides in every prompt of this design');
+    if (o.kind && !CAST_KINDS.includes(o.kind))
+        throw new Error(`--kind is one of ${CAST_KINDS.join(', ')}`);
+    for (const [flag, p] of [['--master', o.master], ['--turnaround', o.turnaround]]) {
+        if (!p)
+            continue;
+        if (!existsSync(p))
+            throw new Error(`${flag} ${p} is not on disk`);
+        try {
+            decodePng(readFileSync(p));
+        }
+        catch {
+            throw new Error(`${flag} ${p} is not a PNG this reader decodes — save it as an 8-bit PNG`);
+        }
+    }
+    const dir = join(game, CAST_DIR, id);
+    mkdirSync(dir, { recursive: true });
+    const master = join(dir, 'master.png');
+    if (join(game, masterPath(id)) !== o.master)
+        copyFileSync(o.master, master);
+    if (o.turnaround)
+        copyFileSync(o.turnaround, join(dir, 'turnaround.png'));
+    const pal = colours(decodePng(readFileSync(master)));
+    writeFileSync(join(dir, 'palette.json'), JSON.stringify({ measured_from: 'master.png', colours: pal.map((c) => ({ hex: c.hex, share: c.share })) }, null, 2) + '\n');
+    const card = {
+        id, name: o.name?.trim() || id, kind: o.kind ?? 'character', pins: o.pins.trim(),
+        features: (o.features ?? []).map((f) => f.trim()).filter(Boolean).slice(0, 12),
+        ...(o.mayChange ? { may_change: o.mayChange.trim() } : {}),
+        ...(o.moves !== undefined ? { moves: o.moves } : {}),
+        master_sha256: sha(master), accepted_at: now.toISOString(), ...(o.by ? { accepted_by: o.by } : {}),
+    };
+    writeFileSync(join(dir, 'card.json'), JSON.stringify(card, null, 2) + '\n');
+    writeFileSync(join(dir, 'card.md'), cardMd(card, pal.map((c) => `${c.hex} (${Math.round(c.share * 100)}%)`)));
+    return readCast(game).get(id);
+}
+function cardMd(c, pal) {
+    return [
+        `# ${c.name} (${c.kind})`, '',
+        `Master: \`master.png\`, accepted ${c.accepted_at.slice(0, 10)}${c.accepted_by ? ` by ${c.accepted_by}` : ''}. Every later picture of ${c.name} is drawn with it attached first.`, '',
+        `**Never changes:** ${c.pins}`, '',
+        `**May change:** ${c.may_change ?? 'the pose and the expression'}`, '',
+        ...(c.features.length ? ['**Features the identity check lists first:**', ...c.features.map((f) => `- ${f}`), ''] : []),
+        `**Palette (measured):** ${pal.join(', ') || 'none measured'}`, '',
+    ].join('\n');
+}