@homie-rocks/studio 0.11.0 → 0.12.0

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 |

package/saves/saves.ts

@@ -0,0 +1,326 @@
+/*
+ * saves.ts — cloud saves for a game on a Homie studio (@homie-rocks/studio/saves). SAVES.md beside it is the guide.
+ * =============================================================================
+ *
+ *   import { createSaves } from '@homie-rocks/studio/saves';
+ *   const saves = createSaves({ game: 'my-game' });
+ *   const hero = (await saves.get<Hero>('hero')) ?? newHero();
+ *   await saves.set('hero', hero);                       // safe in this browser at once, in the cloud when online
+ *   saves.stats.add({ kills: 1, seconds: 30 });          // lifetime numbers that survive a wipe
+ *   await saves.fall({ character: hero.name, summary: { level: hero.level }, wipe: true });  // hardcore death
+ *   saves.on('player', () => reload());                  // the player signed in on this device: their saves changed
+ *
+ * WHERE IT KEEPS THINGS. A game on a studio site runs in a sandboxed frame that can keep nothing of its own. The
+ * play shell around it (on the studio's own origin) does it: a local copy in that browser, an outbox that syncs to
+ * the studio's Worker and D1, and the player's passkey sign-in. This file only talks to the shell (postMessage),
+ * so the game never sees a session or a cookie, and can only reach its OWN game's saves. Without a shell (the
+ * game opened as a plain file, a Vite dev server, a game.json with no "saves": true) it keeps everything in this
+ * page's localStorage instead (mode 'local'), so the same code runs everywhere.
+ *
+ * ROOMS ARE NOT SAVES. A room forgets everything 60 s after its last player leaves. A character that must last
+ * days lives in saves: load it when the player arrives, save it when it changes, and let the room carry only the
+ * live round.
+ *
+ * It has no imports and uses only erasable TypeScript: vendor it into a game like netplay.ts, or import it.
+ * =============================================================================
+ */
+
+export const SAVES_VERSION = 1;
+
+export interface Player {
+  /** `pl_…` on a studio site (null before this browser saved anything, and in local mode). */
+  id: string | null;
+  name: string;
+  /** No passkey yet: progress is kept in this browser only until the player makes an account. */
+  guest: boolean;
+  /** The studio owner's own account (marked once with `homie-studio players owner`). Show, never trust. */
+  owner: boolean;
+  signedIn: boolean;
+  /** No studio shell around the game: everything is in this page's localStorage. */
+  local: boolean;
+}
+
+export interface SaveEntry { key: string; version: number; updatedAt: number | null; pending?: boolean }
+export interface SetResult { ok: boolean; synced: boolean; version: number; error?: string; message?: string }
+export interface Memorial { character: string; player: string; summary: Record<string, unknown>; at: number }
+export interface SavesStatus { mode: 'cloud' | 'local'; online: boolean; pending: number; lastSyncAt: number | null; lastError: string | null }
+export interface Conflict<T = unknown> { key: string; mine: T | null; theirs: T | null; theirsVersion: number }
+export type SavesEvent = 'player' | 'synced' | 'conflict' | 'status' | 'error';
+
+export interface SavesOptions {
+  /** The game's id (its folder): names the local-mode store. On a studio site the shell's own game id is used. */
+  game?: string;
+  /**
+   * Another device saved a key since this one's copy (this browser was offline, or two devices played at once).
+   * Return the value to keep (merge them, or return `mine`), or `undefined` for the cloud's (the default: a stale
+   * offline copy never overwrites newer progress, so a hardcore character cannot come back from the dead).
+   */
+  onConflict?: (c: Conflict) => unknown | Promise<unknown>;
+  /** Tests and custom shells: where messages go (default: the parent frame) and the shell's answer window. */
+  target?: { postMessage: (m: unknown, origin: string) => void } | null;
+  /** Force local mode (true) or cloud mode (false). Default: cloud when the shell said so (HOMIE_NET.saves). */
+  local?: boolean;
+  /** Local mode's storage (default: localStorage when usable, else memory). */
+  storage?: { getItem(k: string): string | null; setItem(k: string, v: string): void } | null;
+}
+
+export interface Saves {
+  /** Resolves once the player and their saves are loaded (cloud mode: from the shell's copy, then the cloud). */
+  readonly ready: Promise<Player>;
+  readonly player: Player;
+  readonly mode: 'cloud' | 'local';
+  /** The last known value of a key, at once (for a render loop). `get` is the same, as a promise. */
+  peek<T = unknown>(key: string): T | null;
+  get<T = unknown>(key: string): Promise<T | null>;
+  /** Keep a value (JSON, 64 KiB; 1 MiB with the studio's storage). Resolves when synced, or after ~4 s saved locally. */
+  set<T = unknown>(key: string, value: T): Promise<SetResult>;
+  remove(key: string): Promise<SetResult>;
+  list(): Promise<SaveEntry[]>;
+  /** Delete this game's saves (except `keep`): "new game". Lifetime stats and memorials stay. */
+  wipe(opts?: { keep?: string[] }): Promise<{ ok: boolean; synced: boolean }>;
+  readonly stats: {
+    get(): Promise<Record<string, number>>;
+    /** Add to counters: { kills: 1, gold: 25, seconds: 30 }. */
+    add(values: Record<string, number>): Promise<{ ok: boolean }>;
+    /** Keep the highest: { level: 12 }. */
+    max(values: Record<string, number>): Promise<{ ok: boolean }>;
+    /** Keep the lowest: { fastestRun: 312 }. */
+    min(values: Record<string, number>): Promise<{ ok: boolean }>;
+  };
+  /**
+   * A character died for good (hardcore): a memorial in the hall of the fallen (its name, your display name, a
+   * small summary), and with `wipe: true` this game's saves are deleted in the same step (except `keep`).
+   */
+  fall(m: { character: string; summary?: Record<string, unknown>; wipe?: boolean; keep?: string[] }): Promise<{ ok: boolean; synced: boolean; memorial: Memorial | null }>;
+  /** The hall of the fallen: the newest memorials of this game (everyone's), or `mine: true`. */
+  fallen(opts?: { limit?: number; mine?: boolean }): Promise<Memorial[]>;
+  /** Change the player's display name on this studio (the same rules as the account page). */
+  rename(name: string): Promise<{ ok: boolean; name?: string; message?: string }>;
+  /** Ask the shell to show its sign-in sheet (a passkey). Call it from a button the player pressed. */
+  signIn(reason?: string): void;
+  /** Wait until every change is in the cloud (or the network said no). */
+  flush(): Promise<SavesStatus>;
+  status(): SavesStatus;
+  on(ev: 'player', fn: (p: Player) => void): () => void;
+  on(ev: 'conflict', fn: (c: Conflict & { kept: 'theirs' | 'game' }) => void): () => void;
+  on(ev: 'synced' | 'status', fn: (s: SavesStatus) => void): () => void;
+  on(ev: 'error', fn: (e: { key?: string; error: string; message?: string }) => void): () => void;
+}
+
+const KEY = /^[A-Za-z0-9_.:-]{1,64}$/;
+type Msg = Record<string, unknown> & { t?: string; q?: number; ev?: string; ok?: boolean };
+
+export function createSaves(opts: SavesOptions = {}): Saves {
+  const g = globalThis as unknown as {
+    HOMIE_NET?: { saves?: boolean }; parent?: unknown; addEventListener?: typeof addEventListener; localStorage?: Storage;
+  };
+  const cloud = opts.local === undefined ? Boolean(g.HOMIE_NET?.saves) : !opts.local;
+  const game = String(opts.game ?? 'game').replace(/[^a-z0-9-]/g, '').slice(0, 40) || 'game';
+  const listeners = new Map<string, Set<(x: unknown) => void>>();
+  const emit = (ev: string, x: unknown): void => { for (const fn of listeners.get(ev) ?? []) { try { fn(x); } catch { /* the game's */ } } };
+  let player: Player = { id: null, name: 'Guest', guest: true, owner: false, signedIn: false, local: !cloud };
+  let mirror: Record<string, unknown> = {};
+  let st: SavesStatus = { mode: cloud ? 'cloud' : 'local', online: true, pending: 0, lastSyncAt: null, lastError: null };
+
+  /* ------------------------------------------------------------ cloud mode: the shell */
+  const target = opts.target !== undefined ? opts.target : (g.parent && g.parent !== (globalThis as unknown) ? g.parent as { postMessage: (m: unknown, o: string) => void } : null);
+  let seq = 0;
+  const waiting = new Map<number, (m: Msg) => void>();
+  const ask = (op: string, args: Record<string, unknown> = {}, timeoutMs = 20_000): Promise<Msg> => new Promise((resolve) => {
+    if (!target) { resolve({ ok: false, error: 'no-shell', message: 'no studio shell around this game' }); return; }
+    const q = ++seq;
+    const timer = setTimeout(() => { waiting.delete(q); resolve({ ok: false, error: 'timeout', message: 'the play shell did not answer' }); }, timeoutMs);
+    waiting.set(q, (m) => { clearTimeout(timer); resolve(m); });
+    try { target.postMessage({ t: 'homie-save', q, op, ...args }, '*'); } catch { clearTimeout(timer); waiting.delete(q); resolve({ ok: false, error: 'no-shell' }); }
+  });
+  const asPlayer = (p: unknown): Player => {
+    const o = (p ?? {}) as Partial<Player>;
+    return { id: typeof o.id === 'string' ? o.id : null, name: typeof o.name === 'string' ? o.name : 'Guest', guest: o.guest !== false, owner: o.owner === true, signedIn: o.guest === false, local: false };
+  };
+
+  if (cloud && g.addEventListener) {
+    g.addEventListener('message', (ev: MessageEvent) => {
+      const m = ev.data as Msg;
+      if (!m || typeof m !== 'object' || m.t !== 'homie-save') return;
+      if (target && ev.source && ev.source !== (target as unknown)) return;
+      if (typeof m.q === 'number' && waiting.has(m.q)) { const f = waiting.get(m.q)!; waiting.delete(m.q); f(m); return; }
+      if (m.ev === 'player') {
+        player = asPlayer(m.player);
+        if (m.cache && typeof m.cache === 'object') mirror = { ...(m.cache as Record<string, unknown>) };
+        emit('player', player);
+      } else if (m.ev === 'status' || m.ev === 'synced') {
+        if (m.status) st = { ...(m.status as SavesStatus) };
+        emit(m.ev, st);
+      } else if (m.ev === 'error') emit('error', { key: m.key, error: m.error, message: m.message });
+      else if (m.ev === 'conflict') {
+        const c = { key: String(m.key), mine: m.mine ?? null, theirs: m.theirs ?? null, theirsVersion: Number(m.theirsVersion) || 0 };
+        if (typeof m.ask === 'number' && opts.onConflict) {
+          Promise.resolve().then(() => opts.onConflict!(c)).then((keep) => {
+            target?.postMessage({ t: 'homie-save', op: 'resolve', ask: m.ask, ...(keep === undefined ? { keep: 'theirs' } : { keep: 'value', value: keep }) }, '*');
+          }, () => target?.postMessage({ t: 'homie-save', op: 'resolve', ask: m.ask, keep: 'theirs' }, '*'));
+          return;
+        }
+        if (m.kept === 'theirs') { if (c.theirs === null) delete mirror[c.key]; else mirror[c.key] = c.theirs; }
+        emit('conflict', { ...c, kept: m.kept === 'game' ? 'game' : 'theirs' });
+      }
+    });
+  }
+
+  /* ------------------------------------------------------------ local mode: this page's storage */
+  const memory = new Map<string, string>();
+  const store = opts.storage !== undefined && opts.storage !== null ? opts.storage : (() => {
+    try { const ls = g.localStorage; if (ls) { ls.setItem('homie-saves.test', '1'); return ls; } } catch { /* sandboxed */ }
+    return { getItem: (k: string) => memory.get(k) ?? null, setItem: (k: string, v: string) => { memory.set(k, v); } };
+  })();
+  interface LocalDb { saves: Record<string, { v: unknown; ver: number; at: number }>; stats: Record<string, number>; fallen: Memorial[] }
+  const LOCAL = `homie-saves.local.${game}`;
+  const readLocal = (): LocalDb => { try { const j = JSON.parse(store.getItem(LOCAL) ?? 'null'); if (j && j.saves) return j; } catch { /* fresh */ } return { saves: {}, stats: {}, fallen: [] }; };
+  const writeLocal = (db: LocalDb): void => { try { store.setItem(LOCAL, JSON.stringify(db)); } catch { /* full */ } };
+
+  /* ------------------------------------------------------------ ready */
+  const ready: Promise<Player> = (async () => {
+    if (!cloud || !target) {
+      player = { id: null, name: 'You', guest: true, owner: false, signedIn: false, local: true };
+      st = { ...st, mode: 'local' };
+      const db = readLocal();
+      mirror = Object.fromEntries(Object.entries(db.saves).map(([k, e]) => [k, e.v]));
+      return player;
+    }
+    const r = await ask('hello', { v: SAVES_VERSION, resolver: Boolean(opts.onConflict) }, 15_000);
+    if (r.ok) {
+      player = asPlayer(r.player);
+      mirror = { ...((r.cache as Record<string, unknown>) ?? {}) };
+      if (r.status) st = { ...(r.status as SavesStatus) };
+    } else st = { ...st, online: false, lastError: String(r.message ?? r.error ?? 'no shell') };
+    return player;
+  })();
+
+  const checkKey = (key: string): string | null => (KEY.test(String(key)) ? null : 'a save key is 1 to 64 letters, digits, _ . : or -');
+
+  const api: Saves = {
+    ready,
+    get player() { return player; },
+    get mode() { return cloud && target ? 'cloud' : 'local'; },
+    peek<T>(key: string): T | null { return (key in mirror ? mirror[key] : null) as T | null; },
+    async get<T>(key: string): Promise<T | null> {
+      await ready;
+      if (checkKey(key)) return null;
+      if (api.mode === 'local') return (readLocal().saves[key]?.v ?? null) as T | null;
+      const r = await ask('get', { key });
+      if (r.ok) { if (r.value === null || r.value === undefined) delete mirror[key]; else mirror[key] = r.value; }
+      return (r.ok ? r.value ?? null : mirror[key] ?? null) as T | null;
+    },
+    async set<T>(key: string, value: T): Promise<SetResult> {
+      await ready;
+      const bad = checkKey(key);
+      if (bad) return { ok: false, synced: false, version: 0, error: 'key', message: bad };
+      if (value === undefined) return { ok: false, synced: false, version: 0, error: 'value', message: 'a save needs a value; use remove() to delete a key' };
+      let copy: unknown;
+      try { copy = JSON.parse(JSON.stringify(value)); } catch { return { ok: false, synced: false, version: 0, error: 'value', message: 'a save is JSON' }; }
+      mirror[key] = copy;
+      if (api.mode === 'local') {
+        const db = readLocal();
+        const ver = (db.saves[key]?.ver ?? 0) + 1;
+        db.saves[key] = { v: copy, ver, at: Date.now() };
+        writeLocal(db);
+        return { ok: true, synced: true, version: ver };
+      }
+      const r = await ask('set', { key, value: copy });
+      return { ok: Boolean(r.ok), synced: Boolean(r.synced), version: Number(r.version) || 0, ...(r.ok ? {} : { error: String(r.error), message: String(r.message ?? '') }) };
+    },
+    async remove(key: string): Promise<SetResult> {
+      await ready;
+      const bad = checkKey(key);
+      if (bad) return { ok: false, synced: false, version: 0, error: 'key', message: bad };
+      delete mirror[key];
+      if (api.mode === 'local') { const db = readLocal(); delete db.saves[key]; writeLocal(db); return { ok: true, synced: true, version: 0 }; }
+      const r = await ask('del', { key });
+      return { ok: Boolean(r.ok), synced: Boolean(r.synced), version: 0, ...(r.ok ? {} : { error: String(r.error), message: String(r.message ?? '') }) };
+    },
+    async list(): Promise<SaveEntry[]> {
+      await ready;
+      if (api.mode === 'local') return Object.entries(readLocal().saves).sort(([a], [b]) => a.localeCompare(b)).map(([key, e]) => ({ key, version: e.ver, updatedAt: e.at }));
+      const r = await ask('list');
+      return Array.isArray(r.keys) ? r.keys as SaveEntry[] : [];
+    },
+    async wipe({ keep = [] } = {}) {
+      await ready;
+      for (const k of Object.keys(mirror)) if (!keep.includes(k)) delete mirror[k];
+      if (api.mode === 'local') { const db = readLocal(); for (const k of Object.keys(db.saves)) if (!keep.includes(k)) delete db.saves[k]; writeLocal(db); return { ok: true, synced: true }; }
+      const r = await ask('wipe', { keep });
+      return { ok: Boolean(r.ok), synced: Boolean(r.synced) };
+    },
+    stats: {
+      async get() {
+        await ready;
+        if (api.mode === 'local') return { ...readLocal().stats };
+        const r = await ask('stats', { kind: 'get' });
+        return (r.stats as Record<string, number>) ?? {};
+      },
+      add: (values) => bump('add', values),
+      max: (values) => bump('max', values),
+      min: (values) => bump('min', values),
+    },
+    async fall({ character, summary = {}, wipe = false, keep = [] }) {
+      await ready;
+      if (wipe) for (const k of Object.keys(mirror)) if (!keep.includes(k)) delete mirror[k];
+      if (api.mode === 'local') {
+        const db = readLocal();
+        const memorial: Memorial = { character: String(character).slice(0, 32), player: player.name, summary, at: Date.now() };
+        db.fallen.unshift(memorial);
+        db.fallen = db.fallen.slice(0, 50);
+        if (wipe) for (const k of Object.keys(db.saves)) if (!keep.includes(k)) delete db.saves[k];
+        writeLocal(db);
+        return { ok: true, synced: true, memorial };
+      }
+      const r = await ask('fall', { character, summary, wipe, keep });
+      return { ok: Boolean(r.ok), synced: Boolean(r.synced), memorial: (r.memorial as Memorial) ?? null };
+    },
+    async fallen({ limit = 20, mine = false } = {}) {
+      await ready;
+      if (api.mode === 'local') return readLocal().fallen.slice(0, limit);
+      const r = await ask('fallen', { limit, mine });
+      return Array.isArray(r.fallen) ? r.fallen as Memorial[] : [];
+    },
+    async rename(name: string) {
+      await ready;
+      if (api.mode === 'local') { player = { ...player, name: String(name).slice(0, 24) }; emit('player', player); return { ok: true, name: player.name }; }
+      const r = await ask('rename', { name });
+      return { ok: Boolean(r.ok), ...(r.name ? { name: String(r.name) } : {}), ...(r.message ? { message: String(r.message) } : {}) };
+    },
+    signIn(reason?: string) { if (api.mode === 'cloud') void ask('signin', reason ? { reason } : {}); },
+    async flush() {
+      await ready;
+      if (api.mode === 'local') return st;
+      const r = await ask('flush', {}, 30_000);
+      if (r.status) st = { ...(r.status as SavesStatus) };
+      return st;
+    },
+    status() { return st; },
+    on(ev: SavesEvent, fn: (x: never) => void) {
+      const set = listeners.get(ev) ?? new Set();
+      set.add(fn as (x: unknown) => void);
+      listeners.set(ev, set);
+      return () => { set.delete(fn as (x: unknown) => void); };
+    },
+  } as Saves;
+
+  async function bump(kind: 'add' | 'max' | 'min', values: Record<string, number>): Promise<{ ok: boolean }> {
+    await ready;
+    if (api.mode === 'local') {
+      const db = readLocal();
+      for (const [k, raw] of Object.entries(values ?? {})) {
+        const n = Number(raw);
+        if (!Number.isFinite(n)) continue;
+        const cur = db.stats[k];
+        db.stats[k] = cur === undefined ? n : kind === 'add' ? cur + n : kind === 'max' ? Math.max(cur, n) : Math.min(cur, n);
+      }
+      writeLocal(db);
+      return { ok: true };
+    }
+    const r = await ask('stats', { kind, values });
+    return { ok: Boolean(r.ok) };
+  }
+
+  return api;
+}

