hayao 0.3.0 → 0.4.1

package/dist/scene/skeletonDebug.d.ts

@@ -0,0 +1,28 @@
+import { type Transform } from '../core/math';
+import type { DrawCommand } from '../render/commands';
+import { Node, type NodeConfig } from './node';
+export interface SkeletonDebugConfig extends NodeConfig {
+    /** The rig root to visualize. Defaults to the node's parent. */
+    rig?: Node;
+    /** Bone segment color. Default '#e0483b'. */
+    boneColor?: string;
+    /** Joint pivot color. Default '#f4d35e'. */
+    pivotColor?: string;
+    /** Joint circle radius, px. Default 3. */
+    pivotRadius?: number;
+    /** Bone stroke width, px. Default 2. */
+    strokeWidth?: number;
+}
+/** Draws a rig's bones + pivots as transient overlay commands. Cosmetic. */
+export declare class SkeletonDebug extends Node {
+    readonly type = "SkeletonDebug";
+    rig: Node | null;
+    boneColor: string;
+    pivotColor: string;
+    pivotRadius: number;
+    strokeWidth: number;
+    constructor(config?: SkeletonDebugConfig);
+    protected onReady(): void;
+    protected draw(out: DrawCommand[], _world: Transform): void;
+    private emitFor;
+}

package/dist/scene/verletChain.d.ts

@@ -0,0 +1,76 @@
+import { type Transform, type Vec2 } from '../core/math';
+import type { DrawCommand } from '../render/commands';
+import { Node, type NodeConfig } from './node';
+export interface VerletChainConfig extends NodeConfig {
+    /** Number of segments (points = segments + 1). */
+    segments: number;
+    /** Total rest length of the chain, px. */
+    length: number;
+    /** Acceleration applied to free points, px/s² in WORLD space (+y is down). */
+    gravity?: Vec2;
+    /** Per-step velocity retention 0..1 (1 = undamped). Default 0.985. */
+    damping?: number;
+    /** Constraint-relaxation passes per step. Default 3. */
+    iterations?: number;
+    /** Pin the tail too (set `tailTarget` for where). Default false. */
+    pinTail?: boolean;
+    /** Stroke color for draw(). Default '#333'. */
+    stroke?: string;
+    /** Stroke width at the head, px. Default 3. */
+    strokeWidth?: number;
+    /** Taper the stroke toward the tail (draws per-segment polys). Default false. */
+    taper?: boolean;
+}
+/**
+ * The rope node. Read `points` (node-local) to attach child sprites along the
+ * chain, `segmentAngle(i)` to orient them, and call `impulse(v)` to flick it.
+ */
+export declare class VerletChain extends Node {
+    readonly type: string;
+    gravity: Vec2;
+    damping: number;
+    iterations: number;
+    pinTail: boolean;
+    stroke: string;
+    strokeWidth: number;
+    taper: boolean;
+    /**
+     * Where the tail is pinned when `pinTail` is true, in NODE-LOCAL space
+     * (same space as `points`). null leaves the tail free even with pinTail set.
+     */
+    tailTarget: Vec2 | null;
+    readonly segments: number;
+    /** Rest length of one segment. */
+    readonly segmentLength: number;
+    private px;
+    private py;
+    private prevx;
+    private prevy;
+    /** Node-local mirror of the sim points, updated after each step. */
+    private readonly local;
+    private initialized;
+    private impX;
+    private impY;
+    constructor(config: VerletChainConfig);
+    /**
+     * Chain points in NODE-LOCAL space, head first (`points[0]` ≈ {0,0}).
+     * The Vec2 objects are reused across steps — read, don't retain copies-by-ref.
+     */
+    get points(): readonly Vec2[];
+    /**
+     * Direction of segment i (0..segments-1) in node-local space, radians
+     * (0 = +x, y-down screen convention). Map child sprites to segments with
+     * `sprite.pos = chain.points[i]; sprite.rotation = chain.segmentAngle(i)`.
+     */
+    segmentAngle(i: number): number;
+    /** Flick the chain: add a velocity (world px/s) to every free point next step. */
+    impulse(v: Vec2): void;
+    protected onProcess(dt: number): void;
+    /**
+     * Stroked open poly of the chain. `points` are node-local and `world` is the
+     * self-inclusive world transform handed to draw(), so commands emit with it
+     * directly. With `taper`, each segment is its own 2-point poly at a linearly
+     * decreasing width (segments are few, so this stays cheap); otherwise one poly.
+     */
+    protected draw(out: DrawCommand[], world: Transform): void;
+}

