@homie-rocks/studio 0.58.8 → 0.58.11

package/CHANGELOG.md

@@ -17,6 +17,38 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.58.11] - 2026-10-19
+
+**Plugin 0.58.5**
+
+Host a studio on Workers for Platforms with a private preview, check it with a browser in the cloud, and prepare a studio for a move with an owner-controlled read-only switch.
+
+### Added
+
+- A studio can deploy to a Workers for Platforms dispatch namespace: `cloudflare.dispatchNamespace`, `worker`, `d1Id` and `domain` in studio.json name the preprovisioned Worker, and `homie-studio deploy` sends the build there with Wrangler's own `--dispatch-namespace`. `cloudflare.preview` names a second Worker and database, and `homie-studio deploy --preview` sends the same build to it. A platform that hosts studios this way (Homie Managed) enforces the target at its API boundary.
+- Every command and skill that opens a browser (check, playtest, look, perf, shoot, lab check, port check, crowd load, 3D renders, art captures and video takes) can use a browser in the cloud: with `HOMIE_BROWSER_WS_ENDPOINT` set to a CDP WebSocket address (Cloudflare Browser Run, for example), they connect to it instead of starting Chrome on this computer. A platform target leaves queues and cron triggers to the platform.
+- `homie-studio drain on|off|status` pauses new room admissions without deploying or closing existing sockets. A move waits for empty rooms and delivered records before freezing the source.
+- Managed media bindings preserve streamed media, range requests and large player saves.
+- A read-only switch for a studio: `homie-studio read-only on|off|status` (and the local MCP tool `studio_read_only`) freezes the live studio for a few minutes, for a move to another host or maintenance, without losing anything. It sets the Worker secret `STUDIO_READ_ONLY` with the studio's own Cloudflare sign-in, as a new Worker version. While on, changes answer 503 with `Retry-After` and `x-studio-read-only: 1`; pages, games, live rooms and the Stripe webhook keep working, D1 takes no other write, room records wait in each room, scheduled and queued work waits, and `/api/games` reports `readOnly`.
+
+### Fixed
+
+- Standalone apps can read an app-record write's read-only refusal; other write routes remain restricted to the studio's own origin.
+
+## [0.58.9] - 2026-10-19
+
+**Plugin 0.58.3**
+
+Build games from shared parts while keeping server rules deterministic.
+
+### Fixed
+
+- Rules can import registered studio parts and the re-exports created by `part_new`. Every dependency receives the existing rules checks, including filesystem boundary checks.
+
+### Changed
+
+- Game guides require finding, adding and actually using fitting parts before writing replacements, with source credits and concrete gaps recorded in Built from.
+
 ## [0.58.8] - 2026-10-19
 
 **Plugin 0.58.3**
@@ -165,6 +197,9 @@ A room nobody is playing rests, and the next touch wakes it with that input stil
 - Rebuild your games. Set `room.rest` to `"never"` (or `restSeconds` to 0) for a turn timer or a show that must keep
   going while people are present. A lasting world never rests.
 
+### Added
+
+
 ## [0.58.0] - 2026-10-16
 
 **Plugin 0.58.0**

package/README.md

@@ -752,6 +752,40 @@ that, with when it ends.
 open it), the command says "network preflight failed", not that the site or a game is broken, and offers the local
 dev site instead.
 
