worldorbit 2.5.16 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worldorbit",
-  "version": "2.5.16",
+  "version": "2.6.0",
   "description": "A text-based DSL and parser pipeline for orbital worldbuilding",
   "type": "module",
   "main": "./dist/unpkg/worldorbit.esm.js",

package/packages/core/dist/atlas-edit.js

@@ -1,5 +1,5 @@
 import { collectAtlasDiagnostics } from "./atlas-validate.js";
-export function createEmptyAtlasDocument(systemId = "WorldOrbit", version = "2.0") {
+export function createEmptyAtlasDocument(systemId = "WorldOrbit", version = "2.5") {
     return {
         format: "worldorbit",
         version,
@@ -25,6 +25,7 @@ export function createEmptyAtlasDocument(systemId = "WorldOrbit", version = "2.0
         },
         groups: [],
         relations: [],
+        events: [],
         objects: [],
         diagnostics: [],
     };
@@ -51,6 +52,12 @@ export function listAtlasDocumentPaths(document) {
     for (const relation of [...document.relations].sort(compareIdLike)) {
         paths.push({ kind: "relation", id: relation.id });
     }
+    for (const event of [...document.events].sort(compareIdLike)) {
+        paths.push({ kind: "event", id: event.id });
+        for (const pose of [...event.positions].sort(comparePoseObjectId)) {
+            paths.push({ kind: "event-pose", id: event.id, key: pose.objectId });
+        }
+    }
     for (const object of [...document.objects].sort(compareIdLike)) {
         paths.push({ kind: "object", id: object.id });
     }
@@ -66,6 +73,10 @@ export function getAtlasDocumentNode(document, path) {
             return path.key ? (document.system?.atlasMetadata[path.key] ?? null) : null;
         case "group":
             return path.id ? findGroup(document, path.id) : null;
+        case "event":
+            return path.id ? findEvent(document, path.id) : null;
+        case "event-pose":
+            return path.id && path.key ? findEventPose(document, path.id, path.key) : null;
         case "object":
             return path.id ? findObject(document, path.id) : null;
         case "viewpoint":
@@ -106,6 +117,18 @@ export function upsertAtlasDocumentNode(document, path, value) {
             }
             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.');
@@ -154,6 +177,19 @@ export function removeAtlasDocumentNode(document, path) {
                 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);
@@ -222,6 +258,22 @@ export function resolveAtlasDiagnosticPath(document, diagnostic) {
             };
         }
     }
+    if (diagnostic.field?.startsWith("event.")) {
+        const parts = diagnostic.field.split(".");
+        if (parts[1] && findEvent(document, parts[1])) {
+            if (parts[2] === "pose" && parts[3] && findEventPose(document, 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(document).atlasMetadata) {
         return {
             kind: "metadata",
@@ -253,6 +305,12 @@ function findGroup(document, groupId) {
 function findRelation(document, relationId) {
     return document.relations.find((relation) => relation.id === relationId) ?? null;
 }
+function findEvent(document, eventId) {
+    return document.events.find((event) => event.id === eventId) ?? null;
+}
+function findEventPose(document, eventId, objectId) {
+    return findEvent(document, eventId)?.positions.find((pose) => pose.objectId === objectId) ?? null;
+}
 function findViewpoint(system, viewpointId) {
     return system?.viewpoints.find((viewpoint) => viewpoint.id === viewpointId) ?? null;
 }
@@ -268,6 +326,22 @@ function upsertById(items, value) {
     }
     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(comparePoseObjectId);
+        return;
+    }
+    event.positions[index] = value;
+}
 function compareIdLike(left, right) {
     return left.id.localeCompare(right.id);
 }
+function comparePoseObjectId(left, right) {
+    return left.objectId.localeCompare(right.objectId);
+}

package/packages/core/dist/atlas-validate.js

@@ -11,6 +11,7 @@ export function collectAtlasDiagnostics(document, sourceSchemaVersion) {
     const diagnostics = [];
     const objectMap = new Map(document.objects.map((object) => [object.id, object]));
     const groupIds = new Set(document.groups.map((group) => group.id));
+    const eventIds = new Set(document.events.map((event) => event.id));
     if (!document.system) {
         diagnostics.push(error("validate.system.required", "Atlas documents must declare exactly one system."));
     }
@@ -20,6 +21,7 @@ export function collectAtlasDiagnostics(document, sourceSchemaVersion) {
         ["viewpoint", document.system?.viewpoints.map((viewpoint) => viewpoint.id) ?? []],
         ["annotation", document.system?.annotations.map((annotation) => annotation.id) ?? []],
         ["relation", document.relations.map((relation) => relation.id)],
+        ["event", document.events.map((event) => event.id)],
         ["object", document.objects.map((object) => object.id)],
     ]) {
         for (const id of ids) {
@@ -36,11 +38,14 @@ export function collectAtlasDiagnostics(document, sourceSchemaVersion) {
         validateRelation(relation, objectMap, diagnostics);
     }
     for (const viewpoint of document.system?.viewpoints ?? []) {
-        validateViewpointFilter(viewpoint.filter, groupIds, sourceSchemaVersion, diagnostics, viewpoint.id);
+        validateViewpoint(viewpoint, groupIds, eventIds, sourceSchemaVersion, diagnostics, objectMap);
     }
     for (const object of document.objects) {
         validateObject(object, document.system, objectMap, groupIds, diagnostics);
     }
+    for (const event of document.events) {
+        validateEvent(event, document.system, objectMap, diagnostics);
+    }
     return diagnostics;
 }
 function validateRelation(relation, objectMap, diagnostics) {
@@ -60,15 +65,24 @@ function validateRelation(relation, objectMap, diagnostics) {
         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(viewpoint, groupIds, eventIds, sourceSchemaVersion, diagnostics, objectMap) {
+    const filter = viewpoint.filter;
+    if (sourceSchemaVersion === "2.1" || sourceSchemaVersion === "2.5") {
+        if (filter) {
+            for (const groupId of filter.groupIds) {
+                if (!groupIds.has(groupId)) {
+                    diagnostics.push(warn("validate.viewpoint.group.unknown", `Unknown group "${groupId}" in viewpoint "${viewpoint.id}".`, undefined, `viewpoint.${viewpoint.id}.groups`));
+                }
+            }
+        }
+        for (const eventId of viewpoint.events ?? []) {
+            if (!eventIds.has(eventId)) {
+                diagnostics.push(warn("validate.viewpoint.event.unknown", `Unknown event "${eventId}" in viewpoint "${viewpoint.id}".`, undefined, `viewpoint.${viewpoint.id}.events`));
+            }
         }
     }
+    validateProjection(viewpoint.projection, diagnostics, `viewpoint.${viewpoint.id}.projection`, viewpoint.id);
+    validateCamera(viewpoint.camera, viewpoint.projection, viewpoint.rotationDeg, diagnostics, viewpoint.id, viewpoint.focusObjectId, viewpoint.selectedObjectId, filter, objectMap);
 }
 function validateObject(object, system, objectMap, groupIds, diagnostics) {
     const placement = object.placement;
@@ -81,6 +95,12 @@ function validateObject(object, system, objectMap, groupIds, diagnostics) {
             }
         }
     }
+    if (typeof object.epoch === "string" && !object.epoch.trim()) {
+        diagnostics.push(warn("validate.epoch.empty", `Object "${object.id}" defines an empty epoch string.`, object.id, "epoch"));
+    }
+    if (typeof object.referencePlane === "string" && !object.referencePlane.trim()) {
+        diagnostics.push(warn("validate.referencePlane.empty", `Object "${object.id}" defines an empty reference plane string.`, object.id, "referencePlane"));
+    }
     if (orbitPlacement) {
         if (!objectMap.has(orbitPlacement.target)) {
             diagnostics.push(error("validate.orbit.target.unknown", `Unknown placement target "${orbitPlacement.target}" on "${object.id}".`, object.id, "orbit"));
@@ -156,6 +176,128 @@ function validateObject(object, system, objectMap, groupIds, diagnostics) {
         }
     }
 }
+function validateEvent(event, system, objectMap, diagnostics) {
+    const fieldPrefix = `event.${event.id}`;
+    const referencedIds = new Set();
+    if (!event.kind.trim()) {
+        diagnostics.push(error("validate.event.kind.required", `Event "${event.id}" is missing a "kind" value.`, undefined, `${fieldPrefix}.kind`));
+    }
+    if (typeof event.epoch === "string" && !event.epoch.trim()) {
+        diagnostics.push(warn("validate.event.epoch.empty", `Event "${event.id}" defines an empty epoch string.`, undefined, `${fieldPrefix}.epoch`));
+    }
+    if (typeof event.referencePlane === "string" && !event.referencePlane.trim()) {
+        diagnostics.push(warn("validate.event.referencePlane.empty", `Event "${event.id}" defines an empty reference plane string.`, undefined, `${fieldPrefix}.referencePlane`));
+    }
+    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.`, undefined, `${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}".`, undefined, `${fieldPrefix}.target`));
+        }
+    }
+    const seenParticipants = 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}".`, undefined, `${fieldPrefix}.participants`));
+            continue;
+        }
+        seenParticipants.add(participantId);
+        if (!objectMap.has(participantId)) {
+            diagnostics.push(error("validate.event.participants.unknown", `Unknown event participant "${participantId}" on "${event.id}".`, undefined, `${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.`, undefined, `${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.`, undefined, `${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.`, undefined, `${fieldPrefix}.participants`));
+    }
+    const poseIds = 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.`, undefined, 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}".`, undefined, 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.`, undefined, poseFieldPrefix));
+        }
+        validateEventPose(pose, object, event, system, objectMap, diagnostics, poseFieldPrefix, event.id);
+    }
+    const missingPoseIds = [...referencedIds].filter((objectId) => !poseIds.has(objectId));
+    if (event.positions.length > 0 && missingPoseIds.length > 0) {
+        diagnostics.push(warn("validate.event.positions.partial", `Event "${event.id}" leaves ${missingPoseIds.length} referenced object(s) on their base placement.`, undefined, `${fieldPrefix}.positions`));
+    }
+}
+function validateEventPose(pose, object, event, system, 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.`, undefined, 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}".`, undefined, `${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".`, undefined, `${fieldPrefix}.distance`));
+        }
+        if (placement.phase && !resolveEffectiveEpoch(system, object, event, pose)) {
+            diagnostics.push(warn("validate.event.pose.phase.epochMissing", `Event "${eventId}" pose "${pose.objectId}" sets "phase" without an effective epoch.`, undefined, `${fieldPrefix}.phase`));
+        }
+        if (placement.inclination && !resolveEffectiveReferencePlane(system, object, event, pose)) {
+            diagnostics.push(warn("validate.event.pose.inclination.referencePlaneMissing", `Event "${eventId}" pose "${pose.objectId}" sets "inclination" without an effective reference plane.`, undefined, `${fieldPrefix}.inclination`));
+        }
+        if (placement.period && !massInSolar(objectMap.get(placement.target)?.properties.mass)) {
+            diagnostics.push(warn("validate.event.pose.period.massMissing", `Event "${eventId}" pose "${pose.objectId}" sets "period" but its central mass cannot be derived.`, undefined, `${fieldPrefix}.period`));
+        }
+        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}".`, undefined, `${fieldPrefix}.surface`));
+        }
+        else if (!SURFACE_TARGET_TYPES.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.`, undefined, `${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}".`, undefined, `${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}".`, undefined, `${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}".`, undefined, `${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}".`, undefined, `${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}".`, undefined, `${fieldPrefix}.at`));
+            }
+        }
+    }
+}
 function validateAtTarget(object, objectMap, diagnostics) {
     const reference = object.placement?.mode === "at" ? object.placement.reference : null;
     if (!reference) {
@@ -261,6 +403,67 @@ function durationInDays(value) {
             return null;
     }
 }
+function validateProjection(projection, diagnostics, field, viewpointId) {
+    if (projection !== "topdown" &&
+        projection !== "isometric" &&
+        projection !== "orthographic" &&
+        projection !== "perspective") {
+        diagnostics.push(error("validate.viewpoint.projection.invalid", `Unknown projection "${String(projection)}" in viewpoint "${viewpointId}".`, undefined, field));
+    }
+}
+function validateCamera(camera, projection, rotationDeg, diagnostics, viewpointId, focusObjectId, selectedObjectId, filter, objectMap) {
+    if (!camera) {
+        return;
+    }
+    const prefix = `viewpoint.${viewpointId}.camera`;
+    for (const [key, value] of [
+        ["azimuth", camera.azimuth],
+        ["elevation", camera.elevation],
+        ["roll", camera.roll],
+        ["distance", camera.distance],
+    ]) {
+        if (value !== null && (!Number.isFinite(value) || (key === "distance" && value <= 0))) {
+            diagnostics.push(error("validate.viewpoint.camera.invalid", `Invalid camera ${key} "${String(value)}" in viewpoint "${viewpointId}".`, undefined, `${prefix}.${key}`));
+        }
+    }
+    if (camera.distance !== null && projection !== "perspective") {
+        diagnostics.push(warn("validate.viewpoint.camera.distance.partialEffect", `Camera "distance" only has a semantic effect in perspective viewpoints; "${viewpointId}" uses "${projection}".`, undefined, `${prefix}.distance`));
+    }
+    if (projection === "topdown" &&
+        (camera.elevation !== null || camera.roll !== null)) {
+        diagnostics.push(warn("validate.viewpoint.camera.topdownPartial", `Camera elevation/roll on topdown viewpoint "${viewpointId}" are currently stored for future 3D use and only partially affect 2D rendering.`, undefined, prefix));
+    }
+    if (projection === "isometric" &&
+        camera.elevation !== null) {
+        diagnostics.push(info("validate.viewpoint.camera.isometricStored", `Camera elevation on isometric viewpoint "${viewpointId}" is preserved semantically for future 3D rendering.`, undefined, `${prefix}.elevation`));
+    }
+    if (camera.azimuth !== null && camera.azimuth !== 0 && rotationDeg !== 0) {
+        diagnostics.push(warn("validate.viewpoint.rotation.cameraOverlap", `Viewpoint "${viewpointId}" uses camera.azimuth; keep "rotation" only for 2D screen rotation to avoid ambiguity.`, undefined, `${prefix}.azimuth`));
+    }
+    const hasAnchor = (focusObjectId !== null && objectMap.has(focusObjectId)) ||
+        (selectedObjectId !== null && objectMap.has(selectedObjectId)) ||
+        !!filter;
+    if (!hasAnchor) {
+        diagnostics.push(info("validate.viewpoint.camera.anchorMissing", `Viewpoint "${viewpointId}" stores camera settings without a focus object, selection, or filter anchor.`, undefined, prefix));
+    }
+}
+function resolveEffectiveEpoch(system, object, event, pose) {
+    return normalizeOptionalContextString(pose?.epoch) ??
+        normalizeOptionalContextString(event?.epoch) ??
+        normalizeOptionalContextString(object.epoch) ??
+        normalizeOptionalContextString(system?.epoch) ??
+        null;
+}
+function resolveEffectiveReferencePlane(system, object, event, pose) {
+    return normalizeOptionalContextString(pose?.referencePlane) ??
+        normalizeOptionalContextString(event?.referencePlane) ??
+        normalizeOptionalContextString(object.referencePlane) ??
+        normalizeOptionalContextString(system?.referencePlane) ??
+        null;
+}
+function normalizeOptionalContextString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
 function toleranceForField(object, field) {
     const tolerance = object.tolerances?.find((entry) => entry.field === field)?.value;
     if (typeof tolerance === "number") {