@boltr/geometry 0.1.0

package/__tests__/movement.test.js

@@ -0,0 +1,159 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  isPositionOccupied,
+  isInFriendlyExclusionZone,
+  isInEnemyExclusionZone,
+  isPathBlockedByEnemies,
+  validateWaypointPath,
+} = require('../src/movement');
+
+const makeUnit = (overrides) => ({
+  unit_index: 0, player_id: 1, position: { x: 10, y: 10 },
+  base_radius: 0.5, eliminated: false, ...overrides,
+});
+
+describe('isPositionOccupied', () => {
+  it('detects overlap with sum of radii', () => {
+    const units = [makeUnit({ base_radius: 0.5 })];
+    // Distance 0.8 < 0.5 + 0.5 = 1.0 → occupied
+    assert.ok(isPositionOccupied({ x: 10.8, y: 10 }, 0.5, units));
+  });
+
+  it('returns false when no overlap', () => {
+    const units = [makeUnit({ base_radius: 0.5 })];
+    // Distance 2 > 0.5 + 0.5 = 1.0
+    assert.ok(!isPositionOccupied({ x: 12, y: 10 }, 0.5, units));
+  });
+
+  it('excludes self by unit_index', () => {
+    const units = [makeUnit({ unit_index: 0, base_radius: 0.5 })];
+    assert.ok(!isPositionOccupied({ x: 10, y: 10 }, 0.5, units, 0));
+  });
+
+  it('uses larger base_radius', () => {
+    const units = [makeUnit({ base_radius: 1.0 })];
+    // Distance 1.2 < 1.0 + 0.5 = 1.5 → occupied
+    assert.ok(isPositionOccupied({ x: 11.2, y: 10 }, 0.5, units));
+  });
+});
+
+describe('isInFriendlyExclusionZone', () => {
+  it('returns true when friendly bases would overlap', () => {
+    const op = makeUnit({ unit_index: 0, player_id: 1, base_radius: 0.5 });
+    const units = [
+      op,
+      makeUnit({ unit_index: 1, player_id: 1, position: { x: 15, y: 10 }, base_radius: 0.5 }),
+    ];
+    // Try to end at 14.5 → distance 0.5 < 0.5 + 0.5 = 1.0
+    assert.ok(isInFriendlyExclusionZone({ x: 14.5, y: 10 }, op, units));
+  });
+
+  it('returns false for enemy units', () => {
+    const op = makeUnit({ unit_index: 0, player_id: 1, base_radius: 0.5 });
+    const units = [
+      op,
+      makeUnit({ unit_index: 1, player_id: 2, position: { x: 10.5, y: 10 }, base_radius: 0.5 }),
+    ];
+    assert.ok(!isInFriendlyExclusionZone({ x: 10.5, y: 10 }, op, units));
+  });
+});
+
+describe('isPathBlockedByEnemies', () => {
+  it('detects enemy blocking the path', () => {
+    const op = makeUnit({ unit_index: 0, player_id: 1 });
+    const enemy = makeUnit({ unit_index: 2, player_id: 2, position: { x: 5, y: 10 }, base_radius: 0.5 });
+    const units = [op, enemy];
+    // Path from (0, 10) to (10, 10) passes through enemy at (5, 10)
+    // Blocking radius = 0.5 + 1.0 = 1.5
+    const result = isPathBlockedByEnemies({ x: 0, y: 10 }, { x: 10, y: 10 }, op, units);
+    assert.ok(result.blocked);
+    assert.equal(result.blocker.unit_index, 2);
+  });
+
+  it('exempts charge target', () => {
+    const op = makeUnit({ unit_index: 0, player_id: 1 });
+    const enemy = makeUnit({ unit_index: 2, player_id: 2, position: { x: 5, y: 10 }, base_radius: 0.5 });
+    const units = [op, enemy];
+    const result = isPathBlockedByEnemies({ x: 0, y: 10 }, { x: 10, y: 10 }, op, units, 2);
+    assert.ok(!result.blocked);
+  });
+
+  it('ignores friendly units', () => {
+    const op = makeUnit({ unit_index: 0, player_id: 1 });
+    const friendly = makeUnit({ unit_index: 1, player_id: 1, position: { x: 5, y: 10 } });
+    const units = [op, friendly];
+    const result = isPathBlockedByEnemies({ x: 0, y: 10 }, { x: 10, y: 10 }, op, units);
+    assert.ok(!result.blocked);
+  });
+});
+
+describe('validateWaypointPath', () => {
+  const op = makeUnit({ unit_index: 0, player_id: 1, base_radius: 0.5 });
+  const emptyUnits = [op];
+
+  it('validates a simple single-waypoint path', () => {
+    const result = validateWaypointPath(
+      { x: 0, y: 10 }, [{ x: 3, y: 10 }], 0.5, 6, op, emptyUnits, [], null
+    );
+    assert.ok(result.valid);
+    assert.ok(Math.abs(result.totalDistance - 3) < 0.001);
+  });
+
+  it('validates multi-waypoint path', () => {
+    const result = validateWaypointPath(
+      { x: 0, y: 0 }, [{ x: 3, y: 0 }, { x: 3, y: 4 }], 0.5, 10, op, emptyUnits, [], null
+    );
+    assert.ok(result.valid);
+    assert.ok(Math.abs(result.totalDistance - 7) < 0.001);
+  });
+
+  it('rejects path exceeding max distance', () => {
+    const result = validateWaypointPath(
+      { x: 0, y: 0 }, [{ x: 10, y: 0 }], 0.5, 6, op, emptyUnits, [], null
+    );
+    assert.ok(!result.valid);
+    assert.ok(result.error.includes('exceeds maximum'));
+  });
+
+  it('rejects empty waypoints', () => {
+    const result = validateWaypointPath(
+      { x: 0, y: 0 }, [], 0.5, 6, op, emptyUnits, [], null
+    );
+    assert.ok(!result.valid);
+  });
+
+  it('adds per-piece terrain penalty', () => {
+    const terrain = [
+      { type: 'lightCover', vertices: [{ x: 1, y: -2 }, { x: 2, y: -2 }, { x: 2, y: 2 }, { x: 1, y: 2 }] },
+      { type: 'difficult', vertices: [{ x: 3, y: -2 }, { x: 4, y: -2 }, { x: 4, y: 2 }, { x: 3, y: 2 }] },
+    ];
+    // Path crosses 2 pieces → +4" penalty, total = 5 + 4 = 9
+    const result = validateWaypointPath(
+      { x: 0, y: 0 }, [{ x: 5, y: 0 }], 0.5, 8, op, emptyUnits, terrain, null
+    );
+    assert.ok(!result.valid);
+    assert.ok(result.error.includes('4 inches penalty'));
+  });
+
+  it('rejects path blocked by enemy', () => {
+    const enemy = makeUnit({ unit_index: 2, player_id: 2, position: { x: 5, y: 0 }, base_radius: 0.5 });
+    const units = [op, enemy];
+    const result = validateWaypointPath(
+      { x: 0, y: 0 }, [{ x: 10, y: 0 }], 0.5, 15, op, units, [], null
+    );
+    assert.ok(!result.valid);
+    assert.ok(result.error.includes('blocked by enemy'));
+  });
+
+  it('rejects path ending on blocked terrain', () => {
+    const terrain = [
+      { type: 'heavyCover', vertices: [{ x: 4, y: -2 }, { x: 6, y: -2 }, { x: 6, y: 2 }, { x: 4, y: 2 }] },
+    ];
+    const result = validateWaypointPath(
+      { x: 0, y: 0 }, [{ x: 5, y: 0 }], 0.5, 10, op, emptyUnits, terrain, null
+    );
+    assert.ok(!result.valid);
+    assert.ok(result.error.includes('heavyCover'));
+  });
+});

