@homie-rocks/studio 0.6.0 → 0.7.0

package/README.md

@@ -10,7 +10,7 @@ Most people never run this by hand: the Homie plugin for Claude Code and Codex d
 and the person approves Cloudflare once in their browser.
 
 ```sh
-npx -y --package=https://homie.rocks/npm/homie-studio-0.6.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y --package=https://homie.rocks/npm/homie-studio-0.7.0.tgz homie-studio new ./night-owls --name "Night Owls"
 cd night-owls && npm install
 npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
@@ -21,6 +21,21 @@ npx homie-studio publish                               # the homie.rocks directo
 npx homie-studio stats                                 # the studio's own numbers, for its owner
 ```
 
+## The site: the hub's shape, and a landing for every game
+
+Every studio site has the same sections as homie.rocks, in the studio's own look (`site/theme.json`): Home (the
+featured game, live rooms, the latest posts), Games, Music, Videos, Rooms (every public room playing now,
+joinable) and Posts (`posts/*.md`, with Atom and JSON feeds). A section with nothing in it has no tab, and its
+page answers 404. Every game gets a landing at `/<game>/`: a full-bleed hero from its own footage or art, the
+pitch, a big Play button into a public room, how to play on a phone, a computer and a TV (with the join code),
+live rooms, credits (the original and its licence for a port), and "Make a game like this". Every page ends with
+"Made with Homie". Anything the studio puts in `site/` wins: a whole page, a partial, its tokens, its CSS, its
+files. `site/SITE.md` says all of it.
+
+The play page writes its room into the address, and a small room button at the edge shares it: Invite, Big
+screen and the room code. Every HTML answer is `no-transform`, and the site's pages are never framed by another
+site.
+
 ## Rooms of up to 32
 
 Every room of a game has the seats its netplay manifest names: game.json's `netplay`
@@ -97,6 +112,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
 | `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`. |
 | `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects; `/<game>/tv` is the big screen with a join QR (`qr.mjs`); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site or from storage at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
+| `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page. |
 | `worker/stats.mjs`, `worker/stats-page.mjs`, `lib/stats.mjs` | The studio's own stats: what is counted and how, the owner-only `/api/stats` and `/_studio/stats`, and `homie-studio stats`. |
 | `lib/media.mjs`, `media/MEDIA.md` | The `music/` and `videos/` manifests: which entries get a page, and where each file's bytes come from (the site itself up to 25 MiB a file, the studio's storage, or a link). `media list` shows it; `media put` uploads a file to storage and records its key. |
 | `netplay/` | The netplay contract (`NETPLAY.md`) and its game helper (`@homie-rocks/studio/netplay`). |

package/bin/homie-studio.mjs

