reze-engine 0.22.1 → 0.23.1

package/dist/shaders/passes/physics-debug.d.ts

@@ -0,0 +1,2 @@
+export declare const PHYSICS_DEBUG_SHADER_WGSL = "\nstruct CameraUniforms {\n  view: mat4x4f,\n  projection: mat4x4f,\n  viewPos: vec3f,\n  _pad: f32,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\noverride SHAPE_KIND: u32 = 0u;\noverride SOLID_ALPHA: f32 = 1.0;\n\nstruct VsIn {\n  @location(0) unit: vec4f,       // xyz = unit pos; w = capsule axial anchor\n  @location(1) modelCol0: vec4f,\n  @location(2) modelCol1: vec4f,\n  @location(3) modelCol2: vec4f,\n  @location(4) modelCol3: vec4f,\n  @location(5) size: vec4f,       // xyz = size; w unused\n  @location(6) color: vec4f,\n};\n\nstruct VsOut {\n  @builtin(position) pos: vec4f,\n  @location(0) color: vec4f,\n};\n\n@vertex\nfn vsMain(in: VsIn) -> VsOut {\n  let model = mat4x4f(in.modelCol0, in.modelCol1, in.modelCol2, in.modelCol3);\n  var local: vec3f;\n  if (SHAPE_KIND == 1u) {\n    local = in.unit.xyz * in.size.xyz;\n  } else if (SHAPE_KIND == 2u) {\n    // PMX capsule: size.x = radius, size.y = full cylinder height. Bullet 2.x's\n    // btCapsuleShape(radius, height) stores height/2 internally, so the actual\n    // collision cylinder spans \u00B1size.y/2 \u2014 halve here to match.\n    let r = in.size.x;\n    let halfH = in.size.y * 0.5;\n    local = vec3f(in.unit.x * r, in.unit.y * r + halfH * in.unit.w, in.unit.z * r);\n  } else {\n    local = in.unit.xyz * in.size.x;\n  }\n  let world = model * vec4f(local, 1.0);\n  var out: VsOut;\n  out.pos = camera.projection * camera.view * world;\n  out.color = in.color;\n  return out;\n}\n\n@fragment\nfn fsMain(in: VsOut) -> @location(0) vec4f {\n  return vec4f(in.color.rgb, in.color.a * SOLID_ALPHA);\n}\n";
+//# sourceMappingURL=physics-debug.d.ts.map

package/dist/shaders/passes/physics-debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-debug.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/physics-debug.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,yBAAyB,2kDAuDrC,CAAA"}

package/dist/shaders/passes/physics-debug.js

