@volter/editor-threejs 0.5.213 → 0.5.214

package/dist-node/serving.mjs

@@ -5,17 +5,7 @@ import ts from "typescript";
 // serving/animation-live-module.ts
 var ANIMATION_LIVE_MODULE_ID = "virtual:volter-three-animation-live";
 var animationLiveModuleSource = `
-const live = (globalThis[Symbol.for('volter.three.animation.live')] ??= {
-  mixers: new Map(),
-  listeners: new Set(),
-  version: 0,
-});
-function notify() {
-  live.version++;
-  for (const listener of live.listeners) {
-    try { listener(); } catch (error) { console.error(error); }
-  }
-}
+const live = (globalThis[Symbol.for('volter.three.animation.live')] ??= { mixers: new Map() });
 export function __volterMixer(mixer, key) {
   if (!mixer || typeof mixer.clipAction !== 'function') return mixer;
   if (mixer.__volterMixerKey) return mixer;
@@ -28,10 +18,8 @@ export function __volterMixer(mixer, key) {
     if (action) {
       const played = action.getClip();
       const target = action.getRoot();
-      let changed = false;
-      if (played && !entry.clips.has(played.name)) { entry.clips.set(played.name, played); changed = true; }
-      if (target && !entry.roots.has(target)) { entry.roots.add(target); changed = true; }
-      if (changed) notify();
+      if (played && !entry.clips.has(played.name)) entry.clips.set(played.name, played);
+      if (target) entry.roots.add(target);
     }
     return action;
   };
@@ -40,10 +28,8 @@ export function __volterMixer(mixer, key) {
     const result = uncacheRoot.call(this, root);
     entry.roots.delete(root);
     if (root === this.getRoot()) live.mixers.delete(this);
-    notify();
     return result;
   };
-  notify();
   return mixer;
 }
 /** drei's \`useAnimations\` result: its mixer, and the clips it was handed. */
@@ -52,11 +38,9 @@ export function __volterAnimations(result, key) {
   __volterMixer(result.mixer, key);
   const entry = live.mixers.get(result.mixer);
   if (entry && Array.isArray(result.clips)) {
-    let changed = false;
     for (const clip of result.clips) {
-      if (clip && clip.name && !entry.clips.has(clip.name)) { entry.clips.set(clip.name, clip); changed = true; }
+      if (clip && clip.name && !entry.clips.has(clip.name)) entry.clips.set(clip.name, clip);
     }
-    if (changed) notify();
   }
   return result;
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/editor-threejs",
   "publisher": "volter",
   "author": "Volter AI, Inc.",
-  "version": "0.5.213",
+  "version": "0.5.214",
   "engines": {
     "vscode": "*"
   },
@@ -83,7 +83,6 @@
     "./kit/components/stage-transform-chrome": "./src/kit/components/stage-transform-chrome.ts",
     "./kit/components/stage-transform-tools": "./src/kit/components/stage-transform-tools.tsx",
     "./kit/components/standard-viewport-dressing": "./src/kit/components/standard-viewport-dressing.ts",
-    "./kit/components/world-root-binding": "./src/kit/components/world-root-binding.ts",
     "./kit/constraint-helper": "./src/kit/constraint-helper.ts",
     "./kit/editor-shell-store": "./src/kit/editor-shell-store.ts",
     "./kit/editor-viewport": "./src/kit/editor-viewport.ts",
@@ -95,7 +94,6 @@
     "./kit/model-thumbnail": "./src/kit/model-thumbnail.ts",
     "./kit/projection/three": "./src/kit/projection/three.ts",
     "./kit/reflection-probe-helper": "./src/kit/reflection-probe-helper.ts",
-    "./kit/scene-document-viewport": "./src/kit/scene-document-viewport.ts",
     "./kit/scene-framing": "./src/kit/scene-framing.ts",
     "./kit/scene-view-fog": "./src/kit/scene-view-fog.ts",
     "./kit/spatial-handle-visuals": "./src/kit/spatial-handle-visuals.ts",
@@ -416,11 +414,11 @@
     }
   },
   "dependencies": {
-    "@volter/project": "0.5.213",
+    "@volter/project": "0.5.214",
     "@sparkjsdev/spark": "^2.1.0",
     "three.quarks": "^0.16.0",
     "typescript": "5.9.3",
-    "@volter/sdk": "0.5.213",
+    "@volter/sdk": "0.5.214",
     "postprocessing": "6.39.5",
     "quarks.core": "0.16.0",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"

package/serving/animation-live-module.ts

@@ -12,17 +12,7 @@
 export const ANIMATION_LIVE_MODULE_ID = 'virtual:volter-three-animation-live';
 
 export const animationLiveModuleSource = `
-const live = (globalThis[Symbol.for('volter.three.animation.live')] ??= {
-  mixers: new Map(),
-  listeners: new Set(),
-  version: 0,
-});
-function notify() {
-  live.version++;
-  for (const listener of live.listeners) {
-    try { listener(); } catch (error) { console.error(error); }
-  }
-}
+const live = (globalThis[Symbol.for('volter.three.animation.live')] ??= { mixers: new Map() });
 export function __volterMixer(mixer, key) {
   if (!mixer || typeof mixer.clipAction !== 'function') return mixer;
   if (mixer.__volterMixerKey) return mixer;
@@ -35,10 +25,8 @@ export function __volterMixer(mixer, key) {
     if (action) {
       const played = action.getClip();
       const target = action.getRoot();
-      let changed = false;
-      if (played && !entry.clips.has(played.name)) { entry.clips.set(played.name, played); changed = true; }
-      if (target && !entry.roots.has(target)) { entry.roots.add(target); changed = true; }
-      if (changed) notify();
+      if (played && !entry.clips.has(played.name)) entry.clips.set(played.name, played);
+      if (target) entry.roots.add(target);
     }
     return action;
   };
@@ -47,10 +35,8 @@ export function __volterMixer(mixer, key) {
     const result = uncacheRoot.call(this, root);
     entry.roots.delete(root);
     if (root === this.getRoot()) live.mixers.delete(this);
-    notify();
     return result;
   };
-  notify();
   return mixer;
 }
 /** drei's \`useAnimations\` result: its mixer, and the clips it was handed. */
@@ -59,11 +45,9 @@ export function __volterAnimations(result, key) {
   __volterMixer(result.mixer, key);
   const entry = live.mixers.get(result.mixer);
   if (entry && Array.isArray(result.clips)) {
-    let changed = false;
     for (const clip of result.clips) {
-      if (clip && clip.name && !entry.clips.has(clip.name)) { entry.clips.set(clip.name, clip); changed = true; }
+      if (clip && clip.name && !entry.clips.has(clip.name)) entry.clips.set(clip.name, clip);
     }
-    if (changed) notify();
   }
   return result;
 }

package/src/animation/live-mixers.ts

