reze-engine 0.24.1 → 0.25.1

package/dist/gpu-profile.d.ts

@@ -0,0 +1,19 @@
+export declare class GpuTimestamp {
+    enabled: boolean;
+    readonly supported: boolean;
+    private device;
+    private querySet;
+    private resolveBuffer;
+    private readbackBuffer;
+    private nextSlot;
+    private frameLabels;
+    private inFlight;
+    private pendingLabels;
+    constructor(device: GPUDevice);
+    private ensureCreated;
+    beginFrame(): void;
+    wrap(desc: GPURenderPassDescriptor, label: string): GPURenderPassDescriptor;
+    endFrame(encoder: GPUCommandEncoder): void;
+    afterSubmit(): void;
+}
+//# sourceMappingURL=gpu-profile.d.ts.map

package/dist/gpu-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-profile.d.ts","sourceRoot":"","sources":["../src/gpu-profile.ts"],"names":[],"mappings":"AAoBA,qBAAa,YAAY;IACvB,OAAO,UAAQ;IACf,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,QAAQ,CAAQ;IAKxB,OAAO,CAAC,aAAa,CAAwB;gBAEjC,MAAM,EAAE,SAAS;IAK7B,OAAO,CAAC,aAAa;IAiBrB,UAAU,IAAI,IAAI;IAWlB,IAAI,CAAC,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,GAAG,uBAAuB;IAqB3E,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAW1C,WAAW,IAAI,IAAI;CAwBpB"}

package/dist/gpu-profile.js

@@ -0,0 +1,120 @@
+// WebGPU timestamp-query profiling. Records pass durations into the same
+// profiler module as CPU phases (so the snapshot table mixes both with a
+// "gpu." prefix). Read-only — no effect on rendering output.
+//
+// Pattern (per spec):
+//   1. Each render pass declares timestampWrites { begin, end } slot indices.
+//   2. After all passes, encoder.resolveQuerySet writes uint64 ns timestamps
+//      into a QUERY_RESOLVE buffer.
+//   3. We copy the resolve buffer into a MAP_READ readback buffer.
+//   4. Submit. After the GPU finishes, mapAsync resolves; we read durations
+//      and record them.
+//
+// One readback buffer with an in-flight gate: if mapAsync hasn't resolved
+// from a previous frame, we skip the copy this frame (no contention, just
+// one frame of dropped sampling).
+import { profiler } from "./physics/profile";
+const MAX_PASSES_PER_FRAME = 64;
+export class GpuTimestamp {
+    constructor(device) {
+        this.enabled = false;
+        this.querySet = null;
+        this.resolveBuffer = null;
+        this.readbackBuffer = null;
+        this.nextSlot = 0;
+        this.frameLabels = [];
+        this.inFlight = false;
+        // Set inside endFrame() when a copy was queued this frame; consumed by
+        // afterSubmit() to kick mapAsync. mapAsync must run AFTER queue.submit —
+        // calling it before submit puts the buffer into "mapping pending" state,
+        // which makes the copy in the encoder illegal.
+        this.pendingLabels = null;
+        this.device = device;
+        this.supported = device.features.has("timestamp-query");
+    }
+    ensureCreated() {
+        if (this.querySet || !this.supported)
+            return;
+        const slots = MAX_PASSES_PER_FRAME * 2;
+        this.querySet = this.device.createQuerySet({ type: "timestamp", count: slots });
+        this.resolveBuffer = this.device.createBuffer({
+            label: "gpu-timestamp-resolve",
+            size: slots * 8,
+            usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+        });
+        this.readbackBuffer = this.device.createBuffer({
+            label: "gpu-timestamp-readback",
+            size: slots * 8,
+            usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+        });
+    }
+    // Called once at the top of each render() before any pass wrap.
+    beginFrame() {
+        if (!this.enabled || !this.supported)
+            return;
+        this.ensureCreated();
+        this.nextSlot = 0;
+        this.frameLabels = [];
+    }
+    // Wrap a render-pass descriptor with timestampWrites for `label`. If
+    // profiling is off / unsupported / out of slots, returns desc unchanged.
+    // The same label called multiple times (e.g. each bloom mip) is fine —
+    // the profiler accumulates by label.
+    wrap(desc, label) {
+        if (!this.enabled || !this.querySet)
+            return desc;
+        if (this.nextSlot + 2 > MAX_PASSES_PER_FRAME * 2)
+            return desc;
+        const begin = this.nextSlot;
+        const end = this.nextSlot + 1;
+        this.nextSlot += 2;
+        this.frameLabels.push(label);
+        return {
+            ...desc,
+            timestampWrites: {
+                querySet: this.querySet,
+                beginningOfPassWriteIndex: begin,
+                endOfPassWriteIndex: end,
+            },
+        };
+    }
+    // Call on the encoder after all passes, BEFORE encoder.finish(). Adds
+    // resolveQuerySet + copyBufferToBuffer commands. mapAsync is deferred to
+    // afterSubmit() — calling it before submit transitions the readback buffer
+    // into "mapping pending" state, which makes the queued copy illegal.
+    endFrame(encoder) {
+        if (!this.enabled || !this.querySet || this.frameLabels.length === 0)
+            return;
+        const count = this.frameLabels.length * 2;
+        encoder.resolveQuerySet(this.querySet, 0, count, this.resolveBuffer, 0);
+        if (this.inFlight)
+            return;
+        encoder.copyBufferToBuffer(this.resolveBuffer, 0, this.readbackBuffer, 0, count * 8);
+        this.pendingLabels = this.frameLabels.slice();
+    }
+    // Call AFTER device.queue.submit(). Kicks mapAsync if a copy was queued
+    // this frame; the .then() reads durations and unmaps.
+    afterSubmit() {
+        const labels = this.pendingLabels;
+        if (!labels)
+            return;
+        this.pendingLabels = null;
+        this.inFlight = true;
+        const readback = this.readbackBuffer;
+        void readback.mapAsync(GPUMapMode.READ).then(() => {
+            const arr = new BigInt64Array(readback.getMappedRange());
+            for (let i = 0; i < labels.length; i++) {
+                const start = arr[i * 2];
+                const end = arr[i * 2 + 1];
+                // Per spec, timestamps are nanoseconds.
+                const ms = Number(end - start) / 1e6;
+                if (ms >= 0 && ms < 1000)
+                    profiler.record("gpu." + labels[i], ms);
+            }
+            readback.unmap();
+            this.inFlight = false;
+        }, () => {
+            this.inFlight = false;
+        });
+    }
+}

