@homie-rocks/studio 0.35.1 → 0.37.0

package/lib/art-tools.mjs

@@ -36,7 +36,7 @@ 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';
-import { listGames } from './studio.mjs';
+import { experienceDir, experienceFile, listExperiences as listGames } from './studio.mjs';
 
 export const ART_UI = Object.freeze({
   style: 'ui://homie-studio/style',
@@ -55,7 +55,7 @@ function picture(h, file, max = 160 * 1024) {
 
 function gameOf(root, id) {
   const games = listGames(root);
-  if (id && (games.some((g) => g.id === id) || existsSync(join(root, 'games', String(id), 'CODEX.md')))) return String(id);
+  if (id && (games.some((g) => g.id === id) || existsSync(join(experienceDir(root, String(id)), 'CODEX.md')))) return String(id);
   if (!id && games.length === 1) return games[0].id;
   throw new Error(`which game? ${games.map((g) => g.id).join(', ') || 'there is none yet (game_plan or game_make first)'}`);
 }
@@ -64,11 +64,11 @@ function gameOf(root, id) {
 function styleData(h, root, game, extra = {}) {
   const doc = readDecisions(root, game);
   let title = null;
-  try { title = JSON.parse(readFileSync(join(root, 'games', game, 'game.json'), 'utf8')).name ?? null; } catch { /* planned: its codex names it */ }
-  if (!title) { try { title = /^#\s+(.+)$/m.exec(readFileSync(join(root, 'games', game, 'CODEX.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''))?.[1]?.trim() ?? null; } catch { title = null; } }
+  try { title = JSON.parse(readFileSync(experienceFile(root, game), 'utf8')).name ?? null; } catch { /* planned: its codex names it */ }
+  if (!title) { try { title = /^#\s+(.+)$/m.exec(readFileSync(join(experienceDir(root, game), 'CODEX.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''))?.[1]?.trim() ?? null; } catch { title = null; } }
   title = title ?? game;
   const manifest = readManifest(root, game);
-  const dirs = doc ? boardView(root, game, doc).map((d) => ({ ...d, swatch: picture(h, d.swatch ? join(root, 'games', game, d.swatch) : null), mood: d.mood?.path ? { image: picture(h, join(root, 'games', game, d.mood.path)), usd: d.mood.usd ?? null, label: 'a painted target, not what the game draws' } : null })) : [];
+  const dirs = doc ? boardView(root, game, doc).map((d) => ({ ...d, swatch: picture(h, d.swatch ? join(experienceDir(root, game), d.swatch) : null), mood: d.mood?.path ? { image: picture(h, join(experienceDir(root, game), d.mood.path)), usd: d.mood.usd ?? null, label: 'a painted target, not what the game draws' } : null })) : [];
   const rows = doc ? decisionRows(doc) : [];
   return {
     kind: 'style', game, title, path: doc?.path ?? null, line: doc ? oneLine(doc) : null, budget: doc?.budget?.usd ?? null, chosen: doc?.board?.chosen ?? null,
@@ -98,7 +98,7 @@ async function characterThumb(h, root, game, row) {
     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;
+  return concept ? picture(h, join(experienceDir(root, 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. */

package/lib/asset-check.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * `homie-studio assets check <id>`: static, free, on every asset and on the whole game. What it adds up is an
  * INVENTORY ESTIMATE: the recorded files' own triangles, draw calls and pictures times their declared placements. It
@@ -74,7 +75,7 @@ const tierOf = (a) => (a.kind === 'clip' ? 'clip' : BUDGETS[a.tier] ? a.tier : a
 
 /** A game's game.json, or {} (a planned game has none yet). */
 export function gameJson(root, id) {
-  try { return JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')) ?? {}; } catch { return {}; }
+  try { return JSON.parse(readFileSync(experienceFile(root, id), 'utf8')) ?? {}; } catch { return {}; }
 }
 
 /*
@@ -238,7 +239,7 @@ export async function assetsCheck(root, id, { validate = true, write = true } =
   const doc = readDecisions(root, id);
   const game = gameJson(root, id);
   const budgets = budgetsFor(doc, game);
-  const gdir = join(root, 'games', id);
+  const gdir = experienceDir(root, id);
   let tools = null;
   try { tools = await import('./optimise.mjs'); } catch { tools = null; }
   const rows = [];

package/lib/asset-import.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * A MODEL FILE INTO A GAME: the person's own (imported), or one a provider generated on their account (the models
  * skill's image-to-3D). `homie-studio assets add <id> --file <model> --license <kind>`.
@@ -54,7 +55,7 @@ export function screenImport(path) {
  * the concept and mesh calls with their receipts and prices), slug (the art job's folder).
  */
 export async function importModel(root, id, file, opts = {}) {
-  const gdir = join(root, 'games', id);
+  const gdir = experienceDir(root, id);
   if (!existsSync(join(gdir, 'game.json')) && !existsSync(join(gdir, 'CODEX.md'))) throw new Error(`no game "${id}"`);
   const path = resolve(root, file);
   const route = opts.route === 'generated' ? 'generated' : 'imported';
@@ -117,7 +118,7 @@ export async function importModel(root, id, file, opts = {}) {
  * mesh fix it); one stale only on its budgets is not.
  */
 export async function redoModel(root, id, assetId) {
-  const gdir = join(root, 'games', id);
+  const gdir = experienceDir(root, id);
   const e = readManifest(root, id).assets.find((a) => a.id === assetId);
   if (!e) throw new Error(`no asset "${assetId}" in games/${id}/assets/manifest.json`);
   const raw = (e.files ?? []).find((f) => f.role === 'raw');

package/lib/asset-manifest.mjs

@@ -22,7 +22,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { pinByUse, readDecisions, revisionsFor } from './decisions.mjs';
-import { GAME_ID } from './studio.mjs';
+import { experienceDir, experienceFile, GAME_ID } from './studio.mjs';
 
 export const MANIFEST_FILE = join('assets', 'manifest.json');
 export const RIGHTS_FILE = join('assets', 'RIGHTS.md');
@@ -81,7 +81,7 @@ export function underFor(kind, route) {
   return [...(UNDER[kind] ?? UNDER.prop), ...(route === 'library' ? ['cast.family'] : []), ...(route === 'generated' ? ['derived.prompt'] : [])];
 }
 
-const fileOf = (root, id) => join(root, 'games', id, MANIFEST_FILE);
+const fileOf = (root, id) => join(experienceDir(root, id), MANIFEST_FILE);
 const now = () => new Date().toISOString();
 const clean = (s, n = 300) => (typeof s === 'string' ? s.replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, n) : null);
 
@@ -167,7 +167,7 @@ export function removeAsset(root, id, assetId) {
   writeManifest(root, id, manifest);
   writeRights(root, id, manifest);
   syncCredits(root, id, manifest);
-  const gdir = join(root, 'games', id);
+  const gdir = join(experienceDir(root, id));
   const named = new Set(manifest.assets.flatMap((a) => (a.files ?? []).map((f) => f.path)));
   const deleted = []; const kept = [];
   for (const f of gone.files ?? []) {
@@ -216,7 +216,7 @@ export function licenceProblems(root, id, manifest = readManifest(root, id)) {
 
 /** Model files a game ships (.glb, .gltf, .fbx, .obj, .vrm under games/<id>/) that no manifest entry names. */
 export function unrecordedModels(root, id, manifest = readManifest(root, id)) {
-  const dir = join(root, 'games', id);
+  const dir = join(experienceDir(root, id));
   const named = new Set(manifest.assets.flatMap((a) => (a.files ?? []).map((f) => f.path)));
   const out = [];
   const walk = (rel, depth) => {
@@ -245,7 +245,7 @@ const PICTURE = /\.(png|jpe?g|webp|avif|gif|hdr|exr|ktx2)$/i;
  * The codex (private, the style board's own swatches) is not walked at all.
  */
 export function unrecordedPictures(root, id, manifest = readManifest(root, id), { cover = null } = {}) {
-  const dir = join(root, 'games', id);
+  const dir = join(experienceDir(root, id));
   const named = new Set(manifest.assets.flatMap((a) => (a.files ?? []).map((f) => f.path)));
   const coverPaths = new Set(cover ? [String(cover).replace(/^\.\//, ''), `public/${String(cover).replace(/^\.\//, '')}`] : []);
   const shipped = []; const notShipped = [];
@@ -296,7 +296,7 @@ function routeWords(a) {
 /** RIGHTS.md for one game, in plain words. */
 export function rightsMarkdown(root, id, manifest = readManifest(root, id)) {
   let game = {};
-  try { game = JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')); } catch { game = {}; }
+  try { game = JSON.parse(readFileSync(experienceFile(root, id), 'utf8')); } catch { game = {}; }
   const lines = [
     `# Rights: ${game.name ?? id}`,
     '',
@@ -333,7 +333,7 @@ function termsApply(t, a) {
 }
 
 export function writeRights(root, id, manifest = readManifest(root, id)) {
-  const file = join(root, 'games', id, RIGHTS_FILE);
+  const file = join(experienceDir(root, id), RIGHTS_FILE);
   mkdirSync(dirname(file), { recursive: true });
   const text = rightsMarkdown(root, id, manifest);
   if (!existsSync(file) || readFileSync(file, 'utf8') !== text) writeFileSync(file, text);
@@ -347,7 +347,7 @@ export function writeRights(root, id, manifest = readManifest(root, id)) {
  * and one per attribution-required file. Lines this function wrote carry `"asset": true`; every other part stays.
  */
 export function syncCredits(root, id, manifest = readManifest(root, id)) {
-  const file = join(root, 'games', id, 'credits.json');
+  const file = join(experienceDir(root, id), 'credits.json');
   let credits = {};
   try { credits = JSON.parse(readFileSync(file, 'utf8')); } catch { credits = {}; }
   const before = Array.isArray(credits.parts) ? credits.parts : [];

package/lib/build.mjs

@@ -1,3 +1,4 @@
+import { appProblems } from '../worker/app-format.mjs';
 /**
  * `homie-studio build` — every game in games/ bundled into site/dist, plus the
  * catalogue the Worker serves (games.json).
@@ -55,7 +56,7 @@ import { buildMedia } from './media.mjs';
 import { buildSiteFiles, isoDate, landingOf, readPosts, readTheme } from './site.mjs';
 import { checkJsonLd } from './schema-check.mjs';
 import { SCHEMA_REFUSED } from '../worker/schema.mjs';
-import { PACKAGE_ROOT, isRulesGame, listGames, readStudio } from './studio.mjs';
+import { PACKAGE_ROOT, isRulesGame, listExperiences as listGames, readStudio } from './studio.mjs';
 
 // The rules build brings a JavaScript parser with it. It is loaded when a build first needs it, never when this
 // module is: Homie for Claude Desktop starts the toolkit with no node_modules beside it (scripts/desktop.mjs).
@@ -75,10 +76,10 @@ import { audienceOf } from '../worker/shop-rules.mjs';
 import { loungeConfig, loungeProblems } from '../worker/lounge-store.mjs';
 // GAME PARTS (parts/PARTS.md): the three call-outs below are all the build knows of them.
 import { buildParts, partsPlugin } from './parts-build.mjs';
-// RULES ON THE SERVER (NETPLAY.md section 29): a game with a src/rules.ts is built as a view bundle plus a rules module.
+// RULES ON THE SERVER (NETPLAY.md section 29): a game declaring a room object and src/rules.ts builds as a view bundle plus a rules module.
 
 /** Never copied into a static game's served folder. */
-const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md', 'lab.json', 'codex']);
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'app.json', 'PORT.md', 'CODEX.md', 'lab.json', 'codex']);
 const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
 
 /** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
@@ -269,7 +270,7 @@ export function netplayOf(g, out = null) {
  */
 export function seatsFor(g, net = netplayOf(g)) {
   const named = [net.maxPlayers, net.players?.max, g.players?.max].map((n) => Math.floor(Number(n))).find((n) => Number.isFinite(n) && n >= 1);
-  const asked = named ?? 8;
+  const asked = named ?? (g.kind === 'app' ? 32 : 8);
   const max = Math.min(SEAT_MAX, asked);
   const minNamed = [net.minPlayers, net.players?.min, g.players?.min].map((n) => Math.floor(Number(n))).find((n) => Number.isFinite(n) && n >= 1);
   return { min: Math.min(max, minNamed ?? 1), max, asked };
@@ -376,7 +377,7 @@ function pointAtBundle(html, bundle) {
  * game is served (/games/<id>/ on the site, /<id>/__game/ in its frame, the lab). A game with no dynamic import is
  * one file, as before. `hashed` (the site's build) names the bundle by its content too: see the top of this file.
  */
-export async function buildGameFiles(esbuild, root, g, out, { maps = false, sourcemap = null, cache = {}, log = () => {}, hashed = false } = {}) {
+export async function buildGameFiles(esbuild, root, g, out, { maps = false, sourcemap = null, cache = {}, log = () => {}, hashed = false, lab = false, longCheck = false } = {}) {
   rmSync(out, { recursive: true, force: true });
   mkdirSync(join(out, 'assets'), { recursive: true });
   const mode = g.build?.mode ?? 'bundle';
@@ -394,7 +395,7 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
   }
   if (ruled && mode !== 'bundle') throw new Error(`games/${g.id} has a src/rules.ts and game.json "build": { "mode": "${mode}" }. A game written as rules plus view is built by Homie itself: take the "build" setting out.`);
   const { prepareRules, viewPlugin } = ruled ? await rulesBuild() : {};
-  const rules = ruled ? await prepareRules(esbuild, root, g, { log }) : null;
+  const rules = ruled ? await prepareRules(esbuild, root, g, { log, longCheck }) : null;
   const bundle = async (entryRel) => {
     const entry = join(g.dir, entryRel);
     if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
@@ -406,7 +407,7 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
       // game.json assets.budgets, read by createModels() (assets/assets.ts): a constant in the bundle, never a fetch.
       define: { __HOMIE_MODEL_BUDGETS__: JSON.stringify(budgets ?? {}) },
       // GAME PARTS: `@parts/<host>/<id>` and `@parts/<id>` resolve to the part's entry, and the game is credited.
-      plugins: [partsPlugin(root, g.id), ...(rules ? [viewPlugin(g, rules, entry)] : [])],
+      plugins: [partsPlugin(root, g.id), ...(rules ? [viewPlugin(g, rules, entry, { lab })] : [])],
     };
     const failed = (error) => {
       const first = error.errors?.[0];
@@ -416,7 +417,7 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
     warnings += result.warnings.length;
     metafile = result.metafile;
     const outputs = Object.entries(result.metafile.outputs).filter(([k]) => k.endsWith('.js'));
-    const main = outputs.find(([, v]) => v.entryPoint)?.[0];
+    const main = outputs.find(([, v]) => rules ? v.entryPoint === 'homie-view:homie:view' : Boolean(v.entryPoint))?.[0];
     if (!main) throw new Error(`games/${g.id} did not build: esbuild wrote no bundle for ${entryRel}`);
     bundled = `assets/${basename(main)}`;
     chunks = outputs.filter(([k]) => k !== main).map(([k]) => `assets/${basename(k)}`).sort();
@@ -466,6 +467,7 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
     for (const file of [bundled, ...chunks].filter(Boolean)) digest.update(readFileSync(join(out, file)));
     digest.update(readFileSync(join(out, 'index.html')));
     rules.build = digest.digest('hex').slice(0, 32);
+    writeFileSync(join(out, 'rules.json'), `${JSON.stringify({ v: 1, host: rules.settings.host, offline: rules.settings.offline, build: rules.build, files: [bundled, ...chunks] })}\n`);
     if (g.netplay?.version !== undefined) log(`  ${g.id}: rules games use their build hash as the revision; netplay.version is not read`);
   }
   return { mode, warnings, metafile, bundle: bundled, chunks, rules };
@@ -486,7 +488,7 @@ export function orderGames(games, order, log = () => {}) {
   return [...games].sort((a, b) => (at.get(a.id) ?? Infinity) - (at.get(b.id) ?? Infinity) || a.id.localeCompare(b.id));
 }
 
-export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false, types = false } = {}) {
+export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false, types = false, beforePublish = async () => {}, longCheck = false } = {}) {
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
   // The shop first (shop/SHOP.md): invalid shop settings stop the build before anything is built.
@@ -494,6 +496,7 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   const live = join(root, 'site', 'dist');
   const games = listGames(root).filter((g) => !only || g.id === only);
   if (only && !games.length) throw new Error(`no game "${only}" in games/`);
+  for (const g of games) if (g.kind === 'app') { const bad = appProblems(g); if (bad.length) throw new Error(`apps/${g.id}/app.json: ${bad.join('; ')}`); }
   // `--types`: the games' TypeScript is checked first (esbuild only strips types, it never reads them), and a type
   // error stops the build before anything is built.
   const typed = types ? typecheck(root, games, { log }) : null;
@@ -504,13 +507,13 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   // from the site as it is.
   const dist = openStage(root, { from: only ? live : null });
   try {
-    return await buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps });
+    return await buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps, beforePublish, longCheck });
   } finally {
     rmSync(dist, { recursive: true, force: true });
   }
 }
 
-async function buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps }) {
+async function buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps, beforePublish, longCheck }) {
   const built = [];
   const retired = [];
   const cache = {};
@@ -519,7 +522,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   for (const g of games) {
     const out = join(dist, 'games', g.id);
     const started = Date.now();
-    const { mode, warnings, bundle, chunks, rules } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log, hashed: true });
+    const { mode, warnings, bundle, chunks, rules } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log, hashed: true, longCheck });
     if (rules) ruled.push({ id: g.id, ...rules }); else browserHosted.push(g.id);
     // The guides' vocabulary (NETPLAY.md section 18): checked here, so a room never meets a line it cannot say.
     vocabFor(g, out);
@@ -542,11 +545,14 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
       id: g.id, name: g.name, mode, bytes, ms: Date.now() - started, warnings, seats: seats.max,
       ...(bundle ? { bundle } : {}), ...(chunks.length ? { chunks: chunks.length, chunkBytes: later } : {}),
     });
-    log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB${chunks.length ? ` + ${chunks.length} ${chunks.length === 1 ? 'chunk' : 'chunks'} loaded later, ${Math.max(1, Math.round(later / 1024))} KB` : ''})`);
-    if (rules) log(`  ${g.id}: its rules run on the server (checked and guarded, ${Math.max(1, Math.round(rules.code.length / 1024))} KB, build ${rules.build}; three seconds with bots: the busiest tick used ${rules.tickUnits} of ${rules.settings.budget.tick} budget units, ${rules.units} of them in one handler)`);
+    log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB${chunks.length ? ` + ${chunks.length} additional ${chunks.length === 1 ? 'chunk' : 'chunks'}, ${Math.max(1, Math.round(later / 1024))} KB` : ''})`);
+    if (rules && (rules.settings.offline || rules.settings.host === 'browser')) log(`${g.id}: this game's rules and tunables are sent to players' devices so it can be played offline`);
+    if (rules) log(`  ${g.id}: its rules run ${rules.settings.host === 'browser' ? "in a player's browser" : 'on the server'} (checked and guarded, ${Math.max(1, Math.round(rules.code.length / 1024))} KB, build ${rules.build}; ${rules.check.ticks} ticks played, the room rebuilt from its save ${rules.check.restores} times: the busiest tick used ${rules.tickUnits} of ${rules.settings.budget.tick} budget units, ${rules.units} of them in one handler; the largest save was ${rules.check.largestSaveBytes} bytes)`);
+    if (rules && rules.settings.host === 'server' && (rules.snapshotBytes > rules.snapshotCap || rules.checkpointBytes > rules.checkpointCap)) log(`  ${g.id}: this state fits server and offline play but exceeds browser hosting limits.`);
+    if (rules) log(`  ${g.id}: smoke-run largest snapshot ${rules.snapshotBytes} B / ${rules.snapshotCap} B browser cap; checkpoint ${rules.checkpointBytes} B / ${rules.checkpointCap} B browser cap (measured, not an upper bound)`);
   }
   // A game written before rules (its own code is the host) builds and runs exactly as it did. Said in one line.
-  if (browserHosted.length) log(`hosted by a player's browser, as before (no src/rules.ts; nothing to do): ${browserHosted.join(', ')}`);
+  if (browserHosted.length) log(`hosted by a player's browser, as before (no room object; nothing to do): ${browserHosted.join(', ')}`);
   const all = listGames(root);
   // No game is handed over whole any more (remix was retired; worker/license.mjs). A one-game build starts from the
   // site as it is, which an older toolkit may have built: what that wrote for remixers (a game's whole source, and
@@ -571,8 +577,8 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   // studio.json site.order: the catalogue's order is every listing's order.
   const shown = orderGames(all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))), s.order, log);
   // Server-hosted games: what this build made, and for a one-game build what the catalogue before it said of the others.
-  const rulesOf = new Map(ruled.map((r) => [r.id, { host: 'server', tickHz: r.settings.tickHz, inputHz: r.settings.inputHz, contract: r.schema.contract, build: r.build, stateHash: r.stateHash, rounds: r.rounds }]));
-  if (only) for (const row of readJson(join(dist, 'games.json'))?.games ?? []) if (row?.room?.host === 'server' && row.id !== only && !rulesOf.has(row.id)) rulesOf.set(row.id, row.room);
+  const rulesOf = new Map(ruled.map((r) => [r.id, { host: r.settings.host, offline: r.settings.offline, tickHz: r.settings.tickHz, inputHz: r.settings.inputHz, contract: r.schema.contract, build: r.build, stateHash: r.stateHash, rounds: r.rounds }]));
+  if (only) for (const row of readJson(join(dist, 'games.json'))?.games ?? []) if (row?.room?.contract && row.id !== only && !rulesOf.has(row.id)) rulesOf.set(row.id, row.room);
   // What each game's build is (its landing's own pictures are not part of it): the digest the manifest names.
   const builds = {};
   const rows = shown.map((g) => {
@@ -597,6 +603,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     const bundle = bundleOf(dir);
     builds[g.id] = { hash: gameDigest(dir), ...(bundle ? { bundle } : {}) };
     return {
+      ...(g.kind === 'app' ? { kind: 'app', roles: g.roles, surfaces: g.surfaces, words: g.words, records: g.records, parts: g.parts ?? [], check: g.check } : {}),
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
       ...(ui ? { ui } : {}),
       // A rules game's round is its rules' own (`room.rounds`), and its movement a per-kind choice there: game.json's
@@ -714,7 +721,8 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   if (deploy) for (const b of built) log(`  ${b.id}: ${b.changed}${b.changed === 'new' ? '' : ' since the last build here'}, build ${b.hash}`);
   // The rules of the server-hosted games, where the studio's Worker imports them (site/src/rules/). Written with the
   // site, never before: a game that did not build has left both as they were.
-  const hosted = (await rulesBuild()).writeRules(root, ruled, all.filter((g) => rulesOf.has(g.id)).map((g) => g.id));
+  await beforePublish();
+  const hosted = (await rulesBuild()).writeRules(root, ruled, all.filter((g) => rulesOf.get(g.id)?.host === 'server').map((g) => g.id));
   // All of it is there: now, and only now, it becomes site/dist (lib/stage.mjs).
   const swapped = swapIn(dist, live);
   return {

package/lib/characters.mjs

@@ -28,7 +28,7 @@ import { readManifest, recordAsset, writeManifest } from './asset-manifest.mjs';
 import { VERBS, VERB_IDS, bakeLibrary, findClip, gaitOf, rigOf, writeLibrary } from './clips.mjs';
 import { readDecisions } from './decisions.mjs';
 import { FAMILIES, normaliseRig, skeletonOf, socketBone } from './rig.mjs';
-import { GAME_ID } from './studio.mjs';
+import { experienceDir, experienceFile, GAME_ID } from './studio.mjs';
 
 /** Where humanoid clips come from when a character has none of its own: KayKit's adventurers (CC0, 76 clips). */
 export const CLIP_SOURCES = Object.freeze({
@@ -146,7 +146,7 @@ function appendClips(into, from) {
  * `own`: its own clips (a clip source) or null. Returns { path, skeleton, verbs, clips, missing, bytes, entry }.
  */
 async function bakeFor(root, game, rig, own, verbs, { from = null, lib = null, cache = new Map(), license = null } = {}) {
-  const gdir = join(root, 'games', game);
+  const gdir = join(experienceDir(root, game));
   const skel = rig.skeleton;
   const fallback = from ?? CLIP_SOURCES[skel.family] ?? null;
   const existing = await existingLibrary(gdir, skel.id);
@@ -206,7 +206,7 @@ async function bakeFor(root, game, rig, own, verbs, { from = null, lib = null, c
  */
 export async function addCharacter(root, game, opts = {}) {
   if (!GAME_ID.test(String(game ?? ''))) throw new Error(`"${game}" is not a game id`);
-  const gdir = join(root, 'games', game);
+  const gdir = join(experienceDir(root, game));
   if (!existsSync(join(gdir, 'game.json')) && !existsSync(join(gdir, 'CODEX.md'))) throw new Error(`no game "${game}"`);
   const t = await tools();
   const { optimiseModel, measureDoc } = await import('./optimise.mjs');
@@ -297,7 +297,7 @@ export async function bakeClips(root, game, asset, { verbs = [], from = null, li
   if (!a?.rig) throw new Error(`${asset} is not a rigged character in ${game} (assets add brings one in)`);
   const t = await tools();
   const model = a.files.find((f) => f.role === 'model');
-  const doc = await t.io.readBinary(readFileSync(join(root, 'games', game, model.path)));
+  const doc = await t.io.readBinary(readFileSync(join(experienceDir(root, game), model.path)));
   doc.setLogger(t.logger);
   const rig = rigOf(doc);
   if (rig.skeleton.id !== a.rig.skeleton) rig.skeleton.id = a.rig.skeleton;
@@ -368,7 +368,7 @@ export async function measureGait(root, game, assetId) {
   const a = m.assets.find((x) => x.id === assetId);
   const model = (a?.files ?? []).find((f) => f.role === 'model');
   if (!a?.rig || !model) return null;
-  const gdir = join(root, 'games', game);
+  const gdir = join(experienceDir(root, game));
   const t = await tools();
   const read = async (rel) => { const d = await t.io.readBinary(readFileSync(join(gdir, rel))); d.setLogger(t.logger); return d; };
   const rig = rigOf(await read(model.path));
@@ -420,7 +420,7 @@ export function animPlan(root, game) {
   return {
     ok: true, command: 'anim plan', game, verbs: need, rows, unrigged,
     decisions: Object.fromEntries(['anim.style', 'anim.clips', 'anim.source', 'anim.motion', 'anim.blend', 'anim.procedural', 'rig.skeleton', 'rig.source', 'rig.bones', 'game.feel'].map((k) => [k, d[k] ? { label: d[k].label, state: d[k].state } : null])),
-    lab: existsSync(join(root, 'games', game, 'lab.json')) ? JSON.parse(readFileSync(join(root, 'games', game, 'lab.json'), 'utf8')) : null,
+    lab: existsSync(join(experienceDir(root, game), 'lab.json')) ? JSON.parse(readFileSync(join(experienceDir(root, game), 'lab.json'), 'utf8')) : null,
   };
 }
 
@@ -434,7 +434,7 @@ export async function animPreview(root, game, { asset = null, verbs = null, size
   const rows = plan.rows.filter((r) => !asset || r.id === asset);
   if (!rows.length) return { ok: false, command: 'anim preview', game, why: asset ? `${asset} is not a rigged character in ${game}` : `${game} has no rigged characters yet (assets add <game> <character item>)` };
   const m = readManifest(root, game);
-  const gdir = join(root, 'games', game);
+  const gdir = join(experienceDir(root, game));
   let tokens = null;
   try { tokens = JSON.parse(readFileSync(join(gdir, 'style.json'), 'utf8')); } catch { tokens = null; }
   tokens = tokens?.palette ? tokens : { palette: { bg: '#e9eef2', ink: '#1d2b3a', accent: '#ff8a5b', accent2: '#5cbf8a', danger: '#e2553f', good: '#45b36b', gold: '#ffd25a' } };

package/lib/check.mjs

@@ -141,6 +141,9 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
   // it either, that refusal (for a lookup: BLOCKED, this computer's network, local testing offered) is the report.
   const cannotAsk = siteRefusal(await reachSite(base, { path: `/${game}/play`, timeout: 15_000 }), { command: 'check', play });
   if (cannotAsk?.preflight === 'local') return cannotAsk;
+  let appMeta = null;
+  try { appMeta = (await (await fetch(`${base}/api/games`)).json()).games?.find((g) => g.id === game && g.kind === 'app'); } catch { /* browser preflight below still names failures */ }
+  if (appMeta) return checkApp({ url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
   if (shots) mkdirSync(shots, { recursive: true });
   const profiles = [];
   const browsers = [];
@@ -333,3 +336,49 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
     for (const p of profiles) rmSync(p, { recursive: true, force: true });
   }
 }
+
+/** Apps prove a real action crossing surfaces and a reconnect, without inventing a round. */
+export async function checkApp({ url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
+  const proof = meta.check;
+  if (!proof || typeof proof.action !== 'string' || typeof proof.observe !== 'string') return { ok: false, command: 'check', kind: 'app', why: 'app.json check needs action and observe CSS selectors for a real shared action' };
+  if (shots) mkdirSync(shots, { recursive: true });
+  const profile = mkdtempSync(join(tmpdir(), 'homie-app-check-'));
+  let browser;
+  const surfaces = [];
+  const room = `check-${Date.now().toString(36)}`;
+  try {
+    browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
+    for (const [name, width, height, path] of [['wall', 1280, 720, 'tv'], ['phone', 390, 844, 'open'], ['phone-two', 390, 844, 'open']]) {
+      const context = await browser.createBrowserContext();
+      const page = await context.newPage();
+      await page.setViewport({ width, height, isMobile: name !== 'wall', hasTouch: name !== 'wall' });
+      const params = new URLSearchParams(proof.params ?? {}); params.set('room', room);
+      await page.goto(`${url}/${game}/${path}?${params}`, { waitUntil: 'domcontentloaded', timeout: 90_000 });
+      await page.waitForFunction(() => window.__shell?.link?.state === 'online', { timeout: 90_000 });
+      const frame = page.frames().find((f) => /\/__game\//.test(f.url()));
+      if (!frame) throw new Error(`${name} never loaded the app`);
+      await frame.waitForSelector(proof.observe, { timeout: 30_000 });
+      surfaces.push({ name, page, frame });
+      log(`${name} connected to ${room}`);
+    }
+    const textOf = (f) => f.$eval(proof.observe, (e) => e.textContent);
+    const actor = surfaces[1];
+    await actor.frame.waitForFunction((selector) => { const el = document.querySelector(selector); return el && !el.disabled && !el.hidden; }, {}, proof.action);
+    const before = await textOf(actor.frame);
+    await actor.frame.click(proof.action);
+    await actor.frame.waitForFunction((selector, was) => document.querySelector(selector)?.textContent !== was, {}, proof.observe, before);
+    const after = await textOf(actor.frame);
+    for (const s of surfaces) await s.frame.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after);
+    // The actor reloads with its ticket and room. The other screens remain live.
+    await actor.page.reload({ waitUntil: 'domcontentloaded' });
+    await actor.page.waitForFunction(() => window.__shell?.link?.state === 'online', { timeout: 90_000 });
+    actor.frame = actor.page.frames().find((f) => /\/__game\//.test(f.url()));
+    await actor.frame.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after);
+    const rooms = await Promise.all(surfaces.map((s) => s.page.evaluate(() => window.__shell.room)));
+    if (rooms.some((r) => r !== room)) throw new Error('surfaces did not retain the same room');
+    if (shots) for (const s of surfaces) await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 65 });
+    report?.check?.('app-action', 'pass', { note: 'action reached wall and both phones; reconnect retained it' });
+    return { ok: true, command: 'check', kind: 'app', room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: true };
+  } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
+  finally { await browser?.close().catch(() => {}); rmSync(profile, { recursive: true, force: true }); }
+}

package/lib/cloudflare.mjs

@@ -40,7 +40,7 @@ import { whyFailed } from './net.mjs';
 import { repoOf } from './repo.mjs';
 import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
-import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layoutOf, listGames, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
+import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layoutOf, listExperiences as listGames, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;

package/lib/codex.mjs

@@ -41,7 +41,7 @@ import { extname, join, relative, resolve, sep } from 'node:path';
 import { latestFeedFor, summarize } from './feed-summary.mjs';
 import { escapeHtml as esc, renderMarkdown } from './markdown.mjs';
 import { readTheme } from './site.mjs';
-import { GAME_ID, listGames, readStudio } from './studio.mjs';
+import { experienceDir, experienceFile, GAME_ID, listExperiences as listGames, readStudio } from './studio.mjs';
 import { decisionRows, readDecisions } from './decisions.mjs';
 
 export const CODEX_FILE = 'CODEX.md';
@@ -514,7 +514,7 @@ function codexGame(root, id, { create = false } = {}) {
   const game = listGames(root).find((g) => g.id === id);
   if (game) return game;
   if (!GAME_ID.test(String(id ?? ''))) return null;
-  const dir = join(root, 'games', id);
+  const dir = join(experienceDir(root, id));
   if (existsSync(join(dir, 'game.json'))) return null;
   return existsSync(join(dir, CODEX_FILE)) || create ? { id, dir, name: null, planned: true } : null;
 }

package/lib/collision.mjs

@@ -32,7 +32,7 @@ import { createRequire } from 'node:module';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { modelTools } from './optimise.mjs';
-import { listGames } from './studio.mjs';
+import { listExperiences as listGames } from './studio.mjs';
 
 /** The body that must fit when a file names none: a person, in metres. */
 export const DEFAULT_MOVER = Object.freeze({ radius: 0.35, height: 1.8, step: 0.3, maxDrop: 0.5, arrival: 1, speed: 4 });

package/lib/decisions.mjs

@@ -20,7 +20,7 @@ import { dirname, join } from 'node:path';
 import { HEX, deltaHex, hexToRgb, luminance, mix, nudge } from './colour.mjs';
 import { CAMERAS, FAMILIES, FONT_SETS, GENRES, LIGHTS, MOODS, PALETTES, PALETTE_KEYS, RENDERS, SHAPES } from './style-presets.mjs';
 import { readTheme } from './site.mjs';
-import { GAME_ID, listGames } from './studio.mjs';
+import { experienceDir, experienceFile, GAME_ID, listExperiences as listGames } from './studio.mjs';
 
 export const DECISIONS_FILE = join('codex', 'decisions.json');
 export const STATES = Object.freeze(['auto', 'steered', 'pinned', 'locked']);
@@ -35,7 +35,7 @@ const clean = (s, n = 200) => String(s ?? '').replace(/[\x00-\x1f\x7f]+/g, ' ').
 
 /** What the automatic picks read: the person's words, the codex (its concept, art text and cards), the game. */
 export function contextOf(root, id, { prompt = '' } = {}) {
-  const dir = join(root, 'games', id);
+  const dir = join(experienceDir(root, id));
   let codex = '';
   try { codex = readFileSync(join(dir, 'CODEX.md'), 'utf8').replace(/<!--[\s\S]*?-->/g, ''); } catch { codex = ''; }
   let game = {};
@@ -282,12 +282,12 @@ function castFrom(ctx) {
 
 /* ------------------------------------------------------------------ the file */
 
-const fileOf = (root, id) => join(root, 'games', id, DECISIONS_FILE);
+const fileOf = (root, id) => join(experienceDir(root, id), DECISIONS_FILE);
 
 function gameDirOf(root, id) {
   if (!GAME_ID.test(String(id ?? ''))) throw new Error(`"${id}" is not a game id`);
-  const dir = join(root, 'games', id);
-  if (!existsSync(join(dir, 'game.json')) && !existsSync(join(dir, 'CODEX.md'))) throw new Error(`no game "${id}" (no games/${id}/game.json or CODEX.md)${listGames(root).length ? `; games: ${listGames(root).map((g) => g.id).join(', ')}` : ''}`);
+  const dir = join(experienceDir(root, id));
+  if (!existsSync(experienceFile(root, id)) && !existsSync(join(dir, 'CODEX.md'))) throw new Error(`no game "${id}" (no games/${id}/game.json or CODEX.md)${listGames(root).length ? `; games: ${listGames(root).map((g) => g.id).join(', ')}` : ''}`);
   return dir;
 }
 
@@ -332,7 +332,7 @@ export function styleTokens(doc) {
 function writeStyleTokens(root, id, doc) {
   const t = styleTokens(doc);
   if (!t) return;
-  const file = join(root, 'games', id, 'style.json');
+  const file = join(experienceDir(root, id), 'style.json');
   const text = `${JSON.stringify(t, null, 2)}\n`;
   if (!existsSync(file) || readFileSync(file, 'utf8') !== text) writeFileSync(file, text);
 }
@@ -790,7 +790,7 @@ export function pickDirection(root, id, choice, { mixes = {}, manifest = null }
 
 /** One dated line under the codex's Latest, newest first ("- 2026-10-02: …"). */
 export function addLatestLine(root, id, text) {
-  const file = join(root, 'games', id, 'CODEX.md');
+  const file = join(experienceDir(root, id), 'CODEX.md');
   if (!existsSync(file)) return false;
   const src = readFileSync(file, 'utf8');
   const line = `- ${now().slice(0, 10)}: ${clean(text, 300)}`;