@@ -19,15 +19,13 @@ export interface LiveMixer {
 
 interface Registry {
   readonly mixers: Map<unknown, LiveMixer>;
-  readonly listeners: Set<() => void>;
-  version: number;
 }
 
 const REGISTRY = Symbol.for('volter.three.animation.live');
 
 function registry(): Registry {
   const holder = globalThis as unknown as Record<symbol, Registry | undefined>;
-  return (holder[REGISTRY] ??= { mixers: new Map(), listeners: new Set(), version: 0 });
+  return (holder[REGISTRY] ??= { mixers: new Map() });
 }
 
 /** The live mixer that animates `object`, or null when the game animates it with none. */
@@ -43,9 +41,3 @@ export function liveMixerFor(object: THREE.Object3D): LiveMixer | null {
 export function liveMixers(): LiveMixer[] {
   return [...registry().mixers.values()];
 }
-
-export function subscribeLiveMixers(listener: () => void): () => void {
-  const listeners = registry().listeners;
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}

package/src/kit/animation/three-clips-subject.ts

@@ -5,7 +5,7 @@
  * reaches clips loaded through useGLTF and useAnimations. Subjects seek through
  * AnimationMixer.setTime; the transport owns playback position.
  */
-import { liveMixerFor, subscribeLiveMixers } from '@volter/editor-threejs/animation/live-mixers';
+import { liveMixerFor } from '@volter/editor-threejs/animation/live-mixers';
 import * as THREE from 'three';
 import type { StageTransport } from '@volter/sdk/animation/stage-transport';
 
@@ -104,62 +104,22 @@ function attachInspected(object: THREE.Object3D, transport: StageTransport): (()
   return detach;
 }
 
-/**
- * One scan of a mounted root, and the handle that keeps it current.
- *
- * `refresh()` DIFFS by object uuid rather than re-attaching: a rescan of an
- * unchanged tree must not detach and re-attach every subject, because that
- * would reset which clip each one is showing under a person's hands. The
- * caller decides when to rescan (the stage host throttles it and skips it
- * while the world is driving time).
- */
+/** One scan of a mounted root, and the handle that detaches what it attached. */
 export interface ClipSubjectScan {
-  refresh(): void;
   dispose(): void;
 }
 
-export function scanClipSubjects(
-  root: THREE.Object3D | (() => THREE.Object3D | null),
-  transport: StageTransport,
-  options: {
-    /** Rescan when the game registers or drops a mixer. */
-    readonly rescanOnLiveMixers?: boolean;
-  } = {},
-): ClipSubjectScan {
+export function scanClipSubjects(root: THREE.Object3D, transport: StageTransport): ClipSubjectScan {
   const attached = new Map<string, () => void>();
-
-  const refresh = (): void => {
-    const seen = new Set<string>();
-    // A getter for a stage whose rendered scene is not fixed at construction:
-    // a world stage draws the session store's scene once the world mounts.
-    const current = typeof root === 'function' ? root() : root;
-    current?.traverse((object) => {
-      if (attached.has(object.uuid)) {
-        seen.add(object.uuid);
-        return;
-      }
-      // The inspection wins when an object has both: it means a world binding
-      // is already driving that skeleton, and a second mixer over it would
-      // give one object two writers.
-      const detach = attachInspected(object, transport) ?? attachOwnClips(object, transport);
-      if (!detach) return;
-      attached.set(object.uuid, detach);
-      seen.add(object.uuid);
-    });
-    for (const [uuid, detach] of [...attached]) {
-      if (seen.has(uuid)) continue;
-      detach();
-      attached.delete(uuid);
-    }
-  };
-
-  refresh();
-  const stopMixers = options.rescanOnLiveMixers ? subscribeLiveMixers(refresh) : () => {};
-
+  root.traverse((object) => {
+    // The project's own mixer wins when an object has both: the project's
+    // code is already driving that skeleton, and a second mixer over it would
+    // give one object two writers.
+    const detach = attachInspected(object, transport) ?? attachOwnClips(object, transport);
+    if (detach) attached.set(object.uuid, detach);
+  });
   return {
-    refresh,
     dispose: () => {
-      stopMixers();
       for (const detach of attached.values()) detach();
       attached.clear();
     },

package/src/kit/authoring/component-instance-root.ts

@@ -105,9 +105,8 @@ function forwardedCallsiteOid(object: THREE.Object3D | null | undefined): string
  * same oid twice, and both mint the same shape of id: the first one seen in
  * depth-first order keeps the bare address, later ones get `#1`, `#2`, ….
  *
- * The suffix is spelled HERE and nowhere else: the minting walks
- * (`projection/three.ts`, `R3fSourceAuthoringAdapter.indexGraph`), the authority
- * check and the presence report all use this one.
+ * The suffix is spelled HERE and nowhere else; the minting walk
+ * (`projection/three.ts`) uses this one.
  */
 export function occurrenceId(baseId: string, occurrence: number): string {
   return occurrence === 0 ? baseId : `${baseId}#${occurrence}`;

package/src/kit/components/Object3DDocumentToolbar.tsx

@@ -112,8 +112,7 @@ export function Object3DDocumentToolbar({
     session?.getSnapshot ?? noSessionVersion,
   );
   // THIS STAGE's own store and its own helpers: the shared panels read
-  // whichever store the FOCUSED document's stage runs on , and a toolbar is a control over ITS document, never over the
-  // world root's.
+  // whichever store the FOCUSED document's stage runs on, and a toolbar is a control over ITS document.
   useSyncExternalStore(subscribeStageStores, stageStoresVersion, stageStoresVersion);
   const stage = stageStore(documentId);
   useSyncExternalStore(

package/src/kit/components/StageHost.tsx

@@ -57,8 +57,7 @@ import {
   studioStageApplies,
 } from '@volter/sdk/stage-context';
 import { registerStageStore } from '@volter/sdk/stage-store-registry';
-import { announceDocumentStage, registerDocumentViewport } from '@volter/sdk/document-viewports';
-import { sceneDocumentViewport } from '../scene-document-viewport';
+import { announceDocumentStage } from '@volter/sdk/document-viewports';
 import { threeStageTransformChrome } from './stage-transform-chrome';
 import { RetainedDocumentStates } from '../retained-document-states';
 import { perspectiveDistanceToFitBox } from '../three-viewport/camera-fit';
@@ -87,7 +86,6 @@ import {
 } from '@volter/sdk/workspace-document-registry';
 import { AssetEditorShell } from '@volter/sdk/components/AssetEditorShell';
 import { StageOverlays } from './StageOverlays';
-import type { WorldRootStageBinding } from './world-root-binding';
 import { TransportStrip } from '../transport-strip';
 
 // The stage's own keyboard actions, behind the same lazy boundary as the
@@ -113,10 +111,12 @@ import {
   mergeLayers,
   type PresentationLayer,
   reportViewDraw,
+  setViewFraming,
   setViewPresentation,
   stageLightsPerMode,
   startingPresentation,
   subscribeViewportPresentation,
+  viewFraming,
   viewPresentation,
   viewPresentationSnapshot,
   type ViewportDrawMode,
@@ -166,23 +166,6 @@ export type SourceDocumentAuthoringFactory = (
   context: SourceDocumentAuthoringContext,
 ) => ToolObject3DDocumentAuthoring;
 
-/** WHAT THE STAGE IS SHOWING. `build` is one Object3D the caller's `build()`
- * constructs, in isolation; its kind supplies authoring behavior and chrome,
- * and this host owns renderer lifetime, capture and disposal. `world-root` is
- * the project's world: the contributing package's binding mounts the
- * manifest's roots and presents the live roots Play adopts, and this host
- * gives it the same surface place, frame session, per-stage door and
- * overlays. A modeling host never loads a world binding. */
-export type Object3DDocumentContent =
-  | { readonly kind: 'build' }
-  | { readonly kind: 'world-root'; load(): Promise<WorldRootStageBinding> };
-
-/** Throttle for the world-root stage's clip rescan. A traverse per store
- *  notification would run on every selection change; 500 ms is fast enough
- *  that a streamed-in character becomes scrubbable while a person is still
- *  looking at it. */
-const CLIP_RESCAN_INTERVAL_MS = 500;
-
 /** Module-level so its identity is stable across renders, which
  *  `useSyncExternalStore` requires; the theme root is global, so no stage's
  *  own element narrows it. */
@@ -190,15 +173,7 @@ function subscribeThemeViewportGroup(onChange: () => void): () => void {
   return subscribeNativeSelectionTheme(null, onChange);
 }
 
-export interface Object3DDocumentViewportProps
-  extends Omit<ToolObject3DAuthoringProps, 'build' | 'sourcePath'> {
-  /** Required by `build` content (and by the SDK door, where both stay
-   *  mandatory); a `world-root` stage constructs nothing of its own and has no
-   *  single source file — its content is the manifest's roots. */
-  readonly build?: ToolObject3DAuthoringProps['build'];
-  readonly sourcePath?: string;
-  /** See {@link Object3DDocumentContent}. Default `{ kind: 'build' }`. */
-  readonly content?: Object3DDocumentContent;
+export interface Object3DDocumentViewportProps extends ToolObject3DAuthoringProps {
   /** See `@volter/sdk`'s `ToolObject3DAuthoringProps.audit`. */
   readonly audit?: boolean;
   /** Reuse the canonical Asset Lab viewport with NONE of the document chrome —
@@ -425,7 +400,7 @@ class Object3DDocumentHost {
 
   constructor(
     readonly lane: 'own' | 'inspector-preview',
-    readonly surface: ReturnType<typeof mountViewportSurface> | ReturnType<WorldRootStageBinding['mountWorldRootSurface']>,
+    readonly surface: ReturnType<typeof mountViewportSurface>,
     store: EditorShellStore,
   ) {
     this.store = store;
@@ -511,7 +486,6 @@ export function Object3DDocumentViewport({
   statistics,
   subject,
   gridScale,
-  content,
 }: Object3DDocumentViewportProps) {
   const viewStageKind = stageKind ?? stageKindOf(documentId);
   // ANNOUNCE THE STAGE (`authoring/object3d-document-session-registry.ts`).
@@ -588,16 +562,10 @@ export function Object3DDocumentViewport({
     return () => retainedObject3DStages.release(retained, generation);
   }, [documentId]);
   const retainedState = retainedRef.current;
-  // WHAT THIS STAGE SHOWS. A world root stays attached while hidden: Play
-  // adopts into it, and the play-entry flight rides its frame clock.
-  const worldRoot = content?.kind === 'world-root';
   // Only a visible pane owns an interactive attachment. Hidden documents
   // retain their state and return their renderer to the bounded pool.
-  const wantsSurface = active || worldRoot;
-  const worldRootLoadRef = useRef(content?.kind === 'world-root' ? content.load : null);
-  worldRootLoadRef.current = content?.kind === 'world-root' ? content.load : null;
-  const [surfaceAttached, setSurfaceAttached] = useState(wantsSurface);
-  useEffect(() => setSurfaceAttached(wantsSurface), [wantsSurface]);
+  const [surfaceAttached, setSurfaceAttached] = useState(active);
+  useEffect(() => setSurfaceAttached(active), [active]);
   // The selection silhouette is a LIVE prop: a modeling document turns it off
   // the moment it enters its own sub-object mode and back on when it leaves,
   // and the session applies that to the composer it has already built. The ref
@@ -620,7 +588,7 @@ export function Object3DDocumentViewport({
     setSurfaceStatus('building');
     return () => {
       const host = documentHostRef.current;
-      if (host && !worldRoot) {
+      if (host) {
         // Inactive tabs stay open in the workspace. Their source remains
         // mounted in retained CPU state while the expensive attachment goes
         // back to the pool. A source revision or final close still disposes it.
@@ -640,7 +608,7 @@ export function Object3DDocumentViewport({
       host?.close();
       documentHostRef.current = null;
     };
-  }, [documentId, rendererLane, retainedState, surfaceAttached, worldRoot]);
+  }, [documentId, rendererLane, retainedState, surfaceAttached]);
   const openingViewRef = useRef(openingView);
   openingViewRef.current = openingView;
   const documentPresentationRef = useRef(documentPresentation);
@@ -677,10 +645,6 @@ export function Object3DDocumentViewport({
   const persistenceSessionRef = useRef<Promise<AssetDocumentPersistenceSession> | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [surfaceStatus, setSurfaceStatus] = useState<'building' | 'ready'>('building');
-  // A world root's own mount state and the binding that draws its overlays.
-  const [worldRootBinding, setWorldRootBinding] = useState<WorldRootStageBinding | null>(null);
-  const [designMountStatus, setDesignMountStatus] = useState<'mounting' | 'ready'>('mounting');
-  const [designRootIds, setDesignRootIds] = useState<readonly string[]>([]);
   const [projection, setProjection] = useState<ThreeViewportProjection>('perspective');
   // The live authoring adapter this document's inspection composes from. It
   // only exists once the graph is built, so it is state rather than a ref:
@@ -707,122 +671,14 @@ export function Object3DDocumentViewport({
   useEffect(() => {
     let cancelled = false;
     if (!surfaceAttached) return;
-    /**
-     * THE WORLD ROOT'S CONTENT BINDING. It shows the project's world rather
-     * than one constructed Object3D, so it brings its own surface, scene,
-     * composer and the presenter Play adopts through; everything else about
-     * the stage is the host's, exactly as it is for a prefab or a model.
-     */
-    const installWorldRoot = async (
-      load: () => Promise<WorldRootStageBinding>,
-    ): Promise<void> => {
-      const container = containerRef.current;
-      const canvasHost = canvasHostRef.current;
-      if (!container || !canvasHost || documentHostRef.current) return;
-      const stats = shellStatsRef.current;
-      const store = threeStoreForHost();
-      if (!stats || !store) {
-        // The world root IS the shell's own subject — its readout, its
-        // adoption stack, its transport. A bounded host has none of that.
-        setError('The world root needs the editor shell above it; this host has none.');
-        return;
-      }
-      const binding = await load();
-      if (cancelled || documentHostRef.current) return;
-      setWorldRootBinding(() => binding);
-      markViewportConstructStarted();
-      const host = new Object3DDocumentHost(
-        'own',
-        binding.mountWorldRootSurface(canvasHost, container, displayName),
-        // The world is the session's own subject: Play adoption, ingest, the
-        // project history and the host door's hierarchy facet all address the
-        // SESSION store, so this stage runs on it rather than a private one.
-        store,
-      );
-      documentHostRef.current = host;
-      host.cleanups.push(registerStageStore(documentId, host.store.shell));
-      host.cleanups.push(registerStageTransport(documentId, host.transport));
-      host.cleanups.push(
-        registerDocumentViewport(documentId, {
-          ...sceneDocumentViewport(host.store, documentId),
-          ...threeStageTransformChrome(documentId),
-        }),
-      );
-      const stage = binding.installWorldRootStage({
-        store: host.store,
-        documentId,
-        container,
-        canvas: host.surface.canvas,
-        renderer: host.surface.renderer,
-        stats,
-        onMountStatus: setDesignMountStatus,
-        onRootIds: setDesignRootIds,
-        runFrame: (delta) => runViewportFrame(documentId, delta),
-      });
-      host.viewport = stage.viewport;
-      host.frame = stage.frame;
-      host.content = {
-        scene: stage.scene,
-        settle: () => Promise.resolve(),
-        dispose: async () => stage.dispose(),
-      };
-      // Rescan clip subjects on throttled store changes as the world tree mounts and updates.
-      // Inspect the scene the stage draws, including a session store’s scene.
-      const clipScan = scanClipSubjects(() => host.store.scene ?? stage.scene, host.transport, {
-        // A game makes its mixers as its world runs, not when the store changes.
-        rescanOnLiveMixers: true,
-      });
-      let lastClipScan = 0;
-      host.cleanups.push(() => clipScan.dispose());
-      host.cleanups.push(
-        host.store.shell.subscribe(() => {
-          const now = performance.now();
-          if (now - lastClipScan < CLIP_RESCAN_INTERVAL_MS) return;
-          lastClipScan = now;
-          clipScan.refresh();
-        }),
-      );
-      // This stage's presenter is the real one: Play adoption is a condition
-      // on the world-root binding, and a `build` stage declines every root.
-      host.cleanups.push(
-        bindViewportRig(
-          {
-            camera: stage.viewport.camera,
-            drawCamera: () => stage.viewport.renderCamera,
-            orbit: stage.viewport.orbitControls,
-            projection: stage.viewport.projectionOwner,
-            scene: stage.scene,
-            renderer: host.surface.renderer,
-          },
-          stage.setHelper,
-          { documentId },
-        ),
-      );
-      rendererSessionRef.current = host.rendererSession;
-      host.initialized = true;
-      markViewportConstructReady();
-      // The binding's own overlay reports mount progress.
-      setSurfaceStatus('ready');
-      // Always active: the play-entry flight rides this clock while the Game
-      // document holds focus; the stage skips frames by its own visibility.
-      host.rendererSession.setActive(true);
-    };
     const install = async () => {
       await documentHostRef.current?.content?.settle();
       while (liveGestureActive()) await whenLiveGestureIdle();
       if (cancelled) return;
-      const loadWorldRoot = worldRootLoadRef.current;
-      if (loadWorldRoot) return installWorldRoot(loadWorldRoot);
       const container = containerRef.current;
       const canvasHost = canvasHostRef.current;
       if (!container || !canvasHost) return;
-      if (!build || sourcePath === undefined) {
-        // `build` content is one Object3D the caller constructs from one file.
-        // Both are required by the SDK; validate callers at the runtime boundary.
-        setError('This stage shows `build` content and was given no `build()`/`sourcePath`.');
-        return;
-      }
-      let source: ReturnType<NonNullable<typeof build>>;
+      let source: ReturnType<typeof build>;
       const retainedGeneration = retainedObject3DStages.generation(retainedState);
       try {
         source = retainedState.source ?? build();
@@ -877,6 +733,8 @@ export function Object3DDocumentViewport({
       const history = workspaceHistoryService();
       if (history) store.shell.attachHistory(history);
       const shared = rendererLane === 'inspector-preview';
+      // Only the document's own view keeps its framing: a preview of it stands where it frames.
+      const recordsFraming = !shared && !chromeless;
       const studioStage = studioStageRef.current;
       const hasShell = hasShellRef.current;
       const assetSubject = assetSubjectRef.current;
@@ -1440,6 +1298,7 @@ export function Object3DDocumentViewport({
             presentationAdapter?.hierarchy.idForNativeObject?.(object) ?? adapter.hierarchy.idForNativeObject?.(object);
           if (id) store.objectMap.set(id, object);
         });
+        const opening = !host.session;
         if (!host.session) {
           // The view's camera (`ViewportCamera`): its field of view, and the direction it opens
           // from when the document states none.
@@ -1528,6 +1387,18 @@ export function Object3DDocumentViewport({
           // After the pose, which draws in perspective: an orthographic view comes back as one.
           viewport.setProjection(projection);
           retainedState.camera = null;
+        } else if (opening && recordsFraming) {
+          // THE VIEW'S STATE OVER THE FILE'S: a document that was seen before opens where it was
+          // last seen (`viewFraming`, restored from workspace storage, as Code-OSS restores an
+          // editor's view state), in place of the opening view its file states.
+          const framing = viewFraming(documentId);
+          if (framing) {
+            const [x, y, z] = framing.position;
+            const [tx, ty, tz] = framing.target;
+            const [ux, uy, uz] = framing.up;
+            viewport.setPose({ x, y, z }, { x: tx, y: ty, z: tz }, undefined, { x: ux, y: uy, z: uz });
+            host.session.setProjection(framing.projection);
+          }
         }
         const documentSession = host.session;
         documentStateRef.current = documentState;
@@ -1578,8 +1449,11 @@ export function Object3DDocumentViewport({
           if (viewPresentation(documentId).drawMode !== mode)
             setViewPresentation(documentId, { drawMode: mode as ViewportDrawMode });
         };
-        // Initialize draw mode from the document’s file, then the restored view, then the session default. Synchronize the view to the resulting session mode.
-        const restoredMode = ownLayer?.drawMode ?? viewPresentationSnapshot(documentId).drawMode;
+        // The draw mode the view opens in: the view state (the person's last view of this document,
+        // `document-view-states.ts`), else what the document's file states, else the session's default,
+        // as Code-OSS restores an editor's view state over its input's defaults. The view then follows
+        // the session.
+        const restoredMode = viewPresentationSnapshot(documentId).drawMode ?? ownLayer?.drawMode;
         if (restoredMode !== undefined && viewModes.has(restoredMode) && host.session)
           host.session.setMode(restoredMode);
         sessionToView();
@@ -1718,8 +1592,39 @@ export function Object3DDocumentViewport({
           }
         };
         host.syncHostScene = syncHostScene;
+        // WHERE THE VIEW STANDS, recorded as it moves (`setViewFraming`): when the orbit controls
+        // report a move (`OrbitControls.update` dispatches `change` for any move, `setPose`'s
+        // included), when the session changes (its projection), and before every draw. A door can
+        // move the camera with no ordinary draw after it: measured, a pose set through
+        // `editor.present` was not recorded by draws alone; that the page's tab was not on screen
+        // is the likely cause, not measured. A photograph's draw (`captureImage`) leaves the view's
+        // camera where it stands. During a photograph the projection recorded last stands, as a
+        // guard: no caller switches the projection for a photograph today.
+        let recordedFraming = '';
+        let recordedProjection: 'perspective' | 'orthographic' | null = null;
+        const recordFraming = (): void => {
+          if (!recordsFraming) return;
+          const position = viewport.camera.position.toArray();
+          const target = viewport.orbitControls.target.toArray();
+          const up = viewport.camera.up.toArray();
+          const projection =
+            documentSession.photographing() && recordedProjection !== null ? recordedProjection : documentSession.projection();
+          const key = `${position}|${target}|${up}|${projection}`;
+          if (key === recordedFraming) return;
+          recordedFraming = key;
+          recordedProjection = projection;
+          setViewFraming(documentId, { position, target, up, projection });
+        };
+        const controls = viewport.orbitControls;
+        controls.addEventListener('change', recordFraming);
+        const stopSessionFraming = documentSession.subscribe(recordFraming);
+        host.cleanups.push(() => {
+          controls.removeEventListener('change', recordFraming);
+          stopSessionFraming();
+        });
         documentSession.setBeforeRender((interactive) => {
           host.syncHostScene?.();
+          recordFraming();
           const mode = documentSession.presentation().mode;
           const navigation = interactive && ['solid', 'preview', 'clay', 'unlit', 'matcap'].includes(mode);
           return source.prepareDraw?.(documentSession.camera(), {interactive: navigation, height: renderer.domElement.height, multiDraw: renderer.extensions.has('WEBGL_multi_draw'), renderer, drawMode: mode, pixelScale: documentSession.drawPixelScale(), photograph: documentSession.photographing()});
@@ -1736,7 +1641,7 @@ export function Object3DDocumentViewport({
           host.transportAdvances++;
           source.update?.(deltaSeconds);
         };
-        // Scan this source's animation subjects once. World-root stages rescan as their trees update.
+        // Scan this source's animation subjects once.
         const clipScan = scanClipSubjects(source.root, host.transport);
         host.cleanups.push(() => clipScan.dispose());
         const retainedTransport = retainedState.transport;
@@ -1867,8 +1772,8 @@ export function Object3DDocumentViewport({
           host.presence?.syncMarkers(delta);
           viewport.update(delta);
           // This stage's frame hook. After viewport.update, the same order the
-          // scene panel uses, so anything riding the loop (a camera flight)
-          // has final say over the pose and orbit damping never fights it.
+          // scene panel uses, so anything riding the loop has final say over
+          // the pose and orbit damping never fights it.
           if (!chromeless) runViewportFrame(documentId, delta);
           if (navigationMeasurement) {
             const camera = documentSession.camera();
@@ -2102,7 +2007,6 @@ export function Object3DDocumentViewport({
             store.shell.onViewportAction((action) => {
               switch (action.type) {
                 case 'focus-selection':
-                case 'focus-scene':
                   // The session frames the selection, else the whole subject,
                   // and says so on the console when there is nothing to frame.
                   if (!host.session?.frame() && host.session?.root)
@@ -2251,7 +2155,6 @@ export function Object3DDocumentViewport({
     surfaceAttached,
     sourceAuthoring,
     sourcePath,
-    worldRoot,
   ]);
 
   useEffect(() => {
@@ -2263,11 +2166,10 @@ export function Object3DDocumentViewport({
       firstFrameGateRef.current = false;
       markViewportRafResume(documentId);
     }
-    // A world root keeps its clock while another document holds focus.
-    session.setActive(active || worldRoot);
+    session.setActive(active);
     // A hidden stage keeps no live accumulation (its targets are the drawing buffer's size).
     if (!active) documentHostRef.current?.session?.releaseLive();
-  }, [active, documentId, worldRoot]);
+  }, [active, documentId]);
 
   // The stage's own handle for the capabilities that drive it directly (the
   // viewport hotkeys). `surfaceStatus` is what re-renders once the stage has
@@ -2336,14 +2238,6 @@ export function Object3DDocumentViewport({
             chrome="document"
           />
         ) : null}
-        {shellStore && worldRootBinding ? (
-          <worldRootBinding.Overlays
-            store={shellStore}
-            documentId={documentId}
-            mountStatus={designMountStatus}
-            rootIds={designRootIds}
-          />
-        ) : null}
         {/* Show a dismissible error notice over any stage that remains available. */}
         {error && (
           <EditorBanner

package/src/kit/components/ViewportViewMenu.tsx

@@ -27,7 +27,7 @@ const ZERO = () => 0;
 
 /**
  * Editor-camera projection and axis presets for the stage’s own shell. A documentId targets its
- * Object3DDocumentSession; the world root uses the editor-wide projection. label shows the view
+ * Object3DDocumentSession; without one, the editor-wide projection. label shows the view
  * name instead of a camera icon, and kebab prefixes the label with three dots.
  */
 export function ViewportViewMenu({

package/src/kit/components/stage-transform-tools.tsx

@@ -3,8 +3,7 @@
  * document's chrome (`@volter/sdk/document-viewports`): what the
  * host's transform tools drive on it (`stage-context.ts`'s one answer), the tool
  * strip on its shelf and the gizmo's header wells. Every tool writes THIS
- * stage's own store (`stage-store-registry.ts`); the world root's stage runs on
- * the session store, so the Scene document is unchanged either way.
+ * stage's own store (`stage-store-registry.ts`).
  */
 import { type ViewportInteraction, viewPresentation } from '@volter/sdk/viewport-presentation';
 import { useEffect, useSyncExternalStore } from 'react';

package/src/kit/editor-shell-store.ts

@@ -99,35 +99,11 @@ export class EditorShellStore {
     this._statePersistence = persistence;
   }
 
-  /** The game camera lookup the last `focusOnScene` carried, read by the world stage while its
-   *  auto-frame window is open. */
-  get sceneCameraLookup(): (() => THREE.Camera | null) | null {
-    return this._sceneCameraLookup;
-  }
-  protected _sceneCameraLookup: (() => THREE.Camera | null) | null = null;
-
-  /**
-   * Frame the whole active scene — the first thing a reader should see when a
-   * world they did not author opens. The viewport keeps
-   * asking until the world HAS content, because a game builds itself
-   * asynchronously; any camera input from the reader cancels it (see
-   * `the world root's stage`). A no-op for a scene the reader already has a camera on.
-   *
-   * `gameCamera` is a LIVE LOOKUP, not a camera: a game's own camera
-   * may not exist yet on the frame it is captured on, so the viewport asks
-   * again while its window is open. When one turns up, its view is adopted
-   * instead of any measurement — see `scene-framing.ts`.
-   */
-  focusOnScene(gameCamera?: () => THREE.Camera | null): void {
-    this._sceneCameraLookup = gameCamera ?? null;
-    this.shell.focusOnScene();
-  }
-
   /**
    * Live viewport camera pose, read straight from the bound Three.js camera +
    * orbit target (`bindScene`/`setOrbitTarget`).
    * Null only when nothing has bound a camera yet (e.g. a headless store in a
-   * unit test that never mounted `the world root's stage`).
+   * unit test that never mounted a stage).
    */
   get cameraPose(): { position: THREE.Vector3; target: THREE.Vector3; fov: number } | null {
     if (!this._camera) return null;
@@ -326,7 +302,7 @@ export class EditorShellStore {
    * Fresh, on-demand viewport capture (unthrottled, unlike the periodic
    * autosave thumbnail above) — backs the `capture-viewport` relay command.
    * Returns null when no renderer/scene/camera is bound yet (e.g. before
-   * `the world root's stage` has mounted).
+   * a stage has mounted).
    */
   captureViewportImage(
     size: number | { width: number; height: number } = EditorShellStore.THUMBNAIL_SIZE,

package/src/kit/editor-viewport.ts

@@ -1432,7 +1432,7 @@ export class EditorViewport {
     return this._scene;
   }
 
-  /** Camera that paints the Scene document: the free editor camera. */
+  /** Camera that paints the stage: the free editor camera. */
   get renderCamera(): THREE.Camera {
     return this.freeCamera;
   }

package/src/kit/three-integration.ts

@@ -22,7 +22,6 @@ import { editorHost } from '@volter/sdk/host';
 import { onShellStore } from '@volter/sdk/shell-store-door';
 import { registerThreeCanvasRender } from './three-canvas-render';
 import { registerThreeHierarchyRowMedia } from './three-hierarchy-row-media';
-import { registerThreePlayCameraFlight } from './play-camera-flight';
 import { registerThreeInspectionMedia } from './three-inspection-media';
 import { threeStateOf } from './three-state';
 import { installViewportAuthoringPolicy } from './viewport-authoring-policy';
@@ -68,7 +67,6 @@ export function ensureThreeIntegration(): () => void {
     reportViewportStatus(),
     registerThreeCanvasRender(),
     registerThreeHierarchyRowMedia(),
-    registerThreePlayCameraFlight(),
     registerRendererResourceCounts('hostLive', liveHostRendererCount),
     registerRendererResourceCounts('interactive', interactiveViewportRendererCounts),
     registerRendererResourceCounts('inspectorPreview', inspectorPreviewRendererCounts),

package/src/viewport-api.ts

@@ -1,7 +1,6 @@
 /**
  * THE AUTHORED THREE VIEWPORT'S PUBLIC SHAPE — what a lane that mounts something reaches through
- * `viewport-door.ts`: the rig a camera flight drives, the frame loop it rides, the helpers it
- * shows and every mounted stage.
+ * `viewport-door.ts`: every mounted stage, its rig, its frame loop and the helpers it shows.
  */
 import type * as THREE from 'three';
 import type { StageFrameCostReading } from '@volter/sdk';
@@ -35,9 +34,7 @@ export interface ViewportRig {
 
 /**
  * ONE MOUNTED 3D STAGE, named by the document it draws. Every 3D document
- * mounts a stage of its own ; this is the door
- * to a particular one, where the viewport door's singular members
- * are the door to whichever is primary.
+ * mounts a stage of its own; this is the door to a particular one.
  */
 export interface ViewportStage {
   /** The workspace document this stage draws. */
@@ -50,14 +47,8 @@ export interface ViewportStage {
 }
 
 /**
- * THE AUTHORED VIEWPORT, as a lane that mounts something reaches it: the rig
- * a camera flight drives and the frame loop it rides. Which native surface the
- * viewport renders is the host's; a lane that finds no rig (a headless tab, a
- * project with no Three root) mounts without one.
- *
- * THE SINGULAR MEMBERS ARE THE PRIMARY STAGE — the FOCUSED stage, else the
- * first bound. A camera flight wants exactly that one, which is why it reads
- * here and never enumerates.
+ * THE AUTHORED VIEWPORT, as a lane that mounts something reaches it. Which
+ * native surface the viewport renders is the host's.
  *
  * {@link stages} is EVERY mounted 3D stage. A helper is an `Object3D` and an
  * `Object3D` has one parent, so there is no "set it once for all stages": a
@@ -66,9 +57,6 @@ export interface ViewportStage {
  * it made that pass.
  */
 export interface ViewportDoor {
-  rig(): ViewportRig | null;
-  /** Runs after the viewport's own per-frame update; the return unsubscribes. */
-  onFrame(fn: (dtSeconds: number) => void): () => void;
   /**
    * Show an editor-only helper object of `kind` in the authored viewport (a
    * baked navmesh's debug mesh), replacing the previous one of that kind;

package/src/viewport-door.ts

@@ -2,14 +2,11 @@
  * Registry for document stages' viewport rigs, helper displays and frame callbacks. Each mounted
  * 3D stage binds under its document id and runs its frame hook from its own RAF loop.
  *
- * `viewportRig` and `onViewportFrame` follow the primary stage: the focused document's bound
- * stage, else the first bound. The camera-flight seam reads that rig and uses its frame clock.
  * `viewportStages()` exposes every bound stage so helpers can be attached to each separately.
  * Stage subscriptions and helpers survive canvas remounts under the same document id.
  */
 
 import type { ViewportDoor, ViewportRig, ViewportStage } from './viewport-api';
-import { activeWorkspaceDocumentId } from '@volter/sdk/workspace-document-registry';
 
 /** An editor-only helper object, typed by the host door it is shown through. */
 type HelperObject = Parameters<ViewportDoor['setHelper']>[1];
@@ -24,8 +21,7 @@ interface Binding {
   readonly helpers: Map<string, HelperObject>;
 }
 
-/** Every bound stage, keyed by the document it draws; insertion-ordered, so
- *  "the first bound" is a real answer. */
+/** Every bound stage, keyed by the document it draws, in bind order. */
 const bound = new Map<string, Binding>();
 /** Retain frame subscribers and helper assignments by document across viewport remounts and before binding. */
 const stageStateByDocument = new Map<
@@ -47,23 +43,8 @@ function stageStateFor(documentId: string): {
   }
   return state;
 }
-/** Listeners on the singular `onViewportFrame`: they follow the PRIMARY
- *  stage, so they are held here and fanned in rather than added to a
- *  binding's own set, which would strand them on a stage that stops being
- *  primary (or unmounts). */
-const primaryFrameListeners = new Set<(dtSeconds: number) => void>();
 const stageListeners = new Set<(stages: readonly ViewportStage[]) => void>();
 
-/** THE PRIMARY STAGE: focused > first bound. */
-function primary(): Binding | null {
-  const focused = activeWorkspaceDocumentId();
-  if (focused !== null) {
-    const match = bound.get(focused);
-    if (match) return match;
-  }
-  return bound.values().next().value ?? null;
-}
-
 let stagesCache: readonly ViewportStage[] | null = null;
 
 function notifyStages(): void {
@@ -121,20 +102,6 @@ export function bindViewportRig(
   };
 }
 
-export function viewportRig(): ViewportRig | null {
-  return primary()?.rig ?? null;
-}
-
-/** Runs after the PRIMARY stage's own per-frame update, and RE-TARGETS: the
- *  listener follows whichever stage is primary, not the one that was primary
- *  when it subscribed. */
-export function onViewportFrame(fn: (dtSeconds: number) => void): () => void {
-  primaryFrameListeners.add(fn);
-  return () => {
-    primaryFrameListeners.delete(fn);
-  };
-}
-
 /** Every bound stage, in bind order. */
 export function viewportStages(): readonly ViewportStage[] {
   if (!stagesCache)
@@ -156,12 +123,9 @@ export function onViewportStages(fn: (stages: readonly ViewportStage[]) => void)
   };
 }
 
-/** A stage's RAF loop calls this after its own update each frame. The stage's
- *  own listeners always run; the primary-stage listeners run here only when
- *  this stage IS the primary. */
+/** A stage's RAF loop calls this after its own update each frame, running the stage's own listeners. */
 export function runViewportFrame(documentId: string, dtSeconds: number): void {
   const binding = bound.get(documentId);
   if (!binding) return;
   for (const fn of binding.frameListeners) fn(dtSeconds);
-  if (primary() === binding) for (const fn of primaryFrameListeners) fn(dtSeconds);
 }

package/src/kit/components/world-root-binding.ts

@@ -1,59 +0,0 @@
-/**
- * THE WORLD ROOT'S CONTENT BINDING, as the stage host sees it.
- *
- * A stage shows either one Object3D a caller builds (`build` content) or the
- * project's world (`world-root` content): the manifest's roots mounted by a
- * design session, drawn by the world's own image pipeline, with the presenter
- * Play adopts live roots through. The host owns the surface's place, the frame
- * session, the per-stage door, the furniture and the overlays for both. What
- * mounts a world is the contributing package's — it runs the game runtime,
- * which a modeling host never carries — so the package hands the host this
- * binding and the host loads it only for a stage that shows a world.
- */
-import type { ComponentType } from 'react';
-import type * as THREE from 'three';
-import type { EditorShellStore } from '../editor-shell-store';
-import type { EditorStats } from '@volter/sdk/editor-runtime';
-import type { EditorViewport } from '../editor-viewport';
-
-export interface WorldRootStageOptions {
-  /** The session's store: the world is the session's own subject. */
-  readonly store: EditorShellStore;
-  readonly documentId: string;
-  readonly container: HTMLDivElement;
-  readonly canvas: HTMLCanvasElement;
-  readonly renderer: THREE.WebGLRenderer;
-  readonly stats: EditorStats;
-  readonly onMountStatus: (status: 'mounting' | 'ready') => void;
-  readonly onRootIds: (rootIds: readonly string[]) => void;
-  /** This stage's frame hook on the per-stage viewport door. */
-  readonly runFrame: (deltaSeconds: number) => void;
-}
-
-export interface WorldRootStage {
-  readonly scene: THREE.Scene;
-  readonly viewport: EditorViewport;
-  frame(timeMs: number, resumed: boolean): void;
-  setHelper(kind: string, object: THREE.Object3D | null): void;
-  dispose(): void;
-}
-
-export interface WorldRootOverlayProps {
-  readonly store: EditorShellStore;
-  /** The stage's own document — its stage context is read by this id. */
-  readonly documentId: string;
-  readonly mountStatus: 'mounting' | 'ready';
-  readonly rootIds: readonly string[];
-}
-
-export interface WorldRootStageBinding {
-  /** The world's own drawing surface, built to the world's render settings. */
-  mountWorldRootSurface(
-    canvasHost: HTMLDivElement,
-    container: HTMLDivElement,
-    displayName: string,
-  ): { canvas: HTMLCanvasElement; renderer: THREE.WebGLRenderer; lease: null };
-  installWorldRootStage(options: WorldRootStageOptions): WorldRootStage;
-  /** What the stage shows over a world: its mount state and camera authoring. */
-  readonly Overlays: ComponentType<WorldRootOverlayProps>;
-}

package/src/kit/play-camera-flight.ts

@@ -1,291 +0,0 @@
-/**
- * THE PLAY ENTRY CAMERA FLIGHT — the Three integration's half of Play's immersive entry
- * (`@volter/sdk/play-camera-flight`). The kit's transition owns the phases and the
- * chrome; this owns the camera: the editor viewport flies along a Catmull-Rom spline from its
- * preview pose to the AUTHORED game camera's pose, retargets to the game's live camera once it
- * boots so the cross-fade is pixel-continuous, and restores the preview pose when Play ends. The
- * flight reads the authored viewport's rig through the viewport door and rides its frame hook, so
- * flight pacing rides the editor's own frame clock.
- */
-import { registerPlayCameraFlight, type LiveCameraLookup } from '@volter/sdk/play-camera-flight';
-import { onViewportFrame, viewportRig } from '../viewport-door';
-import * as THREE from 'three';
-import { threeStoreForHost } from './three-state';
-
-/** Flight time scales mildly with distance so short hops feel snappy and
- *  cross-scene flights stay graceful, clamped to a tight band. */
-export function flightDurationMs(distance: number): number {
-  return Math.min(1600, Math.max(800, 900 + distance * 25));
-}
-
-export function easeInOutCubic(t: number): number {
-  return t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
-}
-
-/**
- * Control points for the camera flight spline: start, two interior points
- * forming a gentle arc, end. The arc lifts along world-up and bows slightly
- * sideways, both proportional to (but clamped against) the travel distance —
- * a short hop barely arcs, a long flight gets a visible swoop, and a
- * degenerate zero-length flight returns a straight (stationary) curve.
- */
-export function computeFlightControlPoints(
-  start: THREE.Vector3,
-  end: THREE.Vector3,
-  up: THREE.Vector3 = new THREE.Vector3(0, 1, 0),
-): THREE.Vector3[] {
-  const travel = new THREE.Vector3().subVectors(end, start);
-  const distance = travel.length();
-  if (distance < 1e-6) {
-    return [start.clone(), start.clone(), end.clone(), end.clone()];
-  }
-  const lift = Math.min(distance * 0.18, 6);
-  // Side bias perpendicular to travel and up — gives the arc a slight bank
-  // instead of a purely vertical hump. Falls back to zero when travel is
-  // parallel to up (straight vertical flights just lift).
-  const side = new THREE.Vector3().crossVectors(travel, up);
-  if (side.lengthSq() > 1e-9) side.normalize().multiplyScalar(Math.min(distance * 0.08, 2.5));
-  else side.set(0, 0, 0);
-  const liftVec = up.clone().normalize().multiplyScalar(lift);
-  const p1 = start.clone().addScaledVector(travel, 0.3).add(liftVec).add(side);
-  const p2 = end
-    .clone()
-    .addScaledVector(travel, -0.3)
-    .addScaledVector(liftVec, 0.6)
-    .addScaledVector(side, 0.5);
-  return [start.clone(), p1, p2, end.clone()];
-}
-
-/** The narrow store surface `resolveAuthoredCameraTarget` reads. */
-export interface PlayCameraSourceStore {
-  readonly objectMap: ReadonlyMap<string, THREE.Object3D>;
-}
-
-export interface AuthoredCameraTarget {
-  entityId: string;
-  position: [number, number, number];
-  quaternion: [number, number, number, number];
-  fov: number;
-}
-
-/** Editor-only overlays (helpers, gizmos) live on layer 31 — never flight targets. */
-const EDITOR_ONLY_LAYER_MASK = 1 << 31;
-
-function isEditorOnlyOrGizmo(obj: THREE.Object3D): boolean {
-  return (obj.layers.mask & EDITOR_ONLY_LAYER_MASK) !== 0 || /gizmo/i.test(obj.name);
-}
-
-/** Depth-first search for the first real camera in a subtree, skipping
- *  editor-only/gizmo branches wholesale. */
-function findCameraInSubtree(obj: THREE.Object3D): THREE.Camera | null {
-  if (isEditorOnlyOrGizmo(obj)) return null;
-  if ((obj as Partial<THREE.Camera>).isCamera) return obj as THREE.Camera;
-  for (const child of obj.children) {
-    const found = findCameraInSubtree(child);
-    if (found) return found;
-  }
-  return null;
-}
-
-function targetFromObject(
-  entityId: string,
-  obj: THREE.Object3D,
-  fov: number,
-): AuthoredCameraTarget {
-  const position = new THREE.Vector3();
-  const quaternion = new THREE.Quaternion();
-  obj.getWorldPosition(position);
-  obj.getWorldQuaternion(quaternion);
-  return {
-    entityId,
-    position: position.toArray() as [number, number, number],
-    quaternion: quaternion.toArray() as [number, number, number, number],
-    fov,
-  };
-}
-
-/**
- * Find the authored camera in the current editor scene outside editor-only and gizmo branches, and
- * return its live world transform. Return null when the mapped object graph contains no camera.
- */
-export function resolveAuthoredCameraTarget(
-  store: PlayCameraSourceStore,
-): AuthoredCameraTarget | null {
-  for (const [id, obj] of store.objectMap) {
-    const camera = findCameraInSubtree(obj);
-    if (!camera) continue;
-    const perspective = camera as Partial<THREE.PerspectiveCamera>;
-    return targetFromObject(id, camera, perspective.isPerspectiveCamera ? perspective.fov! : 60);
-  }
-  return null;
-}
-
-interface FlightRuntime {
-  startPos: THREE.Vector3;
-  startQuat: THREE.Quaternion;
-  startFov: number;
-  endPos: THREE.Vector3;
-  endQuat: THREE.Quaternion;
-  endFov: number;
-  curve: THREE.CatmullRomCurve3;
-  startedAt: number;
-  durationMs: number;
-  landed: boolean;
-}
-
-function rebuildCurve(flight: FlightRuntime): void {
-  flight.curve = new THREE.CatmullRomCurve3(
-    computeFlightControlPoints(flight.startPos, flight.endPos),
-  );
-}
-
-interface ActiveFlight {
-  readonly runtime: FlightRuntime;
-  readonly snapshot: { position: THREE.Vector3; target: THREE.Vector3; up: THREE.Vector3; fov: number };
-  readonly onLanded: () => void;
-  /** Live camera, registered at live-ready — the flight retargets to it
-   *  each frame so the hand-off converges on whatever the project actually does
-   *  with its camera during boot (follow rigs, SceneCamera components…). */
-  getLiveCamera: LiveCameraLookup | null;
-  /** Driving the camera: from `begin` until the game is on screen (`settle`) or Play ends. */
-  driving: boolean;
-}
-
-let _flight: ActiveFlight | null = null;
-
-function begin(onLanded: () => void): boolean {
-  const viewport = viewportRig();
-  const objects = threeStoreForHost()?.objectMap;
-  const target = objects ? resolveAuthoredCameraTarget({ objectMap: objects }) : null;
-  if (!target || !viewport) return false;
-  const startPos = viewport.camera.position.clone();
-  const endPos = new THREE.Vector3().fromArray(target.position);
-  _flight = {
-    runtime: {
-      startPos,
-      startQuat: viewport.camera.quaternion.clone(),
-      startFov: viewport.camera.fov,
-      endPos,
-      endQuat: new THREE.Quaternion().fromArray(target.quaternion),
-      endFov: target.fov,
-      curve: new THREE.CatmullRomCurve3(computeFlightControlPoints(startPos, endPos)),
-      startedAt: performance.now(),
-      durationMs: flightDurationMs(startPos.distanceTo(endPos)),
-      landed: false,
-    },
-    snapshot: {
-      position: viewport.camera.position.clone(),
-      target: viewport.orbit.target.clone(),
-      up: viewport.camera.up.clone(),
-      fov: viewport.camera.fov,
-    },
-    onLanded,
-    getLiveCamera: null,
-    driving: true,
-  };
-  viewport.orbit.enabled = false;
-  return true;
-}
-
-/** After the flight, leave OrbitControls in a sane state at the landed pose
- *  so the viewport still orbits correctly during play. */
-function settle(): void {
-  const viewport = viewportRig();
-  const active = _flight;
-  if (!active) return;
-  active.driving = false;
-  if (!viewport) return;
-  const camera = viewport.camera;
-  const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
-  const distance = Math.max(1, active.snapshot.position.distanceTo(active.snapshot.target));
-  viewport.orbit.target.copy(camera.position).addScaledVector(forward, distance);
-  // The orbit re-aims with the camera's up: the landed pose's own, so its roll stands.
-  camera.up.set(0, 1, 0).applyQuaternion(camera.quaternion);
-  viewport.orbit.enabled = true;
-}
-
-/** Restore the pre-play camera pose. */
-function end(): void {
-  const active = _flight;
-  if (!active) return;
-  _flight = null;
-  const viewport = viewportRig();
-  if (!viewport) return;
-  const snap = active.snapshot;
-  viewport.camera.position.copy(snap.position);
-  viewport.orbit.target.copy(snap.target);
-  viewport.camera.up.copy(snap.up);
-  viewport.camera.lookAt(snap.target);
-  if (viewport.camera.fov !== snap.fov) {
-    viewport.camera.fov = snap.fov;
-    viewport.camera.updateProjectionMatrix();
-  }
-  viewport.orbit.enabled = true;
-  viewport.orbit.update();
-}
-
-const _liveCamPos = new THREE.Vector3();
-const _liveCamQuat = new THREE.Quaternion();
-
-/**
- * Per-frame flight driver — called from the world root's stage's RAF loop right after
- * `viewport.update(dt)` so the flight has final say over the camera pose.
- */
-onViewportFrame(playTransitionFrame);
-
-function playTransitionFrame(): void {
-  const active = _flight;
-  const viewport = viewportRig();
-  if (!active || !viewport || !active.driving) return;
-  const flight = active.runtime;
-
-  // Retarget to the live game camera once it exists (`track`).
-  // The kit hands the lane's lookup over unread; only an `Object3D` is a camera to converge on.
-  const found = active.getLiveCamera?.() ?? null;
-  const liveCamera = (found as Partial<THREE.Object3D> | null)?.isObject3D ? (found as THREE.Object3D) : null;
-  if (liveCamera) {
-    liveCamera.getWorldPosition(_liveCamPos);
-    liveCamera.getWorldQuaternion(_liveCamQuat);
-    if (_liveCamPos.distanceToSquared(flight.endPos) > 1e-8) {
-      flight.endPos.copy(_liveCamPos);
-      rebuildCurve(flight);
-    }
-    flight.endQuat.copy(_liveCamQuat);
-    const liveFov = (liveCamera as THREE.PerspectiveCamera).fov;
-    if (typeof liveFov === 'number') flight.endFov = liveFov;
-  }
-
-  const camera = viewport.camera;
-  if (flight.landed) {
-    // Holding/cross-fading: pin to the (possibly live-tracked) end pose.
-    camera.position.copy(flight.endPos);
-    camera.quaternion.copy(flight.endQuat);
-    if (camera.fov !== flight.endFov) {
-      camera.fov = flight.endFov;
-      camera.updateProjectionMatrix();
-    }
-    return;
-  }
-
-  const t = Math.min(1, (performance.now() - flight.startedAt) / flight.durationMs);
-  const eased = easeInOutCubic(t);
-  camera.position.copy(flight.curve.getPoint(eased));
-  camera.quaternion.slerpQuaternions(flight.startQuat, flight.endQuat, eased);
-  camera.fov = flight.startFov + (flight.endFov - flight.startFov) * eased;
-  camera.updateProjectionMatrix();
-  if (t >= 1) {
-    flight.landed = true;
-    active.onLanded();
-  }
-}
-
-export function registerThreePlayCameraFlight(): () => void {
-  return registerPlayCameraFlight({
-    begin,
-    track: (liveCamera) => {
-      if (_flight) _flight.getLiveCamera = liveCamera;
-    },
-    settle,
-    end,
-  });
-}

package/src/kit/scene-document-viewport.ts

@@ -1,51 +0,0 @@
-/**
- * THE SCENE'S VIEWPORT (`@volter/sdk/document-viewports`): the world
- * stage draws the Scene through the session store's own camera, shading and
- * grid, and frames the shell's selection. It keeps no selection of its own, so a
- * view's selection is the shell's.
- */
-import type { DocumentViewport } from '@volter/sdk/document-viewports';
-import type { EditorShellStore } from './editor-shell-store';
-import { viewGridVisible } from '@volter/sdk/viewport-presentation';
-
-type ShadingMode = Parameters<EditorShellStore['setShadingMode']>[0];
-
-const SCENE_MODES = new Set<string>(['solid', 'clay', 'unlit', 'wireframe', 'normals', 'overdraw']);
-
-export function sceneDocumentViewport(store: EditorShellStore, documentId: string): DocumentViewport {
-  return {
-    read: () => {
-      const pose = store.cameraPose;
-      if (!pose) return null;
-      const { position, target } = pose;
-      return {
-        camera: {
-          position: { x: position.x, y: position.y, z: position.z },
-          target: { x: target.x, y: target.y, z: target.z },
-          ...(pose.fov ? { fov: pose.fov } : {}),
-        },
-        diagnostic: store.shadingMode,
-        grid: viewGridVisible(documentId),
-      };
-    },
-    setDiagnostic: (diagnostic) => {
-      if (!SCENE_MODES.has(diagnostic)) return false;
-      store.setShadingMode(diagnostic as ShadingMode);
-      return true;
-    },
-    setCamera: (camera) => {
-      if (typeof camera !== 'string') {
-        store.shell.setCameraPose(camera.position, camera.target, camera.fov);
-        return true;
-      }
-      if (camera === 'isometric') return false;
-      store.shell.setViewPreset(camera);
-      return true;
-    },
-    frame: (target) => {
-      if (target === 'document') return false;
-      store.shell.focusOnSelection();
-      return true;
-    },
-  };
-}