@homie-rocks/studio 0.35.1 → 0.37.0

package/CHANGELOG.md

@@ -17,6 +17,46 @@ 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)
+
+The build plays your rules game and names problems before you publish it.
+
+### Added
+
+- **The build plays your rules game before it is written.** After checking the types in rules, movement and view against the game's own declarations, it seats generated players in a room on the real server runtime. They steer, hold every control, send every command the game declares, and sometimes send nothing at all; they leave, come back and give up their seats; the room is restarted as a deploy restarts it. A game with AI companions is played with them too.
+- **A build is refused only for what that play proved.** A handler that threw, a tick that used its whole budget, a character the server had to hold back because its movement outran its declared top speed, a room that did not come back the same from its own save, or a value the room had to change and lose: `NaN`, an infinite number in a fraction or a vector, more entries than a list or a map declares, a text longer than declared. The message names the file, the line of the write and the handler, says what a live room does with the value, and how to repair it. Everything else is an `info:` line that never fails a build: how much was played, which handlers never ran, and how often a whole number was held to its range.
+- **The same game gets the same answer on every computer.** The play is counted in ticks and in the rules' own budget units, never in seconds, so a slow or busy computer builds what a fast one builds and prints the same lines. A small game is played for fifteen minutes of the room's clock, which takes about a second; a heavy game is played until its units are used, a few seconds, and the line says how far that was. `homie-studio build --long-check` plays eight times as much, for a release or a CI run.
+- **A live room never stops for a value that does not fit its field.** It stores the nearest thing the type holds, as before: `NaN` becomes `0`, a list is cut to its size, a whole number is held to its range (`Infinity` is the top of it, so it can stand for "never"). The build is where such a write is caught. `-0` is now stored as `0`, so a room divides the same way before and after a restart, and a map keeps its keys in the order they were added. The `game` skill's `RULES.md` has the table. Saved matches are written in a new form: a match saved by a build made before this change starts afresh once.
+
+- **Let a player host a friends game.** Studios can choose `room.host: "browser"` to run the same rules in an elected player's browser. When that player leaves, another takes over with the saved seats, scores, round clock and AI companions. Server hosting remains the default.
+- **Play offline from the same rules.** Browsers and packaged apps can play with local bots without a connection, unless the studio turns offline play off. Offline progress stays local. The Game Lab uses the same rules with its stages and sliders; online rooms can also use AI guides and decisions.
+- **Browser hosting has different limits.** It depends on a player's device and connection and offers no protection against a modified host: that player can change scores or the match. It has no server recovery guarantee. When a host hides or closes the tab, another player takes over from the current tick; a crash can lose up to a second. Updates are paced to fit the connection, and a room whose state grows beyond the browser limits stops with a clear message. Choose server hosting for stronger authority or larger rooms.
+- **The netplay contract is revision 11** (`netplay/NETPLAY.md`, section 29): the server as a host, input as steps stamped with the room's tick, explicit browser runtime output, and checkpoint handover. Nothing a game written before sends or receives has changed.
+
+### Fixed
+
+- Local development publishes one complete rules build per restart, avoiding the two reloads caused by separate code and asset watchers.
+- Browser rooms recover after a hidden tab, sleep or a dropped connection. Returning players regain a playable body, unavailable offline files keep reconnecting, and failed rules explain why the room stopped.
+- Builds check the relay's browser state limits. A room that grows beyond them stops with a clear message instead of repeatedly changing hosts. Saved inputs and answers are checked before rules use them.
+
 ## [0.35.1] - 2026-10-08
 
 **Plugin 0.36.0** · [#71](https://github.com/homie-rocks/homie/pull/71)

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/agents/agents.ts

@@ -59,6 +59,8 @@ export interface AgentsOptions {
   /** Runtime integration: a room clock and an explicit beat replace the browser timer. */
   now?: () => number;
   manual?: boolean;
+  /** A rules view is always a client; the separate runtime owns guides. */
+  viewOnly?: boolean;
   /** Keep an asked-for goal through scripted floor decisions until completion or sixty seconds. */
   carryFloor?: boolean;
   restore?: AgentsSaved;
@@ -283,7 +285,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
   function onAsk(slot: number, k: string, args: Record<string, unknown>, from: number): void {
     const def = own(vocab.asks, k);
     const s = slotOf(slot);
-    if (!def || !s || argsWhy(def.args, args, lastView.get(slot) ?? viewOf(slot), null)) { st.drops += 1; return; }
+    if (!def || !s || argsWhy(def.args, args, viewOf(slot), people())) { st.drops += 1; return; }
     const now = wall();
     if (def.leave) { const m = avoid.get(slot) ?? new Map<number, number>(); m.set(from, now + AGENT_RULES.leaveMs); avoid.set(slot, m); }
     asks.set(slot, [...(asks.get(slot) ?? []), { k, args, from, at: now }].slice(-4));
@@ -298,7 +300,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
   const offEvent = net.on('event', (e: NetEvent) => {
     const k = e.k;
     const d = (e.d && typeof e.d === 'object' ? e.d : {}) as Record<string, unknown>;
-    if (net.isHost) {
+    if (net.isHost && !opts.viewOnly) {
       const s = slotOfSeat(e.from);
       if (k === 'agent:do' && s) {
         st.dos += 1;
@@ -311,11 +313,11 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
       if (ask && e.from !== null && !net.isAgent(e.from) && Number.isInteger(d['slot'])) { onAsk(d['slot'] as number, ask, (d['args'] ?? {}) as Record<string, unknown>, e.from); return; }
       return;
     }
-    if (k === 'agent:offer' && e.from === net.host?.seat && Number.isInteger(d['slot']) && d['view'] && typeof d['view'] === 'object') { lastView.set(d['slot'] as number, d['view'] as Record<string, unknown>); return; }
+    if (k === 'agent:offer' && e.from === (opts.viewOnly ? null : net.host?.seat) && Number.isInteger(d['slot']) && d['view'] && typeof d['view'] === 'object') { lastView.set(d['slot'] as number, d['view'] as Record<string, unknown>); return; }
     // Every other browser: a guide's line the host relayed (Quiet AI already dropped it in the helper). Its words are
     // this browser's own copy of the vocabulary; an argument is a seat, a value of the line's list, or an id.
     const line = /^say:([a-z][a-z0-9_]{0,31})$/.exec(k)?.[1];
-    if (e.from === net.host?.seat && line && d['ai'] === true && Number.isInteger(d['slot'])) {
+    if (e.from === (opts.viewOnly ? null : net.host?.seat) && line && d['ai'] === true && Number.isInteger(d['slot'])) {
       const args = (d['args'] ?? {}) as Record<string, unknown>;
       const def = own(vocab.lines, line);
       const ids = Object.fromEntries(Object.entries(def?.args ?? {}).map(([n, t]) => [n, t]).filter(([, t]) => typeof t === 'string' && VIEW_ARG.test(t)).map(([n, t]) => [VIEW_ARG.exec(t as string)![1], /^[a-z0-9][a-z0-9_-]{0,39}$/.test(String(args[n as string] ?? '')) ? [args[n as string]] : []]));
@@ -327,7 +329,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
 
   // The host's beat: views to the guides an AI holds (at most one every 2 s each), the floor for the rest.
   const beat = (): void => {
-    if (!net.isHost || net.offline) return;
+    if (opts.viewOnly || !net.isHost || net.offline) return;
     const now = wall();
     for (const s of guides()) {
       const seat = s.agent?.seat ?? null;
@@ -372,7 +374,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
       const s = slotOf(slot);
       if (!def || !s) return false;
       const seat = s.agent?.seat ?? null;
-      if (net.isHost) {
+      if (net.isHost && !opts.viewOnly) {
         const me = net.offline ? 0 : net.seat;
         if (me === null) return false;
         onAsk(slot, k, args, me);

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,19 +13,24 @@
  *                                         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]   (--maps: also keep each bundle's source map and module sizes in
- *                                          .studio/maps/<id>/, never in site/dist: what `perf` reads a CPU profile through;
- *                                          --types: check the games' TypeScript first, with the studio's own
- *                                          `typescript`; a type error stops the build. The site is built in a folder of
+ *   homie-studio build [<id>] [--maps] [--types] [--long-check]   (--maps: also keep each bundle's source map and
+ *                                          module sizes in .studio/maps/<id>/, never in site/dist: what `perf` reads a
+ *                                          CPU profile through; --types: check the games' TypeScript first, with the
+ *                                          studio's own `typescript`; a type error stops the build; --long-check: play
+ *                                          each rules game eight times as long before it is written (a rules game is
+ *                                          always type-checked and played; this is more of the same play, for a
+ *                                          release or a CI run). The site is built in a folder of
  *                                          its own and put in place only when all of it is there: a game that does not
  *                                          build fails the command and leaves site/dist as it was. Each game's line says
  *                                          changed or unchanged, its build hash, and whether its source is shared)
  *   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;
@@ -333,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';
@@ -368,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];
@@ -414,7 +419,7 @@ function print(result) {
       lines.push(`Built ${result.games.map((g) => `${g.id} (${Math.round(g.bytes / 1024)} KB)`).join(', ') || 'no games'} into ${relative(process.cwd(), result.dist) || result.dist}`);
       // Per game: did it change since the build before, which build it is (the hash the live site's manifest says once
       // deployed), and what loads later.
-      for (const g of result.games) lines.push(`  ${g.id}: ${g.changed ?? 'new'}, build ${g.hash ?? '?'}${g.bundle ? ` (${g.bundle}${g.chunks ? ` + ${g.chunks} ${g.chunks === 1 ? 'chunk' : 'chunks'} loaded later` : ''})` : ''}`);
+      for (const g of result.games) lines.push(`  ${g.id}: ${g.changed ?? 'new'}, build ${g.hash ?? '?'}${g.bundle ? ` (${g.bundle}${g.chunks ? ` + ${g.chunks} additional ${g.chunks === 1 ? 'chunk' : 'chunks'}` : ''})` : ''}`);
       if (result.retired) lines.push(`Note: ${result.retired}`);
       if (result.types) lines.push(`Types: ${result.types.games.filter((g) => g.checked).map((g) => g.id).join(', ') || 'no game has TypeScript to check'}${result.types.games.some((g) => g.checked) ? ` checked with TypeScript ${result.types.typescript ?? '?'}, no errors` : ''}`);
       if (result.songs?.length || result.videos?.length) lines.push(`Media pages: ${[...result.songs.map((x) => `/music/${x}/`), ...result.videos.map((x) => `/videos/${x}/`)].join(', ')}`);
@@ -901,12 +906,19 @@ 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".
   if (cmd === 'game' && sub === 'remix') return { ok: false, command: 'game remix', why: 'remix was retired: a game is no longer handed over whole, and no studio serves one. Games build on each other through parts, the pieces of a game its studio chose to share: find one with `homie-studio parts find <words>` and bring it in with `homie-studio parts add` (in chat: parts_find, part_add; parts/PARTS.md)' };
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
-  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps'), types: flags.has('types') }), 'build');
+  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps'), types: flags.has('types'), longCheck: flags.has('long-check') }), 'build');
   if (cmd === 'preview') return preview(root, positional[1] ?? (listGames(root).length === 1 ? listGames(root)[0].id : null));
   if (cmd === 'perf' && sub === 'sizes') return perfSizes(root, positional[2] ?? listGames(root)[0]?.id);
   if (cmd === 'lab') return labCommand(root, sub);
@@ -928,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/lab/lab.ts

@@ -166,6 +166,21 @@ export const lab = {
     return out as Tuned<S>;
   },
 
+  /** Rules use the same slider file as the view. Public values keep their public. prefix in the Lab's UI. */
+  rulesTune(raw: Record<string, unknown>): Record<string, unknown> {
+    if (!ON) return raw;
+    const pub = raw.public && typeof raw.public === 'object' ? raw.public as Record<string, unknown> : {};
+    const spec: TunableFile = {};
+    for (const [k, v] of Object.entries(raw)) if (k !== 'public' && (typeof v === 'number' || typeof (v as TunableSpec)?.value === 'number')) spec[k] = v as TunableSpec | number;
+    for (const [k, v] of Object.entries(pub)) if (typeof v === 'number' || typeof (v as TunableSpec)?.value === 'number') spec[`public.${k}`] = v as TunableSpec | number;
+    const values = host!.tunables(spec);
+    const out: Record<string, unknown> & { public: Record<string, unknown> } = { ...raw, public: { ...pub } };
+    for (const k of Object.keys(spec)) if (Number.isFinite(values[k])) {
+      if (k.startsWith('public.')) out.public[k.slice(7)] = values[k]; else out[k] = values[k];
+    }
+    return out;
+  },
+
   /**
    * Dice for juice (particles, shake, sparks): its own stream in the lab, so a build that adds a particle never moves
    * a gem or a bot in the other build (Math.random() is the world's dice, the same in both). Math.random() outside.

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(', ')})` : ''}`);