worldorbit 2.5.17 → 2.6.0

package/packages/editor/dist/editor.js

@@ -64,7 +64,11 @@ const OBJECT_NUMBER_FIELDS = ["albedo"];
 const FIELD_HELP = {
     "defaults-view": {
         description: "Sets the default camera projection for the atlas.",
-        references: ["Topdown = map-like", "Isometric = angled overview"],
+        references: [
+            "Topdown = map-like",
+            "Isometric = angled overview",
+            "Orthographic/Perspective = 3D-ready semantic views",
+        ],
     },
     "defaults-scale": {
         description: "Chooses the overall spacing/style preset used by the renderer.",
@@ -76,15 +80,35 @@ const FIELD_HELP = {
     },
     "viewpoint-projection": {
         description: "Overrides the projection for this saved viewpoint.",
-        references: ["Topdown = flat orbital map", "Isometric = angled scene"],
+        references: [
+            "Topdown = flat orbital map",
+            "Isometric = angled scene",
+            "Orthographic/Perspective = stored with current 2D fallback",
+        ],
     },
     "viewpoint-zoom": {
         description: "Controls how closely this viewpoint frames the system.",
         references: ["1 = scene fit", "2+ = close-up"],
     },
     "viewpoint-rotation": {
-        description: "Rotates the saved camera angle in degrees.",
-        references: ["90deg = quarter turn", "180deg = flip"],
+        description: "Legacy 2D screen rotation. This is separate from the Schema 2.5 camera block.",
+        references: ["90deg = quarter turn", "Use camera.azimuth for semantic view direction"],
+    },
+    "viewpoint-camera-azimuth": {
+        description: "Horizontal camera direction in degrees for Schema 2.5 viewpoints.",
+        references: ["0 = forward/default", "90 = quarter orbit around the scene"],
+    },
+    "viewpoint-camera-elevation": {
+        description: "Vertical camera tilt in degrees for 3D-ready viewpoints.",
+        references: ["0 = level", "30 = gentle look down"],
+    },
+    "viewpoint-camera-roll": {
+        description: "Rolls the camera around its forward axis.",
+        references: ["0 = upright", "15 = slight bank"],
+    },
+    "viewpoint-camera-distance": {
+        description: "Semantic camera distance for perspective viewpoints.",
+        references: ["4 = close", "12 = wide framing"],
     },
     "viewpoint-events": {
         description: "Lists event IDs that this viewpoint should feature in its detail panel.",
@@ -110,6 +134,14 @@ const FIELD_HELP = {
         description: "Notes where or how the event is visible.",
         references: ['"Visible from Naar"', '"Southern hemisphere only"'],
     },
+    "event-epoch": {
+        description: "Optional event-wide epoch that event poses inherit unless they override it.",
+        references: ['"JY-0001.0"', '"Naar bloom cycle year 18"'],
+    },
+    "event-referencePlane": {
+        description: "Optional event-wide reference plane for all poses in this snapshot.",
+        references: ["ecliptic", "naar-equatorial"],
+    },
     "event-viewpoints": {
         description: "Viewpoint IDs that should list this event prominently.",
         references: ["naar-system", "overview inner-system"],
@@ -150,6 +182,14 @@ const FIELD_HELP = {
         description: "Starting position of the object along its orbit.",
         references: ["0deg = start position", "180deg = opposite side"],
     },
+    "pose-epoch": {
+        description: "Overrides the effective epoch for this pose only.",
+        references: ['"JY-0001.0"', "Falls back to event, object, then system"],
+    },
+    "pose-referencePlane": {
+        description: "Overrides the effective reference plane for this pose only.",
+        references: ["naar-equatorial", "Falls back to event, object, then system"],
+    },
     "prop-radius": {
         description: "Visual body size or real-world-inspired radius value.",
         references: ["1re = Earth radius", "1sol = Sun radius"],
@@ -348,6 +388,8 @@ export function createWorldOrbitEditor(container, options = {}) {
                 participantObjectIds: [],
                 timing: null,
                 visibility: null,
+                epoch: null,
+                referencePlane: null,
                 tags: [],
                 color: null,
                 hidden: false,
@@ -372,6 +414,7 @@ export function createWorldOrbitEditor(container, options = {}) {
                 preset: atlasDocument.system?.defaults.preset ?? null,
                 zoom: null,
                 rotationDeg: 0,
+                camera: null,
                 layers: {},
                 filter: null,
             };
@@ -1335,6 +1378,7 @@ export function createWorldOrbitEditor(container, options = {}) {
                 null,
             zoom: parseNullableNumber(readOptionalTextInput(form, "viewpoint-zoom")),
             rotationDeg: parseNullableNumber(readOptionalTextInput(form, "viewpoint-rotation")) ?? 0,
+            camera: buildViewCameraFromForm(form),
             layers: {
                 background: readCheckbox(form, "layer-background"),
                 guides: readCheckbox(form, "layer-guides"),
@@ -1380,6 +1424,8 @@ export function createWorldOrbitEditor(container, options = {}) {
             participantObjectIds: splitTokens(readOptionalTextInput(form, "event-participants")),
             timing: readOptionalTextInput(form, "event-timing"),
             visibility: readOptionalTextInput(form, "event-visibility"),
+            epoch: readOptionalTextInput(form, "event-epoch"),
+            referencePlane: readOptionalTextInput(form, "event-referencePlane"),
             tags: splitTokens(readOptionalTextInput(form, "event-tags")),
             color: readOptionalTextInput(form, "event-color"),
             hidden: readCheckbox(form, "event-hidden"),
@@ -1406,6 +1452,8 @@ export function createWorldOrbitEditor(container, options = {}) {
         const replacement = {
             objectId: nextObjectId,
             placement: buildPlacementFromPoseForm(form, currentPose),
+            epoch: readOptionalTextInput(form, "pose-epoch"),
+            referencePlane: readOptionalTextInput(form, "pose-referencePlane"),
         };
         const inner = parseOptionalUnit(readOptionalTextInput(form, "prop-inner"));
         const outer = parseOptionalUnit(readOptionalTextInput(form, "prop-outer"));
@@ -1806,6 +1854,8 @@ function renderDefaultsInspector(formState) {
     ${renderInspectorSection("defaults", "basics", "Basics", `${renderSelectField("Projection", "defaults-view", [
         ["topdown", "Topdown"],
         ["isometric", "Isometric"],
+        ["orthographic", "Orthographic"],
+        ["perspective", "Perspective"],
     ], defaults?.view ?? "topdown")}
       ${renderTextField("Scale preset", "defaults-scale", defaults?.scale ?? "")}
       ${renderTextField("Units", "defaults-units", defaults?.units ?? "")}
@@ -1842,6 +1892,8 @@ function renderViewpointInspector(formState, id) {
       ${renderSelectField("Projection", "viewpoint-projection", [
         ["topdown", "Topdown"],
         ["isometric", "Isometric"],
+        ["orthographic", "Orthographic"],
+        ["perspective", "Perspective"],
     ], viewpoint.projection)}
       ${renderSelectField("Preset", "viewpoint-preset", [
         ["", "Document default"],
@@ -1852,6 +1904,11 @@ function renderViewpointInspector(formState, id) {
     ], viewpoint.preset ?? "")}
       ${renderTextField("Zoom", "viewpoint-zoom", viewpoint.zoom === null ? "" : String(viewpoint.zoom))}
       ${renderTextField("Rotation", "viewpoint-rotation", String(viewpoint.rotationDeg))}`, true)}
+    ${renderInspectorSection("viewpoint", "camera", "Camera", `${renderTextField("Azimuth", "viewpoint-camera-azimuth", viewpoint.camera?.azimuth === null || viewpoint.camera?.azimuth === undefined ? "" : String(viewpoint.camera.azimuth))}
+      ${renderTextField("Elevation", "viewpoint-camera-elevation", viewpoint.camera?.elevation === null || viewpoint.camera?.elevation === undefined ? "" : String(viewpoint.camera.elevation))}
+      ${renderTextField("Roll", "viewpoint-camera-roll", viewpoint.camera?.roll === null || viewpoint.camera?.roll === undefined ? "" : String(viewpoint.camera.roll))}
+      ${renderTextField("Distance", "viewpoint-camera-distance", viewpoint.camera?.distance === null || viewpoint.camera?.distance === undefined ? "" : String(viewpoint.camera.distance))}
+      <p class="wo-editor-inline-note">Rotation stays a 2D screen-rotation hint. The camera block stores Schema 2.5 view direction and framing.</p>`)}
     ${renderInspectorSection("viewpoint", "layers", "Layers", `<fieldset class="wo-editor-fieldset">
         <legend>Layers</legend>
         ${renderCheckboxField("Background", "layer-background", viewpoint.layers.background !== false)}
@@ -1889,6 +1946,8 @@ function renderEventInspector(formState, id) {
       ${renderTextField("Participants", "event-participants", eventEntry.participantObjectIds.join(" "))}
       ${renderTextField("Timing", "event-timing", eventEntry.timing ?? "")}
       ${renderTextField("Visibility", "event-visibility", eventEntry.visibility ?? "")}
+      ${renderTextField("Epoch", "event-epoch", eventEntry.epoch ?? "")}
+      ${renderTextField("Reference plane", "event-referencePlane", eventEntry.referencePlane ?? "")}
       ${renderTextField("Tags", "event-tags", eventEntry.tags.join(" "))}
       ${renderTextField("Color", "event-color", eventEntry.color ?? "")}
       ${renderCheckboxField("Hidden", "event-hidden", eventEntry.hidden === true)}`, true)}
@@ -1943,6 +2002,9 @@ function renderEventPoseInspector(formState, eventId, objectId) {
       ${renderTextField("Phase", "placement-phase", pose.placement?.mode === "orbit" && pose.placement.phase ? formatUnitValue(pose.placement.phase) : "")}
       ${renderTextField("Inner", "prop-inner", pose.inner ? formatUnitValue(pose.inner) : "")}
       ${renderTextField("Outer", "prop-outer", pose.outer ? formatUnitValue(pose.outer) : "")}`, true)}
+    ${renderInspectorSection("event-pose", "context", "Context", `${renderTextField("Epoch", "pose-epoch", pose.epoch ?? "")}
+      ${renderTextField("Reference plane", "pose-referencePlane", pose.referencePlane ?? "")}
+      <p class="wo-editor-inline-note">Falls back to event, then object, then system context when left empty.</p>`)}
   </form>`;
 }
 function renderAnnotationInspector(formState, id) {
@@ -2138,6 +2200,20 @@ function parseNullableNumber(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
 }
+function buildViewCameraFromForm(form) {
+    const camera = {
+        azimuth: parseNullableNumber(readOptionalTextInput(form, "viewpoint-camera-azimuth")),
+        elevation: parseNullableNumber(readOptionalTextInput(form, "viewpoint-camera-elevation")),
+        roll: parseNullableNumber(readOptionalTextInput(form, "viewpoint-camera-roll")),
+        distance: parseNullableNumber(readOptionalTextInput(form, "viewpoint-camera-distance")),
+    };
+    return camera.azimuth !== null ||
+        camera.elevation !== null ||
+        camera.roll !== null ||
+        camera.distance !== null
+        ? camera
+        : null;
+}
 function parseObjectTypes(value) {
     const tokens = splitTokens(value);
     return tokens.filter((token) => OBJECT_TYPES.includes(token));
@@ -2746,6 +2822,21 @@ function mapDiagnosticFieldToInputNames(selection, field) {
                     return ["viewpoint-zoom"];
                 case "rotationDeg":
                     return ["viewpoint-rotation"];
+                case "camera":
+                    return [
+                        "viewpoint-camera-azimuth",
+                        "viewpoint-camera-elevation",
+                        "viewpoint-camera-roll",
+                        "viewpoint-camera-distance",
+                    ];
+                case "camera.azimuth":
+                    return ["viewpoint-camera-azimuth"];
+                case "camera.elevation":
+                    return ["viewpoint-camera-elevation"];
+                case "camera.roll":
+                    return ["viewpoint-camera-roll"];
+                case "camera.distance":
+                    return ["viewpoint-camera-distance"];
                 case "events":
                     return ["viewpoint-events"];
                 default:
@@ -2771,6 +2862,10 @@ function mapDiagnosticFieldToInputNames(selection, field) {
                     return ["event-timing"];
                 case "visibility":
                     return ["event-visibility"];
+                case "epoch":
+                    return ["event-epoch"];
+                case "referencePlane":
+                    return ["event-referencePlane"];
                 case "tags":
                     return ["event-tags"];
                 case "color":
@@ -2799,6 +2894,12 @@ function mapDiagnosticFieldToInputNames(selection, field) {
             if (field === "inner" || field === "outer") {
                 return [`prop-${field}`];
             }
+            if (field === "epoch") {
+                return ["pose-epoch"];
+            }
+            if (field === "referencePlane") {
+                return ["pose-referencePlane"];
+            }
             return [];
         case "annotation":
             switch (field) {

package/packages/viewer/dist/atlas-state.js

@@ -62,13 +62,14 @@ export function searchSceneObjects(scene, query, limit = 12) {
 }
 export function createAtlasStateSnapshot(viewerState, renderOptions, filter, viewpointId) {
     return {
-        version: "2.0",
+        version: "2.5",
         viewpointId,
         activeEventId: renderOptions.activeEventId ?? null,
         viewerState: { ...viewerState },
         renderOptions: {
             preset: renderOptions.preset,
             projection: renderOptions.projection,
+            camera: renderOptions.camera ? { ...renderOptions.camera } : null,
             layers: renderOptions.layers ? { ...renderOptions.layers } : undefined,
             scaleModel: renderOptions.scaleModel ? { ...renderOptions.scaleModel } : undefined,
             activeEventId: renderOptions.activeEventId ?? null,
@@ -82,7 +83,7 @@ export function serializeViewerAtlasState(state) {
 export function deserializeViewerAtlasState(serialized) {
     const raw = JSON.parse(decodeURIComponent(serialized));
     return {
-        version: "2.0",
+        version: raw.version === "2.0" ? "2.0" : "2.5",
         viewpointId: raw.viewpointId ?? null,
         activeEventId: raw.activeEventId ?? raw.renderOptions?.activeEventId ?? null,
         viewerState: {
@@ -95,6 +96,7 @@ export function deserializeViewerAtlasState(serialized) {
         renderOptions: {
             preset: raw.renderOptions?.preset,
             projection: raw.renderOptions?.projection,
+            camera: raw.renderOptions?.camera ? { ...raw.renderOptions.camera } : null,
             layers: raw.renderOptions?.layers ? { ...raw.renderOptions.layers } : undefined,
             scaleModel: raw.renderOptions?.scaleModel
                 ? { ...raw.renderOptions.scaleModel }
@@ -117,6 +119,7 @@ export function createViewerBookmark(name, label, atlasState) {
             viewerState: { ...atlasState.viewerState },
             renderOptions: {
                 ...atlasState.renderOptions,
+                camera: atlasState.renderOptions.camera ? { ...atlasState.renderOptions.camera } : null,
                 layers: atlasState.renderOptions.layers ? { ...atlasState.renderOptions.layers } : undefined,
                 scaleModel: atlasState.renderOptions.scaleModel
                     ? { ...atlasState.renderOptions.scaleModel }

package/packages/viewer/dist/atlas-viewer.js

@@ -326,6 +326,8 @@ export function createAtlasViewer(container, options) {
     }
     function buildInspectorSnapshot() {
         const activeViewer = requireViewer();
+        const scene = activeViewer.getScene();
+        const camera = scene.camera;
         return {
             selection: activeViewer.getSelectionDetails(),
             activeViewpoint: activeViewer.getActiveViewpoint(),
@@ -333,14 +335,23 @@ export function createAtlasViewer(container, options) {
             atlasState: activeViewer.getAtlasState(),
             visibleObjectIds: activeViewer.getVisibleObjects().map((object) => object.objectId),
             scene: {
-                title: activeViewer.getScene().title,
-                projection: activeViewer.getScene().projection,
-                renderPreset: activeViewer.getScene().renderPreset,
-                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,
+                title: scene.title,
+                projection: scene.projection,
+                renderProjection: scene.renderProjection,
+                camera: camera
+                    ? {
+                        azimuth: camera.azimuth,
+                        elevation: camera.elevation,
+                        roll: camera.roll,
+                        distance: camera.distance,
+                    }
+                    : null,
+                renderPreset: scene.renderPreset,
+                groupCount: scene.groups.length,
+                semanticGroupCount: scene.semanticGroups.length,
+                relationCount: scene.relations.length,
+                eventCount: scene.events.length,
+                viewpointCount: scene.viewpoints.length,
             },
         };
     }

package/packages/viewer/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { CoordinatePoint, RenderOrbitVisual, RenderPresetName, RenderSceneEvent, RenderSceneGroup, RenderSceneLabel, RenderScaleModel, RenderScene, RenderSceneObject, RenderSceneViewpoint, SceneRenderOptions, ViewProjection, WorldOrbitObject, WorldOrbitDocument } from "@worldorbit/core";
+import type { CoordinatePoint, RenderOrbitVisual, RenderProjectionFallback, RenderPresetName, RenderSceneEvent, RenderSceneGroup, RenderSceneLabel, RenderScaleModel, RenderScene, RenderSceneObject, RenderSceneViewpoint, SceneRenderOptions, ViewProjection, WorldOrbitObject, WorldOrbitDocument, WorldOrbitViewCamera } from "@worldorbit/core";
 export type WorldOrbitThemeName = "atlas" | "nightglass" | "ember";
 export type WorldOrbitEmbedMode = "static" | "interactive";
 export type TooltipMode = "hover" | "pinned" | "disabled";
@@ -104,13 +104,14 @@ export interface ViewerTooltipDetails {
     details: ViewerObjectDetails;
 }
 export interface ViewerAtlasState {
-    version: "2.0";
+    version: "2.0" | "2.5";
     viewpointId: string | null;
     activeEventId?: string | null;
     viewerState: ViewerState;
     renderOptions: {
         preset?: RenderPresetName;
         projection?: "document" | ViewProjection;
+        camera?: WorldOrbitViewCamera | null;
         layers?: ViewerLayerOptions;
         scaleModel?: Partial<RenderScaleModel>;
         activeEventId?: string | null;
@@ -139,6 +140,8 @@ export interface AtlasInspectorSnapshot {
     scene: {
         title: string;
         projection: ViewProjection;
+        renderProjection: RenderProjectionFallback;
+        camera: WorldOrbitViewCamera | null;
         renderPreset: RenderPresetName | null;
         groupCount: number;
         semanticGroupCount: number;

package/packages/viewer/dist/viewer.js

@@ -43,6 +43,7 @@ export function createInteractiveViewer(container, options) {
         padding: options.padding,
         preset: options.preset,
         projection: options.projection,
+        camera: options.camera ? { ...options.camera } : null,
         scaleModel: options.scaleModel ? { ...options.scaleModel } : undefined,
         theme: options.theme,
         layers: options.layers,
@@ -333,6 +334,12 @@ export function createInteractiveViewer(container, options) {
             if (currentInput.kind !== "scene" && viewpoint.projection !== scene.projection) {
                 nextRenderOptions.projection = viewpoint.projection;
             }
+            if (viewpoint.camera) {
+                nextRenderOptions.camera = { ...viewpoint.camera };
+            }
+            else if (renderOptions.camera) {
+                nextRenderOptions.camera = null;
+            }
             if (viewpointLayers) {
                 nextRenderOptions.layers = viewpointLayers;
             }
@@ -992,6 +999,7 @@ function renderSceneFromInput(input, renderOptions) {
 function cloneRenderOptions(renderOptions) {
     return {
         ...renderOptions,
+        camera: renderOptions.camera ? { ...renderOptions.camera } : null,
         filter: renderOptions.filter ? { ...renderOptions.filter } : undefined,
         scaleModel: renderOptions.scaleModel ? { ...renderOptions.scaleModel } : undefined,
         layers: renderOptions.layers ? { ...renderOptions.layers } : undefined,
@@ -1005,6 +1013,13 @@ function mergeRenderOptions(current, next) {
     return {
         ...current,
         ...next,
+        camera: next.camera !== undefined
+            ? next.camera
+                ? { ...next.camera }
+                : null
+            : current.camera
+                ? { ...current.camera }
+                : null,
         filter: next.filter !== undefined
             ? normalizeViewerFilter(next.filter)
             : current.filter
@@ -1037,6 +1052,7 @@ function hasSceneAffectingRenderOptions(options) {
         options.padding !== undefined ||
         options.preset !== undefined ||
         options.projection !== undefined ||
+        options.camera !== undefined ||
         options.scaleModel !== undefined ||
         options.activeEventId !== undefined);
 }