@volter/editor-threejs 0.5.66 → 0.5.68

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

@@ -0,0 +1,332 @@
+/** Viewport rendering for the format-neutral spatial-handle contract. */
+
+import type {
+  SpatialDragHandle,
+  SpatialHandleGuide,
+  SpatialHandleLayer,
+} from '@volter/editor-project/adapter';
+import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
+import * as THREE from 'three';
+
+export interface SpatialHandleBinding {
+  readonly nodeId: string;
+  readonly handle: SpatialDragHandle;
+}
+
+export interface SpatialHandleMesh extends THREE.Mesh {
+  readonly isSpatialHandleMesh: true;
+}
+
+export interface SpatialHandleVisualSet {
+  readonly roots: THREE.Object3D[];
+  readonly handles: SpatialHandleMesh[];
+}
+
+const bindingByMesh = new WeakMap<SpatialHandleMesh, SpatialHandleBinding>();
+const HANDLE_GEOMETRY = new THREE.SphereGeometry(1, 12, 8);
+
+function vector(value: readonly [number, number, number]): THREE.Vector3 {
+  return new THREE.Vector3(value[0], value[1], value[2]);
+}
+
+function lineMaterial(guide: SpatialHandleGuide): THREE.LineBasicMaterial {
+  const options = {
+    color: guide.color,
+    transparent: true,
+    opacity: guide.opacity ?? 0.68,
+    depthTest: false,
+  };
+  return guide.dashed
+    ? new THREE.LineDashedMaterial({ ...options, dashSize: 0.18, gapSize: 0.12 })
+    : new THREE.LineBasicMaterial(options);
+}
+
+function addLine(
+  root: THREE.Group,
+  points: readonly THREE.Vector3[],
+  material: THREE.LineBasicMaterial,
+  closed = false,
+): void {
+  const linePoints = closed && points.length > 0 ? [...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);
+}
+
+function circlePoints(
+  center: THREE.Vector3,
+  radius: number,
+  axisA: THREE.Vector3,
+  axisB: THREE.Vector3,
+  segments = 64,
+): THREE.Vector3[] {
+  const points: THREE.Vector3[] = [];
+  for (let i = 0; i < segments; i++) {
+    const angle = (i / segments) * Math.PI * 2;
+    points.push(
+      center
+        .clone()
+        .addScaledVector(axisA, Math.cos(angle) * radius)
+        .addScaledVector(axisB, Math.sin(angle) * radius),
+    );
+  }
+  return points;
+}
+
+function sphereGuide(guide: Extract<SpatialHandleGuide, { kind: 'sphere' }>): THREE.Group {
+  const root = new THREE.Group();
+  const center = vector(guide.center);
+  const material = lineMaterial(guide);
+  addLine(
+    root,
+    circlePoints(center, guide.radius, new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 1, 0)),
+    material,
+    true,
+  );
+  addLine(
+    root,
+    circlePoints(center, guide.radius, new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 0, 1)),
+    material,
+    true,
+  );
+  addLine(
+    root,
+    circlePoints(center, guide.radius, new THREE.Vector3(0, 1, 0), new THREE.Vector3(0, 0, 1)),
+    material,
+    true,
+  );
+  return root;
+}
+
+function lineGuide(guide: Extract<SpatialHandleGuide, { kind: 'line' }>): THREE.Group {
+  const root = new THREE.Group();
+  addLine(root, guide.points.map(vector), lineMaterial(guide));
+  return root;
+}
+
+function coneGuide(guide: Extract<SpatialHandleGuide, { kind: 'cone' }>): THREE.Group {
+  const root = new THREE.Group();
+  const origin = vector(guide.origin);
+  const direction = vector(guide.direction).normalize();
+  const seed =
+    Math.abs(direction.y) < 0.9 ? new THREE.Vector3(0, 1, 0) : new THREE.Vector3(1, 0, 0);
+  const right = new THREE.Vector3().crossVectors(seed, direction).normalize();
+  const up = new THREE.Vector3().crossVectors(direction, right).normalize();
+  const halfAngle = THREE.MathUtils.degToRad(Math.max(0, Math.min(360, guide.angle)) / 2);
+  const material = lineMaterial(guide);
+  const rim: THREE.Vector3[] = [];
+  for (let i = 0; i < 64; i++) {
+    const around = (i / 64) * Math.PI * 2;
+    const radial = right
+      .clone()
+      .multiplyScalar(Math.cos(around))
+      .addScaledVector(up, Math.sin(around));
+    rim.push(
+      origin
+        .clone()
+        .addScaledVector(direction, Math.cos(halfAngle) * guide.length)
+        .addScaledVector(radial, Math.sin(halfAngle) * guide.length),
+    );
+  }
+  addLine(root, rim, material, true);
+  for (const index of [0, 16, 32, 48]) addLine(root, [origin, rim[index]!], material);
+  return root;
+}
+
+function orientedPoint(
+  local: THREE.Vector3,
+  center: readonly [number, number, number],
+  rotation: readonly [number, number, number, number],
+): THREE.Vector3 {
+  return local.applyQuaternion(new THREE.Quaternion(...rotation)).add(new THREE.Vector3(...center));
+}
+
+function boxGuide(guide: Extract<SpatialHandleGuide, { kind: 'box' }>): THREE.Group {
+  const root = new THREE.Group();
+  const material = lineMaterial(guide);
+  const [x, y, z] = guide.halfExtents;
+  const corners = [
+    [-x, -y, -z],
+    [x, -y, -z],
+    [x, y, -z],
+    [-x, y, -z],
+    [-x, -y, z],
+    [x, -y, z],
+    [x, y, z],
+    [-x, y, z],
+  ].map(([cx, cy, cz]) =>
+    orientedPoint(new THREE.Vector3(cx, cy, cz), guide.center, guide.rotation),
+  );
+  for (const [a, b] of [
+    [0, 1],
+    [1, 2],
+    [2, 3],
+    [3, 0],
+    [4, 5],
+    [5, 6],
+    [6, 7],
+    [7, 4],
+    [0, 4],
+    [1, 5],
+    [2, 6],
+    [3, 7],
+  ] as const) {
+    addLine(root, [corners[a]!, corners[b]!], material);
+  }
+  return root;
+}
+
+function capsuleGuide(guide: Extract<SpatialHandleGuide, { kind: 'capsule' }>): THREE.Group {
+  const root = new THREE.Group();
+  const material = lineMaterial(guide);
+  const rotate = new THREE.Quaternion(...guide.rotation);
+  const center = vector(guide.center);
+  const transform = (point: THREE.Vector3): THREE.Vector3 =>
+    point.applyQuaternion(rotate).add(center);
+  const circle = (y: number, axisA: THREE.Vector3, axisB: THREE.Vector3): THREE.Vector3[] =>
+    circlePoints(new THREE.Vector3(0, y, 0), guide.radius, axisA, axisB).map(transform);
+  addLine(
+    root,
+    circle(guide.halfHeight, new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 0, 1)),
+    material,
+    true,
+  );
+  addLine(
+    root,
+    circle(-guide.halfHeight, new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 0, 1)),
+    material,
+    true,
+  );
+  for (const [x, z] of [
+    [guide.radius, 0],
+    [-guide.radius, 0],
+    [0, guide.radius],
+    [0, -guide.radius],
+  ]) {
+    addLine(
+      root,
+      [
+        transform(new THREE.Vector3(x, -guide.halfHeight, z)),
+        transform(new THREE.Vector3(x, guide.halfHeight, z)),
+      ],
+      material,
+    );
+  }
+  for (const axis of ['x', 'z'] as const) {
+    const points: THREE.Vector3[] = [];
+    for (let i = 0; i <= 32; i++) {
+      const angle = (i / 32) * Math.PI;
+      const point = new THREE.Vector3(0, guide.halfHeight + Math.sin(angle) * guide.radius, 0);
+      point[axis] = Math.cos(angle) * guide.radius;
+      points.push(transform(point));
+    }
+    for (let i = 0; i <= 32; i++) {
+      const angle = Math.PI + (i / 32) * Math.PI;
+      const point = new THREE.Vector3(0, -guide.halfHeight + Math.sin(angle) * guide.radius, 0);
+      point[axis] = Math.cos(angle) * guide.radius;
+      points.push(transform(point));
+    }
+    addLine(root, points, material);
+  }
+  return root;
+}
+
+function guideObject(guide: SpatialHandleGuide): THREE.Object3D {
+  const root =
+    guide.kind === 'line'
+      ? lineGuide(guide)
+      : guide.kind === 'sphere'
+        ? sphereGuide(guide)
+        : guide.kind === 'cone'
+          ? coneGuide(guide)
+          : guide.kind === 'box'
+            ? boxGuide(guide)
+            : capsuleGuide(guide);
+  root.layers.set(EDITOR_LAYER);
+  root.traverse((child) => child.layers.set(EDITOR_LAYER));
+  return root;
+}
+
+function handleMesh(nodeId: string, handle: SpatialDragHandle): SpatialHandleMesh {
+  const material = new THREE.MeshBasicMaterial({
+    color: handle.color,
+    depthTest: false,
+    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 });
+  mesh.position.copy(vector(handle.position));
+  mesh.renderOrder = 998;
+  mesh.layers.set(EDITOR_LAYER);
+  bindingByMesh.set(mesh, { nodeId, handle });
+  return mesh;
+}
+
+export function createSpatialHandleVisuals(
+  nodeId: string,
+  layers: readonly SpatialHandleLayer[],
+): SpatialHandleVisualSet {
+  const roots: THREE.Object3D[] = [];
+  const handles: SpatialHandleMesh[] = [];
+  for (const layer of layers) {
+    for (const guide of layer.guides) roots.push(guideObject(guide));
+    for (const handle of layer.handles) {
+      const mesh = handleMesh(nodeId, handle);
+      roots.push(mesh);
+      handles.push(mesh);
+    }
+  }
+  return { roots, handles };
+}
+
+export function spatialHandleBinding(mesh: SpatialHandleMesh): SpatialHandleBinding | null {
+  return bindingByMesh.get(mesh) ?? null;
+}
+
+export function setSpatialHandleHovered(mesh: SpatialHandleMesh, hovered: boolean): void {
+  const binding = bindingByMesh.get(mesh);
+  const material = mesh.material as THREE.MeshBasicMaterial;
+  material.color.set(
+    hovered && binding?.handle.writable ? '#ffffff' : (binding?.handle.color ?? '#ffffff'),
+  );
+}
+
+export function scaleSpatialHandle(mesh: SpatialHandleMesh, camera: THREE.Camera): void {
+  const distance = mesh.position.distanceTo(camera.position);
+  mesh.scale.setScalar(Math.max(0.025, distance * 0.012));
+}
+
+function disposeRenderable(
+  child: THREE.Object3D,
+  disposedGeometries: Set<THREE.BufferGeometry>,
+  disposedMaterials: Set<THREE.Material>,
+): void {
+  const renderable = child as THREE.Line | THREE.Mesh;
+  const geometry = renderable.geometry;
+  if (geometry && geometry !== HANDLE_GEOMETRY && !disposedGeometries.has(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;
+    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));
+  }
+}

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