+## Read-only for a few minutes: `homie-studio read-only`
+
+Before moving a studio to another host, or during maintenance, the owner freezes it from their own computer and
+opens it again when the work is done. Nothing is lost on the way:
+
+```sh
+npx homie-studio read-only on        # every change is refused for now; the site stays up
+npx homie-studio read-only status    # what Cloudflare has, and what the live site says
+npx homie-studio read-only off       # open again
+```
+
+The switch is the Worker secret `STUDIO_READ_ONLY` (`1`), set and deleted with the studio's own Wrangler sign-in.
+Cloudflare applies a secret as a new version of the live Worker within seconds, with no build or deploy, and a deploy
+made while it is on keeps it on; like any new version, it reconnects live rooms once. The local MCP tool
+`studio_read_only` does the same for an AI. While it is on:
+
+- every request other than `GET`, `HEAD` and `OPTIONS` answers `503` with `Retry-After: 120`,
+  `x-studio-read-only: 1` and `{"ok":false,"error":"read-only","message":"…"}`. Nothing it carried was applied, so
+  the caller sends it again later;
+- every other answer carries `x-studio-read-only: 1` too, a page shows a short "read-only for a few minutes"
+  notice, and `/api/games` says `"readOnly": true` (and `false` when open), so a tool checks the switch without
+  sending a write;
+- D1 refuses writes, so a read that would also write (a visit counted, a sign-in link redeemed) writes nothing; 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:
+  payments already made are recorded and fulfilled;
+- live rooms keep playing and new ones still open (matchmaking and sockets are `GET`s, a room's state is its own
+  storage), but no room writes to D1: round records and function events wait in the room's outbox and are written
+  once the studio is open, counters with the room's next report;
+- scheduled work skips its tick, apart from the recovery of Stripe events (an owner function due in that minute does
+  not run for it); queued work other than Stripe events is retried after the window.
+
+`worker/read-only.mjs` is the whole behaviour.
+
 ## A trailer: `homie-studio trailer`
 
 ```sh

package/bin/homie-studio.mjs

@@ -106,6 +106,12 @@
  *                                         A command that changes something outside this computer (deploy, publish,
  *                                         storage add, the office, …) stops at a flag it does not know: nothing is sent.
  *   homie-studio storage add              (large media only: an R2 bucket; needs R2 turned on for the account)
+ *   homie-studio read-only [on|off|status] [--url <site>]
+ *                                         (freeze the live studio for a few minutes, e.g. while moving it or for
+ *                                          maintenance: the Worker secret STUDIO_READ_ONLY, applied at once with no
+ *                                          deploy. 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; /api/games says readOnly. worker/read-only.mjs says exactly what)
  *   homie-studio media list               (every song and video page, where each file is served from, what moves to R2)
  *   homie-studio media move [<file>...] [--dry-run] [--verify]
  *                                         (with storage: the big files of published songs and videos into R2, each
@@ -529,6 +535,13 @@ function print(result) {
         ...(result.parts && partsPlanLines(result.parts).length ? ['', ...partsPlanLines(result.parts)] : []),
         ...(result.standalone?.length ? ['', ...result.standalone] : []));
       break;
+    case 'drain on':
+    case 'drain off':
+    case 'drain status':
+    case 'read-only on':
+    case 'read-only off':
+    case 'read-only status':
+      lines.push(result.message); break;
     case 'storage add':
       lines.push(result.already ? `Storage is already added: R2 bucket ${result.bucket}.` : `Storage added: R2 bucket ${result.bucket}.`, 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
@@ -827,8 +840,10 @@ function print(result) {
  */
 const OUTWARD_FLAGS = {
   publish: ['homie', 'site', 'before'],
-  deploy: ['plan', 'ci', 'homie', 'own-route'],
+  deploy: ['plan', 'ci', 'homie', 'own-route', 'preview'],
   'storage add': [],
+  'drain': ['url'],
+  'read-only': ['url'],
   'media put': ['as'],
   'media move': ['dry-run', 'plan', 'verify'],
   'setup attach': ['homie', 'client'],
@@ -917,6 +932,8 @@ async function main() {
   if (['build', 'check', 'upgrade'].includes(cmd)) {
     for (const line of (await import('../lib/authoring-guides.mjs')).authoringWords({ kind: ['app', 'business', 'cause'].includes(readStudio(root).kind) || listExperiences(root).some(g => g.kind === 'app') ? 'app' : 'game' })) process.stderr.write(`${line}\n`);
   }
+  if (cmd === 'drain') return (await import('../lib/move-drain.mjs')).drainCommand(root, sub ?? 'status', { url: flags.get('url') ?? null });
+  if (cmd === 'read-only') return (await import('../lib/read-only.mjs')).readOnlyCommand(root, sub ?? 'status', { url: flags.get('url') ?? null });
   if (cmd === 'events') return (await import('../lib/events-cli.mjs')).eventsCommand(root, sub, positional, flags, { log });
   if (cmd === 'function' || cmd === 'functions') return (await import('../lib/functions-cli.mjs')).functionCommand(root, sub, positional, flags, { log });
   if (cmd === 'connector') return (await import('../lib/connector-token.mjs')).connectorToken(root,{url:flags.get('url'),tools:typeof flags.get('tools')==='string'?flags.get('tools').split(','):[],out:flags.get('out'),days:flags.has('days')?Number(flags.get('days')):30,revoke:flags.get('revoke')});
@@ -1056,7 +1073,7 @@ async function main() {
   // Cloudflare's Workers Builds runs `npm run deploy` with WORKERS_CI=1 (and its own token for this one account).
   if (cmd === 'deploy' && (process.env.WORKERS_CI === '1' || flags.has('ci'))) return tracked(root, 'deploy', () => ciDeploy(root, { log }), 'deploy');
   // What the deploy means for standalone copies already made (a changed netplay version), read before it runs.
-  if (cmd === 'deploy') { const copies = standaloneDeployNotes(root); return tracked(root, 'deploy', async () => { const r = await deploy(root, { log, homie: flags.get('homie'), ownRoute: flags.has('own-route') }); return r?.ok ? { ...r, standalone: copies } : r; }, 'deploy'); }
+  if (cmd === 'deploy') { const copies = standaloneDeployNotes(root); return tracked(root, 'deploy', async () => { const r = await deploy(root, { log, homie: flags.get('homie'), ownRoute: flags.has('own-route'), preview: flags.has('preview') }); return r?.ok ? { ...r, standalone: copies } : r; }, 'deploy'); }
   if (cmd === 'storage' && sub === 'add') return storageAdd(root, { log });
   if (cmd === 'storage') {
     const cf = readStudio(root).cloudflare ?? {};

package/guides/art/scripts/art.mjs

@@ -6,7 +6,7 @@ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statS
 import { dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { experienceDir, experienceJson, isServerRules, SLUG, checkBudget, findStudio, readBudget, readJson, setBudget, writeJson } from '../../music/scripts/lib/studio.mjs';
-import { GPU_FLAGS, chromePath, htmlToPng, loadPuppeteer } from '../../video/scripts/lib/browser.mjs';
+import { GPU_FLAGS, chromePath, htmlToPng, launchChrome, loadPuppeteer, remoteBrowserEndpoint } from '../../video/scripts/lib/browser.mjs';
 
 import { decode, stats } from '../../playtest/scripts/lib/pixels.mjs';
 
@@ -64,8 +64,9 @@ async function frame(root) {
   const seconds = Math.max(4, Math.min(60, Number(flags.get('seconds') ?? 12)));
   const dir = artDir(root, String(flags.get('slug') ?? 'frames'));
   const puppeteer = loadPuppeteer(root); const exe = chromePath();
-  if (!puppeteer || !exe) throw new Error(!exe ? 'no Chrome found (set CHROME_PATH)' : 'puppeteer-core is missing (npm install in the studio)');
-  const browser = await puppeteer.launch({ executablePath: exe, headless: true, timeout: 150_000, args: [...GPU_FLAGS, '--mute-audio', '--window-size=1920,1080', '--hide-scrollbars', '--force-color-profile=srgb', '--no-first-run'] });
+  const cloud = remoteBrowserEndpoint();
+  if (!puppeteer || (!exe && !cloud)) throw new Error(!exe && !cloud ? 'no Chrome found (set CHROME_PATH)' : 'puppeteer-core is missing (npm install in the studio)');
+  const browser = await launchChrome(puppeteer, { executablePath: exe, headless: true, timeout: 150_000, args: [...GPU_FLAGS, '--mute-audio', '--window-size=1920,1080', '--hide-scrollbars', '--force-color-profile=srgb', '--no-first-run'] });
   const shots = [];
   try {
     const page = await browser.newPage();

package/guides/game/RULES.md

@@ -6,6 +6,8 @@ A rules game has `src/rules.ts`, `src/move.ts`, `src/view.ts`, `game.json`,
 from the same package. Import `move` into the rules. Pictures and controls belong in
 view.ts; shared movement belongs in move.ts; all game decisions belong in rules.ts.
 
+Rules may import a deterministic part already added to this studio with `@parts/<host>/<id>` (or an own part with `@parts/<id>`). The re-export created by `part_new` works too. Every imported module is checked by the same rules guard; browser-only audio, UI and control parts belong in the view. Parts cannot import arbitrary files outside this game and registered parts.
+
 ```ts
 import { defineRules, f } from '@homie-rocks/studio/rules';
 import { move } from './move';

