@volter/editor-threejs 0.5.211 → 0.5.212

package/src/adapter/reflection-probe.ts

@@ -8,7 +8,7 @@
  * this is a live adapter seam, not another document format.
  */
 import type * as THREE from 'three';
-import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+import { getUserData } from '../ecs/user-data';
 
 export type ReflectionProbeShape = 'box' | 'sphere';
 export type ReflectionProbeCaptureMode = 'on-change' | 'manual' | 'realtime';
@@ -65,11 +65,3 @@ export function reflectionProbeOf(
     ? (candidate as ReflectionProbeMark)
     : null;
 }
-
-export function setReflectionProbeMark(object: THREE.Object3D, mark: ReflectionProbeMark): void {
-  setUserData(object, 'reflectionProbe', mark);
-}
-
-export function clearReflectionProbeMark(object: THREE.Object3D): void {
-  deleteUserData(object, 'reflectionProbe');
-}

package/src/adapter/three-contract.ts

@@ -1,72 +1,18 @@
 /**
  * The Three-typed half of the adapter contract. `@volter/project`
- * states the `three` surface with its medium objects opaque (a scene, a
+ * states the `stage` surface with its medium objects opaque (a scene, a
  * camera, a renderer, a hierarchy's scene objects, navigation's debug mesh);
  * this module names them as three.js objects for the editor side that renders
- * and authors them. A `three`-surface adapter hands exactly these objects, so
+ * and authors them. A `stage`-surface adapter hands exactly these objects, so
  * each view below is a narrowing of what the contract already carries, not a
  * conversion.
  */
 
-import type {
-  AuthoringAdapter,
-  HierarchyProvider,
-  MountedThreeRoot,
-  NavigationAdapter,
-  PhysicsAdapter,
-  ThreeHostContext,
-} from '@volter/project/adapter';
-import type { NavBakeParams } from '@volter/project/adapter/system-adapter';
+import type { HierarchyProvider } from '@volter/project/adapter';
 import type * as THREE from 'three';
 
-/** Shared GLTF/texture cache a `three` host hands its roots. */
-export interface ThreeAssetCache {
-  /** Load an asset by URL. Returns a cached promise if already loading/loaded. */
-  load<T = unknown>(url: string): Promise<T>;
-  /** Get a previously-loaded asset synchronously. Throws if not yet loaded. */
-  get<T = unknown>(url: string): T;
-}
-
-/** What a `three`-surface root is handed, Three-typed. */
-export type ThreeRootHostContext = ThreeHostContext<typeof THREE, THREE.WebGLRenderer, ThreeAssetCache>;
-
-/** A live, mounted Three world, Three-typed. */
-export type ThreeMountedRoot = MountedThreeRoot<THREE.Scene, THREE.Camera>;
-
-/** A mounted `three` root, as the Three objects it hands. */
-export function threeRoot(mounted: MountedThreeRoot): ThreeMountedRoot {
-  return mounted as ThreeMountedRoot;
-}
-
-/** The hierarchy's scene-object doors, Three-typed. */
-export interface ThreeHierarchy {
-  object3D?(id: string): THREE.Object3D | null;
-  idForObject3D?(o: THREE.Object3D): string | null;
-}
-
-/** A `three`-surface authoring adapter's hierarchy, as the Three objects it hands. */
-export function threeHierarchy(adapter: Pick<AuthoringAdapter, 'hierarchy'>): HierarchyProvider & ThreeHierarchy {
-  return adapter.hierarchy as HierarchyProvider & ThreeHierarchy;
-}
-
-/** The live Three object a `three`-surface hierarchy hands for `id` (null
+/** The live Three object a `stage`-surface hierarchy hands for `id` (null
  * when it has none, or omits the door). */
