@volter/editor-threejs 0.5.65 → 0.5.67

package/src/kit/editor-shell-store.ts

@@ -0,0 +1,814 @@
+/**
+ * EditorShellStore — the shell store's THREE half: the adopted scene and its object map, the
+ * renderer and camera, viewport tools (transform, snapping, pivot, gizmo), helper and shading
+ * state, LOD pins, capture and the periodic editor-state save. It extends `ShellStore`
+ * (`shell-store.ts`), the media-neutral half the kit's other modules type against, and leaves
+ * the kit for `@volter/editor-threejs` with the viewport (ARCHITECTURE.md §The plan, unit 3).
+ * It knows `THREE.Object3D`s and ids, never a document model: an adapter's document is that
+ * adapter's private business (`authoring-inversion-guard.test.ts` is the tripwire).
+ */
+
+import type { ViewportTab } from '@volter/editor-sdk';
+import { viewportCaptureOutputPass } from '@volter/editor-threejs/capture/output-pass';
+import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
+import type { WorldRendererConfig } from '@volter/editor-threejs/adapter/renderer-config';
+import { getUserData, setUserData } from '@volter/editor-threejs/ecs/user-data';
+import type { ViewportShadingMode } from '@volter/editor-threejs/render/viewport-shading';
+import * as THREE from 'three';
+import type { BatchedRenderer } from 'three.quarks';
+import { findEntityLod } from './entity-lod';
+import { entityIdOf } from './entity-object';
+import { ShellStore } from '@volter/editor-sdk/kit/shell-store';
+export type { NotifyScope, PlayEditRegime } from '@volter/editor-sdk/kit/shell-store';
+import { withSceneFogNeutralized } from './scene-view-fog';
+
+/** The store's persistence collaborator — installed by the shell, never
+ *  imported by the store (see `attachStatePersistence`). */
+export interface EditorStatePersistence {
+  save(state: Record<string, unknown>): unknown;
+  saveThumbnail?(dataUrl: string): unknown;
+}
+
+/**
+ * WHICH TOOL THE SHELF HAS ARMED — four that draw a transform gizmo, and one
+ * that draws none.
+ *
+ * `'select'` is Blender's Select Box, and it is a TOOL rather than an absence:
+ * its shelf opens on it (`space_toolsystem_toolbar.py`,
+ * `_defs_view3d_generic.select_box` first in the Object Mode `_tools_default`;
+ * photographed at the engine's pin in `gizmo-select-box.png`), so a selected
+ * object shows its outline and nothing else until Move / Rotate / Scale /
+ * Transform is armed. Before it there was no "no gizmo" state at all — this
+ * store's default was `'combined'` and every selection drew three tools'
+ * handles at once — which is why it is a member here rather than a flag beside
+ * it. `editor-viewport.ts` detaches on it, through the same branch a
+ * non-writable selection already took.
+ *
+ * Which member a STAGE is born with is its presentation's (`interaction.bootTool`,
+ * `kit/viewport-presentation`); arming one is always a click in the shelf.
+ */
+export type { GizmoAnchor, PivotMode, TransformMode, TransformSpace } from '@volter/editor-sdk/kit/shell-store';
+
+export type ShadingMode = ViewportShadingMode;
+
+/**
+ * What a store notification says CHANGED.
+ *
+ * `'selection'` is the narrow one and it is claimed by exactly five writers
+ * (`select`, `selectMultiple`, `addToSelection`, `toggleSelection`,
+ * `applySelectionBeforePresentation`), each of which touches
+ * `_viewportSelections` and nothing else. `'content'` is the default and means
+ * "assume anything may have changed", so a mutation that forgets to classify
+ * itself is safe by construction — the failure mode of a wrong claim is a
+ * stale panel, so the burden of proof sits on the narrow value.
+ * See {@link EditorShellStore.contentVersion}.
+ */
+
+/** Exact structural delta supplied by a live Three projection mutation. */
+export interface IngestObjectMapStructureDelta {
+  readonly changedParentIds: ReadonlySet<string>;
+  readonly rootsChanged: boolean;
+  /** Exact projected membership changes; omission keeps legacy callers conservative. */
+  readonly addedIds?: ReadonlySet<string>;
+  readonly removedIds?: ReadonlySet<string>;
+}
+
+/** All projected parent rows changed after a previously observed gizmo epoch. */
+export interface IngestObjectMapChanges {
+  readonly epoch: number;
+  readonly changedParentIds: ReadonlySet<string>;
+}
+
+/** Exact object-map identities whose membership changed after an observed gizmo epoch. */
+export interface IngestObjectMapMembershipChanges {
+  readonly epoch: number;
+  readonly changedIds: ReadonlySet<string>;
+}
+
+/** Enough exact structural epochs to span deferred React consumers; older readers rebuild. */
+const OBJECT_MAP_MEMBERSHIP_HISTORY = 256;
+
+
+
+/** The two viewport tabs, Edit · Play. Defined ONCE, in the SDK's shared
+ *  vocabulary (`@volter/editor-sdk`), because the control API speaks it too;
+ *  re-exported here so editor modules keep one import site. */
+export type { ViewportTab };
+
+export type { HelperVisibility } from '@volter/editor-sdk/kit/shell-store';
+
+export type { ViewportAction } from '@volter/editor-sdk/kit/shell-store';
+
+export class EditorShellStore {
+  /** Made by `threeStateOf`, once per shell store. */
+  constructor(readonly shell: ShellStore) {}
+
+  // --- Scene graph references (set via bindScene) ---
+  protected _scene: THREE.Scene | null = null;
+  /** Adoption stack (see enterPlayScene): each frame is the scene state that
+   *  was active when an adoption replaced it, restored in LIFO order by
+   *  exitPlayScene. A STACK (not a single slot) because adoptions nest for
+   *  R3F projects: the design session adopts its fiber scene at design time,
+   *  and play adopts the live game scene OVER it while the play-entry
+   *  transition still needs the design scene alive — the design session then
+   *  unwinds its own frame from the middle via releaseAdoptedScene. */
+  protected _adoptionStack: Array<{
+    /** `null` when the adoption replaced no scene: a session with no Scene stage plays too. */
+    scene: THREE.Scene | null;
+    objectMap: Map<string, THREE.Object3D>;
+    /** Opaque payload from {@link _captureAdoptionExtras} — a document half's
+     *  own per-adoption snapshot. The shell never inspects it. */
+    extras: unknown;
+    selection: Set<string>;
+    /** The image config that was active BEFORE this adoption — same LIFO
+     *  discipline as `scene`, so a frame spliced out of the middle simply
+     *  stops being a restore point. See {@link _applyAdoptedImageConfig}. */
+    imageConfig: WorldRendererConfig | undefined;
+  }> = [];
+  protected _objectMap = new Map<string, THREE.Object3D>();
+  protected _renderer: THREE.WebGLRenderer | null = null;
+  protected _camera: THREE.Camera | null = null;
+  protected _batchedRenderer: BatchedRenderer | null = null;
+  protected _lastThumbnailTime = 0;
+  protected _lastEditorStateSaveTime = 0;
+  protected _orbitTarget: THREE.Vector3 | null = null;
+
+  // --- UI state (not stored in scene graph) ---
+  /**
+   * Bumped whenever gizmos must be re-applied without a structural signature
+   * change (W3a B1): a single-entity rebuild (`_rebuildEntity` →
+   * `updateEntityPreview`) disposes the old Object3D WITH all its helper
+   * children, but leaves the objectMap identity/size and every toggle
+   * untouched — the viewport's `gizmoSig` gate would otherwise skip both
+   * `applyEntityGizmos` and the per-type visibility pass until an unrelated
+   * event.
+   */
+  protected _gizmoEpoch = 0;
+  /** Last structural epoch at which each projected parent's direct children changed. */
+  protected _objectMapParentChangedAt = new Map<string, number>();
+  /** A root change (or an unclassified legacy call) requires a full hierarchy read. */
+  protected _objectMapFullChangeEpoch = 0;
+  /** Last exact add/remove epoch for each projected id, independently consumed by the viewport. */
+  protected _objectMapMembershipChangedAt = new Map<string, number>();
+  /** Missing membership detail requires the viewport to reconcile its complete helper indexes. */
+  protected _objectMapMembershipFullChangeEpoch = 0;
+  /** Epochs older than this were compacted from the bounded membership history. */
+  protected _objectMapMembershipHistoryFloor = 0;
+  protected _showStats = false;
+  protected _shadingMode: ShadingMode = 'solid';
+  protected _statePersistence: EditorStatePersistence | null = null;
+  protected _vertexSnapActive = false;
+  /**
+   * Bumped only when post-processing-relevant state changes (environment / scene
+   * structure / play-stop scene swap). The viewport rebuilds its EffectComposer
+   * only when this changes — NOT on every notify — so a transform drag/scrub (which
+   * notifies per frame but never touches these) no longer recompiles shaders 60×/s.
+   */
+  protected _composerVersion = 0;
+  bindScene(
+    scene: THREE.Scene,
+    renderer?: THREE.WebGLRenderer,
+    batchedRenderer?: BatchedRenderer | null,
+    camera?: THREE.Camera,
+  ): void {
+    // A stage mounting while a scene is adopted binds the edit scene UNDER the adoption, where
+    // Stop restores it; the adopted scene stays the active one.
+    const base = this._adoptionStack[0];
+    if (base) base.scene = scene;
+    else this._scene = scene;
+    this._renderer = renderer ?? null;
+    this._batchedRenderer = batchedRenderer ?? null;
+    if (camera) this._camera = camera;
+  }
+
+  /** Set the orbit controls target reference for camera state persistence. */
+  setOrbitTarget(target: THREE.Vector3): void {
+    this._orbitTarget = target;
+  }
+
+  /** Update only the editor presentation camera (for perspective/orthographic
+   * switching) without rebinding or replacing an adopted game scene. */
+  setViewportCamera(camera: THREE.Camera): void {
+    this._camera = camera;
+  }
+
+
+  /**
+   * Where view/tool state and the autosave thumbnail go. The shell installs
+   * its transport here (`EditorContext` binds the server SDK); the store
+   * itself names no endpoint, so a document-local store (Asset Lab) or a
+   * fixture store simply never persists. Same collaborator shape as
+   * `attachHistory`, same one-owner rule.
+   */
+  attachStatePersistence(persistence: EditorStatePersistence): void {
+    if (this._statePersistence === persistence) return;
+    if (this._statePersistence) {
+      throw new Error('EditorStore is already attached to a state persistence.');
+    }
+    this._statePersistence = persistence;
+  }
+
+  /** The game camera lookup the last `focusOnScene` carried, read by the world stage while its
+   *  auto-frame window is open. */
+  get sceneCameraLookup(): (() => THREE.Camera | null) | null {
+    return this._sceneCameraLookup;
+  }
+  protected _sceneCameraLookup: (() => THREE.Camera | null) | null = null;
+
+  /**
+   * Frame the whole active scene — the first thing a reader should see when a
+   * world they did not author is adopted (an ingest mount). The viewport keeps
+   * asking until the world HAS content, because a game builds itself
+   * asynchronously; any camera input from the reader cancels it (see
+   * `the world root's stage`). A no-op for a scene the reader already has a camera on.
+   *
+   * `gameCamera` is a LIVE LOOKUP, not a camera: an adopted game's own camera
+   * may not exist yet on the frame it is captured on, so the viewport asks
+   * again while its window is open. When one turns up, its view is adopted
+   * instead of any measurement — see `scene-framing.ts`.
+   */
+  focusOnScene(gameCamera?: () => THREE.Camera | null): void {
+    this._sceneCameraLookup = gameCamera ?? null;
+    this.shell.focusOnScene();
+  }
+
+
+  /**
+   * Live viewport camera pose, read straight from the bound Three.js camera +
+   * orbit target (`bindScene`/`setOrbitTarget` — wired by `world-root-stage.ts`).
+   * Null only when nothing has bound a camera yet (e.g. a headless store in a
+   * unit test that never mounted `the world root's stage`).
+   */
+  get cameraPose(): { position: THREE.Vector3; target: THREE.Vector3; fov: number } | null {
+    if (!this._camera) return null;
+    const fov = (this._camera as THREE.PerspectiveCamera).fov;
+    return {
+      position: this._camera.position.clone(),
+      target: this._orbitTarget ? this._orbitTarget.clone() : new THREE.Vector3(),
+      fov: typeof fov === 'number' ? fov : 0,
+    };
+  }
+
+  // --- Scene graph accessors ---
+
+  /** The object map: entity ID → Three.js Object3D. */
+  get objectMap(): Map<string, THREE.Object3D> {
+    return this._objectMap;
+  }
+
+  /** The bound Three.js scene. */
+  get scene(): THREE.Scene | null {
+    return this._scene;
+  }
+
+  /** Monotonic counter bumped when post-processing inputs change (see field doc). */
+  get composerVersion(): number {
+    return this._composerVersion;
+  }
+
+  /** See {@link _gizmoEpoch} — folded into the viewport's gizmo signature. */
+  get gizmoEpoch(): number {
+    return this._gizmoEpoch;
+  }
+
+  /**
+   * Return the exact projected parents changed after `epoch`, or `null` when a
+   * root/unclassified change crossed that boundary and callers must rebuild.
+   * Parent timestamps make this safe across React batching: no consumer drains
+   * a shared queue, and several projectile commits collapse into one union.
+   */
+  ingestObjectMapChangesSince(epoch: number): IngestObjectMapChanges | null {
+    if (epoch < 0 || epoch > this._gizmoEpoch || epoch < this._objectMapFullChangeEpoch) {
+      return null;
+    }
+    const changedParentIds = new Set<string>();
+    for (const [id, changedAt] of this._objectMapParentChangedAt) {
+      if (changedAt > epoch) changedParentIds.add(id);
+    }
+    return { epoch: this._gizmoEpoch, changedParentIds };
+  }
+
+  /** Return exact added/removed identities since `epoch`, or `null` across an unclassified edit. */
+  ingestObjectMapMembershipChangesSince(epoch: number): IngestObjectMapMembershipChanges | null {
+    if (
+      epoch < 0 ||
+      epoch > this._gizmoEpoch ||
+      epoch < this._objectMapMembershipFullChangeEpoch ||
+      epoch < this._objectMapMembershipHistoryFloor
+    ) {
+      return null;
+    }
+    const changedIds = new Set<string>();
+    for (const [id, changedAt] of this._objectMapMembershipChangedAt) {
+      if (changedAt > epoch) changedIds.add(id);
+    }
+    return { epoch: this._gizmoEpoch, changedIds };
+  }
+
+  isSkeletonVisible(id: string): boolean {
+    return Boolean(getUserData(this._objectMap.get(id), 'skeletonVisible'));
+  }
+
+  setSkeletonVisible(id: string, visible: boolean): void {
+    const object = this._objectMap.get(id);
+    if (!object) return;
+    setUserData(object, 'skeletonVisible', visible);
+    object.traverse((child) => {
+      if (getUserData(child, 'editorHelperType') !== 'skeletons') return;
+      setUserData(child, 'skeletonEnabled', visible);
+      child.visible = visible || this.shell.helperVisibility.skeletons;
+    });
+    this.shell.notifyChange();
+  }
+  get showStats(): boolean {
+    return this._showStats;
+  }
+  get shadingMode(): ShadingMode {
+    return this._shadingMode;
+  }
+  /** Notify subscribers after an ingest adapter mutated a live foreign object
+   *  (material/visibility). Runtime-only — no dirty/autosave, because the edit
+   *  lives on the live `Object3D` and nothing here owns a document. */
+
+  /** Notify after a live adapter changed `objectMap` membership.
+   *
+   * Unlike an ordinary reflected-property edit, a membership change requires
+   * the viewport to re-apply native helper visibility. The map is mutated in
+   * place, and a remove+add burst can keep its size unchanged, so neither map
+   * identity nor size is a complete signal. `_gizmoEpoch` is the viewport's
+   * existing explicit rebuild input; bump it only at this structural seam. */
+  notifyIngestObjectMapEdit(delta?: IngestObjectMapStructureDelta): void {
+    this._gizmoEpoch++;
+    if (delta === undefined || delta.rootsChanged) {
+      this._objectMapFullChangeEpoch = this._gizmoEpoch;
+      this._objectMapParentChangedAt.clear();
+    } else {
+      for (const id of delta.changedParentIds) {
+        this._objectMapParentChangedAt.set(id, this._gizmoEpoch);
+      }
+    }
+    if (delta?.addedIds === undefined || delta.removedIds === undefined) {
+      this._objectMapMembershipFullChangeEpoch = this._gizmoEpoch;
+      this._objectMapMembershipChangedAt.clear();
+    } else {
+      for (const id of delta.addedIds) this._objectMapMembershipChangedAt.set(id, this._gizmoEpoch);
+      for (const id of delta.removedIds) {
+        this._objectMapMembershipChangedAt.set(id, this._gizmoEpoch);
+      }
+      const historyFloor = Math.max(0, this._gizmoEpoch - OBJECT_MAP_MEMBERSHIP_HISTORY);
+      if (historyFloor > this._objectMapMembershipHistoryFloor) {
+        this._objectMapMembershipHistoryFloor = historyFloor;
+        for (const [id, changedAt] of this._objectMapMembershipChangedAt) {
+          if (changedAt <= historyFloor) this._objectMapMembershipChangedAt.delete(id);
+        }
+      }
+    }
+    const affectsShell =
+      delta === undefined ||
+      delta.rootsChanged ||
+      [...(delta.addedIds ?? []), ...(delta.removedIds ?? [])].some((id) =>
+        this.shell.selectedEntityIds.has(id),
+      );
+    this.shell.notifyChange('content', affectsShell ? 'shell' : 'object-map', false);
+  }
+
+  // --- Play mode scene swap ---
+
+  /** Callback to sync transform edits to game ECS. Set by play-mode, cleared on exit.
+   *  Receives the NODE ID as well as the live object: the `PhysicsAdapter` seam
+   *  it ultimately feeds is id-keyed since P-4, and the id is already in hand
+   *  at the one call site — so nothing downstream has to map an object back. */
+  protected _ecsSyncTransform: ((id: string, obj: THREE.Object3D) => void) | null = null;
+
+  /** Set a callback that syncs editor transform changes to the game's ECS state. */
+  setEcsSyncTransform(fn: ((id: string, obj: THREE.Object3D) => void) | null): void {
+    this._ecsSyncTransform = fn;
+  }
+
+  /**
+   * Swap the store's active scene to the game scene. Editor scene is preserved.
+   *
+   * Also snapshots whatever the active document half hands back from
+   * {@link _captureAdoptionExtras}. A half that keeps mutating its LIVE
+   * metadata during play (so its inspector fields keep working) must have
+   * those edits discarded when play stops — otherwise a play-time edit
+   * silently persists with `isDirty` false. `exitPlayScene` restores the
+   * snapshot.
+   */
+  enterPlayScene(
+    gameScene: THREE.Scene,
+    imageConfig?: WorldRendererConfig | undefined,
+    projectedObjects?: ReadonlyMap<string, THREE.Object3D>,
+  ): void {
+    this._adoptionStack.push({
+      scene: this._scene,
+      objectMap: this._objectMap,
+      extras: this._captureAdoptionExtras(),
+      selection: new Set(this.shell.selectedEntityIds),
+      imageConfig: this._adoptedImageConfig,
+    });
+    this._scene = gameScene;
+    this._applyAdoptedImageConfig(imageConfig);
+
+    // The store INDEXES an adopted scene; it no longer models it. A foreign
+    // adapter supplies its pure projection explicitly, so editor identity is
+    // never written into the game's Object3Ds. Source-backed/adopted worlds
+    // already carry native authoring stamps and retain the fallback walk.
+    const gameMap = projectedObjects
+      ? new Map(projectedObjects)
+      : (() => {
+          const stamped = new Map<string, THREE.Object3D>();
+          const visit = (obj: THREE.Object3D): void => {
+            if (isEditorOwnedObject(obj)) return;
+            const eid = entityIdOf(obj);
+            if (eid !== undefined) stamped.set(eid, obj);
+            for (const child of obj.children) visit(child);
+          };
+          for (const child of gameScene.children) visit(child);
+          return stamped;
+        })();
+    this._objectMap = gameMap;
+
+    this.shell.applySelectionBeforePresentation(
+      [...this.shell.selectedEntityIds].filter((id) => gameMap.has(id)),
+    );
+    // A viewport LOD pin must not follow the entity id into the adopted game
+    // scene — there `WebGLRenderer.projectObject` owns level visibility (it
+    // calls `lod.update(camera)` for every visible LOD whose `autoUpdate` is
+    // still true, which is what a pin turns OFF), and per-frame enforcement
+    // would fight it.
+    this._lodForcedLevels.clear();
+    this._composerVersion++; // scene swapped → composer must rebuild against the game scene
+    this.shell.notifyChange();
+  }
+
+  /** Whether the active scene is one another document adopted (`enterPlayScene`). */
+  get hasAdoptedScene(): boolean {
+    return this._adoptionStack.length > 0;
+  }
+
+  /** Restore the previously-adopted scene (LIFO — see enterPlayScene). */
+  exitPlayScene(): void {
+    const frame = this._adoptionStack.pop();
+    if (!frame) return;
+    this._scene = frame.scene;
+    this._objectMap = frame.objectMap;
+    this._applyAdoptedImageConfig(frame.imageConfig);
+    // Discard any play-time env/name/ui edits — restore the pre-play snapshot.
+    this._restoreAdoptionExtras(frame.extras);
+    this.shell.applySelectionBeforePresentation([...frame.selection]);
+    this._composerVersion++; // scene swapped back → composer must rebuild against the editor scene
+    this.shell.notifyChange();
+  }
+
+  /**
+   * Release ONE adopter's adoption, wherever it sits in the stack. When
+   * `scene` is the ACTIVE scene this is exactly `exitPlayScene`; when a later
+   * adoption (play over the R3F design session) has already replaced it, the
+   * frame that would restore `scene` is unlinked from the middle of the stack
+   * instead — nothing visible changes now, and the LATER adopter's exit
+   * restores the state underneath as if this adoption never happened. No-op
+   * when `scene` was never adopted (or was already released).
+   */
+  releaseAdoptedScene(scene: THREE.Scene): void {
+    if (this._scene === scene) {
+      this.exitPlayScene();
+      return;
+    }
+    const index = this._adoptionStack.findIndex((frame) => frame.scene === scene);
+    if (index === -1) return;
+    this._adoptionStack.splice(index, 1);
+  }
+
+  /**
+   * THE ADOPTED CONTENT'S OWN COLOUR PIPELINE — what it is, not where it is
+   * applied.
+   *
+   * A mounted world may report the pipeline it was authored for
+   * (`MountedThreeRoot.rendererConfig`), and `applyWorldRendererConfig` puts it
+   * on the renderer its own host handed it. In the editor those are two
+   * DIFFERENT renderers: the design session mounts against a non-rasterizing
+   * one (`authoring/design-time-renderer.ts`) and the viewport draws the
+   * mounted scene with its own. So the declaration landed on a surface with no
+   * pixels while the surface with pixels kept the engine's defaults — measured
+   * on the translated Godot platformer, whose roughness-0 metal reads as chrome
+   * under the editor's ACES while the game renders it under its own curve.
+   *
+   * The store only REMEMBERS the declaration and bumps `_composerVersion` when
+   * it changes; `the world root's stage.rebuildComposer` is the one place that derives
+   * the viewport renderer's whole configuration, and it applies this last. That
+   * split is why there is no restore bookkeeping here: a rebuild always resets
+   * the renderer to the engine defaults first, so "unwind" is just the next
+   * rebuild seeing a different (or absent) config.
+   */
+  protected _adoptedImageConfig: WorldRendererConfig | undefined;
+
+  /** What the active adopted content declared about the renderer that draws it,
+   *  or `undefined` when it declared nothing (leave the editor's own alone). */
+  get adoptedImageConfig(): WorldRendererConfig | undefined {
+    return this._adoptedImageConfig;
+  }
+
+  protected _applyAdoptedImageConfig(next: WorldRendererConfig | undefined): void {
+    if (next === this._adoptedImageConfig) return;
+    this._adoptedImageConfig = next;
+    this._composerVersion++;
+  }
+
+  /** True while an ADOPTED live game scene is the active scene — every
+   *  `enterPlayScene` caller: play adoption, ingest mounts, and the R3F
+   *  design session. Adopted scenes own their lighting/rendering completely;
+   *  the viewport uses this to keep editor-fabricated presentation (the
+   *  helper light rig) out of them. */
+  get isAdoptedSceneActive(): boolean {
+    return this._adoptionStack.length > 0;
+  }
+
+  // --- Vertex snap ---
+  get vertexSnapActive(): boolean {
+    return this._vertexSnapActive;
+  }
+  setVertexSnapActive(active: boolean): void {
+    this._vertexSnapActive = active;
+    this.shell.notifyChange();
+  }
+
+  protected static readonly THUMBNAIL_INTERVAL_MS = 60_000;
+  protected static readonly THUMBNAIL_SIZE = 256;
+
+  /**
+   * Render the bound camera's current view to a PNG data URL at `size`x`size`.
+   * Autosave thumbnails request game content only; an explicit SDK/editor
+   * viewport capture requests every camera layer so grid/helpers/gizmos are
+   * represented honestly. Both use the same offscreen render-target technique,
+   * so neither needs `preserveDrawingBuffer` on the live WebGL canvas.
+   *
+   * THE COLOUR PIPELINE IS THE WHOLE REASON THERE ARE TWO TARGETS. Three
+   * applies `renderer.toneMapping` and `renderer.outputColorSpace` ONLY when
+   * the destination is the canvas: rendering into an ordinary
+   * `WebGLRenderTarget` compiles every material with `NoToneMapping` and a
+   * LINEAR output transfer (`WebGLPrograms.getParameters` and
+   * `WebGLRenderer.setProgram` both gate on `currentRenderTarget === null`).
+   * So the single-target version of this function answered "what does the
+   * viewport look like" with a raw linear frame — measurably darker and
+   * flatter than the pixels on screen, and immune to every tone-mapping
+   * change (verified live: flipping the viewport to `NoToneMapping` moved the
+   * captured PNG by 0 bytes). That made this door — the only look at the EDIT
+   * viewport, and the source of every project thumbnail — unusable as
+   * evidence about the image.
+   *
+   * The fix is three's own: render the scene into a HALF-FLOAT linear buffer
+   * (so highlights survive to be tone-mapped) and resolve it through
+   * `OutputPass`, which reads `toneMapping`/`toneMappingExposure`/
+   * `outputColorSpace` off the renderer and applies exactly what the on-screen
+   * frame gets.
+   */
+  protected _renderViewportImage(
+    size: number | { width: number; height: number },
+    includeEditorLayers: boolean,
+  ): string | null {
+    if (!this._renderer || !this._scene || !this._camera) return null;
+    // A number is a SQUARE of that size — the default shape; `{width, height}`
+    // renders the buffer and the camera at that aspect so a shaped look needs
+    // no crop (`@volter/editor-sdk`'s `CaptureDimensions`).
+    const width = typeof size === 'number' ? size : size.width;
+    const height = typeof size === 'number' ? size : size.height;
+    // The same floor `authoring/object3d-document-session.ts`'s `captureImage`
+    // already sets, for the same reason: the doubled size is handed straight to
+    // `createImageData`, so a non-finite size throws
+    // `TypeError: Value is not of type 'long'` from the middle of the render
+    // path instead of failing where the value entered.
+    if (!Number.isFinite(width) || width < 1) return null;
+    if (!Number.isFinite(height) || height < 1) return null;
+
+    // render at 2x then downscale for crisp result
+    const renderWidth = width * 2;
+    const renderHeight = height * 2;
+    const renderer = this._renderer;
+    const sceneTarget = new THREE.WebGLRenderTarget(renderWidth, renderHeight, {
+      type: THREE.HalfFloatType,
+    });
+    const renderTarget = new THREE.WebGLRenderTarget(renderWidth, renderHeight);
+    const prevTarget = renderer.getRenderTarget();
+    const prevPixelRatio = renderer.getPixelRatio();
+
+    const camera = this._camera;
+    const prevLayers = camera.layers.mask;
+    const perspectiveCamera = camera instanceof THREE.PerspectiveCamera ? camera : null;
+    const previousAspect = perspectiveCamera?.aspect;
+    if (includeEditorLayers) {
+      camera.layers.enableAll();
+    } else {
+      camera.layers.disableAll();
+      camera.layers.enable(0); // clean project thumbnail: game content only
+    }
+
+    try {
+      if (perspectiveCamera) {
+        perspectiveCamera.aspect = width / height;
+        perspectiveCamera.updateProjectionMatrix();
+      }
+      renderer.setPixelRatio(1);
+      renderer.setRenderTarget(sceneTarget);
+      // The same view policy the on-screen draw applies (`scene-view-fog.ts`).
+      // This capture is the ONLY look anyone gets at the Edit viewport — the
+      // `vgai screenshot` evidence and every project thumbnail — so a capture
+      // that renders the game's fog while the viewport does not would make the
+      // one door onto the image disagree with the image.
+      withSceneFogNeutralized(this._scene, () =>
+        renderer.render(this._scene as THREE.Scene, camera),
+      );
+      viewportCaptureOutputPass().render(renderer, renderTarget, sceneTarget, 0, false);
+    } finally {
+      renderer.setRenderTarget(prevTarget);
+      renderer.setPixelRatio(prevPixelRatio);
+      camera.layers.mask = prevLayers;
+      if (perspectiveCamera && previousAspect !== undefined) {
+        perspectiveCamera.aspect = previousAspect;
+        perspectiveCamera.updateProjectionMatrix();
+      }
+    }
+
+    // Read pixels from the render target
+    const rowBytes = renderWidth * 4;
+    const pixels = new Uint8Array(rowBytes * renderHeight);
+    renderer.readRenderTargetPixels(renderTarget, 0, 0, renderWidth, renderHeight, pixels);
+    renderTarget.dispose();
+    sceneTarget.dispose();
+
+    // Flip vertically (WebGL reads bottom-up) and write to a full-size canvas
+    const fullCanvas = document.createElement('canvas');
+    fullCanvas.width = renderWidth;
+    fullCanvas.height = renderHeight;
+    const fullCtx = fullCanvas.getContext('2d')!;
+    const imageData = fullCtx.createImageData(renderWidth, renderHeight);
+    for (let y = 0; y < renderHeight; y++) {
+      const srcRow = (renderHeight - 1 - y) * rowBytes;
+      const dstRow = y * rowBytes;
+      imageData.data.set(pixels.subarray(srcRow, srcRow + rowBytes), dstRow);
+    }
+    fullCtx.putImageData(imageData, 0, 0);
+
+    // Downscale to the requested size
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx2d = canvas.getContext('2d')!;
+    ctx2d.drawImage(fullCanvas, 0, 0, width, height);
+
+    return canvas.toDataURL('image/png');
+  }
+
+  protected _captureThumbnail(): void {
+    const now = Date.now();
+    if (now - this._lastThumbnailTime < EditorShellStore.THUMBNAIL_INTERVAL_MS) return;
+    this._lastThumbnailTime = now;
+    const dataUrl = this._renderViewportImage(EditorShellStore.THUMBNAIL_SIZE, false);
+    if (dataUrl) void this._statePersistence?.saveThumbnail?.(dataUrl);
+  }
+
+  /**
+   * Fresh, on-demand viewport capture (unthrottled, unlike the periodic
+   * autosave thumbnail above) — backs the `capture-viewport` relay command.
+   * Returns null when no renderer/scene/camera is bound yet (e.g. before
+   * `the world root's stage` has mounted).
+   */
+  captureViewportImage(
+    size: number | { width: number; height: number } = EditorShellStore.THUMBNAIL_SIZE,
+  ): string | null {
+    return this._renderViewportImage(size, true);
+  }
+
+  /** The live Scene viewport's own `<canvas>`, or null before a renderer is
+   *  bound. A photograph of the whole editor page (`editor-chrome-capture.ts`)
+   *  needs to recognise it: its WebGL context has no `preserveDrawingBuffer`,
+   *  so its pixels come from {@link captureViewportImage}, not a late read. */
+  viewportCanvas(): HTMLCanvasElement | null {
+    return this._renderer?.domElement ?? null;
+  }
+
+  // --- Editor state persistence ---
+
+  protected static readonly EDITOR_STATE_INTERVAL_MS = 60_000;
+
+  protected _saveEditorStateIfDue(): void {
+    if (!this._statePersistence) return;
+    const now = Date.now();
+    if (now - this._lastEditorStateSaveTime < EditorShellStore.EDITOR_STATE_INTERVAL_MS) return;
+    this._lastEditorStateSaveTime = now;
+
+    const state: Record<string, unknown> = {
+      transformMode: this.shell.transformMode,
+      transformSpace: this.shell.transformSpace,
+      snapEnabled: this.shell.snapEnabled,
+      snapValues: this.shell.snapValues,
+      preserveChildrenTransform: this.shell.preserveChildrenTransform,
+      pivotMode: this.shell.pivotMode,
+      gizmoAnchor: this.shell.gizmoAnchor,
+      showHelpers: this.shell.showHelpers,
+      helperVisibility: { ...this.shell.helperVisibility },
+      showStats: this._showStats,
+      shadingMode: this._shadingMode,
+    };
+
+    Object.assign(state, this._editorStateExtras());
+
+    if (this._camera) {
+      const cam = this._camera as THREE.PerspectiveCamera;
+      state['camera'] = {
+        position: cam.position.toArray(),
+        target: this._orbitTarget ? this._orbitTarget.toArray() : [0, 0, 0],
+      };
+    }
+
+    void this._statePersistence.save(state);
+  }
+
+  // --- Mutations ---
+
+  /**
+   * EDITOR-ONLY level-preview override (W2b): entity id → index into the
+   * live THREE.LOD's (ascending-by-distance) levels to pin in the viewport.
+   * Pure UI state — never written to the descriptor, so it can't leak into
+   * the saved scene or the undo history. Enforced per frame by
+   * `EditorViewport.update` (the glTF loads async and entity rebuilds replace
+   * the THREE.LOD instance, so a one-shot apply would silently un-pin).
+   */
+  protected _lodForcedLevels = new Map<string, number>();
+
+  get lodForcedLevels(): ReadonlyMap<string, number> {
+    return this._lodForcedLevels;
+  }
+
+  getLodForcedLevel(id: string): number | null {
+    return this._lodForcedLevels.get(id) ?? null;
+  }
+
+  /** Pin an entity's viewport LOD display to one level, or `null` for Auto
+   * (distance-based selection — the renderer's own `LOD.update(camera)`). */
+  setLodForcedLevel(id: string, level: number | null): void {
+    if (level === null) {
+      this._lodForcedLevels.delete(id);
+      // Hand control back to the renderer's distance-based selection.
+      const obj = this._objectMap.get(id);
+      const projectedObjects = new Set(this._objectMap.values());
+      const lodObj = obj ? findEntityLod(obj, (node) => projectedObjects.has(node)) : null;
+      if (lodObj) lodObj.autoUpdate = true;
+    } else {
+      this._lodForcedLevels.set(id, level);
+    }
+    this.shell.notifyChange();
+  }
+
+  toggleStats(): void {
+    this._showStats = !this._showStats;
+    this.shell.notifyChange();
+  }
+
+  setShadingMode(mode: ShadingMode): void {
+    this._shadingMode = mode;
+    // View-only state. The viewport applies it during its own render and
+    // restores native materials before returning to editor/game code.
+    this.shell.notifyChange();
+  }
+
+  // --- Subclass hooks -------------------------------------------------------
+  // The ONLY way the shell reaches into a document half. Each is a no-op here,
+  // so the shell runs standalone; a subclass that owns a document overrides the
+  // ones it needs (`store-notify-scope.test.ts` exercises the deferral hooks).
+
+
+
+  /** Captured into the adoption frame by `enterPlayScene`, handed back by
+   *  `exitPlayScene`. A document half snapshots its metadata here so
+   *  play-time edits to it are discarded on exit. */
+  protected _captureAdoptionExtras(): unknown {
+    return undefined;
+  }
+
+  /** Restore counterpart of {@link _captureAdoptionExtras}. */
+  protected _restoreAdoptionExtras(_extras: unknown): void {}
+
+
+  /** Extra keys folded into the periodic editor-state save. A document half
+   *  contributes whatever it needs restored on the next boot. */
+  protected _editorStateExtras(): Record<string, unknown> {
+    return {};
+  }
+}
+
+const threeStates = new WeakMap<ShellStore, EditorShellStore>();
+
+/**
+ * The Three half of a shell store, made the first time it is asked for. Kit modules hand out
+ * the media-neutral `ShellStore`; Three code asks here for its own half, so the kit constructs
+ * only the neutral store and a composition without Three never makes one.
+ */
+export function threeStateOf(store: ShellStore): EditorShellStore {
+  let three = threeStates.get(store);
+  if (!three) {
+    three = new EditorShellStore(store);
+    threeStates.set(store, three);
+  }
+  return three;
+}