reze-engine 0.24.1 → 0.25.1

package/dist/engine.js

@@ -12,10 +12,11 @@ import { LTC_MAG_LUT_SIZE, LTC_MAG_LUT_DATA } from "./shaders/ltc_mag_lut";
 import { SHADOW_DEPTH_SHADER_WGSL } from "./shaders/passes/shadow";
 import { GROUND_SHADOW_SHADER_WGSL } from "./shaders/passes/ground";
 import { OUTLINE_SHADER_WGSL } from "./shaders/passes/outline";
+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 { COMPOSITE_SHADER_WGSL } from "./shaders/passes/composite";
+import { buildCompositeShader } from "./shaders/passes/composite";
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick";
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap";
 import { compileGraph } from "./graph/compile";
@@ -147,6 +148,91 @@ export const DEFAULT_ENGINE_OPTIONS = {
     camera: { distance: 26.6, target: new Vec3(0, 12.5, 0), fov: Math.PI / 4 },
     onRaycast: undefined,
 };
+// ── Sheer-material detection ──────────────────────────────────────────────────
+// PMX carries no "translucent" flag: a see-through veil usually has diffuse
+// alpha 1.0 and does its transparency entirely in the TEXTURE's alpha channel.
+// Classifying by material alpha alone put such cloth in the opaque bucket,
+// where it draws in PMX order with depth writes — anything the engine draws
+// after it (the hair render-class draws LAST for the eye-stencil effect) got
+// depth-rejected behind the veil, so you saw the body through it but not the
+// hair. These helpers measure a material's real coverage by sampling the
+// texture's alpha at the material's own triangle CENTROIDS — centroids, not
+// vertices, because hair-card corners sit in transparent texture margins and
+// vertex sampling would misclassify hair (which must stay opaque-bucket for
+// stencil interplay and shadows).
+/** Downsampled alpha plane of a decoded texture (≤128², nearest-sampled). */
+function buildAlphaSampler(source, rgba, width, height) {
+    try {
+        const w = Math.max(1, Math.min(128, width));
+        const h = Math.max(1, Math.min(128, height));
+        const canvas = new OffscreenCanvas(w, h);
+        const cx = canvas.getContext("2d", { willReadFrequently: true });
+        if (!cx)
+            return null;
+        if (source) {
+            cx.drawImage(source, 0, 0, w, h);
+        }
+        else if (rgba) {
+            const tmp = new OffscreenCanvas(width, height);
+            const tcx = tmp.getContext("2d");
+            if (!tcx)
+                return null;
+            tcx.putImageData(new ImageData(new Uint8ClampedArray(rgba), width, height), 0, 0);
+            cx.drawImage(tmp, 0, 0, w, h);
+        }
+        else {
+            return null;
+        }
+        const img = cx.getImageData(0, 0, w, h).data;
+        const a = new Uint8ClampedArray(w * h);
+        for (let i = 0; i < w * h; i++)
+            a[i] = img[i * 4 + 3];
+        return { a, w, h };
+    }
+    catch {
+        return null;
+    }
+}
+/** Texture-alpha statistics over ≤400 of the material's triangle centroids:
+ *  `avg` (0..1) and `translucentFrac` — the fraction of samples that are
+ *  neither fully opaque nor fully cut out (alpha in ~0.03..0.97). Together
+ *  they classify two distinct things:
+ *    sheer   (avg low)            — a veil: mostly see-through everywhere
+ *    partial (translucentFrac up) — mostly-opaque cloth with sheer REGIONS,
+ *                                   e.g. a lace skirt panel
+ *  Both route to the transparent bucket; only `sheer` is excluded from the
+ *  shadow map and outline pass. */
+const SHEER_ALPHA_THRESHOLD = 0.7;
+const PARTIAL_TRANSLUCENT_FRAC = 0.15;
+function materialAlphaStats(verts, indices, firstIndex, count, sampler) {
+    if (!sampler)
+        return { avg: 1, translucentFrac: 0 };
+    const triCount = Math.floor(count / 3);
+    if (triCount === 0)
+        return { avg: 1, translucentFrac: 0 };
+    const step = Math.max(1, Math.floor(triCount / 400));
+    let sum = 0;
+    let translucent = 0;
+    let n = 0;
+    for (let t = 0; t < triCount; t += step) {
+        const i0 = indices[firstIndex + t * 3];
+        const i1 = indices[firstIndex + t * 3 + 1];
+        const i2 = indices[firstIndex + t * 3 + 2];
+        const u = (verts[i0 * 8 + 6] + verts[i1 * 8 + 6] + verts[i2 * 8 + 6]) / 3;
+        const v = (verts[i0 * 8 + 7] + verts[i1 * 8 + 7] + verts[i2 * 8 + 7]) / 3;
+        // Wrap (MMD UVs may tile), then nearest-sample the downsampled plane.
+        const x = Math.min(sampler.w - 1, Math.max(0, Math.floor((u - Math.floor(u)) * sampler.w)));
+        const y = Math.min(sampler.h - 1, Math.max(0, Math.floor((v - Math.floor(v)) * sampler.h)));
+        const a = sampler.a[y * sampler.w + x];
+        sum += a;
+        if (a > 8 && a < 247)
+            translucent++;
+        n++;
+    }
+    if (n === 0)
+        return { avg: 1, translucentFrac: 0 };
+    return { avg: sum / n / 255, translucentFrac: translucent / n };
+}
 export class Engine {
     static getInstance() {
         if (!Engine.instance) {
@@ -188,12 +274,19 @@ export class Engine {
         // unchanged).
         this.hdrFormat = "rgba16float";
         // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-        this.compositeUniformData = new Float32Array(24);
+        this.compositeUniformData = new Float32Array(28);
         /** 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
+        // recompile (the same instant tier as setStyleParam).
+        this.backgroundEffect = null;
+        /** time=0 origin for the active effect — reset each setBackgroundEffect. */
+        this.bgEffectEpochMs = 0;
         this.compositeBloomView = null;
         this.bloomBlitUniformData = new Float32Array(4);
         this.bloomUpsampleUniformData = new Float32Array(4);
@@ -210,6 +303,11 @@ export class Engine {
         this.pendingPick = null;
         this.modelInstances = new Map();
         this.textureCache = new Map();
+        // Downsampled CPU alpha channel per texture (≤128², ~16KB) — kept so materials
+        // can be classified as SHEER at load by sampling alpha at their own UVs (the
+        // GPU texture can't be read back cheaply, and PMX diffuse alpha is usually 1.0
+        // even for see-through cloth: the translucency lives in the texture).
+        this.textureAlphaCache = new Map();
         this.mipBlitPipeline = null;
         this.mipBlitSampler = null;
         this._nextDefaultModelId = 0;
@@ -239,6 +337,8 @@ export class Engine {
         };
         this.animationFrameId = null;
         this.renderLoopCallback = null;
+        /** Debug/diagnostic: skip every inverted-hull outline draw. */
+        this.outlineEnabled = true;
         /** When set, render resolution is pinned to this size instead of tracking the
          *  canvas's CSS size × devicePixelRatio (see setRenderSize). */
         this.fixedRenderSize = null;
@@ -537,7 +637,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.
         u[11] = this.backdropEquirectView ? 2 : bg ? 1 : 0;
+        u[25] = this.backgroundEffect ? 1 : 0;
+        u[26] = this.canvas.width;
+        u[27] = this.canvas.height;
         this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u);
     }
     /**
@@ -552,6 +657,9 @@ export class Engine {
         if (this.device && this.compositeUniformBuffer)
             this.writeCompositeViewUniforms();
     }
+    setOutlineEnabled(on) {
+        this.outlineEnabled = on;
+    }
     rebuildCompositeBindGroup() {
         if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView)
             return;
@@ -566,6 +674,7 @@ 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 } },
             ],
         });
     }
@@ -613,6 +722,165 @@ export class Engine {
         if (this.device && this.compositeUniformBuffer)
             this.writeCompositeViewUniforms();
     }
+    makeCompositePipeline(module, applyGamma, label) {
+        return this.device.createRenderPipeline({
+            label,
+            layout: this.compositePipelineLayout,
+            vertex: { module, entryPoint: "vs" },
+            fragment: {
+                module,
+                entryPoint: "fs",
+                constants: { APPLY_GAMMA: applyGamma ? 1 : 0 },
+                targets: [{ format: this.presentationFormat }],
+            },
+            primitive: { topology: "triangle-list" },
+        });
+    }
+    /**
+     * 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:
+     *
+     *     fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+     *
+     * 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.
+     *
+     * 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.
+     */
+    async setBackgroundEffect(wgsl, params) {
+        if (!this.device)
+            return { ok: false, diagnostics: ["setBackgroundEffect requires init() to have run"] };
+        if (wgsl === null) {
+            this.backgroundEffect?.paramsBuffer?.destroy();
+            this.backgroundEffect = 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: [] };
+        }
+        // ── 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
+        // on both sides so no reordering is needed.
+        const entries = Object.entries(params ?? {});
+        const layout = new Map();
+        const fields = [];
+        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)`] };
+            }
+            const isVec = typeof value !== "number";
+            const align = isVec ? 16 : 4;
+            const offset = Math.ceil(cursor / align) * align;
+            layout.set(name, { offset: offset / 4, comps: isVec ? 3 : 1 });
+            fields.push(`  ${name}: ${isVec ? "vec3f" : "f32"},`);
+            cursor = offset + (isVec ? 12 : 4);
+        }
+        const paramsData = new Float32Array(Math.max(4, Math.ceil(cursor / 16) * 4));
+        for (const [name, value] of entries) {
+            const slot = layout.get(name);
+            if (typeof value === "number")
+                paramsData[slot.offset] = value;
+            else {
+                paramsData[slot.offset] = value.x;
+                paramsData[slot.offset + 1] = value.y;
+                paramsData[slot.offset + 2] = value.z;
+            }
+        }
+        const paramsDecl = entries.length
+            ? `struct BgParams {\n${fields.join("\n")}\n}\n@group(0) @binding(7) var<uniform> params: BgParams;\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 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 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 };
+        let identity;
+        let gamma;
+        try {
+            const make = (applyGamma, label) => this.device.createRenderPipelineAsync({
+                label,
+                layout: this.compositePipelineLayout,
+                vertex: { module, entryPoint: "vs" },
+                fragment: {
+                    module,
+                    entryPoint: "fs",
+                    constants: { APPLY_GAMMA: applyGamma ? 1 : 0 },
+                    targets: [{ format: this.presentationFormat }],
+                },
+                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)"),
+            ]);
+        }
+        catch (e) {
+            return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] };
+        }
+        // ── Swap — only now does the old effect (and its params buffer) go away.
+        this.backgroundEffect?.paramsBuffer?.destroy();
+        let paramsBuffer = null;
+        if (entries.length) {
+            paramsBuffer = this.device.createBuffer({
+                label: "bg 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.compositePipelineIdentity = identity;
+        this.compositePipelineGamma = gamma;
+        this.bgEffectEpochMs = performance.now();
+        this.rebuildCompositeBindGroup();
+        this.writeCompositeViewUniforms();
+        return { ok: true, diagnostics: [] };
+    }
+    /** 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;
+        if (!fx || !fx.paramsBuffer)
+            return;
+        const slot = fx.paramLayout.get(name);
+        if (!slot)
+            return;
+        if (typeof value === "number")
+            fx.paramsData[slot.offset] = value;
+        else {
+            fx.paramsData[slot.offset] = value.x;
+            fx.paramsData[slot.offset + 1] = value.y;
+            fx.paramsData[slot.offset + 2] = value.z;
+        }
+        this.device.queue.writeBuffer(fx.paramsBuffer, 0, fx.paramsData);
+    }
     /** Patch bloom; GPU uniforms update immediately if `init()` has run. */
     setBloomOptions(patch) {
         const b = this.bloomSettings;
@@ -1052,6 +1320,44 @@ export class Engine {
                 depthCompare: "less-equal",
             },
         });
+        // Depth-write-off twin for transparent-bucket draws (see pipelineForDrawCall).
+        this.neutralPipelineNoDepthWrite = this.createRenderPipeline({
+            label: "neutral base pipeline (no depth write)",
+            layout: mainPipelineLayout,
+            shaderModule: neutralModule,
+            vertexBuffers: fullVertexBuffers,
+            fragmentTargets: sceneTargets,
+            cullMode: "none",
+            depthStencil: {
+                format: "depth24plus-stencil8",
+                depthWriteEnabled: false,
+                depthCompare: "less-equal",
+            },
+        });
+        // Depth-only prepass for transparent draws (see depth-prepass.ts): writes the
+        // fabric's depth AFTER its color blended, so outlines drawn later are
+        // occluded behind it. Color targets kept for pass compatibility, writeMask 0.
+        const prepassModule = this.device.createShaderModule({
+            label: "transparent depth prepass",
+            code: TRANSPARENT_DEPTH_PREPASS_WGSL,
+        });
+        this.transparentDepthPrepassPipeline = this.device.createRenderPipeline({
+            label: "transparent depth prepass",
+            layout: mainPipelineLayout,
+            vertex: { module: prepassModule, entryPoint: "vs", buffers: fullVertexBuffers },
+            fragment: {
+                module: prepassModule,
+                entryPoint: "fs",
+                targets: sceneTargets.map((t) => ({ format: t.format, writeMask: 0 })),
+            },
+            primitive: { cullMode: "none" },
+            multisample: { count: Engine.MULTISAMPLE_COUNT },
+            depthStencil: {
+                format: "depth24plus-stencil8",
+                depthWriteEnabled: true,
+                depthCompare: "less-equal",
+            },
+        });
         this.shadowLightVPBuffer = this.device.createBuffer({
             size: 64,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
@@ -1180,6 +1486,16 @@ export class Engine {
                 // Don’t write outline into depth buffer — stops z-fighting / black cracks vs body (MMD-style; body depth stays authoritative)
                 depthWriteEnabled: false,
                 depthCompare: "less-equal",
+                // CONFIRMED fix (bisected live via setOutlineEnabled): hull fragments
+                // carry their surface's exact depth, so against this model's paired
+                // near-coplanar skirt layers the hulls WON depth ties in patches —
+                // the black shapes on the dress. A small constant bias makes hulls lose
+                // every tie; silhouette rims compare against the far background and are
+                // unaffected. No slope term — slope explodes at silhouettes and would
+                // erase the rims themselves (previous regression).
+                depthBias: 4,
+                depthBiasSlopeScale: 0,
+                depthBiasClamp: 0,
                 // Skip fragments where the eye stamped stencil=EYE_VALUE. Those pixels are owned by
                 // the see-through-hair blend (hair-over-eyes), so letting the outline's near-black
                 // edge color overwrite them would re-introduce the dark almond we just killed.
@@ -1350,9 +1666,15 @@ export class Engine {
         // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
         this.compositeUniformBuffer = this.device.createBuffer({
             label: "composite view uniforms",
-            // 6 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
-            // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray.
-            size: 96,
+            // 7 × 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.
+            size: 112,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.bgParamsDummyBuffer = this.device.createBuffer({
+            label: "bg effect params (dummy)",
+            size: 16,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
         this.compositeBindGroupLayout = this.device.createBindGroupLayout({
@@ -1369,6 +1691,9 @@ export class Engine {
                 { binding: 5, visibility: GPUShaderStage.FRAGMENT, texture: {} },
                 // 360 backdrop equirect (PhotoDome-style skybox) — 1×1 fallback when unset.
                 { binding: 6, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+                // User background-effect params — dummy buffer when no effect is set. The
+                // layout is explicit, so the base shader legally ignores the binding.
+                { binding: 7, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
             ],
         });
         this.fallbackEquirectTexture = this.device.createTexture({
@@ -1378,27 +1703,15 @@ export class Engine {
             usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
         });
         this.fallbackEquirectView = this.fallbackEquirectTexture.createView();
-        const compositeShader = this.device.createShaderModule({
-            label: "composite shader",
-            code: COMPOSITE_SHADER_WGSL,
-        });
-        const compositePipelineLayout = this.device.createPipelineLayout({
+        this.compositePipelineLayout = this.device.createPipelineLayout({
             bindGroupLayouts: [this.compositeBindGroupLayout],
         });
-        const makeCompositePipeline = (applyGamma, label) => this.device.createRenderPipeline({
-            label,
-            layout: compositePipelineLayout,
-            vertex: { module: compositeShader, entryPoint: "vs" },
-            fragment: {
-                module: compositeShader,
-                entryPoint: "fs",
-                constants: { APPLY_GAMMA: applyGamma ? 1 : 0 },
-                targets: [{ format: this.presentationFormat }],
-            },
-            primitive: { topology: "triangle-list" },
+        const compositeShader = this.device.createShaderModule({
+            label: "composite shader",
+            code: buildCompositeShader(null),
         });
-        this.compositePipelineIdentity = makeCompositePipeline(false, "composite pipeline (gamma=1)");
-        this.compositePipelineGamma = makeCompositePipeline(true, "composite pipeline (gamma!=1)");
+        this.compositePipelineIdentity = this.makeCompositePipeline(compositeShader, false, "composite pipeline (gamma=1)");
+        this.compositePipelineGamma = this.makeCompositePipeline(compositeShader, true, "composite pipeline (gamma!=1)");
         // GPU vertex-morph compute pipeline (shared by all models; per-model bind groups).
         // Bindings: 0-4 read-only storage (base pos, CSR rowStart/colMorph/colOffset, weights),
         // 5 read-write storage (vertex buffer), 6 uniform (params).
@@ -2208,6 +2521,7 @@ export class Engine {
             if (!shared) {
                 tex.destroy();
                 this.textureCache.delete(path);
+                this.textureAlphaCache.delete(path);
             }
         }
         for (const buf of inst.gpuBuffers) {
@@ -2698,12 +3012,17 @@ export class Engine {
         const prefix = `${inst.name}: `;
         // 1-based so that (0,0) = clear color = "no hit"
         const modelId = this.modelInstances.size + 1;
+        const texLogicalPath = (texIndex) => texIndex < 0 || texIndex >= textures.length
+            ? null
+            : joinAssetPath(inst.basePath, normalizeAssetPath(textures[texIndex].path));
         const loadTextureByIndex = async (texIndex) => {
-            if (texIndex < 0 || texIndex >= textures.length)
-                return null;
-            const logicalPath = joinAssetPath(inst.basePath, normalizeAssetPath(textures[texIndex].path));
-            return this.createTextureFromLogicalPath(inst, logicalPath);
+            const logicalPath = texLogicalPath(texIndex);
+            return logicalPath ? this.createTextureFromLogicalPath(inst, logicalPath) : null;
         };
+        // Mesh data for sheerness sampling (8 floats/vertex; uv at +6). See
+        // materialIsSheer — classification happens per material below.
+        const meshVertices = model.getVertices();
+        const meshIndices = model.getIndices();
         // 頭 bone index for the eye shader's rear-view gate (-1 when absent).
         const headBoneIndex = model.getSkeleton().bones.findIndex((b) => b.name === "頭");
         let currentIndexOffset = 0;
@@ -2719,7 +3038,27 @@ export class Engine {
                 diffuseTexture = this.fallbackMaterialTexture;
             }
             const materialAlpha = mat.diffuse[3];
-            const isTransparent = materialAlpha < 1.0 - 0.001;
+            // Transparent bucket when the MATERIAL says so — or when the TEXTURE does
+            // (sheer cloth almost always ships with diffuse alpha 1.0 and carries its
+            // translucency in texture alpha). Transparent-bucket draws happen after
+            // the opaque bucket (and after the late-drawn hair render-class), so a
+            // veil composites over the hair behind it instead of depth-rejecting it;
+            // they are also excluded from the shadow map, so sheer cloth stops
+            // casting the solid shadow of an opaque sheet.
+            const diffusePath = texLogicalPath(mat.diffuseTextureIndex);
+            const alphaSampler = diffusePath ? this.textureAlphaCache.get(diffusePath) : null;
+            const stats = materialAlphaStats(meshVertices, meshIndices, currentIndexOffset, indexCount, alphaSampler);
+            const sheer = stats.avg < SHEER_ALPHA_THRESHOLD;
+            const partial = !sheer && stats.translucentFrac > PARTIAL_TRANSLUCENT_FRAC;
+            // Transparent bucket: drawn after the opaque bucket (and hair) with depth
+            // WRITE OFF, so a lace panel folded in front of itself blends both layers
+            // consistently instead of a triangle-order patchwork of single/double
+            // coverage. Partial-sheer cloth still casts shadows and keeps its outline;
+            // fully sheer cloth (veil) does neither.
+            const isTransparent = materialAlpha < 1.0 - 0.001 || sheer || partial;
+            // Load-time classification log — one line per material, cheap and
+            // invaluable when a model renders wrong (bucket/outline/sheer disputes).
+            console.info(`[reze] ${mat.name}: alpha=${materialAlpha.toFixed(2)} avg=${stats.avg.toFixed(2)} sheerFrac=${stats.translucentFrac.toFixed(2)} ${sheer ? "SHEER" : partial ? "PARTIAL" : "opaque"} bucket=${isTransparent ? "transparent" : "opaque"} edge=${(mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0 ? (sheer ? "skipped(sheer)" : "on") : "off"}`);
             // Sphere map (sph=1 multiply / spa=2 add). Mode 3 (sub-texture UV) is
             // rare and not implemented — treated as none, like a failed load.
             let sphereMode = mat.sphereMode === 1 || mat.sphereMode === 2 ? mat.sphereMode : 0;
@@ -2759,8 +3098,14 @@ export class Engine {
                 materialName: mat.name,
                 groupId: null,
                 baseBindGroupEntries,
+                castsShadow: !sheer,
             });
-            if ((mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0) {
+            // No inverted-hull outline for SHEER materials: the outline shader draws a
+            // solid edgeColor silhouette (it never samples texture alpha), so a
+            // see-through veil dragged a near-black hull over the cloth behind it —
+            // broken black shapes that waved with physics and flickered with camera
+            // angle. A solid rim on see-through fabric is wrong in principle.
+            if ((mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0 && !sheer) {
                 const materialUniformData = new Float32Array([
                     mat.edgeColor[0],
                     mat.edgeColor[1],
@@ -2895,6 +3240,9 @@ export class Engine {
                 return null;
             }
         }
+        // CPU alpha sampler for sheerness classification (see textureAlphaCache).
+        // Canvas 2D premultiplies RGB on readback, but the ALPHA channel is exact.
+        this.textureAlphaCache.set(cacheKey, buildAlphaSampler(source, rgba, width, height));
         const mipLevelCount = Math.floor(Math.log2(Math.max(width, height))) + 1;
         const texture = this.device.createTexture({
             label: `texture: ${cacheKey}`,
@@ -3640,9 +3988,13 @@ export class Engine {
             return { ok: false, diagnostics, slotMap: result.slotMap };
         }
         let pipeline;
+        let pipelineNoDepthWrite;
         let overEyesPipeline;
         try {
             pipeline = await this.createRenderClassPipeline(renderClass, module, false);
+            // Transparent-bucket draws don't write depth (self-overlap must blend, not
+            // patchwork) — same shading, different depth state.
+            pipelineNoDepthWrite = await this.createRenderClassPipeline(renderClass, module, false, false);
             if (renderClass === "hair")
                 overEyesPipeline = await this.createRenderClassPipeline(renderClass, module, true);
         }
@@ -3666,6 +4018,7 @@ export class Engine {
             renderClass,
             alphaMode,
             pipeline,
+            pipelineNoDepthWrite,
             overEyesPipeline,
             uniformBuffer,
             slotMap: result.slotMap,
@@ -3724,14 +4077,14 @@ export class Engine {
             ground: 4,
         };
         inst.drawCalls.sort((a, b) => typeOrder[a.type] - typeOrder[b.type] || this.drawCallRank(inst, a) - this.drawCallRank(inst, b));
-        inst.shadowDrawCalls = inst.drawCalls.filter((d) => d.type === "opaque");
+        inst.shadowDrawCalls = inst.drawCalls.filter((d) => (d.type === "opaque" || d.type === "transparent") && d.castsShadow === true);
     }
     /**
      * Render-class pipeline state. A group's compiled graph swaps the fragment shading; the
      * render-class owns pass integration (stencil interplay, depth bias, cull). auto = plain;
      * eye = stamp + front cull + bias; hair = stencil-test (+ the over-eyes variant).
      */
-    createRenderClassPipeline(renderClass, module, overEyes) {
+    createRenderClassPipeline(renderClass, module, overEyes, depthWrite = true) {
         const base = {
             label: `style ${renderClass}${overEyes ? " (over eyes)" : ""}`,
             layout: this.mainPipelineLayout,
@@ -3741,7 +4094,7 @@ export class Engine {
         };
         const plainDepth = {
             format: "depth24plus-stencil8",
-            depthWriteEnabled: true,
+            depthWriteEnabled: depthWrite,
             depthCompare: "less-equal",
         };
         let depthStencil = plainDepth;
@@ -3788,6 +4141,12 @@ export class Engine {
     // Pipeline for a material draw call: its group's compiled pipeline when grouped, else
     // the neutral base (ungrouped materials render the default graph).
     pipelineForDrawCall(inst, dc) {
+        // Transparent draws WRITE depth — MMD semantics: PMX triangle/material order
+        // is the author's compositing order, and a fold HIDES its far side rather
+        // than blending it (the far side shades dark — light-averted — so letting it
+        // show through read as gray fold-shaped stains; depth-write-off made every
+        // fold do that). The no-write twins stay available for a future true-OIT
+        // path but are deliberately unused.
         if (dc.groupId) {
             const install = inst.styleGroups.get(dc.groupId);
             if (install)
@@ -3828,6 +4187,8 @@ export class Engine {
      * rebind group 0/1 correctly if needed.
      */
     drawOutlines(pass, inst, type) {
+        if (!this.outlineEnabled)
+            return;
         let bound = false;
         for (const draw of inst.drawCalls) {
             if (draw.type !== type || !this.shouldRenderDrawCall(inst, draw))
@@ -3856,12 +4217,35 @@ export class Engine {
         // Single stencil-reference set covers eye (write), hair (read not-equal),
         // and hairOverEyes (read equal). Non-stencil pipelines ignore the value.
         pass.setStencilReference(Engine.STENCIL_EYE_VALUE);
+        // Order matters (the black-hull saga): transparent color draws don't write
+        // depth (self-overlap must double-blend, not patchwork), so ALL outlines
+        // draw after the transparent depth PREPASS has recorded the fabric's depth
+        // — otherwise every hull behind a sheer skirt shows straight through it.
         this.drawMaterials(pass, inst, "opaque");
-        this.drawOutlines(pass, inst, "opaque-outline");
         this.drawHairOverEyes(pass, inst);
         this.drawMaterials(pass, inst, "transparent");
+        this.drawOutlines(pass, inst, "opaque-outline");
         this.drawOutlines(pass, inst, "transparent-outline");
     }
+    /** Depth-only re-draw of transparent-bucket materials (see depth-prepass.ts).
+     *  Unused while transparent draws write depth themselves (MMD parity) — kept
+     *  for the dormant no-write/OIT path. */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    drawTransparentDepthPrepass(pass, inst) {
+        let bound = false;
+        for (const draw of inst.drawCalls) {
+            if (draw.type !== "transparent" || !this.shouldRenderDrawCall(inst, draw))
+                continue;
+            if (!bound) {
+                pass.setPipeline(this.transparentDepthPrepassPipeline);
+                pass.setBindGroup(0, this.perFrameBindGroup);
+                pass.setBindGroup(1, inst.mainPerInstanceBindGroup);
+                bound = true;
+            }
+            pass.setBindGroup(2, draw.bindGroup);
+            pass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0);
+        }
+    }
     /**
      * Second hair pass for the see-through-hair effect. Re-draws every hair-class grouped
      * opaque draw with its compiled over-eyes pipeline — stencil-matched to `EYE_VALUE`,
@@ -3913,7 +4297,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.compositeUniformBuffer) {
+        if ((this.backdropEquirectView || this.backgroundEffect) && this.compositeUniformBuffer) {
             const v = viewMatrix.values;
             const u = this.compositeUniformData;
             const tanHalf = Math.tan((this.camera.fov ?? Math.PI / 4) / 2);
@@ -3930,6 +4314,10 @@ export class Engine {
             u[21] = v[6];
             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[26] = this.canvas.width;
+            u[27] = this.canvas.height;
             this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u);
         }
     }