hayao 0.1.0 → 0.3.0

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;
@@ -11,6 +13,8 @@ export interface Tone {
     type?: OscillatorType;
     gain?: number;
     delay?: number;
+    /** Stereo position -1 (left) … 1 (right) — the spatial-audio hook. */
+    pan?: number;
 }
 export declare class AudioBus {
     private ctx;
@@ -28,8 +32,32 @@ export declare class AudioBus {
     private applyVolumes;
     /** Play a single tone (no-op if audio unstarted). */
     tone(spec: Tone): void;
+    /**
+     * A positional cue: gain falls with distance, pan follows the horizontal
+     * offset. dx/dist in design-space px; hearing range sets the falloff.
+     */
+    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;

package/dist/audio/synth.d.ts

@@ -0,0 +1,56 @@
+import { Rng } from '../core/rng';
+import { type Samples } from './pcm';
+export type Wave = 'sine' | 'triangle' | 'saw' | 'square' | 'noise';
+/**
+ * A one-shot sound, fully described by data. Every field is optional; omitted
+ * fields take musical defaults. Times are seconds, pitch offsets are semitones,
+ * depths are 0..1 unless noted.
+ */
+export interface SoundSpec {
+    /** Base pitch in Hz. */
+    freq?: number;
+    /** Oscillator shape. */
+    wave?: Wave;
+    /** Square/pulse duty cycle 0..1 (square only). */
+    duty?: number;
+    attack?: number;
+    decay?: number;
+    sustain?: number;
+    release?: number;
+    sustainLevel?: number;
+    /** Percussive volume spike at onset (jsfxr "punch"), 0..1. */
+    punch?: number;
+    /** Overall output gain. */
+    volume?: number;
+    slide?: number;
+    slideAccel?: number;
+    pitchJump?: number;
+    pitchJumpTime?: number;
+    vibrato?: number;
+    vibratoFreq?: number;
+    /** Second detuned oscillator, cents (0 = off). Adds unison warmth/chorus. */
+    detune?: number;
+    /** Sub-oscillator: a sine one octave down, mixed at this level 0..1. Adds weight. */
+    sub?: number;
+    noise?: number;
+    shapeCurve?: number;
+    fm?: number;
+    fmFreq?: number;
+    tremolo?: number;
+    tremoloFreq?: number;
+    bitCrush?: number;
+    lowpass?: number;
+    highpass?: number;
+    delay?: number;
+    delayFeedback?: number;
+}
+/**
+ * Render a SoundSpec to a mono signal. Pure and deterministic: pass a seeded
+ * `rng` for reproducible noise (defaults to a fixed seed so bare specs are
+ * still bit-stable). The returned buffer is normalized only by `volume`, so a
+ * caller can mix many at chosen gains.
+ */
+export declare function renderSound(spec: SoundSpec, opts?: {
+    rng?: Rng;
+    sampleRate?: number;
+}): Samples;

package/dist/audio/theory.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Parse scientific pitch notation ("C4", "F#3", "Bb5", "A4") to a MIDI number.
+ * Middle C (C4) = 60, A4 = 69. Throws on malformed input so bad authoring is
+ * caught, not silently mis-sounded.
+ */
+export declare function noteToMidi(name: string): number;
+/** MIDI number → name in sharps, e.g. 60 → "C4". */
+export declare function midiToName(midi: number): string;
+/** MIDI number → frequency in Hz (A4 = a4, default 440). Deterministic. */
+export declare function midiToFreq(midi: number, a4?: number): number;
+/** Convenience: pitch name or MIDI number → Hz. */
+export declare function pitchToFreq(pitch: string | number, a4?: number): number;
+/** Scale (mode) interval tables in semitones from the tonic. */
+export declare const SCALES: {
+    readonly major: readonly [0, 2, 4, 5, 7, 9, 11];
+    readonly minor: readonly [0, 2, 3, 5, 7, 8, 10];
+    readonly harmonicMinor: readonly [0, 2, 3, 5, 7, 8, 11];
+    readonly melodicMinor: readonly [0, 2, 3, 5, 7, 9, 11];
+    readonly dorian: readonly [0, 2, 3, 5, 7, 9, 10];
+    readonly phrygian: readonly [0, 1, 3, 5, 7, 8, 10];
+    readonly lydian: readonly [0, 2, 4, 6, 7, 9, 11];
+    readonly mixolydian: readonly [0, 2, 4, 5, 7, 9, 10];
+    readonly locrian: readonly [0, 1, 3, 5, 6, 8, 10];
+    readonly majorPentatonic: readonly [0, 2, 4, 7, 9];
+    readonly minorPentatonic: readonly [0, 3, 5, 7, 10];
+    readonly blues: readonly [0, 3, 5, 6, 7, 10];
+    readonly chromatic: readonly [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+};
+export type ScaleName = keyof typeof SCALES;
+/**
+ * Scale degrees as MIDI numbers spanning `octaves` starting at `tonic`.
+ * e.g. scaleMidis(noteToMidi('C4'), 'major', 2) → C4 D4 E4 … up two octaves.
+ */
+export declare function scaleMidis(tonic: number, mode?: ScaleName, octaves?: number): number[];
+/** Pitch classes (0–11) of a scale — for in-key checks. */
+export declare function scalePitchClasses(tonic: number, mode?: ScaleName): Set<number>;
+/**
+ * Build a diatonic chord by stacking thirds on a scale degree. `degree` is
+ * 0-based (0 = I/i). Returns MIDI numbers. `size` 3 = triad, 4 = seventh.
+ * Because it stacks the actual scale, chord quality (maj/min/dim) falls out of
+ * the mode automatically — no quality table to get wrong.
+ */
+export declare function diatonicChord(tonic: number, mode: ScaleName, degree: number, size?: number): number[];
+/**
+ * Realize a roman-numeral progression in a key to concrete chords (arrays of
+ * MIDI notes). Case-insensitive on the numeral; a trailing "7" adds a seventh.
+ * e.g. progression(noteToMidi('C4'),'major',['I','V','vi','IV']).
+ */
+export declare function progression(tonic: number, mode: ScaleName, romans: string[]): number[][];
+/** Transpose a set of MIDI notes by semitones. */
+export declare function transpose(notes: number[], semitones: number): number[];
+/**
+ * Open a close-position chord: drop the root an octave so the voicing spreads
+ * out and the root/7th no longer clash in the same octave. Turns muddy stacked
+ * sevenths into something that breathes.
+ */
+export declare function openVoicing(chord: number[]): number[];
+/**
+ * Smooth a progression's voice-leading. Each chord after the first is octave-
+ * shifted so its notes sit near the previous chord's register — voices move by
+ * small steps instead of leaping in parallel root position. The single biggest
+ * cure for the "MIDI demo" sound. Returns new chords (MIDI, sorted low→high).
+ */
+export declare function voiceLead(chords: number[][]): number[][];

package/dist/content/campaign.d.ts

@@ -0,0 +1,69 @@
+import type { Rng } from '../core/rng';
+import type { Puzzle } from '../verify/solver';
+import type { SolveOptions } from '../verify/solver';
+import { type DifficultyBand, type GeneratedLevel } from './generate';
+/** One named stretch of the campaign, generated inside its own difficulty band. */
+export interface ActSpec<State = unknown, Move = unknown> extends DifficultyBand {
+    /** Display name ("The Shallows", "Deep Roots", …). */
+    name: string;
+    /** How many verified levels this act contributes. */
+    count: number;
+    /**
+     * Optional per-act candidate factory — overrides the campaign default. This is
+     * how an act introduces a NEW mechanic or board size (a bigger grid, a new tile
+     * kind) while the earlier acts keep the simpler one: mechanic-gating as data.
+     */
+    factory?: (rng: Rng) => Puzzle<State, Move>;
+    /** Optional per-act solver budget override. */
+    solve?: SolveOptions;
+    /** Optional per-act attempt cap override. */
+    maxAttempts?: number;
+}
+export interface CampaignSpec<State, Move> {
+    /** Default candidate factory — used by any act that doesn't bring its own. */
+    factory?: (rng: Rng) => Puzzle<State, Move>;
+    /** Ordered acts; earlier acts should sit in lower difficulty bands. */
+    acts: ActSpec<State, Move>[];
+    /** Base seed for the whole campaign (default 1). */
+    seed?: number;
+    /** Default solver budget for acts that don't override it. */
+    solve?: SolveOptions;
+    /** Rough authoring estimate: minutes a median player spends per level (default 1.5). */
+    minutesPerLevel?: number;
+}
+/** A generated level tagged with the act it belongs to and its campaign index. */
+export interface CampaignLevel<State, Move> extends GeneratedLevel<State, Move> {
+    /** Zero-based act index. */
+    act: number;
+    /** The act's display name. */
+    actName: string;
+    /** Position within its act. */
+    actIndex: number;
+}
+export interface ActBounds {
+    name: string;
+    /** First campaign index (inclusive). */
+    from: number;
+    /** Last campaign index (inclusive). */
+    to: number;
+}
+export interface Campaign<State, Move> {
+    levels: CampaignLevel<State, Move>[];
+    acts: ActBounds[];
+    /** Per-level difficulty (solver depth), campaign order — feed to `rampIssues`. */
+    difficulty: number[];
+    /** Reproduce the campaign: every level's sub-seed, in order. */
+    seeds: number[];
+    /** Honest length estimate in minutes (levels × minutesPerLevel). */
+    estMinutes: number;
+}
+/**
+ * Compose a full campaign by generating each act inside its band and concatenating
+ * them in order. Deterministic: same spec → same campaign everywhere. Acts are
+ * seeded independently (base seed mixed with the act index) so re-tuning one act's
+ * band or count never reshuffles the others.
+ *
+ * Throws (via `generateLevels`) if any act's band is too tight to fill — a loud,
+ * early failure beats silently shipping a short act.
+ */
+export declare function composeCampaign<State, Move>(spec: CampaignSpec<State, Move>): Campaign<State, Move>;

package/dist/content/dsl.d.ts

@@ -0,0 +1,61 @@
+import type { Rng } from '../core/rng';
+import { type WeightedEntry } from '../logic/random';
+/**
+ * One declarative wave. Fires `count` of `spawn` at time `time` (sim seconds).
+ * When `every` is set it repeats on that interval until `end` (exclusive),
+ * modelling a continuous spawn stream. `spawn` may be a single id or a weighted
+ * table, in which case each firing rolls the table via `world.rng`.
+ */
+export interface WaveDef {
+    /** First fire time, in fixed sim seconds (compare against `world.time`). */
+    time: number;
+    /** What to spawn: a fixed id, or a weighted set rolled per firing. */
+    spawn: string | WeightedEntry<string>[];
+    /** How many per firing (default 1). */
+    count?: number;
+    /** Repeat interval in seconds; omit for a one-shot wave. */
+    every?: number;
+    /** Repeats stop once the next fire time reaches this (seconds). */
+    end?: number;
+}
+/** Mutable director cursor — plain JSON, keep it in `world.state`. */
+export interface DirectorState {
+    /** Next fire time per wave index; Infinity once a wave is exhausted. */
+    next: number[];
+}
+/** One resolved spawn instruction emitted by the director. */
+export interface SpawnEvent {
+    /** Concrete spawn id (already rolled if the wave used a weighted set). */
+    spawn: string;
+    count: number;
+    /** Source wave index, for callers that want to key behavior off the wave. */
+    wave: number;
+}
+/** Initialize a director cursor for a schedule. */
+export declare function initDirector(waves: readonly WaveDef[]): DirectorState;
+/**
+ * Advance the director to `time` (sim seconds) and return every spawn that is
+ * now due, in wave order. Mutates `state.next` in place. Deterministic: it emits
+ * the same events for the same (schedule, time, rng-state) on every machine.
+ * A repeating wave can fire multiple times in one poll if the frame straddled
+ * several intervals (e.g. after a restore), so catch-up never drops spawns.
+ */
+export declare function pollDirector(waves: readonly WaveDef[], state: DirectorState, time: number, rng?: Rng): SpawnEvent[];
+/**
+ * A declarative upgrade or evolution node. `requires` lists ids that must all be
+ * owned before this one can be offered — the cat-survivors evolution gate and a
+ * deckbuilder's upgrade prerequisites are the same shape.
+ */
+export interface UpgradeDef {
+    id: string;
+    /** Ids that must all be owned before this becomes available. */
+    requires?: string[];
+    /** Optional: only offer while UNDER this many owned copies (repeatable upgrades). */
+    maxStacks?: number;
+}
+/**
+ * Which upgrades are offerable given what's owned: prerequisites all met, and
+ * not already at `maxStacks` (default 1 — offered until owned once). `owned` may
+ * repeat ids to represent stacks. Ordered by definition order for hash stability.
+ */
+export declare function availableUpgrades(defs: readonly UpgradeDef[], owned: readonly string[]): UpgradeDef[];

package/dist/content/generate.d.ts

@@ -0,0 +1,78 @@
+import { Rng } from '../core/rng';
+import { type Puzzle, type SolveOptions } from '../verify/solver';
+/** A difficulty window expressed on the solver's own proof metrics. */
+export interface DifficultyBand {
+    /** Minimum solution length (shortest winning move count). Below this = trivial. */
+    minDepth?: number;
+    /** Maximum solution length. Above this = a slog / likely unfair. */
+    maxDepth?: number;
+    /** Minimum nodes the solver expanded (a branchiness / "how much thinking" proxy). */
+    minNodes?: number;
+    /** Maximum nodes expanded — caps combinatorial monsters. */
+    maxNodes?: number;
+}
+export interface GenerateOptions<State, Move> extends DifficultyBand {
+    /** How many verified levels to return. */
+    count: number;
+    /** Base seed; the whole run is a pure function of it (default 1). */
+    seed?: number;
+    /** Cap on candidate attempts before giving up (default count * 60). */
+    maxAttempts?: number;
+    /** Search budget handed to the solver per candidate. */
+    solve?: SolveOptions;
+    /**
+     * Extra rejection hook — return true to discard an otherwise in-band candidate
+     * (e.g. a genre-specific "too few boxes" or "spawn adjacent to goal" rule).
+     */
+    reject?: (puzzle: Puzzle<State, Move>, result: AcceptedProof<Move>, subSeed: number) => boolean;
+    /**
+     * Canonical de-dup key for a candidate. Defaults to the puzzle's own initial
+     * state key, so two seeds that happen to build the same layout collapse to one.
+     */
+    dedupeKey?: (puzzle: Puzzle<State, Move>, result: AcceptedProof<Move>) => string;
+}
+/** The solver proof carried by an accepted candidate. */
+export interface AcceptedProof<Move> {
+    /** Shortest winning move sequence (the existence proof). */
+    path: Move[];
+    /** Its length — the primary difficulty metric. */
+    depth: number;
+    /** Nodes the solver expanded to find it — a complexity proxy. */
+    nodes: number;
+}
+/** A generated, solver-verified level: reproducible from `seed`, ramped by `depth`. */
+export interface GeneratedLevel<State, Move> extends AcceptedProof<Move> {
+    /** Position in the returned (difficulty-sorted) sequence. */
+    index: number;
+    /** The sub-seed that rebuilds this exact puzzle via `factory(new Rng(seed))`. */
+    seed: number;
+    /** The built puzzle instance (single-level: `initial()` returns this candidate). */
+    puzzle: Puzzle<State, Move>;
+}
+export interface GenerateReport<State, Move> {
+    levels: GeneratedLevel<State, Move>[];
+    /** Candidates tried. */
+    attempts: number;
+    /** How many were solvable at all (in-band or not). */
+    solvable: number;
+    /** True if `count` levels were found before `maxAttempts` ran out. */
+    complete: boolean;
+    /** Reproduce the whole run: the sub-seeds, in ramp order. */
+    seeds: number[];
+}
+/** Derive an independent, reproducible sub-seed for attempt `i` of a base run. */
+export declare function subSeed(seed: number, i: number): number;
+/**
+ * Generate `count` solver-verified levels inside a difficulty band. Builds
+ * candidates from `factory`, proves each with the BFS solver, and keeps the
+ * in-band, non-duplicate ones — sorted by solution depth so the returned
+ * sequence already ramps. Pure: same options → same levels, everywhere.
+ *
+ * A capped solver search (`exhausted`) is treated as "unknown, reject" — a level
+ * only ships if it was actually PROVEN winnable within budget.
+ */
+export declare function generateLevelsReport<State, Move>(factory: (rng: Rng) => Puzzle<State, Move>, opts: GenerateOptions<State, Move>): GenerateReport<State, Move>;
+/** Convenience: just the ramped levels. Throws if the band was too tight to fill. */
+export declare function generateLevels<State, Move>(factory: (rng: Rng) => Puzzle<State, Move>, opts: GenerateOptions<State, Move>): GeneratedLevel<State, Move>[];
+/** Rebuild the exact puzzle for a stored sub-seed — the campaign ships seeds, not maps. */
+export declare function levelFromSeed<State, Move>(factory: (rng: Rng) => Puzzle<State, Move>, seed: number): Puzzle<State, Move>;