@homie-rocks/studio 0.9.0 → 0.10.0

package/lib/scaffold.mjs

@@ -25,40 +25,66 @@ import { dirname, join, relative, resolve } from 'node:path';
 import { STUDIO_VERSION, packageSpec } from './version.mjs';
 import { STATS_MIGRATION, STATS_MIGRATION_FILE } from '../worker/stats.mjs';
 import { themeFile } from './site.mjs';
+import { PACKAGE_ROOT } from './studio.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
-export const WRANGLER_VERSION = '4.126.0';
+/** 4.135.0 or later: Worker Previews (`wrangler preview`, a Durable Object namespace per Preview). */
+export const WRANGLER_VERSION = '4.145.0';
 
 export function slugify(name) {
   return String(name ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
     .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '') || 'studio';
 }
 
-/** The Worker config, generated so a later deploy can rewrite exactly what it owns. */
-export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null }) {
+/*
+ * The Worker config, generated so a later deploy can rewrite exactly what it owns.
+ *
+ * `layout: 'root'` (every studio from 0.10.0) keeps it at the studio's root, where Cloudflare's Workers Builds and
+ * the "Deploy to Cloudflare" button look for it; `'site'` is the older site/wrangler.jsonc.
+ *
+ * PREVIEWS (Cloudflare Worker Previews, Wrangler 4.135.0+): a branch deploys with `npx wrangler preview` (Workers
+ * Builds does it on every push that is not to the production branch) to its own URL, and Cloudflare gives every
+ * Preview its OWN Durable Object namespace, so a Preview's public rooms never meet production's. The `previews`
+ * block binds the same Table and Lobby classes and names the Preview (HOMIE_PREVIEW). It binds no D1 on purpose:
+ * a Preview counts nothing into the studio's stats, records no rounds and never claims itself in the directory;
+ * its pages and rooms work without it.
+ *
+ * No `database_id` until one is known: Wrangler (4.45.0+) and the Deploy to Cloudflare flow create the database
+ * the binding names and keep it linked.
+ */
+export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root' }) {
+  const at = layout === 'site' ? { schema: '../node_modules', main: 'src/worker.mjs', dist: './dist', migrations: 'migrations' }
+    : { schema: 'node_modules', main: 'site/src/worker.mjs', dist: './site/dist', migrations: 'site/migrations' };
+  const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }];
   const config = {
-    $schema: '../node_modules/wrangler/config-schema.json',
+    $schema: `${at.schema}/wrangler/config-schema.json`,
     name: worker,
-    main: 'src/worker.mjs',
+    main: at.main,
     compatibility_date: COMPAT_DATE,
+    // The site's own fetches (its directory claim, "played this week") go out as any browser's would, so a studio
+    // whose directory is on the same zone (a house studio on *.homie.rocks, or two Workers on one workers.dev
+    // subdomain) reaches it instead of failing with 1042.
+    compatibility_flags: ['global_fetch_strictly_public'],
     workers_dev: true,
-    preview_urls: false,
-    assets: { directory: './dist', binding: 'ASSETS', run_worker_first: true },
-    durable_objects: { bindings: [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }] },
+    preview_urls: true,
+    assets: { directory: at.dist, binding: 'ASSETS', run_worker_first: true },
+    durable_objects: { bindings: rooms },
     migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }],
-    d1_databases: [{ binding: 'DB', database_name: d1, ...(d1Id ? { database_id: d1Id } : {}), migrations_dir: 'migrations' }],
+    d1_databases: [{ binding: 'DB', database_name: d1, ...(d1Id ? { database_id: d1Id } : {}), migrations_dir: at.migrations }],
     ...(r2 ? { r2_buckets: [{ binding: 'MEDIA', bucket_name: r2 }] } : {}),
     vars: { STUDIO_NAME: name },
     observability: { enabled: true },
+    previews: { vars: { STUDIO_NAME: name, HOMIE_PREVIEW: '1' }, durable_objects: { bindings: rooms } },
   };
