hayao 0.1.0 → 0.3.0

package/dist/app/game.d.ts

@@ -2,6 +2,23 @@ import { World } from '../world';
 import type { Node } from '../scene/node';
 import { type InputLog, type InputMap } from '../input/actions';
 import type { ClockConfig } from '../core/clock';
+import { type TuningSpec, type TuningValues } from './tuning';
+/**
+ * Optional boot splash. Rendered by the engine (so its colors are palette-guaranteed
+ * and never trip a contrast escape the way a hand-rolled loading <div> can) while
+ * `preload` runs. Pass `splash: false` to opt out entirely.
+ */
+export interface SplashConfig {
+    /** Splash headline (defaults to the game title). */
+    title?: string;
+    /** Background/foreground pair; defaults to a contrast-guaranteed pair from the game background. */
+    palette?: {
+        bg: string;
+        fg: string;
+    };
+    /** Keep the splash up at least this long, so a fast preload doesn't flash by. */
+    minDurationMs?: number;
+}
 export interface GameDefinition {
     title: string;
     width?: number;
@@ -14,11 +31,39 @@ export interface GameDefinition {
     build(world: World): Node;
     /** Optional compact probe snapshot for verification (defaults to World.probe). */
     probe?(world: World): Record<string, unknown>;
+    /**
+     * Live-tunable parameters, declared once. Defaults ARE the config; Studio and
+     * tests override them via `createWorld(def, { tuning })` and the sim reads
+     * resolved values with `world.tune(key)`. Values are hashed + snapshotted.
+     */
+    tuning?: TuningSpec;
+    /**
+     * Re-attach behaviors/controllers after `world.restore()` rebuilds the tree
+     * from data (closures do not survive a restore). One contract serves every
+     * carryover path: Studio knob changes, variant toggles, HMR, and net rollback.
+     */
+    attach?(world: World): void;
+    /**
+     * Awaited before the world starts stepping — load fonts, sprite atlases, a
+     * SoundFont, anything async. The engine holds a splash on screen until it
+     * resolves, so there is no asset pop-in and no ungoverned pre-first-frame window.
+     */
+    preload?(world: World): Promise<void>;
+    /** Boot splash config, or `false` to start on the first frame with no cover. */
+    splash?: SplashConfig | false;
 }
 /** Identity + defaults. Kept as a function so games read `export default defineGame({…})`. */
 export declare function defineGame(def: GameDefinition): Required<Pick<GameDefinition, 'width' | 'height' | 'seed' | 'inputMap' | 'background'>> & GameDefinition;
-/** Build a live, deterministic World from a game definition. No browser needed. */
-export declare function createWorld(def: GameDefinition, seedOverride?: number): World;
+export interface CreateWorldOptions {
+    seed?: number;
+    /** Overrides for declared tuning knobs (undeclared keys are dropped). */
+    tuning?: TuningValues;
+}
+/**
+ * Build a live, deterministic World from a game definition. No browser needed.
+ * `opts` as a bare number is the legacy seed override.
+ */
+export declare function createWorld(def: GameDefinition, opts?: number | CreateWorldOptions): World;
 /** The input map a game uses (with defaults applied). */
 export declare function gameInputMap(def: GameDefinition): InputMap;
 export interface HeadlessResult {

package/dist/app/tuning.d.ts

@@ -0,0 +1,68 @@
+import type { GameDefinition } from './game';
+export type TuningValue = number | string;
+export type TuningValues = Record<string, TuningValue>;
+export interface TuningKnob {
+    key: string;
+    /** Human label for panels; defaults to the key. */
+    label?: string;
+    type: 'number' | 'color' | 'enum';
+    default: TuningValue;
+    /** number knobs: slider bounds + resolution. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** enum knobs: the allowed values. */
+    options?: string[];
+    /** Panel grouping (e.g. 'jump', 'combat', 'style'). */
+    group?: string;
+    /**
+     * Pure-view knob (palette, fonts): eligible for cheap re-apply without a sim
+     * rebuild. Sim-affecting knobs leave this unset.
+     */
+    cosmetic?: boolean;
+}
+export interface TuningSpec {
+    knobs: TuningKnob[];
+}
+/**
+ * A named alternative of a game for A/B playtesting: a tuning preset and/or a
+ * definition patch. Tuning-only variants can hot-swap mid-play (rebuild with
+ * snapshot carryover); `patch` variants restart fresh.
+ */
+export interface Variant {
+    label: string;
+    tuning?: TuningValues;
+    patch?(def: GameDefinition): GameDefinition;
+}
+/** Sugar for declaring knobs without repeating the key in a label. */
+export declare const knob: {
+    num(key: string, opts: {
+        default: number;
+        min?: number;
+        max?: number;
+        step?: number;
+        label?: string;
+        group?: string;
+        cosmetic?: boolean;
+    }): TuningKnob;
+    color(key: string, opts: {
+        default: string;
+        label?: string;
+        group?: string;
+        cosmetic?: boolean;
+    }): TuningKnob;
+    enumOf(key: string, opts: {
+        default: string;
+        options: string[];
+        label?: string;
+        group?: string;
+        cosmetic?: boolean;
+    }): TuningKnob;
+};
+/**
+ * Resolve a spec + overrides into concrete values: declared defaults first,
+ * overrides applied only for DECLARED keys (unknown keys are dropped — a typo'd
+ * override must not smuggle undeclared state into the hash), numbers clamped to
+ * [min, max] and coerced, enum values validated against `options`.
+ */
+export declare function resolveTuning(spec: TuningSpec | undefined, overrides?: TuningValues): TuningValues;

package/dist/art/autotile.d.ts

@@ -0,0 +1,77 @@
+import { type Transform } from '../core/math';
+import type { PolyCommand, RectCommand } from '../render/commands';
+export type BoolGrid = readonly (readonly boolean[])[];
+/** Build a grid from rows of text; a cell is solid when its char is in `solid`. */
+export declare function gridFromRows(rows: readonly string[], solid?: string): boolean[][];
+export declare const Edge: {
+    readonly N: 1;
+    readonly E: 2;
+    readonly S: 4;
+    readonly W: 8;
+};
+export type Edge = (typeof Edge)[keyof typeof Edge];
+/** 4-bit edge mask of solid neighbours around a cell. */
+export declare function mask4(grid: BoolGrid, x: number, y: number): number;
+/** 8-bit neighbour mask, bit order N,NE,E,SE,S,SW,W,NW (1,2,4,…,128). */
+export declare function mask8(grid: BoolGrid, x: number, y: number): number;
+/** Base tile shapes an edge mask resolves to (rotate `frame` by `rotation`×90° CW). */
+export declare const WangFrame: {
+    readonly Isolated: 0;
+    readonly Cap: 1;
+    readonly Straight: 2;
+    readonly Bend: 3;
+    readonly Tee: 4;
+    readonly Cross: 5;
+};
+export type WangFrame = (typeof WangFrame)[keyof typeof WangFrame];
+export interface WangTile {
+    mask: number;
+    frame: WangFrame;
+    /** Quarter turns clockwise applied to the base frame (0–3). */
+    rotation: number;
+}
+/** Resolve an edge mask (0–15) to its base frame + rotation. */
+export declare function wangTile(mask: number): WangTile;
+/** Classify every solid cell into a {frame, rotation}; empty cells are `null`. */
+export declare function autotile4(grid: BoolGrid): (WangTile | null)[][];
+/** Per-dual-cell case index (0–15) over the grid corners; size (h-1)×(w-1). */
+export declare function marchingSquaresCases(grid: BoolGrid): number[][];
+export interface ContourSegment {
+    a: {
+        x: number;
+        y: number;
+    };
+    b: {
+        x: number;
+        y: number;
+    };
+}
+export interface ContourOptions {
+    /** Cell size in design units. Default 1. */
+    cell?: number;
+    x?: number;
+    y?: number;
+}
+/** Iso-contour line segments tracing the solid/empty boundary (design units). */
+export declare function marchingSquaresContours(grid: BoolGrid, options?: ContourOptions): ContourSegment[];
+export interface AutotileDrawOptions {
+    /** Tile size in design units. Default 8. */
+    tile?: number;
+    x?: number;
+    y?: number;
+    z?: number;
+    transform?: Transform;
+    /** Fill colour of solid tiles. */
+    fill?: string;
+    /** Stroke colour drawn only on sides exposed to empty (the seam). */
+    edge?: string;
+    edgeWidth?: number;
+}
+/**
+ * Draw a boolean grid as seamless tiles: a fill per solid cell plus an edge
+ * stroke only on sides facing empty (derived from `mask4`). Pure draw data for
+ * a `cosmetic` node.
+ */
+export declare function autotileToCommands(grid: BoolGrid, options?: AutotileDrawOptions): (RectCommand | PolyCommand)[];
+/** Draw the marching-squares iso-contour as open polylines (cosmetic draw data). */
+export declare function contourToCommands(grid: BoolGrid, options?: AutotileDrawOptions): PolyCommand[];

package/dist/art/bitmapFont.d.ts

@@ -0,0 +1,113 @@
+import { type Transform } from '../core/math';
+import type { DrawCommand, RectCommand, TextAlign } from '../render/commands';
+import { Node, type NodeConfig } from '../scene/node';
+import { type BitmapFont } from './font5';
+/** One source character with an optional colour and its index in the source string. */
+export interface RichChar {
+    ch: string;
+    color?: string;
+    i: number;
+}
+/**
+ * Parse inline colour markup into per-character colours. `{name}` pushes a
+ * colour, `{/}` pops it (a stack, so nesting works); `{{` is a literal `{`.
+ * A tag resolves through `colorMap`, or is used literally if it starts with `#`
+ * or is not in the map. Text outside any tag has no colour (caller default).
+ */
+export declare function parseRich(markup: string, colorMap?: Record<string, string>): RichChar[];
+/** Width in font-pixels of a run of already-resolved chars on one line. */
+export declare function measureLine(font: BitmapFont, chars: readonly RichChar[]): number;
+/** Width in font-pixels of a plain string (no wrapping). */
+export declare function measureText(font: BitmapFont, text: string): number;
+export interface PlacedGlyph {
+    ch: string;
+    color?: string;
+    /** Source-string index (for typewriter reveal). */
+    i: number;
+    /** Top-left in font-pixel units. */
+    x: number;
+    y: number;
+    w: number;
+}
+export interface TextLayout {
+    glyphs: PlacedGlyph[];
+    /** Bounding size in font-pixel units. */
+    width: number;
+    height: number;
+    lines: number;
+}
+export interface TextLayoutOptions {
+    /** Wrap width in font-pixels. Omit for no wrapping. */
+    maxWidth?: number;
+    /** Extra blank rows between lines. Default 1. */
+    lineSpacing?: number;
+    /** Horizontal alignment within `maxWidth` (or the widest line). Default 'left'. */
+    align?: TextAlign;
+}
+/**
+ * Lay out text into placed glyphs (font-pixel coords), word-wrapping on spaces
+ * and breaking on `\n`. Accepts a plain string or a `RichChar[]` from
+ * `parseRich`. Pure and deterministic.
+ */
+export declare function layoutText(font: BitmapFont, input: string | readonly RichChar[], options?: TextLayoutOptions): TextLayout;
+/** Typewriter: how many source characters are revealed after `elapsed` seconds. */
+export declare function typewriterCount(total: number, elapsedSec: number, charsPerSec: number): number;
+export interface TextDrawOptions {
+    /** Font-pixel cell size in design units. Default 2. */
+    cell?: number;
+    /** Top-left origin in local space. Default 0,0. */
+    x?: number;
+    y?: number;
+    z?: number;
+    /** Default fill for glyphs without an inline colour. Default '#000'. */
+    color?: string;
+    transform?: Transform;
+    /** Draw only glyphs whose source index is `< reveal` (typewriter). */
+    reveal?: number;
+}
+/**
+ * Project a laid-out text to run-merged `rect` commands — one rect per
+ * horizontal span of lit pixels. Pure; the commands belong under a `cosmetic`
+ * node.
+ */
+export declare function textToCommands(font: BitmapFont, layout: TextLayout, options?: TextDrawOptions): RectCommand[];
+export interface BitmapTextConfig extends NodeConfig {
+    text: string;
+    font?: BitmapFont;
+    cell?: number;
+    color?: string;
+    /** Resolve `{tag}` markup names to colours. */
+    colorMap?: Record<string, string>;
+    /** Wrap width in font-pixels. */
+    maxWidth?: number;
+    lineSpacing?: number;
+    align?: TextAlign;
+    /** Typewriter speed in chars/sec (clock-driven). Omit to show all at once. */
+    charsPerSec?: number;
+    /** Center the block on the node origin instead of top-left. Default false. */
+    center?: boolean;
+}
+/**
+ * A scene node that renders bitmap text with optional inline colour and a
+ * clock-driven typewriter reveal. Pure view → `cosmetic = true` (never hashed).
+ */
+export declare class BitmapText extends Node {
+    readonly type = "BitmapText";
+    text: string;
+    font: BitmapFont;
+    cell: number;
+    color: string;
+    colorMap: Record<string, string>;
+    maxWidth?: number;
+    lineSpacing: number;
+    align: TextAlign;
+    charsPerSec?: number;
+    center: boolean;
+    private startTime;
+    constructor(config: BitmapTextConfig);
+    protected onReady(): void;
+    /** Restart the typewriter from the current sim time. */
+    restartReveal(): void;
+    private buildLayout;
+    protected draw(out: DrawCommand[], world: Transform): void;
+}

package/dist/art/font5.d.ts

@@ -0,0 +1,11 @@
+/** A font: named glyph bitmaps plus vertical/spacing metrics. */
+export interface BitmapFont {
+    readonly height: number;
+    /** Blank columns between glyphs. */
+    readonly tracking: number;
+    /** Width of a space character (advance only, no pixels). */
+    readonly spaceWidth: number;
+    readonly glyphs: Readonly<Record<string, readonly string[]>>;
+}
+/** The default built-in font: 5px tall, proportional, uppercase + digits + punctuation. */
+export declare const FONT_5: BitmapFont;

package/dist/art/palette.d.ts

@@ -1,3 +1,40 @@
+import type { Rng } from '../core/rng';
+/**
+ * The Kentō swatch set — the single source of truth every named palette derives
+ * from. Neutrals form one continuous ground→ink ramp; each of the eight hues has
+ * a `Deep` tone (holds AA as a large mark on light washi) and a bright tone (pops
+ * on dark sumi/kuro). Traditional Japanese color names keep it on-brand. Pick a
+ * hue by name the way the site does, or use a ready-made `Palette` below.
+ */
+export declare const KENTO: {
+    readonly gofun: "#f7f1e2";
+    readonly washi: "#efe7d3";
+    readonly kinu: "#e4d8bd";
+    readonly line: "#d8cbac";
+    readonly kinako: "#b9a882";
+    readonly stone: "#6c6252";
+    readonly sumiSoft: "#494133";
+    readonly sumi: "#23201a";
+    readonly kuro: "#181820";
+    readonly yohaku: "#12121a";
+    readonly darkLine: "#2c2c36";
+    readonly shuDeep: "#b23a24";
+    readonly shu: "#d9583c";
+    readonly kakiDeep: "#bf6a1c";
+    readonly kaki: "#e79a49";
+    readonly koDeep: "#94741d";
+    readonly ko: "#e3c054";
+    readonly matsuDeep: "#4a7a3a";
+    readonly matsu: "#8bad52";
+    readonly asagiDeep: "#2c7a90";
+    readonly asagi: "#57bad2";
+    readonly aiDeep: "#2b4257";
+    readonly ai: "#5a86ad";
+    readonly fujiDeep: "#63548c";
+    readonly fuji: "#a091cf";
+    readonly sakuDeep: "#b0506e";
+    readonly saku: "#e097ac";
+};
 export interface Palette {
     name: string;
     bg: string;
@@ -10,11 +47,53 @@ export interface Palette {
     warn: string;
     /** A small ordered ramp for categorical fills. */
     ramp: string[];
+    /** The full on-brand swatch set, for games that pick hues by name. */
+    swatches?: typeof KENTO;
 }
+/** Default light woodblock palette — washi ground, sumi ink, deep accents. */
 export declare const MEADOW: Palette;
+/** Dark counterpart — kuro ground, gofun ink, the same hues in their bright tone. */
 export declare const DUSK: Palette;
+/** Higher-key paper variant — brightest ground, same hue family. */
 export declare const PAPER: Palette;
 export declare const PALETTES: Record<string, Palette>;
 /** Blend two hex colors (t in [0,1]). Deterministic, no allocations of note. */
 export declare function mix(a: string, b: string, t: number): string;
 export declare function withAlpha(hex: string, alpha: number): string;
+export interface HSL {
+    /** Hue in degrees [0,360). */
+    h: number;
+    /** Saturation [0,1]. */
+    s: number;
+    /** Lightness [0,1]. */
+    l: number;
+}
+/** HSL → hex. h in degrees (wraps), s/l in [0,1]. */
+export declare function hsl(h: number, s: number, l: number): string;
+/** HSV/HSB → hex. h in degrees (wraps), s/v in [0,1]. */
+export declare function hsv(h: number, s: number, v: number): string;
+/** Decompose a hex color into HSL. Inverse of `hsl()`. */
+export declare function hexToHsl(hex: string): HSL;
+export interface DriftAmounts {
+    /** Max hue drift ± degrees. */
+    hue?: number;
+    /** Max saturation drift ± (absolute, [0,1]). */
+    sat?: number;
+    /** Max lightness drift ± (absolute, [0,1]). */
+    light?: number;
+}
+/**
+ * Drift a color in HSL space by random amounts from `world.rng` (space-huggers'
+ * `mutate`). Deterministic given rng state; hue wraps, s/l clamp. Cosmetic, but
+ * because it consumes rng draws, call it in a stable order.
+ */
+export declare function mutateColor(rng: Rng, hex: string, amounts?: DriftAmounts): string;
+/** Blend two hex colors in linear light (gamma-correct). t in [0,1]. */
+export declare function mixLinear(a: string, b: string, t: number): string;
+/**
+ * Sample a multi-stop gradient at t in [0,1], blending in linear light. Stops
+ * are evenly spaced hex colors (≥ 1). Great for procedural sky/heat/health ramps.
+ */
+export declare function sampleGradient(stops: readonly string[], t: number): string;
+/** Materialize an n-color ramp from gradient stops (linear-light interpolation). */
+export declare function gradient(stops: readonly string[], n: number): string[];

package/dist/art/texture.d.ts

@@ -0,0 +1,78 @@
+import { type Transform } from '../core/math';
+import type { DrawCommand, RectCommand } from '../render/commands';
+import { Node, type NodeConfig } from '../scene/node';
+/** A palette entry; `null` (or a missing index) renders transparent. */
+export type Swatch = string | null;
+/** A small indexed bitmap: `data[y * width + x]` is a palette index. */
+export declare class PixelBuffer {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array;
+    constructor(width: number, height: number, data?: Uint8Array);
+    get(x: number, y: number): number;
+    set(x: number, y: number, index: number): void;
+    /** Build from a rows-of-strings grid, mapping each character to an index. */
+    static fromRows(rows: readonly string[], charToIndex: Record<string, number>): PixelBuffer;
+    /** A copy with every index passed through `lut` (2-bit → palette remap). */
+    remap(lut: readonly number[]): PixelBuffer;
+}
+/**
+ * Decode a 1-bit-per-pixel bitmap packed MSB-first into a BigInt/hex string
+ * (the super-castle-style trick). Pixel `i` reads bit `(w*h-1-i)`, so a hex
+ * literal reads left-to-right, top-to-bottom. Produces indices 0 or 1.
+ */
+export declare function decodeBits(source: bigint | string, width: number, height: number): PixelBuffer;
+/**
+ * Decode a 2-bit-per-pixel bitmap (indices 0–3) packed MSB-first, matching the
+ * dying-dreams "2-bit source → palette LUT" pipeline. Pass the result through
+ * `PixelBuffer.remap(lut)` to lift the 2-bit indices into a wider palette.
+ */
+export declare function decode2bit(source: bigint | string, width: number, height: number): PixelBuffer;
+/**
+ * Decode a run-length-encoded index stream (witchcat-style). `runs` is a flat
+ * list of `[count, index, count, index, …]` filled row-major. A short encoding
+ * for sprites dominated by flat colour.
+ */
+export declare function decodeRLE(runs: readonly number[], width: number, height: number): PixelBuffer;
+/** Encode a PixelBuffer back to RLE run pairs — the inverse of `decodeRLE`. */
+export declare function encodeRLE(buf: PixelBuffer): number[];
+export interface PixelDrawOptions {
+    /** Size of one pixel cell in design units. Default 1. */
+    cell?: number;
+    /** Top-left origin in local space. Default 0,0. */
+    x?: number;
+    y?: number;
+    /** Painter z. Default 0. */
+    z?: number;
+    /** World transform for the emitted commands. Default identity. */
+    transform?: Transform;
+}
+/**
+ * Project a PixelBuffer to `rect` draw commands, run-merging horizontal spans
+ * of the same colour so a 16×16 sprite is a handful of rects, not 256. Palette
+ * entries that are `null`/undefined render transparent (skipped). Pure — the
+ * commands carry no state and belong under a `cosmetic` node.
+ */
+export declare function pixelsToCommands(buf: PixelBuffer, palette: readonly Swatch[], options?: PixelDrawOptions): RectCommand[];
+export interface TextureSpriteConfig extends NodeConfig {
+    buffer: PixelBuffer;
+    palette: readonly Swatch[];
+    /** Pixel cell size in design units. Default 1. */
+    cell?: number;
+    /** Draw centered on the node origin instead of top-left. Default true. */
+    center?: boolean;
+}
+/**
+ * A scene node that renders a decoded PixelBuffer. It is pure view over
+ * constant art data, so it is `cosmetic = true` by default — excluded from
+ * `serialize()`/`hash()`/snapshot. Position/scale it like any other node.
+ */
+export declare class TextureSprite extends Node {
+    readonly type = "TextureSprite";
+    buffer: PixelBuffer;
+    palette: readonly Swatch[];
+    cell: number;
+    center: boolean;
+    constructor(config: TextureSpriteConfig);
+    protected draw(out: DrawCommand[], world: Transform): void;
+}

package/dist/audio/adaptive.d.ts

@@ -0,0 +1,58 @@
+/** A breakpoint on an RTPC curve: at input `x`, the target is `y`. */
+export interface Breakpoint {
+    x: number;
+    y: number;
+}
+/**
+ * Evaluate a piecewise-linear RTPC curve at `x`. Breakpoints are sorted by x;
+ * values outside the range clamp to the nearest endpoint. This one primitive
+ * drives volume, filter cutoff, layer gain, and distance in a uniform, testable
+ * way — exactly what a Wwise RTPC / FMOD parameter automation does.
+ */
+export declare function evalCurve(curve: Breakpoint[], x: number): number;
+export type DistanceModel = 'linear' | 'inverse' | 'exponential';
+/**
+ * Distance-attenuation gain, matching the Web Audio PannerNode formulas exactly
+ * so an offline render agrees with live playback. `refDistance` is full volume,
+ * `maxDistance` is the floor, `rolloff` shapes the falloff.
+ */
+export declare function distanceGain(model: DistanceModel, distance: number, refDistance?: number, maxDistance?: number, rolloff?: number): number;
+/**
+ * Equal-power stereo pan from a horizontal offset. dx is the source's screen-x
+ * relative to the listener; `spread` is the half-width at which pan saturates.
+ */
+export declare function panFromOffset(dx: number, spread?: number): number;
+/**
+ * A positional cue's mix: distance-attenuated gain × pan. Combines the two
+ * above into what a 2-D game actually needs. `hearing` is the cutoff beyond
+ * which the source is inaudible.
+ */
+export interface SpatialMix {
+    gain: number;
+    pan: number;
+    audible: boolean;
+}
+export declare function spatialMix(dx: number, dy: number, hearing?: number, rolloff?: number): SpatialMix;
+/** A named layer of vertical (stacked) adaptive music. */
+export interface MusicLayer {
+    name: string;
+    /** The layer fades in from `fadeIn` and reaches full gain by `full` intensity. */
+    fadeIn: number;
+    full: number;
+    /** Optional cap on this layer's gain (default 1). */
+    maxGain?: number;
+}
+/**
+ * Vertical layering: given an intensity value (0..1, e.g. combat proximity),
+ * return each layer's gain. Layers fade in at their thresholds so texture
+ * thickens with intensity without ever interrupting the flow — the single
+ * biggest adaptive-music payoff per line, and trivially deterministic.
+ */
+export declare function layerGains(layers: MusicLayer[], intensity: number): Record<string, number>;
+/**
+ * A ducking envelope target: while a higher-priority bus (dialogue, a stinger)
+ * is active, the ducked bus drops by `amount` dB. Returns a linear gain the
+ * driver ramps toward with setTargetAtTime — deterministic because it's keyed
+ * off game state, not an audio sidechain.
+ */
+export declare function duckGain(active: boolean, amountDb?: number): number;

package/dist/audio/album.d.ts

@@ -0,0 +1,16 @@
+import { type Song } from './music';
+export interface AlbumTrack {
+    id: string;
+    title: string;
+    intent: string;
+    make: () => Song;
+}
+/** The album. */
+export declare const ALBUM: {
+    title: string;
+    subtitle: string;
+    concept: string;
+    tracks: AlbumTrack[];
+};
+/** Look up an album track by id. */
+export declare function albumTrack(id: string): AlbumTrack | undefined;

package/dist/audio/analysis.d.ts

@@ -0,0 +1,59 @@
+import { type Samples } from './pcm';
+/** Amplitude ratio → decibels full-scale. Silence maps to -Infinity. */
+export declare function dbfs(amp: number): number;
+/** Root-mean-square level of a signal. */
+export declare function rms(sig: Samples): number;
+/** Peak absolute sample. */
+export declare function peakAmp(sig: Samples): number;
+/** Zero crossings per second — a rough "noisiness / brightness" proxy. */
+export declare function zcr(sig: Samples, sampleRate?: number): number;
+/**
+ * In-place iterative radix-2 Cooley–Tukey FFT. `re`/`im` length must be a power
+ * of two. Deterministic: twiddle factors come from dcos/dsin.
+ */
+export declare function fft(re: Float32Array, im: Float32Array): void;
+/** Hann-windowed magnitude spectrum of a frame (length rounded down to pow2). */
+export declare function magnitudeSpectrum(frame: Samples): Float32Array;
+/**
+ * Spectral centroid (Hz) — the "center of mass" of the spectrum, a robust
+ * brightness measure. Averaged over Hann frames across the whole signal.
+ */
+export declare function spectralCentroid(sig: Samples, sampleRate?: number): number;
+/**
+ * Spectral flux onset envelope: per-frame sum of positive magnitude increases.
+ * Peaks mark note onsets — the basis for tempo/onset-density features.
+ */
+export declare function fluxEnvelope(sig: Samples, frameSize?: number, hop?: number): Float32Array;
+/** Onsets per second — busy/percussive vs sparse/sustained. */
+export declare function onsetDensity(sig: Samples, sampleRate?: number): number;
+/**
+ * Estimate tempo (BPM) by autocorrelating the flux onset envelope and picking
+ * the strongest lag in the 60–200 BPM band. Returns 0 if indeterminate.
+ */
+export declare function estimateTempo(sig: Samples, sampleRate?: number): number;
+/** Crest factor in dB (peak / rms). Music usually lives ~8–20 dB; a tiny value
+ * means it's squashed/distorted, a huge value means it's mostly silence. */
+export declare function crestFactorDb(sig: Samples): number;
+/** Fractional energy in coarse frequency bands — the spectral balance of a mix.
+ * Returns fractions (summing to ~1) for sub / bass / lowMid / mid / high / air. */
+export interface BandBalance {
+    sub: number;
+    bass: number;
+    lowMid: number;
+    mid: number;
+    high: number;
+    air: number;
+}
+export declare function bandBalance(sig: Samples, sampleRate?: number): BandBalance;
+/** A compact numeric fingerprint of a signal — the audio-filmstrip's assertions. */
+export interface AudioFeatures {
+    durationSec: number;
+    rms: number;
+    peakDb: number;
+    centroidHz: number;
+    zcr: number;
+    onsetDensity: number;
+    tempoBpm: number;
+}
+/** Extract the full feature vector used by verification. */
+export declare function features(sig: Samples, sampleRate?: number): AudioFeatures;