@volter/editor-threejs 0.5.211 → 0.5.212

package/src/kit/authoring/shell-viewport-policy.ts

@@ -2,47 +2,41 @@
  * THE SHELL'S ANSWERS to `ViewportAuthoringPolicy` — the composition the
  * editor installs at boot (`EditorContext.tsx`'s `EditorProvider`).
  *
- * Every member here is a one-line delegation to the module that already owned
- * that answer. Nothing moved and nothing was reimplemented: the point of the
- * seam is only that `editor-viewport.ts` no longer imports these modules, so
+ * Every member here is a one-line delegation to the module that owns that
+ * answer. The point of the seam is only that `editor-viewport.ts` does not
+ * import these modules, so
  * the gizmo viewport does not carry the composite adapter, the workspace
  * document registry, or the layered-pick walk in its own closure
- * (ARCHITECTURE-CORE §Editor chrome, "the viewport stack is separable").
+ *.
  *
  * This file is the shell side of that boundary and is free to import all of
  * them.
  */
 
 import type { ViewportAuthoringPolicy } from '../viewport-authoring-policy';
-import { getActiveAuthoring } from '@volter/sdk/kit/authoring/active-adapter';
-import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
-import { pickTopmost } from '@volter/sdk/kit/authoring/layered-pick';
-import { resolvePanelAuthoring } from '@volter/sdk/kit/authoring/panel-authoring';
-import { isViewportToolContextVisible, resolveViewportToolContext } from '@volter/sdk/kit/authoring/viewport-tool-context';
-import {
-  applyRootHiddenVisibility,
-  isThreejsSurfaceVisible,
-  resolveThreeViewportRootId,
-  suppressRootEnvironment,
-} from './world-hidden-viewport';
+import { getActiveAuthoring } from '@volter/sdk/authoring/active-adapter';
+import { CompositeAuthoringAdapter } from '@volter/sdk/authoring/composite-authoring-adapter';
+import { pickTopmost } from '@volter/sdk/authoring/layered-pick';
+import { resolvePanelAuthoring } from '@volter/sdk/authoring/panel-authoring';
+import { isViewportToolContextVisible, resolveViewportToolContext } from '@volter/sdk/authoring/viewport-tool-context';
+import { isStageVisible, resolveStageRootId } from '@volter/sdk/authoring/stage-root';
+import { applyRootHiddenVisibility, suppressRootEnvironment } from './world-hidden-viewport';
 
 export const SHELL_VIEWPORT_AUTHORING_POLICY: ViewportAuthoringPolicy = {
   activeAuthoring: (store) => getActiveAuthoring(store),
   panelAuthoring: (store) => resolvePanelAuthoring(store).adapter,
   pick: (store, clientX, clientY, intent) => pickTopmost(store, clientX, clientY, { intent }),
   toolOwner: (adapter, selectedIds) => resolveViewportToolContext(adapter, selectedIds),
-  // Both halves of "is this owner painted here" — visibility says a three
-  // surface is drawn at all, selection ownership says it is the world being
-  // edited. The viewport ANDs the result with `kind === 'three'`, exactly as it
-  // did when it called these two itself.
+  // Require both a visible three.js surface and ownership by the world being edited. The viewport
+  // also gates this result on a stage surface.
   toolOwnerPainted: (store, owner) =>
-    isThreejsSurfaceVisible(store) && isViewportToolContextVisible(store, owner),
+    isStageVisible(store) && isViewportToolContextVisible(store, owner),
   threeSurfaceShowing: (store, adapter) =>
-    isThreejsSurfaceVisible(store) &&
+    isStageVisible(store) &&
     (adapter instanceof CompositeAuthoringAdapter
-      ? adapter.childAdapters().some((child) => child.kind === 'three')
-      : !adapter.rects && typeof adapter.hierarchy.object3D === 'function'),
-  threeViewportRootId: (store) => resolveThreeViewportRootId(store),
+      ? adapter.childAdapters().some((child) => child.kind === 'stage')
+      : !adapter.rects && typeof adapter.hierarchy.nativeObject === 'function'),
+  threeViewportRootId: (store) => resolveStageRootId(store),
   applyRootHiddenVisibility,
   suppressRootEnvironment,
 };

