@volter/editor-threejs 0.5.210 → 0.5.212

package/src/kit/scene-framing.ts

@@ -1,64 +1,11 @@
-/**
- * What the editor camera should look at when it adopts a world nobody authored
- * here — the two answers behind `EditorViewport.focusOnScene`.
- *
- * ## The measured defect
- *
- * Auto-frame framed the game's ENTIRE content AABB. Measured on a Cuberun
- * mount: a 2,000-radius BackSide skybox sphere, a sun mesh at `z = -2000` and a
- * hyperspace prop at `z ≈ -5365` stretched that AABB to ~8,400 units deep, so
- * the fit distance landed the camera 12,870 units away from a ~1,000-unit
- * gameplay corridor. 93% of the Scene viewport was black, and the one visible
- * thing was the OUTSIDE of the skybox. The same world framed at working
- * distance is vivid and correct. (Descent measured the same looseness at a
- * smaller scale: a camera at ~2,580 for an ~800-unit world.)
- *
- * The union is the wrong instrument because a backdrop is not content the
- * reader is looking FOR — it is content that exists to be far away. One prop
- * 5,000 units out costs the whole framing, and no amount of care in the fit
- * math can recover it.
- *
- * ## The two answers, in order
- *
- * 1. {@link viewFromGameCamera} — a game's author already decided the
- *    interesting view, so seeding the orbit camera from the world matrix of a
- *    camera the game itself placed opens the Scene tab where the game looks.
- *    {@link pickGameCamera} decides which camera that is.
- * 2. {@link frameableContentBounds} — the fallback for a game whose camera we
- *    cannot name. It trims outliers off the union before framing.
- *
- * ## Why gap-trimming and not a percentile
- *
- * A blanket percentile (frame the inner 90% of content) would tighten the
- * framing of EVERY world, including the uniform ones that are framed correctly
- * today. This trims only across a spatial GAP: a face of the bounding box moves
- * inward only when a small share of boxes sits beyond a void spanning a large
- * fraction of the current diagonal. A uniformly-filled world has no such gap,
- * so it comes back byte-identical to the plain union — that identity is the
- * first property the tests pin.
- */
+/** Frame adopted worlds from useful content bounds: trim enclosing backdrops and isolated distant clusters while retaining uniformly distributed content. */
 
-import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
 import * as THREE from 'three';
 
-/** Tuning for {@link frameableContentBounds}. Defaults are the shipped values. */
-export interface FrameableBoundsOptions {
-  /** Largest share of the boxes all trimming together may discard. */
-  maxOutlierFraction?: number;
-  /** A gap must span this share of the current content diagonal to be a gap. */
-  minGapFraction?: number;
-  /** Below this many boxes there is no distribution to judge; nothing trims. */
-  minSampleSize?: number;
-  /** Cap on trim passes, so cost stays bounded on a huge world. */
-  maxPasses?: number;
-}
-
-const DEFAULTS: Required<FrameableBoundsOptions> = {
-  maxOutlierFraction: 0.1,
-  minGapFraction: 0.2,
-  minSampleSize: 8,
-  maxPasses: 8,
-};
+const MAX_OUTLIER_FRACTION = 0.1;
+const MIN_GAP_FRACTION = 0.2;
+const MIN_SAMPLE_SIZE = 8;
+const MAX_TRIM_PASSES = 8;
 
 /** Orbit pivot distance when there is no content to measure one from. */
 const EMPTY_CONTENT_PIVOT_DISTANCE = 10;
