hayao 0.1.0 → 0.3.0

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

@@ -0,0 +1,22 @@
+/** Deterministic sine (bit-identical on every JS engine). */
+export declare function dsin(x: number): number;
+/** Deterministic cosine (bit-identical on every JS engine). */
+export declare function dcos(x: number): number;
+/** Deterministic arctangent. */
+export declare function datan(x: number): number;
+/** Deterministic atan2(y, x) with standard quadrant conventions. */
+export declare function datan2(y: number, x: number): number;
+/** Deterministic 2^x via Taylor series on the reduced argument. */
+export declare function dexp2(x: number): number;
+/** Deterministic natural exponential eˣ. Routes through dexp2 (eˣ = 2^(x/ln2)). */
+export declare function dexp(x: number): number;
+/** Deterministic hypotenuse: sqrt is IEEE-correctly-rounded, hypot is not. */
+export declare function dhypot(x: number, y: number): number;
+/** Deterministic natural logarithm. */
+export declare function dlog(x: number): number;
+/** Deterministic base-10 logarithm. */
+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;

package/dist/core/math.d.ts

@@ -14,6 +14,8 @@ export declare const clamp: (v: number, lo: number, hi: number) => number;
 export declare const lerp: (a: number, b: number, t: number) => number;
 export declare const invLerp: (a: number, b: number, v: number) => number;
 export declare const remap: (v: number, a0: number, a1: number, b0: number, b1: number) => number;
+/** Hermite smoothstep: 0 below `edge0`, 1 above `edge1`, eased in between. */
+export declare const smoothstep: (edge0: number, edge1: number, v: number) => number;
 export declare const TAU: number;
 export declare const deg2rad: (d: number) => number;
 export declare const rad2deg: (r: number) => number;