hayao 0.3.0 → 0.4.0

package/docs/CONVENTIONS.md

@@ -56,12 +56,77 @@ 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,
+`clock`, `time`, plus `state`, `events`, `width`/`height`, `paused`,
+`timeScale`, and `camera()`) — prefer it over closing over `world` from
+`build()`, so a node's behavior is self-contained and liftable. Type the state
+with `defineGame<TState>` and keep it in `world.state`/`ctx.state` — never in
+module-level variables, which leak across `restart()` and hide from `hash()`
+(see ENGINE.md §Typed state). 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).
 
+## Renderers
+
+The engine ships four renderer backends, all consuming the same `DrawCommand[]`
+display list. The sim never reads the renderer — renderer choice is purely a host
+concern and has zero effect on `world.hash()` or determinism.
+
+| Backend | `RunOptions.renderer` | Best for |
+|---|---|---|
+| `SvgRenderer` | `'svg'` (default) | Sparse scenes, DOM inspection, crisp resolution-independence |
+| `Canvas2DRenderer` | `'canvas'` | High entity counts, particles, performance-first |
+| `WebGL2Renderer` | `'webgl'` | Post-processing effects (bloom, pixelate, glitch, palette rotation) |
+| `HeadlessRenderer` | — (Node.js only) | Tests, `npm run verify`, `toSVGString()` |
+
+To select a renderer:
+
+```ts
+import { runBrowser, WebGL2Renderer } from '@hayao';
+
+// Built-in string shorthand:
+runBrowser(def, mount, { renderer: 'webgl' });
+
+// Or pass your own configured instance directly via the DOM:
+const renderer = new WebGL2Renderer({ width, height, background,
+  postProcess: `#version 300 es
+    precision mediump float;
+    in vec2 v_uv;
+    uniform sampler2D u_scene;
+    out vec4 fragColor;
+    void main() {
+      // Vignette
+      vec2 uv = v_uv - 0.5;
+      float d = dot(uv, uv);
+      fragColor = texture(u_scene, v_uv) * (1.0 - d * 1.8);
+    }`,
+});
+```
+
+### WebGL2Renderer post-processing
+
+`WebGL2Renderer` rasterizes the full display list via Canvas2D (pixel-exact
+parity with `Canvas2DRenderer`) then passes the frame through a GLSL fragment
+shader. This gives you any full-screen effect in 5 lines of GLSL, without
+touching the display list or the sim.
+
+The fragment shader interface:
+- `in vec2 v_uv` — 0..1 UV with (0,0) at top-left
+- `uniform sampler2D u_scene` — the rasterized frame
+- `out vec4 fragColor` — output pixel
+
+Change the shader at runtime:
+```ts
+// On game handle:
+(handle.renderer as WebGL2Renderer).setPostProcess(shaderSrc);
+(handle.renderer as WebGL2Renderer).clearPostProcess(); // back to passthrough
+```
+
+**Verifiability**: because the renderer is a pure display-list consumer, the
+`HeadlessRenderer` and `SvgRenderer` see the identical `DrawCommand[]` input
+and remain the reference backends for all verify passes. Post-processing effects
+are cosmetic — they are never part of the game's `world.hash()`.
+
 ## Pointer & continuous input
 
 Keyboard actions are the default and the only input that flows through the
@@ -78,6 +143,204 @@ 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.
 