package/guides/game/SKILL.md

@@ -46,6 +46,8 @@ Cloudflare or physical-phone capacity guarantees.
 ## Start it
 
 - **Look for pieces before writing them.** Games build on each other by sharing parts: a creature from one game,
+  Search by system (touch controls, feedback, sound, scoring, title and results UI, rooms), not only by genre. Add a fitting result with `part_add` before implementing a replacement; import and use it in the game. A starter or npm package is not a catalog search. Record part version, source game/studio, licence and integration in CODEX **Built from**, or the search and concrete gap if nothing fits. In managed studios these same tools work; wait for the committed preview through `build_progress` after adding a part.
+
   a level from another, a bot brain from a third. For each system the game needs (camera, movement, bots, pickups,
   effects, sound, UI, environment), before writing it from scratch:
   - check the `@homie-rocks/*` packages (npm) for the general mechanism: camera, input, audio, effects;

package/guides/playtest/scripts/playtest.mjs

@@ -34,7 +34,7 @@ import { fileURLToPath } from 'node:url';
 import { experienceDir, experienceJson, findStudio, readJson } from '../../music/scripts/lib/studio.mjs';
 import { measure, sheetPng, warnings } from '../../sound/scripts/lib/measure.mjs';
 import { wavBytes } from '../../sound/scripts/lib/synth.mjs';
