@volter/editor-core 0.5.57

package/src/three-viewport/selection-outline.ts

@@ -0,0 +1,183 @@
+/**
+ * Native Three selection presentation for editor-owned authoring viewports.
+ *
+ * A transform box answers where an object's editable bounds are; it does not
+ * answer which pixels belong to the selected object. Unity and Unreal draw
+ * both for that reason. This module supplies the geometry-following half with
+ * postprocessing's real OutlineEffect, while EditorViewport keeps native
+ * helpers for cameras, lights, bones and other nodes that draw no geometry.
+ *
+ * The effect is presentation only. It never enters a project render pipeline,
+ * changes source, or adds an authoring-data format.
+ */
+
+import {
+  EDITOR_SELECTION_LAYER,
+  isInEditorOwnedSubtree,
+} from '@volter/editor-threejs/viewport/editor-layers';
+import type { OutlineEffect } from 'postprocessing';
+import type * as THREE from 'three';
+
+/**
+ * The three postprocessing bindings {@link createThreeSelectionOutline} needs,
+ * passed in rather than statically imported.
+ *
+ * `postprocessing` is ~200 kB of shaders and passes, and the surfaces this
+ * module serves do not all want it: `editor-viewport.ts` imports only
+ * {@link collectThreeSelectionOutlineTargets} (a pure traversal), and the
+ * Asset Lab 3D document builds its composer on its FIRST frame, not at module
+ * load. A static import here put the whole library in both closures
+ * eagerly. A caller that already loaded postprocessing for its own composer
+ * hands over its own bindings (`the world root's stage`); one that has not opens the
+ * lazy door {@link loadThreeSelectionOutline}.
+ */
+export interface ThreeSelectionOutlineEffects {
+  readonly OutlineEffect: typeof import('postprocessing').OutlineEffect;
+  readonly BlendFunction: typeof import('postprocessing').BlendFunction;
+  readonly KernelSize: typeof import('postprocessing').KernelSize;
+}
+
+/**
+ * Build the editor's real postprocessing effect. A half-resolution medium
+ * blur resolves to a stable 3–4 CSS-pixel silhouette on both 1x and HiDPI
+ * displays instead of a driver-dependent hairline; pulse is deliberately
+ * disabled because selection is state, not an alert.
+ */
+export function createThreeSelectionOutline(
+  { BlendFunction, KernelSize, OutlineEffect }: ThreeSelectionOutlineEffects,
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  colors: { readonly visible: number; readonly hidden: number },
+): OutlineEffect {
+  const effect = withoutSelectionLayerWarning(
+    () =>
+      new OutlineEffect(scene, camera, {
+        // Alpha keeps the selection color legible over both black and white
+        // materials. The effect's default screen blend washes out on pale assets.
+        blendFunction: BlendFunction.ALPHA,
+        visibleEdgeColor: colors.visible,
+        hiddenEdgeColor: colors.hidden,
+        edgeStrength: 5,
+        pulseSpeed: 0,
+        blur: true,
+        kernelSize: KernelSize.MEDIUM,
+        resolutionScale: 0.5,
+        xRay: true,
+      }),
+  );
+  // OutlineEffect temporarily removes layer 0 from selected meshes, renders
+  // scene depth, then renders only its selection layer for the mask. The
+  // editor camera normally enables ALL layers so it can draw layer-31 gizmos;
+  // without this exclusion the selected mesh remains in the depth pass via
+  // the effect's own layer and both masks cancel to no visible edge.
+  effect.selectionLayer = EDITOR_SELECTION_LAYER;
+  camera.layers.disable(EDITOR_SELECTION_LAYER);
+  return effect;
+}
+
+/**
+ * `OutlineEffect` constructs its `Selection` with a render layer taken from
+ * a module-wide counter, which the editor then overrides
+ * (`EDITOR_SELECTION_LAYER`, below). The counter still moves, and after 30
+ * constructions in one page — every Object3D document session builds its
+ * own effect — the library warns "Layer out of range, resetting to 2" and
+ * carries on. For this editor that line is noise: the layer it worries
+ * about is replaced before the effect ever renders. The console gate treats
+ * every warning as unresolved work, so the one message is held back for
+ * exactly the synchronous construction that provokes it; anything else the
+ * constructor says still reaches the console.
+ */
+function withoutSelectionLayerWarning<T>(construct: () => T): T {
+  const warn = console.warn;
+  console.warn = (...args: unknown[]) => {
+    if (args[0] === 'Layer out of range, resetting to 2') return;
+    warn.apply(console, args);
+  };
+  try {
+    return construct();
+  } finally {
+    console.warn = warn;
+  }
+}
+
+/** THE LAZY DOOR: load `postprocessing` on demand and build the effect. For a
+ *  caller with no composer of its own, so the library arrives with the
+ *  silhouette rather than with the surface. Repeat calls are free — the module
+ *  is cached after the first. */
+export async function loadThreeSelectionOutline(
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  colors: { readonly visible: number; readonly hidden: number },
+): Promise<OutlineEffect> {
+  const { BlendFunction, KernelSize, OutlineEffect } = await import('postprocessing');
+  return createThreeSelectionOutline(
+    { BlendFunction, KernelSize, OutlineEffect },
+    scene,
+    camera,
+    colors,
+  );
+}
+
+/** Apply supplied renderer-ready colors without rebuilding GPU pass resources. */
+export function setThreeSelectionOutlineColors(
+  effect: OutlineEffect,
+  colors: { readonly visible: number; readonly hidden: number },
+): void {
+  effect.visibleEdgeColor.setHex(colors.visible);
+  effect.hiddenEdgeColor.setHex(colors.hidden);
+}
+
+function isOutlineRenderable(object: THREE.Object3D): boolean {
+  if ((object as THREE.Bone).isBone) return false;
+  return (
+    (object as THREE.Mesh).isMesh ||
+    (object as THREE.Line).isLine ||
+    (object as THREE.Points).isPoints ||
+    (object as THREE.Sprite).isSprite
+  );
+}
+
+/**
+ * Expand selected semantic roots to the actual renderables postprocessing can
+ * mask. Selection rows commonly name a Group/component root, while an outline
+ * effect can only paint its Mesh/Line/Points/Sprite descendants.
+ */
+export function collectThreeSelectionOutlineTargets(
+  selectedRoots: Iterable<THREE.Object3D>,
+): THREE.Object3D[] {
+  const targets: THREE.Object3D[] = [];
+  const seen = new Set<THREE.Object3D>();
+  for (const root of selectedRoots) {
+    // A bone has its own native joint highlight. Walking through it to a
+    // skinned/accessory descendant would make selecting the joint look like
+    // selecting the model instead.
+    if ((root as THREE.Bone).isBone) continue;
+    // Select what the component actually DRAWS, including implementation
+    // children folded out of the hierarchy. Unlike an AABB measurement, the
+    // mask pass cannot be poisoned by pooled/template geometry that is not
+    // currently rendered; it only paints pixels the subtree draws now.
+    root.traverse((object) => {
+      if (seen.has(object) || isInEditorOwnedSubtree(object) || !isOutlineRenderable(object)) {
+        return;
+      }
+      seen.add(object);
+      targets.push(object);
+    });
+  }
+  return targets;
+}
+
+/** Update only when the concrete renderable set changed, avoiding layer churn. */
+export function syncThreeSelectionOutline(
+  effect: OutlineEffect,
+  selectedRoots: Iterable<THREE.Object3D>,
+): void {
+  const targets = collectThreeSelectionOutlineTargets(selectedRoots);
+  if (
+    effect.selection.size === targets.length &&
+    targets.every((target) => effect.selection.has(target))
+  ) {
+    return;
+  }
+  effect.selection.set(targets);
+}

