@homie-rocks/studio 0.24.4 → 0.25.0

package/bin/homie-studio.mjs

@@ -219,6 +219,12 @@
  *                                          glTF-Validator, licences, stale assets, big files in git
  *   homie-studio assets lineup|review|rights|stale|remove <id> …   the lineup (true scale, silhouettes, palette drift),
  *                                          a reviewer's score, RIGHTS.md, what a changed decision made stale
+ *   homie-studio cast <id>                the characters: proportions, silhouette, palette, skeleton family, clips
+ *   homie-studio anim [plan] <id>         each character's clips against the verbs the game needs (idle, run, jump,
+ *                                          attack, hit, die, ...) and where each comes from
+ *   homie-studio anim add <id> <asset> --verbs jump,attack [--from <library item>]   more verbs, retargeted onto its
+ *                                          skeleton at build time into its clip library (public/anims/<skeleton>.glb)
+ *   homie-studio anim preview <id> [--asset <asset>]   looping previews of every clip (animated WebP) and a sheet
  *
  *   homie-studio statusline               the current build in one line (what Claude Code's status line shows)
  *   homie-studio statusline --install [--project <folder>]
@@ -266,12 +272,12 @@ import { installStatusLine, statusLine } from '../lib/statusline.mjs';
 import { restartWithProxy } from '../lib/net.mjs';
 import { demoGames, formatDemo } from '../lib/demo.mjs';
 import { serveMcp } from '../lib/mcp.mjs';
-import { artLines, assetsCommand, styleCommand } from '../lib/art-cli.mjs';
+import { animCommand, artLines, assetsCommand, castView, styleCommand } from '../lib/art-cli.mjs';
 import { formatHandoff, handoff } from '../lib/handoff.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai'];
+const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -287,10 +293,11 @@ const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
   if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
-  if (result.ok === false && result.command !== 'port check' && !(result.command === 'look' && result.rows)) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}${result.instead ? `\n${result.instead}` : ''}\n`); return; }
+  // A check that found problems still prints them (its rows say what to fix), never a bare "failed".
+  if (result.ok === false && result.command !== 'port check' && !(result.command === 'look' && result.rows) && !(result.command === 'assets check' && result.rows)) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}${result.instead ? `\n${result.instead}` : ''}\n`); return; }
   if (result.ok === false && result.command === 'port check' && !result.rows) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   const lines = [];
