@homie-rocks/studio 0.32.0 → 0.33.0

package/lib/scaffold.mjs

@@ -29,9 +29,10 @@ import { PLAYERS_MIGRATION, PLAYERS_MIGRATION_FILE } from '../worker/players.mjs
 import { OFFICE_MIGRATION, OFFICE_MIGRATION_FILE } from '../worker/office-schema.mjs';
 import { SERVERS_MIGRATION, SERVERS_MIGRATION_FILE } from '../worker/servers.mjs';
 import { CHAT_MIGRATION, CHAT_MIGRATION_FILE } from '../worker/chat-store.mjs';
-import { SHOP_MIGRATION, SHOP_MIGRATION_FILE } from '../worker/shop-store.mjs';
+import { SHOP_MIGRATION, SHOP_MIGRATION_FILE, SHOP_RESERVATIONS, SHOP_RESERVATIONS_FILE, SHOP_STATEMENTS, SHOP_STATEMENTS_FILE } from '../worker/shop-store.mjs';
 import { LOUNGE_MIGRATION, LOUNGE_MIGRATION_FILE } from '../worker/lounge-store.mjs';
 import { themeFile } from './site.mjs';
+import { rulesIndex } from './studio.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
 /** 4.135.0 or later: Worker Previews (`wrangler preview`, a Durable Object namespace per Preview). */
@@ -75,7 +76,9 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     // The site's own fetches (its directory claim, "played this week") go out as any browser's would, so a studio
     // whose directory is on the same zone (a house studio on *.homie.rocks, or two Workers on one workers.dev
     // subdomain) reaches it instead of failing with 1042.
-    compatibility_flags: ['global_fetch_strictly_public'],
+    // `disallow_eval_during_startup`: no code is made from a string while the Worker loads (Cloudflare never allows it
+    // later). A game's rules run in this Worker (NETPLAY.md section 29), and nothing in them is ever made from text.
+    compatibility_flags: ['global_fetch_strictly_public', 'disallow_eval_during_startup'],
     workers_dev: true,
     preview_urls: true,
     // The studio's own custom-domain and exact-host routes, as its owner wrote them: this file is written again by