package/site/SITE.md

@@ -156,6 +156,15 @@ The game runs in a sandboxed frame with an opaque origin, which is why its allow
 (`fullscreen *; autoplay *; gamepad *`): Safari refuses a bare `gamepad` there (`getGamepads()` throws a
 SecurityError), so a controller would not work.
 
+## Player accounts: `/account/`
+
+A studio whose games keep saves (game.json `"saves": true`, [../saves/SAVES.md](../saves/SAVES.md)) has a player
+account page at `/account/`, in the studio's look: make an account with a passkey, sign in on another device,
+choose a name, add or remove passkeys, a recovery email (only with a mail sender), download everything, delete
+everything. The play page of such a game carries the saves bridge and a "who is playing" row in its room sheet,
+and shows a passkey sheet over the game when the game asks (`saves.signIn()`); its landing links the account page.
+`/account/` belongs to the site: `site/pages/account/` and `site/public/account/` are refused.
+
 ## The arcade knock
 
 A game made with Homie's arcade controls asks its page's origin for a Homie box (`GET /__homie/call`), and a score

package/starters/ember-vale/game.json

@@ -0,0 +1,20 @@
+{
+  "id": "ember-vale",
+  "name": "Ember Vale",
+  "blurb": "A hero who lasts for days. Hunt slimes with whoever is here tonight; your level, gold and name follow you to every device. Go hardcore and a death is forever.",
+  "players": { "min": 1, "max": 8 },
+  "roundSeconds": 90,
+  "entry": "src/main.ts",
+  "netplay": { "v": 1, "public": true, "movement": "owner" },
+  "saves": true,
+  "landing": {
+    "pitch": "Your hero keeps every level. The night does not.",
+    "howToPlay": [
+      "Make a hero, or pick up the one you left.",
+      "Strike slimes for experience and gold; the King Slime pays best.",
+      "Every night ends with a ranking; your hero keeps what it earned.",
+      "Hardcore: one life. Fall and you join the Hall of the Fallen."
+    ],
+    "controls": { "phone": "Drag on the left to move, STRIKE on the right.", "computer": "WASD or arrows to move, Space to strike." }
+  }
+}

