hayao 0.2.0 → 0.3.0

package/docs/VERIFICATION.md

@@ -0,0 +1,226 @@
+# 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. 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.
+
+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.3.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,36 @@
   "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",
+    "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",