hayao 0.4.0 → 0.4.1

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

@@ -4,6 +4,10 @@ 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

@@ -50,6 +50,14 @@ export interface Paint {
      * 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 {
@@ -140,6 +148,17 @@ export interface ImageCommand extends Base {
     h: number;
 }
 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/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;

package/dist/scene/clipPlayer.d.ts

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

package/dist/scene/ikTarget.d.ts

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

package/dist/scene/light.d.ts

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

package/dist/scene/shadow2d.d.ts

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

package/dist/scene/skeletonDebug.d.ts

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

package/dist/verify/gates.d.ts

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