hayao 0.3.0 → 0.4.1

package/dist/input/actions.d.ts

@@ -1,12 +1,50 @@
-/** action name → physical key codes (KeyboardEvent.code strings). */
-export type InputMap = Record<string, string[]>;
+/**
+ * action name → physical bindings (KeyboardEvent.code strings, or pointer
+ * buttons `mouse.left` / `mouse.right` / `mouse.middle`). Readonly on both
+ * levels so `as const` maps type-check without casts.
+ */
+export type InputMap = Readonly<Record<string, readonly string[]>>;
+/** Per-frame analog axis values (already quantized). Recorded into the log + hash. */
+export type AxisFrame = Record<string, number>;
 export declare class InputState {
     private down;
     private prev;
-    /** Analog axes (e.g. from gamepad or pointer), sampled per step. */
+    /**
+     * Analog axes (e.g. from pointer or gamepad), sampled per step. By default
+     * these are LIVE host samples — NOT hashed or logged (see PointerSource).
+     * Axes passed to `beginFrame`'s second argument are the exception: they are
+     * *logged* (enter `getState()` → hash, and the input log), so quantized analog
+     * aim replays bit-exactly. Both live and logged values read back via `axis()`.
+     */
     readonly axes: Map<string, number>;
-    /** Engine: set which actions are down this step (from live input or replay). */
-    beginFrame(actionsDown: Iterable<string>): void;
+    /** The subset of axes that are part of the deterministic log + hash this frame. */
+    private logged;
+    /**
+     * Action names some source has declared it can produce (null until the first
+     * declareActions call). Headless worlds with no sources never declare, so
+     * they never warn — the typo guard only arms once a host wires real input.
+     */
+    private declared;
+    /** Unknown names already warned about (warn ONCE per name). */
+    private warned;
+    /**
+     * Register action names a source (or input map) can produce. The browser
+     * driver declares the keyboard map's actions and the pointer's `mouse.*`
+     * buttons; custom sources should declare theirs too. Once at least one
+     * declaration has happened, querying an undeclared action name via
+     * `isDown`/`justPressed`/`justReleased` logs a console.warn ONCE per name —
+     * catching `isDown('jmup')` typos that would otherwise fail silently.
+     */
+    declareActions(names: Iterable<string>): void;
+    /** Warn-once guard for querying an action no source has declared. O(1). */
+    private checkDeclared;
+    /**
+     * Engine: set which actions are down this step (from live input or replay).
+     * `axes` (optional) are QUANTIZED analog values that become part of the log
+     * and hash for this frame — use `snapAxis`/`quantizeAngle` at the host edge so
+     * replay and lockstep netplay reproduce analog aim exactly.
+     */
+    beginFrame(actionsDown: Iterable<string>, axes?: AxisFrame): void;
     isDown(action: string): boolean;
     justPressed(action: string): boolean;
     justReleased(action: string): boolean;
@@ -16,25 +54,41 @@ export declare class InputState {
     getState(): {
         down: string[];
         prev: string[];
+        axes?: Array<[string, number]>;
     };
     setState(s: {
         down: string[];
         prev: string[];
+        axes?: Array<[string, number]>;
     }): void;
 }
+/**
+ * Quantize an analog value into `buckets` levels across `[min,max]` and return
+ * the SNAPPED value (deterministic — same input → same output on every engine).
+ * Feed the result through `beginFrame`'s axes so analog input is replay-exact.
+ */
+export declare function snapAxis(value: number, buckets: number, min?: number, max?: number): number;
+/** Snap an angle (radians) to the nearest of `buckets` evenly-spaced headings. */
+export declare function quantizeAngle(radians: number, buckets: number): number;
 /** Map a set of raw key codes to the set of actions they trigger. */
 export declare function keysToActions(map: InputMap, keysDown: Set<string>): string[];
 /** Records the per-frame action-down sets → a compact, replayable input log. */
 export declare class InputRecorder {
     private frames;
-    record(actionsDown: string[]): void;
+    private axes;
+    private anyAxes;
+    record(actionsDown: string[], axes?: AxisFrame): void;
     get length(): number;
     toLog(): InputLog;
 }
 export interface InputLog {
     frames: string[][];
+    /** Optional per-frame quantized analog axes, aligned to `frames` (absent = none). */
+    axes?: Array<AxisFrame | undefined>;
 }
 /** Replays a recorded log: returns the action set for frame index i. */
 export declare function frameActions(log: InputLog, i: number): string[];
+/** The logged analog axes for frame index i, or undefined if none were recorded. */
+export declare function frameAxes(log: InputLog, i: number): AxisFrame | undefined;
 /** A default set of common bindings games can start from. */
 export declare const DEFAULT_INPUT_MAP: InputMap;

package/dist/input/gamepad.d.ts

@@ -0,0 +1,101 @@
+import { type InputState } from './actions';
+import type { KeyboardSource } from './source';
+/** A mapping from Gamepad.buttons indices to action names. */
+export type GamepadMap = Record<number, string>;
+export interface GamepadSourceOptions {
+    /**
+     * Gamepad index (0–3). Default 0.
+     * Tip: listen for the 'gamepadconnected' event to discover the right index;
+     * the first connected controller is always index 0.
+     */
+    index?: number;
+    /**
+     * Bucket count for quantizing analog stick values (±1 range).
+     * Higher = finer precision, larger axes log. Default 128 (~0.016 resolution).
+     */
+    stickBuckets?: number;
+    /**
+     * Bucket count for quantizing trigger values (0..1 range).
+     * Default 64 (~0.016 resolution).
+     */
+    triggerBuckets?: number;
+    /**
+     * Deadzone magnitude radius (0..1) applied to each stick independently before
+     * quantization. Values below this threshold are snapped to zero; above it the
+     * range is remapped to 0..1 so the output always uses the full scale.
+     * Default 0.12 (typical hardware drift).
+     */
+    deadzone?: number;
+    /**
+     * Gamepad button index → action name. Pressed buttons call
+     * `keyboard.setHeld(action, on)` so they enter the SAME deterministic action
+     * log as keys and are covered by record/replay + netplay.
+     * Defaults to DEFAULT_GAMEPAD_MAP (face buttons + d-pad mapped to common actions).
+     */
+    buttonMap?: GamepadMap;
+    /**
+     * The KeyboardSource to drive actions through. Required for button→action
+     * routing. Typically `handle.input` from the GameHandle returned by runBrowser.
+     */
+    keyboard?: KeyboardSource;
+}
+/**
+ * Axis keys written each step:
+ *
+ *   gamepad.lx / gamepad.ly   — left stick, ±1 (after deadzone + quantize)
+ *   gamepad.rx / gamepad.ry   — right stick, ±1
+ *   gamepad.lt / gamepad.rt   — left / right trigger, 0..1
+ *   gamepad.dpad.x            — d-pad horizontal, −1 / 0 / +1
+ *   gamepad.dpad.y            — d-pad vertical,   −1 / 0 / +1 (−1 = up)
+ *
+ * Read them in the sim with `world.input.axis('gamepad.lx')`.
+ *
+ * Determinism note: axes written by sample() are live host samples and are NOT
+ * part of the string input log or world.hash() by default. Buttons routed
+ * through a KeyboardSource DO enter the log. For bit-exact analog replay, pass
+ * quantized axes as the second argument to world.step(actions, axes) — they
+ * then enter getState() → hash and InputRecorder.
+ */
+export declare class GamepadSource {
+    private index;
+    private stickBuckets;
+    private triggerBuckets;
+    private deadzone;
+    private buttonMap;
+    private keyboard;
+    /** Track which buttons were pressed last frame to detect edge transitions. */
+    private prevPressed;
+    constructor(opts?: GamepadSourceOptions);
+    /**
+     * Write the current gamepad state into InputState axes (quantized). Call once
+     * per fixed step, before world.advance() — the browser driver does this via
+     * the `sources` option in RunOptions. See also: runBrowser, GameHandle.
+     */
+    sample(input: InputState): void;
+    /**
+     * Release all held actions and clean up. Call when removing the source or
+     * switching gamepads.
+     */
+    dispose(): void;
+}
+/**
+ * Standard Gamepad API button mapping for a "Standard Gamepad" layout
+ * (Xbox / PlayStation / Switch Pro controllers).
+ *
+ *   Index  Xbox        PlayStation   Action
+ *   0      A           Cross         confirm
+ *   1      B           Circle        cancel
+ *   2      X           Square        action2
+ *   3      Y           Triangle      action
+ *   8      Select/View Share         restart (hold to restart)
+ *   9      Start/Menu  Options       confirm (pause menu OK)
+ *   12     D-pad up                  up
+ *   13     D-pad down                down
+ *   14     D-pad left                left
+ *   15     D-pad right               right
+ *
+ * Triggers (6/7) and bumpers (4/5) are intentionally omitted — their analog
+ * values are exposed as gamepad.lt / gamepad.rt axes instead, and games can
+ * add them to a custom map if they want discrete actions.
+ */
+export declare const DEFAULT_GAMEPAD_MAP: GamepadMap;

package/dist/input/source.d.ts

@@ -1,9 +1,25 @@
 import { type InputMap, type InputState } from './actions';
+/**
+ * Minimal contract for a host-side input source. Implement this to feed any
+ * hardware (gamepad, MIDI, accelerometer, on-screen controls) into the sim's
+ * InputState.axes without touching the engine internals.
+ *
+ * The engine samples each registered source once per fixed step, BEFORE
+ * world.advance(). Register via RunOptions.sources or GameHandle.addSource().
+ */
+export interface InputSource {
+    /** Write quantized values into input.axes. Called before each world.advance(). */
+    sample(input: InputState): void;
+    /** Optional cleanup (remove listeners, release held actions). */
+    dispose?(): void;
+}
 import type { Vec2 } from '../core/math';
 export declare class KeyboardSource {
     private keysDown;
     /** Virtual action taps (from DOM buttons etc.) pending consumption by a step. */
     private pressed;
+    /** Sustained virtual actions (held on-screen controls) — persist until released. */
+    private held;
     private map;
     private target;
     private onDown;
@@ -12,6 +28,8 @@ export declare class KeyboardSource {
     constructor(map: InputMap, target?: Document | HTMLElement);
     /** The actions currently held down, as a stable sorted array. */
     currentActions(): string[];
+    /** The action names this source's map can produce (for InputState.declareActions). */
+    actionNames(): string[];
     /**
      * Virtually tap an action (DOM button, touch control). The tap is held until
      * at least one fixed step has sampled it — the driver calls clearPressed()
@@ -21,6 +39,20 @@ export declare class KeyboardSource {
     press(action: string): void;
     /** Consume pending virtual taps (driver-called after ≥1 step ran). */
     clearPressed(): void;
+    /**
+     * Sustain an action for as long as an on-screen control is held. Unlike
+     * `press()` (an edge-shaped tap cleared after one step), a held action models
+     * STATE: it stays in `currentActions()` every step until `setHeld(action,
+     * false)` / `releaseHeld(action)`. This is what a virtual joystick or
+     * hold-to-fire button wants — set it on drag-start, clear it on release, no
+     * re-press-per-frame. Held actions still flow through the same deterministic
+     * action set as keys.
+     */
+    setHeld(action: string, on?: boolean): void;
+    /** Release a sustained action (sugar for `setHeld(action, false)`). */
+    releaseHeld(action: string): void;
+    /** Drop all sustained actions (e.g. on blur / control teardown). */
+    clearHeld(): void;
     setMap(map: InputMap): void;
     dispose(): void;
 }
@@ -33,19 +65,45 @@ export interface PointerReadout {
     down: boolean;
     /** Has the pointer ever produced an event (else x/y are a neutral 0,0)? */
     active: boolean;
+    /** Stable per-touch id (from PointerEvent.pointerId). Absent on the primary hover readout. */
+    id?: number;
 }
 /** What a PointerSource needs from a renderer: the DOM node + the design mapper. */
 export interface PointerTarget {
     readonly element?: HTMLElement | SVGElement;
     toDesign?(clientX: number, clientY: number): Vec2;
 }
+export interface PointerSourceOptions {
+    /**
+     * Allow the browser's context menu on the attached element. Default false —
+     * the menu is suppressed (preventDefault on 'contextmenu') so right-click is
+     * usable as game input.
+     */
+    contextMenu?: boolean;
+    /**
+     * Route pointer buttons into the deterministic action pipeline: while a
+     * button is held, `sample()` calls `keyboard.setHeld('mouse.left' |
+     * 'mouse.right' | 'mouse.middle')` so buttons enter the SAME actionsDown log
+     * as keys — `justPressed('mouse.right')` works, replays stay exact, and an
+     * inputMap can bind them (`shield: ['mouse.right']`). The browser driver
+     * wires this to the GameHandle's KeyboardSource automatically.
+     */
+    keyboard?: KeyboardSource;
+}
+/** The pointer-button action names PointerSource can hold (via its keyboard). */
+export declare const MOUSE_ACTIONS: readonly ["mouse.left", "mouse.right", "mouse.middle"];
 /**
  * Continuous pointer / touch input — the sibling of KeyboardSource for games
  * driven by *where* the cursor is (slice, aim, drag, point-and-click, placement).
  * It listens on the renderer's canvas, converts every event to DESIGN space via
  * `renderer.toDesign`, and each fixed step writes the sample into InputState's
- * analog axes: `pointer.x`, `pointer.y`, `pointer.down` (1/0). Sim code then
- * reads `world.input.axis('pointer.x')` — no out-of-engine letterbox glue.
+ * analog axes: `pointer.x`, `pointer.y`, `pointer.down` (1/0), plus
+ * `pointer.right` / `pointer.middle` (1/0) for the secondary mouse buttons
+ * (the context menu is suppressed by default so right-click is usable — see
+ * PointerSourceOptions). Sim code then reads `world.input.axis('pointer.x')`
+ * — no out-of-engine letterbox glue. With `keyboard` wired, buttons also enter
+ * the action pipeline as `mouse.left/right/middle` (bindable in an inputMap,
+ * `justPressed`-able, replay-exact).
  *
  * Determinism note: axes are host-sampled live input and are NOT part of the
  * string input log or the world hash. `sample()` QUANTIZES design coords to a
@@ -53,23 +111,46 @@ export interface PointerTarget {
  * the sim only ever sees the quantized values, live or replayed. For lockstep
  * netplay, still prefer discrete actions (map a tap to a key via
  * KeyboardSource.press, or snap position to a grid cell). See docs/CONVENTIONS.md.
+ *
+ * Multitouch: `read()`/`sample()` describe the PRIMARY pointer (mouse or the
+ * most-recent finger) and are byte-identical to the single-pointer past. For
+ * dual-stick / multi-finger schemes, read every live touch via `readAll()` —
+ * each carries its stable `id` so you can tell which finger is which.
  */
 export declare class PointerSource {
     private clientX;
     private clientY;
     private isDown;
+    private rightDown;
+    private middleDown;
     private seen;
+    /** Live touches by pointerId (a pressed finger/button); excludes hover-only mouse. */
+    private touches;
     private target;
     private el;
+    private keyboard;
     private onMove;
     private onDown;
     private onUp;
-    constructor(target: PointerTarget);
+    private onCtx;
+    constructor(target: PointerTarget, opts?: PointerSourceOptions);
     /** The current pointer position in design space + press state. */
     read(): PointerReadout;
+    /**
+     * Every live (pressed) touch in DESIGN space, ordered by ascending id so the
+     * array is stable to iterate. Empty when nothing is pressed. This is the
+     * multitouch channel — a dual-stick game reads `left = touches[0]`, etc., or
+     * partitions by screen half.
+     */
+    readAll(): PointerReadout[];
     /**
      * Write the current sample into an InputState's axes as pointer.x / pointer.y /
-     * pointer.down. Call once per step (the browser driver does this before advance).
+     * pointer.down, plus pointer.right / pointer.middle (0/1) for the secondary
+     * buttons. Call once per step (the browser driver does this before advance).
+     *
+     * When a keyboard is wired (PointerSourceOptions.keyboard), buttons are ALSO
+     * held as actions `mouse.left` / `mouse.right` / `mouse.middle` so they flow
+     * through the same deterministic actionsDown log as keys.
      */
     sample(input: InputState): void;
     dispose(): void;

package/dist/logic/coroutine.d.ts

@@ -0,0 +1,68 @@
+/** Resumes after `seconds` of accumulated sim time. */
+export declare function sleep(seconds: number): Wait;
+/** Resumes on the first step where `cond()` is true (checked once per step). */
+export declare function waitFor(cond: () => boolean): Wait;
+/** Resumes on the next step — yields one frame (e.g. to let a spawn render). */
+export declare function nextStep(): Wait;
+/**
+ * Resumes when ANY of the waits completes; the yield expression evaluates to
+ * the winning index (ties resolve to the lowest index — deterministic).
+ */
+export declare function race(...waits: Wait[]): Wait;
+/** Resumes when ALL of the waits have completed. */
+export declare function all(...waits: Wait[]): Wait;
+interface SleepWait {
+    kind: 'sleep';
+    left: number;
+}
+interface CondWait {
+    kind: 'cond';
+    cond: () => boolean;
+    /** Memo so a satisfied condition is never re-evaluated (inside all()). */
+    met?: boolean;
+}
+interface NextWait {
+    kind: 'next';
+    passed?: boolean;
+}
+interface RaceWait {
+    kind: 'race';
+    waits: Wait[];
+}
+interface AllWait {
+    kind: 'all';
+    waits: Wait[];
+}
+/** What a coroutine may yield. A `CoroutineHandle` yield joins that runner. */
+export type Wait = SleepWait | CondWait | NextWait | RaceWait | AllWait | CoroutineHandle;
+/** A started coroutine. `done` flips when it returns, throws, or is stopped. */
+export interface CoroutineHandle {
+    readonly name: string;
+    readonly done: boolean;
+    /** Kill the runner (its generator's finally blocks run via `return()`). */
+    stop(): void;
+}
+/**
+ * A deterministic scheduler for many concurrent coroutines. Owns no clock —
+ * call `step(dt)` from wherever your game advances (typically a brain node's
+ * `onUpdate`), so coroutine time IS sim time.
+ */
+export declare class Coroutines {
+    private runners;
+    /** Started since the last step boundary; adopted at the top of the next step. */
+    private pending;
+    private nextId;
+    /**
+     * Register a coroutine. Its body runs (up to the first yield) on the NEXT
+     * `step()` — never immediately, and never mid-step. Pass a `name` so a
+     * thrown generator warns something better than "co3".
+     */
+    start(gen: () => Generator<Wait, void, number>, name?: string): CoroutineHandle;
+    /** Advance every live runner by one fixed step, in insertion order. */
+    step(dt: number): void;
+    /** Stop every runner (including ones not yet adopted). */
+    stopAll(): void;
+    /** Live runner count (started-but-not-yet-stepped ones included). */
+    get active(): number;
+}
+export {};

package/dist/render/canvas.d.ts

@@ -1,5 +1,5 @@
-import { type DrawCommand } from './commands';
-import { type Renderer, type 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;
@@ -12,13 +12,9 @@ export declare class Canvas2DRenderer implements Renderer {
     mount(parent: HTMLElement): void;
     private resize;
     draw(commands: DrawCommand[]): void;
-    /** Resolve a fill: a gradient (mapped to the shape's bbox) or a solid color. */
-    private fillFor;
-    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,13 @@
+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.
+ *
+ * A lighting run (commands at `LAYER_LIGHT`) is composited through an offscreen
+ * buffer between the world and HUD passes: world → light buffer (multiply) →
+ * HUD. When no light run is present this is exactly the old single-pass paint.
+ */
+export declare function drawToCanvas2D(ctx: Ctx2D, commands: DrawCommand[], width: number, height: number, background: string, scale: number): void;
+export {};

package/dist/render/commands.d.ts

@@ -45,6 +45,19 @@ export interface Paint {
     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[];
+    /**
+     * Blend mode for compositing this command over what is already painted — the
+     * Canvas2D/SVG-expressible intersection: `'multiply'` darkens (ambient base,
+     * shadow quads), `'screen'` brightens (a light pool). Omit for normal
+     * source-over. Consumed by the lighting run (see render/lightRun.ts); Canvas
+     * maps it to `globalCompositeOperation`, SVG to `mix-blend-mode`.
+     */
+    blend?: 'multiply' | 'screen';
 }
 export type TextAlign = 'left' | 'center' | 'right';
 interface Base extends Paint {
@@ -52,6 +65,13 @@ 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
@@ -75,6 +95,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. */
@@ -105,7 +147,18 @@ 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;
+/**
+ * Render-layer conventions. Commands sort by layer FIRST (see `sortCommands`),
+ * so these are painter-order bands, not a fixed enum — a game may still use any
+ * fractional layer. `LAYER_LIGHT` sits between world and HUD so the lighting run
+ * multiplies over world content but never darkens the overlay pass.
+ */
+export declare const LAYER_WORLD = 0;
+/** The lighting run: reserved band above the world, below the HUD. */
+export declare const LAYER_LIGHT = 0.5;
+/** Screen-space overlay pass (HUD, transitions) — set for `screenSpace` subtrees. */
+export declare const LAYER_HUD = 1;
+/** 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/lightRun.d.ts

@@ -0,0 +1,35 @@
+import { type CircleCommand, type DrawCommand, type PolyCommand, type RectCommand } from './commands';
+/** The three painter bands the compositor needs: world, the light run, HUD/overlay. */
+export interface LightRunSplit {
+    /** Everything below the light layer (the lit world). */
+    below: DrawCommand[];
+    /** The light run itself (layer === LAYER_LIGHT), in stream order. */
+    light: DrawCommand[];
+    /** Everything above the light layer (HUD/overlay — never darkened). */
+    above: DrawCommand[];
+}
+/**
+ * Split a SORTED display list into below/light/above runs by layer. The caller
+ * passes commands already through `sortCommands`, so the light run is contiguous.
+ */
+export declare function splitByLightLayer(sorted: DrawCommand[]): LightRunSplit;
+/** One parsed light: its pool circle plus the shadow polys that erase it. */
+export interface ParsedLight {
+    circle: CircleCommand;
+    shadows: PolyCommand[];
+}
+/** A parsed light run: the ambient darkness base + the per-light pools/shadows. */
+export interface ParsedLightRun {
+    ambient: RectCommand;
+    lights: ParsedLight[];
+}
+/**
+ * Parse a light run (as produced by `splitByLightLayer().light`) into its
+ * structured form, or `null` if the stream does not match the expected order —
+ * in which case the backend must fall back to painting the run flat. An EMPTY
+ * run is unparseable (null): there is nothing to composite, so backends paint
+ * it flat (a no-op) and produce byte-identical output to a lit-layer-free frame.
+ */
+export declare function parseLightRun(run: DrawCommand[]): ParsedLightRun | null;
+/** True when a command carries the light-layer tag (helper for tests/backends). */
+export declare const isLightCommand: (c: DrawCommand) => boolean;

package/dist/render/paint.d.ts

@@ -25,6 +25,14 @@ export interface BBox {
 }
 /** 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;

package/dist/render/renderer.d.ts

@@ -18,8 +18,24 @@ export interface Renderer {
      * (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;
@@ -36,3 +52,12 @@ export declare function clientToDesign(rect: {
     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,5 @@
 import type { DrawCommand } from './commands';
-import { type Renderer, type 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;
@@ -15,5 +15,6 @@ export declare class SvgRenderer implements Renderer {
     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,9 +1,14 @@
 import { type DrawCommand } from './commands';
 /**
  * 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.
+ * ids of any gradient/shadow/mask <defs> so several inner markups can share one
+ * SVG document (e.g. a filmstrip) without their `url(#…)` references colliding.
+ *
+ * A lighting run (commands at `LAYER_LIGHT`) is emitted as the nested-blend group
+ * between the world and HUD passes. An EMPTY or unparseable run falls through the
+ * normal per-command path (honouring each command's `blend` via mix-blend-mode),
+ * so a lit-layer-free frame is byte-identical to before this feature.
  */
-export declare function commandsToSVGInner(commands: DrawCommand[], idPrefix?: string): string;
+export declare function commandsToSVGInner(commands: DrawCommand[], idPrefix?: string, viewW?: number, viewH?: number): 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;