hayao 0.2.0 → 0.3.0

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/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>;

package/dist/content/level.d.ts

@@ -0,0 +1,93 @@
+import { type TilemapData } from '../physics/tilemap';
+import { type Cell, type Passable } from '../logic/graph';
+export interface LevelEntity {
+    /** Entity kind, resolved from the legend (e.g. 'crystal', 'gust'). */
+    kind: string;
+    /** Tile coordinates. */
+    tx: number;
+    ty: number;
+    /** Center of the tile in design-space px. */
+    x: number;
+    y: number;
+}
+/** The authored input: rows + a legend. Everything else is derived. */
+export interface LevelSpec {
+    name: string;
+    /** Tile edge in px (default 32). */
+    tileSize?: number;
+    /** ASCII rows, top to bottom. Ragged rows are padded with empty on the right. */
+    rows: string[];
+    /** Non-terrain marker char → entity kind. 'S'/'G' are reserved and need no legend. */
+    legend?: Record<string, string>;
+}
+/** The resolved, validated level — plain JSON, safe to hash/snapshot/diff. */
+export interface LevelData extends Required<Omit<LevelSpec, 'legend'>> {
+    legend: Record<string, string>;
+    cols: number;
+    rowCount: number;
+    spawn: Cell;
+    goal: Cell;
+    entities: LevelEntity[];
+}
+/** Center of a tile in design-space px. */
+export declare const tileCenter: (tx: number, ty: number, tileSize: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Resolve a LevelSpec into a full LevelData: find the spawn/goal markers, extract
+ * legend entities, and record dimensions. Throws only on the two structural sins
+ * that make a level meaningless (no spawn, no goal); everything else is surfaced
+ * as a soft issue by `levelIssues` so an agent can see ALL problems at once.
+ */
+export declare function defineLevel(spec: LevelSpec): LevelData;
+/**
+ * Validate a level's data. Returns human-readable issues (empty = clean), in the
+ * layoutIssues idiom. Catches unknown glyphs, spawn/goal buried in solid, and
+ * markers off the map — the authoring mistakes that produce a broken stage.
+ */
+export declare function levelIssues(data: LevelData): string[];
+/** Build the collision tilemap from the level's terrain (markers → empty). */
+export declare function levelToTilemap(data: LevelData): TilemapData;
+export interface ReachReport {
+    ok: boolean;
+    /** Labels of things the spawn cannot reach ('goal', or 'entity@tx,ty'). */
+    unreachable: string[];
+    /** Count of reachable cells/footholds (search size). */
+    reached: number;
+}
+/**
+ * Generic connectivity proof: flood-fill non-solid cells from the spawn and check
+ * the goal (and every entity) is reachable. Right for top-down / roguelike stages
+ * where movement is grid-walking. `passable` defaults to "not a solid tile".
+ */
+export declare function levelReachable(data: LevelData, opts?: {
+    passable?: Passable;
+    diagonal?: boolean;
+}): ReachReport;
+export interface PlatformerReachOptions {
+    /** Max tiles the body can rise in one jump (derive from jumpHeight / tileSize). */
+    jumpTiles: number;
+    /** Max horizontal tiles cleared in a jump (derive from jumpDistance / tileSize). */
+    runTiles: number;
+}
+/**
+ * Platformer reachability: build the graph of FOOTHOLDS (a non-solid, non-hazard
+ * cell with solid/one-way ground directly below) and connect two footholds when a
+ * jump arc can carry the body between them — up to `jumpTiles` of rise, any drop,
+ * within `runTiles` horizontally. Then BFS from the spawn's foothold and confirm
+ * the goal's foothold is reachable. This is the honest "can you actually climb it?"
+ * proof a flat flood-fill can't give — it respects gravity and jump limits.
+ */
+export declare function platformerReachable(data: LevelData, opts: PlatformerReachOptions): ReachReport;
+export interface LevelChange {
+    kind: 'tile' | 'entity+' | 'entity-' | 'spawn' | 'goal';
+    detail: string;
+}
+/**
+ * Structural diff between two levels — the primitive that makes data-authored
+ * stages iterable: change three tiles, see exactly three changes, not a whole
+ * rewritten build() function. Compares terrain cell-by-cell, entities by position,
+ * and the spawn/goal markers.
+ */
+export declare function diffLevels(a: LevelData, b: LevelData): LevelChange[];

package/dist/content/worldgraph.d.ts

@@ -0,0 +1,73 @@
+import { type Puzzle, type SolveResult } from '../verify/solver';
+/** A place in the world (a room or a named area). */
+export interface WorldRegion {
+    id: string;
+    name?: string;
+    biome?: string;
+}
+/** A traversal between two regions, gated behind abilities. Bidirectional unless `oneWay`. */
+export interface WorldEdge {
+    from: string;
+    to: string;
+    /** Ability ids ALL required to pass. Empty/undefined = open. */
+    requires?: string[];
+    /** If true, only `from → to` (a drop you can't climb back up). */
+    oneWay?: boolean;
+}
+/** A collectible that grants an ability, located in a region. */
+export interface WorldPickup {
+    id: string;
+    region: string;
+    /** Ability id this pickup grants. */
+    grants: string;
+}
+/** The whole world as pure data. */
+export interface WorldGraphDef {
+    regions: WorldRegion[];
+    edges: WorldEdge[];
+    pickups: WorldPickup[];
+    /** Starting region id. */
+    start: string;
+    /** Goal region id (the "heart" — where a minimal completion ends). */
+    goal: string;
+}
+/** A progression state: where you are + which pickups you've taken (sorted). */
+export interface ProgressState {
+    region: string;
+    taken: string[];
+}
+export type ProgressMove = {
+    kind: 'move';
+    to: string;
+} | {
+    kind: 'take';
+    pickup: string;
+};
+/** 'complete' = reach the goal; 'full' = reach the goal with 100% pickups. */
+export type CompletionMode = 'complete' | 'full';
+/** Ability ids granted by a set of taken pickup ids. */
+export declare function abilitiesOf(world: WorldGraphDef, taken: readonly string[]): Set<string>;
+/** Build the progression Puzzle for `solve()` to prove. */
+export declare function progressionPuzzle(world: WorldGraphDef, mode?: CompletionMode): Puzzle<ProgressState, ProgressMove>;
+/** Prove a minimal completion (reach the goal) exists. */
+export declare function proveCompletable(world: WorldGraphDef): SolveResult<ProgressMove>;
+/** Prove a 100% completion (all pickups + reach the goal) exists. */
+export declare function proveFullCompletion(world: WorldGraphDef): SolveResult<ProgressMove>;
+/** Regions reachable from the start with a FIXED ability set (no collecting). */
+export declare function reachableRegions(world: WorldGraphDef, abilities: Iterable<string>): string[];
+export interface SoftlockReport {
+    ok: boolean;
+    /** Reachable states (as keys) from which the goal can never be reached. */
+    deadEnds: string[];
+    /** How many progression states are reachable from the start (a size proxy). */
+    statesExplored: number;
+}
+/**
+ * Prove no softlock: enumerate every reachable progression state and confirm the
+ * goal stays reachable from each. Only one-way edges can create a dead end;
+ * with all-bidirectional edges a completable world is softlock-free by
+ * construction, but this checks it directly regardless.
+ */
+export declare function findSoftlocks(world: WorldGraphDef, mode?: CompletionMode): SoftlockReport;
+/** Structural problems a solver can't express (dangling ids, dupes, isolation). */
+export declare function validateWorld(world: WorldGraphDef): string[];

package/dist/core/dmath.d.ts

@@ -18,3 +18,5 @@ export declare function dlog(x: number): number;
 export declare const dlog10: (x: number) => number;
 /** Deterministic base-2 logarithm. */
 export declare const dlog2: (x: number) => number;
+/** Deterministic base^exp (bit-identical across JS engines). */
+export declare function dpow(base: number, exp: number): number;