@homie-rocks/studio 0.36.0 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -75,7 +75,15 @@
       "default": "./rules/host.ts"
     },
     "./worker": "./worker/index.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./links": {
+      "types": "./links/links.d.ts",
+      "default": "./links/links.mjs"
+    },
+    "./apps": {
+      "types": "./apps/apps.ts",
+      "default": "./apps/apps.ts"
+    }
   },
   "files": [
     "bin/",
@@ -99,7 +107,10 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "links/",
+    "apps/",
+    "app-starters/"
   ],
   "engines": {
     "node": ">=22"

package/parts/PARTS.md

@@ -1,6 +1,6 @@
-# Game parts
+# Studio parts
 
-Games build on each other by sharing **parts**: a piece of a game that its studio chooses to share, so somebody
+Studios build on each other by sharing **parts**: a reusable piece of a game, app, music or video that its studio chooses to share, so somebody
 making another game can use it. A creature from one game, a level from another, a bot brain from a third. That is
 the whole idea. Without parts, a creator's AI has to come up with everything on its own.
 
@@ -8,7 +8,7 @@ Mashing up is not a command: it is making a game with parts from several games.
 
 ## The rules
 
-1. **A part is a piece of a game, never the whole game.** Remix, which handed over an entire game, is retired;
+1. **A part is a reusable piece, never a whole game or app.** Remix, which handed over an entire game, is retired;
    parts are what replaces it.
 2. **A part can take any form** that suits the piece: code, assets, data, a JSON description, a tuned config, or a
    mix. Form is not restricted.
@@ -89,10 +89,11 @@ named after it):
 | Field | What it is |
 | --- | --- |
 | `id`, `name`, `kind`, `version`, `summary` | `version` is three numbers; a shared version never changes, so a change is a new version. `summary` is one sentence. |
-| `kind` | `character`, `rig`, `clips`, `environment`, `effect`, `sound`, `ui`, `mechanic`, `shader`, `level-generator`, `bot-brain`, `audio-pack`, `set-piece`. There is no kind for a whole game. |
+| `kind` | `character`, `rig`, `clips`, `environment`, `effect`, `sound`, `ui`, `mechanic`, `shader`, `level-generator`, `bot-brain`, `audio-pack`, `set-piece`. `quiz`, `menu-board`, `waitlist`, `live-total`, `loop`, `stem`, `track`, `video-intro`, `video-template` also name parts. There is no kind for a whole game or app. |
 | `license`, `attribution` | Needed to share: an SPDX identifier, and who a game using the part credits. |
 | `share` | **Default `false`.** The part's own switch, and the only thing that decides whether it is shared. |
-| `from` | The game and studio the part came out of. Written when a part is lifted out of a game. |
+| `uses` | Optional intended uses: `game`, `app`, `venue`, `cause`, `music`, `video`. Describe the purpose, independently of licence and any future pricing. |
+| `from` | The source and studio: `game`, `app`, `music` or `video` with its id. Written when a part is lifted out of a game. |
 | `entry` | For a part with code: the module a game imports. A part of assets or data has none. |
 | `files` | Every file with its SHA-256 and size, **written by the tool, never by hand**. A file may carry `"rights"` (below). |
 | `preview` | `page`: a self-contained HTML page shown in a sandboxed frame. `image`: a still. `aspect`: the frame's shape as `"W:H"` (whole numbers 1 to 32, no flatter than 3:1, no taller than 1:2; default `"16:9"`). `phoneAspect`: the shape when the frame is narrower than 600 px. |
@@ -167,3 +168,7 @@ build, whether or not the add named the game.
   A package the studio's own `package.json` already names at a version npm says does not fit is explained and left
   alone.
 - The plumbing behind the tools is `homie-studio parts find | new | add | share | unshare | check`.
+
+App parts use the same lift/import/credit paths as game parts. Music and video parts can start empty with the corresponding kind; add their selected files, licence and provenance before sharing. `uses` describes what they are for, not permission to use them: the licence controls that. No price or checkout behavior is introduced; future commercial metadata can be added separately without changing the meaning of `share`.
+
+For example: `homie-studio parts new welcome-queue --kind waitlist --uses app,venue`, or `parts new gala-loop --kind loop --uses venue,cause`. A source app is selected by the existing `--from <id>` and `--game <id>` options.

package/shop/SHOP.md

@@ -201,3 +201,16 @@ Game and TV checkout use the same tab if a new tab is unavailable, then return t
 During rollback, the released Worker grants only a cart’s first item until the new Worker repairs it; it
 allows whole-cart player refunds even when a tip is included, and counts partially refunded carts at
 the full amount toward a cap. The additive schema preserves its original rows and entitlement keys.
