worldorbit 2.5.15 → 2.5.17

package/dist/unpkg/worldorbit.js

@@ -647,6 +647,7 @@ var WorldOrbit = (() => {
       system,
       groups: [],
       relations: [],
+      events: [],
       objects
     };
   }
@@ -1104,8 +1105,10 @@ var WorldOrbit = (() => {
     const scaleModel = resolveScaleModel(layoutPreset, options.scaleModel);
     const spacingFactor = layoutPresetSpacing(layoutPreset);
     const systemId = document2.system?.id ?? null;
-    const objectMap = new Map(document2.objects.map((object) => [object.id, object]));
-    const relationships = buildSceneRelationships(document2.objects, objectMap);
+    const activeEventId = options.activeEventId ?? null;
+    const effectiveObjects = createEffectiveObjects(document2.objects, document2.events ?? [], activeEventId);
+    const objectMap = new Map(effectiveObjects.map((object) => [object.id, object]));
+    const relationships = buildSceneRelationships(effectiveObjects, objectMap);
     const positions = /* @__PURE__ */ new Map();
     const orbitDrafts = [];
     const leaderDrafts = [];
@@ -1114,7 +1117,7 @@ var WorldOrbit = (() => {
     const atObjects = [];
     const surfaceChildren = /* @__PURE__ */ new Map();
     const orbitChildren = /* @__PURE__ */ new Map();
-    for (const object of document2.objects) {
+    for (const object of effectiveObjects) {
       const placement = object.placement;
       if (!placement) {
         rootObjects.push(object);
@@ -1209,13 +1212,14 @@ var WorldOrbit = (() => {
     const objects = [...positions.values()].map((position) => createSceneObject(position, scaleModel, relationships));
     const orbitVisuals = orbitDrafts.map((draft) => createOrbitVisual(draft, relationships.groupIds.get(draft.object.id) ?? null));
     const leaders = leaderDrafts.map((draft) => createLeaderLine(draft));
-    const labels = createSceneLabels(objects, height, scaleModel.labelMultiplier);
+    const labels = createSceneLabels(objects, width, height, scaleModel.labelMultiplier);
     const relations = createSceneRelations(document2, objects);
-    const layers = createSceneLayers(orbitVisuals, relations, leaders, objects, labels);
-    const groups = createSceneGroups(objects, orbitVisuals, leaders, labels, relationships);
+    const events = createSceneEvents(document2.events ?? [], objects, activeEventId);
+    const layers = createSceneLayers(orbitVisuals, relations, events, leaders, objects, labels);
+    const groups = createSceneGroups(objects, orbitVisuals, leaders, labels, relationships, scaleModel.labelMultiplier);
     const semanticGroups = createSceneSemanticGroups(document2, objects);
     const viewpoints = createSceneViewpoints(document2, projection, frame.preset, relationships, objectMap);
-    const contentBounds = calculateContentBounds(width, height, objects, orbitVisuals, leaders, labels);
+    const contentBounds = calculateContentBounds(width, height, objects, orbitVisuals, leaders, labels, scaleModel.labelMultiplier);
     return {
       width,
       height,
@@ -1241,6 +1245,8 @@ var WorldOrbit = (() => {
       groups,
       semanticGroups,
       viewpoints,
+      events,
+      activeEventId,
       objects,
       orbitVisuals,
       relations,
@@ -1259,6 +1265,35 @@ var WorldOrbit = (() => {
       y: center.y + dx * sin + dy * cos
     };
   }
+  function createEffectiveObjects(objects, events, activeEventId) {
+    const cloned = objects.map((object) => structuredClone(object));
+    if (!activeEventId) {
+      return cloned;
+    }
+    const activeEvent = events.find((event) => event.id === activeEventId);
+    if (!activeEvent) {
+      return cloned;
+    }
+    const objectMap = new Map(cloned.map((object) => [object.id, object]));
+    for (const pose of activeEvent.positions) {
+      const object = objectMap.get(pose.objectId);
+      if (!object) {
+        continue;
+      }
+      object.placement = pose.placement ? structuredClone(pose.placement) : null;
+      if (pose.inner) {
+        object.properties.inner = { ...pose.inner };
+      } else {
+        delete object.properties.inner;
+      }
+      if (pose.outer) {
+        object.properties.outer = { ...pose.outer };
+      } else {
+        delete object.properties.outer;
+      }
+    }
+    return cloned;
+  }
   function resolveLayoutPreset(document2) {
     const rawScale = String(document2.system?.properties.scale ?? "balanced").toLowerCase();
     switch (rawScale) {
@@ -1414,24 +1449,14 @@ var WorldOrbit = (() => {
       hidden: draft.object.properties.hidden === true
     };
   }
-  function createSceneLabels(objects, sceneHeight, labelMultiplier) {
+  function createSceneLabels(objects, sceneWidth, sceneHeight, labelMultiplier) {
     const labels = [];
     const occupied = [];
-    const visibleObjects = [...objects].filter((object) => !object.hidden && object.object.renderHints?.renderLabel !== false).sort((left, right) => left.sortKey - right.sortKey);
+    const objectMap = new Map(objects.map((object) => [object.objectId, object]));
+    const visibleObjects = [...objects].filter((object) => !object.hidden && object.object.renderHints?.renderLabel !== false).sort(compareLabelPlacementOrder);
     for (const object of visibleObjects) {
-      const direction = object.y > sceneHeight * 0.62 ? -1 : 1;
-      const labelHalfWidth = estimateLabelHalfWidth(object, labelMultiplier);
-      let labelY = object.y + direction * (object.radius + 18 * labelMultiplier);
-      let secondaryY = labelY + direction * (16 * labelMultiplier);
-      let bounds = createLabelRect(object.x, labelY, secondaryY, labelHalfWidth, direction);
-      let attempts = 0;
-      while (occupied.some((entry) => rectsOverlap(entry, bounds)) && attempts < 10) {
-        labelY += direction * 14 * labelMultiplier;
-        secondaryY += direction * 14 * labelMultiplier;
-        bounds = createLabelRect(object.x, labelY, secondaryY, labelHalfWidth, direction);
-        attempts += 1;
-      }
-      occupied.push(bounds);
+      const placement = selectLabelPlacement(object, objectMap, occupied, sceneWidth, sceneHeight, labelMultiplier) ?? createLabelPlacement(object, defaultVerticalDirection(object, objectMap.get(object.parentId ?? "") ?? null, sceneHeight), 0, labelMultiplier);
+      occupied.push(createLabelRect(object, placement, labelMultiplier));
       labels.push({
         renderId: `${object.renderId}-label`,
         objectId: object.objectId,
@@ -1440,17 +1465,128 @@ var WorldOrbit = (() => {
         semanticGroupIds: [...object.semanticGroupIds],
         label: object.label,
         secondaryLabel: object.secondaryLabel,
-        x: object.x,
-        y: labelY,
-        secondaryY,
-        textAnchor: "middle",
-        direction: direction < 0 ? "above" : "below",
+        x: placement.x,
+        y: placement.labelY,
+        secondaryY: placement.secondaryY,
+        textAnchor: placement.textAnchor,
+        direction: placement.direction,
         hidden: object.hidden
       });
     }
     return labels;
   }
-  function createSceneLayers(orbitVisuals, relations, leaders, objects, labels) {
+  function compareLabelPlacementOrder(left, right) {
+    const priorityDiff = labelPlacementPriority(left) - labelPlacementPriority(right);
+    if (priorityDiff !== 0) {
+      return priorityDiff;
+    }
+    const renderPriorityDiff = (right.object.renderHints?.renderPriority ?? 0) - (left.object.renderHints?.renderPriority ?? 0);
+    if (renderPriorityDiff !== 0) {
+      return renderPriorityDiff;
+    }
+    return left.sortKey - right.sortKey;
+  }
+  function labelPlacementPriority(object) {
+    switch (object.object.type) {
+      case "star":
+        return 0;
+      case "planet":
+        return 1;
+      case "moon":
+        return 2;
+      case "belt":
+      case "ring":
+        return 3;
+      case "asteroid":
+      case "comet":
+        return 4;
+      case "structure":
+      case "phenomenon":
+        return 5;
+    }
+  }
+  function selectLabelPlacement(object, objectMap, occupied, sceneWidth, sceneHeight, labelMultiplier) {
+    for (const direction of preferredLabelDirections(object, objectMap, sceneWidth, sceneHeight)) {
+      const maxAttempts = direction === "left" || direction === "right" ? 4 : 6;
+      for (let attempt = 0; attempt <= maxAttempts; attempt += 1) {
+        const placement = createLabelPlacement(object, direction, attempt, labelMultiplier);
+        const rect = createLabelRect(object, placement, labelMultiplier);
+        if (!occupied.some((entry) => rectsOverlap(entry, rect))) {
+          return placement;
+        }
+      }
+    }
+    return null;
+  }
+  function preferredLabelDirections(object, objectMap, sceneWidth, sceneHeight) {
+    const parent = object.parentId ? objectMap.get(object.parentId) ?? null : null;
+    const vertical = defaultVerticalDirection(object, parent, sceneHeight);
+    const oppositeVertical = vertical === "below" ? "above" : "below";
+    const horizontal = defaultHorizontalDirection(object, parent, sceneWidth);
+    const oppositeHorizontal = horizontal === "right" ? "left" : "right";
+    const preferHorizontal = object.object.type === "structure" || object.object.type === "phenomenon" || object.object.placement?.mode === "at" || object.object.placement?.mode === "surface" || object.object.placement?.mode === "free";
+    return preferHorizontal ? [horizontal, vertical, oppositeHorizontal, oppositeVertical] : [vertical, horizontal, oppositeVertical, oppositeHorizontal];
+  }
+  function defaultVerticalDirection(object, parent, sceneHeight) {
+    if (parent && Math.abs(object.y - parent.y) > 6) {
+      return object.y >= parent.y ? "below" : "above";
+    }
+    return object.y > sceneHeight * 0.62 ? "above" : "below";
+  }
+  function defaultHorizontalDirection(object, parent, sceneWidth) {
+    if (parent && Math.abs(object.x - parent.x) > 6) {
+      return object.x >= parent.x ? "right" : "left";
+    }
+    return object.x >= sceneWidth / 2 ? "right" : "left";
+  }
+  function createLabelPlacement(object, direction, attempt, labelMultiplier) {
+    const step = 14 * labelMultiplier;
+    switch (direction) {
+      case "above": {
+        const labelY = object.y - (object.radius + 18 * labelMultiplier + attempt * step);
+        return {
+          x: object.x,
+          labelY,
+          secondaryY: labelY - 16 * labelMultiplier,
+          textAnchor: "middle",
+          direction
+        };
+      }
+      case "below": {
+        const labelY = object.y + object.radius + 18 * labelMultiplier + attempt * step;
+        return {
+          x: object.x,
+          labelY,
+          secondaryY: labelY + 16 * labelMultiplier,
+          textAnchor: "middle",
+          direction
+        };
+      }
+      case "left": {
+        const x = object.x - (object.visualRadius + 16 * labelMultiplier + attempt * step);
+        const labelY = object.y - 4 * labelMultiplier;
+        return {
+          x,
+          labelY,
+          secondaryY: labelY + 16 * labelMultiplier,
+          textAnchor: "end",
+          direction
+        };
+      }
+      case "right": {
+        const x = object.x + object.visualRadius + 16 * labelMultiplier + attempt * step;
+        const labelY = object.y - 4 * labelMultiplier;
+        return {
+          x,
+          labelY,
+          secondaryY: labelY + 16 * labelMultiplier,
+          textAnchor: "start",
+          direction
+        };
+      }
+    }
+  }
+  function createSceneLayers(orbitVisuals, relations, events, leaders, objects, labels) {
     const backOrbitIds = orbitVisuals.filter((visual) => !visual.hidden && Boolean(visual.backArcPath)).map((visual) => visual.renderId);
     const frontOrbitIds = orbitVisuals.filter((visual) => !visual.hidden).map((visual) => visual.renderId);
     return [
@@ -1465,6 +1601,10 @@ var WorldOrbit = (() => {
         id: "relations",
         renderIds: relations.filter((relation) => !relation.hidden).map((relation) => relation.renderId)
       },
+      {
+        id: "events",
+        renderIds: events.filter((event) => !event.hidden).map((event) => event.renderId)
+      },
       {
         id: "objects",
         renderIds: objects.filter((object) => !object.hidden).map((object) => object.renderId)
@@ -1476,7 +1616,7 @@ var WorldOrbit = (() => {
       { id: "metadata", renderIds: ["wo-title", "wo-subtitle", "wo-meta"] }
     ];
   }
-  function createSceneGroups(objects, orbitVisuals, leaders, labels, relationships) {
+  function createSceneGroups(objects, orbitVisuals, leaders, labels, relationships, labelMultiplier) {
     const groups = /* @__PURE__ */ new Map();
     const ensureGroup = (groupId) => {
       if (!groupId) {
@@ -1525,7 +1665,7 @@ var WorldOrbit = (() => {
       }
     }
     for (const group of groups.values()) {
-      group.contentBounds = calculateGroupBounds(group, objects, orbitVisuals, leaders, labels);
+      group.contentBounds = calculateGroupBounds(group, objects, orbitVisuals, leaders, labels, labelMultiplier);
     }
     return [...groups.values()].sort((left, right) => left.label.localeCompare(right.label));
   }
@@ -1559,6 +1699,29 @@ var WorldOrbit = (() => {
       };
     }).sort((left, right) => left.relation.id.localeCompare(right.relation.id));
   }
+  function createSceneEvents(events, objects, activeEventId) {
+    const objectMap = new Map(objects.map((object) => [object.objectId, object]));
+    return events.map((event) => {
+      const objectIds = [.../* @__PURE__ */ new Set([
+        ...event.targetObjectId ? [event.targetObjectId] : [],
+        ...event.participantObjectIds
+      ])];
+      const positions = objectIds.map((objectId) => objectMap.get(objectId)).filter(Boolean);
+      const centroidX = positions.length > 0 ? positions.reduce((sum, object) => sum + object.x, 0) / positions.length : 0;
+      const centroidY = positions.length > 0 ? positions.reduce((sum, object) => sum + object.y, 0) / positions.length : 0;
+      return {
+        renderId: `${createRenderId(event.id)}-event`,
+        eventId: event.id,
+        event,
+        objectIds,
+        participantIds: [...event.participantObjectIds],
+        targetObjectId: event.targetObjectId,
+        x: centroidX,
+        y: centroidY,
+        hidden: event.hidden || positions.length === 0 || positions.every((object) => object.hidden) || activeEventId !== null && event.id !== activeEventId
+      };
+    }).sort((left, right) => left.event.id.localeCompare(right.event.id));
+  }
   function createSceneViewpoints(document2, projection, preset, relationships, objectMap) {
     const generatedOverview = createGeneratedOverviewViewpoint(document2, projection, preset);
     const drafts = /* @__PURE__ */ new Map();
@@ -1612,6 +1775,7 @@ var WorldOrbit = (() => {
       summary: "Fit the whole system with the current atlas defaults.",
       objectId: null,
       selectedObjectId: null,
+      eventIds: [],
       projection,
       preset,
       rotationDeg: 0,
@@ -1648,6 +1812,9 @@ var WorldOrbit = (() => {
           draft.select = normalizedValue;
         }
         return;
+      case "events":
+        draft.eventIds = splitListValue(normalizedValue);
+        return;
       case "projection":
       case "view":
         draft.projection = parseViewProjection(normalizedValue) ?? projection;
@@ -1704,6 +1871,7 @@ var WorldOrbit = (() => {
       summary: draft.summary?.trim() || createViewpointSummary(label, objectId, filter),
       objectId,
       selectedObjectId,
+      eventIds: [...new Set(draft.eventIds ?? [])],
       projection: draft.projection ?? projection,
       preset: draft.preset ?? preset,
       rotationDeg: draft.rotationDeg ?? 0,
@@ -1761,7 +1929,7 @@ var WorldOrbit = (() => {
         next["orbits-front"] = enabled;
         continue;
       }
-      if (rawLayer === "background" || rawLayer === "guides" || rawLayer === "orbits-back" || rawLayer === "orbits-front" || rawLayer === "relations" || rawLayer === "objects" || rawLayer === "labels" || rawLayer === "metadata") {
+      if (rawLayer === "background" || rawLayer === "guides" || rawLayer === "orbits-back" || rawLayer === "orbits-front" || rawLayer === "relations" || rawLayer === "events" || rawLayer === "objects" || rawLayer === "labels" || rawLayer === "metadata") {
         next[rawLayer] = enabled;
       }
     }
@@ -1809,7 +1977,7 @@ var WorldOrbit = (() => {
     }
     return parts.join(" - ");
   }
-  function calculateContentBounds(width, height, objects, orbitVisuals, leaders, labels) {
+  function calculateContentBounds(width, height, objects, orbitVisuals, leaders, labels, labelMultiplier) {
     let minX = Number.POSITIVE_INFINITY;
     let minY = Number.POSITIVE_INFINITY;
     let maxX = Number.NEGATIVE_INFINITY;
@@ -1839,7 +2007,7 @@ var WorldOrbit = (() => {
     for (const label of labels) {
       if (label.hidden)
         continue;
-      includeLabelBounds(label, include);
+      includeLabelBounds(label, include, labelMultiplier);
     }
     if (!Number.isFinite(minX) || !Number.isFinite(minY)) {
       return createBounds(0, 0, width, height);
@@ -1877,13 +2045,10 @@ var WorldOrbit = (() => {
     include(object.x - object.visualRadius - 24, object.y - object.visualRadius - 16);
     include(object.x + object.visualRadius + 24, object.y + object.visualRadius + 36);
   }
-  function includeLabelBounds(label, include) {
-    const labelScale = 1;
-    const labelHalfWidth = estimateLabelHalfWidthFromText(label.label, label.secondaryLabel, labelScale);
-    include(label.x - labelHalfWidth, label.y - 18);
-    include(label.x + labelHalfWidth, label.y + 8);
-    include(label.x - labelHalfWidth, label.secondaryY - 14);
-    include(label.x + labelHalfWidth, label.secondaryY + 8);
+  function includeLabelBounds(label, include, labelMultiplier) {
+    const bounds = createLabelRectFromText(label.x, label.y, label.secondaryY, label.textAnchor, label.direction, label.label, label.secondaryLabel, labelMultiplier);
+    include(bounds.left, bounds.top);
+    include(bounds.right, bounds.bottom);
   }
   function placeObject(object, x, y, depth, positions, orbitDrafts, leaderDrafts, context) {
     if (positions.has(object.id)) {
@@ -2273,7 +2438,7 @@ var WorldOrbit = (() => {
         return null;
     }
   }
-  function calculateGroupBounds(group, objects, orbitVisuals, leaders, labels) {
+  function calculateGroupBounds(group, objects, orbitVisuals, leaders, labels, labelMultiplier) {
     let minX = Number.POSITIVE_INFINITY;
     let minY = Number.POSITIVE_INFINITY;
     let maxX = Number.NEGATIVE_INFINITY;
@@ -2302,7 +2467,7 @@ var WorldOrbit = (() => {
     }
     for (const label of labels) {
       if (!label.hidden && group.labelIds.includes(label.objectId)) {
-        includeLabelBounds(label, include);
+        includeLabelBounds(label, include, labelMultiplier);
       }
     }
     if (!Number.isFinite(minX) || !Number.isFinite(minY)) {
@@ -2327,12 +2492,28 @@ var WorldOrbit = (() => {
     }
     return current.id;
   }
-  function createLabelRect(x, labelY, secondaryY, labelHalfWidth, direction) {
+  function createLabelRect(object, placement, labelMultiplier) {
+    return createLabelRectFromText(placement.x, placement.labelY, placement.secondaryY, placement.textAnchor, placement.direction, object.label, object.secondaryLabel, labelMultiplier);
+  }
+  function createLabelRectFromText(x, labelY, secondaryY, textAnchor, direction, label, secondaryLabel, labelMultiplier) {
+    const labelHalfWidth = estimateLabelHalfWidthFromText(label, secondaryLabel, labelMultiplier);
+    const labelWidth = labelHalfWidth * 2;
+    const topPadding = direction === "above" ? 18 : 12;
+    const bottomPadding = direction === "above" ? 8 : 12;
+    let left = x - labelHalfWidth;
+    let right = x + labelHalfWidth;
+    if (textAnchor === "start") {
+      left = x;
+      right = x + labelWidth;
+    } else if (textAnchor === "end") {
+      left = x - labelWidth;
+      right = x;
+    }
     return {
-      left: x - labelHalfWidth,
-      right: x + labelHalfWidth,
-      top: Math.min(labelY, secondaryY) - (direction < 0 ? 18 : 12),
-      bottom: Math.max(labelY, secondaryY) + (direction < 0 ? 8 : 12)
+      left,
+      right,
+      top: Math.min(labelY, secondaryY) - topPadding,
+      bottom: Math.max(labelY, secondaryY) + bottomPadding
     };
   }
   function rectsOverlap(left, right) {
@@ -2519,11 +2700,6 @@ var WorldOrbit = (() => {
   function customColorFor(value) {
     return typeof value === "string" && value.trim() ? value : void 0;
   }
-  function estimateLabelHalfWidth(object, labelMultiplier) {
-    const primaryWidth = object.label.length * 4.6 * labelMultiplier + 18;
-    const secondaryWidth = object.secondaryLabel.length * 3.9 * labelMultiplier + 18;
-    return Math.max(primaryWidth, secondaryWidth, object.visualRadius + 18);
-  }
   function estimateLabelHalfWidthFromText(label, secondaryLabel, labelMultiplier) {
     const primaryWidth = label.length * 4.6 * labelMultiplier + 18;
     const secondaryWidth = secondaryLabel.length * 3.9 * labelMultiplier + 18;
@@ -2563,6 +2739,7 @@ var WorldOrbit = (() => {
       system,
       groups: structuredClone(document2.groups ?? []),
       relations: structuredClone(document2.relations ?? []),
+      events: structuredClone(document2.events ?? []),
       objects: document2.objects.map(cloneWorldOrbitObject),
       diagnostics
     };
@@ -2570,7 +2747,7 @@ var WorldOrbit = (() => {
   function upgradeDocumentToDraftV2(document2, options = {}) {
     return convertAtlasDocumentToLegacyDraft(upgradeDocumentToV2(document2, options));
   }
-  function materializeAtlasDocument(document2) {
+  function materializeAtlasDocument(document2, options = {}) {
     const system = document2.system ? {
       type: "system",
       id: document2.system.id,
@@ -2581,6 +2758,8 @@ var WorldOrbit = (() => {
       properties: materializeDraftSystemProperties(document2.system),
       info: materializeDraftSystemInfo(document2.system)
     } : null;
+    const objects = document2.objects.map(cloneWorldOrbitObject);
+    applyEventPoseOverrides(objects, document2.events ?? [], options.activeEventId ?? null);
     return {
       format: "worldorbit",
       version: "1.0",
@@ -2588,7 +2767,8 @@ var WorldOrbit = (() => {
       system,
       groups: structuredClone(document2.groups ?? []),
       relations: structuredClone(document2.relations ?? []),
-      objects: document2.objects.map(cloneWorldOrbitObject)
+      events: document2.events.map(cloneWorldOrbitEvent),
+      objects
     };
   }
   function materializeDraftDocument(document2) {
@@ -2716,6 +2896,7 @@ var WorldOrbit = (() => {
       summary: viewpoint.summary,
       focusObjectId: viewpoint.objectId,
       selectedObjectId: viewpoint.selectedObjectId,
+      events: [...viewpoint.eventIds],
       projection: viewpoint.projection,
       preset: viewpoint.preset,
       zoom: viewpoint.scale,
@@ -2748,6 +2929,52 @@ var WorldOrbit = (() => {
       info: { ...object.info }
     };
   }
+  function cloneWorldOrbitEvent(event) {
+    return {
+      ...event,
+      participantObjectIds: [...event.participantObjectIds],
+      tags: [...event.tags],
+      positions: event.positions.map(cloneWorldOrbitEventPose)
+    };
+  }
+  function cloneWorldOrbitEventPose(pose) {
+    return {
+      objectId: pose.objectId,
+      placement: clonePlacement(pose.placement),
+      inner: pose.inner ? { ...pose.inner } : void 0,
+      outer: pose.outer ? { ...pose.outer } : void 0
+    };
+  }
+  function clonePlacement(placement) {
+    return placement ? structuredClone(placement) : null;
+  }
+  function applyEventPoseOverrides(objects, events, activeEventId) {
+    if (!activeEventId) {
+      return;
+    }
+    const event = events.find((entry) => entry.id === activeEventId);
+    if (!event) {
+      return;
+    }
+    const objectMap = new Map(objects.map((object) => [object.id, object]));
+    for (const pose of event.positions) {
+      const object = objectMap.get(pose.objectId);
+      if (!object) {
+        continue;
+      }
+      object.placement = clonePlacement(pose.placement);
+      if (pose.inner) {
+        object.properties.inner = { ...pose.inner };
+      } else {
+        delete object.properties.inner;
+      }
+      if (pose.outer) {
+        object.properties.outer = { ...pose.outer };
+      } else {
+        delete object.properties.outer;
+      }
+    }
+  }
   function cloneProperties(properties) {
     const next = {};
     for (const [key, value] of Object.entries(properties)) {
@@ -2845,6 +3072,9 @@ var WorldOrbit = (() => {
       if ((viewpoint.filter?.groupIds.length ?? 0) > 0) {
         info2[`${prefix}.groups`] = viewpoint.filter?.groupIds.join(" ") ?? "";
       }
+      if (viewpoint.events.length > 0) {
+        info2[`${prefix}.events`] = viewpoint.events.join(" ");
+      }
     }
     for (const annotation of system.annotations) {
       const prefix = `annotation.${annotation.id}`;
@@ -2869,7 +3099,7 @@ var WorldOrbit = (() => {
     if (orbitFront !== void 0 || orbitBack !== void 0) {
       tokens.push(orbitFront !== false || orbitBack !== false ? "orbits" : "-orbits");
     }
-    for (const key of ["background", "guides", "relations", "objects", "labels", "metadata"]) {
+    for (const key of ["background", "guides", "relations", "events", "objects", "labels", "metadata"]) {
       if (layers[key] !== void 0) {
         tokens.push(layers[key] ? key : `-${key}`);
       }
@@ -2973,6 +3203,10 @@ var WorldOrbit = (() => {
       lines.push("");
       lines.push(...formatAtlasRelation(relation));
     }
+    for (const event of [...document2.events].sort(compareIdLike)) {
+      lines.push("");
+      lines.push(...formatAtlasEvent(event));
+    }
     const sortedObjects = [...document2.objects].sort(compareObjects);
     if (sortedObjects.length > 0 && lines.at(-1) !== "") {
       lines.push("");
@@ -3003,6 +3237,10 @@ var WorldOrbit = (() => {
       lines.push("");
       lines.push(...formatAtlasRelation(relation));
     }
+    for (const event of [...legacy.events].sort(compareIdLike)) {
+      lines.push("");
+      lines.push(...formatAtlasEvent(event));
+    }
     const sortedObjects = [...legacy.objects].sort(compareObjects);
     if (sortedObjects.length > 0 && lines.at(-1) !== "") {
       lines.push("");
@@ -3214,6 +3452,9 @@ var WorldOrbit = (() => {
     if (layerTokens.length > 0) {
       lines.push(`  layers ${layerTokens.join(" ")}`);
     }
+    if (viewpoint.events.length > 0) {
+      lines.push(`  events ${viewpoint.events.join(" ")}`);
+    }
     if (viewpoint.filter) {
       lines.push("  filter");
       if (viewpoint.filter.query) {
@@ -3286,6 +3527,54 @@ var WorldOrbit = (() => {
     }
     return lines;
   }
+  function formatAtlasEvent(event) {
+    const lines = [`event ${event.id}`, `  kind ${quoteIfNeeded(event.kind)}`];
+    if (event.label) {
+      lines.push(`  label ${quoteIfNeeded(event.label)}`);
+    }
+    if (event.summary) {
+      lines.push(`  summary ${quoteIfNeeded(event.summary)}`);
+    }
+    if (event.targetObjectId) {
+      lines.push(`  target ${event.targetObjectId}`);
+    }
+    if (event.participantObjectIds.length > 0) {
+      lines.push(`  participants ${event.participantObjectIds.join(" ")}`);
+    }
+    if (event.timing) {
+      lines.push(`  timing ${quoteIfNeeded(event.timing)}`);
+    }
+    if (event.visibility) {
+      lines.push(`  visibility ${quoteIfNeeded(event.visibility)}`);
+    }
+    if (event.tags.length > 0) {
+      lines.push(`  tags ${event.tags.map(quoteIfNeeded).join(" ")}`);
+    }
+    if (event.color) {
+      lines.push(`  color ${quoteIfNeeded(event.color)}`);
+    }
+    if (event.hidden) {
+      lines.push("  hidden true");
+    }
+    if (event.positions.length > 0) {
+      lines.push("");
+      lines.push("  positions");
+      for (const pose of [...event.positions].sort(comparePoseObjectId)) {
+        lines.push(`    pose ${pose.objectId}`);
+        for (const fieldLine of formatEventPoseFields(pose)) {
+          lines.push(`      ${fieldLine}`);
+        }
+      }
+    }
+    return lines;
+  }
+  function formatEventPoseFields(pose) {
+    return [
+      ...formatPlacement(pose.placement),
+      ...formatOptionalUnit("inner", pose.inner),
+      ...formatOptionalUnit("outer", pose.outer)
+    ];
+  }
   function formatValue(value) {
     if (Array.isArray(value)) {
       return value.map((item) => quoteIfNeeded(item)).join(" ");
@@ -3327,7 +3616,7 @@ var WorldOrbit = (() => {
     if (orbitFront !== void 0 || orbitBack !== void 0) {
       tokens.push(orbitFront !== false || orbitBack !== false ? "orbits" : "-orbits");
     }
-    for (const key of ["background", "guides", "relations", "objects", "labels", "metadata"]) {
+    for (const key of ["background", "guides", "relations", "events", "objects", "labels", "metadata"]) {
       if (layers[key] !== void 0) {
         tokens.push(layers[key] ? key : `-${key}`);
       }
@@ -3355,6 +3644,9 @@ var WorldOrbit = (() => {
   function compareIdLike(left, right) {
     return left.id.localeCompare(right.id);
   }
+  function comparePoseObjectId(left, right) {
+    return left.objectId.localeCompare(right.objectId);
+  }
   function objectTypeIndex(objectType) {
     switch (objectType) {
       case "star":
@@ -3550,6 +3842,7 @@ var WorldOrbit = (() => {
     const diagnostics = [];
     const objectMap = new Map(document2.objects.map((object) => [object.id, object]));
     const groupIds = new Set(document2.groups.map((group) => group.id));
+    const eventIds = new Set(document2.events.map((event) => event.id));
     if (!document2.system) {
       diagnostics.push(error("validate.system.required", "Atlas documents must declare exactly one system."));
     }
@@ -3559,6 +3852,7 @@ var WorldOrbit = (() => {
       ["viewpoint", document2.system?.viewpoints.map((viewpoint) => viewpoint.id) ?? []],
       ["annotation", document2.system?.annotations.map((annotation) => annotation.id) ?? []],
       ["relation", document2.relations.map((relation) => relation.id)],
+      ["event", document2.events.map((event) => event.id)],
       ["object", document2.objects.map((object) => object.id)]
     ]) {
       for (const id of ids) {
@@ -3574,11 +3868,14 @@ var WorldOrbit = (() => {
       validateRelation(relation, objectMap, diagnostics);
     }
     for (const viewpoint of document2.system?.viewpoints ?? []) {
-      validateViewpointFilter(viewpoint.filter, groupIds, sourceSchemaVersion, diagnostics, viewpoint.id);
+      validateViewpoint(viewpoint.filter, viewpoint.events ?? [], groupIds, eventIds, sourceSchemaVersion, diagnostics, viewpoint.id);
     }
     for (const object of document2.objects) {
       validateObject(object, document2.system, objectMap, groupIds, diagnostics);
     }
+    for (const event of document2.events) {
+      validateEvent(event, objectMap, diagnostics);
+    }
     return diagnostics;
   }
   function validateRelation(relation, objectMap, diagnostics) {
@@ -3596,13 +3893,19 @@ var WorldOrbit = (() => {
       diagnostics.push(error("validate.relation.kind.required", `Relation "${relation.id}" is missing a "kind" value.`));
     }
   }
-  function validateViewpointFilter(filter, groupIds, sourceSchemaVersion, diagnostics, viewpointId) {
-    if (!filter || sourceSchemaVersion !== "2.1") {
-      return;
-    }
-    for (const groupId of filter.groupIds) {
-      if (!groupIds.has(groupId)) {
-        diagnostics.push(warn("validate.viewpoint.group.unknown", `Unknown group "${groupId}" in viewpoint "${viewpointId}".`));
+  function validateViewpoint(filter, eventRefs, groupIds, eventIds, sourceSchemaVersion, diagnostics, viewpointId) {
+    if (sourceSchemaVersion === "2.1") {
+      if (filter) {
+        for (const groupId of filter.groupIds) {
+          if (!groupIds.has(groupId)) {
+            diagnostics.push(warn("validate.viewpoint.group.unknown", `Unknown group "${groupId}" in viewpoint "${viewpointId}".`, void 0, `viewpoint.${viewpointId}.groups`));
+          }
+        }
+      }
+      for (const eventId of eventRefs) {
+        if (!eventIds.has(eventId)) {
+          diagnostics.push(warn("validate.viewpoint.event.unknown", `Unknown event "${eventId}" in viewpoint "${viewpointId}".`, void 0, `viewpoint.${viewpointId}.events`));
+        }
       }
     }
   }
@@ -3688,6 +3991,103 @@ var WorldOrbit = (() => {
       }
     }
   }
+  function validateEvent(event, objectMap, diagnostics) {
+    const fieldPrefix = `event.${event.id}`;
+    const referencedIds = /* @__PURE__ */ new Set();
+    if (!event.kind.trim()) {
+      diagnostics.push(error("validate.event.kind.required", `Event "${event.id}" is missing a "kind" value.`, void 0, `${fieldPrefix}.kind`));
+    }
+    if (!event.targetObjectId && event.participantObjectIds.length === 0) {
+      diagnostics.push(error("validate.event.references.required", `Event "${event.id}" must define a "target" or at least one participant.`, void 0, `${fieldPrefix}.participants`));
+    }
+    if (event.targetObjectId) {
+      referencedIds.add(event.targetObjectId);
+      if (!objectMap.has(event.targetObjectId)) {
+        diagnostics.push(error("validate.event.target.unknown", `Unknown event target "${event.targetObjectId}" on "${event.id}".`, void 0, `${fieldPrefix}.target`));
+      }
+    }
+    const seenParticipants = /* @__PURE__ */ new Set();
+    for (const participantId of event.participantObjectIds) {
+      referencedIds.add(participantId);
+      if (seenParticipants.has(participantId)) {
+        diagnostics.push(warn("validate.event.participants.duplicate", `Event "${event.id}" repeats participant "${participantId}".`, void 0, `${fieldPrefix}.participants`));
+        continue;
+      }
+      seenParticipants.add(participantId);
+      if (!objectMap.has(participantId)) {
+        diagnostics.push(error("validate.event.participants.unknown", `Unknown event participant "${participantId}" on "${event.id}".`, void 0, `${fieldPrefix}.participants`));
+      }
+    }
+    if (event.targetObjectId && event.participantObjectIds.length > 0 && !event.participantObjectIds.includes(event.targetObjectId)) {
+      diagnostics.push(warn("validate.event.target.notParticipant", `Event "${event.id}" defines a target outside its participants list.`, void 0, `${fieldPrefix}.target`));
+    }
+    if (event.positions.length === 0) {
+      diagnostics.push(warn("validate.event.positions.missing", `Event "${event.id}" has no positions block and cannot drive a scene snapshot.`, void 0, `${fieldPrefix}.positions`));
+    }
+    if (/(?:^|[-_])(solar-eclipse|lunar-eclipse|transit|occultation)(?:$|[-_])/.test(event.kind) && referencedIds.size < 3) {
+      diagnostics.push(warn("validate.event.kind.participants", `Event "${event.id}" looks like an eclipse or transit but references fewer than three bodies.`, void 0, `${fieldPrefix}.participants`));
+    }
+    const poseIds = /* @__PURE__ */ new Set();
+    for (const pose of event.positions) {
+      const poseFieldPrefix = `${fieldPrefix}.pose.${pose.objectId}`;
+      if (poseIds.has(pose.objectId)) {
+        diagnostics.push(error("validate.event.pose.duplicate", `Event "${event.id}" defines "${pose.objectId}" more than once in positions.`, void 0, poseFieldPrefix));
+        continue;
+      }
+      poseIds.add(pose.objectId);
+      const object = objectMap.get(pose.objectId);
+      if (!object) {
+        diagnostics.push(error("validate.event.pose.object.unknown", `Unknown event pose object "${pose.objectId}" on "${event.id}".`, void 0, poseFieldPrefix));
+        continue;
+      }
+      if (!referencedIds.has(pose.objectId)) {
+        diagnostics.push(warn("validate.event.pose.unreferenced", `Event pose "${pose.objectId}" on "${event.id}" is not listed in target/participants.`, void 0, poseFieldPrefix));
+      }
+      validateEventPose(pose, object, objectMap, diagnostics, poseFieldPrefix, event.id);
+    }
+  }
+  function validateEventPose(pose, object, objectMap, diagnostics, fieldPrefix, eventId) {
+    const placement = pose.placement;
+    if (!placement) {
+      diagnostics.push(error("validate.event.pose.placement.required", `Event "${eventId}" pose "${pose.objectId}" is missing a placement mode.`, void 0, fieldPrefix));
+      return;
+    }
+    if (placement.mode === "orbit") {
+      if (!objectMap.has(placement.target)) {
+        diagnostics.push(error("validate.event.pose.orbit.target.unknown", `Unknown event orbit target "${placement.target}" on "${eventId}:${pose.objectId}".`, void 0, `${fieldPrefix}.orbit`));
+      }
+      if (placement.distance && placement.semiMajor) {
+        diagnostics.push(error("validate.event.pose.orbit.distanceConflict", `Event "${eventId}" pose "${pose.objectId}" cannot declare both "distance" and "semiMajor".`, void 0, `${fieldPrefix}.distance`));
+      }
+      return;
+    }
+    if (placement.mode === "surface") {
+      const target = objectMap.get(placement.target);
+      if (!target) {
+        diagnostics.push(error("validate.event.pose.surface.target.unknown", `Unknown event surface target "${placement.target}" on "${eventId}:${pose.objectId}".`, void 0, `${fieldPrefix}.surface`));
+      } else if (!SURFACE_TARGET_TYPES2.has(target.type)) {
+        diagnostics.push(error("validate.event.pose.surface.target.invalid", `Event surface target "${placement.target}" on "${eventId}:${pose.objectId}" is not surface-capable.`, void 0, `${fieldPrefix}.surface`));
+      }
+      return;
+    }
+    if (placement.mode === "at") {
+      if (object.type !== "structure" && object.type !== "phenomenon") {
+        diagnostics.push(error("validate.event.pose.at.objectType", `Only structures and phenomena may use "at" placement in events; found "${object.type}" on "${eventId}:${pose.objectId}".`, void 0, `${fieldPrefix}.at`));
+      }
+      const reference = placement.reference;
+      if (reference.kind === "named" && !objectMap.has(reference.name)) {
+        diagnostics.push(error("validate.event.pose.at.target.unknown", `Unknown event at-reference target "${placement.target}" on "${eventId}:${pose.objectId}".`, void 0, `${fieldPrefix}.at`));
+      } else if (reference.kind === "anchor" && !objectMap.has(reference.objectId)) {
+        diagnostics.push(error("validate.event.pose.anchor.target.unknown", `Unknown event anchor target "${reference.objectId}" on "${eventId}:${pose.objectId}".`, void 0, `${fieldPrefix}.at`));
+      } else if (reference.kind === "lagrange") {
+        if (!objectMap.has(reference.primary)) {
+          diagnostics.push(error("validate.event.pose.lagrange.primary.unknown", `Unknown event Lagrange target "${reference.primary}" on "${eventId}:${pose.objectId}".`, void 0, `${fieldPrefix}.at`));
+        } else if (reference.secondary && !objectMap.has(reference.secondary)) {
+          diagnostics.push(error("validate.event.pose.lagrange.secondary.unknown", `Unknown event Lagrange target "${reference.secondary}" on "${eventId}:${pose.objectId}".`, void 0, `${fieldPrefix}.at`));
+        }
+      }
+    }
+  }
   function validateAtTarget(object, objectMap, diagnostics) {
     const reference = object.placement?.mode === "at" ? object.placement.reference : null;
     if (!reference) {
@@ -3888,6 +4288,21 @@ var WorldOrbit = (() => {
     });
   }
   var DRAFT_OBJECT_FIELD_KEYS = new Set(DRAFT_OBJECT_FIELD_SPECS.keys());
+  var EVENT_POSE_FIELD_KEYS = /* @__PURE__ */ new Set([
+    "orbit",
+    "distance",
+    "semiMajor",
+    "eccentricity",
+    "period",
+    "angle",
+    "inclination",
+    "phase",
+    "at",
+    "surface",
+    "free",
+    "inner",
+    "outer"
+  ]);
   function parseWorldOrbitAtlas(source) {
     return parseAtlasSource(source);
   }
@@ -3905,12 +4320,15 @@ var WorldOrbit = (() => {
     const objectNodes = [];
     const groups = [];
     const relations = [];
+    const events = [];
+    const eventPoseNodes = /* @__PURE__ */ new Map();
     let sawDefaults = false;
     let sawAtlas = false;
     const viewpointIds = /* @__PURE__ */ new Set();
     const annotationIds = /* @__PURE__ */ new Set();
     const groupIds = /* @__PURE__ */ new Set();
     const relationIds = /* @__PURE__ */ new Set();
+    const eventIds = /* @__PURE__ */ new Set();
     for (let index = 0; index < lines.length; index++) {
       const rawLine = lines[index];
       const lineNumber = index + 1;
@@ -3941,7 +4359,7 @@ var WorldOrbit = (() => {
         continue;
       }
       if (indent === 0) {
-        section = startTopLevelSection(tokens, lineNumber, sourceSchemaVersion, diagnostics, system, objectNodes, groups, relations, viewpointIds, annotationIds, groupIds, relationIds, { sawDefaults, sawAtlas });
+        section = startTopLevelSection(tokens, lineNumber, sourceSchemaVersion, diagnostics, system, objectNodes, groups, relations, events, eventPoseNodes, viewpointIds, annotationIds, groupIds, relationIds, eventIds, { sawDefaults, sawAtlas });
         if (section.kind === "system") {
           system = section.system;
         } else if (section.kind === "defaults") {
@@ -3960,6 +4378,7 @@ var WorldOrbit = (() => {
       throw new WorldOrbitError('Missing required atlas schema header "schema 2.0"');
     }
     const objects = objectNodes.map((node) => normalizeDraftObject(node, sourceSchemaVersion, diagnostics));
+    const normalizedEvents = events.map((event) => normalizeDraftEvent(event, eventPoseNodes.get(event.id) ?? []));
     const outputVersion = forcedOutputVersion ?? (sourceSchemaVersion === "2.0-draft" ? "2.0" : sourceSchemaVersion);
     const baseDocument = {
       format: "worldorbit",
@@ -3967,6 +4386,7 @@ var WorldOrbit = (() => {
       system,
       groups,
       relations,
+      events: normalizedEvents,
       objects,
       diagnostics
     };
@@ -4002,7 +4422,7 @@ var WorldOrbit = (() => {
     const version = tokens[1].value.toLowerCase();
     return version === "2.1" ? "2.1" : version === "2.0-draft" ? "2.0-draft" : "2.0";
   }
-  function startTopLevelSection(tokens, line, sourceSchemaVersion, diagnostics, system, objectNodes, groups, relations, viewpointIds, annotationIds, groupIds, relationIds, flags) {
+  function startTopLevelSection(tokens, line, sourceSchemaVersion, diagnostics, system, objectNodes, groups, relations, events, eventPoseNodes, viewpointIds, annotationIds, groupIds, relationIds, eventIds, flags) {
     const keyword = tokens[0]?.value.toLowerCase();
     switch (keyword) {
       case "system":
@@ -4039,7 +4459,7 @@ var WorldOrbit = (() => {
         if (!system) {
           throw new WorldOrbitError('Atlas section "viewpoint" requires a preceding system declaration', line, tokens[0].column);
         }
-        return startViewpointSection(tokens, line, system, viewpointIds);
+        return startViewpointSection(tokens, line, system, viewpointIds, sourceSchemaVersion, diagnostics);
       case "annotation":
         if (!system) {
           throw new WorldOrbitError('Atlas section "annotation" requires a preceding system declaration', line, tokens[0].column);
@@ -4051,6 +4471,9 @@ var WorldOrbit = (() => {
       case "relation":
         warnIfSchema21Feature(sourceSchemaVersion, diagnostics, "relation", { line, column: tokens[0].column });
         return startRelationSection(tokens, line, relations, relationIds);
+      case "event":
+        warnIfSchema21Feature(sourceSchemaVersion, diagnostics, "event", { line, column: tokens[0].column });
+        return startEventSection(tokens, line, events, eventPoseNodes, eventIds, sourceSchemaVersion, diagnostics);
       case "object":
         return startObjectSection(tokens, line, sourceSchemaVersion, diagnostics, objectNodes);
       default:
@@ -4087,7 +4510,7 @@ var WorldOrbit = (() => {
       seenFields: /* @__PURE__ */ new Set()
     };
   }
-  function startViewpointSection(tokens, line, system, viewpointIds) {
+  function startViewpointSection(tokens, line, system, viewpointIds, sourceSchemaVersion, diagnostics) {
     if (tokens.length !== 2) {
       throw new WorldOrbitError("Invalid viewpoint declaration", line, tokens[0]?.column ?? 1);
     }
@@ -4104,6 +4527,7 @@ var WorldOrbit = (() => {
       summary: "",
       focusObjectId: null,
       selectedObjectId: null,
+      events: [],
       projection: system.defaults.view,
       preset: system.defaults.preset,
       zoom: null,
@@ -4116,6 +4540,8 @@ var WorldOrbit = (() => {
     return {
       kind: "viewpoint",
       viewpoint,
+      sourceSchemaVersion,
+      diagnostics,
       seenFields: /* @__PURE__ */ new Set(),
       inFilter: false,
       filterIndent: null,
@@ -4206,6 +4632,49 @@ var WorldOrbit = (() => {
       seenFields: /* @__PURE__ */ new Set()
     };
   }
+  function startEventSection(tokens, line, events, eventPoseNodes, eventIds, sourceSchemaVersion, diagnostics) {
+    if (tokens.length !== 2) {
+      throw new WorldOrbitError("Invalid event declaration", line, tokens[0]?.column ?? 1);
+    }
+    const id = normalizeIdentifier2(tokens[1].value);
+    if (!id) {
+      throw new WorldOrbitError("Event id must not be empty", line, tokens[1].column);
+    }
+    if (eventIds.has(id)) {
+      throw new WorldOrbitError(`Duplicate event id "${id}"`, line, tokens[1].column);
+    }
+    const event = {
+      id,
+      kind: "",
+      label: humanizeIdentifier3(id),
+      summary: null,
+      targetObjectId: null,
+      participantObjectIds: [],
+      timing: null,
+      visibility: null,
+      tags: [],
+      color: null,
+      hidden: false,
+      positions: []
+    };
+    const rawPoses = [];
+    events.push(event);
+    eventPoseNodes.set(id, rawPoses);
+    eventIds.add(id);
+    return {
+      kind: "event",
+      event,
+      sourceSchemaVersion,
+      diagnostics,
+      seenFields: /* @__PURE__ */ new Set(),
+      rawPoses,
+      inPositions: false,
+      positionsIndent: null,
+      activePose: null,
+      poseIndent: null,
+      activePoseSeenFields: /* @__PURE__ */ new Set()
+    };
+  }
   function startObjectSection(tokens, line, sourceSchemaVersion, diagnostics, objectNodes) {
     if (tokens.length < 3) {
       throw new WorldOrbitError("Invalid atlas object declaration", line, tokens[0]?.column ?? 1);
@@ -4262,6 +4731,9 @@ var WorldOrbit = (() => {
       case "relation":
         applyRelationField(section, tokens, line);
         return;
+      case "event":
+        applyEventField(section, indent, tokens, line);
+        return;
       case "object":
         applyObjectField(section, indent, tokens, line);
         return;
@@ -4388,7 +4860,14 @@ var WorldOrbit = (() => {
         section.viewpoint.rotationDeg = parseFiniteNumber2(value, line, tokens[0].column, "rotation");
         return;
       case "layers":
-        section.viewpoint.layers = parseLayerTokens(tokens.slice(1), line);
+        section.viewpoint.layers = parseLayerTokens(tokens.slice(1), line, section.sourceSchemaVersion, section.diagnostics);
+        return;
+      case "events":
+        warnIfSchema21Feature(section.sourceSchemaVersion, section.diagnostics, "viewpoint.events", {
+          line,
+          column: tokens[0].column
+        });
+        section.viewpoint.events = parseTokenList(tokens.slice(1), line, "events");
         return;
       default:
         throw new WorldOrbitError(`Unknown viewpoint field "${tokens[0].value}"`, line, tokens[0].column);
@@ -4493,6 +4972,106 @@ var WorldOrbit = (() => {
         throw new WorldOrbitError(`Unknown relation field "${tokens[0].value}"`, line, tokens[0].column);
     }
   }
+  function applyEventField(section, indent, tokens, line) {
+    if (section.activePose && indent <= (section.poseIndent ?? 0)) {
+      section.activePose = null;
+      section.poseIndent = null;
+      section.activePoseSeenFields.clear();
+    }
+    if (!section.activePose && section.inPositions && indent <= (section.positionsIndent ?? 0)) {
+      section.inPositions = false;
+      section.positionsIndent = null;
+    }
+    if (section.activePose) {
+      section.activePose.fields.push(parseEventPoseField(tokens, line, section.activePoseSeenFields));
+      return;
+    }
+    if (section.inPositions) {
+      if (tokens.length !== 2 || tokens[0].value.toLowerCase() !== "pose") {
+        throw new WorldOrbitError(`Unknown event positions field "${tokens[0].value}"`, line, tokens[0]?.column ?? 1);
+      }
+      const objectId = tokens[1].value;
+      if (!objectId.trim()) {
+        throw new WorldOrbitError("Event pose object id must not be empty", line, tokens[1].column);
+      }
+      const rawPose = {
+        objectId,
+        fields: [],
+        location: { line, column: tokens[0].column }
+      };
+      section.rawPoses.push(rawPose);
+      section.activePose = rawPose;
+      section.poseIndent = indent;
+      section.activePoseSeenFields = /* @__PURE__ */ new Set();
+      return;
+    }
+    if (tokens.length === 1 && tokens[0].value.toLowerCase() === "positions") {
+      if (section.seenFields.has("positions")) {
+        throw new WorldOrbitError('Duplicate event field "positions"', line, tokens[0].column);
+      }
+      section.seenFields.add("positions");
+      section.inPositions = true;
+      section.positionsIndent = indent;
+      return;
+    }
+    const key = requireUniqueField(tokens, section.seenFields, line);
+    switch (key) {
+      case "kind":
+        section.event.kind = joinFieldValue(tokens, line);
+        return;
+      case "label":
+        section.event.label = joinFieldValue(tokens, line);
+        return;
+      case "summary":
+        section.event.summary = joinFieldValue(tokens, line);
+        return;
+      case "target":
+        section.event.targetObjectId = joinFieldValue(tokens, line);
+        return;
+      case "participants":
+        section.event.participantObjectIds = parseTokenList(tokens.slice(1), line, "participants");
+        return;
+      case "timing":
+        section.event.timing = joinFieldValue(tokens, line);
+        return;
+      case "visibility":
+        section.event.visibility = joinFieldValue(tokens, line);
+        return;
+      case "tags":
+        section.event.tags = parseTokenList(tokens.slice(1), line, "tags");
+        return;
+      case "color":
+        section.event.color = joinFieldValue(tokens, line);
+        return;
+      case "hidden":
+        section.event.hidden = parseAtlasBoolean(joinFieldValue(tokens, line), "hidden", {
+          line,
+          column: tokens[0].column
+        });
+        return;
+      default:
+        throw new WorldOrbitError(`Unknown event field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+  }
+  function parseEventPoseField(tokens, line, seenFields) {
+    if (tokens.length < 2) {
+      throw new WorldOrbitError("Invalid event pose field line", line, tokens[0]?.column ?? 1);
+    }
+    const key = tokens[0].value;
+    if (!EVENT_POSE_FIELD_KEYS.has(key)) {
+      throw new WorldOrbitError(`Unknown event pose field "${key}"`, line, tokens[0].column);
+    }
+    if (seenFields.has(key)) {
+      throw new WorldOrbitError(`Duplicate event pose field "${key}"`, line, tokens[0].column);
+    }
+    seenFields.add(key);
+    return {
+      type: "field",
+      key,
+      values: tokens.slice(1).map((token) => token.value),
+      location: { line, column: tokens[0].column }
+    };
+  }
   function applyObjectField(section, indent, tokens, line) {
     if (section.activeBlock && indent <= (section.blockIndent ?? 0)) {
       section.activeBlock = null;
@@ -4551,7 +5130,7 @@ var WorldOrbit = (() => {
   function parseObjectTypeTokens(tokens, line) {
     return parseTokenList(tokens, line, "objectTypes").filter((value) => value === "star" || value === "planet" || value === "moon" || value === "belt" || value === "asteroid" || value === "comet" || value === "ring" || value === "structure" || value === "phenomenon");
   }
-  function parseLayerTokens(tokens, line) {
+  function parseLayerTokens(tokens, line, sourceSchemaVersion, diagnostics) {
     const layers = {};
     for (const token of parseTokenList(tokens, line, "layers")) {
       const enabled = !token.startsWith("-") && !token.startsWith("!");
@@ -4561,7 +5140,13 @@ var WorldOrbit = (() => {
         layers["orbits-front"] = enabled;
         continue;
       }
-      if (raw === "background" || raw === "guides" || raw === "orbits-back" || raw === "orbits-front" || raw === "relations" || raw === "objects" || raw === "labels" || raw === "metadata") {
+      if (raw === "background" || raw === "guides" || raw === "orbits-back" || raw === "orbits-front" || raw === "relations" || raw === "events" || raw === "objects" || raw === "labels" || raw === "metadata") {
+        if (raw === "events" && sourceSchemaVersion && diagnostics) {
+          warnIfSchema21Feature(sourceSchemaVersion, diagnostics, "layers.events", {
+            line,
+            column: tokens[0]?.column ?? 1
+          });
+        }
         layers[raw] = enabled;
       }
     }
@@ -4700,7 +5285,7 @@ var WorldOrbit = (() => {
   }
   function normalizeDraftObject(node, sourceSchemaVersion, diagnostics) {
     const fieldMap = collectDraftFields(node.fields);
-    const placement = extractDraftPlacement(node.objectType, fieldMap);
+    const placement = extractPlacementFromFieldMap(fieldMap);
     const properties = normalizeDraftProperties(node.objectType, fieldMap);
     const groups = parseOptionalTokenList(fieldMap.get("groups")?.[0]);
     const epoch = parseOptionalJoinedValue(fieldMap.get("epoch")?.[0]);
@@ -4752,6 +5337,24 @@ var WorldOrbit = (() => {
     }
     return object;
   }
+  function normalizeDraftEvent(event, rawPoses) {
+    return {
+      ...event,
+      participantObjectIds: [...new Set(event.participantObjectIds)],
+      tags: [...new Set(event.tags)],
+      positions: rawPoses.map((pose) => normalizeDraftEventPose(pose))
+    };
+  }
+  function normalizeDraftEventPose(rawPose) {
+    const fieldMap = collectDraftFields(rawPose.fields);
+    const placement = extractPlacementFromFieldMap(fieldMap);
+    return {
+      objectId: rawPose.objectId,
+      placement,
+      inner: parseOptionalUnitField(fieldMap.get("inner")?.[0], "inner"),
+      outer: parseOptionalUnitField(fieldMap.get("outer")?.[0], "outer")
+    };
+  }
   function collectDraftFields(fields) {
     const grouped = /* @__PURE__ */ new Map();
     for (const field of fields) {
@@ -4768,7 +5371,7 @@ var WorldOrbit = (() => {
     }
     return grouped;
   }
-  function extractDraftPlacement(objectType, fieldMap) {
+  function extractPlacementFromFieldMap(fieldMap) {
     const orbitField = fieldMap.get("orbit")?.[0];
     const atField = fieldMap.get("at")?.[0];
     const surfaceField = fieldMap.get("surface")?.[0];
@@ -5061,6 +5664,7 @@ var WorldOrbit = (() => {
       },
       groups: [],
       relations: [],
+      events: [],
       objects: [],
       diagnostics: []
     };
@@ -5087,6 +5691,12 @@ var WorldOrbit = (() => {
     for (const relation of [...document2.relations].sort(compareIdLike2)) {
       paths.push({ kind: "relation", id: relation.id });
     }
+    for (const event of [...document2.events].sort(compareIdLike2)) {
+      paths.push({ kind: "event", id: event.id });
+      for (const pose of [...event.positions].sort(comparePoseObjectId2)) {
+        paths.push({ kind: "event-pose", id: event.id, key: pose.objectId });
+      }
+    }
     for (const object of [...document2.objects].sort(compareIdLike2)) {
       paths.push({ kind: "object", id: object.id });
     }
@@ -5102,6 +5712,10 @@ var WorldOrbit = (() => {
         return path.key ? document2.system?.atlasMetadata[path.key] ?? null : null;
       case "group":
         return path.id ? findGroup(document2, path.id) : null;
+      case "event":
+        return path.id ? findEvent(document2, path.id) : null;
+      case "event-pose":
+        return path.id && path.key ? findEventPose(document2, path.id, path.key) : null;
       case "object":
         return path.id ? findObject(document2, path.id) : null;
       case "viewpoint":
@@ -5141,6 +5755,18 @@ var WorldOrbit = (() => {
         }
         upsertById(next.groups, value);
         return next;
+      case "event":
+        if (!path.id) {
+          throw new Error('Event updates require an "id" value.');
+        }
+        upsertById(next.events, value);
+        return next;
+      case "event-pose":
+        if (!path.id || !path.key) {
+          throw new Error('Event pose updates require an event "id" and pose "key" value.');
+        }
+        upsertEventPose(next.events, path.id, value);
+        return next;
       case "object":
         if (!path.id) {
           throw new Error('Object updates require an "id" value.');
@@ -5189,6 +5815,19 @@ var WorldOrbit = (() => {
           next.groups = next.groups.filter((group) => group.id !== path.id);
         }
         return next;
+      case "event":
+        if (path.id) {
+          next.events = next.events.filter((event) => event.id !== path.id);
+        }
+        return next;
+      case "event-pose":
+        if (path.id && path.key) {
+          const event = findEvent(next, path.id);
+          if (event) {
+            event.positions = event.positions.filter((pose) => pose.objectId !== path.key);
+          }
+        }
+        return next;
       case "viewpoint":
         if (path.id) {
           system.viewpoints = system.viewpoints.filter((viewpoint) => viewpoint.id !== path.id);
@@ -5257,6 +5896,22 @@ var WorldOrbit = (() => {
         };
       }
     }
+    if (diagnostic.field?.startsWith("event.")) {
+      const parts = diagnostic.field.split(".");
+      if (parts[1] && findEvent(document2, parts[1])) {
+        if (parts[2] === "pose" && parts[3] && findEventPose(document2, parts[1], parts[3])) {
+          return {
+            kind: "event-pose",
+            id: parts[1],
+            key: parts[3]
+          };
+        }
+        return {
+          kind: "event",
+          id: parts[1]
+        };
+      }
+    }
     if (diagnostic.field && diagnostic.field in ensureSystem(document2).atlasMetadata) {
       return {
         kind: "metadata",
@@ -5288,6 +5943,12 @@ var WorldOrbit = (() => {
   function findRelation(document2, relationId) {
     return document2.relations.find((relation) => relation.id === relationId) ?? null;
   }
+  function findEvent(document2, eventId) {
+    return document2.events.find((event) => event.id === eventId) ?? null;
+  }
+  function findEventPose(document2, eventId, objectId) {
+    return findEvent(document2, eventId)?.positions.find((pose) => pose.objectId === objectId) ?? null;
+  }
   function findViewpoint(system, viewpointId) {
     return system?.viewpoints.find((viewpoint) => viewpoint.id === viewpointId) ?? null;
   }
@@ -5303,9 +5964,25 @@ var WorldOrbit = (() => {
     }
     items[index] = value;
   }
+  function upsertEventPose(events, eventId, value) {
+    const event = events.find((entry) => entry.id === eventId);
+    if (!event) {
+      throw new Error(`Unknown event "${eventId}" for pose update.`);
+    }
+    const index = event.positions.findIndex((entry) => entry.objectId === value.objectId);
+    if (index === -1) {
+      event.positions.push(value);
+      event.positions.sort(comparePoseObjectId2);
+      return;
+    }
+    event.positions[index] = value;
+  }
   function compareIdLike2(left, right) {
     return left.id.localeCompare(right.id);
   }
+  function comparePoseObjectId2(left, right) {
+    return left.objectId.localeCompare(right.objectId);
+  }
 
   // packages/core/dist/load.js
   var ATLAS_SCHEMA_PATTERN = /^schema\s+2(?:\.0|\.1)?$/i;
@@ -5540,6 +6217,7 @@ var WorldOrbit = (() => {
     background: true,
     guides: true,
     relations: true,
+    events: true,
     orbits: true,
     objects: true,
     labels: true,
@@ -5691,12 +6369,14 @@ var WorldOrbit = (() => {
     return {
       version: "2.0",
       viewpointId,
+      activeEventId: renderOptions.activeEventId ?? null,
       viewerState: { ...viewerState },
       renderOptions: {
         preset: renderOptions.preset,
         projection: renderOptions.projection,
         layers: renderOptions.layers ? { ...renderOptions.layers } : void 0,
-        scaleModel: renderOptions.scaleModel ? { ...renderOptions.scaleModel } : void 0
+        scaleModel: renderOptions.scaleModel ? { ...renderOptions.scaleModel } : void 0,
+        activeEventId: renderOptions.activeEventId ?? null
       },
       filter: normalizeViewerFilter(filter)
     };
@@ -5709,6 +6389,7 @@ var WorldOrbit = (() => {
     return {
       version: "2.0",
       viewpointId: raw.viewpointId ?? null,
+      activeEventId: raw.activeEventId ?? raw.renderOptions?.activeEventId ?? null,
       viewerState: {
         scale: raw.viewerState?.scale ?? 1,
         rotationDeg: raw.viewerState?.rotationDeg ?? 0,
@@ -5720,7 +6401,8 @@ var WorldOrbit = (() => {
         preset: raw.renderOptions?.preset,
         projection: raw.renderOptions?.projection,
         layers: raw.renderOptions?.layers ? { ...raw.renderOptions.layers } : void 0,
-        scaleModel: raw.renderOptions?.scaleModel ? { ...raw.renderOptions.scaleModel } : void 0
+        scaleModel: raw.renderOptions?.scaleModel ? { ...raw.renderOptions.scaleModel } : void 0,
+        activeEventId: raw.activeEventId ?? raw.renderOptions?.activeEventId ?? null
       },
       filter: normalizeViewerFilter(raw.filter ?? null)
     };
@@ -5736,7 +6418,8 @@ var WorldOrbit = (() => {
         renderOptions: {
           ...atlasState.renderOptions,
           layers: atlasState.renderOptions.layers ? { ...atlasState.renderOptions.layers } : void 0,
-          scaleModel: atlasState.renderOptions.scaleModel ? { ...atlasState.renderOptions.scaleModel } : void 0
+          scaleModel: atlasState.renderOptions.scaleModel ? { ...atlasState.renderOptions.scaleModel } : void 0,
+          activeEventId: atlasState.renderOptions.activeEventId ?? null
         },
         filter: atlasState.filter ? { ...atlasState.filter } : null
       }
@@ -5754,6 +6437,7 @@ var WorldOrbit = (() => {
       background: viewpoint.layers.background,
       guides: viewpoint.layers.guides,
       relations: viewpoint.layers.relations,
+      events: viewpoint.layers.events,
       orbits: viewpoint.layers["orbits-front"] === void 0 && viewpoint.layers["orbits-back"] === void 0 ? void 0 : viewpoint.layers["orbits-front"] !== false || viewpoint.layers["orbits-back"] !== false,
       objects: viewpoint.layers.objects,
       labels: viewpoint.layers.labels,
@@ -6040,6 +6724,7 @@ var WorldOrbit = (() => {
     const orbitMarkup = layers.orbits ? renderOrbitLayer(scene, visibleObjectIds, layers.structures) : { back: "", front: "" };
     const leaderMarkup = layers.guides ? scene.leaders.filter((leader) => !leader.hidden).filter((leader) => visibleObjectIds.has(leader.objectId)).filter((leader) => layers.structures || !isStructureLike(leader.object)).map((leader) => `<line class="wo-leader wo-leader-${leader.mode}" x1="${leader.x1}" y1="${leader.y1}" x2="${leader.x2}" y2="${leader.y2}" data-render-id="${escapeXml(leader.renderId)}" data-group-id="${escapeAttribute(leader.groupId ?? "")}" />`).join("") : "";
     const relationMarkup = layers.relations ? scene.relations.filter((relation) => !relation.hidden).filter((relation) => visibleObjectIds.has(relation.fromObjectId) && visibleObjectIds.has(relation.toObjectId)).map((relation) => `<line class="wo-relation" x1="${relation.x1}" y1="${relation.y1}" x2="${relation.x2}" y2="${relation.y2}" data-render-id="${escapeXml(relation.renderId)}" data-relation-id="${escapeAttribute(relation.relationId)}" />`).join("") : "";
+    const eventMarkup = layers.events ? scene.events.filter((event) => !event.hidden).map((event) => renderSceneEventOverlay(scene, event, visibleObjectIds, theme)).join("") : "";
     const objectMarkup = layers.objects ? visibleObjects.map((object) => renderSceneObject(object, options.selectedObjectId ?? null, theme)).join("") : "";
     const labelMarkup = layers.labels ? visibleLabels.map((label) => renderSceneLabel(scene, label, options.selectedObjectId ?? null)).join("") : "";
     const metadataMarkup = layers.metadata ? `<text class="wo-title" x="56" y="64">${escapeXml(scene.title)}</text>
@@ -6075,6 +6760,9 @@ var WorldOrbit = (() => {
     .wo-orbit-front { opacity: 0.9; }
     .wo-orbit-band { stroke: ${theme.orbitBand}; stroke-linecap: round; }
     .wo-relation { stroke: ${theme.relation}; stroke-width: 2; stroke-dasharray: 10 6; }
+    .wo-event-line { stroke: ${theme.accent}; stroke-width: 1.6; stroke-dasharray: 5 5; opacity: 0.72; }
+    .wo-event-node { fill: ${theme.accent}; stroke: ${theme.selected}; stroke-width: 1.4; opacity: 0.92; }
+    .wo-event-label { fill: ${theme.accent}; font-family: ${theme.fontFamily}; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; }
     .wo-leader { stroke: ${theme.leader}; stroke-width: 1.5; stroke-dasharray: 6 5; }
     .wo-label { fill: ${theme.ink}; font-family: ${theme.fontFamily}; font-weight: 600; letter-spacing: 0.02em; }
     .wo-label-secondary { fill: ${theme.muted}; font-family: ${theme.fontFamily}; font-weight: 500; }
@@ -6109,6 +6797,7 @@ var WorldOrbit = (() => {
         ${layers.orbits ? `<g data-layer-id="orbits-back">${orbitMarkup.back}</g>` : ""}
         ${layers.guides ? `<g data-layer-id="guides">${leaderMarkup}</g>` : ""}
         ${layers.relations ? `<g data-layer-id="relations">${relationMarkup}</g>` : ""}
+        ${layers.events ? `<g data-layer-id="events">${eventMarkup}</g>` : ""}
         ${layers.objects ? `<g data-layer-id="objects">${objectMarkup}</g>` : ""}
         ${layers.orbits ? `<g data-layer-id="orbits-front">${orbitMarkup.front}</g>` : ""}
         ${layers.labels ? `<g data-layer-id="labels">${labelMarkup}</g>` : ""}
@@ -6116,6 +6805,20 @@ var WorldOrbit = (() => {
     </g>
   </g>
 </svg>`;
+  }
+  function renderSceneEventOverlay(scene, event, visibleObjectIds, theme) {
+    const participants = event.objectIds.filter((objectId) => visibleObjectIds.has(objectId)).map((objectId) => scene.objects.find((object) => object.objectId === objectId && !object.hidden)).filter(Boolean);
+    if (participants.length === 0) {
+      return "";
+    }
+    const stroke = event.event.color || theme.accent;
+    const label = event.event.label || event.event.id;
+    const lineMarkup = participants.map((object) => `<line class="wo-event-line" x1="${event.x}" y1="${event.y}" x2="${object.x}" y2="${object.y}" stroke="${escapeAttribute(stroke)}" data-event-id="${escapeAttribute(event.eventId)}" data-object-id="${escapeAttribute(object.objectId)}" />`).join("");
+    return `<g class="wo-event" data-render-id="${escapeXml(event.renderId)}" data-event-id="${escapeAttribute(event.eventId)}">
+    ${lineMarkup}
+    <circle class="wo-event-node" cx="${event.x}" cy="${event.y}" r="5" fill="${escapeAttribute(stroke)}" />
+    <text class="wo-event-label" x="${event.x}" y="${event.y - 10}" text-anchor="middle" font-size="10">${escapeXml(label)}</text>
+  </g>`;
   }
   function renderDocumentToSvg(document2, options = {}) {
     return renderSceneToSvg(renderDocumentToScene(document2, options), options);
@@ -6715,6 +7418,13 @@ var WorldOrbit = (() => {
         value: `${details.object.resonance.targetObjectId} ${details.object.resonance.ratio}`
       });
     }
+    if (details.relatedEvents.length > 0) {
+      fields.set("events", {
+        key: "events",
+        label: "Events",
+        value: details.relatedEvents.map((event) => event.event.label || event.event.id).join(", ")
+      });
+    }
     if (placement?.mode === "at") {
       fields.set("placement", {
         key: "placement",
@@ -7129,6 +7839,12 @@ var WorldOrbit = (() => {
         emitAtlasStateChange();
         return true;
       },
+      getActiveEventId() {
+        return renderOptions.activeEventId ?? null;
+      },
+      setActiveEvent(id) {
+        api.setRenderOptions({ activeEventId: id });
+      },
       search(query, limit = 12) {
         return searchSceneObjects(scene, query, limit);
       },
@@ -7393,6 +8109,7 @@ var WorldOrbit = (() => {
         orbit: scene.orbitVisuals.find((orbit) => orbit.objectId === renderObject.objectId && !orbit.hidden) ?? null,
         relatedOrbits: scene.orbitVisuals.filter((orbit) => !orbit.hidden && (orbit.objectId === renderObject.objectId || renderObject.ancestorIds.includes(orbit.objectId) || renderObject.childIds.includes(orbit.objectId))),
         relations: scene.relations.filter((relation) => !relation.hidden && (relation.fromObjectId === renderObject.objectId || relation.toObjectId === renderObject.objectId)),
+        relatedEvents: scene.events.filter((event) => !event.hidden && (event.targetObjectId === renderObject.objectId || event.objectIds.includes(renderObject.objectId))),
         parent: getObjectById(renderObject.parentId),
         children: renderObject.childIds.map((childId) => getObjectById(childId)).filter(Boolean),
         ancestors: renderObject.ancestorIds.map((ancestorId) => getObjectById(ancestorId)).filter(Boolean),
@@ -7709,7 +8426,8 @@ var WorldOrbit = (() => {
       filter: renderOptions.filter ? { ...renderOptions.filter } : void 0,
       scaleModel: renderOptions.scaleModel ? { ...renderOptions.scaleModel } : void 0,
       layers: renderOptions.layers ? { ...renderOptions.layers } : void 0,
-      theme: renderOptions.theme && typeof renderOptions.theme === "object" ? { ...renderOptions.theme } : renderOptions.theme
+      theme: renderOptions.theme && typeof renderOptions.theme === "object" ? { ...renderOptions.theme } : renderOptions.theme,
+      activeEventId: renderOptions.activeEventId ?? null
     };
   }
   function mergeRenderOptions(current, next) {
@@ -7729,7 +8447,7 @@ var WorldOrbit = (() => {
     };
   }
   function hasSceneAffectingRenderOptions(options) {
-    return options.width !== void 0 || options.height !== void 0 || options.padding !== void 0 || options.preset !== void 0 || options.projection !== void 0 || options.scaleModel !== void 0;
+    return options.width !== void 0 || options.height !== void 0 || options.padding !== void 0 || options.preset !== void 0 || options.projection !== void 0 || options.scaleModel !== void 0 || options.activeEventId !== void 0;
   }
   function resolveSourceRenderOptions2(loaded, renderOptions) {
     const atlasDocument = loaded.atlasDocument ?? loaded.draftDocument;
@@ -8339,6 +9057,7 @@ var WorldOrbit = (() => {
           groupCount: activeViewer.getScene().groups.length,
           semanticGroupCount: activeViewer.getScene().semanticGroups.length,
           relationCount: activeViewer.getScene().relations.length,
+          eventCount: activeViewer.getScene().events.length,
           viewpointCount: activeViewer.getScene().viewpoints.length
         }
       };