@homie-rocks/studio 0.10.0 → 0.12.0

package/lib/statusline.mjs

@@ -0,0 +1,155 @@
+/**
+ * THE CLAUDE CODE STATUS LINE: one quiet line under the prompt with the studio's current build, from its progress
+ * feed (lib/progress.mjs), for example
+ *
+ *   ▶ Ember Run · Checks ▰▰▰▰▰▰▱▱▱▱ 62% · 3/5 checks · $0.40 of $2.00
+ *
+ * Optional, and only on the person's yes: `homie-studio statusline --install` writes the `statusLine` setting into
+ * this studio's `.claude/settings.local.json` (this person, this studio; Claude Code keeps that file out of git, and
+ * the studio's .gitignore does too). Claude Code runs the command after each message and, with `refreshInterval`,
+ * every few seconds while a long check runs; it sends the session as JSON on stdin (`workspace.current_dir`), and
+ * shows what the command prints. With no build running it shows only the studio's name, dimmed; a build that ended
+ * stays for a few minutes (passed, failed or stopped), then goes.
+ *
+ * Plugins cannot set a status line (a plugin's settings take only `agent` and `subagentStatusLine`), so this is a
+ * one-line project setting the person agrees to, never something the plugin switches on.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { currentFeedDoc, latestFeedFor, summarize } from './feed-summary.mjs';
+import { PACKAGE_ROOT, findStudio } from './studio.mjs';
+
+const ANSI = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', cyan: '\x1b[36m' };
+/** How long an ended build stays on the line. */
+export const RECENT_MS = 10 * 60_000;
+
+function bar(percent, width) {
+  const full = Math.round((percent / 100) * width);
+  return { done: '▰'.repeat(full), left: '▱'.repeat(Math.max(0, width - full)) };
+}
+
+/**
+ * The line for the studio at or above `dir`, or '' outside a studio. Parts are dropped from the end (spend, then
+ * checks) until the line fits in `columns`.
+ */
+export function statusLine({ dir = process.cwd(), now = Date.now(), columns = 100, color = true } = {}) {
+  const root = findStudio(dir);
+  if (!root) return '';
+  let name = 'Studio';
+  try { name = JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')).name || name; } catch { /* keep */ }
+  const s = summarize(currentFeedDoc(root) ?? latestFeedFor(root, null));
+  const paint = (code, text) => (color && text ? `${code}${text}${ANSI.reset}` : text);
+  const fit = (parts) => {
+    // parts: [[plain, painted], …]; keep the first two whole, then as many as fit.
+    const width = Math.max(20, columns - 2);
+    let keep = parts.length;
+    const len = (n) => parts.slice(0, n).reduce((a, [plain]) => a + plain.length, 0) + (n - 1) * 3;
+    while (keep > 1 && len(keep) > width) keep -= 1;
+    const out = parts.slice(0, keep).map(([, painted]) => painted).join(paint(ANSI.dim, ' · '));
+    const plain = parts.slice(0, keep).map(([p]) => p).join(' · ');
+    return plain.length > width ? `${plain.slice(0, width - 1)}…` : out;
+  };
+  const ended = s && s.state !== 'running' ? Date.parse(s.endedAt ?? s.updatedAt ?? 0) : null;
+  if (!s || (ended !== null && !(now - ended < RECENT_MS))) return fit([[`◇ ${name}`, paint(ANSI.dim, `◇ ${name}`)]]);
+
+  const title = s.title.length > 40 ? `${s.title.slice(0, 39)}…` : s.title;
+  if (s.state === 'passed') {
+    return fit([[`✓ ${title} done`, paint(ANSI.green, `✓ ${title} done`)], ...(s.preview ? [[s.preview, paint(ANSI.dim, s.preview)]] : [])]);
+  }
+  if (s.state === 'failed') {
+    const why = `failed${s.stage ? ` at ${s.stage.label}` : ''}${s.error ? `: ${s.error}` : ''}`;
+    return fit([[`✗ ${title}`, paint(ANSI.red, `✗ ${title}`)], [why, paint(ANSI.red, why)]]);
+  }
+  if (s.state === 'stopped') return fit([[`■ ${title} stopped`, paint(ANSI.yellow, `■ ${title} stopped`)]]);
+
+  const width = columns < 70 ? 6 : 10;
+  const b = bar(s.percent, width);
+  const stage = s.stopping ? 'stopping…' : (s.stage?.label ?? 'Starting');
+  const progress = `${stage} ${b.done}${b.left} ${s.percent}%`;
+  const parts = [
+    [`▶ ${title}`, paint(ANSI.bold, `▶ ${title}`)],
+    [progress, `${paint(ANSI.cyan, stage)} ${paint(ANSI.green, b.done)}${paint(ANSI.dim, b.left)} ${s.percent}%`],
+  ];
+  if (s.checks.total) {
+    const text = `${s.checks.pass}/${s.checks.total} checks${s.checks.fail ? `, ${s.checks.fail} failing` : ''}`;
+    parts.push([text, paint(s.checks.fail ? ANSI.red : ANSI.dim, text)]);
+  }
+  if (s.spend.text) parts.push([s.spend.text, paint(ANSI.dim, s.spend.text)]);
+  return fit(parts);
+}
+
+/* ------------------------------------------------------------------ the setting */
+
+const LOCAL = join('.claude', 'settings.local.json');
+const readJson = (path) => { if (!existsSync(path)) return {}; return JSON.parse(readFileSync(path, 'utf8')); };
+/** Our own status line: a command that runs this toolkit's statusline. */
+export const isOurs = (statusLine) => typeof statusLine?.command === 'string' && /homie-studio|@homie-rocks[\\/]studio/.test(statusLine.command) && /statusline/.test(statusLine.command);
+
+/**
+ * The command the setting runs: this studio's pinned toolkit, by an absolute path (forward slashes, for Windows
+ * too). Set in another folder (the one Claude Code was started in, above the studio), it names the studio too.
+ */
+export function statusLineCommand(root, { named = false } = {}) {
+  const pinned = join(root, 'node_modules', '@homie-rocks', 'studio', 'bin', 'statusline.mjs');
+  const script = existsSync(pinned) ? pinned : join(PACKAGE_ROOT, 'bin', 'statusline.mjs');
+  const slash = (p) => p.replace(/\\/g, '/');
+  return `node "${slash(script)}"${named ? ` --studio "${slash(root)}"` : ''}`;
+}
+
+/** Every settings file that may already hold a status line for this studio, most specific first. */
+function settingsFiles(project, env) {
+  const user = env.CLAUDE_CONFIG_DIR ? join(env.CLAUDE_CONFIG_DIR, 'settings.json') : join(env.HOME || homedir(), '.claude', 'settings.json');
+  return [
+    { where: 'this project, this person (.claude/settings.local.json)', path: join(project, LOCAL) },
+    { where: 'this project (.claude/settings.json)', path: join(project, '.claude', 'settings.json') },
+    { where: 'every project of this person (the user settings)', path: user },
+  ];
+}
+
+/**
+ * `homie-studio statusline --install`: the status line in this studio's .claude/settings.local.json. It never
+ * replaces a status line the person already has (anywhere Claude Code would read one) unless `replace`.
+ * `remove`: take ours out again.
+ */
+export function installStatusLine(root, { replace = false, remove = false, project = null, env = process.env } = {}) {
+  // Claude Code reads project settings from the folder it was started in. A studio made as a subfolder of that
+  // folder is named in the command, and the setting goes where Claude Code reads it (`--project <that folder>`).
+  const here = project ? resolve(project) : root;
+  if (!existsSync(here)) return { ok: false, command: 'statusline install', why: `no folder ${here}` };
+  const files = settingsFiles(here, env);
+  const local = files[0].path;
+  let mine;
+  try { mine = readJson(local); } catch { return { ok: false, command: 'statusline install', why: `${LOCAL} is not valid JSON; fix it by hand first (nothing was changed)` }; }
+  if (remove) {
+    if (!isOurs(mine.statusLine)) return { ok: true, command: 'statusline remove', removed: false, message: 'No Homie status line in this studio; nothing changed.' };
+    delete mine.statusLine;
+    writeFileSync(local, `${JSON.stringify(mine, null, 2)}\n`);
+    return { ok: true, command: 'statusline remove', removed: true, file: LOCAL, message: `Removed the Homie status line from ${LOCAL}.` };
+  }
+  const command = statusLineCommand(root, { named: here !== root });
+  if (isOurs(mine.statusLine) && mine.statusLine.command === command) return { ok: true, command: 'statusline install', already: true, file: LOCAL, statusLine: mine.statusLine, message: 'The status line is already on in this studio.' };
+  if (!replace) {
+    for (const f of files) {
+      let s = null;
+      try { s = readJson(f.path).statusLine ?? null; } catch { s = null; }
+      if (s && !isOurs(s)) {
+        return { ok: false, command: 'statusline install', exists: { where: f.where, command: String(s.command ?? s.type ?? '').slice(0, 120) }, why: `there is already a status line (${f.where}). Nothing was changed. With --replace, this studio shows the build's progress instead (only here; the other one stays everywhere else).` };
+      }
+    }
+  }
+  mine.statusLine = { type: 'command', command, padding: 0, refreshInterval: 5 };
+  mkdirSync(join(here, '.claude'), { recursive: true });
+  writeFileSync(local, `${JSON.stringify(mine, null, 2)}\n`);
+  // Claude Code keeps settings.local.json out of git when it makes the file; this one we made, so say it here too.
+  const ignore = join(here, '.gitignore');
+  let ignored = false;
+  if (existsSync(ignore) || here === root) try {
+    const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+    if (!/^\.claude\/settings\.local\.json\s*$/m.test(text)) { writeFileSync(ignore, `${text}${text && !text.endsWith('\n') ? '\n' : ''}# This person's own Claude Code settings for this studio (the status line).\n.claude/settings.local.json\n`); ignored = true; }
+  } catch { /* no .gitignore to keep */ }
+  return {
+    ok: true, command: 'statusline install', file: here === root ? LOCAL : join(here, LOCAL), statusLine: mine.statusLine, gitignore: ignored,
+    message: `The status line is on ${here === root ? `in this studio (${LOCAL})` : `for Claude Code started in ${here} (${LOCAL} there)`}: one line under the prompt with the current build's stage, a progress bar, its checks and what it spent. Claude Code reloads settings by itself; it shows from the next message. Turn it off with: npx --no-install homie-studio statusline --remove`,
+  };
+}

package/lib/studio.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed']);
+const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed', 'account']);
 
 export function findStudio(from = process.cwd()) {
   let at = resolve(from);

package/lib/template-history.json

@@ -175,6 +175,54 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.11.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",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.12.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)": "3a3d3bef7e8d1a50",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "63069b31c87a2aa2",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -194,6 +194,11 @@ it.
 - If the old host does not return, the relay elects someone else. That browser restores
   from the stored checkpoint (at most 30 s old) and from its own newest snapshot.
 
+**What a room is not.** A room forgets everything 60 s after its last player leaves (`forgetMs`). Progress that
+must last (a character, unlocks, days of play) is the player's, not the room's: it goes in cloud saves
+(`@homie-rocks/studio/saves`, `../saves/SAVES.md`). The host decides what happened and tells that player's own
+browser (an `ev` to its seat); only that browser changes and saves the player's progress.
+
 ## 5. Wire protocol v1
 
 - **Transport:** one WebSocket per game document, carrying JSON text frames

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.10.0",
+  "version": "0.12.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",
@@ -26,6 +26,10 @@
       "types": "./port/early.ts",
       "default": "./port/early.ts"
     },
+    "./saves": {
+      "types": "./saves/saves.ts",
+      "default": "./saves/saves.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },
@@ -35,6 +39,7 @@
     "netplay/",
     "port/",
     "worker/",
+    "saves/",
     "starters/",
     "media/",
     "site/",

package/port/index.ts

@@ -12,6 +12,7 @@
  *   createHud    a minimal clock / scores / results overlay
  *   BotBrain, seek, nearest, rubberBand
  *                bot scaffolds
+ *   createSaves  player accounts and cloud saves (a character that lasts days, on every device; saves/SAVES.md)
  * and everything from @homie-rocks/studio/netplay.
  */
 import './early';
@@ -27,3 +28,4 @@ export { exposePort, type PortProbeOptions, type View } from './probe';
 export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap, type RoomCkpt } from './room';
 export { createHud, type HudOptions } from './hud';
 export { BotBrain, seek, flee, wanderer, nearest, rubberBand, protectedNewcomer, type V2 } from './bots';
+export { createSaves, SAVES_VERSION, type Saves, type SavesOptions, type Player, type SaveEntry, type SetResult, type Memorial, type SavesStatus, type Conflict } from '../saves/saves';

package/port/keys.ts

@@ -75,6 +75,9 @@ export function createKeys(target: Window | HTMLElement = window): Keys {
   const edges = new Set<string>();
   const kd = (e: Event): void => {
     const k = e as KeyboardEvent;
+    // A key typed into the game's own text box (a hero's name, a chat line) is a word, never a move.
+    const el = k.target as HTMLElement | null;
+    if (el && (el.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(el.tagName ?? ''))) return;
     if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Space'].includes(k.code)) k.preventDefault();
     if (!held.has(k.code)) edges.add(k.code);
     held.add(k.code);

package/saves/SAVES.md

@@ -0,0 +1,236 @@
+# Players and cloud saves
+
+A studio's games can keep progress that lasts: a character that levels up for days, unlocks, a collection,
+lifetime stats, a hardcore mode with a hall of the fallen. It follows the player to every device they sign in
+on. Everything lives in the studio's **own** Worker and D1, on its own Cloudflare account: no third party, no
+tracker, no cookie from anyone else, and no other studio can see these players.
+
+## Rooms are rooms; saves are saves
+
+A public room is tonight's match. It keeps the live round (bodies, the clock, the world) and **forgets everything
+60 seconds after its last player leaves**. That is right for a round and wrong for a hero. So a persistent game
+keeps two kinds of state apart:
+
+| | The room (`@homie-rocks/studio/netplay`, `createRoom`) | The save (`@homie-rocks/studio/saves`) |
+| --- | --- | --- |
+| Lasts | while anyone is in the room (+60 s) | until the player deletes it |
+| Belongs to | the room; the host browser runs the rules | one player, one game |
+| Holds | positions, enemies, pickups, the round's score | name, level, gold, inventory, unlocks, settings |
+| Written | 20 times a second, in memory | when it changes, at most about once a second |
+
+The pattern (the `ember-vale` starter does exactly this):
+
+1. When the player arrives, **load** the hero from saves; until it loads, play as a level-1 body.
+2. The host decides what happened (who killed what) and tells **that player's own browser** (a netplay event
+   to its seat). Only the hero's own browser changes the hero and **saves** it.
+3. The room carries what the others need to see (my level, so my health bar is right), never the save itself.
+
+## Quick start
+
+game.json:
+
+```json
+{ "id": "my-rpg", "saves": true }
+```
+
+`src/main.ts`:
+
+```ts
+import { createSaves } from '@homie-rocks/studio/saves';   // also in '@homie-rocks/studio/port'
+
+interface Hero { name: string; level: number; xp: number; gold: number }
+const saves = createSaves({ game: 'my-rpg' });
+
+let hero = (await saves.get<Hero>('hero')) ?? { name: 'Wanderer', level: 1, xp: 0, gold: 0 };
+// … the hero gains something:
+hero.gold += 25;
+await saves.set('hero', hero);          // safe on this device at once; in the cloud when online
+
+// The player signed in on this device (or signed out): these are someone else's saves now.
+saves.on('player', async () => { hero = (await saves.get<Hero>('hero')) ?? newHero(); });
+```
+
+`"saves": true` turns on the play page's saves bridge for that game, and a "Your progress follows you" link on its
+landing. Pressing Play never needs an account.
+
+## Who the player is
+
+- **A guest** is made the first time a game saves something (never on Play). Their progress is kept on the server
+  for that browser (a cookie that is this site's alone) and in that browser's local copy.
+- **An account** is a guest (or anyone) who made a **passkey** on this site: Face ID, a fingerprint, a PIN or a
+  security key. No password, no email. A guest who makes an account keeps everything: it is the same player.
+- **Another device**: "Sign in" with the same passkey. The device's own passkey sync carries it (iCloud Keychain,
+  Google Password Manager, a password manager), or the browser offers a phone's QR code. The same saves are there.
+  A guest who signs in to an account they already have keeps the account's saves, and anything only the guest had
+  (keys, stats, memorials the account lacks) moves over.
+- **Recovery**: add another passkey on another device or a security key (`/account/`). A **recovery email** is
+  offered only when the studio has a mail sender: a Cloudflare Email Service binding named `PLAYER_MAIL`
+  (`"send_email": [{ "name": "PLAYER_MAIL" }]` in wrangler.jsonc; Email Sending needs the Workers paid plan and a
+  domain onboarded to it) and a `PLAYER_MAIL_FROM` variable on that domain. The address is confirmed by a
+  one-time link, and a recovery link lets the player make a new passkey; the old sessions end.
+- **Names** follow the same rules as a room's names: one line, at most 24 characters, whitespace collapsed, no
+  control, zero-width or bidi characters, at least one letter or digit, never a role ("admin", "moderator",
+  "owner", "official"…) or the studio's own name, and always drawn as text. A guest's name is a two-word handle
+  until they choose one. A signed-in player plays under their name in every room of the studio.
+- The game can show who is playing (`saves.player`: `name`, `guest`, `signedIn`, `owner`) and offer
+  `saves.signIn(reason)` from its own button: the play page shows its sign-in sheet over the game.
+- **The account page** is `/account/` on the studio's site: make an account, sign in, name, passkeys (add,
+  remove), recovery email, download everything, delete everything.
+
+Passkeys belong to the **host name** they were made on. Accounts made on a studio's workers.dev address do not
+sign in on its custom domain later: give a persistent game its final address before people make accounts. A
+Preview (a branch's own URL) has no database, so it has no accounts. In `npm run dev`, open
+`http://localhost:8787` (not `127.0.0.1`): a passkey needs a name, not an IP address.
+
+## The API
+
+`createSaves(options?)`:
+
+| Option | |
+| --- | --- |
+| `game` | The game's id (names the local-only store). On a studio site the shell's own game id is used: a game can only ever reach its own saves. |
+| `onConflict(c)` | Another device saved a key since this one's copy. Return the value to keep (merge `c.mine` and `c.theirs`), or `undefined` for the cloud's (the default). |
+| `local` | `true` forces local-only mode (tests, a game outside a studio). |
+
+| Call | |
+| --- | --- |
+| `ready` | Resolves with the player once their saves are loaded. |
+| `player` | `{ id, name, guest, owner, signedIn, local }`. |
+| `peek(key)` | The last known value, at once (for a render loop). |
+| `get(key)` | The value, or `null`. |
+| `set(key, value)` | `{ ok, synced, version }`. JSON only. Resolves when synced, or after about 4 s with `synced: false` (it is safe on this device and syncs later). |
+| `remove(key)` | Delete one key. |
+| `list()` | `[{ key, version, updatedAt, pending }]`. |
+| `wipe({ keep })` | Delete this game's saves except `keep` ("new game"). Stats and memorials stay. |
+| `stats.add({…})`, `stats.max({…})`, `stats.min({…})`, `stats.get()` | Lifetime numbers that only add up, or keep the highest or lowest: kills, gold earned, seconds played, best level, fastest run. A wipe or a death keeps them. |
+| `fall({ character, summary, wipe, keep })` | A memorial in the hall of the fallen; with `wipe: true`, this game's saves (except `keep`) are deleted in the same database transaction. |
+| `fallen({ limit, mine })` | The hall of the fallen: the newest memorials of this game (`{ character, player, summary, at }`, no player id). |
+| `rename(name)` | The player's display name on this studio. |
+| `signIn(reason?)` | Show the sign-in sheet. Call it from a button the player pressed. |
+| `flush()`, `status()` | Wait for the cloud; `{ mode, online, pending, lastSyncAt, lastError }`. |
+| `on('player' \| 'synced' \| 'status' \| 'conflict' \| 'error', fn)` | Returns an unsubscribe function. |
+
+Without a studio around it (the game opened as a plain file, in a Vite dev server, or a game.json without
+`"saves": true`) the same calls keep everything in that page's own storage (`mode: 'local'`).
+
+## Offline, versions and conflicts
+
+The play page keeps a copy of the player's saves in that browser and an **outbox** of changes. A `set` while
+offline is safe at once and syncs when the connection comes back (the `online` event, and retries that back off
+to 30 s), in order: memorials first, then saves, then stats. Leaving the page sends what is left.
+
+Every key has a **version** that goes up by one with each write. Every change names the version it was made from,
+so a stale copy never overwrites newer progress silently: if another device saved the key in between, the change
+is a **conflict**. By default the newer cloud copy wins and the game hears `conflict`; with `onConflict` the game
+decides (merge two inventories, keep the higher level). This is also what stops a hardcore hero from coming back:
+an old offline copy of a dead hero is a conflict with the wipe, and the wipe wins.
+
+A write is atomic **per key**, not across keys: keep one character in one key.
+
+## The hall of the fallen: a hardcore recipe
+
+```ts
+async function heroDied(cause: string) {
+  if (!hero.hardcore) { hero.gold = Math.floor(hero.gold * 0.9); await saves.set('hero', hero); return; }
+  const fallen = hero;
+  hero = null;
+  await saves.stats.add({ deaths: 1, heroesLost: 1 });      // lifetime: kept
+  await saves.fall({
+    character: fallen.name,
+    summary: { level: fallen.level, gold: fallen.gold, kills: fallen.kills, cause },
+    wipe: true,                                             // the hero's save goes, in the same step
+    keep: ['settings'],                                     // what survives (sound volume, key bindings)
+  });
+  showHall(await saves.fallen({ limit: 10 }));             // the names of the dead, newest first
+}
+```
+
+- The death and the wipe are one transaction on the server; on the device the wipe happens at once, even offline.
+- Memorials are public to the game's players: the character's name, the player's display name and the summary
+  (at most 2 KB). A player's own memorials go with their account if they delete it.
+- At most 20 memorials a day per player and game.
+
+## Limits
+
+| | |
+| --- | --- |
+| A value | 64 KiB of JSON (1 MiB with the studio's storage, R2: kept under a random key that `/media/` never serves) |
+| Keys | 64 per player per game; names of 1 to 64 letters, digits, `_ . : -` |
+| A game's saves | 256 KiB per player in D1 (and 4 MiB of large ones with storage) |
+| One write | 32 keys |
+| Stats | 64 names per player per game, finite numbers |
+| Passkeys | 10 per account |
+| Rates (per Worker instance, in memory) | 120 writes and 240 reads a minute per player; 60 sign-in or sign-up tries per address per 10 minutes; 60 new players per address an hour |
+| New players | 5,000 a day for the whole studio (the `PLAYER_LIMIT_DAILY` variable changes it) |
+
+On Cloudflare's free plan a D1 database has 100,000 row writes a day for everything (stats included). A save is
+one write; the play page coalesces a burst into one request per key. Save on change, not every frame.
+
+## What is stored, and privacy
+
+Migration `site/migrations/0004_players.sql` (deploy applies it; an older studio gets it from the next deploy):
+
+| Table | What | Never |
+| --- | --- | --- |
+| `players` | a random id (`pl_…`), the display name, guest and owner flags, when made and last seen (refreshed at most every six hours) | an email, a password, an IP address |
+| `player_passkeys` | each passkey's public key, algorithm, signature counter, a label ("iPhone"), when made and last used | a private key (it cannot leave the device) |
+| `player_sessions` | the SHA-256 of each session cookie and short-lived room pass | the cookie itself |
+| `player_challenges` | the SHA-256 of each one-time challenge or emailed link, for minutes | |
+| `player_emails` | a recovery email, only if the player added one | |
+| `saves`, `player_stats`, `memorials` | what the game saved | anything the game did not |
+
+- **The player** sees all of it at `/account/`, downloads it as one JSON file (`/api/player/export`), and deletes
+  it all (`/api/player/delete`): their passkeys, sessions, saves, stats, memorials and email, and their large
+  saves in R2. The page tells them to remove the passkey from their device too, and tells the device itself where
+  the browser supports it.
+- **The owner** sees counts (`homie-studio players`, the private stats page, `studio_stats`) and, through the back
+  office, names and when players were last seen: never a passkey, a session or an email.
+- **No IP address is stored.** Rate limits count in memory and forget. No third-party script, beacon or cookie is
+  used; the passkey ceremony is between the player's device and this site.
+- **Guests** nobody has played for 180 days are deleted with everything they kept.
+- The session cookie is `studio_player`: HttpOnly, Secure, SameSite=Lax, this site only. The game, in its sandboxed
+  frame, never sees it: the play page makes every saves call for it, for that game only.
+
+## For the studio's back office
+
+Server-side, from the Worker (`import { players } from '@homie-rocks/studio/worker'`):
+
+```js
+await players.count(env);              // { accounts, guests, owners, new7d, active1d, active7d }
+await players.list(env, { limit, cursor, q, guests });   // { players: [{ id, name, guest, owner, createdAt, seenAt, passkeys }], next }
+await players.get(env, id);            // the same, plus saves per game (keys, bytes, last write), stats, memorials
+await players.of(request, env);        // the request's signed-in player, or null
+await players.isOwner(request, env);   // the request is the owner's own account
+await players.passFor(env, id, { game, minutes });       // a short-lived pass naming a player ('pp_…')
+await players.readPass(env, pass);     // { id, name, guest, owner, game } or null
+await players.rename(env, id, name);   // moderation: the same name rules
+await players.remove(env, id);         // everything of that player, as their own Delete does
+```
+
+**The owner's own account**: the owner plays with an ordinary passkey account on their site, and marks it once:
+`npx --no-install homie-studio players owner` (it uses the studio's own Cloudflare login, like `stats link`) gives
+a one-time link; opened where they are signed in, one press marks that account as the owner's. `players owner
+--revoke` unmarks every account.
+
+**In a room**: the play page can ask `POST /api/player/pass { "game": "<id>" }` for a 10-minute pass; a room that
+needs to know who a socket is (to recognise the owner, or to kick by account) takes it on the socket URL and calls
+`players.readPass` before handing the socket to the Table.
+
+## HTTP
+
+Same origin only (a POST must come from this site's own pages, as JSON). For reference; games use the SDK.
+
+| | |
+| --- | --- |
+| `GET /api/player/me` | the signed-in player, the features (`accounts`, `email`), the limits |
+| `POST /api/player/signup/options`, `POST /api/player/signup` | make an account, or add a passkey to this browser's guest or account |
+| `POST /api/player/signin/options`, `POST /api/player/signin` | sign in with a passkey (discoverable: no name typed) |
+| `POST /api/player/signout`, `POST /api/player/name`, `GET /api/player/passkeys`, `POST /api/player/passkeys/remove` | |
+| `GET /api/player/export`, `POST /api/player/delete` (`{ "confirm": "delete" }`) | everything, and nothing |
+| `GET /api/player/saves/<game>[?values=1]`, `GET /api/player/saves/<game>/<key>` | read |
+| `POST /api/player/saves/<game>` `{ set: [{ key, value, base }], del: [{ key, base }] }` | write (a guest is made on the first) |
+| `POST /api/player/saves/<game>/wipe` `{ keep }` | |
+| `GET`/`POST /api/player/stats/<game>` `{ add, max, min }` | lifetime stats |
+| `GET /api/player/fallen/<game>[?mine=1]`, `POST /api/player/fallen/<game>` `{ character, summary, wipe, keep }` | the hall of the fallen |
+| `POST /api/player/pass`, `POST /api/player/owner` | a room pass; the owner's one-time mark |
+| `POST /api/player/email`, `/email/verify`, `/email/remove`, `/recover`, `/recover/options` | the recovery email, with a mail sender |