reze-engine 0.40.0 → 0.41.1

package/dist/engine.js

@@ -17,6 +17,7 @@ import { TRANSPARENT_DEPTH_PREPASS_WGSL } from "./shaders/passes/depth-prepass";
 import { SELECTION_MASK_SHADER_WGSL, SELECTION_EDGE_SHADER_WGSL } from "./shaders/passes/selection";
 import { GIZMO_SHADER_WGSL } from "./shaders/passes/gizmo";
 import { BLOOM_BLIT_SHADER_WGSL, 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";
@@ -46,7 +47,17 @@ const PRESET_NAME_HINTS = [
         "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", "耳环", "耳環"]],
     [
@@ -159,7 +170,7 @@ export const DEFAULT_DEPTH_OF_FIELD_OPTIONS = {
 export const DEFAULT_VIEW_TRANSFORM = {
     exposure: 0.6,
     gamma: 1.0,
-    look: "medium_high_contrast",
+    transform: "filmic",
 };
 const NEUTRAL_GRADE_CHANNEL = 0.5;
 export const DEFAULT_COLOR_GRADING = {
@@ -302,19 +313,24 @@ export class Engine {
         /** Depth-only view of the scene's MSAA depth buffer, read by the DoF gather. */
         this.depthReadView = null;
         // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-        this.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.
+        this.compositeUniformData = new Float32Array(44);
         /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
         this.backgroundColor = null;
         // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
         this.backdropEquirectTexture = null;
         this.backdropEquirectView = null;
-        // 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).
-        this.backgroundEffect = null;
-        /** time=0 origin for the active effect — reset each setBackgroundEffect. */
-        this.bgEffectEpochMs = 0;
+        this.effect = null;
+        this.agxLutTexture = null;
+        /** time=0 origin for the active effect — reset each setEffect. */
+        this.effectEpochMs = 0;
         this.compositeBloomView = null;
         this.bloomBlitUniformData = new Float32Array(4);
         this.bloomUpsampleUniformData = new Float32Array(4);
@@ -649,7 +665,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,
         };
     }
     /** Current bloom settings (Blender names; tint is a copied `Vec3`). */
@@ -667,7 +683,7 @@ export class Engine {
     }
     getViewTransformOptions() {
         const v = this.viewTransform;
-        return { exposure: v.exposure, gamma: v.gamma, look: v.look };
+        return { exposure: v.exposure, gamma: v.gamma, transform: v.transform };
     }
     /**
      * Color-grade the tonemapped scene (ASC CDL slope/offset/power + saturation).
@@ -707,8 +723,8 @@ export class Engine {
             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();
         }
@@ -737,10 +753,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,
@@ -799,9 +817,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" }) },
             ],
         });
     }
@@ -864,42 +883,71 @@ 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, params) {
+    async setEffect(wgsl, params) {
+        const noMounts = { background: false, foreground: false };
         if (!this.device)
-            return { ok: false, diagnostics: ["setBackgroundEffect requires init() to have run"] };
+            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
         // uniform rules (f32 align 4, vec3f align 16 size 12), computed identically
@@ -910,7 +958,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;
@@ -931,14 +979,14 @@ 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
@@ -947,7 +995,7 @@ export class Engine {
         if (diagnostics.length === 0 && scopeErr)
             diagnostics.push(scopeErr.message);
         if (diagnostics.length > 0)
-            return { ok: false, diagnostics };
+            return { ok: false, diagnostics, mounts };
         let identity;
         let gamma;
         try {
@@ -964,36 +1012,40 @@ 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 = 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() {
+        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, value) {
-        const fx = this.backgroundEffect;
+    /** Write one effect param (declared at setEffect) — a uniform write, no
+     *  recompile; the instant tier, like setStyleParam. */
+    setEffectParam(name, value) {
+        const fx = this.effect;
         if (!fx || !fx.paramsBuffer)
             return;
         const slot = fx.paramLayout.get(name);
@@ -1073,7 +1125,10 @@ export class Engine {
             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
@@ -1247,6 +1302,38 @@ 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.
+     */
+    async loadAgxLut() {
+        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.
+        }
+    }
     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,
@@ -1492,6 +1579,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: {} },
             ],
         });
         // Shared zero StyleUniforms buffer — bound by every ungrouped material; grouped
