@arcane-engine/runtime 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @arcane/runtime
+
+TypeScript runtime for Arcane — a code-first, test-native, agent-native 2D game engine.
+
+## Installation
+
+```bash
+npm install @arcane/runtime
+```
+
+**Note:** You also need the Arcane CLI:
+```bash
+cargo install arcane-cli
+```
+
+## Quick Example
+
+```typescript
+import { createStore } from "@arcane/runtime/state";
+import { onFrame, drawSprite } from "@arcane/runtime/rendering";
+
+const store = createStore({ player: { x: 0, y: 0 } });
+
+onFrame(() => {
+  const state = store.getState();
+  drawSprite("player", state.player.x, state.player.y, { width: 32, height: 32 });
+});
+```
+
+## Documentation
+
+- [Getting Started](https://github.com/anthropics/arcane/blob/main/docs/getting-started.md)
+- [API Reference](https://github.com/anthropics/arcane/blob/main/docs/api-reference.md)
+- [Examples](https://github.com/anthropics/arcane/tree/main/examples)
+
+## License
+
+Apache 2.0

package/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @arcane/runtime — Agent-native 2D game engine runtime
+ *
+ * This package contains the TypeScript runtime APIs for Arcane.
+ * Import specific modules from subpaths:
+ *
+ * @example
+ * ```typescript
+ * import { createStore } from "@arcane/runtime/state";
+ * import { onFrame, drawSprite } from "@arcane/runtime/rendering";
+ * import { findPath } from "@arcane/runtime/pathfinding";
+ * ```
+ *
+ * @see https://github.com/anthropics/arcane
+ */
+
+// Re-export commonly used types
+export type { Vec2, EntityId } from "./src/state/types.ts";
+export type { GameStore } from "./src/state/store.ts";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@arcane-engine/runtime",
+  "version": "0.1.0",
+  "description": "Agent-native 2D game engine runtime - TypeScript APIs for state management, rendering, and game logic",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./state": "./src/state/index.ts",
+    "./rendering": "./src/rendering/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./physics": "./src/physics/index.ts",
+    "./pathfinding": "./src/pathfinding/index.ts",
+    "./systems": "./src/systems/index.ts",
+    "./agent": "./src/agent/index.ts",
+    "./testing": "./src/testing/harness.ts"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "game-engine",
+    "2d",
+    "gamedev",
+    "typescript",
+    "ai-agent",
+    "agent-native",
+    "state-management",
+    "ecs",
+    "recipes"
+  ],
+  "author": "Arcane Contributors",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/arcane.git",
+    "directory": "packages/runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/anthropics/arcane/issues"
+  },
+  "homepage": "https://github.com/anthropics/arcane#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/agent/agent.test.ts

@@ -0,0 +1,384 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import { registerAgent } from "./protocol.ts";
+import { defaultDescribe } from "./describe.ts";
+import { createStore } from "../state/store.ts";
+import type { AgentConfig, DescribeOptions } from "./types.ts";
+
+// --- Test state types ---
+
+type RPGState = {
+  player: { hp: number; maxHp: number; pos: { x: number; y: number } };
+  enemies: { id: string; hp: number }[];
+  turn: number;
+  phase: "playing" | "won" | "dead";
+};
+
+const makeState = (): RPGState => ({
+  player: { hp: 20, maxHp: 20, pos: { x: 1, y: 1 } },
+  enemies: [
+    { id: "goblin", hp: 6 },
+    { id: "rat", hp: 3 },
+  ],
+  turn: 1,
+  phase: "playing",
+});
+
+// Helper to create a get/setState-backed agent
+function makeAgent(initial?: RPGState) {
+  let state = initial ?? makeState();
+  return registerAgent<RPGState>({
+    name: "test-agent",
+    getState: () => state,
+    setState: (s) => { state = s; },
+    actions: {
+      move: {
+        handler: (s, args) => ({
+          ...s,
+          player: {
+            ...s.player,
+            pos: {
+              x: s.player.pos.x + (args.dx as number ?? 0),
+              y: s.player.pos.y + (args.dy as number ?? 0),
+            },
+          },
+          turn: s.turn + 1,
+        }),
+        description: "Move the player by (dx, dy)",
+        args: [
+          { name: "dx", type: "number" },
+          { name: "dy", type: "number" },
+        ],
+      },
+      wait: {
+        handler: (s) => ({ ...s, turn: s.turn + 1 }),
+        description: "Wait one turn",
+      },
+      failAction: {
+        handler: () => { throw new Error("intentional failure"); },
+        description: "Always fails",
+      },
+    },
+  });
+}
+
+// --- registerAgent ---
+
+describe("registerAgent", () => {
+  it("returns a protocol with the agent name", () => {
+    const agent = makeAgent();
+    assert.equal(agent.name, "test-agent");
+  });
+
+  it("installs on globalThis.__arcaneAgent", () => {
+    const agent = makeAgent();
+    assert.equal((globalThis as any).__arcaneAgent, agent);
+  });
+
+  it("works with a GameStore", () => {
+    const store = createStore(makeState());
+    const agent = registerAgent<RPGState>({
+      name: "store-agent",
+      store,
+      actions: {
+        wait: {
+          handler: (s) => ({ ...s, turn: s.turn + 1 }),
+          description: "Wait one turn",
+        },
+      },
+    });
+    assert.equal(agent.getState().turn, 1);
+    agent.executeAction("wait");
+    assert.equal(agent.getState().turn, 2);
+    // store should reflect the change
+    assert.equal(store.getState().turn, 2);
+  });
+});
+
+// --- getState ---
+
+describe("getState", () => {
+  it("returns the current state", () => {
+    const agent = makeAgent();
+    const state = agent.getState();
+    assert.equal(state.player.hp, 20);
+    assert.equal(state.turn, 1);
+  });
+});
+
+// --- inspect ---
+
+describe("inspect", () => {
+  it("returns a value at a simple path", () => {
+    const agent = makeAgent();
+    assert.equal(agent.inspect("turn"), 1);
+  });
+
+  it("returns a value at a nested path", () => {
+    const agent = makeAgent();
+    assert.equal(agent.inspect("player.hp"), 20);
+    assert.equal(agent.inspect("player.pos.x"), 1);
+  });
+
+  it("returns undefined for nonexistent path", () => {
+    const agent = makeAgent();
+    assert.equal(agent.inspect("nonexistent"), undefined);
+  });
+
+  it("returns array elements by index path", () => {
+    const agent = makeAgent();
+    assert.equal(agent.inspect("enemies.0.id"), "goblin");
+    assert.equal(agent.inspect("enemies.1.hp"), 3);
+  });
+});
+
+// --- describe ---
+
+describe("describe", () => {
+  it("uses default describe when none provided", () => {
+    const agent = makeAgent();
+    const desc = agent.describe();
+    assert.ok(desc.includes("player"));
+    assert.ok(desc.includes("turn"));
+  });
+
+  it("accepts a custom describe function", () => {
+    let state = makeState();
+    const agent = registerAgent<RPGState>({
+      name: "custom-desc",
+      getState: () => state,
+      setState: (s) => { state = s; },
+      describe: (s) => `Turn ${s.turn}, HP: ${s.player.hp}/${s.player.maxHp}`,
+    });
+    assert.equal(agent.describe(), "Turn 1, HP: 20/20");
+  });
+
+  it("passes options to describe function", () => {
+    let state = makeState();
+    const agent = registerAgent<RPGState>({
+      name: "opts-desc",
+      getState: () => state,
+      setState: (s) => { state = s; },
+      describe: (s, opts) => `v=${opts.verbosity ?? "normal"}, p=${opts.path ?? "none"}`,
+    });
+    assert.equal(agent.describe({ verbosity: "minimal" }), "v=minimal, p=none");
+    assert.equal(agent.describe({ path: "player" }), "v=normal, p=player");
+  });
+});
+
+// --- listActions ---
+
+describe("listActions", () => {
+  it("returns all registered actions", () => {
+    const agent = makeAgent();
+    const actions = agent.listActions();
+    assert.equal(actions.length, 3);
+    const names = actions.map((a) => a.name);
+    assert.ok(names.includes("move"));
+    assert.ok(names.includes("wait"));
+    assert.ok(names.includes("failAction"));
+  });
+
+  it("includes description and args metadata", () => {
+    const agent = makeAgent();
+    const moveAction = agent.listActions().find((a) => a.name === "move");
+    assert.ok(moveAction !== undefined);
+    assert.equal(moveAction!.description, "Move the player by (dx, dy)");
+    assert.equal(moveAction!.args!.length, 2);
+    assert.equal(moveAction!.args![0].name, "dx");
+  });
+
+  it("returns empty array when no actions registered", () => {
+    let state = makeState();
+    const agent = registerAgent<RPGState>({
+      name: "no-actions",
+      getState: () => state,
+      setState: (s) => { state = s; },
+    });
+    assert.deepEqual(agent.listActions(), []);
+  });
+});
+
+// --- executeAction ---
+
+describe("executeAction", () => {
+  it("executes an action and updates state", () => {
+    const agent = makeAgent();
+    const result = agent.executeAction("move", JSON.stringify({ dx: 1, dy: 0 }));
+    assert.equal(result.ok, true);
+    assert.equal(result.state.player.pos.x, 2);
+    assert.equal(result.state.turn, 2);
+    // State is committed
+    assert.equal(agent.getState().player.pos.x, 2);
+  });
+
+  it("executes an action with no args", () => {
+    const agent = makeAgent();
+    const result = agent.executeAction("wait");
+    assert.equal(result.ok, true);
+    assert.equal(result.state.turn, 2);
+  });
+
+  it("returns error for unknown action", () => {
+    const agent = makeAgent();
+    const result = agent.executeAction("nonexistent");
+    assert.equal(result.ok, false);
+    assert.ok(result.error!.includes("Unknown action"));
+  });
+
+  it("returns error for invalid JSON args", () => {
+    const agent = makeAgent();
+    const result = agent.executeAction("move", "{bad json");
+    assert.equal(result.ok, false);
+    assert.ok(result.error!.includes("Invalid JSON"));
+  });
+
+  it("returns error when action handler throws", () => {
+    const agent = makeAgent();
+    const result = agent.executeAction("failAction");
+    assert.equal(result.ok, false);
+    assert.ok(result.error!.includes("intentional failure"));
+  });
+});
+
+// --- simulate ---
+
+describe("simulate", () => {
+  it("simulates an action without committing state", () => {
+    const agent = makeAgent();
+    const result = agent.simulate("move", JSON.stringify({ dx: 1, dy: 0 }));
+    assert.equal(result.ok, true);
+    assert.equal(result.state.player.pos.x, 2);
+    // Original state unchanged
+    assert.equal(agent.getState().player.pos.x, 1);
+  });
+
+  it("returns error for unknown action", () => {
+    const agent = makeAgent();
+    const result = agent.simulate("nonexistent");
+    assert.equal(result.ok, false);
+    assert.ok(result.error!.includes("Unknown action"));
+  });
+
+  it("returns error for invalid JSON args", () => {
+    const agent = makeAgent();
+    const result = agent.simulate("move", "{bad}");
+    assert.equal(result.ok, false);
+    assert.ok(result.error!.includes("Invalid JSON"));
+  });
+
+  it("returns error when simulation throws", () => {
+    const agent = makeAgent();
+    const result = agent.simulate("failAction");
+    assert.equal(result.ok, false);
+    assert.ok(result.error!.includes("intentional failure"));
+  });
+});
+
+// --- rewind ---
+
+describe("rewind", () => {
+  it("resets to initial state", () => {
+    const agent = makeAgent();
+    agent.executeAction("move", JSON.stringify({ dx: 5, dy: 5 }));
+    agent.executeAction("wait");
+    assert.equal(agent.getState().turn, 3);
+    assert.equal(agent.getState().player.pos.x, 6);
+
+    const restored = agent.rewind();
+    assert.equal(restored.turn, 1);
+    assert.equal(restored.player.pos.x, 1);
+    assert.equal(agent.getState().turn, 1);
+  });
+
+  it("returns a deep clone (modifying it does not affect agent)", () => {
+    const agent = makeAgent();
+    const restored = agent.rewind();
+    (restored as any).turn = 999;
+    assert.equal(agent.getState().turn, 1);
+  });
+});
+
+// --- captureSnapshot ---
+
+describe("captureSnapshot", () => {
+  it("captures current state with timestamp", () => {
+    const agent = makeAgent();
+    agent.executeAction("wait");
+    const snap = agent.captureSnapshot();
+    assert.equal(snap.state.turn, 2);
+    assert.ok(typeof snap.timestamp === "number");
+    assert.ok(snap.timestamp > 0);
+  });
+
+  it("returns a deep clone", () => {
+    const agent = makeAgent();
+    const snap = agent.captureSnapshot();
+    (snap.state as any).turn = 999;
+    assert.equal(agent.getState().turn, 1);
+  });
+});
+
+// --- defaultDescribe ---
+
+describe("defaultDescribe", () => {
+  it("minimal: shows key names for objects", () => {
+    const desc = defaultDescribe({ a: 1, b: 2 }, { verbosity: "minimal" });
+    assert.equal(desc, "{a, b}");
+  });
+
+  it("minimal: shows count for arrays", () => {
+    const desc = defaultDescribe([1, 2, 3], { verbosity: "minimal" });
+    assert.equal(desc, "Array(3)");
+  });
+
+  it("normal: shows first 3 keys with values", () => {
+    const desc = defaultDescribe(
+      { a: 1, b: "hello", c: [1, 2], d: true },
+      { verbosity: "normal" },
+    );
+    assert.ok(desc.includes("a: 1"));
+    assert.ok(desc.includes('b: "hello"'));
+    assert.ok(desc.includes("c: Array(2)"));
+    assert.ok(desc.includes("4 keys total"));
+  });
+
+  it("normal: shows first 3 array items", () => {
+    const desc = defaultDescribe([10, 20, 30, 40], { verbosity: "normal" });
+    assert.ok(desc.includes("10"));
+    assert.ok(desc.includes("20"));
+    assert.ok(desc.includes("30"));
+    assert.ok(desc.includes("4 total"));
+  });
+
+  it("detailed: returns full JSON", () => {
+    const obj = { x: 1, y: 2 };
+    const desc = defaultDescribe(obj, { verbosity: "detailed" });
+    assert.deepEqual(JSON.parse(desc), obj);
+  });
+
+  it("handles path option", () => {
+    const state = { player: { hp: 10 }, enemies: [1, 2] };
+    const desc = defaultDescribe(state, { path: "player", verbosity: "detailed" });
+    assert.deepEqual(JSON.parse(desc), { hp: 10 });
+  });
+
+  it("returns not-found message for invalid path", () => {
+    const desc = defaultDescribe({ a: 1 }, { path: "x.y.z" });
+    assert.ok(desc.includes("not found"));
+  });
+
+  it("handles primitives", () => {
+    assert.equal(defaultDescribe(42, {}), "42");
+    assert.equal(defaultDescribe("hello", {}), "hello");
+    assert.equal(defaultDescribe(true, {}), "true");
+  });
+
+  it("handles null state", () => {
+    assert.equal(defaultDescribe(null, {}), "null");
+  });
+
+  it("defaults to normal verbosity", () => {
+    const desc = defaultDescribe({ a: 1 }, {});
+    assert.ok(desc.includes("a: 1"));
+  });
+});

package/src/agent/describe.ts

@@ -0,0 +1,72 @@
+import type { DescribeOptions, Verbosity } from "./types.ts";
+
+/** Default describe function that summarizes game state at the given verbosity */
+export function defaultDescribe(state: unknown, options: DescribeOptions): string {
+  const verbosity: Verbosity = options.verbosity ?? "normal";
+  const target = options.path ? getByPath(state, options.path) : state;
+
+  if (target === undefined) {
+    return options.path ? `Path "${options.path}" not found` : "No state";
+  }
+
+  if (verbosity === "detailed") {
+    return JSON.stringify(target, null, 2);
+  }
+
+  if (typeof target !== "object" || target === null) {
+    return String(target);
+  }
+
+  if (Array.isArray(target)) {
+    return describeArray(target, verbosity);
+  }
+
+  return describeObject(target as Record<string, unknown>, verbosity);
+}
+
+function describeArray(arr: unknown[], verbosity: Verbosity): string {
+  if (verbosity === "minimal") {
+    return `Array(${arr.length})`;
+  }
+  // normal: show first 3 items
+  const preview = arr.slice(0, 3).map((item) => summarizeValue(item));
+  const suffix = arr.length > 3 ? `, ... (${arr.length} total)` : "";
+  return `[${preview.join(", ")}${suffix}]`;
+}
+
+function describeObject(obj: Record<string, unknown>, verbosity: Verbosity): string {
+  const keys = Object.keys(obj);
+  if (verbosity === "minimal") {
+    return `{${keys.join(", ")}}`;
+  }
+  // normal: show key: summarized value for first 3 keys
+  const lines = keys.slice(0, 3).map((k) => `  ${k}: ${summarizeValue(obj[k])}`);
+  if (keys.length > 3) {
+    lines.push(`  ... (${keys.length} keys total)`);
+  }
+  return `{\n${lines.join("\n")}\n}`;
+}
+
+function summarizeValue(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `Array(${value.length})`;
+  if (typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>);
+    return `{${keys.length} keys}`;
+  }
+  return String(value);
+}
+
+function getByPath(obj: unknown, path: string): unknown {
+  const segments = path.split(".");
+  let current: unknown = obj;
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[seg];
+  }
+  return current;
+}

package/src/agent/index.ts

@@ -0,0 +1,20 @@
+// Types
+export type {
+  Verbosity,
+  DescribeOptions,
+  ActionInfo,
+  ArgInfo,
+  ActionResult,
+  SimulateResult,
+  SnapshotData,
+  ActionHandler,
+  DescribeFn,
+  AgentConfig,
+  AgentProtocol,
+} from "./types.ts";
+
+// Protocol
+export { registerAgent } from "./protocol.ts";
+
+// Describe
+export { defaultDescribe } from "./describe.ts";