-import { GPU_FLAGS, chromePath, loadPuppeteer } from '../../video/scripts/lib/browser.mjs';
+import { GPU_FLAGS, chromePath, launchChrome, loadPuppeteer, remoteBrowserEndpoint } from '../../video/scripts/lib/browser.mjs';
 import { finish, within } from './lib/exit.mjs';
 import { actionProfile, activePlay, connectionNote, contextOf, describeActions, describeState, judgeFirst, judgeMove, judgeScores, judgeUi, oppositeOf, shellOverlaps, EXTRA_NAMES, readPort, UI_CAVEAT, pairMismatch, readinessOf, renderCost, reportMd, reviewLine, stateOf, weakest, REVIEW_KINDS } from './lib/judge.mjs';
 import { decode, motion, stats, uiCover } from './lib/pixels.mjs';
@@ -72,7 +72,7 @@ const open = [];
 async function launch(device, url, { tap = false, autoplay = false } = {}) {
   const vp = DEVICES[device];
   const profile = mkdtempSync(join(tmpdir(), 'homie-playtest-'));
-  const browser = await puppeteer.launch({
+  const browser = await launchChrome(puppeteer, {
     executablePath: EXE, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 120_000, // 150 s to start on a loaded computer
     args: [...GPU_FLAGS, '--mute-audio', `--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', ...(autoplay ? ['--autoplay-policy=no-user-gesture-required'] : [])],
   });
@@ -650,10 +650,10 @@ async function run() {
     const text = existsSync(gi) ? readFileSync(gi, 'utf8') : '';
     if (!/^\.playtest\/?$/m.test(text)) appendFileSync(gi, `${text.endsWith('\n') || !text ? '' : '\n'}.playtest/\n`);
   }
-  try { const f = statfsSync(out); if ((f.bavail * f.bsize) / 1e9 < 10) throw new Error('under 10 GB free on this disk: free some space before a playtest'); } catch (e) { if (/GB free/.test(e.message)) throw e; }
+  try { const f = statfsSync(out), minimumGB = remoteBrowserEndpoint() ? 1 : 10; if ((f.bavail * f.bsize) / 1e9 < minimumGB) throw new Error(`under ${minimumGB} GB free on this disk: free some space before a playtest`); } catch (e) { if (/GB free/.test(e.message)) throw e; }
   EXE = chromePath();
   puppeteer = loadPuppeteer(root);
-  if (!EXE || !puppeteer) throw new Error(!EXE ? 'no Chrome found (set CHROME_PATH to a Chrome or Chromium)' : 'puppeteer-core is not installed (it comes with @homie-rocks/studio: npm install in the studio)');
+  if ((!EXE && !remoteBrowserEndpoint()) || !puppeteer) throw new Error(!EXE && !remoteBrowserEndpoint() ? 'no Chrome found (set CHROME_PATH to a Chrome or Chromium)' : 'puppeteer-core is not installed (it comes with @homie-rocks/studio: npm install in the studio)');
   const gameJson = root ? readJson(experienceJson(experienceDir(root, game)), {}) : {};
   const isApp = root && experienceJson(experienceDir(root, game)).endsWith('/app.json');
   const started = Date.now();

package/guides/video/scripts/lib/browser.mjs

@@ -56,12 +56,12 @@ export function loadPuppeteer(root) {
 /** Launch; returns { browser, close } where close() also deletes the throwaway profile. */
 export async function launch(root, { width = 1920, height = 1080, extra = [] } = {}) {
   const exe = chromePath();
-  if (!exe) throw new Error('no Chrome found (set CHROME_PATH to a Chrome or Chromium; on Linux, `npx --no-install homie-studio chrome install` in a studio fetches Chrome for Testing)');
+  if (!exe && !remoteBrowserEndpoint()) throw new Error('no Chrome found (set CHROME_PATH to a Chrome or Chromium; on Linux, `npx --no-install homie-studio chrome install` in a studio fetches Chrome for Testing)');
   const puppeteer = loadPuppeteer(root);
   if (!puppeteer) throw new Error('puppeteer-core is not installed (it comes with @homie-rocks/studio: run npm install in the studio)');
   const profile = mkdtempSync(join(tmpdir(), 'homie-video-'));
   // 150 s for Chrome to start: on a loaded computer a cold start has taken over a minute.
-  const browser = await puppeteer.launch({
+  const browser = await launchChrome(puppeteer, {
     executablePath: exe, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 180_000,
     args: [...GPU_FLAGS, `--window-size=${width},${height}`, '--hide-scrollbars', '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--force-color-profile=srgb', ...extra],
   });
@@ -85,3 +85,24 @@ export async function htmlToPng(root, html, out, { width, height }) {
   } finally { await close(); }
   return out;
 }
+
+/** Optional CDP endpoint for a browser in the cloud (Cloudflare Browser Run, CI): HOMIE_BROWSER_WS_ENDPOINT.
+ * https://developers.cloudflare.com/browser-run/cdp/puppeteer/ — each connection is its own browser session. */
+export function remoteBrowserEndpoint(env = process.env) {
+  if (!env.HOMIE_BROWSER_WS_ENDPOINT) return null;
+  const endpoint = new URL(env.HOMIE_BROWSER_WS_ENDPOINT);
+  if (!['ws:', 'wss:'].includes(endpoint.protocol) || endpoint.username || endpoint.password) {
+    throw new Error('HOMIE_BROWSER_WS_ENDPOINT must be a WebSocket URL without embedded credentials');
+  }
+  return endpoint.href;
+}
+
+/** Puppeteer's own CDP connection when a cloud browser is set; otherwise the usual local launch. */
+export function launchChrome(puppeteer, options, { env = process.env } = {}) {
+  const browserWSEndpoint = remoteBrowserEndpoint(env);
+  if (!browserWSEndpoint) return puppeteer.launch(options);
+  // A cloud browser has no window: the size a local launch asks for with --window-size becomes the page's viewport.
+  const size = (options.args ?? []).map((a) => /^--window-size=(\d+),(\d+)$/.exec(a)).find(Boolean);
+  return puppeteer.connect({ browserWSEndpoint, protocolTimeout: options.protocolTimeout ?? 180_000,
+    defaultViewport: size ? { width: Number(size[1]), height: Number(size[2]) } : null });
+}

package/lib/check.mjs

@@ -33,7 +33,7 @@ import { readAppNeeds, proveAppNeeds, saveAppNeeds, needSteps, primaryNeedSurfac
 import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { cpus, loadavg, tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { SOFTWARE_GL, chromeArgs, findChrome, measureFrames, noChrome } from './chrome.mjs';
+import { SOFTWARE_GL, chromeArgs, findChrome, measureFrames, noChrome, remoteBrowserEndpoint, launchChrome } from './chrome.mjs';
 import { reachSite, siteRefusal } from './net.mjs';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -156,7 +156,7 @@ export async function check({ webglFailure = false, isolate = true, root = null,
     } catch(error) {return {ok:false,command:'check',kind:'app',why:error.message};}
   }
   const chrome = findChrome();
-  if (!chrome) return { ok: false, command: 'check', why: noChrome() };
+  if (!chrome && !remoteBrowserEndpoint()) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   if (appMeta) return checkApp({ webglFailure, isolate, root, url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
@@ -193,7 +193,7 @@ export async function check({ webglFailure = false, isolate = true, root = null,
     for (const kind of kinds) {
       const profile = mkdtempSync(join(tmpdir(), 'homie-studio-check-'));
       profiles.push(profile);
-      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(), '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
       });
@@ -394,7 +394,7 @@ export async function checkApp({ webglFailure = false, isolate = true, root = nu
       }
       return remoteCookies.get(key);
     };
-    if(baseline || plan?.needs.some(n=>[...needSteps(n.steps),...(n.assertions??[])].some(i=>i.surface))) browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
+    if(baseline || plan?.needs.some(n=>[...needSteps(n.steps),...(n.assertions??[])].some(i=>i.surface))) browser = await launchChrome(puppeteer, { executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
     const openSurface = async (name, role) => {
       const dimensions={wall:[1280,720],phone:[390,844],'phone-two':[390,844],tablet:[1024,768],staff:[1024,768],kiosk:[1080,1920]};
       if(!dimensions[name])throw new Error(`Unknown needs surface ${name}`);

package/lib/chrome.mjs

@@ -135,3 +135,26 @@ export async function measureFrames(page, ms = 2000) {
     ]);
   } catch { return { fps: null, renderer: null }; }
 }
+
+/** Optional CDP endpoint for CI and cloud browsers, including Cloudflare Browser Run.
+ * Each connection must acquire its own browser session; the caller closes it as usual.
+ * Cloudflare: https://developers.cloudflare.com/browser-run/cdp/puppeteer/
+ */
+export function remoteBrowserEndpoint(env = process.env) {
+  if (!env.HOMIE_BROWSER_WS_ENDPOINT) return null;
+  const endpoint = new URL(env.HOMIE_BROWSER_WS_ENDPOINT);
+  if (!['ws:', 'wss:'].includes(endpoint.protocol) || endpoint.username || endpoint.password) {
+    throw new Error('HOMIE_BROWSER_WS_ENDPOINT must be a WebSocket URL without embedded credentials');
+  }
+  return endpoint.href;
+}
+
+/** Puppeteer's own CDP connection; local checks keep their normal Chrome launch. */
+export function launchChrome(puppeteer, options, { env = process.env } = {}) {
+  const browserWSEndpoint = remoteBrowserEndpoint(env);
+  if (!browserWSEndpoint) return puppeteer.launch(options);
+  // A cloud browser has no window: the size a local launch asks for with --window-size becomes the page's viewport.
+  const size = (options.args ?? []).map((a) => /^--window-size=(\d+),(\d+)$/.exec(a)).find(Boolean);
+  return puppeteer.connect({ browserWSEndpoint, protocolTimeout: options.protocolTimeout ?? 180_000,
+    defaultViewport: size ? { width: Number(size[1]), height: Number(size[2]) } : null });
+}

package/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import {dispatchTarget,dispatchArgs,targetConfig} from './dispatch-target.mjs';
 import {ensureStudioSigningKey} from './studios-keys.mjs';
 import {redactText} from './redact.mjs';
 import {enableReadReplication} from './read-replication.mjs';
@@ -73,10 +74,12 @@ export function wranglerBin(root) {
 }
 
 /** Wrangler from the studio's own node_modules, using Cloudflare's own sign-in. */
-export function runner(root, env) {
+export function runner(root, env, { preview = false } = {}) {
   const bin = wranglerBin(root);
+  const target = dispatchTarget(readStudio(root), { preview });
   if (!bin) throw new Error('Wrangler is not installed in this studio yet: run `npm install` in the studio folder first');
   return (args, { cwd = workerDir(root), input, timeout = 10 * 60_000 } = {}) => {
+    args = dispatchArgs(args, target, target && targetConfig(root, target));
     const dev = join(workerDir(root), '.wrangler', 'homie-dev.wrangler.json');
     if (args.includes('--local') && !args.includes('--config') && existsSync(dev)) args = [...args, '--config', dev, '--persist-to', join(workerDir(root), '.wrangler', 'state')];
     const res = spawnSync(bin, args, {
@@ -278,8 +281,12 @@ export async function deploy(root, opts = {}) {
   try { return await deployLocked(root, opts); } finally { process.off('exit', onExit); lock.release(); }
 }
 
-async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRoute = false } = {}) {
+async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRoute = false, preview = false } = {}) {
   const studio = readStudio(root);
+  if (dispatchTarget(studio, { preview })) {
+    await build(root, { log, deploy: true });
+    return ciDeploy(root, { log, preview });
+  }
   const cf = { r2: null, created: [], ...studio.cloudflare };
   const created = new Set(cf.created ?? []);
   // A wildcard or catch-all route in the studio's own config would hand other hostnames of the zone to this Worker:
@@ -636,8 +643,9 @@ export function configNames(root) {
  * nothing back (a CI checkout is thrown away). On the very first deploy the database may not exist yet: Wrangler
  * creates the one the binding names while it deploys, and the migrations run right after.
  */
-export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
-  const w = wrangler ?? runner(root, {});
+export async function ciDeploy(root, { log = () => {}, wrangler = null, preview = false } = {}) {
+  const target = dispatchTarget(readStudio(root), { preview });
+  const w = wrangler ?? runner(root, {}, { preview });
   refreshWorkerConfig(root);
   const names = configNames(root);
   const steps = [];
@@ -645,10 +653,11 @@ export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
   const refuse = (why, out) => ({ ok: false, command: 'deploy', ci: true, ...(explainCloudflare(out) ?? { why }), steps });
   if (!existsSync(join(root, 'site', 'dist', 'games.json'))) return { ok: false, command: 'deploy', ci: true, why: 'nothing is built: the build command is `npm run build` (homie-studio build), and it runs before this', steps };
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
-  try {await ensureBackgroundQueues(root,w);} catch(error) {return refuse(error.message);}
+  // A platform target's queues are the platform's (lib/dispatch-target.mjs).
+  if (!target) { try {await ensureBackgroundQueues(root,w);} catch(error) {return refuse(error.message);} }
   const apply = () => w(['d1', 'migrations', 'apply', names.binding, '--remote']);
   let migrate = apply();
-  const first = migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);
+  const first = !target && migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);
   if (migrate.code !== 0 && !first) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   if (!first) step('D1 migrations applied');
   const register=()=>w(['d1','execute',names.binding,'--remote','--command',functionDeploymentSQL(root)]);
@@ -680,8 +689,9 @@ export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
   // The live address, from what Wrangler printed (a custom domain in studio.json wins).
   const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? null;
   let url = null;
-  try { url = siteUrl(root) ?? workersDev; } catch { url = workersDev; }
-  const claim = url ? await warmClaim(url) : null;
+  try { url = target ? `https://${target.domain}` : siteUrl(root) ?? workersDev; } catch { url = workersDev; }
+  // A private preview is never claimed in the directory.
+  const claim = url && !target?.preview ? await warmClaim(url) : null;
   step(claim ? (listedHere(root,{site:url})?'the site is listed':'the site is claimed, not listed') : 'no directory claim yet (the site claims itself when the directory first reads it)');
   let games = [];
   try { games = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')).games.map((g) => g.id); } catch { games = []; }

package/lib/crowd-load.mjs

@@ -7,6 +7,7 @@ import { resolve } from 'node:path';
 import { createHash } from 'node:crypto';
 import { performance, monitorEventLoopDelay } from 'node:perf_hooks';
 import puppeteer from 'puppeteer-core';
+import { launchChrome } from './chrome.mjs';
 import { Histogram } from './crowd-worker.mjs';
 const opts = {};
 const args = process.argv.slice(2);
@@ -180,7 +181,7 @@ function makeWorker(index) {
 async function chromeWindow(i) {
   const profile = await mkdtemp(`${tmpdir()}/crowd-load-`);
   profiles.push(profile);
-  const browser = await puppeteer.launch({
+  const browser = await launchChrome(puppeteer, {
     executablePath:
       opts.chrome ??
       process.env.CHROME_PATH ??

package/lib/dispatch-target.mjs

@@ -0,0 +1,49 @@
+import {existsSync,mkdirSync,readFileSync,writeFileSync,renameSync} from 'node:fs';
+import {dirname,isAbsolute,join} from 'node:path';
+import {configPath,workerDir} from './studio.mjs';
+/**
+ * A preprovisioned Workers for Platforms target, deployed by ordinary Wrangler
+ * (https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/).
+ * studio.json names it; the platform owns routing and resources and enforces the target at its API boundary:
+ *
+ *   "cloudflare": {"dispatchNamespace":"…","worker":"…","d1Id":"…","domain":"…",
+ *                  "preview":{"worker":"…","d1Id":"…","domain":"…"}}
+ *
+ * `deploy --preview` sends the same build to the preview Worker and its own database.
+ */
+const NAME=/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$/,UUID=/^[0-9a-f-]{36}$/i,HOST=/^[a-z0-9.-]+$/i;
+export function dispatchTarget(studio,{preview=false}={}) {
+  const cf=studio.cloudflare??{};
+  if(cf.dispatchNamespace===undefined) {
+    if(preview)throw Error('deploy --preview needs a Workers for Platforms preview target in studio.json (cloudflare.preview)');
+    return null;
+  }
+  if(typeof cf.dispatchNamespace!=='string'||!NAME.test(cf.dispatchNamespace))throw Error('Invalid cloudflare.dispatchNamespace');
+  const t=preview?cf.preview:cf;
+  if(!t||!NAME.test(t.worker??'')||!UUID.test(t.d1Id??'')||!HOST.test(t.domain??''))throw Error(`A dispatch target needs its preprovisioned worker, d1Id and domain in studio.json${preview?' (cloudflare.preview)':''}`);
+  return {namespace:cf.dispatchNamespace,worker:t.worker,d1Id:t.d1Id,domain:t.domain.toLowerCase(),preview};
+}
+/** The studio's generated wrangler.jsonc, pointed at the target: its Worker name and its database. */
+export function targetConfig(root,target) {
+  const base=workerDir(root),json=JSON.parse(readFileSync(configPath(root),'utf8').replace(/^\s*\/\/.*$/gm,''));
+  const abs=p=>p&&!isAbsolute(p)?join(base,p):p;
+  delete json.$schema;
+  json.name=target.worker;
+  if(json.main)json.main=abs(json.main);
+  if(json.assets?.directory)json.assets.directory=abs(json.assets.directory);
+  if(!json.d1_databases?.length)throw Error('The studio has no D1 database in wrangler.jsonc');
+  json.d1_databases=json.d1_databases.map((d,i)=>({...d,...(i===0?{database_id:target.d1Id}:{}),...(d.migrations_dir?{migrations_dir:abs(d.migrations_dir)}:{})}));
+  // The platform routes its hostnames, runs its scheduled ticks and owns its queues: a dispatch Worker has no
+  // routes, workers.dev, cron triggers or queue bindings of its own.
+  for(const key of ['route','routes','workers_dev','preview_urls','triggers','queues'])delete json[key];
+  const file=join(base,'.wrangler',target.preview?'homie-preview.wrangler.json':'homie-target.wrangler.json');
+  mkdirSync(dirname(file),{recursive:true});
+  const temp=`${file}.${process.pid}.tmp`;writeFileSync(temp,`${JSON.stringify(json,null,2)}\n`);renameSync(temp,file);
+  return file;
+}
+export function dispatchArgs(args,target,config) {
+  if(!target||args.includes('--local'))return args;
+  if(args.some(a=>['--name','--dispatch-namespace','--config','-c'].includes(a)||/^--(name|dispatch-namespace|config)=/.test(a)))throw Error('The deployment target comes from studio.json');
+  if(!config||!existsSync(config))throw Error('The deployment target configuration is missing');
+  return ['deploy','secret'].includes(args[0])?[...args,'--config',config,'--dispatch-namespace',target.namespace]:[...args,'--config',config];
+}

package/lib/lab-check.mjs

@@ -23,7 +23,7 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { chromeArgs, findChrome, noChrome, SOFTWARE_GL } from './chrome.mjs';
+import { chromeArgs, findChrome, noChrome, SOFTWARE_GL, launchChrome, remoteBrowserEndpoint } from './chrome.mjs';
 import { labDir, startLabServer } from './lab.mjs';
 import { isRulesGame, listExperiences as listGames } from './studio.mjs';
 
@@ -109,7 +109,7 @@ export async function labCheck(root, id, { take = null, today = 'HEAD', device =
   const game = id ?? (games.length === 1 ? games[0].id : null);
   if (!game || !games.some((g) => g.id === game)) return { ok: false, command: 'lab check', why: `name the game: homie-studio lab check <${games.map((g) => g.id).join('|') || 'id'}>` };
   const chrome = findChrome();
-  if (!chrome) return { ok: false, command: 'lab check', why: noChrome() };
+  if (!chrome && !remoteBrowserEndpoint()) return { ok: false, command: 'lab check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'lab check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
@@ -117,7 +117,7 @@ export async function labCheck(root, id, { take = null, today = 'HEAD', device =
   mkdirSync(dir, { recursive: true });
   const server = await startLabServer(root, { port: 0, today, watchFiles: false, log: () => {} });
   let browser;
-  try { browser = await puppeteer.launch({
+  try { browser = await launchChrome(puppeteer, {
     executablePath: chrome, headless: true, timeout: 150_000, protocolTimeout: 240_000,
     args: [...chromeArgs(), '--mute-audio', '--window-size=1600,1000', '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows', '--force-color-profile=srgb'],
   }); } catch (error) { await server.close(); throw error; }

package/lib/look.mjs

@@ -10,7 +10,7 @@
 import { mkdirSync, 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';
 
 
 export const LOOK_DEVICES = {
@@ -25,14 +25,14 @@ const nameOf = (path) => path.replace(/^\/+|\/+$/g, '').replace(/[^a-z0-9]+/gi,
 export async function look({ url, paths, shots, devices = Object.keys(LOOK_DEVICES), log = () => {} }) {
   if (!url) return { ok: false, command: 'look', why: 'give --url (the local dev address or the live site)' };
   const chrome = findChrome();
-  if (!chrome) return { ok: false, command: 'look', why: noChrome() };
+  if (!chrome && !remoteBrowserEndpoint()) return { ok: false, command: 'look', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'look', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   const base = String(url).replace(/\/+$/, '');
   mkdirSync(shots, { recursive: true });
   const profile = mkdtempSync(join(tmpdir(), 'homie-studio-look-'));
   // 150 s for Chrome to start: on a loaded computer a cold start has taken over a minute.
-  const browser = await puppeteer.launch({
+  const browser = await launchChrome(puppeteer, {
     executablePath: chrome, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 180_000,
     args: [...chromeArgs(), '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
   });

package/lib/mcp-tools.mjs

@@ -810,6 +810,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.',

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