hayao 0.3.0 → 0.4.1

package/dist/render/webgl.d.ts

@@ -0,0 +1,176 @@
+import type { DrawCommand } from './commands';
+import { type Renderer, type RendererConfig, type Viewport } from './renderer';
+import type { Vec2 } from '../core/math';
+/** Value for a GLSL uniform: float, vec2, vec3, or vec4. */
+export type UniformValue = number | [number, number] | [number, number, number] | [number, number, number, number];
+/**
+ * One pass in a post-processing pipeline. Each pass is a GLSL fragment shader
+ * that receives:
+ *   uniform sampler2D u_scene      — the original Canvas2D rasterized frame
+ *   uniform sampler2D u_prev       — output of the previous pass (= u_scene for pass 0)
+ *   uniform float     u_time       — wall-clock seconds (cosmetic only, never hashed)
+ *   uniform vec2      u_resolution — display canvas size in pixels
+ *   in vec2           v_uv         — 0..1 UV with (0,0) at top-left
+ *   out vec4          fragColor    — output pixel
+ *
+ * Plus any custom uniforms added via setUniform() or the pass's own `uniforms` map.
+ */
+export interface PostProcessPass {
+    /** GLSL #version 300 es fragment shader source. */
+    shader: string;
+    /** Per-pass custom uniforms (merged with the renderer-level ones, pass overrides renderer). */
+    uniforms?: Record<string, UniformValue>;
+}
+/**
+ * Ready-made GLSL fragment shaders for common post-processing effects.
+ * Use in setPostProcess() or as passes in setPipeline().
+ *
+ * Each effect references u_scene / u_prev / u_time / u_resolution as needed.
+ * Custom tuning: pass a custom uniform via setUniform() — names are noted below.
+ *
+ * @example
+ * ```ts
+ * import { WebGL2Renderer, WEBGL_EFFECTS } from '@hayao';
+ * const renderer = new WebGL2Renderer({ width, height, postProcess: WEBGL_EFFECTS.vignette });
+ * // Tune: renderer.setUniform('u_vignette', 0.5);
+ * ```
+ */
+export declare const WEBGL_EFFECTS: {
+    /** Passthrough — no effect. */
+    readonly passthrough: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_scene;\nuniform sampler2D u_prev;\nout vec4 fragColor;\nvoid main() { fragColor = texture(u_prev, v_uv); }";
+    /** Pixelate: blockSize in pixels (default 4). setUniform('u_block', N) */
+    readonly pixelate: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform vec2 u_resolution;\nuniform float u_block;\nout vec4 fragColor;\nvoid main() {\n  float block = max(1.0, u_block > 0.0 ? u_block : 4.0);\n  vec2 px = floor(v_uv * u_resolution / block) * block / u_resolution;\n  fragColor = texture(u_prev, px);\n}";
+    /** Vignette: darkens edges. setUniform('u_vignette', 0.0..1.0, default 0.4) */
+    readonly vignette: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform float u_vignette;\nout vec4 fragColor;\nvoid main() {\n  vec4 col = texture(u_prev, v_uv);\n  vec2 uv = v_uv - 0.5;\n  float d = dot(uv, uv);\n  float strength = u_vignette > 0.0 ? u_vignette : 0.4;\n  fragColor = col * (1.0 - d * strength * 4.0);\n}";
+    /** CRT scanlines + slight barrel distortion. u_time drives the scan roll. */
+    readonly crt: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform vec2 u_resolution;\nuniform float u_time;\nuniform float u_crt_lines;    // scanline density, default 600\nuniform float u_crt_warp;     // barrel strength, default 0.08\nout vec4 fragColor;\nvoid main() {\n  float lines = u_crt_lines > 0.0 ? u_crt_lines : 600.0;\n  float warp  = u_crt_warp  > 0.0 ? u_crt_warp  : 0.08;\n  // barrel distortion\n  vec2 uv = v_uv - 0.5;\n  float r2 = dot(uv, uv);\n  uv *= 1.0 + warp * r2;\n  uv += 0.5;\n  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) {\n    fragColor = vec4(0.0, 0.0, 0.0, 1.0);\n    return;\n  }\n  vec4 col = texture(u_prev, uv);\n  // rolling scanlines\n  float scan = sin((uv.y * lines + u_time * 40.0) * 3.14159) * 0.5 + 0.5;\n  col.rgb *= 0.75 + 0.25 * scan;\n  // slight green phosphor tint\n  col.rgb = mix(col.rgb, col.rgb * vec3(0.9, 1.05, 0.85), 0.3);\n  fragColor = col;\n}";
+    /** Chromatic aberration / RGB fringe. setUniform('u_aberration', 0..0.01, default 0.004) */
+    readonly chromaticAberration: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform float u_aberration;\nout vec4 fragColor;\nvoid main() {\n  float amt = u_aberration > 0.0 ? u_aberration : 0.004;\n  vec2 dir = v_uv - 0.5;\n  float r = texture(u_prev, v_uv + dir * amt * 2.0).r;\n  float g = texture(u_prev, v_uv).g;\n  float b = texture(u_prev, v_uv - dir * amt * 2.0).b;\n  fragColor = vec4(r, g, b, 1.0);\n}";
+    /** Palette-shift / hue rotation. u_hue_shift in radians, driven by u_time for animation. */
+    readonly hueRotate: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform float u_hue_shift; // radians; if 0 uses u_time\nuniform float u_time;\nout vec4 fragColor;\nvoid main() {\n  float angle = u_hue_shift != 0.0 ? u_hue_shift : u_time * 0.5;\n  vec4 col = texture(u_prev, v_uv);\n  // Hue rotate via Rodrigues in YIQ-ish space\n  float c = cos(angle), s = sin(angle);\n  mat3 m = mat3(\n    0.299+0.701*c+0.168*s, 0.587-0.587*c+0.330*s, 0.114-0.114*c-0.497*s,\n    0.299-0.299*c-0.328*s, 0.587+0.413*c+0.035*s, 0.114-0.114*c+0.292*s,\n    0.299-0.300*c+1.250*s, 0.587-0.588*c-1.050*s, 0.114+0.886*c-0.203*s\n  );\n  fragColor = vec4(m * col.rgb, col.a);\n}";
+    /** Wave distortion (heat haze, underwater). setUniform('u_wave_amp', default 0.003) */
+    readonly wave: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform float u_time;\nuniform float u_wave_amp;\nuniform float u_wave_freq;\nout vec4 fragColor;\nvoid main() {\n  float amp  = u_wave_amp  > 0.0 ? u_wave_amp  : 0.003;\n  float freq = u_wave_freq > 0.0 ? u_wave_freq : 8.0;\n  vec2 uv = v_uv;\n  uv.x += sin(uv.y * freq + u_time * 2.5) * amp;\n  uv.y += cos(uv.x * freq + u_time * 2.5) * amp;\n  fragColor = texture(u_prev, clamp(uv, 0.0, 1.0));\n}";
+    /** Bloom pass 1/4: extract bright pixels above threshold (default 0.6). */
+    readonly bloomBrightpass: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform float u_bloom_threshold;\nout vec4 fragColor;\nvoid main() {\n  vec4 col = texture(u_prev, v_uv);\n  float lum = dot(col.rgb, vec3(0.2126, 0.7152, 0.0722));\n  float thresh = u_bloom_threshold > 0.0 ? u_bloom_threshold : 0.55;\n  float weight = smoothstep(thresh - 0.05, thresh + 0.05, lum);\n  fragColor = col * weight;\n}";
+    /** Bloom pass 2/4: horizontal gaussian blur (13-tap). */
+    readonly bloomHBlur: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform vec2 u_resolution;\nuniform float u_bloom_spread;\nout vec4 fragColor;\nvoid main() {\n  float spread = u_bloom_spread > 0.0 ? u_bloom_spread : 1.0;\n  vec2 texel = vec2(spread / u_resolution.x, 0.0);\n  const float W[7] = float[](0.0625, 0.125, 0.1875, 0.25, 0.1875, 0.125, 0.0625);\n  vec4 sum = vec4(0.0);\n  for (int i = 0; i < 7; i++)\n    sum += texture(u_prev, clamp(v_uv + float(i-3) * texel, 0.0, 1.0)) * W[i];\n  fragColor = sum;\n}";
+    /** Bloom pass 3/4: vertical gaussian blur (13-tap). */
+    readonly bloomVBlur: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_prev;\nuniform vec2 u_resolution;\nuniform float u_bloom_spread;\nout vec4 fragColor;\nvoid main() {\n  float spread = u_bloom_spread > 0.0 ? u_bloom_spread : 1.0;\n  vec2 texel = vec2(0.0, spread / u_resolution.y);\n  const float W[7] = float[](0.0625, 0.125, 0.1875, 0.25, 0.1875, 0.125, 0.0625);\n  vec4 sum = vec4(0.0);\n  for (int i = 0; i < 7; i++)\n    sum += texture(u_prev, clamp(v_uv + float(i-3) * texel, 0.0, 1.0)) * W[i];\n  fragColor = sum;\n}";
+    /** Bloom pass 4/4: composite original + blurred bloom. u_bloom_intensity controls strength. */
+    readonly bloomComposite: "#version 300 es\nprecision mediump float;\nin vec2 v_uv;\nuniform sampler2D u_scene;\nuniform sampler2D u_prev;\nuniform float u_bloom_intensity;\nout vec4 fragColor;\nvoid main() {\n  vec4 scene = texture(u_scene, v_uv);\n  vec4 bloom = texture(u_prev, v_uv);\n  float intensity = u_bloom_intensity > 0.0 ? u_bloom_intensity : 0.8;\n  fragColor = vec4(scene.rgb + bloom.rgb * intensity, scene.a);\n}";
+};
+export declare const BLOOM_PIPELINE: PostProcessPass[];
+export interface WebGLRendererConfig extends RendererConfig {
+    /**
+     * Initial post-processing shader or pipeline. Pass a GLSL string for a
+     * single-pass effect, or use setPipeline() for multi-pass. Defaults to
+     * passthrough.
+     */
+    postProcess?: string;
+}
+/**
+ * GPU-accelerated renderer with a programmable GLSL post-processing pipeline.
+ *
+ * ## Quick start
+ * ```ts
+ * import { WebGL2Renderer, WEBGL_EFFECTS, BLOOM_PIPELINE } from '@hayao';
+ *
+ * // Single-pass:
+ * const renderer = new WebGL2Renderer({ width, height,
+ *   postProcess: WEBGL_EFFECTS.vignette });
+ * renderer.setUniform('u_vignette', 0.5);
+ *
+ * // Multi-pass bloom:
+ * const renderer = new WebGL2Renderer({ width, height });
+ * renderer.setPipeline(BLOOM_PIPELINE);
+ * renderer.setUniform('u_bloom_intensity', 1.2);
+ *
+ * // Runtime effect swap:
+ * renderer.setPostProcess(WEBGL_EFFECTS.crt);
+ * renderer.clearPostProcess(); // back to passthrough
+ * ```
+ *
+ * ## Auto-uniforms (available in every shader, every pass)
+ * - `uniform float u_time`       — wall-clock seconds (cosmetic, never hashed)
+ * - `uniform vec2 u_resolution`  — display canvas size in px (w, h)
+ * - `uniform sampler2D u_scene`  — original Canvas2D rasterized frame
+ * - `uniform sampler2D u_prev`   — output of the previous pass (= u_scene for pass 0)
+ *
+ * ## Determinism
+ * `u_time` is wall-clock and NOT part of `world.hash()`. The renderer is a
+ * pure display-list consumer — it never writes state back into the engine.
+ * All verify passes run against `HeadlessRenderer` / `SvgRenderer` and see
+ * the same DrawCommand[] regardless of post-processing.
+ */
+export declare class WebGL2Renderer implements Renderer {
+    readonly width: number;
+    readonly height: number;
+    private background;
+    private glCanvas;
+    private gl;
+    private offscreen;
+    private ctx2d;
+    private dpr;
+    /** Original rasterized scene texture. */
+    private sceneTex;
+    /** Intermediate pass framebuffers (one per non-final pass). */
+    private fbos;
+    /** Compiled programs, one per pass. */
+    private programs;
+    /** Per-pass uniform maps (merged with global uniforms). */
+    private passUniforms;
+    /** Empty VAO for gl_VertexID-only draws. */
+    private vao;
+    /** Frames drawn, driving u_time at a nominal 60 fps (cosmetic, but deterministic). */
+    private framesDrawn;
+    /** Global custom uniforms applied to every pass. */
+    private uniforms;
+    constructor(config: WebGLRendererConfig);
+    mount(parent: HTMLElement): void;
+    private resize;
+    private buildPipeline;
+    draw(commands: DrawCommand[]): void;
+    /**
+     * Set a custom uniform applied to every pass. Useful for knob-driven effect
+     * parameters (intensity, scale, colour) without recompiling the shader.
+     * The value is set on every draw() until cleared or overridden.
+     *
+     * ```ts
+     * renderer.setUniform('u_vignette', 0.5);
+     * renderer.setUniform('u_bloom_intensity', [1.0, 0.8]);
+     * ```
+     */
+    setUniform(name: string, value: UniformValue): this;
+    /** Remove a custom uniform. */
+    clearUniform(name: string): this;
+    /**
+     * Replace the post-processing pipeline. Accepts an array of passes; each
+     * pass reads `u_prev` (previous output) and `u_scene` (original frame).
+     * Throws on shader compile error — previous pipeline stays active.
+     *
+     * For single-pass effects, prefer `setPostProcess(shader)`. For the standard
+     * bloom setup, use `setPipeline(BLOOM_PIPELINE)`.
+     *
+     * ```ts
+     * renderer.setPipeline([
+     *   { shader: WEBGL_EFFECTS.bloomBrightpass },
+     *   { shader: WEBGL_EFFECTS.bloomHBlur },
+     *   { shader: WEBGL_EFFECTS.bloomVBlur },
+     *   { shader: WEBGL_EFFECTS.bloomComposite },
+     * ]);
+     * renderer.setUniform('u_bloom_intensity', 1.0);
+     * ```
+     */
+    setPipeline(passes: PostProcessPass[]): this;
+    /**
+     * Convenience: set a single-pass post-processing shader.
+     * Throws on compile error — previous effect stays active.
+     */
+    setPostProcess(fragmentShader: string): this;
+    /** Restore passthrough (no post-processing). */
+    clearPostProcess(): this;
+    get element(): HTMLCanvasElement;
+    toDesign(clientX: number, clientY: number): Vec2;
+    viewport(): Viewport;
+    dispose(): void;
+}