@@ -1619,6 +1713,14 @@ export class Engine {
         this.shadowMapDepthView = this.shadowMapTexture.createView();
         // 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
         this.perFrameBindGroup = this.device.createBindGroup({
@@ -1891,11 +1993,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({
@@ -1935,6 +2038,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({
@@ -2536,6 +2642,12 @@ export class Engine {
     hasCameraVmd() {
         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() {
+        return this.cameraAnimation?.duration ?? 0;
+    }
     /** Drop the loaded camera VMD and return to orbit control. */
     clearCameraVmd() {
         this.cameraAnimation = null;
@@ -2740,7 +2852,7 @@ export class Engine {
         // zero buffer is engine-owned.
         this.forEachInstance((inst) => {
             for (const install of inst.styleGroups.values())
-                install.uniformBuffer.destroy();
+                this.destroyInstall(install);
             inst.styleGroups.clear();
         });
         this.zeroStyleBuffer?.destroy();
@@ -2866,7 +2978,7 @@ export class Engine {
         }
         // Per-group StyleUniforms buffers aren't in gpuBuffers (allocated post-load).
         for (const install of inst.styleGroups.values())
-            install.uniformBuffer.destroy();
+            this.destroyInstall(install);
         this.modelInstances.delete(name);
     }
     getModelNames() {
@@ -2948,11 +3060,50 @@ 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).
-    createMaterialBindGroup(label, baseEntries, styleBuffer) {
+    /** 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. */
+    destroyInstall(install) {
+        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. */
+    uploadGroupImages(group) {
+        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;
+        });
+    }
+    createMaterialBindGroup(label, baseEntries, styleBuffer, groupImages) {
+        // 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 = [];
+        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],
         });
     }
     setMaterialVisible(modelName, materialName, visible) {
@@ -4305,12 +4456,20 @@ export class Engine {
         this.updateCameraUniforms();
         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)
+        const depthRead = dofOn || (this.effect?.hasForeground ?? false);
+        this.renderPassDescriptor.depthStencilAttachment.depthStoreOp = depthRead ? "store" : "discard";
+        if (depthRead)
             this.writeDepthOfFieldUniforms();
         const encoder = this.device.createCommandEncoder();
         // GPU vertex morphs: write morphed positions into vertex buffers before any pass reads
@@ -4523,7 +4682,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);
             }
         }
@@ -4557,7 +4716,7 @@ export class Engine {
         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));
     }
@@ -4568,7 +4727,7 @@ export class Engine {
             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());
@@ -4657,6 +4816,9 @@ export class Engine {
                 size: 256,
                 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,
@@ -4665,9 +4827,28 @@ 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 };
     }
@@ -4686,7 +4867,7 @@ export class Engine {
             if (dc.groupId === groupId)
                 continue;
             dc.groupId = groupId;
-            dc.bindGroup = this.createMaterialBindGroup(`material: ${dc.materialName}`, dc.baseBindGroupEntries, install ? install.uniformBuffer : this.zeroStyleBuffer);
+            dc.bindGroup = this.createMaterialBindGroup(`material: ${dc.materialName}`, dc.baseBindGroupEntries, install ? install.uniformBuffer : this.zeroStyleBuffer, install?.images);
         }
         this.sortDrawCalls(inst);
     }
@@ -4938,7 +5119,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);
@@ -4956,9 +5137,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);
         }
     }

package/dist/graph/presets/body.js

@@ -52,7 +52,7 @@ export const BODY_GRAPH = {
         {
             id: "principled",
             type: "principled",
-            inputs: { metallic: 0.0, specular: 0.5, roughness: 0.3, spec_clamp: 10.0, sheen: 0.0, sheen_tint: 0.0 },
+            inputs: { metallic: 0.0, specular_ior_level: 0.5, roughness: 0.3, spec_clamp: 10.0, sheen_weight: 0.0, sheen_tint: 0.0 },
         },
         { id: "p_sum", type: "add_shader" },
         { id: "mix_shader_001", type: "mix_shader", inputs: { fac: 0.5 } },
@@ -89,7 +89,7 @@ export const BODY_GRAPH = {
         { from: { node: "noise_ramp", socket: "fac_out" }, to: { node: "principled_base", socket: "fac" } },
         { from: { node: "bc", socket: "color" }, to: { node: "principled_base", socket: "a" } },
         { from: { node: "bc", socket: "color" }, to: { node: "p_emit", socket: "color" } },
-        { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base" } },
+        { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base_color" } },
         { from: { node: "bump", socket: "vector" }, to: { node: "principled", socket: "normal" } },
         { from: { node: "principled", socket: "color" }, to: { node: "p_sum", socket: "a" } },
         { from: { node: "p_emit", socket: "color" }, to: { node: "p_sum", socket: "b" } },