@homie-rocks/studio 0.36.0 → 0.37.1

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).
@@ -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

@@ -31,6 +31,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { registerWorkersAddress } from './domain.mjs';
 import { cloudflareAuth } from './brain-probe.mjs';
 import { build } from './build.mjs';
 import { builtGames, compareDeploy, deployWords, lastDeploy, lastDeployRecord, lockDeploy, recordDeploy } from './deploy-state.mjs';
@@ -40,7 +41,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;
@@ -93,10 +94,10 @@ export function explainCloudflare(out, accountId = null) {
   const text = String(out ?? '');
   const dash = accountId ? `https://dash.cloudflare.com/${accountId}` : 'https://dash.cloudflare.com';
   if (/\b10034\b|verify your email/i.test(text)) {
-    return { needs: 'cloudflare-verify-email', why: `Cloudflare needs this account's email address verified before it runs a Worker. Ask the person to open the verification email from Cloudflare (or ${dash}/profile and "Send verification email"), click it, then run \`npm run deploy\` again. No payment method is needed.` };
+    return { needs: 'cloudflare-verify-email', why: `Cloudflare needs this account's email address verified before it runs a Worker. Ask the person to open the verification email from Cloudflare (or ${dash}/profile and "Send verification email"), click it. The AI resumes deployment after verification.` };
   }
   if (/register a workers\.dev subdomain|workers\/onboarding/i.test(text)) {
-    return { needs: 'workers-dev-subdomain', why: `This Cloudflare account has no workers.dev address yet. Ask the person to open ${dash}/workers/onboarding once and pick one (it is free), then run \`npm run deploy\` again.` };
+    return { needs: 'workers-dev-subdomain', why: `This Cloudflare account has no workers.dev address yet. AI: retry deploy to register it automatically through the existing sign-in. If Cloudflare refuses, open ${dash}/workers/onboarding and handle the setting in the browser; the person only handles provider authorization.` };
   }
   if (/maximum number of (D1 )?databases|database limit|too many databases/i.test(text)) {
     return { needs: 'd1-limit', why: 'This Cloudflare account has used all the D1 databases its plan allows (10 on the free plan). Nothing was deployed. Ask the person which unused database of theirs to remove, or use another account; never delete one yourself.' };
@@ -366,7 +367,15 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   }
 
   const started = Date.now();
-  const dep = w(['deploy', ...repoVar(root)]);
+  let dep = w(['deploy', ...repoVar(root)]);
+  if (dep.code !== 0 && explainCloudflare(dep.out, accountId)?.needs === 'workers-dev-subdomain') {
+    const headers = await cloudflareAuth({ env: { ...process.env, ...projectsCloudflareEnv(root) }, bin: wranglerBin(root), cwd: root,
+      exec: async (_bin, args) => { const r = w(args, { cwd: root }); return { code: r.code, stdout: r.stdout }; } });
+    const address = await registerWorkersAddress({ accountId, slug: studio.slug, headers, ...(fetchFn ? { fetchFn } : {}) });
+    if (!address.ok) return { ok: false, command: 'deploy', needs: 'workers-dev-subdomain', why: address.next };
+    step(address.created ? 'registered the account’s workers.dev address automatically' : 'kept the account’s existing workers.dev address');
+    dep = w(['deploy', ...repoVar(root)]);
+  }
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
   remember(`worker:${cf.worker}`);
   // The workers.dev address names the Cloudflare account (often after its owner): it stays on this computer, in

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';
@@ -192,7 +192,7 @@ export async function setupStatus({
   rows.push({
     id: 'node', label: 'Node.js', need: 'required', state: major >= 22 ? 'ok' : 'missing', detail: `v${node}${major >= 22 ? '' : ' (22 or newer is needed)'}`,
     unlocks: 'everything: the studio\'s toolkit runs on it',
-    fix: major >= 22 ? null : { who: 'person', open: 'https://nodejs.org/en/download', say: 'Install Node.js 22 or newer (the LTS download), then start a new session.' },
+    fix: major >= 22 ? null : { who: 'ai', say: 'Call setup_prepare in the Desktop extension; with a shell, install Node.js 22 or newer for this computer and continue setup. The person never runs a command.' },
   });
 
   // The Homie connector (the AI says; the network is checked here), Cloudflare, GitHub and the providers, at once.
@@ -318,15 +318,15 @@ export async function setupStatus({
       { label: 'email verified', state: verified, detail: deployed ? 'a deploy went through' : verified === 'act' ? 'the last deploy was refused until it is' : 'Cloudflare checks it at the first deploy' },
     ];
     const fix = attached ? null : signedIn === 'act'
-      ? { who: 'ai', run: 'npx wrangler login', say: 'Cloudflare opens in your browser: approve once. A free account works; no payment method.', open: 'https://dash.cloudflare.com/sign-up' }
+      ? { who: 'ai', run: 'npx wrangler login', say: 'Cloudflare opens in your browser: approve once.', open: 'https://dash.cloudflare.com/sign-up' }
       : verified === 'act'
-        ? { who: 'person', open: 'https://dash.cloudflare.com/profile', say: 'Open the email Cloudflare sent and click its link (or Profile, "Send verification email"); then deploy again.' }
+        ? { who: 'person', open: 'https://dash.cloudflare.com/profile', say: 'Open the email Cloudflare sent and click its link (or Profile, "Send verification email"); your AI resumes deployment.' }
         : signedIn === 'later' || verified === 'later'
-          ? { who: 'person', open: 'https://dash.cloudflare.com/sign-up', say: 'No Cloudflare account yet? Make a free one now (no payment method) and click the link in the email it sends. Your AI signs in for you later; you approve once.' }
+          ? { who: 'ai', say: 'Continue making the studio. When it is ready to go live, call cloudflare_login; the person signs in or creates an account in that browser flow.' }
           : null;
     rows.push({
       id: 'cloudflare', label: 'Cloudflare', need: 'to go online', state: worst(parts.map((p) => p.state)), detail: parts.map((p) => `${p.label}: ${p.detail}`).join('; '), parts,
-      unlocks: 'putting the studio\'s site and public rooms online, on its own free Cloudflare account', fix,
+      unlocks: 'putting the studio\'s site and public rooms online, on its own Cloudflare account', fix,
     });
   }
 
@@ -357,7 +357,7 @@ export async function setupStatus({
       unlocks: 'sound effects and a synthesized theme (free, on this computer), trailers, and footage in a landing page\'s hero',
       fix: ok ? null : mac ? { who: 'ai', run: 'brew install ffmpeg', say: 'about a minute with Homebrew; you approve the install.' }
         : win ? { who: 'ai', run: 'winget install --id Gyan.FFmpeg -e', say: 'you approve the install.' }
-          : { who: 'person', say: 'Install your system\'s ffmpeg package (for example: sudo apt-get install -y ffmpeg).' },
+          : { who: 'ai', run: 'sudo apt-get install -y ffmpeg', say: 'Install ffmpeg with this system’s package manager; only an OS authorization prompt belongs to the person.' },
     });
   }
 
@@ -398,7 +398,7 @@ export async function setupStatus({
     id: 'fal', label: 'fal', need: 'optional', state: fal.key ? (fal.valid === false ? 'act' : 'ok') : 'optional',
     detail: !fal.key ? 'no FAL_KEY in this environment' : fal.valid === true ? 'FAL_KEY is set and fal accepts it' : fal.valid === false ? 'fal refused the FAL_KEY that is set (wrong or revoked)' : 'FAL_KEY is set (fal did not answer just now)',
     unlocks: 'painted art and backdrops (the art skill) and generated video clips (the video skill), on your own fal account under a budget; covers from a real frame and captured trailers are free',
-    fix: fal.key && fal.valid !== false ? null : { who: 'person', open: 'https://fal.ai/dashboard/keys', say: 'Make a key, put FAL_KEY in the environment your AI runs in (for example a line in your shell profile), and start a new session. Never paste it into the chat.' },
+    fix: fal.key && fal.valid !== false ? null : { who: 'ai', say: 'Use local art and captured footage. Paid fal scripts need an already connected account; never ask the person to find or set a key. Offer the provider browser connection only when generated media is requested.', open: 'https://fal.ai/dashboard' },
   });
 
   // Stripe, only in a studio that sells. Installing agent tooling is not proof of Worker credentials.

package/lib/domain.mjs

@@ -0,0 +1,43 @@
+/** Configure one requested hostname. Wrangler creates its DNS and TLS on deploy using OAuth.
+ * No zone ids or DNS values pass through the person. Existing unrelated routes stay intact.
+ */
+import { writeFileSync } from 'node:fs';
+import { readConfig, routesOf } from './routes.mjs';
+import { configPath, readStudio, writeStudio } from './studio.mjs';
+
+export function studioDomain(root, hostname) {
+  const host = String(hostname ?? '').trim().toLowerCase();
+  if (host.length > 253 || !host.includes('.') || !host.split('.').every((p) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(p)) || host.endsWith('.workers.dev')) {
+    return { ok: false, next: 'AI: use the requested domain hostname alone, for example play.example.com.' };
+  }
+  const config = readConfig(root);
+  if (!config) return { ok: false, next: 'AI: repair the studio’s Wrangler configuration, then retry studio_domain.' };
+  const routes = routesOf(config);
+  if (!routes.some((r) => r.pattern === host && r.custom_domain === true)) routes.push({ pattern: host, custom_domain: true });
+  const studio = readStudio(root);
+  writeFileSync(configPath(root), `${JSON.stringify({ ...config, routes }, null, 2)}\n`);
+  writeStudio(root, { ...studio, cloudflare: { ...studio.cloudflare, domain: host } });
+  return { ok: true, host, next: 'AI: run studio_deploy with plan: true, then deploy within the person’s request. Cloudflare creates DNS and TLS with the existing sign-in. If the zone is not active on this account, keep the current live address and help connect the domain in the browser.', open: 'https://dash.cloudflare.com/?to=/:account/domains' };
+}
+
+/** A first deploy may need the account's workers.dev name. Never rename an existing one. */
+export async function registerWorkersAddress({ accountId, slug = 'studio', headers, fetchFn = fetch } = {}) {
+  const next = 'AI: retry Cloudflare sign-in with cloudflare_login, then deploy again.';
+  if (!headers || !accountId) return { ok: false, next };
+  const url = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/workers/subdomain`;
+  try {
+    const old = await fetchFn(url, { headers, signal: AbortSignal.timeout(15_000) });
+    const body = await old.json();
+    if (old.ok && body.success !== false && body.result?.subdomain) return { ok: true, created: false };
+    if (old.status !== 404 && !(old.ok && body.success !== false && !body.result?.subdomain)) return { ok: false, next, status: old.status };
+    // Stable, unguessable from the account name, and no choice of a technical setting for the person.
+    const { createHash } = await import('node:crypto');
+    const stem = String(slug).toLowerCase().replace(/[^a-z0-9-]/g, '').replace(/^-+|-+$/g, '').slice(0, 40) || 'studio';
+    const suffix = createHash('sha256').update(accountId).digest('hex').slice(0, 10);
+    const res = await fetchFn(url, { method: 'PUT', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({ subdomain: `${stem}-${suffix}` }), signal: AbortSignal.timeout(15_000) });
+    const made = await res.json();
+    return res.ok && made.success !== false && made.result?.subdomain
+      ? { ok: true, created: true }
+      : { ok: false, status: res.status, next: 'AI: open https://dash.cloudflare.com/?to=/:account/workers-and-pages and resolve the account address with the existing sign-in, then retry deploy. Do not ask the person for a setting or id.' };
+  } catch { return { ok: false, next: 'AI: retry deploy when Cloudflare is reachable; no account setting was confirmed.' }; }
+}

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}$/;