-  if (/^(style|assets)( |$)/.test(String(result.command ?? ''))) { process.stdout.write(`${artLines(result).join('\n')}\n`); return; }
+  if (/^(style|assets|cast|anim)( |$)/.test(String(result.command ?? ''))) { process.stdout.write(`${artLines(result).join('\n')}\n`); return; }
   switch (result.command) {
     case 'new':
       lines.push(`${result.name} is a studio now: ${result.dir}`, '', 'Wrote:', ...result.wrote.map((f) => `  ${f}`), '', `Dependencies: ${result.installed}`, '', 'Next:', ...result.next.map((n) => `  ${n}`), '', result.online);
@@ -686,6 +693,8 @@ async function main() {
   const root = requireStudio();
   if (cmd === 'style') return styleCommand(root, sub, positional, flags, { log });
   if (cmd === 'assets') return assetsCommand(root, sub, positional, flags, { log });
+  if (cmd === 'anim') return animCommand(root, sub, positional, flags, { log });
+  if (cmd === 'cast') { const games = listGames(root); const id = sub ?? (games.length === 1 ? games[0].id : null); if (!id) return { ok: false, command: 'cast', why: `name the game: homie-studio cast <id>${games.length ? ` (${games.map((g) => g.id).join(', ')})` : ''}` }; return castView(root, id); }
   if (cmd === 'statusline') return installStatusLine(root, { remove: flags.has('remove'), replace: flags.has('replace'), project: flags.get('project') ?? null });
   if (cmd === 'codex') return codexCommand(root, sub);
   if (cmd === 'progress') return progressCommand(root, sub);

package/chat/CHAT.md

@@ -14,9 +14,12 @@ studio's owner is responsible for, read [OWNERS.md](OWNERS.md).
 
 - **The Chat pill** on the play page, beside the room button: the room's last minutes, the
   reactions, the quick lines, typing where allowed, Report on a line, and two switches ("Show my
-  messages over my character", "Show chat on this screen").
+  messages over my character", "Show chat on this screen"). On a phone it is a round icon, as the
+  room button is, with the count of new lines on its corner; on a computer it says "Chat" unless
+  the word would reach the middle of the top edge, where games keep a clock or a title.
 - **The float:** every reaction rises up every screen in the room.
-- **The ticker:** a new line shows for a moment where the play page's status chip sits.
+- **The strip:** a new line shows for a moment where the play page's status chip sits (the bottom
+  left), or where the game says (below).
 - **The big screen** (`/<game>/tv`) shows the room's lines in a corner; the **watch page** has a
   Chat button; **homie.rocks** shows the room's chat on its card when the studio allows it.
 
@@ -49,9 +52,37 @@ studio's owner is responsible for, read [OWNERS.md](OWNERS.md).
 | `block`, `allow` | the studio's own words to hold (`word*` inside words) or to let through | none |
 
 `"chat": false` turns it off. A kids server, and every beginner server, keeps chat to emoji and
-quick lines whatever the game says. Where new lines show for a moment: game.json
-`"screen": { "chat": "bottom-right" }` (any corner, `top-center` or `bottom-center`), or `false`
-for only the pill's count.
+quick lines whatever the game says.
+
+**Where it sits on the screen, in game.json `"screen"`**, so a game with a busy HUD keeps typed
+chat without anything covering its clock, its title or its controls. The Chat pill sits in the
+room button's band, so `"screen": { "share": … }` places both (`"label": false` keeps both round
+icons). `"screen": { "chat": … }` places the strip of new lines and the big screen's corner:
+
+```json
+"screen": {
+  "share": { "phone": { "at": "top-left", "label": false } },
+  "chat": {
+    "desk": { "at": "top-left", "y": 130 },
+    "phone": { "lines": "sheet-only" },
+    "tv": { "at": "top-right" }
+  }
+}
+```
+
+| Field | | Default |
+|---|---|---|
+| `at` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center` or `bottom-right` | the bottom left (the bottom right when the room button is at the bottom left) |
+| `x`, `y` | move it in from its side and its edge, in CSS pixels (0 to 600; in the middle of an edge, `x` moves it either way). Sharing the room button's place, it also sits past the button | 0 |
+| `lines` | `strip` (new lines show for a moment), or `sheet-only` (they wait in the Chat sheet and the pill counts them) | `strip` |
+| `desk`, `phone`, `sideways`, `tv` | a computer, a phone held upright, a phone turned sideways (else as `phone`), the big screen: each changes only what it names | |
+
+A plain string (`"chat": "bottom-right"`) is a place for every device, and `false` is
+`"lines": "sheet-only"` for every device. The big screen has no sheet: it takes a corner only
+(the top level's when that is a corner, else the one its join card leaves free) and keeps its
+lines unless its own `tv` entry says `"sheet-only"`, which leaves it the float. A wrong field is
+the default on the page, and `homie-studio build` says which. Look at the play page on a phone
+and a computer while a round is on and somebody says something, and at `/<id>/tv`.
 
 **Speech bubbles over characters**, with the port kit (the starters draw them):
 

package/lib/art-cli.mjs

@@ -29,6 +29,14 @@
  *   assets stale <id>       assets made under an older decision
  *   assets redo <id> <asset>            made again from its kept raw file (free): today's budgets and render style
  *   assets remove <id> <asset>
+ *   assets add <id> <character item> [--keep "1H_Sword,Round_Shield"] [--verbs jump,attack] [--clips-from <item|file>]
+ *                   an animated library character (a rig, or parts with clips): the character pipeline (lib/characters.mjs)
+ *   assets add <id> --file <rigged.glb> --kind character --rigged --license <kind> [--clips-from <item>]
+ *
+ *   cast <id>                         the characters: proportions, silhouette, palette, skeleton family, source, clips
+ *   anim [plan] <id>                  each character's clips against the verbs the game needs, and where each comes from
+ *   anim add <id> <asset> --verbs jump,attack [--from <library item | file>]   more verbs, retargeted onto its skeleton
+ *   anim preview <id> [--asset <asset>] [--verbs idle,run]   looping previews (animated WebP) and a sheet, free
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -36,6 +44,7 @@ import { licenceProblems, readManifest, removeAsset, rightsMarkdown, syncCredits
 import { CATALOGUE_IDS, PHASES, blastRadius, decisionRows, derivedPrompt, initDecisions, lockDecision, oneLine, phaseProgress, pickDirection, readDecisions, setDecision, staleAssets, steerDecision, unlockDecision } from './decisions.mjs';
 import { listGames } from './studio.mjs';
 import { checkLines } from './asset-check.mjs';
+import { animPlan as animPlanOf } from './characters.mjs';
 
 /** The game a command means: the one named, else the only one. */
 function gameOf(root, id, command) {
@@ -91,6 +100,13 @@ export function writeArtSummary(root, id) {
       spend: artSpend(root, id),
       check: check ? { ok: check.ok, at: check.at, totals: check.totals, budgets: { drawCalls: check.budgets?.drawCalls, triangles: check.budgets?.triangles, textureMB: check.budgets?.textureMB, firstPlayMB: check.budgets?.firstPlayMB }, failing: check.rows.filter((r) => !r.ok).map((r) => r.id) } : null,
       lineup: lineup ? { at: lineup.at, flagged: lineup.flagged, images: lineup.images } : null,
+      // The characters and their clips (lib/characters.mjs animPlan): the Art tab's Characters, /cast and /clips.
+      ...(() => {
+        try {
+          const plan = animPlanOf(root, id);
+          return { need: plan.verbs, characters: plan.rows.map((r) => ({ id: r.id, kind: r.kind, route: r.route, family: r.family, skeleton: r.skeleton, bones: r.bones, verbs: [...r.clips.filter((c) => c.have).map((c) => c.verb), ...r.extra], missing: r.missing, retargeted: r.clips.filter((c) => c.retargeted).length, animsKB: r.animsKB })), skinning: check?.skinning ? { players: check.skinning.players, vertices: check.skinning.vertices, bones: check.skinning.bones, budget: check.skinning.budget } : null };
+        } catch { return { need: [], characters: [], skinning: null }; }
+      })(),
       board: doc?.board ? { chosen: doc.board.chosen, directions: doc.board.directions.map((d) => ({ id: d.id, label: d.label, swatch: d.swatch, mood: d.mood?.path ?? null })) } : null,
     };
     writeFileSync(join(dir, 'latest.json'), `${JSON.stringify(summary, null, 2)}\n`);
@@ -100,6 +116,18 @@ export function writeArtSummary(root, id) {
 
 const list = (v) => String(v ?? '').split(',').map((x) => x.trim()).filter(Boolean);
 
+/** A raw character file kept beside its art job (art/<slug>/raw/, git-ignored), as importModel keeps a prop's. */
+async function keepRaw(root, file, slug) {
+  const { copyFileSync } = await import('node:fs');
+  const { basename } = await import('node:path');
+  const src = resolve(root, file);
+  const safe = String(slug).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'character';
+  const dir = join(root, 'art', safe, 'raw');
+  const to = join(dir, basename(src));
+  if (src !== to) { mkdirSync(dir, { recursive: true }); copyFileSync(src, to); }
+  return `../../art/${safe}/raw/${basename(src)}`;
+}
+
 export async function styleCommand(root, sub, positional, flags, { log = () => {} } = {}) {
   const known = ['init', 'show', 'set', 'steer', 'lock', 'unlock', 'board', 'pick', 'mood', 'golden', 'blast', 'prompt'];
   const verb = known.includes(sub) ? sub : 'show';
@@ -165,15 +193,30 @@ export async function assetsCommand(root, sub, positional, flags, { log = () =>
     const doc = readDecisions(root, id);
     r = { ok: true, command: 'assets', id, assets: m.assets.map((a) => ({ id: a.id, kind: a.kind, route: a.route, tier: a.tier ?? null, card: a.card ?? null, license: a.license?.kind ?? null, remix: a.license?.remix ?? null, file: (a.files ?? []).find((f) => f.role === 'model')?.path ?? null, tris: a.measured?.tris ?? null, kb: a.measured?.glbKB ?? null, usd: +(a.made?.steps ?? []).reduce((n, s) => n + (Number(s.usd) || 0), 0).toFixed(3) })), stale: doc ? staleAssets(doc, m).map((s) => s.id) : [], spend: artSpend(root, id) };
   } else if (verb === 'add') {
-    if (flags.get('file')) {
+    const rigFlags = { keep: flags.has('keep') ? list(flags.get('keep')) : null, verbs: list(flags.get('verbs')), clipsFrom: flags.get('clips-from') ?? null, texture: flags.get('texture') ?? null, triangles: flags.get('triangles') ?? null };
+    const characterKind = ['character', 'creature'].includes(String(flags.get('kind') ?? ''));
+    if (flags.get('file') && (flags.has('rigged') && characterKind) && !flags.has('no-rig')) {
+      // A rigged character file (the person's own, or a provider's): the character pipeline, clips and all.
+      const { addCharacter } = await import('./characters.mjs');
+      let steps = [];
+      if (flags.get('steps')) steps = JSON.parse(readFileSync(resolve(String(flags.get('steps'))), 'utf8'));
+      const raw = await keepRaw(root, String(flags.get('file')), flags.get('slug') ?? flags.get('as') ?? 'character');
+      r = await addCharacter(root, id, { file: String(flags.get('file')), as: flags.get('as') ?? args[1] ?? null, kind: flags.get('kind'), card: flags.get('card') ?? null, height: flags.get('height') ?? null, license: flags.get('license') ?? null, attribution: flags.get('attribution') ?? null, owner: flags.get('owner') ?? null, notes: flags.get('notes') ?? null, route: flags.get('route') ?? 'imported', steps, concept: flags.get('concept') ?? null, rawPath: raw, ...rigFlags });
+    } else if (flags.get('file')) {
       const { importModel } = await import('./asset-import.mjs');
       let steps = [];
       if (flags.get('steps')) steps = JSON.parse(readFileSync(resolve(String(flags.get('steps'))), 'utf8'));
       r = await importModel(root, id, String(flags.get('file')), { as: flags.get('as') ?? args[1] ?? null, kind: flags.get('kind') ?? 'prop', tier: flags.get('tier') ?? null, card: flags.get('card') ?? null, height: flags.get('height') ?? null, triangles: flags.get('triangles') ?? null, texture: flags.get('texture') ?? null, license: flags.get('license') ?? null, attribution: flags.get('attribution') ?? null, notes: flags.get('notes') ?? null, owner: flags.get('owner') ?? null, route: flags.get('route') ?? 'imported', steps, concept: flags.get('concept') ?? null, slug: flags.get('slug') ?? null, rigged: flags.has('rigged') });
     } else {
       if (!args[1]) return { ok: false, command: 'assets add', why: 'usage: homie-studio assets add <game> <library item> (assets find "<words>" lists them), or --file <model> --license <kind>' };
-      const { addFromLibrary, libraryBase } = await import('./library.mjs');
-      r = await addFromLibrary(root, id, args[1], { as: flags.get('as') ?? null, height: flags.get('height') ?? null, card: flags.get('card') ?? null, lib: libraryBase(flags.get('library') ?? undefined) });
+      const { addFromLibrary, libraryBase, loadIndex } = await import('./library.mjs');
+      const lib = libraryBase(flags.get('library') ?? undefined);
+      const { index } = await loadIndex({ lib });
+      const item = index.items.find((x) => x.id === args[1]) ?? index.items.find((x) => x.item === args[1]);
+      const { addCharacter, isAnimated } = await import('./characters.mjs');
+      // An animated character (a rig, or parts with clips): phone-sized with its clips in its skeleton's clip library.
+      if (isAnimated(item) && !flags.has('no-rig')) r = await addCharacter(root, id, { item: item.id, as: flags.get('as') ?? null, height: flags.get('height') ?? null, card: flags.get('card') ?? null, kind: flags.get('kind') ?? null, lib, index, ...rigFlags });
+      else r = await addFromLibrary(root, id, args[1], { as: flags.get('as') ?? null, height: flags.get('height') ?? null, card: flags.get('card') ?? null, lib, index });
     }
   } else if (verb === 'redo') {
     if (!args[1]) return { ok: false, command: 'assets redo', why: 'usage: homie-studio assets redo <game> <asset> (made again from its kept raw file, free)' };
@@ -189,6 +232,44 @@ export async function assetsCommand(root, sub, positional, flags, { log = () =>
   return r;
 }
 
+/** `cast <id>`: the game's characters and the decisions that shape them (a cast list for the cast card and the mod). */
+export function castView(root, id) {
+  const doc = readDecisions(root, id);
+  const m = readManifest(root, id);
+  const d = doc?.decisions ?? {};
+  const pal = d['style.palette']?.value ?? null;
+  const planned = (d['cast.list']?.value ?? []).filter((c) => c.kind === 'character' || c.kind === 'creature');
+  const made = m.assets.filter((a) => a.kind === 'character' || a.kind === 'creature');
+  const rows = [
+    ...made.map((a) => ({ id: a.id, card: a.card ?? null, kind: a.kind, state: 'made', route: a.route, source: a.from?.item ?? (a.route === 'generated' ? 'generated' : a.license?.kind ?? null), family: a.rig?.family ?? null, skeleton: a.rig?.skeleton ?? null, bones: a.rig?.bones ?? a.measured?.bones ?? null, tris: a.measured?.tris ?? null, heightM: a.measured?.heightM ?? null, kb: a.measured?.glbKB ?? null, verbs: a.rig?.verbs ?? [], keep: a.rig?.keep ?? [], usd: +(a.made?.steps ?? []).reduce((n, s) => n + (Number(s.usd) || 0), 0).toFixed(3), license: a.license?.kind ?? null })),
+    ...planned.filter((c) => !made.some((a) => a.id === c.id || a.card === c.card)).map((c) => ({ id: c.id, card: c.card, kind: c.kind, state: 'planned', route: null, source: null, family: null, skeleton: null, bones: null, tris: null, heightM: c.heightM ?? null, kb: null, verbs: [], keep: [], usd: 0, license: null })),
+  ];
+  return {
+    ok: true, command: 'cast', id,
+    decisions: Object.fromEntries(['style.proportions', 'style.shape', 'style.palette', 'cast.family', 'cast.scale', 'cast.variation', 'rig.skeleton', 'rig.source', 'rig.bones'].map((k) => [k, d[k] ? { label: d[k].label, state: d[k].state, why: d[k].why } : null])),
+    silhouette: d['style.shape']?.value?.silhouette ?? 'every character readable black on white at 64 px tall',
+    palette: pal ? ['bg', 'ink', 'accent', 'accent2', 'danger', 'good', 'gold'].map((k) => pal[k]).filter(Boolean) : [],
+    rows,
+    spend: artSpend(root, id),
+  };
+}
+
+export async function animCommand(root, sub, positional, flags, { log = () => {} } = {}) {
+  const known = ['plan', 'add', 'preview'];
+  const verb = known.includes(sub) ? sub : 'plan';
+  const args = known.includes(sub) ? positional.slice(2) : positional.slice(1);
+  const id = gameOf(root, args[0], `anim ${verb}`);
+  const C = await import('./characters.mjs');
+  let r;
+  if (verb === 'plan') r = C.animPlan(root, id);
+  else if (verb === 'add') {
+    if (!args[1]) return { ok: false, command: 'anim add', why: 'usage: homie-studio anim add <game> <character asset> --verbs jump,attack [--from <library item | file>]' };
+    r = await C.bakeClips(root, id, args[1], { verbs: list(flags.get('verbs')), from: flags.get('from') ?? null });
+  } else r = await C.animPreview(root, id, { asset: flags.get('asset') ?? args[1] ?? null, verbs: flags.has('verbs') ? list(flags.get('verbs')) : null, log });
+  writeArtSummary(root, id);
+  return r;
+}
+
 /* ------------------------------------------------------------------ what a person reads */
 
 const MARK = { auto: '·', steered: '~', pinned: '●', locked: '■' };
@@ -197,7 +278,7 @@ export function artLines(r) {
   const L = [];
   switch (r.command) {
     case 'style init':
-      L.push(`${r.summary}.`, `  ${r.picked.length} decision${r.picked.length === 1 ? '' : 's'} picked automatically (a ${r.genre} game)${r.kept.length ? `; ${r.kept.length} kept as the person set them` : ''}. ${r.file}`, '  Open the codex to change anything; steer, lock or the style board give the person control.');
+      L.push(`${r.summary}.`, `  ${r.picked.length} decision${r.picked.length === 1 ? '' : 's'} picked automatically (a ${r.genre} game)${r.kept.length ? `; ${r.kept.length} kept (set by the person, or what the game already draws)` : ''}. ${r.file}`, '  Open the codex to change anything; steer, lock or the style board give the person control.');
       break;
     case 'style': {
       L.push(`${r.id}: ${r.line}`, `  path: ${r.path}${r.budget ? `, art budget US$${r.budget.usd}` : ', free routes only (no art budget)'}`);
@@ -252,7 +333,8 @@ export function artLines(r) {
       if (r.items.length) L.push(`  Add one: homie-studio assets add <game> ${r.items[0].id} [--height <m>]`);
       break;
     case 'assets add':
-      L.push(`games/${r.game}: ${r.asset} added (${r.item ? `from the library: ${r.item}` : r.route}; licence ${r.license}).`, ...(r.after ? [`  ${r.before.tris} -> ${r.after.tris} triangles, ${r.before.kb} -> ${r.after.kb} KB, ${r.after.heightM} m tall; raw kept in ${r.raw} (git-ignored)`] : []), ...(r.pinned?.length ? [`  pinned by use: ${r.pinned.join(', ')}`] : []), ...(r.warnings ?? []).map((w) => `  note: ${w}`));
+      L.push(`games/${r.game}: ${r.asset} added (${r.item ? `from the library: ${r.item}` : r.route}; licence ${r.license}).`, ...(r.after ? [`  ${r.before.tris} -> ${r.after.tris} triangles, ${r.before.kb} -> ${r.after.kb} KB, ${r.after.heightM} m tall${r.raw ? `; raw kept in ${r.raw} (git-ignored)` : ''}`] : []),
+        ...(r.skeleton ? [`  ${r.family} skeleton ${r.skeleton} (${r.after?.bones ?? '?'} bones, ${r.after?.drawCalls ?? '?'} draw call${r.after?.drawCalls === 1 ? '' : 's'}${r.merged ? `, ${r.merged} parts merged` : ''}${r.dropped?.length ? `, left out: ${r.dropped.join(', ')}` : ''}); clips in ${r.anims}: ${r.verbs.join(', ')}${r.clipsFrom?.length ? ` (retargeted from ${r.clipsFrom.join(', ')})` : ''}${r.missing?.length ? `; no source for ${r.missing.join(', ')}` : ''}`] : []), ...(r.pinned?.length ? [`  pinned by use: ${r.pinned.join(', ')}`] : []), ...(r.warnings ?? []).map((w) => `  note: ${w}`));
       break;
     case 'assets redo':
       L.push(`games/${r.game}: ${r.asset} made again from its raw file (free): ${r.before.tris} -> ${r.after.tris} triangles, ${r.after.kb} KB, ${r.after.heightM} m (${r.ops.join(', ')})`, ...(r.warnings ?? []).map((w) => `  note: ${w}`));
@@ -278,6 +360,24 @@ export function artLines(r) {
     case 'assets remove':
       L.push(r.ok ? `Removed ${r.asset} from the manifest${r.deleted.length ? `, and its shipped copy (${r.deleted.join(', ')})` : ''}.${r.kept.length ? ` Kept ${r.kept.join(', ')}: changed since it was recorded, so delete it yourself if it is unused.` : ''} A raw file in art/ stays.` : r.why);
       break;
+    case 'cast': {
+      const out = [`The cast of ${r.id}: ${r.rows.length} character${r.rows.length === 1 ? '' : 's'}`];
+      for (const [k, v] of Object.entries(r.decisions)) if (v) out.push(`  ${k}: ${v.label} [${v.state}]`);
+      for (const row of r.rows) out.push(`  ${row.state === 'made' ? 'made   ' : 'planned'} ${row.id} (${row.kind}${row.route ? `, ${row.route}` : ''})${row.family ? `: ${row.family} skeleton ${row.skeleton}, ${row.bones} bones, ${row.tris} triangles, ${row.heightM} m, ${row.verbs.length} clips` : ''}${row.usd ? `, US$${row.usd}` : ''}`);
+      return out;
+    }
+    case 'anim plan': {
+      const out = [`Clips for ${r.game}: the game needs ${r.verbs.join(', ')}`];
+      for (const row of r.rows) {
+        out.push(`  ${row.id} (${row.familyLabel}, ${row.skeleton}, ${row.bones} bones${row.animsKB ? `, its clip library ${row.animsKB} KB` : ''})`);
+        for (const c of row.clips) out.push(`    ${c.have ? 'ok  ' : 'MISS'} ${c.verb}${c.have ? ` <- ${c.source}${c.retargeted ? ` (retargeted from ${c.from})` : ''}` : ''}`);
+        if (row.extra.length) out.push(`    also: ${row.extra.join(', ')}`);
+      }
+      for (const u of r.unrigged) out.push(`  ${u}: no rig (a static model; the animate guide says how to rig one)`);
+      return out;
+    }
+    case 'anim add': return [`${r.asset}: ${r.added.length ? `added ${r.added.join(', ')}` : 'nothing new'} (its skeleton ${r.skeleton}: ${r.verbs.join(', ')}${r.kb ? `; ${r.kb} KB` : ''})${r.missing.length ? `; no source has ${r.missing.join(', ')}` : ''}${r.why ? ` (${r.why})` : ''}`];
+    case 'anim preview': return [`Previews in .studio/art/${r.game}/anim/:`, ...r.rows.map((row) => `  ${row.id}: ${row.verbs.map((v) => v.verb).join(', ')}${row.sheet ? ` (sheet ${row.sheet})` : ''}`)];
     case 'assets check':
       L.push(...checkLines(r));
       break;

package/lib/art-tools.mjs

@@ -14,6 +14,14 @@
  *   asset_check     phone budgets, the validator, licences, staleness
  *   asset_lineup    true scale, silhouettes, palette drift, flags                                                 lineup card
  *   asset_rights    RIGHTS.md and every asset's licence                                                           rights card
+ *   cast_plan       the characters: proportions, silhouette, palette, skeleton family, source, clips, cost         cast card
+ *   character_make  one generated, rigged character on the person's own fal account: a priced dry run unless approve;
+ *                   the A-pose concept first, then (after looking) Meshy's mesh and auto-rig, the library's clips
+ *                   retargeted onto it for free                                                                    lineup card
+ *   anim_plan       each character's clips against the verbs the game needs, as looping previews; Feel opens the
+ *                   Game Lab on the move                                                                          animation card
+ *   anim_add        more verbs for a character, retargeted onto its skeleton (free)                              animation card
+ *   anim_preview    the looping previews drawn again (free)                                                       animation card
  *
  * Work that needs the studio's own tools (rendering, optimising) runs the studio's pinned CLI as a job; decisions are
  * plain files and change here directly. Pictures go to cards as small data: URLs (each a few hundred KB at most).
@@ -21,7 +29,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readManifest } from './asset-manifest.mjs';
-import { artSpend, writeArtSummary } from './art-cli.mjs';
+import { artSpend, castView, writeArtSummary } from './art-cli.mjs';
+import { animPlan } from './characters.mjs';
 import { CATALOGUE_IDS, decisionRows, lockDecision, oneLine, phaseProgress, pickDirection, readDecisions, setDecision, staleAssets, steerDecision, unlockDecision } from './decisions.mjs';
 import { libraryBase, loadIndex, searchLibrary, itemThumb } from './library.mjs';
 import { boardView } from './style-board.mjs';
@@ -33,6 +42,7 @@ export const ART_UI = Object.freeze({
   cast: 'ui://homie-studio/cast',
   lineup: 'ui://homie-studio/lineup',
   rights: 'ui://homie-studio/rights',
+  animation: 'ui://homie-studio/animation',
 });
 
 /** A picture file as a data: URL no bigger than `max` (a smaller JPEG when it is over), or null. */
@@ -77,6 +87,68 @@ function styleText(d) {
   ].join('\n');
 }
 
+/** A character's small picture: its looping idle preview, else its library thumbnail, else its concept. */
+async function characterThumb(h, root, game, row) {
+  const idle = join(root, '.studio', 'art', game, 'anim', `${row.id}-idle.webp`);
+  if (existsSync(idle)) return picture(h, idle, 40 * 1024);
+  const m = readManifest(root, game).assets.find((a) => a.id === row.id);
+  if (m?.from?.item) {
+    try { const lib = await loadIndex({ lib: libraryBase() }); const it = lib.index.items.find((x) => x.id === m.from.item); const t = it ? await itemThumb(lib.lib, it) : null; if (t) return `data:image/webp;base64,${Buffer.from(t).toString('base64')}`; } catch { /* no library here */ }
+  }
+  const concept = (m?.files ?? []).find((f) => f.role === 'concept');
+  return concept ? picture(h, join(root, 'games', game, concept.path), 60 * 1024) : null;
+}
+
+/** Which Game Lab take tunes a verb (lab.json): one named for it or whose note says it, else the default. */
+function takeFor(lab, verb) {
+  const takes = Object.entries(lab?.takes ?? {});
+  const words = { attack: /swing|attack|strike|hit|punch|knock/i, jump: /jump|hop|leap/i, cast: /cast|spell/i, dodge: /dodge|roll/i, run: /run|dash|sprint/i };
+  const hit = takes.find(([k]) => k === verb) ?? takes.find(([k, t]) => (words[verb] ?? new RegExp(verb, 'i')).test(`${k} ${t?.note ?? ''}`));
+  return hit ? hit[0] : null;
+}
+
+/** The animation card's data: the plan, with looping previews for up to `max` characters (the answer stays small). */
+function animationData(h, root, game, { asset = null, max = 4 } = {}) {
+  const plan = animPlan(root, game);
+  const dir = join(root, '.studio', 'art', game, 'anim');
+  let budget = 560 * 1024;
+  const order = asset ? [...plan.rows.filter((r) => r.id === asset), ...plan.rows.filter((r) => r.id !== asset)] : plan.rows;
+  // One character a skeleton first (its clips are its skeleton's), then the rest.
+  const seen = new Set(); const first = []; const rest = [];
+  for (const r of order) { if (!seen.has(r.skeleton) || r.id === asset) { seen.add(r.skeleton); first.push(r); } else rest.push(r); }
+  const shown = new Set([...first, ...rest].slice(0, Math.max(1, max)).map((r) => r.id));
+  // Each shown character gets an even share of the answer, its core verbs first, so none is left all placeholders.
+  const CORE = ['idle', 'run', 'jump', 'attack', 'cast', 'hit', 'walk', 'land'];
+  const share = Math.floor(budget / Math.max(1, shown.size));
+  const rows = order.map((r) => {
+    const have = [...r.clips.filter((c) => c.have).map((c) => c.verb), ...r.extra];
+    const verbs = [...CORE.filter((v) => have.includes(v)), ...have.filter((v) => !CORE.includes(v))];
+    const previews = {};
+    if (shown.has(r.id)) {
+      let left = Math.min(share, budget);
+      for (const v of verbs) {
+        const f = join(dir, `${r.id}-${v}.webp`);
+        if (!existsSync(f)) continue;
+        const pic = picture(h, f, 40 * 1024);
+        if (!pic || pic.length > left) continue;
+        left -= pic.length; budget -= pic.length; previews[v] = pic;
+      }
+    }
+    return { ...r, shown: shown.has(r.id), previews, previewed: Object.keys(previews).length };
+  });
+  const takes = plan.lab?.takes ? Object.fromEntries(Object.entries(plan.lab.takes).map(([k, t]) => [k, t?.note ?? ''])) : {};
+  const feel = Object.fromEntries(['jump', 'attack', 'cast', 'run', 'dodge', 'hit', 'land'].map((v) => [v, takeFor(plan.lab, v)]).filter(([, t]) => t));
+  return { kind: 'animation', game, verbs: plan.verbs, rows, decisions: plan.decisions, takes, feel, unrigged: plan.unrigged };
+}
+
+function animationText(d) {
+  return [
+    `Clips for ${d.game}: the game needs ${d.verbs.join(', ')}.`,
+    ...d.rows.map((r) => `  ${r.id} (${r.familyLabel}, ${r.bones} bones): ${r.clips.map((c) => `${c.verb}${c.have ? '' : ' MISSING'}`).join(', ')}${r.extra.length ? `; also ${r.extra.join(', ')}` : ''}${r.previewed ? ` (${r.previewed} previews on the card)` : ''}`),
+    ...(Object.keys(d.feel).length ? [`Feel: the Game Lab tunes ${Object.entries(d.feel).map(([v, t]) => `${v} (take "${t}")`).join(', ')} New beside Today (game_lab { "take": "<take>" }).`] : ['Feel: the game has no Game Lab take for a move yet (lab.json; the lab guide).']),
+  ].join('\n');
+}
+
 export function artToolDefs(ctx, h) {
   const { ok, fail, cli, stillRunning, whyOf, needsInstall, ui, str, STUDIO_ARG, RO, RW } = h;
   const GAME = { game: str('The game\'s id (default: the only game)'), ...STUDIO_ARG };
@@ -327,5 +399,100 @@ export function artToolDefs(ctx, h) {
         return ok(`${x.file}:\n\n${x.text.slice(0, 6000)}`, { kind: 'rights', game, file: x.file, rows, problems: x.licence, text: x.text.slice(0, 20_000) });
       },
     },
+    {
+      name: 'cast_plan', title: 'Plan the characters',
+      description: 'The cast card for a game\'s characters: the decisions that shape them (proportions in heads and metres, the silhouette rule, the palette, the skeleton family, where rigs come from) and every character made or planned, with its picture, source (the free CC0 starter library, generated on the person\'s fal account, their own), skeleton and bones, triangles, height and clips. Free; nothing is made. A library character comes in with asset_add (its clips baked into its skeleton\'s clip library); a generated one with character_make (paid, priced first).',
+      inputSchema: { type: 'object', properties: { ...GAME } },
+      annotations: { title: 'Plan the characters', ...RO }, _meta: ui(ART_UI.cast),
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const game = gameOf(root, a.game);
+        const c = castView(root, game);
+        const rows = [];
+        for (const r of c.rows) rows.push({ ...r, thumb: r.state === 'made' ? await characterThumb(h, root, game, r) : null });
+        const data = { kind: 'cast', mode: 'characters', game, decisions: c.decisions, silhouette: c.silhouette, palette: c.palette, rows, spend: c.spend };
+        return ok([`The characters of ${game} (${rows.length}):`, ...Object.entries(c.decisions).filter(([, v]) => v).map(([k, v]) => `  ${k}: ${v.label} [${v.state}]`), ...rows.map((r) => `  ${r.state} ${r.id}${r.family ? `: ${r.family} skeleton, ${r.bones} bones, ${r.tris} triangles, ${r.heightM} m, clips ${r.verbs.join(', ')}` : ''} (${r.route ?? 'planned'}${r.usd ? `, US$${r.usd}` : ''})`), 'anim_plan shows each one\'s clips, looping.'].join('\n'), data);
+      },
+    },
+    {
+      name: 'character_make', title: 'Make a character (paid)',
+      description: 'One generated, rigged character for a game, in its locked style, on the person\'s OWN fal account: a full-body concept image in an A-pose (the derived style prompt; the golden images, or like: a library character, as the style reference), then Meshy 7.1 image-to-3D with its humanoid auto-rig, then free local work: made phone-sized, its skeleton mapped to the standard, the starter library\'s CC0 clips retargeted onto it (idle, run, jump, attack, hit, ...), recorded with receipts and licence. About US$1.44 (US$0.035 concept + US$1.40 mesh and rig). Without approve it is a priced dry run: tell the person the price and ask. budget sets the cap they agreed to. Step 1 makes only the concept: LOOK at it; then step: "mesh" with approve. Humanoids with clear limbs only. Never in a loop.',
+      inputSchema: { type: 'object', properties: { ...GAME, asset: str('The new character\'s id, e.g. ranger'), card: str('Its codex card, e.g. "Players/Ranger"'), what: str('Who, in plain words: build, clothes, colours, what they carry'), height: { type: 'number', description: 'Its height in metres (default: the game\'s character height)' }, like: str('A starter-library character whose look it should match (a style reference), e.g. kaykit-adventurers/rogue'), step: str('concept (default) or mesh', { enum: ['concept', 'mesh'] }), approve: { type: 'boolean', description: 'The person agreed to the price' }, budget: { type: 'number', description: 'The cap in US dollars the person agreed to for this game\'s models' }, again: { type: 'boolean', description: 'A new concept with changed words (costs another concept)' } }, required: ['asset'] },
+      annotations: { title: 'Make a character (paid)', readOnlyHint: false, destructiveHint: false, openWorldHint: true }, _meta: ui(ART_UI.lineup),
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const need = needsInstall(ctx, root); if (need) return need;
+        const game = gameOf(root, a.game);
+        const asset = String(a.asset ?? '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+        if (a.budget !== undefined) {
+          const b = await models(root, `budget for ${game}`, ['budget', game, '--cap', String(Number(a.budget))], { wait: 20_000 }).catch((e) => ({ error: e.message }));
+          if (b.error || b.job?.code) return fail(`The budget was not set: ${b.error ?? whyOf(b.job)}`);
+        }
+        const args = ['character', game, asset, ...(a.card ? ['--card', String(a.card)] : []), ...(a.what ? ['--what', String(a.what)] : []), ...(a.height ? ['--height', String(a.height)] : []), ...(a.like ? ['--like', String(a.like)] : []), ...(a.step === 'mesh' ? ['--mesh'] : []), ...(a.again ? ['--concept-again'] : []), ...(a.approve === true ? ['--yes'] : ['--dry-run'])];
+        let r;
+        try { r = await models(root, `${a.step === 'mesh' ? 'the rigged character' : 'the concept'} for ${asset}`, args, { wait: a.approve === true ? ctx.waitMs : 30_000 }); } catch (error) { return fail(error.message); }
+        if (!r.ended) return stillRunning(r.job, a.step === 'mesh' ? `The rigged character ${asset} (about 2 to 5 minutes)` : `The concept for ${asset}`);
+        const x = r.result ?? {};
+        writeArtSummary(root, game);
+        const concept = x.concept ? picture(h, join(root, x.concept), 260 * 1024) : null;
+        const request = { ...(a.card ? { card: String(a.card) } : {}), ...(a.what ? { what: String(a.what) } : {}), ...(a.height ? { height: Number(a.height) } : {}), ...(a.like ? { like: String(a.like) } : {}) };
+        const data = { kind: 'lineup', mode: 'make', character: true, game, asset, request, step: x.step ?? a.step ?? 'concept', dryRun: Boolean(x.dryRun), price: x.price ?? null, total: x.total ?? null, then: x.then ?? null, needs: x.needs ?? null, concept, model: x.model ?? null, before: x.before ?? null, after: x.after ?? null, usd: x.usd ?? null, verbs: x.verbs ?? [], skeleton: x.skeleton ?? null, spend: artSpend(root, game), next: x.next ?? null, why: x.why ?? null };
+        if (r.job.code !== 0 && !x.needs) return fail(`Not made: ${x.why ?? whyOf(r.job)}`, data);
+        const text = x.dryRun ? `${x.step === 'mesh' ? 'The rigged character' : `The concept for ${asset}`} would cost about US$${x.price?.usd} (${x.price?.basis})${x.total ? `; with the mesh and rig, about US$${x.total} for the character` : ''}, on the person's own fal account. Ask them; then character_make with approve: true (and budget: <their cap> the first time).`
+          : x.needs === 'approval' ? x.why
+            : x.step === 'concept' ? `The concept for ${asset} is made (US$${x.usd}). LOOK at it (file_read ${x.concept}): one character, whole, in an A-pose, in the game's style, on a plain background? Then character_make { "asset": "${asset}", "step": "mesh", "approve": true } (about US$${x.then?.usd ?? '1.40'}), or new words with again: true.`
+              : x.step === 'mesh' ? `${asset} is a rigged character in games/${game}: ${x.after?.tris} triangles, ${x.after?.kb} KB, ${x.after?.heightM} m, skeleton ${x.skeleton}; clips (retargeted, free): ${(x.verbs ?? []).join(', ')} (US$${x.usd}; receipts ${x.receipts?.join(', ')}). anim_preview shows its clips looping; asset_lineup shows it beside the rest.`
+                : (x.next ?? JSON.stringify(x));
+        return ok(text, data);
+      },
+    },
+    {
+      name: 'anim_plan', title: 'Clips',
+      description: 'The animation card: every character\'s clips against the verbs the game needs (its anim.clips decision: idle, walk, run, jump, attack, hit, die, ...), each as a LOOPING PREVIEW (when drawn: anim_preview), where it came from (its own, or the CC0 library\'s retargeted onto its skeleton), what is missing (anim_add adds it, free), and Feel: the Game Lab on the move (game_lab with the take that plays it), New beside Today. Free.',
+      inputSchema: { type: 'object', properties: { ...GAME, asset: str('Optional: the character to show first') } },
+      annotations: { title: 'Clips', ...RO }, _meta: ui(ART_UI.animation),
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const game = gameOf(root, a.game);
+        const d = animationData(h, root, game, { asset: a.asset ?? null });
+        if (!d.rows.length) return fail(`${game} has no rigged characters yet: asset_add a library character (assets_find "knight" kind character), or character_make`, d);
+        return ok(animationText(d), d);
+      },
+    },
+    {
+      name: 'anim_add', title: 'Add clips',
+      description: 'More verbs for a character (jump, attack, hit, die, emote, cast, block, dodge, ...): baked into its skeleton\'s clip library at build time, its own clip where it has one, else retargeted from the starter library\'s CC0 humanoid clips (from: another library item or a file). Free, a few seconds; every character with that skeleton gets them.',
+      inputSchema: { type: 'object', properties: { ...GAME, asset: str('The character'), verbs: { description: 'Verbs to add, e.g. ["jump","attack"] or "jump,attack"' }, from: str('Optional: a library item or a file to take them from') }, required: ['asset', 'verbs'] },
+      annotations: { title: 'Add clips', ...RW }, _meta: ui(ART_UI.animation),
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const need = needsInstall(ctx, root); if (need) return need;
+        const game = gameOf(root, a.game);
+        const verbs = (Array.isArray(a.verbs) ? a.verbs : String(a.verbs ?? '').split(',')).map((v) => String(v).trim()).filter(Boolean);
+        const r = await cli(ctx, root, `clips for ${a.asset}`, ['anim', 'add', game, String(a.asset), '--verbs', verbs.join(','), ...(a.from ? ['--from', String(a.from)] : [])]);
+        if (!r.ended) return stillRunning(r.job, 'Baking the clips');
+        if (r.job.code !== 0) return fail(`Not added: ${whyOf(r.job)}`);
+        const p = await cli(ctx, root, `previews of ${a.asset}`, ['anim', 'preview', game, '--asset', String(a.asset)]).catch(() => null);
+        const d = animationData(h, root, game, { asset: String(a.asset) });
+        const x = r.result ?? {};
+        return ok(`${a.asset}: ${x.added?.length ? `added ${x.added.join(', ')}` : 'nothing new'}${x.missing?.length ? `; no source has ${x.missing.join(', ')}` : ''}.${p?.ended ? '' : ' (Its previews are still being drawn.)'}\n${animationText(d)}`, { ...d, added: x.added ?? [], missing: x.missing ?? [] });
+      },
+    },
+    {
+      name: 'anim_preview', title: 'Draw the clips',
+      description: 'Draw every character\'s clips as small looping previews (animated WebP, under the game\'s light; free, one headless Chrome on this computer, a few seconds a character) and answer with the animation card.',
+      inputSchema: { type: 'object', properties: { ...GAME, asset: str('Optional: only this character') } },
+      annotations: { title: 'Draw the clips', ...RW }, _meta: ui(ART_UI.animation),
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const need = needsInstall(ctx, root); if (need) return need;
+        const game = gameOf(root, a.game);
+        const r = await cli(ctx, root, `clip previews for ${game}`, ['anim', 'preview', game, ...(a.asset ? ['--asset', String(a.asset)] : [])]);
+        if (!r.ended) return stillRunning(r.job, 'The previews');
+        if (r.job.code !== 0) return fail(`Not drawn: ${whyOf(r.job)}`);
+        const d = animationData(h, root, game, { asset: a.asset ?? null });
+        return ok(`${animationText(d)}\nSheets (a person reads them with file_read): ${(r.result?.rows ?? []).map((x) => x.sheet).filter(Boolean).join(', ')}`, d);
+      },
+    },
   ];
 }