package/dist/scene/clipPlayer.d.ts

@@ -0,0 +1,58 @@
+import { Node, type NodeConfig } from './node';
+import { type ClipDef } from '../anim/clip';
+export interface ClipPlayerConfig extends NodeConfig {
+    /** The rig root this player poses. Defaults to the player's own parent at ready. */
+    rig?: Node;
+}
+/**
+ * Plays named clips onto a rig. Add clips with `add(name, def)`, then `play(name,
+ * {fade})`. Reads: `time` (current playhead, s), `current` (playing clip name).
+ * Signals: `event` (payload = event name) and `finished` (a `once` clip ended).
+ */
+export declare class ClipPlayer extends Node {
+    readonly type = "ClipPlayer";
+    private rig;
+    private skeleton;
+    private clips;
+    private currentName;
+    private elapsed;
+    private prevName;
+    private prevElapsed;
+    private fadeDur;
+    private fadeT;
+    private poseA;
+    private poseB;
+    private poseMix;
+    constructor(config?: ClipPlayerConfig);
+    protected onReady(): void;
+    /** Register a clip under `name`. Rebinds its tracks against the current rig. */
+    add(name: string, def: ClipDef): this;
+    /** Re-resolve the rig + every clip's tracks (call after the rig subtree changes). */
+    rebind(rig?: Node): void;
+    private ensureSkeleton;
+    /**
+     * Play `name`, optionally crossfading over `fade` seconds from whatever is
+     * playing. Restarting the same clip with no fade rewinds it. A fade freezes the
+     * outgoing clip's playhead and blends it out with EASINGS.quadInOut.
+     */
+    play(name: string, opts?: {
+        fade?: number;
+    }): void;
+    /** Stop playback (freezes the rig at its current pose). */
+    stop(): void;
+    /** Current playhead in seconds (raw elapsed, pre-loop-wrap). */
+    get time(): number;
+    /** The clip currently playing, or null. */
+    get current(): string | null;
+    /** Fired with the event name each time the playhead crosses a clip event. */
+    get event(): import("..").Signal<string>;
+    /** Fired when a `once` clip reaches its end. */
+    get finished(): import("..").Signal<string>;
+    protected onProcess(dt: number): void;
+    /** Direct steady-state apply: sample each bound track and write its channel. */
+    private applyDirect;
+    /** Sample an entry's bound tracks into a reusable Pose (clears then fills). */
+    private samplePose;
+    /** Write a mixed pose back onto the incoming entry's bound nodes. */
+    private applyPose;
+}

