@arcane-engine/runtime 0.1.0

package/src/agent/protocol.ts

@@ -0,0 +1,125 @@
+import type {
+  AgentConfig,
+  AgentProtocol,
+  ActionInfo,
+  ActionResult,
+  SimulateResult,
+  SnapshotData,
+  DescribeOptions,
+} from "./types.ts";
+import { defaultDescribe } from "./describe.ts";
+import { get } from "../state/query.ts";
+
+declare const globalThis: { __arcaneAgent?: AgentProtocol<unknown> };
+
+/** Deep clone a value via JSON round-trip */
+function deepClone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/** Register an agent protocol, installing it on globalThis.__arcaneAgent */
+export function registerAgent<S>(config: AgentConfig<S>): AgentProtocol<S> {
+  const getState = "store" in config
+    ? () => config.store.getState() as S
+    : config.getState;
+
+  const setState = "store" in config
+    ? (s: S) => config.store.replaceState(s)
+    : config.setState;
+
+  // Capture initial state for rewind
+  const initialSnapshot: SnapshotData<S> = {
+    state: deepClone(getState()),
+    timestamp: Date.now(),
+  };
+
+  const actions = config.actions ?? {};
+  const describeFn = config.describe ?? defaultDescribe;
+
+  const protocol: AgentProtocol<S> = {
+    name: config.name,
+
+    getState(): S {
+      return getState();
+    },
+
+    inspect(path: string): unknown {
+      return get(getState(), path);
+    },
+
+    describe(options?: DescribeOptions): string {
+      return describeFn(getState(), options ?? {});
+    },
+
+    listActions(): readonly ActionInfo[] {
+      return Object.entries(actions).map(([name, action]) => ({
+        name,
+        description: action.description,
+        ...(action.args ? { args: action.args } : {}),
+      }));
+    },
+
+    executeAction(name: string, argsJson?: string): ActionResult<S> {
+      const action = actions[name];
+      if (!action) {
+        return { ok: false, state: getState(), error: `Unknown action: ${name}` };
+      }
+
+      let args: Record<string, unknown> = {};
+      if (argsJson) {
+        try {
+          args = JSON.parse(argsJson);
+        } catch (e) {
+          return { ok: false, state: getState(), error: `Invalid JSON args: ${(e as Error).message}` };
+        }
+      }
+
+      try {
+        const newState = action.handler(getState(), args);
+        setState(newState);
+        return { ok: true, state: newState };
+      } catch (e) {
+        return { ok: false, state: getState(), error: `Action failed: ${(e as Error).message}` };
+      }
+    },
+
+    simulate(name: string, argsJson?: string): SimulateResult<S> {
+      const action = actions[name];
+      if (!action) {
+        return { ok: false, state: getState(), error: `Unknown action: ${name}` };
+      }
+
+      let args: Record<string, unknown> = {};
+      if (argsJson) {
+        try {
+          args = JSON.parse(argsJson);
+        } catch (e) {
+          return { ok: false, state: getState(), error: `Invalid JSON args: ${(e as Error).message}` };
+        }
+      }
+
+      try {
+        const cloned = deepClone(getState());
+        const newState = action.handler(cloned, args);
+        return { ok: true, state: newState };
+      } catch (e) {
+        return { ok: false, state: getState(), error: `Simulation failed: ${(e as Error).message}` };
+      }
+    },
+
+    rewind(): S {
+      setState(deepClone(initialSnapshot.state));
+      return deepClone(initialSnapshot.state);
+    },
+
+    captureSnapshot(): SnapshotData<S> {
+      return {
+        state: deepClone(getState()),
+        timestamp: Date.now(),
+      };
+    },
+  };
+
+  (globalThis as any).__arcaneAgent = protocol;
+  return protocol;
+}

package/src/agent/types.ts

