@homie-rocks/studio 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -17,6 +17,22 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.37.0] - 2026-10-09
+
+**Plugin 0.38.0** · [#72](https://github.com/homie-rocks/homie/pull/72)
+
+A studio holds apps beside its games, with public player cards and a shop you can find.
+
+### Added
+
+- Apps are a studio kind: `apps/<id>/app.json`, `app new` / `app_make`, one morphing screen with roles and parts, and a 3D welcome queue starter. Apps share game build, rooms, screen, shop, parts and standalone paths; their buttons say Open and Scan to join.
+- App records outlast rooms in the studio's D1, with validated fields, role permissions, account grants, private staff addresses and optimistic updates. Public links/QR and cryptographic IDs work on LAN HTTP; `dev --lan` prints phone-reachable addresses.
+- Local rules rebuilds retry transient wall-clock timing rejections up to three times, keeping the last good build and the existing performance guard.
+- App checks exercise a real action across a wall and two phones and prove reconnect without requiring rounds. The app skill and scaffold guidance cover roles, single-screen composition, engine/media reuse and customer store builds. Parts now include app components, music and video with explicit intended uses and the existing licence checks; sharing adds no selling flow.
+
+- Public apps carry the same player card as games, opening their own screen and using their own picture and wording.
+- An open shop has a visible Shop button above the play/open screen, with room reserved for it. Set `screen.shop` to `false` to hide it; `createShop().open()` or `.open(item)` opens the same shop from your own button. Closed shops and experiences with nothing for sale show no control.
+
 ## [0.36.0] - 2026-10-08
 
 **Plugin 0.37.0** · [#68](https://github.com/homie-rocks/homie/pull/68) · [#73](https://github.com/homie-rocks/homie/pull/73)

package/README.md

@@ -1,11 +1,13 @@
 # @homie-rocks/studio
 
-A studio for games, music and video on its own Cloudflare. One repository (`AGENTS.md`,
-`games/`, `music/`, `videos/`, `posts/`, `site/`), multiplayer games on the Homie netplay
+A studio for games, apps, music and video on its own Cloudflare. One repository (`AGENTS.md`,
+`games/`, `apps/`, `music/`, `videos/`, `posts/`, `site/`), multiplayer games on the Homie netplay
 contract (every browser renders, strangers meet in public rooms, bots fill seats, rounds
 restart), and a site Worker with Table/Lobby Durable Objects and D1 that the studio deploys
 to its own Cloudflare account with Wrangler. The homie.rocks directory lists the games.
 
+Apps are one morphing screen, its roles and its parts: a customer phone, a staff tablet and a wall can share a 3D scene without rounds or scores. `homie-studio app new welcome` creates a working welcome queue in `apps/welcome/`; install its declared dependencies, build, then use `dev --lan` and the printed Wi-Fi address. `check welcome --url <origin>` proves a shared action and reconnect across three screens. Staff permissions, lasting D1 records, public QR/link helpers and customer standalone builds use the existing studio machinery. See [the app guide](apps/APPS.md).
+
 Most people never run this by hand: the Homie plugin for Claude Code, Codex and Grok does,
 and the person approves Cloudflare once in their browser.
 

package/app-starters/welcome/app.json

@@ -0,0 +1,106 @@
+{
+  "id": "welcome",
+  "name": "Welcome together",
+  "blurb": "A little place to gather. Join the queue, keep your ticket, and see when it is your turn.",
+  "entry": "src/main.ts",
+  "roles": {
+    "customer": {
+      "signIn": false,
+      "can": [
+        "read:queue",
+        "create:queue"
+      ]
+    },
+    "wall": {
+      "signIn": false,
+      "can": [
+        "read:queue"
+      ]
+    },
+    "staff": {
+      "signIn": true,
+      "can": [
+        "read:queue",
+        "update:queue",
+        "delete:queue"
+      ]
+    }
+  },
+  "surfaces": {
+    "phone": "customer",
+    "wall": "wall",
+    "kiosk": "customer",
+    "tablet": "staff"
+  },
+  "words": {
+    "open": "Open",
+    "join": "Scan to join",
+    "one": "person",
+    "many": "people"
+  },
+  "records": {
+    "persist": true,
+    "collections": {
+      "queue": {
+        "fields": {
+          "label": {
+            "type": "string",
+            "required": true,
+            "maxLength": 24
+          },
+          "status": {
+            "type": "string",
+            "required": true,
+            "enum": [
+              "waiting",
+              "called"
+            ],
+            "initial": "waiting"
+          }
+        }
+      }
+    }
+  },
+  "parts": [
+    "queue",
+    "ticket",
+    "welcome-scene"
+  ],
+  "netplay": {
+    "v": 1,
+    "public": true,
+    "version": "1",
+    "params": [
+      "role",
+      "surface",
+      "ticket"
+    ]
+  },
+  "playerCard": false,
+  "chat": false,
+  "agents": {
+    "vote": false
+  },
+  "watch": "overview",
+  "screen": {
+    "join": "bottom-right",
+    "share": "top-right"
+  },
+  "needs": {
+    "three": "0.185.1",
+    "@homie-rocks/camera": "0.2.1",
+    "@homie-rocks/geom": "0.1.1"
+  },
+  "check": {
+    "action": "[data-join]",
+    "observe": "[data-count]",
+    "surface": "phone"
+  },
+  "landing": {
+    "pitch": "A warm welcome. A place in line. One screen, together.",
+    "controls": {
+      "phone": "Join once and keep your ticket.",
+      "computer": "Staff call the next person from their signed-in tablet."
+    }
+  }
+}

package/app-starters/welcome/index.html

@@ -0,0 +1,4 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><title>Welcome together</title>
+<style>
+*{box-sizing:border-box}html,body{margin:0;width:100%;height:100%;overflow:hidden;background:#122f38;color:#fff4da;font-family:ui-rounded,system-ui,sans-serif}canvas{position:fixed;inset:0;width:100%;height:100%}main{position:fixed;inset:0;padding:clamp(22px,5vw,72px);pointer-events:none;display:flex;flex-direction:column;justify-content:space-between}header{max-width:580px}.eyebrow{font-size:11px;letter-spacing:.24em;text-transform:uppercase;color:#b7d8ce}h1{font-size:clamp(46px,7.5vw,108px);line-height:.94;letter-spacing:-.06em;margin:18px 0}p{line-height:1.5;max-width:31em;color:#cce0d4}.panel{pointer-events:auto;background:#fff4da;color:#163b40;width:min(390px,100%);border-radius:24px;padding:22px;box-shadow:0 18px 70px #061e3244;transform:translateY(0);transition:transform .7s,background .7s}.panel.called{background:#c6efb3;transform:translateY(-10px)}.number{font-size:clamp(34px,5vw,60px);font-weight:750;letter-spacing:-.05em}button{border:0;min-height:50px;border-radius:14px;padding:12px 20px;font:700 16px system-ui;background:#163b40;color:#fff4da;cursor:pointer;width:100%;touch-action:manipulation}button:disabled{opacity:.45;cursor:default}button:focus-visible{outline:3px solid #ffb655;outline-offset:4px}.panel p{color:#49655f;font-size:13px;margin:10px 0}.line{display:flex;justify-content:space-between;align-items:center;margin-bottom:16px}.tag{font:600 12px system-ui;text-transform:uppercase;letter-spacing:.1em}#ticket-qr{width:80px;height:80px;float:right;margin:0 0 6px 14px}#ticket-qr:empty{display:none}#ticket-qr svg{width:100%;height:100%}.live{display:flex;gap:8px;align-items:center;font-size:12px}.dot{width:7px;height:7px;background:#c6efb3;border-radius:50%}#status{min-height:18px;font-size:12px}body.wall .panel{width:min(510px,45vw)}body.wall header{max-width:800px}body.staff .panel{width:420px}footer{position:absolute;right:35px;bottom:24px;font-size:10px;letter-spacing:.15em;color:#9fbbb4}@media(max-width:600px){main{padding:78px 22px 26px}h1{font-size:48px}header p{font-size:13px;max-width:245px}.panel{padding:18px}footer{display:none}}@media(max-height:520px){main{flex-direction:row;align-items:center;padding:60px 24px 20px;gap:30px}h1{font-size:40px}.panel{max-width:310px}header p{display:none}}@media(prefers-reduced-motion:reduce){*{transition:none!important}}
+</style></head><body><canvas aria-hidden="true"></canvas><main><header><div class="eyebrow">A space for everyone</div><h1>Good things<br>start here.</h1><p id="intro">Take a little moment. We’ll keep your place while you settle in.</p><div class="live"><i class="dot"></i><span id="connection">Joining the room…</span></div></header><section class="panel" aria-label="Your place"><div id="ticket-qr"></div><div class="line"><span class="tag" id="panel-label">Welcome in</span><span><b data-count>0</b> waiting</span></div><div class="number" id="ticket">Make yourself at home.</div><p id="detail">No account needed. Just a place in line.</p><button data-join>Join the queue</button><button data-next hidden>Call the next person</button><div id="status" role="status" aria-live="polite"></div></section><footer>ONE PLACE · TOGETHER</footer></main><script type="module" src="./assets/main.js"></script></body></html>

package/app-starters/welcome/src/main.ts

@@ -0,0 +1,107 @@
+import * as THREE from 'three';
+import { damp1 } from '@homie-rocks/camera/spring.js';
+import { chamferBox } from '@homie-rocks/geom/chamfer.js';
+import { createNetplay } from '@homie-rocks/studio/netplay';
+import { createAppRecords, type AppRecord } from '@homie-rocks/studio/apps';
+import { appLink, qrSvg, randomId } from '@homie-rocks/studio/links';
+
+type Ticket = { label: string; status: string };
+const net = createNetplay<{ light: number }>({ game: 'welcome', maxPlayers: 32, snapshotHz: 2 });
+const role = net.params.role ?? 'customer';
+document.body.className = role;
+const $ = <T extends HTMLElement = HTMLElement>(s: string) => document.querySelector<T>(s)!;
+const join = $<HTMLButtonElement>('[data-join]');
+const next = $<HTMLButtonElement>('[data-next]');
+const records = createAppRecords<Ticket>({ collection: 'queue' });
+let rows: AppRecord<Ticket>[] = [];
+let mine = net.params.ticket ?? '';
+let pending = false;
+let loaded = false;
+let light = 0;
+let refreshing = false;
+join.hidden = role !== 'customer'; next.hidden = role !== 'staff';
+if (role === 'wall') { $('h1').innerHTML = 'You’re in<br>good company.'; $('#intro').textContent = 'A warm welcome, one person at a time. Scan to find your place.'; }
+if (role === 'staff') { $('h1').innerHTML = 'Make someone’s<br>day brighter.'; $('#intro').textContent = 'Your welcome desk. Call the next person when you are ready.'; }
+function paint() {
+  const waiting = rows.filter((r) => r.data.status === 'waiting');
+  const called = rows.filter((r) => r.data.status === 'called').at(-1);
+  const own = rows.find((r) => r.id === mine);
+  $('[data-count]').textContent = String(waiting.length);
+  $('#panel-label').textContent = role === 'customer' ? (own ? 'Your ticket' : 'Welcome in') : 'Now welcoming';
+  $('#ticket').textContent = role === 'customer' ? own ? `No. ${own.data.label}` : 'Make yourself at home.' : called ? `No. ${called.data.label}` : 'Ready when you are.';
+  $('#detail').textContent = own?.data.status === 'called' ? 'It’s your turn. Come on over!' : own ? `You have a place. ${Math.max(0, waiting.findIndex((r) => r.id === mine))} ahead of you.` : role === 'customer' ? 'No account needed. Just a place in line.' : waiting.length ? `${waiting.length} ${waiting.length === 1 ? 'person is' : 'people are'} waiting for a welcome.` : 'The next arrival will appear here.';
+  $('.panel').classList.toggle('called', own?.data.status === 'called' || (role !== 'customer' && !!called));
+  join.hidden = role !== 'customer' || !!own;
+  join.disabled = pending || !loaded; next.disabled = pending || !waiting.length;
+}
+async function refresh() {
+  if (refreshing) return; refreshing = true;
+  try { rows = await records.list(); loaded = true; $('#status').textContent = ''; paint(); }
+  catch (e) { $('#status').textContent = (e as Error).message; }
+  finally { refreshing = false; }
+}
+async function action(fn: () => Promise<unknown>) {
+  pending = true; paint();
+  try { await fn(); net.send('records-changed'); await refresh(); }
+  catch (e) { $('#status').textContent = (e as Error).message; }
+  finally { pending = false; paint(); }
+}
+join.onclick = () => action(async () => {
+  mine = randomId();
+  const label = mine.slice(0, 4).toUpperCase();
+  await records.create({ label, status: 'waiting' }, mine);
+  // Build a customer link from a clean address, never from a private staff URL.
+  const origin = new URL((window as any).HOMIE_NET.url.replace(/^ws/, 'http')).origin;
+  const url = appLink(`/${(window as any).HOMIE_NET.url.split('/')[3]}/open`, { ticket: mine, room: (window as any).HOMIE_NET.room }, origin);
+  $('#ticket-qr').innerHTML = qrSvg(url, { title: 'Keep your ticket' });
+  parent.postMessage({ type: 'homie-app-ticket', ticket: mine }, '*');
+});
+next.onclick = () => action(async () => {
+  const first = rows.find((r) => r.data.status === 'waiting');
+  if (first) await records.update(first, { ...first.data, status: 'called' });
+});
+// The room carries scene state and change notices; records always come from the authorized database.
+net.on('event', (e) => { if (e.k === 'records-changed') { if (net.role === 'host') net.send('records-changed'); void refresh(); } });
+net.on('snapshot', (s) => { light = s.d.light; });
+net.on('link', () => { void refresh(); });
+setInterval(() => { if (net.role === 'host') { light = net.now() / 1000; net.snapshot({ light }); } $('#connection').textContent = net.link === 'online' ? 'Here together · live' : 'Reconnecting…'; }, 500);
+setInterval(() => void refresh(), 2000); // recover a missed notice; no dependency on a trusted browser host
+void refresh(); paint();
+
+// A single sculptural scene. Queue arrivals unfold the lanterns; the camera follows your context.
+const renderer = new THREE.WebGLRenderer({ canvas: $('canvas'), antialias: true, alpha: false });
+renderer.setPixelRatio(Math.min(devicePixelRatio, 1.5)); renderer.setClearColor('#122f38');
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+const scene = new THREE.Scene(); scene.fog = new THREE.Fog('#122f38', 12, 30);
+const camera = new THREE.PerspectiveCamera(37, 1, .1, 60);
+scene.add(new THREE.HemisphereLight('#fff1ce', '#214f5b', 3));
+const sun = new THREE.DirectionalLight('#ffd2a2', 5); sun.position.set(-3, 8, 6); scene.add(sun);
+const mat = (color: string, metalness = 0) => new THREE.MeshStandardMaterial({ color, roughness: .45, metalness });
+const cream = mat('#f4d8a4'); const green = mat('#9dbda0'); const gold = mat('#e8a953', .35);
+const stage = new THREE.Group(); scene.add(stage); stage.position.set(1.5, -.9, 0);
+const plinth = new THREE.Mesh(new THREE.CylinderGeometry(3.5, 3.7, .35, 64), mat('#254952')); plinth.position.y = -.4; stage.add(plinth);
+const ring = new THREE.Mesh(new THREE.TorusGeometry(2.4, .055, 10, 90), gold); ring.rotation.x = Math.PI / 2; ring.position.y = -.15; stage.add(ring);
+const arch = new THREE.Mesh(new THREE.TorusGeometry(1.65, .18, 16, 64, Math.PI), cream); arch.position.set(0, .15, -.8); stage.add(arch);
+for (const x of [-1.65, 1.65]) { const leg = new THREE.Mesh(chamferBox(.36, 1.5, .36, .08), cream); leg.position.set(x, -.55, -.8); stage.add(leg); }
+const lanterns: THREE.Group[] = [];
+for (let i = 0; i < 12; i++) {
+  const g = new THREE.Group(); const body = new THREE.Mesh(chamferBox(.42, .7, .42, .08), i % 3 ? green : gold); g.add(body);
+  const cap = new THREE.Mesh(new THREE.SphereGeometry(.14, 16, 12), cream); cap.position.y = .5; g.add(cap);
+  const angle = i * Math.PI * 2 / 12; g.position.set(Math.sin(angle) * 2.35, 0, Math.cos(angle) * 2.35); stage.add(g); lanterns.push(g);
+}
+const reduced = matchMedia('(prefers-reduced-motion: reduce)');
+const vel = { v: 0 }; let distance = 10; let last = performance.now();
+function resize() { renderer.setSize(innerWidth, innerHeight); camera.aspect = innerWidth / innerHeight; camera.updateProjectionMatrix(); }
+addEventListener('resize', resize); resize();
+function draw(now: number) {
+  requestAnimationFrame(draw); const dt = Math.min(.05, (now - last) / 1000); last = now;
+  const waiting = rows.filter((r) => r.data.status === 'waiting').length;
+  distance = damp1(distance, mine ? 8.7 : 10.8, vel, .8, dt);
+  const phone = innerWidth < 600;
+  camera.position.set(phone ? 7 : 6, phone ? 6 : 5, distance); camera.lookAt(phone ? 1 : -.4, .6, 0);
+  stage.position.x = phone ? 1.8 : 2.4;
+  stage.rotation.y = reduced.matches ? 0 : Math.sin(light * .12) * .09;
+  lanterns.forEach((g, i) => { const target = i < waiting ? 1 : .28; g.scale.y += (target - g.scale.y) * (1 - Math.exp(-dt * 5)); g.position.y = .18 + (reduced.matches ? 0 : Math.sin(now / 1000 + i) * .05); });
+  renderer.render(scene, camera);
+}
+requestAnimationFrame(draw);

package/apps/APPS.md

@@ -0,0 +1,61 @@
+# One screen, roles, parts
+
+`homie-studio app new welcome` writes `apps/welcome/app.json` and the welcome scene. Games and apps share one ID namespace, bundle/room/TV/watch pipeline, parts, shop and standalone builds. Source apps build into the compatibility asset namespace `site/dist/games/<id>`; `games.json` uses `kind: "app"`. Public manifests expose `apps[]` with `open` and `wall` addresses separately from `games[]`.
+
+Open `/<id>/open`, its landing `/<id>/`, or its wall `/<id>/tv`. `?surface=kiosk` and `?role=customer` choose a declared public presentation. The phone surface must be public for standalone customer builds. Every app remains one view that transforms; roles choose what is visible and permitted, not a menu of pages.
+
+## Lasting records
+
+The studio's existing D1 stores app records independently of room checkpoints. Deploy/dev apply `0014_studio_apps.sql`; old studios gain it through the normal migration helper. Previews without D1 return a clear unavailable response, never pretend to persist. Room saves still expire according to the room contract.
+
+```ts
+import { createAppRecords } from '@homie-rocks/studio/apps';
+const queue = createAppRecords<{ label: string; status: string }>({ collection: 'queue' });
+const rows = await queue.list();
+await queue.create({ label: 'A17', status: 'waiting' });
+await queue.update(rows[0], { ...rows[0].data, status: 'called' });
+await queue.remove(rows[0]);
+queue.dispose();
+```
+
+The shell handles requests only from its own frame and uses its own role, link and account, never authority claimed by the message. The Worker checks every request. Roles declare `signIn: boolean` and `can: ["read:queue", "create:queue", "update:queue", "delete:queue"]`. Collections declare fields with `type` (string/number/boolean), optional `required`, `maxLength`, `enum`, and `initial` (the only value allowed on create). Unknown fields are refused. Records are at most 8 KB, collection reads at most 1,000 records, request bodies at most 12 KB. A full collection refuses creates. This is a small operational helper, not an unbounded ledger.
+
+Generate a fresh ID for every new record; never reuse a deleted ID. Updates and deletes compare `version` atomically. Conflicts return 409; reload and resolve them. A successful write is committed before acknowledgement. Records are scoped by app and collection, not by room. Deleting a room does not delete records. With `records.persist: false`, use netplay keyed state for transient data instead. Database failures are visible and never replaced with fabricated local success.
+
+Use existing netplay events for refresh notices and shared animation. A missed or malicious notice cannot change authoritative records: reload them on reconnect and at a bounded fallback interval. The starter polls every two seconds and accelerates on room notices. Browser hosts remain untrusted for business data. Public collection reads reveal the whole public collection; ticket IDs and UI filtering are not access control. Use separate protected collections for private data.
+
+## Staff
+
+`homie-studio app role welcome staff --url <origin>` returns an unpredictable role address for the owner. Add `--player <account-id>` to grant an existing non-guest account, or `--revoke` with that player to remove it. The command reuses the office's short-lived owner key. Accounts/passkeys and the office owner's existing session are reused. An anonymous browser with the link goes to `/account/` to sign in; a signed-in account without a grant receives 403. Every record call rechecks the grant, so revocation applies to open tablets too.
+
+The private address hides the staff entrance; it is not a bearer permission. It is never in public metadata. Passkeys require HTTPS or localhost. `dev --lan` exposes the local site to the same Wi-Fi, but does not weaken staff authentication. On local HTTP, provision test sessions explicitly in tests or use a secure local origin for real sign-in.
+
+## Links and plain HTTP
+
+```ts
+import { appLink, qrSvg, randomId } from '@homie-rocks/studio/links';
+const ticket = randomId(); // 128 cryptographic bits through getRandomValues
+const url = appLink('/welcome/open', { ticket, room: 'main' }, 'https://studio.example');
+const svg = qrSvg(url, { title: 'Your ticket' });
+```
+
+The QR encoder is the existing wall encoder, publicly exported with types. Links allow HTTP(S), preserve parameters and encode values. Do not copy `access` or any other private parameter into a public ticket. The helper works on LAN HTTP, where `crypto.randomUUID` may not exist.
+
+## Parts, check and stores
+
+Parts import exactly as games do (`@parts/<id>` or `@parts/<host>/<id>`), with the same provenance and credit checks. `check.action` and `check.observe` name real UI selectors: the checker clicks on a phone, waits for changed text on wall and both phones, then reloads the actor and checks again. `check.params` optionally supplies public URL parameters (for example `{ "ticket": "404" }`) to all three surfaces so the action can address an existing sample record. The checker always chooses its own room. No round hooks are required. This performs the declared action and writes real records: use a local/test studio or a workflow explicitly safe to exercise.
+
+`homie-studio standalone plan/build <app-id>` reuses Electron/Capacitor and the same built bundle. Public customer record calls use the existing standalone origin allowlist; credentials are never shared across origins. Native staff sign-in, private collections, offline record writes, native billing and automatic store upload are not implemented. Existing game standalone behavior is unchanged. A store build still needs its normal local SDK, signing and store review.
+
+## Shop button on the screen
+
+An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to hide this button (merge with any existing screen settings). The room panel and your own shop buttons still work. Closed shops, kids policies and an empty selection show no button.
+
+```ts
+import { createShop } from '@homie-rocks/studio/shop';
+const shop = createShop();
+shopButton.onclick = () => shop.open();
+itemButton.onclick = () => shop.open('supporter');
+```
+
+These calls open the same shop in games and apps. Inside a player card, purchases leave for the studio's shop; ordinary play/open pages start Stripe checkout. The studio's TV and kids policies still apply.

package/apps/apps.ts

@@ -0,0 +1,28 @@
+/** Lasting records through the same sandbox bridge used by saves and the shop. */
+import { randomId } from '../links/links.mjs';
+export interface AppRecord<T> { id: string; data: T; version: number; updatedAt: number }
+export function createAppRecords<T extends Record<string, unknown>>({ collection }: { collection: string }) {
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(collection)) throw new Error('invalid collection');
+  const pending = new Map<string, { resolve: (v: any) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  const receive = (e: MessageEvent) => {
+    if (e.source !== parent || e.data?.type !== 'homie-app-result') return;
+    const p = pending.get(e.data.id); if (!p) return;
+    pending.delete(e.data.id); clearTimeout(p.timer);
+    if (e.data.result?.ok) p.resolve(e.data.result); else p.reject(new Error(e.data.result?.error ?? 'app request failed'));
+  };
+  addEventListener('message', receive);
+  const ask = (method: string, record?: string, data?: T, version?: number): Promise<any> => new Promise((resolve, reject) => {
+    const id = randomId();
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error('app shell did not answer')); }, 15000);
+    pending.set(id, { resolve, reject, timer });
+    parent.postMessage({ type: 'homie-app', id, collection, method, record, data, version }, '*');
+  });
+  return {
+    async list(): Promise<AppRecord<T>[]> { return (await ask('GET')).records; },
+    async get(id: string): Promise<AppRecord<T> | null> { return (await ask('GET', id)).records[0] ?? null; },
+    create: (data: T, id = randomId()) => ask('POST', id, data),
+    update: (record: AppRecord<T>, data: T) => ask('PUT', record.id, data, record.version),
+    remove: (record: AppRecord<T>) => ask('DELETE', record.id, undefined, record.version),
+    dispose() { removeEventListener('message', receive); for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('disposed')); } pending.clear(); },
+  };
+}

