hayao 0.3.0 → 0.4.0

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/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/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/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;