@arcane-engine/runtime 0.1.0 → 0.2.1

package/src/systems/types.ts

@@ -1,35 +1,81 @@
 import type { ArcaneError } from "../state/error.ts";
 
-/** A condition that must be true for a rule to fire. */
+/**
+ * A predicate that checks whether a rule's preconditions are met.
+ * Must be a pure function.
+ *
+ * @param state - Current game state (read-only by convention).
+ * @param args - Additional arguments passed to {@link applyRule}.
+ * @returns True if the condition is satisfied.
+ */
 export type Condition<S> = (state: S, args: Record<string, unknown>) => boolean;
 
-/** An action that transforms state when a rule fires. */
+/**
+ * A pure transform that produces new state when a rule fires.
+ * Multiple actions on a rule are chained: each receives the output of the previous.
+ *
+ * @param state - Current game state.
+ * @param args - Additional arguments passed to {@link applyRule}.
+ * @returns New state (must not mutate the input).
+ */
 export type Action<S> = (state: S, args: Record<string, unknown>) => S;
 
-/** A named rule with conditions and actions. */
+/**
+ * A named rule consisting of conditions and actions.
+ *
+ * When applied via {@link applyRule}, all conditions must pass for the
+ * actions to execute. Actions are chained in order.
+ *
+ * @typeParam S - The game state type.
+ */
 export type Rule<S> = Readonly<{
+  /** Unique name within the system. Used for lookup by {@link applyRule} and {@link extend}. */
   name: string;
+  /** Conditions that must all return true for the rule to fire. Empty = always fires. */
   conditions: readonly Condition<S>[];
+  /** State transforms to apply in order when the rule fires. */
   actions: readonly Action<S>[];
+  /** If set, this rule replaces the rule with the given name when used in {@link extend}. */
   replaces?: string;
 }>;
 
-/** A named system: a collection of rules. */
+/**
+ * A named system: an ordered collection of rules that together define game mechanics.
+ * Created via {@link system} and extended via {@link extend}.
+ *
+ * @typeParam S - The game state type.
+ */
 export type SystemDef<S> = Readonly<{
+  /** System name (e.g., "combat", "inventory"). */
   name: string;
+  /** Ordered list of rules in this system. */
   rules: readonly Rule<S>[];
 }>;
 
-/** Result of applying a single rule. */
+/**
+ * Result of applying a single rule via {@link applyRule}.
+ *
+ * @typeParam S - The game state type.
+ */
 export type RuleResult<S> = Readonly<{
+  /** True if all conditions passed and actions executed successfully. */
   ok: boolean;
+  /** The resulting state (unchanged if ok is false). */
   state: S;
+  /** Name of the rule that was applied. */
   ruleName: string;
+  /** Error details if ok is false (rule not found or conditions failed). */
   error?: ArcaneError;
 }>;
 
-/** Options for extending a system. */
+/**
+ * Options for extending a system via {@link extend}.
+ *
+ * @typeParam S - The game state type.
+ */
 export type ExtendOptions<S> = {
+  /** New rules to add. Rules with `replaces` set will replace existing rules by name. */
   rules?: readonly Rule<S>[];
+  /** Names of existing rules to remove from the system. */
   remove?: readonly string[];
 };

package/src/testing/harness.ts

@@ -1,20 +1,97 @@
-// Universal test harness — works in both Node.js and V8 (deno_core).
-//
-// Node mode: delegates to node:test and node:assert.
-// V8 mode: standalone implementations with result reporting via
-//   globalThis.__reportTest(suite, test, passed, error?)
+/**
+ * Universal test harness for Arcane — works in both Node.js and V8 (deno_core).
+ *
+ * In **Node mode**: delegates to `node:test` and `node:assert`.
+ * In **V8 mode**: standalone implementations with result reporting via
+ * `globalThis.__reportTest(suite, test, passed, error?)`.
+ *
+ * Test files import `{ describe, it, assert }` from this module and work
+ * identically in both environments.
+ *
+ * @example
+ * ```ts
+ * import { describe, it, assert } from "../testing/harness.ts";
+ *
+ * describe("math", () => {
+ *   it("adds numbers", () => {
+ *     assert.equal(1 + 1, 2);
+ *   });
+ *
+ *   it("supports deep equality", () => {
+ *     assert.deepEqual({ a: 1 }, { a: 1 });
+ *   });
+ * });
+ * ```
+ */
 