package/dist/ui/touch.d.ts

@@ -0,0 +1,51 @@
+import type { GameHandle } from '../app/browser';
+/** A virtual stick. Give it 4 directional actions, and/or an analog axis prefix. */
+export interface TouchStick {
+    /** Directional actions held while tilted past the deadzone. Array = [up,down,left,right]. */
+    dirs?: [string, string, string, string] | {
+        up: string;
+        down: string;
+        left: string;
+        right: string;
+    };
+    /**
+     * Emit live analog axes `${prefix}x`, `${prefix}y` (−1..1) and `${prefix}angle`
+     * (radians), quantized to `buckets`. NOTE: these are LIVE axes (feel), not part
+     * of the input log — for replay-exact analog aim, thread them through
+     * `world.step(actions, axes)` (see docs/CONVENTIONS.md §Pointer).
+     */
+    prefix?: string;
+    /** Axis quantization levels (default 32). */
+    buckets?: number;
+    /** Dead-zone as a fraction of the stick radius, 0..1 (default 0.28). */
+    deadzone?: number;
+}
+export interface TouchButton {
+    action: string;
+    /** Glyph/label drawn on the button (default the action name). */
+    label?: string;
+    /** Hold the action while pressed (default true); false = one-shot tap via press(). */
+    hold?: boolean;
+}
+export interface TouchControlsLayout {
+    /** Left-corner stick (movement). Array shorthand → [up,down,left,right]. */
+    left?: TouchStick | [string, string, string, string];
+    /** Right-corner stick (aim). */
+    right?: TouchStick | [string, string, string, string];
+    /** Action buttons, stacked at the lower-right. */
+    buttons?: TouchButton[];
+    /** Only mount when the device has a coarse (touch) pointer (default true). */
+    touchOnly?: boolean;
+}
+export declare class TouchControls {
+    private handle;
+    private root;
+    private disposers;
+    /** Every action this control set can hold — released together on dispose/reset. */
+    private owned;
+    constructor(handle: GameHandle, layout: TouchControlsLayout);
+    private addStick;
+    private addButtons;
+    private hold;
+    dispose(): void;
+}

package/dist/verify/dom.d.ts

@@ -0,0 +1,26 @@
+import { type GameHandle } from '../app/browser';
+import type { GameDefinition } from '../app/game';
+export interface DomHarness {
+    /** The live game handle (world, input, pointer, renderer, viewport…). */
+    handle: GameHandle;
+    /** Press a finger/pointer down at design (x,y) with a stable id (default 1). */
+    touchDown(x: number, y: number, id?: number): void;
+    /** Move a tracked finger/pointer to design (x,y). */
+    touchMove(x: number, y: number, id?: number): void;
+    /** Lift a finger/pointer (default id 1). */
+    touchUp(id?: number): void;
+    /**
+     * Sample the live pointer + keyboard input into the sim, then run `n` fixed
+     * steps — the same order `runBrowser` uses, minus wall-clock. Held/virtual
+     * actions and quantized axes flow through exactly as in production.
+     */
+    step(n?: number, axes?: Record<string, number>): void;
+    dispose(): void;
+}
+/**
+ * Boot a game's real host wiring under the DOM for a host-layer test. The loop is
+ * frozen (`isHeld`) so stepping is deterministic and test-driven — call `step()`
+ * after firing input. Attach a `TouchControls` to `harness.handle` to prove a
+ * virtual gamepad end-to-end.
+ */
+export declare function bootDom(def: GameDefinition, mount?: HTMLElement): DomHarness;

package/dist/verify/gates.d.ts

