hayao 0.4.0 → 0.4.1

package/docs/API.md

@@ -3,19 +3,23 @@
 > Auto-generated by `npm run api`. Everything importable from `@hayao`.
 > Grep here for the real surface — never guess an API from memory.
 
-**717 exports.**
+**775 exports.**
 
-## classs (59)
+## classs (68)
 
 - `AmbientField`
 - `AnimationPlayer`
 - `AudioBus`
 - `BitmapText`
+- `Blend1D`
+- `Blend2D`
+- `Bone2D`
 - `BroadcastChannelTransport`
 - `Camera2D`
 - `CameraController`
 - `Canvas2DRenderer`
 - `CinematicPlayer`
+- `ClipPlayer`
 - `Clock`
 - `Coroutines`
 - `DepthSort`
@@ -24,11 +28,13 @@
 - `Fsm`
 - `GamepadSource`
 - `HeadlessRenderer`
+- `IkTarget`
 - `InputBuffer`
 - `InputRecorder`
 - `InputState`
 - `IsoPrism`
 - `KeyboardSource`
+- `LightLayer`
 - `LocalStorageAdapter`
 - `LockstepSession`
 - `LoopbackHub`
@@ -44,6 +50,7 @@
 - `PixelBuffer`
 - `PlayerInput`
 - `PointerSource`
+- `PointLight`
 - `RingBuffer`
 - `Rng`
 - `RollbackSession`
@@ -54,6 +61,8 @@
 - `Shaker`
 - `Shell`
 - `Signal`
+- `Skeleton`
+- `SkeletonDebug`
 - `SnapshotRing`
 - `SpatialHash`
 - `Sprite`
@@ -67,7 +76,7 @@
 - `WebGL2Renderer`
 - `World`
 
-## functions (310)
+## functions (330)
 
 - `abilitiesOf`: (world: WorldGraphDef, taken: readonly string[]) => Set<string>
 - `addBody`: (rw: RigidWorld, def: RigidBodyDef) => number
@@ -77,6 +86,7 @@
 - `albumTrack`: (id: string) => AlbumTrack | undefined
 - `all`: (...waits: Wait[]) => Wait
 - `analyzePlaytest`: (def: GameDefinition<Record<string, unknown>>, session: PlaytestSession, opts?: AnalyzeOptions) => PlaytestReport
+- `applyChannel`: (node: Node, channel: ClipChannel, value: number) => void
 - `applyImpulse`: (rw: RigidWorld, id: number, ix: number, iy: number, px?: number | undefined, py?: number | undefined) => void
 - `applyReverb`: (buf: StereoBuffer, opts?: ReverbOptions) => void
 - `applyTransform`: (m: Transform, p: Vec2) => Vec2
@@ -93,10 +103,12 @@
 - `availableUpgrades`: (defs: readonly UpgradeDef[], owned: readonly string[]) => UpgradeDef[]
 - `bandBalance`: (sig: Samples, sampleRate?: number) => BandBalance
 - `bfs`: <N>(start: N, neighbours: Neighbours<N>, key: NodeKey<N>, opts?: { goal?: ((n: N) => boolean) | undefined; maxNodes?: number | undefined; }) => BfsResult<N>
+- `blendIssues`: (samples: BlendSample[], dims?: 2 | 1) => string[]
 - `blobPath`: (rng: Rng, radius: number, wobble?: number, lobes?: number) => string
 - `bodyAABB`: (b: RigidBody) => Rect
 - `bodyContains`: (b: RigidBody, x: number, y: number) => boolean
 - `bootDom`: (def: GameDefinition<Record<string, unknown>>, mount?: HTMLElement | undefined) => DomHarness
