@ifc-lite/renderer 3.2.0 → 4.2.0

package/dist/depth-reconstruct.d.ts

@@ -0,0 +1,43 @@
+/**
+ * View-space reconstruction from the scene depth buffer, for screen-space
+ * passes that have no normal or position target (ambient occlusion, #5384).
+ *
+ * The depth attachment holds reverse-Z device depth (1 at the near plane,
+ * cleared to 0), produced by `MathUtils.perspectiveReverseZ` (infinite far
+ * plane) or `MathUtils.orthographicReverseZ`. Both are handled by one
+ * formula over four projection-matrix entries rather than a mode switch, so
+ * a pass never has to know which camera mode drew the frame:
+ *
+ *   device depth d = (m10 * z + m14) / (m11 * z + m15)   (z = view-space z, < 0)
+ *   =>        z = (m14 - d * m15) / (d * m11 - m10)
+ *
+ * and the view-space x/y follow from NDC and the clip w (`m11 * z + m15`):
+ *
+ *   x = (ndcX * w - m12) / m0,  y = (ndcY * w - m13) / m5
+ *
+ * (`m8`/`m9` are zero in both projections.) `shaders/depth-reconstruct.wgsl.ts`
+ * is the WGSL twin of these functions; the unit tests round-trip real
+ * projection matrices through the TS side.
+ */
+import type { Mat4 } from './types.js';
+/** The projection entries the reconstruction needs, packed as two vec4s. */
+export interface DepthReconstructParams {
+    /** `[m10, m11, m14, m15]`: device depth to view-space z. */
+    depth: [number, number, number, number];
+    /** `[m0, m5, m12, m13]`: NDC x/y (with clip w) to view-space x/y. */
+    xy: [number, number, number, number];
+}
+/** Extract the reconstruction params from a (column-major) projection matrix. */
+export declare function depthReconstructParams(projection: Mat4): DepthReconstructParams;
+/** View-space z (negative in front of the camera) of a device depth value. */
+export declare function viewZFromDepth(depth: number, p: DepthReconstructParams): number;
+/** Clip-space w at view-space z: the view distance in perspective, 1 in ortho. */
+export declare function clipWFromViewZ(viewZ: number, p: DepthReconstructParams): number;
+/** View-space position of an NDC point at a device depth. */
+export declare function viewPositionFromDepth(ndcX: number, ndcY: number, depth: number, p: DepthReconstructParams): [number, number, number];
+/**
+ * Pixels per world unit at clip w = 1, for a drawing buffer `heightPx` tall.
+ * A world-space length `r` at clip w spans `r * scale / w` pixels.
+ */
+export declare function pixelsPerWorldUnit(projection: Mat4, heightPx: number): number;
+//# sourceMappingURL=depth-reconstruct.d.ts.map

package/dist/depth-reconstruct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth-reconstruct.d.ts","sourceRoot":"","sources":["../src/depth-reconstruct.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,qEAAqE;IACrE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,IAAI,GAAG,sBAAsB,CAM/E;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAG/E;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAE/E;AAED,6DAA6D;AAC7D,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,CAAC,EAAE,sBAAsB,GACxB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAK1B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7E"}

package/dist/depth-reconstruct.js

@@ -0,0 +1,35 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/** Extract the reconstruction params from a (column-major) projection matrix. */
+export function depthReconstructParams(projection) {
+    const m = projection.m;
+    return {
+        depth: [m[10], m[11], m[14], m[15]],
+        xy: [m[0], m[5], m[12], m[13]],
+    };
+}
+/** View-space z (negative in front of the camera) of a device depth value. */
+export function viewZFromDepth(depth, p) {
+    const [m10, m11, m14, m15] = p.depth;
+    return (m14 - depth * m15) / (depth * m11 - m10);
+}
+/** Clip-space w at view-space z: the view distance in perspective, 1 in ortho. */
+export function clipWFromViewZ(viewZ, p) {
+    return p.depth[1] * viewZ + p.depth[3];
+}
+/** View-space position of an NDC point at a device depth. */
+export function viewPositionFromDepth(ndcX, ndcY, depth, p) {
+    const z = viewZFromDepth(depth, p);
+    const w = clipWFromViewZ(z, p);
+    const [m0, m5, m12, m13] = p.xy;
+    return [(ndcX * w - m12) / m0, (ndcY * w - m13) / m5, z];
+}
+/**
+ * Pixels per world unit at clip w = 1, for a drawing buffer `heightPx` tall.
+ * A world-space length `r` at clip w spans `r * scale / w` pixels.
+ */
+export function pixelsPerWorldUnit(projection, heightPx) {
+    return 0.5 * heightPx * projection.m[5];
+}
+//# sourceMappingURL=depth-reconstruct.js.map

