maze-test 0.1.0 → 0.2.0

package/dist/cli.cjs

@@ -0,0 +1,1368 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_node_process = __toESM(require("process"), 1);
+
+// src/coordinates.ts
+function cell(row, col) {
+  return { row, col };
+}
+function cellKey(value) {
+  return `${value.row},${value.col}`;
+}
+function sameCell(a, b) {
+  return a?.row === b?.row && a?.col === b?.col;
+}
+function columnLabel(col) {
+  if (!Number.isInteger(col) || col < 1) throw new Error(`Invalid column number: ${col}`);
+  let value = col;
+  let label = "";
+  while (value > 0) {
+    value -= 1;
+    label = String.fromCharCode(65 + value % 26) + label;
+    value = Math.floor(value / 26);
+  }
+  return label;
+}
+function letterNumberCoordinate(value) {
+  return `${columnLabel(value.col)}${value.row}`;
+}
+function neighbors(value, rows, cols) {
+  return [
+    cell(value.row - 1, value.col),
+    cell(value.row + 1, value.col),
+    cell(value.row, value.col - 1),
+    cell(value.row, value.col + 1)
+  ].filter((item) => item.row >= 1 && item.row <= rows && item.col >= 1 && item.col <= cols);
+}
+
+// src/maze.ts
+function generateSolidCellMaze(options = {}) {
+  const rows = oddDimension(options.rows ?? 15, "rows");
+  const cols = oddDimension(options.cols ?? 15, "cols");
+  const seed = integerOption(options.seed ?? 1, "seed", 0);
+  const requestedSeed = integerOption(options.requestedSeed ?? seed, "requestedSeed", 0);
+  const braid = numberOption(options.braid ?? 0, "braid", 0, 1);
+  const rng = mulberry32(seed);
+  const grid = Array.from({ length: rows }, () => Array(cols).fill("#"));
+  const logicalCells = [];
+  for (let row = 1; row < rows - 1; row += 2) {
+    for (let col = 1; col < cols - 1; col += 2) logicalCells.push({ row, col });
+  }
+  const start = logicalCells[randomInt(rng, logicalCells.length)];
+  if (!start) throw new Error("The maze has no logical cells.");
+  const visited = /* @__PURE__ */ new Set([cellKey(start)]);
+  const stack = [start];
+  grid[start.row][start.col] = ".";
+  while (stack.length > 0) {
+    const current = stack.at(-1);
+    if (!current) break;
+    const choices = shuffle(
+      rng,
+      logicalNeighbors(current, rows, cols).filter((item) => !visited.has(cellKey(item)))
+    );
+    const next = choices[0];
+    if (!next) {
+      stack.pop();
+      continue;
+    }
+    grid[(current.row + next.row) / 2][(current.col + next.col) / 2] = ".";
+    grid[next.row][next.col] = ".";
+    visited.add(cellKey(next));
+    stack.push(next);
+  }
+  braidDeadEnds(grid, braid, rng);
+  const terrain = grid.map((row) => row.join(""));
+  const first = farthestFloor(cell(2, 2), terrain).cell;
+  const second = farthestFloor(first, terrain).cell;
+  const maze = {
+    schemaVersion: "solid-cell-maze-v3@1",
+    id: options.id ?? `solid-maze-${rows}x${cols}-${requestedSeed}`,
+    seed,
+    requestedSeed,
+    rows,
+    cols,
+    braid,
+    coordinateSystem: {
+      origin: "top-left",
+      columns: "letters-left-to-right",
+      rows: "numbers-top-to-bottom"
+    },
+    terrain,
+    entry: first,
+    goal: second,
+    doors: [],
+    objects: [],
+    metrics: emptyMetrics(rows, cols)
+  };
+  maze.metrics = analyzeSolidCellMaze(maze);
+  return maze;
+}
+function decorateSolidCellMaze(maze, options = {}) {
+  const result = structuredClone(maze);
+  const decorationSeed = integerOption(options.seed ?? maze.seed + 71311, "decoration seed", 0);
+  const rng = mulberry32(decorationSeed);
+  const mainPath = shortestPath(result, result.entry, result.goal);
+  const occupied = /* @__PURE__ */ new Set([cellKey(result.entry), cellKey(result.goal)]);
+  const doorCount = integerOption(
+    options.doorCount ?? Math.max(1, Math.floor(result.metrics.floorCells / 120)),
+    "doorCount",
+    0
+  );
+  const chestCount = integerOption(options.chestCount ?? 2, "chestCount", 0);
+  const trapCount = integerOption(options.trapCount ?? 2, "trapCount", 0);
+  const medicineCount = integerOption(options.medicineCount ?? 2, "medicineCount", 0);
+  const doorIndices = selectGatingDoorIndices(result, mainPath, doorCount);
+  result.doors = doorIndices.map((index, doorIndex) => {
+    const position = mainPath[index];
+    if (!position) throw new Error(`No path cell exists at door index ${index}.`);
+    occupied.add(cellKey(position));
+    return { id: `door-${doorIndex + 1}`, position, state: "closed" };
+  });
+  const objects = [];
+  for (let index = 0; index < result.doors.length; index += 1) {
+    const doorIndex = doorIndices[index];
+    if (doorIndex === void 0) throw new Error("Door index mismatch.");
+    const preferredIndex = Math.max(1, Math.floor(doorIndex * 0.55));
+    const position = freePathCellBefore(mainPath, preferredIndex, occupied);
+    occupied.add(cellKey(position));
+    const key = { id: `key-${index + 1}`, type: "key", position };
+    objects.push(key);
+  }
+  const degrees = degreeMap(result);
+  const deadEnds = shuffle(
+    rng,
+    floorCells(result).filter(
+      (item) => degrees.get(cellKey(item)) === 1 && !occupied.has(cellKey(item))
+    )
+  );
+  for (let index = 0; index < chestCount; index += 1) {
+    const position = takeFree(deadEnds, result, occupied, rng, "chest");
+    occupied.add(cellKey(position));
+    const chest = {
+      id: `chest-${index + 1}`,
+      type: "chest",
+      position,
+      treasures: 1 + index % 3
+    };
+    objects.push(chest);
+  }
+  const trapCandidates = shuffle(rng, mainPath.slice(2, -2));
+  for (let index = 0; index < trapCount; index += 1) {
+    const position = takeFree(trapCandidates, result, occupied, rng, "trap");
+    occupied.add(cellKey(position));
+    const trap = {
+      id: `trap-${index + 1}`,
+      type: "trap",
+      position,
+      damage: 1
+    };
+    objects.push(trap);
+  }
+  const medicineCandidates = shuffle(rng, floorCells(result));
+  for (let index = 0; index < medicineCount; index += 1) {
+    const position = takeFree(medicineCandidates, result, occupied, rng, "medicine");
+    occupied.add(cellKey(position));
+    const medicine = {
+      id: `medicine-${index + 1}`,
+      type: "medicine",
+      position,
+      recovery: 1
+    };
+    objects.push(medicine);
+  }
+  result.objects = objects;
+  result.metrics = analyzeSolidCellMaze(result);
+  return result;
+}
+function analyzeSolidCellMaze(maze) {
+  assertShape(maze);
+  const floors = floorCells(maze);
+  const graph = adjacency(maze);
+  const distances = bfsDistances(maze.entry, graph);
+  const degreeValues = [...graph.values()].map((items) => items.length);
+  const edgeCount = degreeValues.reduce((sum, value) => sum + value, 0) / 2;
+  const mainPath = shortestPath(maze, maze.entry, maze.goal);
+  const objectCounts = {};
+  for (const object of maze.objects ?? []) {
+    objectCounts[object.type] = (objectCounts[object.type] ?? 0) + 1;
+  }
+  return {
+    totalCells: maze.rows * maze.cols,
+    wallCells: maze.rows * maze.cols - floors.length,
+    floorCells: floors.length,
+    connectedFloorCells: distances.size,
+    connected: distances.size === floors.length,
+    floorAdjacencyEdges: edgeCount,
+    independentCycles: edgeCount - floors.length + 1,
+    deadEnds: degreeValues.filter((value) => value === 1).length,
+    junctions: degreeValues.filter((value) => value >= 3).length,
+    entryGoalDistance: mainPath.length > 0 ? mainPath.length - 1 : null,
+    doorCount: maze.doors.length,
+    gatingDoorCount: maze.doors.filter(
+      (door) => shortestPath(maze, maze.entry, maze.goal, door.position).length === 0
+    ).length,
+    objectCounts
+  };
+}
+function validateSolidCellMaze(maze) {
+  const errors = [];
+  try {
+    assertShape(maze);
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [error instanceof Error ? error.message : String(error)],
+      metrics: null
+    };
+  }
+  for (let row = 1; row <= maze.rows; row += 1) {
+    for (let col = 1; col <= maze.cols; col += 1) {
+      const value = terrainAt(maze, cell(row, col));
+      if (value !== "#" && value !== ".") errors.push(`Invalid terrain at ${row},${col}: ${value}`);
+      if ((row === 1 || row === maze.rows || col === 1 || col === maze.cols) && value !== "#") {
+        errors.push(`The outer boundary is not a wall at ${row},${col}.`);
+      }
+    }
+  }
+  if (!isFloor(maze, maze.entry)) errors.push("The entry is not on a floor cell.");
+  if (!isFloor(maze, maze.goal)) errors.push("The goal is not on a floor cell.");
+  if (sameCell(maze.entry, maze.goal)) errors.push("The entry and goal overlap.");
+  const occupied = /* @__PURE__ */ new Set([cellKey(maze.entry), cellKey(maze.goal)]);
+  for (const door of maze.doors) {
+    if (!isFloor(maze, door.position)) errors.push(`${door.id} is not on a floor cell.`);
+    const key = cellKey(door.position);
+    if (occupied.has(key)) errors.push(`${door.id} overlaps another feature.`);
+    occupied.add(key);
+  }
+  for (const object of maze.objects) {
+    if (!isFloor(maze, object.position)) errors.push(`${object.id} is not on a floor cell.`);
+    const key = cellKey(object.position);
+    if (occupied.has(key)) errors.push(`${object.id} overlaps another feature.`);
+    occupied.add(key);
+  }
+  const metrics = analyzeSolidCellMaze(maze);
+  if (!metrics.connected) {
+    errors.push(`Floor cells are disconnected: ${metrics.connectedFloorCells}/${metrics.floorCells}.`);
+  }
+  if (metrics.deadEnds === 0) errors.push("The maze has no dead ends.");
+  if (metrics.junctions === 0) errors.push("The maze has no junctions.");
+  if (metrics.gatingDoorCount !== metrics.doorCount) {
+    errors.push(`${metrics.doorCount - metrics.gatingDoorCount} door(s) can be bypassed.`);
+  }
+  const path = shortestPath(maze, maze.entry, maze.goal);
+  const pathIndex = new Map(path.map((item, index) => [cellKey(item), index]));
+  for (let index = 0; index < maze.doors.length; index += 1) {
+    const door = maze.doors[index];
+    if (!door) continue;
+    const key = maze.objects.find((item) => item.id === `key-${index + 1}`);
+    const doorIndex = pathIndex.get(cellKey(door.position));
+    const keyIndex = key ? pathIndex.get(cellKey(key.position)) : void 0;
+    if (!key) errors.push(`Missing a key for ${door.id}.`);
+    else if (keyIndex === void 0 || doorIndex === void 0 || keyIndex >= doorIndex) {
+      errors.push(`${key.id} is not before ${door.id} on the main path.`);
+    }
+  }
+  return { valid: errors.length === 0, errors, metrics };
+}
+function shortestPath(maze, start, goal, excludedCell = null) {
+  if (excludedCell && (sameCell(start, excludedCell) || sameCell(goal, excludedCell))) return [];
+  const graph = adjacency(maze, excludedCell);
+  const queue = [start];
+  const parent = /* @__PURE__ */ new Map([[cellKey(start), null]]);
+  const values = /* @__PURE__ */ new Map([[cellKey(start), start]]);
+  let queueIndex = 0;
+  while (queueIndex < queue.length) {
+    const current = queue[queueIndex];
+    queueIndex += 1;
+    if (!current) break;
+    if (sameCell(current, goal)) break;
+    for (const next of graph.get(cellKey(current)) ?? []) {
+      const key = cellKey(next);
+      if (parent.has(key)) continue;
+      parent.set(key, cellKey(current));
+      values.set(key, next);
+      queue.push(next);
+    }
+  }
+  if (!parent.has(cellKey(goal))) return [];
+  const path = [];
+  let cursor = cellKey(goal);
+  while (cursor !== null) {
+    const value = values.get(cursor);
+    if (!value) throw new Error(`Could not reconstruct path at ${cursor}.`);
+    path.push(value);
+    cursor = parent.get(cursor) ?? null;
+  }
+  return path.reverse();
+}
+function terrainAt(maze, value) {
+  if (value.row < 1 || value.row > maze.rows || value.col < 1 || value.col > maze.cols) {
+    return null;
+  }
+  return maze.terrain[value.row - 1]?.[value.col - 1] ?? null;
+}
+function isFloor(maze, value) {
+  return terrainAt(maze, value) === ".";
+}
+function braidDeadEnds(grid, braid, rng) {
+  if (braid <= 0) return;
+  const rows = grid.length;
+  const cols = grid[0]?.length ?? 0;
+  const logicalCells = [];
+  for (let row = 1; row < rows - 1; row += 2) {
+    for (let col = 1; col < cols - 1; col += 2) logicalCells.push({ row, col });
+  }
+  const deadEnds = shuffle(
+    rng,
+    logicalCells.filter((value) => openLogicalNeighbors(grid, value).length === 1)
+  );
+  for (const current of deadEnds) {
+    if (rng() > braid) continue;
+    const closed = shuffle(
+      rng,
+      logicalNeighbors(current, rows, cols).filter(
+        (next2) => grid[(current.row + next2.row) / 2]?.[(current.col + next2.col) / 2] === "#"
+      )
+    );
+    const next = closed[0];
+    if (!next) continue;
+    grid[(current.row + next.row) / 2][(current.col + next.col) / 2] = ".";
+  }
+}
+function openLogicalNeighbors(grid, current) {
+  return logicalNeighbors(current, grid.length, grid[0]?.length ?? 0).filter(
+    (next) => grid[(current.row + next.row) / 2]?.[(current.col + next.col) / 2] === "."
+  );
+}
+function logicalNeighbors(value, rows, cols) {
+  return [
+    { row: value.row - 2, col: value.col },
+    { row: value.row + 2, col: value.col },
+    { row: value.row, col: value.col - 2 },
+    { row: value.row, col: value.col + 2 }
+  ].filter((item) => item.row >= 1 && item.row < rows - 1 && item.col >= 1 && item.col < cols - 1);
+}
+function farthestFloor(start, terrain) {
+  const maze = { rows: terrain.length, cols: terrain[0]?.length ?? 0, terrain };
+  const graph = adjacency(maze);
+  const distances = bfsDistances(start, graph);
+  let farthest = start;
+  let distance = -1;
+  for (const [key, value] of distances) {
+    if (value <= distance) continue;
+    distance = value;
+    farthest = parseCellKey(key);
+  }
+  return { cell: farthest, distance };
+}
+function floorCells(maze) {
+  const values = [];
+  for (let row = 1; row <= maze.rows; row += 1) {
+    for (let col = 1; col <= maze.cols; col += 1) {
+      if (isFloor(maze, cell(row, col))) values.push(cell(row, col));
+    }
+  }
+  return values;
+}
+function adjacency(maze, excludedCell = null) {
+  const floors = floorCells(maze).filter((item) => !excludedCell || !sameCell(item, excludedCell));
+  const floorKeys = new Set(floors.map(cellKey));
+  return new Map(
+    floors.map((item) => [
+      cellKey(item),
+      neighbors(item, maze.rows, maze.cols).filter((next) => floorKeys.has(cellKey(next)))
+    ])
+  );
+}
+function bfsDistances(start, graph) {
+  const distances = /* @__PURE__ */ new Map([[cellKey(start), 0]]);
+  const queue = [start];
+  let queueIndex = 0;
+  while (queueIndex < queue.length) {
+    const current = queue[queueIndex];
+    queueIndex += 1;
+    if (!current) break;
+    const distance = distances.get(cellKey(current));
+    if (distance === void 0) continue;
+    for (const next of graph.get(cellKey(current)) ?? []) {
+      const key = cellKey(next);
+      if (distances.has(key)) continue;
+      distances.set(key, distance + 1);
+      queue.push(next);
+    }
+  }
+  return distances;
+}
+function degreeMap(maze) {
+  return new Map([...adjacency(maze)].map(([key, values]) => [key, values.length]));
+}
+function selectGatingDoorIndices(maze, mainPath, count) {
+  if (count === 0) return [];
+  const degrees = degreeMap(maze);
+  const candidates = [];
+  for (let index = 3; index < mainPath.length - 3; index += 1) {
+    const pathCell = mainPath[index];
+    if (!pathCell || (degrees.get(cellKey(pathCell)) ?? 0) !== 2) continue;
+    if (shortestPath(maze, maze.entry, maze.goal, pathCell).length === 0) candidates.push(index);
+  }
+  if (candidates.length < count) {
+    throw new Error(`Only ${candidates.length} non-bypassable path cells are available for ${count} doors.`);
+  }
+  const targets = spacedIndices(mainPath.length - 1, count, 0.28, 0.78);
+  const selected = [];
+  for (const target of targets) {
+    const available = candidates.filter((index) => !selected.includes(index));
+    available.sort(
+      (left, right) => Math.abs(left - target) - Math.abs(right - target) || left - right
+    );
+    const candidate = available[0];
+    if (candidate === void 0) throw new Error(`Could not place ${count} doors.`);
+    selected.push(candidate);
+  }
+  if (selected.length !== count) throw new Error(`Could not space ${count} doors along the main path.`);
+  return selected.sort((left, right) => left - right);
+}
+function freePathCellBefore(mainPath, preferredIndex, occupied) {
+  for (let distance = 0; distance < mainPath.length; distance += 1) {
+    for (const index of [preferredIndex - distance, preferredIndex + distance]) {
+      if (index <= 0 || index >= mainPath.length - 1) continue;
+      const candidate = mainPath[index];
+      if (candidate && !occupied.has(cellKey(candidate))) return candidate;
+    }
+  }
+  throw new Error("There is no free path cell on which to place a key.");
+}
+function takeFree(candidates, maze, occupied, rng, type) {
+  while (candidates.length > 0) {
+    const value = candidates.shift();
+    if (value && !occupied.has(cellKey(value))) return value;
+  }
+  const fallback = shuffle(rng, floorCells(maze)).find((item) => !occupied.has(cellKey(item)));
+  if (!fallback) throw new Error(`There are not enough free floor cells to place ${type}.`);
+  return fallback;
+}
+function spacedIndices(edgeCount, count, startRatio, endRatio) {
+  if (count === 0) return [];
+  const values = [];
+  for (let index = 0; index < count; index += 1) {
+    const ratio = count === 1 ? (startRatio + endRatio) / 2 : startRatio + (endRatio - startRatio) * index / (count - 1);
+    values.push(Math.max(2, Math.min(edgeCount - 2, Math.floor(edgeCount * ratio))));
+  }
+  return [...new Set(values)];
+}
+function parseCellKey(key) {
+  const [row, col] = key.split(",").map(Number);
+  if (row === void 0 || col === void 0) throw new Error(`Invalid cell key: ${key}`);
+  return cell(row, col);
+}
+function assertShape(maze) {
+  oddDimension(maze.rows, "rows");
+  oddDimension(maze.cols, "cols");
+  if (!Array.isArray(maze.terrain) || maze.terrain.length !== maze.rows) {
+    throw new Error("The terrain row count does not match rows.");
+  }
+  if (maze.terrain.some((row) => typeof row !== "string" || row.length !== maze.cols)) {
+    throw new Error("A terrain row does not match cols.");
+  }
+}
+function oddDimension(value, name) {
+  integerOption(value, name, 7);
+  if (value % 2 === 0) throw new Error(`${name} must be odd.`);
+  return value;
+}
+function integerOption(value, name, minimum) {
+  if (!Number.isInteger(value) || value < minimum) {
+    throw new Error(`${name} must be an integer greater than or equal to ${minimum}.`);
+  }
+  return value;
+}
+function numberOption(value, name, minimum, maximum) {
+  if (!Number.isFinite(value) || value < minimum || value > maximum) {
+    throw new Error(`${name} must be between ${minimum} and ${maximum}.`);
+  }
+  return value;
+}
+function randomInt(rng, maximum) {
+  return Math.floor(rng() * maximum);
+}
+function shuffle(rng, input) {
+  const values = [...input];
+  for (let index = values.length - 1; index > 0; index -= 1) {
+    const target = randomInt(rng, index + 1);
+    const prior = values[index];
+    const replacement = values[target];
+    if (prior === void 0 || replacement === void 0) continue;
+    values[index] = replacement;
+    values[target] = prior;
+  }
+  return values;
+}
+function mulberry32(seed) {
+  let value = seed >>> 0;
+  return () => {
+    value += 1831565813;
+    let mixed = value;
+    mixed = Math.imul(mixed ^ mixed >>> 15, mixed | 1);
+    mixed ^= mixed + Math.imul(mixed ^ mixed >>> 7, mixed | 61);
+    return ((mixed ^ mixed >>> 14) >>> 0) / 4294967296;
+  };
+}
+function emptyMetrics(rows, cols) {
+  return {
+    totalCells: rows * cols,
+    wallCells: rows * cols,
+    floorCells: 0,
+    connectedFloorCells: 0,
+    connected: false,
+    floorAdjacencyEdges: 0,
+    independentCycles: 0,
+    deadEnds: 0,
+    junctions: 0,
+    entryGoalDistance: null,
+    doorCount: 0,
+    gatingDoorCount: 0,
+    objectCounts: {}
+  };
+}
+
+// src/simulator.ts
+var DELTAS = {
+  up: [-1, 0],
+  down: [1, 0],
+  left: [0, -1],
+  right: [0, 1]
+};
+function simulateTrial(maze, actions, initial = {}) {
+  const health = initial.health ?? 5;
+  const state = {
+    position: structuredClone(maze.entry),
+    health,
+    healthMax: initial.healthMax ?? health,
+    keys: initial.keys ?? 0,
+    treasures: initial.treasures ?? 0,
+    alive: health > 0,
+    reachedGoal: false,
+    openedDoors: [],
+    collectedKeys: [],
+    openedChests: [],
+    triggeredTraps: [],
+    usedMedicines: []
+  };
+  const trace = [];
+  for (let index = 0; index < actions.length; index += 1) {
+    const direction = actions[index];
+    if (!direction) continue;
+    trace.push(executeStep(maze, state, direction, index + 1));
+  }
+  return {
+    state: structuredClone(state),
+    trace,
+    answers: {
+      finalPosition: letterNumberCoordinate(state.position),
+      keys: state.keys,
+      treasures: state.treasures,
+      health: state.health,
+      alive: state.alive,
+      reachedGoal: state.reachedGoal,
+      openedDoors: state.openedDoors.length,
+      openedChests: state.openedChests.length,
+      triggeredTraps: state.triggeredTraps.length,
+      usedMedicines: state.usedMedicines.length,
+      blockedMoves: trace.filter((item) => !item.moved).length,
+      blockedAfterDeath: trace.filter((item) => item.reason === "dead").length
+    }
+  };
+}
+function executeStep(maze, state, direction, step) {
+  const before = structuredClone(state);
+  const events = [];
+  if (!state.alive) return record(step, direction, before, state, false, "dead", events);
+  const [dr, dc] = DELTAS[direction];
+  const target = cell(state.position.row + dr, state.position.col + dc);
+  if (terrainAt(maze, target) !== ".") {
+    return record(step, direction, before, state, false, "wall-or-outside", events);
+  }
+  const door = maze.doors.find((item) => sameCell(item.position, target));
+  if (door && !state.openedDoors.includes(door.id)) {
+    if (state.keys <= 0) {
+      return record(
+        step,
+        direction,
+        before,
+        state,
+        false,
+        "closed-door-without-key",
+        events
+      );
+    }
+    state.keys -= 1;
+    state.openedDoors.push(door.id);
+    events.push({ type: "open-door", id: door.id, keyCost: 1 });
+  }
+  state.position = target;
+  const object = maze.objects.find((item) => sameCell(item.position, target));
+  if (object?.type === "key" && !state.collectedKeys.includes(object.id)) {
+    state.collectedKeys.push(object.id);
+    state.keys += 1;
+    events.push({ type: "collect-key", id: object.id });
+  }
+  if (object?.type === "chest" && !state.openedChests.includes(object.id)) {
+    if (state.keys > 0) {
+      state.keys -= 1;
+      state.openedChests.push(object.id);
+      state.treasures += object.treasures;
+      events.push({
+        type: "open-chest",
+        id: object.id,
+        keyCost: 1,
+        treasures: object.treasures
+      });
+    } else {
+      events.push({ type: "pass-closed-chest", id: object.id });
+    }
+  }
+  if (object?.type === "trap" && !state.triggeredTraps.includes(object.id)) {
+    state.triggeredTraps.push(object.id);
+    state.health = Math.max(0, state.health - object.damage);
+    events.push({ type: "trigger-trap", id: object.id, damage: object.damage });
+  }
+  if (object?.type === "medicine" && !state.usedMedicines.includes(object.id)) {
+    state.usedMedicines.push(object.id);
+    const prior = state.health;
+    state.health = Math.min(state.healthMax, state.health + object.recovery);
+    events.push({ type: "use-medicine", id: object.id, recovery: state.health - prior });
+  }
+  if (state.health <= 0 && state.alive) {
+    state.alive = false;
+    events.push({ type: "die" });
+  }
+  if (sameCell(state.position, maze.goal) && !state.reachedGoal) {
+    state.reachedGoal = true;
+    events.push({ type: "reach-goal" });
+  }
+  return record(step, direction, before, state, true, null, events);
+}
+function record(step, direction, before, state, moved, reason, events) {
+  return {
+    step,
+    direction,
+    before,
+    moved,
+    reason,
+    events,
+    after: structuredClone(state)
+  };
+}
+
+// src/trial.ts
+var DIRECTIONS = {
+  up: { en: "up", zh: "\u4E0A" },
+  down: { en: "down", zh: "\u4E0B" },
+  left: { en: "left", zh: "\u5DE6" },
+  right: { en: "right", zh: "\u53F3" }
+};
+var ENGLISH_RULES = [
+  "The explorer can move only one cell at a time to an orthogonally adjacent cell. An instruction to move several cells is executed as that many consecutive one-cell moves.",
+  "If the next cell is a wall or outside the map, the explorer stays in place, and the remaining actions continue.",
+  "A closed door occupies a whole cell. To enter it, the explorer must spend one key; the door then stays open. Without a key, the explorer stays in place.",
+  "The first time the explorer enters a cell containing a key, they collect it. A key cannot be collected twice.",
+  "The first time the explorer enters a cell containing an unopened chest, one key is spent to open it if a key is available. Without a key, the explorer may pass through but does not open the chest.",
+  "A trap removes one health point the first time it is entered and has no effect afterward.",
+  "A medicine room restores one health point the first time it is entered, without exceeding maximum health, and has no effect afterward.",
+  "When health reaches zero, the explorer dies. All remaining moves are still read but cannot change any state.",
+  "Once the explorer enters the goal cell, reached-goal remains true even if the explorer later leaves it."
+];
+var CHINESE_RULES = [
+  "\u63A2\u9669\u8005\u6BCF\u6B21\u53EA\u80FD\u5411\u4E0A\u3001\u4E0B\u3001\u5DE6\u3001\u53F3\u76F8\u90BB\u7684\u4E00\u683C\u79FB\u52A8\uFF1B\u201C\u5411\u67D0\u65B9\u5411\u79FB\u52A8\u82E5\u5E72\u683C\u201D\u4F9D\u6B21\u6267\u884C\u76F8\u5E94\u6B21\u6570\u7684\u5355\u683C\u79FB\u52A8\u3002",
+  "\u5982\u679C\u4E00\u6B21\u79FB\u52A8\u7684\u76EE\u6807\u662F\u5899\u683C\u6216\u8D85\u51FA\u5730\u56FE\uFF0C\u63A2\u9669\u8005\u505C\u5728\u539F\u5730\uFF0C\u4F46\u540E\u7EED\u884C\u52A8\u4ECD\u7136\u7EE7\u7EED\u3002",
+  "\u95E8\u5360\u636E\u4E00\u4E2A\u5B8C\u6574\u683C\u5B50\u3002\u76EE\u6807\u683C\u662F\u5173\u95ED\u7684\u95E8\u65F6\uFF0C\u63A2\u9669\u8005\u82E5\u6301\u6709\u94A5\u5319\uFF0C\u5C31\u6D88\u8017\u4E00\u628A\u94A5\u5319\u3001\u6253\u5F00\u8BE5\u95E8\u5E76\u8FDB\u5165\u95E8\u683C\uFF1B\u6CA1\u6709\u94A5\u5319\u5219\u505C\u5728\u539F\u5730\u3002\u5DF2\u7ECF\u6253\u5F00\u7684\u95E8\u53EF\u4EE5\u76F4\u63A5\u8FDB\u5165\u3002",
+  "\u63A2\u9669\u8005\u7B2C\u4E00\u6B21\u8FDB\u5165\u67D0\u628A\u94A5\u5319\u6240\u5728\u7684\u683C\u5B50\u65F6\u53D6\u5F97\u8BE5\u94A5\u5319\uFF0C\u94A5\u5319\u6570\u589E\u52A0\u4E00\uFF1B\u540C\u4E00\u628A\u94A5\u5319\u4E0D\u80FD\u91CD\u590D\u53D6\u5F97\u3002",
+  "\u63A2\u9669\u8005\u7B2C\u4E00\u6B21\u8FDB\u5165\u5C1A\u672A\u6253\u5F00\u7684\u5B9D\u7BB1\u683C\u4E14\u6301\u6709\u94A5\u5319\u65F6\uFF0C\u6D88\u8017\u4E00\u628A\u94A5\u5319\u3001\u6253\u5F00\u5B9D\u7BB1\u5E76\u53D6\u5F97\u5176\u4E2D\u5168\u90E8\u5B9D\u7269\uFF1B\u6CA1\u6709\u94A5\u5319\u65F6\u53EF\u4EE5\u7ECF\u8FC7\u8BE5\u683C\uFF0C\u4F46\u4E0D\u80FD\u6253\u5F00\u5B9D\u7BB1\u3002",
+  "\u63A2\u9669\u8005\u7B2C\u4E00\u6B21\u8FDB\u5165\u67D0\u4E2A\u9677\u9631\u683C\u65F6\u51CF\u5C11\u4E00\u70B9\u5065\u5EB7\u503C\uFF1B\u540C\u4E00\u9677\u9631\u4EE5\u540E\u4E0D\u518D\u751F\u6548\u3002",
+  "\u4ECD\u7136\u5B58\u6D3B\u7684\u63A2\u9669\u8005\u7B2C\u4E00\u6B21\u8FDB\u5165\u67D0\u4E2A\u836F\u54C1\u623F\u65F6\u6062\u590D\u4E00\u70B9\u5065\u5EB7\u503C\uFF0C\u4F46\u4E0D\u5F97\u8D85\u8FC7\u5065\u5EB7\u4E0A\u9650\uFF1B\u540C\u4E00\u836F\u54C1\u623F\u4EE5\u540E\u4E0D\u518D\u751F\u6548\u3002",
+  "\u5065\u5EB7\u503C\u964D\u4E3A\u96F6\u65F6\u63A2\u9669\u8005\u6B7B\u4EA1\u3002\u6B7B\u4EA1\u4EE5\u540E\uFF0C\u6240\u6709\u5C1A\u672A\u6267\u884C\u7684\u79FB\u52A8\u90FD\u4E0D\u518D\u6539\u53D8\u4EFB\u4F55\u72B6\u6001\u3002",
+  "\u63A2\u9669\u8005\u4E00\u65E6\u8FDB\u5165\u7EC8\u70B9\u683C\uFF0C\u5C31\u628A\u201C\u66FE\u7ECF\u5230\u8FBE\u7EC8\u70B9\u201D\u8BB0\u5F55\u4E3A\u771F\uFF1B\u4EE5\u540E\u5373\u4F7F\u79BB\u5F00\u7EC8\u70B9\uFF0C\u8BE5\u8BB0\u5F55\u4ECD\u7136\u4FDD\u6301\u4E3A\u771F\u3002"
+];
+var ENGLISH_QUESTIONS = [
+  "Which cell is the explorer in after all actions are complete?",
+  "How many keys does the explorer have at the end?",
+  "How many treasures has the explorer collected at the end?",
+  "How many health points does the explorer have at the end?",
+  "Is the explorer alive at the end?",
+  "Did the explorer ever reach the goal?",
+  "How many doors were opened?",
+  "How many chests were opened?",
+  "How many traps were triggered?",
+  "How many medicine rooms were used?",
+  "How many individual moves did not change the explorer's position?"
+];
+var CHINESE_QUESTIONS = [
+  "\u5168\u90E8\u884C\u52A8\u7ED3\u675F\u540E\uFF0C\u63A2\u9669\u8005\u4F4D\u4E8E\u54EA\u4E00\u683C\uFF1F",
+  "\u63A2\u9669\u8005\u6700\u540E\u6301\u6709\u51E0\u628A\u94A5\u5319\uFF1F",
+  "\u63A2\u9669\u8005\u6700\u540E\u53D6\u5F97\u4E86\u51E0\u4EF6\u5B9D\u7269\uFF1F",
+  "\u63A2\u9669\u8005\u6700\u540E\u8FD8\u5269\u51E0\u70B9\u5065\u5EB7\u503C\uFF1F",
+  "\u63A2\u9669\u8005\u6700\u540E\u662F\u5426\u4ECD\u7136\u5B58\u6D3B\uFF1F",
+  "\u884C\u52A8\u8FC7\u7A0B\u4E2D\uFF0C\u63A2\u9669\u8005\u662F\u5426\u66FE\u7ECF\u5230\u8FBE\u7EC8\u70B9\uFF1F",
+  "\u884C\u52A8\u8FC7\u7A0B\u4E2D\u4E00\u5171\u6253\u5F00\u4E86\u51E0\u9053\u95E8\uFF1F",
+  "\u884C\u52A8\u8FC7\u7A0B\u4E2D\u4E00\u5171\u6253\u5F00\u4E86\u51E0\u53EA\u5B9D\u7BB1\uFF1F",
+  "\u884C\u52A8\u8FC7\u7A0B\u4E2D\u4E00\u5171\u89E6\u53D1\u4E86\u51E0\u4E2A\u9677\u9631\uFF1F",
+  "\u884C\u52A8\u8FC7\u7A0B\u4E2D\u4E00\u5171\u4F7F\u7528\u4E86\u51E0\u4E2A\u836F\u54C1\u623F\uFF1F",
+  "\u884C\u52A8\u8FC7\u7A0B\u4E2D\u5171\u6709\u591A\u5C11\u6B21\u79FB\u52A8\u6CA1\u6709\u6539\u53D8\u63A2\u9669\u8005\u7684\u4F4D\u7F6E\uFF1F"
+];
+function generateTrial(options = {}) {
+  const resolved = resolveTrialOptions(options);
+  const maze = selectMaze(resolved);
+  const plan = buildScenarioPlan(maze, resolved.scenario);
+  const result = simulateTrial(maze, plan.actions, plan.initialState);
+  verifyScenario(resolved.scenario, result.answers, maze);
+  const sections = {
+    map: renderMapDescription(maze, plan.initialState, resolved.language, resolved.style),
+    rules: renderRules(resolved.language),
+    actions: renderActionDescription(plan.actions, resolved.language, resolved.style),
+    questions: renderQuestions(resolved.language)
+  };
+  const question = renderQuestion(resolved, maze, sections);
+  const answer = renderAnswer(resolved, maze, result.answers, plan.actions.length);
+  return {
+    schemaVersion: "maze-test-trial@1",
+    options: resolved,
+    maze,
+    initialState: plan.initialState,
+    actions: plan.actions,
+    sections,
+    question,
+    answer,
+    result
+  };
+}
+function resolveTrialOptions(options = {}) {
+  const scenario = options.scenario ?? "success";
+  const language = options.language ?? "en";
+  if (!["success", "treasure-and-leave", "death-and-stop"].includes(scenario)) {
+    throw new Error(`Unknown scenario: ${scenario}`);
+  }
+  if (language !== "en" && language !== "zh") throw new Error(`Unknown language: ${language}`);
+  const resolved = {
+    seed: integer(options.seed ?? 1, "seed", 0),
+    rows: oddInteger(options.rows ?? 15, "rows", 7),
+    cols: oddInteger(options.cols ?? 15, "cols", 7),
+    braid: finiteNumber(options.braid ?? 0, "braid", 0, 1),
+    doorCount: integer(options.doorCount ?? 1, "doorCount", 0),
+    chestCount: integer(options.chestCount ?? 2, "chestCount", 0),
+    trapCount: integer(options.trapCount ?? 2, "trapCount", 0),
+    medicineCount: integer(options.medicineCount ?? 2, "medicineCount", 0),
+    scenario,
+    language,
+    style: integer(options.style ?? 0, "style", 0),
+    minDistance: integer(options.minDistance ?? 0, "minDistance", 0),
+    maxAttempts: integer(options.maxAttempts ?? 500, "maxAttempts", 1)
+  };
+  if (scenario === "treasure-and-leave" && resolved.chestCount < 1) {
+    throw new Error("The treasure-and-leave scenario requires at least one chest.");
+  }
+  if (scenario === "treasure-and-leave" && resolved.medicineCount < 1) {
+    throw new Error("The treasure-and-leave scenario requires at least one medicine room.");
+  }
+  if (scenario === "death-and-stop" && resolved.trapCount < 1) {
+    throw new Error("The death-and-stop scenario requires at least one trap.");
+  }
+  return resolved;
+}
+function selectMaze(options) {
+  let lastError = null;
+  for (let offset = 0; offset < options.maxAttempts; offset += 1) {
+    const effectiveSeed = options.seed + offset;
+    try {
+      const base = generateSolidCellMaze({
+        rows: options.rows,
+        cols: options.cols,
+        braid: options.braid,
+        seed: effectiveSeed,
+        requestedSeed: options.seed,
+        id: `maze-test-${options.rows}x${options.cols}-${options.seed}`
+      });
+      const maze = decorateSolidCellMaze(base, {
+        seed: effectiveSeed + 8e4,
+        doorCount: options.doorCount,
+        chestCount: options.chestCount,
+        trapCount: options.trapCount,
+        medicineCount: options.medicineCount
+      });
+      const validation = validateSolidCellMaze(maze);
+      if (!validation.valid) throw new Error(validation.errors.join(" "));
+      if ((validation.metrics?.entryGoalDistance ?? 0) < options.minDistance) {
+        throw new Error(`The entry-goal distance is below ${options.minDistance}.`);
+      }
+      const plan = buildScenarioPlan(maze, options.scenario);
+      const result = simulateTrial(maze, plan.actions, plan.initialState);
+      verifyScenario(options.scenario, result.answers, maze);
+      return maze;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  const detail = lastError instanceof Error ? ` Last error: ${lastError.message}` : "";
+  throw new Error(
+    `Could not generate a valid trial in ${options.maxAttempts} deterministic attempts.${detail}`
+  );
+}
+function buildScenarioPlan(maze, scenario) {
+  if (scenario === "success") {
+    return {
+      initialState: { health: 5, healthMax: 5, keys: 0, treasures: 0 },
+      actions: pathToActions(shortestPath(maze, maze.entry, maze.goal))
+    };
+  }
+  if (scenario === "treasure-and-leave") {
+    const medicine = maze.objects.find((item) => item.type === "medicine");
+    const chest = maze.objects.find((item) => item.type === "chest");
+    if (!medicine || !chest) throw new Error("This scenario requires a medicine room and a chest.");
+    const path1 = shortestPath(maze, maze.entry, medicine.position);
+    const path2 = shortestPath(maze, medicine.position, chest.position);
+    const path3 = shortestPath(maze, chest.position, maze.goal);
+    const leavePath = [...path3].reverse().slice(0, Math.min(10, path3.length));
+    let actions = [
+      ...pathToActions(path1),
+      ...pathToActions(path2),
+      ...pathToActions(path3),
+      ...pathToActions(leavePath)
+    ];
+    const initialState = {
+      health: 3,
+      healthMax: 5,
+      keys: maze.doors.length + 2,
+      treasures: 0
+    };
+    const beforeBump = simulateTrial(maze, actions, initialState);
+    const bump = wallDirection(maze, beforeBump.state.position);
+    if (bump) actions = [...actions, bump, bump];
+    return { initialState, actions };
+  }
+  const trap = maze.objects.find((item) => item.type === "trap");
+  if (!trap) throw new Error("This scenario requires a trap.");
+  const toTrap = shortestPath(maze, maze.entry, trap.position);
+  const afterTrap = shortestPath(maze, trap.position, maze.goal).slice(0, 14);
+  return {
+    initialState: {
+      health: 1,
+      healthMax: 1,
+      keys: maze.doors.length + 1,
+      treasures: 0
+    },
+    actions: [...pathToActions(toTrap), ...pathToActions(afterTrap)]
+  };
+}
+function verifyScenario(scenario, answers, maze) {
+  if (scenario === "success" && (!answers.reachedGoal || !answers.alive || answers.finalPosition !== letterNumberCoordinate(maze.goal))) {
+    throw new Error("The success scenario did not finish alive at the goal.");
+  }
+  if (scenario === "treasure-and-leave" && (!answers.reachedGoal || answers.finalPosition === letterNumberCoordinate(maze.goal) || answers.openedChests < 1 || answers.usedMedicines < 1 || answers.blockedMoves < 2)) {
+    throw new Error("The treasure-and-leave scenario did not meet its invariants.");
+  }
+  if (scenario === "death-and-stop" && (answers.alive || answers.blockedAfterDeath < 5)) {
+    throw new Error("The death-and-stop scenario did not meet its invariants.");
+  }
+}
+function renderQuestion(options, maze, sections) {
+  const isZh = options.language === "zh";
+  const title = isZh ? "\u8FF7\u5BAB\u8BD5\u9898" : "Maze Trial";
+  const labels = isZh ? ["\u5730\u56FE\u63CF\u8FF0", "\u673A\u5236\u63CF\u8FF0", "\u884C\u52A8\u63CF\u8FF0", "\u95EE\u9898"] : ["Map", "Rules", "Actions", "Questions"];
+  const seedLine = maze.seed === options.seed ? `${isZh ? "\u79CD\u5B50" : "Seed"}: ${options.seed}` : `${isZh ? "\u79CD\u5B50" : "Seed"}: ${options.seed} (${isZh ? "\u6709\u6548\u8FF7\u5BAB\u79CD\u5B50" : "effective maze seed"}: ${maze.seed})`;
+  return [
+    `# ${title}`,
+    "",
+    seedLine,
+    "",
+    `## 1. ${labels[0]}`,
+    "",
+    sections.map,
+    "",
+    `## 2. ${labels[1]}`,
+    "",
+    sections.rules,
+    "",
+    `## 3. ${labels[2]}`,
+    "",
+    sections.actions,
+    "",
+    `## 4. ${labels[3]}`,
+    "",
+    sections.questions,
+    ""
+  ].join("\n");
+}
+function renderAnswer(options, maze, answers, actionCount) {
+  const zh = options.language === "zh";
+  const rows = zh ? [
+    ["\u6700\u7EC8\u4F4D\u7F6E", answers.finalPosition],
+    ["\u6700\u7EC8\u94A5\u5319\u6570", answers.keys],
+    ["\u6700\u7EC8\u5B9D\u7269\u6570", answers.treasures],
+    ["\u6700\u7EC8\u5065\u5EB7\u503C", answers.health],
+    ["\u662F\u5426\u5B58\u6D3B", answers.alive ? "\u662F" : "\u5426"],
+    ["\u662F\u5426\u66FE\u5230\u8FBE\u7EC8\u70B9", answers.reachedGoal ? "\u662F" : "\u5426"],
+    ["\u6253\u5F00\u7684\u95E8", answers.openedDoors],
+    ["\u6253\u5F00\u7684\u5B9D\u7BB1", answers.openedChests],
+    ["\u89E6\u53D1\u7684\u9677\u9631", answers.triggeredTraps],
+    ["\u4F7F\u7528\u7684\u836F\u54C1\u623F", answers.usedMedicines],
+    ["\u672A\u6539\u53D8\u4F4D\u7F6E\u7684\u79FB\u52A8", answers.blockedMoves]
+  ] : [
+    ["Final position", answers.finalPosition],
+    ["Keys remaining", answers.keys],
+    ["Treasures collected", answers.treasures],
+    ["Health remaining", answers.health],
+    ["Alive", answers.alive ? "Yes" : "No"],
+    ["Ever reached the goal", answers.reachedGoal ? "Yes" : "No"],
+    ["Doors opened", answers.openedDoors],
+    ["Chests opened", answers.openedChests],
+    ["Traps triggered", answers.triggeredTraps],
+    ["Medicine rooms used", answers.usedMedicines],
+    ["Moves that did not change position", answers.blockedMoves]
+  ];
+  return [
+    `# ${zh ? "\u6807\u51C6\u7B54\u6848" : "Answer Key"}`,
+    "",
+    `${zh ? "\u79CD\u5B50" : "Seed"}: ${options.seed}`,
+    ...maze.seed === options.seed ? [] : [
+      `${zh ? "\u6709\u6548\u8FF7\u5BAB\u79CD\u5B50" : "Effective maze seed"}: ${maze.seed}`
+    ],
+    "",
+    `| ${zh ? "\u95EE\u9898" : "Item"} | ${zh ? "\u7B54\u6848" : "Answer"} |`,
+    "|---|---|",
+    ...rows.map(([label, value]) => `| ${label} | ${String(value)} |`),
+    "",
+    `${zh ? "\u539F\u5B50\u884C\u52A8\u6570" : "Atomic action count"}: ${actionCount}`,
+    ""
+  ].join("\n");
+}
+function renderMapDescription(maze, initial, language, style) {
+  const terrain = renderTerrainDescription(maze, language, style);
+  const objects = renderObjectDescription(maze, language);
+  if (language === "zh") {
+    return [
+      `\u8FD9\u662F\u4E00\u5EA7${maze.rows}\u884C${maze.cols}\u5217\u7684\u8FF7\u5BAB\u3002\u5DE6\u4E0A\u89D2\u4E3AA1\uFF0C\u5217\u4ECE\u5DE6\u5411\u53F3\u4F9D\u6B21\u6807\u4E3AA\u81F3${columnLabel(maze.cols)}\uFF0C\u884C\u4ECE\u4E0A\u5411\u4E0B\u7F16\u53F7\u4E3A1\u81F3${maze.rows}\u3002`,
+      `\u5165\u53E3\u4F4D\u4E8E${letterNumberCoordinate(maze.entry)}\uFF0C\u7EC8\u70B9\u4F4D\u4E8E${letterNumberCoordinate(maze.goal)}\u3002`,
+      "",
+      terrain,
+      "",
+      "\u8FF7\u5BAB\u4E2D\u7684\u95E8\u548C\u5176\u4ED6\u5BF9\u8C61\u5206\u5E03\u5982\u4E0B\u3002\u95E8\u672C\u8EAB\u5360\u636E\u4E00\u4E2A\u5B8C\u6574\u683C\u5B50\u3002",
+      objects,
+      "",
+      `\u8FF7\u5BAB\u4E2D\u6709\u4E00\u540D\u63A2\u9669\u8005\u3002\u4ED6\u4ECE\u5165\u53E3\u51FA\u53D1\uFF0C\u521D\u59CB\u5065\u5EB7\u503C\u4E3A${numberZh(initial.health)}\u70B9\uFF0C\u5065\u5EB7\u4E0A\u9650\u4E3A${numberZh(initial.healthMax)}\u70B9\uFF1B${initialPossessions(initial, language)}\uFF0C\u5C1A\u672A\u5230\u8FBE\u7EC8\u70B9\u3002`
+    ].join("\n");
+  }
+  return [
+    `This maze has ${maze.rows} rows and ${maze.cols} columns. The top-left cell is A1. Columns run left to right from A to ${columnLabel(maze.cols)}, and rows run top to bottom from 1 to ${maze.rows}.`,
+    `The entry is at ${letterNumberCoordinate(maze.entry)}, and the goal is at ${letterNumberCoordinate(maze.goal)}.`,
+    "",
+    terrain,
+    "",
+    "Doors and other objects are distributed as follows. Each door occupies a whole cell.",
+    objects,
+    "",
+    `An explorer starts at the entry with ${initial.health} health point${plural(initial.health)}, a maximum health of ${initial.healthMax}, ${initialPossessions(initial, language)}, and reached-goal set to false.`
+  ].join("\n");
+}
+function renderTerrainDescription(maze, language, style) {
+  const clauses = Array.from({ length: maze.rows }, (_, index) => index + 1).map((row) => {
+    const kinds = Array.from(
+      { length: maze.cols },
+      (_, index) => terrainAt(maze, cell(row, index + 1)) === "." ? "floor" : "wall"
+    );
+    const label = language === "zh" ? [`\u7B2C${row}\u884C`, `${row}\u3001`, `\uFF08${row}\uFF09`][style % 3] : `Row ${row}: `;
+    return `${label ?? `\u7B2C${row}\u884C`}${describeTerrainLine(kinds, language)}`;
+  });
+  return language === "zh" ? ["\u6BCF\u884C\u5185\u90E8\u7684\u683C\u5B50\u5747\u4ECE\u5DE6\u5F80\u53F3\u8BA1\u6570\u3002\u4ECE\u4E0A\u5F80\u4E0B\uFF0C\u5404\u884C\u7684\u683C\u5B50\u60C5\u51B5\u5982\u4E0B\uFF1A", `${clauses.join("\uFF1B\n")}\u3002`].join("\n") : ["Within each row, cells are counted from left to right:", `${clauses.join(";\n")}.`].join("\n");
+}
+function describeTerrainLine(kinds, language) {
+  const walls = [];
+  const floors = [];
+  for (let index = 0; index < kinds.length; index += 1) {
+    (kinds[index] === "wall" ? walls : floors).push(index + 1);
+  }
+  if (language === "zh") {
+    if (walls.length === 0) return "\u90FD\u662F\u901A\u8DEF";
+    if (floors.length === 0) return "\u90FD\u662F\u5899\u58C1";
+    const limit2 = Math.floor(kinds.length / 3);
+    if (walls.length <= limit2) return `\u9664\u4E86${positionList(walls, language)}\u662F\u5899\u58C1\u4EE5\u5916\uFF0C\u5176\u4F59\u90FD\u662F\u901A\u8DEF`;
+    if (floors.length <= limit2) return `\u9664\u4E86${positionList(floors, language)}\u662F\u901A\u8DEF\u4EE5\u5916\uFF0C\u5176\u4F59\u90FD\u662F\u5899\u58C1`;
+    return `${positionList(walls, language)}\u662F\u5899\u58C1\uFF0C${positionList(floors, language)}\u662F\u901A\u8DEF`;
+  }
+  if (walls.length === 0) return "all cells are passages";
+  if (floors.length === 0) return "all cells are walls";
+  const limit = Math.floor(kinds.length / 3);
+  if (walls.length <= limit) return `all cells are passages except ${positionList(walls, language)}, which ${walls.length === 1 ? "is a wall" : "are walls"}`;
+  if (floors.length <= limit) return `all cells are walls except ${positionList(floors, language)}, which ${floors.length === 1 ? "is a passage" : "are passages"}`;
+  return `${positionList(walls, language)} ${walls.length === 1 ? "is a wall" : "are walls"}; ${positionList(floors, language)} ${floors.length === 1 ? "is a passage" : "are passages"}`;
+}
+function positionList(indices, language) {
+  const ranges = [];
+  let start = indices[0];
+  let end = indices[0];
+  if (start === void 0 || end === void 0) return "";
+  for (const value of indices.slice(1)) {
+    if (value === end + 1) {
+      end = value;
+      continue;
+    }
+    ranges.push([start, end]);
+    start = value;
+    end = value;
+  }
+  ranges.push([start, end]);
+  const parts = ranges.map(
+    ([from, to]) => language === "zh" ? from === to ? `\u7B2C${from}\u683C` : `\u7B2C${from}\u683C\u81F3\u7B2C${to}\u683C` : from === to ? `cell ${from}` : `cells ${from}-${to}`
+  );
+  if (parts.length === 1) return parts[0] ?? "";
+  const last = parts.at(-1);
+  return language === "zh" ? `${parts.slice(0, -1).join("\u3001")}\u548C${last}` : `${parts.slice(0, -1).join(", ")} and ${last}`;
+}
+function renderObjectDescription(maze, language) {
+  const sentences = [];
+  const doorPositions = maze.doors.map((item) => letterNumberCoordinate(item.position));
+  const keys = maze.objects.filter((item) => item.type === "key");
+  const chests = maze.objects.filter((item) => item.type === "chest");
+  const traps = maze.objects.filter((item) => item.type === "trap");
+  const medicines = maze.objects.filter((item) => item.type === "medicine");
+  if (language === "zh") {
+    if (doorPositions.length > 0) sentences.push(`${coordinateList(doorPositions, language)}${doorPositions.length > 1 ? "\u5404" : ""}\u6709\u4E00\u9053\u521D\u59CB\u5173\u95ED\u7684\u95E8\u3002`);
+    const keyPositions = keys.map((item) => letterNumberCoordinate(item.position));
+    if (keyPositions.length > 0) sentences.push(`${coordinateList(keyPositions, language)}${keyPositions.length > 1 ? "\u5404" : ""}\u653E\u7740\u4E00\u628A\u94A5\u5319\u3002`);
+    for (const chest of chests) sentences.push(`${letterNumberCoordinate(chest.position)}\u653E\u7740\u4E00\u53EA\u521D\u59CB\u5173\u95ED\u7684\u5B9D\u7BB1\uFF0C\u7BB1\u5185\u6709${numberZh(chest.treasures)}\u4EF6\u5B9D\u7269\u3002`);
+    const trapPositions = traps.map((item) => letterNumberCoordinate(item.position));
+    if (trapPositions.length > 0) sentences.push(`${coordinateList(trapPositions, language)}${trapPositions.length > 1 ? "\u5404" : ""}\u8BBE\u6709\u4E00\u4E2A\u5C1A\u672A\u89E6\u53D1\u7684\u9677\u9631\u3002`);
+    const medicinePositions = medicines.map((item) => letterNumberCoordinate(item.position));
+    if (medicinePositions.length > 0) sentences.push(`${coordinateList(medicinePositions, language)}${medicinePositions.length > 1 ? "\u5404" : ""}\u6709\u4E00\u4E2A\u5C1A\u672A\u4F7F\u7528\u7684\u836F\u54C1\u623F\u3002`);
+  } else {
+    if (doorPositions.length > 0) sentences.push(`${coordinateList(doorPositions, language)} ${doorPositions.length === 1 ? "contains a closed door" : "each contain a closed door"}.`);
+    const keyPositions = keys.map((item) => letterNumberCoordinate(item.position));
+    if (keyPositions.length > 0) sentences.push(`${coordinateList(keyPositions, language)} ${keyPositions.length === 1 ? "contains a key" : "each contain a key"}.`);
+    for (const chest of chests) sentences.push(`${letterNumberCoordinate(chest.position)} contains a closed chest with ${chest.treasures} treasure${plural(chest.treasures)}.`);
+    const trapPositions = traps.map((item) => letterNumberCoordinate(item.position));
+    if (trapPositions.length > 0) sentences.push(`${coordinateList(trapPositions, language)} ${trapPositions.length === 1 ? "contains an untriggered trap" : "each contain an untriggered trap"}.`);
+    const medicinePositions = medicines.map((item) => letterNumberCoordinate(item.position));
+    if (medicinePositions.length > 0) sentences.push(`${coordinateList(medicinePositions, language)} ${medicinePositions.length === 1 ? "contains an unused medicine room" : "each contain an unused medicine room"}.`);
+  }
+  return sentences.length > 0 ? sentences.join("\n") : language === "zh" ? "\u6CA1\u6709\u95E8\u6216\u5176\u4ED6\u5BF9\u8C61\u3002" : "There are no doors or other objects.";
+}
+function renderRules(language) {
+  return (language === "zh" ? CHINESE_RULES : ENGLISH_RULES).join("\n");
+}
+function renderQuestions(language) {
+  return (language === "zh" ? CHINESE_QUESTIONS : ENGLISH_QUESTIONS).join("\n");
+}
+function renderActionDescription(actions, language, style) {
+  const runs = compressActions(actions);
+  if (language === "zh") {
+    const connectors = ["\u968F\u540E", "\u63A5\u7740", "\u7136\u540E", "\u518D", "\u4E4B\u540E"];
+    const clauses2 = runs.map((run, index) => {
+      const connector = index === 0 ? "\u63A2\u9669\u8005\u5148" : connectors[(style + index) % connectors.length];
+      return `${connector ?? "\u7136\u540E"}\u5411${DIRECTIONS[run.direction].zh}\u79FB\u52A8${numberZh(run.count)}\u683C`;
+    });
+    return paragraphize(clauses2, "\uFF0C", "\u3002");
+  }
+  const clauses = runs.map((run, index) => {
+    const connector = index === 0 ? "First, the explorer moves" : index % 4 === 0 ? "The explorer then moves" : "then moves";
+    const directionForms = {
+      up: ["up", "upward"],
+      down: ["down", "downward"],
+      left: ["left", "to the left"],
+      right: ["right", "to the right"]
+    };
+    const forms = directionForms[run.direction];
+    const direction = forms[(style + index) % forms.length] ?? DIRECTIONS[run.direction].en;
+    return `${connector} ${direction} ${run.count} cell${plural(run.count)}`;
+  });
+  return paragraphize(clauses, ", ", ".");
+}
+function paragraphize(clauses, separator, terminator) {
+  const sentences = [];
+  for (let index = 0; index < clauses.length; index += 4) {
+    sentences.push(`${clauses.slice(index, index + 4).join(separator)}${terminator}`);
+  }
+  return sentences.join("\n");
+}
+function compressActions(actions) {
+  const runs = [];
+  for (const direction of actions) {
+    const prior = runs.at(-1);
+    if (prior?.direction === direction) prior.count += 1;
+    else runs.push({ direction, count: 1 });
+  }
+  return runs;
+}
+function pathToActions(path) {
+  const actions = [];
+  for (let index = 1; index < path.length; index += 1) {
+    const current = path[index];
+    const prior = path[index - 1];
+    if (!current || !prior) continue;
+    const dr = current.row - prior.row;
+    const dc = current.col - prior.col;
+    actions.push(dr === -1 ? "up" : dr === 1 ? "down" : dc === -1 ? "left" : "right");
+  }
+  return actions;
+}
+function wallDirection(maze, position) {
+  const candidates = [
+    ["up", cell(position.row - 1, position.col)],
+    ["down", cell(position.row + 1, position.col)],
+    ["left", cell(position.row, position.col - 1)],
+    ["right", cell(position.row, position.col + 1)]
+  ];
+  return candidates.find(([, target]) => terrainAt(maze, target) !== ".")?.[0] ?? null;
+}
+function coordinateList(values, language) {
+  if (values.length <= 1) return values[0] ?? "";
+  const last = values.at(-1);
+  return language === "zh" ? `${values.slice(0, -1).join("\u3001")}\u548C${last}` : `${values.slice(0, -1).join(", ")} and ${last}`;
+}
+function initialPossessions(state, language) {
+  if (language === "zh") {
+    const keys2 = state.keys > 0 ? `\u8D77\u521D\u6301\u6709${numberZh(state.keys)}\u628A\u94A5\u5319` : "\u8D77\u521D\u6CA1\u6709\u94A5\u5319";
+    const treasures2 = state.treasures > 0 ? `\u6301\u6709${numberZh(state.treasures)}\u4EF6\u5B9D\u7269` : "\u6CA1\u6709\u5B9D\u7269";
+    return `${keys2}\uFF0C${treasures2}`;
+  }
+  const keys = state.keys > 0 ? `${state.keys} key${plural(state.keys)}` : "no keys";
+  const treasures = state.treasures > 0 ? `${state.treasures} treasure${plural(state.treasures)}` : "no treasures";
+  return `${keys} and ${treasures}`;
+}
+function numberZh(value) {
+  const forms = ["\u96F6", "\u4E00", "\u4E24", "\u4E09", "\u56DB", "\u4E94", "\u516D", "\u4E03", "\u516B", "\u4E5D", "\u5341"];
+  return forms[value] ?? String(value);
+}
+function plural(value) {
+  return value === 1 ? "" : "s";
+}
+function integer(value, name, minimum) {
+  if (!Number.isInteger(value) || value < minimum) {
+    throw new Error(`${name} must be an integer greater than or equal to ${minimum}.`);
+  }
+  return value;
+}
+function oddInteger(value, name, minimum) {
+  integer(value, name, minimum);
+  if (value % 2 === 0) throw new Error(`${name} must be odd.`);
+  return value;
+}
+function finiteNumber(value, name, minimum, maximum) {
+  if (!Number.isFinite(value) || value < minimum || value > maximum) {
+    throw new Error(`${name} must be between ${minimum} and ${maximum}.`);
+  }
+  return value;
+}
+
+// src/cli.ts
+var VERSION = "0.2.0";
+try {
+  const parsed = parseArguments(import_node_process.default.argv.slice(2));
+  if (parsed === "help") {
+    import_node_process.default.stdout.write(helpText());
+  } else if (parsed === "version") {
+    import_node_process.default.stdout.write(`${VERSION}
+`);
+  } else {
+    const trial = generateTrial(parsed.trial);
+    if (parsed.format === "text") {
+      import_node_process.default.stdout.write(parsed.command === "question" ? trial.question : trial.answer);
+    } else if (parsed.command === "question") {
+      import_node_process.default.stdout.write(
+        `${JSON.stringify(
+          {
+            schemaVersion: trial.schemaVersion,
+            kind: "question",
+            options: trial.options,
+            maze: {
+              id: trial.maze.id,
+              requestedSeed: trial.maze.requestedSeed,
+              effectiveSeed: trial.maze.seed,
+              metrics: trial.maze.metrics
+            },
+            sections: trial.sections,
+            question: trial.question
+          },
+          null,
+          2
+        )}
+`
+      );
+    } else {
+      import_node_process.default.stdout.write(
+        `${JSON.stringify(
+          {
+            schemaVersion: trial.schemaVersion,
+            kind: "answer",
+            options: trial.options,
+            maze: {
+              id: trial.maze.id,
+              requestedSeed: trial.maze.requestedSeed,
+              effectiveSeed: trial.maze.seed
+            },
+            answers: trial.result.answers,
+            actionCount: trial.actions.length,
+            answer: trial.answer
+          },
+          null,
+          2
+        )}
+`
+      );
+    }
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  import_node_process.default.stderr.write(`maze-test: ${message}
+Run "maze-test --help" for usage.
+`);
+  import_node_process.default.exitCode = 1;
+}
+function parseArguments(args) {
+  const values = [...args];
+  let command = "question";
+  const first = values[0];
+  if (first && !first.startsWith("-")) {
+    values.shift();
+    if (first === "question" || first === "q") command = "question";
+    else if (first === "answer" || first === "a") command = "answer";
+    else throw new Error(`Unknown command: ${first}`);
+  }
+  const trial = {};
+  let format = "text";
+  for (let index = 0; index < values.length; index += 1) {
+    const raw = values[index];
+    if (!raw) continue;
+    const equalIndex = raw.indexOf("=");
+    const flag = equalIndex >= 0 ? raw.slice(0, equalIndex) : raw;
+    const inline = equalIndex >= 0 ? raw.slice(equalIndex + 1) : void 0;
+    if (flag === "--help" || flag === "-h") return "help";
+    if (flag === "--version" || flag === "-v") return "version";
+    if (flag === "--json") {
+      format = "json";
+      continue;
+    }
+    const value = inline ?? values[++index];
+    if (value === void 0) throw new Error(`Missing value for ${flag}.`);
+    switch (flag) {
+      case "--seed":
+        trial.seed = parseInteger(value, flag);
+        break;
+      case "--rows":
+        trial.rows = parseInteger(value, flag);
+        break;
+      case "--cols":
+        trial.cols = parseInteger(value, flag);
+        break;
+      case "--braid":
+        trial.braid = parseNumber(value, flag);
+        break;
+      case "--doors":
+        trial.doorCount = parseInteger(value, flag);
+        break;
+      case "--chests":
+        trial.chestCount = parseInteger(value, flag);
+        break;
+      case "--traps":
+        trial.trapCount = parseInteger(value, flag);
+        break;
+      case "--medicines":
+        trial.medicineCount = parseInteger(value, flag);
+        break;
+      case "--scenario":
+        trial.scenario = value;
+        break;
+      case "--lang":
+      case "--language":
+        trial.language = value;
+        break;
+      case "--style":
+        trial.style = parseInteger(value, flag);
+        break;
+      case "--min-distance":
+        trial.minDistance = parseInteger(value, flag);
+        break;
+      case "--max-attempts":
+        trial.maxAttempts = parseInteger(value, flag);
+        break;
+      case "--format":
+        if (value !== "text" && value !== "json") throw new Error(`Invalid format: ${value}`);
+        format = value;
+        break;
+      default:
+        throw new Error(`Unknown option: ${flag}`);
+    }
+  }
+  return { command, format, trial };
+}
+function parseInteger(value, flag) {
+  if (!/^-?\d+$/u.test(value)) throw new Error(`${flag} requires an integer.`);
+  return Number(value);
+}
+function parseNumber(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new Error(`${flag} requires a number.`);
+  return parsed;
+}
+function helpText() {
+  return `maze-test ${VERSION}
+
+Generate a deterministic maze question or its answer key.
+
+Usage:
+  maze-test [question] [options]
+  maze-test answer [options]
+
+Commands:
+  question, q              Generate the question (default)
+  answer, a                Generate the matching answer key
+
+Options:
+  --seed <integer>         Root seed (default: 1)
+  --rows <odd integer>     Number of rows (default: 15)
+  --cols <odd integer>     Number of columns (default: 15)
+  --braid <0..1>           Chance to remove a dead end (default: 0)
+  --doors <integer>        Number of doors and keys (default: 1)
+  --chests <integer>       Number of chests (default: 2)
+  --traps <integer>        Number of traps (default: 2)
+  --medicines <integer>    Number of medicine rooms (default: 2)
+  --scenario <name>        success | treasure-and-leave | death-and-stop
+                           (default: success)
+  --lang <language>        en | zh (default: en)
+  --style <integer>        Deterministic wording variation (default: 0)
+  --min-distance <integer> Minimum entry-to-goal distance (default: 0)
+  --max-attempts <integer> Deterministic search limit (default: 500)
+  --format <format>        text | json (default: text)
+  --json                   Alias for --format json
+  -h, --help               Show help
+  -v, --version            Show version
+
+Examples:
+  npx maze-test question --seed 42 --rows 15 --cols 15
+  npx maze-test answer --seed 42 --rows 15 --cols 15
+  npx maze-test question --seed 42 --lang zh
+  npx maze-test answer --seed 42 --format json
+`;
+}
+//# sourceMappingURL=cli.cjs.map