@homie-rocks/studio 0.24.5 → 0.26.0

package/lib/site.mjs

@@ -419,8 +419,19 @@ export function landingOf(g, out, { videos = [], songs = [], log = () => {} } =
   // The landing's own colours (landing.theme): only colours, and the ink on its own accent worked out like the studio's.
   // Else the game's own palette (games/<id>/style.json, its art-direction decisions): one look from the game to its page.
   const style = !L.theme ? readJson(join(g.dir, 'style.json'))?.palette : null;
-  // Its accents only: the page keeps the studio's light or dark scheme, so its text always reads.
-  const fromStyle = style && typeof style === 'object' ? { accent: style.accent, glow: style.accent2 } : null;
+  // 0.26.0: the whole landing in that palette (its paper as the page, its ink as the words, its accents) when the game
+  // sets no landing colours or scheme of its own and its ink reads on its paper (4.5:1): a bright game is no longer
+  // shown on the studio's dark page. The scheme follows the paper. Anything less readable: its accents only, on the
+  // studio's scheme, as before.
+  let fromStyle = style && typeof style === 'object' ? { accent: style.accent, glow: style.accent2 } : null;
+  let ownScheme = null;
+  if (fromStyle && L.scheme === undefined) {
+    const paper = luminance(style.bg); const ink = luminance(style.ink);
+    if (paper !== null && ink !== null && (Math.max(paper, ink) + 0.05) / (Math.min(paper, ink) + 0.05) >= 4.5) {
+      fromStyle = { ...fromStyle, bg: style.bg, fg: style.ink };
+      ownScheme = paper > ink ? 'light' : 'dark';
+    }
+  }
   const raw = L.theme && typeof L.theme === 'object' ? L.theme : fromStyle;
   const theme = raw ? Object.fromEntries(['accent', 'glow', 'bg', 'fg'].filter((k) => COLOR.test(String(raw[k] ?? ''))).map((k) => [k, raw[k]])) : null;
   if (theme?.accent) { const l = luminance(theme.accent); if (l !== null) theme.accentInk = l > 0.4 ? '#0b0b10' : '#ffffff'; }
@@ -443,7 +454,7 @@ export function landingOf(g, out, { videos = [], songs = [], log = () => {} } =
     source: g.share?.source !== false,
     tv: g.screen?.tv !== false && L.tv !== false,
     theme: theme && Object.keys(theme).length ? theme : null,
-    ...(L.scheme === 'light' || L.scheme === 'dark' ? { scheme: L.scheme } : {}),
+    ...(L.scheme === 'light' || L.scheme === 'dark' ? { scheme: L.scheme } : ownScheme ? { scheme: ownScheme, schemeFrom: 'style' } : {}),
   };
 }
 

package/lib/studio.mjs

@@ -3,7 +3,7 @@
  * current directory, and its games.
  */
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { httpsPage, licenseOf, pageOfSource, remixAllowed, remixCredit, remixRow } from '../worker/license.mjs';
 
@@ -208,7 +208,10 @@ async function fetchStarterModels(dest, only = null) {
   }
   const missing = [];
   let fetched = 0;
