@homie-rocks/studio 0.36.0 → 0.37.1

package/lib/parts.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * GAME PARTS: THE FORMAT AND ITS CHECKER (parts/PARTS.md is the design; this file holds it to its word).
  *
@@ -24,7 +25,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, r
 import { dirname, join, relative } from 'node:path';
 
 export const PART_ID = /^[a-z0-9][a-z0-9-]{0,47}$/;
-export const PART_KINDS = Object.freeze(['character', 'rig', 'clips', 'environment', 'effect', 'sound', 'ui', 'mechanic', 'shader', 'level-generator', 'bot-brain', 'audio-pack', 'set-piece']);
+export const PART_KINDS = Object.freeze(['character', 'rig', 'clips', 'environment', 'effect', 'sound', 'ui', 'mechanic', 'shader', 'level-generator', 'bot-brain', 'audio-pack', 'set-piece', 'quiz', 'menu-board', 'waitlist', 'live-total', 'loop', 'stem', 'track', 'video-intro', 'video-template']);
 export const NETPLAY_KINDS = Object.freeze(['host-authoritative', 'replicated', 'local']);
 export const PROVENANCE = Object.freeze(['original', 'generated', 'imported']);
 export const PIVOTS = Object.freeze(['feet', 'centre', 'base', 'origin']);
@@ -315,8 +316,9 @@ export function checkPart(part, { id = null } = {}) {
     if (!isObj(part.cost)) bad('cost', 'it is not an object', '{ "triangles": 0, "drawCalls": 0, "textureMB": 0, "bytes": 0, "measuredOn": "…" }');
     else for (const k of ['triangles', 'drawCalls', 'textureMB', 'bytes']) if (part.cost[k] !== undefined && !(Number.isFinite(part.cost[k]) && part.cost[k] >= 0)) bad(`cost.${k}`, 'it is not a number of 0 or more', 'leave out a cost nobody measured');
   }
