@quest-editor/ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pipobizelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @quest-editor/ai
+
+Monster movement AI for HeroQuest — per-type behavior + pathfinding. **Pure and
+engine-agnostic**: no React, no DB, no rendering, no `Math.random`. It talks only to a small
+`BoardQuery` port that each consumer implements, and takes an injected seeded RNG, so the same
+code drives the **tracker** (suggested moves) and the future **online** game (authoritative,
+replayable). Design: `../../docs/monster-ai.md`.
+
+## Status
+
+- ✅ **Pathfinding** (milestone 1): `distanceField`, `stepToward`, `aStar`, `reachableFrom`.
+- ✅ **Behavior** (milestone 2): `decideMonsterTurn` — per-type policies (Mind = AI tier),
+  target selection, approach, attack, and flee.
+- ⬜ Coordination (allies focus-fire), ranged/spell intents — later.
+
+## The port
+
+Implement `BoardQuery` over your board state (the tracker maps it from a live session's
+`board_state` + revealed fog; the online game from its authoritative state):
+
+```ts
+interface BoardQuery {
+  readonly width: number
+  readonly height: number
+  passable(t: Tile): boolean            // enterable terrain (not void/rock)
+  occupant(t: Tile): 'hero' | 'monster' | null
+  blockedEdge(a: Tile, b: Tile): boolean // wall or closed/unrevealed door between adjacent tiles
+  lineOfSight(a: Tile, b: Tile): boolean // ranged/visibility (unused by pathfinding)
+}
+```
+
+## Pathfinding
+
+```ts
+import { distanceField, stepToward, makeRng } from '@quest-editor/ai'
+
+const rng = makeRng(seed)
+// One multi-source pass from the heroes → cost-to-nearest-hero for every tile:
+const field = distanceField(board, heroes /* Tile[] */)
+// Each monster descends the field within its movement budget (no per-agent search):
+const path = stepToward(board, field, monster.pos, MONSTER_STATS[subtype].movement, rng)
+```
+
+- **Why a distance field, not per-monster A\*:** the grid is tiny (~500 tiles) and many
+  monsters share one goal set (the heroes). Computing the field once and letting every monster
+  read it is `O(tiles)` + `O(budget)` per monster — strictly cheaper than N separate searches,
+  and it yields nearest-hero + direction + reachability for free.
+- **Opportunity Attack:** a monster may path **through** a hero's square (never end on it).
+  Passing costs `DEFAULT_HERO_PASS_COST` extra, so routes detour around heroes when cheap but
+  flood through when that's the only way in — the chokepoint fix from `heroquest-rules`.
+- **Determinism:** stable neighbor order + index tie-breaks; the injected RNG only breaks ties
+  between equally-good steps. Same inputs + seed ⇒ identical paths.
+- Recompute the field each Zargon turn (state changes); it's cheap.
+
+`aStar(board, from, to)` is a fallback for "path to this exact empty tile" when a behavior
+picks a specific destination.
+
+## Behavior
+
+```ts
+import { decideMonsterTurn } from '@quest-editor/ai'
+
+// Per Zargon turn, for each living monster (recompute as the board changes):
+const decisions = decideMonsterTurn({
+  self: { id, pos, subtype: 'goblin', body },     // body = current
+  heroes: [{ id, pos, subtype, body, threat }],   // threat = danger score (e.g. attack dice)
+  board,
+  rng,
+  // stats?: { movement, mind, body }  ← pass core's MONSTER_STATS to be authoritative
+})
+// → [{ kind:'move', path, to }, { kind:'attack', targetId, from }] | [{ kind:'wait' }]
+```
+
+- **Mind = AI tier:** 0 mindless (skeleton/zombie/mummy → nearest hero), 1-2 instinct
+  (orc aggressive; **goblin = opportunistic coward**), 3-4 tactical (fimir/chaos/gargoyle →
+  highest-threat target, **retreat when wounded/surrounded**).
+- **Stats** come from a built-in table mirroring `@quest-editor/core` (so the package is
+  dependency-free); pass `stats` to override with the canonical values.
+- Decisions are serializable intents — the app resolves combat and applies movement. The
+  tracker renders them as *suggestions*; the online server applies them authoritatively.
+

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+/** A board square (grid coordinate). */
+interface Tile {
+    x: number;
+    y: number;
+}
+/** Who occupies a square — affects movement (monsters block; heroes are pass-through). */
+type Faction = 'hero' | 'monster';
+/**
+ * The board PORT. The AI talks only to this — never to a concrete board model.
+ * Each consumer (tracker, online) implements an adapter over its own state.
+ *
+ * HeroQuest grid semantics: orthogonal movement; walls/doors live on the EDGE
+ * between two squares (hence `blockedEdge`, not per-tile walls).
+ */
+interface BoardQuery {
+    readonly width: number;
+    readonly height: number;
+    /** Is this square part of the playable dungeon and enterable terrain (not void/rock)? */
+    passable(t: Tile): boolean;
+    /** Current occupant of the square, or null if empty. */
+    occupant(t: Tile): Faction | null;
+    /**
+     * Is movement across the edge between ADJACENT tiles `a`→`b` blocked?
+     * Covers walls and closed/unrevealed doors (fog). Must be symmetric.
+     */
+    blockedEdge(a: Tile, b: Tile): boolean;
+    /** Unobstructed straight line (for ranged attacks / visibility). Unused by pathfinding. */
+    lineOfSight(a: Tile, b: Tile): boolean;
+}
+/** Deterministic RNG: returns a float in [0, 1). Injected so the AI is reproducible. */
+type RNG = () => number;
+
+/**
+ * Seeded deterministic RNG (mulberry32). Same seed → same stream, on any machine.
+ * Used instead of `Math.random()` so monster decisions are reproducible (server/client
+ * agreement, replays, snapshot tests).
+ */
+declare function makeRng(seed: number): RNG;
+
+/**
+ * Pathfinding over the BoardQuery port. Tuned for the actual shape of the problem:
+ * a tiny grid (~500 tiles) with many agents sharing one goal set (the heroes).
+ *
+ * Primary primitive = a **distance field** (Dijkstra map): one multi-source pass from
+ * the heroes' attack-adjacent tiles yields cost-to-nearest-hero for every tile. Every
+ * monster then gradient-descends that field within its movement budget — no per-agent
+ * search. `aStar` is a fallback for one-off "path to this exact tile" queries.
+ *
+ * Opportunity Attack (heroquest-rules/homebrew/opportunity-attack.md): a monster may move
+ * THROUGH a hero's square (never end on it). Passing costs `heroPassCost` extra, so the
+ * field detours around heroes when cheap but floods through when that's the only way in.
+ */
+
+/** Sentinel for "unreachable" in a distance field. */
+declare const UNREACHABLE = 2147483647;
+/**
+ * Extra cost to path THROUGH a hero's square (the AoO risk). A monster will detour up to
+ * this many tiles to avoid it before passing through. Tunable behavior knob.
+ */
+declare const DEFAULT_HERO_PASS_COST = 8;
+/**
+ * Multi-source Dijkstra map: distance (in movement cost) from every tile to the nearest
+ * valid attack position next to any `goal` (hero). Returns a flat `Int32Array` indexed by
+ * `y * width + x`; unreachable tiles hold `UNREACHABLE`.
+ *
+ * `goals` is the goal set — pass all heroes to chase the nearest, or one hero to focus-fire.
+ */
+declare function distanceField(board: BoardQuery, goals: Tile[], opts?: {
+    heroPassCost?: number;
+}): Int32Array;
+/**
+ * Greedily descend a distance field from `from`, up to `budget` steps, returning the path
+ * (excluding `from`). The path may pass THROUGH hero squares but never ENDS on one (trailing
+ * pass-through tiles are trimmed). Stops on reaching an attack-adjacent tile (field 0).
+ *
+ * Contract: call only when the monster is not already in attack range — deciding that is the
+ * behavior layer's job. `rng` breaks ties between equally-good steps (varied yet reproducible).
+ */
+declare function stepToward(board: BoardQuery, field: Int32Array, from: Tile, budget: number, rng: RNG): Tile[];
+/**
+ * A* shortest path from `from` to an exact free tile `to` (orthogonal, uniform cost).
+ * Treats every occupied tile as blocked (this is the "go to a specific empty tile" helper;
+ * hero pass-through is the distance field's job). Returns the path excluding `from`, `[]`
+ * if already there, or `null` if `to` is invalid/occupied/unreachable.
+ */
+declare function aStar(board: BoardQuery, from: Tile, to: Tile): Tile[] | null;
+/**
+ * Unweighted BFS of every tile reachable from `from` within `budget` steps.
+ * Returns `dist` (steps to each tile, `UNREACHABLE` if not reached) and `came`
+ * (predecessor index for path reconstruction). Monster tiles always block; hero
+ * tiles block unless `throughHeroes` is set (movement may pass through, fleeing
+ * may not — passing a hero would provoke the Opportunity Attack).
+ */
+declare function reachableFrom(board: BoardQuery, from: Tile, budget: number, opts?: {
+    throughHeroes?: boolean;
+}): {
+    dist: Int32Array;
+    came: Int32Array;
+};
+
+interface Combatant {
+    id: string;
+    pos: Tile;
+    /** Monster: a MONSTER_STATS subtype. Hero: its class (unused by the AI). */
+    subtype: string;
+    /** Current Body (alive if > 0). */
+    body: number;
+    /** Hero danger score (e.g. attack dice) — drives tactical targeting & goblin caution. */
+    threat?: number;
+}
+/** The acting monster's stats the AI needs (mirrors @quest-editor/core MONSTER_STATS). */
+interface MonsterStats {
+    /** Squares it may move this turn (monsters use a fixed value; heroes roll). */
+    movement: number;
+    /** Intelligence → AI tier (0 mindless · 1-2 instinct · 3-4 tactical). */
+    mind: number;
+    /** Max Body — used to gauge "wounded" for the flee decision. */
+    body: number;
+}
+interface MonsterTurnInput {
+    self: Combatant;
+    heroes: Combatant[];
+    /** Other living monsters (reserved for coordination; unused in v0 beyond presence). */
+    allies?: Combatant[];
+    board: BoardQuery;
+    rng: RNG;
+    /** Authoritative stats for `self`; if omitted, the built-in table is used by subtype. */
+    stats?: MonsterStats;
+    /** Override the Opportunity-Attack pass-through cost used while pathing. */
+    heroPassCost?: number;
+}
+type Decision = {
+    kind: 'move';
+    path: Tile[];
+    to: Tile;
+} | {
+    kind: 'attack';
+    targetId: string;
+    from: Tile;
+} | {
+    kind: 'wait';
+};
+/** A hero with threat ≥ this is "tough" — a lone goblin won't engage it. */
+declare const GOBLIN_TOUGH_THREAT = 3;
+/** Adjacent heroes ≥ this = "surrounded" — a tactical monster retreats. */
+declare const SURROUNDED = 3;
+/** 0 = mindless · 1 = instinct · 2 = tactical. */
+declare function monsterTier(mind: number): 0 | 1 | 2;
+/** Heroes orthogonally adjacent to `pos` with an open edge (attackable right now). */
+declare function adjacentAttackableHeroes(board: BoardQuery, pos: Tile, heroes: Combatant[]): Combatant[];
+/**
+ * Decide one monster's turn: a list of intents (`move` then maybe `attack`, or `wait`).
+ * Deterministic for a given seed. Call once per monster per Zargon turn (recompute as the
+ * board changes between monsters).
+ */
+declare function decideMonsterTurn(input: MonsterTurnInput): Decision[];
+
+export { type BoardQuery, type Combatant, DEFAULT_HERO_PASS_COST, type Decision, type Faction, GOBLIN_TOUGH_THREAT, type MonsterStats, type MonsterTurnInput, type RNG, SURROUNDED, type Tile, UNREACHABLE, aStar, adjacentAttackableHeroes, decideMonsterTurn, distanceField, makeRng, monsterTier, reachableFrom, stepToward };

