@homie-rocks/studio 0.32.1 → 0.33.1

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/studio.mjs

@@ -94,11 +94,32 @@ export function listGames(root) {
     .sort((a, b) => a.id.localeCompare(b.id));
 }
 
+/**
+ * RULES ON THE SERVER (NETPLAY.md section 29). A game written as rules plus view says so in game.json with a `"room"`
+ * object (where its rules run, its tick rate…; rules/rules.ts `roomSettings` checks them at build) and has a
+ * src/rules.ts. Any other game is hosted by a player's browser, as before. The file alone decides nothing: games made
+ * before this had their own src/rules.ts, with whatever they liked in it, and they build exactly as they did.
+ */
+export const isRulesGame = (g) => g?.room != null && typeof g.room === 'object' && existsSync(join(g.dir, 'src', 'rules.ts'));
+
+const RULES_HEADER = '// Written by `homie-studio build` from this studio\'s games. Do not edit: the next build writes it again.\n';
+/**
+ * site/src/rules/index.mjs: the table of this studio's server-hosted games as site/src/worker.mjs imports it (an
+ * empty one for a studio with none, which is what a new studio starts with). lib/rules-build.mjs writes the rest.
+ */
+export function rulesIndex(ids = []) {
+  const lines = [`${RULES_HEADER}// The rules of this studio's server-hosted games, for the Worker (site/src/worker.mjs hands them to hostRules).`];
+  ids.forEach((id, i) => lines.push(`import rules${i} from './${id}.mjs';`, `import data${i} from './${id}.data.mjs';`));
+  lines.push(`export default {${ids.map((id, i) => `\n  ${JSON.stringify(id)}: { rules: rules${i}, ...data${i} },`).join('')}${ids.length ? '\n' : ''}};`);
+  return `${lines.join('\n')}\n`;
+}
+
 export function starters() {
   const dir = join(PACKAGE_ROOT, 'starters');
   return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => {
     const meta = JSON.parse(readFileSync(join(dir, d.name, 'game.json'), 'utf8'));
-    return { id: d.name, name: meta.name, blurb: meta.blurb, players: meta.players, roundSeconds: meta.roundSeconds };
+    // `example`: a starter that shows how something is written (coin-dash: rules on the server) and is not yet offered as the start of a new game.
+    return { id: d.name, name: meta.name, blurb: meta.blurb, players: meta.players, roundSeconds: meta.roundSeconds, ...(meta.example === true ? { example: true } : {}) };
   });
 }
 

package/lib/template-history.json

@@ -1732,6 +1732,96 @@
      }
     }
    }
+  },
+  "0.33.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": [
+      "29a04ed3d956610a",
+      "a7f290579585368c"
+     ],
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": [
+      "3173053462311959",
+      "56225d9c6292d975",
+      "b04b0a2b25f524f2"
+     ],
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": [
+        "5d1c068adda1116b",
+        "7cad8fd10f62fef1"
+       ]
+      }
+     }
+    }
+   }
+  },
+  "0.33.1": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "56225d9c6292d975",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/upgrade.mjs

@@ -15,8 +15,9 @@
  *              `--diff` prints the difference, so the person can take the template's words by hand.
  *
  * Plus the pin: when this CLI is newer than the version package.json pins (run through
- * `npx -y --package=<the new tarball> homie-studio upgrade`), --apply pins this version (then `npm install`), and
- * studio.json's `homie.studio` says the version the studio is on.
+ * `npx -y @homie-rocks/studio@<the new version> upgrade`), --apply pins this version (then `npm install`), and
+ * studio.json's `homie.studio` says the version the studio is on. The pin it writes is always the npm registry's:
+ * a studio made before 0.10.0 pinned an address on homie.rocks, and its first upgrade moves it to the registry.
  *
  * Without --apply it changes nothing and says what --apply would do: the person agrees first. It never touches
  * studio.json beyond `homie.studio`, the studio's look (site/theme.json), its Worker config (deploy's), its games,
@@ -43,7 +44,7 @@ import { STUDIO_VERSION, packageSpec } from './version.mjs';
 /** Whole files the template writes and a studio may keep as they are: updated only while the studio never changed them. */
 export const TEMPLATE_FILES = ['AGENTS.md', 'CLAUDE.md', 'README.md', 'HANDOFF.md', 'games/README.md', 'music/README.md', 'videos/README.md', 'posts/README.md', 'site/README.md', 'site/src/worker.mjs'];
 /** Files the template adds when missing and never changes once they exist (a migration is applied; a manifest is the studio's). */
-export const ADD_ONLY = ['music/manifest.json', 'videos/manifest.json', '.claude/skills/.gitkeep'];
+export const ADD_ONLY = ['music/manifest.json', 'videos/manifest.json', '.claude/skills/.gitkeep', 'site/src/rules/index.mjs'];
 const MIGRATIONS = /^site\/migrations\/[^/]+\.sql$/;
 /** The name and slug stand-ins the history is fingerprinted with. */
 export const STAND_IN = { name: '{{studio.name}}', slug: '{{studio.slug}}' };
