maze-test 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,222 @@
-/** The npm package name. */
+type Language = "en" | "zh";
+type ScenarioKind = "success" | "treasure-and-leave" | "death-and-stop";
+type Direction = "up" | "down" | "left" | "right";
+interface Cell {
+    row: number;
+    col: number;
+}
+interface Door {
+    id: string;
+    position: Cell;
+    state: "closed";
+}
+interface KeyObject {
+    id: string;
+    type: "key";
+    position: Cell;
+}
+interface ChestObject {
+    id: string;
+    type: "chest";
+    position: Cell;
+    treasures: number;
+}
+interface TrapObject {
+    id: string;
+    type: "trap";
+    position: Cell;
+    damage: number;
+}
+interface MedicineObject {
+    id: string;
+    type: "medicine";
+    position: Cell;
+    recovery: number;
+}
+type MazeObject = KeyObject | ChestObject | TrapObject | MedicineObject;
+interface MazeMetrics {
+    totalCells: number;
+    wallCells: number;
+    floorCells: number;
+    connectedFloorCells: number;
+    connected: boolean;
+    floorAdjacencyEdges: number;
+    independentCycles: number;
+    deadEnds: number;
+    junctions: number;
+    entryGoalDistance: number | null;
+    doorCount: number;
+    gatingDoorCount: number;
+    objectCounts: Partial<Record<MazeObject["type"], number>>;
+}
+interface Maze {
+    schemaVersion: "solid-cell-maze-v3@1";
+    id: string;
+    seed: number;
+    requestedSeed: number;
+    rows: number;
+    cols: number;
+    braid: number;
+    coordinateSystem: {
+        origin: "top-left";
+        columns: "letters-left-to-right";
+        rows: "numbers-top-to-bottom";
+    };
+    terrain: string[];
+    entry: Cell;
+    goal: Cell;
+    doors: Door[];
+    objects: MazeObject[];
+    metrics: MazeMetrics;
+}
+interface GenerateMazeOptions {
+    rows?: number;
+    cols?: number;
+    seed?: number;
+    requestedSeed?: number;
+    braid?: number;
+    id?: string;
+}
+interface DecorateMazeOptions {
+    seed?: number;
+    doorCount?: number;
+    chestCount?: number;
+    trapCount?: number;
+    medicineCount?: number;
+}
+interface InitialState {
+    health: number;
+    healthMax: number;
+    keys: number;
+    treasures: number;
+}
+interface TrialState extends InitialState {
+    position: Cell;
+    alive: boolean;
+    reachedGoal: boolean;
+    openedDoors: string[];
+    collectedKeys: string[];
+    openedChests: string[];
+    triggeredTraps: string[];
+    usedMedicines: string[];
+}
+interface TrialEvent {
+    type: "open-door" | "collect-key" | "open-chest" | "pass-closed-chest" | "trigger-trap" | "use-medicine" | "die" | "reach-goal";
+    id?: string;
+    keyCost?: number;
+    treasures?: number;
+    damage?: number;
+    recovery?: number;
+}
+type BlockedReason = "dead" | "wall-or-outside" | "closed-door-without-key";
+interface TrialTraceItem {
+    step: number;
+    direction: Direction;
+    before: TrialState;
+    moved: boolean;
+    reason: BlockedReason | null;
+    events: TrialEvent[];
+    after: TrialState;
+}
+interface TrialAnswers {
+    finalPosition: string;
+    keys: number;
+    treasures: number;
+    health: number;
+    alive: boolean;
+    reachedGoal: boolean;
+    openedDoors: number;
+    openedChests: number;
+    triggeredTraps: number;
+    usedMedicines: number;
+    blockedMoves: number;
+    blockedAfterDeath: number;
+}
+interface SimulationResult {
+    state: TrialState;
+    trace: TrialTraceItem[];
+    answers: TrialAnswers;
+}
+interface TrialOptions {
+    seed?: number;
+    rows?: number;
+    cols?: number;
+    braid?: number;
+    doorCount?: number;
+    chestCount?: number;
+    trapCount?: number;
+    medicineCount?: number;
+    scenario?: ScenarioKind;
+    language?: Language;
+    style?: number;
+    minDistance?: number;
+    maxAttempts?: number;
+}
+interface ResolvedTrialOptions {
+    seed: number;
+    rows: number;
+    cols: number;
+    braid: number;
+    doorCount: number;
+    chestCount: number;
+    trapCount: number;
+    medicineCount: number;
+    scenario: ScenarioKind;
+    language: Language;
+    style: number;
+    minDistance: number;
+    maxAttempts: number;
+}
+interface TrialSections {
+    map: string;
+    rules: string;
+    actions: string;
+    questions: string;
+}
+interface MazeTrial {
+    schemaVersion: "maze-test-trial@1";
+    options: ResolvedTrialOptions;
+    maze: Maze;
+    initialState: InitialState;
+    actions: Direction[];
+    sections: TrialSections;
+    question: string;
+    answer: string;
+    result: SimulationResult;
+}
+interface MazeValidation {
+    valid: boolean;
+    errors: string[];
+    metrics: MazeMetrics | null;
+}
+
+declare function cell(row: number, col: number): Cell;
+declare function cellKey(value: Cell): string;
+declare function sameCell(a: Cell | undefined, b: Cell | undefined): boolean;
+declare function columnLabel(col: number): string;
+declare function letterNumberCoordinate(value: Cell): string;
+declare function rowColumnCoordinate(value: Cell): string;
+declare function neighbors(value: Cell, rows: number, cols: number): Cell[];
+
+declare function generateSolidCellMaze(options?: GenerateMazeOptions): Maze;
+declare function decorateSolidCellMaze(maze: Maze, options?: DecorateMazeOptions): Maze;
+declare function analyzeSolidCellMaze(maze: Maze): MazeMetrics;
+declare function validateSolidCellMaze(maze: Maze): MazeValidation;
+declare function shortestPath(maze: Pick<Maze, "rows" | "cols" | "terrain">, start: Cell, goal: Cell, excludedCell?: Cell | null): Cell[];
+declare function terrainAt(maze: Pick<Maze, "rows" | "cols" | "terrain">, value: Cell): string | null;
+declare function isFloor(maze: Pick<Maze, "rows" | "cols" | "terrain">, value: Cell): boolean;
+
+declare function renderCharacterMaze(maze: Maze, language?: Language): string;
+
+declare function simulateTrial(maze: Maze, actions: readonly Direction[], initial?: Partial<InitialState>): SimulationResult;
+declare function stateKey(state: TrialState): string;
+
+declare function generateTrial(options?: TrialOptions): MazeTrial;
+declare function generateQuestion(options?: TrialOptions): string;
+declare function generateAnswer(options?: TrialOptions): string;
+declare function resolveTrialOptions(options?: TrialOptions): ResolvedTrialOptions;
+
+/** The npm package name. Retained for compatibility with the initial release. */
 declare const packageName = "maze-test";
 
-export { packageName };
+export { type BlockedReason, type Cell, type ChestObject, type DecorateMazeOptions, type Direction, type Door, type GenerateMazeOptions, type InitialState, type KeyObject, type Language, type Maze, type MazeMetrics, type MazeObject, type MazeTrial, type MazeValidation, type MedicineObject, type ResolvedTrialOptions, type ScenarioKind, type SimulationResult, type TrapObject, type TrialAnswers, type TrialEvent, type TrialOptions, type TrialSections, type TrialState, type TrialTraceItem, analyzeSolidCellMaze, cell, cellKey, columnLabel, decorateSolidCellMaze, generateAnswer, generateQuestion, generateSolidCellMaze, generateTrial, isFloor, letterNumberCoordinate, neighbors, packageName, renderCharacterMaze, resolveTrialOptions, rowColumnCoordinate, sameCell, shortestPath, simulateTrial, stateKey, terrainAt, validateSolidCellMaze };