package/dist/index.js

@@ -0,0 +1,381 @@
+// src/rng.ts
+function makeRng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 | 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/pathfinding.ts
+var UNREACHABLE = 2147483647;
+var DEFAULT_HERO_PASS_COST = 8;
+var DIRS = [
+  [0, -1],
+  [-1, 0],
+  [1, 0],
+  [0, 1]
+];
+var inBounds = (b, x, y) => x >= 0 && y >= 0 && x < b.width && y < b.height;
+var enterCost = (b, t, heroPassCost) => b.occupant(t) === "hero" ? 1 + heroPassCost : 1;
+var MinHeap = class {
+  dist = [];
+  node = [];
+  get size() {
+    return this.node.length;
+  }
+  push(d, n) {
+    this.dist.push(d);
+    this.node.push(n);
+    let c = this.node.length - 1;
+    while (c > 0) {
+      const p = c - 1 >> 1;
+      if (this.less(c, p)) {
+        this.swap(c, p);
+        c = p;
+      } else break;
+    }
+  }
+  pop() {
+    const top = this.node[0];
+    const d = this.dist.pop();
+    const n = this.node.pop();
+    if (this.node.length) {
+      this.dist[0] = d;
+      this.node[0] = n;
+      let p = 0;
+      for (; ; ) {
+        const l = 2 * p + 1;
+        const r = 2 * p + 2;
+        let s = p;
+        if (l < this.node.length && this.less(l, s)) s = l;
+        if (r < this.node.length && this.less(r, s)) s = r;
+        if (s === p) break;
+        this.swap(s, p);
+        p = s;
+      }
+    }
+    return top;
+  }
+  less(a, b) {
+    return this.dist[a] < this.dist[b] || this.dist[a] === this.dist[b] && this.node[a] < this.node[b];
+  }
+  swap(a, b) {
+    const d = this.dist[a];
+    this.dist[a] = this.dist[b];
+    this.dist[b] = d;
+    const n = this.node[a];
+    this.node[a] = this.node[b];
+    this.node[b] = n;
+  }
+};
+function distanceField(board, goals, opts = {}) {
+  const heroPassCost = opts.heroPassCost ?? DEFAULT_HERO_PASS_COST;
+  const W = board.width;
+  const dist = new Int32Array(W * board.height).fill(UNREACHABLE);
+  const heap = new MinHeap();
+  for (const g of goals) {
+    for (const [dx, dy] of DIRS) {
+      const nx = g.x + dx;
+      const ny = g.y + dy;
+      if (!inBounds(board, nx, ny)) continue;
+      const n = { x: nx, y: ny };
+      if (!board.passable(n) || board.occupant(n) !== null) continue;
+      if (board.blockedEdge(n, g)) continue;
+      const id = ny * W + nx;
+      if (dist[id] !== 0) {
+        dist[id] = 0;
+        heap.push(0, id);
+      }
+    }
+  }
+  while (heap.size) {
+    const cur = heap.pop();
+    const cx = cur % W;
+    const cy = cur / W | 0;
+    const curT = { x: cx, y: cy };
+    const base = dist[cur];
+    for (const [dx, dy] of DIRS) {
+      const mx = cx + dx;
+      const my = cy + dy;
+      if (!inBounds(board, mx, my)) continue;
+      const m = { x: mx, y: my };
+      if (!board.passable(m) || board.occupant(m) === "monster") continue;
+      if (board.blockedEdge(m, curT)) continue;
+      const cost = base + enterCost(board, curT, heroPassCost);
+      const mid = my * W + mx;
+      if (cost < dist[mid]) {
+        dist[mid] = cost;
+        heap.push(cost, mid);
+      }
+    }
+  }
+  return dist;
+}
+function stepToward(board, field, from, budget, rng) {
+  const W = board.width;
+  const path = [];
+  let cur = from;
+  let curVal = field[from.y * W + from.x];
+  for (let step = 0; step < budget; step++) {
+    let best = UNREACHABLE;
+    let cands = [];
+    for (const [dx, dy] of DIRS) {
+      const nx = cur.x + dx;
+      const ny = cur.y + dy;
+      if (!inBounds(board, nx, ny)) continue;
+      const n = { x: nx, y: ny };
+      if (!board.passable(n) || board.occupant(n) === "monster") continue;
+      if (board.blockedEdge(cur, n)) continue;
+      const v = field[ny * W + nx];
+      if (v >= UNREACHABLE) continue;
+      if (v < best) {
+        best = v;
+        cands = [n];
+      } else if (v === best) {
+        cands.push(n);
+      }
+    }
+    if (cands.length === 0) break;
+    if (curVal < UNREACHABLE && best >= curVal) break;
+    const next = cands.length === 1 ? cands[0] : cands[Math.floor(rng() * cands.length)];
+    path.push(next);
+    cur = next;
+    curVal = best;
+    if (best === 0) break;
+  }
+  while (path.length && board.occupant(path[path.length - 1]) !== null) path.pop();
+  return path;
+}
+function aStar(board, from, to) {
+  if (from.x === to.x && from.y === to.y) return [];
+  if (!inBounds(board, to.x, to.y) || !board.passable(to) || board.occupant(to) !== null) return null;
+  const W = board.width;
+  const N = W * board.height;
+  const start = from.y * W + from.x;
+  const goal = to.y * W + to.x;
+  const g = new Int32Array(N).fill(UNREACHABLE);
+  const came = new Int32Array(N).fill(-1);
+  const h = (x, y) => Math.abs(x - to.x) + Math.abs(y - to.y);
+  const heap = new MinHeap();
+  g[start] = 0;
+  heap.push(h(from.x, from.y), start);
+  while (heap.size) {
+    const cur = heap.pop();
+    if (cur === goal) break;
+    const cx = cur % W;
+    const cy = cur / W | 0;
+    const curT = { x: cx, y: cy };
+    for (const [dx, dy] of DIRS) {
+      const nx = cx + dx;
+      const ny = cy + dy;
+      if (!inBounds(board, nx, ny)) continue;
+      const n = { x: nx, y: ny };
+      if (!board.passable(n) || board.occupant(n) !== null || board.blockedEdge(curT, n)) continue;
+      const nid = ny * W + nx;
+      const ng = g[cur] + 1;
+      if (ng < g[nid]) {
+        g[nid] = ng;
+        came[nid] = cur;
+        heap.push(ng + h(nx, ny), nid);
+      }
+    }
+  }
+  if (g[goal] >= UNREACHABLE) return null;
+  const path = [];
+  let c = goal;
+  while (c !== start) {
+    path.push({ x: c % W, y: c / W | 0 });
+    c = came[c];
+    if (c === -1) return null;
+  }
+  path.reverse();
+  return path;
+}
+function reachableFrom(board, from, budget, opts = {}) {
+  const through = opts.throughHeroes ?? false;
+  const W = board.width;
+  const N = W * board.height;
+  const dist = new Int32Array(N).fill(UNREACHABLE);
+  const came = new Int32Array(N).fill(-1);
+  const startId = from.y * W + from.x;
+  dist[startId] = 0;
+  let frontier = [startId];
+  for (let steps = 0; steps < budget && frontier.length; steps++) {
+    const next = [];
+    for (const cur of frontier) {
+      const cx = cur % W;
+      const cy = cur / W | 0;
+      const curT = { x: cx, y: cy };
+      for (const [dx, dy] of DIRS) {
+        const nx = cx + dx;
+        const ny = cy + dy;
+        if (!inBounds(board, nx, ny)) continue;
+        const n = { x: nx, y: ny };
+        if (!board.passable(n) || board.blockedEdge(curT, n)) continue;
+        const occ = board.occupant(n);
+        if (occ === "monster" || occ === "hero" && !through) continue;
+        const nid = ny * W + nx;
+        if (dist[nid] !== UNREACHABLE) continue;
+        dist[nid] = steps + 1;
+        came[nid] = cur;
+        next.push(nid);
+      }
+    }
+    frontier = next;
+  }
+  return { dist, came };
+}
+
+// src/behavior.ts
+var GOBLIN_TOUGH_THREAT = 3;
+var SURROUNDED = 3;
+var BASE_STATS = {
+  goblin: { movement: 10, mind: 1, body: 1 },
+  orc: { movement: 8, mind: 2, body: 1 },
+  fimir: { movement: 6, mind: 3, body: 2 },
+  skeleton: { movement: 6, mind: 0, body: 1 },
+  zombie: { movement: 5, mind: 0, body: 1 },
+  mummy: { movement: 4, mind: 0, body: 2 },
+  chaos: { movement: 7, mind: 3, body: 3 },
+  gargoyle: { movement: 6, mind: 4, body: 3 }
+};
+var DEFAULT_STATS = { movement: 6, mind: 0, body: 1 };
+var statOf = (subtype) => BASE_STATS[subtype] ?? DEFAULT_STATS;
+function monsterTier(mind) {
+  return mind === 0 ? 0 : mind <= 2 ? 1 : 2;
+}
+var adjacentTiles = (a, b) => Math.abs(a.x - b.x) + Math.abs(a.y - b.y) === 1;
+var canAttack = (board, from, hero) => adjacentTiles(from, hero.pos) && !board.blockedEdge(from, hero.pos);
+function adjacentAttackableHeroes(board, pos, heroes) {
+  return heroes.filter((h) => canAttack(board, pos, h));
+}
+var isTough = (h) => (h.threat ?? 0) >= GOBLIN_TOUGH_THREAT;
+var weakest = (list) => list.reduce((b, h) => h.body < b.body || h.body === b.body && h.id < b.id ? h : b);
+var strongest = (list) => list.reduce((b, h) => {
+  const t = h.threat ?? 0;
+  const bt = b.threat ?? 0;
+  return t > bt || t === bt && h.id < b.id ? h : b;
+});
+function approachInfo(board, hero, self, budget, heroPassCost) {
+  const field = distanceField(board, [hero.pos], { heroPassCost });
+  if (canAttack(board, self.pos, hero)) return { hero, field, dist: 0, reachable: true };
+  const W = board.width;
+  let best = UNREACHABLE;
+  for (const [dx, dy] of [
+    [0, -1],
+    [-1, 0],
+    [1, 0],
+    [0, 1]
+  ]) {
+    const nx = self.pos.x + dx;
+    const ny = self.pos.y + dy;
+    if (nx < 0 || ny < 0 || nx >= board.width || ny >= board.height) continue;
+    const n = { x: nx, y: ny };
+    if (!board.passable(n) || board.occupant(n) === "monster" || board.blockedEdge(self.pos, n)) continue;
+    const v = field[ny * W + nx];
+    if (v < best) best = v;
+  }
+  const dist = best >= UNREACHABLE ? UNREACHABLE : best + 1;
+  return { hero, field, dist, reachable: dist <= budget };
+}
+function chooseApproachTarget(tier, subtype, infos) {
+  const pathable = infos.filter((i) => i.dist < UNREACHABLE);
+  if (!pathable.length) return null;
+  const reachable = pathable.filter((i) => i.reachable);
+  const pool = reachable.length ? reachable : pathable;
+  const byClosest = (a, b) => a.dist - b.dist || (a.hero.id < b.hero.id ? -1 : 1);
+  const byWounded = (a, b) => a.hero.body - b.hero.body || byClosest(a, b);
+  if (subtype === "goblin") {
+    const soft = pool.filter((i) => !isTough(i.hero));
+    return [...soft.length ? soft : pool].sort(byWounded)[0];
+  }
+  if (tier === 0) return [...pool].sort(byClosest)[0];
+  if (tier === 1) return [...pool].sort(byWounded)[0];
+  return [...pool].sort(
+    (a, b) => (b.hero.threat ?? 0) - (a.hero.threat ?? 0) || byClosest(a, b)
+  )[0];
+}
+var isDisadvantaged = (self, pressure) => self.body <= 1 || pressure >= SURROUNDED;
+function flee(board, danger, self, budget) {
+  const { dist, came } = reachableFrom(board, self.pos, budget, { throughHeroes: false });
+  const W = board.width;
+  let bestId = -1;
+  let bestSafety = -1;
+  let bestSteps = Infinity;
+  for (let id = 0; id < dist.length; id++) {
+    if (dist[id] === UNREACHABLE || dist[id] === 0) continue;
+    const x = id % W;
+    const y = id / W | 0;
+    if (board.occupant({ x, y }) !== null) continue;
+    const d = danger[id];
+    const safety = d >= UNREACHABLE ? UNREACHABLE - 1 : d;
+    if (safety > bestSafety || safety === bestSafety && dist[id] < bestSteps) {
+      bestSafety = safety;
+      bestSteps = dist[id];
+      bestId = id;
+    }
+  }
+  if (bestId < 0) return [];
+  const path = [];
+  const startId = self.pos.y * W + self.pos.x;
+  for (let c = bestId; c !== startId && c !== -1; c = came[c]) path.push({ x: c % W, y: c / W | 0 });
+  path.reverse();
+  return path;
+}
+function decideMonsterTurn(input) {
+  const { self, board, rng, heroPassCost } = input;
+  const heroes = input.heroes.filter((h) => h.body > 0);
+  if (!heroes.length) return [{ kind: "wait" }];
+  const stats = input.stats ?? statOf(self.subtype);
+  const budget = stats.movement;
+  const tier = monsterTier(stats.mind);
+  const subtype = self.subtype;
+  const adj = adjacentAttackableHeroes(board, self.pos, heroes);
+  const pressure = adj.length;
+  const fleeDecision = () => {
+    const danger = distanceField(board, heroes.map((h) => h.pos), { heroPassCost });
+    const path2 = flee(board, danger, self, budget);
+    if (path2.length) return [{ kind: "move", path: path2, to: path2[path2.length - 1] }];
+    if (adj.length) return [{ kind: "attack", targetId: weakest(adj).id, from: self.pos }];
+    return [{ kind: "wait" }];
+  };
+  if (adj.length) {
+    if (subtype === "goblin") {
+      const soft = adj.filter((h) => !isTough(h));
+      if (soft.length) return [{ kind: "attack", targetId: weakest(soft).id, from: self.pos }];
+      return fleeDecision();
+    }
+    if (tier === 2 && isDisadvantaged(self, pressure)) return fleeDecision();
+    const target = tier === 2 ? strongest(adj) : weakest(adj);
+    return [{ kind: "attack", targetId: target.id, from: self.pos }];
+  }
+  if (tier === 2 && isDisadvantaged(self, pressure)) return fleeDecision();
+  const infos = heroes.map((h) => approachInfo(board, h, self, budget, heroPassCost));
+  const chosen = chooseApproachTarget(tier, subtype, infos);
+  if (!chosen) return [{ kind: "wait" }];
+  const path = stepToward(board, chosen.field, self.pos, budget, rng);
+  const endPos = path.length ? path[path.length - 1] : self.pos;
+  const decisions = [];
+  if (path.length) decisions.push({ kind: "move", path, to: endPos });
+  if (canAttack(board, endPos, chosen.hero))
+    decisions.push({ kind: "attack", targetId: chosen.hero.id, from: endPos });
+  if (!decisions.length) decisions.push({ kind: "wait" });
+  return decisions;
+}
+export {
+  DEFAULT_HERO_PASS_COST,
+  GOBLIN_TOUGH_THREAT,
+  SURROUNDED,
+  UNREACHABLE,
+  aStar,
+  adjacentAttackableHeroes,
+  decideMonsterTurn,
+  distanceField,
+  makeRng,
+  monsterTier,
+  reachableFrom,
+  stepToward
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@quest-editor/ai",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --tsconfig tsconfig.build.json",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
+  }
+}