+**Replay-exact analog** (twin-stick aim, analog throttle): pass QUANTIZED axes as
+`world.step(actions, axes)`'s second argument. Those enter `getState()` → hash and
+the input log (`InputRecorder`/`frameAxes`), so `assertDeterministic` and netplay
+reproduce them. Snap at the edge with `snapAxis(v, buckets)` / `quantizeAngle(rad,
+buckets)`. Games that never pass axes keep their pinned hashes byte-for-byte.
+
+**Mouse buttons are actions.** The browser driver wires PointerSource to the
+KeyboardSource, so while a button is held the actions `mouse.left` /
+`mouse.right` / `mouse.middle` are down — bindable in an inputMap
+(`shield: ['mouse.right']`), queryable directly
+(`input.justPressed('mouse.left')`), and replay-exact because they enter the
+same deterministic actionsDown log as keys. The raw 0/1 axes `pointer.right`
+/ `pointer.middle` exist alongside `pointer.down` for analog-style reads. The
+browser context menu is suppressed by default so right-click is usable as game
+input (opt back in via `PointerSourceOptions.contextMenu`).
+
+**Action names, not key codes.** `isDown`/`justPressed`/`justReleased` take
+ACTION names from the input map (`'jump'`), never key codes (`'Space'`). Once
+a host has declared its sources, querying an action no source can produce
+logs a console.warn once per name — so `isDown('jmup')` fails loudly instead
+of silently never firing. (`justReleased` exists and mirrors `justPressed`.)
+
+**Sustained virtual input.** `press()` is a one-shot tap (cleared after one step).
+For an on-screen control that models STATE (held joystick, hold-to-fire), use
+`input.setHeld(action, on)` — it stays in the action set every step until released,
+no re-press-per-frame.
+
+**Multitouch.** `pointer.read()`/`sample()` describe the primary pointer (unchanged).
+For two thumbs at once, `pointer.readAll()` returns every live touch with its stable
+`id`. Or skip the raw layer: **`TouchControls`** (`ui/`, sibling to `Shell`) renders
+floating sticks/buttons and drives the same action set via `setHeld` — a virtual
+gamepad in one declaration. Anchor host-drawn UI to the played area with
+`handle.viewport()` (letterbox rect + scale), never re-derived `getBoundingClientRect`.
+
+**Proving the host layer.** Touch/pointer host code is the one layer sim proofs
+can't see. `bootDom(def)` (`verify/dom`, under jsdom/happy-dom) boots the real
+`runBrowser` wiring, fires synthetic touches, and steps so you assert on `probe()`.
+
+
+## Custom input sources (gamepad, MIDI, accelerometer, …)
+
+The engine's input layer is open-ended: anything that implements `InputSource`
+(`sample(input: InputState) + optional dispose()`) can be plugged in alongside
+the built-in `KeyboardSource` and `PointerSource`.
+
+### Wiring a source into the step loop
+
+Pass sources at start-up — or add them after the handle is returned:
+
+```ts
+import { GamepadSource, DEFAULT_GAMEPAD_MAP } from '@hayao';
+
+// Option A: at start-up
+const handle = runBrowser(def, mount, {
+  sources: [new GamepadSource({ keyboard: handle.input })], // ← needs handle first
+});
+
+// Option B: post-creation (recommended for gamepad — wait for 'gamepadconnected')
+const handle = runBrowser(def, mount);
+window.addEventListener('gamepadconnected', () => {
+  const gamepad = new GamepadSource({ keyboard: handle.input });
+  handle.addSource(gamepad);  // sampled every step; addSource returns a cleanup fn
+});
+```
+
+### Axis naming convention
+
+Use a dotted namespace prefixed by the source name. All hayao built-ins follow:
+
+| Axis key          | Source       | Range  | Notes                           |
+|-------------------|--------------|--------|---------------------------------|
+| `pointer.x`       | PointerSource| design | Design-space x (letterbox-safe) |
+| `pointer.y`       | PointerSource| design | Design-space y                  |
+| `pointer.down`    | PointerSource| 0/1    | Primary pointer pressed         |
+| `gamepad.lx`      | GamepadSource| ±1     | Left stick x (after deadzone)   |
+| `gamepad.ly`      | GamepadSource| ±1     | Left stick y                    |
+| `gamepad.rx`      | GamepadSource| ±1     | Right stick x                   |
+| `gamepad.ry`      | GamepadSource| ±1     | Right stick y                   |
+| `gamepad.lt`      | GamepadSource| 0..1   | Left trigger                    |
+| `gamepad.rt`      | GamepadSource| 0..1   | Right trigger                   |
+| `gamepad.dpad.x`  | GamepadSource| −1/0/1 | D-pad horizontal                |
+| `gamepad.dpad.y`  | GamepadSource| −1/0/1 | D-pad vertical (−1 = up)        |
+
+Custom sources: follow the same dotted convention (`mydev.axis1`, `midi.cc7`).
+
+### When to call sample()
+
+The engine calls `sample(world.input)` once per fixed step, **before**
+`world.advance()`. This mirrors `PointerSource.sample()` in the browser driver.
+Never call `sample()` inside `onUpdate` or from sim code — axes are host-side.
+
+### Determinism rules for custom sources
+
+1. **Quantize at the host edge.** Use `snapAxis(v, buckets)` / `quantizeAngle`
+   before writing to `input.axes`. Unquantized floats differ across machines and
+   across frames when the device hasn't moved — quantized values are stable.
+2. **Axes are live by default** (NOT in `world.hash()` or the input log). This
+   is correct for most uses: the sim reads a "current" value, and replay is
+   driven by the recorded action log, not raw hardware.
+3. **For replay-exact analog** (twin-stick aim, analog throttle): pass the
+   quantized axes as the SECOND argument to `world.step(actions, axes)`. They
+   then enter `getState()` → hash and `InputRecorder` (same as pointer axes in
+   Studio sessions). Only do this if you need bit-exact replay of analog values.
+4. **For discrete input** (button press → action): call
+   `keyboard.setHeld(action, on)` — presses flow through `KeyboardSource.currentActions()`
+   into the SAME deterministic string log as keys and are covered by record/replay
+   and lockstep netplay at zero extra cost. This is what `GamepadSource` does for
+   its `buttonMap`. Prefer `setHeld` over `press()` for buttons: `press()` is a
+   one-shot tap (cleared after one step), `setHeld` models the held/released cycle.
+
+### GamepadSource
+
+`GamepadSource` is the reference implementation of `InputSource`. It polls
+`navigator.getGamepads()` per step and provides:
+
+- **Analog sticks + triggers** as quantized axes (see table above).
+- **D-pad + face buttons + start/select** as deterministic actions via a
+  `GamepadMap` (button index → action name). Defaults match `DEFAULT_INPUT_MAP`
+  so a gamepad works with the keyboard action set out of the box.
+- **Deadzone** with circular magnitude clamping (default 0.12, matching typical
+  hardware drift). Output is remapped to fill the full ±1 range post-deadzone.
+- **Configurable quantization** (`stickBuckets`, `triggerBuckets`).
+
+```ts
+import { GamepadSource, DEFAULT_GAMEPAD_MAP } from '@hayao';
+
+const gamepad = new GamepadSource({
+  keyboard: handle.input,                // required for button→action routing
+  index: 0,                              // gamepad slot (default 0)
+  deadzone: 0.15,                        // override default 0.12
+  stickBuckets: 64,                      // coarser for a grid-based game
+  buttonMap: {
+    ...DEFAULT_GAMEPAD_MAP,
+    6: 'dodge',                          // LT → dodge action
+  },
+});
+const removeGamepad = handle.addSource(gamepad);
+// later: removeGamepad() to dispose and stop sampling
+```
+
+Sim code reads analog axes the same way pointer input is read:
+
+```ts
+player.onUpdate = (n, dt, ctx) => {
+  const lx = ctx.input.axis('gamepad.lx'); // −1..1 after deadzone + quantize
+  const ly = ctx.input.axis('gamepad.ly');
+  // Also check the fallback action for keyboard/dpad parity:
+  const dx = ctx.input.isDown('right') ? 1 : ctx.input.isDown('left') ? -1 : lx;
+  n.pos.x += dx * 200 * dt;
+};
+```
+
+### Building your own InputSource
+
+```ts
+import { InputSource, snapAxis, InputState } from '@hayao';
+
+class AccelerometerSource implements InputSource {
+  private x = 0;
+  private y = 0;
+
+  constructor() {
+    window.addEventListener('devicemotion', (e) => {
+      this.x = e.accelerationIncludingGravity?.x ?? 0;
+      this.y = e.accelerationIncludingGravity?.y ?? 0;
+    });
+  }
+
+  sample(input: InputState): void {
+    // Normalize to ±1, quantize for determinism.
+    input.axes.set('accel.x', snapAxis(this.x / 9.8, 64, -1, 1));
+    input.axes.set('accel.y', snapAxis(this.y / 9.8, 64, -1, 1));
+  }
+}
+
+handle.addSource(new AccelerometerSource());
+// Sim: ctx.input.axis('accel.x')
+```
+
+## Depth & 2.5D (isometric / overlap)
+
+Painter's `z` is the one depth primitive: the renderer stable-sorts by it, ties
+broken by tree order. For any game where sprites overlap (top-down, iso), derive
+`z` from a depth axis instead of hand-setting it per mover:
+
+- **`DepthSort({ key })`** — a container that assigns each child's `z` from an
+  accessor at draw time (positions are final for the frame). `key: (n) => n.pos.y`
+  for top-down overlap; `key: (n) => n.gx + n.gy` for an iso lattice. It removes
+  per-node depth bookkeeping from every overlap game.
+- **`iso({ tileW, tileH, origin })`** — the grid↔screen projection (core, no
+  trig, hash-safe). `toScreen(gx, gy, elev?)` places a cell; `toGrid(sx, sy)`
+  inverts the ground plane so `pointer.x/y` → a tile coord. Use this for picking;
+  `physics/tilemap` is **orthogonal-only** and cannot pick on an iso map.
+- **`IsoPrism({ tileW, tileH, height, fill })`** — a raised tile as three
+  auto-shaded faces (top + two sides), one node instead of three hand-rolled
+  polys. Pairs with `DepthSort` keyed on `gx + gy`.
+- **`diamond` / `regularPoly` shapes** — sugar over `poly` so an iso tile or hex
+  reads as intent, not four re-typed corners.
 
 ## The human-contact layer
 