@@ -0,0 +1,66 @@
+/**
+ * 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/editor-sdk/kit/stories/project-story-regions';
+import { declaredStoryMedium, reportUndeclaredStoryMedium } from '@volter/editor-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;
+}
+
+/**
+ * The DOM design board's membership — every story DECLARED as `dom`.
+ *
+ * An undeclared story is named once and is not a member. Nothing here
+ * 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
+ * `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.
+ */
+export function domStoryBoardMembers<
+  T extends {
+    readonly id?: string;
+    readonly name?: string;
+    readonly modulePath?: string;
+    readonly tags?: readonly string[];
+  },
+>(stories: readonly T[]): T[] {
+  const regions = getProjectStoryRegions();
+  const members: T[] = [];
+  for (const story of stories) {
+    const declared = declaredStoryMedium({ modulePath: story.modulePath, regions });
+    if (declared.medium === 'dom') {
+      members.push(story);
+      continue;
+    }
+    if (declared.via === 'undeclared' && story.modulePath) {
+      reportUndeclaredStoryMedium(story.modulePath, declared.reason);
+    }
+  }
+  return members;
+}
+

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

@@ -0,0 +1,44 @@
+/**
+ * The Three set's canvases, rendered at a caller's scale
+ * (`@volter/editor-sdk/kit/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/editor-sdk/kit/canvas-frames';
+import { allObject3DDocumentSessions } from './authoring/object3d-document-session-registry';
+import { liveCanvasFrame } from '@volter/editor-sdk/kit/live-canvas-frame';
+import { threeStoreForHost } from './three-state';
+
+async function imageOf(dataUrl: string): Promise<HTMLImageElement> {
+  const image = new Image();
+  image.src = dataUrl;
+  await image.decode();
+  return image;
+}
+
+export function registerThreeCanvasRender(): () => void {
+  return registerCanvasRender((canvas, size) => {
+    const store = threeStoreForHost();
+    if (store && store.viewportCanvas() === canvas) {
+      return (async () => {
+        const presented = await liveCanvasFrame(canvas);
+        if (presented) return presented;
+        const dataUrl = store.captureViewportImage(size);
+        return dataUrl ? imageOf(dataUrl) : null;
+      })();
+    }
+    const session = allObject3DDocumentSessions().find((candidate) => candidate.renderer.domElement === canvas);
+    if (!session) return null;
+    return (async () => {
+      // The PRESENTED frame first: everything the host drew over the document's
+      // own render — the compass above all — lives only in the default
+      // framebuffer, and `captureImage` is an offscreen re-render of the subject
+      // alone. Falling back to it keeps a stopped loop photographable.
+      const presented = await session.requestPresentedFrame();
+      if (presented) return presented;
+      const dataUrl = session.captureImage(size);
+      return dataUrl ? imageOf(dataUrl) : null;
+    })();
+  });
+}

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

@@ -0,0 +1,26 @@
+/**
+ * The Three integration's answers to the hierarchy panel's row questions
+ * (`@volter/editor-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.
+ */
+import { registerHierarchyRowMedia } from '@volter/editor-sdk/kit/hierarchy-row-media';
+import { entityObject3D } from './entity-object';
+import { markReaderFor } from './hierarchy-mark-reader';
+import { instancedRowDetail } from './instanced-presentation';
+import { threeStateOf } from './three-state';
+
+export function registerThreeHierarchyRowMedia(): () => void {
+  return registerHierarchyRowMedia({
+    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

@@ -0,0 +1,73 @@
+/**
+ * THE THREE.JS ANSWER TO "what does this node look like"
+ * (`@volter/editor-sdk/kit/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
+ * has an Asset Editor document to jump to. The kit's composer
+ * (`compose-subject.ts`) builds the sections from this answer.
+ */
+import {
+  type InspectionNodeMedia,
+  registerInspectionNodeMedia,
+} from '@volter/editor-sdk/kit/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/editor-sdk/kit/document-open-registry';
+import { InspectorPreviewBody } from '@volter/editor-sdk/kit/components/inspector-preview-section';
+import { entityObject3D } from './entity-object';
+import { describeInstancedPresentation } from './instanced-presentation';
+import { threeStoreForHost } from './three-state';
+
+
+// The heavy render stack stays behind `lazy()`, so a headless composer
+// (`editor.inspect`, which never renders) pays nothing for it.
+const InspectorObjectPreview = lazy(() =>
+  import('./components/InspectorObjectPreview').then((m) => ({ default: m.InspectorObjectPreview })),
+);
+
+function objectMedia(
+  object: THREE.Object3D,
+  assetDocument: InspectionNodeMedia['assetDocument'],
+): InspectionNodeMedia {
+  return {
+    preview: (object as THREE.Camera).isCamera
+      ? null
+      : ({ displayName, previewKey, actions }) =>
+          (mode) =>
+            createElement(InspectorPreviewBody, {
+              picture: () =>
+                createElement(InspectorObjectPreview, { previewKey, object, displayName, fill: true }),
+              previewKey,
+              actions,
+              ...(mode ? { mode } : {}),
+            }),
+    // `contentWorldBounds` resolves instance matrices live — three's own cached
+    // object box would answer for whatever pose was first asked about.
+    instanced: describeInstancedPresentation(object, contentWorldBounds(object)),
+    assetDocument,
+  };
+}
+
+export function registerThreeInspectionMedia(): () => void {
+  return registerInspectionNodeMedia((adapter, nodeId) => {
+    const store = threeStoreForHost();
+    if (!store) return null;
+    const object = entityObject3D(adapter, store.objectMap, nodeId);
+    if (!object) return null;
+    return objectMedia(
+      object,
+      store.objectMap.has(nodeId)
+        ? {
+            // The live `Object3D.name` is the only name there is.
+            open: () =>
+              openRegisteredDocument('asset-editor:entity', store.shell, {
+                entityId: nodeId,
+                title: object.name || nodeId,
+              }),
+          }
+        : null,
+    );
+  });
+}

package/src/kit/three-integration.ts

@@ -0,0 +1,86 @@
+/**
+ * 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
+ * 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/editor-sdk/kit/command-registry';
+import { saveThumbnail } from '@volter/editor-sdk/kit/editor-api';
+import { registerHostHierarchyObjects } from '../host-hierarchy-objects';
+import { registerContributionSurfaces } from '@volter/editor-sdk/kit/contribution-surfaces';
+import { registerRendererResourceCounts } from '@volter/editor-sdk/kit/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/editor-sdk/kit/project-local-state';
+import { onShellStore } from '@volter/editor-sdk/kit/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 { installViewportAuthoringPolicy } from './viewport-authoring-policy';
+import { viewportCommands } from './viewport-commands';
+import { reportViewportStatus } from './viewport-status-facet';
+
+/**
+ * The session's view state (tools, helpers, shading, camera) and its thumbnails, saved to the
+ * project's own `view` section. ONE object across a Fast Refresh of this module, because
+ * `attachStatePersistence` keeps one owner and a re-evaluated module constant is a new one.
+ */
+const hotData = (import.meta as ImportMeta & { hot?: { data: Record<string, unknown> } }).hot?.data;
+const VIEW_STATE_PERSISTENCE: EditorStatePersistence = (hotData?.['viewStatePersistence'] as
+  | EditorStatePersistence
+  | undefined) ?? {
+  save: (state) => writeProjectLocalSection('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;
+  const stops = [
+    registerContributionSurfaces({
+      Object3DPreview: Object3DPreviewSurface,
+      Object3DAuthoring: Object3DAuthoringSurface,
+    }),
+    registerContributedCommands('three-viewport', viewportCommands),
+    registerThreeAssetViewers(),
+    registerThreeInspectionMedia(),
+    registerModelThumbnails(),
+    reportViewportStatus(),
+    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),
+    // The session store's Three half saves its view state; attached once per store.
+    onShellStore((store) => threeStateOf(store).attachStatePersistence(VIEW_STATE_PERSISTENCE)),
+  ];
+  // The gizmo viewport's questions (which adapter is active, what is under the pointer, which
+  // root is world-hidden) are answered before any viewport mounts.
+  installViewportAuthoringPolicy(SHELL_VIEWPORT_AUTHORING_POLICY);
+  installed = () => {
+    for (const stop of stops.reverse()) stop();
+    installed = null;
+  };
+  return installed;
+}

package/src/kit/three-state.ts

@@ -0,0 +1,33 @@
+/** A shell store's Three half (`threeStateOf`, beside the half in `editor-shell-store.ts`). */
+import type { ShellStore } from '@volter/editor-sdk/kit/shell-store';
+import { type EditorShellStore, threeStateOf } from './editor-shell-store';
+import { useEditorStore, useOptionalEditorStore } from '@volter/editor-sdk/kit/editor-runtime';
+import { onShellStore, shellStoreForHost } from '@volter/editor-sdk/kit/shell-store-door';
+
+export { threeStateOf };
+
+/** {@link threeStateOf} for a store that may be absent (outside a session). */
+export function optionalThreeStateOf(store: ShellStore | null): EditorShellStore | null {
+  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)));
+}