maze-test 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,315 @@
-/** The npm package name. */
+type Language = "en" | "zh";
+type ScenarioKind = "success" | "treasure-and-leave" | "death-and-stop" | "mechanism-tour";
+type Direction = "up" | "down" | "left" | "right";
+type MechanismComplexity = "basic" | "intermediate" | "advanced";
+type KeyMaterial = "copper" | "silver" | "gold";
+type TreasureType = "treasure" | "coin" | "gem" | "relic";
+type PotionKind = "healing" | "poison" | "antidote" | "haste" | "slow";
+type SpeedMode = "normal" | "fast" | "slow";
+type MaterialCounts = Record<KeyMaterial, number>;
+type TreasureCounts = Record<TreasureType, number>;
+interface MechanismConfig {
+    complexity: MechanismComplexity;
+    trapDamages: number[];
+    potionKinds: PotionKind[];
+    keyMaterials: KeyMaterial[];
+    treasureTypes: TreasureType[];
+    poisonDamage: number;
+    poisonDuration: number;
+    speedDuration: number;
+    movementTime: Record<SpeedMode, number>;
+}
+interface Cell {
+    row: number;
+    col: number;
+}
+interface Door {
+    id: string;
+    position: Cell;
+    state: "closed";
+    material?: KeyMaterial;
+}
+interface KeyObject {
+    id: string;
+    type: "key";
+    position: Cell;
+    material?: KeyMaterial;
+}
+interface TreasureContent {
+    type: TreasureType;
+    count: number;
+}
+interface ChestObject {
+    id: string;
+    type: "chest";
+    position: Cell;
+    treasures: number;
+    contents: TreasureContent[];
+    lockMaterial?: KeyMaterial;
+}
+interface TrapObject {
+    id: string;
+    type: "trap";
+    position: Cell;
+    damage: number;
+}
+/** Legacy basic-mode healing object retained for schema compatibility. */
+interface MedicineObject {
+    id: string;
+    type: "medicine";
+    position: Cell;
+    recovery: number;
+}
+interface PotionObject {
+    id: string;
+    type: "potion";
+    position: Cell;
+    kind: PotionKind;
+    potency?: number;
+    duration?: number;
+}
+type MazeObject = KeyObject | ChestObject | TrapObject | MedicineObject | PotionObject;
+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" | "solid-cell-maze-v4@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";
+    };
+    mechanisms: MechanismConfig;
+    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;
+    mechanisms?: MechanismConfig;
+}
+interface DecorateMazeOptions {
+    seed?: number;
+    doorCount?: number;
+    chestCount?: number;
+    trapCount?: number;
+    medicineCount?: number;
+    potionCount?: number;
+    mechanisms?: MechanismConfig;
+}
+interface InitialState {
+    health: number;
+    healthMax: number;
+    keys: number;
+    treasures: number;
+    keysByMaterial?: Partial<MaterialCounts>;
+    treasuresByType?: Partial<TreasureCounts>;
+    elapsedTime?: number;
+    speed?: SpeedMode;
+    speedRemaining?: number;
+    poisonDamage?: number;
+    poisonRemaining?: number;
+}
+interface TrialState {
+    position: Cell;
+    health: number;
+    healthMax: number;
+    keys: number;
+    keysByMaterial: MaterialCounts;
+    treasures: number;
+    treasuresByType: TreasureCounts;
+    elapsedTime: number;
+    speed: SpeedMode;
+    speedRemaining: number;
+    poisonDamage: number;
+    poisonRemaining: number;
+    alive: boolean;
+    reachedGoal: boolean;
+    openedDoors: string[];
+    collectedKeys: string[];
+    openedChests: string[];
+    triggeredTraps: string[];
+    usedMedicines: string[];
+    usedPotions: string[];
+}
+interface TrialEvent {
+    type: "open-door" | "collect-key" | "open-chest" | "pass-closed-chest" | "trigger-trap" | "use-medicine" | "drink-potion" | "poison-tick" | "speed-expired" | "die" | "reach-goal";
+    id?: string;
+    material?: KeyMaterial;
+    potionKind?: PotionKind;
+    keyCost?: number;
+    treasures?: number;
+    contents?: TreasureContent[];
+    damage?: number;
+    recovery?: number;
+    duration?: number;
+    timeCost?: number;
+}
+type BlockedReason = "dead" | "wall-or-outside" | "closed-door-without-key" | "closed-door-without-matching-key";
+interface TrialTraceItem {
+    step: number;
+    direction: Direction;
+    before: TrialState;
+    moved: boolean;
+    reason: BlockedReason | null;
+    events: TrialEvent[];
+    after: TrialState;
+}
+interface TrialAnswers {
+    finalPosition: string;
+    keys: number;
+    keysByMaterial: MaterialCounts;
+    treasures: number;
+    treasuresByType: TreasureCounts;
+    health: number;
+    alive: boolean;
+    reachedGoal: boolean;
+    openedDoors: number;
+    openedChests: number;
+    triggeredTraps: number;
+    usedMedicines: number;
+    usedPotions: number;
+    elapsedTime: number;
+    finalSpeed: SpeedMode;
+    speedRemaining: number;
+    poisonDamage: number;
+    poisonRemaining: 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;
+    potionCount?: number;
+    complexity?: MechanismComplexity;
+    trapDamages?: number[];
+    potionKinds?: PotionKind[];
+    keyMaterials?: KeyMaterial[];
+    treasureTypes?: TreasureType[];
+    poisonDamage?: number;
+    poisonDuration?: number;
+    speedDuration?: 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;
+    potionCount: number;
+    mechanisms: MechanismConfig;
+    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@2";
+    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 mechanismPreset(complexity: MechanismComplexity): MechanismConfig;
+declare function resolveMechanisms(options: TrialOptions): MechanismConfig;
+declare function defaultObjectCounts(complexity: MechanismComplexity): {
+    doors: number;
+    chests: number;
+    traps: number;
+    potions: number;
+};
+declare function emptyMaterialCounts(values?: Partial<MaterialCounts>): MaterialCounts;
+declare function emptyTreasureCounts(values?: Partial<TreasureCounts>): TreasureCounts;
+declare function totalMaterialKeys(counts: MaterialCounts): number;
+
+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 KeyMaterial, type KeyObject, type Language, type MaterialCounts, type Maze, type MazeMetrics, type MazeObject, type MazeTrial, type MazeValidation, type MechanismComplexity, type MechanismConfig, type MedicineObject, type PotionKind, type PotionObject, type ResolvedTrialOptions, type ScenarioKind, type SimulationResult, type SpeedMode, type TrapObject, type TreasureContent, type TreasureCounts, type TreasureType, type TrialAnswers, type TrialEvent, type TrialOptions, type TrialSections, type TrialState, type TrialTraceItem, analyzeSolidCellMaze, cell, cellKey, columnLabel, decorateSolidCellMaze, defaultObjectCounts, emptyMaterialCounts, emptyTreasureCounts, generateAnswer, generateQuestion, generateSolidCellMaze, generateTrial, isFloor, letterNumberCoordinate, mechanismPreset, neighbors, packageName, renderCharacterMaze, resolveMechanisms, resolveTrialOptions, rowColumnCoordinate, sameCell, shortestPath, simulateTrial, stateKey, terrainAt, totalMaterialKeys, validateSolidCellMaze };