package/dist/depth-reconstruct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth-reconstruct.js","sourceRoot":"","sources":["../src/depth-reconstruct.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAkC/D,iFAAiF;AACjF,MAAM,UAAU,sBAAsB,CAAC,UAAgB;IACrD,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IACvB,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACnC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,CAAyB;IACrE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IACrC,OAAO,CAAC,GAAG,GAAG,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;AACnD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,CAAyB;IACrE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,IAAY,EACZ,KAAa,EACb,CAAyB;IAEzB,MAAM,CAAC,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAgB,EAAE,QAAgB;IACnE,OAAO,GAAG,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC"}

package/dist/device.js

@@ -202,7 +202,7 @@ export class WebGPUDevice {
             this.context.configure({
                 device: this.device,
                 format: this.format,
-                usage: GPUTextureUsage.RENDER_ATTACHMENT,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
                 alphaMode: 'premultiplied',
             });
             this.contextConfigured = true;

package/dist/device.js.map

@@ -1 +1 @@
-{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"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"}

package/dist/environment.d.ts

@@ -2,10 +2,14 @@
  * Lighting environment for the main shading pipelines and the procedural
  * sky pass.
  *
- * Every field is optional; the defaults reproduce the renderer's historical
- * hardcoded look exactly (sun at normalize(0.5, 1, 0.3), hemisphere ambient,
- * 0.85 exposure), so callers that never pass `RenderOptions.environment`
- * see no visual change.
+ * Every field is optional. The default rig is a one-sided sun from the side
+ * the default camera sees, a hemisphere ambient strong enough to keep faces
+ * turned away from it at roughly 40-50% of the key, a fill from the opposite
+ * side and 0.85 exposure (#5382). The geometry shader converts these
+ * intensities to linear irradiance (`IRRADIANCE_CALIBRATION` in
+ * `shaders/main.wgsl.ts`), so the default rig lights a sun-facing horizontal
+ * surface at unit irradiance (by luma; the near-neutral sky leaves each
+ * channel within about 1.5% of that).
  *
  * Directions are in viewer/world space (Y-up). `sunDirection` points TOWARD
  * the sun, matching the shader's `dot(N, sunDirection)` convention.
@@ -23,27 +27,34 @@ export interface LightingEnvironment {
     /** Unit vector toward the sun (Y-up viewer space). Normalized defensively. */
     sunDirection?: [number, number, number];
     sunColor?: Vec3Color;
-    /** Diffuse strength of the sun term (historic default 0.55). */
+    /** Diffuse strength of the one-sided sun term (default 0.4). */
     sunIntensity?: number;
-    /** Hemisphere-ambient sky colour (historic default [0.3, 0.35, 0.4]). */
+    /**
+     * Hemisphere-ambient sky colour (default [0.34, 0.35, 0.36]). Kept close to
+     * neutral: the ambient carries almost half of the key light, so a strongly
+     * blue sky would tint every sunlit white surface.
+     */
     skyColor?: Vec3Color;
-    /** Hemisphere-ambient ground colour (historic default [0.15, 0.1, 0.08]). */
+    /** Hemisphere-ambient ground colour (default [0.24, 0.2, 0.17], a warm bounce). */
     groundColor?: Vec3Color;
-    /** Hemisphere ambient strength (historic default 0.25). */
+    /**
+     * Hemisphere ambient strength (default 0.775). This is what lights faces
+     * turned away from the sun, so it sets how dark the shaded side and cast
+     * shadows read.
+     */
     ambientIntensity?: number;
-    /** Fixed fill-light strength (historic default 0.15). */
+    /** Strength of the fill bouncing in from the side opposite the sun (default 0.1). */
     fillIntensity?: number;
-    /** Rim-light strength (historic default 0.15). */
+    /** Rim-light strength, a fixed light from -Z (default 0.05). */
     rimIntensity?: number;
     /**
      * Sun terminator softness — the diffuse "wrap" that lifts the light/shadow
      * boundary off a hard `max(N·L, 0)` toward wrap-around lighting. 0 is a crisp
-     * terminator (hard shadows); larger values soften it (overcast look). Historic
-     * default 0.3 (the value the term was hardcoded to before it was exposed).
-     * Clamped to [0, 1] on resolve.
+     * terminator (hard shadows); larger values soften it (overcast look). Default
+     * 0.3. Clamped to [0, 1] on resolve.
      */
     sunSoftness?: number;
-    /** Pre-tonemap exposure multiplier (historic default 0.85). */
+    /** Exposure multiplier on the light, before highlight roll-off (default 0.85). */
     exposure?: number;
     /**
      * Draw the procedural sky background. When false (default) the frame
@@ -67,7 +78,7 @@ export type ResolvedEnvironment = Required<Omit<LightingEnvironment, 'sky'>> & {
  * night → twilight → golden hour → day.
  */
 export declare function deriveSkyGradient(sunElevation: number): SkyGradient;
-/** Fill in defaults; the result always renders identically to the legacy look when `env` is undefined/empty. */
+/** Fill in defaults; `env` undefined/empty resolves to the default rig. */
 export declare function resolveEnvironment(env?: LightingEnvironment): ResolvedEnvironment;
 /** Byte size of the packed environment UBO (must match the WGSL struct). */
 export declare const ENVIRONMENT_UNIFORM_SIZE = 80;

package/dist/environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,kCAAkC;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC5B;AAED,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC,GAAG;IAC7E,GAAG,EAAE,WAAW,CAAC;CAClB,CAAC;AAwDF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CAgDnE;AAED,gHAAgH;AAChH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAqBjF;AAED,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,mBAAmB,EACxB,GAAG,CAAC,EAAE,YAAY,GACjB,YAAY,CAuBd"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,kCAAkC;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,mFAAmF;IACnF,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC5B;AAED,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC,GAAG;IAC7E,GAAG,EAAE,WAAW,CAAC;CAClB,CAAC;AA8DF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CAqDnE;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAqBjF;AAED,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,mBAAmB,EACxB,GAAG,CAAC,EAAE,YAAY,GACjB,YAAY,CAuBd"}

package/dist/environment.js

@@ -1,10 +1,16 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
-/** Historic hardcoded sun direction, normalized: (0.5, 1, 0.3) / |…|. */
+/**
+ * Default sun direction, normalized: (-0.45, 1, 0.6) / |…|.
+ *
+ * The default camera looks from +X+Z, so it sees the +X and +Z faces. This
+ * sun lights +Z and leaves +X in shade, so the opening view has a lit side
+ * and a shaded side (#5382). The previous (0.5, 1, 0.3) lit both.
+ */
 const DEFAULT_SUN_DIR = (() => {
-    const len = Math.hypot(0.5, 1.0, 0.3);
-    return [0.5 / len, 1.0 / len, 0.3 / len];
+    const len = Math.hypot(-0.45, 1.0, 0.6);
+    return [-0.45 / len, 1.0 / len, 0.6 / len];
 })();
 /**
  * Unit sun direction, falling back to {@link DEFAULT_SUN_DIR} for any input
@@ -69,16 +75,21 @@ export function deriveSkyGradient(sunElevation) {
     };
     // Ground tones stay near-neutral grey: BIM cameras spend most of their
     // time looking DOWN, so the below-horizon colour fills the screen — a
-    // warm "earth" tone reads as a mud-brown background there.
+    // warm "earth" tone reads as a mud-brown background there. They are
+    // lifted (same channel ratios, higher magnitude — not blended toward the
+    // warm horizon hue) relative to the previous values so a downward view
+    // reads as a lighter neutral fill rather than a dreary mid-grey wall
+    // (#5583); the shader also widens the horizon→ground falloff so this is a
+    // gradient, not a hard cut.
     const golden = {
         zenith: [0.18, 0.32, 0.56],
         horizon: [0.95, 0.55, 0.28],
-        ground: [0.11, 0.105, 0.105],
+        ground: [0.176, 0.168, 0.168],
     };
     const day = {
         zenith: [0.18, 0.40, 0.78],
         horizon: [0.66, 0.78, 0.90],
-        ground: [0.14, 0.145, 0.15],
+        ground: [0.252, 0.261, 0.27],
     };
     // sin(altitude) stops: night below -0.21 (~-12°), twilight to ~0,
     // golden to ~0.17 (~10°), full day above ~0.35 (~20°).
@@ -103,19 +114,19 @@ export function deriveSkyGradient(sunElevation) {
     };
     return g;
 }
-/** Fill in defaults; the result always renders identically to the legacy look when `env` is undefined/empty. */
+/** Fill in defaults; `env` undefined/empty resolves to the default rig. */
 export function resolveEnvironment(env) {
     const sunDirection = normalized(env?.sunDirection ?? DEFAULT_SUN_DIR);
     const derived = deriveSkyGradient(sunDirection[1]);
     return {
         sunDirection,
         sunColor: env?.sunColor ?? [1, 1, 1],
-        sunIntensity: env?.sunIntensity ?? 0.55,
-        skyColor: env?.skyColor ?? [0.3, 0.35, 0.4],
-        groundColor: env?.groundColor ?? [0.15, 0.1, 0.08],
-        ambientIntensity: env?.ambientIntensity ?? 0.25,
-        fillIntensity: env?.fillIntensity ?? 0.15,
-        rimIntensity: env?.rimIntensity ?? 0.15,
+        sunIntensity: env?.sunIntensity ?? 0.4,
+        skyColor: env?.skyColor ?? [0.34, 0.35, 0.36],
+        groundColor: env?.groundColor ?? [0.24, 0.2, 0.17],
+        ambientIntensity: env?.ambientIntensity ?? 0.775,
+        fillIntensity: env?.fillIntensity ?? 0.1,
+        rimIntensity: env?.rimIntensity ?? 0.05,
         sunSoftness: clamp01(env?.sunSoftness ?? 0.3),
         exposure: env?.exposure ?? 0.85,
         skyEnabled: env?.skyEnabled ?? false,

package/dist/environment.js.map

@@ -1 +1 @@
-{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"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"}

package/dist/federation-registry.d.ts

@@ -12,6 +12,8 @@ export interface ModelRange {
     modelId: string;
     offset: number;
     maxExpressId: number;
+    reservedMaxExpressId: number;
+    publishedStart: number | null;
 }
 export interface GlobalIdLookup {
     modelId: string;
@@ -34,6 +36,19 @@ export declare class FederationRegistry {
      * @returns The offset to add to all expressIds for this model
      */
     registerModel(modelId: string, maxExpressId: number): number;
+    /** Reserve a fixed local-ID envelope before progressive publication. */
+    reserveModel(modelId: string, reservedMaxExpressId: number): number;
+    /** Publish the next contiguous owned local range inside a reservation. */
+    publishRange(modelId: string, start: number, end: number): void;
+    /** Publish derived/overlay IDs from the separately reserved headroom. */
+    publishOverlayRange(modelId: string, start: number, end: number): void;
+    /**
+     * Resolve an owned overlay range while it is still detached from its
+     * mutation transaction. This validates the exact range that will be
+     * publishable, but deliberately does not make it pickable or owned yet.
+     * Callers must publish it only after the backing records commit.
+     */
+    previewOverlayGlobalId(modelId: string, start: number, end: number, expressId: number): number;
     /**
      * Unregister a model (when removed from viewer)
      * Note: The offset space is NOT reclaimed to avoid invalidating any
@@ -88,6 +103,7 @@ export declare class FederationRegistry {
      * Clear all registrations (for full reset)
      */
     clear(): void;
+    private isPublished;
     /**
      * Binary search to find the range that could contain a globalId
      * Returns the range with the largest offset that is <= globalId

package/dist/federation-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"federation-registry.d.ts","sourceRoot":"","sources":["../src/federation-registry.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAsBD;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAyC5D;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAYtC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAQtD;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAwBrD;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKpD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIzC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IASxE;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAOrD;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAsB1B;AAID,eAAO,MAAM,kBAAkB,oBAA2B,CAAC"}
+{"version":3,"file":"federation-registry.d.ts","sourceRoot":"","sources":["../src/federation-registry.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAsBD;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAQ5D,wEAAwE;IACxE,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,MAAM;IAyCnE,0EAA0E;IAC1E,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAc/D,yEAAyE;IACzE,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAatE;;;;;OAKG;IACH,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAe9F;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAYtC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAWtD;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAwBrD;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKpD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIzC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAUxE;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAOrD;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,WAAW;IAOnB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAsB1B;AAID,eAAO,MAAM,kBAAkB,oBAA2B,CAAC"}

package/dist/federation-registry.js

@@ -36,12 +36,21 @@ export class FederationRegistry {
      * @returns The offset to add to all expressIds for this model
      */
     registerModel(modelId, maxExpressId) {
+        const existing = this.modelRanges.get(modelId);
+        if (existing)
+            return existing.offset;
+        const offset = this.reserveModel(modelId, maxExpressId);
+        this.publishRange(modelId, 0, maxExpressId);
+        return offset;
+    }
+    /** Reserve a fixed local-ID envelope before progressive publication. */
+    reserveModel(modelId, reservedMaxExpressId) {
         // Validate inputs
         if (!modelId || typeof modelId !== 'string') {
             throw new Error(`[FederationRegistry] Invalid modelId: ${modelId}`);
         }
-        if (typeof maxExpressId !== 'number' || !Number.isFinite(maxExpressId) || maxExpressId < 0) {
-            throw new Error(`[FederationRegistry] Invalid maxExpressId: ${maxExpressId} for model ${modelId}`);
+        if (typeof reservedMaxExpressId !== 'number' || !Number.isFinite(reservedMaxExpressId) || reservedMaxExpressId < 0) {
+            throw new Error(`[FederationRegistry] Invalid reservedMaxExpressId: ${reservedMaxExpressId} for model ${modelId}`);
         }
         // Check for duplicate registration
         if (this.modelRanges.has(modelId)) {
@@ -50,13 +59,13 @@ export class FederationRegistry {
             return existing.offset;
         }
         // Check for overflow
-        if (this.nextOffset + maxExpressId > MAX_SAFE_OFFSET) {
+        if (this.nextOffset + reservedMaxExpressId > MAX_SAFE_OFFSET) {
             throw new Error(`[FederationRegistry] Cannot register model: would exceed safe ID limit. ` +
-                `Current offset: ${this.nextOffset}, model max ID: ${maxExpressId}. ` +
+                `Current offset: ${this.nextOffset}, reserved model max ID: ${reservedMaxExpressId}. ` +
                 `Please unload some models first.`);
         }
         const offset = this.nextOffset;
-        const range = { modelId, offset, maxExpressId };
+        const range = { modelId, offset, maxExpressId: -1, reservedMaxExpressId, publishedStart: null };
         this.modelRanges.set(modelId, range);
         this.sortedRanges.push(range);
         // Keep sorted by offset for binary search
@@ -64,9 +73,60 @@ export class FederationRegistry {
         // Next model starts after this model's range (+1 gap for safety), plus
         // reserved headroom for mutation-overlay ids allocated into this model's
         // own space after load (see OVERLAY_ID_HEADROOM above).
-        this.nextOffset = offset + maxExpressId + 1 + OVERLAY_ID_HEADROOM;
+        this.nextOffset = offset + reservedMaxExpressId + 1 + OVERLAY_ID_HEADROOM;
         return offset;
     }
+    /** Publish the next contiguous owned local range inside a reservation. */
+    publishRange(modelId, start, end) {
+        const range = this.modelRanges.get(modelId);
+        if (!range)
+            throw new Error(`[FederationRegistry] Cannot publish unknown model ${modelId}`);
+        if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > range.reservedMaxExpressId) {
+            throw new Error(`[FederationRegistry] Invalid published range ${start}..${end} for ${modelId}`);
+        }
+        if (range.publishedStart === null) {
+            range.publishedStart = start;
+        }
+        else if (start !== range.maxExpressId + 1) {
+            throw new Error(`[FederationRegistry] Published IDs for ${modelId} must be contiguous and source ordered`);
+        }
+        range.maxExpressId = end;
+    }
+    /** Publish derived/overlay IDs from the separately reserved headroom. */
+    publishOverlayRange(modelId, start, end) {
+        const range = this.modelRanges.get(modelId);
+        if (!range)
+            throw new Error(`[FederationRegistry] Cannot publish unknown model ${modelId}`);
+        const overlayEnd = range.reservedMaxExpressId + OVERLAY_ID_HEADROOM;
+        if (!Number.isInteger(start) || !Number.isInteger(end) || start < range.reservedMaxExpressId + 1 || end < start || end > overlayEnd) {
+            throw new Error(`[FederationRegistry] Invalid overlay range ${start}..${end} for ${modelId}`);
+        }
+        if (start !== range.maxExpressId + 1) {
+            throw new Error(`[FederationRegistry] Overlay IDs for ${modelId} must extend published ownership contiguously`);
+        }
+        range.maxExpressId = end;
+    }
+    /**
+     * Resolve an owned overlay range while it is still detached from its
+     * mutation transaction. This validates the exact range that will be
+     * publishable, but deliberately does not make it pickable or owned yet.
+     * Callers must publish it only after the backing records commit.
+     */
+    previewOverlayGlobalId(modelId, start, end, expressId) {
+        const range = this.modelRanges.get(modelId);
+        if (!range)
+            throw new Error(`[FederationRegistry] Cannot preview unknown model ${modelId}`);
+        const overlayEnd = range.reservedMaxExpressId + OVERLAY_ID_HEADROOM;
+        if (!Number.isInteger(start) || !Number.isInteger(end) || !Number.isInteger(expressId)
+            || start < range.reservedMaxExpressId + 1 || end < start || end > overlayEnd
+            || expressId < start || expressId > end) {
+            throw new Error(`[FederationRegistry] Invalid overlay preview ${start}..${end} for ${modelId}`);
+        }
+        if (start !== range.maxExpressId + 1) {
+            throw new Error(`[FederationRegistry] Overlay preview for ${modelId} must extend published ownership contiguously`);
+        }
+        return range.offset + expressId;
+    }
     /**
      * Unregister a model (when removed from viewer)
      * Note: The offset space is NOT reclaimed to avoid invalidating any
@@ -91,6 +151,9 @@ export class FederationRegistry {
         if (!range) {
             return expressId;
         }
+        if (!this.isPublished(range, expressId)) {
+            throw new Error(`[FederationRegistry] Local ID ${expressId} is not published for model ${modelId}`);
+        }
         return expressId + range.offset;
     }
     /**
@@ -108,7 +171,7 @@ export class FederationRegistry {
         }
         // Verify the globalId is actually within this model's range
         const localId = globalId - range.offset;
-        if (localId < 0 || localId > range.maxExpressId) {
+        if (!this.isPublished(range, localId)) {
             // globalId is in the gap between models
             return null;
         }
@@ -157,8 +220,10 @@ export class FederationRegistry {
         const range = this.modelRanges.get(modelId);
         if (!range)
             return null;
+        if (range.publishedStart === null)
+            return null;
         return {
-            start: range.offset,
+            start: range.offset + range.publishedStart,
             end: range.offset + range.maxExpressId,
         };
     }
@@ -171,7 +236,7 @@ export class FederationRegistry {
         if (!range)
             return false;
         const localId = globalId - range.offset;
-        return localId >= 0 && localId <= range.maxExpressId;
+        return this.isPublished(range, localId);
     }
     /**
      * Clear all registrations (for full reset)
@@ -181,6 +246,12 @@ export class FederationRegistry {
         this.sortedRanges = [];
         this.nextOffset = 0;
     }
+    isPublished(range, localId) {
+        return range.publishedStart !== null
+            && Number.isInteger(localId)
+            && localId >= range.publishedStart
+            && localId <= range.maxExpressId;
+    }
     /**
      * Binary search to find the range that could contain a globalId
      * Returns the range with the largest offset that is <= globalId

package/dist/federation-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"federation-registry.js","sourceRoot":"","sources":["../src/federation-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"federation-registry.js","sourceRoot":"","sources":["../src/federation-registry.ts"],"names":[],"mappings":"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"}

package/dist/gpu-static-upload.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The ONE way the renderer creates a GPU buffer pre-filled with static
+ * geometry (vertex, index and per-instance data) — issue #5429.
+ *
+ * Why `queue.writeBuffer` and never `createBuffer({ mappedAtCreation: true })`:
+ * on Chromium (Chrome / Edge / WebView2, D3D12), a mapped-at-creation buffer
+ * keeps a shared-memory copy of its FULL contents mapped into both the
+ * renderer and the GPU process for as long as the buffer lives, even after
+ * `unmap()`. That region is charged to system commit but appears in neither
+ * process's private bytes, so a loaded scene carried an invisible second copy
+ * of all its resident geometry (≈1.1 GB per 1 GiB uploaded in the issue's
+ * standalone repro; ~6 GB for a 50-file federation). `writeBuffer` into a
+ * plain `COPY_DST` buffer stages through a transient transfer allocation and
+ * keeps nothing alive afterwards.
+ *
+ * It also removes this path's synchronous `RangeError` ("createBuffer failed,
+ * size (…) is too large for the implementation when mappedAtCreation ==
+ * true"): Chromium throws that only when it cannot back the mapping, and a
+ * buffer created without `mappedAtCreation` has no mapping to back. A real
+ * GPU out-of-memory still reports the way it always did for the device-side
+ * allocation — asynchronously, as a `GPUOutOfMemoryError` through the
+ * device's error scopes / `uncapturederror`.
+ *
+ * Alignment is this helper's job, not the caller's. `writeBuffer` throws an
+ * `OperationError` DOMException when the byte count is not a multiple of 4,
+ * and `gpu-upload-guard.ts`'s `isDeviceLossThrow` classifies EVERY
+ * DOMException as a device loss — so one odd-length upload (a u16 index list
+ * with an odd count, say) would falsely latch the whole session as lost.
+ * The buffer size is therefore rounded up to 4 bytes (minimum 4), and an
+ * unaligned payload is copied into a zero-padded staging array first. The
+ * padding lies past every `indexCount` / vertex count the caller draws with,
+ * so it is never read.
+ *
+ * `writeBuffer` copies `data` before it returns (WebGPU spec: the contents
+ * are captured at call time), so callers may reuse or drop their CPU array
+ * immediately, exactly as they could after `unmap()`.
+ */
+export declare function createStaticGpuBuffer(device: GPUDevice, data: ArrayBufferView | ArrayBuffer, usage: GPUBufferUsageFlags): GPUBuffer;
+//# sourceMappingURL=gpu-static-upload.d.ts.map

package/dist/gpu-static-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-static-upload.d.ts","sourceRoot":"","sources":["../src/gpu-static-upload.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,eAAe,GAAG,WAAW,EACnC,KAAK,EAAE,mBAAmB,GACzB,SAAS,CAiBX"}