-export function threeObject(hierarchy: Pick<HierarchyProvider, 'object3D'>, id: string): THREE.Object3D | null {
-  return (hierarchy.object3D?.(id) ?? null) as THREE.Object3D | null;
-}
-
-/** A `three`-surface navigation adapter, as the Three objects it trades in. */
-export interface ThreeNavigationAdapter extends NavigationAdapter {
-  debugMesh(scene: THREE.Scene): THREE.Object3D | null;
-  bake?(meshes: THREE.Mesh[], params?: NavBakeParams): boolean;
-  clear?(scene: THREE.Scene): void;
-}
-
-export function threeNavigation(adapter: NavigationAdapter): ThreeNavigationAdapter {
-  return adapter as ThreeNavigationAdapter;
-}
-
-/** A `three`-surface physics adapter's debug-draw object. */
-export function threePhysicsDebugDraw(adapter: PhysicsAdapter): THREE.Object3D | null {
-  return (adapter.debugDraw?.() ?? null) as THREE.Object3D | null;
+export function threeObject(hierarchy: Pick<HierarchyProvider, 'nativeObject'>, id: string): THREE.Object3D | null {
+  return (hierarchy.nativeObject?.(id) ?? null) as THREE.Object3D | null;
 }

package/src/animation/live-mixers.ts

@@ -49,7 +49,3 @@ export function subscribeLiveMixers(listener: () => void): () => void {
   listeners.add(listener);
   return () => listeners.delete(listener);
 }
-
-export function liveMixersVersion(): number {
-  return registry().version;
-}

package/src/api.ts

@@ -0,0 +1,7 @@
+/**
+ * EDITOR-THREEJS'S API, AS TYPES: what its page half's `activate` returns (`../contributions/three.page.ts`). A package
+ * that reads the API imports these type-only; the values come from `getExtension(...).exports`.
+ */
+export type ThreePageApi = ReturnType<typeof import('../contributions/three.page').activate>;
+export type { ViewportStage } from './viewport-api';
+export type { DocumentDisplayTransform } from './render/document-display-transform';

package/src/asset-loaders.ts

@@ -1,90 +1,11 @@
-/**
- * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
- * `.animgraph.json` loader — removed by E5; see
- * packages/threejs-runtime/src/animation/xstate-animation-binding.ts.)
- *
- * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
- * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
- * (entity-factory, scene-sync). Previously this logic was duplicated across six
- * sites with three separate GLTF caches and four GLTFLoader instances, so fixes
- * (DRACO wiring, the `__sharedGeometry` clone-safety tag, skybox handling) did
- * not propagate. Everything funnels through the shared loaders in `../loader`
- * (`gltfLoader` is DRACO-wired — CB2 — and `textureLoader` shares the engine
- * LoadingManager / asset-prefix rewrite).
- *
- * Cache lifetime / P1.8: these caches are intentionally module-level and persist
- * ACROSS hot-reloads / scene switches (they are NOT cleared on every scene load).
- * This is deliberate: (1) it makes repeated Play→Stop→Play cheap, and (2) it
- * underpins the `__sharedGeometry` contract from P0.2 — GLTF clones share the
- * cached source geometry, so clearing mid-session would orphan live clones. The
- * caches are keyed by URL, so loading the SAME asset N times is bounded (one
- * entry per distinct URL, not per load). They are released only on full runtime
- * teardown via {@link clearAssetCaches}.
- */
+/** Canonical GLTF and texture loading, URL-keyed caches and clone-safe shared geometry. Caches persist across scene changes and are released on runtime teardown. */
 
 import type { SplatMesh } from '@sparkjsdev/spark';
 import * as THREE from 'three';
-import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
-import { AssetParseError } from './asset-parse-error';
 import { setUserData } from './ecs/user-data';
-import { gltfLoader, resolveUrl, textureLoader } from './loader';
-
-const textureCache = new Map<string, THREE.Texture>();
-const gltfCache = new Map<
-  string,
-  Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }>
->();
+import { resolveUrl } from './loader';
 const splatBytesCache = new Map<string, Promise<Uint8Array>>();
 