-  for (const a of wanted) {
+  // A character the starter names with a `rig` recipe goes through the character pipeline (lib/characters.mjs): made
+  // phone-sized, its held things picked, its clips baked into its skeleton's clip library. Everything else is copied.
+  const rigged = wanted.filter((a) => a.rig && ['character', 'creature'].includes(a.kind));
+  for (const a of wanted.filter((x) => !rigged.includes(x))) {
     const item = index.items.find((x) => x.id === a.from.item);
     const f = a.files.find((x) => x.role === 'model');
     if (!item) { missing.push({ asset: a.id, item: a.from.item, why: `the library has no ${a.from.item}` }); continue; }
@@ -222,7 +225,19 @@ async function fetchStarterModels(dest, only = null) {
     } catch (error) { missing.push({ asset: a.id, item: a.from.item, why: error.message }); }
   }
   writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
-  return { fetched, missing, from: lib.base };
+  let baked = 0;
+  if (rigged.length) {
+    const { addCharacter } = await import('./characters.mjs');
+    const root = join(dest, '..', '..');
+    const game = basename(dest);
+    for (const a of rigged) {
+      try {
+        await addCharacter(root, game, { item: a.from.item, as: a.id, kind: a.kind, card: a.card ?? null, height: a.rig.heightM ?? null, keep: a.rig.keep ?? null, verbs: a.rig.verbs ?? [], lib, index });
+        fetched += 1; baked += 1;
+      } catch (error) { missing.push({ asset: a.id, item: a.from.item, why: error.message }); }
+    }
+  }
+  return { fetched, missing, from: lib.base, ...(baked ? { characters: baked } : {}) };
 }
 
 /**

package/lib/style-board.mjs

@@ -170,7 +170,9 @@ export async function assetsLineup(root, id, { log = () => {} } = {}) {
     // `inGame`: what the game's code does to it at runtime (drawn at another height, repainted from style.json): the
     // lineup draws it the same way (the repaint as the board's re-tint, the nearest the game's own swap can be shown).
     const scale = a.inGame?.heightM && a.measured?.heightM ? a.inGame.heightM / a.measured.heightM : null;
-    models.push({ a, input: modelIn(a.id, readFileSync(abs), { label: a.card ? String(a.card).split('/').pop() : a.id, ...(scale ? { scale } : {}), ...(a.inGame?.tint ? { tint: lightColours({ sky: a.inGame.tint, ground: a.inGame.tint }, tokens.palette).sky } : a.inGame?.repaint ? { retint: true } : Number(a.inGame?.pull) > 0 ? { pull: Number(a.inGame.pull) } : {}) }), abs });
+    // A character stands in its idle pose from its skeleton's clip library (not its bind pose: arms out in a T).
+    const anims = a.rig?.anims && existsSync(join(root, 'games', id, a.rig.anims)) ? readFileSync(join(root, 'games', id, a.rig.anims)).toString('base64') : null;
+    models.push({ a, input: modelIn(a.id, readFileSync(abs), { label: a.card ? String(a.card).split('/').pop() : a.id, ...(scale ? { scale } : {}), ...(anims ? { anims, pose: 'idle', poseAt: 0.3 } : {}), ...(a.inGame?.tint ? { tint: lightColours({ sky: a.inGame.tint, ground: a.inGame.tint }, tokens.palette).sky } : a.inGame?.repaint ? { retint: true } : Number(a.inGame?.pull) > 0 ? { pull: Number(a.inGame.pull) } : {}) }), abs });
   }
   if (!models.length) return { ok: false, command: 'assets lineup', id, why: `games/${id} has no recorded models yet (assets add, or the models skill)` };
   const dir = join(root, '.studio', 'art', id);

package/lib/template-history.json

@@ -1195,6 +1195,84 @@
      }
     }
    }
+  },
+  "0.25.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "abf2f0d59341512d",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "aaea65236db52126",
+     "## Running live games (the back office)": "4aa5f513a7cd2c3b",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "b04b0a2b25f524f2",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "7e8458adc1b81ece",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
+  },
+  "0.26.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "abf2f0d59341512d",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "aaea65236db52126",
+     "## Running live games (the back office)": "4aa5f513a7cd2c3b",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "b04b0a2b25f524f2",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "7e8458adc1b81ece",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
   }
  }
 }

package/mcp/ui/animation.js

@@ -0,0 +1,56 @@
+/* The animation card: each character's clips against the verbs the game needs, every one a small looping preview drawn
+ * by the game engine under the game's light (anim_preview), where it came from (its own, or the CC0 library's clips
+ * retargeted onto its skeleton), the verbs it lacks with Add (anim_add: free, baked into its skeleton's clip library),
+ * and Feel: the Game Lab on the move that plays it (game_lab with its take), New beside Today. */
+(function () {
+  var C = Card;
+  var state = { busy: null };
+  function tile(r, c, sc) {
+    var t = C.el('div', 'clip' + (c.have ? '' : ' missing'));
+    var art = C.el('div', 'art');
+    var src = r.previews && r.previews[c.verb];
+    var i = src ? C.img(src, r.id + ' ' + c.verb) : null;
+    if (i) art.appendChild(i); else art.appendChild(C.el('span', '', c.have ? '…' : '+'));
+    t.appendChild(art);
+    t.appendChild(C.el('b', '', c.verb + (c.loop ? ' ↻' : '')));
+    t.appendChild(C.el('span', '', c.have ? (c.source ? c.source + (c.retargeted ? ' · retargeted' : '') : 'its own') : 'missing'));
+    if (!c.have) t.appendChild(C.btn(state.busy === r.id + c.verb ? 'Adding…' : 'Add (free)', 'small', function () {
+      state.busy = r.id + c.verb; C.render();
+      C.call('anim_add', { game: sc.game, asset: r.id, verbs: [c.verb] }).then(function (res) { state.busy = null; C.tell('clip:' + r.id + c.verb, 'The person added the ' + c.verb + ' clip to ' + r.id + ' on the animation card (free, retargeted onto its skeleton).'); C.take(res); }).catch(function () { state.busy = null; C.render(); });
+    }));
+    var take = sc.feel && sc.feel[c.verb];
+    if (c.have && take) t.appendChild(C.btn('Feel', 'ghost small', function () {
+      state.busy = 'Opening the Game Lab on “' + take + '”…'; C.render();
+      C.tell('feel:' + c.verb, 'The person pressed Feel on ' + r.id + '\'s ' + c.verb + ' clip: the Game Lab opens on the "' + take + '" take, New beside Today; its Motion sliders (fade, actSpeed, jumpStretch, landSquash, lean, ...) tune how it feels.');
+      C.call('game_lab', { game: sc.game, take: take }).then(function (res) { state.busy = null; C.take(res); }).catch(function () { state.busy = 'The Game Lab did not start.'; C.render(); });
+    }));
+    return t;
+  }
+  function render(sc) {
+    var card = C.el('main', 'card');
+    var rows = sc.rows || [];
+    var missing = rows.reduce(function (n, r) { return n + (r.missing || []).length; }, 0);
+    C.add(card, C.top('Clips', C.add(C.el('div', 'actions'), C.pill(missing ? missing + ' missing' : 'All there', missing ? 'warn' : 'ok'), C.fullscreenButton())),
+      C.el('h1', '', 'How the characters of ' + sc.game + ' move'),
+      C.el('p', 'sub', 'The game needs ' + (sc.verbs || []).join(', ') + '. Clips are baked into one library per skeleton at build time; every character on that skeleton shares it.'));
+    if (state.busy && !/^[a-z0-9-]+[a-z]+$/.test(state.busy)) card.appendChild(C.el('p', 'note', state.busy));
+    rows.forEach(function (r) {
+      var sec = C.el('section', 'chars');
+      sec.appendChild(C.add(C.el('div', 'dirhead'), C.el('b', '', r.id), C.el('span', '', r.familyLabel + ' · ' + r.bones + ' bones' + (r.animsKB ? ' · clips ' + r.animsKB + ' KB' : '') + ' · ' + r.route)));
+      if (r.shown) {
+        var grid = C.el('div', 'clips');
+        (r.clips || []).forEach(function (c) { grid.appendChild(tile(r, c, sc)); });
+        (r.extra || []).forEach(function (v) { grid.appendChild(tile(r, { verb: v, have: true, loop: false, source: null }, sc)); });
+        sec.appendChild(grid);
+        if (!r.previewed) sec.appendChild(C.btn(state.busy === 'draw' + r.id ? 'Drawing…' : 'Draw its clips (free)', 'ghost small', function () { state.busy = 'draw' + r.id; C.render(); C.call('anim_preview', { game: sc.game, asset: r.id }).then(function (res) { state.busy = null; C.take(res); }).catch(function () { state.busy = null; C.render(); }); }));
+      } else sec.appendChild(C.btn('Show its clips', 'ghost small', function () { C.call('anim_plan', { game: sc.game, asset: r.id }).then(C.take).catch(C.render); }));
+      card.appendChild(sec);
+    });
+    (sc.unrigged || []).forEach(function (u) { card.appendChild(C.el('p', 'fine', u + ' has no rig: a still model (the animate guide says how to rig one).')); });
+    var foot = C.el('div', 'foot');
+    foot.appendChild(C.el('span', 'when', Object.keys(sc.feel || {}).length ? 'Feel opens the Game Lab on this computer' : 'No Game Lab take yet: the lab guide adds one'));
+    card.appendChild(foot);
+    return card;
+  }
+  C.start({ kind: 'animation', label: 'Clips', fullscreen: true, render: render, poll: null });
+})();

