@homie-rocks/studio 0.58.8 → 0.58.11

package/lib/port-check.mjs

@@ -33,7 +33,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { chromeArgs, findChrome, isLoopbackUrl, noChrome } from './chrome.mjs';
+import { chromeArgs, findChrome, isLoopbackUrl, noChrome, launchChrome, remoteBrowserEndpoint } from './chrome.mjs';
 import { reachSite, siteRefusal } from './net.mjs';
 
 const GPU = [
@@ -245,7 +245,7 @@ async function chrome(puppeteer, kind, exe) {
   const dir = mkdtempSync(join(tmpdir(), 'homie-port-check-'));
   const vp = kind === 'phone' ? { width: 412, height: 915 } : kind === 'tv' ? { width: 1280, height: 720 } : { width: 1280, height: 800 };
   // 150 s for Chrome to start: on a loaded computer a cold start has taken over a minute.
-  const browser = await puppeteer.launch({ executablePath: exe, headless: true, userDataDir: dir, timeout: 150_000, protocolTimeout: 120_000, args: [...GPU, `--window-size=${vp.width},${vp.height}`] });
+  const browser = await launchChrome(puppeteer, { executablePath: exe, headless: true, userDataDir: dir, timeout: 150_000, protocolTimeout: 120_000, args: [...GPU, `--window-size=${vp.width},${vp.height}`] });
   const page = (await browser.pages())[0] ?? await browser.newPage();
   if (kind === 'phone') await page.emulate({ viewport: { ...vp, deviceScaleFactor: 2.625, isMobile: true, hasTouch: true }, userAgent: `${ANDROID_UA} ${TAG}` });
   else { await page.setViewport({ ...vp, deviceScaleFactor: 1 }); await page.setUserAgent(`${await browser.userAgent()} ${TAG}`); }
@@ -501,7 +501,7 @@ export async function portCheck({ url, game, root, only = null, shots = null, lo
   const base = String(url).replace(/\/+$/, '');
   const want = new Set((only ? String(only).split(',') : ALL).map((s) => s.trim()).filter(Boolean));
   const exe = findChrome();
-  if (!exe) return { ok: false, command: 'port check', why: noChrome() };
+  if (!exe && !remoteBrowserEndpoint()) return { ok: false, command: 'port check', why: noChrome() };
   const req = createRequire(join(root ?? process.cwd(), 'package.json'));
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { try { puppeteer = req('puppeteer-core'); } catch { return { ok: false, command: 'port check', why: 'puppeteer-core is missing (it comes with @homie-rocks/studio: npm install)' }; } }

package/lib/read-only.mjs

@@ -0,0 +1,69 @@
+/**
+ * homie-studio read-only on|off|status [--url <site>]
+ *
+ * Freezes the studio for a few minutes (a move to another host, maintenance) without losing anything: the Worker
+ * secret STUDIO_READ_ONLY=1, set and deleted with the studio's own Wrangler sign-in. Cloudflare applies a secret to
+ * the live Worker at once, with no build or deploy, and a deploy made while it is on keeps it on. What the Worker
+ * does while it is on is worker/read-only.mjs. After the change the command reads the live site's /api/games
+ * (`readOnly`) until it agrees, so the person is told what the site does, not only what was asked of Cloudflare.
+ */
+import {readStudio,siteUrl} from './studio.mjs';
+import {runner} from './cloudflare.mjs';
+import {redactText} from './redact.mjs';
+import {READ_ONLY_HEADER,READ_ONLY_RETRY_SECONDS} from '../worker/read-only.mjs';
+
+export const READ_ONLY_SETTING='STUDIO_READ_ONLY';
+const ACTIONS=['on','off','status'];
+
+const wranglerSaid=r=>redactText(String([r?.out,r?.stdout].filter(Boolean).join('\n')||'Wrangler failed')).text.trim().slice(-1200);
+
+/** What the live site says now: true or false from /api/games, null when it could not be read. */
+async function liveReadOnly(site,want,{fetchFn,wait,tries}) {
+  let seen=null;
+  for(let i=0;i<tries;i++) {
+    if(i&&wait)await new Promise(r=>setTimeout(r,wait));
+    try {
+      const res=await fetchFn(new URL('/api/games',site),{headers:{accept:'application/json'},signal:AbortSignal.timeout(10_000)});
+      const body=res.ok?await res.json():null;
+      seen=typeof body?.readOnly==='boolean'?body.readOnly:null;
+    } catch {seen=null;}
+    if(seen===want)return seen;
+  }
+  return seen;
+}
+
+export async function readOnlyCommand(root,action,{run=null,fetchFn=fetch,url=null,wait=2000,tries=10}={}) {
+  if(!ACTIONS.includes(action))throw new Error('Use homie-studio read-only on, off or status');
+  const command=`read-only ${action}`;
+  const studio=readStudio(root),cf=studio.cloudflare??{};
+  if(!cf.worker)return {ok:false,command,needs:'deploy',why:'This studio is not on Cloudflare yet, so there is nothing to make read-only: deploy it first (homie-studio deploy).'};
+  const w=run??runner(root,cf.accountId?{CLOUDFLARE_ACCOUNT_ID:cf.accountId}:{});
+  const listed=await w(['secret','list','--name',cf.worker]);
+  let names=null;
+  try{names=listed.code===0?JSON.parse(listed.stdout??listed.out).map(s=>s.name):null;}catch{names=null;}
+  if(!names)return {ok:false,command,needs:'cloudflare',why:`Wrangler could not read the Worker's settings (sign in with npx wrangler login, then run this again).\n${wranglerSaid(listed)}`};
+  const was=names.includes(READ_ONLY_SETTING);
+  const readOnly=action==='status'?was:action==='on';
+  const already=action!=='status'&&was===readOnly;
+  if(!already&&action!=='status') {
+    // The value travels on stdin, as every Worker secret does here; Cloudflare applies it as a new Worker version.
+    const changed=action==='on'
+      ?await w(['secret','put',READ_ONLY_SETTING,'--name',cf.worker],{input:'1\n'})
+      :await w(['secret','delete',READ_ONLY_SETTING,'--name',cf.worker],{input:'y\n'});
+    if(changed.code!==0)return {ok:false,command,needs:'cloudflare',why:`Cloudflare did not take the change, so the studio is still ${was?'read-only':'open'}.\n${wranglerSaid(changed)}`};
+  }
+  const site=url??siteUrl(root,studio);
+  const live=site?await liveReadOnly(site,readOnly,{fetchFn,wait,tries:action==='status'?1:tries}):null;
+  const state=readOnly?'read-only':'open';
+  const lines=[
+    action==='status'?`The studio is ${state} (Cloudflare's setting ${READ_ONLY_SETTING} is ${was?'set':'not set'}).`
+      :already?`The studio was already ${state}: nothing was changed.`
+      :readOnly?`The studio is read-only now. Every change answers 503 with Retry-After: ${READ_ONLY_RETRY_SECONDS} and ${READ_ONLY_HEADER}: 1 until you run homie-studio read-only off. Pages, games and live rooms keep working, and Stripe payments are still fulfilled.`
+      :'The studio is open again: changes are taken, and what waited (room records, queued work) is delivered.',
+    live===null?(site?`${site}/api/games did not answer, so what the live site does is unmeasured: run homie-studio read-only status.`:'This computer does not know the site\'s address: pass --url to check it.')
+      :live===readOnly?`${site}/api/games says readOnly: ${live}.`
+      :`${site}/api/games still says readOnly: ${live}. Cloudflare takes a few seconds: run homie-studio read-only status.`,
+  ];
+  if(!already&&action!=='status')lines.push('Cloudflare applied it as a new version of the Worker, as a deploy does: anyone in a live room reconnects once.');
+  return {ok:true,command,readOnly,already,setting:READ_ONLY_SETTING,header:READ_ONLY_HEADER,worker:cf.worker,site,live,message:lines.join('\n')};
+}

package/lib/render3d.mjs

@@ -15,7 +15,7 @@
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { chromeArgs, findChrome, noChrome } from './chrome.mjs';
+import { chromeArgs, findChrome, noChrome, launchChrome, remoteBrowserEndpoint } from './chrome.mjs';
 import { PACKAGE_ROOT } from './studio.mjs';
 
 let bundled = null;
@@ -50,12 +50,12 @@ export function saveDataUrl(url, file) { const { bytes } = dataUrlBytes(url); wr
  */
 export async function withRenderer(fn, { log = () => {} } = {}) {
   const chrome = findChrome();
-  if (!chrome) throw new Error(noChrome());
+  if (!chrome && !remoteBrowserEndpoint()) throw new Error(noChrome());
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { throw new Error('puppeteer-core is not installed (it comes with @homie-rocks/studio: npm install)'); }
   const script = await renderScript();
   const profile = mkdtempSync(join(tmpdir(), 'homie-render-'));
-  const browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 300_000, args: [...chromeArgs(), '--no-first-run', '--no-default-browser-check', '--hide-scrollbars'] });
+  const browser = await launchChrome(puppeteer, { executablePath: chrome, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 300_000, args: [...chromeArgs(), '--no-first-run', '--no-default-browser-check', '--hide-scrollbars'] });
   try {
     const page = await browser.newPage();
     const errors = [];

package/lib/rules-guard.mjs

@@ -38,12 +38,14 @@
  * code written to attack: no rules from outside the studio run on its server.
  */
 import { parse } from '@babel/parser';
+import { listOwnParts, readOrigins, vendorDir } from './parts.mjs';
+import { partsPlugin, resolvePartImport } from './parts-build.mjs';
 import babelTraverse from '@babel/traverse';
 import * as babelGenerator from '@babel/generator';
 import * as t from '@babel/types';
 import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 
 const traverse = babelTraverse.default ?? babelTraverse;
 const generate = babelGenerator.generate ?? babelGenerator.default;
@@ -190,7 +192,7 @@ const isTarget = (path) => (path.parentPath.isAssignmentExpression() && path.par
  *             and nothing is rewritten
  * Returns { code, problems }.
  */
-export function guardSource(code, { file = 'rules.js', map = null, linked = false } = {}) {
+export function guardSource(code, { file = 'rules.js', map = null, linked = false, checkedImports = false } = {}) {
   const problems = [];
   const tracer = map ? new TraceMap(typeof map === 'string' ? JSON.parse(map) : map) : null;
   const lineOf = (node) => {
@@ -240,12 +242,12 @@ export function guardSource(code, { file = 'rules.js', map = null, linked = fals
     if (t.isImportDeclaration(st)) {
       const from = st.source.value;
       if (from === RULES_MODULE || (linked && from === GUARD_MODULE)) { for (const s of st.specifiers) homie.add(s.local.name); continue; }
-      if (/^\.\.?\//.test(from) && !linked) { for (const s of st.specifiers) own.add(s.local.name); continue; }
+      if ((/^\.\.?\//.test(from) || from.startsWith('@parts/')) && !linked) { for (const s of st.specifiers) own.add(s.local.name); continue; }
       bad(st, `rules import only ${RULES_MODULE} and the game's own files, not "${from}"`);
       continue;
     }
     const decl = t.isExportNamedDeclaration(st) || t.isExportDefaultDeclaration(st) ? st.declaration : st;
-    if (t.isExportAllDeclaration(st) || (t.isExportNamedDeclaration(st) && !st.declaration)) { if (st.source) bad(st, 'rules export their own declarations, not another file\'s'); continue; }
+    if (t.isExportAllDeclaration(st) || (t.isExportNamedDeclaration(st) && !st.declaration)) { if (st.source && (!checkedImports || linked || !/^\.\.?\//.test(st.source.value) && !st.source.value.startsWith('@parts/'))) bad(st, 'rules export their own declarations, or re-export checked local files or parts'); continue; }
     if (t.isFunctionDeclaration(decl)) continue;
     if (t.isVariableDeclaration(decl)) {
       // Removing types turns `export default <expression>` into a `var` that is exported as the default: that one is the module's own.
@@ -719,11 +721,22 @@ export async function guardFiles(esbuild, root, gameDir, entry) {
   const problems = [];
   const todo = [entry];
   const sites = {};
+  const canonical = p => existsSync(p) ? realpathSync(p) : resolve(p);
+  const inside = (dir, file) => { const rel = relative(canonical(dir), canonical(file)); return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/')); };
+  const origins = readOrigins(root);
+  const game = basename(gameDir);
+  const vendors = Object.entries(origins.parts).filter(([, entry]) => {
+    const purchase = entry.purchases?.[game] ?? entry.purchase;
+    return purchase?.scope !== 'game' || purchase.game === game;
+  }).map(([ref]) => vendorDir(root, ref));
+  const partDirs = [...listOwnParts(root).filter(p => p.part).map(p => p.dir), ...vendors]
+    .filter(p => inside(root, p) && existsSync(join(p, 'part.json')));
+  const allowed = file => inside(gameDir, file) || partDirs.some(dir => inside(dir, file));
   while (todo.length) {
     const file = todo.pop();
     if (files.has(file)) continue;
     const shown = relative(root, file).split('\\').join('/');
-    if (relative(gameDir, file).startsWith('..')) { problems.push({ file: shown, line: 0, message: 'rules import only files of their own game' }); files.set(file, null); continue; }
+    if (!allowed(file)) { problems.push({ file: shown, line: 0, message: 'rules import only files of their own game' }); files.set(file, null); continue; }
     let stripped;
     try { stripped = await esbuild.transform(readFileSync(file, 'utf8'), { loader: /\.ts$/.test(file) ? 'ts' : 'js', format: 'esm', target: 'es2022', sourcemap: 'external', sourcefile: shown }); } catch (error) {
       const first = error.errors?.[0];
@@ -744,15 +757,20 @@ export async function guardFiles(esbuild, root, gameDir, entry) {
         }
       },
     });
-    const res = guardSource(stripped.code, { file: shown, map: stripped.map });
+    const res = guardSource(stripped.code, { file: shown, map: stripped.map, checkedImports: true });
     problems.push(...res.problems);
     files.set(file, res.code);
-    for (const m of stripped.code.matchAll(/^\s*import\s[^'"]*['"](\.\.?\/[^'"]+)['"]/gm)) {
-      const next = resolveOwn(file, m[1]);
-      const line = original.program.body.find(n => n.type === 'ImportDeclaration' && n.source.value === m[1])?.loc?.start.line ?? 1;
-      if (next && relative(gameDir,next).startsWith('..')) problems.push({file:shown,line,message:'rules import only files of their own game'});
+    const module = parse(stripped.code, { sourceType: 'module' });
+    for (const declaration of module.program.body) {
+      if (!['ImportDeclaration', 'ExportAllDeclaration', 'ExportNamedDeclaration'].includes(declaration.type) || !declaration.source) continue;
+      const spec = declaration.source.value;
+      if (!/^\.\.?\//.test(spec) && !spec.startsWith('@parts/')) continue;
+      const resolved = spec.startsWith('@parts/') ? resolvePartImport(root, spec, origins) : { path: resolveOwn(file, spec) };
+      const next = resolved.path;
+      const line = original.program.body.find(n => n.source?.value === spec)?.loc?.start.line ?? 1;
+      if (next && !allowed(next)) problems.push({file:shown,line,message:'rules import only files of their own game or registered parts'});
       else if (next) todo.push(next);
-      else problems.push({ file: shown, line, message: `"${m[1]}" is not a file of this game` });
+      else problems.push({file:shown,line,message:resolved.error ?? `"${spec}" is not a file of this game or a registered part`});
     }
   }
   return { files, problems, sites };
@@ -787,7 +805,7 @@ export async function guardRules(esbuild, root, gameDir, { entry = join(gameDir,
   if (problems.length) return { ok: false, code: null, problems, files };
   let linked;
   try {
-    linked = await esbuild.build({ entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', write: false, absWorkingDir: root, logLevel: 'silent', external: [RULES_MODULE, GUARD_MODULE], plugins: [guardedPlugin(files)], legalComments: 'none' });
+    linked = await esbuild.build({ entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', write: false, absWorkingDir: root, logLevel: 'silent', external: [RULES_MODULE, GUARD_MODULE], plugins: [partsPlugin(root, basename(gameDir)), guardedPlugin(files)], legalComments: 'none' });
   } catch (error) {
     const first = error.errors?.[0];
     return { ok: false, code: null, files, problems: [{ file: first?.location?.file ?? relative(root, entry), line: first?.location?.line ?? 0, message: `the rules did not link: ${first?.text ?? error.message}` }] };

package/lib/shoot.mjs

@@ -41,7 +41,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { bundleOf, gameDigest } from './build.mjs';
 import { arrivalReadiness, LAUNCH_TIMEOUT_MS } from './check.mjs';
-import { SOFTWARE_GL, chromeArgs, findChrome, noChrome } from './chrome.mjs';
+import { SOFTWARE_GL, chromeArgs, findChrome, noChrome, launchChrome, remoteBrowserEndpoint } from './chrome.mjs';
 import { reachSite, siteRefusal } from './net.mjs';
 import { previewServer } from './preview.mjs';
 
@@ -153,7 +153,7 @@ async function open(puppeteer, chrome, device, url, profiles, browsers, { previe
   const profile = mkdtempSync(join(tmpdir(), 'homie-studio-shoot-'));
   profiles.push(profile);
   const vp = SHOOT_DEVICES[device];
-  const browser = await puppeteer.launch({
+  const browser = await launchChrome(puppeteer, {
     executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, protocolTimeout: 180_000,
     args: [...chromeArgs(), '--mute-audio', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check', `--window-size=${vp.width},${vp.height}`, '--hide-scrollbars', '--force-color-profile=srgb'],
   });
@@ -191,7 +191,7 @@ export async function shoot({ url, game, frames = 60, fps = 30, device = 'comput
   if (!(Number.isInteger(frames) && frames >= 1 && frames <= 1800)) return { ok: false, command: 'shoot', why: '--frames 1..1800' };
   if (!(fps >= 1 && fps <= 120)) return { ok: false, command: 'shoot', why: '--fps 1..120' };
   const chrome = findChrome();
-  if (!chrome) return { ok: false, command: 'shoot', why: noChrome() };
+  if (!chrome && !remoteBrowserEndpoint()) return { ok: false, command: 'shoot', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'shoot', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   // --preview: this command serves the one built game itself (no Wrangler, no rooms) and shoots that page.

package/lib/template-history.json

@@ -4512,6 +4512,48 @@
      }
     }
    }
+  },
+  "0.58.11": {
+   "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": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.58.8",
+  "version": "0.58.11",
   "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",

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.58.8","sha256":"dd01f171a16a619c527dc71c2beaaf0c9a9b70c395cb28156214d3ac988f81c5"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.58.11","sha256":"4b6a276c704c1647234dfdbef1628bff5ade43b918653552b493965a2db72f9b"});

package/worker/index.mjs

@@ -1,3 +1,5 @@
+import {drainSince,isAdmission,drainResponse} from './move-drain.mjs';
+import {managedMedia} from './managed-media.mjs';
 /** Studio Worker event boundaries and public toolkit exports. */
 import { catalogue } from './catalogue.mjs';
 import {trackBackground,requestDatabase,MUTATION_VERSION} from './request-db.mjs';
@@ -11,6 +13,7 @@ import { appCors, isAppOrigin } from './standalone.mjs';
 
 
 import {json,finish} from './responses.mjs';
+import {isReadOnly,readOnlyAccess,readOnlyDatabase,readOnlyResponse,markReadOnly,heldBatch,ReadOnlyError} from './read-only.mjs';
 
 export {useRoutes} from './custom-routes.mjs';
 export {isOwner,hasRole,requireSameOrigin} from './route-auth.mjs';
@@ -30,10 +33,17 @@ export {AppRecordHub, EventHub} from './stream-objects.mjs';
 export {directoryOf,useTools,getStudioTools} from './tool-registry.mjs';
 const route = async (...args) => (await import('./routes.mjs')).default(...args);
 export default {
-  async queue(batch,env) {return (await import('./background-queue.mjs')).consumeBackground(batch,await loadShopLinks(env));},
+  async queue(batch,env) {
+    // Read-only (worker/read-only.mjs): Stripe events are fulfilled now, the rest is retried after the window.
+    if(isReadOnly(env))batch=heldBatch(batch);
+    if(!batch.messages.length)return;
+    return (await import('./background-queue.mjs')).consumeBackground(batch,await loadShopLinks(env));
+  },
   async scheduled(event, env, ctx) {
     env=await loadShopLinks(env);
-    const analytics=event.cron === '17 * * * *' ? (await import('./analytics.mjs')).rollupAnalytics(env) : Promise.resolve();
+    const readOnly=isReadOnly(env);
+    if(readOnly)console.log(JSON.stringify({at:new Date().toISOString(),ev:'scheduled-read-only',cron:event.cron,why:'the studio is read-only: this tick only recovers Stripe events'}));
+    const analytics=event.cron === '17 * * * *' && !readOnly ? (await import('./analytics.mjs')).rollupAnalytics(env) : Promise.resolve();
     ctx.waitUntil(analytics);
     const maintenance=(async () => {
       const [{notifyTools},{reconcileOrders,shopOf}]=await Promise.all([import('./runtime-support.mjs'),import('./shop.mjs')]);
@@ -49,17 +59,27 @@ export default {
         ['Stripe recovery',async()=>{if(env.BACKGROUND && event.cron==='17 * * * *')await (await import('./stripe-intake.mjs')).sweepStripeEvents(env,cat);}],
         ['owner functions',async()=> (await import('./functions.mjs')).scheduleFunctions(event,env,cat,cat.studio?.url??'https://studio.invalid')],
       ];
-      await Promise.all(tasks.map(async([name,run])=>{try{await run();}catch(error){console.error('Scheduled '+name+' failed:',error.message);}}));
+      // Read-only: only payment fulfilment runs; every other task does its work on its next tick.
+      await Promise.all(tasks.filter(([name])=>!readOnly||name==='Stripe recovery').map(async([name,run])=>{try{await run();}catch(error){console.error('Scheduled '+name+' failed:',error.message);}}));
     })();
     ctx.waitUntil(maintenance);
     await Promise.all([maintenance,analytics]);
   },
   async fetch(request, env, ctx) {
+    env=managedMedia(env);
+    if(isAdmission(request)&&await drainSince(env))return drainResponse();
     const staticPath=new URL(request.url).pathname;
     if(['GET','HEAD'].includes(request.method)&&staticPath==='/_homie/site.js')return finish(await route(request,env,ctx),staticPath);
     env=await loadShopLinks(env,new URL(request.url).origin);
-    env={...env,DB:requestDatabase(env.DB,request,{mutated:false,summaries:Boolean(env.BACKGROUND)})};
     const url = new URL(request.url);
+    const appRecords = isAppOrigin(request) && /^\/[^/]+\/api\/app\/records\//.test(url.pathname);
+
+    // Read-only (worker/read-only.mjs): a change is refused before anything runs; a read gets a D1 that refuses writes.
+    const readOnly=isReadOnly(env),access=readOnly?readOnlyAccess(request,url.pathname):'write';
+    if(access==='refuse')return appRecords?appCors(request,readOnlyResponse()):readOnlyResponse();
+    let refusedWrite=false;
+    env={...env,DB:requestDatabase(env.DB,request,{mutated:false,summaries:Boolean(env.BACKGROUND)})};
+    if(access==='read')env={...env,DB:readOnlyDatabase(env.DB,()=>{refusedWrite=true;})};
     if(env.HOMIE_CONCEPT==='1' && url.pathname==='/robots.txt')return new Response('User-agent: *\nDisallow: /\n',{headers:{'content-type':'text/plain','x-robots-tag':'noindex, nofollow'}});
     if(env.HOMIE_CONCEPT==='1' && url.pathname==='/.well-known/homie-studio.json')return json({ok:false,error:'concept-unlisted'},404,{'x-robots-tag':'noindex, nofollow'});
     const dispatch=()=>import('./background-queue.mjs').then(m=>m.enqueueChanges(env,url.origin));
@@ -81,14 +101,16 @@ export default {
     const requestCtx=background.context;
     // 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, requestCtx), url.pathname); } catch (error) {
-      if (!appLobby) throw error;
-      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 (error instanceof ReadOnlyError) res = readOnlyResponse();
+      else if (!appLobby) throw error;
+      else {
+        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);
+      }
     } finally {
       // A route can commit a write and then fail. Its outbox still needs delivery.
       if(env.DB) {
@@ -108,6 +130,9 @@ export default {
       }
       res=new Response(body,{status:res.status,headers});
     }
+    // A read that needed its write, and failed for want of it, says why.
+    if(readOnly&&refusedWrite&&res.status>=500)res=readOnlyResponse();
+    if(readOnly)res=await markReadOnly(res);
     const bookmark=env.DB?.getBookmark?.();
     if(bookmark&&res.status!==101){const headers=new Headers(res.headers);headers.set('x-studio-bookmark',bookmark);res=new Response(res.body,{status:res.status,statusText:res.statusText,headers});}
     if (appLobby || appRecords) return appCors(request, res);

package/worker/lobby.mjs

@@ -2,6 +2,7 @@ import {LobbyPeak} from './lobby-peak.mjs';
 import {MatchRouter} from './match-router.mjs';
 import {LOBBY_SHARDS,SHARDED_ROOM_BASE} from './lobby-shards.mjs';
 import {json} from './responses.mjs';
+import {readOnlyEnv} from './read-only.mjs';
 import {lobbyStore} from './lobby-store.mjs';
 import { errorLine, versionOf } from './room-protocol.mjs';
 import { ROOM_ID } from './page-policy.mjs';
@@ -16,7 +17,7 @@ export {LOBBY_APP_VERSIONS, LOBBY_ROOMS_MAX} from './lobby-limits.mjs';
 export class Lobby {
   constructor(ctx, env) {
     this.ctx = ctx;
-    this.env = env;
+    this.env = readOnlyEnv(env); // read-only: matchmaking goes on, its D1 counters wait (worker/read-only.mjs)
     this.store = lobbyStore(ctx.storage);
     this.rooms = new Map();
     this.reservations=new Map();

package/worker/managed-media.mjs

@@ -0,0 +1,16 @@
+/** Hydrate the R2-compatible metadata returned by the studio-scoped managed binding.
+ * Streams cross RPC without buffering songs, videos or saves in the Worker heap. */
+function object(value) {
+ if(!value)return null;
+ return {...value,
+  writeHttpMetadata(headers){for(const [key,name] of Object.entries({contentType:'content-type',contentLanguage:'content-language',contentDisposition:'content-disposition',contentEncoding:'content-encoding',cacheControl:'cache-control',cacheExpiry:'expires'})){if(value.httpMetadata?.[key])headers.set(name,String(value.httpMetadata[key]));}},
+  arrayBuffer:()=>new Response(value.body).arrayBuffer(),
+  text:()=>new Response(value.body).text(),
+  json:()=>new Response(value.body).json(),
+ };
+}
+export function managedMedia(env) {
+ if(!env.HOMIE_MEDIA)return env;
+ const binding=env.HOMIE_MEDIA;
+ return {...env,MEDIA:{get:async(key,options)=>object(await binding.get(key,options)),head:async key=>object(await binding.head(key)),put:async(key,body,options)=>object(await binding.put(key,body,options)),delete:keys=>binding.delete(keys)}};
+}

package/worker/move-drain.mjs

@@ -0,0 +1,47 @@
+import {LOBBY_SHARDS} from './lobby-shards.mjs';
+export const DRAIN_KEY='studio_move_drain';
+/** How long an isolate trusts its last reading of the drain flag. A move's census waits minutes after the drain
+ * starts (drainStatus), so an admission a few seconds late is still counted; steady seats and sockets cost no D1 read. */
+export const DRAIN_TTL_MS=5000;
+const readings=new WeakMap();
+export async function drainSince(env,{now=Date.now(),fresh=false}={}){
+ if(!env.DB)return null;
+ const cached=readings.get(env.DB);
+ if(!fresh&&cached&&now-cached.at<DRAIN_TTL_MS)return cached.since;
+ const db=env.DB.withSession?env.DB.withSession('first-primary'):env.DB;
+ const row=await db.prepare('SELECT value FROM meta WHERE key=?1').bind(DRAIN_KEY).first();
+ const at=Number(row?.value),since=Number.isSafeInteger(at)&&at>0?at:null;
+ readings.set(env.DB,{at:now,since});
+ return since;
+}
+export function isAdmission(request){const path=new URL(request.url).pathname;return request.headers.get('upgrade')?.toLowerCase()==='websocket'||/\/api\/(lobby|agents)(\/|$)/.test(path);}
+export const drainResponse=()=>Response.json({ok:false,error:'moving',message:'This studio is moving. Existing rooms can finish; please join again shortly.'},{status:503,headers:{'retry-after':'30','cache-control':'no-store'}});
+/** Read every shard directly: cached public summaries exclude private games and hide outages. */
+export async function drainStatus(env,cat,{now=Date.now()}={}){
+ const since=await drainSince(env,{fresh:true});if(!since)return {draining:false,drained:false};
+ let clients=0,pending=0,rooms=0;
+ for(const game of cat.games??[]){
+  const names=new Set();
+  let cursor='';
+  for(;;){
+   const rows=(await env.DB.prepare("SELECT key FROM meta WHERE key LIKE ?1 AND key>?2 ORDER BY key LIMIT 500").bind('move-room:'+game.id+':%',cursor).all()).results;
+   if(!Array.isArray(rows))throw Error('Room admission registry unavailable');
+   for(const row of rows)names.add(row.key.slice(('move-room:'+game.id+':').length));
+   if(rows.length<500)break;cursor=rows.at(-1).key;
+  }
+  for(let shard=0;shard<LOBBY_SHARDS;shard++){
+   const stub=env.LOBBY.get(env.LOBBY.idFromName(shard?`${game.id}/shard/${shard}`:game.id));
+   const r=await stub.fetch('https://lobby/rooms');if(!r.ok)throw Error('Cannot measure rooms while moving');
+   const body=await r.json();if(!Array.isArray(body.rooms))throw Error('Invalid room census');
+   for(const room of body.rooms)names.add(room.name);
+  }
+  for(const name of names){
+   const r=await env.TABLE.get(env.TABLE.idFromName(`${game.id}/${name}`)).fetch(`https://table/__move-status?game=${encodeURIComponent(game.id)}&room=${encodeURIComponent(name)}`);
+   if(!r.ok)throw Error('Cannot measure a room while moving');
+   const body=await r.json();
+   if(!Number.isSafeInteger(body.clients)||body.clients<0||!Number.isSafeInteger(body.pending)||body.pending<0)throw Error('Invalid room drain receipt');
+   clients+=body.clients;pending+=body.pending;rooms++;
+  }
+ }
+ return {draining:true,since,clients,pending,rooms,drained:now-since>=240000&&clients===0&&pending===0};
+}

package/worker/read-only.mjs

@@ -0,0 +1,113 @@
+/**
+ * READ-ONLY: the owner freezes the studio for a few minutes (a move to another host, maintenance) and nothing is lost.
+ * `homie-studio read-only on` sets the Worker secret STUDIO_READ_ONLY=1 (lib/read-only.mjs); `off` deletes it. A
+ * secret, not a var in wrangler.jsonc, because Cloudflare applies it to the live Worker at once with no build or
+ * deploy, and a deploy made while it is on keeps it on.
+ *
+ * While it is on:
+ * - every request other than GET, HEAD and OPTIONS answers 503 with Retry-After, `x-studio-read-only: 1` and
+ *   {ok:false,error:'read-only',message}; nothing it carried was applied, so the caller sends it again later;
+ * - reads keep answering, and every answer carries `x-studio-read-only: 1`; an HTML page shows a short notice;
+ *   `/api/games` says `readOnly: true`, so a tool checks the switch without sending a write;
+ * - D1 refuses writes for every request and every room: a read that would also have written (a visit counted, a
+ *   sign-in link redeemed) writes nothing, and a page that needed its write answers the same 503;
+ * - Stripe's webhook (POST /api/shop/hook) and the queued reconciliation of its events keep the whole database, so
+ *   a payment already made is still recorded and fulfilled;
+ * - live rooms keep playing (their sockets and matchmaking are GETs, their state is the room's own storage); what a
+ *   room would write to D1 waits: round records and function events stay in the room's outbox and are delivered once
+ *   the studio is open again, counters are retried with the next report;
+ * - scheduled maintenance is skipped for its tick, except the recovery of Stripe events; queued work other than
+ *   Stripe events is retried after the read-only window.
+ */
+export const READ_ONLY_HEADER = 'x-studio-read-only';
+export const READ_ONLY_RETRY_SECONDS = 120;
+export const READ_ONLY_MESSAGE = 'This studio is read-only for a few minutes. Nothing was changed: try again shortly.';
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/** Writes that must go on while the studio is read-only: a payment already made is fulfilled. */
+const WRITES_KEPT = new Set(['POST /api/shop/hook']);
+
+export const isReadOnly = (env) => /^(1|true|on)$/i.test(String(env?.STUDIO_READ_ONLY ?? '').trim());
+
+export class ReadOnlyError extends Error {
+  constructor() { super('read-only: this studio is not writing to its database for a few minutes'); this.name = 'ReadOnlyError'; }
+}
+
+export function readOnlyResponse(extra = {}) {
+  return new Response(`${JSON.stringify({ ok: false, error: 'read-only', message: READ_ONLY_MESSAGE })}\n`, {
+    status: 503,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'retry-after': String(READ_ONLY_RETRY_SECONDS), [READ_ONLY_HEADER]: '1', ...extra },
+  });
+}
+
+/** What a request may do while the studio is read-only: 'refuse' it, 'read' (D1 refuses writes), or 'write'. */
+export function readOnlyAccess(request, path) {
+  if (WRITES_KEPT.has(`${request.method} ${path}`)) return 'write';
+  return SAFE_METHODS.has(request.method) ? 'read' : 'refuse';
+}
+
+const WRITE_WORD = /\b(?:INSERT|UPDATE|DELETE|REPLACE|UPSERT|CREATE|DROP|ALTER|ATTACH|DETACH|VACUUM|REINDEX)\b/i;
+/** A statement that cannot change the database: SELECT, VALUES, a WITH that only selects, EXPLAIN, or a PRAGMA read. */
+export function readsOnly(sql) {
+  const text = String(sql ?? '');
+  if (/^\s*EXPLAIN\b/i.test(text)) return true;
+  if (/^\s*PRAGMA\b/i.test(text)) return !text.includes('=');
+  if (/^\s*(?:SELECT|VALUES)\b/i.test(text)) return true;
+  return /^\s*WITH\b/i.test(text) && !WRITE_WORD.test(text);
+}
+
+/**
+ * D1 that refuses writes: a write rejects with ReadOnlyError (a promise, as D1's own calls are) and never reaches the
+ * database; reads and every other property are D1's own. `refused` is called with each refused statement.
+ */
+export function readOnlyDatabase(DB, refused = () => {}) {
+  if (!DB) return DB;
+  const refuse = (sql) => { refused(sql); return Promise.reject(new ReadOnlyError()); };
+  const statement = (stmt, sql) => {
+    const guarded = (method) => async (...args) => readsOnly(sql) ? stmt[method](...args) : refuse(sql);
+    return { bind: (...args) => statement(stmt.bind(...args), sql), first: guarded('first'), all: guarded('all'), run: guarded('run'), raw: guarded('raw'), _sql: sql, _readOnly: stmt };
+  };
+  const own = {
+    prepare: (sql) => statement(DB.prepare(sql), sql),
+    batch: async (list) => {
+      const bad = list.find((s) => !s?._readOnly || !readsOnly(s._sql));
+      if (bad) return refuse(bad?._sql ?? 'UNKNOWN');
+      return DB.batch(list.map((s) => s._readOnly));
+    },
+    exec: async (sql, ...args) => readsOnly(sql) ? DB.exec(sql, ...args) : refuse(sql),
+    withSession: (...args) => readOnlyDatabase(DB.withSession(...args), refused),
+  };
+  return new Proxy(own, { get(target, key) {
+    if (key in target) return target[key];
+    const value = DB[key];
+    return typeof value === 'function' ? value.bind(DB) : value;
+  } });
+}
+
+/** A Durable Object's env: its D1 refuses writes while the studio is read-only. */
+export const readOnlyEnv = (env) => isReadOnly(env) && env.DB ? { ...env, DB: readOnlyDatabase(env.DB) } : env;
+
+/** Queued work while read-only: Stripe events are reconciled now; everything else comes back after the window. */
+export function heldBatch(batch) {
+  const now = [];
+  for (const message of batch.messages) {
+    if (message.body?.v === 1 && message.body.type === 'stripe.event') now.push(message);
+    else message.retry({ delaySeconds: READ_ONLY_RETRY_SECONDS });
+  }
+  return { ...batch, messages: now };
+}
+
+const NOTICE = '<aside role="status" data-studio-read-only style="position:fixed;z-index:2147483647;bottom:0;left:0;right:0;text-align:center;background:#1f2937;color:#f9fafb;padding:8px 12px;font:600 14px system-ui,sans-serif;pointer-events:none">Read-only for a few minutes: everything can be seen and played, and changes can be made again shortly.</aside>';
+/** Every answer says the studio is read-only; a page also shows it. */
+export async function markReadOnly(res) {
+  if (!res || res.status === 101 || res.webSocket) return res;
+  const headers = new Headers(res.headers);
+  headers.set(READ_ONLY_HEADER, '1');
+  let body = res.body;
+  if (/text\/html/i.test(headers.get('content-type') ?? '') && res.status < 300 && body) {
+    const html = await res.text();
+    body = /<\/body>/i.test(html) ? html.replace(/<\/body>(?![\s\S]*<\/body>)/i, `${NOTICE}</body>`) : html + NOTICE;
+    headers.delete('content-length');
+    headers.delete('etag');
+  }
+  return new Response(body, { status: res.status, statusText: res.statusText, headers });
+}