-  return `// This studio's site on its own Cloudflare account (written by homie-studio; \`homie-studio deploy\`
-// fills in the D1 id). Everything here runs on Cloudflare's Workers Free plan. There is no R2 binding
+  return `// This studio's site on its own Cloudflare account (written by homie-studio). Everything here runs on
+// Cloudflare's Workers Free plan. \`npm run deploy\` (on this computer, or in Workers Builds) puts it live;
+// \`npx wrangler preview\` puts a branch on its own Preview URL with its own rooms. There is no R2 binding
 // until \`homie-studio storage add\` gives the studio storage for large media.
 ${JSON.stringify(config, null, 2)}
 `;
 }
 
-function agentsMd({ name, slug }) {
+export function agentsMd({ name, slug }) {
   return `# ${name}
 
 This folder is a studio: **${name}** (\`${slug}\`). It is one repository.
@@ -75,7 +101,9 @@ directory lists its games; homie.rocks does not host them.
 | \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`. |
 | \`music/\`, \`videos/\` | Songs, scores, loops; trailers, music videos, cutscenes. \`manifest.json\` lists each one (\`node_modules/@homie-rocks/studio/media/MEDIA.md\`); a published entry gets a page at \`/music/<slug>/\` or \`/videos/<slug>/\`, served from the site itself (files up to 25 MiB) or, for larger media, from the studio's storage once it has storage (see below; \`npx --no-install homie-studio media put <file>\`). Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
 | \`posts/\` | The studio's news and drops: one markdown file each (\`posts/2026-09-30-we-are-live.md\`: \`title:\`, \`date:\`, \`summary:\`, and \`game:\` / \`song:\` / \`video:\` to link one). They are the site's Posts, with Atom and JSON feeds. |
-| \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`), D1 migrations, \`wrangler.jsonc\`. |
+| \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`) and its D1 migrations. |
+| \`wrangler.jsonc\` | The Worker's Cloudflare config (the Worker, D1, the Table and Lobby Durable Objects, and \`previews\` for branch Previews), at the root, where Cloudflare's Workers Builds reads it. A studio made before 0.10.0 keeps it in \`site/\` and deploys from a computer; every command finds either. |
+| \`changes/\` | One small file per change that went out through a pull request (\`homie-studio progress pr\` writes it): the site lists the newest, so the Claude app can tell when a merged change is live. |
 | \`studio.json\` | The studio's name, slug, Cloudflare resource names, custom domain and stats sharing. \`.studio/\` (git-ignored) is this computer's own state. |
 | \`.claude/skills/\` | Skills only this studio uses. Homie's own skills come from the Homie plugin. |
 
@@ -103,6 +131,11 @@ studio's pinned copy, never a registry lookup of the bare name.
   SQLite-backed Durable Objects, all on the free Workers plan (no payment method needed).
   If Wrangler is not signed in, run \`npx wrangler login\`: the person approves once in
   their browser. It never overwrites a Worker or database this studio did not create.
+- **Workers Builds** (Cloudflare's own CI, set up by the "Deploy to Cloudflare" button or in the dashboard): on
+  every push to \`main\` it runs \`npm run build\` and \`npm run deploy\`, which in Workers Builds only applies
+  the D1 migrations and deploys (it never creates or refuses anything); on every other branch it runs
+  \`npm run build\` and \`npx wrangler preview\`, a Preview URL with its own rooms. The live site claims itself
+  in the homie.rocks directory the first time it is read, so nothing is stored by hand.
 - \`npx --no-install homie-studio storage add\` — only when the studio needs large media (songs,
   videos): an R2 bucket for \`media put\`, served at \`/media/<key>\`. Cloudflare asks for a
   payment method on the account before R2 works (its first 10 GB a month are free), so this
@@ -186,7 +219,7 @@ Claude-only notes go below this line. -->
 `;
 }
 