@@ -0,0 +1,69 @@
+// Wireframe + solid overlay for physics rigid bodies (sphere / box / capsule).
+// Rendered in its own pass after composite, straight to the swapchain — no
+// MSAA, no depth, no MRT — so it sits cleanly on top of the tonemapped scene
+// regardless of camera angle, model occlusion, or the composite alpha gate.
+//
+//   SHAPE_KIND   0 = sphere   → unit-sphere line/tri primitive scaled by size.x (radius)
+//                1 = box      → unit cube ±1 scaled by size.xyz (half-extents)
+//                2 = capsule  → unit cap+ring with per-vertex `axial` (-1/0/+1)
+//                               that lifts cap rings/arcs ±halfHeight along Y;
+//                               XZ scales by size.x (radius), Y by size.y/2.
+//   SOLID_ALPHA  fragment alpha multiplier. Wireframe pipelines leave this at
+//                1.0 for crisp edges; solid pipelines set it to ~0.2 so the fill
+//                stays gentle under stacked bodies.
+export const PHYSICS_DEBUG_SHADER_WGSL = /* wgsl */ `
+struct CameraUniforms {
+  view: mat4x4f,
+  projection: mat4x4f,
+  viewPos: vec3f,
+  _pad: f32,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+override SHAPE_KIND: u32 = 0u;
+override SOLID_ALPHA: f32 = 1.0;
+
+struct VsIn {
+  @location(0) unit: vec4f,       // xyz = unit pos; w = capsule axial anchor
+  @location(1) modelCol0: vec4f,
+  @location(2) modelCol1: vec4f,
+  @location(3) modelCol2: vec4f,
+  @location(4) modelCol3: vec4f,
+  @location(5) size: vec4f,       // xyz = size; w unused
+  @location(6) color: vec4f,
+};
+
+struct VsOut {
+  @builtin(position) pos: vec4f,
+  @location(0) color: vec4f,
+};
+
+@vertex
+fn vsMain(in: VsIn) -> VsOut {
+  let model = mat4x4f(in.modelCol0, in.modelCol1, in.modelCol2, in.modelCol3);
+  var local: vec3f;
+  if (SHAPE_KIND == 1u) {
+    local = in.unit.xyz * in.size.xyz;
+  } else if (SHAPE_KIND == 2u) {
+    // PMX capsule: size.x = radius, size.y = full cylinder height. Bullet 2.x's
+    // btCapsuleShape(radius, height) stores height/2 internally, so the actual
+    // collision cylinder spans ±size.y/2 — halve here to match.
+    let r = in.size.x;
+    let halfH = in.size.y * 0.5;
+    local = vec3f(in.unit.x * r, in.unit.y * r + halfH * in.unit.w, in.unit.z * r);
+  } else {
+    local = in.unit.xyz * in.size.x;
+  }
+  let world = model * vec4f(local, 1.0);
+  var out: VsOut;
+  out.pos = camera.projection * camera.view * world;
+  out.color = in.color;
+  return out;
+}
+
+@fragment
+fn fsMain(in: VsOut) -> @location(0) vec4f {
+  return vec4f(in.color.rgb, in.color.a * SOLID_ALPHA);
+}
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "reze-engine",
-    "version": "0.22.1",
+    "version": "0.23.1",
     "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
@@ -23,7 +23,7 @@
         "build": "tsc",
         "dev": "tsc --watch",
         "test": "node --import ./tests/register.mjs --test tests/*.test.mjs",
-        "prepublishOnly": "cp ../README.md ./README.md && npm run build"
+        "prepublishOnly": "node -e \"require('fs').copyFileSync('../README.md','README.md')\" && npm run build"
     },
     "keywords": [
         "webgpu",

package/src/engine.ts

@@ -301,6 +301,9 @@ export type EngineOptions = {
   world?: WorldOptions
   sun?: SunOptions
   camera?: CameraOptions
+  /** Canvas background (display-space sRGB 0–1), composited under the scene after
+   *  tonemapping. Omit/null = transparent canvas (see setBackgroundColor). */
+  background?: Vec3 | null
   /** Initial EEVEE-style bloom; tune at runtime with `setBloomOptions`. */
   bloom?: Partial<BloomOptions>
   /** View transform (exposure/gamma) applied in composite before/after Filmic. */
@@ -542,7 +545,15 @@ export class Engine {
   private compositeBindGroup!: GPUBindGroup
   private compositeUniformBuffer!: GPUBuffer
   // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-  private readonly compositeUniformData = new Float32Array(8)
+  private readonly compositeUniformData = new Float32Array(24)
+  /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
+  private backgroundColor: Vec3 | null = null
+  // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
+  private backdropEquirectTexture: GPUTexture | null = null
+  private backdropEquirectView: GPUTextureView | null = null
+  private fallbackEquirectTexture!: GPUTexture
+  private fallbackEquirectView!: GPUTextureView
+  private compositeBloomView: GPUTextureView | null = null
 
   // EEVEE-style bloom pyramid (mirrors Blender 3.6 effect_bloom_frag.glsl):
   //   blit (HDR → half-res, 4-tap Karis + soft threshold/knee)
@@ -674,6 +685,8 @@ export class Engine {
     this.onGizmoDrag = options?.onGizmoDrag
     this.bloomSettings = Engine.mergeBloomDefaults(options?.bloom)
     this.viewTransform = Engine.mergeViewTransformDefaults(options?.view)
+    const bg = options?.background
+    this.backgroundColor = bg ? new Vec3(bg.x, bg.y, bg.z) : null
   }
 
   /** Merge partial bloom with EEVEE defaults (same as constructor). */
@@ -745,9 +758,91 @@ export class Engine {
     u[5] = b.color.y
     u[6] = b.color.z
     u[7] = effIntensity
+    // Background composited UNDER the scene in display space (post-tonemap), so it
+    // matches a CSS color of the same value exactly. Mode (u[11]): 0 = transparent
+    // (DOM shows), 1 = solid color, 2 = 360 equirect (sampled by view ray; the
+    // camera basis at u[12..23] is refreshed per frame by updateCameraUniforms).
+    const bg = this.backgroundColor
+    u[8] = bg?.x ?? 0
+    u[9] = bg?.y ?? 0
+    u[10] = bg?.z ?? 0
+    u[11] = this.backdropEquirectView ? 2 : bg ? 1 : 0
     this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u)
   }
 
+  /**
+   * Set the canvas background color (display-space sRGB, 0–1 per channel — the
+   * same value a CSS background of that color shows, applied after tonemapping).
+   * Pass null for a transparent canvas (the page/DOM shows through — e.g. when a
+   * backdrop image layer sits behind the canvas). Applies on the next frame.
+   * A 360 backdrop (setBackdropEquirect) takes precedence while set.
+   */
+  setBackgroundColor(color: Vec3 | null): void {
+    this.backgroundColor = color ? new Vec3(color.x, color.y, color.z) : null
+    if (this.device && this.compositeUniformBuffer) this.writeCompositeViewUniforms()
+  }
+
+  private rebuildCompositeBindGroup(): void {
+    if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView) return
+    this.compositeBindGroup = this.device.createBindGroup({
+      label: "composite bind group",
+      layout: this.compositeBindGroupLayout,
+      entries: [
+        { binding: 0, resource: this.hdrResolveTexture.createView() },
+        { binding: 1, resource: this.compositeBloomView },
+        { binding: 2, resource: this.bloomSampler },
+        { binding: 3, resource: { buffer: this.compositeUniformBuffer } },
+        { binding: 4, resource: this.maskResolveView },
+        { binding: 5, resource: this.filmicLutView },
+        { binding: 6, resource: this.backdropEquirectView ?? this.fallbackEquirectView },
+      ],
+    })
+  }
+
+  /**
+   * Set a 360° backdrop from an equirectangular (2:1) image — a PhotoDome-style
+   * skybox at infinity, sampled per-pixel by view direction so it follows the
+   * camera. Display-only: composited in display space behind the scene, it never
+   * affects lighting, bloom, or tonemapping. Pass null to remove (the background
+   * color, or transparency, takes over again).
+   */
+  setBackdropEquirect(source: ImageBitmap | HTMLImageElement | HTMLCanvasElement | null): void {
+    this.backdropEquirectTexture?.destroy()
+    this.backdropEquirectTexture = null
+    this.backdropEquirectView = null
+    if (source && this.device) {
+      let width = Math.max(1, "naturalWidth" in source ? source.naturalWidth : source.width)
+      let height = Math.max(1, "naturalHeight" in source ? source.naturalHeight : source.height)
+      let upload: ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas = source
+      // Panoramas routinely exceed maxTextureDimension2D (e.g. 10000×5000 vs the
+      // default 8192) — quietly downscale to fit rather than surfacing an error.
+      const limit = this.device.limits.maxTextureDimension2D
+      if (width > limit || height > limit) {
+        const scale = Math.min(limit / width, limit / height)
+        const w = Math.max(1, Math.floor(width * scale))
+        const h = Math.max(1, Math.floor(height * scale))
+        const canvas = new OffscreenCanvas(w, h)
+        const cx = canvas.getContext("2d")!
+        cx.imageSmoothingQuality = "high"
+        cx.drawImage(source, 0, 0, w, h)
+        upload = canvas
+        width = w
+        height = h
+      }
+      const tex = this.device.createTexture({
+        label: "backdrop equirect",
+        size: [width, height],
+        format: "rgba8unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+      })
+      this.device.queue.copyExternalImageToTexture({ source: upload }, { texture: tex }, [width, height])
+      this.backdropEquirectTexture = tex
+      this.backdropEquirectView = tex.createView()
+    }
+    this.rebuildCompositeBindGroup()
+    if (this.device && this.compositeUniformBuffer) this.writeCompositeViewUniforms()
+  }
+
   /** Patch bloom; GPU uniforms update immediately if `init()` has run. */
   setBloomOptions(patch: Partial<BloomOptions>): void {
     const b = this.bloomSettings
@@ -1545,7 +1640,9 @@ export class Engine {
     // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
     this.compositeUniformBuffer = this.device.createBuffer({
       label: "composite view uniforms",
-      size: 32,
+      // 6 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
+      // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray.
+      size: 96,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
     this.compositeBindGroupLayout = this.device.createBindGroupLayout({
@@ -1560,8 +1657,17 @@ export class Engine {
         { binding: 4, visibility: GPUShaderStage.FRAGMENT, texture: {} },
         // Filmic tone LUT (r16float, filterable) — sampled with the binding-2 sampler.
         { binding: 5, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        // 360 backdrop equirect (PhotoDome-style skybox) — 1×1 fallback when unset.
+        { binding: 6, visibility: GPUShaderStage.FRAGMENT, texture: {} },
       ],
     })
+    this.fallbackEquirectTexture = this.device.createTexture({
+      label: "equirect fallback",
+      size: [1, 1],
+      format: "rgba8unorm",
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    })
+    this.fallbackEquirectView = this.fallbackEquirectTexture.createView()
 
     const compositeShader = this.device.createShaderModule({
       label: "composite shader",
@@ -1708,13 +1814,35 @@ export class Engine {
     window.addEventListener("mouseup", this.handleGizmoMouseUp)
   }
 
-  private handleResize() {
-    const displayWidth = this.canvas.clientWidth
-    const displayHeight = this.canvas.clientHeight
+  /** When set, render resolution is pinned to this size instead of tracking the
+   *  canvas's CSS size × devicePixelRatio (see setRenderSize). */
+  private fixedRenderSize: { width: number; height: number } | null = null
+
+  /**
+   * Pin the render resolution (canvas backing store + every render target) to an
+   * explicit size, decoupled from the canvas's CSS layout size — for offline
+   * rendering at arbitrary resolution (video export). On screen the browser scales
+   * the buffer to the layout box, so the canvas may display letterboxed/stretched
+   * while pinned; hosts typically cover it with an export overlay. Pass null to
+   * return to CSS-size × devicePixelRatio tracking. Applies immediately (targets
+   * rebuild before this returns), so the next render() is at the new size.
+   */
+  setRenderSize(width: number, height: number): void
+  setRenderSize(size: null): void
+  setRenderSize(widthOrNull: number | null, height?: number): void {
+    this.fixedRenderSize =
+      widthOrNull === null
+        ? null
+        : { width: Math.max(1, Math.floor(widthOrNull)), height: Math.max(1, Math.floor(height ?? 1)) }
+    this.resizePending = false
+    this.handleResize()
+  }
 
+  private handleResize() {
+    // Fixed override (offline/video rendering) wins; otherwise track CSS size × dpr.
     const dpr = window.devicePixelRatio || 1
-    const width = Math.floor(displayWidth * dpr)
-    const height = Math.floor(displayHeight * dpr)
+    const width = this.fixedRenderSize ? this.fixedRenderSize.width : Math.floor(this.canvas.clientWidth * dpr)
+    const height = this.fixedRenderSize ? this.fixedRenderSize.height : Math.floor(this.canvas.clientHeight * dpr)
 
     if (!this.multisampleTexture || this.canvas.width !== width || this.canvas.height !== height) {
       this.canvas.width = width
@@ -1927,19 +2055,8 @@ export class Engine {
           )
         }
         // Composite reads bloomUp mip 0 (full pyramid collapsed); fallback to bloomDown mip 0 if no upsample level.
-        const compositeBloomView = this.bloomMipCount > 1 ? this.bloomUpMipViews[0] : this.bloomDownMipViews[0]
-        this.compositeBindGroup = this.device.createBindGroup({
-          label: "composite bind group",
-          layout: this.compositeBindGroupLayout,
-          entries: [
-            { binding: 0, resource: this.hdrResolveTexture.createView() },
-            { binding: 1, resource: compositeBloomView },
-            { binding: 2, resource: this.bloomSampler },
-            { binding: 3, resource: { buffer: this.compositeUniformBuffer } },
-            { binding: 4, resource: this.maskResolveView },
-            { binding: 5, resource: this.filmicLutView },
-          ],
-        })
+        this.compositeBloomView = this.bloomMipCount > 1 ? this.bloomUpMipViews[0] : this.bloomDownMipViews[0]
+        this.rebuildCompositeBindGroup()
       }
 
       this.writeCompositeViewUniforms()
@@ -2335,6 +2452,8 @@ export class Engine {
     gridLineOpacity?: number
     gridLineColor?: Vec3
     noiseStrength?: number
+    /** Whole-ground opacity, 0–1 (multiplies the radial edge fade). Default 1. */
+    opacity?: number
   }): void {
     const opts = {
       width: 160,
@@ -2348,6 +2467,7 @@ export class Engine {
       gridLineOpacity: 0.4,
       gridLineColor: new Vec3(0.85, 0.85, 0.85),
       noiseStrength: 0.05,
+      opacity: 1.0,
       ...options,
     }
     this.createGroundGeometry(opts.width, opts.height)
@@ -2968,6 +3088,7 @@ export class Engine {
     gridLineOpacity: number
     gridLineColor: Vec3
     noiseStrength: number
+    opacity: number
   }) {
     const {
       diffuseColor,
@@ -2979,6 +3100,7 @@ export class Engine {
       gridLineOpacity,
       gridLineColor,
       noiseStrength,
+      opacity,
     } = opts
     // Shadow map is already created in setupPipelines()
     const gb = new Float32Array(16)
@@ -2993,7 +3115,7 @@ export class Engine {
     gb[8] = gridLineWidth
     gb[9] = gridLineOpacity
     gb[10] = noiseStrength
-    gb[11] = 0
+    gb[11] = opacity
     gb[12] = gridLineColor.x
     gb[13] = gridLineColor.y
     gb[14] = gridLineColor.z
@@ -3907,15 +4029,32 @@ export class Engine {
   render() {
     if (!this.multisampleTexture || !this.camera || !this.device) return
 
+    const currentTime = performance.now()
+    const deltaTime = this.lastFrameTime > 0 ? (currentTime - this.lastFrameTime) / 1000 : 0.016
+    this.lastFrameTime = currentTime
+    this.renderWithDelta(deltaTime)
+  }
+
+  /**
+   * Render one frame advancing every clock — animation, physics, tweens, and the
+   * camera VMD — by exactly `deltaSeconds`, independent of wall time. This is the
+   * offline-rendering primitive (video export): call it N times with 1/fps and the
+   * result is deterministic whether the machine renders faster or slower than
+   * realtime. Also resets the realtime clock so a later render() (returning to the
+   * live loop) doesn't see the export's wall-clock gap as one giant delta.
+   */
+  renderFrame(deltaSeconds: number) {
+    if (!this.multisampleTexture || !this.camera || !this.device) return
+    this.lastFrameTime = performance.now()
+    this.renderWithDelta(deltaSeconds)
+  }
+
+  private renderWithDelta(deltaTime: number) {
     if (this.resizePending) {
       this.resizePending = false
       this.handleResize()
     }
 
-    const currentTime = performance.now()
-    const deltaTime = this.lastFrameTime > 0 ? (currentTime - this.lastFrameTime) / 1000 : 0.016
-    this.lastFrameTime = currentTime
-
     const hasModels = this.modelInstances.size > 0
     if (hasModels) {
       this.updateInstances(deltaTime)
@@ -4538,6 +4677,31 @@ export class Engine {
     this.cameraMatrixData[33] = cameraPos.y
     this.cameraMatrixData[34] = cameraPos.z
     this.device.queue.writeBuffer(this.cameraUniformBuffer, 0, this.cameraMatrixData)
+
+    // 360 backdrop: the composite reconstructs each pixel's view ray from the
+    // camera basis — refresh it every frame the skybox is active. The view matrix
+    // 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) {
+      const v = viewMatrix.values
+      const u = this.compositeUniformData
+      const tanHalf = Math.tan((this.camera.fov ?? Math.PI / 4) / 2)
+      const aspect = this.canvas.width / Math.max(1, this.canvas.height)
+      u[12] = v[0]
+      u[13] = v[4]
+      u[14] = v[8]
+      u[15] = tanHalf * aspect
+      u[16] = v[1]
+      u[17] = v[5]
+      u[18] = v[9]
+      u[19] = tanHalf
+      u[20] = v[2]
+      u[21] = v[6]
+      u[22] = v[10]
+      u[23] = 0
+      this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u)
+    }
   }
 
   private updateSkinMatrices() {

package/src/shaders/passes/composite.ts

@@ -12,7 +12,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>, 2>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 6>;
 // 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
@@ -28,7 +28,13 @@ override APPLY_GAMMA: bool = true;
 // continuity kills the banding — sampled with hardware linear filtering.
 @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.
+// viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
+// viewU[5] = (camera forward, _) — refreshed per frame while the skybox is active.
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
+@group(0) @binding(6) var bgEquirect: texture_2d<f32>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
@@ -70,6 +76,21 @@ fn filmic(x: f32) -> f32 {
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }
-  return vec4f(disp * alpha, alpha);
+  // Composite over the background in display space (premultiplied out).
+  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.
+    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;
+  }
+  return vec4f(disp * alpha + bgRgb * bgA * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
 }
 `