package/src/three-viewport/skeleton-helper.ts

@@ -0,0 +1,61 @@
+import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
+import { getObjectMark, setObjectMark } from '@volter/editor-threejs/ecs/object-marks';
+import * as THREE from 'three';
+
+const SKELETON_HELPER_TYPE = 'skeletons';
+const SKELETON_PARENT_COLOR = new THREE.Color(0x00e5ff);
+const SKELETON_CHILD_COLOR = new THREE.Color(0xffb000);
+
+export function styleEditorSkeletonHelper(helper: THREE.SkeletonHelper): void {
+  const colors = helper.geometry.getAttribute('color');
+  // SkeletonHelper emits two vertices per bone link. Three's stock pure
+  // blue/green endpoints disappear against vgai's dark viewport, especially
+  // in captures. Keep the native helper geometry, but use editor-contrast
+  // colors so the inspection affordance is actually visible.
+  for (let i = 0; i < colors.count; i += 2) {
+    colors.setXYZ(i, SKELETON_PARENT_COLOR.r, SKELETON_PARENT_COLOR.g, SKELETON_PARENT_COLOR.b);
+    if (i + 1 < colors.count) {
+      colors.setXYZ(i + 1, SKELETON_CHILD_COLOR.r, SKELETON_CHILD_COLOR.g, SKELETON_CHILD_COLOR.b);
+    }
+  }
+  colors.needsUpdate = true;
+  helper.renderOrder = 999;
+  const material = helper.material as THREE.LineBasicMaterial;
+  material.depthTest = false;
+  material.depthWrite = false;
+  material.toneMapped = false;
+  setObjectMark(helper, 'editorHelper', true);
+  setObjectMark(helper, 'editorHelperType', SKELETON_HELPER_TYPE);
+  helper.traverse((child) => child.layers.set(EDITOR_LAYER));
+}
+
+export function ensureSkeletonHelper(root: THREE.Object3D): THREE.SkeletonHelper | null {
+  let existing: THREE.SkeletonHelper | null = null;
+  let hasSkinnedMesh = false;
+  root.traverse((object) => {
+    if (getObjectMark(object, 'editorHelperType') === SKELETON_HELPER_TYPE) {
+      existing = object as THREE.SkeletonHelper;
+    }
+    if ((object as THREE.SkinnedMesh).isSkinnedMesh) hasSkinnedMesh = true;
+  });
+  if (existing || !hasSkinnedMesh) return existing;
+
+  const helper = new THREE.SkeletonHelper(root);
+  if (helper.bones.length === 0) {
+    helper.dispose();
+    return null;
+  }
+  styleEditorSkeletonHelper(helper);
+
+  // SkeletonHelper normally expects to be a scene-root sibling. Keeping it
+  // under the entity makes lifecycle cleanup automatic, so use entity-local
+  // coordinates instead of applying the entity world transform twice.
+  helper.matrix = new THREE.Matrix4();
+  helper.matrixAutoUpdate = false;
+  helper.name = 'EditorSkeletonHelper';
+  helper.visible = Boolean(getObjectMark(root, 'skeletonVisible'));
+  setObjectMark(helper, 'skeletonEnabled', helper.visible);
+  root.add(helper);
+  root.updateMatrixWorld(true);
+  return helper;
+}