+  if (part.uses !== undefined && (!Array.isArray(part.uses) || part.uses.some((u) => !['game', 'app', 'venue', 'cause', 'music', 'video'].includes(u)))) bad('uses', 'uses must name game, app, venue, cause, music or video');
   if (part.from !== undefined && part.from !== null) {
-    if (!isObj(part.from) || (part.from.game != null && !/^[a-z0-9][a-z0-9-]{0,39}$/.test(String(part.from.game)))) bad('from', 'it does not name the game the part came out of', '{ "game": "<the game\'s id>", "studio": "<the studio\'s name>" }');
+    if (!isObj(part.from) || ((part.from.game ?? part.from.app ?? part.from.music ?? part.from.video) != null && !/^[a-z0-9][a-z0-9-]{0,39}$/.test(String(part.from.game ?? part.from.app ?? part.from.music ?? part.from.video)))) bad('from', 'it does not name the game the part came out of', '{ "game": "<the game\'s id>", "studio": "<the studio\'s name>" }');
   }
   if (part.provenance !== undefined) {
     if (!isObj(part.provenance)) bad('provenance', 'it is not an object', '{ "source": "original" }');
@@ -353,14 +355,16 @@ export function requiredParts(part) {
  */
 export function assetRecords(root) {
   const out = new Map();
-  const games = join(root, 'games');
-  if (!existsSync(games)) return out;
+  for (const folder of ['games', 'apps']) {
+  const games = join(root, folder);
+  if (!existsSync(games)) continue;
   for (const e of readdirSync(games, { withFileTypes: true })) {
     if (!e.isDirectory()) continue;
     let m = null;
     try { m = JSON.parse(readFileSync(join(games, e.name, 'assets', 'manifest.json'), 'utf8')); } catch { m = null; }
     for (const a of Array.isArray(m?.assets) ? m.assets : []) for (const f of a.files ?? []) if (/^[a-f0-9]{64}$/.test(String(f.sha256 ?? ''))) out.set(f.sha256, { game: e.name, asset: a.id, kind: a.license?.kind ?? null, attribution: a.license?.attribution ?? null });
   }
+  }
   return out;
 }
 /** The asset-manifest licence kinds a file may be handed on under (lib/asset-manifest.mjs LICENSES, `redistribute`). */
@@ -520,7 +524,7 @@ function relSpec(fromFile, toFile) {
  * would point nowhere, and a part that reaches back into one game is not a part another game can use.
  */
 function liftPlan(root, game, paths) {
-  const gdir = join(root, 'games', game);
+  const gdir = join(experienceDir(root, game));
   const files = [];
   const walk = (rel) => {
     const abs = join(gdir, rel);
@@ -528,15 +532,15 @@ function liftPlan(root, game, paths) {
     if (statSync(abs).isDirectory()) { for (const e of readdirSync(abs, { withFileTypes: true })) if (!e.name.startsWith('.') && e.name !== 'node_modules') walk(`${rel}/${e.name}`); } else files.push(rel);
   };
   for (const raw of paths) {
-    const rel = posix(String(raw)).replace(/^\.\//, '').replace(/^games\/[^/]+\//, '').replace(/\/+$/, '');
+    const rel = posix(String(raw)).replace(/^\.\//, '').replace(/^(?:games|apps)\/[^/]+\//, '').replace(/\/+$/, '');
     if (!rel || rel.split('/').includes('..') || rel.startsWith('/')) throw new Error(`"${raw}" is not a path inside games/${game}`);
     walk(rel);
   }
   if (!files.length) throw new Error(`name the files of games/${game} that become the part (src/creature.ts, or a folder)`);
   // A part is a piece of a game, never the whole game: its entry, its page and its game.json stay the game's.
   let entry = 'src/main.ts';
-  try { entry = JSON.parse(readFileSync(join(gdir, 'game.json'), 'utf8')).entry ?? entry; } catch { /* the default entry */ }
-  const whole = files.filter((f) => f === entry || f === 'game.json' || f === 'index.html');
+  try { entry = JSON.parse(readFileSync(experienceFile(root, game), 'utf8')).entry ?? entry; } catch { /* the default entry */ }
+  const whole = files.filter((f) => f === entry || f === 'game.json' || f === 'app.json' || f === 'index.html');
   if (whole.length) throw new Error(`${whole.join(', ')} ${whole.length === 1 ? 'is' : 'are'} the game itself. A part is a piece of a game, never the whole game: name the files of one piece (the creature, the level generator, the camera).`);
   // The folder they share (without a leading src/, which every part has of its own).
   const dirs = files.map((f) => f.split('/').slice(0, -1));
@@ -560,15 +564,16 @@ function liftPlan(root, game, paths) {
  * `parts new`: a private part with every field a sharer will need, so the gaps are visible from the first minute.
  * `from` (a game's id) with `paths` lifts those files out of the game (above); without, the part starts empty.
  */
-export function newPart(root, id, { kind = 'mechanic', name = null, from = null, paths = [] } = {}) {
+export function newPart(root, id, { kind = 'mechanic', name = null, from = null, paths = [], uses = [] } = {}) {
   if (!PART_ID.test(String(id ?? ''))) return { ok: false, command: 'parts new', why: `"${id ?? ''}" is not a part id: lowercase letters, digits and hyphens (chase-camera)` };
   if (!PART_KINDS.includes(kind)) return { ok: false, command: 'parts new', why: `"${kind}" is not a kind of part: ${PART_KINDS.join(', ')}` };
+  if (!Array.isArray(uses) || uses.some((u) => !['game', 'app', 'venue', 'cause', 'music', 'video'].includes(u))) return { ok: false, command: 'parts new', why: 'invalid intended uses' };
   const dir = partDir(root, id);
   if (existsSync(dir)) return { ok: false, command: 'parts new', why: `parts/${id} is there already` };
   const title = clean(name, 80) || id.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
   let entry = null; let lifted = null; let fromGame = null;
   if (from) {
-    if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(String(from)) || !existsSync(join(root, 'games', from, 'game.json'))) return { ok: false, command: 'parts new', why: `there is no game "${from}" in this studio to lift a part out of` };
+    if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(String(from)) || !existsSync(experienceFile(root, from))) return { ok: false, command: 'parts new', why: `there is no game "${from}" in this studio to lift a part out of` };
     let plan;
     try { plan = liftPlan(root, from, paths); } catch (error) { return { ok: false, command: 'parts new', why: error.message }; }
     if (plan.outside.length) return { ok: false, command: 'parts new', why: `These files still reach into the rest of games/${from}: ${plan.outside.slice(0, 6).join('; ')}. A part has to stand without the game: lift those files too, or pass what they provide in as an argument first. Nothing was moved.`, outside: plan.outside };
@@ -589,7 +594,7 @@ export function newPart(root, id, { kind = 'mechanic', name = null, from = null,
     entry = mods.find((p) => /^src\/index\.[a-z]+$/.test(p)) ?? mods[0] ?? null;
     let studio = null;
     try { studio = JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')).name ?? null; } catch { studio = null; }
-    fromGame = { game: from, ...(studio ? { studio: clean(studio, 80) } : {}) };
+    fromGame = { [experienceFile(root, from).endsWith('/app.json') ? 'app' : 'game']: from, ...(studio ? { studio: clean(studio, 80) } : {}) };
   } else {
     mkdirSync(dir, { recursive: true });
     if (['mechanic', 'ui', 'effect', 'shader', 'level-generator', 'bot-brain'].includes(kind)) {
@@ -602,7 +607,7 @@ export function newPart(root, id, { kind = 'mechanic', name = null, from = null,
   mkdirSync(join(dir, 'preview'), { recursive: true });
   if (!existsSync(join(dir, 'preview', 'index.html'))) writeFileSync(join(dir, 'preview', 'index.html'), PREVIEW_HTML(title));
   writePart(dir, {
-    id, name: title, kind, version: '0.1.0', summary: '', license: '', attribution: '', share: false, tags: [],
+    id, name: title, kind, version: '0.1.0', summary: '', license: '', attribution: '', share: false, tags: [], ...(uses.length ? { uses } : {}),
     ...(fromGame ? { from: fromGame } : {}),
     ...(entry ? { entry } : {}),
     files: [],
@@ -628,7 +633,7 @@ export function newPart(root, id, { kind = 'mechanic', name = null, from = null,
 
 /* ------------------------------------------------------------------ checking a set together */
 
-const creditsFile = (root, game) => join(root, 'games', game, 'credits.json');
+const creditsFile = (root, game) => join(experienceDir(root, game), 'credits.json');
 
 /**
  * THE LICENCES OF THE PARTS A GAME USES, and where they cannot be combined: [{ level: 'conflict' | 'warn' | 'note',
@@ -687,7 +692,7 @@ export function syncPartCredits(root, game, origins) {
   const keep = (Array.isArray(credits.parts) ? credits.parts : []).filter((p) => typeof p?.part !== 'string');
   const mine = Object.entries(origins.parts ?? {}).filter(([, e]) => (e.games ?? []).includes(game)).map(([ref, e]) => creditLine(ref, e));
   if (!mine.length && !existsSync(file)) return null;
-  if (!existsSync(join(root, 'games', game))) return null;
+  if (!existsSync(join(experienceDir(root, game)))) return null;
   const text = `${JSON.stringify({ ...credits, parts: [...keep, ...mine] }, null, 2)}\n`;
   if (!existsSync(file) || readFileSync(file, 'utf8') !== text) writeFileSync(file, text);
   return `games/${game}/credits.json`;

package/lib/perf.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * `homie-studio perf <game> --url <site>` — how fast a game runs, measured the same way every time, so a change can be
  * judged against the build before it (`perf compare`, lib/perf-stats.mjs).
@@ -681,7 +682,7 @@ export function perfSizes(root, game) {
   const dir = join(root, 'site', 'dist', 'games', game);
   if (!existsSync(dir)) return { ok: false, command: 'perf sizes', why: `no build of ${game}: run npm run build first` };
   let cover = null;
-  try { cover = JSON.parse(readFileSync(join(root, 'games', game, 'game.json'), 'utf8')).cover ?? null; } catch { /* none */ }
+  try { cover = JSON.parse(readFileSync(experienceFile(root, game), 'utf8')).cover ?? null; } catch { /* none */ }
   const files = listFiles(dir).map((f) => {
     const buf = readFileSync(join(dir, f));
     const kind = kindOf(f);

package/lib/player-image.mjs

@@ -12,10 +12,10 @@ import { PLAYER_IMAGE, playerEnabled, playerImageRule } from '../worker/embed.mj
  */
 export async function playerImage(cat, game, dist, log) {
   if (!playerEnabled(cat, game)) return null;
-  const sources = [...new Set([game.landing?.hero?.wideImage, game.landing?.cover,
+  const sources = [...new Set([game.landing?.hero?.wideImage, game.landing?.hero?.tallImage, game.landing?.cover,
     game.cover ? `/games/${game.id}/${game.cover}` : null, cat.studio.theme?.social].filter(Boolean))];
   const warn = (file, rule) => log(`warning: ${file}: player card needs ${rule}; keeping the picture card unless another image qualifies.`);
-  if (!sources.length) warn(`games/${game.id}/game.json`, 'a cover or a studio social picture in the built site (starters do not include one)');
+  if (!sources.length) warn(`${game.kind === 'app' ? 'apps' : 'games'}/${game.id}/${game.kind === 'app' ? 'app' : 'game'}.json`, 'a cover or a studio social picture in the built site (starters do not include one)');
   const root = realpathSync(dist);
   for (const src of sources) {
     if (!src.startsWith('/') || src.startsWith('//')) { warn(src, 'a local image the build can measure'); continue; }

package/lib/prepare.mjs

@@ -0,0 +1,47 @@
+/** Private Node installation for a Desktop host with a bundled runtime but no system Node.
+ * Official archive + SHA-256, no shell, administrator rights or shell profile edits.
+ */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const nodeHome = (home = homedir()) => join(home, '.cache', 'homie-studio', 'node');
+export async function prepareNode({ home = homedir(), platform = process.platform, arch = process.arch, fetchFn = fetch, exec = spawnSync } = {}) {
+  const base = nodeHome(home);
+  const bin = join(base, platform === 'win32' ? 'node.exe' : 'bin/node');
+  if (existsSync(bin)) return { ok: true, bin, installed: false };
+  if (!['darwin', 'linux', 'win32'].includes(platform) || !['arm64', 'x64'].includes(arch)) {
+    return { ok: false, next: 'Ask the connected AI to install Node.js 22 or newer for this operating system.', open: 'https://nodejs.org/en/download' };
+  }
+  let scratch;
+  try {
+    const get = async (url) => {
+      const r = await fetchFn(url, { signal: AbortSignal.timeout(15_000) });
+      if (!r.ok) throw new Error(`Node download answered ${r.status}`);
+      return r;
+    };
+    const url = 'https://nodejs.org/dist/latest-v22.x';
+    const sums = await (await get(`${url}/SHASUMS256.txt`)).text();
+    const suffix = `${platform === 'win32' ? 'win' : platform}-${arch}.${platform === 'win32' ? 'zip' : 'tar.gz'}`;
+    const entry = sums.split('\n').map((s) => s.trim().split(/\s+/)).find(([hash, file]) => /^[a-f0-9]{64}$/.test(hash) && new RegExp(`^node-v22\\.\\d+\\.\\d+-${suffix.replaceAll('.', '\\.')}$`).test(file ?? ''));
+    if (!entry) throw new Error('No supported Node archive in the official checksum list');
+    const [hash, file] = entry;
+    const data = Buffer.from(await (await get(`https://nodejs.org/dist/${file.match(/^node-(v22\.\d+\.\d+)-/)[1]}/${file}`)).arrayBuffer());
+    if (createHash('sha256').update(data).digest('hex') !== hash) throw new Error('Node archive checksum did not match');
+    mkdirSync(join(home, '.cache', 'homie-studio'), { recursive: true });
+    scratch = mkdtempSync(join(home, '.cache', 'homie-studio', 'node-'));
+    const archive = join(scratch, file);
+    writeFileSync(archive, data);
+    const r = exec('tar', ['-xf', archive, '-C', scratch], { encoding: 'utf8', timeout: 10_000 });
+    if (r.status !== 0) throw new Error('Could not unpack Node with the system archive tool');
+    const unpacked = join(scratch, file.replace(/\.(tar\.gz|zip)$/, ''));
+    const check = exec(join(unpacked, platform === 'win32' ? 'node.exe' : 'bin/node'), ['--version'], { encoding: 'utf8', timeout: 3000 });
+    if (check.status !== 0 || !/^v22\./.test(check.stdout ?? '')) throw new Error('Downloaded Node did not start');
+    renameSync(unpacked, base);
+    return { ok: true, bin, installed: true };
+  } catch (error) {
+    return { ok: false, why: error.message, next: 'AI: retry setup_prepare; if the network still refuses, use the Node installer.', open: 'https://nodejs.org/en/download' };
+  } finally { if (scratch) rmSync(scratch, { recursive: true, force: true }); }
+}

package/lib/scaffold.mjs

@@ -1,3 +1,4 @@
+import { APPS_MIGRATION, APPS_MIGRATION_FILE } from '../worker/app-records.mjs';
 /**
  * `homie-studio new <folder> --name "<Studio Name>"` — a studio is ONE
  * monorepo: a visible folder the person opens in Claude or Codex.
@@ -131,6 +132,26 @@ directory lists its games; homie.rocks does not host them.
 | \`studio.json\` | The studio's name, slug, Cloudflare resource names, custom domain and stats sharing. \`.studio/\` (git-ignored) is this computer's own state. |
 | \`.claude/skills/\` | Skills only this studio uses. Homie's own skills come from the Homie plugin. |
 
+The person describes an outcome; you carry it through setup, building and checks without a tutorial
+or a planning interview. Choose engineering and design defaults from their words and record them
+in the codex. Use "My Studio" when unnamed, phones and computers, local sound and CC0 art.
+They can change anything by asking. A business or charity may want an app, not a game.
+Install missing prerequisites yourself; never ask the person to run a command or handle a key,
+account id, zone id or setting. Honour an existing request to go live or list, subject to host holds.
+For a requested custom hostname, add its custom_domain route in Wrangler along with cloudflare.domain;
+Cloudflare creates DNS and TLS during deploy with the existing sign-in.
+
+
+## Apps: one screen, roles and parts
+
+An app lives in \`apps/<id>/app.json\` and \`src/\`. Make one with \`homie-studio app new <id>\` (or \`app_make\`). Use the Homie plugin's \`app\` skill for businesses, venues, causes and customer apps. No game demo, rounds, scores, bots or mandatory fun: build what the person needs with the fewest human steps.
+
+An app is ONE screen that morphs with context: camera moves, panels unfold, its roles see and do different things, and parts plug into the scene. No page-to-page navigation or menus of links inside it. Use all the same engine packages and media skills as games (camera, geom, props, render, postfx, fx, audio, input, ui-world; style, art, models, animate, music, sound, video). It can be fully 3D and wild while remaining useful and legible.
+
+Declare roles, surfaces, words and lasting record collections in app.json. Netplay's host is not a staff permission. Use \`@homie-rocks/studio/apps\` for authorized lasting records and \`@homie-rocks/studio/links\` for ticket links, QR and HTTP-safe IDs. Staff use private role links plus existing account grants; keep private records out of public collections. Look for engine mechanisms and shared parts before writing a component. Credit licences; sharing is optional and separate from selling.
+
+Build normally, run \`homie-studio dev --lan\`, then \`homie-studio check <id> --url <origin>\`: the app check proves an actual action across a wall and two phones plus reconnect. The public screen is \`/<id>/open\`, the wall \`/<id>/tv\`. Customer apps use the same \`standalone\` build for desktop/iOS/Android; its existing sign-in and store limitations still apply. See \`node_modules/@homie-rocks/studio/apps/APPS.md\`.
+
 ## Commands (all through the pinned CLI in node_modules)
 
 Use \`npm run <script>\` or \`npx --no-install homie-studio <command>\`: \`--no-install\` makes sure it is this
@@ -700,6 +721,7 @@ export function studioFiles({ name, slug, homie, template = false }) {
     'studio.json': `${JSON.stringify(studio, null, 2)}\n`,
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     '.gitignore': GITIGNORE,
+    'apps/README.md': 'One folder per app: app.json, index.html and src/. One transforming screen, its roles and its parts. Start with `npx --no-install homie-studio app new <id>`. The app guide explains lasting records, staff sign-in, LAN preview and standalone builds.\n',
     'games/README.md': 'One folder per game. A new studio has none (its home page says "First game coming soon"). Start one with `npx --no-install homie-studio game new <id> --from gem-rush` when the person asks for a copy of the starter, or once their game is planned.\n',
     'music/README.md': 'Songs, game scores, loops and stems, one folder each (`music/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/music/<slug>/`. Without storage the site serves files up to 25 MiB itself. With storage (`npx --no-install homie-studio storage add`), the big ones live in the studio\'s R2: `npx --no-install homie-studio media move` and every deploy put them there, checked by SHA-256, at the same address. Never into git.\n',
     'music/manifest.json': '{ "v": 1, "items": [] }\n',
@@ -728,6 +750,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${SHOP_RESERVATIONS_FILE}`]: SHOP_RESERVATIONS,
     [`site/migrations/${SHOP_STATEMENTS_FILE}`]: SHOP_STATEMENTS,
     [`site/migrations/${SHOP_LINES_FILE}`]: SHOP_LINES,
+    [`site/migrations/${APPS_MIGRATION_FILE}`]: APPS_MIGRATION,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -877,13 +900,19 @@ function ensureLoungeMigration(root) {
   return `site/migrations/${LOUNGE_MIGRATION_FILE}`;
 }
 
+function ensureAppsMigration(root) {
+  const file = join(root, 'site', 'migrations', APPS_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, APPS_MIGRATION);
+  return `site/migrations/${APPS_MIGRATION_FILE}`;
+}
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */
 export function migrationWord(file) {
-  return /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
+  return /studio_apps/.test(file) ? 'apps: lasting records and signed-in role grants' : /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**

package/lib/shop.mjs

@@ -32,7 +32,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { askedFor, withKey } from './office.mjs';
 import { runner } from './cloudflare.mjs';
-import { listGames, readStudio, siteUrl } from './studio.mjs';
+import { listExperiences as listGames, readStudio, siteUrl } from './studio.mjs';
 import { SHOP_FILE, audienceOf, checkShop, defaultTaxCode, money } from '../worker/shop-rules.mjs';
 import {
   KEY_SHAPE, STRIPE_VERSION, StripeError, WEBHOOK_SECRET_SHAPE, createWebhookEndpoint, expireCheckoutSession, isPermissionError, listWebhookEndpoints, modeOf,

package/lib/standalone-files.mjs

@@ -105,8 +105,8 @@ export function projectPackage(meta, { targets = TARGETS } = {}) {
 }
 
 /** web/config.js: everything the shell knows about the game it frames. `site` '' is a copy that only plays offline. */
-export function configScript(meta, { target, site = '', share, colours = null, movement = null, params = {}, room = null }) {
-  const cfg = { v: 1, game: meta.id, name: meta.name, site: String(site ?? '').replace(/\/+$/, ''), ver: meta.netplayVersion ?? '', ...(movement ? { movement } : {}), params, share, colours, ...(room ? { room } : {}), version: meta.version, target };
+export function configScript(meta, { target, site = '', share, colours = null, movement = null, params = {}, room = null, kind = null }) {
+  const cfg = { ...(kind === 'app' ? { kind: 'app' } : {}), v: 1, game: meta.id, name: meta.name, site: String(site ?? '').replace(/\/+$/, ''), ver: meta.netplayVersion ?? '', ...(movement ? { movement } : {}), params, share, colours, ...(room ? { room } : {}), version: meta.version, target };
   return `window.__HOMIE_APP = ${JSON.stringify(cfg, null, 2).replace(/</g, '\\u003c')};\n`;
 }
 

package/lib/standalone.mjs

@@ -1,3 +1,4 @@
+import { APP_SHELL_JS } from '../worker/app-shell.mjs';
 /**
  * `homie-studio standalone plan|build|run|steam|ci <game>`: A STANDALONE COPY OF A GAME (standalone/STANDALONE.md).
  *
@@ -30,7 +31,7 @@ import { homedir, tmpdir } from 'node:os';
 import { dirname, join, relative } from 'node:path';
 import { build as buildSite, uiOf } from './build.mjs';
 import { compareVersions } from './changelog.mjs';
-import { GAME_ID, PACKAGE_ROOT, isWorkersDev, listGames, readStudio, siteUrl } from './studio.mjs';
+import { GAME_ID, PACKAGE_ROOT, isWorkersDev, listExperiences as listGames, readStudio, siteUrl } from './studio.mjs';
 import { pinnedVersion } from './upgrade.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { sharePlaces } from '../worker/pages.mjs';
@@ -402,11 +403,15 @@ export function webBundle(root, game, dir, { meta, target = 'web', site = '', st
   rmSync(web, { recursive: true, force: true });
   mkdirSync(web, { recursive: true });
   for (const f of ['index.html', 'shell.js', 'shell.css']) copyFileSync(join(SHELL, f), join(web, f));
+  if (game.kind === 'app') {
+    const shell = join(web, 'shell.js');
+    writeFileSync(shell, readFileSync(shell, 'utf8') + '\n' + APP_SHELL_JS);
+  }
   const row = (readJson(join(root, 'site', 'dist', 'games.json'))?.games ?? []).find((g) => g.id === game.id);
   const m = { ...(meta ?? standaloneMeta(studio ?? readStudio(root), game)), ...(row?.room ? { netplayVersion: row.netplay?.version ?? null } : {}) };
   const rules = readJson(join(built, 'rules.json'));
   if (rules) for (const file of rules.files ?? []) if (!existsSync(join(built, file))) throw new Error(`The rules build is incomplete: ${file} is missing. Build the game again before making its app.`);
-  writeFileSync(join(web, 'config.js'), configScript(m, { target, site, share: sharePlaces(game.screen?.share), colours: uiOf(game), movement: game.netplay?.movement ?? game.movement ?? null, room: row?.room ?? null }));
+  writeFileSync(join(web, 'config.js'), configScript(m, { target, site, share: sharePlaces(game.screen?.share), colours: uiOf(game), movement: game.netplay?.movement ?? game.movement ?? null, room: row?.room ?? null, ...(game.kind === 'app' ? { kind: 'app', params: { role: game.surfaces.phone } } : {}) }));
   copyTree(built, join(web, 'game'));
   const index = join(web, 'game', 'index.html');
   writeFileSync(index, withNetScript(readFileSync(index, 'utf8')));

package/lib/stats.mjs

@@ -13,6 +13,7 @@
  * itself is never sent to Cloudflare, never written to a file, and lives for its hours only. A studio running
  * locally (`npm run dev`, a loopback --url) uses the local D1.
  */
+import { networkInterfaces } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
 import { runner } from './cloudflare.mjs';
 import { readStudio, siteUrl, writeStudio } from './studio.mjs';
@@ -21,7 +22,7 @@ const HOUR = 3600_000;
 const RANGES = new Set(['1d', '7d', '30d', '90d']);
 const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
 
-export const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
+export const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]', ...Object.values(networkInterfaces()).flat().filter((n) => n?.family === 'IPv4').map((n) => n.address)].includes(new URL(url).hostname); } catch { return false; } };
 
 export function siteOf(root, url) {
   const studio = readStudio(root);

package/lib/studio.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed', 'account']);
+const RESERVED_IDS = new Set(['api', 'media', 'games', 'apps', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed', 'account']);
 
 export function findStudio(from = process.cwd()) {
   let at = resolve(from);
@@ -82,14 +82,25 @@ export function siteUrl(root, studio = readStudio(root)) {
   return custom ?? readLocal(root).url ?? cf.url ?? null;
 }
 
-export function listGames(root) {
-  const dir = join(root, 'games');
+export function listGames(root) { return listKind(root, 'game'); }
+export function listApps(root) { return listKind(root, 'app'); }
+export function listExperiences(root) {
+  const rows = [...listGames(root), ...listApps(root)].sort((a, b) => a.id.localeCompare(b.id));
+  const ids = new Set();
+  for (const row of rows) { if (ids.has(row.id)) throw new Error(`app/game id collision: ${row.id}`); ids.add(row.id); }
+  return rows;
+}
+export const experienceDir = (root, id) => join(root, existsSync(join(root, 'apps', id, 'app.json')) ? 'apps' : 'games', id);
+export const experienceFile = (root, id) => join(experienceDir(root, id), existsSync(join(root, 'apps', id, 'app.json')) ? 'app.json' : 'game.json');
+function listKind(root, kind) {
+  const dir = join(root, `${kind}s`);
   if (!existsSync(dir)) return [];
   return readdirSync(dir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, 'game.json')))
+    .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, `${kind}.json`)))
     .map((d) => {
-      const meta = JSON.parse(readFileSync(join(dir, d.name, 'game.json'), 'utf8'));
-      return { ...meta, id: meta.id ?? d.name, dir: join(dir, d.name) };
+      const meta = JSON.parse(readFileSync(join(dir, d.name, `${kind}.json`), 'utf8'));
+      if (kind === 'app' && (!GAME_ID.test(d.name) || RESERVED_IDS.has(d.name) || (meta.id !== undefined && meta.id !== d.name))) throw new Error(`apps/${d.name}: id must match its folder and use a free site address`);
+      return { ...meta, ...(kind === 'app' ? { kind: 'app' } : {}), id: meta.id ?? d.name, dir: join(dir, d.name) };
     })
     .sort((a, b) => a.id.localeCompare(b.id));
 }
@@ -141,6 +152,7 @@ function renameTakeSaves(dir, from, id) {
  */
 export async function newGame(root, id, { from = 'gem-rush', name } = {}) {
   if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error(`a game id is lowercase letters, digits and hyphens, up to 40, and not one of ${[...RESERVED_IDS].join(', ')} (got ${JSON.stringify(id)})`);
+  if (listApps(root).some((a) => a.id === id)) throw new Error(`apps/${id} already owns this address`);
   const src = join(PACKAGE_ROOT, 'starters', from);
   if (!existsSync(join(src, 'game.json'))) throw new Error(`no starter "${from}"; starters: ${starters().map((s) => s.id).join(', ')}`);
   const dest = join(root, 'games', id);
@@ -287,3 +299,17 @@ export function addNeeds(root, needs) {
   return { needs: Object.fromEntries(want), needsAdded: added, needsHeld: held, installNeeded: added.length > 0 };
 }
 
+
+export async function newApp(root, id, { name } = {}) {
+  if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error('invalid app id');
+  if (listExperiences(root).some((g) => g.id === id) || existsSync(join(root, 'apps', id))) throw new Error(`app/game ${id} already exists`);
+  const dest = join(root, 'apps', id);
+  cpSync(join(PACKAGE_ROOT, 'app-starters', 'welcome'), dest, { recursive: true });
+  const file = join(dest, 'app.json');
+  const meta = JSON.parse(readFileSync(file, 'utf8'));
+  meta.id = id; meta.name = String(name ?? 'Welcome together').slice(0, 60);
+  writeFileSync(file, `${JSON.stringify(meta, null, 2)}\n`);
+  const main = join(dest, 'src/main.ts');
+  writeFileSync(main, readFileSync(main, 'utf8').replaceAll("game: 'welcome'", `game: '${id}'`));
+  return { ok: true, command: 'app new', id, dir: dest, files: readdirSync(dest, { recursive: true }).map(String), ...addNeeds(root, meta.needs) };
+}

package/lib/style-board.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * THE STYLE BOARD AND THE LINEUP: pictures the engine draws for free (lib/render3d.mjs).
  *
@@ -77,10 +78,10 @@ export async function styleBoard(root, id, { prompt = '', log = () => {}, librar
   if (!doc) { initDecisions(root, id, { prompt, path: 'hands-on' }); doc = readDecisions(root, id); }
   const { directions } = directionsFor(root, id, { prompt: prompt || doc.prompt });
   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 title = game.name ?? id.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
   const words = [prompt, doc.prompt, (doc.decisions['cast.list']?.value ?? []).map((c) => c.id).join(' ')].join(' ');
-  const dir = join(root, 'games', id, BOARD_DIR);
+  const dir = join(experienceDir(root, id), BOARD_DIR);
   mkdirSync(dir, { recursive: true });
   const pieces = {};
   if (library) for (const d of directions) if (!pieces[d.family]) pieces[d.family] = await libraryPieces(d.family, words, 4, log);
@@ -90,7 +91,7 @@ export async function styleBoard(root, id, { prompt = '', log = () => {}, librar
       const url = await r.swatch(tokensOf(d.values), pieces[d.family] ?? [], { title });
       const file = join(dir, `${d.id}-swatch.jpg`);
       const bytes = await savePicture(url, file);
-      out.push({ ...d, swatch: relative(join(root, 'games', id), file), bytes, library: (pieces[d.family] ?? []).map((m) => m.id) });
+      out.push({ ...d, swatch: relative(experienceDir(root, id), file), bytes, library: (pieces[d.family] ?? []).map((m) => m.id) });
     }
     return r.renderer;
   }, { log });
@@ -124,13 +125,13 @@ export async function recordMood(root, id, dirId, image, { usd = null, receipt =
   const d = doc?.board?.directions?.find((x) => x.id === dirId);
   if (!d) throw new Error(`no direction "${dirId}" on the style board (style board ${id} draws it first)`);
   if (!existsSync(image)) throw new Error(`no picture at ${image}`);
-  const file = join(root, 'games', id, BOARD_DIR, `${dirId}-mood.jpg`);
+  const file = join(experienceDir(root, id), BOARD_DIR, `${dirId}-mood.jpg`);
   const sharp = (await import('sharp')).default;
   let q = 82;
   let out = await sharp(readFileSync(image)).resize(960, 540, { fit: 'cover' }).jpeg({ quality: q, mozjpeg: true }).toBuffer();
   while (out.byteLength > PICTURE_MAX && q > 50) { q -= 10; out = await sharp(readFileSync(image)).resize(960, 540, { fit: 'cover' }).jpeg({ quality: q, mozjpeg: true }).toBuffer(); }
   writeFileSync(file, out);
-  d.mood = { path: relative(join(root, 'games', id), file).split('\\').join('/'), usd: usd === null ? null : Number(usd), receipt, model, label: 'target (painted, not what the game draws)', at: new Date().toISOString() };
+  d.mood = { path: relative(experienceDir(root, id), file).split('\\').join('/'), usd: usd === null ? null : Number(usd), receipt, model, label: 'target (painted, not what the game draws)', at: new Date().toISOString() };
   writeDecisions(root, id, doc);
   return { ok: true, command: 'style mood', id, direction: dirId, mood: d.mood };
 }
@@ -143,14 +144,14 @@ export async function addGolden(root, id, image, { from = null } = {}) {
   doc.golden = doc.golden ?? [];
   if (doc.golden.length >= 6) throw new Error('six golden images already: remove one first (style golden <id> remove <n>)');
   const n = doc.golden.reduce((m, g) => Math.max(m, Number(/(\d+)\.jpg$/.exec(g.path)?.[1] ?? 0)), 0) + 1;
-  const dir = join(root, 'games', id, BOARD_DIR, 'golden');
+  const dir = join(experienceDir(root, id), BOARD_DIR, 'golden');
   mkdirSync(dir, { recursive: true });
   const file = join(dir, `${n}.jpg`);
   try {
     const sharp = (await import('sharp')).default;
     writeFileSync(file, await sharp(readFileSync(image)).resize(1024, 1024, { fit: 'inside' }).jpeg({ quality: 84, mozjpeg: true }).toBuffer());
   } catch { if (/\.jpe?g$/i.test(extname(image))) copyFileSync(image, file); else throw new Error('sharp could not read that picture'); }
-  doc.golden.push({ path: relative(join(root, 'games', id), file).split('\\').join('/'), from: from ?? relative(root, image), approvedBy: 'person', at: new Date().toISOString() });
+  doc.golden.push({ path: relative(experienceDir(root, id), file).split('\\').join('/'), from: from ?? relative(root, image), approvedBy: 'person', at: new Date().toISOString() });
   writeDecisions(root, id, doc);
   addLatestLine(root, id, `Added golden image ${n} (from ${from ?? relative(root, image)}): every concept is made with it as a reference.`);
   return { ok: true, command: 'style golden', id, golden: doc.golden };
@@ -183,13 +184,13 @@ export async function assetsLineup(root, id, { log = () => {}, scope = null } =
   for (const a of manifest.assets) {
     const f = (a.files ?? []).find((x) => x.role === 'model');
     if (!f) continue;
-    const abs = join(root, 'games', id, f.path);
+    const abs = join(experienceDir(root, id), f.path);
     if (!existsSync(abs)) continue;
     // `inGame`: what the game's code does to it at runtime (drawn at another height, repainted from style.json): the
     // lineup draws it the same way (the repaint as the board's re-tint, the nearest the game's own swap can be shown).
     const scale = a.inGame?.heightM && a.measured?.heightM ? a.inGame.heightM / a.measured.heightM : null;
     // A character stands in its idle pose from its skeleton's clip library (not its bind pose: arms out in a T).
-    const anims = a.rig?.anims && existsSync(join(root, 'games', id, a.rig.anims)) ? readFileSync(join(root, 'games', id, a.rig.anims)).toString('base64') : null;
+    const anims = a.rig?.anims && existsSync(join(experienceDir(root, id), a.rig.anims)) ? readFileSync(join(experienceDir(root, id), a.rig.anims)).toString('base64') : null;
     models.push({ a, input: modelIn(a.id, readFileSync(abs), { label: a.card ? String(a.card).split('/').pop() : a.id, ...(scale ? { scale } : {}), ...(anims ? { anims, pose: 'idle', poseAt: 0.3 } : {}), ...(a.inGame?.tint ? { tint: lightColours({ sky: a.inGame.tint, ground: a.inGame.tint }, tokens.palette).sky } : a.inGame?.repaint ? { retint: true } : Number(a.inGame?.pull) > 0 ? { pull: Number(a.inGame.pull) } : {}) }), abs });
   }
   if (!models.length) return { ok: false, command: 'assets lineup', id, why: `games/${id} has no recorded models yet (assets add, or the models skill)` };

package/lib/template-history.json

@@ -1989,6 +1989,88 @@
      }
     }
    }
+  },
+  "0.37.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Apps: one screen, roles and parts": "4db0abe4cdfac09f",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
+  },
+  "0.37.1": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "c18362ed28975d81",
+     "## Apps: one screen, roles and parts": "4db0abe4cdfac09f",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
   }
  }
 }

package/links/links.d.ts

@@ -0,0 +1,3 @@
+export function randomId(): string;
+export function appLink(address: string, params?: Record<string, string | number | boolean | null | undefined>, base?: string): string;
+export function qrSvg(text: string, options?: { quiet?: number; dark?: string; light?: string; title?: string; minLevel?: 'L' | 'M' | 'Q' | 'H' }): string;

package/links/links.mjs

@@ -0,0 +1,16 @@
+/** Public links, QR and HTTP-safe IDs; the encoder is shared with the wall shell. */
+export { qrSvg } from '../worker/qr.mjs';
+export function randomId() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export function appLink(address, params = {}, base = globalThis.location?.href) {
+  const url = new URL(address, base);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('links use an HTTP(S) address without credentials');
+  for (const [key, value] of Object.entries(params)) {
+    if (value === null || value === undefined) url.searchParams.delete(key);
+    else url.searchParams.set(key, String(value));
+  }
+  return url.href;
+}