hayao 0.2.0 → 0.4.0

package/dist/rasterize-worker-lite.mjs

@@ -0,0 +1,13 @@
+// Lite rasterize worker shipped in the npm package (dist/): SVG file → PNG in
+// an isolated process, no repo-only helpers (no sanitize pass, system fonts).
+// @resvg/resvg-js resolves from the CONSUMER's node_modules — install it as a
+// devDependency to enable inspect_moment PNGs; without it this exits non-zero
+// and the MCP server degrades to probe + hash.
+//   node rasterize-worker-lite.mjs <in.svg> <width> <out.png>
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const [, , svgPath, width, outPath] = process.argv;
+const { Resvg } = await import('@resvg/resvg-js');
+const svg = readFileSync(svgPath, 'utf8');
+const png = new Resvg(svg, { fitTo: { mode: 'width', value: Number(width) }, font: { loadSystemFonts: true } }).render().asPng();
+writeFileSync(outPath, png);

package/dist/render/canvas.d.ts

@@ -1,5 +1,6 @@
-import { type DrawCommand } from './commands';
-import type { Renderer, RendererConfig } from './renderer';
+import type { DrawCommand } from './commands';
+import { type Renderer, type RendererConfig, type Viewport } from './renderer';
+import type { Vec2 } from '../core/math';
 export declare class Canvas2DRenderer implements Renderer {
     readonly width: number;
     readonly height: number;
@@ -11,9 +12,9 @@ export declare class Canvas2DRenderer implements Renderer {
     mount(parent: HTMLElement): void;
     private resize;
     draw(commands: DrawCommand[]): void;
-    private stroke;
-    private paint;
-    private roundRect;
     get element(): HTMLCanvasElement;
+    /** Map a pointer event's clientX/Y into design space (undoes the letterbox). */
+    toDesign(clientX: number, clientY: number): Vec2;
+    viewport(): Viewport;
     dispose(): void;
 }

package/dist/render/canvas2d-core.d.ts

@@ -0,0 +1,9 @@
+import { type DrawCommand } from './commands';
+type Ctx2D = CanvasRenderingContext2D;
+/**
+ * Paint a sorted display list onto an existing Canvas2D context at `scale`
+ * (device pixel ratio). The caller is responsible for sizing the canvas to
+ * `width * scale` × `height * scale` before calling.
+ */
+export declare function drawToCanvas2D(ctx: Ctx2D, commands: DrawCommand[], width: number, height: number, background: string, scale: number): void;
+export {};

package/dist/render/commands.d.ts

@@ -1,4 +1,39 @@
 import type { Transform } from '../core/math';
+/** One color stop of a gradient. `offset` is 0..1 along the gradient axis. */
+export interface GradientStop {
+    offset: number;
+    color: string;
+}
+/**
+ * A gradient fill in OBJECT-BOUNDING-BOX space: all coordinates are 0..1
+ * relative to the painted shape's bounds, so the same gradient reads correctly
+ * on a shape of any size or position (matches SVG `gradientUnits`).
+ */
+export interface LinearGradient {
+    type: 'linear';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stops: GradientStop[];
+}
+export interface RadialGradient {
+    type: 'radial';
+    /** Center + radius, all 0..1 in object-bounding-box space. */
+    cx: number;
+    cy: number;
+    r: number;
+    stops: GradientStop[];
+}
+export type Gradient = LinearGradient | RadialGradient;
+/** A soft shadow / outer glow. `dx=dy=0` is a symmetric glow; offset = drop. */
+export interface Shadow {
+    color: string;
+    /** Blur radius in local px. */
+    blur: number;
+    dx?: number;
+    dy?: number;
+}
 export interface Paint {
     fill?: string;
     stroke?: string;
@@ -6,6 +41,15 @@ export interface Paint {
     opacity?: number;
     /** Round line joins/caps for organic shapes. */
     round?: boolean;
+    /** A gradient fill; when present it overrides `fill` for the shape body. */
+    gradient?: Gradient;
+    /** A soft outer glow / drop shadow applied to the shape. */
+    shadow?: Shadow;
+    /**
+     * Dash pattern for strokes, in local px (`[dash, gap, …]` — same as
+     * Canvas2D `setLineDash` / SVG `stroke-dasharray`). Omit for solid lines.
+     */
+    lineDash?: number[];
 }
 export type TextAlign = 'left' | 'center' | 'right';
 interface Base extends Paint {
@@ -13,6 +57,20 @@ interface Base extends Paint {
     transform: Transform;
     /** Painter's-order key; ties broken by tree order. Default 0. */
     z: number;
+    /**
+     * Render layer: commands sort by layer FIRST, then z, then tree order.
+     * Layer 0 (default) is the world; layer 1 is the screen-space overlay pass
+     * (HUD, transitions) — set automatically for `Node.screenSpace` subtrees, so
+     * overlays always paint above world content regardless of z values.
+     */
+    layer?: number;
+    /**
+     * Transient view chrome — a drifting popup, particle, or tween that lives for
+     * a moment and is never something the player reads for meaning. Layout lints
+     * (see verify/layout) skip these by default: a "+10" floating over a HUD label
+     * is motion, not a collision. Set by cosmetic emitters (FloatingText/Particles).
+     */
+    transient?: boolean;
 }
 export interface RectCommand extends Base {
     kind: 'rect';
@@ -29,6 +87,28 @@ export interface CircleCommand extends Base {
     cy: number;
     radius: number;
 }
+export interface EllipseCommand extends Base {
+    kind: 'ellipse';
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+}
+/**
+ * A circular arc (open stroke) or sector/pie (closed to the center).
+ * Angles are radians, clockwise from +x (screen convention, y-down);
+ * the arc runs from `start` to `end` in the clockwise direction.
+ */
+export interface ArcCommand extends Base {
+    kind: 'arc';
+    cx: number;
+    cy: number;
+    radius: number;
+    start: number;
+    end: number;
+    /** When true, close through the center (a pie slice) so `fill` reads as a sector. */
+    sector?: boolean;
+}
 export interface PolyCommand extends Base {
     kind: 'poly';
     /** Flat [x0,y0,x1,y1,…] in local space. */
@@ -59,7 +139,7 @@ export interface ImageCommand extends Base {
     w: number;
     h: number;
 }
-export type DrawCommand = RectCommand | CircleCommand | PolyCommand | PathCommand | TextCommand | ImageCommand;
-/** Stable painter's sort: by z, then original index (tree order) as tiebreak. */
+export type DrawCommand = RectCommand | CircleCommand | EllipseCommand | ArcCommand | PolyCommand | PathCommand | TextCommand | ImageCommand;
+/** Stable painter's sort: by layer, then z, then original index (tree order) as tiebreak. */
 export declare function sortCommands(cmds: DrawCommand[]): DrawCommand[];
 export {};

package/dist/render/paint.d.ts

@@ -0,0 +1,41 @@
+import type { DrawCommand, Gradient, GradientStop, LinearGradient, RadialGradient, Shadow } from './commands';
+type StopInput = string | GradientStop;
+/**
+ * A linear gradient by angle in degrees (0 = left→right, 90 = top→bottom).
+ * Stops are colors (auto-spaced) or explicit `{offset, color}`.
+ */
+export declare function linearGradient(stops: readonly StopInput[], angleDeg?: number): LinearGradient;
+/** A radial gradient centered in the shape by default (inner stop first). */
+export declare function radialGradient(stops: readonly StopInput[], opts?: {
+    cx?: number;
+    cy?: number;
+    r?: number;
+}): RadialGradient;
+/** A symmetric soft outer glow. */
+export declare function glow(color: string, blur: number): Shadow;
+/** A soft drop shadow, offset by (dx,dy). */
+export declare function dropShadow(color: string, blur: number, dx?: number, dy?: number): Shadow;
+export declare function gradientDef(g: Gradient, id: string): string;
+export declare function shadowDef(s: Shadow, id: string): string;
+export interface BBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Local-space bounding box of a shape command (null for paths/text/image). */
+export declare function shapeBBox(c: DrawCommand): BBox | null;
+/** Why a command's geometry is unpaintable, or null when it's fine. */
+export declare function invalidCommandReason(c: DrawCommand): string | null;
+/**
+ * console.warn once per (kind + reason) — a bad value animating every frame
+ * logs a single line, not sixty a second. `detail` (the offending command or
+ * error) is passed through so the console shows the actual value.
+ */
+export declare function warnCommandOnce(kind: string, reason: string, detail?: unknown): void;
+/** Build a Canvas gradient mapped from object-bounding-box space into `bbox`. */
+export declare function canvasGradient(ctx: {
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradient;
+}, g: Gradient, bbox: BBox): CanvasGradient;
+export {};

package/dist/render/renderer.d.ts

@@ -1,4 +1,5 @@
 import type { DrawCommand } from './commands';
+import type { Vec2 } from '../core/math';
 /** A backend that paints a display list into a host (DOM, canvas, or nothing). */
 export interface Renderer {
     readonly width: number;
@@ -7,10 +8,56 @@ export interface Renderer {
     draw(commands: DrawCommand[]): void;
     /** Attach to a DOM parent (browser backends). */
     mount?(parent: HTMLElement): void;
+    /** The mounted DOM node (canvas or svg), for attaching pointer listeners. */
+    readonly element?: HTMLElement | SVGElement;
+    /**
+     * Invert the display transform: a browser pointer event's clientX/clientY →
+     * design-space coordinates. The backend owns the letterbox (`object-fit:
+     * contain` / `preserveAspectRatio`) and DPR, so it's the only place that can
+     * undo them correctly. Returns design coords even outside the letterbox
+     * (values fall outside 0..width/height there).
+     */
+    toDesign?(clientX: number, clientY: number): Vec2;
+    /**
+     * The drawn (letterboxed) design area within the mount, in mount-local px:
+     * `{ x, y, width, height, scale }`. Host-drawn UI (floating touch controls,
+     * DOM HUD) anchors to this rect instead of re-deriving the `object-fit:
+     * contain` math the backend already does for `toDesign`. Undefined for
+     * headless backends.
+     */
+    viewport?(): Viewport;
     dispose?(): void;
 }
+/** The drawn area within the mount: offset + size in host px, plus design→px scale. */
+export interface Viewport {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+}
 export interface RendererConfig {
     width: number;
     height: number;
     background?: string;
 }
+/**
+ * Undo a centered uniform-fit (`object-fit: contain` / SVG `xMidYMid meet`):
+ * map a client pixel inside `rect` back to the design box `width×height`. Shared
+ * by every DOM backend so the letterbox math lives in exactly one place.
+ */
+export declare function clientToDesign(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, width: number, height: number, clientX: number, clientY: number): Vec2;
+/**
+ * The centered uniform-fit rect for a design box inside an element of size
+ * `rect` — the inverse framing of `clientToDesign`, in element-local px. Shared
+ * by every DOM backend's `viewport()`.
+ */
+export declare function fitViewport(rect: {
+    width: number;
+    height: number;
+}, width: number, height: number): Viewport;

package/dist/render/svg.d.ts

@@ -1,5 +1,6 @@
 import type { DrawCommand } from './commands';
-import type { Renderer, RendererConfig } from './renderer';
+import { type Renderer, type RendererConfig, type Viewport } from './renderer';
+import type { Vec2 } from '../core/math';
 export declare class SvgRenderer implements Renderer {
     readonly width: number;
     readonly height: number;
@@ -12,5 +13,8 @@ export declare class SvgRenderer implements Renderer {
     draw(commands: DrawCommand[]): void;
     setBackground(color: string): void;
     get element(): SVGSVGElement;
+    /** Map a pointer event's clientX/Y into design space (undoes the letterbox). */
+    toDesign(clientX: number, clientY: number): Vec2;
+    viewport(): Viewport;
     dispose(): void;
 }

package/dist/render/svgString.d.ts

@@ -1,5 +1,9 @@
 import { type DrawCommand } from './commands';
-/** Inner SVG markup for a display list (no wrapping <svg>). */
-export declare function commandsToSVGInner(commands: DrawCommand[]): string;
+/**
+ * Inner SVG markup for a display list (no wrapping <svg>). `idPrefix` salts the
+ * ids of any gradient/shadow <defs> so several inner markups can share one SVG
+ * document (e.g. a filmstrip) without their `url(#…)` references colliding.
+ */
+export declare function commandsToSVGInner(commands: DrawCommand[], idPrefix?: string): string;
 /** A complete, standalone SVG document string for a frame — a headless screenshot. */
 export declare function renderToSVGString(commands: DrawCommand[], width: number, height: number, background?: string): string;

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

@@ -0,0 +1,42 @@
+import { Node, type NodeConfig } from './node';
+import { type Vec2 } from '../core/math';
+import type { Camera2D } from './nodes';
+/** World-space rectangle the camera CENTER is kept inside (before viewport inset). */
+export interface CameraBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface CameraControllerConfig extends NodeConfig {
+    /** Node to follow. May be set later via `follow()`. */
+    target?: Node;
+    /** Camera to drive. Defaults to the world's active camera each step. */
+    camera?: Camera2D;
+    /** Half-extents of a slack box the target may roam before the camera chases. */
+    deadzone?: number | Vec2;
+    /** Per-step chase factor in [0,1]; 1 snaps, lower trails. Default 0.15. */
+    smooth?: number;
+    /** Clamp the view to a world rectangle (the level bounds) so no void shows. */
+    bounds?: CameraBounds;
+}
+export declare class CameraController extends Node {
+    readonly type = "CameraController";
+    cosmetic: boolean;
+    target: Node | null;
+    private cameraRef;
+    deadzone: Vec2;
+    smooth: number;
+    bounds: CameraBounds | null;
+    constructor(config?: CameraControllerConfig);
+    /** Point the controller at a node to follow. */
+    follow(target: Node): this;
+    private host;
+    private camera;
+    /** Where the camera wants to sit: the target position, clamped to bounds. */
+    private desired;
+    /** Jump the camera straight to its desired position (no smoothing). */
+    snap(): void;
+    protected onReady(): void;
+    protected onProcess(): 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;
+}