@@ -210,7 +213,7 @@ studio's pinned copy, never a registry lookup of the bare name.
   one-time link that marks their own player account (a passkey on this site) as the owner's, so their games and
   the studio's back office recognise them.
 - \`npx --no-install homie-studio upgrade\` — after pinning a newer \`@homie-rocks/studio\` (or through
-  \`npx -y --package=<its tarball> homie-studio upgrade\`): what the newer template adds to this studio (AGENTS.md
+  \`npx -y @homie-rocks/studio@<its version> upgrade\`): what the newer template adds to this studio (AGENTS.md
   sections, READMEs, .gitignore lines) and what it keeps. It changes nothing until \`--apply\`, and never
   touches a file or section this studio changed; \`--diff\` shows how those differ from the template's.
 
@@ -433,18 +436,18 @@ studio's pinned copy, never a registry lookup of the bare name.
 - **The studio sells with its OWN Stripe account.** The studio is the seller: its prices, its refunds, its tax, its
   disputes. Money goes from players to the studio's Stripe; homie.rocks never sees it and Homie takes no cut.
   \`SELLING.md\` says what that means for the owner in plain words (not legal advice).
-- **\`shop.json\`** (at the studio's root, reviewed in git): \`till\` (\`stripe\`, the studio is the seller with Stripe
-  Tax on; \`stripe-managed\`, Stripe Managed Payments is the seller of record and files the tax for 3.5% more; or
-  \`off\`), \`currency\`, \`refundDays\` (at least 14), \`capPerPlayerMonth\` (cents, at most 5000) and \`items\`:
-  \`{ "id", "kind": "cosmetic"|"supporter"|"pass"|"unlock"|"tip", "name", "price": <cents>, "gives": ["skin:ember"],
-  "days"?, "game"?, "advantage"? }\`. Real money only: no gems, coins or points. \`npx --no-install homie-studio shop
-  init --supporter\` writes a US$5 Supporter pack; \`shop check\` and every build refuse what the kit refuses.
-- **The kids rules are the kit's, not the studio's to switch off:** nothing random for money (an item that names
-  chance, odds, a crate, a box or a mystery is refused), no countdown offers, no shop on a kids server or in a studio
-  with \`"audience": "kids"\` in studio.json, spending off on every account until a neutral age question says adult,
-  nothing ever for under-13s, 13-17 only through a parent's own checkout (a one-time link), nothing with
-  \`"advantage": true\` on a beginner server, one hosted Stripe checkout per purchase, a monthly cap. The television
-  never sells: its store sheet is a code to buy on a phone.
+- **\`shop.json\`** is the studio's settings file: \`till\` (\`stripe\`, \`stripe-managed\`, or \`off\`), \`currency\`,
+  optional \`refundDays\` and \`capPerPlayerMonth\`, and items with studio-chosen kinds, names, prices and entitlement
+  keys. No Homie ceiling on prices, tips, item count, keys, text, durations or referral terms. Stripe currency
+  units and provider minimums still apply, including zero-decimal currencies. \`shop init --supporter\` writes a
+  supporter item and explicit protective policy, with no spending cap or refund window. Existing values stay.
+- **The studio chooses who may buy:** \`policy.preset\` is \`protective\` (the default), \`adults-only\`, or \`custom\`.
+  Each rule can be read and edited in shop.json; SHOP.md lists them. Protective keeps the account and age
+  question, under-13 refusal, parent checkout for teens, closed kids shops, beginner fairness, refusal of paid
+  randomness and countdowns, and TV code to a phone. Do not silently relax protection for children. The studio
+  is responsible for law and provider terms where it sells; presets are not legal advice.
+- **Flood protection:** \`purchaseAttemptsPerMinute\` (default 6) is per account; \`purchaseAttemptsPerAddressPerMinute\` (default 600) is per address. Both are per Worker instance and configurable.
+  New guest buyers use \`guestBuyersPerAddressPerHour\` (default 600). These protect against floods, not spending.
 - **In a game:** \`import { createShop } from '@homie-rocks/studio/shop'\`; \`shop.has('skin:ember')\`,
   \`shop.entitlements()\`, \`shop.on('change', …)\`, \`shop.open(item)\` from a button the player pressed (never the
   play button, never on a timer), \`shop.used(key)\` when it is equipped. A supporter's badge rides on their seat
@@ -710,8 +713,14 @@ export function studioFiles({ name, slug, homie, template = false }) {
     'site/README.md': SITE_README,
     'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1, and R2 once storage is added.
 // The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
+import { hostRules } from '@homie-rocks/studio/worker';
+// The rules of this studio's games that run on the server (written by homie-studio build; empty until a game has some).
+import rules from './rules/index.mjs';
+
+hostRules(rules);
 export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
+    'site/src/rules/index.mjs': rulesIndex([]),
     'site/migrations/0001_studio.sql': MIGRATION,
     [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
     [`site/migrations/${PLAYERS_MIGRATION_FILE}`]: PLAYERS_MIGRATION,
@@ -719,6 +728,8 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${SERVERS_MIGRATION_FILE}`]: SERVERS_MIGRATION,
     [`site/migrations/${CHAT_MIGRATION_FILE}`]: CHAT_MIGRATION,
     [`site/migrations/${SHOP_MIGRATION_FILE}`]: SHOP_MIGRATION,
+    [`site/migrations/${SHOP_RESERVATIONS_FILE}`]: SHOP_RESERVATIONS,
+    [`site/migrations/${SHOP_STATEMENTS_FILE}`]: SHOP_STATEMENTS,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -825,6 +836,22 @@ export function ensureShopMigration(root) {
   return `site/migrations/${SHOP_MIGRATION_FILE}`;
 }
 
