@homie-rocks/studio 0.48.4 → 0.50.0

package/lib/build.mjs

@@ -487,7 +487,7 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
     digest.update(readFileSync(join(out, 'index.html')));
     rules.build = digest.digest('hex').slice(0, 32);
     writeFileSync(join(out, 'rules.json'), `${JSON.stringify({ v: 1, host: rules.settings.host, offline: rules.settings.offline, build: rules.build, files: [bundled, ...chunks] })}\n`);
-    if (g.netplay?.version !== undefined) log(`  ${g.id}: rules games use their build hash as the revision; netplay.version is not read`);
+    if (g.netplay?.version !== undefined) log(`  ${g.id}: rules ${g.kind === 'app' ? 'apps' : 'games'} use their build hash as the revision; netplay.version is not read`);
   }
   return { mode, warnings, metafile, bundle: bundled, chunks, rules };
 }
@@ -572,7 +572,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
       ...(bundle ? { bundle } : {}), ...(chunks.length ? { chunks: chunks.length, chunkBytes: later } : {}),
     });
     log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB${chunks.length ? ` + ${chunks.length} additional ${chunks.length === 1 ? 'chunk' : 'chunks'}, ${Math.max(1, Math.round(later / 1024))} KB` : ''})`);
-    if (rules && (rules.settings.offline || rules.settings.host === 'browser')) log(`${g.id}: this game's rules and tunables are sent to players' devices so it can be played offline`);
+    if (rules && (rules.settings.offline || rules.settings.host === 'browser')) log(`${g.id}: this ${g.kind === 'app' ? 'app' : 'game'}'s rules and tunables are sent to players' devices so it can be played offline`);
     if (rules) log(`  ${g.id}: its rules run ${rules.settings.host === 'browser' ? "in a player's browser" : 'on the server'} (checked and guarded, ${Math.max(1, Math.round(rules.code.length / 1024))} KB, build ${rules.build}; ${rules.check.ticks} ticks played, the room rebuilt from its save ${rules.check.restores} times: the busiest tick used ${rules.tickUnits} of ${rules.settings.budget.tick} budget units, ${rules.units} of them in one handler; the largest save was ${rules.check.largestSaveBytes} bytes)`);
     if (rules && rules.settings.host === 'server' && (rules.snapshotBytes > rules.snapshotCap || rules.checkpointBytes > rules.checkpointCap)) log(`  ${g.id}: this state fits server and offline play but exceeds browser hosting limits.`);
     if (rules) log(`  ${g.id}: smoke-run largest snapshot ${rules.snapshotBytes} B / ${rules.snapshotCap} B browser cap; checkpoint ${rules.checkpointBytes} B / ${rules.checkpointCap} B browser cap (measured, not an upper bound)`);
@@ -688,7 +688,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   const lounge = loungeConfig(studio, rows, { audience: audienceOf(studio) });
   const catalogue = {
     studio: {
-      name: studio.name, slug: studio.slug, version: STUDIO_VERSION,
+      name: studio.name, slug: studio.slug, version: STUDIO_VERSION, ...(studio.kind ? { kind: studio.kind } : {}),
       ...(typeof studio.tagline === 'string' && studio.tagline.trim() ? { tagline: studio.tagline.trim().slice(0, 140) } : {}),
       theme,
       // studio.json "site": { "schema": { … } }: the owner's own schema.org properties on the studio (sameAs, …).
@@ -727,6 +727,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     // shop.json, checked (nothing secret is ever in it): the Worker sells from this and checks it again.
     ...(shop ? { shop } : {}),
   };
+  for (const app of rows.filter(g => g.kind === 'app' && site.pages.includes(`/${g.id}/`))) log(`site/pages/${app.id}/ replaces the app landing; open /${app.id}/open and wall /${app.id}/tv`);
   for (const game of rows) {
     const image = await playerImage(catalogue, game, dist, log);
     if (image) game.playerImage = image;
@@ -760,6 +761,6 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     ...(retired.length ? { retired: `Remix was retired, and games now build on each other through parts (pieces a studio shares; ask for a part, or see parts/PARTS.md). These settings no longer do anything and can be deleted: ${retired.join('; ')}. No game's source is served whole; a game made from another keeps its credit.` } : {}),
     songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped, mediaNotes: media.notes ?? [],
     posts: posts.map((p) => p.slug), postsSkipped, codexes, parts: partsBuilt, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
-    landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length) })),
+    landings: rows.map((g) => ({ id: g.id, ...(g.kind === 'app' ? { kind: 'app' } : {}), hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length) })),
   };
 }

package/lib/check-site.mjs

@@ -16,7 +16,7 @@ import { once } from 'node:events';
 import { createServer } from 'node:net';
 import { fileURLToPath } from 'node:url';
 import { runningDev } from './dev.mjs';
-import { listGames, siteUrl } from './studio.mjs';
+import { listExperiences, siteUrl } from './studio.mjs';
 
 const CLI = fileURLToPath(new URL('../bin/homie-studio.mjs', import.meta.url));
 
