@homie-rocks/studio 0.36.0 → 0.37.0

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).
@@ -78,7 +79,7 @@ import { buildParts, partsPlugin } from './parts-build.mjs';
 // 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 };
@@ -495,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;
@@ -601,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

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)}`;

package/lib/dev.mjs

@@ -1,3 +1,4 @@
+import { networkInterfaces } from 'node:os';
 /**
  * `homie-studio dev` and `dev --stop`: the whole site on this computer (pages, rooms in a local Durable Object, D1),
  * and exactly this studio's dev server stopped, never another project's.
@@ -32,7 +33,7 @@ import { detectLocalAi, localAiVars } from './local-ai.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 import { routesOf } from './routes.mjs';
 import { ensureMigrations, migrationWord } from './scaffold.mjs';
-import { isRulesGame, listGames, workerDir } from './studio.mjs';
+import { isRulesGame, listExperiences as listGames, workerDir } from './studio.mjs';
 
 export const devFile = (root) => join(workerDir(root), '.wrangler', 'homie-dev.json');
 
@@ -289,7 +290,7 @@ function passLines(stream, to, opts) {
  * saved. `rulesStamp` is what it compares: the newest change among them, and how many there are.
  */
 export function rulesStamp(g) {
-  const files = [join(g.dir, 'game.json'), join(g.dir, 'tunables.json')];
+  const files = [join(g.dir, g.kind === 'app' ? 'app.json' : 'game.json'), join(g.dir, 'tunables.json')];
   for (const sub of ['src', 'map']) {
     const dir = join(g.dir, sub);
     if (existsSync(dir)) for (const name of readdirSync(dir, { recursive: true })) files.push(join(dir, String(name)));
@@ -306,7 +307,7 @@ const builtIds = (root) => { try { return JSON.parse(readFileSync(join(root, 'si
  * `homie-studio dev`: build once, then Wrangler's local runtime until it is stopped. Returns the command's result.
  * options: port, remoteAi, localAi (false: --no-local-ai), timestamps (every line of Wrangler's gets a time), log.
  */
-export async function dev(root, { port: askedPort = 8787, remoteAi = false, localAi = true, timestamps = false, log = () => {}, watchMs = 2000 } = {}) {
+export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi = false, localAi = true, timestamps = false, log = () => {}, watchMs = 2000 } = {}) {
   const port = String(askedPort ?? 8787);
   const stop = 'npx --no-install homie-studio dev --stop';
 
@@ -344,6 +345,7 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
   });
   const origin = `http://127.0.0.1:${port}`;
   log(`Local site: ${origin}/  (each game: ${origin}/<id>/play — open it in two browsers)`);
+  if (lan) for (const address of lanAddresses()) log(`Same Wi-Fi: http://${address}:${port}/ (open this address on phones and wall screens)`);
   const ai = devConfig(root, remoteAi);
   if (ai.note) log(ai.note);
   // The person's own Clef (0.24.4, lib/local-ai.mjs): with Ollama and clef-flash on this computer, the local Worker's
@@ -356,7 +358,7 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
   }
   // --remote-ai: Wrangler's --local turns every remote binding off ("not supported"), so a dev with the real Workers AI
   // (the guides' brains, room chat's review) runs without it; everything else stays local all the same.
-  const args = ['dev', ...(remoteAi ? [] : ['--local']), '--ip', '127.0.0.1', '--port', port, '--var', 'HOMIE_EMBED_PREVIEW:1', ...ai.args, ...localVars];
+  const args = ['dev', ...(remoteAi ? [] : ['--local']), '--ip', lan ? '0.0.0.0' : '127.0.0.1', '--port', port, '--var', 'HOMIE_EMBED_PREVIEW:1', ...ai.args, ...localVars];
   log(`Stop it with: ${stop}   (this studio's dev server only)`);
 
   let child = null;
