@volter/editor-threejs 0.5.57

package/src/render/viewport-shading.ts

@@ -0,0 +1,163 @@
+import * as THREE from 'three';
+import { createNeutralMatcapTexture } from './matcap-texture';
+
+/** Temporary developer-facing shading modes. These never become scene data. */
+export type ViewportShadingMode =
+  | 'solid'
+  | 'clay'
+  | 'unlit'
+  | 'wireframe'
+  | 'matcap'
+  | 'normals'
+  | 'overdraw';
+
+type MaterialPair = {
+  clay: THREE.MeshStandardMaterial;
+  unlit: THREE.MeshBasicMaterial;
+  wireframe: THREE.MeshBasicMaterial;
+};
+
+function materialColor(material: THREE.Material): THREE.Color {
+  const color = (material as THREE.Material & { color?: THREE.Color }).color;
+  return color?.clone() ?? new THREE.Color(0xbec7d1);
+}
+
+function textureOf(material: THREE.Material, key: 'map' | 'alphaMap'): THREE.Texture | null {
+  return (
+    (material as THREE.Material & { map?: THREE.Texture | null; alphaMap?: THREE.Texture | null })[
+      key
+    ] ?? null
+  );
+}
+
+/**
+ * Applies a render-only material view and restores every native material in a
+ * `finally` block. Gameplay and authoring therefore always observe the real
+ * materials; only renderer work inside {@link render} sees the diagnostic view.
+ */
+export class ViewportShadingRenderer {
+  private readonly _derived = new Map<THREE.Material, MaterialPair>();
+  private readonly _normals = new THREE.MeshNormalMaterial();
+  /**
+   * The clay/sculpt look. Built on FIRST USE, not at construction: the matcap
+   * sphere is drawn into a 2D canvas, and every ViewportShadingRenderer that
+   * only ever draws `solid` would otherwise pay for a texture nobody samples.
+   * `toneMapped: false` for the same reason the overdraw material sets it —
+   * a diagnostic look must read exactly as authored, not as the document's
+   * exposure and tone curve happen to grade it.
+   */
+  private _matcap: THREE.MeshMatcapMaterial | null = null;
+  private _matcapTexture: THREE.Texture | null = null;
+  private readonly _overdraw = new THREE.MeshBasicMaterial({
+    color: 0xffffff,
+    transparent: true,
+    opacity: 0.08,
+    depthTest: false,
+    depthWrite: false,
+    blending: THREE.AdditiveBlending,
+    side: THREE.DoubleSide,
+    toneMapped: false,
+  });
+
+  render(
+    scene: THREE.Scene,
+    mode: ViewportShadingMode,
+    draw: () => void,
+    include: (mesh: THREE.Mesh) => boolean = () => true,
+  ): void {
+    if (mode === 'solid') {
+      draw();
+      return;
+    }
+
+    const originals: Array<{
+      mesh: THREE.Mesh;
+      material: THREE.Material | THREE.Material[];
+    }> = [];
+    scene.traverse((object) => {
+      const mesh = object as THREE.Mesh;
+      if (!mesh.isMesh || !mesh.material || !include(mesh)) return;
+      originals.push({ mesh, material: mesh.material });
+      mesh.material = Array.isArray(mesh.material)
+        ? mesh.material.map((material) => this._materialFor(material, mode))
+        : this._materialFor(mesh.material, mode);
+    });
+
+    try {
+      draw();
+    } finally {
+      for (const { mesh, material } of originals) mesh.material = material;
+    }
+  }
+
+  dispose(): void {
+    for (const pair of this._derived.values()) {
+      pair.clay.dispose();
+      pair.unlit.dispose();
+      pair.wireframe.dispose();
+    }
+    this._derived.clear();
+    this._normals.dispose();
+    this._overdraw.dispose();
+    this._matcap?.dispose();
+    this._matcapTexture?.dispose();
+    this._matcap = null;
+    this._matcapTexture = null;
+  }
+
+  private _materialFor(
+    material: THREE.Material,
+    mode: Exclude<ViewportShadingMode, 'solid'>,
+  ): THREE.Material {
+    if (mode === 'normals') return this._normals;
+    if (mode === 'overdraw') return this._overdraw;
+    if (mode === 'matcap') {
+      if (!this._matcap) {
+        this._matcapTexture = createNeutralMatcapTexture();
+        this._matcap = new THREE.MeshMatcapMaterial({
+          matcap: this._matcapTexture,
+          toneMapped: false,
+        });
+      }
+      return this._matcap;
+    }
+
+    let pair = this._derived.get(material);
+    if (!pair) {
+      const common: THREE.MeshBasicMaterialParameters = {
+        color: materialColor(material),
+        map: textureOf(material, 'map'),
+        alphaMap: textureOf(material, 'alphaMap'),
+        alphaTest: material.alphaTest,
+        opacity: material.opacity,
+        transparent: material.transparent,
+        side: material.side,
+        depthTest: material.depthTest,
+        depthWrite: material.depthWrite,
+        vertexColors: Boolean(
+          (material as THREE.Material & { vertexColors?: boolean }).vertexColors,
+        ),
+        fog: (material as THREE.Material & { fog?: boolean }).fog ?? true,
+      };
+      pair = {
+        clay: new THREE.MeshStandardMaterial({
+          color: 0xaeb6c0,
+          roughness: 0.82,
+          metalness: 0,
+          flatShading: true,
+          alphaMap: textureOf(material, 'alphaMap'),
+          alphaTest: material.alphaTest,
+          opacity: material.opacity,
+          transparent: material.transparent,
+          side: material.side,
+          depthTest: material.depthTest,
+          depthWrite: material.depthWrite,
+        }),
+        unlit: new THREE.MeshBasicMaterial(common),
+        wireframe: new THREE.MeshBasicMaterial({ ...common, wireframe: true }),
+      };
+      this._derived.set(material, pair);
+    }
+    return pair[mode];
+  }
+}

