reze-engine 0.24.1 → 0.25.1

package/src/graph/slots.ts

@@ -76,14 +76,23 @@ function prelude(renderClass: RenderClass, alphaMode: AlphaMode): string {
       ? "  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/src/index.ts

@@ -13,6 +13,8 @@ export {
   type GizmoDragEvent,
   type GizmoDragCallback,
   type GizmoDragKind,
+  type BackgroundEffectParamValue,
+  type BackgroundEffectResult,
 } from "./engine"
 export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload"
 export {

package/src/shaders/materials/common.ts

@@ -1,205 +1,207 @@
-// Shared WGSL blocks concatenated by every material shader.
-// Splits the boilerplate (uniform structs, bind group layout, skinning VS, PCF shadow)
-// away from the per-material fragment code so each material file only contains what
-// makes it visually distinct.
-//
-// Concat order in every material:
-//   NODES_WGSL              (nodes.ts — math/noise/BSDF helpers)
-//   COMMON_BINDINGS_WGSL    (uniform structs + @group/@binding declarations)
-//   SAMPLE_SHADOW_WGSL      (3×3 PCF shadow sampler; reads bindings above)
-//   COMMON_VS_WGSL          (skinning vertex shader; reads bindings above)
-//   <material's own constants + @fragment fn fs>
-//
-// WGSL is a whole-module compile — declaration order at module scope doesn't matter,
-// but the readable order is: types → bindings → helpers → entry points.
-
-// ─── Uniform structs + bind group layout ────────────────────────────
-// Every material pipeline uses the same bind group layout, so the same bindings are
-// declared here once. Groups:
-//   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);
-}
-
-`;
-
-// ─── 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);
-}
-
-`;
-
-// ─── 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;
-}
-
-`;
-
-// ─── FS output struct ───────────────────────────────────────────────
-// Location 0: final radiance+alpha (blended into rg11b10ufloat; the HDR target
-// has no alpha channel, but the blend equation still uses the .a you write here
-// as the src-alpha factor that premultiplies rgb into the HDR target).
-// Location 1: auxiliary rg8unorm carrying
-//   .r = bloom mask (1 = contributes to bloom, 0 = skip — e.g. ground).
-//   .g = accumulated canvas alpha — the channel that used to live in hdr.a
-//        before the switch to rg11b10ufloat. Sampled by composite to
-//        un-premultiply color for tonemap and to set the final drawable alpha
-//        (needed for the `premultiplied` canvas alphaMode that blends the
-//        WebGPU surface over the page background).
-// FS output at location 1 must be vec4f — the blend state references src.a, and
-// WebGPU requires the fragment output to provide an alpha component even though
-// the rg8unorm target only stores .r and .g (extra components are discarded).
-// Materials write mask = vec4f(1.0, 1.0, 0.0, color.a); ground writes
-// vec4f(0.0, 1.0, 0.0, edgeFade). With src.a coming from the 4th component and
-// 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,
-};
-
-`;
-
-// ─── Convenience: full shared prelude ───────────────────────────────
-// Material files compose this as `${NODES_WGSL}${COMMON_MATERIAL_PRELUDE_WGSL}` to
-// pull in everything structural. Each material then adds its own constants + fs().
-
-export const COMMON_MATERIAL_PRELUDE_WGSL =
-  COMMON_BINDINGS_WGSL + SAMPLE_SHADOW_WGSL + COMMON_VS_WGSL + COMMON_FS_OUT_WGSL
+// Shared WGSL blocks concatenated by every material shader.
+// Splits the boilerplate (uniform structs, bind group layout, skinning VS, PCF shadow)
+// away from the per-material fragment code so each material file only contains what
+// makes it visually distinct.
+//
+// Concat order in every material:
+//   NODES_WGSL              (nodes.ts — math/noise/BSDF helpers)
+//   COMMON_BINDINGS_WGSL    (uniform structs + @group/@binding declarations)
+//   SAMPLE_SHADOW_WGSL      (3×3 PCF shadow sampler; reads bindings above)
+//   COMMON_VS_WGSL          (skinning vertex shader; reads bindings above)
+//   <material's own constants + @fragment fn fs>
+//
+// WGSL is a whole-module compile — declaration order at module scope doesn't matter,
+// but the readable order is: types → bindings → helpers → entry points.
+
+// ─── Uniform structs + bind group layout ────────────────────────────
+// Every material pipeline uses the same bind group layout, so the same bindings are
+// declared here once. Groups:
+//   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);
+}
+
+`;
+
+// ─── Shadow sampler (3×3 PCF) ───────────────────────────────────────
+// 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;
+}
+
+`;
+
+// ─── FS output struct ───────────────────────────────────────────────
+// Location 0: final radiance+alpha (blended into rg11b10ufloat; the HDR target
+// has no alpha channel, but the blend equation still uses the .a you write here
+// as the src-alpha factor that premultiplies rgb into the HDR target).
+// Location 1: auxiliary rg8unorm carrying
+//   .r = bloom mask (1 = contributes to bloom, 0 = skip — e.g. ground).
+//   .g = accumulated canvas alpha — the channel that used to live in hdr.a
+//        before the switch to rg11b10ufloat. Sampled by composite to
+//        un-premultiply color for tonemap and to set the final drawable alpha
+//        (needed for the `premultiplied` canvas alphaMode that blends the
+//        WebGPU surface over the page background).
+// FS output at location 1 must be vec4f — the blend state references src.a, and
+// WebGPU requires the fragment output to provide an alpha component even though
+// the rg8unorm target only stores .r and .g (extra components are discarded).
+// Materials write mask = vec4f(1.0, 1.0, 0.0, color.a); ground writes
+// vec4f(0.0, 1.0, 0.0, edgeFade). With src.a coming from the 4th component and
+// 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,
+};
+
+`;
+
+// ─── Convenience: full shared prelude ───────────────────────────────
+// Material files compose this as `${NODES_WGSL}${COMMON_MATERIAL_PRELUDE_WGSL}` to
+// pull in everything structural. Each material then adds its own constants + fs().
+
+export const COMMON_MATERIAL_PRELUDE_WGSL =
+  COMMON_BINDINGS_WGSL + SAMPLE_SHADOW_WGSL + COMMON_VS_WGSL + COMMON_FS_OUT_WGSL

package/src/shaders/passes/composite.ts

@@ -1,7 +1,34 @@
 // Composite: HDR scene + bloom pyramid → Filmic tone map → gamma → swapchain.
 // Bloom tint/intensity applied at combine (EEVEE treats them as combine-stage params, not prefilter).
+//
+// The shader is a TEMPLATE: buildCompositeShader() emits either the base pass or
+// a variant with a user background effect injected (setBackgroundEffect). The
+// effect is background mode 3, a sibling of the 360 equirect (mode 2) — it reuses
+// the same per-pixel view-ray reconstruction and composites in display space
+// under the scene, so it never affects lighting, bloom, or tonemapping.
 
-export const COMPOSITE_SHADER_WGSL = /* wgsl */ `
+/** 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
+}
+
+const COMPOSITE_HEAD = /* wgsl */ `
 // Pipeline-override constant: the engine creates two composite pipelines, one
 // with APPLY_GAMMA=false (gamma=1 fast path) and one with APPLY_GAMMA=true.
 // The 'if (APPLY_GAMMA)' below is resolved at pipeline-compile time — the
@@ -12,7 +39,7 @@ override APPLY_GAMMA: bool = true;
 @group(0) @binding(0) var hdrTex: texture_2d<f32>;
 @group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)
 @group(0) @binding(2) var bloomSamp: sampler;
-@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 6>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 7>;
 // Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).
 // .g = accumulated canvas alpha (what hdr.a carried before the HDR format
 // became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then
@@ -29,10 +56,12 @@ override APPLY_GAMMA: bool = true;
 @group(0) @binding(5) var filmicLut: texture_2d<f32>;
 // viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)
 // viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
-//            scene post-tonemap. mode: 0 transparent (DOM shows), 1 solid color,
-//            2 = 360 equirect skybox sampled by view ray.
+//            scene post-tonemap. BASE-layer mode: 0 transparent (DOM shows),
+//            1 solid color, 2 = 360 equirect skybox sampled by view ray. A user
+//            WGSL effect is a separate LAYER over the base (viewU[6].y flag).
 // viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
-// viewU[5] = (camera forward, _) — refreshed per frame while the skybox is active.
+// viewU[5] = (camera forward, _) — refreshed per frame while skybox/effect active.
+// viewU[6] = (time seconds, effect on/off, canvas width, canvas height).
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
 @group(0) @binding(6) var bgEquirect: texture_2d<f32>;
 
@@ -50,6 +79,11 @@ fn filmic(x: f32) -> f32 {
   return textureSampleLevel(filmicLut, bloomSamp, vec2f(u, 0.5), 0.0).r;
 }
 
+/** Canvas size in pixels — for user background effects (aspect correction). */
+fn bgResolution() -> vec2f { return viewU[6].zw; }
+`
+
+const COMPOSITE_BODY = /* wgsl */ `
 @vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
   let x = f32((vi & 1u) << 2u) - 1.0;
   let y = f32((vi & 2u) << 1u) - 1.0;
@@ -76,21 +110,60 @@ fn filmic(x: f32) -> f32 {
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }
-  // Composite over the background in display space (premultiplied out).
+  // Composite over the background in display space (premultiplied out). The
+  // background is TWO layers: a base (transparent / solid color / 360 equirect)
+  // and an optional user WGSL effect over-composited onto it.
   let bg = viewU[2];
-  var bgRgb = bg.rgb;
   var bgA = select(0.0, 1.0, bg.w > 0.5);
-  if (bg.w > 1.5) {
-    // 360 equirect: rebuild this pixel's world-space view ray from the camera
-    // basis, then latitude/longitude-map into the panorama. The dome sits at
-    // infinity (no parallax) — PhotoDome-style, display-only.
+  var bgPm = bg.rgb * bgA;  // premultiplied accumulator
+  let fxOn = viewU[6].y > 0.5;
+  if (bg.w > 1.5 || fxOn) {
+    // The equirect and any effect both need this pixel's world-space view ray,
+    // rebuilt from the camera basis. The dome sits at infinity (no parallax) —
+    // PhotoDome-style, display-only.
     let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.y / fullSz.y * 2.0);
     let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);
-    // LH world (+Z forward): longitude = atan2(x, z), Babylon-PhotoDome convention.
-    let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2π)
-    let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/π
-    bgRgb = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;
+    if (bg.w > 1.5) {
+      // LH world (+Z forward): longitude = atan2(x, z), Babylon-PhotoDome convention.
+      let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2π)
+      let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/π
+      bgPm = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;
+    }
+    BG_EFFECT_CALL
   }
-  return vec4f(disp * alpha + bgRgb * bgA * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
+  return vec4f(disp * alpha + bgPm * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
 }
 `
