@homie-rocks/studio 0.5.0 → 0.7.0

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/media.mjs

@@ -111,7 +111,7 @@ export function buildMedia(root, dist, { r2 = false, log = () => {} } = {}) {
 }
 
 /** `homie-studio media put`: record an uploaded file's R2 key on the entry that names it (or a bare entry). */
-export function recordUpload(root, rel, key, bytes, siteUrl) {
+export function recordUpload(root, rel, key, bytes) {
   const kind = rel.startsWith('videos/') ? 'videos' : 'music';
   const m = readManifest(root, kind);
   let hit = false;
@@ -120,7 +120,7 @@ export function recordUpload(root, rel, key, bytes, siteUrl) {
       if (f.path === rel) { f.key = key; f.bytes = bytes; hit = true; }
     }
   }
-  if (!hit) m.items = [...m.items.filter((i) => i.key !== key), { key, file: rel, bytes, url: siteUrl ? `${siteUrl}/media/${key}` : null, at: new Date().toISOString() }];
+  if (!hit) m.items = [...m.items.filter((i) => i.key !== key), { key, file: rel, bytes, url: `/media/${key.split('/').map(encodeURIComponent).join('/')}`, at: new Date().toISOString() }];
   writeManifest(root, kind, m);
   return { kind, manifest: relative(root, manifestPath(root, kind)), entry: hit };
 }

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
@@ -19,10 +19,12 @@
  * lists every file it writes, so the person sees exactly what changed.
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 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';
@@ -72,9 +74,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/\` | Markdown the studio publishes. |
-| \`site/\` | The studio's Worker (\`src/worker.mjs\`), D1 migrations, \`wrangler.jsonc\`. |
-| \`studio.json\` | The studio's name, slug and Cloudflare resource names. |
+| \`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. |
 
 ## Commands (all through the pinned CLI in node_modules)
@@ -107,6 +109,31 @@ studio's pinned copy, never a registry lookup of the bare name.
   is a separate step the person agrees to; nothing else needs it.
 - \`npx --no-install homie-studio publish\` — list this studio's games in the homie.rocks directory
   (or call the Homie MCP tool \`studio_publish\`).
+- \`npx --no-install homie-studio stats\` — the studio's own numbers, for its owner: visits, Play presses,
+  rooms, the most people playing at once, rounds, songs played, videos watched, and where visitors came
+  from (homie.rocks, other studios, search, the web). \`stats link\` gives the owner a one-time link to the
+  private page \`/_studio/stats\` in their own browser; \`stats key\` a short read key for the Homie MCP tool
+  \`studio_stats\` (never paste a key anywhere else). \`stats share on\` tells the directory two numbers
+  (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
 
@@ -125,6 +152,10 @@ studio's pinned copy, never a registry lookup of the bare name.
 - Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
   keychain. Never write a key, token or password into this repository.
 - Never touch a Cloudflare resource this studio did not create (\`studio.json\` says which).
+- The site's workers.dev address names the Cloudflare account (often after its owner): \`deploy\` keeps it in
+  \`.studio/local.json\`, which git ignores. Never copy it into a committed file. A custom domain goes in
+  studio.json as \`cloudflare.domain\`.
+- A game's room size is its netplay manifest's \`maxPlayers\` (game.json \`netplay\`, or netplay.json), up to 32.
 - Nothing in this studio needs \`~/.homie\` or a Homie box.
 
 ## Beta
@@ -169,7 +200,49 @@ 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/
 site/dist/
 site/.wrangler/
 .wrangler/
@@ -178,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/
@@ -197,7 +272,12 @@ export function studioFiles({ name, slug, homie }) {
     name, slug,
     homie: { studio: STUDIO_VERSION, directory: homie },
     // r2 stays null until `homie-studio storage add`: a new studio deploys with no R2 at all.
-    cloudflare: { worker, d1: `${slug}-db`, r2: null, accountId: null, url: null, created: [] },
+    // `domain`: the studio's own domain once it has one (e.g. "night-owls.example"). The workers.dev address never
+    // goes here: it names the Cloudflare account, so deploy keeps it in .studio/local.json (git-ignored).
+    cloudflare: { worker, d1: `${slug}-db`, r2: null, accountId: null, domain: null, created: [] },
+    // The site counts visits, plays, rooms, rounds and songs for the owner only (`homie-studio stats`); `share`
+    // also tells the homie.rocks directory "played this week" (two numbers) for the hub.
+    stats: { share: false },
   };
   const pkg = {
     name: `${slug}-studio`,
@@ -218,17 +298,44 @@ 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';
 `,
     '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 }),
     '.claude/skills/.gitkeep': '',
   };
 }
 
+/**
+ * A studio made before 0.6.0 has no stats migration: add it (the template owns site/migrations/), so the next
+ * `d1 migrations apply` makes the counters. Returns the file it wrote, or null when it was there.
+ */
+export function ensureStatsMigration(root) {
+  const file = join(root, 'site', 'migrations', STATS_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, STATS_MIGRATION);
+  return `site/migrations/${STATS_MIGRATION_FILE}`;
+}
+
+/**
+ * A studio made before 0.6.0 committed nothing under .studio/ yet: make sure git leaves it out before the first
+ * deploy writes the workers.dev address there. Returns true when it added the line.
+ */
+export function ensureLocalIgnored(root) {
+  const file = join(root, '.gitignore');
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (/^\/?\.studio\/?$/m.test(text)) return false;
+  writeFileSync(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}# This computer's own state: the site's workers.dev address (it names the Cloudflare account).\n.studio/\n`);
+  return true;
+}
+
 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; }
 }