worldorbit 2.5.17 → 3.0.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"],
@@ -206,6 +246,7 @@ export function createWorldOrbitEditor(container, options = {}) {
     const showInspector = options.showInspector ?? true;
     const showPreview = options.showPreview ?? true;
     const shortcutsEnabled = options.shortcuts ?? true;
+    let viewMode = options.viewMode ?? "2d";
     container.classList.add("wo-editor");
     container.dataset.woShowInspector = String(showInspector);
     container.dataset.woShowTextPane = String(showTextPane);
@@ -231,6 +272,7 @@ export function createWorldOrbitEditor(container, options = {}) {
         height: options.viewerHeight ?? 680,
         preset: atlasDocument.system?.defaults.preset ?? "atlas-card",
         projection: "document",
+        viewMode,
         minimap: true,
         tooltipMode: "hover",
         onSelectionChange(selectedObject) {
@@ -297,6 +339,22 @@ export function createWorldOrbitEditor(container, options = {}) {
         getSelection() {
             return selection ? { path: { ...selection } } : null;
         },
+        getViewMode() {
+            return viewMode;
+        },
+        setViewMode(mode) {
+            const previousViewMode = viewMode;
+            try {
+                viewer.setViewMode(mode);
+                viewMode = mode;
+                renderStageOverlay();
+                renderPreviewNow();
+            }
+            catch (error) {
+                viewMode = previousViewMode;
+                throw error;
+            }
+        },
         isDirty() {
             return dirty;
         },
@@ -348,6 +406,8 @@ export function createWorldOrbitEditor(container, options = {}) {
                 participantObjectIds: [],
                 timing: null,
                 visibility: null,
+                epoch: null,
+                referencePlane: null,
                 tags: [],
                 color: null,
                 hidden: false,
@@ -372,6 +432,7 @@ export function createWorldOrbitEditor(container, options = {}) {
                 preset: atlasDocument.system?.defaults.preset ?? null,
                 zoom: null,
                 rotationDeg: 0,
+                camera: null,
                 layers: {},
                 filter: null,
             };
@@ -418,7 +479,7 @@ export function createWorldOrbitEditor(container, options = {}) {
             return viewer.exportSvg();
         },
         exportEmbedMarkup() {
-            return buildEmbedMarkup(getCurrentSourceForExport(), atlasDocument);
+            return buildEmbedMarkup(getCurrentSourceForExport(), atlasDocument, viewMode);
         },
         destroy() {
             if (destroyed) {
@@ -863,6 +924,9 @@ export function createWorldOrbitEditor(container, options = {}) {
             return;
         }
         overlay.innerHTML = "";
+        if (viewMode === "3d") {
+            return;
+        }
         const selectedObjectId = selection?.kind === "object"
             ? selection.id ?? null
             : selection?.kind === "event-pose"
@@ -1335,6 +1399,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 +1445,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 +1473,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"));
@@ -1529,7 +1598,7 @@ export function createWorldOrbitEditor(container, options = {}) {
             previewVisual.innerHTML = nextSvg;
             lastPreviewSvg = nextSvg;
         }
-        const nextMarkup = buildEmbedMarkup(getCurrentSourceForExport(), atlasDocument);
+        const nextMarkup = buildEmbedMarkup(getCurrentSourceForExport(), atlasDocument, viewMode);
         if (previewMarkup && nextMarkup !== lastPreviewMarkup) {
             previewMarkup.textContent = nextMarkup;
             lastPreviewMarkup = nextMarkup;
@@ -1806,6 +1875,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 +1913,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 +1925,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 +1967,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 +2023,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 +2221,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 +2843,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 +2883,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 +2915,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) {
@@ -2868,9 +2990,9 @@ function mapDiagnosticFieldToInputNames(selection, field) {
             return [`prop-${field}`];
     }
 }
-function buildEmbedMarkup(source, document) {
+function buildEmbedMarkup(source, document, viewMode) {
     return renderWorldOrbitBlock(source, {
-        mode: "interactive",
+        mode: viewMode === "3d" ? "interactive-3d" : "interactive-2d",
         preset: document.system?.defaults.preset ?? "atlas-card",
         projection: document.system?.defaults.view ?? "topdown",
     });

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

@@ -1,4 +1,5 @@
 import type { AtlasDocumentPath, AtlasResolvedDiagnostic, WorldOrbitAtlasDocument, WorldOrbitEvent, WorldOrbitAtlasSystem, WorldOrbitAtlasViewpoint, WorldOrbitObject } from "@worldorbit/core";
+import type { WorldOrbitViewMode } from "@worldorbit/viewer";
 export interface WorldOrbitEditorSelection {
     path: AtlasDocumentPath | null;
 }
@@ -16,6 +17,7 @@ export interface WorldOrbitEditorOptions {
     showPreview?: boolean;
     viewerWidth?: number;
     viewerHeight?: number;
+    viewMode?: WorldOrbitViewMode;
     shortcuts?: boolean;
     onChange?: (snapshot: WorldOrbitEditorSnapshot) => void;
     onDiagnosticsChange?: (diagnostics: AtlasResolvedDiagnostic[]) => void;
@@ -29,6 +31,8 @@ export interface WorldOrbitEditor {
     getAtlasDocument(): WorldOrbitAtlasDocument;
     getDiagnostics(): AtlasResolvedDiagnostic[];
     getSelection(): WorldOrbitEditorSelection | null;
+    getViewMode(): WorldOrbitViewMode;
+    setViewMode(mode: WorldOrbitViewMode): void;
     isDirty(): boolean;
     markSaved(): void;
     selectPath(path: AtlasDocumentPath | null): void;

package/packages/markdown/dist/html.js

@@ -1,11 +1,17 @@
-import { loadWorldOrbitSource, renderDocumentToScene, } from "@worldorbit/core";
+import { loadWorldOrbitSource, renderDocumentToScene, renderDocumentToSpatialScene, } from "@worldorbit/core";
 import { createEmbedPayload, createWorldOrbitEmbedMarkup, renderSceneToSvg, } from "@worldorbit/viewer";
 export function renderWorldOrbitBlock(source, options = {}) {
     try {
         const loaded = loadWorldOrbitSource(source);
         const scene = renderDocumentToScene(loaded.document, resolveSourceRenderOptions(loaded, options));
-        if ((options.mode ?? "static") === "interactive") {
-            return createWorldOrbitEmbedMarkup(createEmbedPayload(scene, "interactive", {
+        const mode = options.mode ?? "static";
+        if (mode === "interactive" || mode === "interactive-2d" || mode === "interactive-3d") {
+            const normalizedMode = mode === "interactive" ? "interactive-2d" : mode;
+            return createWorldOrbitEmbedMarkup(createEmbedPayload(scene, normalizedMode, {
+                spatialScene: normalizedMode === "interactive-3d"
+                    ? renderDocumentToSpatialScene(loaded.document, resolveSourceRenderOptions(loaded, options))
+                    : undefined,
+                viewMode: normalizedMode === "interactive-3d" ? "3d" : "2d",
                 initialViewpointId: options.initialViewpointId,
                 initialSelectionObjectId: options.initialSelectionObjectId,
                 initialFilter: options.initialFilter ?? null,
@@ -17,6 +23,7 @@ export function renderWorldOrbitBlock(source, options = {}) {
                 layers: options.layers,
                 subtitle: options.subtitle,
                 preset: options.preset,
+                viewMode: normalizedMode === "interactive-3d" ? "3d" : "2d",
                 initialViewpointId: options.initialViewpointId,
                 initialSelectionObjectId: options.initialSelectionObjectId,
                 initialFilter: options.initialFilter ?? null,

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

@@ -62,16 +62,18 @@ 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,
+            viewMode: renderOptions.viewMode ?? "2d",
         },
         filter: normalizeViewerFilter(filter),
     };
@@ -82,7 +84,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,11 +97,13 @@ 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 }
                 : undefined,
             activeEventId: raw.activeEventId ?? raw.renderOptions?.activeEventId ?? null,
+            viewMode: raw.renderOptions?.viewMode ?? "2d",
         },
         filter: normalizeViewerFilter(raw.filter ?? null),
     };
@@ -117,11 +121,13 @@ 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 }
                     : undefined,
                 activeEventId: atlasState.renderOptions.activeEventId ?? null,
+                viewMode: atlasState.renderOptions.viewMode ?? "2d",
             },
             filter: atlasState.filter ? { ...atlasState.filter } : null,
         },

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,
             },
         };
     }
@@ -469,6 +480,7 @@ function cloneBookmark(bookmark) {
                 scaleModel: bookmark.atlasState.renderOptions.scaleModel
                     ? { ...bookmark.atlasState.renderOptions.scaleModel }
                     : undefined,
+                viewMode: bookmark.atlasState.renderOptions.viewMode ?? "2d",
             },
             filter: bookmark.atlasState.filter ? { ...bookmark.atlasState.filter } : null,
         },

package/packages/viewer/dist/custom-element.js

@@ -1,4 +1,6 @@
 import { loadWorldOrbitSource, renderDocumentToScene, } from "@worldorbit/core";
+import { WorldOrbit3DUnavailableError } from "./errors.js";
+import { render3DUnavailableMarkup } from "./embed.js";
 import { renderSceneToSvg } from "./render.js";
 import { createAtlasViewer } from "./atlas-viewer.js";
 import { createInteractiveViewer } from "./viewer.js";
@@ -51,10 +53,22 @@ export function defineWorldOrbitViewerElement(tagName = "worldorbit-viewer") {
                 });
                 return;
             }
-            this.viewer = createInteractiveViewer(this, {
-                scene,
-                theme,
-            });
+            try {
+                this.viewer = createInteractiveViewer(this, {
+                    source,
+                    theme,
+                    viewMode: mode === "interactive-3d"
+                        ? "3d"
+                        : "2d",
+                });
+            }
+            catch (error) {
+                if (error instanceof WorldOrbit3DUnavailableError && mode === "interactive-3d") {
+                    this.innerHTML = render3DUnavailableMarkup(error.message);
+                    return;
+                }
+                throw error;
+            }
         }
     }
     customElements.define(tagName, WorldOrbitViewerElement);

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

@@ -1,8 +1,10 @@
-import type { RenderScene } from "@worldorbit/core";
+import type { RenderScene, SpatialScene } from "@worldorbit/core";
 import type { MountedWorldOrbitEmbeds, MountWorldOrbitEmbedsOptions, ViewerAtlasState, ViewerFilter, WorldOrbitEmbedPayload } from "./types.js";
 export declare function serializeWorldOrbitEmbedPayload(payload: WorldOrbitEmbedPayload): string;
 export declare function deserializeWorldOrbitEmbedPayload(serialized: string): WorldOrbitEmbedPayload;
 export declare function createEmbedPayload(scene: RenderScene, mode: WorldOrbitEmbedPayload["mode"], options?: {
+    spatialScene?: SpatialScene;
+    viewMode?: "2d" | "3d";
     initialViewpointId?: string;
     initialSelectionObjectId?: string;
     initialFilter?: ViewerFilter | null;
@@ -11,6 +13,7 @@ export declare function createEmbedPayload(scene: RenderScene, mode: WorldOrbitE
 }): WorldOrbitEmbedPayload;
 export declare function createWorldOrbitEmbedMarkup(payload: WorldOrbitEmbedPayload, options?: Pick<MountWorldOrbitEmbedsOptions, "theme" | "layers" | "subtitle" | "preset"> & {
     className?: string;
+    viewMode?: "2d" | "3d";
     initialViewpointId?: string;
     initialSelectionObjectId?: string;
     initialFilter?: ViewerFilter | null;
@@ -18,3 +21,4 @@ export declare function createWorldOrbitEmbedMarkup(payload: WorldOrbitEmbedPayl
     minimap?: boolean;
 }): string;
 export declare function mountWorldOrbitEmbeds(root?: ParentNode, options?: MountWorldOrbitEmbedsOptions): MountedWorldOrbitEmbeds;
+export declare function render3DUnavailableMarkup(message: string): string;