package/src/viewport/clip-planes.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+
+/** The camera's minimum near plane — also the exact value for any small scene. */
+export const EDITOR_CAMERA_NEAR = 0.1;
+
+/** The camera's minimum far plane — also the exact value for any small scene. */
+export const EDITOR_CAMERA_FAR = 1000;
+
+/**
+ * Ceiling on `far / near`. 0.1/1000 is 10^4, so this leaves two doublings of
+ * headroom before `near` starts moving at all, and caps the depth-precision
+ * loss a very large world can inflict.
+ */
+export const EDITOR_CAMERA_MAX_DEPTH_RATIO = 20_000;
+
+/** Slack past the farthest content, so the far plane never grazes it. */
+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.
+ */
+export function fitClipPlanes(
+  distanceToCenter: number,
+  contentRadius: number,
+): { near: number; far: number } {
+  const d = Number.isFinite(distanceToCenter) ? Math.max(0, distanceToCenter) : 0;
+  const r = Number.isFinite(contentRadius) ? Math.max(0, contentRadius) : 0;
+  const far = Math.max(EDITOR_CAMERA_FAR, (d + r) * REACH_MARGIN);
+  const near = Math.max(EDITOR_CAMERA_NEAR, far / EDITOR_CAMERA_MAX_DEPTH_RATIO);
+  return { near, far };
+}

package/src/viewport/content-bounds.ts

