hayao 0.3.0 → 0.4.1

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/anim/blend.d.ts

@@ -0,0 +1,68 @@
+import { type ClipDef } from './clip';
+/** A sampled pose: "target/channel" → value. Plain object; order-insensitive. */
+export type Pose = Record<string, number>;
+/** Compose a pose key from a track's target + channel. */
+export declare const poseKey: (target: string, channel: string) => string;
+/**
+ * Sample a whole clip into a Pose at NORMALIZED phase `phase` in [0,1) — the
+ * blend-space entry point. `phase * duration` is the clip-local time (so two
+ * clips of different length stay in step). Pure; allocates one fresh Pose.
+ */
+export declare function samplePose(def: ClipDef, phase: number): Pose;
+/**
+ * Linear blend of two poses: `out[k] = lerp(a[k], b[k], t)`. Keys present in only
+ * one pose pass through unblended (the other side has no opinion). When `out` is
+ * supplied it is reused (cleared then filled) — the allocation-free path
+ * ClipPlayer takes during a crossfade. Returns `out`.
+ */
+export declare function mixPose(a: Pose, b: Pose, t: number, out?: Pose): Pose;
+/** One entry of a blend space: a clip pinned at a parameter position. */
+export interface BlendSample {
+    clip: ClipDef;
+    /** Parameter position of this sample (e.g. speed). Blend1D reads `.x` only. */
+    x: number;
+    /** Second parameter (Blend2D only). */
+    y?: number;
+}
+/**
+ * A 1-D blend space (e.g. idle→walk→run along speed). Samples are sorted by `x`
+ * on construction; `sample(param, phase)` finds the bracketing pair and mixes
+ * them by the normalized distance, all clips sampled at the SAME phase (foot-lock).
+ * Below the first / above the last sample it clamps to the end clip.
+ */
+export declare class Blend1D {
+    readonly samples: BlendSample[];
+    constructor(samples: BlendSample[]);
+    /** The clip weights at parameter `param` (sums to 1; empty space → {}). */
+    weights(param: number): {
+        clip: ClipDef;
+        weight: number;
+    }[];
+    /** Blend the neighbor clips at `param`, all sampled at normalized `phase`. */
+    sample(param: number, phase: number): Pose;
+}
+/**
+ * A 2-D blend space (e.g. a locomotion pad: forward/back × left/right). No
+ * triangulation library — we pick the NEAREST THREE samples to the query point
+ * and blend them barycentrically; if the point is outside their triangle the
+ * barycentric weights are clamped to >= 0 and renormalized (a documented
+ * approximation: no Delaunay, so a sparse/concave set can pick a non-ideal trio).
+ */
+export declare class Blend2D {
+    readonly samples: Required<BlendSample>[];
+    constructor(samples: BlendSample[]);
+    /** Clip weights at (px,py): nearest-3 barycentric, clamped + renormalized. */
+    weights(px: number, py: number): {
+        clip: ClipDef;
+        weight: number;
+    }[];
+    private barycentric;
+    /** Blend the nearest-3 clips at (px,py), all sampled at normalized `phase`. */
+    sample(px: number, py: number, phase: number): Pose;
+}
+/**
+ * Validate a blend space's samples (levelIssues idiom). Catches empty spaces,
+ * duplicate parameter positions (a degenerate bracket / triangle), and non-finite
+ * coordinates. `dims` selects which axes must be finite.
+ */
+export declare function blendIssues(samples: BlendSample[], dims?: 1 | 2): string[];

package/dist/anim/clip.d.ts