@@ -0,0 +1,73 @@
+import type { GameStore } from "../state/store.ts";
+
+/** Verbosity levels for describe() output */
+export type Verbosity = "minimal" | "normal" | "detailed";
+
+/** Options passed to describe() */
+export type DescribeOptions = Readonly<{
+  verbosity?: Verbosity;
+  path?: string;
+}>;
+
+/** Information about a registered action */
+export type ActionInfo = Readonly<{
+  name: string;
+  description: string;
+  args?: readonly ArgInfo[];
+}>;
+
+/** Describes a single argument to an action */
+export type ArgInfo = Readonly<{
+  name: string;
+  type: string;
+  description?: string;
+}>;
+
+/** Result of executing an action */
+export type ActionResult<S> = Readonly<{
+  ok: boolean;
+  state: S;
+  error?: string;
+}>;
+
+/** Result of simulating an action (state not committed) */
+export type SimulateResult<S> = Readonly<{
+  ok: boolean;
+  state: S;
+  error?: string;
+}>;
+
+/** A captured state snapshot for rewind */
+export type SnapshotData<S> = Readonly<{
+  state: S;
+  timestamp: number;
+}>;
+
+/** An action handler: takes current state and parsed args, returns new state */
+export type ActionHandler<S> = (state: S, args: Record<string, unknown>) => S;
+
+/** Custom describe function */
+export type DescribeFn<S> = (state: S, options: DescribeOptions) => string;
+
+/** Agent configuration — either store-backed or get/setState-backed */
+export type AgentConfig<S> = {
+  name: string;
+  actions?: Record<string, { handler: ActionHandler<S>; description: string; args?: ArgInfo[] }>;
+  describe?: DescribeFn<S>;
+} & (
+  | { store: GameStore<S> }
+  | { getState: () => S; setState: (s: S) => void }
+);
+
+/** The protocol object installed on globalThis */
+export type AgentProtocol<S> = Readonly<{
+  name: string;
+  getState: () => S;
+  inspect: (path: string) => unknown;
+  describe: (options?: DescribeOptions) => string;
+  listActions: () => readonly ActionInfo[];
+  executeAction: (name: string, argsJson?: string) => ActionResult<S>;
+  simulate: (name: string, argsJson?: string) => SimulateResult<S>;
+  rewind: () => S;
+  captureSnapshot: () => SnapshotData<S>;
+}>;

