hayao 0.3.0 → 0.4.0

package/README.md

@@ -199,6 +199,16 @@ pathfinding, procgen, synth, juice) for learning one primitive in isolation.
 of the engine and what generalized lives in
 [docs/BUILDLOG.md](https://github.com/hellojanpacan/hayao-js/blob/main/docs/BUILDLOG.md).
 
+Since v0.3 (on main, toward 0.4.0): a screen-space HUD layer
+(`node.screenSpace`), pause + time scale (`world.paused`/`timeScale`,
+`node.pauseMode`), deterministic generator coroutines, typed `world.state`
+(`defineGame<TState>`), ellipse/arc/lineDash rendering, a ZzFX porting bridge
+(`specFromZzfx`), pointer-button actions, and a built-in hidden-tab ticker —
+driven by the js13k recreation triage in
+[docs/TRIAGE-2026-07-recreations.md](https://github.com/hellojanpacan/hayao-js/blob/main/docs/TRIAGE-2026-07-recreations.md);
+authoring contracts documented in
+[docs/ENGINE.md](https://github.com/hellojanpacan/hayao-js/blob/main/docs/ENGINE.md).
+
 ## License
 
 [MIT](LICENSE) © Jan Pacan

package/bin/create-hayao.mjs

@@ -37,7 +37,7 @@ const files = {
         verify: 'tsx verify.ts',
         build: 'vite build',
       },
-      dependencies: { hayao: '^0.3' },
+      dependencies: { hayao: '^0.4' },
       devDependencies: {
         '@types/node': '^22.10.0',
         tsx: '^4.19.0',

package/dist/app/browser.d.ts

@@ -1,10 +1,11 @@
 import type { CreateWorldOptions, GameDefinition } from './game';
-import { KeyboardSource, PointerSource } from '../input/source';
+import { KeyboardSource, PointerSource, type InputSource } from '../input/source';
 import type { Vec2 } from '../core/math';
-import type { Renderer } from '../render/renderer';
+import type { Renderer, Viewport } from '../render/renderer';
 import type { World } from '../world';
 export interface RunOptions {
-    renderer?: 'svg' | 'canvas';
+    /** Rendering backend. Default 'svg'. Use 'webgl' for post-processing effects. */
+    renderer?: 'svg' | 'canvas' | 'webgl';
     /** Start the pause/settings shell (Esc). Default true. */
     shell?: boolean;
     onRestart?: () => void;
@@ -24,6 +25,13 @@ export interface RunOptions {
      * steps (no pause overlay — Studio's scrubber holds the sim with this).
      */
     isHeld?: () => boolean;
+    /**
+     * Extra input sources (e.g. GamepadSource) sampled each step alongside the
+     * built-in KeyboardSource and PointerSource. Each source's sample() is called
+     * before world.advance(), and dispose() on stop(). You can also add sources
+     * after the handle is returned via GameHandle.addSource().
+     */
+    sources?: InputSource[];
 }
 export interface GameHandle {
     world: World;
@@ -40,10 +48,32 @@ export interface GameHandle {
     canvas: HTMLElement | SVGElement | undefined;
     /** Map a pointer event's clientX/Y to design coordinates (undoes the letterbox). */
     toDesign(clientX: number, clientY: number): Vec2;
+    /** The drawn (letterboxed) area within the mount — anchor host-drawn UI here. */
+    viewport(): Viewport | undefined;
     /** Resolves after preload completes and the first real frame has rendered. */
     ready: Promise<void>;
     /** Run a callback once the game is ready (fires immediately if already ready). */
     onReady(cb: () => void): void;
+    /**
+     * Register an extra input source (e.g. GamepadSource) to be sampled each step
+     * alongside PointerSource. Returns a cleanup function that removes the source
+     * (calling its dispose()) when invoked.
+     *
+     * Typical pattern:
+     *   const handle = runBrowser(def, mount);
+     *   const gamepad = new GamepadSource({ keyboard: handle.input });
+     *   const removeGamepad = handle.addSource(gamepad);
+     */
+    addSource(source: InputSource): () => void;
+    /**
+     * Drive one frame by hand: sample the pointer (and extra sources), advance
+     * the world by dtMs with the currently-held actions, and render — exactly
+     * what the real loop does per frame. Default dtMs is one fixed step's ms.
+     * For headless/tool-driven frame-stepping with visuals updating; the wall-
+     * clock loop keeps running independently (pause the shell or use isHeld to
+     * make tick() the only driver).
+     */
+    tick(dtMs?: number): void;
     stop(): void;
     restart(): void;
 }

package/dist/app/game.d.ts

@@ -19,7 +19,7 @@ export interface SplashConfig {
     /** Keep the splash up at least this long, so a fast preload doesn't flash by. */
     minDurationMs?: number;
 }
-export interface GameDefinition {
+export interface GameDefinition<TState extends Record<string, unknown> = Record<string, unknown>> {
     title: string;
     width?: number;
     height?: number;
@@ -28,9 +28,9 @@ export interface GameDefinition {
     clock?: ClockConfig;
     inputMap?: InputMap;
     /** Build the initial scene tree for a fresh world. */
-    build(world: World): Node;
+    build(world: World<TState>): Node;
     /** Optional compact probe snapshot for verification (defaults to World.probe). */
-    probe?(world: World): Record<string, unknown>;
+    probe?(world: World<TState>): Record<string, unknown>;
     /**
      * Live-tunable parameters, declared once. Defaults ARE the config; Studio and
      * tests override them via `createWorld(def, { tuning })` and the sim reads
@@ -42,18 +42,22 @@ export interface GameDefinition {
      * from data (closures do not survive a restore). One contract serves every
      * carryover path: Studio knob changes, variant toggles, HMR, and net rollback.
      */
-    attach?(world: World): void;
+    attach?(world: World<TState>): void;
     /**
      * Awaited before the world starts stepping — load fonts, sprite atlases, a
      * SoundFont, anything async. The engine holds a splash on screen until it
      * resolves, so there is no asset pop-in and no ungoverned pre-first-frame window.
      */
-    preload?(world: World): Promise<void>;
+    preload?(world: World<TState>): Promise<void>;
     /** Boot splash config, or `false` to start on the first frame with no cover. */
     splash?: SplashConfig | false;
 }
-/** 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;
+/**
+ * Identity + defaults. Kept as a function so games read `export default defineGame({…})`.
+ * Pass a state shape for a typed world: `defineGame<{ score: number }>({ … })`
+ * types `world.state` in build/probe/attach/preload (default keeps untyped calls as-is).
+ */
+export declare function defineGame<TState extends Record<string, unknown> = Record<string, unknown>>(def: GameDefinition<TState>): Required<Pick<GameDefinition<TState>, 'width' | 'height' | 'seed' | 'inputMap' | 'background'>> & GameDefinition<TState>;
 export interface CreateWorldOptions {
     seed?: number;
     /** Overrides for declared tuning knobs (undeclared keys are dropped). */
@@ -63,11 +67,11 @@ export interface CreateWorldOptions {
  * Build a live, deterministic World from a game definition. No browser needed.
  * `opts` as a bare number is the legacy seed override.
  */
-export declare function createWorld(def: GameDefinition, opts?: number | CreateWorldOptions): World;
+export declare function createWorld<TState extends Record<string, unknown> = Record<string, unknown>>(def: GameDefinition<TState>, opts?: number | CreateWorldOptions): World<TState>;
 /** The input map a game uses (with defaults applied). */
 export declare function gameInputMap(def: GameDefinition): InputMap;
-export interface HeadlessResult {
-    world: World;
+export interface HeadlessResult<TState extends Record<string, unknown> = Record<string, unknown>> {
+    world: World<TState>;
     hash: string;
     steps: number;
 }
@@ -76,4 +80,4 @@ export interface HeadlessResult {
  * 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;
+export declare function runHeadless<TState extends Record<string, unknown> = Record<string, unknown>>(def: GameDefinition<TState>, inputLog?: InputLog): HeadlessResult<TState>;

package/dist/audio/audio.d.ts

@@ -17,12 +17,29 @@ export interface Tone {
     pan?: number;
 }
 export declare class AudioBus {
-    private ctx;
+    private _ctx;
     private master;
     private musicGain;
     private sfxGain;
     private vol;
     private padOn;
+    /**
+     * The live AudioContext (null until `start()` unlocks audio). External
+     * synths being ported in (bundled ZzFX/ZzFXM, hand-rolled Web Audio) should
+     * create their sources ON this context — never their own — so they inherit
+     * the autoplay unlock the user gesture already paid for.
+     */
+    get ctx(): AudioContext | null;
+    /**
+     * The SFX mix bus (null until `start()`). Connect external one-shot sources
+     * here instead of `ctx.destination` so master/sfx volume and mute apply.
+     */
+    get sfxBus(): AudioNode | null;
+    /**
+     * The music mix bus (null until `start()`). Connect external music sources
+     * (e.g. a ZzFXM-rendered buffer) here so master/music volume and mute apply.
+     */
+    get musicBus(): AudioNode | null;
     get available(): boolean;
     get started(): boolean;
     /** Must be called from a user gesture (browser autoplay policy). */

package/dist/audio/synth.d.ts

@@ -28,6 +28,13 @@ export interface SoundSpec {
     pitchJumpTime?: number;
     vibrato?: number;
     vibratoFreq?: number;
+    /**
+     * Pitch-envelope repeat period, seconds (ZzFX `repeatTime`). Every `repeat`
+     * seconds the slide/slideAccel/pitchJump progression resets to its start
+     * while the amplitude envelope keeps going — the classic ZzFX stutter/trill.
+     * 0 or absent = off (bit-identical to the pre-`repeat` renderer).
+     */
+    repeat?: number;
     /** Second detuned oscillator, cents (0 = off). Adds unison warmth/chorus. */
     detune?: number;
     /** Sub-oscillator: a sine one octave down, mixed at this level 0..1. Adds weight. */

package/dist/audio/zzfx.d.ts

@@ -0,0 +1,14 @@
+import type { SoundSpec } from './synth';
+/** Test hook: clear the warn-once memory. */
+export declare function resetZzfxWarnings(): void;
+/**
+ * Convert a positional ZzFX parameter array to a hayao SoundSpec.
+ * Argument order (defaults in parens) is ZzFX's `zzfx(...)` signature:
+ * volume(1), randomness(.05), frequency(220), attack(0), sustain(0),
+ * release(.1), shape(0), shapeCurve(1), slide(0), deltaSlide(0), pitchJump(0),
+ * pitchJumpTime(0), repeatTime(0), noise(0), modulation(0), bitCrush(0),
+ * delay(0), sustainVolume(1), decay(0), tremolo(0), filter(0).
+ * Holes/undefined take the ZzFX defaults, so `[,,1675,,.06,.24,1,1.82,,,837,.06]`
+ * pastes straight in.
+ */
+export declare function specFromZzfx(p: readonly (number | undefined)[]): SoundSpec;

package/dist/core/clock.d.ts

@@ -7,7 +7,7 @@ export interface ClockConfig {
 export declare class Clock {
     readonly stepMs: number;
     readonly dt: number;
-    private maxFrameMs;
+    readonly maxFrameMs: number;
     private accumulator;
     private _frame;
     private _simTimeMs;

package/dist/core/projection.d.ts

@@ -0,0 +1,36 @@
+import type { Vec2 } from './math';
+export interface IsoConfig {
+    /** Full width of a tile diamond in screen px (the horizontal diagonal). */
+    tileW: number;
+    /** Full height of a tile diamond in screen px (the vertical diagonal). 2:1 iso ⇒ tileW/2. */
+    tileH: number;
+    /** Screen px where grid cell (0,0)'s CENTER lands. Default (0,0). */
+    origin?: Vec2;
+    /** Screen px a tile rises per unit of elevation. Default tileH (one tile-height per level). */
+    elevStep?: number;
+}
+/**
+ * A parameterised grid↔screen projection. `toScreen` places a (possibly raised)
+ * cell centre; `toGrid` inverts the ground plane (elev 0) to FRACTIONAL grid
+ * coordinates — floor them for the containing tile. Round-trips exactly for
+ * every integer cell. Covers 2:1 iso (tileH = tileW/2), true dimetric, and
+ * top-down/oblique (tileH = tileW) by choice of tile size.
+ */
+export interface IsoProjection {
+    readonly tileW: number;
+    readonly tileH: number;
+    readonly origin: Vec2;
+    readonly elevStep: number;
+    /** Grid cell → screen-space centre. `elev` shifts the point up by `elevStep` per unit. */
+    toScreen(gx: number, gy: number, elev?: number): Vec2;
+    /** Screen point → fractional grid coords on the ground plane (floor for the tile). */
+    toGrid(sx: number, sy: number): Vec2;
+}
+/**
+ * Build an isometric/dimetric/oblique projection. Diamond lattice:
+ *   screenX = origin.x + (gx - gy) · tileW/2
+ *   screenY = origin.y + (gx + gy) · tileH/2 − elev · elevStep
+ * The inverse solves the 2×2 system directly, so `toGrid(toScreen(g)) === g` for
+ * all integer cells (no accumulated float drift).
+ */
+export declare function iso(cfg: IsoConfig): IsoProjection;

package/dist/core/rng.d.ts

@@ -34,5 +34,14 @@ export declare class Rng {
     getState(): RngState;
     setState(state: RngState): void;
 }
+/**
+ * Stateless deterministic noise: hash any mix of numbers to a float in [0,1).
+ * Same inputs ALWAYS give the same output and no stream is consumed, so it is
+ * safe to call from `draw()` for per-entity cosmetic variation (jitter, phase
+ * offsets, hue nudges) — `hashNoise(entity.id, ctx.frame)` never touches
+ * `world.rng` and cannot desync a replay. Mixes the full float bits of each
+ * value through a strong integer hash (murmur3-style avalanche).
+ */
+export declare function hashNoise(...values: number[]): number;
 /** Deterministic 32-bit FNV-1a hash of a string — handy for stable ids/seeds. */
 export declare function hashString(str: string): number;