@@ -12,6 +12,8 @@
  *   homie-studio build [<id>]
  *   homie-studio dev [--port 8787]        (--stop: stop exactly this studio's dev server, nothing else)
  *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio look [<path>...] [--url <site>] [--shots <dir>] [--only computer,phone,sideways]
+ *                                         (the site's pages on a computer and a phone, as pictures, with what is wrong)
  *   homie-studio port plan <game folder>
  *   homie-studio port import <game folder> --id <id> [--name "<Name>"] [--mode static|bundle|command]
  *   homie-studio port check <id> [--url <site>] [--only owner-desk,owner-phone,owner-iphone,round,life,tv] [--shots <dir>]
@@ -36,6 +38,7 @@ import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
 import { deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
 import { publish } from '../lib/directory.mjs';
+import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
@@ -62,7 +65,7 @@ const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
   if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
-  if (result.ok === false && result.command !== 'port check') { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  if (result.ok === false && result.command !== 'port check' && !(result.command === 'look' && result.rows)) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   if (result.ok === false && result.command === 'port check' && !result.rows) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   const lines = [];
   switch (result.command) {
@@ -81,7 +84,12 @@ function print(result) {
     case 'build':
       lines.push(`Built ${result.games.map((g) => `${g.id} (${Math.round(g.bytes / 1024)} KB)`).join(', ') || 'no games'} into ${relative(process.cwd(), result.dist) || result.dist}`);
       if (result.songs?.length || result.videos?.length) lines.push(`Media pages: ${[...result.songs.map((x) => `/music/${x}/`), ...result.videos.map((x) => `/videos/${x}/`)].join(', ')}`);
+      for (const l of result.landings ?? []) lines.push(`Landing /${l.id}/: hero from ${l.hero === 'footage' ? 'its footage' : l.hero === 'art' ? 'its art (moving)' : 'the studio\'s colours (add a cover or hero/ footage)'}${l.credits ? ', credits' : ''}${l.source ? ', "Make a game like this" with its source' : ''}`);
+      if (result.posts?.length) lines.push(`Posts: ${result.posts.map((x) => `/posts/${x}/`).join(', ')} (feeds: /posts/feed.xml, /posts/feed.json)`);
+      if (result.pages?.length || result.partials?.length) lines.push(`The studio's own: ${[...(result.pages ?? []).map((x) => `page ${x}`), ...(result.partials ?? []).map((x) => `partial ${x}`)].join(', ')}`);
       for (const m of result.mediaSkipped ?? []) lines.push(`  left out: ${m.kind}/${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
+      for (const m of result.postsSkipped ?? []) lines.push(`  left out: posts/${m.post}: ${m.why}`);
+      for (const m of result.siteSkipped ?? []) lines.push(`  left out: ${m.what}: ${m.why}`);
       break;
     case 'media list':
       for (const kind of ['music', 'videos']) {
@@ -147,6 +155,9 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'look':
+      lines.push(`${result.ok ? 'Looks right' : 'Look again'}: ${result.rows.length} views of ${result.url}`, ...result.rows.map((r) => `  ${r.ok ? 'ok  ' : 'FIX '} ${r.path} on ${({ computer: 'a computer', phone: 'a phone', sideways: 'a phone turned sideways' })[r.device] ?? r.device}${r.problems.length ? `: ${r.problems.join('; ')}` : ''}`), '', `Pictures (open them and look): ${result.shots}`);
+      break;
     case 'check':
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
         ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`));
@@ -193,6 +204,19 @@ async function main() {
     if (!url) return { ok: false, command: 'check', why: 'give --url (the local dev address or the live site)' };
     return check({ url, game, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log });
   }
+  if (cmd === 'look') {
+    const url = flags.get('url') ?? siteUrl(root);
+    if (!url) return { ok: false, command: 'look', why: 'give --url (the local dev address or the live site)' };
+    let paths = positional.slice(1).map((p) => (p.startsWith('/') ? p : `/${p}`));
+    if (!paths.length) {
+      let cat = null;
+      try { cat = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')); } catch { /* not built */ }
+      const games = cat?.games?.map((g) => g.id) ?? listGames(root).map((g) => g.id);
+      paths = ['/', ...games.map((id) => `/${id}/`), ...(games.length ? ['/games/', '/rooms/'] : []), ...(cat?.posts?.length ? ['/posts/', `/posts/${cat.posts[0].slug}/`] : [])];
+    }
+    const only = flags.get('only') ? String(flags.get('only')).split(',').filter((d) => ['computer', 'phone', 'sideways'].includes(d)) : undefined;
+    return look({ url, paths, shots: flags.get('shots') ? resolve(flags.get('shots')) : join(root, '.studio', 'look'), devices: only, log });
+  }
   if (cmd === 'deploy' && flags.has('plan')) return deployPlan(root);
   if (cmd === 'deploy') return deploy(root, { log, homie: flags.get('homie') });
   if (cmd === 'storage' && sub === 'add') return storageAdd(root, { log });
@@ -304,7 +328,7 @@ try {
   if (result && result.command !== 'help') print(result);
   if (result?.ok === false) process.exitCode = 1;
   // Chrome's pipes can outlive browser.close(); a finished check must not hang its caller.
-  if (result?.command === 'check' || result?.command === 'port check') process.exit(process.exitCode ?? 0);
+  if (result?.command === 'check' || result?.command === 'port check' || result?.command === 'look') process.exit(process.exitCode ?? 0);
 } catch (error) {
   print({ ok: false, why: error instanceof Error ? error.message : String(error) });
   process.exitCode = 1;

package/lib/build.mjs

@@ -5,8 +5,12 @@
  *   site/dist/games/<id>/index.html        the game's page (the Worker adds HOMIE_NET)
  *   site/dist/games/<id>/assets/main.js    its bundle (esbuild; @homie-rocks/studio/netplay inlined)
  *   site/dist/games/<id>/...               everything in games/<id>/public/
- *   site/dist/games.json                   { studio, games[], songs[], videos[] } from studio.json, game.json
- *                                          files and the music/ and videos/ manifests (media/MEDIA.md)
+ *   site/dist/games.json                   { studio, games[], songs[], videos[], posts[], site } from studio.json,
+ *                                          game.json files, the music/ and videos/ manifests (media/MEDIA.md),
+ *                                          posts/*.md and the studio's site/ folder (site/SITE.md)
+ *   site/dist/games/<id>/_landing/...      what the game's landing shows (hero footage, its cover, licence texts)
+ *   site/dist/_site/                       posts.json (the posts' HTML), the studio's own pages (site/pages)
+ *   site/dist/<file>                       site/public, as it is (fonts, a logo, hero footage)
  *   site/dist/music/..., site/dist/videos/...   media files the site serves itself (R2 keys are served from R2)
  *
  * game.json "build" picks how a game becomes files (a ported game keeps its own shape):
@@ -22,6 +26,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statS
 import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
 import { buildMedia } from './media.mjs';
+import { buildSiteFiles, landingOf, readPosts, readTheme } from './site.mjs';
 import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
 import { SEAT_MAX } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
@@ -173,28 +178,49 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   else {
     try { const prev = JSON.parse(readFileSync(join(dist, 'games.json'), 'utf8')); media = { songs: prev.songs ?? [], videos: prev.videos ?? [], skipped: [] }; } catch { media = { songs: [], videos: [], skipped: [] }; }
   }
+  // The site around the games (site/SITE.md): the look, each game's landing, posts, and what site/ overrides.
+  const theme = readTheme(root, { log });
+  const shown = all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html')));
+  const rows = shown.map((g) => {
+    // The seats come from the game's netplay manifest (NETPLAY.md §3): what the Worker gives every room of it.
+    const net = netplayOf(g, join(dist, 'games', g.id));
+    const { min, max } = seatsFor(g, net);
+    return {
+      id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
+      roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
+      ...(g.screen ? { screen: g.screen } : {}),
+      landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
+    };
+  });
+  const { posts, skipped: postsSkipped } = readPosts(root, { games: rows, songs: media.songs, videos: media.videos, log });
+  const site = buildSiteFiles(root, dist, { gameIds: rows.map((g) => g.id), log });
+  mkdirSync(join(dist, '_site'), { recursive: true });
+  writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
+  const s = studio.site && typeof studio.site === 'object' ? studio.site : {};
   const catalogue = {
     studio: {
       name: studio.name, slug: studio.slug, version: STUDIO_VERSION,
+      ...(typeof studio.tagline === 'string' && studio.tagline.trim() ? { tagline: studio.tagline.trim().slice(0, 140) } : {}),
+      theme,
+      site: {
+        ...(rows.some((g) => g.id === s.featured) ? { featured: s.featured } : {}),
+        ...(Array.isArray(s.frameAncestors) ? { frameAncestors: s.frameAncestors.filter((o) => /^https:\/\/[a-z0-9.-]+(?::\d+)?$/i.test(String(o))).slice(0, 8) } : {}),
+      },
       // studio.json `stats.share`: the site tells the directory two numbers for the hub (played this week).
       ...(studio.stats?.share === true ? { stats: { share: true }, directory: studio.homie?.directory ?? 'https://homie.rocks' } : {}),
     },
-    games: all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))).map((g) => {
-      // The seats come from the game's netplay manifest (NETPLAY.md §3): what the Worker gives every room of it.
-      const net = netplayOf(g, join(dist, 'games', g.id));
-      const { min, max } = seatsFor(g, net);
-      return {
-        id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
-        roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
-        ...(g.screen ? { screen: g.screen } : {}),
-      };
-    }),
+    games: rows,
     songs: media.songs,
     videos: media.videos,
+    // Summaries only; each post's HTML is in _site/posts.json.
+    posts: posts.map(({ html, record, ...p }) => p),
+    site: { pages: site.pages, partials: site.partials, ...(site.css ? { css: site.css } : {}) },
   };
   writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);
   return {
     ok: true, command: 'build', dist, games: built, catalogue: catalogue.games.map((g) => g.id),
     songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped,
+    posts: posts.map((p) => p.slug), postsSkipped, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
+    landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length), source: g.landing.source })),
   };
 }

package/lib/look.mjs

@@ -0,0 +1,101 @@
+/**
+ * `homie-studio look [<path>...] --url <site> [--shots <dir>]` — the studio's pages as a stranger sees them:
+ * each page on a computer (1440 x 900), a phone held upright (390 x 844) and the phone turned sideways
+ * (844 x 390), scrolled to the end so everything that rises into view has, then shot whole and above the fold.
+ * Measured on every shot: the answer's status, anything wider than the screen, whether the Play button is on the
+ * first screen (Home and a game's landing), pictures that did not load, footage that did not play, and script errors. Pictures go to
+ * `--shots` (default .studio/look/), which git ignores. One Chrome, closed at the end; its visits are house QA
+ * (the studio's stats leave them out).
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const CHROMES = [
+  process.env.CHROME_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+].filter(Boolean);
+
+export const LOOK_DEVICES = {
+  computer: { width: 1440, height: 900, deviceScaleFactor: 1 },
+  phone: { width: 390, height: 844, deviceScaleFactor: 2, isMobile: true, hasTouch: true },
+  sideways: { width: 844, height: 390, deviceScaleFactor: 2, isMobile: true, hasTouch: true },
+};
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const nameOf = (path) => path.replace(/^\/+|\/+$/g, '').replace(/[^a-z0-9]+/gi, '-') || 'home';
+
+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 = CHROMES.find((p) => existsSync(p));
+  if (!chrome) return { ok: false, command: 'look', why: 'no Chrome found (set CHROME_PATH)' };
+  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-'));
+  const browser = await puppeteer.launch({
+    executablePath: chrome, headless: true, userDataDir: profile,
+    args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
+  });
+  const rows = [];
+  try {
+    for (const path of paths) {
+      for (const device of devices) {
+        const page = await browser.newPage();
+        const errors = [];
+        page.on('pageerror', (e) => errors.push(String(e?.message ?? e).slice(0, 200)));
+        page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text().slice(0, 200)); });
+        await page.setViewport(LOOK_DEVICES[device]);
+        await page.setUserAgent(`${await browser.userAgent()} homie-studio-check look`);
+        const t0 = Date.now();
+        const res = await page.goto(`${base}${path}`, { waitUntil: 'networkidle2', timeout: 45_000 }).catch((e) => { errors.push(`open: ${e.message}`); return null; });
+        const ms = Date.now() - t0;
+        await sleep(900);
+        const fold = await page.evaluate(() => {
+          // Home and a game's landing lead with Play; other pages (a post, the rooms) are not judged on it.
+          if (!['home', 'landing'].includes(document.body?.dataset?.page ?? '')) return { play: null };
+          const play = [...document.querySelectorAll('.play')].find((a) => { const r = a.getBoundingClientRect(); return r.width > 0 && r.height > 0; });
+          const r = play?.getBoundingClientRect();
+          return { play: r ? r.bottom <= innerHeight && r.top >= 0 : false };
+        });
+        const foldFile = join(shots, `${nameOf(path)}-${device}-fold.png`);
+        await page.screenshot({ path: foldFile });
+        await page.evaluate(async () => { for (let y = 0; y < document.documentElement.scrollHeight; y += Math.round(innerHeight * 0.7)) { window.scrollTo({ top: y, behavior: 'instant' }); await new Promise((r) => setTimeout(r, 110)); } window.scrollTo({ top: 0, behavior: 'instant' }); });
+        await sleep(900);
+        const facts = await page.evaluate(() => ({
+          title: document.title,
+          wide: [...document.querySelectorAll('body *')].filter((e) => { const b = e.getBoundingClientRect(); return b.width > 0 && b.right > innerWidth + 1 && !e.closest('[data-hero-media],.nav,pre,.hero-media'); }).slice(0, 5).map((e) => `${e.tagName.toLowerCase()}${e.className ? `.${String(e.className).split(' ')[0]}` : ''}`),
+          brokenImages: [...document.images].filter((i) => i.complete && i.naturalWidth === 0 && i.getAttribute('src')).map((i) => i.getAttribute('src')).slice(0, 5),
+          footage: [...document.querySelectorAll('[data-hero-media] video')].map((v) => ({ playing: !v.paused && v.readyState >= 2, src: (v.currentSrc || '').split('/').pop() })),
+          height: document.documentElement.scrollHeight,
+        }));
+        const file = join(shots, `${nameOf(path)}-${device}.png`);
+        await page.screenshot({ path: file, fullPage: true });
+        const row = {
+          path, device, status: res?.status() ?? null, ms, title: facts.title, height: facts.height, playAboveFold: fold.play,
+          tooWide: facts.wide, brokenImages: facts.brokenImages, footage: facts.footage, errors, shot: file, fold: foldFile,
+        };
+        const bad = [];
+        if (!row.status || row.status >= 400) bad.push(`answered ${row.status}`);
+        if (row.tooWide.length) bad.push(`wider than the screen: ${row.tooWide.join(', ')}`);
+        if (row.playAboveFold === false && device !== 'sideways') bad.push('Play is not on the first screen');
+        if (row.brokenImages.length) bad.push(`pictures that did not load: ${row.brokenImages.join(', ')}`);
+        if (row.footage.some((f) => !f.playing)) bad.push('the hero footage did not play');
+        if (errors.length) bad.push(`${errors.length} script error(s): ${errors[0]}`);
+        row.ok = bad.length === 0;
+        row.problems = bad;
+        rows.push(row);
+        log(`${row.ok ? 'ok  ' : 'LOOK'} ${path} ${device}: ${row.status} in ${ms} ms${bad.length ? ` · ${bad.join(' · ')}` : ''}`);
+        await page.close();
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+    rmSync(profile, { recursive: true, force: true });
+  }
+  writeFileSync(join(shots, 'look.json'), `${JSON.stringify(rows, null, 2)}\n`);
+  return { ok: rows.every((r) => r.ok), command: 'look', url: base, shots, rows };
+}

package/lib/markdown.mjs

@@ -0,0 +1,121 @@
+/**
+ * Markdown for a studio's posts, rendered once at build time into HTML the site serves as it is.
+ *
+ * A small, safe subset (site/SITE.md lists it): headings, paragraphs, **bold**, *italic*, ~~struck~~,
+ * `code`, fenced code blocks, links, images, lists, quotes and rules. Everything else is text: raw HTML in
+ * a post is escaped, never passed through, and a link or image goes only to an https:// address or a path
+ * on the studio's own site (`/…`), so a post can never run a script or point at `javascript:`.
+ */
+
+const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+export const escapeHtml = (value) => String(value ?? '').replace(/[&<>"']/g, (c) => ESC[c]);
+
+/** A link or image address a post may use: https://…, or a path on this site. Anything else is null. */
+export function safeUrl(value, { images = false } = {}) {
+  const url = String(value ?? '').trim();
+  if (!url || /[\s<>"'`\\]/.test(url)) return null;
+  if (url.startsWith('/') && !url.startsWith('//')) return url;
+  if (!images && /^#[A-Za-z0-9_-]{1,64}$/.test(url)) return url;
+  try {
+    const u = new URL(url);
+    return u.protocol === 'https:' ? u.href : null;
+  } catch { return null; }
+}
+
+const HOLD = /\u0000(\d+)\u0000/g;
+const unescapeHtml = (v) => v.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&');
+
+function emphasis(s) {
+  return s
+    .replace(/\*\*([^*]+)\*\*|__([^_]+)__/g, (m, a, b) => `<strong>${a ?? b}</strong>`)
+    .replace(/(^|[^*\w])\*([^*\s][^*]*?)\*(?!\w)/g, (m, pre, t) => `${pre}<em>${t}</em>`)
+    .replace(/(^|[^_\w])_([^_\s][^_]*?)_(?!\w)/g, (m, pre, t) => `${pre}<em>${t}</em>`)
+    .replace(/~{2}([^~]+)~{2}/g, '<s>$1</s>');
+}
+
+/* Inline: code spans, images and links are held aside as finished HTML (so emphasis never reaches inside an
+   address), then emphasis and line breaks, then the held pieces go back. */
+function inline(text) {
+  const kept = [];
+  const hold = (html) => { kept.push(html); return `\u0000${kept.length - 1}\u0000`; };
+  let s = String(text).replace(/\u0000/g, '').replace(/`([^`\n]+)`/g, (_, code) => hold(`<code>${escapeHtml(code)}</code>`));
+  s = escapeHtml(s);
+  s = s.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+&quot;([^&]*)&quot;)?\)/g, (m, alt, src, title) => {
+    const url = safeUrl(unescapeHtml(src), { images: true });
+    return url ? hold(`<img src="${escapeHtml(url)}" alt="${alt}" loading="lazy" decoding="async"${title ? ` title="${title}"` : ''}>`) : alt;
+  });
+  s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (m, label, href) => {
+    const url = safeUrl(unescapeHtml(href));
+    if (!url) return label;
+    return hold(`<a href="${escapeHtml(url)}"${/^https:/.test(url) ? ' rel="noopener"' : ''}>${emphasis(label)}</a>`);
+  });
+  s = s.replace(/&lt;(https:\/\/[^\s&]+)&gt;/g, (m, href) => {
+    const url = safeUrl(href);
+    return url ? hold(`<a href="${escapeHtml(url)}" rel="noopener">${escapeHtml(url.replace(/^https:\/\//, '').replace(/\/$/, ''))}</a>`) : m;
+  });
+  s = emphasis(s).replace(/ {2,}\n|\\\n/g, '<br>').replace(/\n/g, ' ');
+  for (let guard = 0; guard < 8 && HOLD.test(s); guard++) s = s.replace(HOLD, (_, i) => kept[Number(i)]);
+  return s;
+}
+
+/**
+ * Markdown to HTML. Headings shift down one level (a post's page has its title as the one h1), so `#` is h2.
+ * Returns the HTML and the plain text (for a feed's summary and the post record's text).
+ */
+export function renderMarkdown(source) {
+  const lines = String(source ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  let para = [];
+  const flush = () => { if (para.length) { out.push(`<p>${inline(para.join('\n'))}</p>`); para = []; } };
+  const LIST = /^\s{0,3}([-*+]|\d{1,3}[.)])\s+(.*)$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = /^(```|~~~)\s*([A-Za-z0-9_+-]{0,20})\s*$/.exec(line);
+    if (fence) {
+      flush();
+      const body = [];
+      for (i += 1; i < lines.length && !lines[i].startsWith(fence[1]); i++) body.push(lines[i]);
+      out.push(`<pre><code${fence[2] ? ` data-lang="${escapeHtml(fence[2])}"` : ''}>${escapeHtml(body.join('\n'))}</code></pre>`);
+      continue;
+    }
+    if (!line.trim()) { flush(); continue; }
+    const h = /^(#{1,5})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (h) { flush(); const n = Math.min(6, h[1].length + 1); out.push(`<h${n}>${inline(h[2])}</h${n}>`); continue; }
+    if (/^\s{0,3}([-*_])(\s*\1){2,}\s*$/.test(line)) { flush(); out.push('<hr>'); continue; }
+    const img = /^!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)\s*$/.exec(line.trim());
+    if (img) {
+      flush();
+      const url = safeUrl(img[2], { images: true });
+      if (url) out.push(`<figure><img src="${escapeHtml(url)}" alt="${escapeHtml(img[1])}" loading="lazy" decoding="async">${img[3] ? `<figcaption>${inline(img[3])}</figcaption>` : ''}</figure>`);
+      continue;
+    }
+    if (/^\s{0,3}>/.test(line)) {
+      flush();
+      const quote = [];
+      for (; i < lines.length && /^\s{0,3}>/.test(lines[i]); i++) quote.push(lines[i].replace(/^\s{0,3}>\s?/, ''));
+      i -= 1;
+      out.push(`<blockquote>${renderMarkdown(quote.join('\n')).html}</blockquote>`);
+      continue;
+    }
+    const item = LIST.exec(line);
+    if (item) {
+      flush();
+      const ordered = /\d/.test(item[1]);
+      const items = [];
+      for (; i < lines.length; i++) {
+        const m = LIST.exec(lines[i]);
+        if (m && /\d/.test(m[1]) === ordered) items.push([m[2]]);
+        else if (items.length && /^\s{2,}\S/.test(lines[i])) items[items.length - 1].push(lines[i].trim());
+        else break;
+      }
+      i -= 1;
+      out.push(`<${ordered ? 'ol' : 'ul'}>${items.map((parts) => `<li>${inline(parts.join('\n'))}</li>`).join('')}</${ordered ? 'ol' : 'ul'}>`);
+      continue;
+    }
+    para.push(line);
+  }
+  flush();
+  const html = out.join('\n');
+  const text = unescapeHtml(html.replace(/<\/?(?:p|h\d|li|ul|ol|blockquote|pre|figure|figcaption|hr|br)\b[^>]*>/g, ' ').replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
+  return { html, text };
+}

package/lib/scaffold.mjs

@@ -9,8 +9,8 @@
  *   games/<id>/          one folder per game (game.json, index.html, src/)
  *   music/ videos/       manifests in the repo; the big files go to the studio's own storage
  *                        (R2) once it is added with `homie-studio storage add`
- *   posts/               words the studio publishes
- *   site/                the studio's Worker (pages, rooms), its D1 migrations (no R2
+ *   posts/               the studio's news and drops (markdown; the site's Posts, with feeds)
+ *   site/                the studio's Worker (pages, rooms), its look (theme.json), its D1 migrations (no R2
  *                        binding until the studio adds storage: a free Cloudflare account
  *                        without a payment method cannot use R2, and a new studio needs none)
  *   .claude/skills/      skills only this studio uses
@@ -24,6 +24,7 @@ import { homedir } from 'node:os';
 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';
 
 export const COMPAT_DATE = '2026-06-01';
 export const WRANGLER_VERSION = '4.126.0';
@@ -73,8 +74,8 @@ 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/\` | Markdown the studio publishes. |
-| \`site/\` | The studio's Worker (\`src/worker.mjs\`), D1 migrations, \`wrangler.jsonc\`. |
+| \`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\`. |
 | \`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. |
 
@@ -116,6 +117,24 @@ studio's pinned copy, never a registry lookup of the bare name.
   (played this week). The site counts and never tracks: no cookie on a visitor, no person identified,
   nothing sent anywhere; house QA and \`check\` runs are not counted.
 
+## The site
+
+\`npm run build\` makes the studio's site from what is in this folder
+(\`node_modules/@homie-rocks/studio/site/SITE.md\` says all of it):
+
+- **Sections, like homie.rocks:** Home (the featured game, live rooms, latest posts), Games, Music, Videos,
+  Rooms (every public room playing now, joinable) and Posts. A section with nothing in it has no tab, and its
+  page is not found.
+- **Every game gets a landing** at \`/<id>/\`: a full-bleed hero from the game's own footage
+  (\`games/<id>/hero/wide.mp4\` and \`tall.mp4\`, or a trailer in \`videos/\` with \`for.game\`), else its cover
+  with slow motion; the pitch, a big Play button into a public room, phone / computer / TV with the join code,
+  live rooms, how to play, credits, and "Make a game like this". Give it words in game.json's \`landing\` block
+  (\`pitch\`, \`about\`, \`controls\`, \`howToPlay\`, \`credits\`) and art with the plugin's \`art\` and \`video\` skills.
+- **The look** is \`site/theme.json\` (colours, fonts, corner radius, a logo). Anything in \`site/\` wins: a whole
+  page in \`site/pages/\`, a piece of every page in \`site/partials/\`, files in \`site/public/\`, extra CSS in
+  \`site/theme.css\` (\`site/README.md\`).
+- Every page ends with "Made with Homie", linking to homie.rocks/studio/. Restyle it in \`site/theme.css\`; keep it.
+
 ## Making games
 
 - Every game is multiplayer on the web through the netplay contract
@@ -181,6 +200,46 @@ CREATE TABLE IF NOT EXISTS rounds (
 CREATE INDEX IF NOT EXISTS rounds_game_at ON rounds (game, at);
 `;
 
+const POSTS_README = `# Posts
+
+The studio's news and drops. One markdown file each; the site shows them at \`/posts/\` (newest first), on the home
+page, and in two feeds: \`/posts/feed.xml\` (Atom) and \`/posts/feed.json\` (JSON Feed).
+
+The file's name is its address: \`posts/2026-09-30-we-are-live.md\` is \`/posts/we-are-live/\`, dated by its prefix.
+
+\`\`\`markdown
+---
+title: We are live
+date: 2026-09-30
+summary: One line for the cards and the feeds.
+game: crown-thief
+image: /games/crown-thief/cover.jpg
+---
+
+The body, in markdown: **bold**, *italic*, [links](https://homie.rocks/), images, lists, quotes.
+\`\`\`
+
+\`game:\`, \`song:\` and \`video:\` link one of this studio's games, songs or videos (by id or slug); the post shows
+it with a Play, Listen or Watch button. \`draft: true\` keeps a post off the site. Raw HTML is shown as text.
+Files README.md, and names starting with \`_\` or \`.\`, are not posts.
+`;
+
+const SITE_README = `# site/
+
+The studio's site. \`npm run build\` makes every page from the studio (its games, music, videos and posts);
+anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site/SITE.md\`.
+
+| Put it in | What it does |
+| --- | --- |
+| \`theme.json\` | The look: \`bg\`, \`fg\`, \`accent\`, \`glow\` colours, \`display\` and \`text\` fonts (\`fonts\` loads a file from \`public/\`), \`radius\`, \`mark\` (a logo). Or \`palette\`: neon, dock, gold, acid, ember, orchid, tide, candy. |
+| \`theme.css\` | Extra CSS on every page (restyle anything, the "Made with Homie" footer included). |
+| \`partials/<name>.html\` | A piece of every page: \`head\`, \`header\`, \`footer\`, \`home\` (a band on Home), \`game\` (a band on every game's landing), \`game-<id>\` (on one game's), \`post\`. |
+| \`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).
+`;
+
 const GITIGNORE = `node_modules/
 # This computer's own state: the site's workers.dev address (it names the Cloudflare account, often after its owner).
 .studio/
@@ -192,6 +251,8 @@ site/.wrangler/
 *.log
 # Port checks: receipts and screenshots of each run (games/<id>/.port/check-*/).
 games/*/.port/
+# Screenshots from check and look runs.
+.checks/
 # Large media lives in this studio's storage (R2, after storage add) or is served by the site; the manifests beside it are committed.
 # Working files of the music and video skills (frames, captures, provider answers) stay on this computer.
 music/**/work/
@@ -237,7 +298,9 @@ export function studioFiles({ name, slug, homie }) {
     'music/manifest.json': '{ "v": 1, "items": [] }\n',
     'videos/README.md': 'Trailers, music videos and cutscenes, one folder each (`videos/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/videos/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
     'videos/manifest.json': '{ "v": 1, "items": [] }\n',
-    'posts/README.md': 'Markdown posts this studio publishes, one file each.\n',
+    'posts/README.md': POSTS_README,
+    'site/theme.json': themeFile(slug),
+    'site/README.md': SITE_README,
     'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1, and R2 once storage is added.
 // The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
 export { default, Table, Lobby } from '@homie-rocks/studio/worker';