package/src/three-viewport/source-color.ts

@@ -0,0 +1,167 @@
+import * as THREE from 'three';
+
+/**
+ * The colour to give a TONE-MAPPED material so the screen shows the palette's
+ * exact sRGB hex — the inverse of three's ACES fit (the input and output
+ * matrices and the RRT/ODT rational, `tonemapping_pars_fragment`) through the
+ * exposure; Linear divides by it; no tone mapping passes through; any other
+ * operator is left as-is.
+ *
+ * WHICH SURFACES ACTUALLY WANT IT, measured on the live Model stage
+ * (`document-script` over the session's scene, beside a `capture-editor-chrome`
+ * frame of the same instant — the chrome door serves the PRESENTED frame, so
+ * the two are the same pixels):
+ *
+ *  - `scene.background` as a `THREE.Color`: **no**. three does not shade a
+ *    colour background, it CLEARS to it (`WebGLBackground.setClear` →
+ *    `glClearColor`), so no fragment shader and no tone map ever touches it.
+ *    Measured: the scene held `#494949` — this function's inversion of the
+ *    palette's `#3f3f3f` — and the screen read `#494949` exactly, luminance
+ *    73 against Blender's 63. The inversion was compensating for a transform
+ *    that does not run, and that alone is what made the stage light.
+ *  - the floor grid (`editor-floor-grid`, a `ShaderMaterial` with
+ *    `toneMapped: true`): **yes**. Measured: `uColor` held `#575757` — this
+ *    function's inversion of the palette's `#545454` — and the 1 m line read
+ *    83–84 on screen, i.e. the operator ran and landed it on the palette.
+ *  - the floor axes (`LineSegments2`/`LineMaterial`, `toneMapped: false`):
+ *    **no**. `toneMapped: false` is honoured per material (three compiles the
+ *    tone-map chunk per program, not as a composer output pass), so the
+ *    inverted colour reached the screen raw and over-saturated: `#ee234d`
+ *    where Blender's X axis is `#cb293f`.
+ *
+ * So the operator runs PER MATERIAL here, not in a final composer pass: the
+ * grid's `toneMapped: true` was mapped and the axes' `toneMapped: false` was
+ * not, in the same frame, through the same composer.
+ */
+export function toneMappedSourceColor(
+  hex: number,
+  renderer: THREE.WebGLRenderer | undefined,
+): THREE.Color {
+  const target = new THREE.Color(hex); // sRGB hex → linear, three's management
+  if (!renderer || renderer.toneMapping === THREE.NoToneMapping) return target;
+  const exposure = renderer.toneMappingExposure || 1;
+  if (renderer.toneMapping === THREE.LinearToneMapping) return target.multiplyScalar(1 / exposure);
+  if (renderer.toneMapping === THREE.AgXToneMapping) return agxSourceColor(target, exposure);
+  if (renderer.toneMapping !== THREE.ACESFilmicToneMapping) return target;
+  const IN: Mat3 = [
+    [0.59719, 0.35458, 0.04823],
+    [0.076, 0.90834, 0.01566],
+    [0.0284, 0.13383, 0.83777],
+  ];
+  const OUT: Mat3 = [
+    [1.60475, -0.53108, -0.07367],
+    [-0.10208, 1.10813, -0.00605],
+    [-0.00327, -0.07276, 1.07602],
+  ];
+  const fit = (v: number) =>
+    (v * (v + 0.0245786) - 0.000090537) / (v * (0.983729 * v + 0.432951) + 0.238081);
+  const invertFit = (f: number) => {
+    let lo = 0;
+    let hi = 64;
+    for (let i = 0; i < 60; i++) {
+      const mid = (lo + hi) / 2;
+      if (fit(mid) < f) lo = mid;
+      else hi = mid;
+    }
+    return (lo + hi) / 2;
+  };
+  const f = mulMat3(invertMat3(OUT), [target.r, target.g, target.b]);
+  const u = f.map((c) => (c <= 0 ? 0 : invertFit(Math.min(c, 0.999)))) as Vec3;
+  const x = mulMat3(invertMat3(IN), u).map((c) => Math.max(0, c) * (0.6 / exposure)) as Vec3;
+  return new THREE.Color().setRGB(x[0], x[1], x[2], THREE.LinearSRGBColorSpace);
+}
+/**
+ * The same inversion for AgX — the operator the Blender look's stage runs
+ * (`ToolViewportDressing.toneMapping`), because Blender's own scene does.
+ *
+ * Every step of `AgXToneMapping` (`tonemapping_pars_fragment.glsl`) run
+ * backwards: the Rec.2020 round trip, the outset matrix, the 2.2 linearize,
+ * the sigmoid (bisected — the contrast approximation is a sixth-order
+ * polynomial with no closed inverse), the log2 encode, and the inset matrix.
+ * three spells its matrices COLUMN-major, as GLSL's `mat3(vec3, vec3, vec3)`
+ * constructor does; these are the transposes, because {@link mulMat3} is
+ * row-major.
+ */
+function agxSourceColor(target: THREE.Color, exposure: number): THREE.Color {
+  // three spells its matrices COLUMN-major, as GLSL's `mat3(vec3, vec3, vec3)`
+  // constructor does; these are the transposes, because {@link mulMat3} is
+  // row-major. Every row sums to 1 — each of the four is grey-preserving, and
+  // that is the cheap check that the transposition is the right way round.
+  const SRGB_TO_REC2020: Mat3 = [
+    [0.6274, 0.3293, 0.0433],
+    [0.0691, 0.9195, 0.0113],
+    [0.0164, 0.088, 0.8956],
+  ];
+  const REC2020_TO_SRGB: Mat3 = [
+    [1.6605, -0.5876, -0.0728],
+    [-0.1246, 1.1329, -0.0083],
+    [-0.0182, -0.1006, 1.1187],
+  ];
+  const INSET: Mat3 = [
+    [0.856627153315983, 0.0951212405381588, 0.0482516061458583],
+    [0.137318972929847, 0.761241990602591, 0.101439036467562],
+    [0.11189821299995, 0.0767994186031903, 0.811302368396859],
+  ];
+  const OUTSET: Mat3 = [
+    [1.1271005818144368, -0.11060664309660323, -0.016493938717834573],
+    [-0.1413297634984383, 1.157823702216272, -0.016493938717834257],
+    [-0.14132976349843826, -0.11060664309660294, 1.2519364065950405],
+  ];
+  const MIN_EV = -12.47393;
+  const MAX_EV = 4.026069;
+  const contrast = (x: number) => {
+    const x2 = x * x;
+    const x4 = x2 * x2;
+    return (
+      15.5 * x4 * x2 -
+      40.14 * x4 * x +
+      31.96 * x4 -
+      6.868 * x2 * x +
+      0.4298 * x2 +
+      0.1191 * x -
+      0.00232
+    );
+  };
+  const invertContrast = (f: number) => {
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 60; i++) {
+      const mid = (lo + hi) / 2;
+      if (contrast(mid) < f) lo = mid;
+      else hi = mid;
+    }
+    return (lo + hi) / 2;
+  };
+  // Every step of the forward operator, backwards and in reverse order.
+  const rec2020 = mulMat3(SRGB_TO_REC2020, [target.r, target.g, target.b]);
+  const sigmoid = mulMat3(
+    invertMat3(OUTSET),
+    rec2020.map((c) => Math.max(0, c) ** (1 / 2.2)) as Vec3,
+  );
+  const open = sigmoid.map((c) => 2 ** (invertContrast(c) * (MAX_EV - MIN_EV) + MIN_EV)) as Vec3;
+  const linear = mulMat3(REC2020_TO_SRGB, mulMat3(invertMat3(INSET), open)).map(
+    (c) => Math.max(0, c) / exposure,
+  ) as Vec3;
+  return new THREE.Color().setRGB(linear[0], linear[1], linear[2], THREE.LinearSRGBColorSpace);
+}
+type Vec3 = [number, number, number];
+type Mat3 = [Vec3, Vec3, Vec3];
+function mulMat3(m: Mat3, v: Vec3): Vec3 {
+  return [
+    m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+    m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+    m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
+  ];
+}
+function invertMat3(m: Mat3): Mat3 {
+  const [[a, b, c], [d, e, f], [g, h, i]] = m;
+  const A = e * i - f * h;
+  const B = -(d * i - f * g);
+  const C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  return [
+    [A / det, -(b * i - c * h) / det, (b * f - c * e) / det],
+    [B / det, (a * i - c * g) / det, -(a * f - c * d) / det],
+    [C / det, -(a * h - b * g) / det, (a * e - b * d) / det],
+  ];
+}

