@3driseai/3drise-viewer 0.1.27 → 0.1.29

package/dist/components/environment/Sandstorm.js

@@ -0,0 +1,776 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { DEFAULT_ENVIRONMENT_OBJECTS, ENVIRONMENT_OBJECTS_ANIMATABLE } from '@3driseai/3drise-core';
+import { withConfigDefaults } from '../../utils/configAnimations.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigDriver } from '../../hooks/useConfigDriver.js';
+import { useCloudSun } from '../../hooks/useCloudSun.js';
+import { stepPointerField, usePointerField } from '../../utils/pointerField.js';
+// Generated from Claude outputs/environment-lab (common.mjs + sandstorm.mjs, the approved lab modules)
+// by gen_family.mjs — edit there and regenerate.
+// ---------------------------------------------------------------------------- shared core
+// Shared core of the environment objects (lab). Inlined verbatim into every generated component.
+//
+// Slice volume: continuous media (dust, rain curtains, funnels) are rendered as N view-aligned
+// slices between the camera and the far side of the volume, drawn back to front in one instanced
+// call. Each slice is a full-screen quad at a fixed view depth, depth-tested against the scene,
+// so objects inside the medium are hidden by exactly the medium in front of them — volume
+// rendering without a depth texture. Slices are spaced geometrically (dense near the eye) and
+// every fragment samples at a per-pixel dithered depth inside its slab, which turns slice
+// banding into fine grain.
+//
+// What a slice volume costs is pixels x slices x the work per sample, so the core keeps all three down:
+//   noise     vnoise3 is one trilinear fetch from a small 3-D texture holding the very lattice values
+//             the hash gave (the smoothstep goes into the coordinate), instead of 8 hashes and 7 mixes.
+//   bounds    slices cover the volume's box on screen, not the whole screen.
+//   density   on a dense display (device pixel ratio above 1) neighbouring pixels take turns over the
+//             slices (2 or 4 interleaved sets, each sample standing for the slabs it skips), so the
+//             samples per CSS pixel — what the eye resolves — stay what they are at ratio 1.
+//   reach     near layers (streaks, grains, splashes) are not submitted when the camera is too far
+//             from the volume to see any of them (layerInReach).
+const WIND_MS_COMMON = 8; // m/s per unit of windStrength (Rain's 0..1 range)
+const DEG_C = Math.PI / 180;
+function mulberry32(a) {
+    return function () {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+// ---------------------------------------------------------------------------- noise texture
+// The lattice of vnoise3 as a texture: NOISE_N^3 values of the same hash the shader used to evaluate,
+// for lattice points -NOISE_N/2 .. NOISE_N/2 - 1 on each axis (beyond that it repeats). One per page,
+// shared by every environment object.
+const NOISE_N = 64;
+let _noiseTex = null;
+function noiseTexture() {
+    if (_noiseTex)
+        return _noiseTex;
+    const N = NOISE_N, H = N / 2, f = Math.fround;
+    const fr = (x) => f(x - Math.floor(x));
+    const data = new Uint8Array(N * N * N);
+    let o = 0;
+    for (let z = 0; z < N; z++)
+        for (let y = 0; y < N; y++)
+            for (let x = 0; x < N; x++) {
+                // hash13: p = fract(p * 0.1031); p += dot(p, p.zyx + 31.32); return fract((p.x + p.y) * p.z);
+                let px = fr(f((x - H) * f(0.1031))), py = fr(f((y - H) * f(0.1031))), pz = fr(f((z - H) * f(0.1031)));
+                const d = f(f(f(px * f(pz + f(31.32))) + f(py * f(py + f(31.32)))) + f(pz * f(px + f(31.32))));
+                px = f(px + d);
+                py = f(py + d);
+                pz = f(pz + d);
+                data[o++] = Math.min(255, Math.round(fr(f(f(px + py) * pz)) * 255));
+            }
+    const tex = new THREE.Data3DTexture(data, N, N, N);
+    tex.format = THREE.RedFormat;
+    tex.type = THREE.UnsignedByteType;
+    tex.minFilter = THREE.LinearFilter;
+    tex.magFilter = THREE.LinearFilter;
+    tex.wrapS = THREE.RepeatWrapping;
+    tex.wrapT = THREE.RepeatWrapping;
+    tex.wrapR = THREE.RepeatWrapping;
+    tex.unpackAlignment = 1;
+    tex.generateMipmaps = false;
+    tex.needsUpdate = true;
+    _noiseTex = tex;
+    return tex;
+}
+function setColor(uniform, v) {
+    if (v === undefined || v === null)
+        return;
+    if (v.isColor)
+        uniform.value.copy(v);
+    else
+        uniform.value.set(v);
+}
+/** Uniforms every environment object has. */
+function createCommonUniforms() {
+    return {
+        uTime: { value: 0 },
+        uWind: { value: new THREE.Vector2() },
+        uWindDir: { value: new THREE.Vector2(0, 1) },
+        uWindStrength: { value: 0.2 },
+        uTurb: { value: 0.3 },
+        uTurbPhase: { value: 0 },
+        uSpeed: { value: 1 },
+        uVolume: { value: new THREE.Vector3(100, 40, 100) },
+        uCam: { value: new THREE.Vector3() },
+        uCamToLocal: { value: new THREE.Matrix4() },
+        uSliceNear: { value: 0.3 },
+        uSliceFar: { value: 200 },
+        uSliceCount: { value: 32 },
+        uSliceRect: { value: new THREE.Vector4(-1.04, -1.04, 1.04, 1.04) },
+        uSkip: { value: 1 },
+        uSkipMax: { value: 4 },
+        uSliceCurve: { value: 0 },
+        uNoise: { value: noiseTexture() },
+        uFollow: { value: 0 },
+        uViewH: { value: 800 },
+        uIntensity: { value: 1 },
+        uOpacity: { value: 1 },
+        uColor: { value: new THREE.Color('#ffffff') },
+        uShadeColor: { value: new THREE.Color('#808080') },
+        uSunDir: { value: new THREE.Vector3(0.35, 0.42, 0.84).normalize() },
+        uSunColor: { value: new THREE.Color(1.0, 0.93, 0.82) },
+        uSkyAmbient: { value: new THREE.Color(0.55, 0.65, 0.85) },
+        uPointer: { value: new THREE.Vector3() },
+        uPointerVel: { value: new THREE.Vector3() },
+        uPointerActive: { value: 0 },
+        uPointerMode: { value: -1 },
+        uPointerStrength: { value: 1 },
+        uPointerRadius: { value: 1 },
+        uPointerColor: { value: new THREE.Color('#ffffff') },
+    };
+}
+/** The base knobs every environment object shares (push point, part 1). */
+function applyCommonConfig(u, c, pointerModes) {
+    if (c.intensity !== undefined)
+        u.uIntensity.value = c.intensity;
+    if (c.speed !== undefined)
+        u.uSpeed.value = c.speed;
+    if (c.opacity !== undefined)
+        u.uOpacity.value = c.opacity;
+    setColor(u.uColor, c.color);
+    setColor(u.uShadeColor, c.shadeColor);
+    setColor(u.uPointerColor, c.pointerColor);
+    if (c.windStrength !== undefined)
+        u.uWindStrength.value = c.windStrength;
+    if (c.windDirection !== undefined)
+        u.uWindDir.value.set(Math.sin(c.windDirection * DEG_C), Math.cos(c.windDirection * DEG_C));
+    if (c.turbulence !== undefined)
+        u.uTurb.value = c.turbulence;
+    if (c.pointerStrength !== undefined)
+        u.uPointerStrength.value = c.pointerStrength;
+    if (c.pointerRadius !== undefined)
+        u.uPointerRadius.value = c.pointerRadius;
+    if (c.pointerMode !== undefined)
+        u.uPointerMode.value = pointerModes.indexOf(c.pointerMode);
+    if (c.followCamera !== undefined)
+        u.uFollow.value = c.followCamera ? 1 : 0;
+}
+const _cs = new THREE.Vector3(), _cc = new THREE.Vector3(), _cq = new THREE.Quaternion(), _csun = new THREE.Vector3();
+const _cinv = new THREE.Matrix4();
+const _corner = new THREE.Vector3();
+const _cview = new THREE.Matrix4();
+/** Per-frame bookkeeping shared by every object: volume, camera, slice range and bounds, sun, phases. */
+function updateCommon(u, object, camera, dt, viewH, sunWorld, dpr) {
+    // the camera may have been moved this frame (controls) without its matrices following yet
+    camera.updateMatrixWorld();
+    object.updateWorldMatrix(true, false);
+    object.getWorldScale(_cs);
+    u.uVolume.value.set(Math.max(_cs.x, 0.01), Math.max(_cs.y, 0.01), Math.max(_cs.z, 0.01));
+    const V = u.uVolume.value;
+    object.worldToLocal(_cc.copy(camera.position));
+    u.uCam.value.set(_cc.x * V.x, _cc.y * V.y, _cc.z * V.z);
+    _cinv.copy(object.matrixWorld).invert();
+    u.uCamToLocal.value.multiplyMatrices(_cinv, camera.matrixWorld);
+    if (viewH)
+        u.uViewH.value = viewH;
+    // slice range: from where the volume starts in front of the eye to its far corner
+    const C = u.uCam.value;
+    const follow = u.uFollow.value > 0.5;
+    const hx = follow ? 1e6 : V.x / 2, hz = follow ? 1e6 : V.z / 2;
+    const dx = Math.max(Math.abs(C.x) - hx, 0), dz = Math.max(Math.abs(C.z) - hz, 0);
+    const dy = Math.max(-C.y, C.y - V.y, 0);
+    const dNear = Math.hypot(dx, dy, dz);
+    let dFar = 0;
+    for (let i = 0; i < 8; i++) {
+        _corner.set((i & 1 ? 1 : -1) * Math.min(hx, 3e3), i & 2 ? V.y : 0, (i & 4 ? 1 : -1) * Math.min(hz, 3e3));
+        dFar = Math.max(dFar, _corner.distanceTo(C));
+    }
+    const far = camera.far !== undefined ? camera.far : 2000;
+    u.uSliceNear.value = Math.max(0.3, dNear * 0.6);
+    u.uSliceFar.value = Math.max(u.uSliceNear.value * 1.5, Math.min(dFar, 600, far * 0.98));
+    // Slice bounds: the volume's box on screen (NDC). Whole screen when the box reaches behind the
+    // eye (the camera is inside or right next to it) or follows the camera.
+    const R = u.uSliceRect.value.set(-1.04, -1.04, 1.04, 1.04);
+    if (!follow && camera.projectionMatrix) {
+        _cview.copy(camera.matrixWorld).invert().multiply(object.matrixWorld);
+        const P = camera.projectionMatrix.elements, nearZ = camera.near !== undefined ? camera.near : 0.1;
+        let x0 = 1e9, y0 = 1e9, x1 = -1e9, y1 = -1e9, ok = true;
+        for (let i = 0; i < 8 && ok; i++) {
+            _corner.set(i & 1 ? 0.5 : -0.5, i & 2 ? 1 : 0, i & 4 ? 0.5 : -0.5).applyMatrix4(_cview);
+            if (_corner.z > -nearZ) {
+                ok = false;
+                break;
+            }
+            const w = -_corner.z, x = (P[0] * _corner.x + P[8] * _corner.z) / w, y = (P[5] * _corner.y + P[9] * _corner.z) / w;
+            if (x < x0)
+                x0 = x;
+            if (x > x1)
+                x1 = x;
+            if (y < y0)
+                y0 = y;
+            if (y > y1)
+                y1 = y;
+        }
+        // the margin covers the depth dither, which slides a sample along its ray but never off its pixel
+        if (ok)
+            R.set(Math.max(x0 - 0.03, -1.04), Math.max(y0 - 0.03, -1.04), Math.min(x1 + 0.03, 1.04), Math.min(y1 + 0.03, 1.04));
+        if (R.z <= R.x || R.w <= R.y)
+            R.set(0, 0, 0, 0); // off screen: nothing to draw
+    }
+    // Interleaved slices on dense displays: pixels take turns over 2 (ratio >= 1.25) or 4 (>= 1.75) sets.
+    // An object caps it (buildSlices' interleave): fine, fast-changing structure like the tornado's funnel
+    // loses its crispness when neighbours see different slabs, so it takes every slice.
+    u.uSkip.value = Math.min(dpr >= 1.75 ? 4 : dpr >= 1.25 ? 2 : 1, u.uSkipMax.value);
+    // phases (rates integrated on the CPU, so animating them never jumps)
+    const sp = u.uSpeed.value;
+    u.uTime.value += dt * sp;
+    u.uWind.value.addScaledVector(u.uWindDir.value, dt * sp * u.uWindStrength.value * WIND_MS_COMMON);
+    u.uTurbPhase.value += dt * sp * 0.25;
+    if (sunWorld) {
+        object.getWorldQuaternion(_cq).invert();
+        u.uSunDir.value.copy(_csun.copy(sunWorld).normalize().applyQuaternion(_cq));
+    }
+}
+/**
+ * True when a layer that only exists inside the volume and within `reach` metres of the eye can show
+ * anything: used to skip submitting near layers (thousands of instances, each fully evaluated per
+ * vertex) while the camera is away from the volume.
+ */
+function layerInReach(u, reach) {
+    const C = u.uCam.value, V = u.uVolume.value, follow = u.uFollow.value > 0.5;
+    const ox = follow ? 0 : Math.max(Math.abs(C.x) - 0.5 * V.x, 0), oz = follow ? 0 : Math.max(Math.abs(C.z) - 0.5 * V.z, 0);
+    const oy = Math.max(-C.y, C.y - V.y, 0);
+    return ox * ox + oy * oy + oz * oz < reach * reach;
+}
+// Where the pointer plane passes (object-local unit coords; the plane faces the camera):
+// a few metres ahead of the eye inside the volume, else through the volume centre's depth.
+const _pa = new THREE.Vector3(), _pd = new THREE.Vector3(), _pc = new THREE.Vector3();
+function pointerAnchor(object, camera, u, out, ahead) {
+    const V = u.uVolume.value, C = u.uCam.value;
+    const inside = Math.abs(C.x) < 0.5 * V.x && Math.abs(C.z) < 0.5 * V.z && C.y > 0 && C.y < V.y;
+    camera.getWorldDirection(_pd);
+    let dist = ahead || 4.5;
+    if (!inside) {
+        object.updateWorldMatrix(true, false);
+        object.localToWorld(_pc.set(0, 0.5, 0));
+        dist = Math.max(dist, _pc.sub(camera.position).dot(_pd));
+    }
+    _pa.copy(camera.position).addScaledVector(_pd, dist);
+    return object.worldToLocal(out.copy(_pa));
+}
+const NOISE_GLSL = /* glsl */ `
+uniform highp sampler3D uNoise;
+float hash13(vec3 p) { p = fract(p * 0.1031); p += dot(p, p.zyx + 31.32); return fract((p.x + p.y) * p.z); }
+float hash12(vec2 p) { vec3 q = fract(vec3(p.xyx) * 0.1031); q += dot(q, q.yzx + 33.33); return fract((q.x + q.y) * q.z); }
+// value noise from the lattice texture: the smoothstep is put into the coordinate, the trilinear
+// filter does the eight-corner mix (same lattice values as hash13 around the origin)
+float vnoise3(vec3 p) {
+    vec3 i = floor(p); vec3 f = fract(p); f = f * f * (3.0 - 2.0 * f);
+    return texture(uNoise, (i + f + ${(0.5 + NOISE_N / 2).toFixed(1)}) / ${NOISE_N.toFixed(1)}).r;
+}
+float vnoise2(vec2 p) {
+    vec2 i = floor(p); vec2 f = fract(p); f = f * f * (3.0 - 2.0 * f);
+    return mix(mix(hash12(i), hash12(i + vec2(1, 0)), f.x), mix(hash12(i + vec2(0, 1)), hash12(i + vec2(1, 1)), f.x), f.y);
+}
+// three octaves, rotated between octaves so the lattice never lines up
+float fbm3(vec3 p) {
+    float s = 0.5 * vnoise3(p);
+    p = mat3(0.00, 0.80, 0.60, -0.80, 0.36, -0.48, -0.60, -0.48, 0.64) * p * 2.03;
+    s += 0.25 * vnoise3(p);
+    p = mat3(0.00, 0.80, 0.60, -0.80, 0.36, -0.48, -0.60, -0.48, 0.64) * p * 2.01;
+    s += 0.125 * vnoise3(p);
+    return s / 0.875;
+}
+float bump(float x) { float t = clamp(1.0 - x * x, 0.0, 1.0); return t * t; }
+float hgPhase(float mu, float g) { return 0.0795775 * (1.0 - g * g) / pow(1.0 + g * g - 2.0 * g * mu, 1.5); }
+float ign(vec2 px) { return fract(52.9829189 * fract(dot(px, vec2(0.06711056, 0.00583715)))); }
+`;
+const COMMON_UNIFORMS_GLSL = /* glsl */ `
+uniform float uTime, uWindStrength, uTurb, uTurbPhase, uSpeed, uFollow, uViewH;
+uniform vec2 uWind, uWindDir;
+uniform vec3 uVolume, uCam;
+uniform vec3 uSunDir, uSunColor, uSkyAmbient, uColor, uShadeColor, uPointerColor;
+uniform float uIntensity, uOpacity;
+uniform vec3 uPointer, uPointerVel;
+uniform float uPointerActive, uPointerMode, uPointerStrength, uPointerRadius;
+`;
+const FOG_V = /* glsl */ `
+#ifdef USE_FOG
+varying float vFogDepth;
+#endif
+`;
+const FOG_F = /* glsl */ `
+#ifdef USE_FOG
+uniform vec3 fogColor;
+varying float vFogDepth;
+#ifdef FOG_EXP2
+uniform float fogDensity;
+#else
+uniform float fogNear;
+uniform float fogFar;
+#endif
+#endif
+`;
+const FOG_APPLY = /* glsl */ `
+#ifdef USE_FOG
+#ifdef FOG_EXP2
+    float fogFactor = 1.0 - exp(-fogDensity * fogDensity * vFogDepth * vFogDepth);
+#else
+    float fogFactor = smoothstep(fogNear, fogFar, vFogDepth);
+#endif
+    gl_FragColor.rgb = mix(gl_FragColor.rgb, fogColor * gl_FragColor.a, fogFactor);
+#endif
+`;
+/** Soft walls of the volume (metres); the ground is hard. */
+const VOLUME_GLSL = /* glsl */ `
+float volumeFade(vec3 p, float side, float top) {
+    float a = step(0.0, p.y) * (1.0 - smoothstep(uVolume.y - top, uVolume.y, p.y));
+    if (uFollow < 0.5) {
+        vec2 e = 0.5 * uVolume.xz - abs(p.xz);
+        a *= smoothstep(0.0, side, e.x) * smoothstep(0.0, side, e.y);
+    }
+    return a;
+}
+`;
+const SLICE_VERT = /* glsl */ `
+${COMMON_UNIFORMS_GLSL}
+uniform float uSliceNear, uSliceFar, uSliceCount, uSliceCurve;
+uniform vec4 uSliceRect;
+uniform mat4 uCamToLocal;
+attribute vec2 aCorner;
+attribute float aSlice;
+varying vec3 vLocal;
+varying vec3 vRay;
+varying float vDz, vSlice;
+${FOG_V}
+void main() {
+    // slice 0 is the farthest: instances draw back to front
+    float k = log(uSliceFar / uSliceNear);
+    float t0 = 1.0 - (aSlice + 1.0) / uSliceCount;
+    float t1 = 1.0 - aSlice / uSliceCount;
+    // legacy spacing is geometric; even (quadratic) spacing spends far fewer slabs on the first metres
+    float z0 = uSliceCurve > 0.5 ? uSliceNear + (uSliceFar - uSliceNear) * t0 * t0 : uSliceNear * exp(k * t0);
+    float z1 = uSliceCurve > 0.5 ? uSliceNear + (uSliceFar - uSliceNear) * t1 * t1 : uSliceNear * exp(k * t1);
+    float z = 0.5 * (z0 + z1);
+    vDz = z1 - z0;
+    // the quad spans the volume's bounds on screen (NDC), not the screen
+    vec2 ndc = mix(uSliceRect.xy, uSliceRect.zw, aCorner * 0.5 + 0.5);
+    vec3 view = vec3((ndc.x + projectionMatrix[2][0]) * z / projectionMatrix[0][0], (ndc.y + projectionMatrix[2][1]) * z / projectionMatrix[1][1], -z);
+    vSlice = aSlice;
+    gl_Position = projectionMatrix * vec4(view, 1.0);
+    vLocal = (uCamToLocal * vec4(view, 1.0)).xyz * uVolume;
+    vRay = vLocal - uCam;
+#ifdef USE_FOG
+    vFogDepth = z;
+#endif
+}
+`;
+/**
+ * Wraps an object's `vec4 sliceSample(vec3 p, vec3 rd, float dz)` (premultiplied rgb, alpha).
+ *
+ * The canvas stores display (non-linear) values. By default the premultiplied colour goes through
+ * the output transform as it is, which makes a thin layer brighter than its share: the look then
+ * depends on how thin the slabs are (the first objects were tuned by eye under it — leave them).
+ * `straight` converts the colour first and weights it by alpha after, so a medium looks the same
+ * at every slice count, density and quality; new objects use it.
+ */
+function sliceFrag(body, straight) {
+    return /* glsl */ `
+${COMMON_UNIFORMS_GLSL}
+uniform float uSkip;
+varying vec3 vLocal;
+varying vec3 vRay;
+varying float vDz, vSlice;
+${FOG_F}
+${NOISE_GLSL}
+${VOLUME_GLSL}
+${body}
+void main() {
+    // dense displays: neighbouring pixels take turns over the slices (see updateCommon)
+    if (uSkip > 1.5) {
+        vec2 px = mod(floor(gl_FragCoord.xy), 2.0);
+        float turn = uSkip > 3.0 ? mod(px.x * 2.0 + px.y * 3.0, 4.0) : mod(px.x + px.y, 2.0);
+        if (mod(vSlice + turn, uSkip) > 0.5) discard;
+    }
+    vec3 rd = normalize(vRay);
+    // dithered depth inside the slab: banding becomes grain
+    vec3 p = vLocal + rd * (ign(gl_FragCoord.xy) - 0.5) * 0.6 * vDz;
+    if (p.y < 0.0 || p.y > uVolume.y) discard;
+    if (uFollow < 0.5 && (abs(p.x) > 0.5 * uVolume.x || abs(p.z) > 0.5 * uVolume.z)) discard;
+    vec4 s = sliceSample(p, rd, vDz);
+    s *= uOpacity;
+    if (s.a < 0.0015 && dot(s.rgb, vec3(1.0)) < 0.002) discard;
+    gl_FragColor = ${straight ? 'vec4(s.rgb / max(s.a, 1e-5) * uIntensity, 1.0)' : 'vec4(s.rgb * uIntensity, s.a)'};
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>${straight ? '\n    gl_FragColor = vec4(gl_FragColor.rgb * s.a, s.a);' : ''}
+${FOG_APPLY}
+    // A pixel that skipped slabs stands for them: it lays down what 2 or 4 copies of its own thin
+    // layer would have composited to (colour c (1 + t + ...), transmittance t^n), so the volume
+    // keeps exactly the brightness and opacity it has when every pixel takes every slice.
+    if (uSkip > 1.5) {
+        float t = 1.0 - gl_FragColor.a;
+        float t2 = t * t;
+        gl_FragColor = uSkip > 3.0 ? vec4(gl_FragColor.rgb * (1.0 + t) * (1.0 + t2), 1.0 - t2 * t2) : vec4(gl_FragColor.rgb * (1.0 + t), 1.0 - t2);
+    }
+}
+`;
+}
+function premulMaterial(u, vertexShader, fragmentShader, additive) {
+    return new THREE.ShaderMaterial({
+        uniforms: Object.assign({}, THREE.UniformsUtils.clone(THREE.UniformsLib.fog), u),
+        vertexShader, fragmentShader,
+        transparent: true, depthWrite: false, fog: true,
+        blending: THREE.CustomBlending,
+        blendSrc: THREE.OneFactor, blendDst: additive ? THREE.OneFactor : THREE.OneMinusSrcAlphaFactor,
+        blendSrcAlpha: THREE.OneFactor, blendDstAlpha: THREE.OneMinusSrcAlphaFactor,
+        premultipliedAlpha: true,
+    });
+}
+/** Bounds-only `position`: the unit volume box, so Box3.expandByObject centres the gizmo on it. */
+function boxPositions(geo) {
+    geo.setAttribute('position', new THREE.Float32BufferAttribute([-0.5, 0, -0.5, 0.5, 0, 0.5, 0.5, 1, -0.5, -0.5, 1, 0.5], 3));
+    geo.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0.5, 0), 0.87);
+}
+/**
+ * One instanced draw of `count` view-aligned slices. `interleave` (1, 2 or 4, default 4) is the most
+ * sets of slices neighbouring pixels may take turns over on a dense display; 1 = every pixel, every slice.
+ */
+function buildSlices(u, fragmentShader, count, interleave, curve) {
+    const geo = new THREE.InstancedBufferGeometry();
+    boxPositions(geo);
+    geo.setAttribute('aCorner', new THREE.Float32BufferAttribute([-1, -1, 1, -1, 1, 1, -1, 1], 2));
+    geo.setIndex([0, 1, 2, 0, 2, 3]);
+    const idx = new Float32Array(count);
+    for (let i = 0; i < count; i++)
+        idx[i] = i;
+    geo.setAttribute('aSlice', new THREE.InstancedBufferAttribute(idx, 1));
+    geo.instanceCount = count;
+    u.uSliceCount.value = count;
+    u.uSkipMax.value = interleave || 1;
+    u.uSliceCurve.value = curve ? 1 : 0;
+    const mat = premulMaterial(u, SLICE_VERT, fragmentShader, false);
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.frustumCulled = false;
+    mesh.raycast = function () { };
+    return mesh;
+}
+/**
+ * Slice budget by where the eye is (even-spaced volumes only; call after updateCommon). Inside the
+ * volume the medium fills the screen and half the slabs give the same picture, because even spacing
+ * no longer spends a third of them on the first three metres; seen from outside, thinner slabs are
+ * what keeps its brightness, and it covers few pixels, so it takes them all. The count eases between
+ * the two over the first stretch outside the wall.
+ */
+function adaptSlices(u, mesh, full) {
+    const C = u.uCam.value, V = u.uVolume.value, follow = u.uFollow.value > 0.5;
+    const ox = follow ? 0 : Math.max(Math.abs(C.x) - 0.5 * V.x, 0), oz = follow ? 0 : Math.max(Math.abs(C.z) - 0.5 * V.z, 0);
+    const d = Math.hypot(ox, Math.max(-C.y, C.y - V.y, 0), oz);
+    const t = Math.min(d / Math.max(0.25 * Math.min(V.x, V.z), 1), 1);
+    const n = Math.max(4, Math.round(full * (0.5 + 0.5 * t * t * (3 - 2 * t))));
+    mesh.geometry.instanceCount = n;
+    u.uSliceCount.value = n;
+}
+/** Instanced quad geometry with per-instance seeds (two vec4s). */
+function seededQuads(count, rnd) {
+    const geo = new THREE.InstancedBufferGeometry();
+    boxPositions(geo);
+    geo.setAttribute('aCorner', new THREE.Float32BufferAttribute([-1, -1, 1, -1, 1, 1, -1, 1], 2));
+    geo.setIndex([0, 1, 2, 0, 2, 3]);
+    const a = new Float32Array(count * 4), b = new Float32Array(count * 4);
+    for (let i = 0; i < count * 4; i++) {
+        a[i] = rnd();
+        b[i] = rnd();
+    }
+    geo.setAttribute('aSeedA', new THREE.InstancedBufferAttribute(a, 4));
+    geo.setAttribute('aSeedB', new THREE.InstancedBufferAttribute(b, 4));
+    geo.instanceCount = count;
+    return geo;
+}
+/** A streak quad between two view-space points, at least 1 px wide (energy kept by alpha). */
+const STREAK_GLSL = /* glsl */ `
+// returns the clip position of this corner; writes the coverage factor into cover
+vec4 streakCorner(vec4 headV, vec4 tailV, vec2 corner, float widthM, out float cover, out float lenPx) {
+    vec4 h = projectionMatrix * headV;
+    vec4 t = projectionMatrix * tailV;
+    vec2 hs = h.xy / h.w, ts = t.xy / t.w;
+    vec2 scr = vec2(uViewH * projectionMatrix[1][1] / projectionMatrix[0][0], uViewH) * 0.5;
+    vec2 d = (hs - ts) * scr;
+    lenPx = length(d);
+    vec2 dir = lenPx > 1e-4 ? d / lenPx : vec2(0.0, 1.0);
+    vec2 nrm = vec2(dir.y, -dir.x);   // (nrm, dir) right-handed: the quad stays front-facing
+    float wPx = widthM * uViewH * projectionMatrix[1][1] * 0.5 / max(-headV.z, 1e-3);
+    float w = max(wPx, 1.0);
+    cover = wPx / w;
+    vec4 base = corner.y > 0.0 ? h : t;
+    vec2 off = nrm * corner.x * 0.5 * w / scr;
+    // extend half a pixel past both ends so short streaks stay round
+    off += dir * corner.y * 0.5 / scr;
+    return vec4(base.xy + off * base.w, base.zw);
+}
+`;
+// ---------------------------------------------------------------------------- sandstorm
+// Sandstorm — environment object (lab module). Shared core: ./common.mjs.
+// Construction:
+//   dust      a continuous medium in the slice volume. Density = haze + billows, under an
+//             exponential height profile (scale height knob). The billows are 3-octave fbm,
+//             domain-warped and advected with the CPU-integrated wind; they churn upward.
+//   walls     gust fronts (haboobs): a sawtooth in the along-wind coordinate, travelling
+//             downwind at the wind speed. Each period has a steep leading wall that rises
+//             higher (the scale height grows behind the front) and a long settling tail;
+//             the fbm breaks the wall into cauliflower lobes.
+//   light     single scattering with a Henyey–Greenstein forward lobe (g = 0.6) and a
+//             column-depth shadow toward the sun (Beer–Lambert on the analytic profile),
+//             sky fill on the shaded side. The dust colour is the albedo, so thick dust
+//             tints everything behind it (brownout).
+//   grains    saltation: sand grains hop in ballistic arcs a few centimetres high, length
+//             ~ wind speed, drawn as motion-blurred streaks in a camera tile near the ground.
+const catalog = {
+    key: 'sandstorm',
+    name: 'Sandstorm',
+    description: 'A haboob: billowing dust under a scale-height profile, gust fronts that roll downwind as towering walls, and saltating grains streaking along the ground, lit by forward-scattered sun. The cursor is a windbreak, a dust devil or a gust. Use for desert, ash and Mars scenes.',
+    tags: ['sandstorm', 'desert', 'dust', 'haboob', 'weather', 'wind'],
+    structural: ['density', 'quality', 'seed'],
+    pointerModes: ['windbreak', 'devil', 'gust'],
+    pointerLabels: ['Windbreak', 'Dust devil', 'Gust'],
+    volume: [150, 50, 150],
+    staging: { sky: '#9a8a78', ground: '#a8865e', fog: 0.0022, sunEl: 30, sunAz: 150, inside: [[0, 1.7, 14], [0, 4, 0]], outside: [[95, 22, 150], [0, 12, 0]] },
+};
+const QUALITY = { low: { slices: 20, grains: 0.5 }, medium: { slices: 32, grains: 1 }, high: { slices: 48, grains: 1.6 } };
+const GRAIN_BASE = 24000;
+const GRAIN_TILE = 14;
+function createUniforms() {
+    return Object.assign(createCommonUniforms(), {
+        uSigma: { value: 0.035 },
+        uHeight: { value: 0.35 },
+        uWalls: { value: 0.75 },
+        uHaze: { value: 0.4 },
+        uGrains: { value: 1 },
+        uGrainSize: { value: 1 },
+        uWallPhase: { value: 0 },
+        uGrainPhase: { value: 0 },
+    });
+}
+function applyConfig(u, c) {
+    applyCommonConfig(u, c, catalog.pointerModes);
+    if (c.height !== undefined)
+        u.uHeight.value = c.height;
+    if (c.walls !== undefined)
+        u.uWalls.value = c.walls;
+    if (c.haze !== undefined)
+        u.uHaze.value = c.haze;
+    if (c.grains !== undefined)
+        u.uGrains.value = c.grains;
+    if (c.grainSize !== undefined)
+        u.uGrainSize.value = c.grainSize;
+}
+const DUST = /* glsl */ `
+uniform float uSigma, uHeight, uWalls, uHaze, uWallPhase;
+// pointer: the windbreak's lee, the dust devil's swirl and column, or the gust's shove
+vec3 pointerWarp(vec3 p, out float lee, out float devil) {
+    lee = 0.0; devil = 0.0;
+    if (uPointerMode < -0.5 || uPointerActive < 0.001) return p;
+    vec3 P = uPointer * uVolume, V = uPointerVel * uVolume;
+    float R = max(uPointerRadius * 3.0, 0.1), S = uPointerStrength * uPointerActive;
+    vec3 dp = p - P;
+    if (uPointerMode < 0.5) {
+        // windbreak: a still wake downwind of the cursor, widening and filling back in
+        vec3 C = P - V * 0.3;
+        vec2 d = p.xz - C.xz;
+        float along = dot(d, uWindDir), across = dot(d, vec2(-uWindDir.y, uWindDir.x));
+        float w = R * (1.0 + 0.15 * max(along, 0.0));
+        lee = S * bump(across / w) * smoothstep(-0.5 * R, 0.5 * R, along) * exp(-max(along, 0.0) / (10.0 * R)) * smoothstep(3.0 * R, 0.0, p.y - C.y + 1.0);
+        return p;
+    } else if (uPointerMode < 1.5) {
+        // dust devil: a vortex standing on the ground under the cursor, leaning with its motion
+        vec2 c = P.xz - V.xz * 0.4 * clamp(p.y / (8.0 * R), 0.0, 1.0);
+        vec2 d = p.xz - c; float r = length(d);
+        float ang = S * 6.0 * R / (r + 0.6 * R) * exp(-p.y / (10.0 * R)) - uTime * 2.0 * S * bump(r / (3.0 * R));
+        float cs = cos(ang), sn = sin(ang);
+        vec2 q = vec2(cs * d.x - sn * d.y, sn * d.x + cs * d.y);
+        devil = S * bump(r / (1.2 * R)) * exp(-p.y / (8.0 * R));
+        return vec3(c.x + q.x, p.y, c.y + q.y);
+    }
+    // gust: the hand's air shoves the dust along its motion
+    float w = bump(length(dp) / (1.5 * R));
+    vec3 push = V * 0.5; float m = length(push); if (m > 8.0) push *= 8.0 / m;
+    return p - S * w * push;
+}
+// dust density at p (1/m units folded into uSigma); g = how deep inside a wall
+float dust(vec3 p, out float g, out float devil) {
+    float lee;
+    vec3 pw = pointerWarp(p, lee, devil);
+    vec3 q = pw; q.xz -= uWind;
+    float w = vnoise3(q * 0.018 + vec3(0.0, -uTurbPhase * 0.4, 0.0));
+    q.xz += (w - 0.5) * uTurb * 28.0;
+    float n = fbm3(q * vec3(0.045, 0.07, 0.045) + vec3(0.0, -uTime * 0.12, 0.0));
+    // gust fronts: steep leading wall, long tail, travelling downwind
+    float s = dot(pw.xz, uWindDir) / 90.0 - uWallPhase + 0.3 * (w - 0.5);
+    float f = fract(s);
+    g = pow(f, 2.2) * (1.0 - smoothstep(0.93, 1.0, f));
+    float hs = max(uHeight * uVolume.y, 0.5) * (0.55 + 1.6 * g * uWalls);
+    float prof = exp(-pw.y / hs);
+    float body = smoothstep(0.42, 0.7, n + 0.3 * g * uWalls);
+    float d = prof * (uHaze * 0.45 + body * mix(1.0, 0.25 + 2.4 * g, uWalls));
+    d += devil * 12.0 * smoothstep(0.25, 0.7, n + 0.25);
+    return d * (1.0 - lee);
+}
+vec4 sliceSample(vec3 p, vec3 rd, float dz) {
+    float g, devil;
+    float d = dust(p, g, devil) * volumeFade(p, min(10.0, 0.08 * uVolume.x), min(6.0, 0.12 * uVolume.y));
+    if (d < 0.002) return vec4(0.0);
+    float a = 1.0 - exp(-uSigma * d * dz);
+    // self-shadow: one look a few metres toward the sun (lit billow tops, dark undersides),
+    // then Beer–Lambert on the analytic column above
+    vec3 ps = p + uSunDir * 6.0; ps.xz -= uWind;
+    float dS = d * smoothstep(0.3, 0.75, vnoise3(ps * vec3(0.045, 0.07, 0.045) + vec3(0.0, -uTime * 0.12, 0.0)) + 0.15);
+    float hs = max(uHeight * uVolume.y, 0.5);
+    float tau = uSigma * (dS * 30.0 + d * hs * 1.2 / max(uSunDir.y, 0.15));
+    float sunUp = smoothstep(-0.05, 0.1, uSunDir.y);
+    float mu = dot(rd, uSunDir);
+    float phase = hgPhase(mu, 0.6) * 1.2 + 0.25;
+    vec3 sun = uSunColor * sunUp * exp(-tau) * phase;
+    vec3 amb = uSkyAmbient * uShadeColor * (0.45 + 0.4 * exp(-uSigma * d * 25.0));
+    vec3 col = uColor * (sun + amb) + uPointerColor * devil * 0.2 * sun;
+    return vec4(min(col, vec3(1.0)) * a, a);
+}
+`;
+const GRAIN_VERT = /* glsl */ `
+${COMMON_UNIFORMS_GLSL}
+uniform float uGrains, uGrainSize, uGrainPhase;
+attribute vec2 aCorner;
+attribute vec4 aSeedA;
+attribute vec4 aSeedB;
+varying float vAlpha;
+varying vec2 vUv;
+varying vec3 vRd;
+${FOG_V}
+${NOISE_GLSL}
+${VOLUME_GLSL}
+${STREAK_GLSL}
+void main() {
+    float on = step(aSeedB.w, uGrains * 0.5);
+    float windMs = uWindStrength * 8.0;
+    float hopL = mix(0.3, 2.2, aSeedA.w) * mix(0.6, 1.4, uGrainSize) * (0.4 + 0.15 * windMs);
+    float hopH = hopL * mix(0.06, 0.14, aSeedB.x);
+    float sp = windMs * mix(0.45, 0.75, aSeedB.y);
+    // along-wind travel is integrated on the CPU (uGrainPhase = wind distance), so gusts never jump
+    float travel = uGrainPhase * mix(0.45, 0.75, aSeedB.y) / 0.6;
+    vec2 perp = vec2(-uWindDir.y, uWindDir.x);
+    vec2 base = (aSeedA.xz - 0.5) * ${GRAIN_TILE.toFixed(1)};
+    vec2 xz = uWindDir * (dot(base, uWindDir) + travel) + perp * dot(base, perp);
+    xz = uCam.xz + mod(xz - uCam.xz + ${(GRAIN_TILE / 2).toFixed(1)}, ${GRAIN_TILE.toFixed(1)}) - ${(GRAIN_TILE / 2).toFixed(1)};
+    float f = fract(travel / max(hopL, 0.05) + aSeedB.z);
+    float y = hopH * 4.0 * f * (1.0 - f) + 0.01;
+    vec3 p = vec3(xz.x, y, xz.y);
+    float vy = hopH * 4.0 * (1.0 - 2.0 * f) * sp / max(hopL, 0.05);
+    vec3 vel = vec3(uWindDir.x * sp, vy, uWindDir.y * sp);
+    vec3 tail = p - vel * 0.035;
+    vec4 hv = modelViewMatrix * vec4(p / uVolume, 1.0);
+    vec4 tv = modelViewMatrix * vec4(tail / uVolume, 1.0);
+    float cover, lenPx;
+    gl_Position = streakCorner(hv, tv, aCorner, 0.0012 * uGrainSize * mix(0.6, 1.4, aSeedA.y), cover, lenPx);
+    float dist = length(p - uCam);
+    float a = on * cover * volumeFade(p, 2.0, 1.0) * (1.0 - smoothstep(0.32 * ${GRAIN_TILE.toFixed(1)}, 0.5 * ${GRAIN_TILE.toFixed(1)}, dist));
+    a *= smoothstep(0.08, 0.25, uWindStrength) * smoothstep(0.15, 0.5, -hv.z);
+    a /= max(1.0, lenPx * 0.08);
+    vAlpha = a * 0.9;
+    vUv = aCorner;
+    vRd = normalize(p - uCam);
+#ifdef USE_FOG
+    vFogDepth = -hv.z;
+#endif
+}
+`;
+const GRAIN_FRAG = /* glsl */ `
+${COMMON_UNIFORMS_GLSL}
+varying float vAlpha;
+varying vec2 vUv;
+varying vec3 vRd;
+${FOG_F}
+void main() {
+    float across = 1.0 - abs(vUv.x);
+    float along = smoothstep(-1.0, -0.4, vUv.y) * smoothstep(1.0, 0.6, vUv.y);
+    float a = vAlpha * across * along * uOpacity;
+    if (a < 0.003) discard;
+    float sunUp = smoothstep(-0.05, 0.1, uSunDir.y);
+    // quartz grains glint toward the sun
+    vec3 col = uColor * (uSunColor * sunUp * (0.8 + 1.2 * pow(max(dot(vRd, uSunDir), 0.0), 6.0)) + uSkyAmbient * 0.5);
+    gl_FragColor = vec4(min(col, vec3(1.2)) * uIntensity * a, a);
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>
+${FOG_APPLY}
+}
+`;
+function build(u, c) {
+    const q = QUALITY[c.quality] || QUALITY.medium;
+    const dens = Math.max(0.05, c.density ?? 1);
+    u.uSigma.value = 0.014 * dens;
+    const rnd = mulberry32((c.seed ?? 11) * 2654435761);
+    const slices = buildSlices(u, sliceFrag(DUST, false), q.slices, 1, true);
+    slices.renderOrder = 1;
+    const nGrains = Math.round(GRAIN_BASE * q.grains);
+    const grainGeo = seededQuads(nGrains, rnd);
+    const grainMat = premulMaterial(u, GRAIN_VERT, GRAIN_FRAG, false);
+    const grains = new THREE.Mesh(grainGeo, grainMat);
+    grains.frustumCulled = false;
+    grains.renderOrder = 2;
+    grains.raycast = function () { };
+    const object = new THREE.Group();
+    object.name = 'sandstorm';
+    object.add(slices, grains);
+    return {
+        object,
+        materials: [slices.material, grainMat],
+        apply: function (cfg) { applyConfig(u, cfg); },
+        update: function (dt, camera, viewH, sunWorld, dpr) {
+            updateCommon(u, object, camera, dt, viewH, sunWorld, dpr);
+            adaptSlices(u, slices, q.slices);
+            // the hopping grains live within half a tile of the eye, inside the volume
+            grains.visible = layerInReach(u, GRAIN_TILE / 2);
+            const windMs = u.uWindStrength.value * 8;
+            u.uWallPhase.value += dt * u.uSpeed.value * (0.4 + windMs) / 90;
+            u.uGrainPhase.value += dt * u.uSpeed.value * windMs * 0.6;
+        },
+        dispose: function () { slices.geometry.dispose(); slices.material.dispose(); grainGeo.dispose(); grainMat.dispose(); },
+    };
+}
+// =============================================================================
+// Component
+// =============================================================================
+const DEFAULTS = DEFAULT_ENVIRONMENT_OBJECTS.sandstorm;
+/** Knobs that rebuild the object: never live, they change once, on commit. */
+const STRUCTURAL = ['density', 'quality', 'seed'];
+/** Knobs a keyframe or pointer binding may drive per frame — exactly what applyConfig pushes. */
+const ANIMATABLE = new Set(ENVIRONMENT_OBJECTS_ANIMATABLE.sandstorm.map((p) => p.value));
+/** The scene's sky fill is brighter than the medium's own ambient term expects. */
+const SKY_FILL = 0.5;
+/**
+ * A haboob: billowing dust under a scale-height profile, gust fronts that roll downwind as towering walls, and saltating grains streaking along the ground, lit by forward-scattered sun. The cursor is a windbreak, a dust devil or a gust. Use for desert, ash and Mars scenes.
+ *
+ * The volume is the parent's transform: x / z span its scale, y rises from its origin to scale.y.
+ */
+const Sandstorm = ({ config, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) => {
+    const rootRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const cfg = useMemo(() => withConfigDefaults(DEFAULTS, config), [config]);
+    // uniforms outlive rebuilds, so phases and keyframes survive a structural change
+    const uniforms = useMemo(() => createUniforms(), []);
+    const instance = useMemo(() => build(uniforms, cfg), [uniforms, cfg.density, cfg.quality, cfg.seed]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => () => instance.dispose(), [instance]);
+    useLayoutEffect(() => { applyConfig(uniforms, cfg); }, [uniforms, cfg]);
+    const push = useCallback((merged) => { applyConfig(uniforms, merged); }, [uniforms]);
+    useConfigDriver({ rootRef, id, family: 'environment', base: cfg, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+    const pointer = usePointerField();
+    // the scene's sun, read-only: the same one the clouds, the water and the key light use
+    const sun = useCloudSun();
+    const anchor = useMemo(() => new THREE.Vector3(), []);
+    const buffer = useMemo(() => new THREE.Vector2(), []);
+    useFrame((state, delta) => {
+        const dt = Math.min(delta, 0.1);
+        const s = sun.update();
+        uniforms.uSunColor.value.copy(s.color);
+        uniforms.uSkyAmbient.value.copy(s.skyAmbient).multiplyScalar(SKY_FILL);
+        state.gl.getDrawingBufferSize(buffer);
+        instance.update(dt, state.camera, buffer.y, s.direction, state.viewport.dpr);
+        stepPointerField(uniforms, pointer, state.camera, instance.object, 1, dt, pointerAnchor(instance.object, state.camera, uniforms, anchor, 4.5));
+    });
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default Sandstorm;