package/dist/graph/slots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/graph/slots.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAiD5D,eAAO,MAAM,mBAAmB,gHAG/B,CAAA;AAuDD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,oBAAoB,EAAE,OAAO,GAC5B,MAAM,CAYR"}
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/graph/slots.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAiD5D,eAAO,MAAM,mBAAmB,gHAG/B,CAAA;AAgED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,oBAAoB,EAAE,OAAO,GAC5B,MAAM,CAYR"}

package/dist/graph/slots.js

@@ -67,14 +67,22 @@ function prelude(renderClass, alphaMode) {
         ? "  if (alpha < hashed_alpha_threshold(input.restPos)) { discard; }"
         : "  if (alpha < 0.001) { discard; }";
     const gate = renderClass === "eye" ? EYE_REAR_GATE : "";
+    // Double-sided shading, winding-independent: a normal pointing away from the
+    // camera means we're seeing the surface's other side — flip it. Only genuinely
+    // camera-averted fragments change (front surfaces have dot(n,v) > 0 and are
+    // untouched), unlike a front_facing test, which PMX's clockwise winding
+    // inverts. Fixes inner skirt linings (裙子白1-style flipped-normal copies)
+    // shading near-black through sheer outer layers. Eye is exempt: it FRONT-culls
+    // by design, so its visible fragments are back faces with intended normals.
+    const flip = renderClass === "eye" ? "" : "\n  n = select(-n, n, dot(n, v) >= 0.0);";
     return `@fragment fn fs(input: VertexOutput) -> FSOut {
   let tex_s = textureSample(diffuseTexture, diffuseSampler, input.uv);
   // MMD alpha semantics: material alpha × texture alpha.
   let alpha = material.alpha * tex_s.a;
 ${discard}
 
-  let n = safe_normal(input.normal);
-  let v = normalize(camera.viewPos - input.worldPos);
+  var n = safe_normal(input.normal);
+  let v = normalize(camera.viewPos - input.worldPos);${flip}
 ${gate}
   let l = -light.lights[0].direction.xyz;
   let sun = light.lights[0].color.xyz * light.lights[0].color.w;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_VIEW_TRANSFORM, type EngineStats, type EngineOptions, type BloomOptions, type ViewTransformOptions, type LoadModelFromFilesOptions, type MaterialPreset, type MaterialPresetMap, type ModelTransform, type GizmoDragEvent, type GizmoDragCallback, type GizmoDragKind, } from "./engine";
+export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_VIEW_TRANSFORM, type EngineStats, type EngineOptions, type BloomOptions, type ViewTransformOptions, type LoadModelFromFilesOptions, type MaterialPreset, type MaterialPresetMap, type ModelTransform, type GizmoDragEvent, type GizmoDragCallback, type GizmoDragKind, type BackgroundEffectParamValue, type BackgroundEffectResult, } from "./engine";
 export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload";
 export { compileGraph, validateGraph, assignStyleSlots, type CompileOptions, type CompileResult, type StyleSlot, } from "./graph/compile";
 export type { ShaderGraph, GraphNode, GraphLink, ExposedParam, SocketValue, Diagnostic, } from "./graph/schema";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACvG,OAAO,EACL,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7G,YAAY,EACV,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AACzC,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACvG,OAAO,EACL,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7G,YAAY,EACV,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AACzC,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA"}

package/dist/physics/profile.d.ts

@@ -0,0 +1,18 @@
+declare class PhysicsProfiler {
+    enabled: boolean;
+    private sums;
+    private counts;
+    begin(): number;
+    end(label: string, t0: number): void;
+    record(label: string, ms: number): void;
+    snapshot(): Record<string, {
+        avgMs: number;
+        calls: number;
+        totalMs: number;
+    }>;
+    reset(): void;
+}
+export declare const profiler: PhysicsProfiler;
+export type ProfileSnapshot = ReturnType<PhysicsProfiler["snapshot"]>;
+export {};
+//# sourceMappingURL=profile.d.ts.map

package/dist/physics/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/physics/profile.ts"],"names":[],"mappings":"AAIA,cAAM,eAAe;IACnB,OAAO,UAAQ;IACf,OAAO,CAAC,IAAI,CAA8C;IAC1D,OAAO,CAAC,MAAM,CAA8C;IAE5D,KAAK,IAAI,MAAM;IAIf,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IASpC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAQvC,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAU7E,KAAK,IAAI,IAAI;CAId;AAED,eAAO,MAAM,QAAQ,iBAAwB,CAAA;AAC7C,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAA"}

package/dist/physics/profile.js

@@ -0,0 +1,44 @@
+// Per-phase wall-clock accumulator. Off by default — when `enabled` is false,
+// begin()/end() short-circuit so production has zero overhead. Toggle via
+// `RezePhysics.setProfileEnabled(true)` and read with `getProfile()`.
+class PhysicsProfiler {
+    constructor() {
+        this.enabled = false;
+        this.sums = Object.create(null);
+        this.counts = Object.create(null);
+    }
+    begin() {
+        return this.enabled ? performance.now() : 0;
+    }
+    end(label, t0) {
+        if (!this.enabled)
+            return;
+        const dt = performance.now() - t0;
+        this.sums[label] = (this.sums[label] ?? 0) + dt;
+        this.counts[label] = (this.counts[label] ?? 0) + 1;
+    }
+    // Direct accumulator for durations not measured via begin()/end() — used by
+    // GPU timestamp readback, which arrives async after the frame has ended.
+    record(label, ms) {
+        if (!this.enabled)
+            return;
+        this.sums[label] = (this.sums[label] ?? 0) + ms;
+        this.counts[label] = (this.counts[label] ?? 0) + 1;
+    }
+    // Snapshot since last reset(). avgMs is per call; totalMs is the cumulative
+    // window cost — divide by elapsed wall time to get a "% of frame budget".
+    snapshot() {
+        const out = {};
+        for (const k in this.sums) {
+            const total = this.sums[k];
+            const calls = this.counts[k];
+            out[k] = { avgMs: calls > 0 ? total / calls : 0, calls, totalMs: total };
+        }
+        return out;
+    }
+    reset() {
+        this.sums = Object.create(null);
+        this.counts = Object.create(null);
+    }
+}
+export const profiler = new PhysicsProfiler();

package/dist/shaders/materials/common.d.ts

@@ -1,5 +1,5 @@
 export declare const COMMON_BINDINGS_WGSL = "\n\nstruct CameraUniforms {\n  view: mat4x4f,\n  projection: mat4x4f,\n  viewPos: vec3f,\n  _padding: f32,\n};\n\nstruct Light {\n  direction: vec4f,\n  color: vec4f,\n};\n\nstruct LightUniforms {\n  ambientColor: vec4f,\n  lights: array<Light, 4>,\n};\n\n// Per-material uniforms. Every material binds this layout even if it ignores fields;\n// the engine keeps one bind group layout across all material pipelines. The PMX\n// classic-material fields (ambient/specular/shininess) are carried for graph nodes that\n// want them; most graphs read only diffuseColor + alpha.\nstruct MaterialUniforms {\n  diffuseColor: vec3f,   // PMX diffuse rgb \u2014 the material_diffuse node reads this\n  alpha: f32,            // 0 \u2192 discard; <1 \u2192 transparent draw call\n  ambient: vec3f,        // PMX ambient rgb\n  shininess: f32,        // PMX specular power\n  specular: vec3f,       // PMX specular rgb\n  sphereMode: f32,       // 0 none \u00B7 1 multiply (sph) \u00B7 2 add (spa)\n  // Skeleton index of the \u982D (head) bone, or -1. Lets the eye shader gate\n  // the post-alpha-eye stencil by camera-vs-face hemisphere.\n  headBoneIndex: f32,\n  _pad0: f32,\n  _pad1: f32,\n  _pad2: f32,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4f,\n  @location(0) normal: vec3f,\n  @location(1) uv: vec2f,\n  @location(2) worldPos: vec3f,\n  // Bind-pose object-space position (the raw pre-skin vertex attribute). Procedural\n  // textures (noise bump, sparkle, Generated-coord gradients) key off this instead of\n  // worldPos so the pattern rides with the surface \u2014 otherwise the mesh swims through a\n  // world-static noise field under any skinning deformation or root (\u30BB\u30F3\u30BF\u30FC) motion.\n  // At rest skinMats are identity so restPos == worldPos, which is why existing noise-\n  // scale constants stay valid without retuning.\n  @location(3) restPos: vec3f,\n};\n\nstruct LightVP { viewProj: mat4x4f, };\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> light: LightUniforms;\n@group(0) @binding(2) var diffuseSampler: sampler;\n@group(0) @binding(3) var shadowMap: texture_depth_2d;\n@group(0) @binding(4) var shadowSampler: sampler_comparison;\n@group(0) @binding(5) var<uniform> lightVP: LightVP;\n// binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).\n@group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;\n@group(2) @binding(0) var diffuseTexture: texture_2d<f32>;\n@group(2) @binding(1) var<uniform> material: MaterialUniforms;\n// Reserved for future sphere/toon graph nodes; graphs that don't read them get the\n// 1\u00D71 white fallback bound here.\n@group(2) @binding(2) var toonTexture: texture_2d<f32>;\n@group(2) @binding(3) var sphereTexture: texture_2d<f32>;\n\n// Four-bone blended normals can cancel to ~zero on physics-driven parts\n// (opposing bone rotations at 50/50 weights) \u2014 normalize(0) is 0/0 = NaN,\n// which poisons the whole shading stack and flashes through bloom. Fall\n// back to up for degenerate normals instead.\nfn safe_normal(nIn: vec3f) -> vec3f {\n  let l2 = dot(nIn, nIn);\n  if (l2 < 1e-12) { return vec3f(0.0, 1.0, 0.0); }\n  return nIn * inverseSqrt(l2);\n}\n\n";
-export declare const SAMPLE_SHADOW_WGSL = "\n\nfn sampleShadow(worldPos: vec3f, n: vec3f) -> f32 {\n  if (dot(n, -light.lights[0].direction.xyz) <= 0.0) { return 0.0; }\n  let biasedPos = worldPos + n * 0.08;\n  let lclip = lightVP.viewProj * vec4f(biasedPos, 1.0);\n  let ndc = lclip.xyz / max(lclip.w, 1e-6);\n  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);\n  let cmpZ = ndc.z - 0.001;\n  let ts = 1.0 / 2048.0;\n  let s00 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);\n  let s10 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);\n  let s20 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, -ts), cmpZ);\n  let s01 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);\n  let s11 = textureSampleCompareLevel(shadowMap, shadowSampler, suv, cmpZ);\n  let s21 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);\n  let s02 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);\n  let s12 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);\n  let s22 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts,  ts), cmpZ);\n  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);\n}\n\n";
+export declare const SAMPLE_SHADOW_WGSL = "\n\nfn sampleShadow(worldPos: vec3f, n: vec3f) -> f32 {\n  if (dot(n, -light.lights[0].direction.xyz) <= 0.0) { return 0.0; }\n  let biasedPos = worldPos + n * 0.08;\n  let lclip = lightVP.viewProj * vec4f(biasedPos, 1.0);\n  let ndc = lclip.xyz / max(lclip.w, 1e-6);\n  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);\n  let cmpZ = ndc.z - 0.001;\n  let ts = 1.0 / 4096.0;\n  let s00 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);\n  let s10 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);\n  let s20 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, -ts), cmpZ);\n  let s01 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);\n  let s11 = textureSampleCompareLevel(shadowMap, shadowSampler, suv, cmpZ);\n  let s21 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);\n  let s02 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);\n  let s12 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);\n  let s22 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts,  ts), cmpZ);\n  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);\n}\n\n";
 export declare const COMMON_VS_WGSL = "\n\n@vertex fn vs(\n  @location(0) position: vec3f,\n  @location(1) normal: vec3f,\n  @location(2) uv: vec2f,\n  @location(3) joints0: vec4<u32>,\n  @location(4) weights0: vec4<f32>\n) -> VertexOutput {\n  var output: VertexOutput;\n  let pos4 = vec4f(position, 1.0);\n  let weightSum = weights0.x + weights0.y + weights0.z + weights0.w;\n  let invWeightSum = select(1.0, 1.0 / weightSum, weightSum > 0.0001);\n  let nw = select(vec4f(1.0, 0.0, 0.0, 0.0), weights0 * invWeightSum, weightSum > 0.0001);\n  var skinnedPos = vec4f(0.0);\n  var skinnedNrm = vec3f(0.0);\n  for (var i = 0u; i < 4u; i++) {\n    let m = skinMats[joints0[i]];\n    let w = nw[i];\n    skinnedPos += (m * pos4) * w;\n    skinnedNrm += (mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz) * normal) * w;\n  }\n  output.position = camera.projection * camera.view * vec4f(skinnedPos.xyz, 1.0);\n  output.normal = skinnedNrm;\n  output.uv = uv;\n  output.worldPos = skinnedPos.xyz;\n  output.restPos = position;\n  return output;\n}\n\n";
 export declare const COMMON_FS_OUT_WGSL = "\n\nstruct FSOut {\n  @location(0) color: vec4f,\n  @location(1) mask: vec4f,\n};\n\n";
 export declare const COMMON_MATERIAL_PRELUDE_WGSL: string;

package/dist/shaders/materials/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,oBAAoB,8pGA+EhC,CAAC;AAOF,eAAO,MAAM,kBAAkB,4xCAsB9B,CAAC;AAQF,eAAO,MAAM,cAAc,s+BA8B1B,CAAC;AAsBF,eAAO,MAAM,kBAAkB,0FAO9B,CAAC;AAMF,eAAO,MAAM,4BAA4B,QACwC,CAAA"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,oBAAoB,8pGA+EhC,CAAC;AASF,eAAO,MAAM,kBAAkB,4xCAsB9B,CAAC;AAQF,eAAO,MAAM,cAAc,s+BA8B1B,CAAC;AAsBF,eAAO,MAAM,kBAAkB,0FAO9B,CAAC;AAMF,eAAO,MAAM,4BAA4B,QACwC,CAAA"}

package/dist/shaders/materials/common.js

@@ -18,148 +18,150 @@
 //   group(0): per-frame scene (camera, lights, shadow map, BRDF LUT via nodes.ts)
 //   group(1): per-model skinning
 //   group(2): per-material (diffuse texture + material uniforms)
-export const COMMON_BINDINGS_WGSL = /* wgsl */ `
-
-struct CameraUniforms {
-  view: mat4x4f,
-  projection: mat4x4f,
-  viewPos: vec3f,
-  _padding: f32,
-};
-
-struct Light {
-  direction: vec4f,
-  color: vec4f,
-};
-
-struct LightUniforms {
-  ambientColor: vec4f,
-  lights: array<Light, 4>,
-};
-
-// Per-material uniforms. Every material binds this layout even if it ignores fields;
-// the engine keeps one bind group layout across all material pipelines. The PMX
-// classic-material fields (ambient/specular/shininess) are carried for graph nodes that
-// want them; most graphs read only diffuseColor + alpha.
-struct MaterialUniforms {
-  diffuseColor: vec3f,   // PMX diffuse rgb — the material_diffuse node reads this
-  alpha: f32,            // 0 → discard; <1 → transparent draw call
-  ambient: vec3f,        // PMX ambient rgb
-  shininess: f32,        // PMX specular power
-  specular: vec3f,       // PMX specular rgb
-  sphereMode: f32,       // 0 none · 1 multiply (sph) · 2 add (spa)
-  // Skeleton index of the 頭 (head) bone, or -1. Lets the eye shader gate
-  // the post-alpha-eye stencil by camera-vs-face hemisphere.
-  headBoneIndex: f32,
-  _pad0: f32,
-  _pad1: f32,
-  _pad2: f32,
-};
-
-struct VertexOutput {
-  @builtin(position) position: vec4f,
-  @location(0) normal: vec3f,
-  @location(1) uv: vec2f,
-  @location(2) worldPos: vec3f,
-  // Bind-pose object-space position (the raw pre-skin vertex attribute). Procedural
-  // textures (noise bump, sparkle, Generated-coord gradients) key off this instead of
-  // worldPos so the pattern rides with the surface — otherwise the mesh swims through a
-  // world-static noise field under any skinning deformation or root (センター) motion.
-  // At rest skinMats are identity so restPos == worldPos, which is why existing noise-
-  // scale constants stay valid without retuning.
-  @location(3) restPos: vec3f,
-};
-
-struct LightVP { viewProj: mat4x4f, };
-
-@group(0) @binding(0) var<uniform> camera: CameraUniforms;
-@group(0) @binding(1) var<uniform> light: LightUniforms;
-@group(0) @binding(2) var diffuseSampler: sampler;
-@group(0) @binding(3) var shadowMap: texture_depth_2d;
-@group(0) @binding(4) var shadowSampler: sampler_comparison;
-@group(0) @binding(5) var<uniform> lightVP: LightVP;
-// binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).
-@group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
-@group(2) @binding(0) var diffuseTexture: texture_2d<f32>;
-@group(2) @binding(1) var<uniform> material: MaterialUniforms;
-// Reserved for future sphere/toon graph nodes; graphs that don't read them get the
-// 1×1 white fallback bound here.
-@group(2) @binding(2) var toonTexture: texture_2d<f32>;
-@group(2) @binding(3) var sphereTexture: texture_2d<f32>;
-
-// Four-bone blended normals can cancel to ~zero on physics-driven parts
-// (opposing bone rotations at 50/50 weights) — normalize(0) is 0/0 = NaN,
-// which poisons the whole shading stack and flashes through bloom. Fall
-// back to up for degenerate normals instead.
-fn safe_normal(nIn: vec3f) -> vec3f {
-  let l2 = dot(nIn, nIn);
-  if (l2 < 1e-12) { return vec3f(0.0, 1.0, 0.0); }
-  return nIn * inverseSqrt(l2);
-}
-
+export const COMMON_BINDINGS_WGSL = /* wgsl */ `
+
+struct CameraUniforms {
+  view: mat4x4f,
+  projection: mat4x4f,
+  viewPos: vec3f,
+  _padding: f32,
+};
+
+struct Light {
+  direction: vec4f,
+  color: vec4f,
+};
+
+struct LightUniforms {
+  ambientColor: vec4f,
+  lights: array<Light, 4>,
+};
+
+// Per-material uniforms. Every material binds this layout even if it ignores fields;
+// the engine keeps one bind group layout across all material pipelines. The PMX
+// classic-material fields (ambient/specular/shininess) are carried for graph nodes that
+// want them; most graphs read only diffuseColor + alpha.
+struct MaterialUniforms {
+  diffuseColor: vec3f,   // PMX diffuse rgb — the material_diffuse node reads this
+  alpha: f32,            // 0 → discard; <1 → transparent draw call
+  ambient: vec3f,        // PMX ambient rgb
+  shininess: f32,        // PMX specular power
+  specular: vec3f,       // PMX specular rgb
+  sphereMode: f32,       // 0 none · 1 multiply (sph) · 2 add (spa)
+  // Skeleton index of the 頭 (head) bone, or -1. Lets the eye shader gate
+  // the post-alpha-eye stencil by camera-vs-face hemisphere.
+  headBoneIndex: f32,
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,
+};
+
+struct VertexOutput {
+  @builtin(position) position: vec4f,
+  @location(0) normal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) worldPos: vec3f,
+  // Bind-pose object-space position (the raw pre-skin vertex attribute). Procedural
+  // textures (noise bump, sparkle, Generated-coord gradients) key off this instead of
+  // worldPos so the pattern rides with the surface — otherwise the mesh swims through a
+  // world-static noise field under any skinning deformation or root (センター) motion.
+  // At rest skinMats are identity so restPos == worldPos, which is why existing noise-
+  // scale constants stay valid without retuning.
+  @location(3) restPos: vec3f,
+};
+
+struct LightVP { viewProj: mat4x4f, };
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var<uniform> light: LightUniforms;
+@group(0) @binding(2) var diffuseSampler: sampler;
+@group(0) @binding(3) var shadowMap: texture_depth_2d;
+@group(0) @binding(4) var shadowSampler: sampler_comparison;
+@group(0) @binding(5) var<uniform> lightVP: LightVP;
+// binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).
+@group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
+@group(2) @binding(0) var diffuseTexture: texture_2d<f32>;
+@group(2) @binding(1) var<uniform> material: MaterialUniforms;
+// Reserved for future sphere/toon graph nodes; graphs that don't read them get the
+// 1×1 white fallback bound here.
+@group(2) @binding(2) var toonTexture: texture_2d<f32>;
+@group(2) @binding(3) var sphereTexture: texture_2d<f32>;
+
+// Four-bone blended normals can cancel to ~zero on physics-driven parts
+// (opposing bone rotations at 50/50 weights) — normalize(0) is 0/0 = NaN,
+// which poisons the whole shading stack and flashes through bloom. Fall
+// back to up for degenerate normals instead.
+fn safe_normal(nIn: vec3f) -> vec3f {
+  let l2 = dot(nIn, nIn);
+  if (l2 < 1e-12) { return vec3f(0.0, 1.0, 0.0); }
+  return nIn * inverseSqrt(l2);
+}
+
 `;
 // ─── Shadow sampler (3×3 PCF) ───────────────────────────────────────
-// 2048-map, normal-bias 0.08, depth-bias 0.001. Unrolled — Safari's Metal backend
-// doesn't unroll nested shadow loops reliably, and the early out on back-facing
-// fragments saves 9 texture taps per skipped pixel.
-export const SAMPLE_SHADOW_WGSL = /* wgsl */ `
-
-fn sampleShadow(worldPos: vec3f, n: vec3f) -> f32 {
-  if (dot(n, -light.lights[0].direction.xyz) <= 0.0) { return 0.0; }
-  let biasedPos = worldPos + n * 0.08;
-  let lclip = lightVP.viewProj * vec4f(biasedPos, 1.0);
-  let ndc = lclip.xyz / max(lclip.w, 1e-6);
-  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
-  let cmpZ = ndc.z - 0.001;
-  let ts = 1.0 / 2048.0;
-  let s00 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);
-  let s10 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);
-  let s20 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, -ts), cmpZ);
-  let s01 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);
-  let s11 = textureSampleCompareLevel(shadowMap, shadowSampler, suv, cmpZ);
-  let s21 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);
-  let s02 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);
-  let s12 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);
-  let s22 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts,  ts), cmpZ);
-  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
-}
-
+// 4096-map (MUST match Engine.SHADOW_MAP_SIZE), normal-bias 0.08, depth-bias
+// 0.001. Unrolled — Safari's Metal backend doesn't unroll nested shadow loops
+// reliably. The texel size was stale at 1/2048 after the map grew to 4096:
+// PCF taps landed TWO texels apart, quantizing self-shadow edges into
+// texel-sized gray/black squares that crawled with the animation.
+export const SAMPLE_SHADOW_WGSL = /* wgsl */ `
+
+fn sampleShadow(worldPos: vec3f, n: vec3f) -> f32 {
+  if (dot(n, -light.lights[0].direction.xyz) <= 0.0) { return 0.0; }
+  let biasedPos = worldPos + n * 0.08;
+  let lclip = lightVP.viewProj * vec4f(biasedPos, 1.0);
+  let ndc = lclip.xyz / max(lclip.w, 1e-6);
+  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  let cmpZ = ndc.z - 0.001;
+  let ts = 1.0 / 4096.0;
+  let s00 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);
+  let s10 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);
+  let s20 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, -ts), cmpZ);
+  let s01 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);
+  let s11 = textureSampleCompareLevel(shadowMap, shadowSampler, suv, cmpZ);
+  let s21 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);
+  let s02 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);
+  let s12 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);
+  let s22 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts,  ts), cmpZ);
+  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+}
+
 `;
 // ─── Skinning vertex shader ─────────────────────────────────────────
 // Four-bone linear blend skinning. Renormalizes weights when they don't sum to 1
 // (PMX models occasionally ship with unnormalized weights on extras like hair tips).
 // VS normalize on the outgoing normal is skipped — interpolation denormalizes it
 // anyway and every fragment shader does `normalize(input.normal)` as its first line.
-export const COMMON_VS_WGSL = /* wgsl */ `
-
-@vertex fn vs(
-  @location(0) position: vec3f,
-  @location(1) normal: vec3f,
-  @location(2) uv: vec2f,
-  @location(3) joints0: vec4<u32>,
-  @location(4) weights0: vec4<f32>
-) -> VertexOutput {
-  var output: VertexOutput;
-  let pos4 = vec4f(position, 1.0);
-  let weightSum = weights0.x + weights0.y + weights0.z + weights0.w;
-  let invWeightSum = select(1.0, 1.0 / weightSum, weightSum > 0.0001);
-  let nw = select(vec4f(1.0, 0.0, 0.0, 0.0), weights0 * invWeightSum, weightSum > 0.0001);
-  var skinnedPos = vec4f(0.0);
-  var skinnedNrm = vec3f(0.0);
-  for (var i = 0u; i < 4u; i++) {
-    let m = skinMats[joints0[i]];
-    let w = nw[i];
-    skinnedPos += (m * pos4) * w;
-    skinnedNrm += (mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz) * normal) * w;
-  }
-  output.position = camera.projection * camera.view * vec4f(skinnedPos.xyz, 1.0);
-  output.normal = skinnedNrm;
-  output.uv = uv;
-  output.worldPos = skinnedPos.xyz;
-  output.restPos = position;
-  return output;
-}
-
+export const COMMON_VS_WGSL = /* wgsl */ `
+
+@vertex fn vs(
+  @location(0) position: vec3f,
+  @location(1) normal: vec3f,
+  @location(2) uv: vec2f,
+  @location(3) joints0: vec4<u32>,
+  @location(4) weights0: vec4<f32>
+) -> VertexOutput {
+  var output: VertexOutput;
+  let pos4 = vec4f(position, 1.0);
+  let weightSum = weights0.x + weights0.y + weights0.z + weights0.w;
+  let invWeightSum = select(1.0, 1.0 / weightSum, weightSum > 0.0001);
+  let nw = select(vec4f(1.0, 0.0, 0.0, 0.0), weights0 * invWeightSum, weightSum > 0.0001);
+  var skinnedPos = vec4f(0.0);
+  var skinnedNrm = vec3f(0.0);
+  for (var i = 0u; i < 4u; i++) {
+    let m = skinMats[joints0[i]];
+    let w = nw[i];
+    skinnedPos += (m * pos4) * w;
+    skinnedNrm += (mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz) * normal) * w;
+  }
+  output.position = camera.projection * camera.view * vec4f(skinnedPos.xyz, 1.0);
+  output.normal = skinnedNrm;
+  output.uv = uv;
+  output.worldPos = skinnedPos.xyz;
+  output.restPos = position;
+  return output;
+}
+
 `;
 // ─── FS output struct ───────────────────────────────────────────────
 // Location 0: final radiance+alpha (blended into rg11b10ufloat; the HDR target
