worldorbit 2.5.17 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worldorbit",
-  "version": "2.5.17",
+  "version": "3.0.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,

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

@@ -38,13 +38,13 @@ export function collectAtlasDiagnostics(document, sourceSchemaVersion) {
         validateRelation(relation, objectMap, diagnostics);
     }
     for (const viewpoint of document.system?.viewpoints ?? []) {
-        validateViewpoint(viewpoint.filter, viewpoint.events ?? [], groupIds, eventIds, 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, objectMap, diagnostics);
+        validateEvent(event, document.system, objectMap, diagnostics);
     }
     return diagnostics;
 }
@@ -65,21 +65,24 @@ function validateRelation(relation, objectMap, diagnostics) {
         diagnostics.push(error("validate.relation.kind.required", `Relation "${relation.id}" is missing a "kind" value.`));
     }
 }
-function validateViewpoint(filter, eventRefs, groupIds, eventIds, sourceSchemaVersion, diagnostics, viewpointId) {
-    if (sourceSchemaVersion === "2.1") {
+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 "${viewpointId}".`, undefined, `viewpoint.${viewpointId}.groups`));
+                    diagnostics.push(warn("validate.viewpoint.group.unknown", `Unknown group "${groupId}" in viewpoint "${viewpoint.id}".`, undefined, `viewpoint.${viewpoint.id}.groups`));
                 }
             }
         }
-        for (const eventId of eventRefs) {
+        for (const eventId of viewpoint.events ?? []) {
             if (!eventIds.has(eventId)) {
-                diagnostics.push(warn("validate.viewpoint.event.unknown", `Unknown event "${eventId}" in viewpoint "${viewpointId}".`, undefined, `viewpoint.${viewpointId}.events`));
+                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;
@@ -92,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"));
@@ -167,12 +176,18 @@ function validateObject(object, system, objectMap, groupIds, diagnostics) {
         }
     }
 }
-function validateEvent(event, objectMap, 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`));
     }
@@ -221,10 +236,14 @@ function validateEvent(event, objectMap, diagnostics) {
         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, objectMap, diagnostics, poseFieldPrefix, event.id);
