@volter/editor-threejs 0.5.66 → 0.5.68

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

@@ -0,0 +1,333 @@
+/**
+ * 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_LAYER,
+  EDITOR_SELECTION_LAYER,
+  isInEditorOwnedSubtree,
+} from '@volter/editor-threejs/viewport/editor-layers';
+import type { EffectPass, 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: OutlineColors,
+): OutlineEffect {
+  const effect = 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);
+  // A CRISP LINE NEEDS ITS COLOUR UNSCALED. postprocessing's composite multiplies the edge colour
+  // by the edge value and uses that value again as alpha, so a partial edge darkens (Blender's
+  // orange read brown) and a strength above one pushes the colour past itself (it read white).
+  // Under `vgaiCrisp` the colour is divided back out of the edge value, leaving only the alpha
+  // to follow the edge; the editor's own halo keeps the library's composite. And the library
+  // draws an edge only OUTSIDE the silhouette (it scales the edge by the mask, which is zero on
+  // the selection); Blender's detect marks the pixels on both sides of it, so a crisp line keeps
+  // its inner half.
+  const shader = effect.getFragmentShader();
+  const stock = 'vec3 color=edge.x*visibleEdgeColor+edge.y*hiddenEdgeColor;';
+  const outsideOnly = 'edge*=(edgeStrength*mask.x*pulse);';
+  if (shader.includes(stock) && shader.includes(outsideOnly)) {
+    (effect as unknown as { setFragmentShader(source: string): void }).setFragmentShader(
+      shader
+        .replace('uniform float edgeStrength;', 'uniform float edgeStrength;uniform float vgaiCrisp;')
+        .replace(outsideOnly, 'edge*=(edgeStrength*(vgaiCrisp>0.5?1.0:mask.x)*pulse);')
+        .replace(
+          stock,
+          `${stock}if(vgaiCrisp>0.5){float vgaiSum=edge.x+edge.y;if(vgaiSum>0.0)color/=vgaiSum;edge=min(edge,vec2(1.0));}`,
+        ),
+    );
+    // Any `{ value }` is a uniform to three; no runtime three import in this module.
+    effect.uniforms.set('vgaiCrisp', { value: 0 } as THREE.Uniform<number>);
+  }
+  // THE EDITOR'S OWN OVERLAYS DO NOT HIDE THE SELECTION. The effect measures what stands in
+  // front of the selected object with a depth pass under an override material, which writes
+  // depth for everything the camera sees — the floor grid included, though it writes none
+  // itself — so the grid hid the outline's lower half wherever it crossed the object (measured
+  // on Unity's look). Its layer is off the camera for the effect's update only; the effect
+  // saves and restores the camera's mask around its own mask pass.
+  const update = effect.update.bind(effect);
+  effect.update = (renderer, inputBuffer, deltaTime) => {
+    const current = (effect as unknown as { camera: THREE.Camera }).camera;
+    const editorLayerOn = current.layers.isEnabled(EDITOR_LAYER);
+    current.layers.disable(EDITOR_LAYER);
+    try {
+      update(renderer, inputBuffer, deltaTime);
+    } finally {
+      if (editorLayerOn) current.layers.enable(EDITOR_LAYER);
+    }
+  };
+  outlineState.set(effect, { colors, roots: 0 });
+  paintOutline(effect);
+  return effect;
+}
+
+/**
+ * ONE EFFECT PER RENDERER, REUSED. `OutlineEffect` constructs its `Selection`
+ * with a render layer from a module-wide counter that warns "Layer out of
+ * range, resetting to 2" on its 30th construction in a page; the editor
+ * overrides that layer, but built one effect per document session and per
+ * world pipeline rebuild, the warning sat on every session's console as
+ * unresolved work. A released effect goes back to its renderer's pool — its
+ * render targets belong to that renderer's context — and the next surface on
+ * that renderer re-points it at its own scene and camera. Constructions are
+ * bounded by the surfaces open at once.
+ */
+const pooled = new WeakMap<object, OutlineEffect[]>();
+
+/** An outline for `renderer`: a released one re-pointed at `scene` and `camera`, or a new one. */
+export function acquireThreeSelectionOutline(
+  effects: ThreeSelectionOutlineEffects,
+  renderer: object,
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  colors: OutlineColors,
+): OutlineEffect {
+  const effect = pooled.get(renderer)?.pop();
+  if (!effect) return createThreeSelectionOutline(effects, scene, camera, colors);
+  effect.mainScene = scene;
+  effect.mainCamera = camera;
+  camera.layers.disable(EDITOR_SELECTION_LAYER);
+  outlineState.set(effect, { colors, roots: 0 });
+  paintOutline(effect);
+  return effect;
+}
+
+/**
+ * Give `effect` back to `renderer`'s pool, detached from `pass` so the pass's
+ * disposal leaves it intact. Its selection is cleared first: a `Selection`
+ * owns temporary render-layer bits on every object in it.
+ */
+export function releaseThreeSelectionOutline(
+  renderer: object,
+  effect: OutlineEffect,
+  pass: EffectPass | null,
+): void {
+  effect.selection.clear();
+  // `setEffects` is the pass's own (protected) way to let go of its effects.
+  (pass as unknown as { setEffects(effects: never[]): void } | null)?.setEffects([]);
+  const free = pooled.get(renderer) ?? [];
+  if (!free.includes(effect)) free.push(effect);
+  pooled.set(renderer, free);
+}
+
+/** 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: OutlineColors,
+): Promise<OutlineEffect> {
+  const { BlendFunction, KernelSize, OutlineEffect } = await import('postprocessing');
+  return createThreeSelectionOutline(
+    { BlendFunction, KernelSize, OutlineEffect },
+    scene,
+    camera,
+    colors,
+  );
+}
+
+type OutlineColors = {
+  readonly visible: number;
+  readonly hidden: number;
+  readonly active?: { readonly visible: number; readonly hidden: number };
+  readonly outline?: { readonly style: 'soft' | 'crisp'; readonly width: number | null; readonly hidden: boolean };
+};
+
+/**
+ * BLENDER'S OUTLINE DETECT (`overlay_outline_detect_frag.glsl`), over our selection mask instead
+ * of its object-id buffer: a pixel is outline when the mask changes along an axis within the
+ * reach, looked for at one pixel and, with `do_thick_outlines`, two, on both sides of the
+ * silhouette. Only the axes are looked along, which is why Blender's convex corner leaves its
+ * one diagonal pixel dark. Blender's later line anti-aliasing is not transcribed: diagonal edges
+ * step where its are smoothed. Visibility is the stock material's: the least visible of the
+ * pixels looked at.
+ */
+const BLENDER_OUTLINE_DETECT = /* glsl */ `uniform lowp sampler2D inputBuffer;uniform vec2 texelSize;uniform float vgaiReach;
+varying vec2 vUv0;varying vec2 vUv1;varying vec2 vUv2;varying vec2 vUv3;
+void main(){
+  vec2 uv=(vUv0+vUv1)*0.5;
+  vec2 c=texture2D(inputBuffer,uv).rg;
+  float edge=0.0;float visibility=1.0;
+  for(int i=1;i<=2;i++){
+    if(float(i)>vgaiReach||edge>0.0)break;
+    vec2 o=texelSize*float(i);
+    vec2 s0=texture2D(inputBuffer,uv+vec2(o.x,0.0)).rg;vec2 s1=texture2D(inputBuffer,uv-vec2(o.x,0.0)).rg;
+    vec2 s2=texture2D(inputBuffer,uv+vec2(0.0,o.y)).rg;vec2 s3=texture2D(inputBuffer,uv-vec2(0.0,o.y)).rg;
+    if(abs(s0.x-c.x)>0.5||abs(s1.x-c.x)>0.5||abs(s2.x-c.x)>0.5||abs(s3.x-c.x)>0.5)edge=1.0;
+    visibility=min(min(s0.y,s1.y),min(s2.y,s3.y));
+  }
+  gl_FragColor.rg=(1.0-visibility>0.001)?vec2(edge,0.0):vec2(0.0,edge);
+}`;
+
+/** The detect material's own shader, kept to put back when a look turns the crisp form off. */
+const stockDetect = new WeakMap<THREE.ShaderMaterial, string>();
+
+/** Each effect's palette colours and how many roots it last outlined, so a selection change
+ *  and a palette change each paint the right one. */
+const outlineState = new WeakMap<OutlineEffect, { colors: OutlineColors; roots: number }>();
+
+/**
+ * THE ACTIVE OBJECT'S OUTLINE: a lone selected object is the active one, and a palette that
+ * names an active colour draws it in that (Blender's light orange over its darker selection
+ * orange, `modeling-object-selected.png`). Several selected objects draw in the selection
+ * colour; which of them is active is not yet told apart.
+ */
+function paintOutline(effect: OutlineEffect): void {
+  const state = outlineState.get(effect);
+  if (!state) return;
+  const colors = state.roots === 1 && state.colors.active ? state.colors.active : state.colors;
+  effect.visibleEdgeColor.setHex(colors.visible);
+  effect.hiddenEdgeColor.setHex(colors.hidden);
+  // THE LOOK'S FORM. The editor's own is the soft halo `createThreeSelectionOutline` builds (a
+  // half-resolution mask under a medium blur). A crisp line is Blender's: the mask at full
+  // resolution, edge-detected by `BLENDER_OUTLINE_DETECT` and not blurred, so its band is hard
+  // and its corners square.
+  const form = state.colors.outline;
+  const crisp = form?.style === 'crisp';
+  const width = form?.width ?? 2;
+  effect.resolution.scale = crisp ? 1 : 0.5;
+  effect.blurPass.enabled = !crisp;
+  effect.blurPass.kernelSize = 2;
+  const detect = (effect as unknown as { outlinePass: { fullscreenMaterial: THREE.ShaderMaterial } }).outlinePass
+    .fullscreenMaterial;
+  const stock = stockDetect.get(detect) ?? detect.fragmentShader;
+  stockDetect.set(detect, stock);
+  const fragment = crisp ? BLENDER_OUTLINE_DETECT : stock;
+  if (detect.fragmentShader !== fragment) {
+    detect.fragmentShader = fragment;
+    detect.needsUpdate = true;
+  }
+  // Half the width on each side of the silhouette's edge: Blender's 4 device px is its
+  // `do_thick_outlines` reach of 2.
+  detect.uniforms['vgaiReach'] = { value: Math.max(1, Math.round(width / 2)) } as THREE.IUniform<number>;
+  effect.edgeStrength = crisp ? 8 : 5;
+  const crispUniform = effect.uniforms.get('vgaiCrisp');
+  if (crispUniform) crispUniform.value = crisp ? 1 : 0;
+  effect.xRay = form?.hidden ?? true;
+}
+
+/** Apply supplied renderer-ready colors without rebuilding GPU pass resources. */
+export function setThreeSelectionOutlineColors(effect: OutlineEffect, colors: OutlineColors): void {
+  outlineState.set(effect, { colors, roots: outlineState.get(effect)?.roots ?? 0 });
+  paintOutline(effect);
+}
+
+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 roots = [...selectedRoots];
+  // A bone draws its own joint highlight and is never outlined, so it is not an object here.
+  const objects = roots.filter((root) => !(root as THREE.Bone).isBone).length;
+  const state = outlineState.get(effect);
+  if (state && state.roots !== objects) {
+    state.roots = objects;
+    paintOutline(effect);
+  }
+  const targets = collectThreeSelectionOutlineTargets(roots);
+  if (
+    effect.selection.size === targets.length &&
+    targets.every((target) => effect.selection.has(target))
+  ) {
+    return;
+  }
+  effect.selection.set(targets);
+}