-/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
-export function loadTexture(url: string): THREE.Texture {
-  const cached = textureCache.get(url);
-  if (cached) return cached;
-  const tex = textureLoader.load(url);
-  textureCache.set(url, tex);
-  return tex;
-}
-
-/**
- * Load a GLTF/GLB and return a fresh, disposal-safe clone (+ the source's
- * animation clips). DRACO decoding is handled by the shared `gltfLoader`.
- *
- * Clone-safety contract (P0.2 — load-bearing, tested):
- * `SkeletonUtils.clone` shares geometry AND materials with the cached source.
- * We give each clone its OWN materials (so scene cleanup can dispose them
- * without corrupting the cache) and tag every mesh `userData.__sharedGeometry`
- * so cleanup (engine create-runtime fullCleanup + editor scene-sync
- * disposeObject3D) skips disposing the shared geometry buffers.
- */
-export function loadGLTF(
-  url: string,
-): Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }> {
-  let cached = gltfCache.get(url);
-  if (!cached) {
-    cached = new Promise((resolve, reject) => {
-      gltfLoader.load(
-        url,
-        (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }),
-        undefined,
-        (err) => reject(err),
-      );
-    });
-    gltfCache.set(url, cached);
-  }
-  return cached.then((entry) => {
-    const scene = SkeletonUtils.clone(entry.scene) as THREE.Group;
-    scene.traverse((child) => {
-      if (child instanceof THREE.Mesh) {
-        child.material = Array.isArray(child.material)
-          ? child.material.map((m) => m.clone())
-          : child.material.clone();
-        setUserData(child, '__sharedGeometry', true);
-      }
-    });
-    return { scene, animations: entry.animations };
-  });
-}
-
 /**
  * Load one native Gaussian-splat asset as Spark's own Object3D.
  *
@@ -143,100 +64,3 @@ export async function loadSplat(url: string, providedBytes?: Uint8Array): Promis
     throw error;
   }
 }
-
-/**
- * Resolve a single named node inside an already-loaded glTF scene graph (F4,
- * `mesh.node`). Pure and headlessly testable — no fetch, no cache lookups;
- * callers pass the `scene` they already got from {@link loadGLTF}.
- *
- * The returned node is the SAME object (and shares the SAME geometry) as
- * found in `scene` — nothing is cloned or copied out. `scene` is already a
- * fresh `SkeletonUtils.clone()` per {@link loadGLTF}'s clone-safety contract,
- * so mutating/detaching the returned node is safe.
- *
- * Atomic-subtree guard: a `SkinnedMesh` cannot be lifted out of its armature
- * (its skeleton/bind matrices reference sibling bone nodes elsewhere in the
- * hierarchy), so resolving a node that IS a SkinnedMesh, or that CONTAINS one,
- * throws a loud `AssetParseError` instead of silently producing broken skinning.
- */
-export function resolveGltfNode(
-  scene: THREE.Object3D,
-  nodeName: string,
-  src: string,
-): THREE.Object3D {
-  const node = scene.getObjectByName(nodeName);
-  if (!node) {
-    throw new AssetParseError(
-      [
-        {
-          code: 'custom',
-          path: ['mesh', 'node'],
-          message: `glTF "${src}" has no node named "${nodeName}" (getObjectByName found nothing)`,
-        },
-      ],
-      src,
-    );
-  }
-
-  const isSkinned = (o: THREE.Object3D) => (o as THREE.SkinnedMesh).isSkinnedMesh;
-  let containsSkinned = isSkinned(node);
-  if (!containsSkinned) {
-    node.traverse((child) => {
-      if (isSkinned(child)) containsSkinned = true;
-    });
-  }
-  if (containsSkinned) {
-    throw new AssetParseError(
-      [
-        {
-          code: 'custom',
-          path: ['mesh', 'node'],
-          message:
-            `glTF "${src}" node "${nodeName}" is (or contains) a SkinnedMesh — a skinned mesh ` +
-            'cannot be lifted out of its armature (atomic-subtree rule). Reference the whole ' +
-            'file instead of a `node`, or bake/export a non-skinned sub-asset.',
-        },
-      ],
-      src,
-    );
-  }
-
-  return node;
-}
-
-/**
- * Clear the module-level GLTF / texture caches. Call on full runtime teardown
- * (create-runtime fullCleanup / hot-reload) to release cached GPU resources
- * and avoid leaking across editor Play sessions. See the lifetime note at the
- * top of this file for why these are NOT cleared per scene load.
- *
- * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
- * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
- * also clears that env cache.
- */
-export function clearAssetCaches(): void {
-  textureCache.clear();
-  gltfCache.clear();
-  splatBytesCache.clear();
-}
-
-/**
- * Drop the cached entry for ONE asset URL after its bytes changed on disk
- * (editor asset-optimization write-back — W4a). Existing clones keep their
- * shared geometry alive (the cache entry only owns the lookup, not the
- * buffers), and the next `loadGLTF`/`loadTexture` for this URL re-fetches the
- * rewritten file instead of serving stale bytes.
- */
-export function invalidateCachedAsset(url: string): void {
-  textureCache.delete(url);
-  gltfCache.delete(url);
-}
-
-/**
- * Test-only: current sizes of the module-level caches. Used by the P1.8 headless
- * test to assert caches stay bounded (one entry per distinct asset URL) across
- * repeated loads of the same scene, rather than growing per load.
- */
-export function assetCacheSizes(): { textures: number; gltf: number; splat: number } {
-  return { textures: textureCache.size, gltf: gltfCache.size, splat: splatBytesCache.size };
-}