@@ -180,13 +182,13 @@ export const COMMON_VS_WGSL = /* wgsl */ `
 // src-alpha blending enabled:
 //   out.r = mask_r · src.a + dst.r · (1-src.a)   (bloom mask, weighted by alpha)
 //   out.g = 1.0    · src.a + dst.g · (1-src.a)   (canonical premultiplied alpha-over)
-export const COMMON_FS_OUT_WGSL = /* wgsl */ `
-
-struct FSOut {
-  @location(0) color: vec4f,
-  @location(1) mask: vec4f,
-};
-
+export const COMMON_FS_OUT_WGSL = /* wgsl */ `
+
+struct FSOut {
+  @location(0) color: vec4f,
+  @location(1) mask: vec4f,
+};
+
 `;
 // ─── Convenience: full shared prelude ───────────────────────────────
 // Material files compose this as `${NODES_WGSL}${COMMON_MATERIAL_PRELUDE_WGSL}` to

package/dist/shaders/passes/composite.d.ts

@@ -1,2 +1,24 @@
-export declare const COMPOSITE_SHADER_WGSL = "\n// Pipeline-override constant: the engine creates two composite pipelines, one\n// with APPLY_GAMMA=false (gamma=1 fast path) and one with APPLY_GAMMA=true.\n// The 'if (APPLY_GAMMA)' below is resolved at pipeline-compile time \u2014 the\n// dead branch is dropped by the shader compiler (no runtime branch, no pow\n// invocation on Safari's Metal backend in the common case).\noverride APPLY_GAMMA: bool = true;\n\n@group(0) @binding(0) var hdrTex: texture_2d<f32>;\n@group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)\n@group(0) @binding(2) var bloomSamp: sampler;\n@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 6>;\n// Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).\n// .g = accumulated canvas alpha (what hdr.a carried before the HDR format\n// became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then\n// re-premultiply the tonemapped color for output so the premultiplied canvas\n// alphaMode composites the WebGPU surface over the page background correctly.\n@group(0) @binding(4) var maskTex: texture_2d<f32>;\n// Filmic tone curve baked to a WIDTH\u00D71 r16float LUT (bakeFilmicLut on the CPU side).\n// Domain: log2(linear) mapped to [0,13]. Replaces the old array<f32,14> that was indexed\n// by a runtime u32 (a Metal-backend smell \u2014 dynamic local-array indexing lowers to a\n// per-invocation copy/switch) and interpolated piecewise-linearly (C0, so segment slope\n// discontinuities showed as Mach bands in smooth skin/shadow gradients). The LUT is a\n// monotone-cubic (Fritsch\u2013Carlson) fit through the same 14 anchors \u2014 same values, C1\n// continuity kills the banding \u2014 sampled with hardware linear filtering.\n@group(0) @binding(5) var filmicLut: texture_2d<f32>;\n// viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)\n// viewU[2] = (background.rgb, mode) \u2014 display-space sRGB, composited UNDER the\n//            scene post-tonemap. mode: 0 transparent (DOM shows), 1 solid color,\n//            2 = 360 equirect skybox sampled by view ray.\n// viewU[3] = (camera right, tanHalfFov\u00B7aspect); viewU[4] = (camera up, tanHalfFov);\n// viewU[5] = (camera forward, _) \u2014 refreshed per frame while the skybox is active.\n// invGamma = 1/gamma precomputed on CPU \u2014 avoids a per-pixel divide.\n@group(0) @binding(6) var bgEquirect: texture_2d<f32>;\n\n// Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).\nconst FILMIC_LUT_W: f32 = 256.0;\n\nfn filmic(x: f32) -> f32 {\n  // Reference checkpoints (Blender 3.6 Filmic MHC, sobotka/filmic-blender\n  // look_medium-high-contrast.spi1d): linear 0.18 \u2192 ~0.395, linear 1.0 \u2192 ~0.83.\n  // NOTE: version-pinned to Blender 3.6 \u2014 4.x defaults to AgX, not Filmic.\n  let t = clamp(log2(max(x, 1e-10)) + 10.0, 0.0, 13.0);\n  // Map t\u2208[0,13] to the texel-center of baked sample j = t\u00B7(W-1)/13.\n  let u = (t * (FILMIC_LUT_W - 1.0) / 13.0 + 0.5) / FILMIC_LUT_W;\n  // textureSampleLevel (explicit LOD, no derivatives) is legal in non-uniform flow.\n  return textureSampleLevel(filmicLut, bloomSamp, vec2f(u, 0.5), 0.0).r;\n}\n\n@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {\n  let x = f32((vi & 1u) << 2u) - 1.0;\n  let y = f32((vi & 2u) << 1u) - 1.0;\n  return vec4f(x, y, 0.0, 1.0);\n}\n\n@fragment fn fs(@builtin(position) fragCoord: vec4f) -> @location(0) vec4f {\n  let coord = vec2<i32>(fragCoord.xy);\n  let hdr = textureLoad(hdrTex, coord, 0);\n  let alpha = textureLoad(maskTex, coord, 0).g;\n  let a = max(alpha, 1e-6);\n  let straight = hdr.rgb / a;\n  let fullSz = vec2f(textureDimensions(hdrTex));\n  // Bloom is at half-res (pyramid mip 0). Sampler interpolates back to full-res UVs.\n  // fragCoord.xy is already at pixel center (e.g. 0.5, 0.5 for first pixel).\n  let bloomUv = fragCoord.xy / max(fullSz, vec2f(1.0));\n  let tint = viewU[1].xyz;\n  let intensity = viewU[1].w;\n  let bloom = textureSampleLevel(bloomTex, bloomSamp, bloomUv, 0.0).rgb * tint * intensity;\n  let combined = straight + bloom;\n  let exposed = combined * exp2(viewU[0].x);\n  let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));\n  var disp = max(tm, vec3f(0.0));\n  if (APPLY_GAMMA) {\n    disp = pow(disp, vec3f(viewU[0].y));\n  }\n  // Composite over the background in display space (premultiplied out).\n  let bg = viewU[2];\n  var bgRgb = bg.rgb;\n  var bgA = select(0.0, 1.0, bg.w > 0.5);\n  if (bg.w > 1.5) {\n    // 360 equirect: rebuild this pixel's world-space view ray from the camera\n    // basis, then latitude/longitude-map into the panorama. The dome sits at\n    // infinity (no parallax) \u2014 PhotoDome-style, display-only.\n    let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.y / fullSz.y * 2.0);\n    let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);\n    // LH world (+Z forward): longitude = atan2(x, z), Babylon-PhotoDome convention.\n    let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2\u03C0)\n    let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/\u03C0\n    bgRgb = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;\n  }\n  return vec4f(disp * alpha + bgRgb * bgA * (1.0 - alpha), alpha + bgA * (1.0 - alpha));\n}\n";
+/** What a user background effect must define, documented once:
+ *
+ *    fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+ *
+ *  - `ray`  — normalized world-space view direction of this pixel (left-handed,
+ *             +Z forward; identical to what the 360 skybox samples by).
+ *  - `uv`   — 0..1 across the canvas, origin bottom-left (shadertoy-style).
+ *  - `time` — seconds since the effect was applied.
+ *  - `bgResolution()` — canvas size in pixels, for aspect correction.
+ *  - declared params arrive as `params.<name>` (f32 or vec3f).
+ *  Return display-space sRGB + alpha, 0..1. The effect is a LAYER: it is
+ *  over-composited onto the base background (solid color / 360 equirect /
+ *  transparent) and sits behind the scene — alpha 0 lets the base show
+ *  through, so e.g. a starfield returns stars with a transparent sky. */
+export type CompositeEffectSource = {
+    /** User WGSL defining `background(...)` (plus any helpers it wants). */
+    wgsl: string;
+    /** Codegen'd `struct BgParams {...}` + binding decl; empty when no params. */
+    paramsDecl: string;
+};
+export declare function buildCompositeShader(effect?: CompositeEffectSource | null): string;
+/** Kept for compatibility with existing imports (the base, no-effect shader). */
+export declare const COMPOSITE_SHADER_WGSL: string;
 //# sourceMappingURL=composite.d.ts.map