@@ -390,7 +392,7 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
       for (const g of listGames(root)) {
         if (built.includes(g.id) || told.has(g.id)) continue;
         told.add(g.id);
-        log(`games/${g.id} is new and not built yet, so ${origin}/${g.id}/play is a 404 for now. Build it (npx --no-install homie-studio build): this dev server serves what build wrote and picks the new game up by itself.`);
+        log(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id} is new and not built yet, so ${origin}/${g.id}/play is a 404 for now. Build it (npx --no-install homie-studio build): this dev server serves what build wrote and picks the new game up by itself.`);
       }
       for (const id of built) {
         if (startedWith.has(id)) continue;
@@ -412,17 +414,20 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
   };
   // A rules game saved while dev runs is built again (see rulesStamp), one game at a time.
   const stamps = new Map(listGames(root).filter(isRulesGame).map((g) => [g.id, rulesStamp(g)]));
+  const timingRetries = new Map();
   let rebuilding = false;
   let published = Promise.resolve();
   const rulesLook = async () => {
     if (rebuilding || ending) return;
     for (const g of listGames(root).filter(isRulesGame)) {
       const now = rulesStamp(g);
-      if (stamps.get(g.id) === now) continue;
+      const retry = timingRetries.get(g.id);
+      if (stamps.get(g.id) === now && !(retry?.stamp === now && Date.now() >= retry.at)) continue;
+      if (retry?.stamp !== now) timingRetries.delete(g.id);
       stamps.set(g.id, now);
       rebuilding = true;
       try {
-        log(`games/${g.id} changed: checking its rules and building it again…`);
+        log(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id} changed: checking its rules and building it again…`);
         const hash = () => { try { return JSON.parse(readFileSync(join(root, 'site/dist/games.json'), 'utf8')).games.find((x) => x.id === g.id)?.room?.stateHash; } catch { return null; } };
         const before = hash();
         let release;
@@ -439,9 +444,17 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
             await stopped;
           } });
         } finally { release(); }
-        log(`games/${g.id} is rebuilt. ${before && before === hash() ? 'Local rooms resume their saved match; pages reconnect.' : 'The stored shape changed: local rooms reset to a fresh match; pages reconnect.'}`);
+        timingRetries.delete(g.id);
+        log(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id} is rebuilt. ${before && before === hash() ? 'Local rooms resume their saved match; pages reconnect.' : 'The stored shape changed: local rooms reset to a fresh match; pages reconnect.'}`);
       } catch (error) {
-        log(`games/${g.id} did not build, so the local site still runs what it had:\n${String(error?.message ?? error)}`);
+        log(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id} did not build, so the local site still runs what it had:\n${String(error?.message ?? error)}`);
+        // A busy machine can fail the wall-clock tick guard once. Keep the guard, resample at most three times,
+        // and never retry syntax, contract or deterministic budget failures until the author edits them.
+        const attempts = timingRetries.get(g.id)?.attempts ?? 0;
+        if (/rules ran for .*seconds with bots and were too slow/.test(String(error?.message ?? error)) && attempts < 3) {
+          timingRetries.set(g.id, { stamp: now, attempts: attempts + 1, at: Date.now() + 10000 });
+          log(`${g.id}: retrying the timing check in 10 seconds (${attempts + 1}/3); the last good build stays live.`);
+        } else timingRetries.delete(g.id);
       } finally { rebuilding = false; }
       return;
     }
@@ -484,3 +497,7 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
   if (failed) return { ok: false, command: 'dev', needs: 'local-rooms', socket: failed.socket, expected: failed.expected, why: failed.why };
   return { ok: true, command: 'dev', stopped: true };
 }
+
+export function lanAddresses(interfaces = networkInterfaces()) {
+  return [...new Set(Object.values(interfaces).flat().filter((n) => n && !n.internal && n.family === 'IPv4' && !n.address.startsWith('169.254.')).map((n) => n.address))].sort();
+}

package/lib/directory.mjs

