hayao 0.2.0 → 0.4.0

package/docs/QUICKSTART.md

@@ -0,0 +1,141 @@
+# 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. `justReleased` mirrors it.
+- **Query ACTION names, not key codes** — `isDown('jump')`, never
+  `isDown('Space')`. In the browser, an undeclared name warns once in the
+  console instead of silently never firing.
+- **Pointer coordinates are design-space** — `input.axis('pointer.x'/'pointer.y')`
+  already un-letterboxed; mouse buttons are bindable actions
+  (`mouse.left/right/middle`). See CONVENTIONS §Pointer & continuous input.
+- **`splash: false`** in `defineGame` skips the built-in loading splash (e.g.
+  for embeds that paint their own cover).
+- **The browser build is scriptable** — `?capture=1` exposes `window.__hayao`
+  (pump/probe/hash/shot), and `handle.tick()` single-steps the real loop; the
+  loop keeps running in hidden tabs (never patch rAF yourself). See
+  VERIFICATION §Channel 2.
+
+## 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.

package/docs/VERIFICATION.md

@@ -0,0 +1,256 @@
+# Verification — how an AI proves a hayao game works
+
+The whole engine is shaped so you can verify a game **without a browser and
+without playing it**. Build the harness *before* the content; unverified content
+is presumed broken (in-head verification has a documented failure rate).
+
+Two channels, in order:
+
+1. **Numeric channel** — headless `step()`, probes, the solver, and determinism
+   checks. Proves *behavior* and *beatability*. This is where correctness lives.
+2. **Visual channel** — a headless SVG screenshot. Judges *looks* only — palette,
+   layout, legibility. Never correctness.
+
+Everything below runs in Node under Vitest (`npm test`) or the CI script
+(`npm run verify`).
+
+---
+
+## Channel 1a — scripted playthrough (any game)
+
+Drive a world with an input log and assert on its probe. No DOM.
+
+```ts
+import { createWorld } from '@hayao';
+import { myGame } from './game';
+
+const world = createWorld(myGame);          // a live, deterministic World
+world.step(['right']);                      // one fixed step, 'right' held
+world.step([]);                             // release (edges need a rising edge)
+world.step(['confirm']);
+expect(world.probe().score).toBe(1);        // assert on game state, not pixels
+```
+
+Helpers: `scriptedPlaythrough(world, [hold(['right'], 30), wait(10)])` returns a
+probe after each segment; `pump(world, n, actions)` advances n steps. Hold keys
+for several frames — a 1-frame synthetic tap is treated as a real short tap.
+
+## Channel 1b — winnability solver (puzzles / turn-based)
+
+Keep the rules in a pure module implementing `Puzzle<State, Move>` (no engine
+imports), then prove every level beatable by search:
+
+```ts
+import { solve, assertSolvable, type Puzzle } from '@hayao';
+
+const puzzle: Puzzle<State, Move> = {
+  initial: (level) => …,
+  moves:   (s) => […],
+  apply:   (s, m) => …,      // fold in a DETERMINISTIC opponent here if any
+  isWin:   (s) => …,
+  isDead:  (s) => …,          // optional: prune lost states
+  key:     (s) => canonicalString(s),
+};
+
+const r = assertSolvable(puzzle, { level: 0, maxDepth: 80 }); // throws if unwinnable
+console.log(r.depth, r.nodes);              // shortest solution length + search cost
+```
+
+A deterministic opponent means winnability is single-agent BFS — no adversarial
+branching. `solve` returns the shortest `path`, which you can replay through the
+real game (Channel 1a) to prove the *view* agrees with the *logic*.
+
+## Channel 1c — determinism (the regression net)
+
+Same seed + same input log must produce bit-identical state hashes. If not, some
+nondeterminism leaked in (Math.random, Date.now, Set iteration, unordered map).
+
+```ts
+import { assertDeterministic, assertSnapshotStable } from '@hayao';
+
+assertDeterministic(() => createWorld(myGame), inputLog);      // runs twice, compares every step's hash
+assertSnapshotStable(() => createWorld(myGame), inputLog, 20); // snapshot→restore reproduces the tail exactly
+```
+
+`world.hash()` is the structural hash; `world.snapshot()` / `world.restore()` are
+save/undo/time-travel. Mark pure-view nodes `cosmetic = true` so transient display
+(move counters, particles, tweened positions) never pollutes the canonical hash.
+
+## Channel 1d — the golden replay corpus (portfolio-wide refactor net)
+
+Every example pins its full scripted run's final `world.hash()` in a committed
+`examples/<slug>/golden.json`, checked by `t.golden(label, hash)` in its
+verify suite. This turns "did my engine refactor change ANY game's behavior?"
+into one command: `npm run verify` — a pure refactor leaves every golden hash
+untouched; any divergence names the game and the run that changed.
+
+```ts
+// in examples/<slug>/verify.ts, after the full run:
+t.golden('full run', world.hash());
+```
+
+**Re-record policy.** Golden divergence is a failing gate, on purpose. When a
+behavior change is *intentional* (tuning, new content, a deliberate engine
+change), re-record and say so:
+
+1. `UPDATE_GOLDEN=1 npm run verify` — rewrites the affected `golden.json`.
+2. Commit the new hashes IN THE SAME COMMIT as the change, with a line in the
+   message naming which games' behavior changed and why.
+
+Never re-record to silence a divergence you can't explain — an unexplained
+golden change IS the bug the corpus exists to catch.
+
+## Channel 2 — the visual screenshot (looks only)
+
+```ts
+import { HeadlessRenderer, createWorld } from '@hayao';
+
+const world = createWorld(myGame);
+world.step([]);
+const r = new HeadlessRenderer({ width: 1280, height: 720, background: '#f3ecdb' });
+r.draw(world.render());
+writeFileSync('shots/title.svg', r.toSVGString());   // a real vector screenshot, in Node
+```
+
+Because rendering is SVG, the screenshot is **resolution-independent and text is
+crisp** — no canvas fuzz, no GPU. You rarely need a browser at all, because the
+DOM is already inspectable and the sim already runs in Node — but when a tool
+must drive the real browser build, two seams exist:
+
+**`?capture=1` → `window.__hayao`** (`src/verify/capture.ts`). Appending
+`?capture=1` to a game's URL skips the splash and installs a scripted-session
+API on `window`:
+
+| Member | What it does |
+|---|---|
+| `pump(frames, actions?)` | Step exactly `frames` fixed steps with `actions` held (wall-clock loop suspended), then return `probe()` |
+| `probe()` | The game's probe snapshot |
+| `hash()` | `world.hash()` — the determinism hash |
+| `shot()` | Current frame as an SVG string (a vector screenshot) |
+| `save(path)` | POST that SVG to the dev server's `/__shot` endpoint; resolves `true` on success |
+| `key(type, code)` | Dispatch a synthetic `keydown`/`keyup` by key code |
+| `world` | The live `World` — full access when the shorthands aren't enough |
+
+`probe` is whatever the game's `defineGame({ probe })` returns — expose exactly
+the state a scripted session will assert on.
+
+**`handle.tick(dtMs?)`** — the `runBrowser` handle can drive one frame by hand:
+sample the pointer and extra sources, advance by `dtMs` (default one fixed
+step) with the currently-held actions, render. It is the SAME code path the
+wall-clock loop runs, so tool-driven frame stepping is the real loop, not a
+simulation of it. The wall-clock loop keeps running independently — pause the
+shell or hold via `RunOptions.isHeld` to make `tick()` the only driver.
+
+**Hidden tabs and iframes keep ticking.** Browsers throttle rAF to death in
+hidden tabs/iframes; the engine now owns the fallback — when `document.hidden`,
+the loop pumps via `setTimeout(16)` and swaps back to native rAF on
+visibility. Games and harnesses must **NOT** patch the global
+`requestAnimationFrame` anymore: per-game patches double-fire and race the
+engine's scheduler (the 2026-07 triage traced real bugs to exactly that).
+
+For MOTION, use the filmstrip instead of a single frame: it samples a whole
+run into one SVG contact sheet, so pacing, readability under load, and
+layering during play are judgeable from a file.
+
+```ts
+import { renderFilmstrip } from '@hayao';
+t.artifact('run-filmstrip.svg', renderFilmstrip(createWorld(myGame), inputFrames, {
+  width: myGame.width, height: myGame.height, background: myGame.background, panels: 12,
+}));
+// → shots/<slug>/run-filmstrip.svg — open it and actually look.
+```
+
+## Channel 3 — feel probes (quality proxies)
+
+Correctness channels prove the game is *not broken*; they say nothing about
+whether it is *good*. Feel probes give quality a measurable proxy: compute
+metrics from a per-frame probe timeline of the winning run, and gate them on
+windows YOU tune per game. A window is a design decision recorded as a test —
+retuning that wrecks pacing fails loudly instead of silently.
+
+```ts
+import { recordTimeline, firstFrame, inputDensity, longestLull, changeFrames, isMonotonic } from '@hayao';
+
+const tl = recordTimeline(createWorld(myGame), winningLog);
+firstFrame(tl, (p) => p.kills > 0);      // time-to-first-meaningful-action
+inputDensity(winningLog);                 // engagement: waiting ↔ mashing
+longestLull(changeFrames(tl, 'score'), tl.length); // dead-air detector
+isMonotonic(depths, 'up', slack);         // difficulty ramps with breathers
+```
+
+What to gate is genre truth: a stealth game gates its hide/move alternation,
+an incremental its unlock cadence, a puzzle its solve-depth curve. Two rules:
+(1) derive windows from a run you have actually judged as feeling right —
+never invent them; (2) keep them generous enough that tuning breathes, tight
+enough that pacing regressions fail. These are proxies, not proof of fun —
+the filmstrip and a human/AI look stay in the loop.
+
+## Channel 4 — feel gates (the professional floor, made checkable)
+
+Channel 3 measures *pacing* from a timeline; Channel 4 gates the small set of feel
+**fundamentals** that separate amateur from professional and that are genuinely
+mechanical, not matters of taste. Each returns human-readable issues (empty = pass),
+exactly like `layoutIssues` — so wiring one in is one line. This is the direct
+answer to "green tests, dead game": turn more of *feel* green.
+
+```ts
+import { forgivenessIssues, graceWindowIssues, feedbackIssues,
+         salienceIssues, telegraphIssues, cameraIssues, lookAheadIssues } from '@hayao';
+```
+
+1. **Forgiveness.** `forgivenessIssues(cfg)` audits the grace windows (coyote,
+   jump-buffer, corner-nudge) against a floor; `graceWindowIssues(label, W, accepts)`
+   *behaviourally* proves a window accepts an input `0..W` frames late and refuses
+   `W+1` — the exact edge FUN law 5 demands. (updrift proves a 4-frame coyote window
+   by walking a rig off a lip and jumping D frames later.)
+2. **Feedback completeness.** Declare a `FeedbackContract` (event → channels +
+   shake/hit-stop), then `feedbackIssues(contract, events)` proves every significant
+   event answers on ≥ 2 senses within the frame, with juice bounded (min to read,
+   max to not nauseate).
+3. **Readability.** `salienceIssues(render(), avatarFill, background)` proves the
+   avatar out-contrasts both the background and the median scenery fill (WCAG
+   luminance, from pure draw data). `telegraphIssues(timeline, minFrames)` proves
+   every threat activation is preceded by ≥ `minFrames` of telegraph — reactive play
+   needs danger to announce itself.
+4. **Camera lawfulness.** `cameraIssues(samples)` proves the follow never snaps
+   (bounded speed) or jerks (bounded acceleration); `lookAheadIssues(cam, target)`
+   proves it leads the motion rather than trailing. Sample the *follow* position
+   (exclude screen shake), and drop the pre-start frame (no camera exists yet).
+
+The full four-gate suite wired on a real game lives in
+[`examples/updrift/verify.ts`](../examples/updrift/verify.ts); the authoring side is
+[docs/JUICE.md](JUICE.md). Gate on the fundamentals; the *soul* above the floor
+stays authored (a director, not a proof) — but the floor no amateur clears is now
+machine-enforced.
+
+**Portfolio floor (`npm run feel`).** A game declares its contract once —
+`export const feel: FeelSpec` in `game.ts` (avatar fill → salience; controller
+config → forgiveness; feedback contract → feedback; `scrolls` → camera). The audit
+runs every gate each spec enables across all games and exits non-zero on any
+failure; it is part of `npm run verify`, so the floor rises for ALL output, not one
+game. Declare only what is honestly true — a false contract is worse than none.
+
+## Channel 5 — the vision judge (`npm run judge`)
+
+The gates prove the floor mechanically; they can't see that a scene is *empty* or
+*flat*. `npm run judge` renders each game headlessly to PNG (SVG → `@resvg/resvg-js`,
+no browser) so a multimodal model LOOKS at the pixels and scores them against
+[JUDGE.md](JUDGE.md) — then fixes what a human would wince at, staying cosmetic (the
+golden hash unchanged). It's the one judge that can't be a pure function, which is
+why an AI-first engine — deterministic sim, headless render — is uniquely built to
+run it in a loop. Drive it with the `/judge` skill.
+
+---
+
+## The gate (`npm run verify`)
+
+The CI verifier proves every example winnable, replays a solution through the
+real game, and checks determinism — exiting non-zero on any failure. Wire your
+game's puzzle + game into `scripts/verify.ts` and it becomes a pipeline gate.
+
+## Invariants
+
+- All randomness flows through `world.rng`. No `Math.random()` in `src/` or games.
+- No wall-clock in the sim (`Date.now`, `performance.now`, argless `new Date`).
+- Fixed tree order; ordered collections for logic (no `Set`/object-key order).
+- Every shipped level: a solver proof OR a scripted playthrough. No exceptions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hayao",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "An AI-first game engine: a deterministic, headless-native simulation kernel with a Godot-style scene tree, pluggable renderers (SVG/Canvas/headless), and a built-in verification harness — designed so an LLM can author, test, and prove correct a whole game without ever opening a browser.",
   "keywords": [
@@ -26,15 +26,31 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "create-hayao": "./bin/create-hayao.mjs",
+    "hayao-mcp": "./bin/hayao-mcp-cli.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./studio": {
+      "types": "./dist/studio/vitePlugin.d.ts",
+      "import": "./dist/studio-plugin.js"
     }
   },
   "files": [
     "dist",
-    "docs/API.md"
+    "dist-studio",
+    "bin/create-hayao.mjs",
+    "bin/hayao-mcp-cli.mjs",
+    "docs/QUICKSTART.md",
+    "docs/API.md",
+    "docs/VERIFICATION.md",
+    "docs/CONVENTIONS.md",
+    "docs/EMBED.md",
+    "docs/STUDIO.md"
   ],
   "engines": {
     "node": ">=18"
@@ -45,19 +61,37 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
-    "build:lib": "rm -rf dist && esbuild src/index.ts --bundle --format=esm --platform=neutral --target=es2022 --outfile=dist/index.js --sourcemap && tsc -p tsconfig.build.json",
+    "build:lib": "rm -rf dist && esbuild src/index.ts --bundle --format=esm --platform=neutral --target=es2022 --outfile=dist/index.js --sourcemap && esbuild src/index.ts --bundle --minify --format=esm --platform=neutral --target=es2022 --outfile=dist/index.min.js && esbuild src/index.ts --bundle --minify --format=iife --global-name=hayao --platform=neutral --target=es2022 --outfile=dist/hayao.global.js && esbuild src/studio/mcpMain.ts --bundle --format=esm --platform=node --target=es2022 --outfile=dist/mcp.js --external:@resvg/resvg-js --external:hayao && esbuild src/studio/vitePlugin.ts --bundle --format=esm --platform=node --target=es2022 --outfile=dist/studio-plugin.js --external:vite && cp scripts/rasterize-worker-lite.mjs dist/rasterize-worker-lite.mjs && tsc -p tsconfig.build.json",
+    "build:studio": "vite build -c vite.studio.config.ts",
     "check": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "api": "tsx scripts/api-digest.ts",
     "invariants": "tsx scripts/invariants.ts",
-    "verify": "tsx scripts/invariants.ts && tsx scripts/verify.ts",
-    "prepublishOnly": "npm run check && npm test && npm run build:lib",
-    "relay": "node scripts/relay.mjs"
+    "verify": "tsx scripts/verify-all.ts",
+    "eval": "tsx scripts/eval.ts",
+    "create": "node bin/create-hayao.mjs",
+    "prepublishOnly": "npm run check && npm test && npm run build:lib && npm run build:studio",
+    "relay": "node scripts/relay.mjs",
+    "palette": "tsx scripts/palette-audit.ts",
+    "audio": "tsx scripts/audio-render.ts",
+    "feel": "tsx scripts/feel.ts",
+    "judge": "tsx scripts/judge.ts",
+    "thumbs": "tsx scripts/site-thumbs.ts"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^22.10.0",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.0",
+    "happy-dom": "^20.10.6",
+    "leva": "^0.10.1",
+    "qrcode": "^1.5.4",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",