package/src/pathfinding/astar.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import { findPath } from "./astar.ts";
+import type { PathGrid } from "./types.ts";
+
+/** Create a grid from string rows: '#' = wall, '.' = walkable */
+function gridFromStrings(rows: string[]): PathGrid {
+  const height = rows.length;
+  const width = rows[0].length;
+  return {
+    width,
+    height,
+    isWalkable: (x, y) => {
+      if (x < 0 || x >= width || y < 0 || y >= height) return false;
+      return rows[y][x] !== "#";
+    },
+  };
+}
+
+describe("pathfinding", () => {
+  it("start equals goal returns trivial path", () => {
+    const grid = gridFromStrings(["..."]);
+    const result = findPath(grid, { x: 1, y: 0 }, { x: 1, y: 0 });
+    assert.equal(result.found, true);
+    assert.equal(result.path.length, 1);
+    assert.deepEqual(result.path[0], { x: 1, y: 0 });
+    assert.equal(result.cost, 0);
+    assert.equal(result.explored, 0);
+  });
+
+  it("straight line path (no obstacles)", () => {
+    const grid = gridFromStrings([".....", ".....", "....."]);
+    const result = findPath(grid, { x: 0, y: 1 }, { x: 4, y: 1 });
+    assert.equal(result.found, true);
+    assert.equal(result.path.length, 5);
+    assert.deepEqual(result.path[0], { x: 0, y: 1 });
+    assert.deepEqual(result.path[4], { x: 4, y: 1 });
+    assert.equal(result.cost, 4);
+  });
+
+  it("path around single obstacle", () => {
+    const grid = gridFromStrings([
+      ".....",
+      "..#..",
+      ".....",
+    ]);
+    const result = findPath(grid, { x: 1, y: 1 }, { x: 3, y: 1 });
+    assert.equal(result.found, true);
+    // Must go around the wall — path length > 3
+    assert.ok(result.path.length > 3);
+    assert.deepEqual(result.path[0], { x: 1, y: 1 });
+    assert.deepEqual(result.path[result.path.length - 1], { x: 3, y: 1 });
+  });
+
+  it("no path found (completely blocked)", () => {
+    const grid = gridFromStrings([
+      "..#..",
+      "..#..",
+      "..#..",
+    ]);
+    const result = findPath(grid, { x: 0, y: 1 }, { x: 4, y: 1 });
+    assert.equal(result.found, false);
+    assert.equal(result.path.length, 0);
+  });
+
+  it("diagonal movement finds shorter path", () => {
+    const grid = gridFromStrings([
+      "...",
+      "...",
+      "...",
+    ]);
+    const cardinal = findPath(grid, { x: 0, y: 0 }, { x: 2, y: 2 });
+    const diag = findPath(grid, { x: 0, y: 0 }, { x: 2, y: 2 }, { diagonal: true });
+    assert.equal(cardinal.found, true);
+    assert.equal(diag.found, true);
+    assert.ok(diag.cost < cardinal.cost);
+    assert.ok(diag.path.length <= cardinal.path.length);
+  });
+
+  it("diagonal disabled doesn't use diagonals", () => {
+    const grid = gridFromStrings([
+      "...",
+      "...",
+      "...",
+    ]);
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 2, y: 2 }, { diagonal: false });
+    assert.equal(result.found, true);
+    // Without diagonals, each step moves exactly 1 in x or y
+    for (let i = 1; i < result.path.length; i++) {
+      const dx = Math.abs(result.path[i].x - result.path[i - 1].x);
+      const dy = Math.abs(result.path[i].y - result.path[i - 1].y);
+      assert.equal(dx + dy, 1);
+    }
+  });
+
+  it("custom cost function (weighted cells)", () => {
+    const grid: PathGrid = {
+      width: 5,
+      height: 1,
+      isWalkable: () => true,
+      cost: (x, _y) => (x === 2 ? 10 : 1),
+    };
+    // With high cost at x=2, the 1D path must still go through it
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 4, y: 0 });
+    assert.equal(result.found, true);
+    assert.equal(result.cost, 4 + 9); // cells 1,2,3,4 — cost(2)=10, others=1 → 1+10+1+1=13
+  });
+
+  it("max iterations limit reached", () => {
+    const grid = gridFromStrings([
+      "...........",
+      "...........",
+      "...........",
+      "...........",
+      "...........",
+    ]);
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 10, y: 4 }, { maxIterations: 5 });
+    assert.equal(result.found, false);
+    assert.equal(result.explored, 5);
+  });
+
+  it("manhattan heuristic gives correct result", () => {
+    const grid = gridFromStrings([".....", ".....", "....."]);
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 4, y: 2 }, { heuristic: "manhattan" });
+    assert.equal(result.found, true);
+    assert.equal(result.cost, 6);
+  });
+
+  it("euclidean heuristic gives correct result", () => {
+    const grid = gridFromStrings([".....", ".....", "....."]);
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 4, y: 2 }, {
+      heuristic: "euclidean",
+      diagonal: true,
+    });
+    assert.equal(result.found, true);
+    // Diagonal path should be shorter than 6
+    assert.ok(result.cost < 6);
+  });
+
+  it("chebyshev heuristic gives correct result", () => {
+    const grid = gridFromStrings([".....", ".....", "....."]);
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 4, y: 2 }, {
+      heuristic: "chebyshev",
+      diagonal: true,
+    });
+    assert.equal(result.found, true);
+    assert.ok(result.cost < 6);
+  });
+
+  it("large grid (50x50) with obstacles", () => {
+    const row = ".".repeat(50);
+    const rows: string[] = [];
+    for (let y = 0; y < 50; y++) {
+      rows.push(row);
+    }
+    // Add a wall across the middle with a gap
+    const wallRow = "#".repeat(25) + "." + "#".repeat(24);
+    rows[25] = wallRow;
+
+    const grid = gridFromStrings(rows);
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 49, y: 49 });
+    assert.equal(result.found, true);
+    assert.ok(result.path.length > 0);
+    assert.deepEqual(result.path[0], { x: 0, y: 0 });
+    assert.deepEqual(result.path[result.path.length - 1], { x: 49, y: 49 });
+  });
+
+  it("path along corridor", () => {
+    const grid = gridFromStrings([
+      "#####",
+      "#...#",
+      "###.#",
+      "#...#",
+      "#####",
+    ]);
+    const result = findPath(grid, { x: 1, y: 1 }, { x: 1, y: 3 });
+    assert.equal(result.found, true);
+    // Must go right, down through gap, then left
+    assert.deepEqual(result.path[0], { x: 1, y: 1 });
+    assert.deepEqual(result.path[result.path.length - 1], { x: 1, y: 3 });
+    assert.ok(result.path.length >= 5);
+  });
+
+  it("multiple valid paths (finds one)", () => {
+    const grid = gridFromStrings([
+      "...",
+      ".#.",
+      "...",
+    ]);
+    const result = findPath(grid, { x: 0, y: 0 }, { x: 2, y: 2 });
+    assert.equal(result.found, true);
+    assert.deepEqual(result.path[0], { x: 0, y: 0 });
+    assert.deepEqual(result.path[result.path.length - 1], { x: 2, y: 2 });
+    // Cardinal-only path around obstacle is length 5
+    assert.equal(result.path.length, 5);
+  });
+
+  it("out of bounds handled gracefully", () => {
+    const grid = gridFromStrings(["..."]);
+    const r1 = findPath(grid, { x: -1, y: 0 }, { x: 2, y: 0 });
+    assert.equal(r1.found, false);
+
+    const r2 = findPath(grid, { x: 0, y: 0 }, { x: 5, y: 0 });
+    assert.equal(r2.found, false);
+
+    const r3 = findPath(grid, { x: 0, y: -1 }, { x: 2, y: 0 });
+    assert.equal(r3.found, false);
+  });
+});