package/src/kit/authoring/source-object3d-authoring-adapter.ts

@@ -178,23 +178,7 @@ export class SourceObject3DAuthoringAdapter implements AuthoringAdapter {
     });
   }
 
-  // ------------------------------------------------ graph mutated after mount
-  //
-  // The constructor's walk is a snapshot of the graph AT MOUNT, and one class
-  // of document mutates its graph afterwards: the live module document
-  // (`components/asset-viewers/LiveModuleDocument.tsx`) keeps a stable
-  // container root and SWAPS ITS CHILD on every save, precisely so the
-  // viewport's camera survives a rebuild. Measured 2026-08-29: the viewport
-  // showed the rebuilt model while the hierarchy kept the mount-time walk, so
-  // the document row lost its child and the picker addressed a disposed
-  // object.
-  //
-  // The fix is `r3f-source-authoring-adapter.ts`'s, transcribed: re-index on
-  // the GRAPH'S OWN structural events. `parent.add(child)` dispatches
-  // `childadded` on the parent, so watching the scene plus every indexed
-  // object covers every path a subtree can enter through, and no document has
-  // to remember to tell this adapter anything. Editor furniture (gizmo and
-  // helper attachments) is filtered so selection churn does not re-index.
+  // Re-index a live module’s stable root when its child graph changes. Ignore editor helpers so gizmo and selection attachments do not trigger another walk.
 
   private disposed = false;
   dispose(): void {
@@ -299,7 +283,7 @@ export class SourceObject3DAuthoringAdapter implements AuthoringAdapter {
     return label;
   }
 
-  readonly hierarchy: HierarchyProvider = {
+  readonly hierarchy: HierarchyProvider & Required<Pick<HierarchyProvider, 'nativeObject' | 'idForNativeObject'>> = {
     roots: () => [this.hierarchy.node(this.documentNodeId)!],
     node: (id) => {
       if (id === this.documentNodeId) {
@@ -323,8 +307,8 @@ export class SourceObject3DAuthoringAdapter implements AuthoringAdapter {
       const object = this.byId.get(id);
       return object ? this.view.node(object) : null;
     },
-    object3D: (id) => this.byId.get(id) ?? null,
-    idForObject3D: (object: THREE.Object3D) => this.idByObject.get(object) ?? null,
+    nativeObject: (id) => this.byId.get(id) ?? null,
+    idForNativeObject: (object: THREE.Object3D) => this.idByObject.get(object) ?? null,
   };
 
   readonly selection: SelectionProvider = {
@@ -345,33 +329,7 @@ export class SourceObject3DAuthoringAdapter implements AuthoringAdapter {
   private static readonly READ_ONLY_REASON =
     'This document shows what the module builds; its properties are read-only here. Edit the module.';
 
-  /**
-   * READ-ONLY, AND IT SAYS SO NOW. Every write door on this adapter is a
-   * no-op and always was — `transforms.beginEdit`/`apply`/`endEdit` below and
-   * `inspector.set` further down all return `undefined` — but it declared no
-   * `editability`, which is the seam the shell asks BEFORE drawing a control
-   * (`InspectorProvider.editability`'s own contract names "hierarchy eye/lock
-   * controls"). Its default is `{ writable: true }`, so the shell believed
-   * this projection and drew a live control over a surface that discards it.
-   *
-   * MEASURED 2026-09-19 in a cold models scaffold, which is what bought this:
-   * the Outliner's EYE on a Model document lit, kept its `Hide` tooltip and
-   * its `aria-pressed="false"`, and left the frame hash byte-identical —
-   * `GameHierarchy.tsx` gates it on `visibleKnown && (editability?.writable ??
-   * true)`, and `visible` is knowable here (it reads `object.visible`) even
-   * though it is `readonly: true` in the very descriptor list below.
-   *
-   * `transforms` DELIBERATELY DOES NOT GET ONE, and that is a measurement
-   * rather than an oversight. Its write doors are no-ops too, so the honest
-   * answer is the same — but declaring it bought nothing and cost a mark:
-   * `transform-mode-request.ts`, the one place that would have NAMED the
-   * refusal, reads `store.selectedEntityIds` off the SHELL store while a
-   * document stage keeps its selection in its own, so it returns before it
-   * can speak and the host's Move/Rotate/Scale stayed silent either way —
-   * while `GameHierarchy`'s `hierarchy-transform-lock` span immediately
-   * appeared on every row, a glyph Blender's Outliner does not draw. Answer
-   * it when something acts on the answer.
-   */
+  /** This source projection is read-only. Expose editability where the shell consumes it instead of advertising writes the adapter discards. */
   private readonly readOnly = (): { writable: boolean; reason: string } => ({
     writable: false,
     reason: SourceObject3DAuthoringAdapter.READ_ONLY_REASON,
@@ -502,7 +460,7 @@ export class SourceObject3DAuthoringAdapter implements AuthoringAdapter {
   }
 
   get documentRootObject(): THREE.Object3D | null {
-    const rootId = this.hierarchy.node(this.documentNodeId)?.childIds[0];
+    const rootId = this.hierarchy.node(this.documentNodeId)!.childIds[0];
     return rootId ? (this.byId.get(rootId) ?? null) : null;
   }
 

package/src/kit/authoring/three-projection-core.ts

@@ -1,30 +1,8 @@
 /**
- * THE SHARED LIVE-`Object3D` AUTHORING PROJECTION — the derived views every
- * three-surface configuration reads instead of spelling for itself.
- *
- * The layer below is `../projection/three.ts`: it owns the walk, identity
- * minting, the two-way index and picking. This module owns what sits ON that
- * index and used to be duplicated across the configurations — the
- * transparent-wrapper collapse view (`CollapsedHierarchyView`), the transform
- * READ ({@link readLocalTransform}) and the store-selection adoption
- * ({@link StoreSelectionAdoption}).
- *
- * PICKING and BOUNDS are not here because they were never duplicated:
- * `ThreeProjector.pick`/`candidates` is already the one raycast, and
- * `@volter/editor-threejs/viewport/content-bounds` is the bounds walk. Duplicating either would
- * be a hop, not an extraction.
- *
- * The configurations are `three-authoring-adapter.ts` (play adoption and
- * every ingest mount), `r3f-source-authoring-adapter.ts` (edit write-back) and
- * `source-object3d-authoring-adapter.ts` (a native graph opened as a document).
- * They differ by IDENTITY PROVIDER and WRITE TARGET, never by where their graph
- * came from; `three-projection-inventory.test.ts` is the census that keeps it
- * that way.
- *
- * What is deliberately NOT here: the R3F lane's COMPONENT-INSTANCE collapse
- * (`isComponentBoundary` and the owner chain). That rule answers a different
- * question — which callsite rendered this — and merging it with the rule below
- * would be inventing a third, not extracting a shared one.
+ * Shared derived views over the live Object3D projection: transparent-wrapper collapse,
+ * local-transform reads and store-selection adoption. projection/three.ts owns graph traversal,
+ * identity, the two-way index and picking; viewport/content-bounds owns bounds. The source document
+ * adapter chooses identity and write targets.
  */
 
 import type { EditorNode, Transform } from '@volter/project/adapter';
@@ -32,7 +10,7 @@ import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-laye
 import { object3DAuthoringSubjectOf } from '@volter/editor-threejs/adapter/object3d-authoring-subject';
 import { getUserData } from '@volter/editor-threejs/ecs/user-data';
 import type * as THREE from 'three';
-import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import type { ShellStore } from '@volter/sdk/shell-store';
 import { nativeKindOf, type ThreeProjector } from '../projection/three';
 import { localTransformOf } from './live-object-transform';
 
@@ -46,7 +24,7 @@ export interface StoreSelectionAdoptionOptions {
   /** Runs with the OWNED ids whenever the adopted set changes, in either
    *  direction. The Object3D-document configuration drives its nodes'
    *  `selectionChanged` marks from here. */
-  readonly onChange?: (ids: readonly string[]) => void;
+  readonly onChange: (ids: readonly string[]) => void;
 }
 
 function sameIds(a: readonly string[], b: readonly string[]): boolean {
@@ -54,14 +32,8 @@ function sameIds(a: readonly string[], b: readonly string[]): boolean {
 }
 
 /**
- * SELECTION, shared between the store and a configuration's own answer.
- *
- * `EditorViewport`'s additive/toggle paths mutate `ShellStore` directly
- * rather than going through the adapter, so a `SelectionProvider` that only
- * remembered what it was last told drifted from what the viewport had drawn.
- * Reading the store on every `get` is what keeps the hierarchy, the Inspector
- * and the viewport agreeing; comparing against the last adopted ids is what
- * stops that read from re-notifying on every render.
+ * Read selection from the store so direct viewport additive and toggle operations remain visible to
+ * the adapter. Compare with the last adopted ids to avoid notifying again on unchanged reads.
  */
 export class StoreSelectionAdoption {
   /** The store ids last adopted or published — the comparison basis. */
@@ -78,7 +50,7 @@ export class StoreSelectionAdoption {
     if (!sameIds(storeIds, this.adopted)) {
       this.adopted = storeIds;
       this.selected = storeIds;
-      this.options.onChange?.(storeIds);
+      this.options.onChange(storeIds);
     }
     return [...this.selected];
   }
@@ -92,7 +64,7 @@ export class StoreSelectionAdoption {
     this.selected = [...selected];
     const storeIds = this.selected.filter(this.options.owns);
     this.adopted = storeIds;
-    this.options.onChange?.(storeIds);
+    this.options.onChange(storeIds);
     this.options.store.selectMultiple(storeIds);
   }
 }
@@ -137,8 +109,7 @@ export function isTransparentWrapper(object: THREE.Object3D): boolean {
     object3DAuthoringSubjectOf(object) === null &&
     object.userData['oid'] === undefined &&
     getUserData(object, 'authoringInstance') === undefined &&
-    getUserData(object, 'authoringRoot') !== true &&
-    getUserData(object, 'volterComponentRoot') === undefined
+    getUserData(object, 'authoringRoot') !== true
   );
 }
 

package/src/kit/authoring/viewport-pick-context.ts

@@ -1,17 +1,10 @@
 /**
- * Viewport pick context (B4, D12) — the camera/canvas seam that
- * `VolterSceneAuthoringAdapter.pickable.pick` needs but cannot own itself: both
- * live on `EditorViewport`, not on the adapter (the adapter only ever held a
- * `store` — see its own doc comment). A tiny module-level slot, same shape as
- * `./active-systems.ts`: `EditorViewport`'s constructor sets it once its
- * camera/canvas exist; its `dispose()` clears it.
- *
- * Absent (module load, a headless unit test that builds the adapter with no
- * live viewport, or after `dispose()`) ⇒ `pick()` returns `null` — an honest
- * degrade, never a throw.
+ * Camera, canvas and editor controls for adapter raycasting, owned by EditorViewport. A viewport
+ * configured to publish its context installs it after construction and clears it on disposal.
+ * Before a viewport binds or after it is disposed, picking has no context and returns null.
  */
 
-import { setViewportEditorControls, type ViewportEditorControls } from '@volter/sdk/kit/viewport-editor-controls';
+import { setViewportEditorControls, type ViewportEditorControls } from '@volter/sdk/viewport-editor-controls';
 import type * as THREE from 'three';
 
 export interface ViewportPickContext {
@@ -21,7 +14,7 @@ export interface ViewportPickContext {
    * target/pole effectors). The full-cover selection overlay owns pointer
    * events in the project viewport, so it forwards them through this narrow
    * seam instead of duplicating Three raycasting or constraint semantics. */
-  readonly editorControls?: ViewportEditorControls;
+  readonly editorControls: ViewportEditorControls;
 
 }
 

package/src/kit/authoring/viewport-raycast.ts

@@ -1,29 +1,9 @@
 /**
- * Shared three viewport raycast pick (B4, D12) — the adapter-AGNOSTIC
- * entity-under-the-pointer raycast, extracted verbatim from
- * `editor-viewport.ts`'s former `_raycastEntity` so EVERY threejs-backed
- * authoring adapter whose live objects sit in `store.objectMap` reuses the
- * exact same logic:
- *   - first-party `VolterSceneAuthoringAdapter` (edit mode's focused world),
- *   - `ThreeAuthoringAdapter` (any live three tree — bare ingest
- *     mode AND the three child of a multi-world PLAY composite).
- *
- * Pre-B4, `_onPointerUp` ran this raycast UNCONDITIONALLY against
- * `store.objectMap` regardless of which adapter was active, so an ingest/
- * multi-world-play canvas click selected the object under the pointer. B4's
- * `pickTopmost` routes through the active adapter's `pickable` instead, so
- * that behavior only survives if each three adapter exposes a `pickable`
- * backed by THIS helper (the raycast depends
- * only on native Object3Ds plus the active adapter's object→id answer. The
- * default still reads `store.objectMap` and entity stamps for first-party
- * callers; foreign adapters inject their projection without mutating it.
- *
- * The camera/canvas live only on `EditorViewport`, reached through the
- * `viewport-pick-context.ts` seam (its ctor/`dispose()` set/clear it). Absent
- * (a headless unit test, or no live viewport mounted) ⇒ `null`, an honest
- * degrade rather than a throw. Uses its OWN `THREE.Raycaster` with
- * `layers.enableAll()` replicated so it hits gizmo-adjacent EDITOR_LAYER-tagged
- * geometry exactly like the original.
+ * Raycast live three.js authoring graphs through the active adapter’s object-to-id lookup. The
+ * default reads store.objectMap and entity stamps; document adapters can supply their projection.
+ * viewport-pick-context supplies the mounted viewport’s camera and canvas. Return null when no
+ * viewport is mounted, and enable all raycast layers to include selectable overlay-adjacent
+ * geometry.
  */
 
 import { isInEditorOwnedSubtree } from '@volter/editor-threejs/viewport/editor-layers';
@@ -36,25 +16,7 @@ function isBackdropMaterial(material: THREE.Material): boolean {
   return material.depthWrite === false && material.side === THREE.BackSide;
 }
 
-/**
- * Is this object the scene's BACKDROP rather than a thing in it?
- *
- * A sky dome / environment shell is painted behind everything
- * (`depthWrite: false`) and is only visible from INSIDE (`side: BackSide`).
- * Both flags are authored by the game itself, so this is the idiom read as
- * DATA — no name list, no per-project rule.
- *
- * Why picking must skip it: such a mesh ENCLOSES the camera, so every ray
- * eventually reaches it and the pick can never miss. Measured live
- * (2026-08-06, `examples/third-person`): all 64 points of an 8×8 grid over the
- * canvas returned a hit, the top-left "empty sky" among them, which is why
- * clicking empty space never cleared the selection — `_onPointerUp`'s
- * `selection.set([])` branch was simply unreachable in any scene with a sky.
- * A ray that reaches the backdrop has passed through every real thing in the
- * scene; that is a MISS, and the surface's no-selection subject is the honest
- * answer. The backdrop stays selectable from the hierarchy, where it is a row
- * like any other.
- */
+/** Skip enclosing backdrops during viewport picking: BackSide meshes with depthWrite false surround the camera and otherwise turn every ray into a hit. Hierarchy selection still reaches them. */
 export function isBackdropObject(object: THREE.Object3D): boolean {
   const material = (object as Partial<THREE.Mesh>).material;
   if (!material) return false;
@@ -63,15 +25,7 @@ export function isBackdropObject(object: THREE.Object3D): boolean {
     : isBackdropMaterial(material);
 }
 
-/** Raycast `store.objectMap` and return the entity id under `(clientX,
- *  clientY)`, or `null`. Skips editor-helper geometry, and skips ids `isLocked`
- *  rejects — identical to the pre-B4 viewport raycast.
- *
- *  `isLocked` is INJECTED rather than read off the store because "locked" is a
- *  per-format notion: an adapter with a lock concept supplies its own check
- *  (own flag OR any ancestor's — richer than what a generic
- *  `inspector.get(id,'locked')` reproduces), while every live/foreign adapter
- *  has no lock concept and omits it. */
+/** Raycast objectMap at client coordinates, skipping helpers and ids rejected by the caller’s format-specific lock predicate. */
 export function raycastCandidates(
   store: EditorShellStore,
   clientX: number,
@@ -79,15 +33,15 @@ export function raycastCandidates(
   isLocked: (id: string) => boolean = () => false,
   projection?: {
     readonly objects: Iterable<THREE.Object3D>;
-    readonly idForObject3D: (object: THREE.Object3D) => string | null;
+    readonly idForNativeObject: (object: THREE.Object3D) => string | null;
   },
 ): string[] {
   const ctx = getViewportPickContext();
   if (!ctx) return []; // no live viewport mounted — honest degrade
   const rect = ctx.canvas.getBoundingClientRect();
   // Chrome and other panes are not part of this viewport. Coverage also asks
-  // about (0,0); previously that off-canvas query still skinned/raycast the
-  // entire world twice after an interaction.
+  // about (0,0), and that off-canvas query must not skin/raycast the entire
+  // world.
   if (
     rect.width <= 0 ||
     rect.height <= 0 ||
@@ -117,15 +71,7 @@ export function raycastCandidates(
     return true;
   });
 
-  // A SkinnedMesh with CACHED mesh-level bounds is a poisoned pick target:
-  // `SkinnedMesh.raycast` gates on `this.boundingBox`/`boundingSphere`, and a
-  // cache computed through the CPU skinning path carries bone-world
-  // contamination on the humanoid rigs — the gate then misses the localized
-  // ray forever and every click falls through the character (measured live:
-  // 0 triangle hits with the cache present, 8 with it cleared, same ray, same
-  // mesh). Clearing here immunizes the pick against every planter; the
-  // raycast recomputes what it needs, and the framing walk no longer consumes
-  // mesh-level skinned bounds at all (`content-bounds.ts`).
+  // Clear cached SkinnedMesh bounds before raycasting so the localized ray is tested against current geometry, not a stale bone-world-space cache.
   for (const root of entityObjects) {
     root.traverse((node) => {
       // Structural write: three's own `SkinnedMesh` fields hold `Box3 | null`
@@ -166,7 +112,7 @@ export function raycastCandidates(
     let eid: string | null = null;
     if (projection) {
       while (cursor && eid === null) {
-        eid = projection.idForObject3D(cursor);
+        eid = projection.idForNativeObject(cursor);
         cursor = cursor.parent;
       }
     } else {
@@ -183,26 +129,7 @@ export function raycastCandidates(
   return hits;
 }
 
-/**
- * A CLICK THAT SELECTS NOTHING SAYS WHY — and only then.
- *
- * Repeated instances of one component are reported unselectable in the
- * viewport while the HIERARCHY addresses every one of them fine (runhuman
- * passes 100/109/110/111: "in order to move the one previous, I need to click
- * it from the hierarchy"). Identity is not the cause — a reproduction over
- * `sourceOidIdentity` mints distinct ids AND distinct stamps for four renders
- * of one definition element — so the failure is somewhere in this walk, and
- * the three numbers below separate its three possible causes:
- *
- *  - `candidates: 0` — the object never reached `store.objectMap`;
- *  - `candidates: N, rayHits: 0` — it is in the map but the ray missed it
- *    (stale transform, detached subtree, wrong scene);
- *  - `rayHits: N, ids: 0` — it was hit but every hit was filtered as editor
- *    furniture/backdrop, or carried no stamp to resolve.
- *
- * Silent on every click that DOES select something, so an ordinary session
- * never sees it.
- */
+/** Report genuine empty viewport picks with candidate, hit and filtered-hit counts to distinguish missing targets from identity and filtering failures. */
 function reportEmptyPick(
   hits: readonly string[],
   candidates: readonly THREE.Object3D[],
@@ -211,12 +138,7 @@ function reportEmptyPick(
   clientY: number,
 ): void {
   if (hits.length > 0) return;
-  // The coverage CONFORMANCE PROBE exercises `editor.pickable.pick(0, 0)` on
-  // a timer to audit the seam's shape (`coverage/authoring-seam-evidence`,
-  // source: "conformance-probe") — twice every ~5s in a live session,
-  // measured by stack capture. (0,0) is over the app chrome, never a real
-  // viewport click, so the probe's synthetic misses must not narrate as user
-  // clicks that selected nothing.
+  // Ignore (0, 0), which the shell uses for a synthetic conformance probe over app chrome.
   if (clientX === 0 && clientY === 0) return;
   // biome-ignore lint/suspicious/noConsole: diagnostic breadcrumb, same channel as the editor's other timing/stall notes
   console.info(
@@ -233,7 +155,7 @@ export function raycastPick(
   isLocked: (id: string) => boolean = () => false,
   projection?: {
     readonly objects: Iterable<THREE.Object3D>;
-    readonly idForObject3D: (object: THREE.Object3D) => string | null;
+    readonly idForNativeObject: (object: THREE.Object3D) => string | null;
   },
 ): string | null {
   return raycastCandidates(store, clientX, clientY, isLocked, projection)[0] ?? null;

package/src/kit/authoring/world-hidden-viewport.ts

@@ -1,49 +1,13 @@
 /**
- * World-hidden eye (D9, `world-session-state.ts`) applied to the EDIT-mode
- * three viewport.
- *
- * Bug this fixes: the eye on a hierarchy world-group row (`world:<id>
- * (<kind>)`, shown for 2+ world manifests) toggles `isRootHidden(worldId)`
- * and culls the hierarchy subtree, but for a react/pixi world that's ALSO the
- * only thing that mattered — `design-time-layers.ts`'s `applySessionStyle`
- * sets `display:none` on that world's DOM layer. A three world has no DOM
- * layer; nothing else consumes `isRootHidden` for its actual
- * `THREE.Object3D`s, so without this module the eye is a viewport no-op.
- *
- * Session-local only — it writes no file and pushes no undo entry, matching
- * the DOM roots' own `display:none` semantics. Every call RECOMPUTES
- * `obj.visible` rather than remembering a previous value, which is what makes
- * it rebuild-proof: an adapter that re-renders its tree re-stamps
- * `obj.visible` from its own truth and would silently drop a one-shot
- * override, but the very next call here puts the world-hidden override back.
- * Callers must re-invoke this after every rebuild
- * AND after the toggle itself; `editor-viewport.ts`'s `syncFromStore()` is
- * exactly that seam — it already re-runs on every `store.subscribe` notify,
- * which covers both an adapter rebuild (which notifies) and
- * `GameHierarchy.tsx`'s toggle handler (`toggleRootHidden` +
- * `store.notifyIngestEdit()`).
- *
- * A composite's `store.objectMap`/live THREE.Scene holds the manifest's sole
- * three content root. `GameManifestSchema` rejects a second content root of
- * the same medium, so `resolveThreeViewportRootId` below only needs to name
- * that one world id rather than arbitrate per-object ownership.
+ * Apply hidden-world suppression to live three.js content and its scene environment.
  */
 
 import { getUserData } from '@volter/editor-threejs/ecs/user-data';
 import * as THREE from 'three';
-import { isRootHidden } from '@volter/sdk/kit/authoring/world-session-state';
-import { isThreejsSurfaceVisible, resolveThreeViewportRootId } from '@volter/sdk/kit/authoring/three-root';
+import { isRootHidden } from '@volter/sdk/authoring/world-session-state';
 
-export { isThreejsSurfaceVisible, resolveThreeViewportRootId };
-
-/**
- * Apply the eye toggle to every object in `objectMap` (see module doc
- * comment for the full rebuild-proofing rationale). `threeRootId` is
- * accepted as a parameter (rather than re-resolved internally) so a caller
- * that already computed it once per call (e.g. for a cheap re-apply
- * signature) doesn't pay for `resolveThreeViewportRootId`'s composite walk
- * twice.
- */
+/** Set every mapped object invisible when the identified stage root is hidden. Otherwise leave
+ * visibility unchanged. The caller supplies its resolved root id. */
 export function applyRootHiddenVisibility(
   objectMap: ReadonlyMap<string, THREE.Object3D>,
   threeRootId: string | null,
@@ -57,32 +21,15 @@ export function applyRootHiddenVisibility(
 }
 
 /**
- * The background an editor viewport with NO authored environment shows. A
+ * The background used while an entire world is hidden. A
  * single shared instance so the per-notify re-apply below never allocates.
  */
 const HIDDEN_WORLD_BACKGROUND = new THREE.Color('#aaaaaa');
 
 /**
- * The scene-level half of the eye: `applyRootHiddenVisibility` above only
- * covers entity `Object3D`s (the `objectMap`), but a three world also
- * renders things that live directly on the `THREE.Scene` — the authored
- * `background` color/skybox, `fog`, IBL `environment`, and the
- * `envObject`-tagged ambient light `applyEnvironment` adds. None of those are
- * entities, so without this function hiding the world leaves the viewport
- * painted in the world's background color — looking exactly like "the eye
- * didn't work".
- *
- * Same recompute-don't-remember contract as above: this only ever writes the
- * SUPPRESSED state, idempotently, and callers invoke it on every notify while
- * the world is hidden (an inspector environment edit mid-hide re-paints the
- * authored values via `_applyEnvironment` — the very next notify re-suppresses
- * them here). The restore path is `ShellStore.reapplyEnvironment()`, whose
- * truth is `_sceneMeta.environment` — never a snapshot taken here.
- *
- * Post-processing (bloom/vignette) is the composer's half: `the world root's stage`'s
- * `rebuildComposer` passes `undefined` instead of `store.environment` while
- * the world is hidden; `editor-viewport.ts` bumps `composerVersion` (via
- * `reapplyEnvironment`) on both hide/show edges so that rebuild actually runs.
+ * Clear the scene's background, fog and IBL environment, and hide envObject-tagged lights.
+ * The viewport policy calls this while the world is hidden. It writes only the suppressed state
+ * and stores no environment snapshot.
  */
 export function suppressRootEnvironment(scene: THREE.Scene): void {
   scene.background = HIDDEN_WORLD_BACKGROUND;

package/src/kit/capture-camera-pose.ts

@@ -0,0 +1,68 @@
+/**
+ * THE FREE CAPTURE CAMERA AND CLIP POSE, validated at the relay boundary —
+ * `--azimuth/--elevation/--distance` and `--clip/--time` as they arrive on a
+ * capture command.
+ *
+ * THE VERB NAMES ITSELF: the verb is a parameter, so a bad `--azimuth` refuses
+ * in the name of the command the caller ran.
+ */
+
+/** Validate an untrusted `camera` payload: the parsed choice, `undefined` when
+ *  absent, or the refusal message naming `verb`. */
+export function parseCameraChoice(
+  verb: string,
+  value: unknown,
+): { azimuthDegrees: number; elevationDegrees: number; distance?: number } | undefined | string {
+  if (value === undefined) return undefined;
+  const record = value as {
+    azimuthDegrees?: unknown;
+    elevationDegrees?: unknown;
+    distance?: unknown;
+  } | null;
+  if (
+    record === null ||
+    typeof record !== 'object' ||
+    typeof record.azimuthDegrees !== 'number' ||
+    !Number.isFinite(record.azimuthDegrees) ||
+    typeof record.elevationDegrees !== 'number' ||
+    !Number.isFinite(record.elevationDegrees) ||
+    record.elevationDegrees < -90 ||
+    record.elevationDegrees > 90 ||
+    (record.distance !== undefined &&
+      (typeof record.distance !== 'number' ||
+        !Number.isFinite(record.distance) ||
+        record.distance <= 0))
+  ) {
+    return (
+      `${verb} camera must be {azimuthDegrees, elevationDegrees in [-90, 90], ` +
+      'distance? > 0 meters}.'
+    );
+  }
+  return {
+    azimuthDegrees: record.azimuthDegrees,
+    elevationDegrees: record.elevationDegrees,
+    ...(record.distance === undefined ? {} : { distance: record.distance }),
+  };
+}
+
+/** Validate an untrusted `pose` payload: the parsed pose, `undefined` when
+ *  absent, or the refusal message naming `verb`. */
+export function parsePoseChoice(
+  verb: string,
+  value: unknown,
+): { clip: string; timeSeconds: number } | undefined | string {
+  if (value === undefined) return undefined;
+  const record = value as { clip?: unknown; timeSeconds?: unknown } | null;
+  if (
+    record === null ||
+    typeof record !== 'object' ||
+    typeof record.clip !== 'string' ||
+    record.clip.length === 0 ||
+    typeof record.timeSeconds !== 'number' ||
+    !Number.isFinite(record.timeSeconds) ||
+    record.timeSeconds < 0
+  ) {
+    return `${verb} pose must be {clip: non-empty string, timeSeconds >= 0}.`;
+  }
+  return { clip: record.clip, timeSeconds: record.timeSeconds };
+}