@@ -92,6 +92,23 @@ export interface TelegraphFrame {
  * Feed a per-frame timeline (one entry per sim frame) for a single threat.
  */
 export declare function telegraphIssues(timeline: readonly TelegraphFrame[], minFrames: number, label?: string): string[];
+export interface LightingOptions {
+    /**
+     * Minimum effective ambient level (0 = pitch black, 1 = fully lit) the avatar
+     * must sit in — either from the ambient base or a pool falling on it (default
+     * 0.35). Below this the avatar reads as a silhouette in shadow.
+     */
+    minLitLevel?: number;
+}
+/**
+ * Lit-readability gate. Given the rendered display list (which must include the
+ * LightLayer's run) and the avatar's WORLD position + fill, compute the light
+ * level reaching the avatar: the ambient base, lifted toward 1 by any pool whose
+ * radius covers it (scaled by that pool's peak brightness). If the avatar ends up
+ * below `minLitLevel`, it is a silhouette lost in the dark — flagged. When the
+ * frame carries no parseable light run, there is nothing to darken: pass (empty).
+ */
+export declare function lightingIssues(commands: DrawCommand[], avatarFill: string, avatarWorld: Vec2, opts?: LightingOptions): string[];
 export interface CameraOptions {
     /** Fixed timestep between samples in seconds (default 1/60). */
     dt?: number;
@@ -127,6 +144,12 @@ export interface FeelSpec {
     };
     /** True for scrolling games — enables the camera gate (needs sampled positions). */
     scrolls?: boolean;
+    /**
+     * True for games with a LightLayer — enables the lit-readability gate (needs a
+     * rendered frame carrying the light run + the avatar's world position). Uses
+     * `avatarFill` for the color.
+     */
+    lit?: boolean;
 }
 /** Runtime inputs the audit/verify computes and hands to the aggregator. */
 export interface FeelContext {
@@ -140,6 +163,8 @@ export interface FeelContext {
     dt?: number;
     /** Background fallback if the spec omits one. */
     background?: string;
+    /** The avatar's WORLD position in the rendered frame — enables the lit-readability gate. */
+    avatarWorld?: Vec2;
 }
 export interface FeelReport {
     ok: boolean;

package/dist/world.d.ts

@@ -1,7 +1,7 @@
 import { Clock, type ClockConfig } from './core/clock';
 import { EventBus } from './core/events';
 import { Rng } from './core/rng';
-import { InputState } from './input/actions';
+import { InputState, type AxisFrame } from './input/actions';
 import { Node, type WorldContext } from './scene/node';
 import type { Camera2D } from './scene/nodes';
 import { type Transform, type Vec2 } from './core/math';
@@ -14,12 +14,18 @@ export interface WorldConfig {
     height?: number;
     /** Resolved tuning values (see app/tuning.ts). Sim state: hashed + snapshotted. */
     tuning?: Record<string, number | string>;
+    /**
+     * Dev guard: during each step(), `Math.random`/`Date.now` are wrapped so a
+     * stray call inside the sim warns ONCE (with a stack hint) instead of
+     * silently breaking determinism. Never throws; safe to leave on in tests.
+     */
+    guardDeterminism?: boolean;
 }
 /** Default engine event map; games extend it with their own keys. */
 export interface CoreEvents {
     [key: string]: unknown;
 }
-export declare class World implements WorldContext {
+export declare class World<TState extends Record<string, unknown> = Record<string, unknown>> implements WorldContext {
     readonly rng: Rng;
     readonly clock: Clock;
     readonly input: InputState;
@@ -31,15 +37,32 @@ export declare class World implements WorldContext {
      * `hash()` and `snapshot()`, so hidden state here cannot escape determinism
      * checks the way ad-hoc module variables can.
      */
-    state: Record<string, unknown>;
+    state: TState;
     readonly width: number;
     readonly height: number;
+    /**
+     * Pause switch. While true, only `pauseMode: 'always'` subtrees update —
+     * rendering, input sampling, and the clock keep ticking, so a pause menu
+     * (an 'always' subtree) stays live. Sim state: hashed + snapshotted, but
+     * only when true, so pinned hashes of unpaused games are unchanged.
+     */
+    paused: boolean;
+    /**
+     * Sim-time multiplier: the tree receives `clock.dt * timeScale` (slow-mo /
+     * fast-forward), while `'always'` subtrees get the unscaled dt so UI keeps
+     * realtime feel. The clock itself ticks normally. Hashed/snapshotted only
+     * when ≠ 1.
+     */
+    timeScale: number;
     root: Node;
     activeCamera: Camera2D | null;
     private seed;
     private freeQueue;
     private started;
     private tuningValues;
+    private guardDeterminism;
+    private warnedClamp;
+    private warnedNondet;
     constructor(config?: WorldConfig);
     /**
      * Read a tuning value resolved at world creation (declared default unless
@@ -47,6 +70,12 @@ export declare class World implements WorldContext {
      * silently read `undefined` into the sim.
      */
     tune<T extends number | string = number>(key: string): T;
+    /**
+     * Read a shared resource by key. Throws on a missing key (listing what IS
+     * available) — a typo here would otherwise silently read `undefined` into
+     * the sim, exactly like an undeclared tuning knob.
+     */
+    resource<T>(key: string): T;
     get time(): number;
     get frame(): number;
     /** Replace the scene root, entering the tree. */
@@ -57,7 +86,15 @@ export declare class World implements WorldContext {
      * Advance exactly one fixed step with the given actions held down.
      * This is THE deterministic transition — call it from Node or the browser loop.
      */
-    step(actionsDown?: Iterable<string>): void;
+    step(actionsDown?: Iterable<string>, axes?: AxisFrame): void;
+    /**
+     * Wrap `Math.random`/`Date.now` for the duration of a step so a stray call
+     * inside the sim warns ONCE per world (with a stack hint) — the values still
+     * flow through, so nothing breaks mid-frame. Returns the restore function;
+     * properly nested re-entry (a world stepped inside another's step) is safe
+     * because each install restores exactly what it replaced.
+     */
+    private installGuard;
     /**
      * Feed REAL elapsed ms; runs 0+ fixed steps. Returns steps run. This is the
      * realtime driver entry point — it CLAMPS realMs to the clock's maxFrameMs
@@ -65,14 +102,38 @@ export declare class World implements WorldContext {
      * not 72. For headless tests/harnesses that want to fast-forward an exact
      * number of steps, use `runSteps(n)` or `step()` — never `advance` with a big ms.
      */
-    advance(realMs: number, actionsDown?: Iterable<string>): number;
+    advance(realMs: number, actionsDown?: Iterable<string>, axes?: AxisFrame): number;
     /**
      * Run exactly `n` fixed steps — the deterministic fast-forward for tests and
      * headless drivers (unlike `advance`, no realtime clamp). Pass `actionsFor(i)`
      * to script the input per step; omit it to hold nothing down.
      */
-    runSteps(n: number, actionsFor?: (i: number) => Iterable<string>): void;
-    private flushFree;
+    runSteps(n: number, actionsFor?: (i: number) => Iterable<string>, axesFor?: (i: number) => AxisFrame | undefined): void;
+    /**
+     * Run pending frees NOW instead of at the end of the step. `free()` is
+     * deferred (safe during iteration), which means freed nodes survive until
+     * the step ends — during a scene swap that lets old nodes contaminate the
+     * first frame of the new scene. Pattern: `oldRoot.free(); world.flushFree();
+     * buildNewScene()`. Called automatically at the end of every step.
+     */
+    flushFree(): void;
+    /** Visit every live node depth-first (root first, child-index order). */
+    walk(fn: (node: Node) => void): void;
+    /** Total live nodes in the tree (root included). */
+    get nodeCount(): number;
+    /**
+     * One indented line per node — `name (type) [flags] @x,y` — for quick tree
+     * audits in a REPL or test failure message.
+     */
+    debugTree(): string;
+    /** The active camera's world position + zoom, or null (see WorldContext.camera). */
+    camera(): {
+        pos: {
+            x: number;
+            y: number;
+        };
+        zoom: number;
+    } | null;
     /** The view transform (inverse of the active camera), mapping world → screen. */
     viewTransform(): Transform;
     /**
@@ -108,4 +169,8 @@ export interface WorldSnapshot {
     tree: ReturnType<Node['serialize']>;
     /** Resolved tuning values (absent in pre-tuning saves). */
     tuning?: Record<string, number | string>;
+    /** Pause flag (absent when false — keeps old snapshots byte-identical). */
+    paused?: boolean;
+    /** Sim-time multiplier (absent when 1). */
+    timeScale?: number;
 }