worldorbit 2.5.17 → 3.0.0

package/packages/core/dist/format.js

@@ -38,15 +38,17 @@ export function formatDocument(document, options = {}) {
     const schema = options.schema ?? "auto";
     const useDraft = schema === "2.0" ||
         schema === "2.1" ||
+        schema === "2.5" ||
         schema === "2.0-draft" ||
         document.version === "2.0" ||
         document.version === "2.1" ||
+        document.version === "2.5" ||
         document.version === "2.0-draft";
     if (useDraft) {
         if (schema === "2.0-draft") {
             const legacyDraftDocument = document.version === "2.0-draft"
                 ? document
-                : document.version === "2.0" || document.version === "2.1"
+                : document.version === "2.0" || document.version === "2.1" || document.version === "2.5"
                     ? {
                         ...document,
                         version: "2.0-draft",
@@ -55,7 +57,7 @@ export function formatDocument(document, options = {}) {
                     : upgradeDocumentToDraftV2(document);
             return formatDraftDocument(legacyDraftDocument);
         }
-        const atlasDocument = document.version === "2.0" || document.version === "2.1"
+        const atlasDocument = document.version === "2.0" || document.version === "2.1" || document.version === "2.5"
             ? document
             : document.version === "2.0-draft"
                 ? {
@@ -64,11 +66,11 @@ export function formatDocument(document, options = {}) {
                     schemaVersion: "2.0",
                 }
                 : upgradeDocumentToV2(document);
-        if (schema === "2.1" && atlasDocument.version !== "2.1") {
+        if ((schema === "2.0" || schema === "2.1" || schema === "2.5") && atlasDocument.version !== schema) {
             return formatAtlasDocument({
                 ...atlasDocument,
-                version: "2.1",
-                schemaVersion: "2.1",
+                version: schema,
+                schemaVersion: schema,
             });
         }
         return formatAtlasDocument(atlasDocument);
@@ -349,6 +351,21 @@ function formatAtlasViewpoint(viewpoint) {
     if (viewpoint.rotationDeg !== 0) {
         lines.push(`  rotation ${viewpoint.rotationDeg}`);
     }
+    if (viewpoint.camera && hasCameraValues(viewpoint.camera)) {
+        lines.push("  camera");
+        if (viewpoint.camera.azimuth !== null) {
+            lines.push(`    azimuth ${viewpoint.camera.azimuth}`);
+        }
+        if (viewpoint.camera.elevation !== null) {
+            lines.push(`    elevation ${viewpoint.camera.elevation}`);
+        }
+        if (viewpoint.camera.roll !== null) {
+            lines.push(`    roll ${viewpoint.camera.roll}`);
+        }
+        if (viewpoint.camera.distance !== null) {
+            lines.push(`    distance ${viewpoint.camera.distance}`);
+        }
+    }
     const layerTokens = formatDraftLayers(viewpoint.layers);
     if (layerTokens.length > 0) {
         lines.push(`  layers ${layerTokens.join(" ")}`);
@@ -448,6 +465,12 @@ function formatAtlasEvent(event) {
     if (event.visibility) {
         lines.push(`  visibility ${quoteIfNeeded(event.visibility)}`);
     }
+    if (event.epoch) {
+        lines.push(`  epoch ${quoteIfNeeded(event.epoch)}`);
+    }
+    if (event.referencePlane) {
+        lines.push(`  referencePlane ${quoteIfNeeded(event.referencePlane)}`);
+    }
     if (event.tags.length > 0) {
         lines.push(`  tags ${event.tags.map(quoteIfNeeded).join(" ")}`);
     }
@@ -472,10 +495,18 @@ function formatAtlasEvent(event) {
 function formatEventPoseFields(pose) {
     return [
         ...formatPlacement(pose.placement),
+        ...(pose.epoch ? [`epoch ${quoteIfNeeded(pose.epoch)}`] : []),
+        ...(pose.referencePlane ? [`referencePlane ${quoteIfNeeded(pose.referencePlane)}`] : []),
         ...formatOptionalUnit("inner", pose.inner),
         ...formatOptionalUnit("outer", pose.outer),
     ];
 }
+function hasCameraValues(camera) {
+    return (camera.azimuth !== null ||
+        camera.elevation !== null ||
+        camera.roll !== null ||
+        camera.distance !== null);
+}
 function formatValue(value) {
     if (Array.isArray(value)) {
         return value.map((item) => quoteIfNeeded(item)).join(" ");

package/packages/core/dist/index.d.ts

@@ -7,6 +7,7 @@ export { normalizeDocument } from "./normalize.js";
 export { validateDocument } from "./validate.js";
 export { createDiagnostic, diagnosticFromError, normalizeWithDiagnostics, parseWithDiagnostics, validateDocumentWithDiagnostics, } from "./diagnostics.js";
 export { renderDocumentToScene, rotatePoint } from "./scene.js";
+export { evaluateSpatialSceneAtTime, renderDocumentToSpatialScene, } from "./spatial-scene.js";
 export { formatAtlasDocument, formatDocument, formatDraftDocument } from "./format.js";
 export { materializeAtlasDocument, materializeDraftDocument, upgradeDocumentToDraftV2, upgradeDocumentToV2, } from "./draft.js";
 export { parseWorldOrbitAtlas, parseWorldOrbitDraft } from "./draft-parse.js";

package/packages/core/dist/index.js

@@ -7,6 +7,7 @@ export { normalizeDocument } from "./normalize.js";
 export { validateDocument } from "./validate.js";
 export { createDiagnostic, diagnosticFromError, normalizeWithDiagnostics, parseWithDiagnostics, validateDocumentWithDiagnostics, } from "./diagnostics.js";
 export { renderDocumentToScene, rotatePoint } from "./scene.js";
+export { evaluateSpatialSceneAtTime, renderDocumentToSpatialScene, } from "./spatial-scene.js";
 export { formatAtlasDocument, formatDocument, formatDraftDocument } from "./format.js";
 export { materializeAtlasDocument, materializeDraftDocument, upgradeDocumentToDraftV2, upgradeDocumentToV2, } from "./draft.js";
 export { parseWorldOrbitAtlas, parseWorldOrbitDraft } from "./draft-parse.js";

package/packages/core/dist/load.js

@@ -5,8 +5,9 @@ import { WorldOrbitError } from "./errors.js";
 import { normalizeDocument } from "./normalize.js";
 import { parseWorldOrbit } from "./parse.js";
 import { validateDocument } from "./validate.js";
-const ATLAS_SCHEMA_PATTERN = /^schema\s+2(?:\.0|\.1)?$/i;
+const ATLAS_SCHEMA_PATTERN = /^schema\s+2(?:\.0|\.1|\.5)?$/i;
 const ATLAS_SCHEMA_21_PATTERN = /^schema\s+2\.1$/i;
+const ATLAS_SCHEMA_25_PATTERN = /^schema\s+2\.5$/i;
 const LEGACY_DRAFT_SCHEMA_PATTERN = /^schema\s+2\.0-draft$/i;
 export function detectWorldOrbitSchemaVersion(source) {
     for (const line of stripCommentsForSchemaDetection(source).split(/\r?\n/)) {
@@ -20,6 +21,9 @@ export function detectWorldOrbitSchemaVersion(source) {
         if (ATLAS_SCHEMA_21_PATTERN.test(trimmed)) {
             return "2.1";
         }
+        if (ATLAS_SCHEMA_25_PATTERN.test(trimmed)) {
+            return "2.5";
+        }
         if (ATLAS_SCHEMA_PATTERN.test(trimmed)) {
             return "2.0";
         }
@@ -80,7 +84,10 @@ export function loadWorldOrbitSource(source) {
 }
 export function loadWorldOrbitSourceWithDiagnostics(source) {
     const schemaVersion = detectWorldOrbitSchemaVersion(source);
-    if (schemaVersion === "2.0" || schemaVersion === "2.0-draft" || schemaVersion === "2.1") {
+    if (schemaVersion === "2.0" ||
+        schemaVersion === "2.0-draft" ||
+        schemaVersion === "2.1" ||
+        schemaVersion === "2.5") {
         return loadAtlasSourceWithDiagnostics(source, schemaVersion);
     }
     let ast;

package/packages/core/dist/scene.js

@@ -14,7 +14,9 @@ export function renderDocumentToScene(document, options = {}) {
     const height = frame.height;
     const padding = frame.padding;
     const layoutPreset = resolveLayoutPreset(document);
-    const projection = resolveProjection(document, options.projection);
+    const schemaProjection = resolveProjection(document, options.projection);
+    const camera = normalizeViewCamera(options.camera ?? null);
+    const renderProjection = resolveRenderProjection(schemaProjection, camera);
     const scaleModel = resolveScaleModel(layoutPreset, options.scaleModel);
     const spacingFactor = layoutPresetSpacing(layoutPreset);
     const systemId = document.system?.id ?? null;
@@ -57,7 +59,7 @@ export function renderDocumentToScene(document, options = {}) {
         surfaceChildren,
         objectMap,
         spacingFactor,
-        projection,
+        projection: renderProjection,
         scaleModel,
     };
     const primaryRoot = rootObjects.find((object) => object.type === "star") ?? rootObjects[0] ?? null;
@@ -72,7 +74,7 @@ export function renderDocumentToScene(document, options = {}) {
             scaleModel.orbitDistanceMultiplier;
         secondaryRoots.forEach((object, index) => {
             const angle = angleForIndex(index, secondaryRoots.length, -Math.PI / 2);
-            const offset = projectPolarOffset(angle, rootRingRadius, projection, 1);
+            const offset = projectPolarOffset(angle, rootRingRadius, renderProjection, 1);
             placeObject(object, centerX + offset.x, centerY + offset.y, 0, positions, orbitDrafts, leaderDrafts, context);
         });
     }
@@ -137,28 +139,35 @@ export function renderDocumentToScene(document, options = {}) {
     const layers = createSceneLayers(orbitVisuals, relations, events, leaders, objects, labels);
     const groups = createSceneGroups(objects, orbitVisuals, leaders, labels, relationships, scaleModel.labelMultiplier);
     const semanticGroups = createSceneSemanticGroups(document, objects);
-    const viewpoints = createSceneViewpoints(document, projection, frame.preset, relationships, objectMap);
+    const viewpoints = createSceneViewpoints(document, schemaProjection, frame.preset, relationships, objectMap);
     const contentBounds = calculateContentBounds(width, height, objects, orbitVisuals, leaders, labels, scaleModel.labelMultiplier);
     return {
         width,
         height,
         padding,
         renderPreset: frame.preset,
-        projection,
+        projection: schemaProjection,
+        renderProjection,
+        camera,
         scaleModel,
         title: String(document.system?.title ?? document.system?.properties.title ?? document.system?.id ?? "WorldOrbit") ||
             "WorldOrbit",
-        subtitle: `${capitalizeLabel(projection)} view - ${capitalizeLabel(layoutPreset)} layout`,
+        subtitle: buildSceneSubtitle(schemaProjection, renderProjection, layoutPreset, camera),
         systemId,
-        viewMode: projection,
+        viewMode: schemaProjection,
         layoutPreset,
         metadata: {
             format: document.format,
             version: document.version,
-            view: projection,
+            view: schemaProjection,
+            renderProjection,
             scale: String(document.system?.properties.scale ?? layoutPreset),
             units: String(document.system?.properties.units ?? "mixed"),
             preset: frame.preset ?? "custom",
+            ...(camera?.azimuth !== null ? { "camera.azimuth": String(camera?.azimuth) } : {}),
+            ...(camera?.elevation !== null ? { "camera.elevation": String(camera?.elevation) } : {}),
+            ...(camera?.roll !== null ? { "camera.roll": String(camera?.roll) } : {}),
+            ...(camera?.distance !== null ? { "camera.distance": String(camera?.distance) } : {}),
         },
         contentBounds,
         layers,
@@ -195,23 +204,42 @@ function createEffectiveObjects(objects, events, activeEventId) {
         return cloned;
     }
     const objectMap = new Map(cloned.map((object) => [object.id, object]));
+    const referencedIds = new Set([
+        ...(activeEvent.targetObjectId ? [activeEvent.targetObjectId] : []),
+        ...activeEvent.participantObjectIds,
+        ...activeEvent.positions.map((pose) => pose.objectId),
+    ]);
+    for (const objectId of referencedIds) {
+        const object = objectMap.get(objectId);
+        if (!object) {
+            continue;
+        }
+        if (activeEvent.epoch) {
+            object.epoch = activeEvent.epoch;
+        }
+        if (activeEvent.referencePlane) {
+            object.referencePlane = activeEvent.referencePlane;
+        }
+    }
     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.placement) {
+            object.placement = structuredClone(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;
         }
     }
     return cloned;
@@ -252,12 +280,69 @@ function scenePresetDefaults(preset) {
     }
 }
 function resolveProjection(document, projection) {
-    if (projection === "topdown" || projection === "isometric") {
+    if (projection === "topdown" ||
+        projection === "isometric" ||
+        projection === "orthographic" ||
+        projection === "perspective") {
         return projection;
     }
-    return String(document.system?.properties.view ?? "topdown").toLowerCase() === "isometric"
-        ? "isometric"
-        : "topdown";
+    const documentView = String(document.system?.properties.view ?? "topdown").toLowerCase();
+    return parseViewProjection(documentView) ?? "topdown";
+}
+function resolveRenderProjection(projection, camera) {
+    switch (projection) {
+        case "topdown":
+            return "topdown";
+        case "isometric":
+            return "isometric";
+        case "orthographic":
+            return camera && (camera.azimuth !== null || camera.elevation !== null || camera.roll !== null)
+                ? "isometric"
+                : "topdown";
+        case "perspective":
+            return "isometric";
+    }
+}
+function normalizeViewCamera(camera) {
+    if (!camera) {
+        return null;
+    }
+    const normalized = {
+        azimuth: normalizeFiniteCameraValue(camera.azimuth),
+        elevation: normalizeFiniteCameraValue(camera.elevation),
+        roll: normalizeFiniteCameraValue(camera.roll),
+        distance: normalizePositiveCameraDistance(camera.distance),
+    };
+    return normalized.azimuth !== null ||
+        normalized.elevation !== null ||
+        normalized.roll !== null ||
+        normalized.distance !== null
+        ? normalized
+        : null;
+}
+function normalizeFiniteCameraValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizePositiveCameraDistance(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+function buildSceneSubtitle(projection, renderProjection, layoutPreset, camera) {
+    const parts = [`${capitalizeLabel(projection)} view`, `${capitalizeLabel(layoutPreset)} layout`];
+    if (projection !== renderProjection) {
+        parts.push(`2D ${renderProjection} fallback`);
+    }
+    if (camera) {
+        const cameraParts = [
+            camera.azimuth !== null ? `az ${camera.azimuth}` : null,
+            camera.elevation !== null ? `el ${camera.elevation}` : null,
+            camera.roll !== null ? `roll ${camera.roll}` : null,
+            camera.distance !== null ? `dist ${camera.distance}` : null,
+        ].filter(Boolean);
+        if (cameraParts.length > 0) {
+            parts.push(`camera ${cameraParts.join(" / ")}`);
+        }
+    }
+    return parts.join(" - ");
 }
 function resolveScaleModel(layoutPreset, overrides) {
     const defaults = defaultScaleModel(layoutPreset);
@@ -728,6 +813,8 @@ function createSceneViewpoints(document, projection, preset, relationships, obje
 function createGeneratedOverviewViewpoint(document, projection, preset) {
     const title = document.system?.title ?? document.system?.properties.title;
     const label = title ? `${String(title)} Overview` : "Overview";
+    const camera = normalizeViewCamera(null);
+    const renderProjection = resolveRenderProjection(projection, camera);
     return {
         id: "overview",
         label,
@@ -736,6 +823,8 @@ function createGeneratedOverviewViewpoint(document, projection, preset) {
         selectedObjectId: null,
         eventIds: [],
         projection,
+        renderProjection,
+        camera,
         preset,
         rotationDeg: 0,
         scale: null,
@@ -785,6 +874,30 @@ function applyViewpointField(draft, field, value, document, projection, preset,
         case "angle":
             draft.rotationDeg = parseFiniteNumber(normalizedValue) ?? draft.rotationDeg ?? 0;
             return;
+        case "camera.azimuth":
+            draft.camera = {
+                ...(draft.camera ?? createEmptyViewCamera()),
+                azimuth: parseFiniteNumber(normalizedValue),
+            };
+            return;
+        case "camera.elevation":
+            draft.camera = {
+                ...(draft.camera ?? createEmptyViewCamera()),
+                elevation: parseFiniteNumber(normalizedValue),
+            };
+            return;
+        case "camera.roll":
+            draft.camera = {
+                ...(draft.camera ?? createEmptyViewCamera()),
+                roll: parseFiniteNumber(normalizedValue),
+            };
+            return;
+        case "camera.distance":
+            draft.camera = {
+                ...(draft.camera ?? createEmptyViewCamera()),
+                distance: parsePositiveNumber(normalizedValue),
+            };
+            return;
         case "zoom":
         case "scale":
             draft.scale = parsePositiveNumber(normalizedValue);
@@ -826,6 +939,9 @@ function finalizeViewpointDraft(draft, projection, preset, objectMap) {
         : objectId;
     const filter = normalizeViewpointFilter(draft.filter);
     const label = draft.label?.trim() || humanizeIdentifier(draft.id);
+    const resolvedProjection = draft.projection ?? projection;
+    const camera = normalizeViewCamera(draft.camera ?? null);
+    const renderProjection = resolveRenderProjection(resolvedProjection, camera);
     return {
         id: draft.id,
         label,
@@ -833,7 +949,9 @@ function finalizeViewpointDraft(draft, projection, preset, objectMap) {
         objectId,
         selectedObjectId,
         eventIds: [...new Set(draft.eventIds ?? [])],
-        projection: draft.projection ?? projection,
+        projection: resolvedProjection,
+        renderProjection,
+        camera,
         preset: draft.preset ?? preset,
         rotationDeg: draft.rotationDeg ?? 0,
         scale: draft.scale ?? null,
@@ -850,6 +968,14 @@ function createEmptyViewpointFilter() {
         groupIds: [],
     };
 }
+function createEmptyViewCamera() {
+    return {
+        azimuth: null,
+        elevation: null,
+        roll: null,
+        distance: null,
+    };
+}
 function normalizeViewpointFilter(filter) {
     if (!filter) {
         return null;
@@ -868,11 +994,18 @@ function normalizeViewpointFilter(filter) {
         : null;
 }
 function parseViewProjection(value) {
-    return value.toLowerCase() === "isometric"
-        ? "isometric"
-        : value.toLowerCase() === "topdown"
-            ? "topdown"
-            : null;
+    switch (value.toLowerCase()) {
+        case "topdown":
+            return "topdown";
+        case "isometric":
+            return "isometric";
+        case "orthographic":
+            return "orthographic";
+        case "perspective":
+            return "perspective";
+        default:
+            return null;
+    }
 }
 function parseRenderPreset(value) {
     const normalized = value.toLowerCase();
@@ -930,6 +1063,7 @@ function parseViewpointObjectTypes(value) {
 function parseViewpointGroups(value, document, relationships, objectMap) {
     return splitListValue(value).map((entry) => {
         if (document.schemaVersion === "2.1" ||
+            document.schemaVersion === "2.5" ||
             document.groups.some((group) => group.id === entry)) {
             return entry;
         }

package/packages/core/dist/spatial-scene.d.ts

@@ -0,0 +1,3 @@
+import type { CoordinatePoint3D, SpatialScene, SpatialSceneRenderOptions, WorldOrbitDocument } from "./types.js";
+export declare function renderDocumentToSpatialScene(document: WorldOrbitDocument, options?: SpatialSceneRenderOptions): SpatialScene;
+export declare function evaluateSpatialSceneAtTime(scene: SpatialScene, timeSeconds: number): Map<string, CoordinatePoint3D>;