+/** A synchronous or async test function. */
 type TestFn = () => void | Promise<void>;
+
+/** Function signature for `describe()` — defines a test suite. */
 type DescribeFn = (name: string, fn: () => void) => void;
+
+/** Function signature for `it()` — defines a single test case. */
 type ItFn = (name: string, fn: TestFn) => void;
 
+/**
+ * Assertion interface providing common test assertions.
+ *
+ * All assertion methods throw on failure with a descriptive error message.
+ */
 interface Assert {
+  /**
+   * Assert strict equality (`===`).
+   * @param actual - The value to test.
+   * @param expected - The expected value.
+   * @param message - Optional custom failure message.
+   */
   equal(actual: unknown, expected: unknown, message?: string): void;
+
+  /**
+   * Assert deep structural equality (recursive comparison of objects/arrays).
+   * @param actual - The value to test.
+   * @param expected - The expected structure.
+   * @param message - Optional custom failure message.
+   */
   deepEqual(actual: unknown, expected: unknown, message?: string): void;
+
+  /**
+   * Assert strict inequality (`!==`).
+   * @param actual - The value to test.
+   * @param expected - The value that `actual` must not equal.
+   * @param message - Optional custom failure message.
+   */
   notEqual(actual: unknown, expected: unknown, message?: string): void;
+
+  /**
+   * Assert that two values are NOT deeply equal.
+   * @param actual - The value to test.
+   * @param expected - The value that `actual` must not deeply equal.
+   * @param message - Optional custom failure message.
+   */
   notDeepEqual(actual: unknown, expected: unknown, message?: string): void;
+
+  /**
+   * Assert that a value is truthy.
+   * @param value - The value to test.
+   * @param message - Optional custom failure message.
+   */
   ok(value: unknown, message?: string): void;
+
+  /**
+   * Assert that a string matches a regular expression.
+   * @param actual - The string to test.
+   * @param expected - The regex pattern to match against.
+   * @param message - Optional custom failure message.
+   */
   match(actual: string, expected: RegExp, message?: string): void;
+
+  /**
+   * Assert that a function throws an error.
+   * @param fn - The function expected to throw.
+   * @param expected - Optional regex to match against the error message.
+   * @param message - Optional custom failure message.
+   */
   throws(fn: () => unknown, expected?: RegExp, message?: string): void;
 }
 