@@ -0,0 +1,87 @@
+import { EASINGS } from '../scene/tween';
+/** Which transform channel a track drives. */
+export type ClipChannel = 'x' | 'y' | 'rotation' | 'scaleX' | 'scaleY' | 'opacity';
+export declare const CLIP_CHANNELS: readonly ClipChannel[];
+/** How the playhead behaves past `duration`. */
+export type ClipLoop = 'loop' | 'once' | 'pingpong';
+/** One keyframe: value `v` at time `t` (seconds), with the ease used to reach it FROM the previous key. */
+export interface Keyframe {
+    t: number;
+    v: number;
+    /** EASINGS name applied over the segment ENDING at this key. Default 'linear'. */
+    ease?: keyof typeof EASINGS;
+}
+/** One track: a channel of one target node, driven by an ordered keyframe list. */
+export interface TrackDef {
+    /** '/'-separated path from the rig root to the target node (matched by Node.name). */
+    target: string;
+    channel: ClipChannel;
+    /** Keyframes, ascending in `t`. At least one. */
+    keys: Keyframe[];
+}
+/** A discrete event fired as the playhead crosses `t` (half-open (t0,t1] window). */
+export interface ClipEvent {
+    t: number;
+    name: string;
+}
+/** A full clip: duration, loop mode, tracks, optional events. Plain data. */
+export interface ClipDef {
+    /** Clip length in seconds (> 0). */
+    duration: number;
+    loop: ClipLoop;
+    tracks: TrackDef[];
+    events?: ClipEvent[];
+    /** RESERVED — root motion is not implemented (see file header). */
+    rootMotion?: never;
+}
+/**
+ * Map a raw elapsed time to a clip-local time in [0, duration], honoring the
+ * loop mode. `once` clamps at both ends; `loop` wraps; `pingpong` folds so the
+ * playhead ping-pongs 0→d→0. Pure and total (guards duration <= 0 → 0).
+ */
+export declare function clipTime(def: ClipDef, elapsed: number): number;
+/** True once a `once` clip has run past its end (used by ClipPlayer to fire `finished`). */
+export declare function clipFinished(def: ClipDef, elapsed: number): boolean;
+/**
+ * Binary-search the keyframe segment containing local time `t` and return the
+ * eased-interpolated value. Before the first key → first value; after the last →
+ * last value (clips are sampled at a clamped clipTime, so this only bites at the
+ * exact ends). Allocation-free: no array building, no closures.
+ */
+export declare function sampleTrack(keys: Keyframe[], t: number): number;
+/**
+ * A sampled pose channel: which target/channel and the value. `sampleClip`
+ * returns one per track. Kept flat (not a nested object) so ClipPlayer can bind
+ * each to a resolved node once and apply in O(tracks) with no lookups.
+ */
+export interface SampledChannel {
+    target: string;
+    channel: ClipChannel;
+    value: number;
+}
+/**
+ * PURE sample of the whole clip at raw `elapsed` seconds → one SampledChannel per
+ * track. Never mutates `def`. Two calls with the same args are deep-equal. This
+ * is the reference sampler; ClipPlayer uses a prebound, allocation-free variant
+ * of the same math for the hot path.
+ */
+export declare function sampleClip(def: ClipDef, elapsed: number): SampledChannel[];
+/**
+ * Events crossed as the playhead advances from raw `prev` to raw `next`, in the
+ * order they fire. FIXED SEMANTICS:
+ *  - half-open window `(t0, t1]` in clip-local time (an event exactly at the new
+ *    time fires; one exactly at the old time does NOT re-fire);
+ *  - `loop` wrap emits the TAIL segment (prevLocal, duration] then the HEAD
+ *    segment (0, nextLocal];
+ *  - `once` never re-fires an event once the playhead is at/after duration;
+ *  - order within a segment is ascending by `t`, tail before head on a wrap.
+ * Pure; returns event names in fire order.
+ */
+export declare function clipEvents(def: ClipDef, prev: number, next: number): string[];
+/**
+ * Validate a clip's DATA, in the levelIssues/tuningIssues idiom: return ALL
+ * problems as human-readable strings (empty = clean), never throw. Optionally
+ * pass the set of valid target paths (`knownTargets`) to catch tracks that point
+ * at a node the rig doesn't contain.
+ */
+export declare function clipIssues(def: ClipDef, knownTargets?: readonly string[]): string[];

package/dist/anim/ik.d.ts