@@ -146,6 +409,31 @@ 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.
 
+**The dev guard.** Pass `guardDeterminism: true` in the world config and every
+`step()` wraps `Math.random`/`Date.now` so a stray call inside the sim warns
+ONCE with a stack hint (values still flow — nothing breaks mid-frame). It
+never throws, so it is safe to leave on in tests and dev builds. It converts
+"the replay diverged three hours later" into "here is the exact call site, now".
+
+**Cosmetic randomness.** Rule 1 has two escape hatches for pure-view code so
+decoration never perturbs the gameplay stream:
+
+- `world.rng.split(key)` derives an independent child stream — give a cosmetic
+  node its own private `Rng` at construction (Particles and Shaker do this),
+  and its draws stop racing gameplay draws for the same numbers.
+- `hashNoise(...values)` is *stateless* deterministic noise → `[0, 1)`: same
+  inputs, same output, no stream consumed — so it is safe to call from
+  `draw()` for per-entity variation (`hashNoise(i, ctx.frame)` for jitter,
+  phase offsets, hue nudges). Never call `rng.float()` from `draw()`.
+
+**Catch-up steps.** `advance(realMs)` runs as many fixed steps as real time
+demands, clamped at `clock.maxFrameMs` (default 250, with a warn-once when it
+clamps). So the FIRST advance after a stall — tab restored, debugger resumed,
+slow boot — can legitimately run multiple steps at once, and first-frame logic
+that assumes "one advance = one step" (e.g. gravity applied before the floor
+exists) sinks the player. Guard the logic, and in tests never fast-forward
+with a big `advance(ms)` — use `runSteps(n)`, which has no realtime clamp.
+
 ## House style (defaults — swap deliberately, not accidentally)
 
 - **Code-as-art, zero binary assets.** A `Sprite` is a vector `Shape`