package/mcp/ui/card.css

@@ -88,3 +88,7 @@ input[type=text]{flex:1;min-width:0;font:14px/1.2 var(--f-sans);padding:8px 10px
 .budget .track{height:8px;border-radius:4px;background:var(--c-bg3);overflow:hidden}.budget .track i{display:block;height:100%;background:var(--c-ok)}.budget .track i.over{background:var(--c-bad)}
 details summary{cursor:pointer;color:var(--c-fg2);font-size:13px;margin-top:10px}
 @media (max-width:420px){.card{padding:14px 12px 12px;border-radius:var(--r-md)}h1{font-size:18px}.stages{grid-auto-flow:row;grid-auto-columns:auto}.frame{height:520px}}
+.chars{margin:12px 0 0;padding:10px;border-radius:var(--r-md);background:var(--c-bg2)}.chars .dirhead{margin-bottom:8px}
+.clips{display:grid;grid-template-columns:repeat(auto-fill,minmax(104px,1fr));gap:8px}
+.clip{display:grid;gap:3px;align-content:start;padding:6px;border-radius:var(--r-sm);background:var(--c-bg)}.clip .art{aspect-ratio:1;border-radius:var(--r-sm);background:var(--c-bg3);display:grid;place-items:center;overflow:hidden;color:var(--c-fg3);font-size:20px}.clip .art img{width:100%;height:100%;object-fit:cover}
+.clip b{font-size:13px}.clip span{font-size:11.5px;color:var(--c-fg2);overflow-wrap:anywhere}.clip.missing{opacity:.8;box-shadow:inset 0 0 0 1px var(--c-line2)}.clip button{justify-self:start}

package/mcp/ui/cast.js

@@ -48,12 +48,46 @@
     card.appendChild(grid);
     card.appendChild(C.el('p', 'fine', 'Every item is CC0 (free for any use, no credit required), already phone-sized. Adding one copies it into the game: it never loads from anywhere else.'));
   }