package/src/shaders/passes/ground.ts

@@ -8,7 +8,7 @@ struct LightUniforms { ambientColor: vec4f, lights: array<Light, 4>, };
 struct GroundShadowMat {
   diffuseColor: vec3f, fadeStart: f32,
   fadeEnd: f32, shadowStrength: f32, pcfTexel: f32, gridSpacing: f32,
-  gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, _pad: f32,
+  gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, opacity: f32,
   gridLineColor: vec3f, _pad2: f32,
 };
 struct LightVP { viewProj: mat4x4f, };
@@ -86,13 +86,20 @@ struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
   var baseColor = material.diffuseColor * sun * (1.0 - dark * 0.65);
   baseColor *= noiseTint;
   let finalColor = mix(baseColor, material.gridLineColor, gridLine * material.gridLineOpacity * edgeFade);
+  // Whole-ground opacity fades the SURFACE (color, grid) but the shadow stays —
+  // as opacity drops, the received shadow becomes a translucent dark layer
+  // (Blender's Shadow Catcher), so models still feel grounded on a photo or
+  // 360 backdrop. At opacity 1 this reduces exactly to the plain surface.
+  let surfA = edgeFade * material.opacity;
+  let catchA = dark * 0.65 * edgeFade * (1.0 - material.opacity);
+  let outA = surfA + catchA;
   var out: FSOut;
-  out.color = vec4f(finalColor * edgeFade, edgeFade);
+  out.color = vec4f(finalColor * surfA, outA);
   // mask.r = 0: ground never contributes to bloom. mask.g = 1.0 with src.a =
-  // edgeFade turns the aux blend into alpha-over, so the drawable alpha fades
-  // from edgeFade at the center to 0 at the radial edge — letting the page
+  // outA turns the aux blend into alpha-over, so the drawable alpha goes
+  // from outA at the center to 0 at the radial edge — letting the page
   // background show through under the premultiplied canvas alphaMode.
-  out.mask = vec4f(0.0, 1.0, 0.0, edgeFade);
+  out.mask = vec4f(0.0, 1.0, 0.0, outA);
   return out;
 }
 `

package/dist/gpu-profile.d.ts

@@ -1,19 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,120 +0,0 @@
-// 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/physics/profile.d.ts

@@ -1,18 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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"}