@homie-rocks/studio 0.35.1 → 0.37.0

package/lib/rules-types.mjs

@@ -0,0 +1,167 @@
+/** A compiler-only facade: declarations supply contextual types without changing a game's source or its bundle. */
+import { join } from 'node:path';
+import { PACKAGE_ROOT } from './studio.mjs';
+
+const q = JSON.stringify;
+const record = (entries) => `{ ${entries.map(([n, t]) => `${q(n)}: ${t}`).join('; ')} }`;
+function field(f) {
+  if (f.t === 'bit' || f.t === 'press') return 'boolean';
+  if (f.t === 'ref' || f.t === 'text') return 'string';
+  if (f.t === 'vec3' || f.t === 'dir') return 'Vec3';
+  if (f.t === 'list') return `ReadonlyArray<${field(f.of)}>`;
+  if (f.t === 'map') return `Record<string, ${field(f.of)}>`;
+  if (f.t === 'struct') return fields(Object.entries(f.fields));
+  return 'number';
+}
+const fields = (list) => `{ ${list.map(([n, f]) => `get ${q(n)}(): ${field(f)}; set ${q(n)}(value: WriteState<${field(f)}>);`).join(' ')} }`;
+const shapes = (table) => record(Object.entries(table).map(([n, fs]) => [n, fs.length ? fields(fs) : 'Record<string, never>']));
+const value = (v) => v === null ? 'null' : Array.isArray(v) ? `Array<${[...new Set(v.map(value))].join(' | ') || 'never'}>` : typeof v === 'object' ? record(Object.entries(v).map(([n, x]) => [n, value(x)])) : typeof v;
+const picks = (questions) => record(Object.entries(questions).map(([name, question]) => [name,
+  question.type === 'choice' ? (Array.isArray(question.criteria) ? question.criteria : Object.keys(question.criteria)).map(q).join(' | ')
+    : question.type === 'score' ? 'number' : 'boolean']));
+// Vocabulary arguments are admitted by argsWhy; object offers expose their id.
+function vocabularyTypes(vocab, view) {
+  if (!vocab) return { goals: 'Goal', asks: 'GuideRequest', floorAsks: 'GuideRequest', decision: 'GuideDecision' };
+  const argument = source => {
+    if (source === 'player') return 'number';
+    if (Array.isArray(source)) return source.map(q).join(' | ') || 'never';
+    let fd = view[source?.slice(5)];
+    if (fd?.t === 'list') fd = fd.of;
+    if (fd?.t === 'struct') fd = fd.fields.id;
+    return fd && ['text', 'ref', 'u8', 'i8', 'u16', 'i16', 'u32', 'i32', 'fix', 'tick', 'ticks'].includes(fd.t) ? field(fd) : 'never';
+  };
+  const union = (table, discriminator, metadata) => Object.entries(table ?? {}).map(([name, def]) =>
+    `{ readonly ${discriminator}: ${q(name)}; readonly args: Readonly<${record(Object.entries(def.args ?? {}).map(([key, source]) => [key, argument(source)]))}>; ${metadata} }`).join(' | ') || 'never';
+  // A floor names one goal and one line, each with exactly its declared arguments, as argsWhy admits them.
+  const choice = (table, name, args) => [`{ ${name}?: null; ${args}?: Record<string, never> }`, ...Object.entries(table ?? {}).map(([n, def]) => {
+    const list = Object.entries(def.args ?? {}).map(([key, source]) => [key, argument(source)]);
+    return `{ ${name}: ${q(n)}; ${args}${list.length ? `: Readonly<${record(list)}>` : '?: Record<string, never>'} }`;
+  })].join(' | ');
+  return { goals: union(vocab.goals, 'goal', "readonly from: 'brain' | 'floor'; readonly at: number; readonly asked: boolean; readonly state: 'active' | 'done' | 'failed'"),
+    asks: union(vocab.asks, 'k', 'readonly from: number; readonly at: number'),
+    // The arguments of a request the server admitted carry a compile-time mark, so a floor may forward
+    // { goal: ask.k, args: ask.args } without narrowing while arguments it writes itself must fit their goal.
+    floorAsks: 'GameRequest extends infer A ? A extends { args: object } ? Omit<A, \'args\'> & { readonly args: A[\'args\'] & Admitted } : never : never',
+    decision: `(${choice(vocab.goals, 'goal', 'args')} | { goal: Extract<GameRequest['k'], GameGoal['goal']>; args: FloorRequest['args'] }) & (${choice(vocab.lines, 'say', 'sayArgs')})` };
+}
+export function rulesTypes(checked, tune) {
+  const { schema: s, declarations: d } = checked;
+  const vocabulary = vocabularyTypes(checked.vocab, d.view);
+  const kind = (k) => `Self<${fields(k.fields)}, ${fields(k.motion)}, ${fields(k.input)}, ${q(k.name)}, ${k.player}, GameGoal>`;
+  const all = record(s.kinds.map((k) => [k.name, kind(k)]));
+  const create = record(s.kinds.filter((k) => !k.player).map((k) => [k.name, k.fields.length ? fields(k.fields) : 'Record<string, never>']));
+  const asks = record(Object.entries(d.asks).map(([n, a]) => [n, fields(a.state)]));
+  const tunables = { ...Object.fromEntries(Object.entries(tune.public ?? {}).map(([n, v]) => [n, v?.value ?? v])), ...Object.fromEntries(Object.entries(tune).filter(([n]) => n !== 'public').map(([n, v]) => [n, v?.value ?? v])) };
+  const parameters = `${shapes(d.events)}, ${shapes(s.effects)}, ${fields(s.shared)}, ${all}, ${create}, ${asks}, ${value(tunables)}`;
+  const answer = scope => checked.answerScopes ? `Extract<Answers, { ask: ${[...new Set([...(checked.answerScopes.scopes[scope] ?? []), ...checked.answerScopes.common])].map(q).join(' | ') || 'never'} }>` : 'Answers';
+  const entities = record(s.kinds.map((k) => [k.name, `Entity<W, ${kind(k)}, ${fields(k.input)}, Events, Commands, ${fields(Object.entries(d.view))}, ${answer(k.name)}, GameGoal, FloorRequest, GameDecision>`]));
+  const joins = s.kinds.filter((k) => k.player).map((k) => `{ kind: ${q(k.name)}; at: Point; heading?: Point; fields?: Partial<WriteState<${fields(k.fields)}>>; motion?: Partial<WriteState<${fields(k.motion)}>> }`).join(' | ') || 'never';
+  const moves = `{ ${s.kinds.filter((k) => k.radius > 0).map((k) => `${q(k.name)}${k.player ? '' : '?'}: (body: MoveBody<${fields(k.motion)}>, input: ReadonlyState<${fields(k.input)}>, ctx: MoveContext<${value(checked.publicTune)}, ${fields(k.motion)}>) => undefined`).join('; ')} }`;
+  return `// Generated from this game's checked declarations. The build always uses strict compiler settings.
+export * from ${q(join(PACKAGE_ROOT, 'rules/rules.ts'))};
+import type { RulesDef, Vec3, Fields } from ${q(join(PACKAGE_ROOT, 'rules/rules.ts'))};
+import type { World, Self, Entity, Point, MoveBody, MoveContext, ReadonlyState, WriteState, EventData, RoomEvents, Goal, GuideRequest, GuideDecision } from ${q(join(PACKAGE_ROOT, 'rules/types.ts'))};
+export type GameGoal = ${vocabulary.goals};
+export type GameRequest = ${vocabulary.asks};
+declare const admitted: unique symbol;
+type Admitted = { readonly [admitted]: true };
+type FloorRequest = ${vocabulary.floorAsks};
+type GameDecision = ${vocabulary.decision};
+type Events = ${shapes(d.events)};
+type Commands = ${shapes(s.commands)};
+type Answers = ${Object.entries(d.asks).map(([n, a]) => `{ ask: ${q(n)}; by: 'local' | 'ai' | 'floor'; picks: ${picks(a.questions)}; why?: string }`).join(' | ') || 'never'};
+type GameRoomEvents = Omit<RoomEvents<Events>, 'answer'> & { answer: ${answer('room')} };
+export type GameWorld = W;
+export type GameSelf<K extends keyof GameEntities> = GameEntities[K];
+type GameEntities = ${all};
+type W = World<${parameters}>;
+type RW = World<${parameters}, true>;
+type Definition = Omit<RulesDef, 'entities' | 'room' | 'move' | 'asks'> & {
+  entities: ${entities}; move?: Moves;
+  room?: { rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number };
+    start?: (world: RW) => void;
+    join?: (ctx: Pick<W, 'map' | 'shared' | 'tune' | 'math' | 'round'>, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string }) => ${joins};
+    on?: { [K in keyof (Omit<Events, keyof GameRoomEvents> & GameRoomEvents)]?: (world: RW, event: EventData<(Omit<Events, keyof GameRoomEvents> & GameRoomEvents)[K]>) => void };
+  };
+  asks?: ${record(Object.entries(d.asks).map(([n, a]) => [n, `{ state: Fields; questions: ${value(a.questions)}; floor: (state: ReadonlyState<${fields(a.state)}>) => ${picks(a.questions)} }`]))};
+};
+type Moves = ${moves};
+export declare function defineRules(def: Definition): Definition;
+export declare function defineMove(def: Moves): Moves;
+`;
+}
+
+/** The view reads the same declared fields and names as the rules. */
+export function rulesViewTypes(checked) {
+  const s = checked.schema;
+  const entities = record(s.kinds.map(k => [k.name, `ReadonlyState<Omit<GameSelf<${q(k.name)}>, 'input'>> & { readonly mine?: boolean }`]));
+  const effects = record(Object.entries(s.effects).map(([n, fs]) => [n, `ReadonlyState<${fields(fs)}> & { readonly at?: Vec3; readonly id?: string; readonly tick: number }`]));
+  const input = s.kinds.filter(k => k.player).map(k => `Partial<${fields(k.input)}>`).join(' | ') || 'Record<string, never>';
+  return `export * from ${q(join(PACKAGE_ROOT, 'rules/view.ts'))};
+import type { Room as BaseRoom, OpenRoomOptions, RoomRound, RoomStatus } from ${q(join(PACKAGE_ROOT, 'rules/view.ts'))};
+import type { ReadonlyState, WriteState } from ${q(join(PACKAGE_ROOT, 'rules/types.ts'))};
+import type { Vec3 } from ${q(join(PACKAGE_ROOT, 'rules/rules.ts'))};
+import type { GameSelf, GameGoal, GameRequest } from './rules';
+type Entities = ${entities};
+type Commands = ${shapes(s.commands)};
+type Effects = ${effects} & { enter: Entity; leave: Entity; placed: Entity; round: RoomRound | null; status: RoomStatus; say: { readonly slot: number; readonly seat: number | null; readonly text: string; readonly line?: string; readonly kind?: string; readonly args: Readonly<Record<string, unknown>> }; goal: { readonly slot: number; readonly goal: GameGoal; readonly prev: GameGoal | null; readonly askAt: number | null }; ask: { readonly slot: number; readonly k: string; readonly ask?: string; readonly from: number; readonly at: number; readonly args: Readonly<Record<string, unknown>> } };
+export type Entity = Entities[keyof Entities];
+// A request's own arguments; a button's k and args, still a union, pass together.
+type AskArgs<K> = GameRequest extends infer A ? A extends { k: infer N; args: infer X } ? K extends N ? X : never : never : never;
+export type Room<R = never> = Omit<BaseRoom<R>, 'me' | 'each' | 'get' | 'on' | 'shared' | 'input' | 'command' | 'tune' | 'ask' | 'askButtons'> & {
+ // A name written out must be one of the vocabulary's, with its arguments. A name the view only has as a text (a list
+ // of buttons it built itself) passes as it is, with any arguments: the server checks those when they arrive.
+ ask<K extends string>(id: string, k: string extends K ? K : K extends GameRequest['k'] ? K : GameRequest['k'], ...args: string extends K ? [args?: Readonly<Record<string, unknown>>] : {} extends AskArgs<K> ? [args?: AskArgs<K>] : [args: AskArgs<K>]): void;
+ askButtons(id: string, offer?: Record<string, unknown>): Array<GameRequest extends infer A ? A extends { k: string; args: object } ? Pick<A, 'k' | 'args'> & { readonly text: string } : never : never>;
+ readonly me: Extract<Entity, { seat: number }> | null;
+ readonly shared: ReadonlyState<${fields(s.shared)}>;
+ readonly tune: ReadonlyState<${value(checked.publicTune)}>;
+ each<K extends keyof Entities>(kind: K, fn: (entity: Entities[K]) => void): void;
+ get(id: string): Entity | null;
+ on<K extends keyof Effects>(name: K, fn: (event: Effects[K]) => void): () => void;
+ input(sample: ${input}): void;
+ command<K extends keyof Commands>(name: K, ...data: {} extends Commands[K] ? [data?: Commands[K]] : [data: Commands[K]]): void;
+};
+export declare function openRoom<R = never>(options?: OpenRoomOptions): Room<R>;
+`;
+}
+
+/** Answers return to their caller. A room cannot receive an entity's ask response.
+ * Literal asks in a known handler restrict that scope; shared helpers conservatively
+ * contribute their asks to every scope, and a dynamic name retains the full union.
+ */
+export async function rulesAnswerScopes(entry) {
+  const [{ parse }, { default: traverseModule }, fs, path] = await Promise.all([
+    import('@babel/parser'), import('@babel/traverse'), import('node:fs'), import('node:path'),
+  ]);
+  const traverse = traverseModule.default ?? traverseModule;
+  const scopes = new Map(); const common = new Set(); const seen = new Set(); let dynamic = false;
+  const key = node => node?.key?.name ?? node?.key?.value;
+  function read(file) {
+    if (seen.has(file)) return; seen.add(file);
+    const ast = parse(fs.readFileSync(file, 'utf8'), { sourceType: 'module', plugins: ['typescript'] });
+    traverse(ast, {
+      ImportDeclaration(p) {
+        const name = p.node.source.value; if (!name.startsWith('.')) return;
+        const base = path.resolve(path.dirname(file), name);
+        const target = [base, `${base}.ts`, `${base}.js`, path.join(base, 'index.ts')].find(f => fs.existsSync(f) && fs.statSync(f).isFile());
+        if (target) read(target);
+      },
+      CallExpression(p) {
+        const callee = p.node.callee;
+        if (callee.type !== 'MemberExpression' || (callee.property.name ?? callee.property.value) !== 'ask') return;
+        const name = p.node.arguments[0];
+        if (name?.type !== 'StringLiteral') { dynamic = true; return; }
+        let scope;
+        for (let a = p.parentPath; a; a = a.parentPath) {
+          if (a.isObjectProperty() && key(a.node) === 'room') { scope = 'room'; break; }
+          if (a.isObjectProperty() && a.parentPath?.isObjectExpression() && key(a.parentPath.parentPath?.node) === 'entities') { scope = key(a.node); break; }
+        }
+        if (!scope) common.add(name.value);
+        else { const names = scopes.get(scope) ?? new Set(); names.add(name.value); scopes.set(scope, names); }
+      },
+    });
+  }
+  read(entry);
+  return dynamic ? null : { common: [...common], scopes: Object.fromEntries([...scopes].map(([k, names]) => [k, [...names]])) };
+}

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,16 @@ 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. |
 
