hayao 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Pacan (hellojanpacan)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# hayao.js
+
+[![ci](https://github.com/hellojanpacan/hayao-js/actions/workflows/ci.yml/badge.svg)](https://github.com/hellojanpacan/hayao-js/actions/workflows/ci.yml)
+
+**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.
+
+## The one idea
+
+> The game is a pure, deterministic function of its inputs. Rendering, audio,
+> and the browser are **observer plugins**: they watch that function and paint
+> what it produces, but they can never change its result.
+
+```
+state₀ ──step(inputs₀)──▶ state₁ ──step(inputs₁)──▶ state₂ ──▶ …
+```
+
+Hold that invariant and every hard problem for an AI author collapses:
+
+| Normally hard for an AI | Why it's easy here |
+|---|---|
+| "Does my game work?" | `world.step()` runs in Node. Assert on state. No browser, no pixels. |
+| "Is this level winnable?" | `step()` is a pure transition → BFS/DFS search proves it. |
+| "Did my refactor change behavior?" | Replay recorded inputs, compare `world.hash()`. Identical or it's a bug. |
+| "Undo / time-travel / replay" | `world.snapshot()` / `world.restore()`, or replay the input log. Free. |
+| "Testing a canvas game is opaque" | Rendering is a *projection* of state; the sim never needed the canvas. |
+
+## Quickstart
+
+```sh
+npm install
+npm run dev      # vite dev server (hub + examples, MPA mode)
+npm test         # vitest (headless, runs in Node)
+npm run build    # tsc -b && vite build
+npm run check    # tsc --noEmit — typecheck only
+npm run verify   # run the determinism + solver harness over all examples
+```
+
+A game is one folder under `examples/<slug>/`, imports **only** from `@hayao`,
+and is a `defineGame()` call. See [docs/CONVENTIONS.md](docs/CONVENTIONS.md).
+
+## The layers
+
+Everything is one npm package behind a single barrel — **`@hayao`**. Games
+import only from there; the internals are swappable behind it and the whole
+public surface is greppable in one file (`src/index.ts`).
+
+| Layer | Modules | Role |
+|---|---|---|
+| **app/** | `runBrowser` (rAF loop) · `runHeadless` | plugs the kernel into a host |
+| **ui/** | DOM overlays: menus, HUD, pause/settings shell | observer (never mutates sim) |
+| **render/** | display list → `SvgRenderer` \| `Canvas2DRenderer` \| `HeadlessRenderer` | observer (projection → paint) |
+| **audio/** | procedural Web Audio bus (no-op in Node) | observer |
+| **verify/** | probes · replay · `assertDeterministic` · solver | the AI-first harness |
+| **scene/** | `Node`, `Node2D`, `Sprite`, `Text`, `Camera2D`, `Timer`, `AnimationPlayer`, behaviors | **THE STATE** |
+| **input/** | action map · per-step sampling · record / replay | deterministic |
+| **core/** | `Rng` · `Clock` · `EventBus` · `World` · state hash | **THE KERNEL** (headless, pure) |
+
+`core + scene + input` are **deterministic and run in Node**. `render + audio +
+ui + app` are the browser-only observer shell. Break that boundary and the
+verification harness stops being able to prove anything.
+
+## Why not Godot or a raw canvas engine?
+
+Godot's authoring model (nodes, signals, scenes, resources, input actions,
+tweens) is *excellent* — so hayao borrows it wholesale. But Godot's interface is
+GUIs, binary scenes, and a bespoke language, all opaque to an LLM; hayao keeps
+the model and makes every part **text, typed, greppable, and headlessly
+verifiable**. Canvas engines couple the sim to the render loop and the browser;
+hayao decouples them so the sim is a pure function you can test in Node. Full
+reasoning in [docs/ENGINE.md](docs/ENGINE.md).
+
+## Documentation
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — the authoritative design and the determinism contract.
+- [docs/CONVENTIONS.md](docs/CONVENTIONS.md) — how games are structured, house style, definition of done.
+- [docs/VERIFICATION.md](docs/VERIFICATION.md) — the two verification channels; how to prove a game correct.
+- [docs/ENGINE.md](docs/ENGINE.md) — why a custom engine, and when NOT to use one.
+- [docs/LESSONS.md](docs/LESSONS.md) — transferable lessons from real LLM-authored game builds.
+- [docs/FRICTION.md](docs/FRICTION.md) — process-lesson log: what fought an AI session and what check/doc now prevents it.
+- [AGENTS.md](AGENTS.md) — the operating manual for an AI author working in this repo.
+
+## Status
+
+**v0.1 — complete and verified.** All layers are implemented and tested:
+`core/`, `scene/`, `input/`, `render/` (SVG + Canvas2D + headless backends),
+`audio/`, `ui/`, `verify/`, and `app/`. The flagship **Sokoban** example
+(`examples/sokoban/`) is solver-proven winnable on every level and plays in the
+browser. 40 tests pass; `npm run check`, `npm run verify`, and `npm run build`
+are all green. Roadmap: more node types (physics bodies, particles), an ECS
+option for large entity counts, additional example genres, and asset-free audio
+tracks. Contributions welcome.
+
+## License
+
+[MIT](LICENSE) © Jan Pacan

package/dist/app/browser.d.ts

@@ -0,0 +1,19 @@
+import type { GameDefinition } from './game';
+import { KeyboardSource } from '../input/source';
+import type { Renderer } from '../render/renderer';
+import type { World } from '../world';
+export interface RunOptions {
+    renderer?: 'svg' | 'canvas';
+    /** Start the pause/settings shell (Esc). Default true. */
+    shell?: boolean;
+    onRestart?: () => void;
+}
+export interface GameHandle {
+    world: World;
+    renderer: Renderer;
+    /** The live input source — game UI calls input.press('action') for buttons. */
+    input: KeyboardSource;
+    stop(): void;
+    restart(): void;
+}
+export declare function runBrowser(def: GameDefinition, mount: HTMLElement, opts?: RunOptions): GameHandle;

package/dist/app/game.d.ts

@@ -0,0 +1,34 @@
+import { World } from '../world';
+import type { Node } from '../scene/node';
+import { type InputLog, type InputMap } from '../input/actions';
+import type { ClockConfig } from '../core/clock';
+export interface GameDefinition {
+    title: string;
+    width?: number;
+    height?: number;
+    seed?: number;
+    background?: string;
+    clock?: ClockConfig;
+    inputMap?: InputMap;
+    /** Build the initial scene tree for a fresh world. */
+    build(world: World): Node;
+    /** Optional compact probe snapshot for verification (defaults to World.probe). */
+    probe?(world: World): Record<string, unknown>;
+}
+/** Identity + defaults. Kept as a function so games read `export default defineGame({…})`. */
+export declare function defineGame(def: GameDefinition): Required<Pick<GameDefinition, 'width' | 'height' | 'seed' | 'inputMap' | 'background'>> & GameDefinition;
+/** Build a live, deterministic World from a game definition. No browser needed. */
+export declare function createWorld(def: GameDefinition, seedOverride?: number): World;
+/** The input map a game uses (with defaults applied). */
+export declare function gameInputMap(def: GameDefinition): InputMap;
+export interface HeadlessResult {
+    world: World;
+    hash: string;
+    steps: number;
+}
+/**
+ * Run a game to completion in Node with no host — play an input log (or zero
+ * steps) and return the final world + state hash. This is what tests, the CI
+ * verifier, and replays call. The browser is never involved.
+ */
+export declare function runHeadless(def: GameDefinition, inputLog?: InputLog): HeadlessResult;

package/dist/art/palette.d.ts

@@ -0,0 +1,20 @@
+export interface Palette {
+    name: string;
+    bg: string;
+    ink: string;
+    inkSoft: string;
+    line: string;
+    accent: string;
+    accent2: string;
+    good: string;
+    warn: string;
+    /** A small ordered ramp for categorical fills. */
+    ramp: string[];
+}
+export declare const MEADOW: Palette;
+export declare const DUSK: Palette;
+export declare const PAPER: Palette;
+export declare const PALETTES: Record<string, Palette>;
+/** Blend two hex colors (t in [0,1]). Deterministic, no allocations of note. */
+export declare function mix(a: string, b: string, t: number): string;
+export declare function withAlpha(hex: string, alpha: number): string;

package/dist/art/shapes.d.ts

@@ -0,0 +1,12 @@
+import type { Rng } from '../core/rng';
+import { type Vec2 } from '../core/math';
+/** Regular polygon points (flat [x,y,…]) centered at origin. */
+export declare function regularPolygon(sides: number, radius: number, rotation?: number): number[];
+/** Star with alternating outer/inner radii. */
+export declare function star(points: number, outer: number, inner: number, rotation?: number): number[];
+/** An organic blob outline as an SVG path (deterministic given the Rng). */
+export declare function blobPath(rng: Rng, radius: number, wobble?: number, lobes?: number): string;
+/** Convert a point list into a smooth closed path (Catmull-Rom → cubic Bézier). */
+export declare function smoothClosedPath(points: Vec2[], tension?: number): string;
+/** Smooth open path through points (for trails, curves). */
+export declare function smoothOpenPath(points: Vec2[], tension?: number): string;

package/dist/audio/audio.d.ts

@@ -0,0 +1,42 @@
+export interface Volumes {
+    master: number;
+    music: number;
+    sfx: number;
+    muted: boolean;
+}
+/** A single zzfx-ish tone spec. */
+export interface Tone {
+    freq: number;
+    duration: number;
+    type?: OscillatorType;
+    gain?: number;
+    delay?: number;
+}
+export declare class AudioBus {
+    private ctx;
+    private master;
+    private musicGain;
+    private sfxGain;
+    private vol;
+    private padOn;
+    get available(): boolean;
+    get started(): boolean;
+    /** Must be called from a user gesture (browser autoplay policy). */
+    start(): void;
+    setVolumes(v: Partial<Volumes>): void;
+    getVolumes(): Volumes;
+    private applyVolumes;
+    /** Play a single tone (no-op if audio unstarted). */
+    tone(spec: Tone): void;
+    /** Play a sequence of tones as an arpeggio/chord. */
+    play(tones: Tone[]): void;
+    /** Convenience SFX. */
+    blip(freq?: number): void;
+    chime(): void;
+    success(): void;
+    thud(): void;
+    /** Start a soft evolving ambient pad on the music bus. */
+    startAmbient(root?: number, voices?: number[]): void;
+}
+/** Shared default bus. */
+export declare const audio: AudioBus;

package/dist/core/clock.d.ts

@@ -0,0 +1,37 @@
+export interface ClockConfig {
+    /** Simulation rate in Hz (steps per second). Default 60. */
+    hz?: number;
+    /** Max real ms consumed per advance, to avoid a spiral of death. Default 250. */
+    maxFrameMs?: number;
+}
+export declare class Clock {
+    readonly stepMs: number;
+    readonly dt: number;
+    private maxFrameMs;
+    private accumulator;
+    private _frame;
+    private _simTimeMs;
+    constructor(config?: ClockConfig);
+    /**
+     * Feed real elapsed ms; returns how many fixed steps to run now.
+     * Caller runs the sim exactly that many times.
+     */
+    advance(realMs: number): number;
+    /** Called by the World once per executed step to keep counters honest. */
+    tick(): void;
+    /** Interpolation alpha in [0,1) for smooth rendering between fixed steps. */
+    get alpha(): number;
+    get frame(): number;
+    get simTimeMs(): number;
+    get simTimeSec(): number;
+    getState(): {
+        accumulator: number;
+        frame: number;
+        simTimeMs: number;
+    };
+    setState(s: {
+        accumulator: number;
+        frame: number;
+        simTimeMs: number;
+    }): void;
+}

package/dist/core/events.d.ts

@@ -0,0 +1,23 @@
+export type Listener<T> = (payload: T) => void;
+export declare class Signal<T = void> {
+    private listeners;
+    connect(fn: Listener<T>): () => void;
+    once(fn: Listener<T>): () => void;
+    disconnect(fn: Listener<T>): void;
+    emit(payload: T): void;
+    get count(): number;
+    clear(): void;
+}
+/**
+ * A named event bus for cross-cutting game events, keyed by an event map so
+ * payloads are typed. Prefer node-local Signals for local wiring; use the bus
+ * for global concerns (score changed, level complete, sound cue).
+ */
+export declare class EventBus<Events extends Record<string, unknown>> {
+    private signals;
+    private signalFor;
+    on<K extends keyof Events>(key: K, fn: Listener<Events[K]>): () => void;
+    once<K extends keyof Events>(key: K, fn: Listener<Events[K]>): () => void;
+    emit<K extends keyof Events>(key: K, payload: Events[K]): void;
+    clear(): void;
+}

package/dist/core/hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Walk a value in a canonical order (object keys sorted) and fold it into a
+ * 64-bit-ish FNV-1a hash represented as an 8-char hex string. Stable across runs
+ * for structurally identical data.
+ */
+export declare function hashValue(value: unknown): string;

package/dist/core/math.d.ts

@@ -0,0 +1,44 @@
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export declare const vec2: (x?: number, y?: number) => Vec2;
+export declare const vadd: (a: Vec2, b: Vec2) => Vec2;
+export declare const vsub: (a: Vec2, b: Vec2) => Vec2;
+export declare const vscale: (a: Vec2, s: number) => Vec2;
+export declare const vdot: (a: Vec2, b: Vec2) => number;
+export declare const vlen: (a: Vec2) => number;
+export declare const vdist: (a: Vec2, b: Vec2) => number;
+export declare function vnorm(a: Vec2): Vec2;
+export declare const clamp: (v: number, lo: number, hi: number) => number;
+export declare const lerp: (a: number, b: number, t: number) => number;
+export declare const invLerp: (a: number, b: number, v: number) => number;
+export declare const remap: (v: number, a0: number, a1: number, b0: number, b1: number) => number;
+export declare const TAU: number;
+export declare const deg2rad: (d: number) => number;
+export declare const rad2deg: (r: number) => number;
+/** Axis-aligned rectangle. */
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare function rectContains(r: Rect, p: Vec2): boolean;
+export declare function rectsOverlap(a: Rect, b: Rect): boolean;
+/** 2D affine transform as a 6-value matrix [a b c d e f] (like SVG/Canvas). */
+export interface Transform {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
+export declare const IDENTITY: Transform;
+export declare function composeTransform(m: Transform, n: Transform): Transform;
+/** Build a transform from position, rotation (radians), scale. */
+export declare function makeTransform(pos: Vec2, rotation: number, scale: Vec2): Transform;
+export declare function applyTransform(m: Transform, p: Vec2): Vec2;
+/** Invert an affine transform (returns identity if singular). */
+export declare function invertTransform(m: Transform): Transform;

package/dist/core/rng.d.ts

@@ -0,0 +1,38 @@
+export interface RngState {
+    s: [number, number, number, number];
+}
+export declare class Rng {
+    private s0;
+    private s1;
+    private s2;
+    private s3;
+    constructor(seed?: number | RngState);
+    /** Raw 32-bit unsigned integer. */
+    private next;
+    private rotl;
+    /** Float in [0, 1). */
+    float(): number;
+    /** Float in [lo, hi). */
+    range(lo: number, hi: number): number;
+    /** Integer in [0, n). */
+    int(n: number): number;
+    /** Integer in [lo, hi] inclusive. */
+    intRange(lo: number, hi: number): number;
+    /** True with probability p. */
+    chance(p: number): boolean;
+    /** Uniform element of an array. */
+    pick<T>(arr: readonly T[]): T;
+    /** In-place Fisher–Yates shuffle (deterministic). */
+    shuffle<T>(arr: T[]): T[];
+    /**
+     * Derive an independent child stream. Same parent state + same key always
+     * yields the same child — so subsystems (enemy AI, loot, terrain) get stable,
+     * decorrelated randomness without threading one generator through everything.
+     */
+    split(key?: number): Rng;
+    /** Serialize / restore for saves and replay. */
+    getState(): RngState;
+    setState(state: RngState): void;
+}
+/** Deterministic 32-bit FNV-1a hash of a string — handy for stable ids/seeds. */
+export declare function hashString(str: string): number;

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+export * from './core/math';
+export * from './core/rng';
+export * from './core/clock';
+export * from './core/events';
+export * from './core/hash';
+export * from './scene/node';
+export { Node as Node2D } from './scene/node';
+export * from './scene/nodes';
+export * from './scene/tween';
+export * from './scene/particles';
+export * from './scene/registry';
+export * from './input/actions';
+export * from './input/source';
+export * from './physics/tilemap';
+export * from './physics/aabb';
+export * from './physics/platformer';
+export * from './physics/spatialHash';
+export * from './physics/raycast';
+export * from './render/commands';
+export * from './render/renderer';
+export * from './render/svgString';
+export * from './render/svg';
+export * from './render/canvas';
+export * from './render/headless';
+export * from './art/palette';
+export * from './art/shapes';
+export * from './audio/audio';
+export * from './ui/overlay';
+export * from './ui/settings';
+export * from './ui/shell';
+export * from './verify/solver';
+export * from './verify/determinism';
+export * from './verify/playthrough';
+export * from './verify/capture';
+export * from './verify/driver';
+export * from './verify/bot';
+export * from './verify/feel';
+export * from './verify/filmstrip';
+export * from './world';
+export * from './app/game';
+export * from './app/browser';
+/** Engine version. */
+export declare const VERSION = "0.1.0";