@@ -5,7 +5,7 @@
  * nobody can list games under someone else's site.
  */
 import { request } from './net.mjs';
-import { listGames, readLocal, readStudio, siteUrl, writeLocal } from './studio.mjs';
+import { listExperiences as listGames, readLocal, readStudio, siteUrl, writeLocal } from './studio.mjs';
 import { licenceProblems, readManifest } from './asset-manifest.mjs';
 import { partsPlanLines, partsPublishReport } from './parts-build.mjs';
 

package/lib/doctor.mjs

@@ -50,7 +50,7 @@ import { detectLocalAi } from './local-ai.mjs';
 import { findChrome } from './chrome.mjs';
 import { whyFailed } from './net.mjs';
 import { isOurs } from './statusline.mjs';
-import { findStudio, listGames, readLocal, readStudio } from './studio.mjs';
+import { findStudio, listExperiences as listGames, readLocal, readStudio } from './studio.mjs';
 import { standaloneRows } from './standalone.mjs';
 import { projectsCloudflareEnv, projectsElevenLabs } from './projects-env.mjs';
 import { STUDIO_VERSION } from './version.mjs';

package/lib/handoff.mjs

@@ -26,7 +26,7 @@ function originRepo(root) {
   return m ? `${m[1]}/${m[2]}` : null;
 }
 import { setupAttach } from './setup.mjs';
-import { listGames, readStudio } from './studio.mjs';
+import { listExperiences as listGames, readStudio } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 
 const BUILD = /^hb_[a-f0-9]{32}$/;

package/lib/lab-check.mjs

@@ -25,7 +25,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { chromeArgs, findChrome, noChrome, SOFTWARE_GL } from './chrome.mjs';
 import { labDir, startLabServer } from './lab.mjs';
-import { isRulesGame, listGames } from './studio.mjs';
+import { isRulesGame, listExperiences as listGames } from './studio.mjs';
 
 const round = (v, d = 2) => (Number.isFinite(v) ? Math.round(v * 10 ** d) / 10 ** d : null);
 const pct = (xs, p) => { const s = xs.filter(Number.isFinite).sort((a, b) => a - b); return s.length ? s[Math.min(s.length - 1, Math.floor((s.length - 1) * p))] : null; };

package/lib/lab.mjs

@@ -28,7 +28,7 @@ import { createServer } from 'node:http';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, watch, writeFileSync } from 'node:fs';
 import { extname, join, normalize, relative, resolve, sep } from 'node:path';
 import { buildGameFiles, studioEsbuild } from './build.mjs';