@@ -0,0 +1,355 @@
+/**
+ * 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`, `__vgai_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.
+ */
+
+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.
+ */
+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);
+  }
+}
+
+/** Scratch for one node's transformed geometry box — this module is synchronous
+ *  and single-threaded, so one instance serves every call. */
+const nodeBox = new THREE.Box3();
+
+/**
+ * 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.
+ */
+function isFiniteBox(box: THREE.Box3): boolean {
+  return (
+    Number.isFinite(box.min.x) &&
+    Number.isFinite(box.min.y) &&
+    Number.isFinite(box.min.z) &&
+    Number.isFinite(box.max.x) &&
+    Number.isFinite(box.max.y) &&
+    Number.isFinite(box.max.z)
+  );
+}
+
+/** Scratch for the per-instance walk below — same single-threaded argument. */
+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.
+ */
+function expandByInstances(
+  target: THREE.Box3,
+  node: THREE.InstancedMesh,
+  geometryBox: THREE.Box3,
+): void {
+  for (let index = 0; index < node.count; index++) {
+    node.getMatrixAt(index, instanceMatrix);
+    instanceBox.copy(geometryBox).applyMatrix4(instanceMatrix).applyMatrix4(node.matrixWorld);
+    if (!isFiniteBox(instanceBox)) continue;
+    target.union(instanceBox);
+  }
+}
+
+/**
+ * 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}.
+ */
+function expandByNodeGeometry(target: THREE.Box3, node: THREE.Object3D): void {
+  const geometry = (node as THREE.Mesh).geometry as THREE.BufferGeometry | undefined;
+  if (!geometry) return;
+  const local = localRenderableBox(node, geometry);
+  if (!local) return;
+  if ((node as THREE.InstancedMesh).isInstancedMesh) {
+    expandByInstances(target, node as THREE.InstancedMesh, local);
+    return;
+  }
+  nodeBox.copy(local).applyMatrix4(node.matrixWorld);
+  if (!isFiniteBox(nodeBox)) return;
+  target.union(nodeBox);
+}
+
+/** The box `node` draws in its OWN space, computing it on first ask exactly as
+ *  three does. `null` when the geometry cannot produce one at all. */
+function localRenderableBox(
+  node: THREE.Object3D,
+  geometry: THREE.BufferGeometry,
+): THREE.Box3 | null {
+  const renderable = node as THREE.Object3D & {
+    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.
+  if ((node as THREE.SkinnedMesh).isSkinnedMesh) {
+    if (geometry.boundingBox === null) geometry.computeBoundingBox();
+    return geometry.boundingBox;
+  }
+  if (renderable.boundingBox !== undefined && !(node as THREE.InstancedMesh).isInstancedMesh) {
+    if (renderable.boundingBox === null) renderable.computeBoundingBox?.();
+    return renderable.boundingBox ?? null;
+  }
+  if (geometry.boundingBox === null) geometry.computeBoundingBox();
+  return geometry.boundingBox;
+}
+
+/**
+ * Grow `target` to contain `object`'s content subtree, in world space.
+ *
+ * Drop-in for `Box3.expandByObject(object)`, minus implementation subtrees.
+ * Like three's own, it refreshes each visited node's `matrixWorld` from its
+ * parent as it descends and never touches ancestors — a caller that needs the
+ * chain above `object` current calls `updateWorldMatrix(true, false)` first,
+ * exactly as it does today.
+ */
+export function expandBoxByContent(target: THREE.Box3, object: THREE.Object3D): THREE.Box3 {
+  traverseContent(object, (node) => {
+    node.updateWorldMatrix(false, false);
+    expandByNodeGeometry(target, node);
+  });
+  return target;
+}
+
+/** Scratch for the per-node collection below — same single-threaded argument. */
+const collectBox = new THREE.Box3();
+
+/**
+ * One drawing node's world box, plus whether it is authored as a non-occluding
+ * overlay. The 3D board's framing uses the overlay bit to leave a light-beam
+ * cone (or a trigger / AoE) out of the default camera without judging size.
+ */
+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.
+   */
+  readonly overlay: boolean;
+  /**
+   * Every material on this mesh is `BackSide`. That is the authored
+   * "I am the inside of an enclosure" flag a skybox carries, and a hull
+   * or building does not.
+   */
+  readonly enclosure: boolean;
+}
+
+function nodeMaterials(node: THREE.Object3D): THREE.Material[] {
+  const material = (node as THREE.Mesh).material as THREE.Material | THREE.Material[] | undefined;
+  if (!material) return [];
+  return Array.isArray(material) ? material : [material];
+}
+
+/** True when every material on `node` is authored not to write depth. */
+export function nodeIsOverlay(node: THREE.Object3D): boolean {
+  const list = nodeMaterials(node);
+  return list.length > 0 && list.every((entry) => entry.depthWrite === false);
+}
+
+/** True when every material on `node` is authored as an interior enclosure. */
+export function nodeIsEnclosure(node: THREE.Object3D): boolean {
+  const list = nodeMaterials(node);
+  return list.length > 0 && list.every((entry) => entry.side === THREE.BackSide);
+}
+
+/**
+ * The same walk as {@link expandBoxByContent}, reported one record PER NODE
+ * instead of unioned.
+ *
+ * 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
+ * actually draw contribute a box, so groups, lights and cameras add nothing to
+ * the distribution.
+ */
+export function collectContentNodeRecords(
+  object: THREE.Object3D,
+  out: ContentNodeRecord[] = [],
+): ContentNodeRecord[] {
+  traverseContent(object, (node) => {
+    node.updateWorldMatrix(false, false);
+    collectBox.makeEmpty();
+    expandByNodeGeometry(collectBox, node);
+    if (collectBox.isEmpty()) return;
+    out.push({
+      box: collectBox.clone(),
+      overlay: nodeIsOverlay(node),
+      enclosure: nodeIsEnclosure(node),
+    });
+  });
+  return out;
+}
+
+/**
+ * The same walk as {@link collectContentNodeRecords}, boxes only. Callers that
+ * do not need the overlay bit keep this entry.
+ */
+export function collectContentNodeBoxes(
+  object: THREE.Object3D,
+  out: THREE.Box3[] = [],
+): THREE.Box3[] {
+  for (const record of collectContentNodeRecords(object)) out.push(record.box);
+  return out;
+}
+
+/**
+ * The world AABB of `object`'s content subtree.
+ *
+ * Drop-in for `new THREE.Box3().setFromObject(object)`. Pass `target` to reuse
+ * a box across frames (the selection cage recomputes one per selected entity
+ * per frame).
+ */
+export function contentWorldBounds(
+  object: THREE.Object3D,
+  target: THREE.Box3 = new THREE.Box3(),
+): THREE.Box3 {
+  target.makeEmpty();
+  return expandBoxByContent(target, object);
+}
+
+/**
+ * The Bounds diagnostic's twelve-edge box, drawn on {@link contentWorldBounds}
+ * rather than `BoxHelper`'s own `setFromObject`.
+ *
+ * `THREE.BoxHelper` recomputes its box internally on every `update()`, so it
+ * cannot be pointed at a filtered walk; `Box3Helper` is three's own class for
+ * "draw THIS box", which is what we have. Same twelve edges, same colour.
+ */
+export class ContentBoundsHelper extends THREE.Box3Helper {
+  /** The entity object this box is measured from. */
+  readonly entityObject: THREE.Object3D;
+
+  constructor(object: THREE.Object3D, color: THREE.ColorRepresentation) {
+    super(new THREE.Box3(), color);
+    this.entityObject = object;
+    this.update();
+  }
+
+  /** Re-measure. Named to match `BoxHelper.update()`, which the viewport's
+   *  per-frame refresh already calls on everything in its bounds map. */
+  update(): void {
+    contentWorldBounds(this.entityObject, this.box);
+  }
+}

