@holoscript/engine 6.0.3 → 6.0.4

package/dist/spatial/index.cjs

@@ -0,0 +1,2443 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/spatial/index.ts
+var spatial_exports = {};
+__export(spatial_exports, {
+  DEFAULT_SPATIAL_CONFIG: () => DEFAULT_SPATIAL_CONFIG,
+  OctreeLODSystem: () => OctreeLODSystem,
+  OctreeSystem: () => OctreeSystem,
+  SpatialConstraintValidator: () => SpatialConstraintValidator,
+  SpatialContextProvider: () => SpatialContextProvider,
+  SpatialQueryExecutor: () => SpatialQueryExecutor,
+  add: () => add,
+  boxesOverlap: () => boxesOverlap,
+  cross: () => cross,
+  distance: () => distance,
+  distanceSquared: () => distanceSquared,
+  dot: () => dot,
+  getBoxCenter: () => getBoxCenter,
+  isPointInBox: () => isPointInBox,
+  isPointInSphere: () => isPointInSphere,
+  lerp: () => lerp,
+  normalize: () => normalize,
+  scale: () => scale,
+  subtract: () => subtract
+});
+module.exports = __toCommonJS(spatial_exports);
+
+// src/spatial/SpatialTypes.ts
+var DEFAULT_SPATIAL_CONFIG = {
+  updateRate: 30,
+  perceptionRadius: 10,
+  visibilityRadius: 50,
+  trackRegions: true,
+  computeSightLines: true,
+  entityTypeFilter: [],
+  movementThreshold: 0.01
+};
+function distance(a, b) {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const dz = b.z - a.z;
+  return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+function distanceSquared(a, b) {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const dz = b.z - a.z;
+  return dx * dx + dy * dy + dz * dz;
+}
+function isPointInBox(point, box) {
+  return point.x >= box.min.x && point.x <= box.max.x && point.y >= box.min.y && point.y <= box.max.y && point.z >= box.min.z && point.z <= box.max.z;
+}
+function isPointInSphere(point, sphere) {
+  return distance(point, sphere.center) <= sphere.radius;
+}
+function getBoxCenter(box) {
+  return {
+    x: (box.min.x + box.max.x) / 2,
+    y: (box.min.y + box.max.y) / 2,
+    z: (box.min.z + box.max.z) / 2
+  };
+}
+function boxesOverlap(a, b) {
+  return a.min.x <= b.max.x && a.max.x >= b.min.x && a.min.y <= b.max.y && a.max.y >= b.min.y && a.min.z <= b.max.z && a.max.z >= b.min.z;
+}
+function normalize(v) {
+  const len = Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z);
+  if (len === 0) return { x: 0, y: 0, z: 0 };
+  return { x: v.x / len, y: v.y / len, z: v.z / len };
+}
+function subtract(a, b) {
+  return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+}
+function add(a, b) {
+  return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+}
+function scale(v, s) {
+  return { x: v.x * s, y: v.y * s, z: v.z * s };
+}
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+function cross(a, b) {
+  return {
+    x: a.y * b.z - a.z * b.y,
+    y: a.z * b.x - a.x * b.z,
+    z: a.x * b.y - a.y * b.x
+  };
+}
+function lerp(a, b, t) {
+  return {
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+    z: a.z + (b.z - a.z) * t
+  };
+}
+
+// src/spatial/SpatialQuery.ts
+var SpatialQueryExecutor = class {
+  entities = /* @__PURE__ */ new Map();
+  regions = /* @__PURE__ */ new Map();
+  spatialIndex;
+  constructor() {
+    this.spatialIndex = new SpatialIndex();
+  }
+  /**
+   * Update the entity set
+   */
+  updateEntities(entities) {
+    this.entities.clear();
+    for (const entity of entities) {
+      this.entities.set(entity.id, entity);
+    }
+    this.spatialIndex.rebuild(entities);
+  }
+  /**
+   * Update regions
+   */
+  updateRegions(regions) {
+    this.regions.clear();
+    for (const region of regions) {
+      this.regions.set(region.id, region);
+    }
+  }
+  /**
+   * Execute a spatial query
+   */
+  execute(query) {
+    let candidates = Array.from(this.entities.values());
+    if (query.entityTypeFilter && query.entityTypeFilter.length > 0) {
+      candidates = candidates.filter((e) => query.entityTypeFilter.includes(e.type));
+    }
+    let results;
+    switch (query.type) {
+      case "nearest":
+        results = this.executeNearest(query, candidates);
+        break;
+      case "within":
+        results = this.executeWithin(query, candidates);
+        break;
+      case "visible":
+        results = this.executeVisible(query, candidates);
+        break;
+      case "reachable":
+        results = this.executeReachable(query, candidates);
+        break;
+      case "in_region":
+        results = this.executeInRegion(query, candidates);
+        break;
+      case "by_type":
+        results = this.executeByType(query, candidates);
+        break;
+      case "raycast":
+        results = this.executeRaycast(query, candidates);
+        break;
+      default:
+        results = [];
+    }
+    if (query.maxResults && results.length > query.maxResults) {
+      results = results.slice(0, query.maxResults);
+    }
+    return results;
+  }
+  /**
+   * Find nearest entities
+   */
+  executeNearest(query, candidates) {
+    const results = candidates.map((entity) => ({
+      entity,
+      distance: distance(query.from, entity.position),
+      direction: normalize(subtract(entity.position, query.from))
+    }));
+    results.sort((a, b) => a.distance - b.distance);
+    const count = query.count || 1;
+    return results.slice(0, count);
+  }
+  /**
+   * Find entities within radius
+   */
+  executeWithin(query, candidates) {
+    const _radiusSq = query.radius * query.radius;
+    return candidates.map((entity) => {
+      const dist = distance(query.from, entity.position);
+      return {
+        entity,
+        distance: dist,
+        direction: normalize(subtract(entity.position, query.from))
+      };
+    }).filter((r) => {
+      if (query.includePartial && r.entity.bounds) {
+        return r.distance - this.getEntityRadius(r.entity) <= query.radius;
+      }
+      return r.distance <= query.radius;
+    }).sort((a, b) => a.distance - b.distance);
+  }
+  /**
+   * Find visible entities
+   */
+  executeVisible(query, candidates) {
+    const results = [];
+    const maxDist = query.maxDistance || Infinity;
+    for (const entity of candidates) {
+      const dir = subtract(entity.position, query.from);
+      const dist = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+      if (dist > maxDist) continue;
+      if (dist === 0) continue;
+      if (query.direction && query.fov !== void 0) {
+        const normalizedDir = normalize(dir);
+        const dotProduct = dot(normalize(query.direction), normalizedDir);
+        const angle = Math.acos(Math.max(-1, Math.min(1, dotProduct))) * (180 / Math.PI);
+        if (angle > query.fov / 2) continue;
+      }
+      const sightLine = this.checkSightLine(query.from, entity.position, candidates, entity.id);
+      if (!sightLine.blocked) {
+        results.push({
+          entity,
+          distance: dist,
+          direction: normalize(dir),
+          sightLine
+        });
+      }
+    }
+    return results.sort((a, b) => a.distance - b.distance);
+  }
+  /**
+   * Find reachable entities (simplified - no full pathfinding)
+   */
+  executeReachable(query, candidates) {
+    const maxDist = query.maxDistance || Infinity;
+    const obstacles = query.obstacles || [];
+    return candidates.map((entity) => ({
+      entity,
+      distance: distance(query.from, entity.position),
+      direction: normalize(subtract(entity.position, query.from))
+    })).filter((r) => {
+      if (r.distance > maxDist) return false;
+      const sight = this.checkSightLine(query.from, r.entity.position, obstacles, r.entity.id);
+      return !sight.blocked;
+    }).sort((a, b) => a.distance - b.distance);
+  }
+  /**
+   * Find entities in a region
+   */
+  executeInRegion(query, candidates) {
+    return candidates.filter((entity) => this.isInRegion(entity.position, query.region)).map((entity) => ({
+      entity,
+      distance: distance(query.from, entity.position),
+      direction: normalize(subtract(entity.position, query.from))
+    })).sort((a, b) => a.distance - b.distance);
+  }
+  /**
+   * Find entities by type
+   */
+  executeByType(query, candidates) {
+    let filtered = candidates.filter((e) => query.entityTypes.includes(e.type));
+    if (query.radius !== void 0) {
+      filtered = filtered.filter((e) => distance(query.from, e.position) <= query.radius);
+    }
+    return filtered.map((entity) => ({
+      entity,
+      distance: distance(query.from, entity.position),
+      direction: normalize(subtract(entity.position, query.from))
+    })).sort((a, b) => a.distance - b.distance);
+  }
+  /**
+   * Execute raycast
+   */
+  executeRaycast(query, candidates) {
+    const results = [];
+    const dir = normalize(query.direction);
+    for (const entity of candidates) {
+      const hit = this.raycastEntity(query.from, dir, entity, query.maxDistance);
+      if (hit) {
+        results.push({
+          entity,
+          distance: hit.distance,
+          direction: dir
+        });
+      }
+    }
+    results.sort((a, b) => a.distance - b.distance);
+    if (query.hitFirst && results.length > 0) {
+      return [results[0]];
+    }
+    return results;
+  }
+  /**
+   * Check line of sight between two points
+   */
+  checkSightLine(from, to, entities, excludeId) {
+    const dir = subtract(to, from);
+    const dist = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+    const normalizedDir = dist > 0 ? scale(dir, 1 / dist) : { x: 0, y: 0, z: 0 };
+    for (const entity of entities) {
+      if (entity.id === excludeId) continue;
+      const hit = this.raycastEntity(from, normalizedDir, entity, dist);
+      if (hit && hit.distance < dist - 1e-3) {
+        return {
+          from,
+          to,
+          blocked: true,
+          blockingEntity: entity.id,
+          distance: dist
+        };
+      }
+    }
+    return { from, to, blocked: false, distance: dist };
+  }
+  /**
+   * Raycast against a single entity
+   */
+  raycastEntity(origin, direction, entity, maxDistance) {
+    const radius = this.getEntityRadius(entity);
+    const center = entity.position;
+    const oc = subtract(origin, center);
+    const a = dot(direction, direction);
+    const b = 2 * dot(oc, direction);
+    const c = dot(oc, oc) - radius * radius;
+    const discriminant = b * b - 4 * a * c;
+    if (discriminant < 0) return null;
+    const t = (-b - Math.sqrt(discriminant)) / (2 * a);
+    if (t < 0 || t > maxDistance) return null;
+    const point = add(origin, scale(direction, t));
+    return {
+      entity,
+      point,
+      distance: t,
+      normal: normalize(subtract(point, center))
+    };
+  }
+  /**
+   * Get approximate radius of an entity
+   */
+  getEntityRadius(entity) {
+    if (!entity.bounds) return 0.5;
+    if ("radius" in entity.bounds) {
+      return entity.bounds.radius;
+    }
+    const box = entity.bounds;
+    const dx = box.max.x - box.min.x;
+    const dy = box.max.y - box.min.y;
+    const dz = box.max.z - box.min.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
+  }
+  /**
+   * Check if point is in region
+   */
+  isInRegion(point, region) {
+    if ("radius" in region.bounds) {
+      return isPointInSphere(point, region.bounds);
+    }
+    return isPointInBox(point, region.bounds);
+  }
+};
+var SpatialIndex = class {
+  cellSize = 10;
+  cells = /* @__PURE__ */ new Map();
+  /**
+   * Rebuild the index with new entities
+   */
+  rebuild(entities) {
+    this.cells.clear();
+    for (const entity of entities) {
+      const cellKey = this.getCellKey(entity.position);
+      const cell = this.cells.get(cellKey) || [];
+      cell.push(entity);
+      this.cells.set(cellKey, cell);
+    }
+  }
+  /**
+   * Get entities in neighboring cells
+   */
+  getNeighbors(position, radius) {
+    const results = [];
+    const cellRadius = Math.ceil(radius / this.cellSize);
+    const cx = Math.floor(position.x / this.cellSize);
+    const cy = Math.floor(position.y / this.cellSize);
+    const cz = Math.floor(position.z / this.cellSize);
+    for (let dx = -cellRadius; dx <= cellRadius; dx++) {
+      for (let dy = -cellRadius; dy <= cellRadius; dy++) {
+        for (let dz = -cellRadius; dz <= cellRadius; dz++) {
+          const key = `${cx + dx},${cy + dy},${cz + dz}`;
+          const cell = this.cells.get(key);
+          if (cell) {
+            results.push(...cell);
+          }
+        }
+      }
+    }
+    return results;
+  }
+  getCellKey(position) {
+    const cx = Math.floor(position.x / this.cellSize);
+    const cy = Math.floor(position.y / this.cellSize);
+    const cz = Math.floor(position.z / this.cellSize);
+    return `${cx},${cy},${cz}`;
+  }
+};
+
+// src/spatial/SpatialContextProvider.ts
+var import_events = require("events");
+var SpatialContextProvider = class extends import_events.EventEmitter {
+  agents = /* @__PURE__ */ new Map();
+  entities = /* @__PURE__ */ new Map();
+  regions = /* @__PURE__ */ new Map();
+  queryExecutor;
+  updateInterval = null;
+  isRunning = false;
+  constructor() {
+    super();
+    this.queryExecutor = new SpatialQueryExecutor();
+  }
+  // ===========================================================================
+  // LIFECYCLE
+  // ===========================================================================
+  /**
+   * Start the spatial context provider
+   */
+  start() {
+    if (this.isRunning) return;
+    this.isRunning = true;
+    const minInterval = this.getMinUpdateInterval();
+    if (minInterval > 0) {
+      this.updateInterval = setInterval(() => this.update(), minInterval);
+    }
+  }
+  /**
+   * Stop the spatial context provider
+   */
+  stop() {
+    if (!this.isRunning) return;
+    this.isRunning = false;
+    if (this.updateInterval) {
+      clearInterval(this.updateInterval);
+      this.updateInterval = null;
+    }
+  }
+  /**
+   * Manual update (for testing or custom update loops)
+   */
+  update() {
+    const now = Date.now();
+    for (const [agentId, state] of this.agents) {
+      this.updateAgentContext(agentId, state, now);
+    }
+  }
+  // ===========================================================================
+  // AGENT REGISTRATION
+  // ===========================================================================
+  /**
+   * Register an agent for spatial awareness
+   */
+  registerAgent(agentId, position, config = {}) {
+    const fullConfig = { ...DEFAULT_SPATIAL_CONFIG, ...config };
+    const state = {
+      id: agentId,
+      position,
+      config: fullConfig,
+      lastContext: null,
+      trackedEntities: /* @__PURE__ */ new Map(),
+      currentRegions: /* @__PURE__ */ new Set(),
+      subscriptions: /* @__PURE__ */ new Map()
+    };
+    this.agents.set(agentId, state);
+    if (this.isRunning) {
+      this.stop();
+      this.start();
+    }
+  }
+  /**
+   * Unregister an agent
+   */
+  unregisterAgent(agentId) {
+    this.agents.delete(agentId);
+  }
+  /**
+   * Update agent position
+   */
+  updateAgentPosition(agentId, position, velocity) {
+    const state = this.agents.get(agentId);
+    if (!state) return;
+    state.position = position;
+    state.velocity = velocity;
+  }
+  /**
+   * Get agent's current spatial context
+   */
+  getContext(agentId) {
+    const state = this.agents.get(agentId);
+    return state?.lastContext || null;
+  }
+  // ===========================================================================
+  // ENTITY MANAGEMENT
+  // ===========================================================================
+  /**
+   * Add or update an entity
+   */
+  setEntity(entity) {
+    this.entities.set(entity.id, entity);
+    this.rebuildQueryIndex();
+  }
+  /**
+   * Remove an entity
+   */
+  removeEntity(entityId) {
+    this.entities.delete(entityId);
+    this.rebuildQueryIndex();
+  }
+  /**
+   * Batch update entities
+   */
+  setEntities(entities) {
+    this.entities.clear();
+    for (const entity of entities) {
+      this.entities.set(entity.id, entity);
+    }
+    this.rebuildQueryIndex();
+  }
+  /**
+   * Get all entities
+   */
+  getEntities() {
+    return Array.from(this.entities.values());
+  }
+  // ===========================================================================
+  // REGION MANAGEMENT
+  // ===========================================================================
+  /**
+   * Add or update a region
+   */
+  setRegion(region) {
+    this.regions.set(region.id, region);
+    this.queryExecutor.updateRegions(Array.from(this.regions.values()));
+  }
+  /**
+   * Remove a region
+   */
+  removeRegion(regionId) {
+    this.regions.delete(regionId);
+    this.queryExecutor.updateRegions(Array.from(this.regions.values()));
+  }
+  /**
+   * Subscribe to region events for an agent
+   */
+  subscribeToRegion(agentId, regionId, callback) {
+    const state = this.agents.get(agentId);
+    if (!state) return;
+    state.subscriptions.set(regionId, { regionId, callback });
+  }
+  /**
+   * Unsubscribe from region events
+   */
+  unsubscribeFromRegion(agentId, regionId) {
+    const state = this.agents.get(agentId);
+    if (!state) return;
+    state.subscriptions.delete(regionId);
+  }
+  // ===========================================================================
+  // QUERIES
+  // ===========================================================================
+  /**
+   * Execute a spatial query
+   */
+  query(query) {
+    return this.queryExecutor.execute(query);
+  }
+  /**
+   * Find nearest entities to position
+   */
+  findNearest(from, count = 1, typeFilter) {
+    return this.query({
+      type: "nearest",
+      from,
+      count,
+      entityTypeFilter: typeFilter
+    });
+  }
+  /**
+   * Find entities within radius
+   */
+  findWithin(from, radius, typeFilter) {
+    return this.query({
+      type: "within",
+      from,
+      radius,
+      entityTypeFilter: typeFilter
+    });
+  }
+  /**
+   * Find visible entities from position
+   */
+  findVisible(from, direction, fov, maxDistance) {
+    return this.query({
+      type: "visible",
+      from,
+      direction,
+      fov,
+      maxDistance
+    });
+  }
+  // ===========================================================================
+  // PRIVATE METHODS
+  // ===========================================================================
+  /**
+   * Update context for a single agent
+   */
+  updateAgentContext(agentId, state, now) {
+    const { config, position } = state;
+    const nearbyEntities = this.findEntitiesInRadius(position, config.perceptionRadius);
+    const filteredEntities = config.entityTypeFilter.length > 0 ? nearbyEntities.filter((e) => config.entityTypeFilter.includes(e.type)) : nearbyEntities;
+    this.checkEntityEvents(agentId, state, filteredEntities, now);
+    const currentRegions = this.findRegionsContaining(position);
+    this.checkRegionEvents(agentId, state, currentRegions, now);
+    const sightLines = config.computeSightLines ? this.computeSightLines(position, filteredEntities) : [];
+    const context = {
+      agentPosition: position,
+      agentVelocity: state.velocity,
+      nearbyEntities: filteredEntities,
+      currentRegions,
+      allRegions: Array.from(this.regions.values()),
+      sightLines,
+      timestamp: now,
+      updateRate: config.updateRate
+    };
+    state.lastContext = context;
+    this.emit("context:updated", agentId, context);
+  }
+  /**
+   * Find entities within radius of position
+   */
+  findEntitiesInRadius(position, radius) {
+    const radiusSq = radius * radius;
+    return Array.from(this.entities.values()).filter(
+      (e) => distanceSquared(position, e.position) <= radiusSq
+    );
+  }
+  /**
+   * Find regions containing position
+   */
+  findRegionsContaining(position) {
+    return Array.from(this.regions.values()).filter((r) => this.isInRegion(position, r));
+  }
+  /**
+   * Check if position is in region
+   */
+  isInRegion(position, region) {
+    if ("radius" in region.bounds) {
+      return isPointInSphere(position, region.bounds);
+    }
+    return isPointInBox(position, region.bounds);
+  }
+  /**
+   * Check for entity enter/exit events
+   */
+  checkEntityEvents(agentId, state, currentEntities, now) {
+    const currentIds = new Set(currentEntities.map((e) => e.id));
+    for (const entity of currentEntities) {
+      if (!state.trackedEntities.has(entity.id)) {
+        const event = {
+          type: "entity_entered",
+          entity,
+          distance: distance(state.position, entity.position),
+          timestamp: now
+        };
+        this.emit("entity:entered", agentId, event);
+      }
+    }
+    for (const [entityId, cachedEntity] of state.trackedEntities) {
+      if (!currentIds.has(entityId)) {
+        const event = {
+          type: "entity_exited",
+          entity: cachedEntity,
+          timestamp: now
+        };
+        this.emit("entity:exited", agentId, event);
+      }
+    }
+    const newTrackedEntities = /* @__PURE__ */ new Map();
+    for (const entity of currentEntities) {
+      newTrackedEntities.set(entity.id, entity);
+    }
+    state.trackedEntities = newTrackedEntities;
+  }
+  /**
+   * Check for region enter/exit events
+   */
+  checkRegionEvents(agentId, state, currentRegions, now) {
+    const currentIds = new Set(currentRegions.map((r) => r.id));
+    for (const region of currentRegions) {
+      if (!state.currentRegions.has(region.id)) {
+        const event = {
+          type: "region_entered",
+          region,
+          timestamp: now
+        };
+        this.emit("region:entered", agentId, event);
+        const sub = state.subscriptions.get(region.id);
+        if (sub) {
+          sub.callback(event);
+        }
+      }
+    }
+    for (const regionId of state.currentRegions) {
+      if (!currentIds.has(regionId)) {
+        const region = this.regions.get(regionId);
+        if (region) {
+          const event = {
+            type: "region_exited",
+            region,
+            timestamp: now
+          };
+          this.emit("region:exited", agentId, event);
+          const sub = state.subscriptions.get(regionId);
+          if (sub) {
+            sub.callback(event);
+          }
+        }
+      }
+    }
+    state.currentRegions = currentIds;
+  }
+  /**
+   * Compute sight lines to entities
+   */
+  computeSightLines(from, entities) {
+    const allEntities = Array.from(this.entities.values());
+    return entities.map((target) => {
+      const dist = distance(from, target.position);
+      const blocked = this.isLineBlocked(from, target.position, allEntities, target.id);
+      return {
+        from,
+        to: target.position,
+        blocked: blocked.blocked,
+        blockingEntity: blocked.blockerId,
+        distance: dist
+      };
+    });
+  }
+  /**
+   * Check if line between two points is blocked
+   */
+  isLineBlocked(from, to, entities, excludeId) {
+    const dir = normalize(subtract(to, from));
+    const maxDist = distance(from, to);
+    for (const entity of entities) {
+      if (entity.id === excludeId) continue;
+      const radius = this.getEntityRadius(entity);
+      const toEntity = subtract(entity.position, from);
+      const projection = this.dot3(toEntity, dir);
+      if (projection < 0 || projection > maxDist) continue;
+      const closest = {
+        x: from.x + dir.x * projection,
+        y: from.y + dir.y * projection,
+        z: from.z + dir.z * projection
+      };
+      const distToLine = distance(closest, entity.position);
+      if (distToLine < radius) {
+        return { blocked: true, blockerId: entity.id };
+      }
+    }
+    return { blocked: false };
+  }
+  /**
+   * Get entity radius
+   */
+  getEntityRadius(entity) {
+    if (!entity.bounds) return 0.5;
+    if ("radius" in entity.bounds) {
+      return entity.bounds.radius;
+    }
+    const box = entity.bounds;
+    const dx = box.max.x - box.min.x;
+    const dy = box.max.y - box.min.y;
+    const dz = box.max.z - box.min.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
+  }
+  /**
+   * Dot product
+   */
+  dot3(a, b) {
+    return a.x * b.x + a.y * b.y + a.z * b.z;
+  }
+  /**
+   * Rebuild the query executor index
+   */
+  rebuildQueryIndex() {
+    this.queryExecutor.updateEntities(Array.from(this.entities.values()));
+  }
+  /**
+   * Get minimum update interval
+   */
+  getMinUpdateInterval() {
+    let minRate = 0;
+    for (const state of this.agents.values()) {
+      if (state.config.updateRate > minRate) {
+        minRate = state.config.updateRate;
+      }
+    }
+    return minRate > 0 ? 1e3 / minRate : 0;
+  }
+};
+
+// src/spatial/SpatialConstraintValidator.ts
+var SpatialConstraintValidator = class {
+  declarations = /* @__PURE__ */ new Map();
+  diagnostics = [];
+  constraintMap = /* @__PURE__ */ new Map();
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * Validate all spatial constraints across a set of declarations.
+   */
+  validate(declarations) {
+    this.reset();
+    for (const decl of declarations) {
+      this.declarations.set(decl.entityId, decl);
+      this.constraintMap.set(decl.entityId, [...decl.constraints]);
+    }
+    this.resolveReferences();
+    this.detectCircularReferences();
+    for (const decl of declarations) {
+      for (const constraint of decl.constraints) {
+        switch (constraint.kind) {
+          case "spatial_adjacent":
+            this.validateAdjacent(decl, constraint);
+            break;
+          case "spatial_contains":
+            this.validateContains(decl, constraint);
+            break;
+          case "spatial_reachable":
+            this.validateReachable(decl, constraint);
+            break;
+          case "spatial_temporal_adjacent":
+            this.validateTemporalAdjacent(decl, constraint);
+            break;
+          case "spatial_temporal_reachable":
+            this.validateTemporalReachable(decl, constraint);
+            break;
+          case "spatial_trajectory":
+            this.validateTrajectory(decl, constraint);
+            break;
+        }
+      }
+    }
+    this.validateCrossConstraintConsistency();
+    const errors = this.diagnostics.filter((d) => d.severity === "error");
+    const warnings = this.diagnostics.filter((d) => d.severity === "warning");
+    const allConstraints = declarations.flatMap((d) => d.constraints);
+    return {
+      valid: errors.length === 0,
+      diagnostics: [...this.diagnostics],
+      constraintMap: new Map(this.constraintMap),
+      stats: {
+        totalConstraints: allConstraints.length,
+        adjacentCount: allConstraints.filter((c) => c.kind === "spatial_adjacent").length,
+        containsCount: allConstraints.filter((c) => c.kind === "spatial_contains").length,
+        reachableCount: allConstraints.filter((c) => c.kind === "spatial_reachable").length,
+        temporalAdjacentCount: allConstraints.filter((c) => c.kind === "spatial_temporal_adjacent").length,
+        temporalReachableCount: allConstraints.filter(
+          (c) => c.kind === "spatial_temporal_reachable"
+        ).length,
+        trajectoryCount: allConstraints.filter((c) => c.kind === "spatial_trajectory").length,
+        errorsCount: errors.length,
+        warningsCount: warnings.length
+      }
+    };
+  }
+  /**
+   * Validate a single constraint in isolation (useful for incremental checks).
+   */
+  validateSingle(source, constraint, allDeclarations) {
+    this.reset();
+    for (const decl of allDeclarations) {
+      this.declarations.set(decl.entityId, decl);
+    }
+    switch (constraint.kind) {
+      case "spatial_adjacent":
+        this.validateAdjacent(source, constraint);
+        break;
+      case "spatial_contains":
+        this.validateContains(source, constraint);
+        break;
+      case "spatial_reachable":
+        this.validateReachable(source, constraint);
+        break;
+      case "spatial_temporal_adjacent":
+        this.validateTemporalAdjacent(source, constraint);
+        break;
+      case "spatial_temporal_reachable":
+        this.validateTemporalReachable(source, constraint);
+        break;
+      case "spatial_trajectory":
+        this.validateTrajectory(source, constraint);
+        break;
+    }
+    return [...this.diagnostics];
+  }
+  // -------------------------------------------------------------------------
+  // Pass 1: Reference resolution
+  // -------------------------------------------------------------------------
+  resolveReferences() {
+    for (const [entityId, decl] of this.declarations) {
+      for (const constraint of decl.constraints) {
+        const targetId = this.getTargetId(constraint);
+        if (!this.declarations.has(targetId)) {
+          const typeMatches = Array.from(this.declarations.values()).filter(
+            (d) => d.entityType === targetId
+          );
+          if (typeMatches.length === 0) {
+            this.addDiagnostic(
+              "error",
+              "HSP033",
+              `Spatial constraint on '${entityId}' references target '${targetId}' which is not declared. Ensure the target entity exists in the composition.`,
+              decl.line ?? 0,
+              decl.column ?? 0,
+              constraint.kind,
+              entityId,
+              targetId,
+              [`Declare entity '${targetId}' or fix the target reference.`]
+            );
+          }
+        }
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pass 2: Circular reference detection
+  // -------------------------------------------------------------------------
+  detectCircularReferences() {
+    const visited = /* @__PURE__ */ new Set();
+    const stack = /* @__PURE__ */ new Set();
+    const visit = (entityId, path) => {
+      if (stack.has(entityId)) {
+        const cycle = [...path, entityId].join(" -> ");
+        const decl2 = this.declarations.get(entityId);
+        this.addDiagnostic(
+          "error",
+          "HSP034",
+          `Circular spatial constraint reference detected: ${cycle}. Spatial constraints must form a directed acyclic graph.`,
+          decl2?.line ?? 0,
+          decl2?.column ?? 0,
+          "spatial_contains",
+          // containment is the most common source of cycles
+          entityId,
+          path[path.length - 1] || entityId,
+          ["Remove one of the constraints in the cycle to break the circular dependency."]
+        );
+        return;
+      }
+      if (visited.has(entityId)) return;
+      visited.add(entityId);
+      stack.add(entityId);
+      const decl = this.declarations.get(entityId);
+      if (decl) {
+        for (const constraint of decl.constraints) {
+          if (constraint.kind === "spatial_contains") {
+            visit(constraint.containedId, [...path, entityId]);
+          }
+        }
+      }
+      stack.delete(entityId);
+    };
+    for (const entityId of this.declarations.keys()) {
+      visit(entityId, []);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pass 3a: Adjacency validation
+  // -------------------------------------------------------------------------
+  validateAdjacent(source, constraint) {
+    const target = this.resolveTarget(constraint.targetId);
+    if (!target) return;
+    if (!source.position || !target.position) {
+      this.addDiagnostic(
+        "info",
+        "HSP030",
+        `spatial_adjacent constraint between '${source.entityId}' and '${constraint.targetId}': positions not fully known at compile time, deferring to runtime verification.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_adjacent",
+        source.entityId,
+        constraint.targetId
+      );
+      return;
+    }
+    const dist = this.computeAxisDistance(
+      source.position,
+      target.position,
+      constraint.axis ?? "xyz"
+    );
+    if (dist > constraint.maxDistance) {
+      this.addDiagnostic(
+        "error",
+        "HSP030",
+        `spatial_adjacent violation: '${source.entityId}' is ${dist.toFixed(2)}m from '${constraint.targetId}' but must be within ${constraint.maxDistance}m` + (constraint.axis && constraint.axis !== "xyz" ? ` (on ${constraint.axis} axis)` : "") + `.${constraint.label ? ` (${constraint.label})` : ""}`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_adjacent",
+        source.entityId,
+        constraint.targetId,
+        [
+          `Move '${source.entityId}' closer to '${constraint.targetId}' (currently ${dist.toFixed(2)}m, max ${constraint.maxDistance}m).`
+        ]
+      );
+    }
+    if (constraint.minDistance !== void 0 && dist < constraint.minDistance) {
+      this.addDiagnostic(
+        "error",
+        "HSP030",
+        `spatial_adjacent violation: '${source.entityId}' is ${dist.toFixed(2)}m from '${constraint.targetId}' but must be at least ${constraint.minDistance}m apart.${constraint.label ? ` (${constraint.label})` : ""}`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_adjacent",
+        source.entityId,
+        constraint.targetId,
+        [
+          `Move '${source.entityId}' further from '${constraint.targetId}' (currently ${dist.toFixed(2)}m, min ${constraint.minDistance}m).`
+        ]
+      );
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pass 3b: Containment validation
+  // -------------------------------------------------------------------------
+  validateContains(source, constraint) {
+    const contained = this.resolveTarget(constraint.containedId);
+    if (!contained) return;
+    if (!source.bounds) {
+      this.addDiagnostic(
+        "warning",
+        "HSP031",
+        `spatial_contains constraint on '${source.entityId}': container has no declared bounds. Containment cannot be verified at compile time.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_contains",
+        source.entityId,
+        constraint.containedId,
+        [`Add bounds to '${source.entityId}' for compile-time containment checking.`]
+      );
+      return;
+    }
+    if (!contained.position) {
+      this.addDiagnostic(
+        "info",
+        "HSP031",
+        `spatial_contains constraint: '${constraint.containedId}' position not known at compile time, deferring to runtime.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_contains",
+        source.entityId,
+        constraint.containedId
+      );
+      return;
+    }
+    const margin = constraint.margin ?? 0;
+    if (constraint.strict && contained.bounds) {
+      this.validateStrictContainment(source, constraint, contained, margin);
+    } else {
+      this.validatePointContainment(source, constraint, contained.position, margin);
+    }
+    if (constraint.recursive) {
+      this.validateRecursiveContainment(source, constraint);
+    }
+  }
+  /**
+   * Check that a point is inside the container bounds (with margin).
+   */
+  validatePointContainment(container, constraint, point, margin) {
+    const bounds = container.bounds;
+    let isInside;
+    if ("radius" in bounds) {
+      const sphere = bounds;
+      const dist = distance(point, sphere.center);
+      isInside = dist <= sphere.radius - margin;
+    } else {
+      const box = bounds;
+      const shrunk = {
+        min: {
+          x: box.min.x + margin,
+          y: box.min.y + margin,
+          z: box.min.z + margin
+        },
+        max: {
+          x: box.max.x - margin,
+          y: box.max.y - margin,
+          z: box.max.z - margin
+        }
+      };
+      isInside = isPointInBox(point, shrunk);
+    }
+    if (!isInside) {
+      this.addDiagnostic(
+        "error",
+        "HSP031",
+        `spatial_contains violation: '${constraint.containedId}' (at [${point.x}, ${point.y}, ${point.z}]) is outside container '${container.entityId}'` + (margin > 0 ? ` (with margin ${margin}m)` : "") + `.${constraint.label ? ` (${constraint.label})` : ""}`,
+        container.line ?? 0,
+        container.column ?? 0,
+        "spatial_contains",
+        container.entityId,
+        constraint.containedId,
+        [
+          `Move '${constraint.containedId}' inside '${container.entityId}' bounds.`,
+          `Alternatively, increase the container's bounds to enclose the target.`
+        ]
+      );
+    }
+  }
+  /**
+   * Strict containment: contained entity's full bounds must be inside container.
+   */
+  validateStrictContainment(container, constraint, contained, margin) {
+    if (!contained.bounds || !container.bounds) return;
+    const containerBox = this.toBoundingBox(container.bounds);
+    const containedBox = this.toBoundingBox(contained.bounds, contained.position);
+    const shrunk = {
+      min: {
+        x: containerBox.min.x + margin,
+        y: containerBox.min.y + margin,
+        z: containerBox.min.z + margin
+      },
+      max: {
+        x: containerBox.max.x - margin,
+        y: containerBox.max.y - margin,
+        z: containerBox.max.z - margin
+      }
+    };
+    const fullyInside = containedBox.min.x >= shrunk.min.x && containedBox.min.y >= shrunk.min.y && containedBox.min.z >= shrunk.min.z && containedBox.max.x <= shrunk.max.x && containedBox.max.y <= shrunk.max.y && containedBox.max.z <= shrunk.max.z;
+    if (!fullyInside) {
+      this.addDiagnostic(
+        "error",
+        "HSP031",
+        `spatial_contains (strict) violation: '${constraint.containedId}' bounds extend outside container '${container.entityId}'` + (margin > 0 ? ` (with margin ${margin}m)` : "") + `.${constraint.label ? ` (${constraint.label})` : ""}`,
+        container.line ?? 0,
+        container.column ?? 0,
+        "spatial_contains",
+        container.entityId,
+        constraint.containedId,
+        [
+          `Resize '${constraint.containedId}' to fit within '${container.entityId}'.`,
+          `Alternatively, enlarge '${container.entityId}' bounds.`
+        ]
+      );
+    }
+  }
+  /**
+   * Recursively check containment for child entities.
+   */
+  validateRecursiveContainment(container, constraint) {
+    const contained = this.declarations.get(constraint.containedId);
+    if (!contained) return;
+    for (const [, decl] of this.declarations) {
+      if (decl.parentId === constraint.containedId && decl.position && container.bounds) {
+        this.validatePointContainment(
+          container,
+          {
+            ...constraint,
+            containedId: decl.entityId,
+            label: `recursive child of '${constraint.containedId}'`
+          },
+          decl.position,
+          constraint.margin ?? 0
+        );
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pass 3c: Reachability validation
+  // -------------------------------------------------------------------------
+  validateReachable(source, constraint) {
+    const target = this.resolveTarget(constraint.targetId);
+    if (!target) return;
+    if (!source.position || !target.position) {
+      this.addDiagnostic(
+        "info",
+        "HSP032",
+        `spatial_reachable constraint between '${source.entityId}' and '${constraint.targetId}': positions not known at compile time, deferring to runtime.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_reachable",
+        source.entityId,
+        constraint.targetId
+      );
+      return;
+    }
+    const straightDist = distance(source.position, target.position);
+    if (constraint.maxPathLength !== void 0 && straightDist > constraint.maxPathLength) {
+      this.addDiagnostic(
+        "error",
+        "HSP032",
+        `spatial_reachable violation: straight-line distance from '${source.entityId}' to '${constraint.targetId}' is ${straightDist.toFixed(2)}m, exceeding maxPathLength of ${constraint.maxPathLength}m. No valid path can exist.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_reachable",
+        source.entityId,
+        constraint.targetId,
+        [
+          `Move '${source.entityId}' closer to '${constraint.targetId}' or increase maxPathLength.`
+        ]
+      );
+      return;
+    }
+    if (constraint.obstacleTypes && constraint.obstacleTypes.length > 0) {
+      const blockingObstacle = this.checkLineOfSight(
+        source.position,
+        target.position,
+        constraint.obstacleTypes,
+        source.entityId,
+        constraint.targetId
+      );
+      if (blockingObstacle) {
+        const severity = constraint.algorithm === "line_of_sight" ? "error" : "warning";
+        this.addDiagnostic(
+          severity,
+          "HSP032",
+          `spatial_reachable: line-of-sight from '${source.entityId}' to '${constraint.targetId}' is blocked by '${blockingObstacle}'` + (constraint.algorithm && constraint.algorithm !== "line_of_sight" ? `. A ${constraint.algorithm} path may still exist (runtime check required).` : ".") + (constraint.label ? ` (${constraint.label})` : ""),
+          source.line ?? 0,
+          source.column ?? 0,
+          "spatial_reachable",
+          source.entityId,
+          constraint.targetId,
+          [
+            `Remove or reposition obstacle '${blockingObstacle}' to clear the path.`,
+            `Alternatively, use algorithm: "navmesh" or "astar" for path-around-obstacles.`
+          ]
+        );
+      }
+    }
+  }
+  /**
+   * Check line-of-sight between two points through known obstacles.
+   * Returns the ID of the first blocking obstacle, or null if clear.
+   */
+  checkLineOfSight(from, to, obstacleTypes, excludeA, excludeB) {
+    const dir = subtract(to, from);
+    const len = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+    if (len === 0) return null;
+    const normalizedDir = normalize(dir);
+    for (const [entityId, decl] of this.declarations) {
+      if (entityId === excludeA || entityId === excludeB) continue;
+      if (!obstacleTypes.includes(decl.entityType)) continue;
+      if (!decl.bounds) continue;
+      const box = this.toBoundingBox(decl.bounds, decl.position);
+      if (this.rayIntersectsBox(from, normalizedDir, box, len)) {
+        return entityId;
+      }
+    }
+    return null;
+  }
+  // -------------------------------------------------------------------------
+  // Pass 3d: Temporal adjacency validation
+  // -------------------------------------------------------------------------
+  validateTemporalAdjacent(source, constraint) {
+    const target = this.resolveTarget(constraint.targetId);
+    if (!target) return;
+    if (constraint.minDuration < 0) {
+      this.addDiagnostic(
+        "error",
+        "HSP036",
+        `spatial_temporal_adjacent on '${source.entityId}': minDuration must be >= 0 (got ${constraint.minDuration}s).`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_adjacent",
+        source.entityId,
+        constraint.targetId,
+        ["Set minDuration to a non-negative value."]
+      );
+      return;
+    }
+    if (constraint.gracePeriod !== void 0 && constraint.gracePeriod < 0) {
+      this.addDiagnostic(
+        "error",
+        "HSP036",
+        `spatial_temporal_adjacent on '${source.entityId}': gracePeriod must be >= 0 (got ${constraint.gracePeriod}s).`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_adjacent",
+        source.entityId,
+        constraint.targetId,
+        ["Set gracePeriod to a non-negative value."]
+      );
+      return;
+    }
+    if (constraint.gracePeriod !== void 0 && constraint.gracePeriod > constraint.minDuration && constraint.minDuration > 0) {
+      this.addDiagnostic(
+        "warning",
+        "HSP036",
+        `spatial_temporal_adjacent on '${source.entityId}': gracePeriod (${constraint.gracePeriod}s) exceeds minDuration (${constraint.minDuration}s). The grace period allows the entity to remain out of range longer than the required adjacency duration.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_adjacent",
+        source.entityId,
+        constraint.targetId,
+        ["Consider reducing gracePeriod or increasing minDuration."]
+      );
+    }
+    if (source.position && target.position) {
+      const dist = this.computeAxisDistance(
+        source.position,
+        target.position,
+        constraint.axis ?? "xyz"
+      );
+      if (dist > constraint.maxDistance) {
+        this.addDiagnostic(
+          "error",
+          "HSP036",
+          `spatial_temporal_adjacent violation: '${source.entityId}' is ${dist.toFixed(2)}m from '${constraint.targetId}' (max: ${constraint.maxDistance}m). The duration constraint of ${constraint.minDuration}s cannot be satisfied if entities start out of range` + (constraint.axis && constraint.axis !== "xyz" ? ` (on ${constraint.axis} axis)` : "") + `.${constraint.label ? ` (${constraint.label})` : ""}`,
+          source.line ?? 0,
+          source.column ?? 0,
+          "spatial_temporal_adjacent",
+          source.entityId,
+          constraint.targetId,
+          [
+            `Move '${source.entityId}' within ${constraint.maxDistance}m of '${constraint.targetId}'.`,
+            `Or ensure runtime movement brings entities into range.`
+          ]
+        );
+      }
+    } else {
+      this.addDiagnostic(
+        "info",
+        "HSP036",
+        `spatial_temporal_adjacent between '${source.entityId}' and '${constraint.targetId}': positions not fully known at compile time. Duration constraint (${constraint.minDuration}s hold, ${constraint.gracePeriod ?? 0}s grace) will be verified at runtime.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_adjacent",
+        source.entityId,
+        constraint.targetId
+      );
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pass 3e: Temporal reachability validation
+  // -------------------------------------------------------------------------
+  validateTemporalReachable(source, constraint) {
+    const target = this.resolveTarget(constraint.targetId);
+    if (!target) return;
+    if (constraint.predictionHorizon <= 0) {
+      this.addDiagnostic(
+        "error",
+        "HSP037",
+        `spatial_temporal_reachable on '${source.entityId}': predictionHorizon must be > 0 (got ${constraint.predictionHorizon}s).`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_reachable",
+        source.entityId,
+        constraint.targetId,
+        ["Set predictionHorizon to a positive value."]
+      );
+      return;
+    }
+    if (constraint.safetyMargin !== void 0 && constraint.safetyMargin < 0) {
+      this.addDiagnostic(
+        "error",
+        "HSP037",
+        `spatial_temporal_reachable on '${source.entityId}': safetyMargin must be >= 0 (got ${constraint.safetyMargin}m).`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_reachable",
+        source.entityId,
+        constraint.targetId,
+        ["Set safetyMargin to a non-negative value."]
+      );
+      return;
+    }
+    if ((!constraint.movingObstacles || constraint.movingObstacles.length === 0) && (!constraint.staticObstacles || constraint.staticObstacles.length === 0)) {
+      this.addDiagnostic(
+        "warning",
+        "HSP037",
+        `spatial_temporal_reachable on '${source.entityId}': no moving or static obstacles specified. Consider using spatial_reachable instead if velocity prediction is not needed.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_reachable",
+        source.entityId,
+        constraint.targetId,
+        [
+          "Add movingObstacles or staticObstacles to the constraint.",
+          "Or use @spatial_reachable if velocity prediction is not needed."
+        ]
+      );
+    }
+    if (source.position && target.position) {
+      const straightDist = distance(source.position, target.position);
+      if (constraint.maxPathLength !== void 0 && straightDist > constraint.maxPathLength) {
+        this.addDiagnostic(
+          "error",
+          "HSP037",
+          `spatial_temporal_reachable violation: straight-line distance from '${source.entityId}' to '${constraint.targetId}' is ${straightDist.toFixed(2)}m, exceeding maxPathLength of ${constraint.maxPathLength}m. No valid path can exist (prediction horizon: ${constraint.predictionHorizon}s).`,
+          source.line ?? 0,
+          source.column ?? 0,
+          "spatial_temporal_reachable",
+          source.entityId,
+          constraint.targetId,
+          [
+            `Move '${source.entityId}' closer to '${constraint.targetId}' or increase maxPathLength.`
+          ]
+        );
+      }
+    } else {
+      this.addDiagnostic(
+        "info",
+        "HSP037",
+        `spatial_temporal_reachable between '${source.entityId}' and '${constraint.targetId}': positions not known at compile time. Velocity-predicted reachability (horizon: ${constraint.predictionHorizon}s) will be verified at runtime.`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_temporal_reachable",
+        source.entityId,
+        constraint.targetId
+      );
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pass 3f: Trajectory validation
+  // -------------------------------------------------------------------------
+  validateTrajectory(source, constraint) {
+    if (constraint.horizon <= 0) {
+      this.addDiagnostic(
+        "error",
+        "HSP038",
+        `spatial_trajectory on '${source.entityId}': horizon must be > 0 (got ${constraint.horizon}s).`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_trajectory",
+        source.entityId,
+        constraint.regionId ?? source.entityId,
+        ["Set horizon to a positive value."]
+      );
+      return;
+    }
+    if (constraint.sampleCount !== void 0 && constraint.sampleCount < 1) {
+      this.addDiagnostic(
+        "error",
+        "HSP038",
+        `spatial_trajectory on '${source.entityId}': sampleCount must be >= 1 (got ${constraint.sampleCount}).`,
+        source.line ?? 0,
+        source.column ?? 0,
+        "spatial_trajectory",
+        source.entityId,
+        constraint.regionId ?? source.entityId,
+        ["Set sampleCount to at least 1."]
+      );
+      return;
+    }
+    switch (constraint.mode) {
+      case "keep_in":
+      case "keep_out": {
+        if (!constraint.regionId) {
+          this.addDiagnostic(
+            "error",
+            "HSP038",
+            `spatial_trajectory (${constraint.mode}) on '${source.entityId}': regionId is required for '${constraint.mode}' mode.`,
+            source.line ?? 0,
+            source.column ?? 0,
+            "spatial_trajectory",
+            source.entityId,
+            source.entityId,
+            [`Add regionId to the @spatial_trajectory constraint.`]
+          );
+        } else {
+          const region = this.resolveTarget(constraint.regionId);
+          if (region && !region.bounds) {
+            this.addDiagnostic(
+              "warning",
+              "HSP038",
+              `spatial_trajectory (${constraint.mode}) on '${source.entityId}': region '${constraint.regionId}' has no declared bounds. Trajectory containment cannot be verified at compile time.`,
+              source.line ?? 0,
+              source.column ?? 0,
+              "spatial_trajectory",
+              source.entityId,
+              constraint.regionId,
+              [`Add bounds to '${constraint.regionId}' for compile-time trajectory checking.`]
+            );
+          }
+        }
+        break;
+      }
+      case "follow": {
+        if (!constraint.referencePath || constraint.referencePath.length < 2) {
+          this.addDiagnostic(
+            "error",
+            "HSP038",
+            `spatial_trajectory (follow) on '${source.entityId}': referencePath must contain at least 2 points for 'follow' mode (got ${constraint.referencePath?.length ?? 0}).`,
+            source.line ?? 0,
+            source.column ?? 0,
+            "spatial_trajectory",
+            source.entityId,
+            constraint.regionId ?? source.entityId,
+            ["Provide a referencePath with at least 2 waypoints."]
+          );
+        }
+        if (constraint.maxDeviation !== void 0 && constraint.maxDeviation <= 0) {
+          this.addDiagnostic(
+            "error",
+            "HSP038",
+            `spatial_trajectory (follow) on '${source.entityId}': maxDeviation must be > 0 (got ${constraint.maxDeviation}m).`,
+            source.line ?? 0,
+            source.column ?? 0,
+            "spatial_trajectory",
+            source.entityId,
+            constraint.regionId ?? source.entityId,
+            ["Set maxDeviation to a positive value."]
+          );
+        }
+        if (source.position && constraint.referencePath && constraint.referencePath.length >= 2) {
+          const distToStart = distance(source.position, constraint.referencePath[0]);
+          const maxDev = constraint.maxDeviation ?? 1;
+          if (distToStart > maxDev * 3) {
+            this.addDiagnostic(
+              "warning",
+              "HSP038",
+              `spatial_trajectory (follow) on '${source.entityId}': entity starts ${distToStart.toFixed(2)}m from the reference path origin (maxDeviation: ${maxDev}m). The entity may immediately violate the constraint.`,
+              source.line ?? 0,
+              source.column ?? 0,
+              "spatial_trajectory",
+              source.entityId,
+              constraint.regionId ?? source.entityId,
+              [`Move '${source.entityId}' closer to the reference path start point.`]
+            );
+          }
+        }
+        break;
+      }
+      case "waypoint": {
+        if (!constraint.waypoints || constraint.waypoints.length === 0) {
+          this.addDiagnostic(
+            "error",
+            "HSP038",
+            `spatial_trajectory (waypoint) on '${source.entityId}': at least one waypoint is required for 'waypoint' mode.`,
+            source.line ?? 0,
+            source.column ?? 0,
+            "spatial_trajectory",
+            source.entityId,
+            constraint.regionId ?? source.entityId,
+            ["Add waypoints with position and radius to the constraint."]
+          );
+        } else {
+          for (let i = 0; i < constraint.waypoints.length; i++) {
+            const wp = constraint.waypoints[i];
+            if (wp.radius <= 0) {
+              this.addDiagnostic(
+                "error",
+                "HSP038",
+                `spatial_trajectory (waypoint) on '${source.entityId}': waypoint ${i} (${wp.label ?? "unnamed"}) has invalid radius ${wp.radius}m. Radius must be > 0.`,
+                source.line ?? 0,
+                source.column ?? 0,
+                "spatial_trajectory",
+                source.entityId,
+                constraint.regionId ?? source.entityId,
+                [`Set waypoint ${i} radius to a positive value.`]
+              );
+            }
+          }
+        }
+        break;
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pass 4: Cross-constraint consistency
+  // -------------------------------------------------------------------------
+  validateCrossConstraintConsistency() {
+    for (const [entityId, decl] of this.declarations) {
+      const adjacentTargets = decl.constraints.filter((c) => c.kind === "spatial_adjacent").map((c) => c.targetId);
+      const containedIn = this.findContainers(entityId);
+      for (const adjacentTarget of adjacentTargets) {
+        for (const containerId of containedIn) {
+          const container = this.declarations.get(containerId);
+          const target = this.resolveTarget(adjacentTarget);
+          if (container?.bounds && target?.position) {
+            const isTargetReachable = this.isPointNearBounds(
+              target.position,
+              container.bounds,
+              // Use the max distance from the adjacency constraint
+              decl.constraints.filter(
+                (c) => c.kind === "spatial_adjacent" && c.targetId === adjacentTarget
+              ).map((c) => c.maxDistance)[0] ?? Infinity
+            );
+            if (!isTargetReachable) {
+              this.addDiagnostic(
+                "warning",
+                "HSP035",
+                `Potential inconsistency: '${entityId}' must be adjacent to '${adjacentTarget}' but is contained in '${containerId}'. '${adjacentTarget}' appears to be outside the container's reachable range.`,
+                decl.line ?? 0,
+                decl.column ?? 0,
+                "spatial_adjacent",
+                entityId,
+                adjacentTarget,
+                [
+                  `Ensure '${adjacentTarget}' is placed near '${containerId}' bounds.`,
+                  `Or adjust the adjacency maxDistance to account for container size.`
+                ]
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Utility methods
+  // -------------------------------------------------------------------------
+  /**
+   * Reset all internal state for a new validation run.
+   */
+  reset() {
+    this.declarations.clear();
+    this.diagnostics = [];
+    this.constraintMap.clear();
+  }
+  /**
+   * Add a diagnostic to the list.
+   */
+  addDiagnostic(severity, code, message, line, column, constraintKind, sourceId, targetId, suggestions) {
+    this.diagnostics.push({
+      severity,
+      code,
+      message,
+      line,
+      column,
+      constraintKind,
+      sourceId,
+      targetId,
+      suggestions
+    });
+  }
+  /**
+   * Resolve a target ID to a declaration, including type-based matching.
+   */
+  resolveTarget(targetId) {
+    const direct = this.declarations.get(targetId);
+    if (direct) return direct;
+    for (const [, decl] of this.declarations) {
+      if (decl.entityType === targetId) return decl;
+    }
+    return null;
+  }
+  /**
+   * Get the target ID from any spatial constraint.
+   */
+  getTargetId(constraint) {
+    switch (constraint.kind) {
+      case "spatial_adjacent":
+        return constraint.targetId;
+      case "spatial_contains":
+        return constraint.containedId;
+      case "spatial_reachable":
+        return constraint.targetId;
+      case "spatial_temporal_adjacent":
+        return constraint.targetId;
+      case "spatial_temporal_reachable":
+        return constraint.targetId;
+      case "spatial_trajectory":
+        return constraint.regionId ?? constraint.sourceId;
+    }
+  }
+  /**
+   * Compute distance along a specific axis filter.
+   */
+  computeAxisDistance(a, b, axis) {
+    switch (axis) {
+      case "x":
+        return Math.abs(b.x - a.x);
+      case "y":
+        return Math.abs(b.y - a.y);
+      case "z":
+        return Math.abs(b.z - a.z);
+      case "xy": {
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        return Math.sqrt(dx * dx + dy * dy);
+      }
+      case "xz": {
+        const dx = b.x - a.x;
+        const dz = b.z - a.z;
+        return Math.sqrt(dx * dx + dz * dz);
+      }
+      case "xyz":
+      default:
+        return distance(a, b);
+    }
+  }
+  /**
+   * Convert any bounds type to a BoundingBox, optionally offset by position.
+   */
+  toBoundingBox(bounds, offset) {
+    const ox = offset?.x ?? 0;
+    const oy = offset?.y ?? 0;
+    const oz = offset?.z ?? 0;
+    if ("radius" in bounds) {
+      const sphere = bounds;
+      return {
+        min: {
+          x: sphere.center.x + ox - sphere.radius,
+          y: sphere.center.y + oy - sphere.radius,
+          z: sphere.center.z + oz - sphere.radius
+        },
+        max: {
+          x: sphere.center.x + ox + sphere.radius,
+          y: sphere.center.y + oy + sphere.radius,
+          z: sphere.center.z + oz + sphere.radius
+        }
+      };
+    }
+    const box = bounds;
+    return {
+      min: { x: box.min.x + ox, y: box.min.y + oy, z: box.min.z + oz },
+      max: { x: box.max.x + ox, y: box.max.y + oy, z: box.max.z + oz }
+    };
+  }
+  /**
+   * Ray-AABB intersection test.
+   */
+  rayIntersectsBox(origin, direction, box, maxDist) {
+    let tmin = -Infinity;
+    let tmax = Infinity;
+    const axes = ["x", "y", "z"];
+    for (const axis of axes) {
+      const d = direction[axis];
+      const o = origin[axis];
+      const bmin = box.min[axis];
+      const bmax = box.max[axis];
+      if (Math.abs(d) < 1e-10) {
+        if (o < bmin || o > bmax) return false;
+      } else {
+        let t1 = (bmin - o) / d;
+        let t2 = (bmax - o) / d;
+        if (t1 > t2) {
+          const tmp = t1;
+          t1 = t2;
+          t2 = tmp;
+        }
+        tmin = Math.max(tmin, t1);
+        tmax = Math.min(tmax, t2);
+        if (tmin > tmax) return false;
+      }
+    }
+    return tmin >= 0 && tmin <= maxDist;
+  }
+  /**
+   * Check if a point is within `extraRadius` of a bounding volume.
+   */
+  isPointNearBounds(point, bounds, extraRadius) {
+    if ("radius" in bounds) {
+      const sphere = bounds;
+      return distance(point, sphere.center) <= sphere.radius + extraRadius;
+    }
+    const box = bounds;
+    const expanded = {
+      min: {
+        x: box.min.x - extraRadius,
+        y: box.min.y - extraRadius,
+        z: box.min.z - extraRadius
+      },
+      max: {
+        x: box.max.x + extraRadius,
+        y: box.max.y + extraRadius,
+        z: box.max.z + extraRadius
+      }
+    };
+    return isPointInBox(point, expanded);
+  }
+  /**
+   * Find all containers that declare spatial_contains with a given entity.
+   */
+  findContainers(entityId) {
+    const containers = [];
+    for (const [containerId, decl] of this.declarations) {
+      for (const constraint of decl.constraints) {
+        if (constraint.kind === "spatial_contains" && constraint.containedId === entityId) {
+          containers.push(containerId);
+        }
+      }
+    }
+    return containers;
+  }
+};
+
+// src/spatial/OctreeSystem.ts
+var OctreeSystem = class {
+  root;
+  maxEntriesPerNode = 8;
+  maxDepth = 8;
+  entryCount = 0;
+  constructor(centerX, centerY, centerZ, halfSize) {
+    this.root = {
+      cx: centerX,
+      cy: centerY,
+      cz: centerZ,
+      halfSize,
+      entries: [],
+      children: null,
+      depth: 0
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Insert / Remove
+  // ---------------------------------------------------------------------------
+  insert(entry) {
+    const inserted = this.insertIntoNode(this.root, entry);
+    if (inserted) this.entryCount++;
+    return inserted;
+  }
+  insertIntoNode(node, entry) {
+    if (!this.containsPoint(node, entry.x, entry.y, entry.z)) return false;
+    if (node.children === null) {
+      node.entries.push(entry);
+      if (node.entries.length > this.maxEntriesPerNode && node.depth < this.maxDepth) {
+        this.subdivide(node);
+      }
+      return true;
+    }
+    for (const child of node.children) {
+      if (this.insertIntoNode(child, entry)) return true;
+    }
+    node.entries.push(entry);
+    return true;
+  }
+  remove(id) {
+    const removed = this.removeFromNode(this.root, id);
+    if (removed) this.entryCount--;
+    return removed;
+  }
+  removeFromNode(node, id) {
+    const idx = node.entries.findIndex((e) => e.id === id);
+    if (idx >= 0) {
+      node.entries.splice(idx, 1);
+      return true;
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        if (this.removeFromNode(child, id)) return true;
+      }
+    }
+    return false;
+  }
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+  queryRadius(x, y, z, radius) {
+    const results = [];
+    this.queryRadiusNode(this.root, x, y, z, radius, results);
+    return results;
+  }
+  queryRadiusNode(node, x, y, z, radius, results) {
+    if (!this.sphereOverlapsNode(node, x, y, z, radius)) return;
+    for (const entry of node.entries) {
+      const dx = entry.x - x, dy = entry.y - y, dz = entry.z - z;
+      if (Math.sqrt(dx * dx + dy * dy + dz * dz) <= radius + entry.radius) {
+        results.push(entry);
+      }
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        this.queryRadiusNode(child, x, y, z, radius, results);
+      }
+    }
+  }
+  sphereOverlapsNode(node, x, y, z, radius) {
+    const dx = Math.max(0, Math.abs(x - node.cx) - node.halfSize);
+    const dy = Math.max(0, Math.abs(y - node.cy) - node.halfSize);
+    const dz = Math.max(0, Math.abs(z - node.cz) - node.halfSize);
+    return dx * dx + dy * dy + dz * dz <= radius * radius;
+  }
+  // ---------------------------------------------------------------------------
+  // Subdivision
+  // ---------------------------------------------------------------------------
+  subdivide(node) {
+    const hs = node.halfSize / 2;
+    node.children = [];
+    for (let x = -1; x <= 1; x += 2) {
+      for (let y = -1; y <= 1; y += 2) {
+        for (let z = -1; z <= 1; z += 2) {
+          node.children.push({
+            cx: node.cx + x * hs,
+            cy: node.cy + y * hs,
+            cz: node.cz + z * hs,
+            halfSize: hs,
+            entries: [],
+            children: null,
+            depth: node.depth + 1
+          });
+        }
+      }
+    }
+    const entries = [...node.entries];
+    node.entries = [];
+    for (const entry of entries) {
+      let placed = false;
+      for (const child of node.children) {
+        if (this.containsPoint(child, entry.x, entry.y, entry.z)) {
+          child.entries.push(entry);
+          placed = true;
+          break;
+        }
+      }
+      if (!placed) node.entries.push(entry);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+  containsPoint(node, x, y, z) {
+    return Math.abs(x - node.cx) <= node.halfSize && Math.abs(y - node.cy) <= node.halfSize && Math.abs(z - node.cz) <= node.halfSize;
+  }
+  getEntryCount() {
+    return this.entryCount;
+  }
+  clear() {
+    this.root.entries = [];
+    this.root.children = null;
+    this.entryCount = 0;
+  }
+};
+
+// src/spatial/OctreeLODSystem.ts
+var DEFAULT_CONFIG = {
+  maxDepth: 6,
+  powerLawExponent: 1.5,
+  baseDistance: 2,
+  maxDistance: 200,
+  vrMode: false,
+  gaussianBudget: 0,
+  perAvatarReservation: 0,
+  maxAvatars: 3,
+  maxAnchorsPerNode: 16
+};
+var OctreeLODSystem = class {
+  root = null;
+  config;
+  thresholds = [];
+  anchorCount = 0;
+  totalGaussianCount = 0;
+  activeAvatars = 0;
+  nodeCount = 0;
+  /** Scene center for distance calculations */
+  sceneCX = 0;
+  sceneCY = 0;
+  sceneCZ = 0;
+  constructor(config) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.computeThresholds();
+  }
+  // ---------------------------------------------------------------------------
+  // Initialization
+  // ---------------------------------------------------------------------------
+  /**
+   * Initialize the octree with scene bounds.
+   * Must be called before inserting anchors.
+   */
+  initialize(centerX, centerY, centerZ, halfSize) {
+    this.sceneCX = centerX;
+    this.sceneCY = centerY;
+    this.sceneCZ = centerZ;
+    this.root = this.createNode(centerX, centerY, centerZ, halfSize, 0);
+    this.anchorCount = 0;
+    this.totalGaussianCount = 0;
+    this.nodeCount = 1;
+  }
+  /**
+   * Initialize from a bounding box (min/max corners).
+   */
+  initializeFromBounds(minX, minY, minZ, maxX, maxY, maxZ) {
+    const cx = (minX + maxX) / 2;
+    const cy = (minY + maxY) / 2;
+    const cz = (minZ + maxZ) / 2;
+    const halfSize = Math.max(maxX - cx, maxY - cy, maxZ - cz);
+    this.initialize(cx, cy, cz, halfSize);
+  }
+  // ---------------------------------------------------------------------------
+  // Threshold Computation
+  // ---------------------------------------------------------------------------
+  /**
+   * Compute power-law transition thresholds for LOD level selection.
+   *
+   * Power-law spacing (Levy flight-inspired, W.030):
+   *   threshold[i] = baseDistance * ((i + 1) / maxDepth) ^ exponent * (maxDistance / baseDistance)
+   *
+   * This produces thresholds that are tightly spaced near the camera
+   * (where detail matters most) and widely spaced at far distances
+   * (where coarse LOD suffices).
+   */
+  computeThresholds() {
+    const { maxDepth, powerLawExponent, baseDistance, maxDistance } = this.config;
+    this.thresholds = [];
+    for (let i = 0; i < maxDepth; i++) {
+      const t = (i + 1) / maxDepth;
+      const threshold = baseDistance + (maxDistance - baseDistance) * Math.pow(t, powerLawExponent);
+      this.thresholds.push(threshold);
+    }
+  }
+  /**
+   * Get the computed transition thresholds (read-only).
+   */
+  getThresholds() {
+    return this.thresholds;
+  }
+  // ---------------------------------------------------------------------------
+  // Anchor Insertion / Removal
+  // ---------------------------------------------------------------------------
+  /**
+   * Insert an anchor Gaussian into the octree at its designated LOD level.
+   * Returns true if successfully inserted.
+   */
+  insertAnchor(anchor) {
+    if (!this.root) return false;
+    if (anchor.lodLevel < 0 || anchor.lodLevel >= this.config.maxDepth) return false;
+    const inserted = this.insertIntoNode(this.root, anchor);
+    if (inserted) {
+      this.anchorCount++;
+      this.totalGaussianCount += anchor.gaussianCount;
+    }
+    return inserted;
+  }
+  insertIntoNode(node, anchor) {
+    if (!this.containsPoint(node, anchor.x, anchor.y, anchor.z)) return false;
+    if (node.depth === anchor.lodLevel) {
+      node.anchors.push(anchor);
+      node.gaussianCount += anchor.gaussianCount;
+      if (node.anchors.length > this.config.maxAnchorsPerNode && node.depth < this.config.maxDepth - 1 && node.children === null) {
+        this.subdivideNode(node);
+      }
+      return true;
+    }
+    if (node.children === null && node.depth < this.config.maxDepth - 1) {
+      this.subdivideNode(node);
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        if (this.insertIntoNode(child, anchor)) return true;
+      }
+    }
+    if (node.depth < anchor.lodLevel) {
+      node.anchors.push(anchor);
+      node.gaussianCount += anchor.gaussianCount;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Remove an anchor by ID.
+   */
+  removeAnchor(id) {
+    if (!this.root) return false;
+    const result = this.removeFromNode(this.root, id);
+    if (result.removed) {
+      this.anchorCount--;
+      this.totalGaussianCount -= result.gaussianCount;
+    }
+    return result.removed;
+  }
+  removeFromNode(node, id) {
+    const idx = node.anchors.findIndex((a) => a.id === id);
+    if (idx >= 0) {
+      const count = node.anchors[idx].gaussianCount;
+      node.anchors.splice(idx, 1);
+      node.gaussianCount -= count;
+      return { removed: true, gaussianCount: count };
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        const result = this.removeFromNode(child, id);
+        if (result.removed) return result;
+      }
+    }
+    return { removed: false, gaussianCount: 0 };
+  }
+  /**
+   * Bulk-insert anchors (more efficient than individual inserts for large scenes).
+   * Anchors are sorted by LOD level for efficient tree traversal.
+   */
+  bulkInsert(anchors) {
+    if (!this.root) return 0;
+    const sorted = [...anchors].sort((a, b) => a.lodLevel - b.lodLevel);
+    let inserted = 0;
+    for (const anchor of sorted) {
+      if (this.insertAnchor(anchor)) {
+        inserted++;
+      }
+    }
+    return inserted;
+  }
+  // ---------------------------------------------------------------------------
+  // LOD Selection (Core Algorithm)
+  // ---------------------------------------------------------------------------
+  /**
+   * Select LOD levels and anchors to render based on camera position.
+   *
+   * Algorithm:
+   * 1. Compute camera distance to scene center
+   * 2. Walk thresholds to find the deepest (finest) LOD level visible
+   * 3. Select all levels from 0 (coarsest) through the deepest visible level
+   * 4. Collect anchors from selected levels
+   * 5. If budget mode, drop deepest levels until under budget
+   * 6. In VR mode, subtract avatar reservations from available budget
+   */
+  selectLOD(cameraX, cameraY, cameraZ, avatarCount) {
+    if (!this.root) {
+      return {
+        selectedLevels: [],
+        totalGaussians: 0,
+        budgetCapped: false,
+        levelsDropped: 0,
+        anchors: [],
+        cameraDistance: 0,
+        thresholds: [...this.thresholds],
+        availableBudget: this.config.gaussianBudget
+      };
+    }
+    const dx = cameraX - this.sceneCX;
+    const dy = cameraY - this.sceneCY;
+    const dz = cameraZ - this.sceneCZ;
+    const cameraDistance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    let deepestVisibleLevel = 0;
+    for (let i = 0; i < this.thresholds.length; i++) {
+      if (cameraDistance < this.thresholds[i]) {
+        deepestVisibleLevel = i + 1;
+      } else {
+        break;
+      }
+    }
+    deepestVisibleLevel = Math.min(deepestVisibleLevel, this.config.maxDepth - 1);
+    const selectedLevels = [];
+    for (let l = 0; l <= deepestVisibleLevel; l++) {
+      selectedLevels.push(l);
+    }
+    const anchorsByLevel = /* @__PURE__ */ new Map();
+    const gaussiansByLevel = /* @__PURE__ */ new Map();
+    for (const level of selectedLevels) {
+      anchorsByLevel.set(level, []);
+      gaussiansByLevel.set(level, 0);
+    }
+    this.collectAnchors(this.root, selectedLevels, anchorsByLevel, gaussiansByLevel);
+    let availableBudget = this.config.gaussianBudget;
+    const actualAvatars = avatarCount ?? this.activeAvatars;
+    if (this.config.vrMode && this.config.perAvatarReservation > 0 && availableBudget > 0) {
+      const clampedAvatars = Math.min(actualAvatars, this.config.maxAvatars);
+      const reserved = clampedAvatars * this.config.perAvatarReservation;
+      availableBudget = Math.max(0, availableBudget - reserved);
+    }
+    let budgetCapped = false;
+    let levelsDropped = 0;
+    let totalGaussians = 0;
+    for (const level of selectedLevels) {
+      totalGaussians += gaussiansByLevel.get(level) ?? 0;
+    }
+    if (availableBudget > 0 && totalGaussians > availableBudget) {
+      budgetCapped = true;
+      const levelUtility = (level) => {
+        const anchorsAtLevel = anchorsByLevel.get(level) || [];
+        const gaussians = gaussiansByLevel.get(level) || 1;
+        const baseUtility = Math.pow(0.7, level);
+        const avgImportance = anchorsAtLevel.length > 0 ? anchorsAtLevel.reduce((sum, a) => sum + (a.importance ?? 0.5), 0) / anchorsAtLevel.length : 0.5;
+        return baseUtility * avgImportance / gaussians;
+      };
+      while (selectedLevels.length > 1 && totalGaussians > availableBudget) {
+        let worstIdx = selectedLevels.length - 1;
+        let worstRatio = Infinity;
+        for (let i = 1; i < selectedLevels.length; i++) {
+          const ratio = levelUtility(selectedLevels[i]);
+          if (ratio < worstRatio) {
+            worstRatio = ratio;
+            worstIdx = i;
+          }
+        }
+        const droppedLevel = selectedLevels.splice(worstIdx, 1)[0];
+        totalGaussians -= gaussiansByLevel.get(droppedLevel) ?? 0;
+        anchorsByLevel.delete(droppedLevel);
+        levelsDropped++;
+      }
+    }
+    const anchors = [];
+    for (const level of selectedLevels) {
+      const levelAnchors = anchorsByLevel.get(level);
+      if (levelAnchors) {
+        anchors.push(...levelAnchors);
+      }
+    }
+    return {
+      selectedLevels,
+      totalGaussians,
+      budgetCapped,
+      levelsDropped,
+      anchors,
+      cameraDistance,
+      thresholds: [...this.thresholds],
+      availableBudget
+    };
+  }
+  /**
+   * Recursively collect anchors from the octree that belong to the selected levels.
+   */
+  collectAnchors(node, levels, anchorsByLevel, gaussiansByLevel) {
+    if (anchorsByLevel.has(node.depth)) {
+      for (const anchor of node.anchors) {
+        if (levels.includes(anchor.lodLevel)) {
+          anchorsByLevel.get(anchor.lodLevel).push(anchor);
+          gaussiansByLevel.set(
+            anchor.lodLevel,
+            (gaussiansByLevel.get(anchor.lodLevel) ?? 0) + anchor.gaussianCount
+          );
+        }
+      }
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        this.collectAnchors(child, levels, anchorsByLevel, gaussiansByLevel);
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Avatar Reservation Management
+  // ---------------------------------------------------------------------------
+  /**
+   * Set the number of active avatars (for VR budget reservation).
+   */
+  setActiveAvatars(count) {
+    this.activeAvatars = Math.min(Math.max(0, count), this.config.maxAvatars);
+  }
+  /**
+   * Get the number of active avatar reservations.
+   */
+  getActiveAvatars() {
+    return this.activeAvatars;
+  }
+  /**
+   * Get the scene-available Gaussian budget after avatar reservations.
+   */
+  getAvailableSceneBudget() {
+    if (this.config.gaussianBudget <= 0) return Infinity;
+    const reserved = this.activeAvatars * this.config.perAvatarReservation;
+    return Math.max(0, this.config.gaussianBudget - reserved);
+  }
+  // ---------------------------------------------------------------------------
+  // Auto-Assignment: Assign LOD Level from Scale
+  // ---------------------------------------------------------------------------
+  /**
+   * Compute the appropriate LOD level for a Gaussian based on its scale.
+   *
+   * Larger Gaussians (coarse detail) -> lower LOD levels (shallow octree nodes)
+   * Smaller Gaussians (fine detail) -> higher LOD levels (deep octree nodes)
+   *
+   * Uses logarithmic mapping: level = floor(log2(maxScale / scale))
+   * Clamped to [0, maxDepth-1].
+   */
+  computeLODLevelFromScale(scale2, maxScaleInScene) {
+    if (scale2 <= 0 || maxScaleInScene <= 0) return this.config.maxDepth - 1;
+    if (scale2 >= maxScaleInScene) return 0;
+    const ratio = maxScaleInScene / scale2;
+    const level = Math.floor(Math.log2(ratio));
+    return Math.min(Math.max(0, level), this.config.maxDepth - 1);
+  }
+  // ---------------------------------------------------------------------------
+  // Octree Internals
+  // ---------------------------------------------------------------------------
+  createNode(cx, cy, cz, halfSize, depth) {
+    return {
+      cx,
+      cy,
+      cz,
+      halfSize,
+      depth,
+      anchors: [],
+      gaussianCount: 0,
+      children: null
+    };
+  }
+  subdivideNode(node) {
+    const hs = node.halfSize / 2;
+    node.children = [];
+    for (let x = -1; x <= 1; x += 2) {
+      for (let y = -1; y <= 1; y += 2) {
+        for (let z = -1; z <= 1; z += 2) {
+          const child = this.createNode(
+            node.cx + x * hs,
+            node.cy + y * hs,
+            node.cz + z * hs,
+            hs,
+            node.depth + 1
+          );
+          node.children.push(child);
+          this.nodeCount++;
+        }
+      }
+    }
+    const remaining = [];
+    for (const anchor of node.anchors) {
+      let placed = false;
+      if (anchor.lodLevel > node.depth) {
+        for (const child of node.children) {
+          if (this.containsPoint(child, anchor.x, anchor.y, anchor.z)) {
+            if (anchor.lodLevel === child.depth) {
+              child.anchors.push(anchor);
+              child.gaussianCount += anchor.gaussianCount;
+            } else {
+              this.insertIntoNode(child, anchor);
+            }
+            placed = true;
+            break;
+          }
+        }
+      }
+      if (!placed) {
+        remaining.push(anchor);
+      }
+    }
+    node.anchors = remaining;
+    node.gaussianCount = remaining.reduce((sum, a) => sum + a.gaussianCount, 0);
+  }
+  containsPoint(node, x, y, z) {
+    return Math.abs(x - node.cx) <= node.halfSize && Math.abs(y - node.cy) <= node.halfSize && Math.abs(z - node.cz) <= node.halfSize;
+  }
+  // ---------------------------------------------------------------------------
+  // Metrics & Diagnostics
+  // ---------------------------------------------------------------------------
+  /**
+   * Get comprehensive metrics about the octree state.
+   */
+  getMetrics() {
+    const levelStats = /* @__PURE__ */ new Map();
+    for (let i = 0; i < this.config.maxDepth; i++) {
+      levelStats.set(i, { level: i, anchorCount: 0, gaussianCount: 0, nodeCount: 0 });
+    }
+    if (this.root) {
+      this.collectMetrics(this.root, levelStats);
+    }
+    let actualDepth = 0;
+    for (const [level, stats] of levelStats) {
+      if (stats.anchorCount > 0 && level > actualDepth) {
+        actualDepth = level;
+      }
+    }
+    return {
+      totalAnchors: this.anchorCount,
+      totalGaussians: this.totalGaussianCount,
+      levels: Array.from(levelStats.values()),
+      actualDepth,
+      activeAvatarReservations: this.activeAvatars,
+      totalNodes: this.nodeCount
+    };
+  }
+  collectMetrics(node, stats) {
+    const ls = stats.get(node.depth);
+    if (ls) {
+      ls.nodeCount++;
+      for (const anchor of node.anchors) {
+        const anchorStats = stats.get(anchor.lodLevel);
+        if (anchorStats) {
+          anchorStats.anchorCount++;
+          anchorStats.gaussianCount += anchor.gaussianCount;
+        }
+      }
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        this.collectMetrics(child, stats);
+      }
+    }
+  }
+  /**
+   * Get the total number of anchors.
+   */
+  getAnchorCount() {
+    return this.anchorCount;
+  }
+  /**
+   * Get the total Gaussian count across all anchors.
+   */
+  getTotalGaussianCount() {
+    return this.totalGaussianCount;
+  }
+  /**
+   * Get the current configuration.
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Update configuration (recomputes thresholds).
+   */
+  updateConfig(config) {
+    this.config = { ...this.config, ...config };
+    this.computeThresholds();
+  }
+  /**
+   * Clear all anchors and reset the octree.
+   * Preserves configuration.
+   */
+  clear() {
+    if (this.root) {
+      this.root.anchors = [];
+      this.root.gaussianCount = 0;
+      this.root.children = null;
+    }
+    this.anchorCount = 0;
+    this.totalGaussianCount = 0;
+    this.nodeCount = this.root ? 1 : 0;
+  }
+  /**
+   * Check if the system has been initialized.
+   */
+  isInitialized() {
+    return this.root !== null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_SPATIAL_CONFIG,
+  OctreeLODSystem,
+  OctreeSystem,
+  SpatialConstraintValidator,
+  SpatialContextProvider,
+  SpatialQueryExecutor,
+  add,
+  boxesOverlap,
+  cross,
+  distance,
+  distanceSquared,
+  dot,
+  getBoxCenter,
+  isPointInBox,
+  isPointInSphere,
+  lerp,
+  normalize,
+  scale,
+  subtract
+});