+function ensureShopReservations(root) {
+  const file = join(root, 'site', 'migrations', SHOP_RESERVATIONS_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, SHOP_RESERVATIONS);
+  return `site/migrations/${SHOP_RESERVATIONS_FILE}`;
+}
+
+function ensureShopStatements(root) {
+  const file = join(root, 'site', 'migrations', SHOP_STATEMENTS_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, SHOP_STATEMENTS);
+  return `site/migrations/${SHOP_STATEMENTS_FILE}`;
+}
+
 /** Every migration the template owns that this studio lacks, added: the files written (deploy and dev say so). */
 /** A studio made before 0.23.0 has no room chat tables: the owner's chat rules and players' reports. */
 function ensureChatMigration(root) {
@@ -845,7 +872,7 @@ function ensureLoungeMigration(root) {
 }
 
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */

package/lib/shop-catalog.mjs

@@ -27,16 +27,17 @@ import { productIdOf } from '../worker/stripe.mjs';
 const MARK = 'shop-v1';
 
 /** The Products the catalog should hold, from the checked shop.json. */
-export function wantedProducts(shop, slug) {
-  return (shop?.items ?? []).map((it) => {
-    const id = productIdOf(slug, it.id);
+export async function wantedProducts(shop, slug) {
+  return Promise.all((shop?.items ?? []).map(async (it) => {
+    const id = await productIdOf(slug, it.id);
     return {
       id, item: it.id, name: it.name, description: it.blurb ?? null, tax_code: defaultTaxCode(it),
-      metadata: { homie: MARK, homie_studio: String(slug), homie_item: it.id },
+      // Stripe metadata values: 500 characters. https://docs.stripe.com/metadata (fetched 2026-10-08).
+      metadata: { homie: MARK, homie_studio: String(slug), homie_item: it.id.length <= 500 ? it.id : id },
       price: it.kind === 'tip' ? null : { currency: shop.currency, unit_amount: it.price, tax_behavior: 'exclusive' },
-      shown: it.kind === 'tip' ? `pay what you want, ${money(it.min, shop.currency)} to ${money(it.max, shop.currency)}` : money(it.price, shop.currency),
+      shown: it.kind === 'tip' ? `pay what you want, ${money(it.min, shop.currency)}${it.max === null ? ' or more' : ` to ${money(it.max, shop.currency)}`}` : money(it.price, shop.currency),
     };
-  });
+  }));
 }
 
 /**
@@ -60,14 +61,14 @@ export function productsIn(value, out = [], depth = 0) {
 const taxCodeOf = (p) => (typeof p?.tax_code === 'string' ? p.tax_code : p?.tax_code?.id ?? null);
 
 /** The plan: the read first, then (with what Stripe answered) the writes still needed. */
-export function catalogPlan(root, { have = null, mode = null, record = true } = {}) {
+export async function catalogPlan(root, { have = null, mode = null, record = true } = {}) {
   const r = readShop(root);
   if (r.absent) return { ok: false, command: 'shop catalog', why: 'no shop.json: homie-studio shop init writes one first' };
-  if (!r.ok) return { ok: false, command: 'shop catalog', why: `shop.json breaks the rules (homie-studio shop check): ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
+  if (!r.ok) return { ok: false, command: 'shop catalog', why: `shop.json conflicts with the studio settings or payment requirements (homie-studio shop check): ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
   const studio = readStudio(root);
   const slug = studio.slug;
   if (!slug) return { ok: false, command: 'shop catalog', why: 'studio.json has no slug: the catalog\'s Product ids are made from it' };
-  const wanted = wantedProducts(r.shop, slug);
+  const wanted = await wantedProducts(r.shop, slug);
   const read = {
     tool: 'stripe_api_read', method: 'GET', path: '/v1/products', params: { limit: 100, expand: ['data.default_price'] },
     then: 'Save exactly what it answers (every page, while has_more) to a file in the scratch folder, then run: npx --no-install homie-studio shop catalog --have <that file>',

package/lib/shop.mjs

@@ -5,7 +5,7 @@
  *   homie-studio shop                       is it selling, and if not, what is missing (the live site's office view)
  *   homie-studio shop init [--supporter] [--currency usd] [--price 500] [--managed]
  *                                           writes shop.json (a $5 Supporter pack with --supporter) and SELLING.md
- *   homie-studio shop check                 shop.json against the kit's rules (no randomness, real money, the cap…)
+ *   homie-studio shop check                 shop.json against the studio settings and provider requirements
  *   homie-studio shop connect [--managed] [--live]   a page on THIS computer (127.0.0.1, one use, ten minutes) where the owner
  *                                           pastes the studio's restricted Stripe key (the one thing only they can make);
  *                                           with it this process makes the webhook (0.24.3), and the key and the
@@ -32,7 +32,7 @@ import { fileURLToPath } from 'node:url';
 import { askedFor, withKey } from './office.mjs';
 import { runner } from './cloudflare.mjs';
 import { listGames, readStudio, siteUrl } from './studio.mjs';
-import { SHOP_FILE, audienceOf, checkShop, defaultTaxCode, money } from '../worker/shop-rules.mjs';
+import { POLICY_PRESETS, SHOP_FILE, audienceOf, checkShop, defaultTaxCode, money } from '../worker/shop-rules.mjs';
 import {
   KEY_SHAPE, STRIPE_VERSION, StripeError, WEBHOOK_SECRET_SHAPE, createWebhookEndpoint, expireCheckoutSession, isPermissionError, listWebhookEndpoints, modeOf,
   stripeCall, updateWebhookEndpoint,
@@ -62,14 +62,14 @@ export function readShop(root) {
   try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { return { ok: false, shop: null, errors: [{ at: '', message: `shop.json is not JSON: ${error.message}` }], warnings: [], file }; }
   const games = listGames(root).map((g) => g.id);
   const studio = readStudio(root);
-  return { ...checkShop(raw, { games, audience: audienceOf(studio) }), file };
+  return { ...checkShop(raw, { games, audience: audienceOf(studio), studioName: studio.name }), file };
 }
 
 /** The build's half: the checked shop for games.json, or a thrown error that says what to fix (nothing is published). */
 export function shopForBuild(root, { log = () => {} } = {}) {
   const r = readShop(root);
   if (r.absent) return null;
-  if (!r.ok) throw new Error(`shop.json breaks the shop's rules, so the build stops (nothing is sold that the kit refuses):\n${r.errors.map((e) => `  ${e.at || 'shop.json'}: ${e.message}`).join('\n')}`);
+  if (!r.ok) throw new Error(`shop.json conflicts with the studio settings or payment requirements, so the build stops (check the studio settings and payment requirements):\n${r.errors.map((e) => `  ${e.at || 'shop.json'}: ${e.message}`).join('\n')}`);
   for (const w of r.warnings) log(`shop.json ${w.at}: ${w.message}`);
   return r.shop;
 }
@@ -77,7 +77,7 @@ export function shopForBuild(root, { log = () => {} } = {}) {
 export function shopCheck(root) {
   const r = readShop(root);
   if (r.absent) return { ok: true, command: 'shop check', absent: true, message: 'No shop.json: this studio sells nothing (homie-studio shop init writes one).' };
-  return { ok: r.ok, command: 'shop check', errors: r.errors, warnings: r.warnings, items: r.shop?.items.map((i) => `${i.id} (${i.kind}, ${i.kind === 'tip' ? 'pay what you want' : money(i.price, r.shop.currency)})`) ?? [], till: r.shop?.till ?? null, why: r.ok ? undefined : `shop.json: ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
+  return { ok: r.ok, command: 'shop check', policy: r.shop?.policy, capPerPlayerMonth: r.shop?.capPerPlayerMonth, refundDays: r.shop?.refundDays, errors: r.errors, warnings: r.warnings, items: r.shop?.items.map((i) => `${i.id} (${i.kind}, ${i.kind === 'tip' ? 'pay what you want' : money(i.price, r.shop.currency)})`) ?? [], till: r.shop?.till ?? null, why: r.ok ? undefined : `shop.json: ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
 }
 
 /** The Supporter pack the kit suggests first: deterministic, never pay-to-win, a badge on the profile and in rooms. */
@@ -89,11 +89,10 @@ export function shopInit(root, { supporter = false, currency = 'usd', price = 50
   const file = join(root, SHOP_FILE);
   if (existsSync(file)) return { ok: false, command: 'shop init', why: 'shop.json is here already: change it, then homie-studio shop check' };
   const studio = readStudio(root);
-  if (audienceOf(studio) === 'kids') return { ok: false, command: 'shop init', why: 'studio.json says "audience": "kids": a studio made for children sells nothing in its games' };
   const shop = {
-    till: managed ? 'stripe-managed' : 'stripe', currency: String(currency).toLowerCase(), refundDays: 14, capPerPlayerMonth: 5000,
-    items: supporter ? [supporterItem({ price: Math.floor(Number(price)) || 500 })] : [],
-    referrals: { rate: 0.1, windowDays: 30, capPerPlayer: 1000, holdDays: 30, minimumInvoice: 2500, accept: ['stripe-invoice'] },
+    till: managed ? 'stripe-managed' : 'stripe', currency: String(currency).toLowerCase(),
+    policy: { preset: 'protective', ...POLICY_PRESETS.protective },
+    items: supporter ? [supporterItem({ price: Number(price) })] : [],
   };
   const r = checkShop(shop, { games: listGames(root).map((g) => g.id) });
   if (!r.ok) return { ok: false, command: 'shop init', why: r.errors.map((e) => e.message).join('; ') };
@@ -124,10 +123,26 @@ export async function shopRefund(root, order, { url, reason, note } = {}) {
   return askedFor(root, url, r, 'shop refund');
 }
 
-export async function shopStatements(root, { url, period, send = false } = {}) {
-  const r = await withKey(root, url, (call) => (send ? call('/_studio/api/shop/statements/send', { ...(period ? { period } : {}) }) : call(`/_studio/api/shop/statements${period ? `?period=${encodeURIComponent(period)}` : ''}`)));
-  if (!r.ok) return { ok: false, command: 'shop statements', why: r.message ?? r.why ?? 'the studio did not answer' };
-  return { ok: true, command: 'shop statements', period: r.period, ...(send ? { sent: r.sent } : { statements: r.statements }) };
+export async function shopStatements(root, { url, period, cursor = '', send = false } = {}) {
+  if (!send) {
+    const r = await withKey(root, url, (call) => call(`/_studio/api/shop/statements?cursor=${encodeURIComponent(cursor)}${period ? `&period=${encodeURIComponent(period)}` : ''}`));
+    return r.ok ? { ok: true, command: 'shop statements', period: r.period, nextCursor: r.nextCursor, statements: r.statements } : { ok: false, command: 'shop statements', why: r.message ?? r.why ?? 'the studio did not answer' };
+  }
+  const sent = [];
+  console.error('Sending statements. Keep this command open; run it again after closing to resume safely.');
+  return withKey(root, url, async (call) => {
+    do {
+      const page = await call('/_studio/api/shop/statements/send', { cursor, ...(period ? { period } : {}) });
+      if (!page.ok) return { ok: false, command: 'shop statements', sent, why: page.message ?? page.why ?? 'the studio did not answer' };
+      for (const failure of page.failures ?? []) if (!sent.some((x) => !x.ok && x.via === failure.via)) { sent.push(failure); console.error(`${failure.via}: failed: ${failure.why ?? failure.status}`); }
+      sent.push(...page.sent);
+      for (const result of page.sent) console.error(`${result.via}: ${result.ok ? 'page sent' : 'failed: ' + (result.why ?? result.status)}`);
+      period = page.period;
+      cursor = page.nextCursor;
+      if (page.retryAfter) await new Promise((resolve) => setTimeout(resolve, page.retryAfter * 1000));
+    } while (cursor !== null);
+    return { ok: true, command: 'shop statements', period, nextCursor: null, sent };
+  });
 }
 
 /* ------------------------------------------------------------------ the key, from a page on this computer */
@@ -346,15 +361,17 @@ export function shopLines(r) {
   } else if (r.command === 'shop check') {
     if (r.absent) lines.push(r.message);
     else {
-      lines.push(r.ok ? `shop.json follows the rules: ${r.items.join(', ') || 'no items yet'} (till: ${r.till}).` : 'shop.json breaks the rules:');
+      lines.push(r.ok ? `shop.json matches the studio settings: ${r.items.join(', ') || 'no items yet'} (till: ${r.till}).` : 'shop.json conflicts with the studio settings or payment requirements:');
+      if (r.policy) lines.push(`Studio policy: ${r.policy.preset}; edit policy in shop.json. Monthly cap: ${r.capPerPlayerMonth ?? 'not set'}; refund days: ${r.refundDays ?? 'not set'}.`);
       for (const e of r.errors ?? []) lines.push(`  ${e.at}: ${e.message}`);
       for (const w of r.warnings ?? []) lines.push(`  note ${w.at}: ${w.message}`);
     }
   } else if (r.command === 'shop init') {
     lines.push(`Wrote ${r.wrote.join(', ')} (till: ${r.till}${r.items.length ? `; ${r.items.join(', ')}` : ''}). Next:`, ...r.next.map((n) => `  ${n}`));
   } else if (r.command === 'shop statements') {
+    if (r.nextCursor) lines.push(`More rows: shop statements --period ${r.period} --cursor '${r.nextCursor.replaceAll("'", "'\\''")}'${r.sent ? ' --send' : ''}`);
     if (r.sent) for (const s of r.sent) lines.push(`${s.via}: ${s.ok ? 'sent' : `not sent (${s.why ?? s.status})`}`);
-    else for (const s of r.statements ?? []) lines.push(`${s.statement.referrer}: due ${money(s.statement.totals.due, s.statement.currency)} (${s.statement.lines.length} line(s)), signed`);
+    else for (const s of r.statements ?? []) lines.push(`${s.statement.referrer}: due ${s.statement.totals ? money(s.statement.totals.due, s.statement.currency) : 'see first page'} (${s.statement.lines.length} line(s)), signed`);
     if (!(r.sent ?? r.statements ?? []).length) lines.push(`No referral statements for ${r.period}.`);
   } else lines.push(r.message ?? '');
   return lines;

package/lib/standalone-cli.mjs

@@ -9,6 +9,10 @@
  *   standalone build <game> [--for …] [--release] [--site <address>] [--build <n>]
  *       builds the game for the web, then every target this computer can make; one it cannot is skipped with why.
  *   standalone run <game> [--for ios|android]      the built copy, started here (none: this computer's desktop app)
+ *   standalone run <game> --for ios --device       built for the one iPhone or iPad plugged in, signed for the person's
+ *       Apple team (HOMIE_APPLE_TEAM, else the keychain's only one), installed over the cable, started, and then looked
+ *       for among the phone's running programs. --device is the yes to what it changes: the phone is added to the Apple
+ *       team's list of development devices.
  *   standalone steam <game>                        Steam's build files from game.json's numbers; uploads nothing
  *   standalone ci <game>                           .github/workflows/standalone.yml: every target on GitHub's machines
  *
@@ -35,7 +39,9 @@ export async function standaloneCommand(root, sub, positional, flags, { log = ()
   switch (sub ?? 'plan') {
     case 'plan': return told(await standalonePlan(root, id, opts));
     case 'build': return told(await standaloneBuild(root, id, opts));
-    case 'run': return standaloneRun(root, id, { for: flags.has('for') ? flags.get('for') : null });
+    // --device: onto the one iPhone or iPad that is plugged in. It is the person's yes to what that changes outside
+    // this computer (DEVICE_ADDS), and the result carries its own words like a build's.
+    case 'run': { const r = await standaloneRun(root, id, { for: flags.has('for') ? flags.get('for') : null, device: flags.has('device'), site: str('site'), log, ...on }); return r?.device ? { ...r, say: standaloneLines(r) } : r; }
     case 'steam': return standaloneSteam(root, id);
     case 'ci': return standaloneCi(root, id);
     default: return { ok: false, command: 'standalone', why: `"${sub}" is not a standalone command: ${STANDALONE_VERBS.join(', ')}` };
@@ -52,8 +58,30 @@ export function missingLines(missing) {
   return ['What the standalone game does not have (v1):', ...missing.map((m) => `  - ${m.what}: ${m.why}.`)];
 }
 
+/** A run on a real phone: what happened, in the order a person needs it, with what it changed outside this computer. */
+function deviceLines(r) {
+  const L = [];
+  const on = r.phone?.model ? `the ${r.phone.model}` : 'the phone';
+  if (r.ok) {
+    L.push(`${r.name} is on ${on} and running: it was built, installed over the cable, started, and then found among the phone's running programs.`,
+      `  Signed for ${r.team.from === 'HOMIE_APPLE_TEAM' ? 'the team HOMIE_APPLE_TEAM names' : r.team.from}, as ${r.appId}${r.appIdFrom === 'derived' ? ' (a made-up id for trying a build)' : ''}.`,
+      `  ${r.adds}`, ...r.notes.map((n) => `  ${n}`));
+  } else {
+    L.push(`NOT on ${r.phone?.model ? on : 'a phone'}: ${r.why}.`);
+    if (r.fix) L.push(`  ${r.fix}`);
+    if (r.installed) L.push(`  The game IS installed on ${on}; it was not seen running.`);
+    else if (r.built) L.push('  The app was built and signed; it is not on the phone.');
+    // What it may already have changed outside this computer, said even when the rest did not work.
+    if (r.team && r.built) L.push('  The build was signed: the phone is on your Apple team\'s list of development devices now, if it was not before.');
+    else if (r.team && r.stage === 'build-failed') L.push('  The build stopped before the app was made; it may have added the phone to your Apple team\'s list of development devices on the way.');
+  }
+  for (const w of r.warnings ?? []) L.push(`Warning: ${w}`);
+  return L;
+}
+
 export function standaloneLines(r) {
   const L = [];
+  if (r.command === 'standalone run' && r.device) return deviceLines(r);
   // A refusal with something to do about it (a release with no id yet, Steam with no numbers) still says it all.
   if (r.ok === false && !r.targets && !r.rows) { L.push(r.why ?? 'failed'); if (r.instead) L.push('', r.instead); return L; }
   switch (r.command) {
@@ -89,7 +117,7 @@ export function standaloneLines(r) {
       break;
     }
     case 'standalone run':
-      L.push(`${r.game} (${r.target}) ended.`);
+      if (r.device) L.push(...deviceLines(r)); else L.push(`${r.game} (${r.target}) ended.`);
       break;
     case 'standalone steam':
       L.push(`Steam's build file for app ${r.app}: ${r.dir}/${r.wrote.join(', ')} (each depot is that system's release build, out/<system>/release/).`,

package/lib/standalone-tools.mjs

@@ -11,20 +11,25 @@
  * Nothing is ever uploaded to Steam or a store from here, and no signing key is taken in chat: a release reads the
  * environment only. What the standalone game does not have is said to the person as it is, every time.
  */
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { SAY_MISSING, standaloneLines } from './standalone-cli.mjs';
-import { STANDALONE_SINCE, standalonePlan, toolkitNote } from './standalone.mjs';
+import { compareVersions } from './changelog.mjs';
+import { DEVICE_ADDS, STANDALONE_SINCE, standalonePlan, toolkitNote } from './standalone.mjs';
+import { pinnedVersion } from './upgrade.mjs';
 import { TARGETS } from './standalone-files.mjs';
 import { PACKAGE_ROOT } from './studio.mjs';
 
 export { SAY_MISSING };
+/** The first toolkit with `standalone run --device`. */
+export const DEVICE_SINCE = '0.32.1';
 
 export function standaloneToolDefs(ctx, h) {
   const { ok, fail, cli, stillRunning, whyOf, needsInstall, str, STUDIO_ARG } = h;
   return [
     {
       name: 'game_standalone', title: 'Make a standalone game',
-      description: `Make one of the studio's games into an app of its own: a desktop app for macOS, Windows and Linux (the kind of build Steam accepts for upload) and a phone app for iOS and Android (the files the App Store and Google Play accept for upload; each store's review, fees and rules are its own, and nothing here makes an app pass). It is the same web build of the game in a thin shell (Electron on computers, Capacitor on phones); multiplayer still goes through the studio's own deployed site, and with no connection the game plays offline with its bots. Use it when the person asks for a Steam build, a desktop app, a download, an iPhone or Android app, or "a standalone version". ALWAYS call it with plan: true first and tell the person what it says: which targets this computer can build and what the others need, the address that gets built into every copy, and what a standalone copy does NOT have in this version (no player accounts, no cloud saves: saves stay on the device and are lost when the app is uninstalled, no shop, no chat). Then, when they say go, call it again without plan: it builds as a background job that takes minutes (the first build downloads the wrapper tools into the studio's .studio/ folder): it answers with a job, and studio_job { "job": … } gives the result in words when it is done; read that result to the person, including its list of what the standalone game does not have. A target whose tool is missing on this computer is skipped with its fix and the others still build; only the desktop build for this computer's own system is started once to see that the game loads, and every other build says "built, not started on this computer". It never uploads anything and never signs with a key from the chat: a release (release: true) signs from environment variables the person sets themselves, needs the app's id written in game.json first (the tool gives the exact lines), and says UNSIGNED when it could not sign. The studio must be on @homie-rocks/studio ${STANDALONE_SINCE} or later AND deployed before a copy can find rooms.`,
+      description: `Make one of the studio's games into an app of its own: a desktop app for macOS, Windows and Linux (the kind of build Steam accepts for upload) and a phone app for iOS and Android (the files the App Store and Google Play accept for upload; each store's review, fees and rules are its own, and nothing here makes an app pass). It is the same web build of the game in a thin shell (Electron on computers, Capacitor on phones); multiplayer still goes through the studio's own deployed site, and with no connection the game plays offline with its bots. Use it when the person asks for a Steam build, a desktop app, a download, an iPhone or Android app, or "a standalone version". ALWAYS call it with plan: true first and tell the person what it says: which targets this computer can build and what the others need, the address that gets built into every copy, and what a standalone copy does NOT have in this version (no player accounts, no cloud saves: saves stay on the device and are lost when the app is uninstalled, no shop, no chat). Then, when they say go, call it again without plan: it builds as a background job that takes minutes (the first build downloads the wrapper tools into the studio's .studio/ folder): it answers with a job, and studio_job { "job": … } gives the result in words when it is done; read that result to the person, including its list of what the standalone game does not have. A target whose tool is missing on this computer is skipped with its fix and the others still build; only the desktop build for this computer's own system is started once to see that the game loads, and every other build says "built, not started on this computer". It never uploads anything and never signs with a key from the chat: a release (release: true) signs from environment variables the person sets themselves, needs the app's id written in game.json first (the tool gives the exact lines), and says UNSIGNED when it could not sign. In a copy, Quick play finds a room only when the studio's live site is on @homie-rocks/studio ${STANDALONE_SINCE} or later AND deployed since; a room made or joined by its code works with an older site too (seen against 0.31.0, not promised for every older version). ON THE PERSON'S OWN iPHONE OR iPAD: device: true builds the game for the one phone plugged in to this Mac, signs it for their Apple team, installs it over the cable, starts it, and then looks for it among the phone's running programs (it says "running" only when it is there). ${DEVICE_ADDS} So call it with device: true only after the person said yes to that, in those words; it needs a Mac with Xcode signed in to their Apple account, the phone unlocked and trusting the Mac, and Developer Mode on (Settings, Privacy & Security, Developer Mode; the phone restarts). It is a background job too. There is no such run for an Android phone in this version.`,
       inputSchema: {
         type: 'object',
         properties: {
@@ -32,6 +37,7 @@ export function standaloneToolDefs(ctx, h) {
           for: { type: 'array', items: { type: 'string', enum: [...TARGETS] }, description: 'Which to build (default: every one this computer can make)' },
           plan: { type: 'boolean', description: 'Only say what would be built and what is missing; build nothing, install nothing. Do this first' },
           release: { type: 'boolean', description: 'A build for a store or Steam: needs "standalone.appId" in the game\'s game.json, and signs from the environment. Only when the person asked for a release' },
+          device: { type: 'boolean', description: 'Put the game on the one iPhone or iPad plugged in to this Mac and start it. It adds the phone to the person\'s Apple team\'s list of development devices: only after they said yes to that' },
           ...STUDIO_ARG,
         },
         required: ['game'],
@@ -50,6 +56,18 @@ export function standaloneToolDefs(ctx, h) {
         }
         const need = needsInstall(ctx, root);
         if (need) return need;
+        if (a.device === true) {
+          // The run on a phone arrived in 0.32.1: a studio whose own toolkit is older has no such flag (and would
+          // read the words as a different command), so this toolkit's runs.
+          let pinned = null;
+          try { const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); pinned = pinnedVersion(pkg?.devDependencies?.['@homie-rocks/studio'] ?? pkg?.dependencies?.['@homie-rocks/studio']); } catch { pinned = null; }
+          const ours = pinned && compareVersions(pinned, DEVICE_SINCE) < 0;
+          const r = await cli(ctx, root, `standalone run ${game} on a phone`, ['standalone', 'run', game, '--for', 'ios', '--device'], ours ? { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') } : {});
+          if (!r.ended) return stillRunning(r.job, `Putting ${game} on the phone (it takes minutes the first time; its last lines say where it is)`);
+          if (!r.result?.device) return fail(`Not on the phone: ${whyOf(r.job)}`, r.result ? { kind: 'standalone-device', ...r.result } : undefined);
+          const text = (r.result.say ?? standaloneLines(r.result)).join('\n');
+          return r.result.ok ? ok(text, { kind: 'standalone-device', ...r.result }) : fail(text, { kind: 'standalone-device', ...r.result });
+        }
         const args = ['standalone', 'build', game, ...(only ? ['--for', only] : []), ...(a.release === true ? ['--release'] : [])];
         const r = await cli(ctx, root, `standalone build ${game}`, args, old ? { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') } : {});
         // The words are in the result itself (`say`), so studio_job says them too when the build outlasts this call.