package/starters/ember-vale/index.html

@@ -0,0 +1,46 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, user-scalable=no">
+<title>Ember Vale</title>
+<link rel="icon" href="data:,">
+<style>
+  html, body { margin: 0; height: 100%; background: #0b0f0a; overflow: hidden; overscroll-behavior: none; -webkit-user-select: none; user-select: none; font: 15px/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; color: #f3ead2; }
+  canvas { position: fixed; inset: 0; width: 100%; height: 100%; display: block; touch-action: none; }
+  .ui { position: fixed; z-index: 3; }
+  .pill { left: calc(12px + env(safe-area-inset-left)); top: calc(86px + env(safe-area-inset-top)); display: flex; gap: 6px; }
+  .pill button { min-height: 32px; padding: 0 11px; border-radius: 999px; border: 1px solid rgba(243,234,210,.25); background: rgba(10,14,9,.6); color: inherit; font: 600 12.5px/1 inherit; font-family: inherit; cursor: pointer; backdrop-filter: blur(4px); }
+  .panel { left: 50%; top: 50%; transform: translate(-50%, -50%); box-sizing: border-box; width: min(360px, calc(100vw - 24px)); padding: 18px; border-radius: 16px; background: rgba(14,19,12,.94); border: 1px solid rgba(243,234,210,.2); box-shadow: 0 20px 60px rgba(0,0,0,.55); -webkit-user-select: text; user-select: text; }
+  .panel h2 { margin: 0 0 6px; font-size: 20px; color: #ffcf6e; }
+  .panel p { margin: 0 0 12px; color: #c9c0a6; }
+  .panel input[type=text] { box-sizing: border-box; width: 100%; min-height: 44px; padding: 0 12px; border-radius: 10px; border: 1px solid rgba(243,234,210,.25); background: #070a06; color: #fff; font: 16px inherit; font-family: inherit; }
+  .panel label.hc { display: flex; gap: 8px; align-items: center; margin: 12px 0; color: #e7d9b4; }
+  .panel .go { width: 100%; min-height: 46px; border: 0; border-radius: 12px; background: #ffcf6e; color: #1b1405; font: 800 16px inherit; font-family: inherit; cursor: pointer; }
+  .panel ol { margin: 0 0 12px; padding-left: 20px; max-height: 40vh; overflow: auto; }
+  .panel li { margin: 4px 0; color: #e7d9b4; }
+  .panel li small { color: #a39a80; }
+  .panel .close { float: right; background: none; border: 0; color: #c9c0a6; font-size: 20px; cursor: pointer; }
+  [hidden] { display: none !important; }
+</style>
+</head>
+<body>
+<canvas id="c"></canvas>
+<div class="ui pill"><button type="button" id="who"></button><button type="button" id="hall-btn">Hall of the Fallen</button></div>
+<div class="ui panel" id="make" hidden>
+  <h2>A new hero</h2>
+  <p>Your hero keeps every level and coin, on every device you play on.</p>
+  <input type="text" id="hero-name" maxlength="20" placeholder="Name your hero" autocomplete="off">
+  <label class="hc"><input type="checkbox" id="hero-hc"> Hardcore: one life. A death is forever, and the Hall remembers.</label>
+  <button type="button" class="go" id="hero-go">Into the vale</button>
+</div>
+<div class="ui panel" id="hall" hidden>
+  <button type="button" class="close" id="hall-close" aria-label="Close">×</button>
+  <h2 id="hall-title">Hall of the Fallen</h2>
+  <p id="hall-text">Hardcore heroes who fell in Ember Vale.</p>
+  <ol id="hall-list"></ol>
+  <button type="button" class="go" id="hall-go" hidden>Make a new hero</button>
+</div>
+<script type="module" crossorigin src="./assets/main.js"></script>
+</body>
+</html>