+  // The characters: the decisions that shape them, then each one made or planned, with its skeleton and clips.
+  function characters(card, sc) {
+    var d = sc.decisions || {};
+    var facts = C.el('ul', 'list decisions');
+    [['style.proportions', 'Proportions'], ['style.shape', 'Shape and silhouette'], ['cast.family', 'Library family'], ['rig.skeleton', 'Skeleton'], ['rig.source', 'Rigs from'], ['rig.bones', 'Bones']].forEach(function (k) {
+      var v = d[k[0]]; if (!v) return;
+      var li = C.el('li', v.state === 'locked' ? 'locked' : '');
+      li.appendChild(C.add(C.el('div', 'cb'), C.el('b', '', k[1] + ': ' + v.label), C.el('span', '', v.why || '')));
+      li.appendChild(C.pill(v.state, v.state === 'locked' ? 'ok' : ''));
+      facts.appendChild(li);
+    });
+    card.appendChild(facts);
+    var chips = C.el('div', 'chips');
+    (sc.palette || []).forEach(function (hex) { var s = C.el('span', 'swatch'); s.style.background = hex; s.title = hex; chips.appendChild(s); });
+    card.appendChild(C.add(C.el('p', 'fine', 'Palette and silhouette rule: ' + (sc.silhouette || '') + ' '), chips));
+    var list = C.el('ul', 'list cast');
+    (sc.rows || []).forEach(function (r) {
+      var li = C.el('li', r.state === 'made' ? 'done' : 'todo');
+      li.appendChild(thumb(r.thumb, r.id));
+      li.appendChild(C.add(C.el('div', 'cb'), C.el('b', '', r.id + (r.card ? ' · ' + r.card : '')), C.el('span', '', r.state === 'made' ? r.kind + ' · ' + (r.route === 'generated' ? 'generated (US$' + r.usd + ')' : r.route + (r.source ? ': ' + r.source : '')) + ' · ' + r.family + ' skeleton, ' + r.bones + ' bones · ' + r.tris + ' triangles · ' + r.heightM + ' m' : r.kind + ' · planned, ' + (r.heightM ? r.heightM + ' m' : 'no model yet')), r.verbs && r.verbs.length ? C.el('span', '', 'Clips: ' + r.verbs.join(', ')) : null));
+      var side = C.el('div', 'actions');
+      if (r.state === 'made') side.appendChild(C.btn('Clips', 'ghost small', function () { C.call('anim_plan', { game: sc.game, asset: r.id }).then(C.take).catch(C.render); }));
+      else {
+        side.appendChild(C.btn('Find in the library', 'small', function () { C.call('assets_find', { game: sc.game, query: r.id.replace(/-/g, ' '), kind: r.kind }).then(C.take).catch(C.render); }));
+        side.appendChild(C.btn('Generate', 'ghost small', function () { C.tell('char:' + r.id, 'The person wants ' + r.id + ' (' + (r.card || r.kind) + ') generated as a rigged character: price it with character_make (a dry run, about US$1.44) and ask before paying.'); busy[r.id] = 'Asked your AI to price it'; C.render(); }));
+      }
+      if (busy[r.id]) side.appendChild(C.el('span', 'fine', busy[r.id]));
+      li.appendChild(side);
+      list.appendChild(li);
+    });
+    card.appendChild(list);
+    card.appendChild(C.el('p', 'fine', 'Library characters are free (CC0); a generated one is about US$1.44 on your own fal account, priced and asked for first. Spent so far: US$' + (sc.spend ? sc.spend.used.toFixed(2) : '0.00') + '.'));
+  }
   function render(sc) {
     var card = C.el('main', 'card');
-    var title = sc.mode === 'find' ? 'Free models for “' + sc.query + '”' : sc.mode === 'added' ? 'Added ' + (sc.added && sc.added.asset) : 'The cast of ' + sc.game;
-    C.add(card, C.top('Cast', sc.mode === 'plan' ? C.pill((sc.rows || []).filter(function (r) { return r.state === 'made'; }).length + ' of ' + (sc.rows || []).length + ' made', '') : null), C.el('h1', '', title));
+    var title = sc.mode === 'find' ? 'Free models for “' + sc.query + '”' : sc.mode === 'added' ? 'Added ' + (sc.added && sc.added.asset) : sc.mode === 'characters' ? 'The characters of ' + sc.game : 'The cast of ' + sc.game;
+    C.add(card, C.top('Cast', sc.mode === 'characters' ? C.pill((sc.rows || []).filter(function (r) { return r.state === 'made'; }).length + ' made', '') : sc.mode === 'plan' ? C.pill((sc.rows || []).filter(function (r) { return r.state === 'made'; }).length + ' of ' + (sc.rows || []).length + ' made', '') : null), C.el('h1', '', title));
     if (sc.library && sc.library.error) card.appendChild(C.el('p', 'note', 'Starter library: ' + sc.library.error));
     if (sc.mode === 'plan') plan(card, sc);
+    else if (sc.mode === 'characters') characters(card, sc);
     else if (sc.mode === 'find') find(card, sc);
     else if (sc.added) card.appendChild(C.el('p', 'sub', sc.added.asset + ' is in games/' + sc.game + (sc.added.after ? ': ' + sc.added.after.tris + ' triangles, ' + sc.added.after.kb + ' KB' : '') + '. Licence: ' + (sc.added.license || 'CC0') + '.'));
     return card;

package/mcp/ui/lineup.js

@@ -37,25 +37,25 @@
       var a = { game: sc.game, asset: sc.asset };
       for (var q in (sc.request || {})) a[q] = sc.request[q];
       for (var k in args) a[k] = args[k];
-      C.call('asset_make', a).then(function (r) { state.busy = null; C.take(r); }).catch(function () { state.busy = 'That did not reach the studio.'; C.render(); });
+      C.call(sc.character ? 'character_make' : 'asset_make', a).then(function (r) { state.busy = null; C.take(r); }).catch(function () { state.busy = 'That did not reach the studio.'; C.render(); });
     };
     if (sc.concept) { var i = C.img(sc.concept, 'The concept for ' + sc.asset); if (i) { i.style.maxHeight = '360px'; i.style.objectFit = 'contain'; card.appendChild(C.add(C.el('div', 'preview'), i)); } }
     if (sc.dryRun) {
-      card.appendChild(C.el('p', 'sub', (sc.step === 'mesh' ? 'The 3D model' : 'The concept image') + ' costs about US$' + (sc.price ? sc.price.usd : '?') + (sc.total ? '; the whole prop about US$' + sc.total : '') + ', on your own fal account.'));
+      card.appendChild(C.el('p', 'sub', (sc.step === 'mesh' ? (sc.character ? 'The rigged character' : 'The 3D model') : 'The concept image') + ' costs about US$' + (sc.price ? sc.price.usd : '?') + (sc.total ? '; the whole ' + (sc.character ? 'character' : 'prop') + ' about US$' + sc.total : '') + ', on your own fal account.'));
       card.appendChild(C.add(C.el('div', 'actions'), C.btn('Make it (US$' + (sc.price ? sc.price.usd : '?') + ')', '', function () { C.tell('approve:' + sc.asset + sc.step, 'The person approved US$' + (sc.price && sc.price.usd) + ' for the ' + sc.step + ' of ' + sc.asset + ' on the card.'); run({ step: sc.step, approve: true }, 'Making it…'); })));
     } else if (sc.needs === 'approval' || sc.why) card.appendChild(C.el('p', 'note', sc.why || 'Needs the person\'s yes.'));
     else if ((sc.step === 'concept' || sc.step === 'look') && sc.concept) {
-      card.appendChild(C.el('p', 'sub', 'Look at it: the thing, whole, in the game\'s style, on a plain background? Then the 3D model (about US$' + (sc.then ? sc.then.usd : '0.50') + ').'));
-      card.appendChild(C.add(C.el('div', 'actions'), C.btn('Make the 3D model', '', function () { C.tell('mesh:' + sc.asset, 'The person approved the 3D model of ' + sc.asset + ' (about US$' + (sc.then ? sc.then.usd : '0.50') + ') on the card.'); run({ step: 'mesh', approve: true }, 'Making the model (1 to 3 minutes)…'); })));
+      card.appendChild(C.el('p', 'sub', sc.character ? 'Look at it: one character, whole, in an A-pose, in the game\'s style, on a plain background? Then the rigged 3D character (about US$' + (sc.then ? sc.then.usd : '1.40') + '); its clips come from the free library.' : 'Look at it: the thing, whole, in the game\'s style, on a plain background? Then the 3D model (about US$' + (sc.then ? sc.then.usd : '0.50') + ').'));
+      card.appendChild(C.add(C.el('div', 'actions'), C.btn(sc.character ? 'Make the rigged character' : 'Make the 3D model', '', function () { C.tell('mesh:' + sc.asset, 'The person approved the ' + (sc.character ? 'rigged character' : '3D model') + ' of ' + sc.asset + ' (about US$' + (sc.then ? sc.then.usd : sc.character ? '1.40' : '0.50') + ') on the card.'); run({ step: 'mesh', approve: true }, sc.character ? 'Making the rigged character (2 to 5 minutes)…' : 'Making the model (1 to 3 minutes)…'); })));
     } else if (sc.step === 'mesh' && sc.after) {
-      card.appendChild(C.el('p', 'note ok', sc.asset + ': ' + sc.before.tris + ' → ' + sc.after.tris + ' triangles, ' + sc.after.kb + ' KB, ' + sc.after.heightM + ' m. Recorded with its receipts and licence.'));
-      card.appendChild(C.add(C.el('div', 'actions'), C.btn('Show the lineup', 'ghost', function () { state.busy = 'Drawing the lineup…'; C.render(); C.call('asset_lineup', { game: sc.game }).then(function (r) { state.busy = null; C.take(r); }); })));
+      card.appendChild(C.el('p', 'note ok', sc.asset + ': ' + sc.before.tris + ' → ' + sc.after.tris + ' triangles, ' + sc.after.kb + ' KB, ' + sc.after.heightM + ' m. Recorded with its receipts and licence.' + (sc.character && sc.verbs && sc.verbs.length ? ' Clips (the library\'s, retargeted, free): ' + sc.verbs.join(', ') + '.' : '')));
+      card.appendChild(C.add(C.el('div', 'actions'), C.btn('Show the lineup', 'ghost', function () { state.busy = 'Drawing the lineup…'; C.render(); C.call('asset_lineup', { game: sc.game }).then(function (r) { state.busy = null; C.take(r); }); }), sc.character ? C.btn('Show its clips', 'ghost', function () { state.busy = 'Drawing its clips…'; C.render(); C.call('anim_preview', { game: sc.game, asset: sc.asset }).then(function (r) { state.busy = null; C.take(r); }); }) : null));
     }
   }
   function render(sc) {
     var card = C.el('main', 'card');
     var flagged = sc.mode === 'lineup' ? sc.flagged : null;
-    C.add(card, C.top(sc.mode === 'make' ? 'Make a prop' : 'Lineup', C.add(C.el('div', 'actions'), flagged !== null && flagged !== undefined ? C.pill(flagged ? flagged + ' flagged' : 'One look', flagged ? 'warn' : 'ok') : null, C.fullscreenButton())),
+    C.add(card, C.top(sc.mode === 'make' ? (sc.character ? 'Make a character' : 'Make a prop') : 'Lineup', C.add(C.el('div', 'actions'), flagged !== null && flagged !== undefined ? C.pill(flagged ? flagged + ' flagged' : 'One look', flagged ? 'warn' : 'ok') : null, C.fullscreenButton())),
       C.el('h1', '', sc.mode === 'make' ? sc.asset : 'The cast of ' + sc.game + ', at true scale'));
     if (state.busy) card.appendChild(C.el('p', 'note', state.busy));
     if (sc.mode === 'make') make(card, sc); else lineup(card, sc);

package/netplay/NETPLAY.md

@@ -583,13 +583,16 @@ Measured, with Gem Rush's bump (owner movement, 30–50 ms one way):
    overrides). `?screen=1` makes a spectator that shows a QR code to the game URL.
    `/<game>/watch?room=` makes a watcher, with a strip of the players (section 16).
 8. **Show room facts** from the watch feed or the frame's messages: the lobby line,
-   results, and with `?debug=1` the debug strip.
+   results, and with `?debug=1` the debug strip. Until the game is playable, show them on
+   the arrival card, in the game's own look (section 21), never a blank screen.
 9. **One matcher:** every Play door for a game lands in the same rooms (the `Lobby`).
 
 ### The game (a vendored `netplay.ts`)
 
 1. **Call `createNetplay({ game, maxPlayers, movement, checkpoint })` once** and render
-   from the first frame. Never wait for `ready`.
+   from the first frame. Never wait for `ready`. A game that loads for seconds after its
+   first state passes `arrival: 'game'` and calls `net.playable()` once its world and the
+   player's own body are drawn (section 21): the play page's arrival card covers the wait.
 2. **Handle `role` at any time.**
    - Promoted: restore (section 9).
    - Host but not promoted: start a fresh round.
@@ -1422,3 +1425,36 @@ account or typed text.
 the host asks how the slimes hunt (chase, surround, gang up on the most hurt, regroup at the King),
 whether a wave comes, and how hard to push; every screen shows what the slimes are up to when a model
 chose it. The floor is the vale as it always played.
+
+## 21. The arrival (0.26.0)
+
+The play page and the big screen never open on a blank screen. From the page's first paint until
+the game says it is playable, an **arrival card** covers the game's frame in the game's own look:
+its title and pitch, its key art (the landing's hero still, a trailer's poster or its cover,
+drifting slowly), a progress line that says what is happening ("Finding a room…", "Room 4 · 3
+playing · 2 AI", "Loading the game…", "Joining Room 4…", the game's own "Loading the heroes…
+60%") and the controls for this device (game.json `landing.controls`). Then it fades and the
+game has the screen. Its colours are the game's palette (style.json), else its landing's, else
+the studio's (`worker/arrival.mjs`). Nothing here crosses the relay: it is between the game's frame
+and its page, so the wire stays revision 8.
+
+| From the helper to its page | When |
+|---|---|
+| `{ what: 'attached', …, arrival: 'auto' \| 'game' }` | the helper starts (a helper older than 0.26.0 sends no `arrival`) |
+| `{ what: 'loading', p, label? }` | the game's `net.loading(p, label)`: 0 to 1, at most ten a second, never after `playable` |
+| `{ what: 'playable', by: 'game' \| 'auto' }` | once: the game's `net.playable()`, or (`arrival: 'auto'`) the helper's own |
+
+- **`arrival: 'auto'`** (the default, so every game gets the card with no code): the helper says
+  `playable` once this browser has its role and the room's state (a host at once, anyone else at
+  its first snapshot), two animation frames later, so the game has drawn with it.
+- **`arrival: 'game'`**: the game says when, with `net.playable()` once its world and the player's
+  own body are drawn (Hero Rush 3D: its own hero with its real model, not the stand-in), and
+  `net.loading(p, 'the heroes')` while it loads. A game whose own loading takes seconds after the
+  first state (models, textures, a baked terrain) uses this, so the player never sees stand-ins.
+- **The page's fallbacks**, so a game is never hidden behind the card: a helper older than 0.26.0
+  lifts it 0.6 s after the browser has a seat; a frame with no helper, 8 s after it loaded; any game,
+  15 s after its helper attached; and 30 s after the page opened, whatever happens. A kick or a
+  closed room lifts it for its notice. `?arrive=0` leaves it out.
+- **Measured** by `homie-studio perf` (`load.look`: the card's first frame, the first meaningful
+  frame; `load.playable`: seated, the body drawn and the card lifted), from the page's own marks
+  `homie:look` and `homie:playable` and `window.__shell.arrival`.

package/netplay/netplay.ts

@@ -50,6 +50,11 @@
  *     them), messages taken down (`on('unchat')`), and the game's own chat UI
  *     (`net.say(text)`, `net.sayLine(id)`, `net.react(kind)`); the room's rules
  *     are `net.chatRules`. The play page's chat panel needs none of it.