@@ -244,8 +321,29 @@ declare const __reportTest: (
 // Node.js — delegate to built-in modules
 // ---------------------------------------------------------------------------
 
+/**
+ * Define a test suite. Can be nested with other describe() calls.
+ * In V8 mode, nested suites have their test names prefixed with the parent suite name.
+ *
+ * @param name - Suite name displayed in test output.
+ * @param fn - Function containing `it()` test cases and/or nested `describe()` calls.
+ */
 let describe: DescribeFn;
+
+/**
+ * Define a single test case within a describe() suite.
+ * Supports both synchronous and async test functions.
+ *
+ * @param name - Test name displayed in test output.
+ * @param fn - Test function. Throw (or reject) to indicate failure; return to pass.
+ */
 let it: ItFn;
+
+/**
+ * Assertion helpers for test cases. Methods throw on failure with descriptive messages.
+ *
+ * Available assertions: `equal`, `deepEqual`, `notEqual`, `notDeepEqual`, `ok`, `match`, `throws`.
+ */
 let assert: Assert;
 
 if (isNode) {

package/src/testing/mock-renderer.test.ts

@@ -2,16 +2,12 @@
  * Tests demonstrating mock renderer usage
  */
 
-// @ts-nocheck - Uses Node-specific test APIs (beforeEach/afterEach) not in harness
 import { describe, it, assert } from "./harness.ts";
 import { mockRenderer, installMockRenderer, restoreRenderer } from "./mock-renderer.ts";
 
 describe("Mock Renderer", () => {
-  beforeEach(() => {
-    mockRenderer.reset();
-  });
-
   it("should validate drawRect parameters", () => {
+    mockRenderer.reset();
     mockRenderer.drawRect(10.0, 20.0, 100.0, 50.0, { color: { r: 1.0, g: 0.5, b: 0.0 } });
 
     mockRenderer.assertNoErrors();
@@ -19,24 +15,27 @@ describe("Mock Renderer", () => {
   });
 
   it("should catch wrong parameter types", () => {
+    mockRenderer.reset();
     // Wrong: passing object instead of separate params
     mockRenderer.drawRect({ x: 10 } as any, undefined, undefined, undefined);
 
-    assert(mockRenderer.hasErrors(), "Should have errors");
+    assert.ok(mockRenderer.hasErrors(), "Should have errors");
     const errors = mockRenderer.getErrors();
-    assert(errors.some(e => e.includes("must be number")), "Should complain about type");
+    assert.ok(errors.some(e => e.includes("must be number")), "Should complain about type");
   });
 
   it("should catch invalid color values", () => {
+    mockRenderer.reset();
     // Color values must be 0.0-1.0
     mockRenderer.drawRect(0, 0, 100, 100, { color: { r: 255, g: 255, b: 255 } });
 
-    assert(mockRenderer.hasErrors(), "Should have errors");
+    assert.ok(mockRenderer.hasErrors(), "Should have errors");
     const errors = mockRenderer.getErrors();
-    assert(errors.some(e => e.includes("color.r must be 0.0-1.0")), "Should catch invalid color");
+    assert.ok(errors.some(e => e.includes("color.r must be 0.0-1.0")), "Should catch invalid color");
   });
 
   it("should validate drawText parameters", () => {
+    mockRenderer.reset();
     mockRenderer.drawText("Hello", { x: 10.0, y: 20.0, size: 16.0, color: { r: 1.0, g: 1.0, b: 1.0 } });
 
     mockRenderer.assertNoErrors();
@@ -44,26 +43,21 @@ describe("Mock Renderer", () => {
   });
 
   it("should catch NaN values", () => {
+    mockRenderer.reset();
     mockRenderer.drawRect(NaN, 0, 100, 100);
 
-    assert(mockRenderer.hasErrors(), "Should catch NaN");
+    assert.ok(mockRenderer.hasErrors(), "Should catch NaN");
     const errors = mockRenderer.getErrors();
-    assert(errors.some(e => e.includes("NaN")), "Should complain about NaN");
+    assert.ok(errors.some(e => e.includes("NaN")), "Should complain about NaN");
   });
 });
 
 // Example: Testing a game's rendering code
 describe("Game Visual Tests", () => {
-  beforeEach(() => {
+  it("should render HUD correctly", () => {
     mockRenderer.reset();
     installMockRenderer();
-  });
-
-  afterEach(() => {
-    restoreRenderer();
-  });
 
-  it("should render HUD correctly", () => {
     // Import game code that uses rendering
     function renderHUD(health: number, gold: number) {
       (globalThis as any).drawText(`HP: ${health}`, {
@@ -87,7 +81,9 @@ describe("Game Visual Tests", () => {
     mockRenderer.assertCalled("drawText", 2);
 
     const calls = mockRenderer.getCalls("drawText");
-    assert(calls[0].params[0] === "HP: 100", "First text correct");
-    assert(calls[1].params[0] === "Gold: 50", "Second text correct");
+    assert.ok(calls[0].params[0] === "HP: 100", "First text correct");
+    assert.ok(calls[1].params[0] === "Gold: 50", "Second text correct");
+
+    restoreRenderer();
   });
 });

package/src/tweening/chain.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Tests for tween chaining
+ */
+
+import { describe, it, assert } from "../testing/harness.ts";
+import { sequence, parallel, stagger } from "./chain.ts";
+import { updateTweens, stopAllTweens, getActiveTweenCount, reverseTween } from "./tween.ts";
+
+describe("Tween Chaining", () => {
+  it("sequence should run tweens one after another", () => {
+    stopAllTweens();
+
+    const target1 = { x: 0 };
+    const target2 = { y: 0 };
+    const target3 = { z: 0 };
+
+    sequence([
+      { target: target1, props: { x: 100 }, duration: 1.0 },
+      { target: target2, props: { y: 100 }, duration: 1.0 },
+      { target: target3, props: { z: 100 }, duration: 1.0 },
+    ]);
+
+    // First tween should start immediately
+    updateTweens(1.0);
+    assert.equal(target1.x, 100);
+    assert.equal(target2.y, 0); // Not started yet
+    assert.equal(target3.z, 0);
+
+    // Second tween starts after first completes
+    updateTweens(1.0);
+    assert.equal(target1.x, 100);
+    assert.equal(target2.y, 100);
+    assert.equal(target3.z, 0); // Not started yet
+
+    // Third tween starts after second completes
+    updateTweens(1.0);
+    assert.equal(target1.x, 100);
+    assert.equal(target2.y, 100);
+    assert.equal(target3.z, 100);
+  });
+
+  it("parallel should run tweens simultaneously", () => {
+    stopAllTweens();
+
+    const target1 = { x: 0 };
+    const target2 = { y: 0 };
+    const target3 = { z: 0 };
+
+    parallel([
+      { target: target1, props: { x: 100 }, duration: 1.0 },
+      { target: target2, props: { y: 100 }, duration: 1.0 },
+      { target: target3, props: { z: 100 }, duration: 1.0 },
+    ]);
+
+    // All tweens should run simultaneously
+    updateTweens(0.5);
+    assert.equal(target1.x, 50);
+    assert.equal(target2.y, 50);
+    assert.equal(target3.z, 50);
+
+    updateTweens(0.5);
+    assert.equal(target1.x, 100);
+    assert.equal(target2.y, 100);
+    assert.equal(target3.z, 100);
+  });
+
+  it("stagger should delay each tween by stagger amount", () => {
+    stopAllTweens();
+
+    const target1 = { x: 0 };
+    const target2 = { y: 0 };
+    const target3 = { z: 0 };
+
+    stagger(
+      [
+        { target: target1, props: { x: 100 }, duration: 1.0 },
+        { target: target2, props: { y: 100 }, duration: 1.0 },
+        { target: target3, props: { z: 100 }, duration: 1.0 },
+      ],
+      0.5
+    );
+
+    // First tween starts immediately (delay 0)
+    updateTweens(0.5);
+    assert.equal(target1.x, 50);
+    assert.equal(target2.y, 0); // Still in delay
+    assert.equal(target3.z, 0); // Still in delay
+
+    // Second tween starts (delay 0.5), first continues
+    updateTweens(0.5);
+    assert.equal(target1.x, 100); // Complete
+    assert.equal(target2.y, 50); // Halfway
+    assert.equal(target3.z, 0); // Still in delay
+
+    // Third tween starts (delay 1.0), second continues
+    updateTweens(0.5);
+    assert.equal(target1.x, 100);
+    assert.equal(target2.y, 100); // Complete
+    assert.equal(target3.z, 50); // Halfway
+
+    // All complete
+    updateTweens(0.5);
+    assert.equal(target1.x, 100);
+    assert.equal(target2.y, 100);
+    assert.equal(target3.z, 100);
+  });
+
+  it("sequence should chain callbacks correctly", () => {
+    stopAllTweens();
+
+    let completionOrder: number[] = [];
+
+    sequence([
+      {
+        target: { x: 0 },
+        props: { x: 100 },
+        duration: 1.0,
+        options: { onComplete: () => completionOrder.push(1) },
+      },
+      {
+        target: { y: 0 },
+        props: { y: 100 },
+        duration: 1.0,
+        options: { onComplete: () => completionOrder.push(2) },
+      },
+      {
+        target: { z: 0 },
+        props: { z: 100 },
+        duration: 1.0,
+        options: { onComplete: () => completionOrder.push(3) },
+      },
+    ]);
+
+    updateTweens(1.0);
+    assert.equal(completionOrder.length, 1);
+    assert.equal(completionOrder[0], 1);
+
+    updateTweens(1.0);
+    assert.equal(completionOrder.length, 2);
+    assert.equal(completionOrder[1], 2);
+
+    updateTweens(1.0);
+    assert.equal(completionOrder.length, 3);
+    assert.equal(completionOrder[2], 3);
+  });
+
+  it("reverseTween should swap start and target values", () => {
+    stopAllTweens();
+
+    const target = { x: 0 };
+    const tweens = parallel([
+      { target, props: { x: 100 }, duration: 1.0 },
+    ]);
+
+    // Animate halfway
+    updateTweens(0.5);
+    assert.equal(target.x, 50);
+    assert.equal(getActiveTweenCount(), 1); // Tween still active
+
+    // Reverse the tween
+    reverseTween(tweens[0]);
+    assert.equal(getActiveTweenCount(), 1); // Tween still active
+
+    // Now it should animate back towards 0
+    updateTweens(0.5);
+    assert.equal(getActiveTweenCount(), 1); // Should still be active
+    assert.equal(target.x, 25); // Halfway from 50 to 0
+
+    updateTweens(0.5);
+    assert.equal(getActiveTweenCount(), 0); // Now complete
+    assert.equal(target.x, 0);
+  });
+
+  it("sequence should handle empty array", () => {
+    stopAllTweens();
+    const result = sequence([]);
+    assert.equal(result.length, 0);
+  });
+
+  it("parallel should handle empty array", () => {
+    stopAllTweens();
+    const result = parallel([]);
+    assert.equal(result.length, 0);
+  });
+
+  it("stagger should handle empty array", () => {
+    stopAllTweens();
+    const result = stagger([], 0.5);
+    assert.equal(result.length, 0);
+  });
+});

package/src/tweening/chain.ts

@@ -0,0 +1,103 @@
+/**
+ * Tween chaining utilities for composing multiple tweens.
+ *
+ * - {@link sequence} — run tweens one after another.
+ * - {@link parallel} — run tweens simultaneously.
+ * - {@link stagger} — run tweens with a staggered delay between each.
+ */
+
+import { tween, stopTween } from "./tween.ts";
+import type { Tween, TweenOptions, TweenProps } from "./types.ts";
+
+/**
+ * Configuration for a single tween within a {@link sequence}, {@link parallel}, or {@link stagger} chain.
+ */
+export interface TweenConfig {
+  /** The object whose properties will be interpolated. */
+  target: any;
+  /** Map of property names to target (end) values. */
+  props: TweenProps;
+  /** Animation duration in seconds. */
+  duration: number;
+  /** Optional tween options (easing, callbacks, etc.). */
+  options?: TweenOptions;
+}
+
+/**
+ * Run tweens one after another in sequence. Each tween starts when the
+ * previous one completes. Wraps `onComplete` callbacks to chain automatically.
+ *
+ * Note: Only the first tween is created immediately. Subsequent tweens are
+ * created lazily as each predecessor completes.
+ *
+ * @param tweens - Array of tween configurations to run in order.
+ * @returns Array of created tweens (initially contains only the first; more are added as the sequence progresses).
+ *
+ * @example
+ * ```ts
+ * sequence([
+ *   { target: sprite, props: { x: 100 }, duration: 0.5 },
+ *   { target: sprite, props: { y: 200 }, duration: 0.3 },
+ * ]);
+ * ```
+ */
+export function sequence(tweens: TweenConfig[]): Tween[] {
+  if (tweens.length === 0) return [];
+
+  const createdTweens: Tween[] = [];
+  let currentIndex = 0;
+
+  function startNext() {
+    if (currentIndex >= tweens.length) return;
+
+    const config = tweens[currentIndex];
+    const options = config.options ?? {};
+
+    // Wrap onComplete to start next tween
+    const originalOnComplete = options.onComplete;
+    options.onComplete = () => {
+      if (originalOnComplete) {
+        originalOnComplete();
+      }
+      currentIndex++;
+      startNext();
+    };
+
+    const t = tween(config.target, config.props, config.duration, options);
+    createdTweens.push(t);
+  }
+
+  // Start the first tween
+  startNext();
+
+  return createdTweens;
+}
+
+/**
+ * Run all tweens simultaneously. All tweens start immediately.
+ *
+ * @param tweens - Array of tween configurations to run in parallel.
+ * @returns Array of all created tween instances.
+ */
+export function parallel(tweens: TweenConfig[]): Tween[] {
+  return tweens.map((config) =>
+    tween(config.target, config.props, config.duration, config.options)
+  );
+}
+
+/**
+ * Run tweens with a staggered delay between each start.
+ * The i-th tween gets an additional delay of `i * staggerDelay` seconds
+ * (added to any delay already specified in its options).
+ *
+ * @param tweens - Array of tween configurations to stagger.
+ * @param staggerDelay - Delay in seconds between each successive tween start. Must be >= 0.
+ * @returns Array of all created tween instances.
+ */
+export function stagger(tweens: TweenConfig[], staggerDelay: number): Tween[] {
+  return tweens.map((config, index) => {
+    const options = { ...(config.options ?? {}) };
+    options.delay = (options.delay ?? 0) + index * staggerDelay;
+    return tween(config.target, config.props, config.duration, options);
+  });
+}