@auraindustry/aurajs 0.0.7 → 0.1.1

package/src/scene-composition/runtime.mjs

@@ -0,0 +1,751 @@
+export const SCENE_COMPOSITION_SCHEMA = 'aurajs.scene-composition.v1';
+export const SCENE_COMPOSITION_RUNTIME_SCHEMA = 'aurajs.scene-composition-runtime.v1';
+
+const DEFAULT_CAMERA = Object.freeze({
+  mode: 'perspective',
+  fovDegrees: 60,
+  near: 0.1,
+  far: 100,
+  orthographicHeight: 12,
+  position: Object.freeze({ x: 0, y: 3, z: 8 }),
+  target: Object.freeze({ x: 0, y: 1, z: 0 }),
+  up: Object.freeze({ x: 0, y: 1, z: 0 }),
+});
+
+const DEFAULT_AMBIENT_LIGHT = Object.freeze({
+  color: Object.freeze({ r: 1, g: 1, b: 1, a: 1 }),
+  intensity: 0.24,
+});
+
+const DEFAULT_TRANSFORM = Object.freeze({
+  position: Object.freeze({ x: 0, y: 0, z: 0 }),
+  rotation: Object.freeze({ x: 0, y: 0, z: 0 }),
+  scale: Object.freeze({ x: 1, y: 1, z: 1 }),
+});
+
+const DEFAULT_BILLBOARD_COLOR = Object.freeze({ r: 1, g: 1, b: 1, a: 1 });
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneValue(value) {
+  return value == null ? value : structuredClone(value);
+}
+
+function normalizeString(value, fallback = null) {
+  if (typeof value !== 'string') return fallback;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function normalizeNumber(value, fallback) {
+  return Number.isFinite(Number(value)) ? Number(value) : fallback;
+}
+
+function normalizeBoolean(value, fallback = false) {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function normalizeVec3(value, fallback = DEFAULT_TRANSFORM.position) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    x: normalizeNumber(source.x, fallback.x),
+    y: normalizeNumber(source.y, fallback.y),
+    z: normalizeNumber(source.z, fallback.z),
+  };
+}
+
+function normalizeColor(value, fallback = DEFAULT_BILLBOARD_COLOR) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    r: normalizeNumber(source.r, fallback.r),
+    g: normalizeNumber(source.g, fallback.g),
+    b: normalizeNumber(source.b, fallback.b),
+    a: normalizeNumber(source.a, fallback.a),
+  };
+}
+
+function normalizeTransform(value) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    position: normalizeVec3(source.position, DEFAULT_TRANSFORM.position),
+    rotation: normalizeVec3(source.rotation, DEFAULT_TRANSFORM.rotation),
+    scale: normalizeVec3(source.scale, DEFAULT_TRANSFORM.scale),
+  };
+}
+
+function normalizeCameraConfig(value) {
+  const source = isPlainObject(value) ? value : {};
+  const mode = normalizeString(source.mode, DEFAULT_CAMERA.mode);
+  return {
+    mode: mode === 'orthographic' ? 'orthographic' : 'perspective',
+    fovDegrees: normalizeNumber(source.fovDegrees, DEFAULT_CAMERA.fovDegrees),
+    near: normalizeNumber(source.near, DEFAULT_CAMERA.near),
+    far: normalizeNumber(source.far, DEFAULT_CAMERA.far),
+    orthographicHeight: normalizeNumber(
+      source.orthographicHeight,
+      DEFAULT_CAMERA.orthographicHeight,
+    ),
+    position: normalizeVec3(source.position, DEFAULT_CAMERA.position),
+    target: normalizeVec3(source.target, DEFAULT_CAMERA.target),
+    up: normalizeVec3(source.up, DEFAULT_CAMERA.up),
+  };
+}
+
+function normalizeDirectionalLight(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    id: normalizeString(source.id, fallbackId),
+    direction: normalizeVec3(source.direction, { x: -0.4, y: -1, z: -0.3 }),
+    color: normalizeColor(source.color, DEFAULT_BILLBOARD_COLOR),
+    intensity: normalizeNumber(source.intensity, 1),
+  };
+}
+
+function normalizePointLight(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    id: normalizeString(source.id, fallbackId),
+    position: normalizeVec3(source.position, DEFAULT_TRANSFORM.position),
+    color: normalizeColor(source.color, DEFAULT_BILLBOARD_COLOR),
+    intensity: normalizeNumber(source.intensity, 1),
+    range: normalizeNumber(source.range, 8),
+  };
+}
+
+function normalizeSpotLight(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    id: normalizeString(source.id, fallbackId),
+    position: normalizeVec3(source.position, DEFAULT_TRANSFORM.position),
+    direction: normalizeVec3(source.direction, { x: 0, y: -1, z: 0 }),
+    color: normalizeColor(source.color, DEFAULT_BILLBOARD_COLOR),
+    intensity: normalizeNumber(source.intensity, 1),
+    range: normalizeNumber(source.range, 12),
+    innerConeDegrees: normalizeNumber(source.innerConeDegrees, 18),
+    outerConeDegrees: normalizeNumber(source.outerConeDegrees, 28),
+  };
+}
+
+function normalizeEntityList(value, normalizeEntry, defaultPrefix) {
+  const out = [];
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      const normalized = normalizeEntry(value[index], `${defaultPrefix}-${index + 1}`);
+      if (normalized) out.push(normalized);
+    }
+    return out;
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value).sort((left, right) => left.localeCompare(right));
+    for (const key of keys) {
+      const entry = value[key];
+      const normalized = normalizeEntry(
+        isPlainObject(entry) ? { id: key, ...entry } : { id: key, value: entry },
+        key,
+      );
+      if (normalized) out.push(normalized);
+    }
+  }
+  return out;
+}
+
+function normalizeNodeEntry(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  const id = normalizeString(source.id, fallbackId);
+  if (!id) return null;
+  return {
+    id,
+    parentId: normalizeString(source.parentId, null),
+    transform: normalizeTransform(source.transform || source),
+    tags: normalizeTags(source.tags),
+    metadata: isPlainObject(source.metadata) ? cloneValue(source.metadata) : {},
+  };
+}
+
+function normalizeMeshEntry(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  const id = normalizeString(source.id, fallbackId);
+  if (!id) return null;
+  return {
+    id,
+    nodeId: normalizeString(source.nodeId, null),
+    mesh: source.mesh ?? source.meshHandle ?? null,
+    material: source.material ?? source.materialHandle ?? null,
+    visible: source.visible !== false,
+    transform: normalizeTransform(source.transform),
+    tags: normalizeTags(source.tags),
+    metadata: isPlainObject(source.metadata) ? cloneValue(source.metadata) : {},
+  };
+}
+
+function normalizeBillboardEntry(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  const id = normalizeString(source.id, fallbackId);
+  if (!id) return null;
+  return {
+    id,
+    nodeId: normalizeString(source.nodeId, null),
+    textureHandle: source.textureHandle ?? source.texture ?? null,
+    visible: source.visible !== false,
+    width: normalizeNumber(source.width, 1),
+    height: normalizeNumber(source.height, 1),
+    mode: normalizeString(source.mode, 'face') === 'axis' ? 'axis' : 'face',
+    color: normalizeColor(source.color, DEFAULT_BILLBOARD_COLOR),
+    offset: normalizeVec3(source.offset, DEFAULT_TRANSFORM.position),
+    tags: normalizeTags(source.tags),
+    metadata: isPlainObject(source.metadata) ? cloneValue(source.metadata) : {},
+  };
+}
+
+function normalizeAvatarEntry(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  const id = normalizeString(source.id, fallbackId);
+  if (!id) return null;
+  return {
+    id,
+    nodeId: normalizeString(source.nodeId, null),
+    runtime: isAvatarRuntime(source.runtime) ? source.runtime : null,
+    factory: typeof source.factory === 'function' ? source.factory : null,
+    graph: isPlainObject(source.graph) ? cloneValue(source.graph) : null,
+    options: isPlainObject(source.options) ? cloneValue(source.options) : {},
+    spawn: isPlainObject(source.spawn) ? cloneValue(source.spawn) : {},
+    input: isPlainObject(source.input) ? cloneValue(source.input) : {},
+    autoSpawn: source.autoSpawn !== false,
+    tags: normalizeTags(source.tags),
+    metadata: isPlainObject(source.metadata) ? cloneValue(source.metadata) : {},
+  };
+}
+
+function normalizeTriggerWatchEntry(value, fallbackId) {
+  if (typeof value === 'string') {
+    const id = normalizeString(value, fallbackId);
+    if (!id) return null;
+    return {
+      id,
+      avatarId: id,
+      nodeId: null,
+      position: null,
+      getPosition: null,
+    };
+  }
+  const source = isPlainObject(value) ? value : {};
+  const id = normalizeString(source.id, fallbackId);
+  if (!id) return null;
+  return {
+    id,
+    avatarId: normalizeString(source.avatarId, null),
+    nodeId: normalizeString(source.nodeId, null),
+    position: isPlainObject(source.position)
+      ? normalizeVec3(source.position, DEFAULT_TRANSFORM.position)
+      : null,
+    getPosition: typeof source.getPosition === 'function' ? source.getPosition : null,
+  };
+}
+
+function normalizeTriggerEntry(value, fallbackId) {
+  const source = isPlainObject(value) ? value : {};
+  const id = normalizeString(source.id, fallbackId);
+  if (!id) return null;
+  const shape = isPlainObject(source.shape) ? source.shape : {};
+  const type = normalizeString(shape.type, 'box');
+  return {
+    id,
+    nodeId: normalizeString(source.nodeId, null),
+    offset: normalizeVec3(source.offset, DEFAULT_TRANSFORM.position),
+    shape: {
+      type: type === 'sphere' ? 'sphere' : 'box',
+      size: normalizeVec3(shape.size, { x: 1, y: 1, z: 1 }),
+      radius: normalizeNumber(shape.radius, 0.75),
+    },
+    watch: normalizeEntityList(source.watch, normalizeTriggerWatchEntry, `${id}-watch`),
+    onEnter: typeof source.onEnter === 'function' ? source.onEnter : null,
+    onExit: typeof source.onExit === 'function' ? source.onExit : null,
+    tags: normalizeTags(source.tags),
+    metadata: isPlainObject(source.metadata) ? cloneValue(source.metadata) : {},
+  };
+}
+
+function normalizeTags(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value
+    .map((entry) => normalizeString(entry, null))
+    .filter(Boolean))]
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function indexEntities(entries) {
+  const byId = new Map();
+  for (const entry of entries) {
+    byId.set(entry.id, entry);
+  }
+  return byId;
+}
+
+function mergeEntityLists(baseEntries = [], patchEntries = []) {
+  const byId = new Map(baseEntries.map((entry) => [entry.id, cloneValue(entry)]));
+  for (const entry of patchEntries) {
+    byId.set(entry.id, cloneValue(entry));
+  }
+  return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function normalizeSceneCompositionConfig(config = {}) {
+  if (!isPlainObject(config)) {
+    throw new TypeError('Scene composition config must be an object.');
+  }
+
+  const lights = isPlainObject(config.lights) ? config.lights : {};
+  return {
+    schema: SCENE_COMPOSITION_SCHEMA,
+    name: normalizeString(config.name, null),
+    clearColor: isPlainObject(config.clearColor)
+      ? normalizeColor(config.clearColor, { r: 0.02, g: 0.025, b: 0.03, a: 1 })
+      : null,
+    camera: normalizeCameraConfig(config.camera),
+    lights: {
+      ambient: isPlainObject(lights.ambient)
+        ? {
+          color: normalizeColor(lights.ambient.color, DEFAULT_AMBIENT_LIGHT.color),
+          intensity: normalizeNumber(lights.ambient.intensity, DEFAULT_AMBIENT_LIGHT.intensity),
+        }
+        : {
+          color: normalizeColor(DEFAULT_AMBIENT_LIGHT.color),
+          intensity: DEFAULT_AMBIENT_LIGHT.intensity,
+        },
+      directional: normalizeEntityList(lights.directional, normalizeDirectionalLight, 'directional'),
+      point: normalizeEntityList(lights.point, normalizePointLight, 'point'),
+      spot: normalizeEntityList(lights.spot, normalizeSpotLight, 'spot'),
+    },
+    nodes: normalizeEntityList(config.nodes, normalizeNodeEntry, 'node')
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    meshes: normalizeEntityList(config.meshes, normalizeMeshEntry, 'mesh')
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    billboards: normalizeEntityList(config.billboards, normalizeBillboardEntry, 'billboard')
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    avatars: normalizeEntityList(config.avatars, normalizeAvatarEntry, 'avatar')
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    triggers: normalizeEntityList(config.triggers, normalizeTriggerEntry, 'trigger')
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    metadata: isPlainObject(config.metadata) ? cloneValue(config.metadata) : {},
+  };
+}
+
+export function mergeSceneCompositionConfig(baseConfig = {}, patchConfig = {}) {
+  const base = normalizeSceneCompositionConfig(baseConfig);
+  const patch = normalizeSceneCompositionConfig(patchConfig);
+  const source = isPlainObject(patchConfig) ? patchConfig : {};
+  return {
+    schema: SCENE_COMPOSITION_SCHEMA,
+    name: Object.prototype.hasOwnProperty.call(source, 'name') ? patch.name : base.name,
+    clearColor: Object.prototype.hasOwnProperty.call(source, 'clearColor')
+      ? patch.clearColor
+      : base.clearColor,
+    camera: Object.prototype.hasOwnProperty.call(source, 'camera') ? patch.camera : base.camera,
+    lights: Object.prototype.hasOwnProperty.call(source, 'lights') ? patch.lights : base.lights,
+    nodes: mergeEntityLists(base.nodes, patch.nodes),
+    meshes: mergeEntityLists(base.meshes, patch.meshes),
+    billboards: mergeEntityLists(base.billboards, patch.billboards),
+    avatars: mergeEntityLists(base.avatars, patch.avatars),
+    triggers: mergeEntityLists(base.triggers, patch.triggers),
+    metadata: {
+      ...cloneValue(base.metadata),
+      ...cloneValue(patch.metadata),
+    },
+  };
+}
+
+export function sanitizeSceneCompositionForSerialization(config = {}) {
+  const normalized = normalizeSceneCompositionConfig(config);
+  return {
+    schema: normalized.schema,
+    name: normalized.name,
+    clearColor: normalized.clearColor,
+    camera: normalized.camera,
+    lights: normalized.lights,
+    nodes: normalized.nodes,
+    meshes: normalized.meshes.map((entry) => ({
+      ...entry,
+      mesh: sanitizeHandle(entry.mesh),
+      material: sanitizeHandle(entry.material),
+    })),
+    billboards: normalized.billboards.map((entry) => ({
+      ...entry,
+      textureHandle: sanitizeHandle(entry.textureHandle),
+    })),
+    avatars: normalized.avatars.map((entry) => ({
+      id: entry.id,
+      nodeId: entry.nodeId,
+      graph: sanitizeJsonValue(entry.graph),
+      options: sanitizeJsonValue(entry.options),
+      spawn: sanitizeJsonValue(entry.spawn),
+      input: sanitizeJsonValue(entry.input),
+      autoSpawn: entry.autoSpawn,
+      tags: entry.tags,
+      metadata: sanitizeJsonValue(entry.metadata),
+    })),
+    triggers: normalized.triggers.map((entry) => ({
+      id: entry.id,
+      nodeId: entry.nodeId,
+      offset: entry.offset,
+      shape: entry.shape,
+      watch: entry.watch.map((watcher) => ({
+        id: watcher.id,
+        avatarId: watcher.avatarId,
+        nodeId: watcher.nodeId,
+        position: watcher.position,
+      })),
+      tags: entry.tags,
+      metadata: sanitizeJsonValue(entry.metadata),
+    })),
+    metadata: sanitizeJsonValue(normalized.metadata),
+  };
+}
+
+function sanitizeHandle(value) {
+  return Number.isFinite(Number(value)) || typeof value === 'string'
+    ? value
+    : null;
+}
+
+function sanitizeJsonValue(value) {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function createNodeStateMap(nodes) {
+  const nodeMap = new Map();
+  for (const definition of nodes) {
+    nodeMap.set(definition.id, {
+      id: definition.id,
+      parentId: definition.parentId,
+      local: cloneValue(definition.transform),
+      world: cloneValue(definition.transform),
+      nodeId: null,
+      tags: [...definition.tags],
+      metadata: cloneValue(definition.metadata),
+    });
+  }
+  return nodeMap;
+}
+
+function topologicallySortNodes(nodeMap) {
+  const visited = new Set();
+  const stack = [];
+
+  function visit(nodeId) {
+    if (visited.has(nodeId)) return;
+    visited.add(nodeId);
+    const node = nodeMap.get(nodeId);
+    if (!node) return;
+    if (node.parentId && nodeMap.has(node.parentId)) {
+      visit(node.parentId);
+    }
+    stack.push(node);
+  }
+
+  for (const nodeId of [...nodeMap.keys()].sort((left, right) => left.localeCompare(right))) {
+    visit(nodeId);
+  }
+  return stack;
+}
+
+export function composeWorldTransforms(nodeMap) {
+  const ordered = topologicallySortNodes(nodeMap);
+  for (const node of ordered) {
+    const parent = node.parentId ? nodeMap.get(node.parentId) : null;
+    if (!parent) {
+      node.world = cloneValue(node.local);
+      continue;
+    }
+    node.world = {
+      position: {
+        x: parent.world.position.x + (node.local.position.x * parent.world.scale.x),
+        y: parent.world.position.y + (node.local.position.y * parent.world.scale.y),
+        z: parent.world.position.z + (node.local.position.z * parent.world.scale.z),
+      },
+      rotation: {
+        x: parent.world.rotation.x + node.local.rotation.x,
+        y: parent.world.rotation.y + node.local.rotation.y,
+        z: parent.world.rotation.z + node.local.rotation.z,
+      },
+      scale: {
+        x: parent.world.scale.x * node.local.scale.x,
+        y: parent.world.scale.y * node.local.scale.y,
+        z: parent.world.scale.z * node.local.scale.z,
+      },
+    };
+  }
+  return nodeMap;
+}
+
+function isAvatarRuntime(value) {
+  return !!value
+    && typeof value === 'object'
+    && typeof value.getState === 'function'
+    && typeof value.tick === 'function';
+}
+
+function configureCamera(aura, camera) {
+  const camera3d = aura?.camera3d;
+  if (!camera3d) return;
+  if (camera.mode === 'orthographic' && typeof camera3d.orthographic === 'function') {
+    camera3d.orthographic(camera.orthographicHeight, camera.near, camera.far);
+  } else if (typeof camera3d.perspective === 'function') {
+    camera3d.perspective(camera.fovDegrees, camera.near, camera.far);
+  }
+  if (typeof camera3d.setPosition === 'function') {
+    camera3d.setPosition(camera.position.x, camera.position.y, camera.position.z);
+  }
+  if (typeof camera3d.lookAt === 'function') {
+    camera3d.lookAt(camera.target.x, camera.target.y, camera.target.z);
+  }
+}
+
+function configureLights(aura, lights) {
+  const light = aura?.light;
+  if (!light) return;
+  if (typeof light.ambient === 'function') {
+    light.ambient(cloneValue(lights.ambient.color), lights.ambient.intensity);
+  }
+  if (typeof light.directional === 'function') {
+    for (const entry of lights.directional) {
+      light.directional(cloneValue(entry.direction), cloneValue(entry.color), entry.intensity);
+    }
+  }
+  if (typeof light.point === 'function') {
+    for (const entry of lights.point) {
+      light.point(cloneValue(entry.position), cloneValue(entry.color), entry.intensity, entry.range);
+    }
+  }
+  if (typeof light.spot === 'function') {
+    for (const entry of lights.spot) {
+      light.spot({
+        position: cloneValue(entry.position),
+        direction: cloneValue(entry.direction),
+        color: cloneValue(entry.color),
+        intensity: entry.intensity,
+        range: entry.range,
+        innerConeDegrees: entry.innerConeDegrees,
+        outerConeDegrees: entry.outerConeDegrees,
+      });
+    }
+  }
+}
+
+export function mountSceneNodes(aura, nodeMap) {
+  const scene3d = aura?.scene3d;
+  if (!scene3d || typeof scene3d.createNode !== 'function') {
+    return nodeMap;
+  }
+  const ordered = topologicallySortNodes(nodeMap);
+  for (const node of ordered) {
+    node.nodeId = scene3d.createNode(cloneValue(node.local));
+    if (node.parentId) {
+      const parent = nodeMap.get(node.parentId);
+      if (parent?.nodeId && typeof scene3d.setParent === 'function') {
+        scene3d.setParent(node.nodeId, parent.nodeId);
+      }
+    }
+    if (typeof scene3d.setLocalTransform === 'function') {
+      scene3d.setLocalTransform(node.nodeId, cloneValue(node.local));
+    }
+  }
+  return nodeMap;
+}
+
+export function syncRuntimeNodeTransform(aura, nodeState) {
+  const scene3d = aura?.scene3d;
+  if (!scene3d || !nodeState?.nodeId || typeof scene3d.setLocalTransform !== 'function') return;
+  scene3d.setLocalTransform(nodeState.nodeId, cloneValue(nodeState.local));
+}
+
+export function createTriggerRuntimeState(definition) {
+  return {
+    id: definition.id,
+    activeWatcherIds: new Set(),
+    lastEvent: null,
+    enterCount: 0,
+    exitCount: 0,
+  };
+}
+
+export function resolveNodeWorldPosition(nodeMap, nodeId, offset = DEFAULT_TRANSFORM.position) {
+  const node = nodeId ? nodeMap.get(nodeId) : null;
+  const base = node ? node.world.position : DEFAULT_TRANSFORM.position;
+  return {
+    x: base.x + offset.x,
+    y: base.y + offset.y,
+    z: base.z + offset.z,
+  };
+}
+
+export function resolveAvatarPosition(avatarState) {
+  const state = avatarState?.controller?.getState ? avatarState.controller.getState() : null;
+  const avatar = state?.avatar || state || {};
+  const position = avatar.position || avatar.renderPosition || avatar.visual?.position || null;
+  if (!isPlainObject(position)) {
+    return null;
+  }
+  return normalizeVec3(position, DEFAULT_TRANSFORM.position);
+}
+
+export function resolveTriggerWatcherPosition(nodeMap, avatars, watcher) {
+  if (typeof watcher.getPosition === 'function') {
+    const resolved = watcher.getPosition();
+    return isPlainObject(resolved) ? normalizeVec3(resolved, DEFAULT_TRANSFORM.position) : null;
+  }
+  if (watcher.position) {
+    return normalizeVec3(watcher.position, DEFAULT_TRANSFORM.position);
+  }
+  if (watcher.avatarId) {
+    const avatarState = avatars.get(watcher.avatarId);
+    return resolveAvatarPosition(avatarState);
+  }
+  if (watcher.nodeId) {
+    return resolveNodeWorldPosition(nodeMap, watcher.nodeId);
+  }
+  return null;
+}
+
+function pointInTrigger(position, trigger, origin) {
+  const delta = {
+    x: position.x - origin.x,
+    y: position.y - origin.y,
+    z: position.z - origin.z,
+  };
+  if (trigger.shape.type === 'sphere') {
+    const distanceSq = (delta.x * delta.x) + (delta.y * delta.y) + (delta.z * delta.z);
+    return distanceSq <= (trigger.shape.radius * trigger.shape.radius);
+  }
+  return Math.abs(delta.x) <= (trigger.shape.size.x / 2)
+    && Math.abs(delta.y) <= (trigger.shape.size.y / 2)
+    && Math.abs(delta.z) <= (trigger.shape.size.z / 2);
+}
+
+export function evaluateTriggers(nodeMap, avatars, triggerDefinitions, triggerRuntimeState) {
+  const events = [];
+  for (const trigger of triggerDefinitions) {
+    const runtime = triggerRuntimeState.get(trigger.id);
+    if (!runtime) continue;
+    const origin = resolveNodeWorldPosition(nodeMap, trigger.nodeId, trigger.offset);
+    const nextActive = new Set();
+    for (const watcher of trigger.watch) {
+      const position = resolveTriggerWatcherPosition(nodeMap, avatars, watcher);
+      if (!position) continue;
+      const inside = pointInTrigger(position, trigger, origin);
+      if (!inside) continue;
+      nextActive.add(watcher.id);
+      if (!runtime.activeWatcherIds.has(watcher.id)) {
+        runtime.enterCount += 1;
+        runtime.lastEvent = {
+          type: 'enter',
+          triggerId: trigger.id,
+          watcherId: watcher.id,
+          position,
+        };
+        if (typeof trigger.onEnter === 'function') {
+          trigger.onEnter(cloneValue(runtime.lastEvent));
+        }
+        events.push(cloneValue(runtime.lastEvent));
+      }
+    }
+    for (const watcherId of runtime.activeWatcherIds) {
+      if (nextActive.has(watcherId)) continue;
+      runtime.exitCount += 1;
+      runtime.lastEvent = {
+        type: 'exit',
+        triggerId: trigger.id,
+        watcherId,
+        position: null,
+      };
+      if (typeof trigger.onExit === 'function') {
+        trigger.onExit(cloneValue(runtime.lastEvent));
+      }
+      events.push(cloneValue(runtime.lastEvent));
+    }
+    runtime.activeWatcherIds = nextActive;
+  }
+  return events;
+}
+
+export function buildSceneCompositionSnapshot(state) {
+  composeWorldTransforms(state.nodeMap);
+  return {
+    schema: SCENE_COMPOSITION_RUNTIME_SCHEMA,
+    name: state.config.name,
+    mounted: state.mounted,
+    clearColor: cloneValue(state.config.clearColor),
+    camera: cloneValue(state.config.camera),
+    lights: cloneValue(state.config.lights),
+    nodes: [...state.nodeMap.values()]
+      .map((entry) => ({
+        id: entry.id,
+        parentId: entry.parentId,
+        nodeId: entry.nodeId,
+        local: cloneValue(entry.local),
+        world: cloneValue(entry.world),
+        tags: [...entry.tags],
+        metadata: cloneValue(entry.metadata),
+      }))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    meshes: state.config.meshes.map((entry) => ({
+      id: entry.id,
+      nodeId: entry.nodeId,
+      visible: entry.visible,
+      mesh: sanitizeHandle(entry.mesh),
+      material: sanitizeHandle(entry.material),
+      transform: cloneValue(entry.transform),
+      tags: [...entry.tags],
+      metadata: cloneValue(entry.metadata),
+    })),
+    billboards: state.config.billboards.map((entry) => ({
+      id: entry.id,
+      nodeId: entry.nodeId,
+      visible: entry.visible,
+      textureHandle: sanitizeHandle(entry.textureHandle),
+      width: entry.width,
+      height: entry.height,
+      mode: entry.mode,
+      offset: cloneValue(entry.offset),
+      tags: [...entry.tags],
+      metadata: cloneValue(entry.metadata),
+    })),
+    avatars: [...state.avatars.values()]
+      .map((entry) => ({
+        id: entry.id,
+        nodeId: entry.definition.nodeId,
+        spawned: entry.spawned,
+        tags: [...entry.definition.tags],
+        metadata: cloneValue(entry.definition.metadata),
+        state: entry.controller && typeof entry.controller.getState === 'function'
+          ? cloneValue(entry.controller.getState())
+          : null,
+      }))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    triggers: state.config.triggers.map((entry) => {
+      const runtime = state.triggerState.get(entry.id);
+      return {
+        id: entry.id,
+        nodeId: entry.nodeId,
+        shape: cloneValue(entry.shape),
+        offset: cloneValue(entry.offset),
+        activeWatcherIds: runtime ? [...runtime.activeWatcherIds].sort((left, right) => left.localeCompare(right)) : [],
+        enterCount: runtime?.enterCount || 0,
+        exitCount: runtime?.exitCount || 0,
+        lastEvent: runtime?.lastEvent ? cloneValue(runtime.lastEvent) : null,
+        tags: [...entry.tags],
+        metadata: cloneValue(entry.metadata),
+      };
+    }),
+    stats: {
+      nodeCount: state.nodeMap.size,
+      meshCount: state.config.meshes.length,
+      billboardCount: state.config.billboards.length,
+      avatarCount: state.avatars.size,
+      triggerCount: state.config.triggers.length,
+      lastFrameTriggerEventCount: state.lastTriggerEvents.length,
+    },
+  };
+}