package/__tests__/primitives.test.js

@@ -0,0 +1,118 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  calculateDistance,
+  isPointInPolygon,
+  lineSegmentsIntersect,
+  lineIntersectsPolygon,
+  pointToLineSegmentDistance,
+  pointToPolygonDistance,
+  lineSegmentIntersectsCircle,
+  isBaseOverlappingTerrain,
+} = require('../src/primitives');
+
+const square = [
+  { x: 0, y: 0 }, { x: 4, y: 0 }, { x: 4, y: 4 }, { x: 0, y: 4 },
+];
+
+describe('calculateDistance', () => {
+  it('returns 0 for same point', () => {
+    assert.equal(calculateDistance({ x: 1, y: 1 }, { x: 1, y: 1 }), 0);
+  });
+  it('calculates horizontal distance', () => {
+    assert.equal(calculateDistance({ x: 0, y: 0 }, { x: 3, y: 0 }), 3);
+  });
+  it('calculates diagonal distance', () => {
+    const d = calculateDistance({ x: 0, y: 0 }, { x: 3, y: 4 });
+    assert.ok(Math.abs(d - 5) < 0.0001);
+  });
+});
+
+describe('isPointInPolygon', () => {
+  it('returns true for point inside', () => {
+    assert.ok(isPointInPolygon({ x: 2, y: 2 }, square));
+  });
+  it('returns false for point outside', () => {
+    assert.ok(!isPointInPolygon({ x: 5, y: 5 }, square));
+  });
+  it('returns false for invalid vertices', () => {
+    assert.ok(!isPointInPolygon({ x: 0, y: 0 }, null));
+    assert.ok(!isPointInPolygon({ x: 0, y: 0 }, []));
+    assert.ok(!isPointInPolygon({ x: 0, y: 0 }, [{ x: 0, y: 0 }]));
+  });
+});
+
+describe('lineSegmentsIntersect', () => {
+  it('detects crossing segments', () => {
+    assert.ok(lineSegmentsIntersect(0, 0, 4, 4, 0, 4, 4, 0));
+  });
+  it('returns false for parallel segments', () => {
+    assert.ok(!lineSegmentsIntersect(0, 0, 4, 0, 0, 1, 4, 1));
+  });
+});
+
+describe('lineIntersectsPolygon', () => {
+  it('detects line crossing polygon', () => {
+    assert.ok(lineIntersectsPolygon({ x: -1, y: 2 }, { x: 5, y: 2 }, square));
+  });
+  it('returns false for line outside polygon', () => {
+    assert.ok(!lineIntersectsPolygon({ x: 5, y: 5 }, { x: 6, y: 6 }, square));
+  });
+});
+
+describe('pointToLineSegmentDistance', () => {
+  it('returns perpendicular distance', () => {
+    const d = pointToLineSegmentDistance({ x: 2, y: 3 }, { x: 0, y: 0 }, { x: 4, y: 0 });
+    assert.ok(Math.abs(d - 3) < 0.0001);
+  });
+  it('returns distance to endpoint when perpendicular falls outside', () => {
+    const d = pointToLineSegmentDistance({ x: 5, y: 0 }, { x: 0, y: 0 }, { x: 4, y: 0 });
+    assert.ok(Math.abs(d - 1) < 0.0001);
+  });
+});
+
+describe('pointToPolygonDistance', () => {
+  it('returns 0 for point on edge', () => {
+    const d = pointToPolygonDistance({ x: 2, y: 0 }, square);
+    assert.ok(d < 0.0001);
+  });
+  it('returns correct distance to nearest edge', () => {
+    const d = pointToPolygonDistance({ x: 2, y: -1 }, square);
+    assert.ok(Math.abs(d - 1) < 0.0001);
+  });
+});
+
+describe('lineSegmentIntersectsCircle', () => {
+  it('detects segment passing through circle', () => {
+    assert.ok(lineSegmentIntersectsCircle(
+      { x: 0, y: 0 }, { x: 10, y: 0 },
+      { x: 5, y: 0.5 }, 1
+    ));
+  });
+  it('returns false for segment far from circle', () => {
+    assert.ok(!lineSegmentIntersectsCircle(
+      { x: 0, y: 0 }, { x: 10, y: 0 },
+      { x: 5, y: 5 }, 1
+    ));
+  });
+  it('detects segment tangent within radius', () => {
+    assert.ok(lineSegmentIntersectsCircle(
+      { x: 0, y: 0 }, { x: 10, y: 0 },
+      { x: 5, y: 0.9 }, 1
+    ));
+  });
+});
+
+describe('isBaseOverlappingTerrain', () => {
+  it('returns true when center is inside polygon', () => {
+    assert.ok(isBaseOverlappingTerrain({ x: 2, y: 2 }, 0.5, square));
+  });
+  it('returns true when base circle overlaps polygon boundary', () => {
+    // Point is 0.3 inches from polygon edge, base radius is 0.5
+    assert.ok(isBaseOverlappingTerrain({ x: -0.3, y: 2 }, 0.5, square));
+  });
+  it('returns false when base circle does not overlap', () => {
+    // Point is 1 inch from polygon, base radius is 0.5
+    assert.ok(!isBaseOverlappingTerrain({ x: -1, y: 2 }, 0.5, square));
+  });
+});

