hayao 0.2.0 → 0.3.0

package/docs/CONVENTIONS.md

@@ -0,0 +1,223 @@
+# Conventions — how games are built in hayao.js
+
+Every game in this repo follows these. They exist so that any game — by any
+author, human or AI — inherits determinism, testability, and the house look for
+free. They are the practical restatement of [ARCHITECTURE.md](ARCHITECTURE.md);
+where the two disagree, ARCHITECTURE wins.
+
+---
+
+## Files & boundaries
+
+- A game lives ONLY in `examples/<slug>/`: an `index.html` + a `game.ts` entry,
+  split into small modules once the entry approaches ~400 lines (pure sim logic
+  in one file, scene/rendering wiring in another). The vite config
+  auto-discovers `examples/<slug>/index.html` — a new folder needs zero config.
+- Import ONLY from `'@hayao'` — never from `'@hayao/core/rng'`, `'../src/...'`,
+  or any deep path. The barrel (`src/index.ts`) is the entire public surface;
+  keeping imports there is what lets the internals move without breaking games,
+  and lets one grep of one file answer "what can I call?".
+- Never modify `src/*`, `package.json`, `docs/ARCHITECTURE.md`, other examples,
+  or root config from within a game task.
+- Register the game in the hub (`index.html`) so it appears in the example list.
+
+## Bootstrap: `defineGame()`
+
+A game is a single `defineGame()` value — a plain, declarative description of
+how to build the initial world, what the input map is, and (optionally) its
+levels and probes. It contains **no host wiring**: the same value runs under
+`runBrowser()` (rAF loop, real input, an `SvgRenderer`, audio, the UI shell) or
+`runHeadless()` (no host; used by tests and `npm run verify`) unchanged.
+
+```ts
+import { defineGame, World, Node2D, Sprite, DEFAULT_INPUT_MAP } from '@hayao';
+
+export default defineGame({
+  title: 'Slug Rush',
+  inputMap: DEFAULT_INPUT_MAP,            // action → key codes (never raw keys in logic)
+  build(world: World) {                    // populate the initial scene tree
+    const player = world.root.addChild(new Sprite({
+      name: 'player',
+      shape: { kind: 'circle', radius: 16 },
+      fill: '#2485a6', stroke: '#232228', strokeWidth: 3,
+    }));
+    player.onUpdate = (n, dt, ctx) => {       // ctx = the host world (input/rng/clock/time)
+      const move = (ctx.input.isDown('right') ? 1 : 0) - (ctx.input.isDown('left') ? 1 : 0);
+      n.pos.x += move * 200 * dt;          // dt is the FIXED step — deterministic
+    };
+  },
+  probe(world) {                           // compact JSON snapshot for the harness
+    return { ...world.probe(), x: world.root.find('player')?.pos.x };
+  },
+});
+```
+
+The engine, not game code, owns the clock, the rAF loop, focus, audio muting,
+and the DOM shell. Do not re-implement any of that inside a game.
+
+The third `onUpdate`/behavior argument is the **world context** (`input`, `rng`,
+`clock`, `time`) — prefer it over closing over `world` from `build()`, so a node's
+behavior is self-contained and liftable. For headless tests, `world.runSteps(n,
+i => actions)` fast-forwards an exact step count; `world.advance(realMs)` is the
+*realtime* driver and clamps big deltas to one frame budget (never use it to skip
+ahead in a test).
+
+## Pointer & continuous input
+
+Keyboard actions are the default and the only input that flows through the
+deterministic log. For games driven by *where* the cursor is (slice, aim, drag,
+point-and-click, placement), `runBrowser` wires a **`PointerSource`** that samples
+the cursor into `world.input.axes` each step, in DESIGN space:
+`ctx.input.axis('pointer.x' | 'pointer.y' | 'pointer.down')`. Need the mapping
+yourself? `handle.toDesign(clientX, clientY)` (or `renderer.toDesign`) undoes the
+letterbox once, so no game re-derives `getBoundingClientRect()` math.
+
+Determinism caveat: pointer axes are live host samples — they are NOT in the string
+input log or `world.hash()`, so a raw pointer trail does not replay the way key
+actions do. For lockstep/replay, **quantize at the host edge**: map a tap to an
+action (`input.press('fire')`) or snap position to a grid cell you feed as a
+discrete move. Keep raw pointer floats out of the sim's canonical state.
+
+
+## The human-contact layer
+
+The first real playtest of the campaign found every defect in the one layer
+sim proofs cannot see. These rules close that gap; the machine-checkable ones
+are enforced by `layoutIssues()` / `missingControlHints()` from `@hayao`,
+which every verify suite must run on its representative screens.
+
+- **Text is sacred.** A shape either fully CONTAINS a text's box (it is a
+  panel/scrim) or stays fully clear of it — partial overlap is a collision.
+  Background lattice (z ≤ 1: tile grids, felt) is exempt. HUDs drawn over
+  world geometry get a scrim panel, not hope.
+- **First contact teaches.** Every action in the input map must be named by
+  some on-screen text on the first frame (`missingControlHints` = []). Games
+  with phases show a CONTEXTUAL coach line ("X has moved — F fires"), not one
+  static legend. Anything tactical gets an onboarding overlay: goal, threat,
+  verbs — a stranger must know what to do within 30 seconds.
+- **Every entity kind is legible.** Distinct shape+outline per kind (items
+  must not share silhouettes with creatures) and a legend that names them
+  with their true glyphs.
+- **Fiction is earned.** Ending copy may not introduce proper nouns the game
+  never showed; if the title names a thing in-fiction, the first screen says
+  so (the HUD naming "THE DUSKVEIL" is what earns "The Duskveil lifts").
+- **No safe camp.** Every real-time game's verify includes a degenerate-
+  position probe: park at edges/corners and prove the threat still reaches.
+  Bots demonstrate the intended line; this proves there's no cheaper one.
+- **The screen arrives intact.** Renderers letterbox (never stretch or crop);
+  sim clamps include sprite EXTENTS so nothing sinks out of view at the rim.
+
+## Pure-sim separation (turn-based / puzzle games: mandatory)
+
+For anything grid- or turn-based, keep the **rules** in a module with NO scene
+or render imports: state in, state out, deterministic. This is the module the
+solver runs over (see [VERIFICATION.md](VERIFICATION.md)); the scene tree then
+becomes a thin *projection* of that state. Real-time games instead put logic in
+node `onUpdate`/behaviors, but the same rule holds: all state lives in the tree
+or a pure module, never in a renderer or the DOM.
+
+The same discipline applies to menus and settings: model them as a pure reducer
+`(state, action) → { state, fx }`, with sound cues returned as data, then render
+via the DOM shell. "Pure logic" is for anything with state transitions, not just
+puzzles.
+
+## Determinism rules (the contract — restated from ARCHITECTURE §Determinism)
+
+These are non-negotiable. Break one and `assertDeterministic` fails loudly,
+which is the point.
+
+1. **All randomness flows through `Rng`.** Use `world.rng` (or a child from
+   `world.rng.split(key)`). `Math.random()` is banned in `src/` and in games.
+2. **No wall-clock reads in the sim.** Time comes from the `Clock`
+   (`world.time`, `world.frame`, and the fixed `dt` passed to `update`).
+   `Date.now()`, `performance.now()`, and argless `new Date()` are banned in
+   sim code.
+3. **The scene tree updates in a fixed order** — depth-first, child-index order.
+   Don't reorder children for logic reasons mid-step; don't depend on iteration
+   racing anything else.
+4. **Iterate collections in a stable order** — arrays or insertion-ordered
+   `Map`s. Never rely on `Set` iteration order or `Object` key order for logic.
+   (The state hash sorts object keys for you, but your *logic* must not branch
+   on unordered iteration.)
+5. **Floating point is fine** as long as 1–4 hold: same ops, same order, same
+   engine → same bits.
+
+RNG state and clock state are part of `world.hash()`, `world.snapshot()`, and
+saves, so a restored world resumes *identically* — that is what makes replay,
+undo, and time-travel free.
+
+## House style (defaults — swap deliberately, not accidentally)
+
+- **Code-as-art, zero binary assets.** A `Sprite` is a vector `Shape`
+  (`rect` / `circle` / `poly` / `path`) or a `glyph` (a Unicode character) —
+  never a bitmap. Unicode glyphs (♞ ♝ ⚔ ☠ ✿) are instant, legible art.
+  **Shape origins:** `rect`/`circle`/`glyph` are CENTER-anchored on the node's
+  `pos` (a rect draws from `-w/2,-h/2`); `poly`/`path` points are local to `pos`.
+  Thinking in corners? Pass `{ kind: 'rect', w, h, anchor: 'topLeft' }` — otherwise
+  a top-left mental model lands the box half-a-size off.
+  **Outlined text:** a `Text` node carries `Paint`, so `stroke`/`strokeWidth`
+  outline the glyph (the outline lays UNDER the fill, so it frames rather than
+  eats the letter) — the way to make a label read on both light and dark grounds.
+  Don't stack offset copies to fake a halo; one `stroke` does it.
+- **Default palette is Kentō** (`import { KENTO, MEADOW, DUSK } from '@hayao'`).
+  It fuses the site's washi/sumi/ai/shu ink tokens with landscape hues loosely
+  drawn from Miyazaki-16 — eight named hues, each with a `Deep` tone for light
+  grounds and a bright tone for dark grounds, so `MEADOW` (light) and `DUSK`
+  (dark) share one identity. Pick hues by name (`KENTO.asagi`); reach for ~5–6
+  per game plus a ground. Alpha/tone variants via `withAlpha`/`mix` are welcome;
+  monospace/terminal defaults read as lazy and are discouraged. The engine stays
+  palette-agnostic — Kentō is a consistent starting point, never a restriction.
+  Every Kentō pairing is WCAG-AA verified: `npm run palette` is the gate.
+- **Pickups and interactables carry a dark ink outline** (`stroke: KENTO.sumi`
+  on light, `KENTO.gofun` rim on dark), plus a glow/pulse for emphasis. An
+  accent-colored shape flat on the floor vanishes the moment two hues share a
+  family — contrast lives in the edge, not the fill. Judge contrast from a
+  rendered SVG, never from hex values.
+- **Menus, titles, HUD, and settings are DOM overlays** (the ui/ shell), never
+  `Text` nodes drawn into the scene. Humans compare in-scene type to the DOM
+  around it and the scene loses. In-scene `Text` is for in-world labels only.
+- **Strict layering** via the `z` field on nodes/commands: background → world →
+  actors → fx → HUD. Nothing gameplay-critical may be occluded. In-world `Text`
+  defaults to `z=0`, so a label placed ON a sprite (a tile value, a score over a
+  token) needs an explicit `z` ABOVE that sprite or it paints underneath and is
+  silently invisible. `layoutIssues` now flags this (`text … hidden behind …`).
+- **Contrast is now headless-checkable.** Pass the page `background` to
+  `layoutIssues(commands, { background })` and it flags near-invisible fills and
+  sub-AA text from the hex alone — a first line of defense before the vision
+  judge. Still judge final contrast from a rendered SVG; the lint catches the
+  "dark shape on dark ground" class the pixel-blind proofs otherwise miss.
+
+## Definition of done
+
+A game is done when ALL of the following hold. This is a checklist, not a vibe.
+
+1. **Typecheck clean** — `npm run check` reports zero errors. TypeScript strict
+   mode is a free correctness gate; use it.
+2. **Tests pass** — `npm test` green. Sim tests run headlessly in Node.
+3. **Every level is solver-proven or scripted-played** — each shipped level has
+   either a machine win-proof (`solve()`), or a scripted playthrough that
+   asserts the win condition on probes. In-head verification has a documented
+   failure rate (see [LESSONS.md](LESSONS.md)); it is not evidence.
+4. **Deterministic replay verified** — `assertDeterministic(game, seed,
+   inputLog)` passes: two runs of the same seed + input log produce an identical
+   `world.hash()` at every checkpoint.
+5. **The vision judge run and its high findings fixed** — `npm run judge <slug>`
+   renders the game to PNG; actually LOOK at it and score against
+   [JUDGE.md](JUDGE.md) (readability, depth, palette, juice, motion, chrome). Fix
+   every high-severity finding with cosmetic changes (the golden hash must stay
+   unchanged). "Passes the gates" is not "looks shipped"; this closes that gap.
+6. **A complete loop exists** — start → play → win/lose → restart, keyboard-only,
+   and `restart` fully rebuilds world state (no leaked nodes, no stale RNG).
+7. **The full run's hash is pinned** — `t.golden('full run', world.hash())` in
+   `verify.ts`, recorded via `UPDATE_GOLDEN=1 npm run verify`, `golden.json`
+   committed (VERIFICATION §Channel 1d).
+8. **Feel probes gate the genre's pacing** — at least two `recordTimeline`-based
+   metrics with tuned windows, plus a `renderFilmstrip` artifact reviewed for
+   motion/readability (VERIFICATION §Channel 3). Windows come from a run you
+   judged, not from thin air.
+9. **A feel spec is declared and its gates pass** — `export const feel: FeelSpec`
+   in `game.ts` (avatar fill for salience; controller config for forgiveness; a
+   feedback contract; `scrolls` for the camera gate). `npm run feel` runs every
+   gate the spec enables and is part of `npm run verify` — the professional FLOOR
+   is now a CI gate, not a hope (VERIFICATION §Channel 4). Declare only what is
+   honestly true; a false contract is worse than none.