package/dist/scene/ikTarget.d.ts

@@ -0,0 +1,25 @@
+import { Node, type NodeConfig } from './node';
+import { Bone2D } from '../anim/skeleton';
+export interface IkTargetConfig extends NodeConfig {
+    /** The bone chain to solve, ROOT first. 2 bones → analytic solve; N → FABRIK. */
+    bones?: Bone2D[];
+    /** Elbow/knee bend side for the 2-bone solve (+1 or −1). Default 1. */
+    bendDir?: 1 | -1;
+    /** FABRIK iteration cap (N-bone only). Default 16. */
+    maxIter?: number;
+}
+/** A cosmetic node that drives a Bone2D chain to reach the node's own world position. */
+export declare class IkTarget extends Node {
+    readonly type = "IkTarget";
+    bones: Bone2D[];
+    bendDir: 1 | -1;
+    maxIter: number;
+    /** True if the chain reached the target on the last solve (else it was clamped). */
+    reached: boolean;
+    constructor(config?: IkTargetConfig);
+    /** Repoint the solver at a new chain (root-first). */
+    setBones(bones: Bone2D[]): void;
+    protected onProcess(_dt: number): void;
+    /** Current joint positions (parent space) for FABRIK seeding — stable elbow side. */
+    private currentJoints;
+}