package/src/pathfinding/astar.ts

@@ -0,0 +1,193 @@
+import type { Vec2 } from "../state/types.ts";
+import type { PathGrid, PathOptions, PathResult } from "./types.ts";
+
+// Cardinal directions: right, down, left, up
+const CARDINAL_DX = [1, 0, -1, 0];
+const CARDINAL_DY = [0, 1, 0, -1];
+
+// Diagonal directions (appended after cardinal)
+const DIAGONAL_DX = [1, 1, -1, -1];
+const DIAGONAL_DY = [1, -1, 1, -1];
+
+const SQRT2 = Math.SQRT2;
+
+// --- Binary min-heap ---
+
+type HeapEntry = { index: number; f: number };
+
+function heapPush(heap: HeapEntry[], entry: HeapEntry): void {
+  heap.push(entry);
+  let i = heap.length - 1;
+  while (i > 0) {
+    const parent = (i - 1) >> 1;
+    if (heap[parent].f <= heap[i].f) break;
+    const tmp = heap[parent];
+    heap[parent] = heap[i];
+    heap[i] = tmp;
+    i = parent;
+  }
+}
+
+function heapPop(heap: HeapEntry[]): HeapEntry | undefined {
+  const len = heap.length;
+  if (len === 0) return undefined;
+  const top = heap[0];
+  const last = heap[len - 1];
+  heap.length = len - 1;
+  if (len > 1) {
+    heap[0] = last;
+    let i = 0;
+    const half = heap.length >> 1;
+    while (i < half) {
+      let child = (i << 1) + 1;
+      const right = child + 1;
+      if (right < heap.length && heap[right].f < heap[child].f) {
+        child = right;
+      }
+      if (heap[child].f >= heap[i].f) break;
+      const tmp = heap[child];
+      heap[child] = heap[i];
+      heap[i] = tmp;
+      i = child;
+    }
+  }
+  return top;
+}
+
+// --- Heuristics ---
+
+function manhattan(dx: number, dy: number): number {
+  return Math.abs(dx) + Math.abs(dy);
+}
+
+function euclidean(dx: number, dy: number): number {
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+function chebyshev(dx: number, dy: number): number {
+  return Math.max(Math.abs(dx), Math.abs(dy));
+}
+
+function selectHeuristic(name: string): (dx: number, dy: number) => number {
+  if (name === "euclidean") return euclidean;
+  if (name === "chebyshev") return chebyshev;
+  return manhattan;
+}
+
+// --- A* ---
+
+export function findPath(
+  grid: PathGrid,
+  start: Vec2,
+  goal: Vec2,
+  options?: PathOptions,
+): PathResult {
+  const diagonal = options?.diagonal ?? false;
+  const maxIterations = options?.maxIterations ?? 10000;
+  const heuristic = selectHeuristic(options?.heuristic ?? "manhattan");
+
+  const { width, height, isWalkable } = grid;
+  const getCost = grid.cost;
+
+  const sx = start.x | 0;
+  const sy = start.y | 0;
+  const gx = goal.x | 0;
+  const gy = goal.y | 0;
+
+  // Trivial case
+  if (sx === gx && sy === gy) {
+    return { found: true, path: [{ x: sx, y: sy }], cost: 0, explored: 0 };
+  }
+
+  // Out of bounds or unwalkable endpoints
+  if (
+    sx < 0 || sx >= width || sy < 0 || sy >= height ||
+    gx < 0 || gx >= width || gy < 0 || gy >= height ||
+    !isWalkable(sx, sy) || !isWalkable(gx, gy)
+  ) {
+    return { found: false, path: [], cost: 0, explored: 0 };
+  }
+
+  const size = width * height;
+  const gCost = new Float64Array(size);
+  const parentIdx = new Int32Array(size);
+  const closed = new Uint8Array(size);
+
+  // Initialize g-costs to infinity
+  gCost.fill(Infinity);
+
+  const startIdx = sy * width + sx;
+  const goalIdx = gy * width + gx;
+  gCost[startIdx] = 0;
+  parentIdx[startIdx] = -1;
+
+  const heap: HeapEntry[] = [];
+  heapPush(heap, { index: startIdx, f: heuristic(gx - sx, gy - sy) });
+
+  const numCardinal = 4;
+  const numDirs = diagonal ? 8 : 4;
+
+  let iterations = 0;
+
+  while (heap.length > 0) {
+    if (iterations >= maxIterations) {
+      return { found: false, path: [], cost: 0, explored: iterations };
+    }
+
+    const current = heapPop(heap)!;
+    const ci = current.index;
+
+    if (closed[ci]) continue;
+    closed[ci] = 1;
+    iterations++;
+
+    if (ci === goalIdx) {
+      // Reconstruct path
+      const path: Vec2[] = [];
+      let idx = goalIdx;
+      while (idx !== -1) {
+        path.push({ x: idx % width, y: (idx / width) | 0 });
+        idx = parentIdx[idx];
+      }
+      path.reverse();
+      return { found: true, path, cost: gCost[goalIdx], explored: iterations };
+    }
+
+    const cx = ci % width;
+    const cy = (ci / width) | 0;
+
+    for (let d = 0; d < numDirs; d++) {
+      let nx: number, ny: number;
+      let isDiag: boolean;
+      if (d < numCardinal) {
+        nx = cx + CARDINAL_DX[d];
+        ny = cy + CARDINAL_DY[d];
+        isDiag = false;
+      } else {
+        nx = cx + DIAGONAL_DX[d - numCardinal];
+        ny = cy + DIAGONAL_DY[d - numCardinal];
+        isDiag = true;
+      }
+
+      if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
+      if (!isWalkable(nx, ny)) continue;
+
+      const ni = ny * width + nx;
+      if (closed[ni]) continue;
+
+      const moveCost = getCost
+        ? getCost(nx, ny)
+        : (isDiag ? SQRT2 : 1);
+
+      const newG = gCost[ci] + moveCost;
+      if (newG < gCost[ni]) {
+        gCost[ni] = newG;
+        parentIdx[ni] = ci;
+        const h = heuristic(gx - nx, gy - ny);
+        heapPush(heap, { index: ni, f: newG + h });
+      }
+    }
+  }
+
+  return { found: false, path: [], cost: 0, explored: iterations };
+}

package/src/pathfinding/index.ts

@@ -0,0 +1,2 @@
+export type { PathGrid, PathOptions, PathResult } from "./types.ts";
+export { findPath } from "./astar.ts";

package/src/pathfinding/types.ts

@@ -0,0 +1,21 @@
+import type { Vec2 } from "../state/types.ts";
+
+export type PathGrid = {
+  width: number;
+  height: number;
+  isWalkable: (x: number, y: number) => boolean;
+  cost?: (x: number, y: number) => number;
+};
+
+export type PathOptions = {
+  diagonal?: boolean;
+  maxIterations?: number;
+  heuristic?: "manhattan" | "euclidean" | "chebyshev";
+};
+
+export type PathResult = {
+  found: boolean;
+  path: Vec2[];
+  cost: number;
+  explored: number;
+};

package/src/physics/aabb.ts

@@ -0,0 +1,54 @@
+/** Axis-Aligned Bounding Box */
+export type AABB = {
+  x: number;  // left edge
+  y: number;  // top edge
+  w: number;  // width
+  h: number;  // height
+};
+
+/** Check if two AABBs overlap */
+export function aabbOverlap(a: AABB, b: AABB): boolean {
+  return a.x < b.x + b.w && a.x + a.w > b.x &&
+         a.y < b.y + b.h && a.y + a.h > b.y;
+}
+
+/** Check if a circle overlaps an AABB */
+export function circleAABBOverlap(
+  cx: number, cy: number, radius: number,
+  box: AABB
+): boolean {
+  const closestX = Math.max(box.x, Math.min(cx, box.x + box.w));
+  const closestY = Math.max(box.y, Math.min(cy, box.y + box.h));
+  const dx = cx - closestX;
+  const dy = cy - closestY;
+  return (dx * dx + dy * dy) <= (radius * radius);
+}
+
+/** Get collision normal for circle vs AABB. Returns null if no collision. */
+export function circleAABBResolve(
+  cx: number, cy: number, radius: number,
+  box: AABB
+): { nx: number; ny: number } | null {
+  const closestX = Math.max(box.x, Math.min(cx, box.x + box.w));
+  const closestY = Math.max(box.y, Math.min(cy, box.y + box.h));
+  const dx = cx - closestX;
+  const dy = cy - closestY;
+  const distSq = dx * dx + dy * dy;
+
+  if (distSq > radius * radius) return null;
+  if (distSq === 0) {
+    // Circle center is inside the box — push out along shortest axis
+    const midX = box.x + box.w / 2;
+    const midY = box.y + box.h / 2;
+    const fromCenterX = cx - midX;
+    const fromCenterY = cy - midY;
+    if (Math.abs(fromCenterX / box.w) > Math.abs(fromCenterY / box.h)) {
+      return { nx: fromCenterX > 0 ? 1 : -1, ny: 0 };
+    } else {
+      return { nx: 0, ny: fromCenterY > 0 ? 1 : -1 };
+    }
+  }
+
+  const dist = Math.sqrt(distSq);
+  return { nx: dx / dist, ny: dy / dist };
+}

package/src/physics/index.ts

@@ -0,0 +1,2 @@
+export type { AABB } from "./aabb.ts";
+export { aabbOverlap, circleAABBOverlap, circleAABBResolve } from "./aabb.ts";