@homie-rocks/studio 0.58.8 → 0.58.12

package/lib/mcp-tools.mjs

@@ -32,6 +32,7 @@ import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
 import { GAME_ID, PACKAGE_ROOT, findStudio, isRulesGame, listExperiences as listGames, readLocal, readStudio, siteUrl } from './studio.mjs';
 import { runningDev } from './dev.mjs';
+import { dispatchTarget } from './dispatch-target.mjs';
 import { deployWords } from './deploy-state.mjs';
 import { partsForListing, publishBefore, publishesSoFar } from './directory.mjs';
 import { STUDIO_VERSION } from './version.mjs';
@@ -443,7 +444,7 @@ async function startRun(ctx, root, { kind, game, title, steps }) {
   const run = { kind, title, state: 'running', ...(await feedForRun(ctx, root, { id: game ?? null, title })), jobs: [] };
   ctx.runs.set(run.build, run);
   const next = (i) => {
-    if (i >= steps.length) { run.state = 'passed'; endRun(root, run, 'passed', `${title}: done.`); if (kind !== 'deploy') ctx.note(root).checked = true; return; }
+    if (i >= steps.length) { run.state = 'passed'; endRun(root, run, 'passed', `${title}: done.`); if (kind === 'check' || kind === 'playtest') ctx.note(root).checked = true; return; }
     const step = steps[i];
     const job = cliJob(root, step.label, step.args, {
       onEnd: (j) => {
@@ -459,7 +460,30 @@ async function startRun(ctx, root, { kind, game, title, steps }) {
   return buildCard(ctx, root, feedFor(root, run.build));
 }
 
+/**
+ * WHERE "HERE" IS, FOR A HOST AWAY FROM THE PERSON'S SCREEN. A platform that runs this toolkit for the person in a
+ * workspace of its own (Homie Managed's studio workspace, a cloud dev box) has no browser beside it that can open
+ * this computer's addresses. It names the address its studio's private preview is reachable at, HOMIE_PREVIEW_URL,
+ * and the studio's studio.json names that preview's Workers for Platforms target (cloudflare.preview). Then the
+ * studio's site "here" is that preview: preview_run puts the build there (deploy --preview), and check and playtest
+ * open it after doing the same. Without both, nothing changes: the site runs on this computer.
+ */
+export function hostedPreview(root, env = process.env) {
+  const raw = String(env.HOMIE_PREVIEW_URL ?? '').trim();
+  if (!raw) return null;
+  let url;
+  try { url = new URL(raw); } catch { return null; }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) return null;
+  try { if (!dispatchTarget(readStudio(root), { preview: true })) return null; } catch { return null; }
+  return url.href.replace(/\/+$/, '');
+}
+
+/** The step that puts the studio's current build on its hosted preview (a deploy --preview builds first). */
+const PREVIEW_STEP = { label: 'the build on the private preview', args: ['deploy', '--preview'] };
+
 async function devUrl(ctx, root, port) {
+  const hosted = hostedPreview(root);
+  if (hosted) return hosted;
   const dev = devOf(root);
   if (dev) return dev.url;
   const r = await startDev(ctx, root, port);
@@ -810,6 +834,16 @@ export function toolDefs(ctx, avail = {}) {
       annotations: { title: 'Set the studio domain', ...RW },
       run: async (a) => { const r = studioDomain(ctx.root(a.studio), a.hostname); return r.ok ? ok(r.next, r) : fail(r.next, r); },
     },
+    {
+      name: 'studio_read_only', title: 'Make the studio read-only',
+      description: 'Freeze the live studio for a few minutes, e.g. while moving it to another host or during maintenance, and open it again: on, off, or status. Uses the studio\'s own Cloudflare sign-in to set or delete the Worker secret STUDIO_READ_ONLY; Cloudflare applies it at once, with no build or deploy, and live rooms reconnect once. While on, every change answers 503 with Retry-After and x-studio-read-only: 1; pages, games, live rooms and the Stripe webhook keep working. Then it reads the live site\'s /api/games readOnly to confirm. Turn it off when the work is done.',
+      inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['on', 'off', 'status'] }, url: str('Optional: the live site to check, when this computer does not know it'), ...STUDIO_ARG }, required: ['action'] },
+      annotations: { title: 'Make the studio read-only', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+      run: async (a) => {
+        const result = await (await import('./read-only.mjs')).readOnlyCommand(ctx.root(a.studio), a.action, { url: a.url ?? null });
+        return result.ok ? ok(result.message, result) : fail(result.why, result);
+      },
+    },
     {
       name: 'setup_status', title: 'Setup status',
       description: 'Step 0 of a new studio, and any time the person asks what they need or whether they are set up: what this computer and their accounts have (Node, Cloudflare signed in and email verified, Chrome for the checks, ffmpeg, and the optional GitHub, ElevenLabs and fal), what each unlocks, and the exact fix; the studios in the studios folder; and the new-studio checklist with where they are on it. For a studio that is not made yet, pass its name as studio: the checklist is then the new studio\'s, never another studio\'s that happens to be in the folder. Read-only, a few seconds. Optional rows never block anything.',
@@ -1052,6 +1086,18 @@ export function toolDefs(ctx, avail = {}) {
       run: async (a) => {
         const root = ctx.root(a.studio);
         const need = needsInstall(ctx, root); if (need) return need;
+        const hosted = hostedPreview(root);
+        if (hosted) {
+          const games = listGames(root);
+          const g = a.game ? games.find((x) => x.id === a.game) : games[0];
+          const card = await startRun(ctx, root, { kind: 'preview', game: g?.id ?? null, title: `${readStudio(root).name ?? 'The studio'}: private preview`, steps: [PREVIEW_STEP] });
+          const lines = [
+            `The studio's site runs on its private preview, not on this computer: the build is going there now (the card follows it). When it is done: ${hosted}/${games.length ? '' : ' (the home page: "First game coming soon")'}`,
+            ...games.map((x) => `  ${x.name ?? x.id}: ${hosted}/${x.id}/play`),
+            g ? `The person opens ${hosted}/${g.id}/play on two screens (a computer and a phone): two players, one room. Give them the address; do not open a browser for them.` : 'Give the person the address; do not open a browser for them.',
+          ];
+          return { ...card, content: [{ type: 'text', text: lines.join('\n') }, ...(card.content ?? [])] };
+        }
         let url = devOf(root)?.url ?? null;
         let slow = false;
         if (!url) { const r = await startDev(ctx, root, a.port); if (r.error) return fail(r.error); url = r.url; slow = Boolean(r.slow); }
@@ -1071,6 +1117,8 @@ export function toolDefs(ctx, avail = {}) {
       annotations: { title: 'Stop the site here', ...RW },
       run: async (a) => {
         const root = ctx.root(a.studio);
+        const hosted = hostedPreview(root);
+        if (hosted) return ok(`Nothing runs on this computer to stop: the studio's private preview (${hosted}/) stays as it is until the next build is put there.`, { kind: 'preview', stopped: [], hosted });
         const r = await cli(ctx, root, 'dev --stop', ['dev', '--stop'], { wait: 20_000 });
         // What a server stopped another way left behind is cleaned up and said (lib/dev.mjs).
         const note = r.result?.why && (r.result?.stale || r.result?.stopped?.length) ? ` ${r.result.why[0].toUpperCase()}${r.result.why.slice(1)}.` : '';
@@ -1089,8 +1137,10 @@ export function toolDefs(ctx, avail = {}) {
         const game = a.game ?? (games.length === 1 ? games[0].id : null);
         if (!game) return fail(games.length ? `which game? ${games.map((g) => g.id).join(', ')}` : 'there is no game to check yet');
         const url = a.url ? String(a.url) : await devUrl(ctx, root);
+        const hosted = !a.url && hostedPreview(root);
         return startRun(ctx, root, { kind: 'check', game, title: `${games.find((g) => g.id === game)?.name ?? game}: ${games.find((g) => g.id === game)?.kind === 'app' ? 'multi-screen' : 'two-browser'} check`, steps: [
           ...(games.some((g) => g.id === game && isRulesGame(g)) ? [{ label: 'rules build check', args: ['build', game] }] : []),
+          ...(hosted ? [PREVIEW_STEP] : []),
           { label: 'two-browser check', args: ['check', game, '--url', url, '--shots', join('.checks', game)] },
         ] });
       },
@@ -1107,9 +1157,11 @@ export function toolDefs(ctx, avail = {}) {
         const game = a.game ?? (games.length === 1 ? games[0].id : null);
         if (!game) return fail(games.length ? `which game? ${games.map((g) => g.id).join(', ')}` : 'there is no game to playtest yet');
         const url = a.url ? String(a.url) : await devUrl(ctx, root);
+        const hosted = !a.url && hostedPreview(root);
         const shots = join('.checks', `${game}-look`);
         return startRun(ctx, root, { kind: 'playtest', game, title: `${games.find((g) => g.id === game)?.name ?? game}: playtest`, steps: [
           ...(games.some((g) => g.id === game && isRulesGame(g)) ? [{ label: 'rules build check', args: ['build', game] }] : []),
+          ...(hosted ? [PREVIEW_STEP] : []),
           { label: 'two-browser check', args: ['check', game, '--url', url, '--shots', join('.checks', game)] },
           { label: 'pictures on a computer and a phone', soft: true, args: ['look', `/${game}/`, `/${game}/${games.find((g) => g.id === game)?.kind === 'app' ? 'open' : 'play'}`, '--url', url, '--only', 'computer,phone', '--shots', shots],
             // The first screen of each page first (a whole page is a tall picture): what a person sees on arrival.

package/lib/move-drain.mjs

@@ -0,0 +1,18 @@
+import {readStudio,siteUrl} from './studio.mjs';
+import {runner} from './cloudflare.mjs';
+export async function drainCommand(root,action,{run=null,fetchFn=fetch,url=null}={}){
+ if(!['on','off','status'].includes(action))throw Error('Use homie-studio drain on|off|status');
+ const studio=readStudio(root),cf=studio.cloudflare??{};
+ if(!cf.d1)throw Error('Deploy this studio before draining rooms');
+ if(action!=='status'){
+  const w=run??runner(root,cf.accountId?{CLOUDFLARE_ACCOUNT_ID:cf.accountId}:{});
+  const sql=action==='on'?`INSERT INTO meta(key,value) VALUES('studio_move_drain','${Date.now()}') ON CONFLICT(key) DO UPDATE SET value=CASE WHEN CAST(meta.value AS INTEGER)>0 THEN meta.value ELSE excluded.value END;`:"DELETE FROM meta WHERE key='studio_move_drain';";
+  const result=await w(['d1','execute',cf.d1,'--remote','--command',sql]);
+  if(result.code!==0)throw Error('Cloudflare could not change room admission; sign in and retry');
+ }
+ const site=url??siteUrl(root,studio);const response=await fetchFn(new URL('/api/move-status',site),{cache:'no-store',signal:AbortSignal.timeout(120000)});
+ if(!response.ok)throw Error('Room drain is unmeasured; keep the source running');
+ const status=await response.json();
+ if(typeof status.draining!=='boolean'||typeof status.drained!=='boolean')throw Error('Upgrade and deploy the toolkit before draining');
+ return {ok:true,command:'drain '+action,...status,message:status.drained?'All measured rooms are empty and their pending records are delivered. The source can now be made read-only.':status.draining?'Existing rooms keep playing. New admissions are paused. Run homie-studio drain status until drained is true before freezing or changing hosts.':'Room admissions are open.'};
+}

package/lib/perf.mjs

@@ -49,7 +49,7 @@ import { cpus, loadavg, tmpdir, totalmem } from 'node:os';
 import { basename, join, relative, resolve } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import { bundleOf, gameDigest } from './build.mjs';
-import { SOFTWARE_GL, chromeArgs, findChrome, noChrome } from './chrome.mjs';
+import { SOFTWARE_GL, chromeArgs, findChrome, noChrome, launchChrome, remoteBrowserEndpoint } from './chrome.mjs';
 import { CUT_OFF, LAUNCH_TIMEOUT_MS, arrivalFacts, linkOf } from './check.mjs';
 import { reachSite, siteRefusal } from './net.mjs';
 import { judge, judgePaired, round, summarize } from './perf-stats.mjs';
@@ -211,7 +211,7 @@ async function openPlayer(puppeteer, chrome, device, playUrl, label, log, cpu) {
   const rate = device === 'phone' ? cpu : dev.cpu;
   const profileDir = mkdtempSync(join(tmpdir(), 'homie-studio-perf-'));
   const vp = dev.viewport;
-  const browser = await puppeteer.launch({
+  const browser = await launchChrome(puppeteer, {
     executablePath: chrome, headless: true, userDataDir: profileDir, timeout: LAUNCH_TIMEOUT_MS, protocolTimeout: 180_000,
     args: [...chromeArgs(), '--mute-audio', '--autoplay-policy=no-user-gesture-required', `--window-size=${vp.width},${vp.height}`, '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows', '--force-color-profile=srgb', '--enable-precise-memory-info'],
   });
@@ -548,7 +548,7 @@ export async function perfRun({ root = null, url, game, devices = ['computer', '
   const bad = devices.filter((d) => !PERF_DEVICES[d]);
   if (bad.length) return { ok: false, command: 'perf', why: `unknown device ${bad.join(', ')} (computer, phone)` };
   const chrome = findChrome();
-  if (!chrome) return { ok: false, command: 'perf', why: noChrome() };
+  if (!chrome && !remoteBrowserEndpoint()) return { ok: false, command: 'perf', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'perf', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   // One preflight from this process (lib/net.mjs `reachSite`): a name Node cannot look up, or no connection, is said as

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,90 @@
      }
     }
    }
+  },
+  "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"
+      }
+     }
+    }
+   }
+  },
+  "0.58.12": {
+   "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.12",
   "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.12","sha256":"c4b8a5e3b41289d47fc410729449c3ba63c921bae04042e8c2c09c15053c11e9"});

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);