worldorbit 2.6.0 → 3.0.1

package/packages/viewer/dist/viewer.js

@@ -1,7 +1,8 @@
-import { loadWorldOrbitSource, renderDocumentToScene, rotatePoint, } from "@worldorbit/core";
+import { loadWorldOrbitSource, renderDocumentToScene, renderDocumentToSpatialScene, rotatePoint, } from "@worldorbit/core";
 import { computeVisibleObjectIds, createAtlasStateSnapshot, createViewerBookmark, deserializeViewerAtlasState, normalizeViewerFilter, sceneViewpointToLayerOptions, searchSceneObjects, serializeViewerAtlasState, viewpointToViewerFilter, } from "./atlas-state.js";
 import { renderViewerMinimap } from "./minimap.js";
 import { renderSceneToSvg } from "./render.js";
+import { createViewer3DRuntime, } from "./runtime-3d.js";
 import { buildViewerTooltipDetails, renderDefaultTooltipContent, } from "./tooltip.js";
 import { DEFAULT_VIEWER_STATE, composeViewerTransform, fitViewerState, focusViewerState, invertViewerPoint, panViewerState, rotateViewerState, zoomViewerStateAt, } from "./viewer-state.js";
 const DEFAULT_VIEWER_LIMITS = {
@@ -43,6 +44,7 @@ export function createInteractiveViewer(container, options) {
         padding: options.padding,
         preset: options.preset,
         projection: options.projection,
+        viewMode: options.viewMode ?? "2d",
         camera: options.camera ? { ...options.camera } : null,
         scaleModel: options.scaleModel ? { ...options.scaleModel } : undefined,
         theme: options.theme,
@@ -55,9 +57,14 @@ export function createInteractiveViewer(container, options) {
     const previousPosition = container.style.position;
     let currentInput = resolveInitialInput(options);
     let scene = renderSceneFromInput(currentInput, renderOptions);
+    let providedSpatialScene = options.spatialScene ?? null;
+    let spatialScene = renderOptions.viewMode === "3d"
+        ? renderSpatialSceneFromInput(currentInput, renderOptions, providedSpatialScene)
+        : null;
     let state = { ...DEFAULT_VIEWER_STATE };
     let svgElement = null;
     let cameraRoot = null;
+    let runtime3d = null;
     let minimapRoot = null;
     let tooltipRoot = null;
     let suppressClick = false;
@@ -72,6 +79,14 @@ export function createInteractiveViewer(container, options) {
     let activeTooltipObjectId = null;
     let activeTooltipDetails = null;
     let activeViewpointId = null;
+    let animationFrameId = null;
+    let lastAnimationTimestamp = null;
+    let animationState = {
+        playing: false,
+        speed: 1,
+        timeSeconds: 0,
+        frozenByEvent: spatialScene?.timeFrozen ?? false,
+    };
     if (previousTabIndex === null) {
         container.tabIndex = 0;
     }
@@ -81,12 +96,18 @@ export function createInteractiveViewer(container, options) {
     if (!container.style.position) {
         container.style.position = "relative";
     }
+    syncAnimationFrozenState();
     const handleWheel = (event) => {
         if (!behavior.pointer || destroyed) {
             return;
         }
         event.preventDefault();
         container.focus();
+        if (is3DView()) {
+            const factor = clampValue(Math.exp(-event.deltaY * 0.002), 0.6, 1.6);
+            api.zoomBy(factor);
+            return;
+        }
         const anchor = getWorldPointFromClient(event.clientX, event.clientY);
         const factor = clampValue(Math.exp(-event.deltaY * 0.002), 0.6, 1.6);
         updateState(zoomViewerStateAt(scene, state, factor, anchor, constraints));
@@ -99,7 +120,7 @@ export function createInteractiveViewer(container, options) {
         if ((isTouch && !behavior.touch) || (!isTouch && !behavior.pointer)) {
             return;
         }
-        if (!isTouch && event.button !== 0) {
+        if (!isTouch && event.button !== 0 && !is3DView()) {
             return;
         }
         container.focus();
@@ -127,6 +148,9 @@ export function createInteractiveViewer(container, options) {
         }
         const isTouch = event.pointerType === "touch";
         if (isTouch) {
+            if (is3DView()) {
+                return;
+            }
             if (!behavior.touch || !touchPoints.has(event.pointerId)) {
                 return;
             }
@@ -155,6 +179,29 @@ export function createInteractiveViewer(container, options) {
             }
             return;
         }
+        if (is3DView() && behavior.pointer && activePointerId === null) {
+            applyHover(runtime3d?.hitTest(event.clientX, event.clientY) ?? null);
+            return;
+        }
+        if (is3DView() && behavior.pointer && activePointerId === event.pointerId && lastPointerPoint) {
+            const nextPoint = getViewportPointFromClient(event.clientX, event.clientY);
+            const deltaX = nextPoint.x - lastPointerPoint.x;
+            const deltaY = nextPoint.y - lastPointerPoint.y;
+            dragDistance += Math.abs(deltaX) + Math.abs(deltaY);
+            lastPointerPoint = nextPoint;
+            if (dragDistance > 2) {
+                suppressClick = true;
+            }
+            if (event.shiftKey || event.buttons === 2) {
+                api.panBy(deltaX, deltaY);
+            }
+            else {
+                api.rotateBy(deltaX * 0.35);
+                api.panBy(0, deltaY * 0.35);
+            }
+            applyHover(runtime3d?.hitTest(event.clientX, event.clientY) ?? null);
+            return;
+        }
         if (!behavior.pointer || activePointerId !== event.pointerId || !lastPointerPoint) {
             return;
         }
@@ -189,7 +236,9 @@ export function createInteractiveViewer(container, options) {
             suppressClick = false;
             return;
         }
-        const objectId = getClosestObjectId(event.target);
+        const objectId = is3DView()
+            ? runtime3d?.hitTest(event.clientX, event.clientY) ?? null
+            : getClosestObjectId(event.target);
         applySelection(objectId);
         if (behavior.tooltipMode === "pinned") {
             pinnedTooltipObjectId = objectId;
@@ -197,6 +246,9 @@ export function createInteractiveViewer(container, options) {
         }
     };
     const handleMouseOver = (event) => {
+        if (is3DView()) {
+            return;
+        }
         const objectId = getClosestObjectId(event.target);
         applyHover(objectId);
     };
@@ -204,6 +256,9 @@ export function createInteractiveViewer(container, options) {
         applyHover(null);
     };
     const handleFocusIn = (event) => {
+        if (is3DView()) {
+            return;
+        }
         const objectId = getClosestObjectId(event.target);
         if (!objectId) {
             return;
@@ -217,7 +272,9 @@ export function createInteractiveViewer(container, options) {
         if (!behavior.keyboard || destroyed) {
             return;
         }
-        const objectId = getClosestObjectId(event.target);
+        const objectId = is3DView()
+            ? state.selectedObjectId
+            : getClosestObjectId(event.target);
         if ((event.key === "Enter" || event.key === " ") && objectId) {
             event.preventDefault();
             applySelection(objectId);
@@ -294,18 +351,36 @@ export function createInteractiveViewer(container, options) {
         setSource(source) {
             currentInput = { kind: "source", value: source };
             scene = renderSceneFromInput(currentInput, renderOptions);
+            providedSpatialScene = null;
+            spatialScene =
+                renderOptions.viewMode === "3d"
+                    ? renderSpatialSceneFromInput(currentInput, renderOptions, null)
+                    : null;
+            syncAnimationFrozenState();
             activeViewpointId = null;
             rerenderScene(true);
         },
         setDocument(document) {
             currentInput = { kind: "document", value: document };
             scene = renderSceneFromInput(currentInput, renderOptions);
+            providedSpatialScene = null;
+            spatialScene =
+                renderOptions.viewMode === "3d"
+                    ? renderSpatialSceneFromInput(currentInput, renderOptions, null)
+                    : null;
+            syncAnimationFrozenState();
             activeViewpointId = null;
             rerenderScene(true);
         },
         setScene(nextScene) {
             currentInput = { kind: "scene", value: nextScene };
             scene = nextScene;
+            providedSpatialScene = null;
+            spatialScene =
+                renderOptions.viewMode === "3d"
+                    ? renderSpatialSceneFromInput(currentInput, renderOptions, null)
+                    : null;
+            syncAnimationFrozenState();
             activeViewpointId = null;
             rerenderScene(true);
         },
@@ -315,6 +390,30 @@ export function createInteractiveViewer(container, options) {
         getRenderOptions() {
             return cloneRenderOptions(renderOptions);
         },
+        getViewMode() {
+            return renderOptions.viewMode ?? "2d";
+        },
+        setViewMode(mode) {
+            const previousRenderOptions = renderOptions;
+            const previousSpatialScene = spatialScene;
+            const nextRenderOptions = mergeRenderOptions(renderOptions, { viewMode: mode });
+            const nextSpatialScene = mode === "3d"
+                ? renderSpatialSceneFromInput(currentInput, nextRenderOptions, providedSpatialScene)
+                : null;
+            renderOptions = nextRenderOptions;
+            spatialScene = nextSpatialScene;
+            syncAnimationFrozenState();
+            try {
+                rerenderScene(false);
+            }
+            catch (error) {
+                renderOptions = previousRenderOptions;
+                spatialScene = previousSpatialScene;
+                syncAnimationFrozenState();
+                rerenderScene(false);
+                throw error;
+            }
+        },
         listViewpoints() {
             return scene.viewpoints.slice();
         },
@@ -368,6 +467,53 @@ export function createInteractiveViewer(container, options) {
         setActiveEvent(id) {
             api.setRenderOptions({ activeEventId: id });
         },
+        playAnimation() {
+            if (!is3DView()) {
+                animationState = {
+                    ...animationState,
+                    playing: false,
+                };
+                stopAnimationLoop();
+                return;
+            }
+            if (animationState.frozenByEvent) {
+                animationState = {
+                    ...animationState,
+                    playing: false,
+                };
+                return;
+            }
+            animationState = {
+                ...animationState,
+                playing: true,
+            };
+            ensureAnimationFrame();
+        },
+        pauseAnimation() {
+            animationState = {
+                ...animationState,
+                playing: false,
+            };
+            stopAnimationLoop();
+        },
+        resetAnimation() {
+            animationState = {
+                ...animationState,
+                playing: false,
+                timeSeconds: 0,
+            };
+            stopAnimationLoop();
+            syncRuntimePresentation();
+        },
+        setAnimationSpeed(multiplier) {
+            animationState = {
+                ...animationState,
+                speed: clampValue(multiplier, 0.1, 64),
+            };
+        },
+        getAnimationState() {
+            return { ...animationState };
+        },
         search(query, limit = 12) {
             return searchSceneObjects(scene, query, limit);
         },
@@ -427,11 +573,32 @@ export function createInteractiveViewer(container, options) {
         },
         setRenderOptions(options) {
             const sceneAffecting = hasSceneAffectingRenderOptions(options);
-            renderOptions = mergeRenderOptions(renderOptions, options);
+            const previousRenderOptions = renderOptions;
+            const previousScene = scene;
+            const previousSpatialScene = spatialScene;
+            const nextRenderOptions = mergeRenderOptions(renderOptions, options);
+            let nextScene = scene;
             if (currentInput.kind !== "scene" && sceneAffecting) {
-                scene = renderSceneFromInput(currentInput, renderOptions);
+                nextScene = renderSceneFromInput(currentInput, nextRenderOptions);
+            }
+            const nextSpatialScene = nextRenderOptions.viewMode === "3d"
+                ? renderSpatialSceneFromInput(currentInput, nextRenderOptions, providedSpatialScene)
+                : null;
+            renderOptions = nextRenderOptions;
+            scene = nextScene;
+            spatialScene = nextSpatialScene;
+            syncAnimationFrozenState();
+            try {
+                rerenderScene(sceneAffecting);
+            }
+            catch (error) {
+                renderOptions = previousRenderOptions;
+                scene = previousScene;
+                spatialScene = previousSpatialScene;
+                syncAnimationFrozenState();
+                rerenderScene(sceneAffecting);
+                throw error;
             }
-            rerenderScene(sceneAffecting);
         },
         getState() {
             return { ...state };
@@ -449,11 +616,15 @@ export function createInteractiveViewer(container, options) {
             updateState(rotateViewerState(state, deg));
         },
         fitToSystem() {
-            updateState(fitViewerState(scene, state, constraints));
+            updateState(is3DView()
+                ? { ...DEFAULT_VIEWER_STATE, selectedObjectId: state.selectedObjectId }
+                : fitViewerState(scene, state, constraints));
         },
         focusObject(id) {
             activeViewpointId = null;
-            updateState(focusViewerState(scene, state, id, constraints));
+            updateState(is3DView()
+                ? create3DFocusState(id)
+                : focusViewerState(scene, state, id, constraints));
             applySelection(id);
             if (behavior.tooltipMode === "pinned") {
                 pinnedTooltipObjectId = getObjectById(id)?.objectId ?? null;
@@ -465,7 +636,9 @@ export function createInteractiveViewer(container, options) {
             updateTooltip();
         },
         resetView() {
-            const resetState = fitViewerState(scene, { ...DEFAULT_VIEWER_STATE }, constraints);
+            const resetState = is3DView()
+                ? { ...DEFAULT_VIEWER_STATE }
+                : fitViewerState(scene, { ...DEFAULT_VIEWER_STATE }, constraints);
             activeViewpointId = null;
             updateState(resetState);
             applySelection(null);
@@ -495,6 +668,9 @@ export function createInteractiveViewer(container, options) {
             container.removeEventListener("focusin", handleFocusIn);
             container.removeEventListener("focusout", handleFocusOut);
             container.removeEventListener("keydown", handleKeyDown);
+            stopAnimationLoop();
+            runtime3d?.destroy();
+            runtime3d = null;
             tooltipRoot?.remove();
             tooltipRoot = null;
             minimapRoot?.remove();
@@ -522,15 +698,26 @@ export function createInteractiveViewer(container, options) {
     }
     return api;
     function rerenderScene(resetView) {
-        container.innerHTML = renderSceneToSvg(scene, {
-            ...renderOptions,
-            filter: renderOptions.filter ?? null,
-            selectedObjectId: state.selectedObjectId,
-        });
-        svgElement = container.querySelector('[data-worldorbit-svg="true"]');
-        cameraRoot = container.querySelector("#worldorbit-camera-root");
+        runtime3d?.destroy();
+        runtime3d = null;
+        container.innerHTML = "";
+        svgElement = null;
+        cameraRoot = null;
         minimapRoot = null;
         tooltipRoot = null;
+        if (is3DView()) {
+            spatialScene = spatialScene ?? renderSpatialSceneFromInput(currentInput, renderOptions, providedSpatialScene);
+            runtime3d = createViewer3DRuntime(container);
+        }
+        else {
+            container.innerHTML = renderSceneToSvg(scene, {
+                ...renderOptions,
+                filter: renderOptions.filter ?? null,
+                selectedObjectId: state.selectedObjectId,
+            });
+            svgElement = container.querySelector('[data-worldorbit-svg="true"]');
+            cameraRoot = container.querySelector("#worldorbit-camera-root");
+        }
         if (behavior.minimap) {
             minimapRoot = document.createElement("div");
             minimapRoot.dataset.worldorbitMinimapRoot = "true";
@@ -544,11 +731,13 @@ export function createInteractiveViewer(container, options) {
             tooltipRoot.addEventListener("click", handleTooltipClick);
             container.append(tooltipRoot);
         }
-        if (!svgElement || !cameraRoot) {
+        if (!is3DView() && (!svgElement || !cameraRoot)) {
             throw new Error("Interactive viewer could not locate the rendered SVG camera root.");
         }
         state = resetView
-            ? fitViewerState(scene, { ...DEFAULT_VIEWER_STATE }, constraints)
+            ? is3DView()
+                ? { ...DEFAULT_VIEWER_STATE }
+                : fitViewerState(scene, { ...DEFAULT_VIEWER_STATE }, constraints)
             : sanitizeState(state);
         applySelection(state.selectedObjectId &&
             getObjectById(state.selectedObjectId)
@@ -562,7 +751,7 @@ export function createInteractiveViewer(container, options) {
             pinnedTooltipObjectId && getObjectById(pinnedTooltipObjectId)
                 ? pinnedTooltipObjectId
                 : null;
-        updateCameraTransform();
+        syncRuntimePresentation();
         notifyFilterChange();
         notifyViewpointChange();
         options.onViewChange?.({ ...state });
@@ -570,7 +759,7 @@ export function createInteractiveViewer(container, options) {
     }
     function updateState(nextState) {
         state = sanitizeState(nextState);
-        updateCameraTransform();
+        syncRuntimePresentation();
         options.onViewChange?.({ ...state });
         emitAtlasStateChange();
     }
@@ -586,6 +775,10 @@ export function createInteractiveViewer(container, options) {
         };
     }
     function updateCameraTransform() {
+        if (is3DView()) {
+            sync3DView();
+            return;
+        }
         if (!cameraRoot) {
             return;
         }
@@ -594,7 +787,7 @@ export function createInteractiveViewer(container, options) {
         updateTooltip();
     }
     function applySelection(objectId, emitCallback = true) {
-        if (state.selectedObjectId) {
+        if (!is3DView() && state.selectedObjectId) {
             container
                 .querySelector(`[data-object-id="${cssEscape(state.selectedObjectId)}"]`)
                 ?.classList.remove("wo-object-selected");
@@ -605,7 +798,7 @@ export function createInteractiveViewer(container, options) {
                 ? objectId
                 : null,
         };
-        if (state.selectedObjectId) {
+        if (!is3DView() && state.selectedObjectId) {
             container
                 .querySelector(`[data-object-id="${cssEscape(state.selectedObjectId)}"]`)
                 ?.classList.add("wo-object-selected");
@@ -678,6 +871,10 @@ export function createInteractiveViewer(container, options) {
         };
     }
     function syncAtlasHighlights() {
+        if (is3DView()) {
+            sync3DView();
+            return;
+        }
         for (const element of container.querySelectorAll(".wo-chain-selected, .wo-chain-hover, .wo-ancestor-selected, .wo-ancestor-hover, .wo-orbit-related-selected, .wo-orbit-related-hover")) {
             element.classList.remove("wo-chain-selected", "wo-chain-hover", "wo-ancestor-selected", "wo-ancestor-hover", "wo-orbit-related-selected", "wo-orbit-related-hover");
         }
@@ -719,6 +916,19 @@ export function createInteractiveViewer(container, options) {
         }
     }
     function getViewportPointFromClient(clientX, clientY) {
+        if (is3DView()) {
+            const rect = container.getBoundingClientRect();
+            if (!rect.width || !rect.height) {
+                return {
+                    x: scene.width / 2,
+                    y: scene.height / 2,
+                };
+            }
+            return {
+                x: clientX - rect.left,
+                y: clientY - rect.top,
+            };
+        }
         if (!svgElement) {
             return {
                 x: scene.width / 2,
@@ -764,6 +974,19 @@ export function createInteractiveViewer(container, options) {
         const scale = viewpoint.scale !== null && viewpoint.scale !== undefined
             ? clampValue(viewpoint.scale, constraints.minScale, constraints.maxScale)
             : null;
+        if (is3DView()) {
+            const focusId = viewpoint.objectId ?? viewpoint.selectedObjectId ?? null;
+            const target = focusId
+                ? spatialScene?.focusTargets.find((entry) => entry.objectId === focusId)
+                : null;
+            return {
+                scale: scale ?? 1.6,
+                rotationDeg,
+                translateX: target ? -target.center.x : 0,
+                translateY: target ? -target.center.z : 0,
+                selectedObjectId: viewpoint.selectedObjectId ?? viewpoint.objectId ?? null,
+            };
+        }
         const targetObject = viewpoint.objectId &&
             scene.objects.find((object) => object.objectId === viewpoint.objectId && !object.hidden);
         if (targetObject) {
@@ -908,32 +1131,24 @@ export function createInteractiveViewer(container, options) {
         }
     }
     function positionTooltip(element, renderObject) {
-        if (!svgElement) {
+        const point = is3DView()
+            ? runtime3d?.projectObjectToContainer(renderObject.objectId) ?? null
+            : project2DTooltipPoint(renderObject);
+        if (!point) {
             return;
         }
-        const anchor = {
-            x: renderObject.anchorX ?? renderObject.x,
-            y: renderObject.anchorY ??
-                renderObject.y - Math.max(renderObject.visualRadius, renderObject.radius),
-        };
-        const viewportPoint = projectWorldPoint(anchor);
-        const svgRect = svgElement.getBoundingClientRect();
-        const containerRect = container.getBoundingClientRect();
-        const pointX = svgRect.left -
-            containerRect.left +
-            (viewportPoint.x / Math.max(scene.width, 1)) * svgRect.width;
-        const pointY = svgRect.top -
-            containerRect.top +
-            (viewportPoint.y / Math.max(scene.height, 1)) * svgRect.height;
         const maxLeft = Math.max(container.clientWidth - element.offsetWidth - 12, 12);
         const maxTop = Math.max(container.clientHeight - element.offsetHeight - 12, 12);
-        const preferAbove = pointY > container.clientHeight * 0.48;
-        const nextLeft = clampValue(pointX + 18, 12, maxLeft);
-        const nextTop = clampValue(preferAbove ? pointY - element.offsetHeight - 18 : pointY + 18, 12, maxTop);
+        const preferAbove = point.y > container.clientHeight * 0.48;
+        const nextLeft = clampValue(point.x + 18, 12, maxLeft);
+        const nextTop = clampValue(preferAbove ? point.y - element.offsetHeight - 18 : point.y + 18, 12, maxTop);
         element.style.left = `${nextLeft}px`;
         element.style.top = `${nextTop}px`;
     }
     function projectWorldPoint(point) {
+        if (is3DView()) {
+            return point;
+        }
         const center = {
             x: scene.width / 2,
             y: scene.height / 2,
@@ -944,6 +1159,27 @@ export function createInteractiveViewer(container, options) {
             y: center.y + (rotated.y - center.y) * state.scale + state.translateY,
         };
     }
+    function project2DTooltipPoint(renderObject) {
+        if (!svgElement) {
+            return null;
+        }
+        const anchor = {
+            x: renderObject.anchorX ?? renderObject.x,
+            y: renderObject.anchorY ??
+                renderObject.y - Math.max(renderObject.visualRadius, renderObject.radius),
+        };
+        const viewportPoint = projectWorldPoint(anchor);
+        const svgRect = svgElement.getBoundingClientRect();
+        const containerRect = container.getBoundingClientRect();
+        return {
+            x: svgRect.left -
+                containerRect.left +
+                (viewportPoint.x / Math.max(scene.width, 1)) * svgRect.width,
+            y: svgRect.top -
+                containerRect.top +
+                (viewportPoint.y / Math.max(scene.height, 1)) * svgRect.height,
+        };
+    }
     function handleTooltipClick(event) {
         const target = event.target?.closest("[data-tooltip-action]");
         if (!target) {
@@ -971,6 +1207,92 @@ export function createInteractiveViewer(container, options) {
             options.onTooltipChange?.(details);
         }
     }
+    function is3DView() {
+        return renderOptions.viewMode === "3d";
+    }
+    function syncAnimationFrozenState() {
+        animationState = {
+            ...animationState,
+            frozenByEvent: spatialScene?.timeFrozen ?? false,
+        };
+        if (animationState.frozenByEvent) {
+            animationState = {
+                ...animationState,
+                playing: false,
+            };
+            stopAnimationLoop();
+        }
+    }
+    function ensureAnimationFrame() {
+        if (animationFrameId !== null || !animationState.playing || destroyed) {
+            return;
+        }
+        animationFrameId = window.requestAnimationFrame(renderAnimationFrame);
+    }
+    function stopAnimationLoop() {
+        if (animationFrameId !== null) {
+            window.cancelAnimationFrame(animationFrameId);
+            animationFrameId = null;
+        }
+        lastAnimationTimestamp = null;
+    }
+    function renderAnimationFrame(timestamp) {
+        animationFrameId = null;
+        if (!animationState.playing || destroyed) {
+            lastAnimationTimestamp = null;
+            return;
+        }
+        const previousTimestamp = lastAnimationTimestamp ?? timestamp;
+        const deltaSeconds = Math.max((timestamp - previousTimestamp) / 1_000, 0);
+        lastAnimationTimestamp = timestamp;
+        animationState = {
+            ...animationState,
+            timeSeconds: animationState.timeSeconds + deltaSeconds * animationState.speed,
+        };
+        sync3DView();
+        ensureAnimationFrame();
+    }
+    function syncRuntimePresentation() {
+        updateCameraTransform();
+        if (is3DView() && animationState.playing) {
+            ensureAnimationFrame();
+        }
+        else if (!animationState.playing || !is3DView()) {
+            stopAnimationLoop();
+        }
+    }
+    function sync3DView() {
+        if (!is3DView() || !runtime3d || !spatialScene) {
+            return;
+        }
+        runtime3d.update({
+            spatialScene,
+            renderOptions,
+            visibleObjectIds: getVisibleObjectIds(),
+            selectedObjectId: state.selectedObjectId,
+            hoveredObjectId,
+            state,
+            timeSeconds: animationState.timeSeconds,
+        });
+        updateMinimap();
+        updateTooltip();
+    }
+    function create3DFocusState(objectId) {
+        const target = spatialScene?.focusTargets.find((entry) => entry.objectId === objectId);
+        if (!target) {
+            return {
+                ...DEFAULT_VIEWER_STATE,
+                selectedObjectId: objectId,
+            };
+        }
+        return {
+            scale: 1.8,
+            rotationDeg: state.rotationDeg,
+            translateX: -target.center.x,
+            translateY: -target.center.z,
+            selectedObjectId: objectId,
+        };
+    }
 }
 function resolveInitialInput(options) {
     if (options.scene) {
@@ -996,6 +1318,21 @@ function renderSceneFromInput(input, renderOptions) {
         }
     }
 }
+function renderSpatialSceneFromInput(input, renderOptions, providedSpatialScene) {
+    if (providedSpatialScene) {
+        return providedSpatialScene;
+    }
+    switch (input.kind) {
+        case "scene":
+            return fallbackSpatialSceneFromRenderScene(input.value);
+        case "document":
+            return renderDocumentToSpatialScene(input.value, renderOptions);
+        case "source": {
+            const loaded = loadWorldOrbitSource(input.value);
+            return renderDocumentToSpatialScene(loaded.document, resolveSourceRenderOptions(loaded, renderOptions));
+        }
+    }
+}
 function cloneRenderOptions(renderOptions) {
     return {
         ...renderOptions,
@@ -1007,6 +1344,7 @@ function cloneRenderOptions(renderOptions) {
             ? { ...renderOptions.theme }
             : renderOptions.theme,
         activeEventId: renderOptions.activeEventId ?? null,
+        viewMode: renderOptions.viewMode ?? "2d",
     };
 }
 function mergeRenderOptions(current, next) {
@@ -1044,6 +1382,7 @@ function mergeRenderOptions(current, next) {
         theme: next.theme && typeof next.theme === "object"
             ? { ...next.theme }
             : next.theme ?? current.theme,
+        viewMode: next.viewMode ?? current.viewMode ?? "2d",
     };
 }
 function hasSceneAffectingRenderOptions(options) {
@@ -1066,6 +1405,99 @@ function resolveSourceRenderOptions(loaded, renderOptions) {
         preset: atlasDocument.system.defaults.preset,
     };
 }
+function fallbackSpatialSceneFromRenderScene(scene) {
+    return {
+        width: scene.width,
+        height: scene.height,
+        padding: scene.padding,
+        renderPreset: scene.renderPreset,
+        projection: scene.projection,
+        camera: scene.camera,
+        scaleModel: {
+            orbitDistanceMultiplier: 1,
+            bodyRadiusMultiplier: 1,
+            markerSizeMultiplier: 1,
+            ringThicknessMultiplier: 1,
+            focusPadding: 12,
+            minBodyRadius: 4,
+            maxBodyRadius: 40,
+        },
+        title: scene.title,
+        subtitle: scene.subtitle,
+        systemId: scene.systemId,
+        viewMode: "3d",
+        layoutPreset: scene.layoutPreset,
+        metadata: {
+            ...scene.metadata,
+            "viewer.mode": "3d-fallback",
+        },
+        contentBounds: {
+            minX: scene.contentBounds.minX - scene.contentBounds.centerX,
+            minY: -40,
+            minZ: scene.contentBounds.minY - scene.contentBounds.centerY,
+            maxX: scene.contentBounds.maxX - scene.contentBounds.centerX,
+            maxY: 40,
+            maxZ: scene.contentBounds.maxY - scene.contentBounds.centerY,
+            width: scene.contentBounds.width,
+            height: 80,
+            depth: scene.contentBounds.height,
+            center: { x: 0, y: 0, z: 0 },
+        },
+        semanticGroups: scene.semanticGroups,
+        viewpoints: scene.viewpoints,
+        activeEventId: scene.activeEventId,
+        timeFrozen: scene.activeEventId !== null,
+        objects: scene.objects.map((object) => ({
+            objectId: object.objectId,
+            object: object.object,
+            parentId: object.parentId,
+            ancestorIds: object.ancestorIds.slice(),
+            childIds: object.childIds.slice(),
+            groupId: object.groupId,
+            semanticGroupIds: object.semanticGroupIds.slice(),
+            position: {
+                x: object.x - scene.contentBounds.centerX,
+                y: 0,
+                z: object.y - scene.contentBounds.centerY,
+            },
+            radius: object.radius,
+            visualRadius: object.visualRadius,
+            label: object.label,
+            secondaryLabel: object.secondaryLabel,
+            fillColor: object.fillColor,
+            imageHref: object.imageHref,
+            hidden: object.hidden,
+            motion: null,
+        })),
+        orbits: scene.orbitVisuals.map((orbit) => ({
+            objectId: orbit.objectId,
+            object: orbit.object,
+            parentId: orbit.parentId,
+            groupId: orbit.groupId,
+            semanticGroupIds: orbit.semanticGroupIds.slice(),
+            center: { x: 0, y: 0, z: 0 },
+            kind: orbit.kind,
+            radius: orbit.radius,
+            semiMajor: orbit.radius ?? orbit.rx ?? 0,
+            semiMinor: orbit.radius ?? orbit.ry ?? 0,
+            rotationDeg: orbit.rotationDeg,
+            inclinationDeg: 0,
+            band: orbit.band,
+            bandThickness: orbit.bandThickness,
+            hidden: orbit.hidden,
+            motion: null,
+        })),
+        focusTargets: scene.objects.map((object) => ({
+            objectId: object.objectId,
+            center: {
+                x: object.x - scene.contentBounds.centerX,
+                y: 0,
+                z: object.y - scene.contentBounds.centerY,
+            },
+            radius: object.visualRadius + 12,
+        })),
+    };
+}
 function createTouchGestureState(scene, state, touchPoints) {
     const { center, distance } = getTouchCenterAndDistance(touchPoints);
     return {
@@ -1132,6 +1564,34 @@ function installViewerTooltipStyles() {
     const style = document.createElement("style");
     style.id = TOOLTIP_STYLE_ID;
     style.textContent = `
+    .wo-viewer-3d-root {
+      position: relative;
+      min-height: 320px;
+      width: 100%;
+      border-radius: 22px;
+      overflow: hidden;
+      background:
+        radial-gradient(circle at top left, rgba(240, 180, 100, 0.08), transparent 24%),
+        linear-gradient(180deg, rgba(255,255,255,0.02), transparent);
+    }
+    .wo-viewer-3d-loading {
+      display: grid;
+      place-items: center;
+      min-height: 320px;
+      padding: 24px;
+      color: rgba(237, 246, 255, 0.76);
+      font: 600 14px/1.5 "Segoe UI Variable", "Segoe UI", sans-serif;
+      text-align: center;
+    }
+    .wo-viewer-3d-loading.is-error {
+      color: #ffb2b2;
+    }
+    .wo-viewer-3d-canvas {
+      display: block;
+      width: 100%;
+      height: 100%;
+      min-height: 320px;
+    }
     .wo-viewer-tooltip-root {
       position: absolute;
       z-index: 12;