@homie-rocks/studio 0.35.1 → 0.37.0

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,22 +414,47 @@ 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();
-        await build(root, { only: g.id, log });
-        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.'}`);
+        let release;
+        published = new Promise(resolve => { release = resolve; });
+        try {
+          await build(root, { only: g.id, log, beforePublish: async () => {
+            // Wrangler independently watches assets and code. Publishing both while it runs
+            // reloads the old bundle first, then the new one. Stop once at the publish boundary;
+            // the loop below starts once with the complete build and the same local storage.
+            if (!child || child.exitCode !== null) return;
+            restart = g.id;
+            const stopped = new Promise(resolve => child.once('close', resolve));
+            child.kill('SIGTERM');
+            await stopped;
+          } });
+        } finally { release(); }
+        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;
     }
@@ -461,6 +488,7 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
     writeFileSync(devFile(root), `${JSON.stringify({ pid: process.pid, child: child.pid, port: Number(port), at: new Date().toISOString() })}\n`);
     settle().catch(() => {});
     await new Promise((done) => { child.on('close', done); child.on('error', done); });
+    await published;
     if (!restart || ending) break;
     restart = null;
   }
@@ -469,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 { 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; };
@@ -58,6 +58,11 @@ export function summarise(pane, { fps, units }) {
   };
 }
 
