@volter/editor-threejs 0.5.211 → 0.5.213

package/src/viewport/clip-planes.ts

@@ -1,31 +1,4 @@
-/**
- * How far a Three authoring view's perspective camera can see.
- *
- * ## The measured defect this exists for
- *
- * The editor camera was constructed once, with `far = 1000`, and never
- * adjusted. That is fine for the starter template (a cube on a 50-unit grid)
- * and wrong for anything world-sized: framing a world several hundred units
- * across puts the camera past the far plane, so every triangle is clipped and
- * the Scene viewport is a flat, empty field. The failure is graded, which is
- * what made it confusing — at a 454-unit framing the world draws; at 1099 only
- * the fragments within 1000 survive; at 1276 nothing does. A game whose own
- * camera declares `far = 10000` is stating the honest scale of its world, and
- * the editor camera has to reach it.
- *
- * Nothing about that is ingest-specific — a first-party world larger than
- * ~1000 units disappears the same way — so the fix is a property of the editor
- * camera, not of the ingest route.
- *
- * ## Why grow `far` instead of just setting it large
- *
- * The depth buffer's precision is governed by `far / near`, not by `far`. A
- * blanket `far = 100000` would give every small scene a 10^6 ratio and visible
- * z-fighting. So `far` tracks the content the camera actually has to reach,
- * and `near` is pushed out only as much as is needed to keep the ratio bounded
- * — which, for anything at the template's scale, is not at all: the planes come
- * back exactly `0.1 / 1000`, the values the camera has always had.
- */
+/** Fit authoring-camera clip planes to content while bounding their ratio for depth precision. Retain base planes for ordinary small scenes. */
 
 /** The camera's minimum near plane — also the exact value for any small scene. */
 export const EDITOR_CAMERA_NEAR = 0.1;
@@ -34,7 +7,7 @@ export const EDITOR_CAMERA_NEAR = 0.1;
 export const EDITOR_CAMERA_FAR = 1000;
 
 /**
- * Ceiling on `far / near`. 0.1/1000 is 10^4, so this leaves two doublings of
+ * Ceiling on `far / near`. 1000/0.1 is 10^4, so this leaves one doubling of
  * headroom before `near` starts moving at all, and caps the depth-precision
  * loss a very large world can inflict.
  */
@@ -47,9 +20,8 @@ const REACH_MARGIN = 1.25;
  * Clip planes that reach `contentRadius` around a center `distanceToCenter`
  * away, never tighter than the base planes.
  *