package/src/capture/photograph-sampling.ts

@@ -0,0 +1,333 @@
+/** Shared Three capture mechanics; this entry must not import host or contribution code. */
+import * as THREE from 'three';
+import { FullScreenQuad } from 'three/addons/postprocessing/Pass.js';
+
+/**
+ * HOW A PHOTOGRAPH IS ANTI-ALIASED, when its document states it: the samples a renderer's own
+ * temporal accumulation would draw, each with the projection moved by `offset * projectionScale`
+ * pixels, each spread over the neighbours within `reach` by the filter weighed at `offset`, and
+ * summed in the renderer's own space. The document supplies the model (Blender's Workbench and
+ * EEVEE film, `blender-viewport-sampling.ts`); this module only carries it out.
+ */
+export interface PhotographSampling {
+  /** Each sample's offset in pixels, as the filter weighs it. */
+  readonly offsets: readonly (readonly [number, number])[];
+  /** The projection moves `offset * projectionScale` pixels (Workbench 0.5, EEVEE 1). */
+  readonly projectionScale: number;
+  /** Neighbours gathered on each side of a pixel. */
+  readonly reach: number;
+  /** Blackman-Harris over a width of `2 * radius`, or a Gaussian of sigma `0.284 * radius` cut at
+   *  `radius`. A radius of 0 keeps each pixel's own sample. */
+  readonly filter: 'blackman-harris' | 'gaussian';
+  readonly radius: number;
+  /** `log2`: colour summed as log2(1 + c), resolved with exp2(x) - 1, alpha linear (Workbench).
+   *  `luma`: each texel weighed again by 1 / (4 + (R + 2G + B) * exposureScale) and blended with
+   *  the history by that weight over the filter weight so far (EEVEE's film). */
+  readonly accumulation: 'log2' | 'luma';
+  readonly exposureScale: number;
+  /** Drawn without its backdrop, then laid over it after the display encoding in display-linear,
+   *  `pow(c, 2.2)`, as Blender's viewport merges its overlay (the OCIO display shader). The merge
+   *  writes the display encoding itself (sRGB, no tone mapping): a document asks for it only under
+   *  a renderer that tone-maps nothing, and the stage merges only then. */
+  readonly backdropMerge: boolean;
+  /** The live view shows its sum from this many samples on, the ordinary (MSAA) frame before:
+   *  where the sum's edges first are no worse than the ordinary frame's. All of them when unset. */
+  readonly liveFrom?: number;
+}
+
+/** The most samples a photograph draws, whatever a document asks for. */
+export const PHOTOGRAPH_SAMPLE_CAP = 64;
+
+/** The filter's weight at `distance` pixels from a sample. */
+function filterWeight(sampling: PhotographSampling, distance: number): number {
+  if (sampling.radius <= 0) return distance === 0 ? 1 : 0;
+  if (sampling.filter === 'gaussian') {
+    if (distance * distance >= sampling.radius * sampling.radius) return 0;
+    const r = (distance * distance) / (sampling.radius * sampling.radius);
+    const sigma = 0.284;
+    return Math.exp((-0.5 / (sigma * sigma)) * r);
+  }
+  const width = 2 * sampling.radius;
+  if (distance > width * 0.5) return 0;
+  const x = 2 * Math.PI * Math.min(1, Math.max(0, distance / width + 0.5));
+  return 0.35875 - 0.48829 * Math.cos(x) + 0.14128 * Math.cos(2 * x) - 0.01168 * Math.cos(3 * x);
+}
+
+const QUAD_VERTEX = `precision highp float; in vec3 position; in vec2 uv; out vec2 vUv;
+  void main(){vUv=uv;gl_Position=vec4(position,1.0);}`;
+
+/** One sample spread over its neighbours, added to the sum (Workbench's `workbench_taa`). */
+const LOG2_ACCUMULATE = (reach: number) => /* glsl */ `
+precision highp float;
+uniform sampler2D frame;
+uniform float weights[${(2 * reach + 1) ** 2}];
+in vec2 vUv;
+out vec4 outputColor;
+void main() {
+  ivec2 size = textureSize(frame, 0);
+  ivec2 p = ivec2(vUv * vec2(size));
+  vec4 sum = vec4(0.0);
+  int i = 0;
+  for (int y = -${reach}; y <= ${reach}; y++) {
+    for (int x = -${reach}; x <= ${reach}; x++) {
+      vec4 color = clamp(texelFetch(frame, clamp(p + ivec2(x, y), ivec2(0), size - 1), 0), vec4(0.0), vec4(1e10));
+      color.rgb = log2(color.rgb + 1.0);
+      sum += color * weights[i];
+      i++;
+    }
+  }
+  outputColor = sum;
+}`;
+
+/** The sum, out of log2 space (the SMAA resolve's `exp2(x) - 1` over the accumulated weight). */
+const LOG2_RESOLVE = /* glsl */ `
+precision highp float;
+uniform sampler2D sum;
+uniform float total;
+in vec2 vUv;
+out vec4 outputColor;
+void main() {
+  vec4 color = texelFetch(sum, ivec2(vUv * vec2(textureSize(sum, 0))), 0) / total;
+  color.rgb = exp2(color.rgb) - 1.0;
+  if (color.a > 0.999) color.a = 1.0;
+  outputColor = color;
+}`;
+
+/** One sample gathered by luma-weighted filter weights and blended with the history
+ *  (EEVEE's `sample_accum_combined` and `store_combined`, static accumulation). */
+const LUMA_ACCUMULATE = (reach: number) => /* glsl */ `
+precision highp float;
+uniform sampler2D frame;
+uniform sampler2D history;
+uniform float weights[${(2 * reach + 1) ** 2}];
+uniform float filmWeight;
+uniform float exposureScale;
+in vec2 vUv;
+out vec4 outputColor;
+float lumaWeight(vec3 rgb) { return 1.0 / (4.0 + dot(rgb, vec3(1.0, 2.0, 1.0)) * exposureScale); }
+void main() {
+  ivec2 size = textureSize(frame, 0);
+  ivec2 p = ivec2(vUv * vec2(size));
+  vec4 sum = vec4(0.0);
+  float weight = 0.0;
+  int i = 0;
+  for (int y = -${reach}; y <= ${reach}; y++) {
+    for (int x = -${reach}; x <= ${reach}; x++) {
+      vec4 color = texelFetch(frame, clamp(p + ivec2(x, y), ivec2(0), size - 1), 0);
+      float w = lumaWeight(color.rgb) * weights[i];
+      sum += color * w;
+      weight += w;
+      i++;
+    }
+  }
+  vec4 source = weight > 0.0 ? sum / weight : vec4(0.0);
+  if (filmWeight <= 0.0) { outputColor = source; return; }
+  vec4 past = texelFetch(history, p, 0);
+  float pastWeight = lumaWeight(past.rgb) * filmWeight;
+  vec4 color = (past * pastWeight + source * weight) / (pastWeight + weight);
+  if (color.a > 0.995) color.a = 1.0;
+  outputColor = max(color, vec4(0.0));
+}`;
+
+/** The resolved drawing laid over its backdrop as Blender's viewport merges the overlay
+ *  (`gpu_viewport.cc`, `ocio_frag.glsl`): the drawing's colour AS ACCUMULATED, premultiplied (the
+ *  viewport sets up the display shader without predivide), through the view (sRGB, Standard), to
+ *  display-linear by `pow(c, 2.2)`; the background's "alpha under" added, `bg * (1 - alpha)`
+ *  (the overlay buffer's alpha is 0 where nothing else is drawn, so nothing scales the drawing);
+ *  and back by `pow(c, 1/2.2)`. */
+const BACKDROP_MERGE = /* glsl */ `
+precision highp float;
+uniform sampler2D drawing;
+uniform vec3 backdropLinear;
+in vec2 vUv;
+out vec4 outputColor;
+vec3 srgbEncode(vec3 c) {
+  c = clamp(c, 0.0, 1.0);
+  return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(vec3(0.0031308), c));
+}
+void main() {
+  vec4 color = texelFetch(drawing, ivec2(vUv * vec2(textureSize(drawing, 0))), 0);
+  float alpha = clamp(color.a, 0.0, 1.0);
+  vec3 display = pow(srgbEncode(color.rgb), vec3(2.2));
+  vec3 merged = display + backdropLinear * (1.0 - alpha);
+  outputColor = vec4(pow(merged, vec3(1.0 / 2.2)), 1.0);
+}`;
+
+const blend = {
+  depthTest: false,
+  depthWrite: false,
+} as const;
+
+/**
+ * One photograph's accumulation: `add` each jittered render with its offset, then `resolve`
+ * into `result` (scene-linear, the drawing's alpha kept), or `merge` it over a backdrop.
+ */
+export class PhotographAccumulation {
+  readonly offsets: readonly (readonly [number, number])[];
+  private readonly targets: THREE.WebGLRenderTarget[];
+  readonly result: THREE.WebGLRenderTarget;
+  private readonly accumulate: THREE.RawShaderMaterial;
+  private readonly resolver: THREE.RawShaderMaterial | null;
+  private readonly merger = new THREE.RawShaderMaterial({
+    name: 'Photograph backdrop merge', glslVersion: THREE.GLSL3, ...blend, blending: THREE.NoBlending,
+    uniforms: { drawing: { value: null }, backdropLinear: { value: new THREE.Vector3() } },
+    vertexShader: QUAD_VERTEX, fragmentShader: BACKDROP_MERGE,
+  });
+  private readonly quad = new FullScreenQuad();
+  private total = 0;
+  private filmWeight = 0;
+  private current = 0;
+
+  constructor(
+    private readonly sampling: PhotographSampling,
+    width: number,
+    height: number,
+    renderer: THREE.WebGLRenderer,
+    /** `half` for the live view, whose sums need not repeat to the bit (half the memory). */
+    precision: 'best' | 'half' = 'best',
+  ) {
+    this.offsets = sampling.offsets.slice(0, PHOTOGRAPH_SAMPLE_CAP);
+    // Accumulate photographs in single precision when EXT_float_blend is available; use half
+    // precision otherwise. Single precision reduces rounding differences between samples.
+    const float = precision === 'best' &&
+      renderer.extensions.has('EXT_color_buffer_float') && renderer.extensions.has('EXT_float_blend');
+    const options = {
+      type: float ? THREE.FloatType : THREE.HalfFloatType,
+      depthBuffer: false, minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter,
+    } as const;
+    const reach = Math.max(0, Math.round(sampling.reach));
+    if (sampling.accumulation === 'log2') {
+      this.targets = [new THREE.WebGLRenderTarget(width, height, options)];
+      this.result = new THREE.WebGLRenderTarget(width, height, options);
+      this.accumulate = new THREE.RawShaderMaterial({
+        name: 'Photograph accumulation (log2)', glslVersion: THREE.GLSL3, ...blend, transparent: true,
+        blending: THREE.CustomBlending, blendEquation: THREE.AddEquation,
+        blendSrc: THREE.OneFactor, blendDst: THREE.OneFactor, blendSrcAlpha: THREE.OneFactor, blendDstAlpha: THREE.OneFactor,
+        uniforms: { frame: { value: null }, weights: { value: new Array<number>((2 * reach + 1) ** 2).fill(0) } },
+        vertexShader: QUAD_VERTEX, fragmentShader: LOG2_ACCUMULATE(reach),
+      });
+      this.resolver = new THREE.RawShaderMaterial({
+        name: 'Photograph resolve (log2)', glslVersion: THREE.GLSL3, ...blend, blending: THREE.NoBlending,
+        uniforms: { sum: { value: null }, total: { value: 1 } },
+        vertexShader: QUAD_VERTEX, fragmentShader: LOG2_RESOLVE,
+      });
+    } else {
+      this.targets = [new THREE.WebGLRenderTarget(width, height, options), new THREE.WebGLRenderTarget(width, height, options)];
+      this.result = this.targets[0]!;
+      this.accumulate = new THREE.RawShaderMaterial({
+        name: 'Photograph accumulation (luma)', glslVersion: THREE.GLSL3, ...blend, blending: THREE.NoBlending,
+        uniforms: {
+          frame: { value: null }, history: { value: null }, filmWeight: { value: 0 },
+          exposureScale: { value: sampling.exposureScale },
+          weights: { value: new Array<number>((2 * reach + 1) ** 2).fill(0) },
+        },
+        vertexShader: QUAD_VERTEX, fragmentShader: LUMA_ACCUMULATE(reach),
+      });
+      this.resolver = null;
+    }
+  }
+
+  /** The neighbourhood's filter weights for a sample at `offset`, in the shaders' loop order. */
+  private weights(offset: readonly [number, number]): number[] {
+    const reach = Math.max(0, Math.round(this.sampling.reach));
+    const weights: number[] = [];
+    for (let y = -reach; y <= reach; y++)
+      for (let x = -reach; x <= reach; x++) weights.push(filterWeight(this.sampling, Math.hypot(x - offset[0], y - offset[1])));
+    return weights;
+  }
+
+  private draw(renderer: THREE.WebGLRenderer, material: THREE.Material, target: THREE.WebGLRenderTarget | null): void {
+    const autoClear = renderer.autoClear;
+    renderer.setRenderTarget(target);
+    // Added to (or written over) explicitly: never cleared first, whatever the renderer's setting.
+    renderer.autoClear = false;
+    try {
+      this.quad.material = material;
+      this.quad.render(renderer);
+    } finally {
+      renderer.autoClear = autoClear;
+    }
+  }
+
+  clear(renderer: THREE.WebGLRenderer): void {
+    const previous = renderer.getRenderTarget();
+    const color = renderer.getClearColor(new THREE.Color());
+    const alpha = renderer.getClearAlpha();
+    renderer.setClearColor(0x000000, 0);
+    for (const target of this.targets) {
+      renderer.setRenderTarget(target);
+      renderer.clear(true, false, false);
+    }
+    renderer.setClearColor(color, alpha);
+    renderer.setRenderTarget(previous);
+    this.total = 0;
+    this.filmWeight = 0;
+    this.current = 0;
+  }
+
+  add(renderer: THREE.WebGLRenderer, frame: THREE.Texture, offset: readonly [number, number]): void {
+    const previous = renderer.getRenderTarget();
+    const weights = this.weights(offset);
+    const sum = weights.reduce((total, weight) => total + weight, 0);
+    this.accumulate.uniforms['frame']!.value = frame;
+    this.accumulate.uniforms['weights']!.value = weights;
+    if (this.sampling.accumulation === 'log2') {
+      this.draw(renderer, this.accumulate, this.targets[0]!);
+      this.total += sum;
+    } else {
+      const read = this.targets[this.current]!;
+      const write = this.targets[1 - this.current]!;
+      this.accumulate.uniforms['history']!.value = read.texture;
+      this.accumulate.uniforms['filmWeight']!.value = this.filmWeight;
+      this.draw(renderer, this.accumulate, write);
+      this.filmWeight += sum;
+      this.current = 1 - this.current;
+    }
+    renderer.setRenderTarget(previous);
+  }
+
+  /** The filtered drawing, scene-linear with its alpha. */
+  resolve(renderer: THREE.WebGLRenderer): THREE.WebGLRenderTarget {
+    if (!this.resolver) return this.targets[this.current]!;
+    const previous = renderer.getRenderTarget();
+    this.resolver.uniforms['sum']!.value = this.targets[0]!.texture;
+    this.resolver.uniforms['total']!.value = this.total > 0 ? this.total : 1;
+    this.draw(renderer, this.resolver, this.result);
+    renderer.setRenderTarget(previous);
+    return this.result;
+  }
+
+  /** The resolved drawing over `backdrop` (a scene background colour), display-encoded, into
+   *  `target` (null: the canvas). */
+  merge(renderer: THREE.WebGLRenderer, drawing: THREE.WebGLRenderTarget, backdrop: THREE.Color, target: THREE.WebGLRenderTarget | null): void {
+    const previous = renderer.getRenderTarget();
+    // The backdrop as the display shows it, back to display-linear by Blender's own 2.2.
+    const shown = backdrop.clone().convertLinearToSRGB();
+    (this.merger.uniforms['backdropLinear']!.value as THREE.Vector3).set(shown.r ** 2.2, shown.g ** 2.2, shown.b ** 2.2);
+    this.merger.uniforms['drawing']!.value = drawing.texture;
+    this.draw(renderer, this.merger, target);
+    renderer.setRenderTarget(previous);
+  }
+
+  dispose(): void {
+    for (const target of this.targets) target.dispose();
+    if (this.result !== this.targets[0]) this.result.dispose();
+    this.accumulate.dispose();
+    this.resolver?.dispose();
+    this.merger.dispose();
+    this.quad.dispose();
+  }
+}
+
+/** Move `camera`'s projection so the scene lands `offset` output pixels over, on a `width` by
+ *  `height` drawing; answers the undo. */
+export function jitterProjection(camera: THREE.Camera, offset: readonly [number, number], width: number, height: number): () => void {
+  const projection = camera.projectionMatrix.clone();
+  const inverse = camera.projectionMatrixInverse.clone();
+  camera.projectionMatrix.premultiply(new THREE.Matrix4().makeTranslation((2 * offset[0]) / width, (2 * offset[1]) / height, 0));
+  camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
+  return () => {
+    camera.projectionMatrix.copy(projection);
+    camera.projectionMatrixInverse.copy(inverse);
+  };
+}

package/src/capture/scene.ts

@@ -86,7 +86,7 @@ function capture(
     hdr = new THREE.WebGLRenderTarget(renderWidth, renderHeight, { type: THREE.HalfFloatType });
     if (options.effect) hdr.depthTexture = new THREE.DepthTexture(renderWidth, renderHeight);
     renderer.shadowMap.enabled = true;
-    renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    renderer.shadowMap.type = THREE.PCFShadowMap;
     renderer.outputColorSpace = THREE.SRGBColorSpace;
     renderer.toneMapping = options.toneMapping ?? THREE.NoToneMapping;
     renderer.toneMappingExposure = options.exposure ?? 1;