+ *   - The arrival (0.26.0, NETPLAY.md section 21): tells its page when the game
+ *     is playable, so the play page's arrival card (the game's title, art and a
+ *     progress line) gives it the screen: by itself once seated with the room's
+ *     state, or the game's own `net.playable()` (`arrival: 'game'`), with
+ *     `net.loading(p, what)` while it loads. Nothing crosses the relay.
  *
  * WHAT IT DOES NOT DO: rendering, physics, input devices, bots. `Roster` below
  * is the bot-yield bookkeeping a host needs; the bots themselves are the game's.
@@ -451,6 +456,14 @@ export interface NetplayOptions<C = unknown> {
    * moves an AI's body with its own bot code (a Roster that passes `p.agent`). Reading the dial declares 'skill' too.
    */
   caps?: ('skill' | 'agents')[];
+  /**
+   * THE ARRIVAL (NETPLAY.md section 21): who says when the play page's arrival card (the game's title, art and a
+   * progress line while the room connects and the game loads) gives the screen to the game. 'auto' (the default): this
+   * helper, once this browser has its role and the room's state (a host at once, anyone else at its first snapshot),
+   * two animation frames later. 'game': the game itself, with `net.playable()` once its world and the player's own body
+   * are drawn (the page lifts the card anyway 12 s after the helper attached, so a game that never says is never hidden).
+   */
+  arrival?: 'auto' | 'game';
 }
 
 type WebSocketCtor = new (url: string) => WebSocketLike;