@@ -122,25 +69,23 @@ function widestOuterGap(
  */
 export function frameableContentBounds(
   boxes: readonly THREE.Box3[],
-  options: FrameableBoundsOptions = {},
 ): THREE.Box3 {
-  const opts = { ...DEFAULTS, ...options };
   const content = boxes.filter((b) => !b.isEmpty());
   const all = content.map((_, i) => i);
   const full = unionOf(content, all);
-  if (content.length < opts.minSampleSize) return full;
+  if (content.length < MIN_SAMPLE_SIZE) return full;
 
-  let budget = Math.floor(content.length * opts.maxOutlierFraction);
+  let budget = Math.floor(content.length * MAX_OUTLIER_FRACTION);
   if (budget < 1) return full;
 
   const kept = new Set(all);
   let bounds = full;
   const size = new THREE.Vector3();
-  for (let pass = 0; pass < opts.maxPasses && budget > 0; pass++) {
+  for (let pass = 0; pass < MAX_TRIM_PASSES && budget > 0; pass++) {
     const diagonal = bounds.getSize(size).length();
     if (!(diagonal > 0)) break;
     const cut = widestOuterGap(content, kept, budget);
-    if (!cut || cut.gap <= opts.minGapFraction * diagonal) break;
+    if (!cut || cut.gap <= MIN_GAP_FRACTION * diagonal) break;
     for (const i of cut.discard) kept.delete(i);
     budget -= cut.discard.length;
     bounds = unionOf(content, kept);
@@ -154,21 +99,7 @@ export interface SeededView {
   target: THREE.Vector3;
 }
 
-/**
- * The editor orbit pose that reproduces `camera`'s own view.
- *
- * The eye is the game camera's world position and the view direction is its
- * own; the only thing invented is the orbit PIVOT, which is placed at the depth
- * of the content along that view direction — the point the reader is already
- * looking at, so the first orbit drag turns around the world rather than
- * around a point behind their head.
- *
- * Returns `null` when that pivot cannot be placed: the world sits BEHIND the
- * camera (a view showing none of the game is not worth adopting), or it sits
- * ON it, which leaves an orbit pivot at the eye — measured as a target
- * 4.6e-14 units out, an orbit control that can only spin in place. Both fall
- * back to {@link frameableContentBounds}.
- */
+/** Adopt a camera’s world pose with an orbit pivot at visible content depth. Fall back to frameableContentBounds if the content is behind or at the eye. */
 export function viewFromGameCamera(camera: THREE.Camera, content: THREE.Box3): SeededView | null {
   const forward = camera.getWorldDirection(new THREE.Vector3());
   const position = new THREE.Vector3().setFromMatrixPosition(camera.matrixWorld);
@@ -223,43 +154,7 @@ function isVisibleInWorld(object: THREE.Object3D): boolean {
   return true;
 }
 
-/**
- * Does a view posed HERE show the world, or a surface pressed against the lens?
- *
- * The measured defect: a game's own camera is placed for the game's own moment
- * — inside a cockpit, behind a wall it is about to drive through, under
- * terrain that has not settled — and adopting it as the editor's opening view
- * can hand the reader a full-bleed rectangle of rock. The view is a perfectly
- * good gameplay camera and a useless first look, and nothing in the pose
- * itself says which.
- *
- * The instrument is geometric, not pixels: nine rays through the frustum, and
- * a view SHOWS THE WORLD when at least one of them either escapes (sky,
- * backdrop, open space) or reaches something farther than
- * {@link NEAR_FIELD_FRACTION} of what this view claims to be looking at. The
- * threshold is relative to the view's own pivot distance, so it needs no
- * world-scale constant and reads the same on a 10-unit room and a 10,000-unit
- * canyon.
- *
- * Deliberately conservative: EVERY sample must be blocked in the near field
- * before the view is refused, so an ordinary view with a prop in the middle or
- * ground filling its lower half still passes. A refusal here costs the reader
- * only the game's own camera — the caller falls back to
- * {@link frameableContentBounds}, which always shows something.
- *
- * Three's raycast honours `material.side` exactly as the renderer does, and
- * that alignment is the reason this instrument is honest rather than merely
- * cheap: a camera sealed inside a front-faced solid is invisible to BOTH — the
- * reader sees through the shell, the rays escape through it, and the view is
- * correctly not called blocked. The failure this catches is the one that is
- * actually on screen: front faces, filling the frame, right at the lens.
- *
- * (The screenshot lane measures the same failure from the other side, on
- * PIXELS, in `composite-screenshot.ts`. That instrument needs a drawn frame
- * and a GPU readback, and it cannot tell a legitimately flat picture from a
- * blocked one — which is why the decision to adopt a pose is made here, before
- * anything is drawn.)
- */
+/** Check nine geometric frustum rays before adopting a camera pose, rejecting views blocked by a surface near the lens. */
 export function seededViewShowsWorld(
   camera: THREE.Camera,
   content: readonly THREE.Object3D[],
@@ -277,39 +172,3 @@ export function seededViewShowsWorld(
   return false;
 }
 
-/** Every camera in the game's own scene, in scene order, editor furniture and
- *  its subtrees excluded. */
-function gameCameras(node: THREE.Object3D, out: THREE.Camera[] = []): THREE.Camera[] {
-  if (isEditorOwnedObject(node)) return out;
-  if ((node as THREE.Camera).isCamera) out.push(node as THREE.Camera);
-  for (const child of node.children) gameCameras(child, out);
-  return out;
-}
-
-/**
- * The camera whose view an ingest mount should adopt — one the game itself
- * CREATED AND PLACED, which means one that is in the game's own scene graph.
- *
- * The capture's own camera (the one the first `render(scene, camera)` used) is
- * preferred WHEN it is one of those, and is otherwise ignored, because on the
- * first rendered frame it can be a reconciler's placeholder rather than the
- * author's camera. Measured on Cuberun: the captured camera came back with an
- * identity world matrix at the origin while the game's own
- * `<PerspectiveCamera position={[0, 10, -10]}>` was sitting in the scene at
- * (0, 8, 3.5) looking down the corridor — seeding from the capture opened on a
- * flat wall of ground plane, seeding from the scene's camera opened on the
- * game.
- *
- * Editor furniture is never adopted: the capture trap sits on the shared
- * `WebGLRenderer.prototype`, so the editor's own cameras are the one thing
- * that must never come back from here.
- */
-export function pickGameCamera(
-  captured: THREE.Camera | null | undefined,
-  scene: THREE.Object3D,
-): THREE.Camera | null {
-  const cameras = gameCameras(scene);
-  if (cameras.length === 0) return null;
-  if (captured && cameras.includes(captured)) return captured;
-  return cameras[0] as THREE.Camera;
-}

package/src/kit/scene-view-fog.ts

@@ -1,51 +1,6 @@
-import type * as THREE from 'three';
+/** Neutralize scene fog while rendering the authoring view because its camera can sit outside the project camera’s intended fog range. Retain the fog object and shader variant. */
 
-/**
- * Why the Scene viewport draws a world's fog OUT.
- *
- * ## The measured defect
- *
- * Fog is calibrated in metres from THE GAME'S OWN CAMERA. The racing-game
- * mount declares `<fog args={['white', 0, 500]}>`, which is exactly right at
- * its chase camera 20 units behind the car and meaningless anywhere else: its
- * world is ~800 units across, so the editor framing that shows the whole track
- * sits ~700 units back, and every visible surface is past the fog's far plane.
- * Measured on that mount (2026-08-15): the framed Scene view is a featureless
- * white blob — the track, the canyon and the horizon are all the same white.
- *
- * The Scene camera is not the game's camera. It is placed by framing, by a
- * seed, or by the reader's own orbit, at whatever distance the world needs —
- * so a distance-calibrated effect authored for another camera is not a look,
- * it is an erasure.
- *
- * ## Why a view policy and not fog-aware framing
- *
- * The alternative was to have the framing respect the fog range — pick a
- * distance inside it. It cannot work, and the numbers say so rather than an
- * argument: this world's content diagonal is ~1,100 units against a fog far
- * plane of 500, so no distance both shows the track and stays readable. Any
- * fog-aware framing would have to stop showing the world to keep the fog,
- * which is backwards — the first look exists to show the world.
- *
- * So the fog goes, as a VIEW POLICY, in the same class as the shading modes:
- * presentation-only, restored before anything else can observe it, and applied
- * only to the editor's own draw. This is also the established answer in the
- * genre — Unity's Scene view renders fog OFF by default and offers it as a
- * scene-view effect toggle, for exactly this reason.
- *
- * The game's own look is not touched anywhere it belongs: the Game tab, play
- * mode and every exported build render the game's camera through the game's
- * fog. Only the authoring camera is exempted, and there is deliberately no
- * toggle for it — a Scene view that can be washed white by a setting is a
- * fault the reader has to diagnose, and nothing here is worth that.
- *
- * ## Why the parameters and not `scene.fog = null`
- *
- * `!!scene.fog` is part of three's shader-program cache key, so nulling it for
- * one draw and restoring it for the next compiles and keeps a SECOND program
- * variant for every material in the world. Neutralising the fog's own numbers
- * leaves the program identical and the fog term at zero.
- */
+import type * as THREE from 'three';
 
 /** Far enough that no real depth reaches it; `near < far` keeps the linear
  *  fog's `smoothstep(near, far, depth)` well-defined. */

package/src/kit/spatial-handle-visuals.ts

@@ -13,11 +13,9 @@ export interface SpatialHandleBinding {
   readonly handle: SpatialDragHandle;
 }
 
-export interface SpatialHandleMesh extends THREE.Mesh {
-  readonly isSpatialHandleMesh: true;
-}
+export type SpatialHandleMesh = THREE.Mesh<THREE.SphereGeometry, THREE.MeshBasicMaterial>;
 
-export interface SpatialHandleVisualSet {
+interface SpatialHandleVisualSet {
   readonly roots: THREE.Object3D[];
   readonly handles: SpatialHandleMesh[];
 }
@@ -47,10 +45,9 @@ function addLine(
   material: THREE.LineBasicMaterial,
   closed = false,
 ): void {
-  const linePoints = closed && points.length > 0 ? [...points, points[0]!] : [...points];
+  const linePoints = closed ? [...points, points[0]!] : [...points];
   const line = new THREE.Line(new THREE.BufferGeometry().setFromPoints(linePoints), material);
   line.renderOrder = 997;
-  line.layers.set(EDITOR_LAYER);
   if (material instanceof THREE.LineDashedMaterial) line.computeLineDistances();
   root.add(line);
 }
@@ -60,8 +57,8 @@ function circlePoints(
   radius: number,
   axisA: THREE.Vector3,
   axisB: THREE.Vector3,
-  segments = 64,
 ): THREE.Vector3[] {
+  const segments = 64;
   const points: THREE.Vector3[] = [];
   for (let i = 0; i < segments; i++) {
     const angle = (i / segments) * Math.PI * 2;
@@ -244,7 +241,6 @@ function guideObject(guide: SpatialHandleGuide): THREE.Object3D {
           : guide.kind === 'box'
             ? boxGuide(guide)
             : capsuleGuide(guide);
-  root.layers.set(EDITOR_LAYER);
   root.traverse((child) => child.layers.set(EDITOR_LAYER));
   return root;
 }
@@ -256,8 +252,7 @@ function handleMesh(nodeId: string, handle: SpatialDragHandle): SpatialHandleMes
     transparent: true,
     opacity: handle.writable ? 0.92 : 0.35,
   });
-  const mesh = new THREE.Mesh(HANDLE_GEOMETRY, material) as unknown as SpatialHandleMesh;
-  Object.defineProperty(mesh, 'isSpatialHandleMesh', { value: true });
+  const mesh = new THREE.Mesh(HANDLE_GEOMETRY, material);
   mesh.position.copy(vector(handle.position));
   mesh.renderOrder = 998;
   mesh.layers.set(EDITOR_LAYER);
@@ -282,15 +277,15 @@ export function createSpatialHandleVisuals(
   return { roots, handles };
 }
 
-export function spatialHandleBinding(mesh: SpatialHandleMesh): SpatialHandleBinding | null {
-  return bindingByMesh.get(mesh) ?? null;
+export function spatialHandleBinding(mesh: SpatialHandleMesh): SpatialHandleBinding {
+  return bindingByMesh.get(mesh)!;
 }
 
 export function setSpatialHandleHovered(mesh: SpatialHandleMesh, hovered: boolean): void {
-  const binding = bindingByMesh.get(mesh);
-  const material = mesh.material as THREE.MeshBasicMaterial;
+  const binding = spatialHandleBinding(mesh);
+  const material = mesh.material;
   material.color.set(
-    hovered && binding?.handle.writable ? '#ffffff' : (binding?.handle.color ?? '#ffffff'),
+    hovered && binding.handle.writable ? '#ffffff' : binding.handle.color,
   );
 }
 
@@ -301,32 +296,28 @@ export function scaleSpatialHandle(mesh: SpatialHandleMesh, camera: THREE.Camera
 
 function disposeRenderable(
   child: THREE.Object3D,
-  disposedGeometries: Set<THREE.BufferGeometry>,
   disposedMaterials: Set<THREE.Material>,
 ): void {
-  const renderable = child as THREE.Line | THREE.Mesh;
+  const renderable = child as THREE.Object3D & {
+    geometry?: THREE.BufferGeometry;
+    material?: THREE.LineBasicMaterial | THREE.MeshBasicMaterial;
+  };
   const geometry = renderable.geometry;
-  if (geometry && geometry !== HANDLE_GEOMETRY && !disposedGeometries.has(geometry)) {
+  if (geometry && geometry !== HANDLE_GEOMETRY) {
     geometry.dispose();
-    disposedGeometries.add(geometry);
   }
-  const materials = Array.isArray(renderable.material)
-    ? renderable.material
-    : renderable.material
-      ? [renderable.material]
-      : [];
-  for (const material of materials) {
-    if (disposedMaterials.has(material)) continue;
+  const material = renderable.material;
+  if (material) {
+    if (disposedMaterials.has(material)) return;
     material.dispose();
     disposedMaterials.add(material);
   }
 }
 
 export function disposeSpatialHandleVisuals(roots: readonly THREE.Object3D[]): void {
-  const disposedGeometries = new Set<THREE.BufferGeometry>();
   const disposedMaterials = new Set<THREE.Material>();
   for (const root of roots) {
     root.removeFromParent();
-    root.traverse((child) => disposeRenderable(child, disposedGeometries, disposedMaterials));
+    root.traverse((child) => disposeRenderable(child, disposedMaterials));
   }
 }

package/src/kit/stories/three-story-model.ts

@@ -1,33 +1,5 @@
-/**
- * Shared, headless facts about a `three` STORY: whether a mounted story holds
- * three content, and how a story's preview thumbnail is keyed in an in-memory
- * cache. Kept pure and off the React tree so every one of them is
- * unit-testable with no renderer.
- *
- * Membership belongs to the CONSUMER, never to the registry, and it is
- * DECLARED (`story-declared-medium.ts`). The `3D Components` board admits
- * stories whose medium is `three`, the canvas board admits `canvas`, the
- * DOM design board admits `dom` ({@link domStoryBoardMembers}). An
- * undeclared story is a named gap and is not a candidate on any board —
- * nothing here mounts to guess. The project's story registry stays
- * deliberately unfiltered.
- */
-
-import type * as THREE from 'three';
-import { getProjectStoryRegions } from '@volter/sdk/kit/stories/project-story-regions';
-import { declaredStoryMedium, reportUndeclaredStoryMedium } from '@volter/sdk/kit/stories/story-declared-medium';
-
-/**
- * Whether a mounted story's root wrapper actually holds `three` content.
- *
- * A story that renders nothing (or renders only React fragments/null) commits
- * successfully into the wrapper group and yields an EMPTY `Object3D` — a
- * successful mount with nothing in it. A surface shows a story that rendered
- * something; "the mount succeeded" alone is not the test.
- */
-export function mountedStoryHasThreeContent(root: THREE.Object3D): boolean {
-  return root.children.length > 0;
-}
+import { editorHost } from '@volter/sdk/host';
+import { declaredStoryMedium } from '@volter/sdk/stories/story-declared-medium';
 
 /**
  * The DOM design board's membership — every story DECLARED as `dom`.
@@ -36,7 +8,7 @@ export function mountedStoryHasThreeContent(root: THREE.Object3D): boolean {
  * mounts: medium is a declaration, and a last-resort mount would make
  * "residue 0" unfalsifiable (the orphan would land on this board).
  *
- * The board (`authoring/design-time-layers.ts`) renders each member through
+ * The DOM design board renders each member through
  * `react-dom`, so a three story landing on it renders `<group>`/`<primitive>`
  * as unknown DOM tags. Declaration is what keeps those stories off this
  * board; the project's story registry stays deliberately unfiltered.
@@ -49,7 +21,7 @@ export function domStoryBoardMembers<
     readonly tags?: readonly string[];
   },
 >(stories: readonly T[]): T[] {
-  const regions = getProjectStoryRegions();
+  const regions = editorHost().stories.regions();
   const members: T[] = [];
   for (const story of stories) {
     const declared = declaredStoryMedium({ modulePath: story.modulePath, regions });
@@ -58,7 +30,7 @@ export function domStoryBoardMembers<
       continue;
     }
     if (declared.via === 'undeclared' && story.modulePath) {
-      reportUndeclaredStoryMedium(story.modulePath, declared.reason);
+      editorHost().stories.reportUndeclaredMedium(story.modulePath, declared.reason);
     }
   }
   return members;

package/src/kit/three-canvas-render.ts

@@ -1,13 +1,12 @@
 /**
  * The Three set's canvases, rendered at a caller's scale
- * (`@volter/sdk/kit/canvas-frames`): the Scene viewport's presented frame
+ * (`@volter/sdk/canvas-frames`): the Scene viewport's presented frame
  * or a fresh render of it, and an Object3D document's presented frame or an
  * offscreen render of its subject. The editor-chrome photograph asks here, so a
  * 2x capture of a viewport gets a 2x render rather than a 1x one stretched.
  */
-import { registerCanvasRender } from '@volter/sdk/kit/canvas-frames';
+import { presentedCanvasFrame, registerCanvasRender } from '@volter/sdk/canvas-frames';
 import { allObject3DDocumentSessions } from './authoring/object3d-document-session-registry';
-import { liveCanvasFrame } from '@volter/sdk/kit/live-canvas-frame';
 import { threeStoreForHost } from './three-state';
 
 async function imageOf(dataUrl: string): Promise<HTMLImageElement> {
@@ -22,7 +21,7 @@ export function registerThreeCanvasRender(): () => void {
     const store = threeStoreForHost();
     if (store && store.viewportCanvas() === canvas) {
       return (async () => {
-        const presented = await liveCanvasFrame(canvas);
+        const presented = await presentedCanvasFrame(canvas);
         if (presented) return presented;
         const dataUrl = store.captureViewportImage(size);
         return dataUrl ? imageOf(dataUrl) : null;

package/src/kit/three-hierarchy-row-media.ts

@@ -1,10 +1,9 @@
 /**
  * The Three integration's answers to the hierarchy panel's row questions
- * (`@volter/sdk/kit/hierarchy-row-media`): an instanced mesh's row names the units it
- * draws, a node's component marks come off its `Object3D`, and the store's Three half logs which
- * projected parents its object map changed so the panel can patch rows.
+ * (`@volter/sdk/hierarchy-row-media`): an instanced mesh's row names the units it
+ * draws, and a node's component marks come off its `Object3D`.
  */
-import { registerHierarchyRowMedia } from '@volter/sdk/kit/hierarchy-row-media';
+import { registerHierarchyRowMedia } from '@volter/sdk/hierarchy-row-media';
 import { entityObject3D } from './entity-object';
 import { markReaderFor } from './hierarchy-mark-reader';
 import { instancedRowDetail } from './instanced-presentation';
@@ -15,12 +14,5 @@ export function registerThreeHierarchyRowMedia(): () => void {
     detail: (adapter, nodeId, store) =>
       instancedRowDetail(entityObject3D(adapter, threeStateOf(store).objectMap, nodeId)),
     marks: (hierarchy) => markReaderFor(hierarchy),
-    structureLog: (store) => {
-      const three = threeStateOf(store);
-      return {
-        epoch: () => three.gizmoEpoch,
-        parentChangesSince: (epoch) => three.ingestObjectMapChangesSince(epoch),
-      };
-    },
   });
 }

package/src/kit/three-inspection-media.ts

@@ -1,6 +1,6 @@
 /**
  * THE THREE.JS ANSWER TO "what does this node look like"
- * (`@volter/sdk/kit/inspection-node-media`): a selected node the shell's
+ * (`@volter/sdk/inspection-node-media`): a selected node the shell's
  * Three store resolves to a live `Object3D` is previewed as an isolated live
  * view of that object, a camera has no Preview section (its view is the
  * viewport's), an instanced mesh names its units, and a node in the object map
@@ -10,12 +10,12 @@
 import {
   type InspectionNodeMedia,
   registerInspectionNodeMedia,
-} from '@volter/sdk/kit/inspection-node-media';
+} from '@volter/sdk/inspection-node-media';
 import { contentWorldBounds } from '@volter/editor-threejs/viewport/content-bounds';
 import { createElement, lazy } from 'react';
 import type * as THREE from 'three';
-import { openRegisteredDocument } from '@volter/sdk/kit/document-open-registry';
-import { InspectorPreviewBody } from '@volter/sdk/kit/components/inspector-preview-section';
+import { openRegisteredDocument } from '@volter/sdk/document-open-registry';
+import { InspectorPreviewBody } from '@volter/sdk/components/inspector-preview-section';
 import { entityObject3D } from './entity-object';
 import { describeInstancedPresentation } from './instanced-presentation';
 import { threeStoreForHost } from './three-state';
@@ -38,7 +38,7 @@ function objectMedia(
           (mode) =>
             createElement(InspectorPreviewBody, {
               picture: () =>
-                createElement(InspectorObjectPreview, { previewKey, object, displayName, fill: true }),
+                createElement(InspectorObjectPreview, { previewKey, object, displayName }),
               previewKey,
               actions,
               ...(mode ? { mode } : {}),
@@ -62,7 +62,7 @@ export function registerThreeInspectionMedia(): () => void {
         ? {
             // The live `Object3D.name` is the only name there is.
             open: () =>
-              openRegisteredDocument('asset-editor:entity', store.shell, {
+              openRegisteredDocument('asset-editor:entity', {
                 entityId: nodeId,
                 title: object.name || nodeId,
               }),

package/src/kit/three-integration.ts

@@ -1,34 +1,31 @@
 /**
  * THE THREE INTEGRATION, INSTALLED — every registration the kit's Three viewport answers
- * through: the Object3D surfaces contributions mount, the viewport's relay verbs, its Asset Lab
+ * through: the Object3D surfaces contributions mount, its Asset Lab
  * viewers, the inspector's node media, model thumbnails, the viewport status facet,
  * canvas captures, the gizmo viewport's authoring policy, and the view state each session store's
  * Three half saves. The kit constructs none of it; the integration installs it once, and every
  * Three surface asks for it before it mounts (`ensureThreeIntegration`).
  */
-import { registerContributedCommands } from '@volter/sdk/kit/command-registry';
-import { saveThumbnail } from '@volter/sdk/kit/editor-api';
-import { registerHostHierarchyObjects } from '../host-hierarchy-objects';
-import { registerContributionSurfaces } from '@volter/sdk/kit/contribution-surfaces';
-import { registerRendererResourceCounts } from '@volter/sdk/kit/renderer-resource-counts';
+import { saveThumbnail } from '@volter/sdk/api/project-open';
+import { OUTLINER_DATA, OUTLINER_OBJECT, registerHierarchyKinds } from '@volter/sdk/hierarchy-kind-icon';
+import { registerContributionSurfaces } from '@volter/sdk/contribution-surfaces';
+import { registerRendererResourceCounts } from '@volter/sdk/renderer-resource-counts';
 import { interactiveViewportRendererCounts } from './three-viewport/interactive-renderer';
 import { inspectorPreviewRendererCounts } from '../viewport/preview-renderer';
 import { liveHostRendererCount } from '../viewport/renderer-ownership';
-import type * as THREE from 'three';
 import { SHELL_VIEWPORT_AUTHORING_POLICY } from './authoring/shell-viewport-policy';
 import { Object3DAuthoringSurface, Object3DPreviewSurface } from './components/object3d-contribution-surfaces';
 import { registerThreeAssetViewers } from './components/asset-viewers/three-asset-viewers';
 import type { EditorStatePersistence } from './editor-shell-store';
 import { registerModelThumbnails } from './model-thumbnail';
-import { writeProjectLocalSection } from '@volter/sdk/kit/project-local-state';
-import { onShellStore } from '@volter/sdk/kit/shell-store-door';
+import { editorHost } from '@volter/sdk/host';
+import { onShellStore } from '@volter/sdk/shell-store-door';
 import { registerThreeCanvasRender } from './three-canvas-render';
 import { registerThreeHierarchyRowMedia } from './three-hierarchy-row-media';
 import { registerThreePlayCameraFlight } from './play-camera-flight';
 import { registerThreeInspectionMedia } from './three-inspection-media';
-import { threeStateOf, threeStoreForHost } from './three-state';
+import { threeStateOf } from './three-state';
 import { installViewportAuthoringPolicy } from './viewport-authoring-policy';
-import { viewportCommands } from './viewport-commands';
 import { reportViewportStatus } from './viewport-status-facet';
 
 /**
@@ -40,24 +37,31 @@ const hotData = (import.meta as ImportMeta & { hot?: { data: Record<string, unkn
 const VIEW_STATE_PERSISTENCE: EditorStatePersistence = (hotData?.['viewStatePersistence'] as
   | EditorStatePersistence
   | undefined) ?? {
-  save: (state) => writeProjectLocalSection('view', state),
+  save: (state) => editorHost().projectLocalState.write('view', state),
   saveThumbnail,
 };
 if (hotData) hotData['viewStatePersistence'] = VIEW_STATE_PERSISTENCE;
 
-const NO_OBJECTS: ReadonlyMap<string, THREE.Object3D> = new Map();
 
 let installed: (() => void) | null = null;
 
 /** Install the integration; idempotent. Returns the teardown of the first install. */
 export function ensureThreeIntegration(): () => void {
   if (installed) return installed;
+  // The hierarchy glyphs, in place before the first hierarchy render a viewport brings (its rows are memoized). The
+  // core composite gives a `stage` world's group row the manifest surface as its kind (`groupNode`); that row draws
+  // the outliner's object glyph. A model document's root is a datablock, not an object carrying one `mesh-data` row
+  // off it, so the two kinds `source-object3d-authoring-adapter.ts` mints for it, `three-source` and `model-asset`,
+  // draw the data glyph, as `mesh-data` does: the Properties breadcrumb takes its glyph from the datablock, never
+  // from the open tab.
+  registerHierarchyKinds({
+    glyphs: { stage: OUTLINER_OBJECT, 'three-source': OUTLINER_DATA, 'model-asset': OUTLINER_DATA },
+  });
   const stops = [
     registerContributionSurfaces({
       Object3DPreview: Object3DPreviewSurface,
       Object3DAuthoring: Object3DAuthoringSurface,
     }),
-    registerContributedCommands('three-viewport', viewportCommands),
     registerThreeAssetViewers(),
     registerThreeInspectionMedia(),
     registerModelThumbnails(),
@@ -65,10 +69,6 @@ export function ensureThreeIntegration(): () => void {
     registerThreeCanvasRender(),
     registerThreeHierarchyRowMedia(),
     registerThreePlayCameraFlight(),
-    registerHostHierarchyObjects({
-      object: (id) => threeStoreForHost()?.objectMap.get(id) ?? null,
-      objects: () => threeStoreForHost()?.objectMap ?? NO_OBJECTS,
-    }),
     registerRendererResourceCounts('hostLive', liveHostRendererCount),
     registerRendererResourceCounts('interactive', interactiveViewportRendererCounts),
     registerRendererResourceCounts('inspectorPreview', inspectorPreviewRendererCounts),

package/src/kit/three-state.ts

@@ -1,8 +1,7 @@
 /** A shell store's Three half (`threeStateOf`, beside the half in `editor-shell-store.ts`). */
-import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import type { ShellStore } from '@volter/sdk/shell-store';
 import { type EditorShellStore, threeStateOf } from './editor-shell-store';
-import { useEditorStore, useOptionalEditorStore } from '@volter/sdk/kit/editor-runtime';
-import { onShellStore, shellStoreForHost } from '@volter/sdk/kit/shell-store-door';
+import { shellStoreForHost } from '@volter/sdk/shell-store-door';
 
 export { threeStateOf };
 
@@ -11,23 +10,7 @@ export function optionalThreeStateOf(store: ShellStore | null): EditorShellStore
   return store === null ? null : threeStateOf(store);
 }
 
-/** The session store's Three half (`threeStateOf`), for a component that reads the scene,
- *  object map, camera or viewport tools. */
-export function useThreeEditorStore(): EditorShellStore {
-  return threeStateOf(useEditorStore());
-}
-
-/** {@link useThreeEditorStore} outside a session answers `null`. */
-export function useOptionalThreeEditorStore(): EditorShellStore | null {
-  return optionalThreeStateOf(useOptionalEditorStore());
-}
-
 /** The session store's Three half (`three-state.ts`), or `null` before a session opens. */
 export function threeStoreForHost(): EditorShellStore | null {
   return optionalThreeStateOf(shellStoreForHost());
 }
-
-/** {@link onShellStore} for a lane that works on the store's Three half. */
-export function onThreeStore(listener: (store: EditorShellStore) => void): () => void {
-  return onShellStore((store) => listener(threeStateOf(store)));
-}