@holoscript/framework 6.0.3

package/src/ai/__tests__/StateMachine.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { StateMachine, type StateConfig, type TransitionConfig } from '../StateMachine';
+
+describe('StateMachine', () => {
+  let sm: StateMachine;
+
+  beforeEach(() => {
+    sm = new StateMachine();
+  });
+
+  // ---------------------------------------------------------------------------
+  // State Management
+  // ---------------------------------------------------------------------------
+
+  it('addState registers a state', () => {
+    sm.addState({ id: 'idle' });
+    expect(sm.getStateCount()).toBe(1);
+  });
+
+  it('removeState unregisters a state', () => {
+    sm.addState({ id: 'idle' });
+    sm.removeState('idle');
+    expect(sm.getStateCount()).toBe(0);
+  });
+
+  it('setInitialState sets current state and calls onEnter', () => {
+    const onEnter = vi.fn();
+    sm.addState({ id: 'idle', onEnter });
+    sm.setInitialState('idle');
+    expect(sm.getCurrentState()).toBe('idle');
+    expect(onEnter).toHaveBeenCalled();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Transitions
+  // ---------------------------------------------------------------------------
+
+  it('send transitions to new state', () => {
+    sm.addState({ id: 'idle' });
+    sm.addState({ id: 'walk' });
+    sm.addTransition({ from: 'idle', to: 'walk', event: 'move' });
+    sm.setInitialState('idle');
+    expect(sm.send('move')).toBe(true);
+    expect(sm.getCurrentState()).toBe('walk');
+  });
+
+  it('send returns false for unmatched event', () => {
+    sm.addState({ id: 'idle' });
+    sm.setInitialState('idle');
+    expect(sm.send('nonexistent')).toBe(false);
+    expect(sm.getCurrentState()).toBe('idle');
+  });
+
+  it('send calls onExit and onEnter', () => {
+    const onExit = vi.fn();
+    const onEnter = vi.fn();
+    sm.addState({ id: 'a', onExit });
+    sm.addState({ id: 'b', onEnter });
+    sm.addTransition({ from: 'a', to: 'b', event: 'go' });
+    sm.setInitialState('a');
+    sm.send('go');
+    expect(onExit).toHaveBeenCalled();
+    expect(onEnter).toHaveBeenCalled();
+  });
+
+  it('send respects guard condition', () => {
+    sm.addState({ id: 'locked' });
+    sm.addState({ id: 'open' });
+    sm.addTransition({
+      from: 'locked',
+      to: 'open',
+      event: 'unlock',
+      guard: (ctx) => ctx['hasKey'] === true,
+    });
+    sm.setInitialState('locked');
+
+    expect(sm.send('unlock')).toBe(false); // no key
+    sm.setContext('hasKey', true);
+    expect(sm.send('unlock')).toBe(true);
+    expect(sm.getCurrentState()).toBe('open');
+  });
+
+  it('transition action is called', () => {
+    const action = vi.fn();
+    sm.addState({ id: 'a' });
+    sm.addState({ id: 'b' });
+    sm.addTransition({ from: 'a', to: 'b', event: 'go', action });
+    sm.setInitialState('a');
+    sm.send('go');
+    expect(action).toHaveBeenCalled();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Update
+  // ---------------------------------------------------------------------------
+
+  it('update calls onUpdate of current state', () => {
+    const onUpdate = vi.fn();
+    sm.addState({ id: 'idle', onUpdate });
+    sm.setInitialState('idle');
+    sm.update();
+    expect(onUpdate).toHaveBeenCalled();
+  });
+
+  it('update does nothing with no current state', () => {
+    // Should not throw
+    sm.update();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Context
+  // ---------------------------------------------------------------------------
+
+  it('setContext / getContext stores values', () => {
+    sm.setContext('hp', 100);
+    expect(sm.getContext('hp')).toBe(100);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  it('isInState checks current state', () => {
+    sm.addState({ id: 'idle' });
+    sm.setInitialState('idle');
+    expect(sm.isInState('idle')).toBe(true);
+    expect(sm.isInState('walk')).toBe(false);
+  });
+
+  it('getHistory returns state transition history', () => {
+    sm.addState({ id: 'a' });
+    sm.addState({ id: 'b' });
+    sm.addTransition({ from: 'a', to: 'b', event: 'go' });
+    sm.setInitialState('a');
+    sm.send('go');
+    expect(sm.getHistory()).toEqual(['a', 'b']);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Hierarchy
+  // ---------------------------------------------------------------------------
+
+  it('getChildStates returns child states', () => {
+    sm.addState({ id: 'combat' });
+    sm.addState({ id: 'attack', parent: 'combat' });
+    sm.addState({ id: 'defend', parent: 'combat' });
+    const children = sm.getChildStates('combat');
+    expect(children).toContain('attack');
+    expect(children).toContain('defend');
+    expect(children).toHaveLength(2);
+  });
+
+  it('parent transitions bubble up', () => {
+    sm.addState({ id: 'combat' });
+    sm.addState({ id: 'attack', parent: 'combat' });
+    sm.addState({ id: 'idle' });
+    sm.addTransition({ from: 'combat', to: 'idle', event: 'disengage' });
+    sm.setInitialState('attack');
+    // Should find transition from parent 'combat'
+    expect(sm.send('disengage')).toBe(true);
+    expect(sm.getCurrentState()).toBe('idle');
+  });
+});

package/src/ai/__tests__/SteeringBehavior.prod.test.ts

@@ -0,0 +1,251 @@
+/**
+ * SteeringBehavior — Production Tests
+ *
+ * Tests: seek, flee, arrive, wander, avoid, blend
+ */
+
+import { describe, it, expect } from 'vitest';
+import { SteeringBehavior } from '../SteeringBehavior';
+import type { SteeringAgent } from '../SteeringBehavior';
+
+function makeAgent(overrides: Partial<SteeringAgent> = {}): SteeringAgent {
+  return {
+    position: { x: 0, z: 0 },
+    velocity: { x: 0, z: 0 },
+    maxSpeed: 5,
+    maxForce: 10,
+    mass: 1,
+    ...overrides,
+  };
+}
+
+// --- seek ---
+describe('SteeringBehavior.seek', () => {
+  it('returns zero force when already at target', () => {
+    const agent = makeAgent({ position: { x: 3, z: 4 } });
+    const force = SteeringBehavior.seek(agent, { x: 3, z: 4 });
+    expect(force.x).toBe(0);
+    expect(force.z).toBe(0);
+  });
+
+  it('desired velocity length equals maxSpeed minus current velocity', () => {
+    const agent = makeAgent({ maxSpeed: 5 });
+    const force = SteeringBehavior.seek(agent, { x: 10, z: 0 });
+    // desired = (10/10)*5 = 5, velocity = 0 → force.x = 5
+    expect(force.x).toBeCloseTo(5, 4);
+    expect(force.z).toBeCloseTo(0, 4);
+  });
+
+  it('force accounts for existing velocity', () => {
+    const agent = makeAgent({ velocity: { x: 2, z: 0 }, maxSpeed: 5 });
+    const force = SteeringBehavior.seek(agent, { x: 10, z: 0 });
+    // desired.x=5, velocity.x=2 → force.x=3
+    expect(force.x).toBeCloseTo(3, 4);
+  });
+
+  it('seeks in negative direction', () => {
+    const agent = makeAgent();
+    const force = SteeringBehavior.seek(agent, { x: -10, z: 0 });
+    expect(force.x).toBeLessThan(0);
+    expect(force.z).toBeCloseTo(0, 4);
+  });
+
+  it('returns normalized direction toward diagonal target', () => {
+    const agent = makeAgent({ maxSpeed: 1 });
+    const force = SteeringBehavior.seek(agent, { x: 1, z: 1 });
+    const mag = Math.sqrt(force.x ** 2 + force.z ** 2);
+    // desired mag = 1 (maxSpeed), velocity=0 → force mag ≈ 1
+    expect(mag).toBeCloseTo(1, 4);
+    expect(force.x).toBeCloseTo(force.z, 4);
+  });
+});
+
+// --- flee ---
+describe('SteeringBehavior.flee', () => {
+  it('is exact negation of seek result', () => {
+    const agent = makeAgent();
+    const target = { x: 5, z: 3 };
+    const seek = SteeringBehavior.seek(agent, target);
+    const flee = SteeringBehavior.flee(agent, target);
+    expect(flee.x).toBeCloseTo(-seek.x, 6);
+    expect(flee.z).toBeCloseTo(-seek.z, 6);
+  });
+
+  it('points away from target', () => {
+    const agent = makeAgent({ position: { x: 0, z: 0 } });
+    const force = SteeringBehavior.flee(agent, { x: 5, z: 0 });
+    // should steer left (negative x)
+    expect(force.x).toBeLessThan(0);
+  });
+});
+
+// --- arrive ---
+describe('SteeringBehavior.arrive', () => {
+  it('returns zero force at target', () => {
+    const agent = makeAgent({ position: { x: 5, z: 0 } });
+    const force = SteeringBehavior.arrive(agent, { x: 5, z: 0 });
+    expect(force.x).toBe(0);
+    expect(force.z).toBe(0);
+  });
+
+  it('outside slowRadius speed equals maxSpeed', () => {
+    const agent = makeAgent({ maxSpeed: 5, velocity: { x: 0, z: 0 } });
+    const slowRadius = 3;
+    // target at (100,0) is far outside slowRadius
+    const force = SteeringBehavior.arrive(agent, { x: 100, z: 0 }, slowRadius);
+    // desired.x = maxSpeed = 5 → force.x = 5
+    expect(force.x).toBeCloseTo(5, 4);
+  });
+
+  it('inside slowRadius speed proportional to distance', () => {
+    const agent = makeAgent({ maxSpeed: 10, velocity: { x: 0, z: 0 } });
+    const slowRadius = 10;
+    // target at (5, 0) → dist=5 < slowRadius=10 → speed=10*(5/10)=5
+    const force = SteeringBehavior.arrive(agent, { x: 5, z: 0 }, slowRadius);
+    expect(force.x).toBeCloseTo(5, 4);
+  });
+
+  it('deceleration force is less than full-speed seek force', () => {
+    const agent = makeAgent({ maxSpeed: 10, velocity: { x: 0, z: 0 } });
+    const seekForce = SteeringBehavior.seek(agent, { x: 1, z: 0 });
+    const arriveForce = SteeringBehavior.arrive(agent, { x: 1, z: 0 }, 20);
+    expect(Math.abs(arriveForce.x)).toBeLessThan(Math.abs(seekForce.x));
+  });
+
+  it('uses default slowRadius of 5', () => {
+    const agent = makeAgent({ maxSpeed: 10, velocity: { x: 0, z: 0 } });
+    // dist=2 < slowRadius=5 → speed=10*(2/5)=4
+    const force = SteeringBehavior.arrive(agent, { x: 2, z: 0 });
+    expect(force.x).toBeCloseTo(4, 4);
+  });
+});
+
+// --- wander ---
+describe('SteeringBehavior.wander', () => {
+  it('returns a Vec2 object with x and z', () => {
+    const agent = makeAgent({ velocity: { x: 1, z: 0 } });
+    const force = SteeringBehavior.wander(agent);
+    expect(typeof force.x).toBe('number');
+    expect(typeof force.z).toBe('number');
+  });
+
+  it('does not produce infinite or NaN values', () => {
+    const agent = makeAgent({ velocity: { x: 0, z: 0 } });
+    const force = SteeringBehavior.wander(agent);
+    expect(isFinite(force.x)).toBe(true);
+    expect(isFinite(force.z)).toBe(true);
+  });
+
+  it('multiple calls produce varied results (randomness)', () => {
+    const agent = makeAgent({ velocity: { x: 1, z: 0 } });
+    const forces = Array.from({ length: 10 }, () => SteeringBehavior.wander(agent));
+    const unique = new Set(forces.map((f) => `${f.x.toFixed(5)},${f.z.toFixed(5)}`));
+    // extremely unlikely all 10 are identical
+    expect(unique.size).toBeGreaterThan(1);
+  });
+});
+
+// --- avoid ---
+describe('SteeringBehavior.avoid', () => {
+  it('returns zero when no obstacles', () => {
+    const agent = makeAgent();
+    const force = SteeringBehavior.avoid(agent, []);
+    expect(force.x).toBe(0);
+    expect(force.z).toBe(0);
+  });
+
+  it('returns zero when obstacle is beyond lookAhead', () => {
+    const agent = makeAgent({ maxForce: 10 });
+    const force = SteeringBehavior.avoid(agent, [{ position: { x: 100, z: 0 }, radius: 1 }], 5);
+    expect(force.x).toBe(0);
+    expect(force.z).toBe(0);
+  });
+
+  it('pushes away from nearby obstacle', () => {
+    const agent = makeAgent({ position: { x: 0, z: 0 }, maxForce: 10 });
+    // obstacle at (2, 0), within lookAhead=5
+    const force = SteeringBehavior.avoid(agent, [{ position: { x: 2, z: 0 }, radius: 1 }], 5);
+    // push should be in negative x direction
+    expect(force.x).toBeLessThan(0);
+  });
+
+  it('larger obstacle radius causes stronger push', () => {
+    const agent = makeAgent({ position: { x: 0, z: 0 }, maxForce: 100 });
+    const small = SteeringBehavior.avoid(agent, [{ position: { x: 3, z: 0 }, radius: 0.5 }], 5);
+    const large = SteeringBehavior.avoid(agent, [{ position: { x: 3, z: 0 }, radius: 3 }], 5);
+    expect(Math.abs(large.x)).toBeGreaterThan(Math.abs(small.x));
+  });
+
+  it('combines forces from multiple obstacles', () => {
+    const agent = makeAgent({ position: { x: 0, z: 0 }, maxForce: 10 });
+    const oneObs = SteeringBehavior.avoid(agent, [{ position: { x: 2, z: 0 }, radius: 1 }], 5);
+    const twoObs = SteeringBehavior.avoid(
+      agent,
+      [
+        { position: { x: 2, z: 0 }, radius: 1 },
+        { position: { x: -2, z: 0 }, radius: 1 },
+      ],
+      5
+    );
+    // x-components partially cancel, but total force changes
+    expect(Math.abs(twoObs.x)).toBeLessThan(Math.abs(oneObs.x));
+  });
+});
+
+// --- blend ---
+describe('SteeringBehavior.blend', () => {
+  it('returns zero for empty outputs', () => {
+    const result = SteeringBehavior.blend([], 10);
+    expect(result.x).toBe(0);
+    expect(result.z).toBe(0);
+  });
+
+  it('single output with weight=1 passes through unclamped', () => {
+    const result = SteeringBehavior.blend(
+      [{ force: { x: 3, z: 4 }, type: 'seek', weight: 1 }],
+      100
+    );
+    expect(result.x).toBeCloseTo(3, 4);
+    expect(result.z).toBeCloseTo(4, 4);
+  });
+
+  it('clamps result magnitude to maxForce', () => {
+    const result = SteeringBehavior.blend(
+      [{ force: { x: 100, z: 0 }, type: 'seek', weight: 1 }],
+      5
+    );
+    expect(result.x).toBeCloseTo(5, 4);
+    expect(result.z).toBeCloseTo(0, 4);
+  });
+
+  it('weight scales force contribution', () => {
+    const result = SteeringBehavior.blend(
+      [{ force: { x: 10, z: 0 }, type: 'seek', weight: 0.5 }],
+      100
+    );
+    expect(result.x).toBeCloseTo(5, 4);
+  });
+
+  it('multiple outputs are summed with weights', () => {
+    const result = SteeringBehavior.blend(
+      [
+        { force: { x: 4, z: 0 }, type: 'seek', weight: 1 },
+        { force: { x: 6, z: 0 }, type: 'flee', weight: 1 },
+      ],
+      100
+    );
+    expect(result.x).toBeCloseTo(10, 4);
+  });
+
+  it('opposing forces can cancel', () => {
+    const result = SteeringBehavior.blend(
+      [
+        { force: { x: 5, z: 0 }, type: 'seek', weight: 1 },
+        { force: { x: -5, z: 0 }, type: 'flee', weight: 1 },
+      ],
+      100
+    );
+    expect(result.x).toBeCloseTo(0, 4);
+    expect(result.z).toBeCloseTo(0, 4);
+  });
+});

package/src/ai/__tests__/SteeringBehavior.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest';
+import { SteeringBehavior, SteeringAgent, SteeringOutput, Vec2 } from '../SteeringBehavior';
+
+function agent(pos: Vec2 = { x: 0, z: 0 }, vel: Vec2 = { x: 0, z: 0 }): SteeringAgent {
+  return { position: pos, velocity: vel, maxSpeed: 10, maxForce: 5, mass: 1 };
+}
+
+function mag(v: Vec2): number {
+  return Math.sqrt(v.x ** 2 + v.z ** 2);
+}
+
+describe('SteeringBehavior', () => {
+  // --- Seek ---
+  it('seek steers toward target', () => {
+    const f = SteeringBehavior.seek(agent(), { x: 10, z: 0 });
+    expect(f.x).toBeGreaterThan(0);
+  });
+
+  it('seek returns zero at target', () => {
+    const f = SteeringBehavior.seek(agent({ x: 5, z: 5 }), { x: 5, z: 5 });
+    expect(f.x).toBe(0);
+    expect(f.z).toBe(0);
+  });
+
+  it('seek accounts for current velocity', () => {
+    const a = agent({ x: 0, z: 0 }, { x: 5, z: 0 });
+    const f = SteeringBehavior.seek(a, { x: 10, z: 0 });
+    // Desired is 10 (maxSpeed), current is 5, so steering = 5
+    expect(f.x).toBe(5);
+  });
+
+  // --- Flee ---
+  it('flee steers away from target', () => {
+    const f = SteeringBehavior.flee(agent(), { x: 10, z: 0 });
+    expect(f.x).toBeLessThan(0);
+  });
+
+  it('flee is opposite of seek', () => {
+    const a = agent();
+    const seek = SteeringBehavior.seek(a, { x: 5, z: 5 });
+    const flee = SteeringBehavior.flee(a, { x: 5, z: 5 });
+    expect(flee.x).toBeCloseTo(-seek.x, 5);
+    expect(flee.z).toBeCloseTo(-seek.z, 5);
+  });
+
+  // --- Arrive ---
+  it('arrive matches seek when far away', () => {
+    const a = agent();
+    const target = { x: 100, z: 0 };
+    const arrive = SteeringBehavior.arrive(a, target, 5);
+    const seek = SteeringBehavior.seek(a, target);
+    // When far from slowRadius, arrive ≈ seek
+    expect(Math.abs(arrive.x - seek.x)).toBeLessThan(0.1);
+  });
+
+  it('arrive decelerates near target', () => {
+    const far = SteeringBehavior.arrive(agent(), { x: 100, z: 0 }, 5);
+    const near = SteeringBehavior.arrive(agent(), { x: 2, z: 0 }, 5);
+    expect(mag(near)).toBeLessThan(mag(far));
+  });
+
+  it('arrive returns zero at target', () => {
+    const f = SteeringBehavior.arrive(agent({ x: 5, z: 5 }), { x: 5, z: 5 });
+    expect(f.x).toBe(0);
+    expect(f.z).toBe(0);
+  });
+
+  // --- Wander ---
+  it('wander produces a force', () => {
+    const f = SteeringBehavior.wander(agent({ x: 0, z: 0 }, { x: 1, z: 0 }));
+    expect(mag(f)).toBeGreaterThan(0);
+  });
+
+  it('wander produces varied results', () => {
+    const a = agent({ x: 0, z: 0 }, { x: 1, z: 0 });
+    const results = new Set<string>();
+    for (let i = 0; i < 20; i++) {
+      const f = SteeringBehavior.wander(a);
+      results.add(`${f.x.toFixed(2)}_${f.z.toFixed(2)}`);
+    }
+    // Should produce more than one unique result over 20 calls
+    expect(results.size).toBeGreaterThan(1);
+  });
+
+  // --- Avoid ---
+  it('avoid pushes away from obstacle', () => {
+    const a = agent({ x: 0, z: 0 }, { x: 1, z: 0 });
+    const obstacles = [{ position: { x: 3, z: 0 }, radius: 1 }];
+    const f = SteeringBehavior.avoid(a, obstacles, 5);
+    expect(f.x).toBeLessThan(0); // Push back
+  });
+
+  it('avoid returns zero when no obstacles in range', () => {
+    const a = agent();
+    const obstacles = [{ position: { x: 100, z: 100 }, radius: 1 }];
+    const f = SteeringBehavior.avoid(a, obstacles, 5);
+    expect(f.x).toBe(0);
+    expect(f.z).toBe(0);
+  });
+
+  it('avoid handles multiple obstacles', () => {
+    const a = agent({ x: 5, z: 5 });
+    const obstacles = [
+      { position: { x: 6, z: 5 }, radius: 1 },
+      { position: { x: 5, z: 6 }, radius: 1 },
+    ];
+    const f = SteeringBehavior.avoid(a, obstacles, 5);
+    // Should push in -x and -z
+    expect(f.x).toBeLessThan(0);
+    expect(f.z).toBeLessThan(0);
+  });
+
+  // --- Blend ---
+  it('blend combines weighted outputs', () => {
+    const outputs: SteeringOutput[] = [
+      { force: { x: 10, z: 0 }, type: 'seek', weight: 0.5 },
+      { force: { x: 0, z: 10 }, type: 'flee', weight: 0.5 },
+    ];
+    const f = SteeringBehavior.blend(outputs, 100);
+    expect(f.x).toBeCloseTo(5);
+    expect(f.z).toBeCloseTo(5);
+  });
+
+  it('blend truncates to maxForce', () => {
+    const outputs: SteeringOutput[] = [{ force: { x: 100, z: 0 }, type: 'seek', weight: 1 }];
+    const f = SteeringBehavior.blend(outputs, 5);
+    expect(mag(f)).toBeCloseTo(5, 1);
+  });
+
+  it('blend with empty produces zero', () => {
+    const f = SteeringBehavior.blend([], 10);
+    expect(f.x).toBe(0);
+    expect(f.z).toBe(0);
+  });
+});

package/src/ai/__tests__/SteeringBehaviors.prod.test.ts

@@ -0,0 +1,133 @@
+/**
+ * SteeringBehaviors — Production Test Suite
+ *
+ * All methods are static. Vec3 helpers and separation/alignment/cohesion
+ * are private, so we test them indirectly through the public API:
+ * seek, flee, arrive, wander, flock, obstacleAvoidance, applyForce.
+ */
+import { describe, it, expect } from 'vitest';
+import { SteeringBehaviors, type SteeringAgent } from '../SteeringBehaviors';
+
+function agent(px = 0, py = 0, pz = 0, vx = 0, vy = 0, vz = 0): SteeringAgent {
+  return {
+    position: { x: px, y: py, z: pz },
+    velocity: { x: vx, y: vy, z: vz },
+    maxSpeed: 10,
+    maxForce: 5,
+    mass: 1,
+  };
+}
+
+function len(v: { x: number; y: number; z: number }): number {
+  return Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z);
+}
+
+describe('SteeringBehaviors — Production', () => {
+  // ─── Seek ─────────────────────────────────────────────────────────
+  it('seek returns force toward target', () => {
+    const force = SteeringBehaviors.seek(agent(), { x: 10, y: 0, z: 0 });
+    expect(force.x).toBeGreaterThan(0);
+  });
+
+  it('seek force is capped by maxForce', () => {
+    const force = SteeringBehaviors.seek(agent(), { x: 1000, y: 0, z: 0 });
+    expect(len(force)).toBeLessThanOrEqual(5.01);
+  });
+
+  // ─── Flee ─────────────────────────────────────────────────────────
+  it('flee returns force away from threat', () => {
+    const force = SteeringBehaviors.flee(agent(), { x: 10, y: 0, z: 0 });
+    expect(force.x).toBeLessThan(0);
+  });
+
+  // ─── Arrive ───────────────────────────────────────────────────────
+  it('arrive force decreases near target', () => {
+    const farForce = SteeringBehaviors.arrive(agent(0, 0, 0), { x: 10, y: 0, z: 0 }, 5);
+    const nearForce = SteeringBehaviors.arrive(agent(9, 0, 0), { x: 10, y: 0, z: 0 }, 5);
+    expect(len(nearForce)).toBeLessThanOrEqual(len(farForce) + 0.01);
+  });
+
+  it('arrive returns zero at target', () => {
+    const force = SteeringBehaviors.arrive(agent(10, 0, 0), { x: 10, y: 0, z: 0 }, 5);
+    expect(len(force)).toBeCloseTo(0, 2);
+  });
+
+  // ─── Wander ───────────────────────────────────────────────────────
+  it('wander returns force and new angle', () => {
+    const result = SteeringBehaviors.wander(agent(0, 0, 0, 1, 0, 0), 5, 2, 0.5, 0);
+    expect(result.force).toBeDefined();
+    expect(typeof result.newAngle).toBe('number');
+  });
+
+  // ─── Flock ────────────────────────────────────────────────────────
+  it('flock combines separation/alignment/cohesion', () => {
+    const a = agent(0, 0, 0, 1, 0, 0);
+    const neighbors = [agent(2, 0, 0, 1, 0, 0), agent(-2, 0, 0, 1, 0, 0)];
+    const config = {
+      separationWeight: 1,
+      alignmentWeight: 1,
+      cohesionWeight: 1,
+      neighborRadius: 10,
+    };
+    const force = SteeringBehaviors.flock(a, neighbors, config);
+    expect(typeof force.x).toBe('number');
+    expect(typeof force.y).toBe('number');
+    expect(typeof force.z).toBe('number');
+  });
+
+  it('flock returns zero with no neighbors in range', () => {
+    const a = agent(0, 0, 0);
+    const neighbors = [agent(1000, 0, 0)]; // way out of range
+    const config = {
+      separationWeight: 1,
+      alignmentWeight: 1,
+      cohesionWeight: 1,
+      neighborRadius: 5,
+    };
+    const force = SteeringBehaviors.flock(a, neighbors, config);
+    expect(force.x).toBe(0);
+    expect(force.y).toBe(0);
+    expect(force.z).toBe(0);
+  });
+
+  it('flock excludes self from neighbors', () => {
+    const a = agent(0, 0, 0);
+    const config = {
+      separationWeight: 1,
+      alignmentWeight: 1,
+      cohesionWeight: 1,
+      neighborRadius: 10,
+    };
+    const force = SteeringBehaviors.flock(a, [a], config); // self is neighbor
+    expect(force.x).toBe(0); // should be zero since self filtered out
+  });
+
+  // ─── Obstacle Avoidance ───────────────────────────────────────────
+  it('obstacleAvoidance returns zero when no obstacles near', () => {
+    const a = agent(0, 0, 0, 1, 0, 0);
+    const obstacles = [{ center: { x: 100, y: 0, z: 0 }, radius: 1 }];
+    const force = SteeringBehaviors.obstacleAvoidance(a, obstacles, 5);
+    expect(len(force)).toBe(0);
+  });
+
+  it('obstacleAvoidance returns force near obstacle', () => {
+    const a = agent(0, 0, 0, 1, 0, 0);
+    const obstacles = [{ center: { x: 3, y: 0, z: 0 }, radius: 10 }]; // huge obstacle right ahead
+    const force = SteeringBehaviors.obstacleAvoidance(a, obstacles, 5);
+    expect(len(force)).toBeGreaterThan(0);
+  });
+
+  // ─── Apply Force ──────────────────────────────────────────────────
+  it('applyForce updates position and velocity', () => {
+    const a = agent(0, 0, 0, 0, 0, 0);
+    SteeringBehaviors.applyForce(a, { x: 10, y: 0, z: 0 }, 1);
+    expect(a.velocity.x).toBeGreaterThan(0);
+    expect(a.position.x).toBeGreaterThan(0);
+  });
+
+  it('applyForce caps velocity to maxSpeed', () => {
+    const a = agent(0, 0, 0, 0, 0, 0);
+    SteeringBehaviors.applyForce(a, { x: 1000, y: 0, z: 0 }, 1);
+    expect(len(a.velocity)).toBeLessThanOrEqual(a.maxSpeed + 0.01);
+  });
+});