@@ -609,6 +622,17 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   hushed: boolean;
   /** This browser plays as an AI (the frame of an agent pass). */
   readonly asAgent: boolean;
+  /**
+   * THE ARRIVAL (section 21): the world and the player's own body are drawn, so the play page's arrival card gives the
+   * screen to the game. Once; later calls do nothing. Needed only with `arrival: 'game'` (an 'auto' game may call it
+   * earlier than the helper would).
+   */
+  playable(): void;
+  /**
+   * While it loads: how far along the game is (0 to 1) and what it is loading ("the heroes"), for the arrival card's
+   * progress line. At most ten a second reach the page; nothing after `playable()`.
+   */
+  loading(fraction: number, what?: string): void;
   /** Resolves with the first role (welcome, or offline fallback). */
   readonly ready: Promise<RoleChange<S, C>>;
   on<K extends keyof NetHandlers<S, A, C>>(kind: K, fn: NetHandlers<S, A, C>[K]): () => void;
@@ -1110,6 +1134,26 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let idleSkipped = 0;
   /** Why this client stopped for good (a FINAL_ERRORS refusal), or null while it plays or reconnects. */
   let closedWhy: string | null = null;
+  // The arrival (section 21): the play page's card lifts at `playable` (the game's word, or this helper's).
+  const arrival: 'auto' | 'game' = opts.arrival === 'game' ? 'game' : 'auto';
+  let playableSent = false;
+  let autoArmed = false;
+  let snapSeen = false;
+  let loadingAt = 0;
+  function sayPlayable(by: 'game' | 'auto'): void {
+    if (playableSent) return;
+    playableSent = true;
+    post?.({ what: 'playable', by });
+  }
+  /** 'auto': a host at once, anyone else at its first snapshot, then two animation frames (the game drew with it). */
+  function autoPlayable(): void {
+    if (arrival !== 'auto' || playableSent || autoArmed || !roleKnown) return;
+    if (role !== 'host' && !snapSeen) return;
+    autoArmed = true;
+    const raf = (globalThis as { requestAnimationFrame?: (cb: () => void) => number }).requestAnimationFrame;
+    const later = (fn: () => void): void => { if (typeof raf === 'function') raf(fn); else setTimeout(fn, 16); };
+    later(() => later(() => sayPlayable('auto')));
+  }
   /** The studio's announcement now showing, and the seats the studio muted (until when, server ms). */
   let announcement: Announcement | null = null;
   const muted = new Map<number, number>();