@@ -124,19 +125,21 @@ function known(history, who = {}) {
 const semver = (v) => (/^(\d+)\.(\d+)\.(\d+)$/.exec(String(v ?? '')) ?? []).slice(1).map(Number);
 const newer = (a, b) => { const x = semver(a); const y = semver(b); for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0); return false; };
 
-/** The @homie-rocks/studio version a package.json spec pins: a homie.rocks tarball, an exact version, or npm:… of one. */
+/**
+ * The version in the address a studio made before 0.10.0 pinned (https://<directory>/npm/homie-studio-<version>.tgz),
+ * or null. Read for one thing only: so that studio's upgrade knows which version it is leaving. Nothing writes
+ * such an address; its upgrade writes the npm registry's exact version.
+ */
+const addressPin = (spec) => /^https?:\/\/.+\/homie-studio-(\d+\.\d+\.\d+)\.tgz(?:[?#].*)?$/.exec(String(spec ?? ''))?.[1] ?? null;
+
+/** The @homie-rocks/studio version a package.json spec pins: an exact version, npm:… of one, or an older studio's address. */
 export function pinnedVersion(spec) {
   const s = String(spec ?? '');
-  return /homie-studio-(\d+\.\d+\.\d+)\.tgz(?:[?#].*)?$/.exec(s)?.[1] ?? /^(?:npm:@homie-rocks\/studio@)?=?(\d+\.\d+\.\d+)$/.exec(s)?.[1] ?? null;
+  return /^(?:npm:@homie-rocks\/studio@)?=?(\d+\.\d+\.\d+)$/.exec(s)?.[1] ?? addressPin(s);
 }
-/** The same kind of spec, for this version. */
-function specFor(spec, directory) {
-  const s = String(spec ?? '');
-  const tar = /^(https?:\/\/.+\/)homie-studio-\d+\.\d+\.\d+\.tgz$/.exec(s);
-  if (tar) return `${tar[1]}homie-studio-${STUDIO_VERSION}.tgz`;
-  if (/^npm:@homie-rocks\/studio@/.test(s)) return `npm:@homie-rocks/studio@${STUDIO_VERSION}`;
-  if (/^=?\d+\.\d+\.\d+$/.test(s)) return STUDIO_VERSION;
-  return packageSpec(directory);
+/** The pin for this version: the npm registry's exact version (an npm: alias stays an alias). */
+function specFor(spec) {
+  return /^npm:@homie-rocks\/studio@/.test(String(spec ?? '')) ? `npm:@homie-rocks/studio@${STUDIO_VERSION}` : packageSpec();
 }
 
 /** A line diff (the longest common run kept), for the plan: `  ` same, `- ` the studio's, `+ ` the template's. */
@@ -183,8 +186,9 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
   if (pinned && newer(pinned, STUDIO_VERSION)) {
     return { ok: false, command: 'upgrade', from: pinned, to: STUDIO_VERSION, why: `this studio pins @homie-rocks/studio ${pinned}, newer than this ${STUDIO_VERSION}: run its own copy (npx --no-install homie-studio upgrade)` };
   }
-  if (pkg && where && pinned && newer(STUDIO_VERSION, pinned)) {
-    changes.push({ file: 'package.json', kind: 'pin', what: `pin @homie-rocks/studio ${STUDIO_VERSION} (was ${pinned}); then npm install`, from: spec, to: specFor(spec, studio.homie?.directory) });
+  // An older studio's address is moved to the registry even when it names this very version: it is no longer served.
+  if (pkg && where && pinned && (newer(STUDIO_VERSION, pinned) || addressPin(spec))) {
+    changes.push({ file: 'package.json', kind: 'pin', what: `pin @homie-rocks/studio ${STUDIO_VERSION}${addressPin(spec) ? ' from the npm registry' : ''} (was ${pinned}${addressPin(spec) ? ', at an address that is no longer served' : ''}); then npm install`, from: spec, to: specFor(spec) });
   } else if (pkg && where && !pinned) {
     kept.push({ file: 'package.json', what: `@homie-rocks/studio is "${String(spec).slice(0, 80)}" (not a published version): left as it is` });
   }

package/lib/version.mjs

@@ -1,6 +1,6 @@
 /**
  * The one place @homie-rocks/studio says which version it is and where that exact
- * version lives. A studio pins this tarball (package.json + package-lock
+ * version lives. A studio pins this version (package.json + package-lock
  * integrity), so a published game never changes because Homie changed.
  */
 import { readFileSync } from 'node:fs';
@@ -8,14 +8,9 @@ import { readFileSync } from 'node:fs';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const STUDIO_VERSION = pkg.version;
 
-/** The pinned tarball of this version, on a Homie directory (homie.rocks by default). Kept for older studios. */
-export function tarballUrl(base = 'https://homie.rocks', version = STUDIO_VERSION) {
-  return `${String(base).replace(/\/+$/, '')}/npm/homie-studio-${version}.tgz`;
-}
-
 /**
  * What a studio's package.json names: this exact version, from registry.npmjs.org (package-lock.json keeps its
  * integrity). The public registry is what Cloudflare's Workers Builds and a Claude Code cloud session reach with
- * their default network settings; a directory's /npm/ tarball is not.
+ * their default network settings.
  */
 export function packageSpec() { return STUDIO_VERSION; }