package/src/three-viewport/studio-environment.ts

@@ -0,0 +1,96 @@
+/**
+ * The LOOK LANES' neutral studio IBL — `scene.environment` for every surface
+ * that photographs an asset instead of displaying it: the Asset Lab capture
+ * path (`asset-preview.ts`: the model-file lane, `vgai screenshot <module>`
+ * through `project.bake.preview`, labeled shot sets, source-review sheets,
+ * splats) and the asset-browser thumbnails (`model-thumbnail.ts`).
+ *
+ * Why it exists: a `MeshStandardMaterial` with `metalness: 1` has NO diffuse
+ * term — everything it shows is reflected environment. Lit by directional
+ * lights alone it renders BLACK with a pinprick specular, so iron reads as
+ * painted plastic, and the measured cost of that (cold barrel, 2026-08-29) is
+ * that agents detune `metalness` to survive the screenshot — the look lane
+ * silently teaching a wrong material value into shipped assets.
+ *
+ * The bake is three's own `RoomEnvironment` through `PMREMGenerator`, reused
+ * verbatim from the document viewport's dressing
+ * ({@link createStandardEnvironment}) so a capture and the open document light
+ * the same subject the same way. Procedural: no HDRI binary, deterministic
+ * frame to frame.
+ *
+ * Two rules this module exists to hold:
+ *
+ *  - **`environment` only, never `background`.** Each lane keeps its own
+ *    backdrop (the Asset Lab's neutral clear colour, or transparent). An IBL
+ *    that also painted the background would change every existing frame's
+ *    composition, not just its materials.
+ *  - **One bake per renderer.** A PMREM target is GL-context-bound, so it
+ *    cannot be shared across renderers, and baking it per SCENE would pay for
+ *    it once per shot in a 24-frame orbit. The cache is keyed by renderer and
+ *    freed through {@link disposeStudioEnvironment}, which every caller that
+ *    disposes its renderer must call — a PMREM render target leaks otherwise.
+ */
+
+import {
+  createStandardEnvironment,
+  type StandardEnvironment,
+} from '@volter/editor-threejs/viewport/environment';
+import type * as THREE from 'three';
+
+/**
+ * How hard the IBL pushes against the lane's existing key/fill rig.
+ *
+ * The key and fill are UNCHANGED — they still own the form, the direction of
+ * the shading and the highlight. This is a reflection budget, not a second key.
+ *
+ * The blend was picked by reading before/after pairs of the barrel GLB and a
+ * metalness sweep in the module lane, holding the wood constant and asking how
+ * little environment buys back the metal:
+ *  - 1.0 with the ambient untouched: the iron reads, the wood lifts and flattens
+ *    — the shadow side of the staves fills in and the stave-to-stave tone
+ *    variation collapses;
+ *  - 0.55 with {@link STUDIO_AMBIENT_WITH_ENVIRONMENT} at 0.35: metal good,
+ *    wood still visibly brighter and lower-contrast than the historical frame;
+ *  - 0.45 with the ambient at 0.25 (shipped): the wood frame is indistinguishable
+ *    from the historical one at full scale — same warmth, same grain, same
+ *    terminator — while every hoop gains a gradient across the band and the
+ *    bottom hoop stops reading as a shadow.
+ */
+export const STUDIO_ENVIRONMENT_INTENSITY = 0.45;
+
+/**
+ * The lanes' ambient fill is REDUCED when the IBL is present: a
+ * hemisphere/ambient light is a crude stand-in for exactly what the environment
+ * now does properly, and leaving both at full strength double-pays the ambient
+ * term and washes the subject. Each lane multiplies its own historical ambient
+ * intensity by this, so the total ambient energy lands near where it was and
+ * only its DIRECTIONALITY improves.
+ */
+export const STUDIO_AMBIENT_WITH_ENVIRONMENT = 0.25;
+
+const perRenderer = new WeakMap<THREE.WebGLRenderer, StandardEnvironment>();
+
+/**
+ * Light `scene` with the studio IBL baked for `renderer`, baking it on first
+ * use for that renderer. `scene.background` is deliberately untouched.
+ */
+export function applyStudioEnvironment(scene: THREE.Scene, renderer: THREE.WebGLRenderer): void {
+  let environment = perRenderer.get(renderer);
+  if (!environment) {
+    environment = createStandardEnvironment(renderer);
+    perRenderer.set(renderer, environment);
+  }
+  scene.environment = environment.texture;
+  scene.environmentIntensity = STUDIO_ENVIRONMENT_INTENSITY;
+}
+
+/**
+ * Free the bake this renderer owns. Idempotent, and safe for a renderer that
+ * never had one — call it beside `renderer.dispose()`.
+ */
+export function disposeStudioEnvironment(renderer: THREE.WebGLRenderer): void {
+  const environment = perRenderer.get(renderer);
+  if (!environment) return;
+  perRenderer.delete(renderer);
+  environment.dispose();
+}