+
+// Base variant: no effect installed, the flag is never set — the ray block only
+// runs for the equirect, and there is nothing to add. (`dir` may go unused when
+// this compiles with mode<2 shaders; WGSL is fine with an unused let.)
+const NO_EFFECT_CALL = `_ = dir;`
+
+// uv flipped to bottom-left origin (shadertoy convention); clamped so a stray
+// effect can't push negatives/NaN into the premultiplied composite. Standard
+// OVER onto the base layer.
+const EFFECT_CALL = /* wgsl */ `
+    if (fxOn) {
+      let bgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
+      let fx = clamp(background(dir, bgUv, viewU[6].x), vec4f(0.0), vec4f(1.0));
+      bgPm = fx.rgb * fx.a + bgPm * (1.0 - fx.a);
+      bgA = fx.a + bgA * (1.0 - fx.a);
+    }
+`
+
+export function buildCompositeShader(effect?: CompositeEffectSource | null): string {
+  if (!effect) return COMPOSITE_HEAD + COMPOSITE_BODY.replace("BG_EFFECT_CALL", NO_EFFECT_CALL)
+  return (
+    COMPOSITE_HEAD +
+    "\n// ── user background effect (setBackgroundEffect) ──\n" +
+    effect.paramsDecl +
+    "\n" +
+    effect.wgsl +
+    "\n" +
+    COMPOSITE_BODY.replace("BG_EFFECT_CALL", EFFECT_CALL.trim())
+  )
+}
+
+/** Kept for compatibility with existing imports (the base, no-effect shader). */
+export const COMPOSITE_SHADER_WGSL = buildCompositeShader(null)