@@ -0,0 +1,40 @@
+import type { Vec2 } from '../core/math';
+/** Result of a 2-bone solve: absolute WORLD-space angles (radians) for each joint. */
+export interface TwoBoneResult {
+    /** Absolute angle of bone 0 (root→mid). */
+    angle0: number;
+    /** Absolute angle of bone 1 (mid→end). */
+    angle1: number;
+    /** True if the target was in range; false → chain clamped to full extension toward it. */
+    reachable: boolean;
+}
+/**
+ * Analytic two-bone IK. `root` is the base joint (world), `l0`/`l1` the bone
+ * lengths, `target` the desired end-effector position (world). `bendDir` is +1
+ * or −1 to choose which side the middle joint bends to (elbow up/down). Returns
+ * the two ABSOLUTE bone angles (add to nothing — they are world angles; convert
+ * to local by subtracting the parent's world angle at the call site).
+ */
+export declare function solveTwoBoneIK(root: Vec2, l0: number, l1: number, target: Vec2, bendDir?: 1 | -1): TwoBoneResult;
+export interface FabrikResult {
+    /** Joint positions (world), joints[0] === root, joints[n] === end effector. */
+    joints: Vec2[];
+    /** Absolute bone angles (radians), one per bone (length joints.length - 1). */
+    angles: number[];
+    reachable: boolean;
+    /** Iterations actually run before convergence (or the cap). */
+    iterations: number;
+}
+/**
+ * FABRIK N-bone solver. `root` anchors joint 0; `lengths` are the bone lengths
+ * (n bones → n+1 joints); `target` is the desired end position. Alternates a
+ * backward reach (pull the end to the target, propagate inward) and a forward
+ * reach (pin the root, propagate outward) until the end is within `tolerance` of
+ * the target or `maxIter` is hit. When the target is unreachable the chain is
+ * laid out straight toward it (reachable=false). Pure; deterministic (dmath).
+ */
+export declare function solveFabrik(root: Vec2, lengths: number[], target: Vec2, opts?: {
+    maxIter?: number;
+    tolerance?: number;
+    initial?: Vec2[];
+}): FabrikResult;

package/dist/anim/skeleton.d.ts

@@ -0,0 +1,64 @@
+import { Node, type NodeConfig } from '../scene/node';
+import type { ClipChannel, ClipDef, Keyframe } from './clip';
+export interface Bone2DConfig extends NodeConfig {
+    /** Bone reach in local px (root→tip along +x at rotation 0). Default 0. */
+    length?: number;
+}
+/**
+ * A rig joint: a Node with a `length`. Rotation is the joint angle; children
+ * inherit the transform, so a chain of Bone2Ds nested tip-to-root forms a limb.
+ * Registered (`Bone2D`) so a serialized rig round-trips — `length` persists.
+ */
+export declare class Bone2D extends Node {
+    readonly type = "Bone2D";
+    /** Reach in local px along +x. Used by IK, skinning, and the debug overlay. */
+    length: number;
+    constructor(config?: Bone2DConfig);
+    /** Tip position in LOCAL space (root is the node origin; tip is `length` along +x). */
+    get tip(): {
+        x: number;
+        y: number;
+    };
+    protected serializeProps(): Record<string, unknown>;
+    applyProps(props: Record<string, unknown>): void;
+}
+/**
+ * An index of a rig subtree: '/'-separated name path → node. Paths are relative
+ * to the rig root passed to `buildSkeleton` (the root itself is '' and its direct
+ * children are just their names). Ordered iteration only (a plain Map, built by a
+ * deterministic DFS).
+ */
+export declare class Skeleton {
+    readonly root: Node;
+    readonly byPath: Map<string, Node>;
+    constructor(root: Node);
+    private index;
+    /** Resolve a track/IK target path to a node (null if the rig lacks it). */
+    resolve(path: string): Node | null;
+    /** All target paths in the rig — feed to `clipIssues(def, skeleton.targets())`. */
+    targets(): string[];
+    /** Only the Bone2D joints, by path (for IK / skinning). */
+    bones(): Bone2D[];
+}
+/** Build a skeleton index from a rig root. */
+export declare function buildSkeleton(root: Node): Skeleton;
+/**
+ * A track prebound to its target node: the resolved Node, the channel, and the
+ * clip's keyframes captured by reference. ClipPlayer holds an array of these and
+ * applies each with a single write in the hot path — no path lookup, no find().
+ */
+export interface BoundTrack {
+    node: Node;
+    channel: ClipChannel;
+    keys: Keyframe[];
+    /** The track's path, kept for diagnostics / rebind. */
+    target: string;
+}
+/**
+ * Resolve every track of a clip against a skeleton ONCE. Tracks whose target the
+ * rig doesn't contain are dropped (surfaced separately by clipIssues) so the hot
+ * path never guards for a null node. Returns bound tracks in clip order.
+ */
+export declare function resolveTracks(def: ClipDef, skeleton: Skeleton): BoundTrack[];
+/** Apply one channel's value to a node's transform (the single hot-path write). */
+export declare function applyChannel(node: Node, channel: ClipChannel, value: number): void;

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;