-import { GAME_ID, PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
+import { experienceDir, experienceFile, GAME_ID, PACKAGE_ROOT, listExperiences as listGames, readStudio } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { formatLabFile, formatTunables, readLabFile, checkTake, setTunables, tunableValue, TAKE_NAME } from '../lab/take.js';
 
@@ -123,16 +123,16 @@ export function commitOf(root, ref = 'HEAD') {
 
 /** Whether games/<id>/ differs from HEAD (staged, changed or new files). */
 export function dirtyOf(root, id) {
-  const r = git(root, ['status', '--porcelain', '--', `games/${id}`]);
+  const r = git(root, ['status', '--porcelain', '--', relative(root, experienceDir(root, id))]);
   return r.status === 0 ? r.stdout.trim().split('\n').filter(Boolean).length : null;
 }
 
 /** The paths of `sha` that New's bundle read from outside games/<id>/ (a shared folder), plus the game's own. */
 function pathsFor(root, id, sha, metafile) {
-  const want = new Set([`games/${id}`]);
+  const want = new Set([relative(root, experienceDir(root, id))]);
   for (const input of Object.keys(metafile?.inputs ?? {})) {
     const rel = input.split(sep).join('/');
-    if (rel.startsWith('node_modules/') || rel.startsWith('../') || rel.startsWith('/') || rel.startsWith(`games/${id}/`) || rel.includes('/node_modules/')) continue;
+    if (rel.startsWith('node_modules/') || rel.startsWith('../') || rel.startsWith('/') || rel.startsWith(relative(root, experienceDir(root, id)) + '/') || rel.includes('/node_modules/')) continue;
     want.add(rel);
   }
   for (const f of ['package.json', 'studio.json']) want.add(f);
@@ -146,7 +146,7 @@ function checkout(root, id, sha, paths) {
   const dir = join(labDir(root, id), 'checkout');
   const stamp = join(labDir(root, id), 'checkout.json');
   const had = readJson(stamp);
-  if (had?.sha === sha && JSON.stringify(had.paths) === JSON.stringify(paths) && existsSync(join(dir, 'games', id))) return dir;
+  if (had?.sha === sha && JSON.stringify(had.paths) === JSON.stringify(paths) && existsSync(experienceDir(dir, id))) return dir;
   removeCheckout(root, dir);
   mkdirSync(labDir(root, id), { recursive: true });
   const add = git(root, ['worktree', 'add', '--no-checkout', '--detach', dir, sha]);
@@ -154,8 +154,8 @@ function checkout(root, id, sha, paths) {
   const co = git(dir, ['checkout', sha, '--', ...paths]);
   if (co.status !== 0) throw new Error(`git could not check out games/${id} at ${sha.slice(0, 7)}: ${(co.stderr || co.stdout).trim().split('\n').pop()}`);
   // A game with its own build (game.json build.mode "command") builds with its own node_modules: the working tree's.
-  const nm = join(root, 'games', id, 'node_modules');
-  if (existsSync(nm) && existsSync(join(dir, 'games', id)) && !existsSync(join(dir, 'games', id, 'node_modules'))) { try { symlinkSync(nm, join(dir, 'games', id, 'node_modules'), 'dir'); } catch { /* builds without */ } }
+  const nm = join(experienceDir(root, id), 'node_modules');
+  if (existsSync(nm) && existsSync(experienceDir(dir, id)) && !existsSync(join(experienceDir(dir, id), 'node_modules'))) { try { symlinkSync(nm, join(experienceDir(dir, id), 'node_modules'), 'dir'); } catch { /* builds without */ } }
   writeFileSync(stamp, `${JSON.stringify({ sha, paths, at: new Date().toISOString() })}\n`);
   return dir;
 }
@@ -243,7 +243,7 @@ class Builds {
     // A commit changes Today: look every 2 s (one cheap `git rev-parse`).
     this.refTimer = setInterval(() => { void this.followRef(); }, 2000);
     this.refTimer.unref?.();
-    const dir = join(this.root, 'games', this.id);
+    const dir = experienceDir(this.root, this.id);
     try {
       this.watcher = watch(dir, { recursive: true }, (_e, file) => {
         const f = String(file ?? '');

package/lib/library.mjs

@@ -18,7 +18,7 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { LIMITS, checkGlb } from '../assets/safety.mjs';
 import { recordAsset } from './asset-manifest.mjs';
-import { GAME_ID } from './studio.mjs';
+import { experienceDir, experienceFile, GAME_ID } from './studio.mjs';
 
 export const LIBRARY_URL = 'https://homie.rocks/api/library/v0';
 const CACHE = join(homedir(), '.cache', 'homie-studio', 'library');
@@ -117,7 +117,7 @@ const KIND_DIR = { texture: 'tex', sky: 'sky' };
  */
 export async function addFromLibrary(root, game, itemId, { as = null, height = null, card = null, lib = libraryBase(), index = null } = {}) {
   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(gdir)) throw new Error(`no game "${game}"`);
   const idx = index ?? (await loadIndex({ lib })).index;
   const item = idx.items.find((x) => x.id === itemId) ?? idx.items.find((x) => x.item === itemId);

package/lib/mcp-tools.mjs

@@ -28,7 +28,7 @@ import { cliJob, findNode, getJob, installJob, installed, jobView, runningJobs,
 import { Feed, currentId, publicFeed, readFeed, startProgress } from './progress.mjs';
 import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
-import { GAME_ID, PACKAGE_ROOT, findStudio, isRulesGame, listGames, readLocal, readStudio, siteUrl } from './studio.mjs';
+import { GAME_ID, PACKAGE_ROOT, findStudio, isRulesGame, listExperiences as listGames, readLocal, readStudio, siteUrl } from './studio.mjs';
 import { runningDev } from './dev.mjs';
 import { deployWords } from './deploy-state.mjs';
 import { partsForListing, publishBefore, publishesSoFar } from './directory.mjs';
@@ -863,6 +863,25 @@ export function toolDefs(ctx, avail = {}) {
         return ok(`${formatDemo(r)}\n\nFor you, the AI: give the person this Play link in your reply; they open it themselves. Do not open a browser or run any command to open it.`, { kind: 'demo', ...r });
       },
     },
+    {
+      name: 'app_make', title: 'Make an app',
+      description: 'Make one morphing screen with customer, staff and wall roles, lasting records and a shared 3D scene. Uses the same engines, netplay, parts and standalone builds as games. No rounds required.',
+      inputSchema: { type: 'object', properties: { id: str('App id: lowercase, digits, hyphens'), name: str('Display name'), ...STUDIO_ARG }, required: ['id', 'name'] },
+      annotations: { title: 'Make an app', ...RW },
+      run: async (a) => {
+        if (!GAME_ID.test(String(a.id ?? ''))) return fail('invalid app id');
+        const root = ctx.root(a.studio);
+        const r = await cli(ctx, root, `app new ${a.id}`, ['app', 'new', a.id, '--name', String(a.name ?? a.id).slice(0, 60)]);
+        if (!r.ended) return stillRunning(r.job, 'Making the app');
+        if (r.job.code !== 0) return fail(`Not made: ${whyOf(r.job)}`);
+        let install = '';
+        if (r.result?.installNeeded) {
+          if (ctx.install) { const job = runningJobs(root).find((j) => j.label.startsWith('npm install')) ?? installJob(root); install = ` Dependencies are installing (job ${job.id}); wait for studio_job.`; }
+          else install = ' Run studio_install for its engine dependencies.';
+        }
+        return ok(`apps/${a.id} is ready.${install} Build, dev --lan, then check. Follow the app skill: one screen, roles and parts.`, { kind: 'app', ...r.result });
+      },
+    },
     {
       name: 'game_make', title: 'Make a multiplayer game',
       description: 'Make a game in the studio from a multiplayer starter, under the id you choose, to change into the person\'s game: gem-rush (an arena: every browser renders, one hosts the rules, bots fill empty seats, rounds restart), gem-rush-3d (the same arena in three.js, dressed with free CC0 models through @homie-rocks/studio/assets: the start for a 3D game), hero-rush-3d (the arena with animated CC0 heroes that run, jump and swing through @homie-rocks/studio/animate, a shared clip library per skeleton, a jump and a swing tuned in the Game Lab: the start for a 3D game with characters) or ember-vale (a hero who lasts for days, with cloud saves: for persistent games). In a new studio only once their game is planned (game_plan), or when they ask for a copy of a working starter; never as a first step. A planned game\'s codex stays. Before writing one of its systems from scratch, look for a piece of an existing game that does it (parts_find; part_add brings it in), and for the general mechanism in the @homie-rocks/* packages.',
@@ -1007,7 +1026,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'check', title: 'Two-browser check',
-      description: 'Prove a game works: two fresh browsers (a computer and a phone) press Play, land in the same public room and finish a round (about 70 s). Starts the site here first when it is not running. Runs in the background; the build card follows each step going green. Run it before saying a game works.',
+      description: 'Prove an app works across a wall and two phones: an action propagates and survives reconnect, with no rounds. For a game: two fresh browsers (a computer and a phone) press Play, land in the same public room and finish a round (about 70 s). Starts the site here first when it is not running. Runs in the background; the build card follows each step going green. Run it before saying a game works.',
       inputSchema: { type: 'object', properties: { game: str('The game\'s id (default: the only game)'), url: str('Optional: the site to check (default: this computer\'s preview); the live site after a deploy'), ...STUDIO_ARG } },
       annotations: { title: 'Two-browser check', ...RW }, _meta: ui(UI.build),
       run: async (a) => {
@@ -1017,7 +1036,7 @@ export function toolDefs(ctx, avail = {}) {
         const game = a.game ?? (games.length === 1 ? games[0].id : null);
         if (!game) return fail(games.length ? `which game? ${games.map((g) => g.id).join(', ')}` : 'there is no game to check yet');
         const url = a.url ? String(a.url) : await devUrl(ctx, root);
-        return startRun(ctx, root, { kind: 'check', game, title: `${games.find((g) => g.id === game)?.name ?? game}: two-browser check`, steps: [
+        return startRun(ctx, root, { kind: 'check', game, title: `${games.find((g) => g.id === game)?.name ?? game}: ${games.find((g) => g.id === game)?.kind === 'app' ? 'multi-screen' : 'two-browser'} check`, steps: [
           ...(games.some((g) => g.id === game && isRulesGame(g)) ? [{ label: 'rules build check', args: ['build', game] }] : []),
           { label: 'two-browser check', args: ['check', game, '--url', url, '--shots', join('.checks', game)] },
         ] });

package/lib/parts-build.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * GAME PARTS IN THE BUILD (parts/PARTS.md). Three small things lib/build.mjs and the deploy plan call, so the build
  * itself stays one line longer in each place:
@@ -63,7 +64,7 @@ export function partsPlugin(root, game = null) {
       });
       // A brought-in part a game imports is that game's to credit, even when it was added without naming the game.
       build.onEnd(() => {
-        if (!game || !used.size || !existsSync(join(root, 'games', game))) return;
+        if (!game || !used.size || !existsSync(join(experienceDir(root, game)))) return;
         try {
           const now = readOrigins(root);
           let changed = false;
@@ -112,7 +113,7 @@ export function buildParts(root, dist, { studio = {}, log = () => {} } = {}) {
       writeFileSync(join(dest, 'part.json'), `${JSON.stringify(publicPart({ ...packed, share: true }))}\n`);
     }
     // The game it came out of, by the name the studio gives it.
-    const g = part.from?.game;
+    const g = part.from?.game ?? part.from?.app;
     if (g && !names.has(g)) names.set(g, gameFacts(root, g).name);
     index.push({ ...part, ...(g ? { from: { ...part.from, name: names.get(g) } } : {}), url: `/parts/${id}/${versions.at(-1)}/`, page: `/parts/${id}/`, versions });
     log(`shared part ${id} (${versions.join(', ')})`);
@@ -142,7 +143,7 @@ export function partsPublishReport(root) {
   for (const [ref, e] of Object.entries(lock.parts)) for (const g of e.games ?? []) { if (!byGame.has(g)) byGame.set(g, []); byGame.get(g).push([ref, e]); }
   const games = [];
   for (const [game, list] of [...byGame].sort(([a], [b]) => a.localeCompare(b))) {
-    if (!existsSync(join(root, 'games', game, 'game.json'))) continue;
+    if (!existsSync(experienceFile(root, game))) continue;
     const issues = licenceIssues(partItems(root, { game }), { game: gameFacts(root, game) });
     games.push({
       game,

package/lib/parts-cli.mjs

@@ -28,7 +28,7 @@ export async function partsCommand(root, sub, positional, flags, { log = () => {
   const str = (k) => (typeof flags.get(k) === 'string' ? flags.get(k) : null);
   switch (sub ?? 'find') {
     case 'find': return findParts(root, positional.slice(2).join(' '), { kind: str('kind'), tag: str('tag'), license: str('license'), builds: str('builds'), fetch, hub: str('hub') });
-    case 'new': return newPart(root, arg, { kind: str('kind') ?? 'mechanic', name: str('name'), from: str('from'), paths: positional.slice(3) });
+    case 'new': return newPart(root, arg, { kind: str('kind') ?? 'mechanic', name: str('name'), from: str('from'), paths: positional.slice(3), uses: str('uses')?.split(',') });
     case 'check': return checkParts(root, arg ?? null, { write: true });
     case 'share': return arg ? sharePart(root, arg, true) : { ok: false, command: 'parts share', why: 'name the part to share' };
     case 'unshare': return arg ? sharePart(root, arg, false) : { ok: false, command: 'parts unshare', why: 'name the part to stop sharing' };
@@ -49,7 +49,7 @@ function addLines(r) {
   if (r.was && r.same) L.push(`${r.ref} ${r.version} is already here and unchanged.`);
   else if (r.was) L.push(`${r.ref}: ${r.was} → ${r.version}. ${[r.changes.changed.length ? `changed: ${r.changes.changed.join(', ')}` : '', r.changes.added.length ? `new: ${r.changes.added.join(', ')}` : '', r.changes.removed.length ? `gone: ${r.changes.removed.join(', ')}` : ''].filter(Boolean).join('; ') || 'the same files'}. Your tuning.json was kept${r.replaced?.length ? `; REPLACED your edited ${r.replaced.join(', ')} as asked` : ''}.`);
   else L.push(`${r.name} ${r.version} (${r.kind}) from ${r.host} is in ${r.dir}: ${r.files} files, every one checked against its SHA-256. It is this studio's to tune now.`);
-  if (r.from?.name || r.from?.game) L.push(`  It came out of ${r.from.name ?? r.from.game}${r.from.studio ? ` by ${r.from.studio}` : ''}.`);
+  if (r.from?.name || (r.from?.game ?? r.from?.app)) L.push(`  It came out of ${r.from.name ?? (r.from.game ?? r.from.app)}${r.from.studio ? ` by ${r.from.studio}` : ''}.`);
   L.push(`  Licence: ${r.license ?? 'NONE NAMED'} (asks ${r.asks ?? 'unknown'})${r.attribution ? `; credit: ${r.attribution}` : ''}`);
   if (r.credits?.length) L.push(`  Credited in ${r.credits.join(', ')}.`);
   else if (!r.game) L.push('  It is credited in a game\'s credits when that game imports it (the build does it).');
@@ -69,7 +69,7 @@ export function partsLines(r) {
       for (const p of r.results) {
         L.push(`${p.name} (${p.kind}) ${p.version ?? ''} · ${p.license ?? 'no licence named'} · ${p.where === 'hub' ? p.ref : p.where === 'here' ? `${p.ref} (already here)` : `${p.id} (this studio's own${p.share ? ', shared' : ', private'})`}`);
         if (p.summary) L.push(`  ${p.summary}`);
-        if (p.from?.name || p.from?.game) L.push(`  from ${p.from.name ?? p.from.game}${p.from.studio ? ` by ${p.from.studio}` : ''}`);
+        if (p.from?.name || (p.from?.game ?? p.from?.app)) L.push(`  from ${p.from.name ?? (p.from.game ?? p.from.app)}${p.from.studio ? ` by ${p.from.studio}` : ''}`);
         const bits = [costWords(p.cost) && `costs ${costWords(p.cost)}`, buildsWords(p.requires) && `builds on ${buildsWords(p.requires)}`, p.rig && `rig ${p.rig}`, p.netplay && `in a room: ${p.netplay}`].filter(Boolean);
         if (bits.length) L.push(`  ${bits.join(' · ')}`);
         L.push(`  ${p.say}`);