+
+## 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/site/SITE.md

@@ -398,7 +398,7 @@ A studio with a `shop.json` ([../shop/SHOP.md](../shop/SHOP.md)) has `/shop/` (i
 one neutral age question, Buy on Stripe's own page, or a link for a parent), `/shop/thanks`, `/shop/refunds/` (the
 refund policy every seller publishes) and `/shop/parent/<link>` (what a parent opens). The account page lists the
 player's purchases and badges, with the self-serve refund of an unused item. A play page whose game the studio
-sells something for carries the store sheet (the game's `shop.open()`, and Shop in the room sheet); the protective shop policy hides it on kids servers and sends big-screen shoppers to a phone. The studio can edit these policies in shop.json. With a `shop.json`, `/shop/` belongs to the
+sells something for carries the store sheet, and play/open screens show a visible Shop button in a reserved strip above the content. `screen.shop: false` in game.json or app.json hides this button; `createShop().open()` or `.open(item)` opens the same sheet from the experience's own button. Closed shops and experiences without items show no button; the protective shop policy hides it on kids servers and sends big-screen shoppers to a phone. The studio can edit these policies in shop.json. With a `shop.json`, `/shop/` belongs to the
 shop (a `site/pages/shop/` is not served); without one it is the studio's own. The directory manifest says only
 whether the shop is open and its till.
 

package/worker/account-page.mjs

@@ -108,11 +108,12 @@ export function accountPage(cat, { origin = '', next = '/account/', owner = null
   const studio = cat?.studio?.name ?? 'Studio';
   const boot = { next, owner, link, mode, features, studio };
   const games = (cat?.games ?? []).filter((g) => g.saves).map((g) => g.name);
-  const back = next !== '/account/' ? `<p class="back"><a class="ghost" href="${esc(next)}" data-back>Back to the game</a></p>` : '';
+  const app = (cat.games ?? []).some((g) => g.kind === 'app' && next.startsWith(`/${g.id}/`));
+  const back = next !== '/account/' ? `<p class="back"><a class="ghost" href="${esc(next)}" data-back>Back to the ${app ? 'app' : 'game'}</a></p>` : '';
   const main = `<section class="acct" data-account>
 <p class="kicker">${esc(studio)}</p>
-<h1>Your player account</h1>
-<p class="lead">Keep your characters and progress on every device you play on. It is an account on ${esc(studio)} only, made with a passkey: Face ID, a fingerprint or your device's PIN. No password, and no email needed.</p>
+<h1>${app ? 'Your account' : 'Your player account'}</h1>
+<p class="lead">${app ? 'Sign in for your role in this app.' : 'Keep your characters and progress on every device you play on.'} It is an account on ${esc(studio)} only, made with a passkey: Face ID, a fingerprint or your device's PIN. No password, and no email needed.</p>
 <noscript><p class="lead">This page needs JavaScript for passkeys.</p></noscript>
 <div class="card" data-view="loading"><p>Looking for your account…</p></div>
 

package/worker/app-format.mjs

@@ -0,0 +1,42 @@
+/** App metadata shared by the build and the Worker. No browser role grants authority. */
+export const APP_SURFACES = ['phone', 'wall', 'kiosk', 'tablet'];
+export const APP_WORDS = Object.freeze({ open: 'Open', join: 'Scan to join', one: 'person', many: 'people' });
+const key = /^[a-z][a-z0-9-]{0,39}$/;
+const object = (x) => x && typeof x === 'object' && !Array.isArray(x);
+export function appProblems(meta) {
+  const bad = [];
+  if (!object(meta)) return ['app.json must be an object'];
+  const roles = object(meta.roles) ? meta.roles : {};
+  const collections = object(meta.records?.collections) ? meta.records.collections : {};
+  if (!object(meta.roles) || !Object.keys(meta.roles).length) bad.push('roles must declare at least one role');
+  for (const [id, role] of Object.entries(roles)) {
+    if (!key.test(id) || !object(role) || typeof role.signIn !== 'boolean' || !Array.isArray(role.can) || role.can.some((s) => !/^(read|create|update|delete):[a-z][a-z0-9-]{0,39}$/.test(s))) bad.push(`role ${id}: declare signIn and can (read/create/update/delete:collection)`);
+  }
+  if (!Object.values(roles).some((r) => r?.signIn === false)) bad.push('declare a public role');
+  if (!object(meta.surfaces) || !Object.keys(meta.surfaces).length) bad.push('declare surfaces');
+  for (const [surface, role] of Object.entries(meta.surfaces ?? {})) if (!APP_SURFACES.includes(surface) || !Object.hasOwn(meta.roles ?? {}, role)) bad.push(`surface ${surface}: name a declared role`);
+  if (!object(meta.records) || typeof meta.records.persist !== 'boolean' || !object(meta.records.collections)) bad.push('records declares persist and collections');
+  for (const [id, c] of Object.entries(collections)) {
+    if (!key.test(id) || !object(c) || !object(c.fields)) { bad.push(`collection ${id}: declare fields`); continue; }
+    for (const [field, spec] of Object.entries(c.fields)) if (!key.test(field) || !object(spec) || !['string', 'number', 'boolean'].includes(spec.type) || (spec.enum && (!Array.isArray(spec.enum) || !spec.enum.length))) bad.push(`collection ${id}.${field}: invalid field`);
+  }
+  for (const r of Object.values(roles)) for (const cap of Array.isArray(r?.can) ? r.can : []) if (!Object.hasOwn(meta.records?.collections ?? {}, String(cap).split(':')[1])) bad.push(`unknown collection in ${cap}`);
+  for (const [k, v] of Object.entries(meta.words ?? {})) if (!Object.hasOwn(APP_WORDS, k) || typeof v !== 'string' || !v.trim() || v.length > 60) bad.push(`words.${k}: use a short label`);
+  return bad;
+}
+export const appWords = (g) => g?.kind === 'app' ? { ...APP_WORDS, ...g.words } : { open: 'Play', join: 'Scan to play', one: 'player', many: 'players' };
+export const openPath = (g) => `/${g.id}/${g.kind === 'app' ? 'open' : 'play'}`;
+export function appRole(meta, url) {
+  const surface = url.searchParams.get('surface') ?? ((url.pathname.endsWith('/tv') || url.pathname.endsWith('/watch')) || url.searchParams.get('want') === 'screen' ? 'wall' : 'phone');
+  return url.searchParams.get('role') ?? meta.surfaces?.[surface] ?? Object.keys(meta.roles ?? {}).find((r) => !meta.roles[r].signIn);
+}
+export function recordProblem(collection, data, { create = false } = {}) {
+  if (!object(data) || JSON.stringify(data).length > 8192) return 'record must be an object below 8 KB';
+  for (const k of Object.keys(data)) if (!Object.hasOwn(collection.fields, k)) return `unknown field ${k}`;
+  for (const [k, s] of Object.entries(collection.fields)) {
+    const v = data[k];
+    if (v === undefined) { if (s.required) return `missing ${k}`; continue; }
+    if (typeof v !== s.type || (s.type === 'number' && !Number.isFinite(v)) || (typeof v === 'string' && v.length > (s.maxLength ?? 256)) || (s.enum && !s.enum.includes(v)) || (create && s.initial !== undefined && v !== s.initial)) return `invalid ${k}`;
+  }
+  return null;
+}

package/worker/app-records.mjs

@@ -0,0 +1,100 @@
+/** Lasting app records in the studio's own D1. Room hosts never authorize writes. */
+import { appRole, recordProblem } from './app-format.mjs';
+import { isOwner, sameOrigin } from './office.mjs';
+import { players } from './players.mjs';
+import { ownerAllowed } from './stats.mjs';
+import { appOriginOf } from './standalone.mjs';
+export const APPS_MIGRATION_FILE = '0014_studio_apps.sql';
+export const APPS_MIGRATION = `CREATE TABLE IF NOT EXISTS app_records (
+  app TEXT NOT NULL, collection TEXT NOT NULL, id TEXT NOT NULL, value TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 1, updated_at INTEGER NOT NULL,
+  PRIMARY KEY (app, collection, id)
+);
+CREATE TABLE IF NOT EXISTS app_roles (
+  app TEXT NOT NULL, role TEXT NOT NULL, player TEXT NOT NULL,
+  PRIMARY KEY (app, role, player)
+);
+CREATE TABLE IF NOT EXISTS app_role_links (
+  app TEXT NOT NULL, role TEXT NOT NULL, token TEXT NOT NULL,
+  PRIMARY KEY (app, role)
+);
+`;
+const json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+const fail = (status, error) => json({ ok: false, error }, status);
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+async function bodyOf(request) {
+  const reader = request.body?.getReader();
+  if (!reader) return {};
+  let size = 0; const chunks = [];
+  for (;;) { const { done, value } = await reader.read(); if (done) break; size += value.length; if (size > 12_288) { await reader.cancel(); throw new Error('body too large'); } chunks.push(value); }
+  const bytes = new Uint8Array(size); let at = 0;
+  for (const chunk of chunks) { bytes.set(chunk, at); at += chunk.length; }
+  return JSON.parse(new TextDecoder().decode(bytes) || '{}');
+}
+/** Private links conceal staff addresses; a signed-in grant is still required on every request. */
+export async function appAccess(request, env, meta, url) {
+  const role = appRole(meta, url);
+  const declared = Object.hasOwn(meta.roles ?? {}, role) ? meta.roles[role] : null;
+  if (!declared) return { ok: false, status: 404, error: 'unknown role' };
+  if (!declared.signIn) return { ok: true, role, can: declared.can };
+  if (!env.DB) return { ok: false, status: 503, error: 'app roles need the studio database' };
+  const link = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, role).first();
+  if (!link || link.token !== url.searchParams.get('access')) return { ok: false, status: 404, error: 'private role link required' };
+  if (await isOwner(request, env)) return { ok: true, role, can: declared.can };
+  const person = await players.of(request, env);
+  if (!person || person.guest) return { ok: false, status: 401, error: 'sign in to this studio' };
+  const grant = await env.DB.prepare('SELECT player FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3').bind(meta.id, role, person.id).first();
+  return grant ? { ok: true, role, can: declared.can } : { ok: false, status: 403, error: 'this account has no role grant' };
+}
+export async function appRecordsRoute(request, env, meta, url, sub) {
+  if (!sub.startsWith('api/app/')) return null;
+  if (!env.DB) return fail(503, 'app records need the studio database');
+  try {
+    if (sub === 'api/app/roles') {
+      const key = await ownerAllowed(request, env, { kinds: ['office'] });
+      if (!key && !(await isOwner(request, env))) return fail(403, 'owner only');
+      if (request.method !== 'POST') return fail(405, 'POST required');
+      if (!key && !sameOrigin(request, url)) return fail(403, 'same origin required');
+      const b = await bodyOf(request);
+      if (!Object.hasOwn(meta.roles, b.role) || !meta.roles[b.role].signIn) return fail(400, 'name a sign-in role');
+      if (b.player !== undefined) {
+        if (!ID.test(b.player)) return fail(400, 'invalid account');
+        const p = await players.get(b.player, env);
+        if (!p || p.guest) return fail(400, 'role grants require an existing signed-in account');
+        await env.DB.prepare(b.revoke === true ? 'DELETE FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3' : 'INSERT OR IGNORE INTO app_roles (app, role, player) VALUES (?1, ?2, ?3)').bind(meta.id, b.role, b.player).run();
+      }
+      const token = crypto.randomUUID().replaceAll('-', '');
+      if (b.rotate === true) await env.DB.prepare('DELETE FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).run();
+      await env.DB.prepare('INSERT OR IGNORE INTO app_role_links (app, role, token) VALUES (?1, ?2, ?3)').bind(meta.id, b.role, token).run();
+      const row = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).first();
+      return json({ ok: true, link: `${url.origin}/${meta.id}/open?role=${b.role}&access=${row.token}`, role: b.role });
+    }
+    const match = /^api\/app\/records\/([a-z][a-z0-9-]{0,39})(?:\/([A-Za-z0-9_-]{1,64}))?$/.exec(sub);
+    if (!match || !Object.hasOwn(meta.records?.collections ?? {}, match[1])) return fail(404, 'unknown collection');
+    if (meta.records.persist !== true) return fail(409, 'use netplay state for transient records, or enable records.persist');
+    const access = await appAccess(request, env, meta, url);
+    if (!access.ok) return fail(access.status, access.error);
+    const [, collection, id] = match;
+    const op = ({ GET: 'read', POST: 'create', PUT: 'update', DELETE: 'delete' })[request.method];
+    if (!op || !access.can.includes(`${op}:${collection}`)) return fail(403, 'role cannot perform this operation');
+    if (op !== 'read' && !sameOrigin(request, url) && !(appOriginOf(request) && !meta.roles[access.role].signIn)) return fail(403, 'same origin required');
+    if (op === 'read') {
+      const rows = id ? [await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3').bind(meta.id, collection, id).first()].filter(Boolean)
+        : (await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 ORDER BY updated_at, id LIMIT 1000').bind(meta.id, collection).all()).results;
+      return json({ ok: true, records: rows.map((r) => ({ id: r.id, data: JSON.parse(r.value), version: r.version, updatedAt: r.updated_at })) });
+    }
+    if (!id) return fail(400, 'record id required');
+    const body = await bodyOf(request);
+    if (op !== 'delete') { const bad = recordProblem(meta.records.collections[collection], body.data, { create: op === 'create' }); if (bad) return fail(400, bad); }
+    if (op !== 'create' && (!Number.isSafeInteger(body.version) || body.version < 1)) return fail(400, 'record version required');
+    const stmt = op === 'create'
+      ? env.DB.prepare('INSERT OR IGNORE INTO app_records (app, collection, id, value, version, updated_at) SELECT ?1, ?2, ?3, ?4, 1, ?5 WHERE (SELECT COUNT(*) FROM app_records WHERE app = ?1 AND collection = ?2) < 1000').bind(meta.id, collection, id, JSON.stringify(body.data), Date.now())
+      : op === 'update' ? env.DB.prepare('UPDATE app_records SET value = ?4, version = version + 1, updated_at = ?5 WHERE app = ?1 AND collection = ?2 AND id = ?3 AND version = ?6').bind(meta.id, collection, id, JSON.stringify(body.data), Date.now(), body.version)
+      : env.DB.prepare('DELETE FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3 AND version = ?4').bind(meta.id, collection, id, body.version);
+    const result = await stmt.run();
+    return result.meta.changes ? json({ ok: true, id, version: op === 'create' ? 1 : body.version + 1 }) : fail(409, 'record changed, already exists, or collection full; reload');
+  } catch (error) {
+    if (error instanceof SyntaxError || error.message === 'body too large') return fail(400, error.message);
+    return fail(503, 'app database unavailable; apply studio migrations');
+  }
+}

package/worker/app-shell.mjs

@@ -0,0 +1,29 @@
+/** Only the shell's own frame can ask; role and access come from the shell, never the message. */
+export const APP_SHELL_JS = String.raw`(function () {
+  var boot = window.__HOMIE_PLAY || window.__HOMIE_APP || window.__HOMIE_WATCH;
+  if (!boot || boot.kind !== 'app') return;
+  var frame = document.querySelector('iframe.game') || document.querySelector('iframe');
+  var params = new URLSearchParams(location.search);
+  var inflight = 0;
+  addEventListener('message', async function (e) {
+    var m = e.data;
+    if (frame && e.source === frame.contentWindow && m?.type === 'homie-app-ticket' && /^[a-f0-9]{32}$/.test(m.ticket)) { params.set('ticket', m.ticket); history.replaceState(null, '', location.pathname + '?' + params); return; }
+    if (!frame || e.source !== frame.contentWindow || !m || m.type !== 'homie-app' || !/^[a-f0-9]{32}$/.test(m.id || '')) return;
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(m.collection || '') || !['GET','POST','PUT','DELETE'].includes(m.method) || (m.record !== undefined && !/^[A-Za-z0-9_-]{1,64}$/.test(m.record))) return;
+    var result;
+    if (inflight >= 8) result = { ok: false, error: 'too many requests' };
+    else {
+      inflight++;
+      try {
+        var q = new URLSearchParams();
+        ['role','surface','access'].forEach(function (k) { var v = params.get(k); if (v) q.set(k, v); });
+        if (boot.screen && !q.has('role')) q.set('surface', 'wall');
+        var path = (boot.site || '') + '/' + boot.game + '/api/app/records/' + m.collection + (m.record ? '/' + m.record : '') + '?' + q;
+        var res = await fetch(path, { method: m.method, headers: { 'content-type': 'application/json' }, body: m.method === 'GET' ? undefined : JSON.stringify({ data: m.data, version: m.version }) });
+        result = await res.json();
+      } catch (err) { result = { ok: false, error: 'records unavailable; reconnect and retry' }; }
+      finally { inflight--; }
+    }
+    e.source.postMessage({ type: 'homie-app-result', id: m.id, result: result }, '*');
+  });
+})();`;

package/worker/embed.mjs

@@ -1,3 +1,4 @@
+import { appWords, openPath } from './app-format.mjs';
 /**
  * Player cards. X's reference: developer.x.com, "Cards: player card" (archived)
  * (redirects to docs.x.com/overview as checked 2026-10-08). Surviving official sample:
@@ -71,7 +72,8 @@ export function httpsAddress(value, origin) {
   try { const u = new URL(value, origin); return u.protocol === 'https:' && !u.username && !u.password ? u.href : null; } catch { return null; }
 }
 export function playerProperties(cat, game, { origin = '', title = game?.name, description = game?.blurb } = {}) {
-  const player = httpsAddress(`/${game?.id}/play/embed`, origin);
+  if (!game) return {};
+  const player = httpsAddress(`${openPath(game)}/embed`, origin);
   const measured = game?.playerImage;
   const picture = measured && httpsAddress(measured.src, origin);
   // twitter:site goes out when the studio has set its handle; a card is never withheld for the lack of one
@@ -80,7 +82,7 @@ export function playerProperties(cat, game, { origin = '', title = game?.name, d
   if (!playerEnabled(cat, game) || !player || !picture || playerImageRule(measured)) return {};
   return { ...(handle ? { 'twitter:site': handle } : {}), 'twitter:card': 'player', 'twitter:player': player, 'twitter:player:width': PLAYER_SIZE.width,
     'twitter:player:height': PLAYER_SIZE.height, 'twitter:image': picture, 'twitter:title': title,
-    'twitter:description': String(description || `Play ${game.name} in your browser.`).slice(0, 200) };
+    'twitter:description': String(description || `${appWords(game).open} ${game.name} in your browser.`).slice(0, 200) };
 }
 
 /** Browser restrictions belong to the outer host; failures must not kill a game's input loop.

package/worker/index.mjs

@@ -1,3 +1,5 @@
+import { appAccess, appRecordsRoute } from './app-records.mjs';
+import { appRole, openPath } from './app-format.mjs';
 /**
  * @homie-rocks/studio/worker — a studio's own site, on the studio's own Cloudflare.
  *
@@ -173,6 +175,10 @@ async function sellingShop(env, cat) {
   try { return (await readiness(env, shop)).ready ? shop : null; } catch { return null; }
 }
 
+async function availableShellShop(env, cat, game, options) {
+  return await sellingShop(env, cat) ? shellShop(cat, game, options) : null;
+}
+
 async function postsOf(env, origin) {
   try {
     const res = await env.ASSETS.fetch(new Request(`${origin}/_site/posts.json`));
@@ -485,6 +491,7 @@ async function gameDocument(request, env, url, game, meta, cat, { agent = null }
   const ver = versionOf(meta?.netplay?.version);
   // The play page's switches for the game (section 24): the allowed names only, checked again here.
   const params = paramsFrom(url.searchParams, meta);
+  if (meta.kind === 'app' && !params.role) params.role = appRole(meta, url);
   const cfg = {
     v: 1,
     url: `${wsBase}/${game}/__net?room=${encodeURIComponent(room)}${b ? `&b=${b}` : ''}${t ? `&t=${encodeURIComponent(t)}` : ''}${watching ? '&w=1' : ''}${ver ? `&gv=${encodeURIComponent(ver)}` : ''}`,
@@ -511,7 +518,7 @@ async function gameDocument(request, env, url, game, meta, cat, { agent = null }
     ...(meta?.saves && want === 'play' ? { saves: true } : {}),
     // The studio sells something in this game (shop/SHOP.md): the play shell answers @homie-rocks/studio/shop. A
     // watcher has no shop; the shell follows the studio shop policy for kids servers and television checkout.
-    ...(!agent && !watching && shellShop(cat, game) ? { shop: true } : {}),
+    ...(!agent && !watching && await availableShellShop(env, cat, game) ? { shop: true } : {}),
   };
   let html = await res.text();
   const head = `${embedded ? `<script>${EMBED_GAME_JS}</script>` : ''}<script>window.HOMIE_NET=${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script>`;
@@ -601,6 +608,8 @@ export default {
     const url = new URL(request.url);
     // A standalone copy's Lobby call (worker/standalone.mjs): every answer to it can be read by the app's page, an
     // unknown game's 404 and a failure included, so the app can say why it plays offline. No other address is opened.
+    const appRecords = isAppOrigin(request) && /^\/[^/]+\/api\/app\/records\//.test(url.pathname);
+    if (appRecords && request.method === 'OPTIONS') return appCors(request, new Response(null, { status: 204, headers: { 'access-control-allow-methods': 'GET, POST, PUT, DELETE', 'access-control-allow-headers': 'content-type' } }));
     const appLobby = isAppOrigin(request) && /^\/[^/]+\/api\/lobby\/?$/.test(url.pathname);
     let res;
     try { res = finish(await route(request, env, ctx), url.pathname); } catch (error) {
@@ -608,7 +617,7 @@ export default {
       try { console.error(JSON.stringify({ at: new Date().toISOString(), ev: 'lobby-route-failed', path: url.pathname, error: errorLine(error) })); } catch { /* no console */ }
       res = json({ ok: false, error: 'failed' }, 500);
     }
-    if (appLobby) return appCors(request, res);
+    if (appLobby || appRecords) return appCors(request, res);
     // A referral's arrival (worker/referrals.mjs): only a person's page load with ?via= of another site, on a studio
     // that pays referrals. The page is answered first; a cookie is added to it only then.
     if (url.searchParams.has('via') && res && res.status === 200 && /text\/html/i.test(res.headers.get('content-type') ?? '')) {
@@ -691,7 +700,7 @@ async function route(request, env, ctx) {
       // its mark is here). A Preview says it is one.
       ...(cat.studio?.build ? { build: { commit: cat.studio.build.commit ?? null, branch: cat.studio.build.branch ?? null, at: cat.studio.build.at ?? null, changes: (cat.studio.build.changes ?? []).slice(0, 50), ...(env.HOMIE_PREVIEW === '1' ? { preview: true } : {}) } } : {}),
       // Only the public games (a private or invite-only game leaves the directory the next time it reads this).
-      games: await Promise.all((cat.games ?? []).map(async (g) => {
+      games: await Promise.all((cat.games ?? []).filter((g) => g.kind !== 'app').map(async (g) => {
         // The card picture is the landing's hero still (what the landing leads with), else the game's cover.
         const cover = gameCover(g);
         // The licence the game names for itself (an SPDX id), when it names one (worker/license.mjs). Nothing here
@@ -709,6 +718,7 @@ async function route(request, env, ctx) {
           ...(byGame ? { played: byGame[g.id] ?? { days: 7, plays: 0, rounds: 0 } } : {}),
         };
       })),
+      ...((cat.games ?? []).some((g) => g.kind === 'app') ? { apps: cat.games.filter((g) => g.kind === 'app').map((g) => ({ id: g.id, kind: 'app', name: g.name, blurb: g.blurb, page: `${url.origin}/${g.id}/`, open: `${url.origin}/${g.id}/open`, wall: `${url.origin}/${g.id}/tv`, surfaces: Object.keys(g.surfaces ?? {}), ...(g.built ? { build: g.built } : {}) })) } : {}),
       songs: (cat.songs ?? []).map((e) => mediaRow(e, url.origin, 'music', cat)),
       videos: (cat.videos ?? []).map((e) => mediaRow(e, url.origin, 'videos', cat)),
       // The studio's posts, for the hub (the full text is in /posts/feed.json).
@@ -829,7 +839,7 @@ async function route(request, env, ctx) {
     const { rooms, live } = await roomsOf(env, cat.games ?? []);
     return homePage(cat, { origin: url.origin, rooms, live });
   }
-  if (['games', 'rooms', 'posts'].includes(parts[0]) && parts.length === 1) {
+  if (['games', 'apps', 'rooms', 'posts'].includes(parts[0]) && parts.length === 1) {
     const cat = await getCat();
     const has = sectionsOf(cat).some((s) => s.key === parts[0]);
     if (!has) return notFoundPage(parts[0] === 'posts' ? 'This studio has no posts yet.' : 'This studio has no games yet.', cat);
@@ -837,7 +847,7 @@ async function route(request, env, ctx) {
     await countVisit(request, env, ctx, parts[0]);
     if (parts[0] === 'posts') return postsPage(cat, { origin: url.origin });
     const { rooms, live } = await roomsOf(env, cat.games ?? []);
-    return parts[0] === 'games' ? gamesPage(cat, { origin: url.origin, live }) : roomsPage(cat, { origin: url.origin, rooms });
+    return ['games', 'apps'].includes(parts[0]) ? gamesPage(cat, { origin: url.origin, live, kind: parts[0] === 'apps' ? 'app' : 'game' }) : roomsPage(cat, { origin: url.origin, rooms });
   }
   if (parts[0] === 'posts' && parts.length === 2 && POST_SLUG.test(parts[1])) {
     const cat = await getCat();
@@ -857,6 +867,7 @@ async function route(request, env, ctx) {
     if (parts.length === 1 && !path.endsWith('/')) return Response.redirect(`${url.origin}/${game}/`, 301);
     const cat = await getCat();
     let sub = parts.slice(1).join('/');
+    if (meta.kind === 'app' && /^open(?:\/(embed|preview))?$/.test(sub)) sub = sub.replace(/^open/, 'play');
     if (sub === '__restart') {
       if (env.HOMIE_PREVIEW !== '1' || request.method !== 'POST' || !hostedGame(game)) return new Response('not found', { status: 404 });
       const room = url.searchParams.get('room') ?? '';
@@ -869,6 +880,19 @@ async function route(request, env, ctx) {
     // with access, and the owner may have made its rooms smaller than the game's own seats.
     const launch = launchOf(meta, settings, env);
     const max = seatsFor(meta, settings);
+    if (meta.kind === 'app') {
+      if (launch !== 'public' && !(await accessOf(request, env, game, launch)).ok) return json({ ok: false, error: 'not-found' }, 404);
+      const api = await appRecordsRoute(request, env, meta, url, sub);
+      if (api) return api;
+      if (['play', 'tv', 'watch'].includes(sub)) {
+        let a;
+        try { a = await appAccess(request, env, meta, url); } catch { return json({ ok: false, error: 'app roles unavailable; apply studio migrations' }, 503); }
+        if (!a.ok) {
+          if (a.status === 401) return Response.redirect(`${url.origin}/account/?next=${encodeURIComponent(url.pathname + url.search)}`, 302);
+          return json({ ok: false, error: a.error }, a.status);
+        }
+      }
+    }
     const lobby = () => env.LOBBY.get(env.LOBBY.idFromName(game));
     if (sub === 'invite') return redeemInvite(request, env, url, cat, meta, settings);
 
@@ -963,7 +987,7 @@ async function route(request, env, ctx) {
     if (sub === 'play/preview' && env.HOMIE_EMBED_PREVIEW === '1' && isLocalOrigin(url.origin)) return embedPreview(cat, meta, url.origin);
     if (sub === 'tv' || sub === 'play' || sub === 'play/embed') {
       const embed = sub === 'play/embed';
-      if (embed && (!playerEnabled(cat, meta) || launch !== 'public')) return notFoundPage('This game does not play inside a post. Open its studio page to play.', cat);
+      if (embed && (!playerEnabled(cat, meta) || launch !== 'public')) return notFoundPage(meta.kind === 'app' ? 'This app does not open inside a post. Open its studio page.' : 'This game does not play inside a post. Open its studio page to play.', cat);
       const screen = !embed && (sub === 'tv' || url.searchParams.get('screen') === '1');
       const asked = embed ? null : askedRoom;
       if (asked !== null && !ROOM_ID.test(asked)) return badRoomPage(cat, meta, asked, { screen });
@@ -996,20 +1020,20 @@ async function route(request, env, ctx) {
         if (!room) {
           try { room = (await (await lobby().fetch(`https://lobby/join?max=${humanSeats(pol)}&server=${srv.id}&rooms=${srv.roomsMax}${versionOf(meta?.netplay?.version) ? `&ver=${encodeURIComponent(versionOf(meta.netplay.version))}` : ''}`, { method: 'POST' })).json()).room ?? null; } catch { room = null; }
         }
-        const joinUrl = `${url.origin}/${game}/play${room ? `?room=${encodeURIComponent(room)}` : ''}`;
+        const joinUrl = `${url.origin}${openPath(meta)}${room ? `?room=${encodeURIComponent(room)}` : ''}`;
         // Local development: no phone can open this computer's own address, so no code for it; the card says to deploy.
         const local = isLocalOrigin(url.origin);
         let qr = null;
         if (!local) try { qr = qrSvg(joinUrl, { title: `Join ${meta.name ?? game}` }); } catch { /* too long for a QR: the address shows as text */ }
         // Television checkout and kids-server visibility follow the studio shop policy.
-        const sh = shellShop(cat, game, { kids: pol.kids });
+        const sh = await availableShellShop(env, cat, game, { kids: pol.kids });
         let shopQr = null;
         if (sh && !local) try { shopQr = qrSvg(`${url.origin}/shop/?game=${encodeURIComponent(game)}`, { title: `Shop: ${meta.name ?? game}` }); } catch { shopQr = null; }
         return playPage(cat, meta, { origin: url.origin, screen: true, joinUrl, qr, local, room, ticket, owner: d.owner, launch, server, shop: sh ? { ...sh, qr: shopQr, url: `${url.origin}/shop/?game=${game}` } : null });
       }
       await countVisit(request, env, ctx, game, 'play');
       shareDaily(cat, url, ctx);
-      return playPage(cat, meta, { origin: url.origin, embed, preview: env.HOMIE_EMBED_PREVIEW === '1', ticket: embed ? null : ticket, owner: !embed && d.owner, launch, server, ...(embed ? {} : await chatWho(env, game, srv, d.acct)), shop: shellShop(cat, game, { kids: pol.kids }) });
+      return playPage(cat, meta, { origin: url.origin, embed, preview: env.HOMIE_EMBED_PREVIEW === '1', ticket: embed ? null : ticket, owner: !embed && d.owner, launch, server, ...(embed ? {} : await chatWho(env, game, srv, d.acct)), shop: await availableShellShop(env, cat, game, { kids: pol.kids }) });
     }
     if (sub === 'watch') {
       // The same door as Play: a game that is private or an invite-only beta is watched only by whoever may play it.