@homie-rocks/studio 0.58.8 → 0.58.12

package/CHANGELOG.md

@@ -17,6 +17,49 @@ 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.12] - 2026-10-20
+
+**Plugin 0.58.6**
+
+Every browser the toolkit opens can be a cloud browser, and a studio worked on away from the person's screen previews on its own private preview.
+
+### Added
+
+- 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 (in 0.58.11 only check and the playtest script could): 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.
+- A host that runs the toolkit away from the person's screen (Homie Managed's studio workspace, a cloud dev box) can name the address of the studio's private preview in `HOMIE_PREVIEW_URL`. For a studio whose studio.json has a preview target (`cloudflare.preview`), the local MCP server's `preview_run` then puts the build there (`deploy --preview`) and gives that address, `check` and `playtest` put the current build there and open it, and `preview_stop` has nothing to stop. Without it, the site runs on this computer as before.
+
+## [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.
+- `homie-studio check` and the playtest script 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.
+- `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 +208,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'],
   });