package/__tests__/terrain.test.js

@@ -0,0 +1,99 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  checkTargetOnBlockedTerrain,
+  checkMovementBlocked,
+  countPenaltyTerrainPieces,
+  checkTerrainMovementPenalty,
+} = require('../src/terrain');
+
+const impassableBlock = {
+  type: 'impassable',
+  vertices: [{ x: 8, y: 8 }, { x: 12, y: 8 }, { x: 12, y: 12 }, { x: 8, y: 12 }],
+};
+
+const lightCoverBlock = {
+  type: 'lightCover',
+  vertices: [{ x: 2, y: 8 }, { x: 4, y: 8 }, { x: 4, y: 12 }, { x: 2, y: 12 }],
+};
+
+const heavyCoverBlock = {
+  type: 'heavyCover',
+  vertices: [{ x: 14, y: 8 }, { x: 16, y: 8 }, { x: 16, y: 12 }, { x: 14, y: 12 }],
+};
+
+const difficultBlock = {
+  type: 'difficult',
+  vertices: [{ x: 18, y: 8 }, { x: 20, y: 8 }, { x: 20, y: 12 }, { x: 18, y: 12 }],
+};
+
+describe('checkTargetOnBlockedTerrain', () => {
+  it('returns terrain type when base overlaps blocked terrain', () => {
+    // Center at (10, 10) is inside the impassable block
+    assert.equal(checkTargetOnBlockedTerrain({ x: 10, y: 10 }, 0.5, [impassableBlock]), 'impassable');
+  });
+
+  it('returns terrain type when base edge overlaps blocked terrain', () => {
+    // Center 0.3" from edge, base_radius 0.5 → overlaps
+    assert.equal(checkTargetOnBlockedTerrain({ x: 7.8, y: 10 }, 0.5, [impassableBlock]), 'impassable');
+  });
+
+  it('returns null when base does not overlap blocked terrain', () => {
+    assert.equal(checkTargetOnBlockedTerrain({ x: 5, y: 10 }, 0.5, [impassableBlock]), null);
+  });
+
+  it('returns null for empty terrain', () => {
+    assert.equal(checkTargetOnBlockedTerrain({ x: 10, y: 10 }, 0.5, []), null);
+    assert.equal(checkTargetOnBlockedTerrain({ x: 10, y: 10 }, 0.5, null), null);
+  });
+});
+
+describe('checkMovementBlocked', () => {
+  it('returns path_blocked when crossing impassable', () => {
+    assert.equal(
+      checkMovementBlocked({ x: 5, y: 10 }, { x: 15, y: 10 }, 0.5, [impassableBlock]),
+      'path_blocked'
+    );
+  });
+
+  it('returns target_blocked when destination base overlaps impassable', () => {
+    // End position just outside but base overlaps
+    assert.equal(
+      checkMovementBlocked({ x: 5, y: 10 }, { x: 7.8, y: 10 }, 0.5, [impassableBlock]),
+      'target_blocked'
+    );
+  });
+
+  it('returns null when path is clear', () => {
+    assert.equal(
+      checkMovementBlocked({ x: 0, y: 10 }, { x: 5, y: 10 }, 0.5, [impassableBlock]),
+      null
+    );
+  });
+});
+
+describe('countPenaltyTerrainPieces', () => {
+  it('counts distinct terrain pieces crossed', () => {
+    const terrain = [lightCoverBlock, difficultBlock];
+    // Path from (0, 10) to (22, 10) crosses both
+    assert.equal(countPenaltyTerrainPieces({ x: 0, y: 10 }, { x: 22, y: 10 }, terrain), 2);
+  });
+
+  it('returns 0 when no penalty terrain crossed', () => {
+    assert.equal(countPenaltyTerrainPieces({ x: 0, y: 0 }, { x: 1, y: 0 }, [lightCoverBlock]), 0);
+  });
+
+  it('counts heavyCover as penalty terrain', () => {
+    assert.equal(countPenaltyTerrainPieces({ x: 13, y: 10 }, { x: 17, y: 10 }, [heavyCoverBlock]), 1);
+  });
+});
+
+describe('checkTerrainMovementPenalty', () => {
+  it('returns true when penalty terrain crossed', () => {
+    assert.ok(checkTerrainMovementPenalty({ x: 0, y: 10 }, { x: 5, y: 10 }, [lightCoverBlock]));
+  });
+
+  it('returns false when no penalty terrain crossed', () => {
+    assert.ok(!checkTerrainMovementPenalty({ x: 0, y: 0 }, { x: 1, y: 0 }, [lightCoverBlock]));
+  });
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@boltr/geometry",
+  "version": "0.1.0",
+  "description": "Shared geometry primitives for BOLTR tactical combat game",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./primitives": "./src/primitives.js",
+    "./terrain": "./src/terrain.js",
+    "./los": "./src/los.js",
+    "./movement": "./src/movement.js"
+  },
+  "scripts": {
+    "test": "node --test __tests__/*.test.js"
+  },
+  "keywords": ["boltr", "geometry", "game"],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,44 @@
+/**
+ * @boltr/geometry
+ *
+ * Shared geometry primitives and game-specific spatial helpers
+ * for the BOLTR tactical combat game.
+ *
+ * Used by both the Xano backend (lambdas) and the frontend client.
+ */
+
+const primitives = require('./primitives');
+const terrain = require('./terrain');
+const los = require('./los');
+const movement = require('./movement');
+
+module.exports = {
+  // Primitives
+  calculateDistance: primitives.calculateDistance,
+  isPointInPolygon: primitives.isPointInPolygon,
+  lineSegmentsIntersect: primitives.lineSegmentsIntersect,
+  lineIntersectsPolygon: primitives.lineIntersectsPolygon,
+  pointToLineSegmentDistance: primitives.pointToLineSegmentDistance,
+  pointToPolygonDistance: primitives.pointToPolygonDistance,
+  lineSegmentIntersectsCircle: primitives.lineSegmentIntersectsCircle,
+  isBaseOverlappingTerrain: primitives.isBaseOverlappingTerrain,
+
+  // Terrain
+  BLOCKED_TERRAIN_TYPES: terrain.BLOCKED_TERRAIN_TYPES,
+  PENALTY_TERRAIN_TYPES: terrain.PENALTY_TERRAIN_TYPES,
+  checkTargetOnBlockedTerrain: terrain.checkTargetOnBlockedTerrain,
+  checkMovementBlocked: terrain.checkMovementBlocked,
+  countPenaltyTerrainPieces: terrain.countPenaltyTerrainPieces,
+  checkTerrainMovementPenalty: terrain.checkTerrainMovementPenalty,
+
+  // Line of Sight
+  checkLineOfSight: los.checkLineOfSight,
+
+  // Movement
+  DEFAULT_BASE_RADIUS: movement.DEFAULT_BASE_RADIUS,
+  isPositionOccupied: movement.isPositionOccupied,
+  isInFriendlyExclusionZone: movement.isInFriendlyExclusionZone,
+  isInEnemyExclusionZone: movement.isInEnemyExclusionZone,
+  isPathBlockedByEnemies: movement.isPathBlockedByEnemies,
+  validateWaypointPath: movement.validateWaypointPath,
+};

package/src/los.js

@@ -0,0 +1,61 @@
+/**
+ * @boltr/geometry - Line of Sight checks
+ *
+ * Determines cover status between a shooter and target based on
+ * intervening terrain.
+ */
+
+const {
+  lineIntersectsPolygon,
+  pointToPolygonDistance,
+} = require('./primitives');
+
+/**
+ * Check line of sight between shooter and target through terrain.
+ *
+ * Cover shooting mechanics:
+ * - Shooter bracing on cover (within 1"): shoots across without penalty
+ * - Target in cover (within 1"): gets defense bonus
+ * - Heavy cover blocks LOS when neither operative is within 1"
+ * - Light cover at distance has no effect (OBSCURED removed)
+ *
+ * @param {{position: {x: number, y: number}}} shooter
+ * @param {{position: {x: number, y: number}}} target
+ * @param {Array} terrain
+ * @returns {'CLEAR'|'LIGHT_COVER'|'HEAVY_COVER'|'BLOCKED'}
+ */
+function checkLineOfSight(shooter, target, terrain) {
+  if (!terrain || !Array.isArray(terrain) || terrain.length === 0) return 'CLEAR';
+
+  for (const piece of terrain) {
+    if (!piece.vertices || !Array.isArray(piece.vertices)) continue;
+    if (!lineIntersectsPolygon(shooter.position, target.position, piece.vertices)) continue;
+
+    const terrainType = piece.type || 'lightCover';
+
+    // Only lightCover and heavyCover affect shooting
+    if (terrainType !== 'lightCover' && terrainType !== 'heavyCover') continue;
+
+    const shooterDist = pointToPolygonDistance(shooter.position, piece.vertices);
+    const targetDist = pointToPolygonDistance(target.position, piece.vertices);
+
+    // Shooter bracing on cover - no penalty, skip this terrain piece
+    if (shooterDist <= 1.0) continue;
+
+    // Target in cover - defense bonus applies
+    if (targetDist <= 1.0) {
+      if (terrainType === 'heavyCover') return 'HEAVY_COVER';
+      if (terrainType === 'lightCover') return 'LIGHT_COVER';
+    }
+
+    // Neither in contact with heavy cover - blocks LOS
+    if (terrainType === 'heavyCover') return 'BLOCKED';
+
+    // lightCover at distance - no effect (OBSCURED removed)
+  }
+  return 'CLEAR';
+}
+
+module.exports = {
+  checkLineOfSight,
+};

package/src/movement.js

@@ -0,0 +1,235 @@
+/**
+ * @boltr/geometry - Movement validation helpers
+ *
+ * Waypoint-based movement validation, enemy path blocking,
+ * and friendly spacing checks.
+ */
+
+const {
+  calculateDistance,
+  lineSegmentIntersectsCircle,
+  lineIntersectsPolygon,
+  isBaseOverlappingTerrain,
+} = require('./primitives');
+
+const {
+  checkTargetOnBlockedTerrain,
+  checkMovementBlocked,
+  countPenaltyTerrainPieces,
+} = require('./terrain');
+
+/** Default base radius when not specified on a unit */
+const DEFAULT_BASE_RADIUS = 0.5;
+
+/**
+ * Check if a position's base overlaps another unit's base.
+ * Two bases overlap when the distance between centers is less than
+ * the sum of their radii.
+ *
+ * @param {{x: number, y: number}} position
+ * @param {number} baseRadius
+ * @param {Array} units  Game state units array
+ * @param {number|null} excludeUnitIndex  Unit to exclude (self)
+ * @returns {boolean}
+ */
+function isPositionOccupied(position, baseRadius, units, excludeUnitIndex) {
+  return units.some(unit => {
+    if (unit.eliminated) return false;
+    if (excludeUnitIndex !== undefined && unit.unit_index === excludeUnitIndex) return false;
+    const unitRadius = unit.base_radius || DEFAULT_BASE_RADIUS;
+    return calculateDistance(unit.position, position) < (baseRadius + unitRadius);
+  });
+}
+
+/**
+ * Check if a position is within the exclusion zone of any friendly operative.
+ * Uses sum-of-radii (#54): two friendly bases cannot overlap.
+ *
+ * @param {{x: number, y: number}} position
+ * @param {object} operative  The moving operative
+ * @param {Array} units
+ * @returns {boolean}
+ */
+function isInFriendlyExclusionZone(position, operative, units) {
+  const selfRadius = operative.base_radius || DEFAULT_BASE_RADIUS;
+  return units.some(friendly =>
+    friendly.player_id === operative.player_id &&
+    friendly.unit_index !== operative.unit_index &&
+    !friendly.eliminated &&
+    calculateDistance(position, friendly.position) < (selfRadius + (friendly.base_radius || DEFAULT_BASE_RADIUS))
+  );
+}
+
+/**
+ * Check if position is within 1" exclusion zone of any enemy operative.
+ *
+ * @param {{x: number, y: number}} position
+ * @param {object} operative  The moving operative
+ * @param {Array} units
+ * @returns {boolean}
+ */
+function isInEnemyExclusionZone(position, operative, units) {
+  return units.some(enemy =>
+    enemy.player_id !== operative.player_id &&
+    !enemy.eliminated &&
+    calculateDistance(position, enemy.position) < 1
+  );
+}
+
+/**
+ * Check if a straight-line path is blocked by any enemy operatives (#56).
+ * An enemy blocks a path when the line segment comes within
+ * (enemy.base_radius + 1.0) inches of the enemy center.
+ *
+ * @param {{x: number, y: number}} startPos
+ * @param {{x: number, y: number}} endPos
+ * @param {object} operative     The moving operative
+ * @param {Array} units          All game units
+ * @param {number|null} exemptUnitIndex  Charge target to exempt
+ * @returns {{blocked: boolean, blocker?: object}}
+ */
+function isPathBlockedByEnemies(startPos, endPos, operative, units, exemptUnitIndex) {
+  for (const enemy of units) {
+    if (enemy.player_id === operative.player_id) continue;
+    if (enemy.eliminated) continue;
+    if (exemptUnitIndex !== undefined && enemy.unit_index === exemptUnitIndex) continue;
+
+    const blockingRadius = (enemy.base_radius || DEFAULT_BASE_RADIUS) + 1.0;
+    if (lineSegmentIntersectsCircle(startPos, endPos, enemy.position, blockingRadius)) {
+      return { blocked: true, blocker: enemy };
+    }
+  }
+  return { blocked: false };
+}
+
+/**
+ * Validate a waypoint path: checks each segment for terrain blocking,
+ * enemy path blocking, and computes total distance with per-piece penalty.
+ *
+ * @param {{x: number, y: number}} startPos        Operative's current position
+ * @param {{x: number, y: number}[]} waypoints     Array of waypoint positions
+ * @param {number} baseRadius                       Operative's base radius
+ * @param {number} maxDistance                       Maximum allowed movement distance
+ * @param {object} operative                         The moving operative
+ * @param {Array} units                              All game units
+ * @param {Array} terrain                            Terrain array from map_data
+ * @param {object} [mapData]                         Map data for bounds checking
+ * @param {object} [options]                          Options
+ * @param {number|null} [options.exemptEnemyUnitIndex]  Enemy unit to exempt from path blocking (charge target)
+ * @param {boolean} [options.checkEnemyBlocking=true]   Whether to check enemy path blocking
+ * @param {Function} [options.isWithinBounds]           Bounds-checking function
+ * @returns {{valid: boolean, error?: string, totalDistance?: number}}
+ */
+function validateWaypointPath(startPos, waypoints, baseRadius, maxDistance, operative, units, terrain, mapData, options) {
+  const opts = options || {};
+  const checkEnemyBlocking = opts.checkEnemyBlocking !== false;
+  const exemptEnemyUnitIndex = opts.exemptEnemyUnitIndex;
+  const isWithinBounds = opts.isWithinBounds;
+
+  if (!waypoints || !Array.isArray(waypoints) || waypoints.length === 0) {
+    return { valid: false, error: 'Movement requires at least one waypoint' };
+  }
+
+  let totalDistance = 0;
+  const terrainPiecesCrossed = new Set();
+  let currentPos = startPos;
+
+  for (let i = 0; i < waypoints.length; i++) {
+    const wp = waypoints[i];
+    const isFinal = (i === waypoints.length - 1);
+
+    // Validate waypoint format
+    if (!wp || typeof wp.x !== 'number' || typeof wp.y !== 'number') {
+      return { valid: false, error: `Invalid waypoint format at index ${i}` };
+    }
+
+    // Bounds check
+    if (isWithinBounds && !isWithinBounds(wp, mapData)) {
+      return { valid: false, error: `Waypoint ${i} is outside battlefield bounds` };
+    }
+
+    // Check path segment for impassable terrain blocking
+    const blocked = checkMovementBlocked(currentPos, wp, baseRadius, terrain);
+    if (blocked) {
+      return { valid: false, error: `Movement blocked by impassable terrain at segment ${i}` };
+    }
+
+    // Check enemy path blocking (#56)
+    if (checkEnemyBlocking) {
+      const enemyBlock = isPathBlockedByEnemies(currentPos, wp, operative, units, exemptEnemyUnitIndex);
+      if (enemyBlock.blocked) {
+        return { valid: false, error: `Movement path blocked by enemy operative (unit ${enemyBlock.blocker.unit_index})` };
+      }
+    }
+
+    // Final waypoint: check destination terrain and spacing
+    if (isFinal) {
+      const blockedType = checkTargetOnBlockedTerrain(wp, baseRadius, terrain);
+      if (blockedType) {
+        return { valid: false, error: `Cannot end movement on ${blockedType} terrain` };
+      }
+
+      if (isPositionOccupied(wp, baseRadius, units, operative.unit_index)) {
+        return { valid: false, error: 'Target position is occupied by another operative' };
+      }
+
+      if (isInFriendlyExclusionZone(wp, operative, units)) {
+        return { valid: false, error: 'Cannot end movement within exclusion zone of friendly operative' };
+      }
+    }
+
+    // Intermediate waypoints: full validation
+    if (!isFinal) {
+      const blockedType = checkTargetOnBlockedTerrain(wp, baseRadius, terrain);
+      if (blockedType) {
+        return { valid: false, error: `Cannot pass through ${blockedType} terrain at waypoint ${i}` };
+      }
+    }
+
+    // Accumulate terrain penalty pieces for this segment
+    if (terrain && Array.isArray(terrain)) {
+      const PENALTY_TERRAIN_TYPES = ['difficult', 'lightCover', 'heavyCover'];
+      for (const piece of terrain) {
+        if (!piece.vertices || !Array.isArray(piece.vertices)) continue;
+        if (!PENALTY_TERRAIN_TYPES.includes(piece.type)) continue;
+        if (lineIntersectsPolygon(currentPos, wp, piece.vertices)) {
+          // Use a stable identifier for the terrain piece
+          const pieceId = piece.id || `${piece.type}_${piece.vertices[0].x}_${piece.vertices[0].y}`;
+          terrainPiecesCrossed.add(pieceId);
+        }
+      }
+    }
+
+    // Accumulate segment distance
+    totalDistance += calculateDistance(currentPos, wp);
+    currentPos = wp;
+  }
+
+  // Apply per-terrain-piece penalty: +2" per unique piece crossed
+  const TERRAIN_PENALTY_PER_PIECE = 2;
+  const effectiveDistance = totalDistance + (terrainPiecesCrossed.size * TERRAIN_PENALTY_PER_PIECE);
+
+  if (effectiveDistance > maxDistance) {
+    if (terrainPiecesCrossed.size > 0) {
+      return {
+        valid: false,
+        error: `Movement through terrain adds ${terrainPiecesCrossed.size * TERRAIN_PENALTY_PER_PIECE} inches penalty (${totalDistance.toFixed(1)} + ${terrainPiecesCrossed.size * TERRAIN_PENALTY_PER_PIECE} > ${maxDistance})`,
+      };
+    }
+    return {
+      valid: false,
+      error: `Movement distance ${totalDistance.toFixed(1)} inches exceeds maximum ${maxDistance} inches`,
+    };
+  }
+
+  return { valid: true, totalDistance, effectiveDistance, terrainPenalty: terrainPiecesCrossed.size * TERRAIN_PENALTY_PER_PIECE };
+}
+
+module.exports = {
+  DEFAULT_BASE_RADIUS,
+  isPositionOccupied,
+  isInFriendlyExclusionZone,
+  isInEnemyExclusionZone,
+  isPathBlockedByEnemies,
+  validateWaypointPath,
+};

package/src/primitives.js

@@ -0,0 +1,142 @@
+/**
+ * @boltr/geometry - Pure geometry primitives
+ *
+ * These are stateless math functions with no game-logic dependencies.
+ * Every function takes plain {x, y} point objects and vertex arrays.
+ */
+
+/**
+ * Euclidean distance between two points.
+ * @param {{x: number, y: number}} pos1
+ * @param {{x: number, y: number}} pos2
+ * @returns {number}
+ */
+function calculateDistance(pos1, pos2) {
+  return Math.sqrt(Math.pow(pos2.x - pos1.x, 2) + Math.pow(pos2.y - pos1.y, 2));
+}
+
+/**
+ * Point-in-polygon test (ray casting algorithm).
+ * @param {{x: number, y: number}} point
+ * @param {{x: number, y: number}[]} vertices
+ * @returns {boolean}
+ */
+function isPointInPolygon(point, vertices) {
+  if (!vertices || !Array.isArray(vertices) || vertices.length < 3) return false;
+  let inside = false;
+  for (let i = 0, j = vertices.length - 1; i < vertices.length; j = i++) {
+    const xi = vertices[i].x, yi = vertices[i].y;
+    const xj = vertices[j].x, yj = vertices[j].y;
+    if (((yi > point.y) !== (yj > point.y)) &&
+        (point.x < (xj - xi) * (point.y - yi) / (yj - yi) + xi)) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+/**
+ * Test whether two line segments intersect (exclusive of endpoints).
+ * @returns {boolean}
+ */
+function lineSegmentsIntersect(x1, y1, x2, y2, x3, y3, x4, y4) {
+  const denom = (y4 - y3) * (x2 - x1) - (x4 - x3) * (y2 - y1);
+  if (Math.abs(denom) < 0.0001) return false;
+  const ua = ((x4 - x3) * (y1 - y3) - (y4 - y3) * (x1 - x3)) / denom;
+  const ub = ((x2 - x1) * (y1 - y3) - (y2 - y1) * (x1 - x3)) / denom;
+  return ua > 0.001 && ua < 0.999 && ub > 0.001 && ub < 0.999;
+}
+
+/**
+ * Test whether a line segment intersects any edge of a polygon.
+ * @param {{x: number, y: number}} lineStart
+ * @param {{x: number, y: number}} lineEnd
+ * @param {{x: number, y: number}[]} vertices
+ * @returns {boolean}
+ */
+function lineIntersectsPolygon(lineStart, lineEnd, vertices) {
+  if (!vertices || !Array.isArray(vertices) || vertices.length < 3) return false;
+  for (let i = 0; i < vertices.length; i++) {
+    const j = (i + 1) % vertices.length;
+    if (lineSegmentsIntersect(
+      lineStart.x, lineStart.y, lineEnd.x, lineEnd.y,
+      vertices[i].x, vertices[i].y, vertices[j].x, vertices[j].y
+    )) return true;
+  }
+  return false;
+}
+
+/**
+ * Shortest distance from a point to a line segment.
+ * @param {{x: number, y: number}} point
+ * @param {{x: number, y: number}} lineStart
+ * @param {{x: number, y: number}} lineEnd
+ * @returns {number}
+ */
+function pointToLineSegmentDistance(point, lineStart, lineEnd) {
+  const dx = lineEnd.x - lineStart.x;
+  const dy = lineEnd.y - lineStart.y;
+  const lengthSquared = dx * dx + dy * dy;
+  if (lengthSquared === 0) return calculateDistance(point, lineStart);
+  let t = ((point.x - lineStart.x) * dx + (point.y - lineStart.y) * dy) / lengthSquared;
+  t = Math.max(0, Math.min(1, t));
+  const projection = { x: lineStart.x + t * dx, y: lineStart.y + t * dy };
+  return calculateDistance(point, projection);
+}
+
+/**
+ * Shortest distance from a point to the boundary of a polygon.
+ * @param {{x: number, y: number}} point
+ * @param {{x: number, y: number}[]} vertices
+ * @returns {number}
+ */
+function pointToPolygonDistance(point, vertices) {
+  if (!vertices || !Array.isArray(vertices) || vertices.length < 3) return Infinity;
+  let minDist = Infinity;
+  for (let i = 0; i < vertices.length; i++) {
+    const j = (i + 1) % vertices.length;
+    const dist = pointToLineSegmentDistance(point, vertices[i], vertices[j]);
+    if (dist < minDist) minDist = dist;
+  }
+  return minDist;
+}
+
+/**
+ * Test whether a line segment intersects a circle.
+ * Used for path-vs-enemy blocking checks (#56).
+ * @param {{x: number, y: number}} lineStart
+ * @param {{x: number, y: number}} lineEnd
+ * @param {{x: number, y: number}} center  Circle center
+ * @param {number} radius                  Circle radius
+ * @returns {boolean}
+ */
+function lineSegmentIntersectsCircle(lineStart, lineEnd, center, radius) {
+  const dist = pointToLineSegmentDistance(center, lineStart, lineEnd);
+  return dist < radius;
+}
+
+/**
+ * Test whether a base circle overlaps a terrain polygon.
+ * Minkowski-equivalent: the center is inside the polygon OR
+ * the center-to-boundary distance is less than the base radius.
+ * Used for terrain exclusion with operative base size (#55).
+ * @param {{x: number, y: number}} position  Center of base
+ * @param {number} baseRadius                 Radius of base
+ * @param {{x: number, y: number}[]} vertices Polygon vertices
+ * @returns {boolean}
+ */
+function isBaseOverlappingTerrain(position, baseRadius, vertices) {
+  if (isPointInPolygon(position, vertices)) return true;
+  return pointToPolygonDistance(position, vertices) < baseRadius;
+}
+
+module.exports = {
+  calculateDistance,
+  isPointInPolygon,
+  lineSegmentsIntersect,
+  lineIntersectsPolygon,
+  pointToLineSegmentDistance,
+  pointToPolygonDistance,
+  lineSegmentIntersectsCircle,
+  isBaseOverlappingTerrain,
+};

package/src/terrain.js

@@ -0,0 +1,108 @@
+/**
+ * @boltr/geometry - Terrain interaction helpers
+ *
+ * Functions that check how movement paths and positions interact
+ * with terrain polygons on the battlefield.
+ */
+
+const {
+  isPointInPolygon,
+  lineIntersectsPolygon,
+  isBaseOverlappingTerrain,
+} = require('./primitives');
+
+/** Terrain types that block placement / ending movement */
+const BLOCKED_TERRAIN_TYPES = ['lightCover', 'heavyCover', 'impassable'];
+
+/** Terrain types that add a movement penalty when crossed */
+const PENALTY_TERRAIN_TYPES = ['difficult', 'lightCover', 'heavyCover'];
+
+/**
+ * Check whether a position's base circle sits on blocked terrain.
+ * Returns the terrain type string if blocked, or null.
+ *
+ * @param {{x: number, y: number}} position
+ * @param {number} baseRadius
+ * @param {Array} terrain
+ * @returns {string|null}
+ */
+function checkTargetOnBlockedTerrain(position, baseRadius, terrain) {
+  if (!terrain || !Array.isArray(terrain) || terrain.length === 0) return null;
+
+  for (const piece of terrain) {
+    if (!piece.vertices || !Array.isArray(piece.vertices)) continue;
+    if (!BLOCKED_TERRAIN_TYPES.includes(piece.type)) continue;
+    if (isBaseOverlappingTerrain(position, baseRadius, piece.vertices)) {
+      return piece.type;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check whether a straight-line movement path is blocked by impassable terrain.
+ * Also checks whether the destination base overlaps impassable terrain.
+ *
+ * @param {{x: number, y: number}} startPos
+ * @param {{x: number, y: number}} endPos
+ * @param {number} baseRadius
+ * @param {Array} terrain
+ * @returns {'path_blocked'|'target_blocked'|null}
+ */
+function checkMovementBlocked(startPos, endPos, baseRadius, terrain) {
+  if (!terrain || !Array.isArray(terrain) || terrain.length === 0) return null;
+
+  for (const piece of terrain) {
+    if (!piece.vertices || !Array.isArray(piece.vertices)) continue;
+    if (piece.type !== 'impassable') continue;
+
+    if (lineIntersectsPolygon(startPos, endPos, piece.vertices)) {
+      return 'path_blocked';
+    }
+
+    if (isBaseOverlappingTerrain(endPos, baseRadius, piece.vertices)) {
+      return 'target_blocked';
+    }
+  }
+  return null;
+}
+
+/**
+ * Count distinct terrain pieces that impose a movement penalty along a path segment.
+ * Returns the number of unique penalty terrain pieces crossed.
+ *
+ * @param {{x: number, y: number}} startPos
+ * @param {{x: number, y: number}} endPos
+ * @param {Array} terrain
+ * @returns {number}
+ */
+function countPenaltyTerrainPieces(startPos, endPos, terrain) {
+  if (!terrain || !Array.isArray(terrain) || terrain.length === 0) return 0;
+
+  let count = 0;
+  for (const piece of terrain) {
+    if (!piece.vertices || !Array.isArray(piece.vertices)) continue;
+    if (!PENALTY_TERRAIN_TYPES.includes(piece.type)) continue;
+    if (lineIntersectsPolygon(startPos, endPos, piece.vertices)) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Legacy helper: returns boolean if ANY penalty terrain is crossed.
+ * Kept for backward compat during transition to per-piece penalty.
+ */
+function checkTerrainMovementPenalty(startPos, endPos, terrain) {
+  return countPenaltyTerrainPieces(startPos, endPos, terrain) > 0;
+}
+
+module.exports = {
+  BLOCKED_TERRAIN_TYPES,
+  PENALTY_TERRAIN_TYPES,
+  checkTargetOnBlockedTerrain,
+  checkMovementBlocked,
+  countPenaltyTerrainPieces,
+  checkTerrainMovementPenalty,
+};