-function readme({ name }) {
+export function readme({ name }) {
   return `# ${name}
 
 A game studio made with [Homie](https://homie.rocks). Open this folder in Claude Code or Codex
@@ -249,7 +282,7 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 | \`pages/<path>/index.html\` | A whole page at \`/<path>/\`, instead of the generated one (\`pages/<id>/index.html\` replaces a game's landing) or beside them (\`pages/about/index.html\`). It may borrow \`<!-- homie:style -->\`, \`<!-- homie:header -->\`, \`<!-- homie:footer -->\`, \`<!-- homie:script -->\`. |
 | \`public/\` | Files served as they are, at the same path (\`public/fonts/x.woff2\` is \`/fonts/x.woff2\`). |
 
-\`src/worker.mjs\`, \`migrations/\` and \`wrangler.jsonc\` are the Worker; \`dist/\` is the build (not committed).
+\`src/worker.mjs\` and \`migrations/\` are the Worker (its config is \`wrangler.jsonc\`, at the studio's root); \`dist/\` is the build (not committed).
 `;
 
 const GITIGNORE = `node_modules/
@@ -278,10 +311,13 @@ videos/**/*.webm
 `;
 
 /** Every file a new studio gets, relative to its folder. */
-export function studioFiles({ name, slug, homie }) {
+export function studioFiles({ name, slug, homie, template = false }) {
   const worker = slug;
   const studio = {
     name, slug,
+    // A copy of the public template (Deploy to Cloudflare) until `homie-studio setup attach` names it for real:
+    // meanwhile its site shows the name the person typed in Cloudflare's form (STUDIO_NAME).
+    ...(template ? { template: true } : {}),
     homie: { studio: STUDIO_VERSION, directory: homie },
     // r2 stays null until `homie-studio storage add`: a new studio deploys with no R2 at all.
     // `domain`: the studio's own domain once it has one (e.g. "night-owls.example"). The workers.dev address never
@@ -297,11 +333,20 @@ export function studioFiles({ name, slug, homie }) {
     type: 'module',
     scripts: { dev: 'homie-studio dev', build: 'homie-studio build', deploy: 'homie-studio deploy', check: 'homie-studio check', studio: 'homie-studio' },
     devDependencies: { '@homie-rocks/studio': packageSpec(homie), wrangler: WRANGLER_VERSION },
+    // What Cloudflare's "Deploy to Cloudflare" form says about each setting (package.json `cloudflare.bindings`).
+    cloudflare: {
+      label: 'Homie studio',
+      products: ['Workers', 'D1', 'Durable Objects'],
+      bindings: {
+        STUDIO_NAME: { description: 'Your studio\'s name, as its site shows it (for example **Night Owls**). Claude can change it later.' },
+        DB: { description: 'The studio\'s own database: finished rounds, the studio\'s own stats (counts, never a visitor) and its claim in the [homie.rocks](https://homie.rocks/studios/) directory. Free plan.' },
+      },
+    },
   };
-  return {
+  const files = {
     'AGENTS.md': agentsMd({ name, slug }),
     'CLAUDE.md': claudeMd(),
-    'README.md': readme({ name }),
+    'README.md': template ? templateReadme() : readme({ name }),
     'studio.json': `${JSON.stringify(studio, null, 2)}\n`,
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     '.gitignore': GITIGNORE,
@@ -319,9 +364,61 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
     'site/migrations/0001_studio.sql': MIGRATION,
     [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
-    'site/wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2 }),
+    'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
   };
+  if (template) {
+    // A first game, so the site plays the moment Cloudflare deploys it; and a band on Home that connects the new
+    // studio to the Claude chat that set it up (`setup attach` removes both once Claude works in the studio).
+    for (const [rel, text] of starterFiles('gem-rush')) files[`games/gem-rush/${rel}`] = text;
+    files['site/partials/home.html'] = CONNECT_BAND;
+  }
+  return files;
+}
+
+/** A starter's files, as text, relative to its folder. */
+function starterFiles(id) {
+  const dir = join(PACKAGE_ROOT, 'starters', id);
+  const out = [];
+  const walk = (rel) => {
+    for (const entry of readdirSync(join(dir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(path);
+      else out.push([path, readFileSync(join(dir, path), 'utf8')]);
+    }
+  };
+  walk('');
+  return out;
+}
+
+/** The template's first-run band on Home: one link that connects this studio to the Claude chat that set it up. */
+export const CONNECT_BAND = `<!-- A new studio from the Homie template. This band goes away once Claude works in the studio
+     (homie-studio setup attach removes it); delete it by hand any time. -->
+<div class="band-in" style="text-align:center">
+  <p class="kicker">New studio</p>
+  <h2>{{studio.name}} is live</h2>
+  <p>It runs on your own Cloudflare account. Connect it to the Claude chat that set it up, and Claude takes it from here.</p>
+  <p><a class="btn" href="/_studio/connect">Connect to Claude</a></p>
+</div>
+`;
+
+export function templateReadme() {
+  return `# A Homie studio
+
+This repository is a game studio made with [Homie](https://homie.rocks): its games, music, videos and posts,
+and a site with public multiplayer rooms that runs on **your own Cloudflare account**, on the free plan.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/homie-rocks/homie/tree/main/template)
+
+The button copies this studio into your GitHub, creates its Worker, database and rooms on your Cloudflare, and
+deploys it with Workers Builds: every push to \`main\` goes live, and every other branch gets its own Preview.
+The site plays a first game the moment it is up.
+
+Then open the site and tap **Connect to Claude**, or ask Claude in the Claude app to set up your studio with the
+Homie connector: it makes games, songs and videos here, in a pull request you merge with one tap.
+
+\`AGENTS.md\` says how everything here works.
+`;
 }
 
 /**
@@ -352,7 +449,7 @@ function insideGit(dir) {
   try { return execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() === 'true'; } catch { return false; }
 }
 
-export function newStudio(folder, { name, homie, slug: askedSlug, install = true } = {}) {
+export function newStudio(folder, { name, homie, slug: askedSlug, install = true, template = false } = {}) {
   if (typeof folder !== 'string' || !folder.trim()) throw new Error('name the folder for the new studio, e.g. `homie-studio new ~/studios/night-owls --name "Night Owls"`. Nothing was written.');
   if (!name || !String(name).trim()) throw new Error('give the studio a name: --name "Night Owls". Nothing was written.');
   const dir = resolve(folder.replace(/^~(?=\/|$)/, homedir()));
@@ -367,7 +464,7 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
     if (entries.length) throw new Error(`${real} is not empty (${entries.slice(0, 5).join(', ')}${entries.length > 5 ? ', …' : ''}). A new studio goes in a new or empty folder. Nothing was written.`);
   }
   const slug = slugify(askedSlug || name);
-  const files = studioFiles({ name: String(name).trim(), slug, homie: homie || 'https://homie.rocks' });
+  const files = studioFiles({ name: String(name).trim(), slug, homie: homie || 'https://homie.rocks', template });
   mkdirSync(dir, { recursive: true });
   const wrote = [];
   for (const [rel, content] of Object.entries(files)) {

package/lib/setup.mjs

@@ -0,0 +1,90 @@
+/**
+ * `homie-studio setup attach <hs_…>` — this repository is the studio the Claude app's setup card (the Homie MCP
+ * tool studio_setup) is making, said once from the Claude Code session that works in it:
+ *
+ *   - the directory records that Claude works in this repository (the card's "Let Claude work in it" goes green),
+ *     and answers with the studio's live address once its site is connected (the card's Cloudflare step);
+ *   - a copy of the public template (studio.json `template: true`) gets the name the person chose in the chat:
+ *     studio.json, the Worker's STUDIO_NAME, and AGENTS.md and README.md while they are untouched; its first-run
+ *     "Connect to Claude" band goes; studio.json takes the Worker and database names Cloudflare's form chose;
+ *   - the live address goes into .studio/local.json (git-ignored), so `check --url` and the card know it.
+ *
+ * It sends the repository's owner/name and the studio's name and slug, nothing else: no key, no path, no code.
+ * A setup id is single use per repository: a second attach from the same repository answers the same; another
+ * repository is refused.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configNames } from './cloudflare.mjs';
+import { networkWhy } from './progress.mjs';
+import { CONNECT_BAND, agentsMd, readme, slugify, templateReadme } from './scaffold.mjs';
+import { configPath, readStudio, writeLocal, writeStudio } from './studio.mjs';
+import { STUDIO_VERSION } from './version.mjs';
+
+const SETUP_ID = /^hs_[a-f0-9]{32}$/;
+
+/** owner/repo of this checkout's GitHub remote (a Claude Code cloud session's remote goes through its own proxy). */
+export function repoOf(root) {
+  const r = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8', timeout: 5000 });
+  if (r.status !== 0) return null;
+  const url = r.stdout.trim().replace(/\.git$/, '').replace(/\/+$/, '');
+  const m = /[/:]([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100})$/.exec(url);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+export async function setupAttach(root, id, { homie } = {}) {
+  if (!SETUP_ID.test(String(id ?? ''))) return { ok: false, command: 'setup attach', why: 'attach to the setup id the Claude app\'s setup card showed: hs_ and 32 hex digits' };
+  const studio = readStudio(root);
+  const directory = String(homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  const repo = repoOf(root);
+  let res; let body = null;
+  try {
+    res = await fetch(`${directory}/api/studio/setup/${id}/attach`, {
+      method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION}` },
+      body: JSON.stringify({ repo, studio: { name: studio.name, slug: studio.slug, template: studio.template === true }, version: STUDIO_VERSION }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    body = await res.json().catch(() => null);
+  } catch (error) { return { ok: false, command: 'setup attach', why: `${directory} did not answer (${error?.message ?? error})` }; }
+  const blocked = networkWhy(res, directory);
+  if (blocked) return { ok: false, command: 'setup attach', needs: 'network', why: blocked };
+  if (!res.ok || !body?.ok) return { ok: false, command: 'setup attach', why: body?.message ?? `${directory} answered ${res.status}` };
+
+  const renamed = [];
+  const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim().slice(0, 60) : null;
+  if (studio.template === true) {
+    const next = { ...readStudio(root) };
+    delete next.template;
+    const was = { name: next.name, slug: next.slug };
+    if (name) { next.name = name; next.slug = slugify(name); }
+    // The Worker and database are whatever Cloudflare's form named them: studio.json follows wrangler.jsonc.
+    const names = configNames(root);
+    next.cloudflare = { ...next.cloudflare, ...(names.worker ? { worker: names.worker } : {}), ...(names.d1 ? { d1: names.d1 } : {}) };
+    writeStudio(root, next);
+    renamed.push('studio.json');
+    if (name) {
+      const cfg = configPath(root);
+      const text = readFileSync(cfg, 'utf8');
+      const fixed = text.replace(/("STUDIO_NAME"\s*:\s*)"(?:[^"\\]|\\.)*"/g, (_, k) => `${k}${JSON.stringify(name)}`);
+      if (fixed !== text) { writeFileSync(cfg, fixed); renamed.push('wrangler.jsonc'); }
+      const untouched = (file, before, after) => {
+        const path = join(root, file);
+        if (existsSync(path) && readFileSync(path, 'utf8') === before) { writeFileSync(path, after); renamed.push(file); }
+      };
+      untouched('AGENTS.md', agentsMd(was), agentsMd({ name: next.name, slug: next.slug }));
+      untouched('README.md', templateReadme(), readme({ name: next.name }));
+    }
+    const band = join(root, 'site', 'partials', 'home.html');
+    if (existsSync(band) && readFileSync(band, 'utf8') === CONNECT_BAND) { rmSync(band); renamed.push('site/partials/home.html (removed)'); }
+  }
+  if (body.site) writeLocal(root, { url: body.site, connectedAt: new Date().toISOString() });
+  return {
+    ok: true, command: 'setup attach', setup: id, repo, site: body.site ?? null, name: name ?? studio.name, renamed,
+    message: body.site ? `This repository is ${name ?? studio.name}, live at ${body.site}. The Claude app's card shows it.` : `This repository is ${name ?? studio.name}. Its site is not connected yet: ${body.connect ?? 'open the site and tap Connect to Claude'}.`,
+    next: [
+      ...(renamed.length ? ['commit the renamed files on a branch and open a pull request (merging it names the live site)'] : []),
+      'npm install, then npx --no-install homie-studio progress attach <hb_…> when the chat opened a build',
+    ],
+  };
+}

package/lib/studio.mjs

@@ -26,6 +26,17 @@ export function requireStudio(from) {
   return root;
 }
 
+/*
+ * WHERE THE WORKER'S CONFIG LIVES. From 0.10.0 a new studio keeps `wrangler.jsonc` at its root, which is what
+ * Cloudflare's Workers Builds and its "Deploy to Cloudflare" button read (they run the studio's own `npm run build`
+ * and `npm run deploy` at the repository's root). A studio made before 0.10.0 keeps `site/wrangler.jsonc`; every
+ * command runs Wrangler next to whichever the studio has, so both keep working.
+ */
+export function workerDir(root) { return existsSync(join(root, 'wrangler.jsonc')) || !existsSync(join(root, 'site', 'wrangler.jsonc')) ? root : join(root, 'site'); }
+export function configPath(root) { return join(workerDir(root), 'wrangler.jsonc'); }
+/** 'root' (0.10.0 and later: Workers Builds ready) or 'site' (older studios). */
+export function layoutOf(root) { return workerDir(root) === root ? 'root' : 'site'; }
+
 export function readStudio(root) { return JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')); }
 export function writeStudio(root, studio) { writeFileSync(join(root, 'studio.json'), `${JSON.stringify(studio, null, 2)}\n`); }
 

package/lib/template-history.json

@@ -152,6 +152,29 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.10.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "2af7c804c1e81d86",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "c204473d9b468f49",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/lib/version.mjs

@@ -8,10 +8,14 @@ import { readFileSync } from 'node:fs';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const STUDIO_VERSION = pkg.version;
 
-/** The pinned tarball of this version, on a Homie directory (homie.rocks by default). */
+/** The pinned tarball of this version, on a Homie directory (homie.rocks by default). Kept for older studios. */
 export function tarballUrl(base = 'https://homie.rocks', version = STUDIO_VERSION) {
   return `${String(base).replace(/\/+$/, '')}/npm/homie-studio-${version}.tgz`;
 }
 
-/** What a studio's package.json names: until @homie-rocks/studio is on the npm registry, its versioned tarball URL. */
-export function packageSpec(base) { return tarballUrl(base); }
+/**
+ * What a studio's package.json names: this exact version, from registry.npmjs.org (package-lock.json keeps its
+ * integrity). The public registry is what Cloudflare's Workers Builds and a Claude Code cloud session reach with
+ * their default network settings; a directory's /npm/ tarball is not.
+ */
+export function packageSpec() { return STUDIO_VERSION; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/worker/index.mjs

@@ -90,9 +90,71 @@ async function postsOf(env, origin) {
   } catch { return []; }
 }
 
-async function claimOf(env) {
+/*
+ * THE SITE CLAIMS ITSELF IN THE DIRECTORY (0.10.0). The homie.rocks directory lists a studio only when its site
+ * serves the claim the directory handed out for that exact address, which proves the studio controls the site.
+ * Before 0.10.0 `homie-studio deploy` fetched the claim and stored it in D1 from the person's computer; a site built
+ * by Cloudflare's Workers Builds has no such step. So the site asks for its own claim the first time its manifest
+ * is read (by the directory publishing it, or `deploy` reading it once), for the address it is being read at, and
+ * keeps it in its D1 (`meta`, `homie_claim:<origin>`).
+ *
+ * It never asks from a Preview (HOMIE_PREVIEW: a Preview is a branch under review, not the studio), from a studio
+ * whose studio.json says `homie.directory: false`, or without its D1. A directory that does not answer is asked
+ * again at most once a minute per address; the page answers without a claim meanwhile.
+ */
+const CLAIM = /^[a-f0-9]{16,128}$/;
+const claimed = new Map();
+const claimMissed = new Map();
+
+async function storedClaim(env, origin) {
   if (!env.DB) return null;
-  try { return (await env.DB.prepare('SELECT value FROM meta WHERE key = ?').bind('homie_claim').first())?.value ?? null; } catch { return null; }
+  try {
+    const rows = (await env.DB.prepare('SELECT key, value FROM meta WHERE key IN (?1, ?2)').bind(`homie_claim:${origin}`, 'homie_claim').all()).results ?? [];
+    return { own: rows.find((r) => r.key === `homie_claim:${origin}`)?.value ?? null, older: rows.find((r) => r.key === 'homie_claim')?.value ?? null };
+  } catch { return null; }
+}
+
+export function directoryOf(cat) {
+  const d = cat?.studio?.directory;
+  if (d === null || d === false) return null;
+  const at = String(d ?? 'https://homie.rocks').replace(/\/+$/, '');
+  try {
+    const u = new URL(at);
+    return u.protocol === 'https:' || (u.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(u.hostname)) ? u.origin : null;
+  } catch { return null; }
+}
+
+/** This address's claim: kept, else asked of the directory now (and kept), else an older studio's single claim. */
+async function claimOf(env, cat, url) {
+  const origin = url.origin;
+  if (claimed.has(origin)) return claimed.get(origin);
+  const kept = await storedClaim(env, origin);
+  if (kept?.own) { claimed.set(origin, kept.own); return kept.own; }
+  const directory = directoryOf(cat);
+  const local = url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname);
+  const may = directory && env.DB && env.HOMIE_PREVIEW !== '1' && (url.protocol === 'https:' || (local && directory.startsWith('http://')))
+    && Date.now() - (claimMissed.get(origin) ?? 0) > 60_000;
+  if (may) {
+    try {
+      const res = await fetch(`${directory}/api/studio/claim?site=${encodeURIComponent(origin)}`, {
+        headers: { accept: 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION_TAG} (site claim)` }, signal: AbortSignal.timeout(5000),
+      });
+      const body = await res.json().catch(() => null);
+      if (res.ok && CLAIM.test(String(body?.claim ?? ''))) {
+        await env.DB.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?1, ?2)').bind(`homie_claim:${origin}`, body.claim).run();
+        claimed.set(origin, body.claim);
+        return body.claim;
+      }
+    } catch { /* the directory is optional for a live site */ }
+    claimMissed.set(origin, Date.now());
+  }
+  return kept?.older ?? null;
+}
+
+/** A copy of the public template nobody has named yet shows the name typed into Cloudflare's form (STUDIO_NAME). */
+function named(cat, env) {
+  if (!cat?.studio?.template || !env.STUDIO_NAME) return cat;
+  return { ...cat, studio: { ...cat.studio, name: String(env.STUDIO_NAME).slice(0, 60) } };
 }
 
 /** Every public room with people in it, per game (the Lobby's list), and the number playing per game. */
@@ -303,8 +365,14 @@ async function route(request, env, ctx) {
   const parts = path.split('/').filter(Boolean);
   const read = request.method === 'GET' || request.method === 'HEAD';
   let catP = null;
-  const getCat = () => (catP ??= catalogue(env, url.origin));
+  const getCat = () => (catP ??= catalogue(env, url.origin).then((cat) => named(cat, env)));
 
+  // "Connect to Claude" (the template's first-run band): the directory's setup page, for this site's address.
+  if (path === '/_studio/connect' && read) {
+    const directory = directoryOf(await getCat());
+    if (!directory || env.HOMIE_PREVIEW === '1') return json({ ok: false, error: 'no-directory', message: 'This studio is not connected to a directory.' }, 404);
+    return Response.redirect(`${directory}/studio/setup/connect?site=${encodeURIComponent(url.origin)}`, 302);
+  }
   if (path.startsWith('/_studio/')) return ownerRoutes(request, env, url, { catalogueOf: getCat });
   if (path === '/__homie' || path.startsWith('/__homie/')) return notAHomie(request);
   if (path === '/_homie/site.js') return new Response(SITE_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': url.searchParams.get('v') === STUDIO_VERSION_TAG ? 'public, max-age=31536000, immutable' : 'public, max-age=300', 'x-content-type-options': 'nosniff' } });
@@ -336,7 +404,10 @@ async function route(request, env, ctx) {
       ...(cat.studio?.tagline ? { tagline: cat.studio.tagline } : {}),
       site: url.origin,
       studio: cat.studio?.version ?? null,
-      claim: await claimOf(env),
+      claim: await claimOf(env, cat, url),
+      // What is deployed: the commit, when, and the marks of the newest changes (a merged pull request is live when
+      // its mark is here). A Preview says it is one.
+      ...(cat.studio?.build ? { build: { commit: cat.studio.build.commit ?? null, branch: cat.studio.build.branch ?? null, at: cat.studio.build.at ?? null, changes: (cat.studio.build.changes ?? []).slice(0, 50), ...(env.HOMIE_PREVIEW === '1' ? { preview: true } : {}) } } : {}),
       games: (cat.games ?? []).map((g) => {
         // The card picture is the landing's hero still (what the landing leads with), else the game's cover.
         const cover = gameCover(g);

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.9.0';
+export const STUDIO_VERSION_TAG = '0.10.0';