package/docs/EMBED.md

@@ -0,0 +1,85 @@
+# Embedding hayao (offline / single-file)
+
+hayao's thesis is that an LLM can author a whole game as text. The natural
+distribution for that is a **single self-contained HTML file** — no install, no
+bundler, no CDN. That shape is what Claude Artifacts, js13k entries, itch.io HTML
+uploads, and CodePen all want. This page has the two recipes.
+
+`npm run build:lib` emits three library targets:
+
+| File | Format | Use |
+| --- | --- | --- |
+| `dist/index.js` | ESM (readable, sourcemapped) | bundlers, `import` in apps |
+| `dist/index.min.js` | ESM, minified | modern `<script type="module">` / inline import |
+| `dist/hayao.global.js` | IIFE, minified, `window.hayao` | plain `<script src>` / paste-inline |
+
+The minified builds are ~190 KB (~45 KB gzipped) and carry **no**
+`sourceMappingURL` comment, so an inlined copy stays console-clean.
+
+## Recipe A — `<script src>` global (simplest)
+
+The IIFE build exposes everything on `window.hayao`. No modules, no plumbing:
+
+```html
+<div id="app"></div>
+<script src="hayao.global.js"></script>
+<script>
+  const { defineGame, runBrowser, Sprite, Text, Node, vec2 } = hayao;
+  const game = defineGame({
+    title: 'My Game',
+    build(world) {
+      const root = new Node({ name: 'root' });
+      root.addChild(new Text({ text: 'hello', pos: vec2(640, 360), align: 'center' }));
+      return root;
+    },
+  });
+  runBrowser(game, document.getElementById('app'));
+</script>
+```
+
+See [`examples/embed.html`](../examples/embed.html) for a runnable version
+(pointer-follow demo). Serve the folder or open the file after `npm run build:lib`.
+
+## Recipe B — fully inline, single `.html` (truly offline)
+
+For one file with **zero** external requests, paste the engine source directly
+into a `<script>` tag instead of referencing it:
+
+```html
+<div id="app"></div>
+<script>
+  /* ⇩ paste the entire contents of dist/hayao.global.js here ⇩ */
+  "use strict";var hayao=(()=> …;
+  /* ⇧ end of pasted engine ⇧ */
+</script>
+<script>
+  const { defineGame, runBrowser } = hayao;
+  // …your game…
+</script>
+```
+
+That's the shape an LLM tool call can emit whole: one file, opens anywhere,
+works on a plane. Because the minified builds drop the sourcemap comment, there
+are no 404s or console warnings from the inlined copy.
+
+### ESM-inline variant
+
+If you prefer modules, inline `dist/index.min.js` as a blob and dynamic-import it:
+
+```html
+<script type="module">
+  const src = `/* paste dist/index.min.js here */`;
+  const url = URL.createObjectURL(new Blob([src], { type: 'text/javascript' }));
+  const hayao = await import(url);
+  // …use hayao.defineGame / hayao.runBrowser…
+</script>
+```
+
+## Notes
+
+- **Assets.** If your game loads a webfont or atlas, use the `preload` +
+  `splash` lifecycle (see [API.md](API.md)) so there's no pop-in — the engine
+  holds a palette-guaranteed splash until preload resolves.
+- **The one gap the engine can't close.** The window between the browser
+  *fetching* the file and the script *executing* is pre-engine by physics —
+  nothing hayao can draw yet. Recipe B shrinks it to a single local file.

