reze-engine 0.40.0 → 0.41.1

package/src/engine.ts

@@ -31,6 +31,7 @@ import {
   BLOOM_DOWNSAMPLE_SHADER_WGSL,
   BLOOM_UPSAMPLE_SHADER_WGSL,
 } from "./shaders/passes/bloom"
+import { AGX_LUT_GZ, AGX_LUT_SIZE } from "./shaders/agx-lut"
 import { buildCompositeShader } from "./shaders/passes/composite"
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick"
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap"
@@ -84,7 +85,17 @@ const PRESET_NAME_HINTS: Array<[MaterialPreset, string[]]> = [
     "face",
     ["顔", "颜", "顏", "脸", "臉", "かお", "face", "舌", "tongue", "牙", "牙齿", "齿", "歯", "teeth", "tooth", "口腔", "口内", "mouth", "嘴", "唇", "歯茎", "gums"],
   ],
-  ["hair", ["前髪", "後髪", "髪", "髮", "头发", "頭髪", "もみあげ", "アホ毛", "ヘア", "hair", "ahoge", "bang"]],
+  // Simplified 发 is listed as compounds, never bare: it also writes 发光 (glow),
+  // and hair carries a renderClass, so a chance hit puts an emissive panel in the
+  // hair pass. Same reasoning as bare 口 being omitted from face above.
+  [
+    "hair",
+    [
+      "前髪", "後髪", "髪", "髮", "頭髪", "もみあげ", "アホ毛", "ヘア",
+      "头发", "前发", "后发", "长发", "短发", "发丝", "刘海", "辫", "马尾",
+      "hair", "ahoge", "bang",
+    ],
+  ],
   ["body", ["肌", "皮肤", "skin"]],
   ["metal", ["金属", "メタル", "metal", "earring", "耳环", "耳環"]],
   [
@@ -187,6 +198,9 @@ type GroupInstall = {
   /** hair render-class only: the stencil-matched IS_OVER_EYES=true variant. */
   overEyesPipeline?: GPURenderPipeline
   uniformBuffer: GPUBuffer
+  /** The group's own image maps, uploaded once per apply and owned here — the
+   *  install destroys them when it is replaced, so a re-apply cannot leak. */
+  images?: (GPUTexture | null)[]
   slotMap: StyleSlot[]
   /** Serialized (graph + renderClass + alphaMode) — lets applyStyleGroups skip recompiling
    *  an unchanged group. */
@@ -235,14 +249,17 @@ export type SunOptions = {
   direction?: Vec3
 }
 
-/** A background-effect param: number → f32, vector-like → vec3f (see
- *  setBackgroundEffect). Structural {x,y,z} rather than the Vec3 class so
- *  JSON-derived values (a shared scene document's params) pass straight in. */
-export type BackgroundEffectParamValue = number | { x: number; y: number; z: number }
-export type BackgroundEffectResult = {
+/** An effect param: number → f32, vector-like → vec3f (see setEffect).
+ *  Structural {x,y,z} rather than the Vec3 class so JSON-derived values (a
+ *  shared scene document's params) pass straight in. */
+export type EffectParamValue = number | { x: number; y: number; z: number }
+export type EffectResult = {
   ok: boolean
   /** Compile/validation errors, line:col relative to the USER's WGSL. */
   diagnostics: string[]
+  /** Which mounts the WGSL declared — `fn background` / `fn foreground`. Both
+   *  false only on a failed compile, since defining neither IS the failure. */
+  mounts: { background: boolean; foreground: boolean }
 }
 
 export type CameraOptions = {
@@ -317,7 +334,17 @@ export type ViewTransformOptions = {
   exposure: number
   /** After Filmic, display gamma (`pow(rgb, 1/gamma)`). */
   gamma: number
-  look: "default" | "medium_high_contrast"
+  /**
+   * Which display transform the frame is formed with.
+   *
+   * "standard" is Blender's Standard: the sRGB encoding and nothing else, which
+   * is what NPR and anime work uses — the colours the graph computes are the
+   * colours that land, with no film curve reinterpreting them. Both of the
+   * reference Wuthering Waves projects render this way.
+   *
+   * "filmic" is Blender 3.6's Filmic, Medium High Contrast, baked as a LUT.
+   */
+  transform: "agx" | "filmic" | "standard"
 }
 
 // Matches the reference Blender project: Filmic view, Medium High Contrast look,
@@ -325,7 +352,7 @@ export type ViewTransformOptions = {
 export const DEFAULT_VIEW_TRANSFORM: ViewTransformOptions = {
   exposure: 0.6,
   gamma: 1.0,
-  look: "medium_high_contrast",
+  transform: "filmic",
 }
 
 /** Color grading applied to the tonemapped scene (ASC CDL — see grade() in
@@ -772,7 +799,10 @@ export class Engine {
   private depthReadView: GPUTextureView | null = null
   private compositeUniformBuffer!: GPUBuffer
   // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-  private readonly compositeUniformData = new Float32Array(40)
+  // 11 × vec4f — see the viewU comment in composite.ts. The last one is the
+  // camera's world position, which is what lets a foreground effect turn the
+  // depth it is handed into a PLACE (bgWorldPos) rather than a distance.
+  private readonly compositeUniformData = new Float32Array(44)
   /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
   private backgroundColor: Vec3 | null = null
   // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
@@ -780,21 +810,29 @@ export class Engine {
   private backdropEquirectView: GPUTextureView | null = null
   private fallbackEquirectTexture!: GPUTexture
   private fallbackEquirectView!: GPUTextureView
-  // User WGSL background effect (background mode 3, setBackgroundEffect). The
-  // composite pipelines are REBUILT with the user code injected; params live in
-  // their own uniform buffer so setBackgroundEffectParam is a write, not a
+  // The scene's user WGSL effect (setEffect). ONE per scene, mounted under the
+  // scene, over it, or both — whichever of background()/foreground() the code
+  // defines. The composite pipelines are REBUILT with the user code injected;
+  // params live in their own uniform buffer so setEffectParam is a write, not a
   // recompile (the same instant tier as setStyleParam).
-  private backgroundEffect: {
+  private effect: {
     wgsl: string
     paramLayout: Map<string, { offset: number; comps: 1 | 3 }>
     paramsBuffer: GPUBuffer | null
     paramsData: Float32Array<ArrayBuffer>
+    /** Mounted under the scene. */
+    hasBackground: boolean
+    /** Mounted over the finished frame — and the reason the scene pass has to
+     *  STORE its depth, which it otherwise discards into tile memory. */
+    hasForeground: boolean
   } | null = null
+  private agxLutTexture: GPUTexture | null = null
+  private agxFallbackTexture!: GPUTexture
   /** Bound at composite binding 7 when no effect (or a param-less one) is set. */
   private bgParamsDummyBuffer!: GPUBuffer
   private compositePipelineLayout!: GPUPipelineLayout
-  /** time=0 origin for the active effect — reset each setBackgroundEffect. */
-  private bgEffectEpochMs = 0
+  /** time=0 origin for the active effect — reset each setEffect. */
+  private effectEpochMs = 0
   private compositeBloomView: GPUTextureView | null = null
 
   // EEVEE-style bloom pyramid (mirrors Blender 3.6 effect_bloom_frag.glsl):
@@ -969,7 +1007,7 @@ export class Engine {
     return {
       exposure: partial?.exposure ?? d.exposure,
       gamma: partial?.gamma ?? d.gamma,
-      look: partial?.look ?? d.look,
+      transform: partial?.transform ?? d.transform,
     }
   }
 
@@ -989,7 +1027,7 @@ export class Engine {
 
   getViewTransformOptions(): ViewTransformOptions {
     const v = this.viewTransform
-    return { exposure: v.exposure, gamma: v.gamma, look: v.look }
+    return { exposure: v.exposure, gamma: v.gamma, transform: v.transform }
   }
 
   private colorGrading: ColorGradingOptions = {
@@ -1032,7 +1070,7 @@ export class Engine {
     const v = this.viewTransform
     if (patch.exposure !== undefined) v.exposure = patch.exposure
     if (patch.gamma !== undefined) v.gamma = patch.gamma
-    if (patch.look !== undefined) v.look = patch.look
+    if (patch.transform !== undefined) v.transform = patch.transform
     if (this.device && this.compositeUniformBuffer) {
       this.writeCompositeViewUniforms()
     }
@@ -1062,10 +1100,12 @@ export class Engine {
     u[8] = bg?.x ?? 0
     u[9] = bg?.y ?? 0
     u[10] = bg?.z ?? 0
-    // Base-layer mode; a user effect is a separate LAYER flagged at u[25] and
-    // over-composited onto whichever base is active.
+    // Base-layer mode only. A user effect is a separate LAYER over whichever
+    // base is active, and needs no flag of its own: the composite pipeline is
+    // rebuilt per effect, so the compiled variant IS the flag.
     u[11] = this.backdropEquirectView ? 2 : bg ? 1 : 0
-    u[25] = this.backgroundEffect ? 1 : 0
+    // Which display transform forms the frame (see viewTransform in composite.ts).
+    u[25] = v.transform === "agx" ? 2 : v.transform === "standard" ? 1 : 0
     u[26] = this.canvas.width
     u[27] = this.canvas.height
     // ── Grade (viewU[7..9]) ── The UI's three tonal COLORS map to ASC CDL here,
@@ -1133,9 +1173,10 @@ export class Engine {
         { binding: 4, resource: this.maskResolveView },
         { binding: 5, resource: this.filmicLutView },
         { binding: 6, resource: this.backdropEquirectView ?? this.fallbackEquirectView },
-        { binding: 7, resource: { buffer: this.backgroundEffect?.paramsBuffer ?? this.bgParamsDummyBuffer } },
+        { binding: 7, resource: { buffer: this.effect?.paramsBuffer ?? this.bgParamsDummyBuffer } },
         { binding: 8, resource: this.depthReadView },
         { binding: 9, resource: { buffer: this.dofUniformBuffer } },
+        { binding: 10, resource: (this.agxLutTexture ?? this.agxFallbackTexture).createView({ dimension: "3d" }) },
       ],
     })
   }
@@ -1200,45 +1241,72 @@ export class Engine {
   }
 
   /**
-   * Install a WGSL background effect (shadertoy-style) as a LAYER between the
-   * base background and the scene: rendered per-pixel in the composite pass and
-   * over-composited onto whichever base is active (solid color, 360 equirect,
-   * or transparency) — its alpha lets the base show through, so a starfield is
-   * stars over the user's background color. Display-space: never affects
-   * lighting, bloom, or tonemapping, and is captured by offline export like any
-   * background.
-   *
-   * `wgsl` must define:
+   * Install the scene's WGSL effect (shadertoy-style), rendered per-pixel in the
+   * composite pass. ONE effect per scene, and the code says where it mounts by
+   * which of these it defines — either, or both in one file:
    *
    *     fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+   *     fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f
+   *
+   * `background` is a LAYER between the base background and the scene,
+   * over-composited onto whichever base is active (solid color, 360 equirect, or
+   * transparency) — its alpha lets the base show through, so a starfield is
+   * stars over the user's background color. `foreground` composites over the
+   * finished frame instead, which is where rain, snow, petals and fog live, and
+   * is handed `depth`: the camera-space distance in metres of whatever the scene
+   * drew at that pixel (the far plane where it drew nothing). Compare a
+   * particle's own distance against it and the model occludes it; fog just reads
+   * it, since fog's alpha IS a function of distance.
    *
-   * where `ray` is the pixel's normalized world-space view direction (LH, +Z
-   * forward — what the skybox samples by), `uv` is 0..1 bottom-left origin,
-   * `time` is seconds since apply, and `bgResolution()` gives the canvas size.
-   * Return sRGB + alpha. Declared `params` arrive as `params.<name>` (number →
-   * f32, Vec3 → vec3f) and are later tweaked without recompiling via
-   * setBackgroundEffectParam.
+   * `ray` is the pixel's normalized world-space view direction (LH, +Z forward —
+   * what the skybox samples by), `uv` is 0..1 bottom-left origin, `time` is
+   * seconds since apply, and `bgResolution()` gives the canvas size. Return sRGB
+   * + alpha; alpha is the only "how much does this replace" control there is.
+   * Declared `params` arrive as `params.<name>` (number → f32, Vec3 → vec3f),
+   * shared by both mounts, and are later tweaked without recompiling via
+   * setEffectParam.
    *
-   * Compiles off the hot path (async pipelines): on failure the previous
-   * background is KEPT and diagnostics are returned with line numbers relative
-   * to the user's WGSL. Pass null to remove the effect.
+   * Both mounts are display-space: neither affects lighting, bloom or
+   * tonemapping, and both are captured by offline export. A foreground makes the
+   * scene pass STORE its depth buffer (it otherwise discards it into tile
+   * memory) for as long as one is installed.
+   *
+   * Compiles off the hot path (async pipelines): on failure the previous effect
+   * is KEPT and diagnostics are returned with line numbers relative to the
+   * user's WGSL. Pass null to remove the effect.
    */
-  async setBackgroundEffect(
-    wgsl: string | null,
-    params?: Record<string, BackgroundEffectParamValue>,
-  ): Promise<BackgroundEffectResult> {
-    if (!this.device) return { ok: false, diagnostics: ["setBackgroundEffect requires init() to have run"] }
+  async setEffect(wgsl: string | null, params?: Record<string, EffectParamValue>): Promise<EffectResult> {
+    const noMounts = { background: false, foreground: false }
+    if (!this.device) return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts }
 
     if (wgsl === null) {
-      this.backgroundEffect?.paramsBuffer?.destroy()
-      this.backgroundEffect = null
+      this.effect?.paramsBuffer?.destroy()
+      this.effect = null
       const module = this.device.createShaderModule({ label: "composite shader", code: buildCompositeShader(null) })
       this.compositePipelineIdentity = this.makeCompositePipeline(module, false, "composite pipeline (gamma=1)")
       this.compositePipelineGamma = this.makeCompositePipeline(module, true, "composite pipeline (gamma!=1)")
       this.rebuildCompositeBindGroup()
       this.writeCompositeViewUniforms()
-      return { ok: true, diagnostics: [] }
+      return { ok: true, diagnostics: [], mounts: noMounts }
+    }
+
+    // ── Which mounts did the author ask for? A declaration, not a setting: the
+    // entry points present in the source are the ones compiled in. Matching the
+    // `fn` keyword is enough to be safe against a `foreground` LOCAL or a call
+    // to one — those never follow `fn`.
+    const hasBackground = /\bfn\s+background\s*\(/.test(wgsl)
+    const hasForeground = /\bfn\s+foreground\s*\(/.test(wgsl)
+    if (!hasBackground && !hasForeground) {
+      return {
+        ok: false,
+        diagnostics: [
+          "an effect must define fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f " +
+            "or fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f (or both)",
+        ],
+        mounts: noMounts,
+      }
     }
+    const mounts = { background: hasBackground, foreground: hasForeground }
 
     // ── Params: codegen a WGSL struct and mirror its uniform layout on the CPU.
     // Fields are emitted in declaration order; offsets follow WGSL's natural
@@ -1250,7 +1318,7 @@ export class Engine {
     let cursor = 0
     for (const [name, value] of entries) {
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
-        return { ok: false, diagnostics: [`invalid param name "${name}" (must be a WGSL identifier)`] }
+        return { ok: false, diagnostics: [`invalid param name "${name}" (must be a WGSL identifier)`], mounts }
       }
       const isVec = typeof value !== "number"
       const align = isVec ? 16 : 4
@@ -1270,22 +1338,22 @@ export class Engine {
       }
     }
     const paramsDecl = entries.length
-      ? `struct BgParams {\n${fields.join("\n")}\n}\n@group(0) @binding(7) var<uniform> params: BgParams;\n`
+      ? `struct EffectParams {\n${fields.join("\n")}\n}\n@group(0) @binding(7) var<uniform> params: EffectParams;\n`
       : ""
 
     // ── Compile with validation captured, not thrown at the console. Line
     // numbers in diagnostics are rebased to the USER's source.
-    const source = buildCompositeShader({ wgsl, paramsDecl })
+    const source = buildCompositeShader({ wgsl, paramsDecl, hasBackground, hasForeground })
     const userLineOffset = source.slice(0, source.indexOf(wgsl)).split("\n").length - 1
     this.device.pushErrorScope("validation")
-    const module = this.device.createShaderModule({ label: "composite shader (bg effect)", code: source })
+    const module = this.device.createShaderModule({ label: "composite shader (effect)", code: source })
     const info = await module.getCompilationInfo()
     const scopeErr = await this.device.popErrorScope()
     const diagnostics = info.messages
       .filter((m) => m.type === "error")
       .map((m) => `${Math.max(0, m.lineNum - userLineOffset)}:${m.linePos} ${m.message}`)
     if (diagnostics.length === 0 && scopeErr) diagnostics.push(scopeErr.message)
-    if (diagnostics.length > 0) return { ok: false, diagnostics }
+    if (diagnostics.length > 0) return { ok: false, diagnostics, mounts }
     let identity: GPURenderPipeline
     let gamma: GPURenderPipeline
     try {
@@ -1303,37 +1371,42 @@ export class Engine {
           primitive: { topology: "triangle-list" },
         })
       ;[identity, gamma] = await Promise.all([
-        make(false, "composite pipeline (bg effect, gamma=1)"),
-        make(true, "composite pipeline (bg effect, gamma!=1)"),
+        make(false, "composite pipeline (effect, gamma=1)"),
+        make(true, "composite pipeline (effect, gamma!=1)"),
       ])
     } catch (e) {
-      return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] }
+      return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts }
     }
 
     // ── Swap — only now does the old effect (and its params buffer) go away.
-    this.backgroundEffect?.paramsBuffer?.destroy()
+    this.effect?.paramsBuffer?.destroy()
     let paramsBuffer: GPUBuffer | null = null
     if (entries.length) {
       paramsBuffer = this.device.createBuffer({
-        label: "bg effect params",
+        label: "effect params",
         size: paramsData.byteLength,
         usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
       })
       this.device.queue.writeBuffer(paramsBuffer, 0, paramsData)
     }
-    this.backgroundEffect = { wgsl, paramLayout: layout, paramsBuffer, paramsData }
+    this.effect = { wgsl, paramLayout: layout, paramsBuffer, paramsData, hasBackground, hasForeground }
     this.compositePipelineIdentity = identity
     this.compositePipelineGamma = gamma
-    this.bgEffectEpochMs = performance.now()
+    this.effectEpochMs = performance.now()
     this.rebuildCompositeBindGroup()
     this.writeCompositeViewUniforms()
-    return { ok: true, diagnostics: [] }
+    return { ok: true, diagnostics: [], mounts }
+  }
+
+  /** Which mounts the installed effect declared. Both false when none is set. */
+  getEffectMounts(): { background: boolean; foreground: boolean } {
+    return { background: this.effect?.hasBackground ?? false, foreground: this.effect?.hasForeground ?? false }
   }
 
-  /** Write one background-effect param (declared at setBackgroundEffect) — a
-   *  uniform write, no recompile; the instant tier, like setStyleParam. */
-  setBackgroundEffectParam(name: string, value: BackgroundEffectParamValue): void {
-    const fx = this.backgroundEffect
+  /** Write one effect param (declared at setEffect) — a uniform write, no
+   *  recompile; the instant tier, like setStyleParam. */
+  setEffectParam(name: string, value: EffectParamValue): void {
+    const fx = this.effect
     if (!fx || !fx.paramsBuffer) return
     const slot = fx.paramLayout.get(name)
     if (!slot) return
@@ -1407,7 +1480,10 @@ export class Engine {
     if (!this.device || !this.dofUniformBuffer) return
     const d = this.depthOfField
     const u = this.dofUniformData
-    const auto = d.focusMode === "auto" ? this.getModelBodyFocus() : null
+    // `d.enabled &&`, because a foreground effect also drives this write (for
+    // projA/projB alone) and auto-focus walks every visible character's bones —
+    // work nothing would read with the gather switched off.
+    const auto = d.enabled && d.focusMode === "auto" ? this.getModelBodyFocus() : null
     u[0] = d.enabled ? 1 : 0
     u[1] = auto?.distance ?? Math.max(d.focusDistance, 0.05)
     // In auto mode the authored range is a floor — the sharp band never cuts
@@ -1591,6 +1667,37 @@ export class Engine {
   // smooth gradients) while still passing through every anchor (look preserved) and staying
   // monotone (no tonemap overshoot/ringing). Domain is uniform in log2 space: anchor k sits
   // at t=k, k=0..13 (t = log2(linear)+10). See composite.ts::filmic for the sampling map.
+  /**
+   * Decompress and upload Blender's AgX cube.
+   *
+   * Deliberately off the critical path: it is 723 KB once inflated, and a frame
+   * rendered before it lands should show the scene under whatever transform is
+   * already there rather than wait. Until then binding 10 holds a 1×1×1 stand-in,
+   * which is only ever sampled if someone selects AgX in that window.
+   */
+  private async loadAgxLut(): Promise<void> {
+    try {
+      const packed = Uint8Array.from(atob(AGX_LUT_GZ), (ch) => ch.charCodeAt(0))
+      const stream = new Blob([packed]).stream().pipeThrough(new DecompressionStream("gzip"))
+      const bytes = new Uint8Array(await new Response(stream).arrayBuffer())
+      const n = AGX_LUT_SIZE
+      if (bytes.byteLength !== n * n * n * 4) throw new Error(`AgX LUT is ${bytes.byteLength} bytes, expected ${n ** 3 * 4}`)
+      const tex = this.device.createTexture({
+        label: "AgX 57³ LUT",
+        size: [n, n, n],
+        dimension: "3d",
+        format: "rgb10a2unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+      })
+      // .cube order is red fastest, which is exactly a 3D texture's own layout.
+      this.device.queue.writeTexture({ texture: tex }, bytes, { bytesPerRow: n * 4, rowsPerImage: n }, [n, n, n])
+      this.agxLutTexture = tex
+      this.rebuildCompositeBindGroup()
+    } catch {
+      // A missing LUT costs AgX, not the renderer — the other transforms stand.
+    }
+  }
+
   private bakeFilmicLut() {
     const anchors = [
       0.0028, 0.0068, 0.0151, 0.0313, 0.061, 0.112, 0.192, 0.306, 0.459, 0.631, 0.82, 0.907, 0.962, 0.989,
@@ -1864,6 +1971,13 @@ export class Engine {
         // StyleUniforms for compiled graph shaders (adjust-tier sliders). Hand-written
         // presets simply don't declare it — a layout may carry bindings a shader ignores.
         { binding: 4, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        // Style-group image maps. A PMX material carries one image; a
+        // Blender-authored look needs a lightmap or ramp beside it, and those
+        // belong to the GROUP rather than to the model's own material data.
+        { binding: 5, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        { binding: 6, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        { binding: 7, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        { binding: 8, visibility: GPUShaderStage.FRAGMENT, texture: {} },
       ],
     })
 
@@ -1996,6 +2110,14 @@ export class Engine {
 
     // One-shot bake of Blender EEVEE's combined BRDF LUT (DFG + LTC packed rgba8unorm).
     this.bakeBrdfLut()
+    this.agxFallbackTexture = this.device.createTexture({
+      label: "AgX LUT fallback",
+      size: [1, 1, 1],
+      dimension: "3d",
+      format: "rgb10a2unorm",
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    })
+    void this.loadAgxLut()
     this.bakeFilmicLut()
 
     // Now that shadow resources exist, create the main per-frame bind group
@@ -2286,11 +2408,12 @@ export class Engine {
     // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
     this.compositeUniformBuffer = this.device.createBuffer({
       label: "composite view uniforms",
-      // 10 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
+      // 11 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
       // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
-      // (time, _, canvas width, canvas height) for user background effects ·
-      // three grade vectors (CDL offset+contrast, power+saturation, slope+flag).
-      size: 160,
+      // (time, _, canvas width, canvas height) for user effects · three grade
+      // vectors (CDL offset+contrast, power+saturation, slope+flag) · camera
+      // world position, for an effect placing itself in the scene.
+      size: 176,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
     this.dofUniformBuffer = this.device.createBuffer({
@@ -2330,6 +2453,9 @@ export class Engine {
           texture: { sampleType: "depth", viewDimension: "2d", multisampled: true },
         },
         { binding: 9, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        // AgX's 57³ cube. Decompressed and uploaded off the critical path, so a
+        // 1×1×1 stand-in keeps the bind group valid until it arrives.
+        { binding: 10, visibility: GPUShaderStage.FRAGMENT, texture: { viewDimension: "3d" } },
       ],
     })
     this.fallbackEquirectTexture = this.device.createTexture({
@@ -3010,6 +3136,13 @@ export class Engine {
     return this.cameraAnimation !== null
   }
 
+  /** Seconds the loaded camera VMD runs for — its last keyframe — or 0 with none
+   *  loaded. A timeline cannot draw a lane to scale without it, and the camera's
+   *  length is its own: it does not have to match any model's clip. */
+  getCameraVmdDuration(): number {
+    return this.cameraAnimation?.duration ?? 0
+  }
+
   /** Drop the loaded camera VMD and return to orbit control. */
   clearCameraVmd(): void {
     this.cameraAnimation = null
@@ -3238,7 +3371,7 @@ export class Engine {
     // explicit destroy). Per-model group buffers are torn down in removeModel; the shared
     // zero buffer is engine-owned.
     this.forEachInstance((inst) => {
-      for (const install of inst.styleGroups.values()) install.uniformBuffer.destroy()
+      for (const install of inst.styleGroups.values()) this.destroyInstall(install)
       inst.styleGroups.clear()
     })
     this.zeroStyleBuffer?.destroy()
@@ -3387,7 +3520,7 @@ export class Engine {
       buf.destroy()
     }
     // Per-group StyleUniforms buffers aren't in gpuBuffers (allocated post-load).
-    for (const install of inst.styleGroups.values()) install.uniformBuffer.destroy()
+    for (const install of inst.styleGroups.values()) this.destroyInstall(install)
     this.modelInstances.delete(name)
   }
 
@@ -3469,11 +3602,58 @@ export class Engine {
 
   // Build a material's bind group with binding(4) pointing at a given StyleUniforms buffer
   // (the group's buffer when grouped, or the shared zero buffer when ungrouped).
-  private createMaterialBindGroup(label: string, baseEntries: GPUBindGroupEntry[], styleBuffer: GPUBuffer): GPUBindGroup {
+  /** A group's uniform buffer and its maps have the same lifetime — freeing one
+   *  without the other is how a re-apply leaks GPU memory a frame at a time. */
+  private destroyInstall(install: GroupInstall): void {
+    install.uniformBuffer.destroy()
+    for (const tex of install.images ?? []) tex?.destroy()
+  }
+
+  /** Upload a group's image maps. Sources are decoded images the host already
+   *  holds; the engine never fetches, matching how models and motions arrive. */
+  private uploadGroupImages(group: StyleGroup): (GPUTexture | null)[] | undefined {
+    if (!group.images?.length) return undefined
+    return group.images.slice(0, 4).map((entry) => {
+      if (!entry) return null
+      const wrapped = "source" in entry
+      const src = wrapped ? entry.source : entry
+      const width = Math.max(1, "naturalWidth" in src ? src.naturalWidth : src.width)
+      const height = Math.max(1, "naturalHeight" in src ? src.naturalHeight : src.height)
+      const tex = this.device.createTexture({
+        label: `group map: ${group.id}`,
+        size: [width, height],
+        // Colour maps decode to linear on sample, the way material textures do;
+        // data maps must not, or every threshold packed in their channels moves.
+        format: wrapped && entry.srgb ? "rgba8unorm-srgb" : "rgba8unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+      })
+      this.device.queue.copyExternalImageToTexture(
+        { source: src },
+        { texture: tex, premultipliedAlpha: wrapped && entry.premultiplied === true },
+        [width, height],
+      )
+      return tex
+    })
+  }
+
+  private createMaterialBindGroup(
+    label: string,
+    baseEntries: GPUBindGroupEntry[],
+    styleBuffer: GPUBuffer,
+    groupImages?: (GPUTexture | null)[],
+  ): GPUBindGroup {
+    // Every material bind group in the engine is built here, which is why the
+    // group's maps are threaded through this one function rather than patched in
+    // at each call site — an unset slot reads white, never stale.
+    const slots: GPUBindGroupEntry[] = []
+    for (let i = 0; i < 4; i++) {
+      const tex = groupImages?.[i] ?? this.fallbackMaterialTexture
+      slots.push({ binding: 5 + i, resource: tex.createView() })
+    }
     return this.device.createBindGroup({
       label,
       layout: this.mainPerMaterialBindGroupLayout,
-      entries: [...baseEntries, { binding: 4, resource: { buffer: styleBuffer } }],
+      entries: [...baseEntries, { binding: 4, resource: { buffer: styleBuffer } }, ...slots],
     })
   }
 
@@ -5213,12 +5393,20 @@ export class Engine {
     this.updateShadowLightVP()
 
     // Depth of field's entire disabled cost is this branch: depth stays in
-    // TBDR tile memory (discard) unless the composite gather reads it this
-    // frame. Enabled frames also refresh the uniforms — auto-focus tracks the
-    // character and the depth-inversion constants track near/far.
+    // TBDR tile memory (discard) unless something in the composite reads it this
+    // frame. Two things can — the DoF gather, and the depth handed to a
+    // foreground effect — and either one makes the pass store it.
+    //
+    // The uniform refresh is shared for the same reason: linearDepth() inverts
+    // the z-buffer with projA/projB out of dofU[2], which track the camera's
+    // near/far and so must be rewritten every frame either reader is live. A
+    // foreground with a stale pair would read metres from the wrong frustum. The
+    // write leaves dofU[0].x at 0 while DoF is off, so refreshing it does not
+    // switch the gather on.
     const dofOn = this.depthOfField.enabled
-    this.renderPassDescriptor.depthStencilAttachment!.depthStoreOp = dofOn ? "store" : "discard"
-    if (dofOn) this.writeDepthOfFieldUniforms()
+    const depthRead = dofOn || (this.effect?.hasForeground ?? false)
+    this.renderPassDescriptor.depthStencilAttachment!.depthStoreOp = depthRead ? "store" : "discard"
+    if (depthRead) this.writeDepthOfFieldUniforms()
 
     const encoder = this.device.createCommandEncoder()
 
@@ -5437,7 +5625,7 @@ export class Engine {
     for (const [id, install] of inst.styleGroups) {
       if (!nextIds.has(id)) {
         inst.styleGroupGen.set(id, (inst.styleGroupGen.get(id) ?? 0) + 1)
-        install.uniformBuffer.destroy()
+        this.destroyInstall(install)
         inst.styleGroups.delete(id)
       }
     }
@@ -5474,7 +5662,7 @@ export class Engine {
     const install = inst?.styleGroups.get(groupId)
     if (!inst || !install) return
     inst.styleGroupGen.set(groupId, (inst.styleGroupGen.get(groupId) ?? 0) + 1) // discard in-flight compile
-    install.uniformBuffer.destroy()
+    this.destroyInstall(install)
     inst.styleGroups.delete(groupId)
     this.assignDrawCallGroups(inst, this.currentClaims(inst))
   }
@@ -5485,7 +5673,7 @@ export class Engine {
     if (!inst) return
     for (const [id, install] of inst.styleGroups) {
       inst.styleGroupGen.set(id, (inst.styleGroupGen.get(id) ?? 0) + 1)
-      install.uniformBuffer.destroy()
+      this.destroyInstall(install)
     }
     inst.styleGroups.clear()
     this.assignDrawCallGroups(inst, new Map())
@@ -5585,6 +5773,9 @@ export class Engine {
         usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
       })
 
+    // The outgoing install's maps go with it — a re-apply that changes images
+    // would otherwise strand the old textures for the life of the model.
+    const previousImages = inst.styleGroups.get(group.id)?.images
     inst.styleGroups.set(group.id, {
       group,
       renderClass,
@@ -5593,9 +5784,31 @@ export class Engine {
       pipelineNoDepthWrite,
       overEyesPipeline,
       uniformBuffer,
+      images: this.uploadGroupImages(group),
       slotMap: result.slotMap,
       signature,
     })
+    // Rebind this group's draw calls before the old textures go.
+    //
+    // assignDrawCallGroups only rebuilds a bind group when a material CHANGES
+    // group, which is the wrong test here: swapping the graph on a group a
+    // material already belongs to leaves its id alone while replacing the maps
+    // underneath it. The draw call then kept a bind group holding the outgoing
+    // textures — destroyed on the next line — so a graph swap either sampled the
+    // old maps, or the fallback white where the previous graph had none (which
+    // reads as a blown-out white material through any screen or add), or tripped
+    // a validation error on a destroyed texture. Only a reload cleared it.
+    const install = inst.styleGroups.get(group.id)
+    for (const dc of inst.drawCalls) {
+      if (!dc.baseBindGroupEntries || dc.groupId !== group.id) continue
+      dc.bindGroup = this.createMaterialBindGroup(
+        `material: ${dc.materialName}`,
+        dc.baseBindGroupEntries,
+        uniformBuffer,
+        install?.images,
+      )
+    }
+    for (const tex of previousImages ?? []) tex?.destroy()
     this.writeGroupDefaults(uniformBuffer, group, result.slotMap)
     return { ok: true, diagnostics, slotMap: result.slotMap }
   }
@@ -5616,6 +5829,7 @@ export class Engine {
         `material: ${dc.materialName}`,
         dc.baseBindGroupEntries,
         install ? install.uniformBuffer : this.zeroStyleBuffer,
+        install?.images,
       )
     }
     this.sortDrawCalls(inst)
@@ -5881,7 +6095,7 @@ export class Engine {
     // is LEFT-HANDED (+Z forward, see Mat4.lookAtInto), so the world-space
     // right/up/FORWARD vectors are rows 0/1/2 of its rotation block directly
     // (column-major storage: row i = values[i], values[i+4], values[i+8]).
-    if ((this.backdropEquirectView || this.backgroundEffect) && this.compositeUniformBuffer) {
+    if ((this.backdropEquirectView || this.effect) && this.compositeUniformBuffer) {
       const v = viewMatrix.values
       const u = this.compositeUniformData
       const tanHalf = Math.tan((this.camera.fov ?? Math.PI / 4) / 2)
@@ -5899,9 +6113,15 @@ export class Engine {
       u[22] = v[10]
       u[23] = 0
       // Effect clock + canvas size (viewU[6]) — written on the same refresh.
-      u[24] = (performance.now() - this.bgEffectEpochMs) / 1000
+      u[24] = (performance.now() - this.effectEpochMs) / 1000
       u[26] = this.canvas.width
       u[27] = this.canvas.height
+      // Camera world position (viewU[10]) — the other half of bgWorldPos. It
+      // rides this refresh rather than writeCompositeViewUniforms because it
+      // changes every frame the camera does, exactly like the basis above.
+      u[40] = cameraPos.x
+      u[41] = cameraPos.y
+      u[42] = cameraPos.z
       this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u)
     }
   }