package/src/three-viewport-presentation.ts

@@ -0,0 +1,23 @@
+export type ThreeViewportProjection = 'perspective' | 'orthographic';
+
+export interface ThreeViewportPresentationState {
+  readonly projection: ThreeViewportProjection;
+}
+
+let state: ThreeViewportPresentationState = { projection: 'perspective' };
+const listeners = new Set<() => void>();
+
+export function threeViewportPresentation(): ThreeViewportPresentationState {
+  return state;
+}
+
+export function subscribeThreeViewportPresentation(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function setThreeViewportProjection(projection: ThreeViewportProjection): void {
+  if (state.projection === projection) return;
+  state = { ...state, projection };
+  for (const listener of listeners) listener();
+}

package/src/tool-contribution-play.ts

@@ -0,0 +1,74 @@
+/**
+ * The `play` channel every project contribution's props carry — ONE resolution
+ * of "which live game is this contribution looking at", read by all four
+ * contribution hosts (`components/ToolHost.tsx`,
+ * `components/InspectorToolSection.tsx`,
+ * `components/AssetInspectorToolSection.tsx`, and `@vgai/game`'s generation
+ * documents).
+ *
+ * A dev-GUI contribution's whole subject is the running game (owner ruling,
+ * `docs/ARCHITECTURE-CORE.md`, 2026-08-19), and this is its door to one.
+ *
+ * THE DEPENDENCY POINTS THE OTHER WAY, deliberately — play-mode PUBLISHES a
+ * reader here, and this module imports nothing of play-mode's. That is the
+ * same shape `performance-sources.ts` uses, and it is load-bearing rather than
+ * stylistic: an inspector section importing play-mode drags the entire runtime
+ * boot chain (renderer setup, vendored postprocessing, WebGL) into every
+ * module graph that mounts one — which is a real cost in the editor and an
+ * outright import-time crash in a headless host.
+ *
+ * RESOURCE OWNERSHIP: the reader is play-mode's, for the exact lifetime of one
+ * play session. It is the only writer, `publishToolContributionPlay(null)` on
+ * exit is the only teardown, and nothing here caches its result.
+ */
+
+import type { ToolContributionPlay } from '@volter/editor-sdk/contributions';
+import { subscribeInspectedInstance } from './authoring/active-systems';
+
+type PlayReader = () => ToolContributionPlay | null;
+
+let _read: PlayReader | null = null;
+const _listeners = new Set<() => void>();
+
+/** Publish the live reader for a play session, or `null` when one ends. */
+export function publishToolContributionPlay(read: PlayReader | null): void {
+  _read = read;
+  for (const listener of _listeners) listener();
+}
+
+/** The inspected play instance, or `null` while nothing is playing. */
+export function toolContributionPlay(): ToolContributionPlay | null {
+  return _read?.() ?? null;
+}
+
+/**
+ * Observe the two things that change WHICH game a contribution is bound to: a
+ * session starting or stopping (the publication above), and the Inspect
+ * selector moving between live seats. Both, because either alone leaves a host
+ * describing another mount's game — and the split is exactly the case where
+ * that is invisible.
+ */
+export function subscribeToolContributionPlay(listener: () => void): () => void {
+  _listeners.add(listener);
+  const unsubscribeInstance = subscribeInspectedInstance(listener);
+  return () => {
+    _listeners.delete(listener);
+    unsubscribeInstance();
+  };
+}
+
+/**
+ * A stable identity for the bound instance — the `getSnapshot` for
+ * {@link subscribeToolContributionPlay}.
+ *
+ * A STRING rather than the `play` object itself, because
+ * `useSyncExternalStore` compares snapshots with `Object.is` and
+ * {@link toolContributionPlay} builds a fresh object on every call: returning
+ * that would report a change on every render and loop. The mount id is enough
+ * to key on because it is never reused (`play-mode.ts`'s instance-identity
+ * block), so a remount is always a new value.
+ */
+export function toolContributionPlayKey(): string {
+  const play = toolContributionPlay();
+  return play ? `play:${play.instanceId}` : 'stopped';
+}