package/docs/EMBED.md

@@ -80,6 +80,11 @@ If you prefer modules, inline `dist/index.min.js` as a blob and dynamic-import i
 - **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.
+- **Touch.** These targets (Artifacts, itch, js13k) are largely played on phones.
+  A keyboard game is unplayable there until you add `TouchControls` — a virtual
+  gamepad in one declaration that drives the same action set as keys:
+  `new TouchControls(handle, { left: ['up','down','left','right'], buttons: [{ action: 'fire' }] })`.
+  It only mounts on coarse-pointer devices by default. See CONVENTIONS §Pointer.
 - **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

@@ -119,7 +119,19 @@ can reach is provably winnable — all without opening a browser.
 - **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.
+  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
 

package/docs/VERIFICATION.md

@@ -113,10 +113,40 @@ writeFileSync('shots/title.svg', r.toSVGString());   // a real vector screenshot
 ```
 
 Because rendering is SVG, the screenshot is **resolution-independent and text is
-crisp** — no canvas fuzz, no GPU. In the browser, `?capture=1` exposes
-`window.__hayao` (`pump`, `probe`, `hash`, `shot`, `save`, `key`) for scripted
-sessions and aesthetic captures — but you rarely need it, because the DOM is
-already inspectable and the sim already runs in Node.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hayao",
-  "version": "0.3.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": [
@@ -87,6 +87,7 @@
     "@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",