package/src/viewport/editor-layers.ts

@@ -0,0 +1,62 @@
+import { getObjectMark } from '@volter/editor-threejs/ecs/object-marks';
+import type * as THREE from 'three';
+
+/** Layer used for editor-only infrastructure (grid, gizmos, helpers, editor lights). */
+export const EDITOR_LAYER = 31;
+
+/**
+ * Temporary mask layer used by the native Three selection effect. Unlike
+ * {@link EDITOR_LAYER}, membership here does NOT make an object editor-owned:
+ * OutlineEffect adds this bit to the selected game mesh while deriving its
+ * mask. Editor cameras exclude the bit from their ordinary pass so the
+ * effect's depth comparison can actually separate selected pixels.
+ */
+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.
+ */
+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.
+    (object.layers.mask & (1 << EDITOR_LAYER)) !== 0 ||
+    !!getObjectMark(object, 'editorHelper') ||
+    !!getObjectMark(object, 'engineInternal')
+  );
+}
+
+/** True when `object` is editor furniture itself or lives below an
+ * editor-owned root. Helper conventions are not guaranteed to be repeated on
+ * every descendant, so hit-testing a leaf must check its ancestry. */
+export function isInEditorOwnedSubtree(object: THREE.Object3D): boolean {
+  let current: THREE.Object3D | null = object;
+  while (current) {
+    if (isEditorOwnedObject(current)) return true;
+    current = current.parent;
+  }
+  return false;
+}

package/src/viewport/environment.ts

@@ -0,0 +1,26 @@
+import * as THREE from 'three';
+import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
+
+/** A baked IBL environment and the handle that frees its render target. */
+export interface StandardEnvironment {
+  readonly texture: THREE.Texture;
+  dispose(): void;
+}
+
+/**
+ * Bake Three's RoomEnvironment for an authoring view. The caller owns the
+ * returned target; a preview pool may lend its texture without transferring
+ * ownership. No palette, document registration or product service is needed.
+ */
+export function createStandardEnvironment(renderer: THREE.WebGLRenderer): StandardEnvironment {
+  const pmrem = new THREE.PMREMGenerator(renderer);
+  const room = new RoomEnvironment();
+  try {
+    const target = pmrem.fromScene(room, 0.04);
+    return { texture: target.texture, dispose: () => target.dispose() };
+  } finally {
+    // A failed bake must release its temporary scene and generator too.
+    room.dispose();
+    pmrem.dispose();
+  }
+}