@holoscript/framework 6.0.3

package/src/swarm/spatial/__tests__/FlockingBehavior.prod.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from 'vitest';
+import { FlockingBehavior } from '../FlockingBehavior';
+import { Vector3 } from '../Vector3';
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function mkFlock(cfg?: ConstructorParameters<typeof FlockingBehavior>[0]) {
+  return new FlockingBehavior(cfg);
+}
+
+function v(x: number, y = 0, z = 0) {
+  return new Vector3(x, y, z);
+}
+
+// ─── tests ───────────────────────────────────────────────────────────────────
+
+describe('FlockingBehavior — defaultConfig', () => {
+  it('separationRadius = 25', () => expect(mkFlock().getConfig().separationRadius).toBe(25));
+  it('alignmentRadius = 50', () => expect(mkFlock().getConfig().alignmentRadius).toBe(50));
+  it('cohesionRadius = 50', () => expect(mkFlock().getConfig().cohesionRadius).toBe(50));
+  it('maxSpeed = 4', () => expect(mkFlock().getConfig().maxSpeed).toBe(4));
+  it('maxForce = 0.1', () => expect(mkFlock().getConfig().maxForce).toBe(0.1));
+  it('boundaryMode = wrap', () => expect(mkFlock().getConfig().boundaryMode).toBe('wrap'));
+});
+
+describe('FlockingBehavior — boid CRUD', () => {
+  it('addBoid stores boid', () => {
+    const flock = mkFlock();
+    flock.addBoid('b1', v(0));
+    expect(flock.getBoid('b1')).toBeDefined();
+  });
+  it('addBoid returns boid object', () => {
+    const flock = mkFlock();
+    const b = flock.addBoid('b2', v(1, 2, 3));
+    expect(b.id).toBe('b2');
+  });
+  it('addBoid sets position correctly', () => {
+    const flock = mkFlock();
+    flock.addBoid('b3', v(5, 6, 7));
+    const b = flock.getBoid('b3')!;
+    expect(b.position.x).toBe(5);
+    expect(b.position.y).toBe(6);
+  });
+  it('addBoid with explicit velocity uses it', () => {
+    const flock = mkFlock();
+    flock.addBoid('b4', v(0), v(1, 0, 0));
+    expect(flock.getBoid('b4')!.velocity.x).toBe(1);
+  });
+  it('removeBoid returns true', () => {
+    const flock = mkFlock();
+    flock.addBoid('b5', v(0));
+    expect(flock.removeBoid('b5')).toBe(true);
+  });
+  it('removeBoid deletes boid', () => {
+    const flock = mkFlock();
+    flock.addBoid('b6', v(0));
+    flock.removeBoid('b6');
+    expect(flock.getBoid('b6')).toBeUndefined();
+  });
+  it('removeBoid on missing id returns false', () => {
+    expect(mkFlock().removeBoid('nope')).toBe(false);
+  });
+  it('getAllBoids returns all boids', () => {
+    const flock = mkFlock();
+    flock.addBoid('a', v(0));
+    flock.addBoid('b', v(1));
+    expect(flock.getAllBoids()).toHaveLength(2);
+  });
+  it('setBoidPosition moves boid', () => {
+    const flock = mkFlock();
+    flock.addBoid('m', v(0));
+    flock.setBoidPosition('m', v(99, 0, 0));
+    expect(flock.getBoid('m')!.position.x).toBe(99);
+  });
+  it('setBoidPosition no-op for missing id', () => {
+    expect(() => mkFlock().setBoidPosition('none', v(1))).not.toThrow();
+  });
+});
+
+describe('FlockingBehavior — findNeighbors', () => {
+  it('finds boid within radius', () => {
+    const flock = mkFlock();
+    const b1 = flock.addBoid('A', v(0), v(0));
+    flock.addBoid('B', v(10), v(0));
+    const neighbors = flock.findNeighbors(b1, 20);
+    expect(neighbors.some((n) => n.id === 'B')).toBe(true);
+  });
+  it('excludes boid outside radius', () => {
+    const flock = mkFlock();
+    const b1 = flock.addBoid('A', v(0), v(0));
+    flock.addBoid('B', v(100), v(0));
+    const neighbors = flock.findNeighbors(b1, 20);
+    expect(neighbors.some((n) => n.id === 'B')).toBe(false);
+  });
+  it('excludes self from neighbors', () => {
+    const flock = mkFlock();
+    const b1 = flock.addBoid('self', v(0), v(0));
+    const neighbors = flock.findNeighbors(b1, 999);
+    expect(neighbors.every((n) => n.id !== 'self')).toBe(true);
+  });
+});
+
+describe('FlockingBehavior — seek / flee / arrive', () => {
+  it('seek returns non-zero force toward target', () => {
+    const flock = mkFlock();
+    const boid = flock.addBoid('s', v(0), v(0));
+    const force = flock.seek(boid, v(100, 0, 0));
+    expect(force.x).toBeGreaterThan(0);
+  });
+  it('flee returns opposite direction from seek', () => {
+    const flock = mkFlock();
+    const boid = flock.addBoid('f', v(0), v(0));
+    const seekF = flock.seek(boid, v(100, 0, 0));
+    const fleeF = flock.flee(boid, v(100, 0, 0));
+    expect(Math.sign(fleeF.x)).toBe(-Math.sign(seekF.x));
+  });
+  it('arrive returns zero force when at target', () => {
+    const flock = mkFlock({ maxForce: 1 });
+    const boid = flock.addBoid('a', v(0), v(0));
+    const force = flock.arrive(boid, v(0, 0, 0), 10);
+    expect(force.magnitude()).toBeCloseTo(0, 5);
+  });
+  it('arrive slows within slowingRadius', () => {
+    const flock = mkFlock({ maxSpeed: 4, maxForce: 1 });
+    // Place boid exactly at slowingRadius/2 from target
+    const boid = flock.addBoid('slow', v(5), v(0));
+    const fullSeekForce = flock.seek(boid, v(10)).magnitude();
+    const arriveForce = flock.arrive(boid, v(10), 10).magnitude(); // inside slowing zone
+    // Arrive magnitude should be <= full seek magnitude when slowing
+    expect(arriveForce).toBeLessThanOrEqual(fullSeekForce + 0.001);
+  });
+});
+
+describe('FlockingBehavior — separate / align / cohere', () => {
+  it('separate returns zero when no close neighbors', () => {
+    const flock = mkFlock({ separationRadius: 5 });
+    const boid = flock.addBoid('me', v(0), v(0));
+    const far = flock.addBoid('far', v(100), v(0));
+    const force = flock.separate(boid, [boid, far]);
+    expect(force.magnitude()).toBeCloseTo(0, 5);
+  });
+  it('separate returns force away from close neighbor', () => {
+    const flock = mkFlock({ separationRadius: 30, maxSpeed: 4, maxForce: 1 });
+    const boid = flock.addBoid('me', v(0), v(0));
+    const close = flock.addBoid('close', v(5), v(0));
+    const force = flock.separate(boid, [boid, close]);
+    // Should push left (away from +x)
+    expect(force.x).toBeLessThan(0);
+  });
+  it('align returns zero when no in-radius neighbors', () => {
+    const flock = mkFlock({ alignmentRadius: 5 });
+    const boid = flock.addBoid('me', v(0), v(0));
+    const far = flock.addBoid('far', v(100), v(0));
+    const force = flock.align(boid, [boid, far]);
+    expect(force.magnitude()).toBeCloseTo(0, 5);
+  });
+  it('cohere steers toward center of nearby neighbors', () => {
+    const flock = mkFlock({ cohesionRadius: 200, maxSpeed: 4, maxForce: 1 });
+    const boid = flock.addBoid('me', v(0), v(0));
+    flock.addBoid('r1', v(100), v(0));
+    flock.addBoid('r2', v(100), v(0));
+    const all = flock.getAllBoids();
+    const force = flock.cohere(boid, all);
+    // Center of other boids is at x=100, so cohere should push +x
+    expect(force.x).toBeGreaterThan(0);
+  });
+});
+
+describe('FlockingBehavior — update', () => {
+  it('update() runs without throwing', () => {
+    const flock = mkFlock();
+    flock.addBoid('u1', v(0), v(1, 0, 0));
+    flock.addBoid('u2', v(2), v(-1, 0, 0));
+    expect(() => flock.update()).not.toThrow();
+  });
+  it('update() moves boid positions', () => {
+    const flock = mkFlock();
+    flock.addBoid('m', v(0), v(1, 0, 0));
+    const before = flock.getBoid('m')!.position.x;
+    flock.update();
+    expect(flock.getBoid('m')!.position.x).not.toBe(before);
+  });
+  it('applyForce adds to acceleration', () => {
+    const flock = mkFlock();
+    flock.addBoid('af', v(0), v(0));
+    flock.applyForce('af', v(5, 0, 0));
+    expect(flock.getBoid('af')!.acceleration.x).toBe(5);
+  });
+  it('applyForceToAll affects all boids', () => {
+    const flock = mkFlock();
+    flock.addBoid('x1', v(0), v(0));
+    flock.addBoid('x2', v(5), v(0));
+    flock.applyForceToAll(v(0, 0, 2));
+    flock.getAllBoids().forEach((b) => expect(b.acceleration.z).toBe(2));
+  });
+});
+
+describe('FlockingBehavior — analytics', () => {
+  it('getFlockCenter returns zero for empty flock', () => {
+    const c = mkFlock().getFlockCenter();
+    expect(c.magnitude()).toBeCloseTo(0, 5);
+  });
+  it('getFlockCenter returns centroid', () => {
+    const flock = mkFlock();
+    flock.addBoid('a', v(0), v(0));
+    flock.addBoid('b', v(10), v(0));
+    expect(flock.getFlockCenter().x).toBeCloseTo(5, 5);
+  });
+  it('getFlockSpread = 0 for single boid', () => {
+    const flock = mkFlock();
+    flock.addBoid('solo', v(0), v(0));
+    expect(flock.getFlockSpread()).toBe(0);
+  });
+  it('getFlockSpread > 0 for spread boids', () => {
+    const flock = mkFlock();
+    flock.addBoid('a', v(0), v(0));
+    flock.addBoid('b', v(100), v(0));
+    expect(flock.getFlockSpread()).toBeGreaterThan(0);
+  });
+  it('getFlockDirection returns unit vector', () => {
+    const flock = mkFlock();
+    flock.addBoid('d', v(0), v(3, 0, 0));
+    const dir = flock.getFlockDirection();
+    expect(dir.magnitude()).toBeCloseTo(1, 5);
+  });
+});
+
+describe('FlockingBehavior — config', () => {
+  it('setConfig updates a field', () => {
+    const flock = mkFlock();
+    flock.setConfig({ maxSpeed: 10 });
+    expect(flock.getConfig().maxSpeed).toBe(10);
+  });
+  it('setConfig preserves unchanged fields', () => {
+    const flock = mkFlock();
+    flock.setConfig({ maxSpeed: 10 });
+    expect(flock.getConfig().separationRadius).toBe(25);
+  });
+});