+## 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 +711,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 +740,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 +890,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 = {} }) {
-  const cfg = { v: 1, game: meta.id, name: meta.name, site: String(site ?? '').replace(/\/+$/, ''), ver: meta.netplayVersion ?? '', ...(movement ? { movement } : {}), params, share, colours, 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';
@@ -388,6 +389,7 @@ export async function standalonePlan(root, id, opts = {}) {
 
 /* ------------------------------------------------------------------ the web folder */
 
+const readJson = (file) => { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } };
 const copyTree = (from, to) => { rmSync(to, { recursive: true, force: true }); cpSync(from, to, { recursive: true, dereference: true }); };
 
 /**
@@ -401,8 +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));
-  const m = meta ?? standaloneMeta(studio ?? readStudio(root), game);
-  writeFileSync(join(web, 'config.js'), configScript(m, { target, site, share: sharePlaces(game.screen?.share), colours: uiOf(game), movement: game.netplay?.movement ?? game.movement ?? null }));
+  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, ...(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

@@ -1890,7 +1890,10 @@
      "## Art direction and models": "a48fff7bf0a5f2fc",
      "## Running live games (the back office)": "51ebf2ab756f6e4d",
      "## Servers and AI seats": "98d08705087a33ec",
-     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Selling things (the shop)": [
+      "57c04f6526e16890",
+      "9e020d69dd6a954e"
+     ],
      "## Continuing a build from the Claude app": "0d68081e924ca419",
      "## Rules": "2e6b29afb85dcf7e",
      "## Telling Homie": "80b46fdd9e578db8",
@@ -1946,6 +1949,87 @@
      }
     }
    }
+  },
+  "0.36.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",
+     "## 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.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"
+      }
+     }
+    }
+   }
   }
  }
 }