package/docs/QUICKSTART.md

@@ -0,0 +1,129 @@
+# Quickstart — build a game from the `hayao` npm package
+
+This is the consumer-facing guide: what to do after `npm i hayao`, with a
+complete, runnable, headless-verifiable game in ~40 lines. For the full API
+surface see [API.md](API.md); to browse finished games see
+[hayao.dev/play](https://hayao.dev/play/).
+
+## Install
+
+```sh
+npm i hayao
+```
+
+**hayao is ESM-only.** Make sure your project is ES modules — set
+`"type": "module"` in your `package.json` (or use an `.mjs` file). Importing
+from a default CommonJS project fails with a cryptic
+`ERR_PACKAGE_PATH_NOT_EXPORTED`; that error means "switch to ESM," nothing more.
+
+## The one idea
+
+A hayao game is a **pure, deterministic function of its inputs**. Rendering,
+audio, and the browser are *observer plugins* that paint what the function
+produces — they can never change its result. So you can run the whole game in
+Node, assert on its state, and prove a level winnable, with no browser and no
+pixels.
+
+## A complete game (`coins.ts`)
+
+A 5×5 grid; walk onto coins to collect them. Canonical state lives in
+`world.state` (plain JSON — it's what gets hashed). The scene tree is a
+`cosmetic` *view* of that state and never pollutes the hash.
+
+```ts
+import { defineGame, createWorld, drive, Node, Sprite, type World, type InputScript } from 'hayao';
+
+const COLS = 5, ROWS = 5;
+const COINS: [number, number][] = [[4, 0], [4, 4], [0, 4]];
+interface State { x: number; y: number; coins: [number, number][]; collected: number; }
+
+function tick(world: World) {
+  const s = world.state as unknown as State;
+  const i = world.input;
+  if (i.justPressed('right')) s.x = Math.min(COLS - 1, s.x + 1);
+  else if (i.justPressed('left')) s.x = Math.max(0, s.x - 1);
+  else if (i.justPressed('up')) s.y = Math.max(0, s.y - 1);
+  else if (i.justPressed('down')) s.y = Math.min(ROWS - 1, s.y + 1);
+  const before = s.coins.length;
+  s.coins = s.coins.filter(([cx, cy]) => !(cx === s.x && cy === s.y));
+  s.collected += before - s.coins.length;
+}
+
+export const game = defineGame({
+  title: 'Coin Grab', width: COLS * 32, height: ROWS * 32, seed: 1,
+  build(world: World): Node {                       // build MUST return the root Node
+    world.state = { x: 0, y: 0, coins: COINS.map(([x, y]) => [x, y]), collected: 0 } as unknown as Record<string, unknown>;
+    const root = new Node({ name: 'root' });
+    // A view sprite: shape is required (not `size`); mark it cosmetic so it stays out of hash().
+    const player = new Sprite({ name: 'player', shape: { kind: 'rect', w: 28, h: 28 }, fill: '#e8c34a' });
+    player.cosmetic = true;
+    player.onUpdate = (n) => { const s = world.state as unknown as State; n.pos = { x: s.x * 32 + 2, y: s.y * 32 + 2 }; };
+    root.addChild(player);
+    const brain = new Node({ name: 'brain' });        // a node that advances the sim each frame
+    brain.onUpdate = () => tick(world);
+    root.addChild(brain);
+    return root;
+  },
+  probe(world: World) {                               // expose exactly the state you'll assert on
+    const s = world.state as unknown as State;
+    return { x: s.x, y: s.y, collected: s.collected, remaining: s.coins.length, hash: world.hash() };
+  },
+});
+```
+
+## Prove it works — headlessly
+
+`createWorld(game)` runs the sim in Node. `drive(world, script, until?)` steps a
+scripted input log, optionally stopping early when a predicate on `probe()` is
+true. Then assert on `probe()` and `hash()`.
+
+```ts
+// Input scripts are segments of { press, frames }. justPressed is a TRUE rising
+// edge: holding the same action across adjacent frames fires ONCE, so separate
+// repeated taps of the same action with a neutral (release) frame.
+const tap = (dir: string): InputScript => [{ press: [dir], frames: 1 }, { frames: 1 }];
+const script: InputScript = [
+  ...tap('right'), ...tap('right'), ...tap('right'), ...tap('right'),
+  ...tap('down'),  ...tap('down'),  ...tap('down'),  ...tap('down'),
+  ...tap('left'),  ...tap('left'),  ...tap('left'),  ...tap('left'),
+];
+
+const world = createWorld(game);
+const res = drive(world, script, (p) => p.remaining === 0);
+const p = game.probe!(world);
+console.assert(p.collected === 3 && p.remaining === 0, 'all coins collected');
+console.assert(res.matched, 'stopped early on the win predicate');
+
+// Determinism: the same script always produces the same hash.
+const a = createWorld(game); drive(a, script);
+const b = createWorld(game); drive(b, script);
+console.assert(a.hash() === b.hash(), 'two runs hash identically');
+```
+
+Run it:
+
+```sh
+npx tsx coins.ts          # or: node coins.mjs
+```
+
+That's the whole loop an AI author uses: **define → step → assert on
+state/hash**. A refactor that keeps the hash keeps behavior; a level a search
+can reach is provably winnable — all without opening a browser.
+
+## Gotchas the type surface won't shout at you
+
+- **ESM only** — `"type": "module"` (see Install).
+- **`build(world)` must return the root `Node`.** Put canonical, hashed state in
+  `world.state` (plain JSON); never in module-level variables.
+- **`Sprite` takes `{ shape: { kind: 'rect', w, h } }`**, not `{ size }`.
+- **Mark pure-view nodes `cosmetic = true`** so transient display never enters
+  `world.hash()` — otherwise determinism checks will (correctly) fail.
+- **`justPressed` is a one-frame rising edge** — insert a neutral frame between
+  repeated taps of the same action.
+
+## Where to go next
+
+- [API.md](API.md) — the full, greppable public surface (every export + signature).
+- [VERIFICATION.md](VERIFICATION.md) — the two verification channels; how to prove a game correct.
+- [CONVENTIONS.md](CONVENTIONS.md) — how larger games are structured (pure logic modules, solver proofs, house style).
+- [hayao.dev/play](https://hayao.dev/play/) — finished example games, each with source.

package/docs/STUDIO.md

@@ -0,0 +1,97 @@
+# STUDIO.md — the human/AI playtest loop
+
+Hayao proves almost everything by machine — winnability, determinism, ramp,
+feel floors. The one channel no headless gate can close is **fun**, and that
+takes a human. Studio is the instrument for that channel: it turns every human
+playtest into a machine-legible, bit-exactly replayable artifact, and gives the
+agent sanctioned verbs to act on it.
+
+The design doctrine, in one line each:
+
+- **Text is the source of truth.** The Studio UI and its knob panel are
+  observers; accepted values become code only when the agent edits the declared
+  defaults. `.studio/` is session data, never config.
+- **Filesystem is the bus.** The browser posts artifacts to the dev server; the
+  agent reads the same files via the MCP sidecar. The two never hold a socket
+  to each other, so everything works across restarts and from cloud agents.
+- **A session is a re-executable, not a recording.** `(seed, tuning, inputLog,
+  axesLog, knobEvents)` re-simulate the entire run in Node — any metric is
+  computable retroactively, any tick re-inspectable.
+- **Telemetry describes, the human directs.** Metrics and reports feed the
+  human's decisions; nothing is auto-"fixed" from data alone.
+
+## Pieces
+
+| Piece | Where | Role |
+|---|---|---|
+| Tuning knobs | `tuning:` on `defineGame` (see `src/app/tuning.ts`) | declared live-adjustable params; resolved values are hashed sim state read via `world.tune(key)` |
+| `runStudio()` | game `main.ts` (instead of `runBrowser`) | records the session, applies `?seed=`/`?tuning=` URL overrides, exposes `window.__studio` (setKnob / annotate / flush) |
+| Dev middleware | `hayaoStudio()` plugin in `vite.config.ts` | persists sessions + knob values under `.studio/`, serves `/__studio/state`, implements `/__shot` |
+| MCP sidecar | `bin/hayao-mcp.ts`, registered in `.mcp.json` | the agent's verbs: `list_games`, `list_sessions`, `inspect_moment`, `get_knob_state`, `run_verify` |
+| `/studio` skill | `.claude/skills/studio/` | the two loops: knob write-back and playtest reading |
+
+## The session artifact
+
+`.studio/sessions/<id>.json` (`PlaytestSession` in `src/studio/session.ts`):
+seed, initial tuning, per-frame action log, delta-encoded analog axes
+(pointer is grid-quantized at the source so replay is exact), mid-play knob
+events (replayed via rebuild-with-carryover at their exact frame), DOM screen
+events (pause/overlay — menu time the sim can't see), wall-clock marks (tab
+hidden ≠ hesitation), human annotations ("felt-bad @ frame N"), end reason,
+and the git build ref. `playerId`/`consent` fields exist for future invited
+playtesters; creator sessions leave them unset. **Production players are never
+recorded** — this is a dev-server instrument only.
+
+`replaySession(def, session, toFrame?)` reconstructs the world at any tick;
+`assertSnapshotStable`-grade hash equality is covered in
+`src/studio/session.test.ts`.
+
+## Scrub semantics (time travel in the play pane)
+
+The timeline strip under pane A freezes the sim and drags to any recorded
+frame — exact, not approximate: the engine restores the nearest periodic
+snapshot (`SnapshotRing`, every 30 frames) and re-steps the session's own
+recorded inputs (actions, axes, knob events) to the target. The ⌖ button shows
+the live probe at the scrubbed frame. **Resuming after a rewind FORKS the
+timeline**: the discarded future is truncated from the session (frames, axes,
+knob/screen events, annotations past the fork), so the artifact always replays
+as exactly what the player kept — a `scrub` screen event marks the fork frame.
+
+## Tape mode (watch any past session)
+
+A game page opened with `?session=<id>` (`&at=<frame>` optional) becomes a
+read-only player for that artifact: the exact starting world is rebuilt, the
+whole recording is fast-replayed once to fill an adaptively-strided snapshot
+ring, and the full tape is scrubbable end to end — playback steps recorded
+frames at real time (elapsed-time accumulator, so throttled background timers
+can't slow it). The Studio drawer's report links each moment ("longest pause @
+frame N", your annotations, the quit frame) straight into the tape at that
+frame. Knobs and annotation are disabled; nothing records.
+
+## Hot-swap semantics (play across code edits)
+
+A game entry that passes `hot: import.meta.hot` to `runStudio` AND contains the
+literal line `import.meta.hot?.accept();` keeps its live world across code
+edits: on swap the old run snapshots into `hot.data`, the re-executed module
+restores it (new module's tuning wins), and the session splits into segments —
+the old one flushes as `hot-swap`, the new one records the restored snapshot as
+its `startSnapshot`, so **every segment stays bit-exactly replayable** despite
+the code change. Both lines are required: Vite marks HMR boundaries by
+statically scanning module source, so an `accept()` call inside the engine
+cannot mark your entry self-accepting — only the literal in your file can.
+
+## Knob-change semantics
+
+Changing a knob mid-play is a **rebuild-with-carryover**: snapshot → new
+tuning → restore → `def.attach?.(world)`. Behaviors are closures and die on
+restore, so games whose nodes hold closures re-wire them in `attach` — the
+same contract rollback netplay uses. Tuning values live in `world.hash()`, so
+a knob change can never silently escape determinism checks.
+
+## Working on Studio itself
+
+Browser-safe parts (`session.ts`, `record.ts`, `run.ts`) export through the
+`@hayao` barrel; the Vite plugin and MCP sidecar are Node-only and must never
+enter the barrel. Wall-clock use in `run.ts`/`record.ts` is sanctioned by the
+invariants scanner alongside the browser drivers — timestamps go to session
+artifacts (observer data), never into the sim.