+/** A rules take must actually advance its local runtime without joining a room. */
+export function rulesRun(s) {
+  return Boolean(s?.hosting && !s.connected && s.tick > 0 && s.status === 'playing');
+}
+
 /** Where two runs of one build first differ (frame number), or null when every frame matches. */
 export function firstDifference(a, b) {
   const n = Math.max(a?.length ?? 0, b?.length ?? 0);
@@ -137,8 +142,18 @@ export async function labCheck(root, id, { take = null, today = 'HEAD', device =
       new: first.new.available ? firstDifference(first.new.frames, second.new.frames) : null,
       today: first.today.available ? firstDifference(first.today.frames, second.today.frames) : null,
     };
+    const rules = isRulesGame(games.find((g) => g.id === game)) ? await page.evaluate(() => {
+      const out = {};
+      for (const pane of ['new', 'today']) {
+        const frame = [...document.querySelectorAll('iframe')].find((f) => f.src.includes('/' + pane + '/'));
+        const n = frame?.contentWindow?.__homieNet;
+        out[pane] = n ? { format: typeof n.probe?.hosted === 'function', hosting: n.rulesHosting, connected: n.connected, tick: n.probe?.tick?.(), status: n.probe?.status?.() } : null;
+      }
+      return out;
+    }) : null;
+    if (rules && (!rulesRun(rules.new) || (first.today.available && rules.today?.format && !rulesRun(rules.today)))) pageErrors.push('A rules pane did not play on its local host runtime.');
     const summary = {
-      ok: true, game, take: first.take, note: first.note, fps: first.fps, frames: first.frames, device: first.device, seed: first.seed, inputs: first.inputs,
+      ok: !rules || pageErrors.length === 0, rules, game, take: first.take, note: first.note, fps: first.fps, frames: first.frames, device: first.device, seed: first.seed, inputs: first.inputs,
       newBuild: first.newBuild, todayBuild: first.todayBuild, overrides: first.overrides, renderer, software: SOFTWARE_GL.test(String(renderer ?? '')),
       deterministic, new: summarise(first.new, first), today: summarise(first.today, first), pageErrors,
     };
@@ -182,7 +197,7 @@ export async function labCheck(root, id, { take = null, today = 'HEAD', device =
     };
     if (!out) writeFileSync(join(labDir(root, game), 'latest.json'), `${JSON.stringify(latest, null, 2)}\n`);
     return {
-      ok: true, command: 'lab check', game, take: summary.take, out: rel(dir), report: rel(join(dir, 'REPORT.md')), sheet: rel(join(dir, 'sheet.png')), still: rel(stillPath),
+      ok: summary.ok, rules: summary.rules, command: 'lab check', game, take: summary.take, out: rel(dir), report: rel(join(dir, 'REPORT.md')), sheet: rel(join(dir, 'sheet.png')), still: rel(stillPath),
       frames: summary.frames, fps: summary.fps, deterministic, renderer, software: summary.software,
       phases: { new: summary.new.phases?.map((p) => `${p.name} ${p.frames}f`) ?? [], today: summary.today.available ? summary.today.phases.map((p) => `${p.name} ${p.frames}f`) : null },
       timeline: { new: (summary.new.phases ?? []).map(({ name, from, to }) => ({ name, from, to })), today: summary.today.available ? summary.today.phases.map(({ name, from, to }) => ({ name, from, to })) : 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';
 
@@ -67,6 +67,20 @@ export function readTunables(dir) {
   return json;
 }
 
+/** Rules keep public movement knobs grouped on disk; sliders name them public.speed, public.jump, and so on. */
+export function flatTunables(spec) {
+  if (!spec) return null;
+  const { public: pub, ...rest } = spec;
+  return { ...rest, ...Object.fromEntries(Object.entries(pub ?? {}).map(([k, v]) => [`public.${k}`, v])) };
+}
+export function setLabTunables(spec, values) {
+  const r = setTunables(flatTunables(spec), values);
+  if (!spec?.public) return r;
+  const out = { ...r.spec, public: { ...spec.public } };
+  for (const [k, v] of Object.entries(r.spec)) if (k.startsWith('public.')) { out.public[k.slice(7)] = v; delete out[k]; }
+  return { ...r, spec: out };
+}
+
 /** `homie-studio lab set <game> name=value ...`: values written into tunables.json, one tunable a line. */
 export function labSet(root, id, pairs) {
   const g = gameOf(root, id);
@@ -74,12 +88,12 @@ export function labSet(root, id, pairs) {
   if (!spec) return { ok: false, command: 'lab set', why: `games/${g.id} has no tunables.json yet: the lab skill says how a game gets one (lab.tunables)` };
   const values = {};
   for (const p of pairs) {
-    const m = /^([A-Za-z_$][\w$]{0,47})=(.+)$/.exec(String(p));
+    const m = /^((?:public\.)?[A-Za-z_$][\w$]{0,47})=(.+)$/.exec(String(p));
     if (!m) return { ok: false, command: 'lab set', why: `"${p}" is not name=value` };
     values[m[1]] = m[2];
   }
   if (!Object.keys(values).length) return { ok: false, command: 'lab set', why: 'usage: homie-studio lab set <game> <name>=<value> ...' };
-  const r = setTunables(spec, values);
+  const r = setLabTunables(spec, values);
   if (r.refused.length) return { ok: false, command: 'lab set', why: r.refused.join('; ') };
   writeFileSync(join(g.dir, 'tunables.json'), formatTunables(r.spec));
   return { ok: true, command: 'lab set', game: g.id, file: `games/${g.id}/tunables.json`, changed: r.changed };
@@ -109,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);
@@ -132,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]);
@@ -140,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;
 }
@@ -179,7 +193,7 @@ class Builds {
     const t0 = Date.now();
     this.new = { ...this.new, building: true };
     try {
-      const r = await buildGameFiles(this.esbuild, this.root, g, out, { sourcemap: 'linked', log: this.log });
+      const r = await buildGameFiles(this.esbuild, this.root, g, out, { sourcemap: 'linked', lab: true, log: this.log });
       this.new = { ok: true, building: false, error: null, dir: out, at: new Date().toISOString(), ms: Date.now() - t0, bytes: sizeOf(join(out, 'assets', 'main.js')), metafile: r.metafile, mode: r.mode, dirty: dirtyOf(this.root, this.id) };
     } catch (error) {
       this.new = { ok: false, building: false, error: error.message, dir: out, at: new Date().toISOString() };
@@ -209,7 +223,7 @@ class Builds {
       const g = listGames(dir).find((x) => x.id === this.id);
       if (!g) throw new Error(`games/${this.id}/game.json is not in ${c.short}`);
       this.esbuild ??= await studioEsbuild(this.root);
-      await buildGameFiles(this.esbuild, dir, g, out, { sourcemap: 'linked', log: this.log });
+      await buildGameFiles(this.esbuild, dir, g, out, { sourcemap: 'linked', lab: true, log: this.log });
       let tunables = null;
       try { tunables = readTunables(g.dir); } catch { tunables = null; }
       const at = new Date().toISOString();
@@ -229,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 ?? '');
@@ -350,7 +364,7 @@ export async function startLabServer(root, { port = LAB_PORT, today = 'HEAD', lo
     if (what === 'tunables') {
       const spec = readTunables(dir);
       if (!spec) return send(res, 400, { ok: false, why: `games/${id} has no tunables.json` });
-      const r = setTunables(spec, json.values ?? {});
+      const r = setLabTunables(spec, json.values ?? {});
       if (r.refused.length) return send(res, 400, { ok: false, why: r.refused.join('; ') });
       writeFileSync(join(dir, 'tunables.json'), formatTunables(r.spec));
       log(`kept in games/${id}/tunables.json: ${r.changed.map((c) => `${c.name} ${c.from} -> ${c.to}`).join(', ') || 'nothing changed'}`);
@@ -422,7 +436,7 @@ function stateOf(root, b) {
   let tunablesError = null;
   try { tunables = readTunables(g.dir); } catch (error) { tunablesError = error.message; }
   const pane = (p) => ({ ok: p.ok, building: p.building, error: p.error ?? null, none: p.none ?? null, at: p.at ?? null, ms: p.ms ?? null, bytes: p.bytes ?? null });
-  const todayValues = b.today.tunables ? Object.fromEntries(Object.entries(b.today.tunables).map(([k, s]) => [k, tunableValue(s)])) : null;
+  const todayValues = b.today.tunables ? Object.fromEntries(Object.entries(flatTunables(b.today.tunables)).map(([k, s]) => [k, tunableValue(s)])) : null;
   return {
     ok: true,
     version: STUDIO_VERSION,
@@ -431,7 +445,7 @@ function stateOf(root, b) {
     new: { ...pane(b.new), dirty: b.new.dirty ?? null, mode: b.new.mode ?? null },
     today: { ...pane(b.today), ref: b.todayRef, commit: b.today.commit ?? null },
     takes: { default: takes.default, takes: takes.takes, problems: takes.problems, file: `games/${g.id}/lab.json`, exists: takes.exists },
-    tunables: { file: `games/${g.id}/tunables.json`, spec: tunables, today: todayValues, error: tunablesError },
+    tunables: { file: `games/${g.id}/tunables.json`, spec: flatTunables(tunables), today: todayValues, error: tunablesError },
   };
 }
 

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

package/lib/parts-store.mjs

@@ -23,7 +23,7 @@ import {
   packedVersions, parseRef, partDir, readOrigins, readPart, requiredParts, sha256, shareProblems, syncPartCredits, vendorDir, verifyFiles, writeHashes,
   writeOrigins, writePart,
 } from './parts.mjs';
-import { listGames, readStudio } from './studio.mjs';
+import { experienceDir, experienceFile, listExperiences as listGames, readStudio } from './studio.mjs';
 
 export const HUB = 'https://homie.rocks';
 const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
@@ -139,8 +139,8 @@ export function ensurePackages(root, wants, { npm = runNpm, install = false, say
 /** What a part's licence can care about in the game using it: whether the studio sells, and who the game credits. */
 export function gameFacts(root, id) {
   let g = {}; let credits = {};
-  try { g = JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')); } catch { g = {}; }
-  try { credits = JSON.parse(readFileSync(join(root, 'games', id, 'credits.json'), 'utf8')); } catch { credits = {}; }
+  try { g = JSON.parse(readFileSync(experienceFile(root, id), 'utf8')); } catch { g = {}; }
+  try { credits = JSON.parse(readFileSync(join(experienceDir(root, id), 'credits.json'), 'utf8')); } catch { credits = {}; }
   return { id, name: g.name ?? id, sells: existsSync(join(root, 'shop.json')), credits: Array.isArray(credits.parts) ? credits.parts : [] };
 }
 
@@ -177,7 +177,7 @@ const diffFiles = (was, now) => {
 export async function addPart(root, refText, { game = null, fetch, npm = runNpm, install = true, overwrite = false, say = () => {} } = {}) {
   const command = 'parts add';
   const fail = (why, extra = {}) => ({ ok: false, command, why, ...extra });
-  if (game && !existsSync(join(root, 'games', game, 'game.json'))) return fail(`there is no game "${game}" in this studio (${listGames(root).map((g) => g.id).join(', ') || 'it has none yet'})`);
+  if (game && !existsSync(experienceFile(root, game))) return fail(`there is no game "${game}" in this studio (${listGames(root).map((g) => g.id).join(', ') || 'it has none yet'})`);
   let got;
   try { got = await fetchPart(refText, { fetch }); } catch (error) { return fail(error.message); }
   const { ref, part, files, version, base, entry } = got;
@@ -281,14 +281,15 @@ export function sharePart(root, id, on = true) {
   const packed = packPart(root, id);
   if (!packed.ok) { part.share = false; writePart(dir, part); return { ...packed, command }; }
   const lic = licenseOfPart(part.license);
-  return { ok: true, command, id, share: true, version: part.version, license: lic.id, asks: lic.asks, files: part.files.length, bytes: part.cost?.bytes ?? 0, ...(part.from?.game ? { from: part.from } : {}), effect: 'It is live after the studio\'s next deploy, not before: nothing was uploaded now. Sharing a part does not list the studio in the directory.' };
+  return { ok: true, command, id, share: true, version: part.version, license: lic.id, asks: lic.asks, files: part.files.length, bytes: part.cost?.bytes ?? 0, ...(part.from ? { from: part.from } : {}), effect: 'It is live after the studio\'s next deploy, not before: nothing was uploaded now. Sharing a part does not list the studio in the directory.' };
 }
 
 /* ------------------------------------------------------------------ find */
 
 const row = (p, extra) => ({
   id: p.id, name: p.name, kind: p.kind, version: p.version, summary: line(p.summary), license: p.license || null, tags: Array.isArray(p.tags) ? p.tags.slice(0, 12) : [],
-  from: isObj(p.from) ? { game: p.from.game ?? null, name: p.from.name ?? null, studio: p.from.studio ?? null, play: p.from.play ?? null } : null,
+  ...(Array.isArray(p.uses) ? { uses: p.uses } : {}),
+  from: isObj(p.from) ? { ...(p.from.app ? { app: p.from.app, open: p.from.open ?? null } : {}), ...(p.from.music ? { music: p.from.music } : {}), ...(p.from.video ? { video: p.from.video } : {}), game: p.from.game ?? null, name: p.from.name ?? null, studio: p.from.studio ?? null, play: p.from.play ?? null } : null,
   cost: isObj(p.cost) ? p.cost : {}, requires: isObj(p.requires) ? p.requires : {}, rig: p.skeleton?.rig ?? null, netplay: p.contract?.netplay ?? null, ...extra,
 });
 function matches(p, { words, kind, tag, license, builds }) {
@@ -297,7 +298,7 @@ function matches(p, { words, kind, tag, license, builds }) {
   if (license && String(p.license ?? '').toLowerCase() !== String(license).toLowerCase()) return false;
   // What a part builds on: a package it names, or the skeleton it is made for.
   if (builds && !(Object.keys(p.requires?.packages && typeof p.requires.packages === 'object' ? p.requires.packages : {}).includes(builds) || p.rig === builds)) return false;
-  const hay = [p.id, p.name, p.kind, p.summary, ...(p.tags ?? []), p.from?.name, p.from?.game, p.from?.studio].filter(Boolean).join(' ').toLowerCase();
+  const hay = [p.id, p.name, p.kind, p.summary, ...(p.tags ?? []), p.from?.name, p.from?.game, p.from?.app, p.from?.music, p.from?.video, ...(p.uses ?? []), p.from?.studio].filter(Boolean).join(' ').toLowerCase();
   return words.every((w) => hay.includes(w));
 }
 

package/lib/parts-tools.mjs

@@ -51,22 +51,22 @@ export function partsToolDefs(ctx, h) {
       },
     },
     {
-      name: 'part_new', title: 'Make a game part',
-      description: 'Make a part of this studio: a piece of one of its games that another game can use. With from (a game\'s id) and files (paths inside that game: a module or a folder), the files are LIFTED out of the game into parts/<id>/ and the game imports them from there, so it builds and behaves as before; a file that still reaches into the rest of the game is refused by name (pass what it needs in as an argument first). Without from, an empty part to write. A part is a piece of a game, never the whole game, in whatever form suits it (code, assets, data, a tuned config). A new part is private. Offer this after building something reusable.',
-      inputSchema: { type: 'object', properties: { id: str('The part\'s id (lowercase, digits, hyphens): "chase-camera"'), kind: { type: 'string', enum: [...PART_KINDS], description: 'What kind of part (default mechanic)' }, name: str('Its name'), from: str('The game to lift it out of'), files: { type: 'array', items: { type: 'string' }, description: 'With from: paths inside games/<from>/ that become the part ("src/creature.ts", "src/cave")' }, ...STUDIO_ARG }, required: ['id'] },
-      annotations: { title: 'Make a game part', ...RW },
+      name: 'part_new', title: 'Make a shared part',
+      description: 'Make a part of this studio: a reusable piece of a game, app, music or video. With from (a game\'s id) and files (paths inside that game: a module or a folder), the files are LIFTED out of the game into parts/<id>/ and the game imports them from there, so it builds and behaves as before; a file that still reaches into the rest of the game is refused by name (pass what it needs in as an argument first). Without from, an empty part to write. A part is a reusable piece, never an entire experience, in whatever form suits it (code, assets, data, a tuned config). A new part is private. Offer this after building something reusable.',
+      inputSchema: { type: 'object', properties: { id: str('The part\'s id (lowercase, digits, hyphens): "chase-camera"'), kind: { type: 'string', enum: [...PART_KINDS], description: 'What kind of part (default mechanic)' }, name: str('Its name'), uses: { type: 'array', items: { type: 'string', enum: ['game', 'app', 'venue', 'cause', 'music', 'video'] } }, from: str('The game to lift it out of'), files: { type: 'array', items: { type: 'string' }, description: 'With from: paths inside games/<from>/ that become the part ("src/creature.ts", "src/cave")' }, ...STUDIO_ARG }, required: ['id'] },
+      annotations: { title: 'Make a shared part', ...RW },
       run: async (a) => {
         const root = ctx.root(a.studio);
-        const r = newPart(root, String(a.id ?? ''), { kind: a.kind ?? 'mechanic', name: a.name ?? null, from: a.from ? String(a.from) : null, paths: Array.isArray(a.files) ? a.files.map(String) : [] });
+        const r = newPart(root, String(a.id ?? ''), { kind: a.kind ?? 'mechanic', uses: a.uses, name: a.name ?? null, from: a.from ? String(a.from) : null, paths: Array.isArray(a.files) ? a.files.map(String) : [] });
         if (!r.ok) return fail(`No part was made: ${r.why}`, { kind: 'part', ...r });
         return ok([text(r), r.lifted ? `Build ${r.from} now and check it still plays the same.` : '', 'Fill in parts/' + r.id + '/part.json: a one-sentence summary, what it takes from a game ("contract"), and its costs if measured. It stays private until the person asks to share it (part_share).'].filter(Boolean).join('\n'), { kind: 'part', ...r });
       },
     },
     {
-      name: 'part_share', title: 'Share a game part',
+      name: 'part_share', title: 'Share a part',
       description: 'Share one of this studio\'s parts with other studios, or stop sharing it. Only when the person asked: a part is private until they say otherwise. It needs a licence the person picked (an SPDX identifier: CC0-1.0, CC-BY-4.0, MIT…; with license it is set here), who to credit when the licence asks, and known rights to every file: anything in the way is listed in plain words and nothing is shared. It is live after the studio\'s next deploy (studio_deploy), not before; stopping takes effect then too. With share left out it only checks and reports.',
       inputSchema: { type: 'object', properties: { id: str('The part\'s id'), share: { type: 'boolean', description: 'true: share it; false: stop sharing it; left out: only check what stands in the way' }, license: str('The licence the person picked, an SPDX identifier (set before sharing)'), attribution: str('Who a game using it should credit'), ...STUDIO_ARG }, required: ['id'] },
-      annotations: { title: 'Share a game part', ...RW },
+      annotations: { title: 'Share a part', ...RW },
       run: async (a) => {
         const root = ctx.root(a.studio);
         const id = String(a.id ?? '');