@@ -1354,6 +1398,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     emit('role', e);
     resolveView('seat');
     notifyStats(true);
+    autoPlayable();
   }
 
   /** The newest snapshot this browser holds, if recent: a promoted host's restore when the relay has none. */
@@ -1584,7 +1629,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       replaceState(m['state']);
     }
     rebase = true;
-    if (snap && next !== 'host') acceptSnap(snap, JSON.stringify(snap).length, false);
+    // The relay's last snapshot comes with the welcome: the room's state is in (the arrival, section 21).
+    if (snap && next !== 'host' && acceptSnap(snap, JSON.stringify(snap).length, false)) snapSeen = true;
     if (next === 'host' && !snap && !continuing) snap = localSnap();
     offline = false;
     connected = true;
@@ -1685,7 +1731,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (role === 'host') return; // a stale frame from a previous host
     const s: Snapshot<S> = { k: Number(m['k']) || 0, st: Number(m['st']), d: m['d'] as S, from: typeof m['from'] === 'number' ? m['from'] : null };
     if (Array.isArray(m['c'])) s.c = m['c'] as ControlWire[];
-    if (acceptSnap(s, bytes, true)) emit('snapshot', s);
+    if (acceptSnap(s, bytes, true)) { emit('snapshot', s); if (!snapSeen) { snapSeen = true; autoPlayable(); } }
   }
 
   function onInput(m: Record<string, unknown>): void {
@@ -1877,7 +1923,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     // No shell (a plain file, a dev server): the game is its own host, offline.
     queueMicrotask(() => goOfflineHost('offline'));
   } else {
-    post?.({ what: 'attached', v: NETPLAY_VERSION, rev: NETPLAY_REVISION, mark: NETPLAY_MARK });
+    post?.({ what: 'attached', v: NETPLAY_VERSION, rev: NETPLAY_REVISION, mark: NETPLAY_MARK, arrival });
     open();
     // A relay that never answers must not leave a game on a black screen. But the wait is counted only while
     // this page is able to listen: a phone compiling shaders under load is blocked for seconds at a time, and
@@ -2050,6 +2096,15 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     get announcement() { return announcement && (announcement.until === undefined || announcement.until > now()) ? announcement : null; },
     isMuted(s: number | null): boolean { return s !== null && (muted.get(s) ?? 0) > now(); },
     pickPlayer(s: number | null): void { post?.({ what: 'pick', seat: typeof s === 'number' ? s : null }); },
+    playable(): void { sayPlayable('game'); },
+    loading(fraction: number, what?: string): void {
+      if (playableSent) return;
+      const t = wall();
+      const p = Math.max(0, Math.min(1, Number(fraction) || 0));
+      if (t - loadingAt < 100 && p < 1) return;
+      loadingAt = t;
+      post?.({ what: 'loading', p: Math.round(p * 100) / 100, ...(typeof what === 'string' && what ? { label: what.slice(0, 40) } : {}) });
+    },
     get watching() { return watching; },
     get viewSeat() { markFollows(); return watching ? viewNow : (offline ? null : seat); },
     get following() { return watching ? following : seat; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.24.5",
+  "version": "0.26.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -46,6 +46,10 @@
       "types": "./assets/assets.ts",
       "default": "./assets/assets.ts"
     },
+    "./animate": {
+      "types": "./assets/animate.ts",
+      "default": "./assets/animate.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },

package/site/SITE.md

@@ -47,7 +47,13 @@ site's pages only); the owner's tools are `/_studio/api/chat`, `/_studio/api/cha
 Made from the game's own files, nothing invented:
 
 - **The hero**, full-bleed: the game's footage when it has some, else its cover (or key art) moving slowly, tinted
-  with the studio's colour so the words read. A game whose picture is white or cream (a light arena) takes
+  with the studio's colour so the words read. **In the game's own palette (0.26.0):** a game with a style.json (its
+  art direction) and no `landing.scheme` or `landing.theme` of its own gets its whole landing in that palette, its
+  paper as the page, its ink as the words, its accents, light or dark as its paper is, when the ink reads on the paper
+  (4.5:1); its footage then keeps its colour (a third of the tint) and the words sit on a soft panel of its paper. A
+  bright game is no longer shown on the studio's dark page. `landing.scheme`, `landing.theme`, a `site/pages/<id>/`
+  page and `site/theme.css` are the owner's and always win; a palette whose ink does not read keeps its accents only,
+  on the studio's scheme, as before. A game whose picture is white or cream (a light arena) takes
   `"scheme": "light"` in its `landing` block: its landing is drawn light, the hero tinted and shaded with a light
   background and the words dark, where a dark studio's tint would turn it grey (`"dark"` is the other way round,
   for a dark game in a light studio). `landing.theme` colours still win, and the rest of the site keeps its look. Footage is looked for in this order: `landing.hero` in game.json;
@@ -143,6 +149,18 @@ A studio with its own landing in `site/` keeps it: the template never replaces w
 
 ## The play page
 
+**The arrival (0.26.0).** The play page and the big screen never open blank. From the first paint, an arrival
+card covers the game's frame in the game's own look (worker/arrival.mjs): its title, its pitch (`landing.pitch`, else
+the blurb's first sentence), its key art (the landing's hero still, a trailer's poster or its cover, drifting slowly;
+`landing.hero.tallImage` on an upright phone when there is one), a progress line that says what is happening
+("Finding a room…", "Room 4 · 3 playing · 2 AI", "Loading the game…", "Joining Room 4…", and the game's own
+"Loading the heroes… 60%"), and the controls for this device (`landing.controls.phone`, `.computer`, `.tv`). Its
+colours are the game's palette (style.json), else the landing's (`landing.theme`, `landing.scheme`), else the
+studio's. It lifts when the game says it is playable (NETPLAY.md section 21): by itself once seated with the room's
+state, or at the game's own `net.playable()`; a game built before 0.26.0 lifts it once it has a seat, and nothing
+keeps a game behind it longer than 15 s after the game started (30 s after the page opened). `?arrive=0` leaves it
+out. `homie-studio perf` reads its first frame as the time to the first meaningful frame (`load.look`).
+
 `/<id>/play` puts the visitor in a public room at once and writes the room into the address, so a reload comes
 back to it and a copied address brings a friend into it. A small room button at the edge (top right by default)
 opens: **Invite** (the phone's share sheet, or the link copied), **Big screen** (`/<id>/tv` of this room, on

package/starters/gem-rush/game.json

@@ -5,5 +5,6 @@
   "players": { "min": 1, "max": 8 },
   "roundSeconds": 60,
   "entry": "src/main.ts",
-  "netplay": { "v": 1, "public": true, "movement": "owner" }
+  "netplay": { "v": 1, "public": true, "movement": "owner" },
+  "landing": { "pitch": "Grab the gems. Bump your rivals away.", "controls": { "phone": "Drag to move; a second finger bumps.", "computer": "WASD or arrows to move, Space to bump." } }
 }

package/starters/gem-rush-3d/game.json

@@ -7,5 +7,6 @@
   "entry": "src/main.ts",
   "netplay": { "v": 1, "public": true, "movement": "owner" },
   "needs": { "three": "0.185.1" },
-  "assets": "library"
+  "assets": "library",
+  "landing": { "pitch": "Grab the gems. Bump your rivals away.", "controls": { "phone": "Drag to move; a second finger bumps.", "computer": "WASD or arrows to move, Space to bump." } }
 }