@@ -64,16 +64,16 @@ export async function checkSite(root, { url = null, live = false, log = () => {}
 export function changedGames(root, { run = spawnSync } = {}) {
   const git = (...args) => { const r = run('git', args, { cwd: root, encoding: 'utf8' }); return r.status === 0 ? String(r.stdout) : null; };
   if (git('rev-parse', '--is-inside-work-tree') === null) return [];
-  const files = new Set((git('status', '--porcelain', '--', 'games') ?? '').split('\n').map((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> ').pop()).filter(Boolean));
+  const files = new Set((git('status', '--porcelain', '--', 'games', 'apps') ?? '').split('\n').map((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> ').pop()).filter(Boolean));
   const head = (git('symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD') ?? '').trim();
   for (const base of [head, 'origin/main', 'main', 'origin/master', 'master'].filter(Boolean)) {
     const fork = (git('merge-base', 'HEAD', base) ?? '').trim();
     if (!fork) continue;
-    for (const f of (git('diff', '--name-only', `${fork}..HEAD`, '--', 'games') ?? '').split('\n')) if (f) files.add(f);
+    for (const f of (git('diff', '--name-only', `${fork}..HEAD`, '--', 'games', 'apps') ?? '').split('\n')) if (f) files.add(f);
     break;
   }
-  const touched = new Set([...files].map((f) => /^games\/([^/]+)\//.exec(f)?.[1]).filter(Boolean));
-  return listGames(root).map((g) => g.id).filter((id) => touched.has(id));
+  const touched = new Set([...files].map((f) => /^(?:games|apps)\/([^/]+)\//.exec(f)?.[1]).filter(Boolean));
+  return listExperiences(root).map((g) => g.id).filter((id) => touched.has(id));
 }
 
 /** The games a check covers: the one named, else what changed, else all of them. */
@@ -81,5 +81,5 @@ export function gamesToCheck(root, named, options) {
   if (named) return { games: [named], why: 'named' };
   const changed = changedGames(root, options);
   if (changed.length) return { games: changed, why: 'changed in this checkout' };
-  return { games: listGames(root).map((g) => g.id), why: 'nothing changed against the default branch: every game' };
+  return { games: listExperiences(root).map((g) => g.id), why: 'nothing changed against the default branch: every game' };
 }

package/lib/check.mjs

@@ -1,3 +1,4 @@
+import { readAppNeeds, proveAppNeeds, saveAppNeeds } from './app-needs.mjs';
 /**
  * `homie-studio check [<game>] [--url <site> | --live]` — the promise, measured (where it runs and on which games
  * when nobody says: lib/check-site.mjs; never the live site unless asked): two fresh
@@ -127,7 +128,7 @@ export function judgeRounds(browsers, missed = new Map()) {
   return null;
 }
 
-export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
+export async function check({ root = null, url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
   if (!url || !game) throw new Error('usage: homie-studio check <game> --url <site url>');
   const base = String(url).replace(/\/+$/, '');
   const play = `${base}/${game}/play`;
@@ -148,7 +149,7 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
   if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
-  if (appMeta) return checkApp({ url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
+  if (appMeta) return checkApp({ root, url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
   if (shots) mkdirSync(shots, { recursive: true });
   const profiles = [];
   const browsers = [];
@@ -343,7 +344,9 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
 }
 
 /** 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 }) {
+export async function checkApp({ root = null, url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
+  let plan;
+  try { plan = readAppNeeds(root, game); } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
   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 });
@@ -381,9 +384,19 @@ export async function checkApp({ url, game, meta, shots = null, log = () => {},
     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 });
+    for (const s of surfaces) {
+      await s.page.waitForFunction(() => {
+        const cover = document.querySelector('[data-arrive]');
+        return window.__shell?.arrival?.phase === 'done' && (!cover || (getComputedStyle(cover).opacity === '0' && getComputedStyle(cover).visibility === 'hidden'));
+      }, { timeout: READY_TIMEOUT_MS });
+      await s.frame.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+      if (shots) await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 85 });
+    }
     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 };
+    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report }) : null;
+    if (plan) { saveAppNeeds(root, game, plan, needs); const { refreshCodexFile } = await import('./codex.mjs'); refreshCodexFile(root, game); }
+    const ok = !needs || needs.every(n => n.status === 'met');
+    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), 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/codex.mjs

@@ -68,6 +68,15 @@ export const SECTIONS = [
   { key: 'questions', title: 'Open questions', match: /^(open questions|questions|undecided|to decide)\b/i },
 ];
 
+export const APP_SECTIONS = [
+  { key: 'dream', title: 'Their words', match: /^their words|^dream/i },
+  { key: 'scene', title: 'Scene', match: /^scene/i },
+  { key: 'people', title: 'People and surfaces', match: /^people/i },
+  { key: 'offers', title: 'Offers', match: /^offers/i },
+  { key: 'needs', title: 'Needs', match: /^needs/i },
+  ...SECTIONS.filter(s => ['art','sound','milestones','questions'].includes(s.key)),
+];
+
 /* ------------------------------------------------------------------ parsing */
 
 /** A small YAML subset: `key: value`, quoted or bare, and one level of nested `key:` blocks or `{ a: b, c: d }`. */
@@ -130,7 +139,7 @@ export function parseCodex(source) {
     while (seen.has(id)) id = `${id}-2`;
     seen.add(id);
     s.id = id;
-    s.key = SECTIONS.find((k) => k.match.test(s.title))?.key ?? (/^latest|^decisions|^changelog|^news/i.test(s.title) ? 'latest' : null);
+    s.key = [...SECTIONS, ...APP_SECTIONS].find((k) => k.match.test(s.title))?.key ?? (/^latest|^decisions|^changelog|^news/i.test(s.title) ? 'latest' : null);
   }
   return { meta, title, pitch: pitch.join('\n').trim(), sections };
 }
@@ -139,7 +148,7 @@ export function parseCodex(source) {
 export function codexGaps(parsed) {
   const has = (key) => parsed.sections.some((s) => s.key === key && s.body.join('\n').replace(/<!--[\s\S]*?-->/g, '').trim());
   const questions = parsed.sections.filter((s) => s.key === 'questions').flatMap((s) => s.body.filter((l) => /^\s*([-*+]|\d+[.)])\s+\S/.test(l)));
-  return { missing: SECTIONS.filter((s) => s.key !== 'questions' && !has(s.key)).map((s) => s.title), openQuestions: questions.length };
+  return { missing: (parsed.meta.kind === 'app' ? APP_SECTIONS : SECTIONS).filter((s) => s.key !== 'questions' && !has(s.key)).map((s) => s.title), openQuestions: questions.length };
 }
 
 /* ------------------------------------------------------------------ files from the studio */
@@ -303,6 +312,16 @@ ${stats.length ? `<dl class="stats">${stats.map(([k, v]) => `<dt>${esc(k)}</dt><
 }
 
 function sectionHtml(section, emb, ctx) {
+  if (section.key === 'needs') {
+    const source = section.body.join('\n');
+    const block = /^```needs\s*\n([\s\S]*?)^```/m.exec(source);
+    if (block) {
+      try {
+        const needs = JSON.parse(block[1]);
+        if (Array.isArray(needs)) return `<section class="tab" id="${esc(section.id)}" data-key="needs"><h2>${esc(section.title)}</h2>${renderMarkdown(source.replace(block[0], '')).html}<div class="cards">${needs.map(n => `<article class="card"><h3>${esc(n.id)}</h3><p>${esc(n.statement)}</p><p class="meta">${Array.isArray(n.assertions) && n.assertions.length ? 'To demonstrate on the wall and phone' : 'Not yet demonstrable'}</p></article>`).join('')}</div></section>`;
+      } catch { /* Keep malformed source visible for correction. */ }
+    }
+  }
   const intro = [];
   const cards = [];
   let current = null;
@@ -510,13 +529,13 @@ function lookOf(root, game, meta, emb) {
  * sit in games/<id>/ before its game.json does: then the "game" is that planned folder. `create`: a codex is being
  * started for an id with no folder yet.
  */
-function codexGame(root, id, { create = false } = {}) {
+function codexGame(root, id, { create = false, kind = null } = {}) {
   const game = listGames(root).find((g) => g.id === id);
   if (game) return game;
   if (!GAME_ID.test(String(id ?? ''))) return null;
-  const dir = join(experienceDir(root, id));
+  const dir = kind === 'app' ? join(root, 'apps', id) : 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;
+  return existsSync(join(dir, CODEX_FILE)) || create ? { id, dir, kind: dir === join(root, 'apps', id) ? 'app' : 'game', name: null, planned: true } : null;
 }
 
 /**
@@ -529,9 +548,10 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
   const game = codexGame(root, id);
   if (!game) throw new Error(`no game "${id}" in games/, and no codex planning it`);
   const file = join(game.dir, CODEX_FILE);
-  if (!existsSync(file)) throw new Error(`games/${id}/${CODEX_FILE} does not exist yet: npx --no-install homie-studio codex new ${id}`);
-  if (statSync(file).size > LIMITS.source) throw new Error(`games/${id}/${CODEX_FILE} is over ${LIMITS.source / 1024} KB`);
+  if (!existsSync(file)) throw new Error(`${relative(root, file)} does not exist yet: npx --no-install homie-studio codex new ${id}`);
+  if (statSync(file).size > LIMITS.source) throw new Error(`${relative(root, file)} is over ${LIMITS.source / 1024} KB`);
   const parsed = parseCodex(readFileSync(file, 'utf8'));
+  if (game.kind === 'app') parsed.meta.kind = 'app';
   const { meta } = parsed;
   let studio = {};
   try { studio = readStudio(root); } catch { studio = {}; }
@@ -555,7 +575,17 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
   tabs.splice(sections[0]?.key === 'latest' ? 1 : 0, 0, statusTab);
   const cover = typeof meta.cover === 'string' ? emb.image(meta.cover) : null;
   const pitch = parsed.pitch ? renderMarkdown(parsed.pitch).html : (game.blurb ? `<p>${esc(game.blurb)}</p>` : '');
-  const body = sections.map((x) => sectionHtml(x, emb, ctx)).join('\n');
+  const needReportFile = join(root, '.studio', 'checks', `${id}-needs.json`);
+  let needStatus = '';
+  if (game.kind === 'app' && existsSync(needReportFile)) {
+    try {
+      const r = JSON.parse(readFileSync(needReportFile, 'utf8'));
+      const stale = r.codexHash !== createHash('sha256').update(readFileSync(file, 'utf8')).digest('hex');
+      tabs.push('<a href="#needs-status">Needs status</a>');
+      needStatus = `<section class="tab" id="needs-status"><h2>Needs status</h2><p>${stale ? 'Plan changed: this evidence is stale; check again. ' : ''}Checked ${esc(r.at)}. Screen assertions are evidence; review the captures against Their words.</p>${r.needs.map(n => `<article><h3>${esc(n.statement)}</h3><p><strong>${stale ? 'not yet rechecked' : esc(n.status)}</strong> — ${esc(n.why ?? '')}</p>${(n.captures ?? []).map(p => figure(emb, n.statement, relative(root, resolve(root, p)), p)).join('')}</article>`).join('')}</section>`;
+    } catch { /* The next check repairs an incomplete receipt. */ }
+  }
+  const body = needStatus + sections.map((x) => sectionHtml(x, emb, ctx)).join('\n');
   const status = statusHtml(s, ctx);
   const start = s?.state === 'running' ? 'build-status' : (sections[0]?.id ?? 'build-status');
   const tagline = typeof meta.tagline === 'string' ? meta.tagline : '';
@@ -567,13 +597,13 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="robots" content="noindex, nofollow">
-<title>${esc(title)} · Game Codex</title>
+<title>${esc(title)} · ${game.kind === 'app' ? 'App' : 'Game'} Codex</title>
 ${look.links.map((href) => `<link rel="stylesheet" href="${esc(href)}">`).join('\n')}
 <style>${look.faces.join('')}${css(look.palette, look.fonts, ctx.pixel)}</style>
 </head>
 <body data-mode="${esc(mode)}" data-start="${esc(start)}"${ctx.pixel ? ' class="pixel"' : ''}>
 <header class="hero">${cover ? `<div class="bgimg" style="background-image:url(${cover})"></div>` : ''}<div class="wrap">
-<p class="kicker">Game Codex · ${esc(studio.name ?? '')}</p>
+<p class="kicker">${game.kind === 'app' ? 'App' : 'Game'} Codex · ${esc(studio.name ?? '')}</p>
 <h1>${esc(title)}</h1>
 ${tagline ? `<p class="tagline">${esc(tagline)}</p>` : ''}
 ${pitch ? `<div class="pitch">${pitch}</div>` : ''}
@@ -583,12 +613,12 @@ ${pitch ? `<div class="pitch">${pitch}</div>` : ''}
 ${body}
 ${status}
 </main>
-<footer>Game Codex for ${esc(title)}: the plan your AI keeps true as decisions change. Source: games/${esc(id)}/${CODEX_FILE}. Drawn ${esc(now.toISOString().slice(0, 16).replace('T', ' '))} UTC. Made with Homie.</footer>
+<footer>${game.kind === 'app' ? 'App' : 'Game'} Codex for ${esc(title)}: the plan your AI keeps true as decisions change. Source: ${esc(relative(root, file))}. Drawn ${esc(now.toISOString().slice(0, 16).replace('T', ' '))} UTC. Made with Homie.</footer>
 <script>${CODEX_SCRIPT}</script>
 </body>
 </html>
 `;
-  return { html, title, sections: sections.map((x) => ({ id: x.id, title: x.title, key: x.key })), missing: gaps.missing, openQuestions: gaps.openQuestions, warnings: emb.warnings, build: s ? { state: s.state, percent: s.percent } : null };
+  return { html, kind: game.kind ?? 'game', title, sections: sections.map((x) => ({ id: x.id, title: x.title, key: x.key })), missing: gaps.missing, openQuestions: gaps.openQuestions, warnings: emb.warnings, build: s ? { state: s.state, percent: s.percent } : null };
 }
 
 /** `homie-studio codex <id>`: the page on this computer (or the artifact copy). */
@@ -598,7 +628,7 @@ export function writeCodexPage(root, id, { mode = 'file' } = {}) {
   mkdirSync(dir, { recursive: true });
   const file = join(dir, mode === 'artifact' ? `${id}.artifact.html` : `${id}.html`);
   writeFileSync(file, r.html);
-  return { ok: true, command: 'codex', id, mode, file: relative(root, file), path: file, bytes: Buffer.byteLength(r.html), title: r.title, sections: r.sections, missing: r.missing, openQuestions: r.openQuestions, warnings: r.warnings, build: r.build };
+  return { ok: true, command: 'codex', kind: r.kind, id, mode, file: relative(root, file), path: file, bytes: Buffer.byteLength(r.html), title: r.title, sections: r.sections, missing: r.missing, openQuestions: r.openQuestions, warnings: r.warnings, build: r.build };
 }
 
 /** Called whenever a progress feed changes: the local page redraws itself (only when it exists already). */
@@ -632,21 +662,21 @@ export function buildCodexPages(root, dist, ids, { log = () => {} } = {}) {
 /* ------------------------------------------------------------------ a new codex */
 
 /** `homie-studio codex new <id>`: CODEX.md with every section, its look taken from the game and the studio. */
-export function newCodex(root, id, { name = null } = {}) {
+export function newCodex(root, id, { name = null, kind = null } = {}) {
   // A game is planned before it is made: with no game of this id, the codex starts its folder (games/<id>/CODEX.md),
   // and `game new <id>` later makes the game around it.
-  const game = codexGame(root, id, { create: true });
+  const game = codexGame(root, id, { create: true, kind });
   if (!game) return { ok: false, command: 'codex new', why: `"${id}" is not a game id (lowercase letters, digits and hyphens, up to 40)` };
   if (game.planned) { game.name = name ? String(name).slice(0, 60) : id.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' '); mkdirSync(game.dir, { recursive: true }); }
   const file = join(game.dir, CODEX_FILE);
-  if (existsSync(file)) return { ok: false, command: 'codex new', why: `games/${id}/${CODEX_FILE} exists already: change it, never replace it` };
+  if (existsSync(file)) return { ok: false, command: 'codex new', why: `${relative(root, file)} exists already: change it, never replace it` };
   const theme = readTheme(root);
   const land = game.landing?.theme ?? {};
   const q = (v) => JSON.stringify(String(v));
   const cover = ['hero/wide.jpg', 'cover.jpg', 'cover.png', 'public/cover.jpg', 'public/cover.png'].find((p) => existsSync(join(game.dir, p)));
   const today = new Date().toISOString().slice(0, 10);
   const players = game.players ? `${game.players.min ?? 1} to ${game.players.max ?? 8}` : '1 to 8';
-  const text = `---
+  let text = `---
 tagline: ${q(game.blurb ?? '')}
 ${cover ? `cover: ${cover}\n` : ''}palette:
   bg: ${q(theme.bg ?? '#0b0c12')}
@@ -721,9 +751,56 @@ ${game.planned ? `- [ ] The plan (this codex)
 ## Open questions
 
 -
+`;
+  if (game.kind === 'app') text = `---
+kind: app
+tagline: ""
+try: "Open the wall and phone. Follow a real request through the scene."
+---
+# ${game.name ?? id}
+
+## Their words
+<!-- Quote the owner's request. Preserve their dream, not your implementation summary. -->
+
+## Scene
+<!-- Walking in: what is on the wall, what moves/fills/arrives/lights up, how it feels. -->
+
+## People and surfaces
+<!-- Each person, what they must do, and what wall, phone, staff and kiosk show them. -->
+
+## Offers
+<!-- What is sold or given, price and currency, once/monthly, and what payment fulfils. -->
+
+## Needs
+<!-- Each statement is observable on a real screen. Fill this executable needs block.
+Each need: id, statement, steps (surface wall/phone/phone-two; click/fill/select and selector/value),
+assertions (surface, selector, optional text). Include wall and phone assertions and real flow steps.
+A missing flow is reported not met. Do not replace an unmet need with an easier one. -->
+\`\`\`needs
+[]
+\`\`\`
+
+## Art direction
+<!-- Run style init with the owner's words. Composition, materials, typography and motion. -->
+
+## Music and sound
+<!-- Useful cues, silent wall by default, local synthesis or connected providers. -->
+
+## Built from
+<!-- Engine packages, parts_find results and provenance, original work and media routes. -->
+
+## Milestones
+- [ ] Their dream captured
+- [ ] Their scene and workflows running
+- [ ] Every need demonstrated on wall and phone and visually reviewed
+
+## Latest
+- ${today}: Planned from the person's request. Starter plumbing is not completion.
+
+## Open questions
 `;
   writeFileSync(file, text);
-  return { ok: true, command: 'codex new', id, file: relative(root, file), planned: Boolean(game.planned), next: [`fill it from the request and sensible defaults (interview only when asked), then: npx --no-install homie-studio codex ${id}`, ...(game.planned ? [`after recording those defaults: npx --no-install homie-studio game new ${id} --from gem-rush --name "<Name>" makes the game around it (the codex stays)`] : [])] };
+  return { ok: true, command: 'codex new', id, file: relative(root, file), planned: Boolean(game.planned), next: [`fill it from the request and sensible defaults (interview only when asked), then: npx --no-install homie-studio codex ${id}`, ...(game.planned ? [`after recording those defaults: npx --no-install homie-studio ${game.kind === 'app' ? 'app' : 'game'} new ${id} --from ${game.kind === 'app' ? 'welcome' : 'gem-rush'} --name "<Name>" makes the game around it (the codex stays)`] : [])] };
 }
 
 /** A sign-in link that opens one game's codex on the live site (the stats page's one-time sign-in, then the codex). */

package/lib/decisions.mjs

@@ -16,7 +16,7 @@
  * games/<id>/style.json (public, tiny) carries the palette and fonts a game, its landing and its title cards draw with.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { relative, 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';
@@ -39,7 +39,8 @@ export function contextOf(root, id, { prompt = '' } = {}) {
   let codex = '';
   try { codex = readFileSync(join(dir, 'CODEX.md'), 'utf8').replace(/<!--[\s\S]*?-->/g, ''); } catch { codex = ''; }
   let game = {};
-  try { game = JSON.parse(readFileSync(join(dir, 'game.json'), 'utf8')); } catch { game = {}; }
+  try { game = JSON.parse(readFileSync(experienceFile(root, id), 'utf8')); } catch { game = {}; }
+  const kind = existsSync(join(dir, 'app.json')) || /^kind: app$/m.test(codex) ? 'app' : 'game';
   const fm = /^---\n([\s\S]*?)\n---/.exec(codex)?.[1] ?? '';
   const pal = {};
   for (const k of [...PALETTE_KEYS, 'panel']) { const m = new RegExp(`^\\s+${k}:\\s*"?(#[0-9a-fA-F]{3,6})"?`, 'm').exec(fm); if (m) pal[k] = m[1]; }
@@ -50,9 +51,9 @@ export function contextOf(root, id, { prompt = '' } = {}) {
   for (const [key, re] of [['characters', '(?:characters|cast|heroes|creatures|enemies)'], ['items', '(?:items|props|pickups|collectibles)'], ['places', '(?:world|places|setting|zones?|levels?)']]) {
     for (const m of section(re).matchAll(/^###\s+(.+?)\s*$/gm)) cards.push({ section: key, title: clean(m[1], 60) });
   }
-  const words = [prompt, game.name, game.blurb, section('(?:concept|the game|pitch|overview)'), section('(?:art|look|style|visual)'), section('(?:world|setting)')].filter(Boolean).join(' \n ');
+  const words = [prompt, game.name, game.blurb, section('(?:concept|the game|pitch|overview)'), section('(?:art|look|style|visual)'), section('(?:world|setting)'), ...(kind === 'app' ? [section('(?:their words|dream)'), section('scene'), section('people')] : [])].filter(Boolean).join(' \n ');
   const score = (re) => (words.match(new RegExp(re.source, 'gi')) ?? []).length;
-  const genre = Object.entries(GENRES).map(([g, v]) => [g, score(v.words)]).filter(([, n]) => n).sort((a, b) => b[1] - a[1])[0]?.[0] ?? 'party';
+  const genre = kind === 'app' ? 'app' : Object.entries(GENRES).map(([g, v]) => [g, score(v.words)]).filter(([, n]) => n).sort((a, b) => b[1] - a[1])[0]?.[0] ?? 'party';
   const mood = Object.fromEntries(Object.entries(MOODS).map(([m, re]) => [m, score(re)]));
   let theme = {};
   try { theme = readTheme(root); } catch { theme = {}; }
@@ -76,7 +77,7 @@ export function contextOf(root, id, { prompt = '' } = {}) {
     const hs = assets.filter((a) => a.kind === 'character' && Number(a.measured?.heightM) > 0).map((a) => Number(a.measured.heightM)).sort((a, b) => a - b);
     if (hs.length) castHeightM = Math.round(hs[Math.floor(hs.length / 2)] * 100) / 100;
   } catch { clipVerbs = []; }
-  return { id, prompt: clean(prompt, 600), words, score, genre, mood, codexPalette: pal, codexFonts: fonts, theme, cards, players: Number(game.players?.max ?? game.netplay?.maxPlayers ?? 8) || 8, name: game.name ?? id, codexArt: clean(section('(?:art|look|style|visual)'), 400), drawn, clipVerbs, castHeightM };
+  return { id, kind, prompt: clean(prompt, 600), words, score, genre, mood, codexPalette: pal, codexFonts: fonts, theme, cards, players: Number(game.players?.max ?? game.netplay?.maxPlayers ?? 8) || 8, name: game.name ?? id, codexArt: clean(section('(?:art|look|style|visual)'), 400), drawn, clipVerbs, castHeightM };
 }
 
 /** The best match in a preset table by word score: [key, score] or null. */
@@ -356,7 +357,7 @@ function change(rec, patch, { by = 'ai', words = null, reason = null } = {}) {
 export function initDecisions(root, id, { prompt = '', path = null, budget = null } = {}) {
   gameDirOf(root, id);
   const ctx = contextOf(root, id, { prompt });
-  const doc = readDecisions(root, id) ?? { v: 1, scope: 'game', game: id, path: path ?? 'automatic', budget: null, prompt: '', decisions: {}, board: null, golden: [] };
+  const doc = readDecisions(root, id) ?? { v: 1, scope: ctx.kind, game: id, path: path ?? 'automatic', budget: null, prompt: '', decisions: {}, board: null, golden: [] };
   if (path) doc.path = path === 'hands-on' ? 'hands-on' : 'automatic';
   if (budget !== null && budget !== undefined) doc.budget = { usd: Math.max(0, Number(budget) || 0), provider: 'fal', approvedBy: 'the person, in chat', at: now() };
   if (prompt) doc.prompt = clean(prompt, 600);
@@ -367,6 +368,7 @@ export function initDecisions(root, id, { prompt = '', path = null, budget = nul
   const kept = [];
   const made = [];
   for (const [did] of CATALOGUE) {
+    if (ctx.kind === 'app' && !did.startsWith('style.')) continue;
     const def = CAT.get(did);
     const rec = doc.decisions[did];
     // Kept: anything the person steered or locked, anything pinned, and what a starter's style.json already draws.
@@ -380,7 +382,7 @@ export function initDecisions(root, id, { prompt = '', path = null, budget = nul
     made.push(did);
   }
   writeDecisions(root, id, doc);
-  return { ok: true, command: 'style init', id, picked: made, kept, genre: ctx.genre, summary: oneLine(doc), file: `games/${id}/${DECISIONS_FILE}` };
+  return { ok: true, command: 'style init', id, picked: made, kept, kind: ctx.kind, genre: ctx.genre, summary: oneLine(doc), file: relative(root, fileOf(root, id)) };
 }
 
 /** The one line the automatic path says: "Look: flat low-poly, autumn grove palette, high three-quarter camera". */

package/lib/dev.mjs

@@ -310,7 +310,7 @@ const builtIds = (root) => { try { return JSON.parse(readFileSync(join(root, 'si
  * options: port, remoteAi, localAi (false: --no-local-ai), timestamps (every line of Wrangler's gets a time), log.
  */
 export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi = false, localAi = true, timestamps = false, log = () => {}, watchMs = 2000 } = {}) {
-  const port = String(askedPort ?? 8787);
+  let port = String(askedPort ?? 8787);
   const stop = 'npx --no-install homie-studio dev --stop';
 
   // What is really there, before anything is built or started (the header: stale state heals itself).
@@ -327,7 +327,9 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
     const left = await clearLeftover(root, p);
     if (left.stopped.length) log(`Stopped a leftover local runtime of this studio on port ${p} (process ${left.stopped.join(', ')}): its dev server had been stopped another way.`);
     if (p === Number(port) && left.open) {
-      return { ok: false, command: 'dev', needs: 'port', why: `port ${port} is already in use by another program${left.foreign.length ? ` (process ${left.foreign.join(', ')})` : ''}, and it is not this studio's dev server, so nothing was stopped or started. Use another port: npx --no-install homie-studio dev --port ${Number(port) + 1}` };
+      const busy = port;
+      do { port = String(Number(port) + 1); } while (Number(port) < 65535 && await portOpen(Number(port)));
+      log(`Port ${busy} is busy; using http://127.0.0.1:${port}/`);
     }
   }
 

package/lib/doctor.mjs

@@ -297,7 +297,7 @@ export async function setupStatus({
         who: 'person',
         say: app === 'codex'
           ? 'In Codex, open /hooks and trust Homie\'s three hooks: Codex runs no plugin\'s hooks until you do. Then run this again. Until then nothing is held, so your AI asks you before each of those itself.'
-          : 'Grok runs a plugin\'s hooks only once the plugin is trusted, and only from a Homie plugin new enough to name them for Grok. Install it again with trust (grok plugin install homie-rocks/homie#plugins/homie --trust), start a new session (/hooks lists Homie\'s three), then run this again. Until then nothing is held, so your AI asks you before each of those itself.',
+          : 'Grok runs a plugin\'s hooks only once the plugin is trusted, and only from a Homie plugin new enough to name them for Grok. Ask your AI to install the Homie plugin in Grok and open its trust prompt (the AI runs grok plugin install homie-rocks/homie#plugins/homie --trust), start a new session (/hooks lists Homie\'s three), then run this again. Until then nothing is held, so your AI asks you before each of those itself.',
       },
     });
   }

package/lib/handoff.mjs

@@ -37,13 +37,18 @@ const line = (v, max) => String(v ?? '').replace(/[\x00-\x1f\x7f]+/g, ' ').repla
 const lines = (v, max) => String(v ?? '').split(/\r?\n/).map((l) => line(l, max)).filter(Boolean).join('\n').slice(0, max);
 
 /** The steps for a kind of build, in this toolkit's commands (the brief says what; these say how). */
-export function stepsFor(h, { games = [], client = 'chat' } = {}) {
+export function stepsFor(h, { games = [], client = 'chat', studioKind = 'game' } = {}) {
   const id = ID.test(String(h.id ?? '')) ? h.id : null;
   const has = id && games.includes(id);
   const q = (s) => JSON.stringify(String(s));
-  const work = {
+  const app = h.what === 'app' || ['business', 'cause', 'app'].includes(studioKind);
+  const work = app && ['setup', 'make'].includes(h.kind) ? [
+    'Follow the app and shared plan skills: capture their words, scene, people, offers and demonstrable needs in apps/<id>/CODEX.md. Starter plumbing is not the deliverable. Build their scene and prove each need on wall and phone; continue without an engineering interview.',
+    has ? `apps/${id} is here already: change it as the brief says.` : `npx --no-install homie-studio app new ${id ?? '<id>'} --from ${ID.test(String(h.from ?? '')) ? h.from : 'welcome'}`,
+    'Use apps/<id>/app.json for the organisation’s words, roles and records; site/pages/ for public pages; shop init --giving --currency <currency> for gifts.',
+  ] : {
     setup: [
-      `This studio was just set up from ${client === 'grok' ? 'Grok' : client === 'codex' ? 'Codex' : client === 'claude' ? 'the Claude app' : 'this chat'}. Go through the new-studio checklist with the person, one step at a time and never ahead (the plugin's studio-setup skill): it has no game yet, and its home page says "First game coming soon".`,
+      `This studio was just set up from ${client === 'grok' ? 'Grok' : client === 'codex' ? 'Codex' : client === 'claude' ? 'the Claude app' : 'this chat'}. Proceed through the new-studio checklist, building and checks from the request without waiting unless the person asks (the plugin's studio-setup skill): for a business or cause, start with the app skill and app new; choose the starter that fits the requested work.`,
       'See a working game: `npx --no-install homie-studio demo` names a live one on Homie Arcade; copy a starter in only if they ask.',
       'One small change from one sentence of theirs (the studio\'s colours in site/theme.json, a tagline in studio.json, or a first post in posts/), then plan their game into its Game Codex (`npx --no-install homie-studio codex new <id> --name "<Name>"`) before any game is made.',
     ],
@@ -58,7 +63,7 @@ export function stepsFor(h, { games = [], client = 'chat' } = {}) {
   }[h.kind] ?? ['Do what the brief asks.'];
   return [
     ...work,
-    'npm run build; npm run dev in the background; npx --no-install homie-studio check <id> --url http://127.0.0.1:8787 (on Linux without Chrome, first: npx --no-install homie-studio chrome install).',
+    'npm run build; npm run dev in the background; npx --no-install homie-studio check <id> --url <the printed dev address> (on Linux without Chrome, first: npx --no-install homie-studio chrome install).',
     'npx --no-install homie-studio progress change "<what it does, one line>"; commit on a new branch, push, gh pr create; then npx --no-install homie-studio progress pr --url <the pull request>.',
     'Never merge the pull request: the person publishes it from the chat\'s card, in GitHub.',
   ];
@@ -71,8 +76,8 @@ export async function handoff(root, build, { homie, client, fetchFn = globalThis
   if (SETUP.test(String(build ?? ''))) {
     const r = await checkIn(root, build, { homie, client: who.id === 'chat' ? null : who.id });
     if (!r.ok) return { ok: false, command: 'handoff', setup: build, why: r.why, ...(r.needs ? { needs: r.needs } : {}) };
-    const h = { kind: 'setup', what: 'game', title: 'first steps', studio: r.name ?? studio.name, brief: '', setup: build };
-    return { ok: true, command: 'handoff', build: null, ...h, client: who.id, setup: { ok: true, message: r.message, renamed: r.renamed ?? [] }, attached: null, attachWhy: 'no build was opened in the chat yet (the setup card\'s Start building opens one)', steps: stepsFor(h, { client: who.id }) };
+    const h = { kind: 'setup', what: ['business', 'cause', 'app'].includes(studio.kind) ? 'app' : 'game', title: 'first steps', studio: r.name ?? studio.name, brief: '', setup: build };
+    return { ok: true, command: 'handoff', build: null, ...h, client: who.id, setup: { ok: true, message: r.message, renamed: r.renamed ?? [] }, attached: null, attachWhy: 'no build was opened in the chat yet (the setup card\'s Start building opens one)', steps: stepsFor(h, { client: who.id, studioKind: studio.kind }) };
   }
   if (!BUILD.test(String(build ?? ''))) return { ok: false, command: 'handoff', why: `the id from the one line the chat gave: hb_ (a build) or hs_ (a setup) and 32 hex digits` };
   const directory = String(homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
@@ -88,7 +93,7 @@ export async function handoff(root, build, { homie, client, fetchFn = globalThis
   if (want && here && here !== want) return { ok: false, command: 'handoff', build, why: `this build is for ${body.repo}, but this session is in ${here}: open it in ${body.repo} (the card's Build it does), and change nothing here` };
   const h = {
     kind: ['make', 'port', 'change', 'setup'].includes(body.kind) ? body.kind : 'change',
-    what: ['game', 'song', 'video'].includes(body.what) ? body.what : 'game',
+    what: ['app', 'game', 'song', 'video'].includes(body.what) ? body.what : 'game',
     title: line(body.title, 120), studio: line(body.studio, 60) || studio.name, brief: lines(body.brief, 1200),
     id: ID.test(String(body.id ?? '')) ? body.id : null, name: line(body.name, 60) || null, from: ID.test(String(body.from ?? '')) ? body.from : null,
     folder: line(body.folder, 200) || null,
@@ -106,7 +111,7 @@ export async function handoff(root, build, { homie, client, fetchFn = globalThis
     ok: true, command: 'handoff', build, ...h, setup,
     attached: taken.ok ? { feed: taken.build, shared: taken.shared?.build ?? build } : null,
     attachWhy: taken.ok ? null : taken.why,
-    steps: stepsFor(h, { games, client: who.id }),
+    steps: stepsFor(h, { games, client: who.id, studioKind: studio.kind }),
   };
 }