package/bin/homie-studio.mjs

@@ -13,6 +13,8 @@
  *                                         this toolkit as a local MCP server (stdio): the Claude desktop app's Homie
  *                                          extension, Claude Code or any MCP client builds in the same chat that shows
  *                                          the cards (lib/mcp.mjs); --studios: the folder the studios live in
+ *   homie-studio app new <id> [--name "<App Name>"]
+ *   homie-studio app role <id> <role> [--player <account>] [--revoke] [--url <site>]
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio games
  *   homie-studio build [<id>] [--maps] [--types] [--long-check]   (--maps: also keep each bundle's source map and
@@ -28,7 +30,7 @@
  *   homie-studio preview <id> [--port 8788]   (one built game's files at an address on this computer, nothing else: no
  *                                          Wrangler, no rooms, no database; for a capture, a screenshot or a perf script.
  *                                          The game plays offline with its bots. Stop it with Ctrl-C)
- *   homie-studio dev [--port 8787] [--remote-ai] [--no-local-ai] [--timestamps]   (--stop: stop exactly this studio's dev server,
+ *   homie-studio dev [--lan] [--port 8787] [--remote-ai] [--no-local-ai] [--timestamps]   (--stop: stop exactly this studio's dev server,
  *                                         nothing else, and clear a stale record; rooms here are always local: production
  *                                         routes in wrangler.jsonc are left out; a game built while it runs is picked up;
  *                                         --timestamps: a time on every line of Wrangler's, not only the room and error ones;
@@ -336,7 +338,7 @@ import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeO
 import { newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
 import { whatsNewLines } from '../lib/changelog.mjs';
-import { listGames, newGame, readStudio, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
+import { listGames, newGame, newApp, readStudio, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
 import { playersOwner, playersShow } from '../lib/players.mjs';
@@ -371,7 +373,7 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
+const BOOL_FLAGS = ['lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -904,6 +906,13 @@ async function main() {
     if (!url) return { ok: false, command: 'port check', why: 'give --url (the local dev address or the live site)' };
     return tracked(root, 'checks', (report) => portCheck({ url, game, root, only: flags.get('only') ?? null, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log, report }), 'port check');
   }
+  if (cmd === 'app' && sub === 'role') {
+    const { withKey } = await import('../lib/office.mjs');
+    const id = positional[2]; const role = positional[3];
+    if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(id ?? '') || !/^[a-z][a-z0-9-]{0,39}$/.test(role ?? '')) throw new Error('app role <id> <role> [--player <account>] [--revoke] [--url <site>]');
+    return withKey(root, flags.get('url'), (call) => call(`/${id}/api/app/roles`, { role, ...(flags.get('player') ? { player: flags.get('player') } : {}), revoke: flags.has('revoke') }));
+  }
+  if (cmd === 'app' && sub === 'new') return newApp(root, positional[2], { name: flags.get('name') });
   if (cmd === 'game' && sub === 'new') return newGame(root, positional[2], { from: flags.get('from') ?? 'gem-rush', name: flags.get('name') });
   // Remix was retired (a game is never handed over whole): the command is refused in a sentence that says where to
   // go, so an old note, an old card or an agent's memory of the toolkit does not end at "unknown command".
@@ -931,7 +940,7 @@ async function main() {
   }
   // lib/dev.mjs: the dev server, its registration file, and what `--stop` will and will not signal.
   if (cmd === 'dev' && flags.has('stop')) return stopDev(root);
-  if (cmd === 'dev') return dev(root, { port: flags.get('port') ?? 8787, remoteAi: flags.has('remote-ai'), localAi: !flags.has('no-local-ai'), timestamps: flags.has('timestamps'), log });
+  if (cmd === 'dev') return dev(root, { lan: flags.has('lan'), port: flags.get('port') ?? 8787, remoteAi: flags.has('remote-ai'), localAi: !flags.has('no-local-ai'), timestamps: flags.has('timestamps'), log });
   if (cmd === 'check') {
     const game = positional[1] ?? listGames(root)[0]?.id;
     const url = flags.get('url') ?? siteUrl(root);

package/lib/art-cli.mjs

@@ -49,14 +49,14 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { USAGES, licenceProblems, readManifest, removeAsset, rightsMarkdown, setUsage, syncCredits, usageOf, writeRights } from './asset-manifest.mjs';
 import { CATALOGUE_IDS, PHASES, blastRadius, decisionRows, derivedPrompt, initDecisions, lockDecision, oneLine, phaseProgress, pickDirection, readDecisions, setDecision, staleAssets, steerDecision, unlockDecision } from './decisions.mjs';
-import { listGames } from './studio.mjs';
+import { experienceDir, experienceFile, listExperiences as listGames } from './studio.mjs';
 import { checkLines } from './asset-check.mjs';
 import { animPlan as animPlanOf } from './characters.mjs';
 
 /** The game a command means: the one named, else the only one. */
 function gameOf(root, id, command) {
   const games = listGames(root);
-  const planned = id && existsSync(join(root, 'games', id, 'CODEX.md'));
+  const planned = id && existsSync(join(experienceDir(root, id), 'CODEX.md'));
   if (id && (games.some((g) => g.id === id) || planned)) return id;
   if (!id && games.length === 1) return games[0].id;
   throw new Error(`name the game: homie-studio ${command} <id>${games.length ? ` (${games.map((g) => g.id).join(', ')})` : ''}`);

package/lib/art-tools.mjs

@@ -36,7 +36,7 @@ import { animPlan } from './characters.mjs';
 import { CATALOGUE_IDS, decisionRows, lockDecision, oneLine, phaseProgress, pickDirection, readDecisions, setDecision, staleAssets, steerDecision, unlockDecision } from './decisions.mjs';
 import { libraryBase, loadIndex, searchLibrary, itemThumb } from './library.mjs';
 import { boardView } from './style-board.mjs';
-import { listGames } from './studio.mjs';
+import { experienceDir, experienceFile, listExperiences as listGames } from './studio.mjs';
 
 export const ART_UI = Object.freeze({
   style: 'ui://homie-studio/style',
@@ -55,7 +55,7 @@ function picture(h, file, max = 160 * 1024) {
 
 function gameOf(root, id) {
   const games = listGames(root);
-  if (id && (games.some((g) => g.id === id) || existsSync(join(root, 'games', String(id), 'CODEX.md')))) return String(id);
+  if (id && (games.some((g) => g.id === id) || existsSync(join(experienceDir(root, String(id)), 'CODEX.md')))) return String(id);
   if (!id && games.length === 1) return games[0].id;
   throw new Error(`which game? ${games.map((g) => g.id).join(', ') || 'there is none yet (game_plan or game_make first)'}`);
 }
@@ -64,11 +64,11 @@ function gameOf(root, id) {
 function styleData(h, root, game, extra = {}) {
   const doc = readDecisions(root, game);
   let title = null;
-  try { title = JSON.parse(readFileSync(join(root, 'games', game, 'game.json'), 'utf8')).name ?? null; } catch { /* planned: its codex names it */ }
-  if (!title) { try { title = /^#\s+(.+)$/m.exec(readFileSync(join(root, 'games', game, 'CODEX.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''))?.[1]?.trim() ?? null; } catch { title = null; } }
+  try { title = JSON.parse(readFileSync(experienceFile(root, game), 'utf8')).name ?? null; } catch { /* planned: its codex names it */ }
+  if (!title) { try { title = /^#\s+(.+)$/m.exec(readFileSync(join(experienceDir(root, game), 'CODEX.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''))?.[1]?.trim() ?? null; } catch { title = null; } }
   title = title ?? game;
   const manifest = readManifest(root, game);
-  const dirs = doc ? boardView(root, game, doc).map((d) => ({ ...d, swatch: picture(h, d.swatch ? join(root, 'games', game, d.swatch) : null), mood: d.mood?.path ? { image: picture(h, join(root, 'games', game, d.mood.path)), usd: d.mood.usd ?? null, label: 'a painted target, not what the game draws' } : null })) : [];
+  const dirs = doc ? boardView(root, game, doc).map((d) => ({ ...d, swatch: picture(h, d.swatch ? join(experienceDir(root, game), d.swatch) : null), mood: d.mood?.path ? { image: picture(h, join(experienceDir(root, game), d.mood.path)), usd: d.mood.usd ?? null, label: 'a painted target, not what the game draws' } : null })) : [];
   const rows = doc ? decisionRows(doc) : [];
   return {
     kind: 'style', game, title, path: doc?.path ?? null, line: doc ? oneLine(doc) : null, budget: doc?.budget?.usd ?? null, chosen: doc?.board?.chosen ?? null,
@@ -98,7 +98,7 @@ async function characterThumb(h, root, game, row) {
     try { const lib = await loadIndex({ lib: libraryBase() }); const it = lib.index.items.find((x) => x.id === m.from.item); const t = it ? await itemThumb(lib.lib, it) : null; if (t) return `data:image/webp;base64,${Buffer.from(t).toString('base64')}`; } catch { /* no library here */ }
   }
   const concept = (m?.files ?? []).find((f) => f.role === 'concept');
-  return concept ? picture(h, join(root, 'games', game, concept.path), 60 * 1024) : null;
+  return concept ? picture(h, join(experienceDir(root, game), concept.path), 60 * 1024) : null;
 }
 
 /** Which Game Lab take tunes a verb (lab.json): one named for it or whose note says it, else the default. */

package/lib/asset-check.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * `homie-studio assets check <id>`: static, free, on every asset and on the whole game. What it adds up is an
  * INVENTORY ESTIMATE: the recorded files' own triangles, draw calls and pictures times their declared placements. It
@@ -74,7 +75,7 @@ const tierOf = (a) => (a.kind === 'clip' ? 'clip' : BUDGETS[a.tier] ? a.tier : a
 
 /** A game's game.json, or {} (a planned game has none yet). */
 export function gameJson(root, id) {
-  try { return JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')) ?? {}; } catch { return {}; }
+  try { return JSON.parse(readFileSync(experienceFile(root, id), 'utf8')) ?? {}; } catch { return {}; }
 }
 
 /*
@@ -238,7 +239,7 @@ export async function assetsCheck(root, id, { validate = true, write = true } =
   const doc = readDecisions(root, id);
   const game = gameJson(root, id);
   const budgets = budgetsFor(doc, game);
-  const gdir = join(root, 'games', id);
+  const gdir = experienceDir(root, id);
   let tools = null;
   try { tools = await import('./optimise.mjs'); } catch { tools = null; }
   const rows = [];

package/lib/asset-import.mjs

@@ -1,3 +1,4 @@
+import { experienceDir, experienceFile } from './studio.mjs';
 /**
  * A MODEL FILE INTO A GAME: the person's own (imported), or one a provider generated on their account (the models
  * skill's image-to-3D). `homie-studio assets add <id> --file <model> --license <kind>`.
@@ -54,7 +55,7 @@ export function screenImport(path) {
  * the concept and mesh calls with their receipts and prices), slug (the art job's folder).
  */
 export async function importModel(root, id, file, opts = {}) {
-  const gdir = join(root, 'games', id);
+  const gdir = experienceDir(root, id);
   if (!existsSync(join(gdir, 'game.json')) && !existsSync(join(gdir, 'CODEX.md'))) throw new Error(`no game "${id}"`);
   const path = resolve(root, file);
   const route = opts.route === 'generated' ? 'generated' : 'imported';
@@ -117,7 +118,7 @@ export async function importModel(root, id, file, opts = {}) {
  * mesh fix it); one stale only on its budgets is not.
  */
 export async function redoModel(root, id, assetId) {
-  const gdir = join(root, 'games', id);
+  const gdir = experienceDir(root, id);
   const e = readManifest(root, id).assets.find((a) => a.id === assetId);
   if (!e) throw new Error(`no asset "${assetId}" in games/${id}/assets/manifest.json`);
   const raw = (e.files ?? []).find((f) => f.role === 'raw');

package/lib/asset-manifest.mjs

@@ -22,7 +22,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { pinByUse, readDecisions, revisionsFor } from './decisions.mjs';
-import { GAME_ID } from './studio.mjs';
+import { experienceDir, experienceFile, GAME_ID } from './studio.mjs';
 
 export const MANIFEST_FILE = join('assets', 'manifest.json');
 export const RIGHTS_FILE = join('assets', 'RIGHTS.md');
@@ -81,7 +81,7 @@ export function underFor(kind, route) {
   return [...(UNDER[kind] ?? UNDER.prop), ...(route === 'library' ? ['cast.family'] : []), ...(route === 'generated' ? ['derived.prompt'] : [])];
 }
 
-const fileOf = (root, id) => join(root, 'games', id, MANIFEST_FILE);
+const fileOf = (root, id) => join(experienceDir(root, id), MANIFEST_FILE);
 const now = () => new Date().toISOString();
 const clean = (s, n = 300) => (typeof s === 'string' ? s.replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, n) : null);
 
@@ -167,7 +167,7 @@ export function removeAsset(root, id, assetId) {
   writeManifest(root, id, manifest);
   writeRights(root, id, manifest);
   syncCredits(root, id, manifest);
-  const gdir = join(root, 'games', id);
+  const gdir = join(experienceDir(root, id));
   const named = new Set(manifest.assets.flatMap((a) => (a.files ?? []).map((f) => f.path)));
   const deleted = []; const kept = [];
   for (const f of gone.files ?? []) {
@@ -216,7 +216,7 @@ export function licenceProblems(root, id, manifest = readManifest(root, id)) {
 
 /** Model files a game ships (.glb, .gltf, .fbx, .obj, .vrm under games/<id>/) that no manifest entry names. */
 export function unrecordedModels(root, id, manifest = readManifest(root, id)) {
-  const dir = join(root, 'games', id);
+  const dir = join(experienceDir(root, id));
   const named = new Set(manifest.assets.flatMap((a) => (a.files ?? []).map((f) => f.path)));
   const out = [];
   const walk = (rel, depth) => {
@@ -245,7 +245,7 @@ const PICTURE = /\.(png|jpe?g|webp|avif|gif|hdr|exr|ktx2)$/i;
  * The codex (private, the style board's own swatches) is not walked at all.
  */
 export function unrecordedPictures(root, id, manifest = readManifest(root, id), { cover = null } = {}) {
-  const dir = join(root, 'games', id);
+  const dir = join(experienceDir(root, id));
   const named = new Set(manifest.assets.flatMap((a) => (a.files ?? []).map((f) => f.path)));
   const coverPaths = new Set(cover ? [String(cover).replace(/^\.\//, ''), `public/${String(cover).replace(/^\.\//, '')}`] : []);
   const shipped = []; const notShipped = [];
@@ -296,7 +296,7 @@ function routeWords(a) {
 /** RIGHTS.md for one game, in plain words. */
 export function rightsMarkdown(root, id, manifest = readManifest(root, id)) {
   let game = {};
-  try { game = JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')); } catch { game = {}; }
+  try { game = JSON.parse(readFileSync(experienceFile(root, id), 'utf8')); } catch { game = {}; }
   const lines = [
     `# Rights: ${game.name ?? id}`,
     '',
@@ -333,7 +333,7 @@ function termsApply(t, a) {
 }
 
 export function writeRights(root, id, manifest = readManifest(root, id)) {
-  const file = join(root, 'games', id, RIGHTS_FILE);
+  const file = join(experienceDir(root, id), RIGHTS_FILE);
   mkdirSync(dirname(file), { recursive: true });
   const text = rightsMarkdown(root, id, manifest);
   if (!existsSync(file) || readFileSync(file, 'utf8') !== text) writeFileSync(file, text);
@@ -347,7 +347,7 @@ export function writeRights(root, id, manifest = readManifest(root, id)) {
  * and one per attribution-required file. Lines this function wrote carry `"asset": true`; every other part stays.
  */
 export function syncCredits(root, id, manifest = readManifest(root, id)) {
-  const file = join(root, 'games', id, 'credits.json');
+  const file = join(experienceDir(root, id), 'credits.json');
   let credits = {};
   try { credits = JSON.parse(readFileSync(file, 'utf8')); } catch { credits = {}; }
   const before = Array.isArray(credits.parts) ? credits.parts : [];