@volter/editor-threejs 0.5.65 → 0.5.67

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

@@ -0,0 +1,226 @@
+/**
+ * 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.
+ */
+
+import type { EditorNode, Transform } from '@volter/editor-project/adapter';
+import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
+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/editor-sdk/kit/shell-store';
+import { nativeKindOf, type ThreeProjector } from '../projection/three';
+import { localTransformOf } from './live-object-transform';
+
+export interface StoreSelectionAdoptionOptions {
+  readonly store: ShellStore;
+  /** Which ids this projection owns. The store is shared, so it can hold
+   *  another surface's ids and a synthetic row this projection invented. */
+  readonly owns: (id: string) => boolean;
+  /** The selection before anything is picked — usually the document row. */
+  readonly initial: readonly string[];
+  /** 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;
+}
+
+function sameIds(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((id, index) => id === b[index]);
+}
+
+/**
+ * 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.
+ */
+export class StoreSelectionAdoption {
+  /** The store ids last adopted or published — the comparison basis. */
+  private adopted: readonly string[] = [];
+  private selected: string[];
+
+  constructor(private readonly options: StoreSelectionAdoptionOptions) {
+    this.selected = [...options.initial];
+  }
+
+  /** This projection's selection, having adopted whatever the viewport wrote. */
+  current(): string[] {
+    const storeIds = [...this.options.store.selectedEntityIds].filter(this.options.owns);
+    if (!sameIds(storeIds, this.adopted)) {
+      this.adopted = storeIds;
+      this.selected = storeIds;
+      this.options.onChange?.(storeIds);
+    }
+    return [...this.selected];
+  }
+
+  /**
+   * Publish a selection the configuration has already resolved — rows it owns
+   * plus, possibly, a synthetic row of its own. Only the owned ids reach the
+   * store, because that is the index the viewport draws from.
+   */
+  publish(selected: readonly string[]): void {
+    this.selected = [...selected];
+    const storeIds = this.selected.filter(this.options.owns);
+    this.adopted = storeIds;
+    this.options.onChange?.(storeIds);
+    this.options.store.selectMultiple(storeIds);
+  }
+}
+
+/**
+ * A `TransformProvider.get` over a live `Object3D` — the read every three
+ * configuration answers with.
+ *
+ * `null` is the honest identity for an id this projection does not own (the
+ * document row, a synthetic row, a node the last walk dropped): the provider's
+ * contract has no absent answer, and the caller has already been told through
+ * `editability`/`dimensions` that there is nothing there.
+ *
+ * The read itself is `live-object-transform.ts`'s rule — a node whose driver
+ * owns its matrix keeps stale `.position`/`.quaternion`/`.scale` forever, so
+ * the matrix is the transform exactly when the node maintains it. That answer
+ * feeds the Inspector, the selection overlay's anchor and the origin marker,
+ * which is why all three must give it.
+ */
+export function readLocalTransform(object: THREE.Object3D | null): Transform {
+  if (!object) return { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };
+  const live = localTransformOf(object);
+  return { position: live.position, rotation: live.quaternion, scale: live.scale };
+}
+
+/**
+ * THE COLLAPSE RULE. A live graph contains connective nodes a library inserted
+ * rather than the project authoring them — Rapier's `<RigidBody>` puts an
+ * anonymous generic `Object3D` between the prefab and its named mesh. Showing
+ * it starts the hierarchy with an uneditable "Object3D" row and asks the author
+ * to understand library implementation structure.
+ *
+ * This is an OWNERSHIP rule, not a package/name exception: a source-stamped
+ * node, component root, explicit authoring root or native authoring proxy is
+ * semantic and stays visible. Only an unnamed, unclaimed generic container is
+ * transparent, and its meaningful descendants are promoted in place.
+ */
+export function isTransparentWrapper(object: THREE.Object3D): boolean {
+  return (
+    object.type === 'Object3D' &&
+    object.name === '' &&
+    object3DAuthoringSubjectOf(object) === null &&
+    object.userData['oid'] === undefined &&
+    getUserData(object, 'authoringInstance') === undefined &&
+    getUserData(object, 'authoringRoot') !== true &&
+    getUserData(object, 'vgaiComponentRoot') === undefined
+  );
+}
+
+export interface CollapsedHierarchyOptions {
+  /** The index this view derives from — never a second walk. */
+  readonly projector: ThreeProjector;
+  /** Climbing stops here: a graph's own scene is not a row. */
+  readonly scene: THREE.Scene;
+  /** The row a projection root (and any climb that escapes the graph) answers
+   *  to. It exists in the VIEW only, so the projector answers `null` for it. */
+  readonly documentNodeId: string;
+  /** This view's declared roots, as ids of {@link projector}'s index. */
+  readonly rootIds: readonly string[];
+}
+
+/**
+ * The hierarchy view a configuration hands its `HierarchyProvider`: the
+ * projection's own parent/child structure with {@link isTransparentWrapper}
+ * nodes folded out of it.
+ *
+ * Every method answers from the projector's live index, so a configuration that
+ * re-walks (a running world spawns objects) sees the new graph without this
+ * view holding anything stale.
+ */
+export class CollapsedHierarchyView {
+  private readonly rootIdSet: ReadonlySet<string>;
+
+  constructor(private readonly options: CollapsedHierarchyOptions) {
+    this.rootIdSet = new Set(options.rootIds);
+  }
+
+  /** `object`'s visible children — the live objects themselves, so a caller
+   *  that needs the object (not its row) does not go back through the index. */
+  childObjects(object: THREE.Object3D): THREE.Object3D[] {
+    return object.children.flatMap((child) => {
+      if (isEditorOwnedObject(child)) return [];
+      return isTransparentWrapper(child) ? this.childObjects(child) : [child];
+    });
+  }
+
+  childIds(object: THREE.Object3D): string[] {
+    return this.options.projector.childIdsOf(this.childObjects(object));
+  }
+
+  /** The declared roots with transparent ones replaced by what they contain. */
+  rootObjects(): THREE.Object3D[] {
+    return this.options.rootIds.flatMap((id) => {
+      const object = this.options.projector.objectOf(id);
+      if (!object) return [];
+      return isTransparentWrapper(object) ? this.childObjects(object) : [object];
+    });
+  }
+
+  rootIds(): string[] {
+    return this.options.projector.childIdsOf(this.rootObjects());
+  }
+
+  /** The row that owns `object`: the nearest ancestor this view shows, or the
+   *  document row when the climb reaches a declared root or the scene. */
+  parentId(object: THREE.Object3D): string {
+    const { projector, scene, documentNodeId } = this.options;
+    const id = projector.idOf(object);
+    if (id !== null && this.rootIdSet.has(id)) return documentNodeId;
+    let parent = object.parent;
+    while (parent && parent !== scene && isTransparentWrapper(parent)) {
+      parent = parent.parent;
+    }
+    return parent && parent !== scene ? (projector.idOf(parent) ?? documentNodeId) : documentNodeId;
+  }
+
+  /** `object`'s row. An object is named and typed by what it IS — its own
+   *  authoring subject, name, or native type — never by an owner above it. */
+  node(object: THREE.Object3D): EditorNode {
+    const subject = object3DAuthoringSubjectOf(object);
+    return {
+      id: this.options.projector.idOf(object)!,
+      label: subject?.label || object.name || object.type || 'Object3D',
+      role: 'entity',
+      kind: nativeKindOf(object),
+      ...(subject?.typeLabel ? { typeLabel: subject.typeLabel } : {}),
+      parentId: this.parentId(object),
+      childIds: this.childIds(object),
+    };
+  }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Viewport pick context (B4, D12) — the camera/canvas seam that
+ * `VgaiSceneAuthoringAdapter.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.
+ */
+
+import { setViewportEditorControls, type ViewportEditorControls } from '@volter/editor-sdk/kit/viewport-editor-controls';
+import type * as THREE from 'three';
+
+export interface ViewportPickContext {
+  readonly camera: THREE.Camera;
+  readonly canvas: HTMLCanvasElement;
+  /** Editor-owned direct-manipulation projections (currently constraint
+   * 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;
+
+}
+
+let _ctx: ViewportPickContext | null = null;
+
+/** Install/clear the live viewport's pick context (`EditorViewport` ctor/dispose). */
+export function setViewportPickContext(ctx: ViewportPickContext | null): void {
+  _ctx = ctx;
+  setViewportEditorControls(ctx?.editorControls ?? null);
+}
+
+/** The live viewport's camera/canvas, or `null` when none is mounted. */
+export function getViewportPickContext(): ViewportPickContext | null {
+  return _ctx;
+}

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

@@ -0,0 +1,240 @@
+/**
+ * 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 `VgaiSceneAuthoringAdapter` (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.
+ */
+
+import { isInEditorOwnedSubtree } from '@volter/editor-threejs/viewport/editor-layers';
+import * as THREE from 'three';
+import type { EditorShellStore } from '../editor-shell-store';
+import { entityIdOf, nearestEntityObject } from '../entity-object';
+import { getViewportPickContext } from './viewport-pick-context';
+
+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.
+ */
+export function isBackdropObject(object: THREE.Object3D): boolean {
+  const material = (object as Partial<THREE.Mesh>).material;
+  if (!material) return false;
+  return Array.isArray(material)
+    ? material.length > 0 && material.every(isBackdropMaterial)
+    : 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. */
+export function raycastCandidates(
+  store: EditorShellStore,
+  clientX: number,
+  clientY: number,
+  isLocked: (id: string) => boolean = () => false,
+  projection?: {
+    readonly objects: Iterable<THREE.Object3D>;
+    readonly idForObject3D: (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.
+  if (
+    rect.width <= 0 ||
+    rect.height <= 0 ||
+    !Number.isFinite(clientX) ||
+    !Number.isFinite(clientY) ||
+    clientX < rect.left ||
+    clientY < rect.top ||
+    clientX >= rect.left + rect.width ||
+    clientY >= rect.top + rect.height
+  )
+    return [];
+  const mouse = new THREE.Vector2(
+    ((clientX - rect.left) / rect.width) * 2 - 1,
+    -((clientY - rect.top) / rect.height) * 2 + 1,
+  );
+  const raycaster = new THREE.Raycaster();
+  raycaster.layers.enableAll();
+  raycaster.setFromCamera(mouse, ctx.camera);
+
+  const indexed = new Set(projection?.objects ?? store.objectMap.values());
+  // intersectObjects(..., true) already visits descendants. Passing both a
+  // parent and each indexed child repeatedly intersects the same geometry.
+  const entityObjects = [...indexed].filter((object) => {
+    for (let parent = object.parent; parent; parent = parent.parent) {
+      if (indexed.has(parent)) return false;
+    }
+    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`).
+  for (const root of entityObjects) {
+    root.traverse((node) => {
+      // Structural write: three's own `SkinnedMesh` fields hold `Box3 | null`
+      // at runtime (`null` = "compute on demand"), the published type just
+      // does not admit the null it initializes with.
+      const skinned = node as unknown as {
+        isSkinnedMesh?: boolean;
+        boundingBox: unknown;
+        boundingSphere: unknown;
+      };
+      if (skinned.isSkinnedMesh) {
+        skinned.boundingBox = null;
+        skinned.boundingSphere = null;
+      }
+    });
+  }
+
+  const intersects = raycaster.intersectObjects(entityObjects, true);
+  const hits: string[] = [];
+  const seen = new Set<string>();
+  for (const isect of intersects) {
+    // Skip every form of editor-owned geometry. TransformControls marks its
+    // invisible interaction plane only with EDITOR_LAYER; other helpers use
+    // userData flags. Checking the shared predicate prevents either form from
+    // becoming the selected "entity" while still allowing the ray to fall
+    // through to game content behind it.
+    if (isInEditorOwnedSubtree(isect.object)) continue;
+
+    // The scene's backdrop is not a thing under the pointer — see
+    // {@link isBackdropObject}. Skipping it is what lets a click on empty sky
+    // be a MISS, which is what clears the selection.
+    if (isBackdropObject(isect.object)) continue;
+
+    // Walk up to find the projected authoring node. A foreign adapter answers
+    // from its own reverse map; the default keeps the established stamp-based
+    // first-party behavior.
+    let cursor: THREE.Object3D | null = isect.object;
+    let eid: string | null = null;
+    if (projection) {
+      while (cursor && eid === null) {
+        eid = projection.idForObject3D(cursor);
+        cursor = cursor.parent;
+      }
+    } else {
+      const hit = nearestEntityObject(cursor);
+      eid = hit ? (entityIdOf(hit) ?? null) : null;
+    }
+    // Skip locked entities in viewport selection.
+    if (eid !== null && !isLocked(eid) && !seen.has(eid)) {
+      seen.add(eid);
+      hits.push(eid);
+    }
+  }
+  reportEmptyPick(hits, entityObjects, intersects.length, clientX, clientY);
+  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.
+ */
+function reportEmptyPick(
+  hits: readonly string[],
+  candidates: readonly THREE.Object3D[],
+  rayHits: number,
+  clientX: number,
+  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.
+  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(
+    `[viewport-pick] click selected nothing (candidates ${candidates.length}, ` +
+      `rayHits ${rayHits}, resolvedIds 0)`,
+  );
+}
+
+/** Frontmost authorable subject under the pointer. */
+export function raycastPick(
+  store: EditorShellStore,
+  clientX: number,
+  clientY: number,
+  isLocked: (id: string) => boolean = () => false,
+  projection?: {
+    readonly objects: Iterable<THREE.Object3D>;
+    readonly idForObject3D: (object: THREE.Object3D) => string | null;
+  },
+): string | null {
+  return raycastCandidates(store, clientX, clientY, isLocked, projection)[0] ?? null;
+}

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

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+
+import { getUserData } from '@volter/editor-threejs/ecs/user-data';
+import * as THREE from 'three';
+import { isRootHidden } from '@volter/editor-sdk/kit/authoring/world-session-state';
+import { isThreejsSurfaceVisible, resolveThreeViewportRootId } from '@volter/editor-sdk/kit/authoring/three-root';
+
+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.
+ */
+export function applyRootHiddenVisibility(
+  objectMap: ReadonlyMap<string, THREE.Object3D>,
+  threeRootId: string | null,
+): void {
+  const hidden = threeRootId !== null && isRootHidden(threeRootId);
+  if (!hidden) return;
+  // The live `Object3D.visible` IS the authored truth, so the SHOW edge has
+  // nothing to restore FROM — the adapter re-renders its own tree there.
+  // Hiding wins over everything: nothing in a hidden world renders.
+  for (const obj of objectMap.values()) obj.visible = false;
+}
+
+/**
+ * The background an editor viewport with NO authored environment shows. 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.
+ */
+export function suppressRootEnvironment(scene: THREE.Scene): void {
+  scene.background = HIDDEN_WORLD_BACKGROUND;
+  scene.fog = null;
+  scene.environment = null;
+  scene.traverse((obj) => {
+    if (getUserData(obj, 'envObject')) obj.visible = false;
+  });
+}
+