hayao 0.2.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/palette.d.ts

@@ -1,4 +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;
@@ -11,9 +47,14 @@ 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. */

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;

package/dist/audio/audio.d.ts

@@ -1,3 +1,5 @@
+import { type SoundSpec } from './synth';
+import { type Song } from './music';
 export interface Volumes {
     master: number;
     music: number;
@@ -37,6 +39,25 @@ export declare class AudioBus {
     spatial(freq: number, dx: number, dist: number, hearing?: number, duration?: number, type?: OscillatorType): void;
     /** Play a sequence of tones as an arpeggio/chord. */
     play(tones: Tone[]): void;
+    /**
+     * Play a data-defined SoundSpec through the SFX bus. The spec is rendered to
+     * samples (deterministically, at the context rate) and played as an
+     * AudioBuffer — the same SoundSpec that a verify suite proves headlessly.
+     * No-op without an AudioContext.
+     */
+    playSpec(spec: SoundSpec, opts?: {
+        pan?: number;
+        gain?: number;
+        when?: number;
+    }): void;
+    /**
+     * Render a Song offline and play it on the music bus. Returns a stop handle.
+     * `loop` repeats the musical body (excluding the ring-out tail). No-op without
+     * an AudioContext.
+     */
+    playSong(song: Song, opts?: {
+        loop?: boolean;
+    }): () => void;
     /** Convenience SFX. */
     blip(freq?: number): void;
     chime(): void;

package/dist/audio/chord.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parse a chord symbol to MIDI notes at the given octave (default 4). Supports
+ * a slash bass ("C/E", "Dm7/G"). Throws on an unknown quality so authoring
+ * mistakes surface instead of sounding wrong.
+ */
+export declare function chordNotes(symbol: string, octave?: number): number[];
+/**
+ * Rootless voicing: drop the root (the bass covers it) and keep the colour
+ * tones (3rd, 7th, extensions) in a tight register — the authentic sound of
+ * jazz-piano/Rhodes comping. Optionally recenter near `targetMidi`.
+ */
+export declare function rootless(chord: number[], targetMidi?: number): number[];
+/**
+ * Resolve a whole progression of chord symbols to note sets. Convenience for
+ * writing changes as a string array: chordChanges(['Dm7','G7','Cmaj7']).
+ */
+export declare function chordChanges(symbols: string[], octave?: number): number[][];

package/dist/audio/genres.d.ts

@@ -0,0 +1,11 @@
+import { type Song } from './music';
+export interface GenreTrack {
+    id: string;
+    name: string;
+    description: string;
+    make: () => Song;
+}
+/** The genre songbook — the demo set. */
+export declare const GENRES: GenreTrack[];
+/** Look up a genre by id. */
+export declare function genre(id: string): GenreTrack | undefined;

package/dist/audio/lint.d.ts

@@ -0,0 +1,29 @@
+import { type ScaleName } from './theory';
+import type { Song, Pitch } from './music';
+export interface MusicLintResult {
+    ok: boolean;
+    /** Hard failures: malformed data that would render wrong or crash. */
+    errors: string[];
+    /** Musical smells: renders fine, but likely not what was intended. */
+    warnings: string[];
+}
+export interface LintOptions {
+    /** If given, flag notes outside this key/mode as out-of-key warnings. */
+    key?: {
+        tonic: Pitch;
+        mode: ScaleName;
+    };
+    /** Max fraction of out-of-key notes tolerated before it's an error (default 1 = never). */
+    maxOutOfKey?: number;
+}
+/**
+ * Lint a Song. Errors block (bad bpm, empty tracks, unparseable pitches, bad
+ * pattern indices, non-positive durations, out-of-MIDI-range pitches). Warnings
+ * flag musical smells (out-of-key notes, no structural repetition).
+ */
+export declare function lintSong(song: Song, opts?: LintOptions): MusicLintResult;
+/**
+ * Check that a roman-numeral progression resolves to tonic — a real cadence,
+ * not a phrase left hanging. Accepts an ending on I/i, or a V(7)→I/i cadence.
+ */
+export declare function cadenceResolves(romans: string[]): boolean;

package/dist/audio/match.d.ts

@@ -0,0 +1,38 @@
+import type { AudioFeatures } from './analysis';
+/** Per-feature normalization scales — the "how much is a lot" for each axis. */
+interface FeatureWeights {
+    tempoBpm: number;
+    centroidHz: number;
+    rms: number;
+    zcr: number;
+    onsetDensity: number;
+    peakDb: number;
+}
+export interface FeatureDelta {
+    feature: keyof FeatureWeights;
+    reference: number;
+    candidate: number;
+    /** Normalized signed error (candidate − reference) / scale. */
+    normalized: number;
+    /** Human/LLM-actionable direction, e.g. "too dark", "too fast". */
+    note: string;
+}
+export interface MatchResult {
+    /** Overall distance (RMS of normalized per-feature errors). 0 = identical. */
+    distance: number;
+    /** Per-feature breakdown, largest error first. */
+    deltas: FeatureDelta[];
+    /** The single most-off feature's note, or 'close match'. */
+    headline: string;
+}
+/**
+ * Compare a candidate feature vector to a reference. Returns an overall
+ * distance plus a per-feature, direction-aware breakdown sorted by severity.
+ */
+export declare function featureDistance(reference: AudioFeatures, candidate: AudioFeatures, weights?: Partial<FeatureWeights>): MatchResult;
+/**
+ * A compact, printable report of the mismatch — the "shortcomings" surface an
+ * AI loop reads to decide its next move.
+ */
+export declare function matchReport(reference: AudioFeatures, candidate: AudioFeatures): string;
+export {};

package/dist/audio/music.d.ts

@@ -0,0 +1,88 @@
+import { type SoundSpec } from './synth';
+import { type ReverbOptions } from './reverb';
+import { type StereoBuffer } from './pcm';
+/** A voice: everything a SoundSpec has except pitch, which each note supplies. */
+export type Instrument = Omit<SoundSpec, 'freq'>;
+export type Pitch = string | number;
+/** One note (or chord, or rest) in a pattern. */
+export interface Note {
+    /** A pitch, a chord (array of pitches), or null for a rest. */
+    pitch: Pitch | Pitch[] | null;
+    /** Duration in beats. */
+    beats: number;
+    /** Velocity 0..1 (default 1). */
+    vel?: number;
+}
+/** A monophonic-per-note lane: an instrument playing sequenced patterns. */
+export interface Track {
+    name?: string;
+    instrument: Instrument;
+    /** Reusable note patterns, referenced by index in `sequence`. */
+    patterns: Note[][];
+    /** Order in which patterns play. */
+    sequence: number[];
+    /** Track mix level (default 0.7). */
+    gain?: number;
+    /** Stereo position -1..1 (default 0). */
+    pan?: number;
+}
+export interface Song {
+    bpm: number;
+    tracks: Track[];
+    /** Concert-A reference (default 440). */
+    a4?: number;
+    /** Tail seconds appended so release/echo tails ring out (default 2). */
+    tailSec?: number;
+    /** Room reverb applied to the whole mix (space + glue). */
+    reverb?: ReverbOptions;
+    /** Swing 0..1 — delays off-beat 8th notes for a shuffled feel (jazz/lofi). */
+    swing?: number;
+    /** Humanize 0..1 — small seeded timing/velocity jitter so it doesn't feel robotic. */
+    humanize?: number;
+    /**
+     * Velocity→brightness 0..1 — how much a soft note darkens (like a real
+     * instrument: harder = brighter). Scales each voice's lowpass by velocity.
+     * Default 0.5. This is what turns a velocity map into actual phrasing.
+     */
+    velBrightness?: number;
+    /**
+     * Sidechain "pump": a beat-synced ducking of the whole mix — the breathing
+     * signature of electronic music. depth 0..1, beatsPerCycle sets the pulse
+     * (default 1 = every beat).
+     */
+    sidechain?: {
+        depth?: number;
+        beatsPerCycle?: number;
+    };
+    /**
+     * Master bus (a light mastering pass): `lowCut` tucks boomy sub/bass, and
+     * `presence`/`air` lift high-mid clarity and top-end sparkle. `compress`
+     * (0..1) applies a gentle glue compressor with makeup gain — evens dynamics
+     * and lifts perceived loudness (esp. sparse ballads). Each field 0..1.
+     */
+    master?: {
+        lowCut?: number;
+        presence?: number;
+        air?: number;
+        compress?: number;
+    };
+}
+/** Total musical length of a song in beats (the longest track). */
+export declare function songBeats(song: Song): number;
+/** Song duration in seconds, excluding the ring-out tail. */
+export declare function songDuration(song: Song): number;
+/**
+ * Render a Song to a stereo buffer. Deterministic: a per-track seeded Rng feeds
+ * any noise voices, so the same Song always produces the same mix. Notes are
+ * synthesized via renderSound with the track's instrument, the note's pitch and
+ * velocity, and a sustain sized to the note's beat length.
+ */
+export declare function renderSong(song: Song, opts?: {
+    sampleRate?: number;
+    normalizePeak?: number;
+}): StereoBuffer;
+/**
+ * A small library of ready-to-use instrument voices. These are the "adopt a
+ * timbre" defaults so a composer starts from something musical, then tweaks.
+ */
+export declare const INSTRUMENTS: Record<string, Instrument>;

package/dist/audio/pcm.d.ts

@@ -0,0 +1,54 @@
+/** Canonical render rate. 44.1 kHz — CD quality, ubiquitous. */
+export declare const SAMPLE_RATE = 44100;
+/** A mono signal: Float32 samples, nominally in [-1, 1], at some sample rate. */
+export type Samples = Float32Array;
+/** A stereo buffer: two channels sharing one sample rate. The mix target. */
+export interface StereoBuffer {
+    sampleRate: number;
+    left: Float32Array;
+    right: Float32Array;
+}
+/** Allocate a silent stereo buffer of the given duration. */
+export declare function createStereo(durationSec: number, sampleRate?: number): StereoBuffer;
+/** Frame count (samples per channel). */
+export declare function stereoFrames(buf: StereoBuffer): number;
+/** Duration in seconds. */
+export declare function stereoDuration(buf: StereoBuffer): number;
+/**
+ * Equal-power pan law. pan ∈ [-1, 1]: -1 = hard left, 0 = center, +1 = hard
+ * right. Uses a quarter-sine curve so total power is constant across the sweep
+ * (a linear pan would dip −3 dB in the middle).
+ */
+export declare function panGains(pan: number): {
+    l: number;
+    r: number;
+};
+/**
+ * Mix a mono signal into a stereo bus at a start sample, with gain and pan.
+ * Additive — many voices accumulate into one bus. Samples outside the bus are
+ * clipped away (no reallocation), so callers size the bus for the whole score.
+ */
+export declare function mixMono(bus: StereoBuffer, sig: Samples, startSample: number, gain?: number, pan?: number): void;
+/** Largest absolute sample across both channels — the true peak. */
+export declare function peak(buf: StereoBuffer): number;
+/**
+ * Transparent soft-clip. Unity slope at the origin (quiet signals pass through
+ * untouched) and asymptotes to ±1, so it tames peaks without hard-clipping and
+ * without boosting quiet material. Only sqrt — stays deterministic.
+ */
+export declare function softClip(x: number): number;
+/** Soft-clip a whole buffer in place. Tames additive overshoot on a busy mix. */
+export declare function softClipInPlace(buf: StereoBuffer): void;
+/** Scale a buffer in place so its peak sits at `target` (default −1 dBFS-ish). */
+export declare function normalize(buf: StereoBuffer, target?: number): void;
+/**
+ * Encode a stereo buffer as a 16-bit PCM WAV (RIFF) byte array — a real,
+ * playable artifact a human (or a golden-file test) can keep. Zero-dependency.
+ */
+export declare function encodeWav(buf: StereoBuffer): Uint8Array;
+/**
+ * Deterministic 32-bit fingerprint of a signal — samples quantized to 16-bit
+ * then FNV-1a hashed. Lets a test pin "this synth produces exactly this sound"
+ * without storing the whole buffer, and detect any DSP regression.
+ */
+export declare function signalHash(sig: Samples): number;

package/dist/audio/quality.d.ts

@@ -0,0 +1,28 @@
+import type { StereoBuffer } from './pcm';
+/** Stereo width via mid/side energy ratio. 0 = mono, ~0.3+ = a wide mix. */
+export declare function stereoWidth(buf: StereoBuffer): number;
+type Range = [number, number];
+export interface GenreProfile {
+    tempo: Range;
+    centroid: Range;
+    onsets: Range;
+    rms: Range;
+    crestDb: Range;
+    width: Range;
+    /** Max acceptable low-mid (250–800 Hz) fraction — warm genres tolerate more. */
+    maxMud?: number;
+}
+/** Target windows per genre — set to real genre norms for a balanced mix. */
+export declare const GENRE_PROFILES: Record<string, GenreProfile>;
+export interface QualityScore {
+    score: number;
+    dims: Record<string, number>;
+    notes: string[];
+}
+/**
+ * Score a rendered track against a genre profile. Weighted mean of dimensions,
+ * ×100. `notes` lists any dimension below a comfortable threshold with the
+ * measured value and direction, so a composer knows exactly what to fix.
+ */
+export declare function scoreTrack(buf: StereoBuffer, profile: GenreProfile): QualityScore;
+export {};

package/dist/audio/reverb.d.ts

@@ -0,0 +1,15 @@
+import type { StereoBuffer } from './pcm';
+export interface ReverbOptions {
+    /** Wet/dry mix 0..1 (default 0.25). */
+    wet?: number;
+    /** Tail length / feedback 0..1 — bigger = longer, more cathedral (default 0.7). */
+    roomSize?: number;
+    /** High-frequency damping 0..1 — bigger = darker tail (default 0.5). */
+    damp?: number;
+}
+/**
+ * Apply reverb to a stereo buffer in place. A mono send (the L/R sum) feeds two
+ * slightly offset comb/allpass banks to produce a stereo tail, mixed back with
+ * the dry signal. Deterministic — pure delay-line arithmetic.
+ */
+export declare function applyReverb(buf: StereoBuffer, opts?: ReverbOptions): void;