- * Pure and total: a non-finite or negative input yields the base planes rather
- * than an `Infinity`/`NaN` projection matrix, because a camera whose bounds
- * could not be measured must still draw.
+ * Pure and total: a non-finite or negative input contributes zero to the reach.
+ * The remaining input still fits the content, and the base planes bound the result.
  */
 export function fitClipPlanes(
   distanceToCenter: number,

package/src/viewport/content-bounds.ts

@@ -1,71 +1,16 @@
-/**
- * World-space bounds of the GAME OBJECT a reader selected — the one walk every
- * bounds consumer in the editor uses instead of `Box3.setFromObject`.
- *
- * ## Why `Box3.setFromObject` is the wrong instrument here
- *
- * `setFromObject` answers "what is the extent of this whole subtree", and a
- * live game's subtree contains machinery as well as content. The marks in
- * `@volter/editor-threejs/adapter/hierarchy-marks` already say which is which — a component
- * WRAPS its functionality and MARKS the implementation it attaches — and the
- * hierarchy panel and the drag rules already read them. Bounds is the third
- * consumer, and it is the one where getting it wrong is visible on screen.
- *
- * The measurement that forced this (2026-08-14, the translated platformer's
- * coins): a component root at `(12, 3, -5)` owning a 0.5 m coin mesh and, as a
- * real child, its three.quarks `BatchedRenderer` with
- * `matrixWorldAutoUpdate = false`. That renderer draws in WORLD space, so its
- * identity `matrixWorld` is deliberate and correct for rendering — but its
- * `VFXBatch` child carries the billboard template geometry, whose bounding box
- * is `(-0.5, -0.5, 0)…(0.5, 0.5, 0)` and, at identity, sits AT THE WORLD
- * ORIGIN. `setFromObject` unioned the two and returned
- * `(-0.5, -0.5, -5.05)…(12.25, 3.25, 0)`: a selection cage stretching from the
- * coin all the way back to the origin, on a coin that is 0.5 m across. The
- * batch contributes that box whether or not a single particle is alive, so the
- * cage was wrong from the first frame.
- *
- * That is the general shape, not a quarks quirk: ANY built-internal child whose
- * world transform its owner writes by hand (`matrixWorldAutoUpdate = false` is
- * the mechanism the marks' own header recommends) sits somewhere the subtree
- * walk has no reason to expect, and pooled machinery routinely carries stale or
- * template-sized geometry. Excluding implementation is the only rule that
- * survives all of them.
- *
- * ## What is NOT excluded
- *
- * Editor furniture is deliberately still measured. `isEditorOwnedObject`
- * matches `userData.engineInternal`, and the splat bounds proxy
- * (`@volter/editor-threejs-runtime/asset-loaders`, `__volter_splat_bounds`) is engine-internal
- * geometry that exists PRECISELY so generic focus/selection bounds can frame a
- * Gaussian splat — a splat renders no `BufferGeometry` of its own. Excluding
- * editor-owned nodes here would silently un-frame every splat. Consumers that
- * want helpers out of their measurement (`_hasBoundableGeometry`, the asset
- * preview's staging) filter for that themselves, on top of this walk.
- *
- * The selected object ITSELF is always measured, even when it is marked. A
- * revealed internals row is selectable, and answering "where is it" with an
- * empty box would be a refusal dressed as a measurement.
- */
+/** Measure world-space content bounds for shared focus and selection consumers. Include editor-owned bound proxies such as Gaussian-splat geometry; callers may filter helpers separately. */
 
-import { isBuiltInternal } from '@volter/editor-threejs/adapter/hierarchy-marks';
 import * as THREE from 'three';
 
 /**
- * Visit `object` and every descendant that is not implementation, top-down.
- *
- * Subtree-scoped, matching the mark's own contract: a marked node is skipped
- * WITH everything under it, so a rig or a pool costs one check rather than one
- * per bone. `object` itself is always visited — see the header.
+ * Visit `object` and every descendant, top-down.
  */
 export function traverseContent(
   object: THREE.Object3D,
   visit: (node: THREE.Object3D) => void,
 ): void {
   visit(object);
-  for (const child of object.children) {
-    if (isBuiltInternal(child)) continue;
-    traverseContent(child, visit);
-  }
+  for (const child of object.children) traverseContent(child, visit);
 }
 
 /** Scratch for one node's transformed geometry box — this module is synchronous
@@ -73,31 +18,7 @@ export function traverseContent(
 const nodeBox = new THREE.Box3();
 const frameMatrix = new THREE.Matrix4();
 
-/**
- * Is this box a measurement at all?
- *
- * `Box3.isEmpty()` compares `max < min`, and EVERY comparison against `NaN` is
- * false — so a box with a non-finite corner reports itself as a real,
- * non-empty box, unions into every consumer, and turns the whole world's
- * extent into `NaN`.
- *
- * That is not hypothetical and it is not the game's fault: a live world holds
- * transforms that are not numbers yet. Measured on the racing-game mount
- * (2026-08-15) — two of its meshes sit at `quaternion = (NaN, NaN, NaN, NaN)`
- * while the game is PAUSED at frame zero, because a physics binding reads its
- * worker's buffers before the worker has ever answered. The editor mounts an
- * ingested game paused, so that is the exact state the first look measures.
- * One such node poisoned all 71 boxes: the framing refused (`isEmpty()` false,
- * fit distance `NaN`), the game-camera seed refused (`radius` `NaN`), and the
- * Scene tab opened on the editor's boot pose — inside canyon geometry, a
- * full-bleed rectangle of rock.
- *
- * The clip planes already made this decision for themselves
- * (`viewport-clip-planes.ts`: "a camera whose bounds could not be measured
- * must still draw"). Dropping the node HERE is the same decision made once, at
- * the measurement, so framing, clipping and the selection cage all get the
- * finite answer instead of each guarding separately.
- */
+/** Reject non-finite corners before unioning a bounds box. Box3.isEmpty alone does not reject NaN, which would contaminate every derived extent. */
 function isFiniteBox(box: THREE.Box3): boolean {
   return (
     Number.isFinite(box.min.x) &&
@@ -113,29 +34,7 @@ function isFiniteBox(box: THREE.Box3): boolean {
 const instanceMatrix = new THREE.Matrix4();
 const instanceBox = new THREE.Box3();
 
-/**
- * Union an `InstancedMesh`'s OWN drawn units into `target`, in world space.
- *
- * **Why not the object-level `boundingBox` three's own rule prefers here:
- * `InstancedMesh.computeBoundingBox()` CACHES, and instanced content MOVES.**
- * `boundingBox` starts `null`, is filled on the first request, and is never
- * recomputed — three's docs say so outright ("You may need to recompute the
- * bounding box if an instance is transformed"). A trail system that rewrites
- * every instance matrix each frame (the racing-game's `Dust`/`Skid`) is
- * therefore measured forever at whatever pose the editor first happened to ask
- * about, and the per-frame selection cage — which exists to be glued to the
- * thing — is glued to where the content USED to be. Nothing invalidates that
- * cache, because nothing in the game's code knows the editor is looking.
- *
- * So the union is taken from the instance matrices as they stand, per call. The
- * per-instance finite filter is the same decision {@link isFiniteBox} makes one
- * level up and for the same reason: a live world holds transforms that are not
- * numbers yet, and one such unit would otherwise turn the node's whole box into
- * `NaN` — which `isEmpty()` cannot see.
- *
- * Cost is O(count) per call, which is exactly what `computeBoundingBox` costs;
- * the callers that pay it per frame are scoped to the selection.
- */
+/** Union each InstancedMesh unit from its current instance matrix and geometry bounds. Skip non-finite instances instead of relying on the mesh’s cached box. */
 function expandByInstances(
   target: THREE.Box3,
   node: THREE.InstancedMesh,
@@ -157,16 +56,9 @@ function expandByInstances(
 /**
  * Union `node`'s OWN renderable extent into `target`, ignoring its children.
  *
- * The object-level `boundingBox` (SkinnedMesh / BatchedMesh, which account for
- * skinning and draw ranges) takes precedence over the shared geometry's, exactly
- * as three's own `Box3.expandByObject` decides it. We cannot call that method —
- * it walks children, which is the whole thing this module exists to control — so
- * the per-node half is spelled here, over three's public `boundingBox` /
- * `computeBoundingBox` API. Same shape as `model-thumbnail.ts`'s
- * `modelPreviewBounds`, which already needed a filtered walk for its own reason.
- *
- * `InstancedMesh` is the one node three's own rule gets wrong for a LIVE world;
- * see {@link expandByInstances}.
+ * SkinnedMesh uses its geometry's bind-pose box; instanced meshes expand each unit.
+ * Other objects use their own boundingBox when available, then the geometry's box.
+ * The caller controls descendant traversal and editor-helper filtering.
  */
 function expandByNodeGeometry(
   target: THREE.Box3,
@@ -202,21 +94,7 @@ function localRenderableBox(
     boundingBox?: THREE.Box3 | null;
     computeBoundingBox?: () => void;
   };
-  // An InstancedMesh's own `boundingBox` already has the instance matrices
-  // baked in, so it is the GEOMETRY box that `expandByInstances` needs.
-  //
-  // A SkinnedMesh is measured by its GEOMETRY (bind-pose) box, and its
-  // mesh-level cache is deliberately never touched. `computeBoundingBox()` on
-  // a SkinnedMesh runs the CPU skinning path, and on the humanoid rigs it
-  // yields bone-WORLD-contaminated "local" bounds (measured live on the
-  // hosted editor: local box z≈7.8..8.2 for a body whose matrixWorld already
-  // carries z=8). Three CACHES that box on the mesh, and `SkinnedMesh.raycast`
-  // then uses it as an early-out gate against the LOCALIZED ray — so the one
-  // framing/thumbnail pass that touched a character made it click-through
-  // FOREVER: rays hit the floor behind while the body rendered right under
-  // the cursor (the enemy-torso click that selected the jump pad ten units
-  // behind it). The bind-pose box is the honest edit-mode answer here anyway
-  // — edit mode shows the authored pose.
+  // Use geometry bounds for instanced units and the bind-pose box for SkinnedMesh. Leave skinned mesh-level caches untouched so raycasting does not inherit bone-world-space bounds.
   if ((node as THREE.SkinnedMesh).isSkinnedMesh) {
     if (geometry.boundingBox === null) geometry.computeBoundingBox();
     return geometry.boundingBox;
@@ -256,12 +134,7 @@ const collectBox = new THREE.Box3();
  */
 export interface ContentNodeRecord {
   readonly box: THREE.Box3;
-  /**
-   * Every material on this mesh has `depthWrite === false`. That is the
-   * authored "I am a volume, not a body" flag — measured on the lighthouse
-   * beam (`transparent`, `opacity: 0.16`, `depthWrite: false`) and absent
-   * from every body mesh of that prefab and of an opaque hull.
-   */
+  /** Whether every material disables depthWrite, identifying a volume rather than an opaque body for this bounds walk. */
   readonly overlay: boolean;
   /**
    * Every material on this mesh is `BackSide`. That is the authored
@@ -296,14 +169,12 @@ export function nodeIsEnclosure(node: THREE.Object3D): boolean {
  * The union answers "how big is this world"; framing needs "where is this
  * world's content", and those are different questions the moment a world has a
  * backdrop — one skybox sphere or one far prop moves the union and moves
- * nothing else (`scene-framing.ts` has the measurement). Only nodes that
+ * nothing else. Only nodes that
  * actually draw contribute a box, so groups, lights and cameras add nothing to
  * the distribution.
  */
-export function collectContentNodeRecords(
-  object: THREE.Object3D,
-  out: ContentNodeRecord[] = [],
-): ContentNodeRecord[] {
+export function collectContentNodeRecords(object: THREE.Object3D): ContentNodeRecord[] {
+  const out: ContentNodeRecord[] = [];
   traverseContent(object, (node) => {
     node.updateWorldMatrix(false, false);
     collectBox.makeEmpty();

package/src/viewport/editor-layers.ts

@@ -14,35 +14,13 @@ export const EDITOR_LAYER = 31;
 export const EDITOR_SELECTION_LAYER = 30;
 
 /**
- * True when this object is the EDITOR'S OWN furniture rather than game content.
- *
- * There are two marking conventions in this codebase and neither one covers
- * everything: the viewport's constructor-time furniture (`GridHelper`, the
- * editor ambient/directional lights, the three.quarks `BatchedRenderer`, the
- * TransformControls helper, the pivot dummy, the snap indicators) is marked
- * ONLY with `layers.set(EDITOR_LAYER)`, while helpers added later
- * (skeleton/physics/crowd/component gizmos) are marked ONLY with
- * `userData.editorHelper`. A walk that checks one convention silently presents
- * the other half as game content.
- *
- * That is the SimCity ledger's S-1 hierarchy defect: `projectThreeScene`
- * checked only the userData flags, so when an ingest mount FAILED — leaving
- * `store.scene` pointed at the editor viewport scene instead of a captured game
- * scene — the hierarchy listed the editor's own grid, lights, BatchedRenderer,
- * gizmo helper, pivot dummy and two snap indicators under the game world's id.
- * A dead game was indistinguishable from a live one.
- *
- * This is the SAME predicate the engine's ingest walk already applies
- * (`@volter/editor-threejs-runtime/adapter/ingest/structural-ids`'s `isEditorOnly`, layer half) plus
- * the userData half `viewport-shading-boundary.ts` applies — stated once here
- * so the two halves can never drift apart again.
+ * Identify editor furniture through either EDITOR_LAYER or the editorHelper userData mark.
+ * Constructor-time viewport objects and dynamically added helpers use these complementary marks;
+ * hierarchy, capture and export filters must recognize both.
  */
 export function isEditorOwnedObject(object: THREE.Object3D): boolean {
   return (
-    // Read the public mask, which has existed for the full three.js range the
-    // ingest devtools hook supports. `Layers.isEnabled()` is newer than r129:
-    // calling it rejected an otherwise healthy Cuberun capture before the
-    // hierarchy could mount.
+    // The public layer mask identifies editor-only infrastructure.
     (object.layers.mask & (1 << EDITOR_LAYER)) !== 0 ||
     !!getObjectMark(object, 'editorHelper') ||
     !!getObjectMark(object, 'engineInternal')

package/src/viewport/environment.ts

@@ -28,7 +28,7 @@ export function createStandardEnvironment(renderer: THREE.WebGLRenderer): Standa
 }
 
 /**
- * An environment image (`@volter/sdk/kit/environment-images`) as an equirectangular
+ * An environment image (`@volter/sdk/environment-images`) as an equirectangular
  * texture in scene-referred light. Read as half float: a sun past white stays bright, and half
  * float filters linearly where full float cannot (phones).
  */

package/src/viewport/preview-renderer.ts

@@ -1,40 +1,9 @@
 /**
- * The WebGL renderer the INSPECTOR-PREVIEW lane draws through — one per editor
- * session, not one per selection.
- *
- * Why this module exists (measured, 2026-08-07): every chromeless preview
- * (`components/InspectorObjectPreview.tsx` → `Object3DSnapshotDocument` →
- * `Object3DDocumentViewport`) used to construct its own
- * `THREE.WebGLRenderer` on mount, so SELECTING A THING built a whole GL stack.
- * A renderer's constructor is a long chain of synchronous driver round trips
- * (`WebGLCapabilities`/`getExtension`/`getParameter`), and its program cache
- * starts empty, so every selection also recompiled the subject's shaders and
- * re-baked the PMREM environment. A click profiled at ~1.9 s of frozen main
- * thread, 3.5 s of self time in `gl.getParameter` alone. Sharing one renderer
- * removes the construction entirely and lets the program cache and the IBL
- * bake survive across selections.
- *
- * OWNERSHIP — the one place it is stated:
- *  - This module OWNS every canvas, `WebGLRenderer` and baked
- *    {@link StandardEnvironment} it creates. Nothing else may dispose them.
- *  - SHARERS are lease holders: {@link acquireInspectorPreviewRenderer} hands
- *    out a lease, the holder mounts `lease.canvas` in its own container and
- *    draws through `lease.renderer` for as long as it is mounted.
- *  - The ONE teardown path a holder has is {@link InspectorPreviewLease.release}
- *    — it returns the renderer to the pool (or disposes it, if it was an
- *    overflow lease that the pool does not keep). A holder never calls
- *    `renderer.dispose()`, and never disposes `lease.environment()`, whose
- *    handle is deliberately non-owning.
- *  - Per-selection SCENE resources (the snapshot's skeletons, the dressing's
- *    lights/grid/backdrop) stay the holder's, exactly as before: three's
- *    program cache lives on the renderer and is not touched by disposing the
- *    materials that populated it.
- *
- * Capacity is deliberately small. The inspector shows ONE live preview at a
- * time by construction (`InspectionProjection.tsx` drops the disc to its glyph
- * while the preview panel is open), so a second entry is slack for a handover
- * frame, and anything beyond that is a transient renderer disposed on release
- * rather than a growing pool.
+ * Lease pooled WebGL renderers for Inspector previews so program caches and environment bakes
+ * survive selection changes. This module owns each canvas, renderer and StandardEnvironment;
+ * holders mount and draw through the lease, then release it without disposing those shared
+ * resources. Per-selection scene resources belong to the holder. Keep a small idle pool and dispose
+ * overflow renderers on release.
  */
 
 import * as THREE from 'three';
@@ -108,15 +77,8 @@ function disposeEntry(entry: PreviewRendererEntry): void {
   entry.environment?.dispose();
   entry.environment = null;
   entry.renderer.dispose();
-  // `dispose()` frees GPU RESOURCES; it does not give the CONTEXT back. The
-  // canvas holds it until garbage collection decides otherwise, and WebGL
-  // contexts are a hard ~16-per-page budget the browser enforces by killing
-  // the OLDEST — which is the main viewport, so the symptom is a white
-  // viewport and "too many active WebGL contexts" far from the cause
-  // (runhuman pass 104). Every other renderer owner in this editor already
-  // pairs the two (`asset-preview.ts`, `components/world-root-stage.ts`); this
-  // shared pool did not, and it backs both the Inspector preview and the
-  // Object3D tool's viewport, so its transients leaked a context each.
+  // Release the WebGL context as well as GPU resources so discarded previews do not consume the
+  // browser’s context budget.
   entry.renderer.forceContextLoss();
   entry.canvas.remove();
 }

package/src/viewport/renderer-ownership.ts

@@ -1,67 +1,23 @@
 /**
- * The set of `WebGLRenderer`s the editor-side Three integration owns — its viewport, and every
- * offscreen renderer it spins up for thumbnails, asset previews and asset
- * compare.
- *
- * Why this exists: ingest's scene-capture trap
- * (`@volter/editor-threejs-runtime/adapter/ingest/scene-capture`) is installed on the SHARED
- * `three.WebGLRenderer.prototype` — that sharing is the whole mechanism, it is
- * how an unmodified game's renderer gets instrumented without touching the
- * game's source. But it means the editor's own renders arrive at the trap too,
- * and the trap captures the first scene it sees. Any host renderer constructed
- * after the trap installs (a thumbnail bake, an asset preview) could therefore
- * be captured AS THE INGESTED GAME.
- *
- * That is not hypothetical: it is what made the "a game bundling its own three
- * is DETECTED, never silently mistaken for a capture" spec pass or fail on
- * timing alone. When it failed, the editor
- * had adopted its own thumbnail scene as the game: a hierarchy of the editor's
- * own lights, presented as the game's content.
- *
- * Marking is explicit at each construction site rather than inferred, because
- * the honest question ("did the HOST make this renderer?") has no reliable
- * signal at the trap: a host renderer and a game renderer are the same class,
- * both constructed after install, and both render real scenes.
- */
-
-const _hostRenderers = new WeakSet<object>();
-
-/** Record `renderer` as the editor's own. Returns it, so it can wrap a `new`. */
-/**
- * WebGL contexts are a HARD, SMALL browser budget (order of sixteen per page),
- * and this is the one chokepoint every editor-constructed renderer passes
- * through — so it is where an editor that is quietly accumulating them can be
- * caught naming its own culprit.
- *
- * A tester adding and deleting prefabs hit "too many active WebGL contexts"
- * after five rounds and the whole viewport turned white, because the browser
- * evicts the OLDEST context when the limit is reached and the oldest is the
- * main viewport (runhuman pass 104). Three's warning comes from inside
- * `three.module.js` and names nothing about who asked, which is what made it
- * undiagnosable from the report.
- *
- * The count is LIVE: `dispose()` is wrapped so a renderer that is properly
- * torn down stops counting. Past the budget the warning carries the creating
- * stack, so the next sighting names the leak instead of the victim.
+ * Count live WebGLRenderers owned by the editor’s three.js integration, including offscreen
+ * previews. Wrapped dispose calls decrement the count. Warn with the creating stack near the
+ * browser’s context budget so the renderer owner can be located.
  */
 const LIVE_RENDERER_WARN_AT = 8;
 let liveHostRenderers = 0;
 
-export function markHostRenderer<T extends object>(renderer: T): T {
-  _hostRenderers.add(renderer);
+/** Count `renderer` as the editor's own. Returns it, so it can wrap a `new`. */
+export function markHostRenderer<T extends { dispose(): void }>(renderer: T): T {
   liveHostRenderers += 1;
-  const disposable = renderer as { dispose?: () => void };
-  const dispose = disposable.dispose;
-  if (typeof dispose === 'function') {
-    let counted = true;
-    disposable.dispose = function wrappedDispose(this: unknown, ...args: unknown[]) {
-      if (counted) {
-        counted = false;
-        liveHostRenderers -= 1;
-      }
-      return (dispose as (...a: unknown[]) => unknown).apply(this, args);
-    } as () => void;
-  }
+  const dispose = renderer.dispose;
+  let counted = true;
+  renderer.dispose = function wrappedDispose() {
+    if (counted) {
+      counted = false;
+      liveHostRenderers -= 1;
+    }
+    dispose.call(this);
+  };
   if (liveHostRenderers >= LIVE_RENDERER_WARN_AT) {
     // biome-ignore lint/suspicious/noConsole: the standing warning channel for a budget the browser enforces by destroying the viewport
     console.warn(
@@ -80,7 +36,3 @@ export function liveHostRendererCount(): number {
   return liveHostRenderers;
 }
 
-/** True when `renderer` is one the editor constructed for its own rendering. */
-export function isHostRenderer(renderer: unknown): boolean {
-  return typeof renderer === 'object' && renderer !== null && _hostRenderers.has(renderer);
-}

package/src/viewport-api.ts

@@ -1,21 +1,11 @@
 /**
  * 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, every mounted stage, and the one verb that swaps the viewport's subject for a live
- * instance's roots (Play's adoption of the running scene).
+ * shows and every mounted stage.
  */
-import type { MountedRoot } from '@volter/project/adapter/root-adapter';
 import type * as THREE from 'three';
 import type { StageFrameCostReading } from '@volter/sdk';
 
-/** A live instance's roots, presented as the authored viewport's subject. */
-export interface ViewportPresentation {
-  /** The root whose native subject the viewport shows. */
-  readonly worldId: string;
-  /** Restores the viewport's prior subject; idempotent. */
-  dispose(): void;
-}
-
 /** What a frame of a stage costs, uncapped ({@link ViewportRig.frameCost}): the wire's reading
  *  without the stage's id, which the door adds. */
 export type StageFrameCost = Omit<StageFrameCostReading, 'stage'>;
@@ -32,15 +22,20 @@ export interface ViewportRig {
    * `requestAnimationFrame`, each waited out on the GPU, so the number is the frame's cost and
    * not the display's refresh. Absent on a stage with no frame of its own.
    */
-  frameCost?(frames: number, quality?: 'full' | 'navigation'): StageFrameCost;
+  frameCost?(frames: number, quality: 'full' | 'navigation'): StageFrameCost;
   readonly orbit: { readonly target: THREE.Vector3; enabled: boolean; update(): void };
+  /** While `owned`, the stage leaves the camera's projection (its clip planes) to whoever drives it:
+   *  a running game. Absent on a stage that never fits its planes. */
+  readonly projection?: { owned: boolean };
   /** The editor's own scene (helpers live on its editor layer). */
   readonly scene: THREE.Scene;
+  /** The stage's one renderer, for a binding that draws a document's content into this stage's scene through it. */
+  readonly renderer: THREE.WebGLRenderer;
 }
 
 /**
  * ONE MOUNTED 3D STAGE, named by the document it draws. Every 3D document
- * mounts a stage of its own (ARCHITECTURE-CORE §One stage); this is the door
+ * 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.
  */
@@ -56,16 +51,13 @@ export interface ViewportStage {
 
 /**
  * THE AUTHORED VIEWPORT, as a lane that mounts something reaches it: the rig
- * a camera flight drives, the frame loop it rides, and the one verb that
- * swaps the viewport's subject for a live instance's roots (Play's adoption
- * of the running scene). 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.
+ * 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 stage presenting live
- * roots if one is, else the FOCUSED stage, else the first bound. A camera
- * flight and Play's adoption want exactly that one, which is why they read
- * here and never enumerate.
+ * 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.
  *
  * {@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
@@ -73,19 +65,8 @@ export interface ViewportStage {
  * `onStages` is how a lane keeps up with stages that mount and unmount after
  * it made that pass.
  */
-/** A mounted adapter surface offered to the viewport. Execution, input and
- * ticking stay with the caller; presentation requires only identity and mount.
- * A game's richer root instance can satisfy this interface directly.
- */
-export interface ViewportRoot {
-  readonly id: string;
-  readonly mounted: MountedRoot;
-}
-
 export interface ViewportDoor {
   rig(): ViewportRig | null;
-  /** Null when the viewport has no subject among `roots` (no Three root). */
-  presentRoots(roots: readonly ViewportRoot[]): ViewportPresentation | null;
   /** Runs after the viewport's own per-frame update; the return unsubscribes. */
   onFrame(fn: (dtSeconds: number) => void): () => void;
   /**