@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/gen/kinds.js

@@ -0,0 +1,451 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, resolve } from 'node:path';
+import { promptLint } from "./prompt-lint.js";
+import { CAMERA_WORDS, ENGINE_ALIASES, MODEL_GEN_KINDS, modelKindOf, resolveModel } from "./models.js";
+import { providerFor } from "./local/index.js";
+import { dialogueArgs } from "./local/voice-rules.js";
+export const KINDS = {
+    image: { tool: 'generate_image', prompt: 'required' },
+    texture: { tool: 'generate_image', prompt: 'required', fixed: { kind: 'texture' } },
+    strip: { tool: 'generate_image', prompt: 'required', fixed: { kind: 'strip' } },
+    sprite: { tool: 'generate_sprite', prompt: 'required' },
+    edit: { tool: 'edit_image', prompt: 'required' },
+    sheet: { tool: 'generate_spritesheet', prompt: 'optional' },
+    sound: { tool: 'generate_sound', prompt: 'required' },
+    music: { tool: 'generate_music', prompt: 'required' },
+    voice: { tool: 'cast_voice', prompt: 'required', words: 'name' },
+    line: { tool: 'voice_line', prompt: 'required', words: 'text' },
+    dialogue: { tool: 'dialogue', prompt: 'required', words: 'script' },
+    model3d: { tool: 'generate_3d_model', prompt: 'optional' },
+    skybox: { tool: 'generate_skybox', prompt: 'required' },
+    'find-material': { tool: 'find_material', prompt: 'required', words: 'query' },
+    material: { tool: 'get_material', prompt: 'optional', words: 'query' },
+    inspect: { tool: 'inspect_model', prompt: 'none' },
+    'optimize-model': { tool: 'optimize_model', prompt: 'none' },
+    fracture: { tool: 'fracture_model', prompt: 'none' },
+    lod: { tool: 'lod_model', prompt: 'none' },
+    rig: { tool: 'rig_model', prompt: 'none' },
+    render: { tool: 'render_model', prompt: 'none' },
+    finalize: { tool: 'finalize_model', prompt: 'none' },
+    level: { tool: 'build_level', prompt: 'none' },
+    skin: { tool: 'author_skin', prompt: 'none' },
+    retexture: { tool: 'retexture_model', prompt: 'required' },
+    video: { tool: 'generate_video', prompt: 'required' },
+    'edit-video': { tool: 'edit_video', prompt: 'required' },
+    lipsync: { tool: 'lip_sync', prompt: 'none' },
+    characters: { tool: 'list_characters', prompt: 'none' },
+    character: { tool: 'get_character', prompt: 'required', words: 'id' },
+    'restyle-character': { tool: 'restyle_character', prompt: 'required' },
+    motion: { tool: 'author_motion', prompt: 'none' },
+    retarget: { tool: 'retarget_clips', prompt: 'none' },
+    review: { tool: 'review', prompt: 'none', via: 'playtest --hosted' },
+    play: { tool: 'play', prompt: 'none', via: 'playtest --hosted' },
+};
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const GAME_ID = /^[0-9a-f]{32}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const CYCLES = ['idle', 'walk', 'run', 'jump', 'attack', 'act', 'hit', 'death', 'blink'];
+export function parseCycles(v) {
+    const out = String(v).split(',').map((s) => s.trim()).filter(Boolean).map((c) => {
+        const m = /^([a-z]+):(\d+)(?:@(\d+))?$/.exec(c);
+        if (!m || !CYCLES.includes(m[1]))
+            throw new Error(`"${c}" is not name:frames[@fps] with a name from ${CYCLES.join(', ')}`);
+        const frames = Number(m[2]);
+        if (frames < 1 || frames > 12)
+            throw new Error(`${m[1]}: 1 to 12 frames`);
+        return { name: m[1], frames, ...(m[3] ? { fps: Number(m[3]) } : {}) };
+    });
+    if (!out.length)
+        throw new Error('name at least one cycle, e.g. idle:4,walk:6');
+    return out;
+}
+export const isAssetId = (v) => typeof v === 'string' && UUID.test(v);
+export const kindOfTool = (tool) => Object.entries(KINDS).find(([, k]) => k.tool === tool)?.[0] ?? null;
+const text = (v) => (typeof v === 'string' ? v : undefined);
+const flag = () => true;
+const oneOf = (...allowed) => (v) => {
+    if (typeof v !== 'string' || !allowed.includes(v))
+        throw new Error(`expected ${allowed.join(' or ')}, got ${String(v)}`);
+    return v;
+};
+const TAG = /^[a-z][a-z -]{0,23}$/;
+const tagList = (max) => (v) => {
+    const tags = String(v).split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+    if (!tags.length || tags.length > max || tags.some((t) => !TAG.test(t)))
+        throw new Error(`up to ${max} delivery words, comma-separated, e.g. gruff,weary`);
+    return tags;
+};
+export const GEN_FLAGS = {
+    '--size': { value: true, kinds: ['image', 'texture', 'strip', 'sprite', 'render', 'level', 'edit'], field: 'size', parse: (v) => {
+            if (typeof v === 'string' && /^\d+$/.test(v))
+                return Number(v);
+            if (typeof v !== 'string' || !/^\d+x\d+$/.test(v))
+                throw new Error('--size is WIDTHxHEIGHT for an image (e.g. 1024x1024), pixels for a render (e.g. 512)');
+            return v;
+        } },
+    '--target-size': { value: true, kinds: ['image', 'texture', 'strip', 'sprite'], field: 'target_size', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 16 || n > 2048)
+                throw new Error('--target-size is the longest side in pixels, 16 to 2048 (the size the game shows it at, or twice that)');
+            return n;
+        } },
+    '--references': { value: true, kinds: ['image', 'texture', 'strip', 'sprite', 'video'], field: 'references', parse: (v) => {
+            const refs = String(v).split(',').map((s) => s.trim()).filter(Boolean);
+            if (!refs.length || refs.length > 16)
+                throw new Error('--references is 1 to 16 pictures (files or asset ids), comma-separated');
+            return refs;
+        } },
+    '--preset': { value: true, kinds: ['voice', 'line'], field: 'preset', parse: text },
+    '--tags': { value: true, kinds: ['voice', 'line'], field: 'tags', parse: tagList(4) },
+    '--emotion': { value: true, kinds: ['line'], field: 'emotion', parse: tagList(3) },
+    '--voice': { value: true, kinds: ['line'], field: 'voice_asset_id', parse: text },
+    '--gap': { value: true, kinds: ['dialogue'], field: 'gap_ms', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 0 || n > 10000)
+                throw new Error('--gap is the silence between lines in milliseconds, 0 to 10000 (default 250)');
+            return n;
+        } },
+    '--sample': { value: true, kinds: ['voice'], field: 'sample', parse: text },
+    '--description': { value: true, kinds: ['voice'], field: 'description', parse: text },
+    '--quality': { value: true, kinds: ['image', 'texture', 'strip', 'sprite', 'retexture', 'edit', 'sheet', 'restyle-character'], field: 'quality', parse: oneOf('low', 'medium', 'high') },
+    '--transparent': { value: false, kinds: ['image', 'strip'], field: 'transparent', parse: flag },
+    '--negative': { value: true, kinds: ['skybox'], field: 'negative_prompt', parse: text },
+    '--type': { value: true, kinds: ['find-material', 'material'], field: 'kind', parse: oneOf('hdri', 'texture', 'model') },
+    '--id': { value: true, kinds: ['material', 'restyle-character'], field: 'id', parse: text },
+    '--medium': { value: true, kinds: ['characters'], field: 'medium', parse: oneOf('2d', '3d') },
+    '--body': { value: true, kinds: ['characters', 'sheet'], field: 'body', parse: oneOf('biped', 'quadruped', 'flyer') },
+    '--files': { value: true, kinds: ['character'], field: 'files', parse: (v) => String(v).split(',').map((s) => s.trim()).filter(Boolean) },
+    '--resolution': { value: true, kinds: ['material', 'video', 'edit-video', 'lipsync'], field: 'resolution', parse: oneOf('1k', '2k', '480p', '720p', '1080p') },
+    '--limit': { value: true, kinds: ['find-material'], field: 'limit', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 1 || n > 20)
+                throw new Error('--limit is a whole number from 1 to 20');
+            return n;
+        } },
+    '--duration': { value: true, kinds: ['sound', 'video', 'edit-video', 'lipsync'], field: 'duration_seconds', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isFinite(n) || n <= 0)
+                throw new Error('--duration is seconds, e.g. 1.5');
+            return n;
+        } },
+    '--loop': { value: false, kinds: ['sound'], field: 'loop', parse: flag },
+    '--length': { value: true, kinds: ['music'], field: 'length', parse: oneOf('clip', 'full') },
+    '--instrumental': { value: false, kinds: ['music'], field: 'instrumental', parse: flag },
+    '--image-url': { value: true, kinds: ['model3d', 'video', 'lipsync'], field: 'image_url', parse: text },
+    '--image-asset': { value: true, kinds: ['model3d', 'video', 'lipsync'], field: 'image_asset_id', parse: text },
+    '--audio-asset': { value: true, kinds: ['lipsync'], field: 'audio_asset_id', parse: text },
+    '--audio-url': { value: true, kinds: ['lipsync'], field: 'audio_url', parse: text },
+    '--camera-move': { value: true, kinds: ['video'], field: 'camera.move', parse: oneOf(...CAMERA_WORDS.move) },
+    '--lens': { value: true, kinds: ['video'], field: 'camera.lens', parse: oneOf(...CAMERA_WORDS.lens) },
+    '--aperture': { value: true, kinds: ['video'], field: 'camera.aperture', parse: oneOf(...CAMERA_WORDS.aperture) },
+    '--camera-speed': { value: true, kinds: ['video'], field: 'camera.speed', parse: oneOf(...CAMERA_WORDS.speed) },
+    '--aspect': { value: true, kinds: ['video', 'edit-video'], field: 'aspect_ratio', parse: oneOf('16:9', '9:16', '1:1') },
+    '--end-image-asset': { value: true, kinds: ['video'], field: 'end_image_asset_id', parse: text },
+    '--end-image-url': { value: true, kinds: ['video'], field: 'end_image_url', parse: text },
+    '--model': { value: true, kinds: MODEL_GEN_KINDS, field: 'model', parse: text },
+    '--audio': { value: false, kinds: ['video'], field: 'audio', parse: flag },
+    '--keep-audio': { value: false, kinds: ['edit-video'], field: 'keep_audio', parse: flag },
+    '--video-asset': { value: true, kinds: ['edit-video'], field: 'video_asset_id', parse: text },
+    '--video-url': { value: true, kinds: ['edit-video'], field: 'video_url', parse: text },
+    '--reference-asset': { value: true, kinds: ['edit-video'], field: 'reference_image_asset_id', parse: text },
+    '--reference-url': { value: true, kinds: ['edit-video'], field: 'reference_image_url', parse: text },
+    '--style': { value: true, kinds: ['model3d'], field: 'style', parse: oneOf('standard', 'hero', 'lowpoly') },
+    '--engine': { value: true, kinds: ['model3d'], field: 'engine', parse: oneOf(...ENGINE_ALIASES) },
+    '--raw': { value: false, kinds: ['model3d'], field: 'raw', parse: flag },
+    '--back-asset': { value: true, kinds: ['model3d'], field: 'view_asset_ids.back', parse: text },
+    '--left-asset': { value: true, kinds: ['model3d'], field: 'view_asset_ids.left', parse: text },
+    '--right-asset': { value: true, kinds: ['model3d'], field: 'view_asset_ids.right', parse: text },
+    '--animations': { value: true, kinds: ['model3d', 'restyle-character'], field: 'animations', parse: (v) => String(v).split(',').map((s) => s.trim()).filter(Boolean) },
+    '--asset': { value: true, kinds: ['inspect', 'optimize-model', 'fracture', 'lod', 'rig', 'render', 'finalize', 'skin', 'retexture', 'edit', 'sheet', 'motion', 'retarget'], field: 'asset_id', parse: text },
+    '--motions': { value: true, kinds: ['motion'], field: 'motions', parse: (v) => {
+            const raw = String(v).trim();
+            let text = raw;
+            if (!raw.startsWith('[')) {
+                try {
+                    text = readFileSync(raw, 'utf8');
+                }
+                catch {
+                    throw new Error(`--motions is a JSON array or the path of one; cannot read ${raw}`);
+                }
+            }
+            let list;
+            try {
+                list = JSON.parse(text);
+            }
+            catch (e) {
+                throw new Error(`--motions is not JSON: ${e instanceof Error ? e.message : e}`);
+            }
+            if (!Array.isArray(list) || !list.length)
+                throw new Error('--motions is a JSON array of specs, e.g. [{"kind":"nod"}]');
+            return list;
+        } },
+    '--base-clip': { value: true, kinds: ['motion'], field: 'base_clip', parse: text },
+    '--character': { value: true, kinds: ['retarget'], field: 'donor_character', parse: text },
+    '--only': { value: true, kinds: ['retarget'], field: 'clips', parse: (v) => String(v).split(',').map((s) => s.trim()).filter(Boolean) },
+    '--mode': { value: true, kinds: ['edit'], field: 'mode', parse: oneOf('edit', 'restyle', 'pose') },
+    '--cycles': { value: true, kinds: ['sheet'], field: 'animations', parse: (v) => parseCycles(String(v)) },
+    '--view': { value: true, kinds: ['sheet'], field: 'view', parse: (v) => {
+            if (/^(top|above)$/i.test(String(v)) || OVERHEAD.test(String(v)))
+                throw new Error(TOP_DOWN);
+            return oneOf('side', 'front')(v);
+        } },
+    '--frame-size': { value: true, kinds: ['sheet'], field: 'frame_size', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 64 || n > 512)
+                throw new Error('--frame-size is pixels from 64 to 512');
+            return n;
+        } },
+    '--spec': { value: true, kinds: ['level'], field: 'spec', parse: (v) => {
+            if (typeof v !== 'string')
+                throw new Error('--spec is the path of a level spec (.json)');
+            let text;
+            try {
+                text = readFileSync(v, 'utf8');
+            }
+            catch {
+                throw new Error(`cannot read ${v}`);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (e) {
+                throw new Error(`${v} is not JSON: ${e instanceof Error ? e.message : e}`);
+            }
+        } },
+    '--tone': { value: true, kinds: ['skin'], field: 'tone', parse: (v) => {
+            if (typeof v !== 'string' || !HEX.test(v))
+                throw new Error('--tone is a colour, #rrggbb (e.g. #8d5524)');
+            return v.toLowerCase();
+        } },
+    '--palette': { value: true, kinds: ['retexture', 'restyle-character'], field: 'palette', parse: (v) => {
+            const colours = String(v).split(',').map((s) => s.trim()).filter(Boolean);
+            if (colours.length === 0 || colours.length > 8 || colours.some((c) => !HEX.test(c)))
+                throw new Error('--palette is up to 8 colours, #rrggbb,#rrggbb');
+            return colours;
+        } },
+    '--game-id': { value: true, kinds: ['retexture', 'edit', 'sheet', 'restyle-character'], field: 'game_id', parse: (v) => {
+            if (typeof v !== 'string' || !GAME_ID.test(v))
+                throw new Error('--game-id is a game\'s 32-hex id (funpixel.json)');
+            return v;
+        } },
+    '--roughness': { value: false, kinds: ['retexture'], field: 'roughness', parse: flag },
+    '--normal': { value: false, kinds: ['retexture'], field: 'normal', parse: flag },
+    '--budget': { value: true, kinds: ['optimize-model'], field: 'budget', parse: oneOf('food', 'prop', 'thin_walled', 'set_piece', 'character') },
+    '--device': { value: true, kinds: ['optimize-model'], field: 'device', parse: oneOf('phone', 'desktop') },
+    '--height': { value: true, kinds: ['optimize-model'], field: 'height_m', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isFinite(n) || n <= 0)
+                throw new Error('--height is metres, e.g. 1.8');
+            return n;
+        } },
+    '--pieces': { value: true, kinds: ['fracture'], field: 'pieces', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 2 || n > 32)
+                throw new Error('--pieces is a whole number from 2 to 32');
+            return n;
+        } },
+    '--seed': { value: true, kinds: ['fracture', 'video', 'edit-video'], field: 'seed', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 0)
+                throw new Error('--seed is a whole number');
+            return n;
+        } },
+    '--levels': { value: true, kinds: ['lod'], field: 'levels', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 1 || n > 4)
+                throw new Error('--levels is a whole number from 1 to 4');
+            return n;
+        } },
+    '--ratio': { value: true, kinds: ['lod'], field: 'ratio', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isFinite(n) || n < 0.05 || n > 0.95)
+                throw new Error('--ratio is a share from 0.05 to 0.95, e.g. 0.5');
+            return n;
+        } },
+    '--min-triangles': { value: true, kinds: ['lod'], field: 'min_triangles', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 100 || n > 200_000)
+                throw new Error('--min-triangles is a whole number from 100 to 200000');
+            return n;
+        } },
+    '--donor': { value: true, kinds: ['rig', 'retarget'], field: 'donor_asset_id', parse: text },
+    '--clips': { value: true, kinds: ['rig'], field: 'clips', parse: (v) => {
+            const clips = String(v).split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+            const known = ['idle', 'walk', 'attack', 'death'];
+            const bad = clips.find((c) => !known.includes(c));
+            if (bad || clips.length === 0)
+                throw new Error(`--clips is a list from ${known.join(',')}`);
+            return clips;
+        } },
+    '--frames': { value: true, kinds: ['render'], field: 'frames', parse: (v) => {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 1 || n > 12)
+                throw new Error('--frames is a whole number from 1 to 12');
+            return n;
+        } },
+    '--keep-clips': { value: true, kinds: ['finalize'], field: 'keep_clips', parse: (v) => {
+            const clips = String(v).split(',').map((s) => s.trim()).filter(Boolean);
+            if (clips.length === 0 || clips.length > 32 || clips.some((c) => !/^[A-Za-z0-9_.|: -]{1,64}$/.test(c))) {
+                throw new Error('--keep-clips is a comma list of up to 32 clip names, e.g. Idle,Walk');
+            }
+            return clips;
+        } },
+};
+const OVERHEAD = /\b(top[- ]?down|overhead|from above|bird'?s[- ]eye)\b/i;
+const TOP_DOWN = 'a sheet draws every frame from the side or the front; an actor seen from above gets its key poses from `gen edit "<the pose>" --asset <sprite> --mode pose`, one call per pose';
+export function genNotes(req) {
+    const picture = ['image', 'texture', 'strip', 'sprite', 'edit', 'sheet', 'skybox', 'retexture', 'restyle-character'].includes(req.kind);
+    return [
+        ...(req.kind === 'sheet' && OVERHEAD.test(req.prompt) ? [`the prompt asks for a view from above, but ${TOP_DOWN}`] : []),
+        ...(picture ? promptLint(req.prompt, req.input) : []),
+    ];
+}
+export function localKinds(id) {
+    const p = providerFor(id);
+    return p ? (Object.entries(KINDS).filter(([, k]) => p.tools.includes(k.tool)).map(([k]) => k)) : [];
+}
+export function localModelOf(req) {
+    const kind = modelKindOf(req.kind);
+    if (!kind || typeof req.input.model !== 'string')
+        return null;
+    const m = resolveModel(kind, req.input.model);
+    return m.where === 'local' ? m : null;
+}
+export function genRequest(positionals, flags) {
+    const [kindArg, ...words] = positionals;
+    if (!kindArg || !Object.hasOwn(KINDS, kindArg)) {
+        throw new Error(`${kindArg ? `unknown kind: ${kindArg}` : 'no kind given'} — use one of ${Object.keys(KINDS).join(', ')}`);
+    }
+    const kind = kindArg;
+    const spec = KINDS[kind];
+    if (spec.via)
+        throw new Error(`${kind} is submitted by \`funtools ${spec.via}\`; \`funtools job <id> --wait\` reads one back`);
+    const prompt = words.join(' ').trim();
+    const input = { ...spec.fixed };
+    if (prompt) {
+        if (spec.prompt === 'none')
+            throw new Error(`${kind} takes no prompt — pass --asset <asset_id>`);
+        input[spec.words ?? 'prompt'] = prompt;
+    }
+    else if (kind === 'dialogue') {
+        throw new Error('dialogue needs the scene as a JSON file — funtools gen dialogue scene.json (an array of {speaker, text, voice?}, or {lines, cast?, gap_ms?})');
+    }
+    else if (spec.prompt === 'required') {
+        throw new Error(`${kind} needs ${spec.words ? 'keywords' : 'a prompt'} — funtools gen ${kind} "what it should be"`);
+    }
+    for (const [name, value] of Object.entries(flags)) {
+        const f = GEN_FLAGS[name];
+        if (!f)
+            continue;
+        if (!f.kinds.includes(kind))
+            throw new Error(`${name} is for ${f.kinds.join(', ')}, not ${kind}`);
+        let v;
+        try {
+            v = f.parse(value);
+        }
+        catch (e) {
+            throw new Error(`${name}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const [field, key] = f.field.split('.');
+        if (key)
+            input[field] = { ...input[field], [key]: v };
+        else
+            input[field] = v;
+    }
+    if (kind === 'level') {
+        if (!input.spec)
+            throw new Error('level needs --spec <level.json>');
+    }
+    else if (kind === 'lipsync') {
+        if (!input.image_asset_id && !input.image_url)
+            throw new Error('lipsync needs the portrait: --image-asset <picture file or asset_id> or --image-url');
+        if (!input.audio_asset_id && !input.audio_url)
+            throw new Error('lipsync needs the speech: --audio-asset <line.mp3 or asset_id> or --audio-url');
+        if (typeof input.duration_seconds === 'number')
+            input.duration_seconds = Math.ceil(input.duration_seconds);
+    }
+    else if ((spec.prompt === 'none' || kind === 'retexture') && !input.asset_id && kind !== 'characters') {
+        throw new Error(`${kind} needs --asset <asset_id> (a model a job of yours made)`);
+    }
+    else if (kind === 'edit' && !input.asset_id) {
+        throw new Error('edit needs --asset <file or asset_id>: a picture a job of yours made');
+    }
+    else if (kind === 'sheet') {
+        if (!input.animations)
+            throw new Error('sheet needs --cycles, e.g. --cycles idle:4,walk:6');
+        if (!prompt && !input.asset_id)
+            throw new Error('sheet needs the character: a prompt, --asset <sprite file or asset_id>, or both');
+    }
+    if (kind === 'model3d' && !prompt && !input.image_url && !input.image_asset_id) {
+        throw new Error('model3d needs a prompt, --image-url or --image-asset');
+    }
+    if (kind === 'model3d' && input.view_asset_ids && !input.image_url && !input.image_asset_id) {
+        throw new Error('--back-asset, --left-asset and --right-asset are more sides of the front picture — give the front with --image-asset or --image-url');
+    }
+    const modelKind = modelKindOf(kind);
+    const named = modelKind && typeof input.model === 'string' ? resolveModel(modelKind, input.model) : null;
+    const engine3d = kind === 'model3d' ? (named ?? (typeof input.engine === 'string' ? resolveModel('model3d', input.engine) : null)) : null;
+    if (named && kind === 'model3d' && typeof input.engine === 'string' && resolveModel('model3d', input.engine).id !== named.id) {
+        throw new Error(`--model ${named.id} and --engine ${input.engine} name different models — give one`);
+    }
+    if (engine3d?.id === 'meshy-7.1' && input.style === 'lowpoly') {
+        throw new Error('--style lowpoly is made by hunyuan or rodin, not meshy — drop --engine or give --engine hunyuan|rodin');
+    }
+    if (engine3d?.id === 'rodin-2.5' && Array.isArray(input.animations) && input.animations.length > 0) {
+        throw new Error('--engine rodin makes static models only (it has no rig) — drop --animations, or drop --engine to rig a humanoid');
+    }
+    if (kind === 'motion' && !input.motions)
+        throw new Error('motion needs --motions \'[{"kind":"nod"}]\' (or a .json file of specs)');
+    if (kind === 'retarget' && Boolean(input.donor_asset_id) === Boolean(input.donor_character)) {
+        throw new Error('retarget takes the clips from --donor <asset id> or --character <3D library id>, one of them');
+    }
+    if (named?.where === 'local' && !localKinds(named.id).includes(kind)) {
+        throw new Error(`${named.id} runs on this Mac for ${localKinds(named.id).join(', ') || 'nothing yet'}, not ${kind} — drop --model for our pick`);
+    }
+    if (kind === 'voice' && !input.preset)
+        throw new Error('voice needs --preset <one of the 30 voices: Kore, Puck, Charon, …> (TOOLS_API.md, cast_voice)');
+    if (kind === 'line' && Boolean(input.voice_asset_id) === Boolean(input.preset)) {
+        throw new Error('line takes the voice from --voice <voice.json or its asset id> or --preset <name>, one of them');
+    }
+    if (kind === 'dialogue') {
+        const path = String(input.script);
+        delete input.script;
+        Object.assign(input, { ...readScript(path), ...input });
+        dialogueArgs(input);
+        return { kind, tool: spec.tool, input, prompt: basename(path, extname(path)) };
+    }
+    if (kind === 'restyle-character' && !input.id)
+        throw new Error('restyle-character needs --id <character id from funtools character list>');
+    if (kind === 'material') {
+        if (!input.kind)
+            throw new Error('material needs --type hdri|texture|model');
+        if (Boolean(prompt) === Boolean(input.id))
+            throw new Error('material takes keywords or --id <id from find-material>, one of them');
+    }
+    return { kind, tool: spec.tool, input, prompt: prompt || (typeof input.id === 'string' ? input.id : '') };
+}
+function voicePath(v, base) {
+    if (typeof v !== 'string' || isAbsolute(v) || !(v.endsWith('.json') || v.includes('/')))
+        return v;
+    const beside = resolve(base, v);
+    return existsSync(beside) ? beside : v;
+}
+export function readScript(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`dialogue reads the scene from a JSON file: ${path} ${existsSync(path) ? `is not JSON (${e.message})` : 'does not exist'} — e.g. [{"speaker":"Bram","text":"Haul that line.","voice":"Charon"}]`);
+    }
+    const doc = Array.isArray(raw) ? { lines: raw } : raw;
+    if (!doc || typeof doc !== 'object')
+        throw new Error(`${path}: the scene is an array of lines or {lines, cast?, gap_ms?}`);
+    const base = dirname(resolve(path));
+    const d = { ...doc };
+    if (Array.isArray(d.lines))
+        d.lines = d.lines.map((l) => (l && typeof l === 'object' && 'voice' in l ? { ...l, voice: voicePath(l.voice, base) } : l));
+    if (d.cast && typeof d.cast === 'object' && !Array.isArray(d.cast))
+        d.cast = Object.fromEntries(Object.entries(d.cast).map(([k, v]) => [k, voicePath(v, base)]));
+    return d;
+}

package/dist/gen/local/doctor.js

@@ -0,0 +1,25 @@
+import { MODELS } from "../models.js";
+import { providerFor } from "./index.js";
+import { realMachine } from "./provider.js";
+export const LOCAL_HEADING = 'Local models (optional: ours is recommended; these run free on this Mac, slower and not checked by us)';
+export function localModelLines(m = realMachine()) {
+    const out = [];
+    for (const x of MODELS.filter((x) => x.where === 'local')) {
+        const check = `${x.id} (${x.kind}, on this Mac)`;
+        const p = providerFor(x.id);
+        if (!p) {
+            out.push({ model: x.id, check, state: 'warn', says: 'no runner in this funtools yet', next: 'upgrade funtools: npx @funpixel/tools@latest' });
+            continue;
+        }
+        const c = p.check(m);
+        if (c.state === 'installed')
+            out.push({ model: x.id, check, state: 'pass', says: c.says });
+        else if (c.state === 'missing')
+            out.push({ model: x.id, check, state: 'warn', says: `not set up${c.detail ? `: ${c.detail}` : ''}`, next: c.fix });
+        else
+            out.push({ model: x.id, check, state: 'warn', says: c.says, next: `use our pick: leave --model out of gen ${x.kind}` });
+        if (c.state === 'installed' && !m.which('ffmpeg'))
+            out.push({ model: x.id, check: 'ffmpeg (masters what it makes)', state: 'warn', says: 'not installed: its audio ships raw, unmastered', next: 'brew install ffmpeg' });
+    }
+    return out;
+}

package/dist/gen/local/index.js

@@ -0,0 +1,3 @@
+import { kokoro } from "./kokoro.js";
+export const PROVIDERS = [kokoro];
+export const providerFor = (id) => PROVIDERS.find((p) => p.id === id) ?? null;