+- `buildSkeleton`: (root: Node) => Skeleton
 - `cadenceResolves`: (romans: string[]) => boolean
 - `cameraIssues`: (samples: readonly Vec2[], opts?: CameraOptions) => string[]
 - `canvasGradient`: (ctx: { createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient; createRadialGradient(x0: number, y0: number, r0: number, x1: nu…
@@ -108,8 +120,12 @@
 - `chordChanges`: (symbols: string[], octave?: number) => number[][]
 - `chordNotes`: (symbol: string, octave?: number) => number[]
 - `clientToDesign`: (rect: { left: number; top: number; width: number; height: number; }, width: number, height: number, clientX: number, clientY: number) => Vec2
+- `clipEvents`: (def: ClipDef, prev: number, next: number) => string[]
+- `clipFinished`: (def: ClipDef, elapsed: number) => boolean
+- `clipIssues`: (def: ClipDef, knownTargets?: readonly string[] | undefined) => string[]
+- `clipTime`: (def: ClipDef, elapsed: number) => number
 - `collide`: (a: RigidBody, b: RigidBody) => Manifold | null
-- `commandsToSVGInner`: (commands: DrawCommand[], idPrefix?: string) => string
+- `commandsToSVGInner`: (commands: DrawCommand[], idPrefix?: string, viewW?: number, viewH?: number) => string
 - `composeCampaign`: <State, Move>(spec: CampaignSpec<State, Move>) => Campaign<State, Move>
 - `composeTransform`: (m: Transform, n: Transform) => Transform
 - `connectedComponents`: (cols: number, rows: number, passable: Passable, diagonal?: boolean) => Components
@@ -122,6 +138,7 @@
 - `createStereo`: (durationSec: number, sampleRate?: number) => StereoBuffer
 - `createWorld`: <TState extends Record<string, unknown> = Record<string, unknown>>(def: GameDefinition<TState>, opts?: number | CreateWorldOptions | undefined) => World<...>
 - `crestFactorDb`: (sig: Samples) => number
+- `cullSegments`: (light: Vec2, radius: number, segs: readonly ContourSegment[]) => ContourSegment[]
 - `dashJumpDistance`: (cfg?: PlatformerConfig) => number
 - `datan`: (x: number) => number
 - `datan2`: (y: number, x: number) => number
@@ -215,6 +232,7 @@
 - `levelIssues`: (data: LevelData) => string[]
 - `levelReachable`: (data: LevelData, opts?: { passable?: Passable | undefined; diagonal?: boolean | undefined; }) => ReachReport
 - `levelToTilemap`: (data: LevelData) => TilemapData
+- `lightingIssues`: (commands: DrawCommand[], avatarFill: string, avatarWorld: Vec2, opts?: LightingOptions) => string[]
 - `linearGradient`: (stops: readonly StopInput[], angleDeg?: number) => LinearGradient
 - `lineOfSight`: (map: TilemapData, ax: number, ay: number, bx: number, by: number) => boolean
 - `lintSong`: (song: Song, opts?: LintOptions) => MusicLintResult
@@ -238,6 +256,7 @@
 - `mix`: (a: string, b: string, t: number) => string
 - `mixLinear`: (a: string, b: string, t: number) => string
 - `mixMono`: (bus: StereoBuffer, sig: Samples, startSample: number, gain?: number, pan?: number) => void
+- `mixPose`: (a: Pose, b: Pose, t: number, out?: Pose) => Pose
 - `moveRect`: (map: TilemapData, rect: Rect, dx: number, dy: number, opts?: MoveOpts) => MoveResult
 - `mutateColor`: (rng: Rng, hex: string, amounts?: DriftAmounts) => string
 - `netMessage`: <T extends Omit<NetMessage, "v">>(msg: T) => T & { v: number; }
@@ -245,11 +264,13 @@
 - `nineSlice`: (rect: Rect, style: NineSliceStyle, z?: number, transform?: Transform) => DrawCommand[]
 - `normalize`: (buf: StereoBuffer, target?: number) => void
 - `noteToMidi`: (name: string) => number
+- `occludersFromTilemap`: (map: TilemapData) => ContourSegment[]
 - `onsetDensity`: (sig: Samples, sampleRate?: number) => number
 - `openVoicing`: (chord: number[]) => number[]
 - `packVarints`: (nums: readonly number[]) => string
 - `panFromOffset`: (dx: number, spread?: number) => number
 - `panGains`: (pan: number) => { l: number; r: number; }
+- `parseLightRun`: (run: DrawCommand[]) => ParsedLightRun | null
 - `parseRich`: (markup: string, colorMap?: Record<string, string>) => RichChar[]
 - `parseSnapshot`: (text: string | null) => WorldSnapshot | null
 - `passableFromTilemap`: (map: TilemapData) => Passable
@@ -296,6 +317,7 @@
 - `replaySession`: (def: GameDefinition<Record<string, unknown>>, session: PlaytestSession, opts?: number | ReplayOptions | undefined) => World<...>
 - `resetNodeIds`: (start?: number) => void
 - `resetZzfxWarnings`: () => void
+- `resolveTracks`: (def: ClipDef, skeleton: Skeleton) => BoundTrack[]
 - `resolveTuning`: (spec: TuningSpec | undefined, overrides?: TuningValues | undefined) => TuningValues
 - `rigidStep`: (rw: RigidWorld, dt: number) => ContactEvent[]
 - `rleDecode`: (input: string) => string
@@ -309,7 +331,10 @@
 - `runHeadless`: <TState extends Record<string, unknown> = Record<string, unknown>>(def: GameDefinition<TState>, inputLog?: InputLog | undefined) => HeadlessResult<TState>
 - `runStudio`: (baseDef: GameDefinition<Record<string, unknown>>, mount: HTMLElement, opts?: StudioOptions) => StudioHandle
 - `salienceIssues`: (commands: DrawCommand[], avatarFill: string, background: string, opts?: SalienceOptions) => string[]
+- `sampleClip`: (def: ClipDef, elapsed: number) => SampledChannel[]
 - `sampleGradient`: (stops: readonly string[], t: number) => string
+- `samplePose`: (def: ClipDef, phase: number) => Pose
+- `sampleTrack`: (keys: Keyframe[], t: number) => number
 - `scaleMidis`: (tonic: number, mode?: "major" | "minor" | "harmonicMinor" | "melodicMinor" | "dorian" | "phrygian" | "lydian" | "mixolydian" | "locrian" | "majorPentatonic"…
 - `scalePitchClasses`: (tonic: number, mode?: "major" | "minor" | "harmonicMinor" | "melodicMinor" | "dorian" | "phrygian" | "lydian" | "mixolydian" | "locrian" | "majorPentatonic"…
 - `scatter`: (x: number, y: number, probability: number, seed?: number) => boolean
@@ -324,6 +349,7 @@
 - `setScreenObserver`: (cb: ((kind: "show" | "hide", title?: string | undefined) => void) | null) => void
 - `shadeHex`: (hex: string, f: number) => string
 - `shadowDef`: (s: Shadow, id: string) => string
+- `shadowQuads`: (light: Vec2, radius: number, segs: readonly ContourSegment[]) => number[][]
 - `shapeBBox`: (c: DrawCommand) => BBox | null
 - `shapeBox`: (cmd: DrawCommand) => { x: number; y: number; w: number; h: number; } | null
 - `showScreen`: (spec: ScreenSpec) => ScreenHandle
@@ -336,13 +362,16 @@
 - `softClipInPlace`: (buf: StereoBuffer) => void
 - `solidNeighbours`: (g: Grid, x: number, y: number) => number
 - `solve`: <State, Move>(puzzle: Puzzle<State, Move>, options?: SolveOptions) => SolveResult<Move>
+- `solveFabrik`: (root: Vec2, lengths: number[], target: Vec2, opts?: { maxIter?: number | undefined; tolerance?: number | undefined; initial?: Vec2[] | undefined; }) => Fabr…
 - `solveJoint`: (j: Joint, A: RigidBody, B: RigidBody, dt: number, scratch: JointScratch) => void
+- `solveTwoBoneIK`: (root: Vec2, l0: number, l1: number, target: Vec2, bendDir?: 1 | -1) => TwoBoneResult
 - `songBeats`: (song: Song) => number
 - `songDuration`: (song: Song) => number
 - `sortCommands`: (cmds: DrawCommand[]) => DrawCommand[]
 - `spatialMix`: (dx: number, dy: number, hearing?: number, rolloff?: number) => SpatialMix
 - `specFromZzfx`: (p: readonly (number | undefined)[]) => SoundSpec
 - `spectralCentroid`: (sig: Samples, sampleRate?: number) => number
+- `splitByLightLayer`: (sorted: DrawCommand[]) => LightRunSplit
 - `springStep`: (s: SpringState, target: number, omega: number, dt: number) => SpringState
 - `star`: (points: number, outer: number, inner: number, rotation?: number) => number[]
 - `steer2D`: (px: number, py: number, tx: number, ty: number, out: string[], dead?: number) => void
@@ -380,7 +409,7 @@
 - `worldPoints`: (b: RigidBody) => number[]
 - `zcr`: (sig: Samples, sampleRate?: number) => number
 
-## interfaces (240)
+## interfaces (259)
 
 - `AcceptedProof`
 - `ActBounds`
@@ -402,7 +431,10 @@
 - `BfsResult`
 - `BitmapFont`
 - `BitmapTextConfig`
+- `BlendSample`
+- `Bone2DConfig`
 - `BotCtx`
+- `BoundTrack`
 - `Breakpoint`
 - `CameraBounds`
 - `CameraConfig`
@@ -416,6 +448,9 @@
 - `Cell`
 - `CinematicStep`
 - `CircleCommand`
+- `ClipDef`
+- `ClipEvent`
+- `ClipPlayerConfig`
 - `ClockConfig`
 - `Components`
 - `ContactEvent`
@@ -439,6 +474,7 @@
 - `Dungeon`
 - `DungeonOptions`
 - `EllipseCommand`
+- `FabrikResult`
 - `FeatureDelta`
 - `FeedbackOptions`
 - `FeedbackResponse`
@@ -466,6 +502,7 @@
 - `HesitationSpan`
 - `HotContext`
 - `HSL`
+- `IkTargetConfig`
 - `ImageCommand`
 - `InputLog`
 - `InputSource`
@@ -473,12 +510,16 @@
 - `IsoPrismConfig`
 - `IsoProjection`
 - `JointScratch`
+- `Keyframe`
 - `KnobEvent`
 - `LayoutOptions`
 - `LevelChange`
 - `LevelData`
 - `LevelEntity`
 - `LevelSpec`
+- `LightingOptions`
+- `LightLayerConfig`
+- `LightRunSplit`
 - `LinearGradient`
 - `LintOptions`
 - `LockstepOptions`
@@ -501,6 +542,8 @@
 - `Paint`
 - `Palette`
 - `ParallaxLayerConfig`
+- `ParsedLight`
+- `ParsedLightRun`
 - `ParticleStyle`
 - `PathCommand`
 - `PhaseDef`
@@ -518,6 +561,7 @@
 - `PointerReadout`
 - `PointerSourceOptions`
 - `PointerTarget`
+- `PointLightConfig`
 - `PolyCommand`
 - `PostProcessPass`
 - `ProgressState`
@@ -552,6 +596,7 @@
 - `RoomHostOptions`
 - `RunOptions`
 - `SalienceOptions`
+- `SampledChannel`
 - `ScreenEvent`
 - `ScreenHandle`
 - `ScreenSpec`
@@ -561,6 +606,7 @@
 - `Settings`
 - `Shadow`
 - `ShellOptions`
+- `SkeletonDebugConfig`
 - `SoftlockReport`
 - `SolidRect`
 - `SolveOptions`
@@ -594,12 +640,14 @@
 - `TouchControlsLayout`
 - `TouchStick`
 - `Track`
+- `TrackDef`
 - `Transform`
 - `Transition`
 - `TransitionConfig`
 - `Transport`
 - `TuningKnob`
 - `TuningSpec`
+- `TwoBoneResult`
 - `UpgradeDef`
 - `Variant`
 - `VariantRef`
@@ -623,11 +671,13 @@
 - `WorldRegion`
 - `WorldSnapshot`
 
-## types (46)
+## types (50)
 
 - `AxisFrame`
 - `BodyKind`
 - `BoolGrid`
+- `ClipChannel`
+- `ClipLoop`
 - `CompletionMode`
 - `DistanceModel`
 - `DrawCommand`
@@ -648,10 +698,12 @@
 - `NetMessage`
 - `NodeFactory`
 - `NodeKey`
+- `Occluder`
 - `Passable`
 - `PauseMode`
 - `Pitch`
 - `PlayerId`
+- `Pose`
 - `ProbeFrame`
 - `ProgressMove`
 - `RigidShape`
@@ -672,13 +724,14 @@
 - `WipeKind`
 - `WorldFactory`
 
-## consts (61)
+## consts (67)
 
 - `ALBUM`: { title: string; subtitle: string; concept: string; tracks: AlbumTrack[]; }
 - `AMBIENT_PRESETS`: { readonly snow: (colors?: string[]) => AmbientStyle; readonly rain: (colors?: string[]) => AmbientStyle; readonly ash: (colors?: string[]) => AmbientStyle; }
 - `audio`: AudioBus
 - `BLOOM_PIPELINE`: PostProcessPass[]
 - `clamp`: (v: number, lo: number, hi: number) => number
+- `CLIP_CHANNELS`: readonly ClipChannel[]
 - `DEFAULT_GAMEPAD_MAP`: GamepadMap
 - `DEFAULT_INPUT_MAP`: Readonly<Record<string, readonly string[]>>
 - `DEFAULT_PLATFORMER`: PlatformerConfig
@@ -696,8 +749,12 @@
 - `IDENTITY`: Transform
 - `INSTRUMENTS`: Record<string, Instrument>
 - `invLerp`: (a: number, b: number, v: number) => number
+- `isLightCommand`: (c: DrawCommand) => boolean
 - `KENTO`: { readonly gofun: "#f7f1e2"; readonly washi: "#efe7d3"; readonly kinu: "#e4d8bd"; readonly line: "#d8cbac"; readonly kinako: "#b9a882"; readonly stone: "#6c6…
 - `knob`: { num(key: string, opts: { default: number; min?: number | undefined; max?: number | undefined; step?: number | undefined; label?: string | undefined; group?…
+- `LAYER_HUD`: 1
+- `LAYER_LIGHT`: 0.5
+- `LAYER_WORLD`: 0
 - `lerp`: (a: number, b: number, t: number) => number
 - `lerpDamp`: (current: number, target: number, lambda: number, dt: number) => number
 - `mapHeight`: (map: TilemapData) => number
@@ -714,6 +771,7 @@
 - `PARTICLE_PRESETS`: { readonly dust: (colors?: string[]) => ParticleStyle; readonly burst: (colors?: string[]) => ParticleStyle; readonly hit: (colors?: string[]) => ParticleSty…
 - `playerAction`: (player: string, action: string) => string
 - `playerInput`: (world: World<Record<string, unknown>>, player: string) => PlayerInput
+- `poseKey`: (target: string, channel: string) => string
 - `rad2deg`: (r: number) => number
 - `remap`: (v: number, a0: number, a1: number, b0: number, b1: number) => number
 - `SAMPLE_RATE`: 44100
@@ -730,7 +788,7 @@
 - `vdist`: (a: Vec2, b: Vec2) => number
 - `vdot`: (a: Vec2, b: Vec2) => number
 - `vec2`: (x?: number, y?: number) => Vec2
-- `VERSION`: "0.4.0"
+- `VERSION`: "0.4.1"
 - `vlen`: (a: Vec2) => number
 - `vscale`: (a: Vec2, s: number) => Vec2
 - `vsub`: (a: Vec2, b: Vec2) => Vec2

package/docs/CONVENTIONS.md

@@ -342,6 +342,62 @@ broken by tree order. For any game where sprites overlap (top-down, iso), derive
 - **`diamond` / `regularPoly` shapes** — sugar over `poly` so an iso tile or hex
   reads as intent, not four re-typed corners.
 
+## The animation & lighting seam
+
+Two subsystems landed in 0.4.1 — authored **animation** (clips, blend spaces, IK,
+skeletons) and 2D **lighting** (a light layer, point lights, occluder shadows).
+They look unrelated, but they ride the SAME rule, and it is the one rule that
+keeps them from rotting the sim: **deterministic data lives in the sim; the
+motion and the light are observer-side presentation.**
+
+Concretely, on the LOGICAL side (`world.state`, hashed, rolled back, replayed):
+the pose a game *reasons about* is an `Fsm.current` / `PhaseClock` / committed
+anchors + hitboxes in `world.state`, all advanced through `dmath`. Light state
+that *drives gameplay* (is the torch lit? how alarmed is the sentry?) is a value
+in `world.state` too. On the OBSERVER side: `ClipPlayer`, `IkTarget`,
+`SkeletonDebug`, `LightLayer`, and `PointLight` are all `cosmetic = true` by
+construction — they render state that lives elsewhere and are **excluded from
+`serialize()` / `hash()` / `snapshot()`**. State flows LOGICAL → view, never the
+reverse.
+
+What that forbids, in order of how often it bites:
+
+- **Never read a visual pose back into the sim.** A gameplay anchor — a muzzle,
+  a hand, a foot-plant — is computed on the LOGICAL side with `dmath`, NEVER read
+  from a posed `bone.worldTransform()`. The clip/IK result is one frame of eased,
+  crossfaded, observer-only motion; sampling it into the sim couples the hash to
+  the animation and the replay diverges. **The committed-anchor recipe** is the
+  lead pattern: the sim owns the muzzle point as a `dmath` offset from the
+  logical body (in `world.state`); the ClipPlayer poses the visible gun to *point
+  at* it; a shot spawns from the committed anchor, not from the barrel sprite's
+  world transform. The picture follows the truth; the truth never asks the
+  picture where it landed.
+- **Blend weights, IK reach, and light intensity never gate gameplay.** A
+  `Blend1D` weight, an `IkTarget.reached` flag, a `PointLight.litIntensity` after
+  flicker — these are view outputs. Branch gameplay on the logical parameter that
+  *fed* them (the `world.state` speed, the logical "is the target in range"
+  distance, the `world.state` lit boolean), not on the interpolated result.
+- **Secondary-motion and flicker RNG is observer-seeded — never `world.rng`.**
+  A `PointLight`'s flicker uses a private `Rng` seeded at construction (the
+  Particles precedent), advanced in `onProcess`, never in `draw` (which may run
+  0..n times per step). Same for any spring/wobble jitter on the rig. Pulling
+  those numbers from `world.rng` would race the gameplay stream and desync every
+  replay.
+
+**The proof pattern to copy** is the stripped-rig hash-equality test in
+`src/scene/clipPlayer.test.ts`: build a world whose logic advances every frame
+*with* the full cosmetic rig, build the same world *without* it, and assert
+`withRig.hash() === without.hash()` at every frame (plus `assertSnapshotStable`
+with warmup landing mid-clip and mid-crossfade). If stripping the animation
+changes the hash, a visual write has leaked into the sim — the test names the
+frame. Lighting has the same proof: `examples/duskveil/` was relit with a
+`LightLayer` + two cosmetic `PointLight`s over the existing fight, and its golden
+hash is **unchanged** — the lights are pure view, so the pinned replay survives
+the relight. Both sandboxes wire the seam the idiomatic way end to end
+(`sandboxes/anim-lab/` for the rig, `sandboxes/light-lab/` for the lights):
+canonical knob state is hashed, the whole rig/light apparatus is cosmetic and
+excluded.
+
 ## The human-contact layer
 
 The first real playtest of the campaign found every defect in the one layer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hayao",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "An AI-first game engine: a deterministic, headless-native simulation kernel with a Godot-style scene tree, pluggable renderers (SVG/Canvas/headless), and a built-in verification harness — designed so an LLM can author, test, and prove correct a whole game without ever opening a browser.",
   "keywords": [