package/dist/scene/iso.d.ts

@@ -0,0 +1,73 @@
+import type { Transform } from '../core/math';
+import type { DrawCommand, Paint } from '../render/commands';
+import { Node, type NodeConfig } from './node';
+/**
+ * A raised isometric tile = a cube: a top diamond + a front-left and front-right
+ * parallelogram. `pos` is the GROUND cell centre (where an elev-0 diamond would
+ * sit); the block rises `height` screen-px toward −y. Give it a base `fill` and
+ * the two side faces auto-shade (left darkest, right mid) — or override any face
+ * with `top` / `left` / `right`. Emits the three faces in back-to-front order so
+ * the top always paints over the sides within the prism.
+ */
+export interface IsoPrismConfig extends NodeConfig {
+    /** Footprint diamond width (horizontal diagonal) in screen px. */
+    tileW: number;
+    /** Footprint diamond height (vertical diagonal) in screen px. */
+    tileH: number;
+    /** Block height in screen px (0 = a flat tile: only the top diamond). */
+    height: number;
+    /** Base colour; side faces derive from it unless overridden. */
+    fill: string;
+    /** Explicit face paints (override the auto-shade). */
+    top?: Paint;
+    left?: Paint;
+    right?: Paint;
+    /** Shared stroke for all faces (seams between tiles). */
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/** Multiply a #rgb / #rrggbb colour's channels by `f` (clamped) for face shading. */
+export declare function shadeHex(hex: string, f: number): string;
+export declare class IsoPrism extends Node {
+    readonly type = "IsoPrism";
+    tileW: number;
+    tileH: number;
+    height: number;
+    fill: string;
+    topPaint?: Paint;
+    leftPaint?: Paint;
+    rightPaint?: Paint;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    constructor(config: IsoPrismConfig);
+    protected draw(out: DrawCommand[], world: Transform): void;
+    protected serializeProps(): Record<string, unknown>;
+    applyProps(props: Record<string, unknown>): void;
+}
+/**
+ * A container that auto-assigns each child's painter `z` from a depth accessor,
+ * so overlapping sprites stack correctly without every mover re-setting `z` in
+ * its own update. The key is read at DRAW time (positions are final for the
+ * frame), integrating these children into the same global z-order as the rest of
+ * the scene. Godot's `YSort`, generalised to any axis:
+ *   new DepthSort({ key: (n) => n.pos.y })          // top-down overlap
+ *   new DepthSort({ key: (n) => n.userDepth })      // iso gx+gy
+ * See docs/CONVENTIONS.md §Depth for the z-from-depth convention.
+ */
+export interface DepthSortConfig extends NodeConfig {
+    /** Depth of a child → its `z`. Larger = drawn on top (painter's order). */
+    key: (n: Node) => number;
+    /** Multiplier applied to the key before it becomes `z` (default 1). */
+    depthScale?: number;
+}
+export declare class DepthSort extends Node {
+    readonly type = "DepthSort";
+    key: (n: Node) => number;
+    depthScale: number;
+    /** DepthSort is a pure ordering container — its z assignments are view-only. */
+    cosmetic: boolean;
+    constructor(config: DepthSortConfig);
+    collectDraw(out: DrawCommand[], parentWorld?: Transform): void;
+}

package/dist/scene/light.d.ts

@@ -0,0 +1,80 @@
+import { type Transform } from '../core/math';
+import { type DrawCommand } from '../render/commands';
+import { Node, type NodeConfig } from './node';
+import { type Occluder } from './shadow2d';
+export interface PointLightConfig extends NodeConfig {
+    /** Pool radius in design-space px. */
+    radius?: number;
+    /** Light color (hex). */
+    color?: string;
+    /** Peak intensity 0..1 (scales the pool's brightness). */
+    intensity?: number;
+    /**
+     * Falloff exponent for the radial gradient's mid stop (>1 = tighter core,
+     * <1 = broader glow). Default 1.
+     */
+    falloff?: number;
+    /** Flicker: sinusoidal + noise wobble of intensity. Off (amount 0) by default. */
+    flicker?: {
+        amount: number;
+        speed: number;
+    };
+    /** Private flicker-Rng seed (observer-side, not serialized). Default 43. */
+    seed?: number;
+}
+/**
+ * A radial point light. Emits nothing itself (`draw` is empty) — its parent
+ * LightLayer reads its world position, radius, color, and `litIntensity` to
+ * build the run. `litIntensity` is cached each `onProcess` from the flicker
+ * stream; with flicker off it equals `intensity` exactly.
+ */
+export declare class PointLight extends Node {
+    readonly type: string;
+    radius: number;
+    color: string;
+    intensity: number;
+    falloff: number;
+    flicker: {
+        amount: number;
+        speed: number;
+    };
+    /** Current intensity after flicker — read by the LightLayer during draw. */
+    litIntensity: number;
+    private rng;
+    private phase;
+    constructor(config?: PointLightConfig);
+    protected onProcess(dt: number): void;
+    protected serializeProps(): Record<string, unknown>;
+}
+export interface LightLayerConfig extends NodeConfig {
+    /** Ambient darkness the pools lift out of. `color` multiplies the world; `level` blends toward white (1 = no darkening). */
+    ambient?: {
+        color?: string;
+        level?: number;
+    };
+    /** Soft shadows: add a half-opacity penumbra quad per segment (pure geometry, no blur). */
+    softShadows?: boolean;
+    /** Ambient-rect viewport size (screen space). Default 1280×720. */
+    width?: number;
+    height?: number;
+}
+/**
+ * The lighting container. Emits the whole light run from its direct PointLight
+ * children: an ambient darkness base, then per light a screen-blended pool plus
+ * its multiply shadow quads. Cosmetic; place at the tree origin in world space.
+ */
+export declare class LightLayer extends Node {
+    readonly type: string;
+    ambient: {
+        color: string;
+        level: number;
+    };
+    softShadows: boolean;
+    width: number;
+    height: number;
+    private occluders;
+    constructor(config?: LightLayerConfig);
+    /** Set the occluder edges (design-space segments) this layer casts shadows from. */
+    setOccluders(segs: Occluder[]): void;
+    protected draw(out: DrawCommand[], world: Transform): void;
+}

package/dist/scene/node.d.ts

@@ -1,7 +1,7 @@
 import type { Rng } from '../core/rng';
 import type { Clock } from '../core/clock';
 import type { InputState } from '../input/actions';
-import { Signal } from '../core/events';
+import { Signal, type EventBus } from '../core/events';
 import { type Transform, type Vec2 } from '../core/math';
 import type { DrawCommand } from '../render/commands';
 /**
@@ -19,6 +19,33 @@ export interface WorldContext {
     requestFree(node: Node): void;
     /** Seconds elapsed in sim time. */
     readonly time: number;
+    /**
+     * Canonical out-of-tree game state (hashed + snapshotted) — the same object
+     * as `world.state`, so behaviours read/write shared sim data without closing
+     * over the world or stashing it in module variables.
+     */
+    readonly state: Record<string, unknown>;
+    /** The world event bus — emit/subscribe without a `world` closure. */
+    readonly events: EventBus<Record<string, unknown>>;
+    /** Design-space dimensions (what the camera letterboxes to). */
+    readonly width: number;
+    readonly height: number;
+    /** True while the world is paused (only `pauseMode: 'always'` subtrees update). */
+    readonly paused: boolean;
+    /** Sim-time multiplier (1 = realtime); `'always'` subtrees receive unscaled dt. */
+    readonly timeScale: number;
+    /**
+     * The active camera's world position + zoom, or null when none is current.
+     * Structural (no Camera2D import needed) — enough for parallax, culling, and
+     * screen-edge logic without a sibling search through the tree.
+     */
+    camera(): {
+        pos: {
+            x: number;
+            y: number;
+        };
+        zoom: number;
+    } | null;
 }
 /** A composable update unit attached to a node (favour over deep inheritance). */
 export interface Behavior {
@@ -29,6 +56,15 @@ export interface Behavior {
     /** Optional tag for lookup/serialization. */
     readonly kind?: string;
 }
+/**
+ * How a node behaves while the world is paused. `'inherit'` (default) takes the
+ * parent's effective mode (the root default is pausable), `'always'` keeps its
+ * subtree updating through a pause (pause menus, transitions), `'stopped'`
+ * halts its subtree even when the world is running.
+ */
+export type PauseMode = 'inherit' | 'always' | 'stopped';
+/** A resolved pause mode — what 'inherit' collapses to as it flows down the tree. */
+type EffectivePauseMode = 'pausable' | 'always' | 'stopped';
 /** Deterministic id source — reset by the World on load so ids are reproducible. */
 export declare function resetNodeIds(start?: number): void;
 export interface NodeConfig {
@@ -56,6 +92,24 @@ export declare class Node {
      * particles, tweened positions) never pollutes the canonical, verifiable state.
      */
     cosmetic: boolean;
+    /**
+     * Pause behaviour for this subtree (see PauseMode). Serialized only when
+     * non-default, so existing trees keep their pinned hashes.
+     */
+    pauseMode: PauseMode;
+    /**
+     * Screen-space overlay: this subtree ignores the camera — its transforms
+     * compose from IDENTITY (design-space coordinates) — and every command it
+     * emits is tagged `layer: 1` so HUD/overlay content always paints above the
+     * world, whatever the z values. Serialized only when true.
+     */
+    screenSpace: boolean;
+    /**
+     * Optional local anchor: when set, rotation/scale pivot around this point in
+     * local space instead of the node origin (the local transform gains a
+     * trailing translation of −pivot). Serialized only when set.
+     */
+    pivot?: Vec2;
     parent: Node | null;
     readonly children: Node[];
     world: WorldContext | null;
@@ -70,19 +124,41 @@ export declare class Node {
     private _ready;
     private _freed;
     constructor(config?: NodeConfig);
+    /** Shorthand for `pos.x` — reads and writes the same vector. */
+    get x(): number;
+    set x(v: number);
+    /** Shorthand for `pos.y` — reads and writes the same vector. */
+    get y(): number;
+    set y(v: number);
     addChild<T extends Node>(child: T): T;
     removeChild(child: Node): void;
     /** Deferred free: runs exit hooks and detaches at the end of the step. */
     free(): void;
+    /**
+     * Immediately exit + detach ALL children. Unlike `free()` this is NOT
+     * deferred — the children are gone when the call returns (safe here because
+     * it iterates a snapshot of the array). Use it to rebuild a container's
+     * contents wholesale; prefer `free()` for removals during an update.
+     */
+    clearChildren(): void;
     /** Depth-first find by name. */
     find(name: string): Node | null;
+    /** Depth-first find of the first node (self included) that is an instance of `ctor` — typed. */
+    findOfType<T extends Node>(ctor: new (...args: never[]) => T): T | null;
     /** All descendants (and self) of a given type tag. */
     query(type: string, out?: Node[]): Node[];
     addBehavior(b: Behavior): this;
     signal<T = void>(name: string): Signal<T>;
     emit<T>(name: string, payload: T): void;
     enterTree(world: WorldContext): void;
-    updateTree(dt: number): void;
+    /**
+     * Advance this subtree. `dt` is the (time-scaled) step delta; `unscaledDt`
+     * and `paused` come from the world, and `parentMode` is the effective pause
+     * mode flowing down the tree. The walk always descends — a paused node just
+     * skips its callbacks — so an `'always'` descendant (pause menu, transition)
+     * keeps running inside a paused parent.
+     */
+    updateTree(dt: number, unscaledDt?: number, parentMode?: EffectivePauseMode, paused?: boolean): void;
     exitTree(): void;
     get isFreed(): boolean;
     localTransform(): Transform;
@@ -108,6 +184,9 @@ export interface SerializedNode {
     scale: Vec2;
     z: number;
     visible: boolean;
+    /** Local rotation/scale anchor (absent when unset). */
+    pivot?: Vec2;
     props: Record<string, unknown>;
     children: SerializedNode[];
 }
+export {};

package/dist/scene/nodes.d.ts

@@ -8,11 +8,22 @@ import { Node, type NodeConfig } from './node';
  *               middle. Pass `anchor: 'topLeft'` to place `pos` at the top-left
  *               corner instead (the canvas mental model) — no half-size offset.
  *  - `circle` → CENTER-anchored: `pos` is the center.
+ *  - `ellipse`→ CENTER-anchored: `pos` is the center; `rx`/`ry` are the semi-axes.
+ *  - `arc`    → CENTER-anchored: `pos` is the arc's center. Radians, clockwise
+ *               from +x (y-down screen convention), running `start` → `end`.
+ *               `sector: true` closes through the center (a pie slice).
  *  - `glyph`  → CENTER-anchored (align 'center').
  *  - `poly`   → LOCAL coordinates: `points` are relative to `pos` as-is (put your
  *               own 0,0 wherever you like).
  *  - `path`   → LOCAL coordinates: `d` is drawn relative to `pos`.
+ *  - `diamond`→ CENTER-anchored: a `w×h` rhombus (iso tile). `pos` is its middle.
+ *  - `regularPoly` → CENTER-anchored: `sides`-gon of circumradius `r`. `rotation`
+ *               (radians) turns it; 0 puts the first vertex straight up.
  * (`Text` is anchored by its `align`, not centered — see the Text node.)
+ *
+ * `diamond` and `regularPoly` are pure sugar over `poly` (resolved at draw time,
+ * no renderer change) — they exist so an iso tile or a hex reads as intent, not
+ * as four hand-typed corner numbers.
  */
 export type Shape = {
     kind: 'rect';
@@ -23,6 +34,16 @@ export type Shape = {
 } | {
     kind: 'circle';
     radius: number;
+} | {
+    kind: 'ellipse';
+    rx: number;
+    ry: number;
+} | {
+    kind: 'arc';
+    radius: number;
+    start: number;
+    end: number;
+    sector?: boolean;
 } | {
     kind: 'poly';
     points: number[];
@@ -34,7 +55,20 @@ export type Shape = {
     kind: 'glyph';
     char: string;
     size: number;
+} | {
+    kind: 'diamond';
+    w: number;
+    h: number;
+} | {
+    kind: 'regularPoly';
+    sides: number;
+    r: number;
+    rotation?: number;
 };
+/** Local poly points for a center-anchored `w×h` diamond (top, right, bottom, left). */
+export declare function diamondPoints(w: number, h: number): number[];
+/** Local poly points for a center-anchored regular `sides`-gon of circumradius `r`. */
+export declare function regularPolyPoints(sides: number, r: number, rotation?: number): number[];
 export interface SpriteConfig extends NodeConfig, Paint {
     shape: Shape;
 }

package/dist/scene/particles.d.ts

@@ -42,6 +42,25 @@ export declare class Particles extends Node {
     private gravity;
     private drag;
     private shrink;
+    private emitRate;
+    private emitAcc;
+    private emitStyle;
+    private emitOrigin;
+    /**
+     * Start (or retune) continuous emission at `ratePerSec` particles per second.
+     * `style.at` sets the node-local origin (default 0,0); the rest styles
+     * particles exactly like `burst()`. Omitting `style` keeps the previous
+     * emitter style (falling back to the `burst` preset if none was ever set).
+     *
+     * The signal form `emit(name, payload)` inherited from Node still works —
+     * the overload dispatches on the first argument's type.
+     */
+    emit(ratePerSec: number, style?: ParticleStyle & {
+        at?: Vec2;
+    }): void;
+    emit<T>(name: string, payload: T): void;
+    /** Stop continuous emission. Live particles finish their lives naturally. */
+    stopEmit(): void;
     protected onProcess(dt: number): void;
     protected draw(out: DrawCommand[], world: Transform): void;
     get liveCount(): number;

package/dist/scene/shadow2d.d.ts

@@ -0,0 +1,25 @@
+import type { Vec2 } from '../core/math';
+import { type ContourSegment } from '../art/autotile';
+import { type TilemapData } from '../physics/tilemap';
+/** An occluder edge in world (design-space) coordinates. */
+export type Occluder = ContourSegment;
+/**
+ * Occluder edges from a tilemap: the marching-squares contour of the SOLID
+ * cells, in design-space px. Wraps `marchingSquaresContours` over a boolean
+ * grid of `tileAt === TILE.SOLID`, scaled by the map's tileSize.
+ */
+export declare function occludersFromTilemap(map: TilemapData): Occluder[];
+/**
+ * Cull occluders to those that can matter for a light: an endpoint within, or
+ * the segment straddling, the light's reach (radius). A cheap circle/AABB-ish
+ * test — keeps the O(lights × segments) shadow pass tight without changing the
+ * result (a segment fully outside the disc casts no shadow inside it).
+ */
+export declare function cullSegments(light: Vec2, radius: number, segs: readonly Occluder[]): Occluder[];
+/**
+ * Shadow quads cast by `segs` from `light`, one flat `[ax,ay, bx,by, bx',by',
+ * ax',ay']` quad per segment (closed poly winding). Extrusion length is 2×radius
+ * so the far edge always clears the lit disc. A segment passing through the light
+ * (degenerate direction) is skipped. Culling is the caller's job (`cullSegments`).
+ */
+export declare function shadowQuads(light: Vec2, radius: number, segs: readonly Occluder[]): number[][];