package/src/kit/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/kit/three-viewport/source-color.ts

@@ -0,0 +1,197 @@
+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.CustomToneMapping) return godotFilmicSourceColor(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],
+  ];
+}
+
+/**
+ * The same inversion for Godot's Filmic — the curve the presentation's `filmic` mapper installs
+ * in three's custom slot (`components/standard-viewport-dressing.ts`): Hable's curve with an
+ * exposure bias of 2, divided by its value at white, per channel. Monotonic, so bisected.
+ */
+function godotFilmicSourceColor(target: THREE.Color, exposure: number): THREE.Color {
+  const hable = (x: number) =>
+    (x * (0.88 * x + 0.06) + 0.002) / (x * (0.88 * x + 0.6) + 0.06) - 0.01 / 0.3;
+  const white = hable(1);
+  const curve = (x: number) => hable(x) / white;
+  const invert = (f: number) => {
+    if (f <= 0) return 0;
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 60; i++) {
+      const mid = (lo + hi) / 2;
+      if (curve(mid) < f) lo = mid;
+      else hi = mid;
+    }
+    return (lo + hi) / 2;
+  };
+  return new THREE.Color().setRGB(
+    invert(Math.min(target.r, 0.999)) / exposure,
+    invert(Math.min(target.g, 0.999)) / exposure,
+    invert(Math.min(target.b, 0.999)) / exposure,
+    THREE.LinearSRGBColorSpace,
+  );
+}

package/src/kit/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();
+}