+        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, objectMap, diagnostics, fieldPrefix, eventId) {
+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));
@@ -237,6 +256,15 @@ function validateEventPose(pose, object, objectMap, diagnostics, fieldPrefix, ev
         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") {
@@ -375,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") {

package/packages/core/dist/draft-parse.js

@@ -88,6 +88,8 @@ const EVENT_POSE_FIELD_KEYS = new Set([
     "free",
     "inner",
     "outer",
+    "epoch",
+    "referencePlane",
 ]);
 export function parseWorldOrbitAtlas(source) {
     return parseAtlasSource(source);
@@ -132,7 +134,7 @@ function parseAtlasSource(source, forcedOutputVersion) {
         if (!sawSchemaHeader) {
             sourceSchemaVersion = assertDraftSchemaHeader(tokens, lineNumber);
             sawSchemaHeader = true;
-            if (prepared.comments.length > 0 && sourceSchemaVersion !== "2.1") {
+            if (prepared.comments.length > 0 && isSchemaOlderThan(sourceSchemaVersion, "2.1")) {
                 diagnostics.push({
                     code: "parse.schema21.commentCompatibility",
                     severity: "warning",
@@ -207,15 +209,17 @@ function parseAtlasSource(source, forcedOutputVersion) {
 function assertDraftSchemaHeader(tokens, line) {
     if (tokens.length !== 2 ||
         tokens[0].value.toLowerCase() !== "schema" ||
-        !["2.0-draft", "2.0", "2.1"].includes(tokens[1].value.toLowerCase())) {
-        throw new WorldOrbitError('Expected atlas header "schema 2.0", "schema 2.1", or legacy "schema 2.0-draft"', line, tokens[0]?.column ?? 1);
+        !["2.0-draft", "2.0", "2.1", "2.5"].includes(tokens[1].value.toLowerCase())) {
+        throw new WorldOrbitError('Expected atlas header "schema 2.0", "schema 2.1", "schema 2.5", or legacy "schema 2.0-draft"', line, tokens[0]?.column ?? 1);
     }
     const version = tokens[1].value.toLowerCase();
-    return version === "2.1"
-        ? "2.1"
-        : version === "2.0-draft"
-            ? "2.0-draft"
-            : "2.0";
+    return version === "2.5"
+        ? "2.5"
+        : version === "2.1"
+            ? "2.1"
+            : version === "2.0-draft"
+                ? "2.0-draft"
+                : "2.0";
 }
 function startTopLevelSection(tokens, line, sourceSchemaVersion, diagnostics, system, objectNodes, groups, relations, events, eventPoseNodes, viewpointIds, annotationIds, groupIds, relationIds, eventIds, flags) {
     const keyword = tokens[0]?.value.toLowerCase();
@@ -235,6 +239,8 @@ function startTopLevelSection(tokens, line, sourceSchemaVersion, diagnostics, sy
             return {
                 kind: "defaults",
                 system,
+                sourceSchemaVersion,
+                diagnostics,
                 seenFields: new Set(),
             };
         case "atlas":
@@ -327,6 +333,7 @@ function startViewpointSection(tokens, line, system, viewpointIds, sourceSchemaV
         preset: system.defaults.preset,
         zoom: null,
         rotationDeg: 0,
+        camera: null,
         layers: {},
         filter: null,
     };
@@ -341,6 +348,9 @@ function startViewpointSection(tokens, line, system, viewpointIds, sourceSchemaV
         inFilter: false,
         filterIndent: null,
         seenFilterFields: new Set(),
+        inCamera: false,
+        cameraIndent: null,
+        seenCameraFields: new Set(),
     };
 }
 function startAnnotationSection(tokens, line, system, annotationIds) {
@@ -447,6 +457,8 @@ function startEventSection(tokens, line, events, eventPoseNodes, eventIds, sourc
         participantObjectIds: [],
         timing: null,
         visibility: null,
+        epoch: null,
+        referencePlane: null,
         tags: [],
         color: null,
         hidden: false,
@@ -571,6 +583,12 @@ function applyDefaultsField(section, tokens, line) {
     const value = joinFieldValue(tokens, line);
     switch (key) {
         case "view":
+            if (isSchema25Projection(value)) {
+                warnIfSchema25Feature(section.sourceSchemaVersion, section.diagnostics, "defaults.view", {
+                    line,
+                    column: tokens[0].column,
+                });
+            }
             section.system.defaults.view = parseProjectionValue(value, line, tokens[0].column);
             return;
         case "scale":
@@ -610,14 +628,36 @@ function applyAtlasField(section, indent, tokens, line) {
     throw new WorldOrbitError(`Unknown atlas field "${tokens[0].value}"`, line, tokens[0].column);
 }
 function applyViewpointField(section, indent, tokens, line) {
+    if (section.inCamera && indent <= (section.cameraIndent ?? 0)) {
+        section.inCamera = false;
+        section.cameraIndent = null;
+    }
     if (section.inFilter && indent <= (section.filterIndent ?? 0)) {
         section.inFilter = false;
         section.filterIndent = null;
     }
+    if (section.inCamera) {
+        applyViewpointCameraField(section, tokens, line);
+        return;
+    }
     if (section.inFilter) {
         applyViewpointFilterField(section, tokens, line);
         return;
     }
+    if (tokens.length === 1 && tokens[0].value.toLowerCase() === "camera") {
+        warnIfSchema25Feature(section.sourceSchemaVersion, section.diagnostics, "viewpoint.camera", {
+            line,
+            column: tokens[0].column,
+        });
+        if (section.seenFields.has("camera")) {
+            throw new WorldOrbitError('Duplicate viewpoint field "camera"', line, tokens[0].column);
+        }
+        section.seenFields.add("camera");
+        section.inCamera = true;
+        section.cameraIndent = indent;
+        section.viewpoint.camera = section.viewpoint.camera ?? createEmptyViewCamera();
+        return;
+    }
     if (tokens.length === 1 && tokens[0].value.toLowerCase() === "filter") {
         if (section.seenFields.has("filter")) {
             throw new WorldOrbitError('Duplicate viewpoint field "filter"', line, tokens[0].column);
@@ -643,6 +683,12 @@ function applyViewpointField(section, indent, tokens, line) {
             section.viewpoint.selectedObjectId = value;
             return;
         case "projection":
+            if (isSchema25Projection(value)) {
+                warnIfSchema25Feature(section.sourceSchemaVersion, section.diagnostics, "projection", {
+                    line,
+                    column: tokens[0].column,
+                });
+            }
             section.viewpoint.projection = parseProjectionValue(value, line, tokens[0].column);
             return;
         case "preset":
@@ -654,6 +700,13 @@ function applyViewpointField(section, indent, tokens, line) {
         case "rotation":
             section.viewpoint.rotationDeg = parseFiniteNumber(value, line, tokens[0].column, "rotation");
             return;
+        case "camera":
+            warnIfSchema25Feature(section.sourceSchemaVersion, section.diagnostics, "viewpoint.camera", {
+                line,
+                column: tokens[0].column,
+            });
+            section.viewpoint.camera = parseInlineViewCamera(tokens.slice(1), line, section.viewpoint.camera);
+            return;
         case "layers":
             section.viewpoint.layers = parseLayerTokens(tokens.slice(1), line, section.sourceSchemaVersion, section.diagnostics);
             return;
@@ -668,6 +721,28 @@ function applyViewpointField(section, indent, tokens, line) {
             throw new WorldOrbitError(`Unknown viewpoint field "${tokens[0].value}"`, line, tokens[0].column);
     }
 }
+function applyViewpointCameraField(section, tokens, line) {
+    const key = requireUniqueField(tokens, section.seenCameraFields, line);
+    const value = joinFieldValue(tokens, line);
+    const camera = section.viewpoint.camera ?? createEmptyViewCamera();
+    switch (key) {
+        case "azimuth":
+            camera.azimuth = parseFiniteNumber(value, line, tokens[0].column, "camera.azimuth");
+            break;
+        case "elevation":
+            camera.elevation = parseFiniteNumber(value, line, tokens[0].column, "camera.elevation");
+            break;
+        case "roll":
+            camera.roll = parseFiniteNumber(value, line, tokens[0].column, "camera.roll");
+            break;
+        case "distance":
+            camera.distance = parsePositiveNumber(value, line, tokens[0].column, "camera.distance");
+            break;
+        default:
+            throw new WorldOrbitError(`Unknown viewpoint camera field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+    section.viewpoint.camera = camera;
+}
 function applyViewpointFilterField(section, tokens, line) {
     const key = requireUniqueField(tokens, section.seenFilterFields, line);
     const filter = section.viewpoint.filter ?? createEmptyViewpointFilter();
@@ -778,6 +853,13 @@ function applyEventField(section, indent, tokens, line) {
         section.positionsIndent = null;
     }
     if (section.activePose) {
+        if (tokens[0]?.value === "epoch" ||
+            tokens[0]?.value === "referencePlane") {
+            warnIfSchema25Feature(section.sourceSchemaVersion, section.diagnostics, `pose.${tokens[0].value}`, {
+                line,
+                column: tokens[0]?.column ?? 1,
+            });
+        }
         section.activePose.fields.push(parseEventPoseField(tokens, line, section.activePoseSeenFields));
         return;
     }
@@ -832,6 +914,20 @@ function applyEventField(section, indent, tokens, line) {
         case "visibility":
             section.event.visibility = joinFieldValue(tokens, line);
             return;
+        case "epoch":
+            warnIfSchema25Feature(section.sourceSchemaVersion, section.diagnostics, "event.epoch", {
+                line,
+                column: tokens[0].column,
+            });
+            section.event.epoch = joinFieldValue(tokens, line);
+            return;
+        case "referenceplane":
+            warnIfSchema25Feature(section.sourceSchemaVersion, section.diagnostics, "event.referencePlane", {
+                line,
+                column: tokens[0].column,
+            });
+            section.event.referencePlane = joinFieldValue(tokens, line);
+            return;
         case "tags":
             section.event.tags = parseTokenList(tokens.slice(1), line, "tags");
             return;
@@ -981,11 +1077,18 @@ function parseTokenList(tokens, line, fieldName) {
 }
 function parseProjectionValue(value, line, column) {
     const normalized = value.toLowerCase();
-    if (normalized !== "topdown" && normalized !== "isometric") {
+    if (normalized !== "topdown" &&
+        normalized !== "isometric" &&
+        normalized !== "orthographic" &&
+        normalized !== "perspective") {
         throw new WorldOrbitError(`Unknown projection "${value}"`, line, column);
     }
     return normalized;
 }
+function isSchema25Projection(value) {
+    const normalized = value.toLowerCase();
+    return normalized === "orthographic" || normalized === "perspective";
+}
 function parsePresetValue(value, line, column) {
     const normalized = value.toLowerCase();
     if (normalized === "diagram" ||
@@ -1018,6 +1121,48 @@ function createEmptyViewpointFilter() {
         groupIds: [],
     };
 }
+function createEmptyViewCamera() {
+    return {
+        azimuth: null,
+        elevation: null,
+        roll: null,
+        distance: null,
+    };
+}
+function parseInlineViewCamera(tokens, line, current) {
+    if (tokens.length === 0 || tokens.length % 2 !== 0) {
+        throw new WorldOrbitError('Field "camera" expects "<field> <value>" pairs', line, tokens[0]?.column ?? 1);
+    }
+    const camera = current ? { ...current } : createEmptyViewCamera();
+    const seen = new Set();
+    for (let index = 0; index < tokens.length; index += 2) {
+        const fieldToken = tokens[index];
+        const valueToken = tokens[index + 1];
+        const key = fieldToken.value.toLowerCase();
+        if (seen.has(key)) {
+            throw new WorldOrbitError(`Duplicate viewpoint camera field "${fieldToken.value}"`, line, fieldToken.column);
+        }
+        seen.add(key);
+        const value = valueToken.value;
+        switch (key) {
+            case "azimuth":
+                camera.azimuth = parseFiniteNumber(value, line, fieldToken.column, "camera.azimuth");
+                break;
+            case "elevation":
+                camera.elevation = parseFiniteNumber(value, line, fieldToken.column, "camera.elevation");
+                break;
+            case "roll":
+                camera.roll = parseFiniteNumber(value, line, fieldToken.column, "camera.roll");
+                break;
+            case "distance":
+                camera.distance = parsePositiveNumber(value, line, fieldToken.column, "camera.distance");
+                break;
+            default:
+                throw new WorldOrbitError(`Unknown viewpoint camera field "${fieldToken.value}"`, line, fieldToken.column);
+        }
+    }
+    return camera;
+}
 function parseInlineObjectFields(tokens, line, objectType, sourceSchemaVersion, diagnostics) {
     const fields = [];
     let index = 0;
@@ -1158,7 +1303,7 @@ function normalizeDraftObject(node, sourceSchemaVersion, diagnostics) {
         object.tolerances = tolerances;
     if (typedBlocks && Object.keys(typedBlocks).length > 0)
         object.typedBlocks = typedBlocks;
-    if (sourceSchemaVersion !== "2.1") {
+    if (isSchemaOlderThan(sourceSchemaVersion, "2.1")) {
         if (object.groups ||
             object.epoch ||
             object.referencePlane ||
@@ -1184,23 +1329,25 @@ function normalizeDraftEvent(event, rawPoses) {
     };
 }
 function normalizeDraftEventPose(rawPose) {
-    const fieldMap = collectDraftFields(rawPose.fields);
+    const fieldMap = collectDraftFields(rawPose.fields, "event-pose");
     const placement = extractPlacementFromFieldMap(fieldMap);
     return {
         objectId: rawPose.objectId,
         placement,
         inner: parseOptionalUnitField(fieldMap.get("inner")?.[0], "inner"),
         outer: parseOptionalUnitField(fieldMap.get("outer")?.[0], "outer"),
+        epoch: parseOptionalJoinedValue(fieldMap.get("epoch")?.[0]),
+        referencePlane: parseOptionalJoinedValue(fieldMap.get("referencePlane")?.[0]),
     };
 }
-function collectDraftFields(fields) {
+function collectDraftFields(fields, _mode = "object") {
     const grouped = new Map();
     for (const field of fields) {
         const spec = getDraftObjectFieldSpec(field.key);
-        if (!spec) {
+        if (!spec && !EVENT_POSE_FIELD_KEYS.has(field.key)) {
             throw WorldOrbitError.fromLocation(`Unknown field "${field.key}"`, field.location);
         }
-        if (!spec.allowRepeat && grouped.has(field.key)) {
+        if (!spec?.allowRepeat && grouped.has(field.key)) {
             throw WorldOrbitError.fromLocation(`Duplicate field "${field.key}"`, field.location);
         }
         const existing = grouped.get(field.key) ?? [];
@@ -1378,7 +1525,7 @@ function validateDraftObjectFieldCompatibility(fields, objectType) {
     }
 }
 function warnIfSchema21Feature(sourceSchemaVersion, diagnostics, featureName, location) {
-    if (sourceSchemaVersion === "2.1") {
+    if (!isSchemaOlderThan(sourceSchemaVersion, "2.1")) {
         return;
     }
     diagnostics.push({
@@ -1390,6 +1537,34 @@ function warnIfSchema21Feature(sourceSchemaVersion, diagnostics, featureName, lo
         column: location.column,
     });
 }
+function warnIfSchema25Feature(sourceSchemaVersion, diagnostics, featureName, location) {
+    if (!isSchemaOlderThan(sourceSchemaVersion, "2.5")) {
+        return;
+    }
+    diagnostics.push({
+        code: "parse.schema25.featureCompatibility",
+        severity: "warning",
+        source: "parse",
+        message: `Feature "${featureName}" requires schema 2.5; parsed in compatibility mode because the document header is "schema ${sourceSchemaVersion}".`,
+        line: location.line,
+        column: location.column,
+    });
+}
+function isSchemaOlderThan(sourceSchemaVersion, requiredVersion) {
+    return schemaVersionRank(sourceSchemaVersion) < schemaVersionRank(requiredVersion);
+}
+function schemaVersionRank(version) {
+    switch (version) {
+        case "2.0-draft":
+            return 0;
+        case "2.0":
+            return 1;
+        case "2.1":
+            return 2;
+        case "2.5":
+            return 3;
+    }
+}
 function preprocessAtlasSource(source) {
     const chars = [...source];
     const comments = [];

package/packages/core/dist/draft.js

@@ -18,8 +18,8 @@ export function upgradeDocumentToV2(document, options = {}) {
     }
     return {
         format: "worldorbit",
-        version: "2.0",
-        schemaVersion: "2.0",
+        version: "2.5",
+        schemaVersion: "2.5",
         sourceVersion: document.version,
         system,
         groups: structuredClone(document.groups ?? []),
@@ -82,10 +82,15 @@ function createDraftSystem(document, defaults, atlasMetadata, annotations, diagn
     };
 }
 function createDraftDefaults(document, preset, projection) {
+    const rawView = typeof document.system?.properties.view === "string"
+        ? document.system.properties.view.toLowerCase()
+        : null;
     return {
-        view: typeof document.system?.properties.view === "string" &&
-            document.system.properties.view.toLowerCase() === "topdown"
-            ? "topdown"
+        view: rawView === "topdown" ||
+            rawView === "isometric" ||
+            rawView === "orthographic" ||
+            rawView === "perspective"
+            ? rawView
             : projection,
         scale: typeof document.system?.properties.scale === "string"
             ? document.system.properties.scale
@@ -204,6 +209,7 @@ function mapSceneViewpointToDraftViewpoint(viewpoint) {
         preset: viewpoint.preset,
         zoom: viewpoint.scale,
         rotationDeg: viewpoint.rotationDeg,
+        camera: viewpoint.camera ? { ...viewpoint.camera } : null,
         layers: { ...viewpoint.layers },
         filter: viewpoint.filter
             ? {
@@ -258,6 +264,8 @@ function cloneWorldOrbitEventPose(pose) {
         placement: clonePlacement(pose.placement),
         inner: pose.inner ? { ...pose.inner } : undefined,
         outer: pose.outer ? { ...pose.outer } : undefined,
+        epoch: pose.epoch ?? null,
+        referencePlane: pose.referencePlane ?? null,
     };
 }
 function clonePlacement(placement) {
@@ -272,23 +280,42 @@ function applyEventPoseOverrides(objects, events, activeEventId) {
         return;
     }
     const objectMap = new Map(objects.map((object) => [object.id, object]));
+    const referencedIds = new Set([
+        ...(event.targetObjectId ? [event.targetObjectId] : []),
+        ...event.participantObjectIds,
+        ...event.positions.map((pose) => pose.objectId),
+    ]);
+    for (const objectId of referencedIds) {
+        const object = objectMap.get(objectId);
+        if (!object) {
+            continue;
+        }
+        if (event.epoch) {
+            object.epoch = event.epoch;
+        }
+        if (event.referencePlane) {
+            object.referencePlane = event.referencePlane;
+        }
+    }
     for (const pose of event.positions) {
         const object = objectMap.get(pose.objectId);
         if (!object) {
             continue;
         }
-        object.placement = clonePlacement(pose.placement);
+        if (pose.placement) {
+            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;
+        if (pose.epoch) {
+            object.epoch = pose.epoch;
+        }
+        if (pose.referencePlane) {
+            object.referencePlane = pose.referencePlane;
         }
     }
 }
@@ -384,6 +411,18 @@ function materializeDraftSystemInfo(system) {
         if (viewpoint.rotationDeg !== 0) {
             info[`${prefix}.rotation`] = String(viewpoint.rotationDeg);
         }
+        if (viewpoint.camera?.azimuth !== null) {
+            info[`${prefix}.camera.azimuth`] = String(viewpoint.camera?.azimuth);
+        }
+        if (viewpoint.camera?.elevation !== null) {
+            info[`${prefix}.camera.elevation`] = String(viewpoint.camera?.elevation);
+        }
+        if (viewpoint.camera?.roll !== null) {
+            info[`${prefix}.camera.roll`] = String(viewpoint.camera?.roll);
+        }
+        if (viewpoint.camera?.distance !== null) {
+            info[`${prefix}.camera.distance`] = String(viewpoint.camera?.distance);
+        }
         const serializedLayers = serializeViewpointLayers(viewpoint.layers);
         if (serializedLayers) {
             info[`${prefix}.layers`] = serializedLayers;