package/src/swarm/spatial/__tests__/FlockingBehavior.test.ts

@@ -0,0 +1,298 @@
+/**
+ * FlockingBehavior Tests
+ * HoloScript v3.2 - Autonomous Agent Swarms
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { FlockingBehavior } from '../FlockingBehavior';
+import { Vector3 } from '../Vector3';
+
+describe('FlockingBehavior', () => {
+  let flock: FlockingBehavior;
+
+  beforeEach(() => {
+    flock = new FlockingBehavior({
+      separationRadius: 25,
+      alignmentRadius: 50,
+      cohesionRadius: 50,
+      maxSpeed: 4,
+      maxForce: 0.1,
+    });
+  });
+
+  describe('boid management', () => {
+    it('should add a boid', () => {
+      const boid = flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      expect(boid.id).toBe('boid-1');
+      expect(boid.position.x).toBe(0);
+    });
+
+    it('should add boid with velocity', () => {
+      const boid = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(1, 0, 0));
+      expect(boid.velocity.x).toBe(1);
+    });
+
+    it('should generate random velocity if not provided', () => {
+      const boid = flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      const mag = boid.velocity.magnitude();
+      expect(mag).toBeGreaterThan(0);
+    });
+
+    it('should remove a boid', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      expect(flock.removeBoid('boid-1')).toBe(true);
+      expect(flock.getBoid('boid-1')).toBeUndefined();
+    });
+
+    it('should get all boids', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      flock.addBoid('boid-2', new Vector3(10, 0, 0));
+      expect(flock.getAllBoids()).toHaveLength(2);
+    });
+
+    it('should set boid position', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      flock.setBoidPosition('boid-1', new Vector3(100, 100, 100));
+      const boid = flock.getBoid('boid-1');
+      expect(boid?.position.x).toBe(100);
+    });
+  });
+
+  describe('separation', () => {
+    it('should steer away from close neighbors', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const boid2 = flock.addBoid('boid-2', new Vector3(10, 0, 0), new Vector3(0, 0, 0));
+
+      const steer = flock.separate(boid1, [boid2]);
+      // Should steer away (negative x direction)
+      expect(steer.x).toBeLessThan(0);
+    });
+
+    it('should return zero if no neighbors in separation radius', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const boid2 = flock.addBoid('boid-2', new Vector3(100, 0, 0), new Vector3(0, 0, 0));
+
+      const steer = flock.separate(boid1, [boid2]);
+      expect(steer.magnitude()).toBe(0);
+    });
+  });
+
+  describe('alignment', () => {
+    it('should steer toward average heading of neighbors', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const boid2 = flock.addBoid('boid-2', new Vector3(10, 0, 0), new Vector3(1, 0, 0));
+      const boid3 = flock.addBoid('boid-3', new Vector3(-10, 0, 0), new Vector3(1, 0, 0));
+
+      const steer = flock.align(boid1, [boid2, boid3]);
+      // Should align with positive x direction
+      expect(steer.x).toBeGreaterThan(0);
+    });
+
+    it('should return zero if no neighbors in alignment radius', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const boid2 = flock.addBoid('boid-2', new Vector3(100, 0, 0), new Vector3(1, 0, 0));
+
+      const steer = flock.align(boid1, [boid2]);
+      expect(steer.magnitude()).toBe(0);
+    });
+  });
+
+  describe('cohesion', () => {
+    it('should steer toward center of neighbors', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const boid2 = flock.addBoid('boid-2', new Vector3(30, 0, 0), new Vector3(0, 0, 0));
+      const boid3 = flock.addBoid('boid-3', new Vector3(30, 30, 0), new Vector3(0, 0, 0));
+
+      const steer = flock.cohere(boid1, [boid2, boid3]);
+      // Center is at (30, 15, 0), so should steer positive x and y
+      expect(steer.x).toBeGreaterThan(0);
+      expect(steer.y).toBeGreaterThan(0);
+    });
+
+    it('should return zero if no neighbors in cohesion radius', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const boid2 = flock.addBoid('boid-2', new Vector3(100, 0, 0), new Vector3(0, 0, 0));
+
+      const steer = flock.cohere(boid1, [boid2]);
+      expect(steer.magnitude()).toBe(0);
+    });
+  });
+
+  describe('steering behaviors', () => {
+    it('should seek target', () => {
+      const boid = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const target = new Vector3(100, 0, 0);
+
+      const steer = flock.seek(boid, target);
+      expect(steer.x).toBeGreaterThan(0);
+    });
+
+    it('should flee from target', () => {
+      const boid = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const target = new Vector3(100, 0, 0);
+
+      const steer = flock.flee(boid, target);
+      expect(steer.x).toBeLessThan(0);
+    });
+
+    it('should arrive and slow down near target', () => {
+      // Use high maxForce to avoid clamping
+      const arrivalFlock = new FlockingBehavior({ maxSpeed: 4, maxForce: 10 });
+      const boid = arrivalFlock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      const nearTarget = new Vector3(2, 0, 0); // Very close, within slowingRadius
+      const farTarget = new Vector3(100, 0, 0);
+
+      const nearSteer = arrivalFlock.arrive(boid, nearTarget, 20);
+      const farSteer = arrivalFlock.arrive(boid, farTarget, 20);
+
+      // Near target should have smaller force due to slowing behavior
+      expect(nearSteer.magnitude()).toBeLessThan(farSteer.magnitude());
+    });
+  });
+
+  describe('neighbors', () => {
+    it('should find neighbors within radius', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      flock.addBoid('boid-2', new Vector3(10, 0, 0));
+      flock.addBoid('boid-3', new Vector3(100, 0, 0));
+
+      const neighbors = flock.findNeighbors(boid1, 50);
+      expect(neighbors).toHaveLength(1);
+      expect(neighbors[0].id).toBe('boid-2');
+    });
+
+    it('should exclude self from neighbors', () => {
+      const boid1 = flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      flock.addBoid('boid-2', new Vector3(0, 0, 0)); // Same position
+
+      const neighbors = flock.findNeighbors(boid1, 50);
+      expect(neighbors).toHaveLength(1);
+      expect(neighbors[0].id).toBe('boid-2');
+    });
+  });
+
+  describe('update', () => {
+    it('should update all boids', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(1, 0, 0));
+      flock.addBoid('boid-2', new Vector3(10, 0, 0), new Vector3(1, 0, 0));
+
+      const initialPos = flock.getBoid('boid-1')!.position.clone();
+      flock.update();
+      const newPos = flock.getBoid('boid-1')!.position;
+
+      expect(newPos.equals(initialPos)).toBe(false);
+    });
+
+    it('should respect max speed', () => {
+      const boid = flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(100, 0, 0));
+      flock.update();
+
+      expect(boid.velocity.magnitude()).toBeLessThanOrEqual(flock.getConfig().maxSpeed);
+    });
+  });
+
+  describe('external forces', () => {
+    it('should apply force to single boid', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      flock.applyForce('boid-1', new Vector3(1, 0, 0));
+
+      const boid = flock.getBoid('boid-1')!;
+      expect(boid.acceleration.x).toBe(1);
+    });
+
+    it('should apply force to all boids', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(0, 0, 0));
+      flock.addBoid('boid-2', new Vector3(10, 0, 0), new Vector3(0, 0, 0));
+      flock.applyForceToAll(new Vector3(0, 1, 0));
+
+      expect(flock.getBoid('boid-1')!.acceleration.y).toBe(1);
+      expect(flock.getBoid('boid-2')!.acceleration.y).toBe(1);
+    });
+  });
+
+  describe('flock statistics', () => {
+    it('should calculate flock center', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      flock.addBoid('boid-2', new Vector3(10, 0, 0));
+      flock.addBoid('boid-3', new Vector3(20, 0, 0));
+
+      const center = flock.getFlockCenter();
+      expect(center.x).toBe(10);
+      expect(center.y).toBe(0);
+    });
+
+    it('should return zero for empty flock center', () => {
+      const center = flock.getFlockCenter();
+      expect(center.magnitude()).toBe(0);
+    });
+
+    it('should calculate flock direction', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0), new Vector3(1, 0, 0));
+      flock.addBoid('boid-2', new Vector3(10, 0, 0), new Vector3(1, 0, 0));
+
+      const direction = flock.getFlockDirection();
+      expect(direction.x).toBeCloseTo(1);
+      expect(direction.y).toBeCloseTo(0);
+    });
+
+    it('should calculate flock spread', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      flock.addBoid('boid-2', new Vector3(10, 0, 0));
+      flock.addBoid('boid-3', new Vector3(-10, 0, 0));
+
+      const spread = flock.getFlockSpread();
+      expect(spread).toBe(10);
+    });
+
+    it('should return zero spread for single boid', () => {
+      flock.addBoid('boid-1', new Vector3(0, 0, 0));
+      expect(flock.getFlockSpread()).toBe(0);
+    });
+  });
+
+  describe('boundaries', () => {
+    it('should wrap positions', () => {
+      const boundedFlock = new FlockingBehavior({
+        boundaryMode: 'wrap',
+        worldBounds: {
+          min: new Vector3(0, 0, 0),
+          max: new Vector3(100, 100, 100),
+        },
+      });
+
+      const boid = boundedFlock.addBoid('boid-1', new Vector3(99, 50, 50), new Vector3(10, 0, 0));
+      boundedFlock.update();
+
+      // Should wrap to low x values
+      expect(boid.position.x).toBeLessThan(100);
+    });
+
+    it('should bounce off boundaries', () => {
+      const boundedFlock = new FlockingBehavior({
+        boundaryMode: 'bounce',
+        worldBounds: {
+          min: new Vector3(0, 0, 0),
+          max: new Vector3(100, 100, 100),
+        },
+      });
+
+      const boid = boundedFlock.addBoid('boid-1', new Vector3(99, 50, 50), new Vector3(10, 0, 0));
+      boundedFlock.update();
+
+      // Velocity should be reversed
+      expect(boid.velocity.x).toBeLessThan(0);
+    });
+  });
+
+  describe('configuration', () => {
+    it('should update configuration', () => {
+      flock.setConfig({ maxSpeed: 10 });
+      expect(flock.getConfig().maxSpeed).toBe(10);
+    });
+
+    it('should preserve existing config values', () => {
+      flock.setConfig({ maxSpeed: 10 });
+      expect(flock.getConfig().separationRadius).toBe(25);
+    });
+  });
+});