@3driseai/3drise-viewer 0.1.28 → 0.1.29

package/dist/components/environment/Tornado.js

@@ -0,0 +1,762 @@
+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 + tornado.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 },
+        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;
+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;
+    float z0 = uSliceNear * exp(k * t0);
+    float z1 = 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) {
+    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 || 4;
+    const mat = premulMaterial(u, SLICE_VERT, fragmentShader, false);
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.frustumCulled = false;
+    mesh.raycast = function () { };
+    return mesh;
+}
+/** 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);
+}
+`;
+// ---------------------------------------------------------------------------- tornado
+// Tornado — environment object (lab module). Shared core: ./common.mjs.
+// A standalone vortex: no debris particles, no parent cloud — the funnel dissolves into the sky.
+// Construction:
+//   vortex    a Rankine vortex on a wandering axis: solid-body rotation inside the core radius
+//             r_c, v ∝ 1/r outside, so the angular velocity is Ω inside and Ω (r_c / r)² outside.
+//             The foot wanders on slow incommensurate sines and the axis bends like a rope;
+//             the core widens with height.
+//   funnel    condensation where the pressure deficit (r_c / r)² passes a threshold that rises
+//             toward the ground — "reach" lowers the funnel until it touches down.
+//   flow      everything is sampled in the flow's own frame: the angle is advected by ω(r, y)
+//             (differential rotation: the inside spins faster, so streaks wind into spirals) and
+//             the height by the updraft (they climb). Streaks are helical — stretched along a
+//             helix whose pitch is the ratio of updraft to swirl. Winding never runs away: two
+//             copies of the field half a cycle apart are cross-faded with cosine weights
+//             (advected-texture regeneration), so each copy fades out before it resets.
+//   dust      ground dust drawn into the vortex: an inflow layer whose streaks wind into spiral
+//             arms by the same differential rotation, lifted into a sheath that climbs the
+//             outside of the funnel, with fine wisps flung off the sheath.
+//   light     the funnel is a condensation surface — lit on the sun side, sky-lit in shadow;
+//             the dust scatters forward (Henyey–Greenstein, g = 0.5).
+const catalog = {
+    key: 'tornado',
+    name: 'Tornado',
+    description: 'A standalone tornado as a Rankine vortex: a condensation funnel on a wandering, rope-like axis with helical streaks that wind by differential rotation and climb on the updraft, and ground dust spiralling in and swirling up a sheath around it. The cursor steers it, feeds it or bends it with a gust. Use for storm and drama scenes.',
+    tags: ['tornado', 'vortex', 'storm', 'twister', 'weather', 'interactive'],
+    structural: ['density', 'quality', 'seed'],
+    pointerModes: ['steer', 'feed', 'gust'],
+    pointerLabels: ['Steer', 'Feed', 'Gust'],
+    volume: [160, 90, 160],
+    staging: { sky: '#5f6670', ground: '#4f5a44', fog: 0.0028, sunEl: 22, sunAz: 120, inside: [[0, 2, 70], [0, 28, 0]], outside: [[0, 18, 220], [0, 34, 0]] },
+    pointerAhead: 60,
+};
+const QUALITY = { low: 22, medium: 36, high: 52 };
+const REGEN = 8.0; // spin units before a copy of the flow field is regenerated
+function createUniforms() {
+    return Object.assign(createCommonUniforms(), {
+        uSigma: { value: 0.06 },
+        uRotation: { value: 1 },
+        uCore: { value: 1 },
+        uReach: { value: 0.9 },
+        uWander: { value: 0.5 },
+        uLift: { value: 1 },
+        uDust: { value: 1 },
+        uDustSpread: { value: 1 },
+        uDustColor: { value: new THREE.Color('#8a7358') },
+        uSpin: { value: 0 },
+        uRise: { value: 0 },
+        uWanderPhase: { value: 0 },
+        uBase: { value: new THREE.Vector2() },
+        uFeed: { value: 0 },
+        uBend: { value: new THREE.Vector3() },
+    });
+}
+function applyConfig(u, c) {
+    applyCommonConfig(u, c, catalog.pointerModes);
+    if (c.rotation !== undefined)
+        u.uRotation.value = c.rotation;
+    if (c.coreRadius !== undefined)
+        u.uCore.value = c.coreRadius;
+    if (c.reach !== undefined)
+        u.uReach.value = c.reach;
+    if (c.wander !== undefined)
+        u.uWander.value = c.wander;
+    if (c.lift !== undefined)
+        u.uLift.value = c.lift;
+    if (c.dust !== undefined)
+        u.uDust.value = c.dust;
+    if (c.dustSpread !== undefined)
+        u.uDustSpread.value = c.dustSpread;
+    setColor(u.uDustColor, c.dustColor);
+}
+const VORTEX = /* glsl */ `
+uniform float uSigma, uRotation, uCore, uReach, uWander, uLift, uDust, uDustSpread, uSpin, uRise, uWanderPhase, uFeed;
+uniform vec2 uBase;
+uniform vec3 uBend, uDustColor;
+// axis centre at height y (metres): the foot at uBase, rope-like bends, leaning downwind with height
+vec2 axisAt(float y) {
+    float H = uVolume.y, h = clamp(y / H, 0.0, 1.0);
+    vec2 w = vec2(sin(uWanderPhase * 0.31 + h * 2.3) + 0.5 * sin(uWanderPhase * 0.53 + h * 5.1 + 1.7),
+                  cos(uWanderPhase * 0.27 + h * 2.9 + 0.4) + 0.5 * sin(uWanderPhase * 0.47 + h * 4.3));
+    vec2 c = uBase * pow(1.0 - h, 1.3) + w * uWander * 0.1 * H * sin(3.14159 * h * 0.9 + 0.2);
+    c += uWindDir * uWindStrength * 0.15 * H * h * h;
+    c += uBend.xz * exp(-pow((y - uBend.y) / (0.18 * H * max(uPointerRadius, 0.2)), 2.0));
+    return c;
+}
+float coreAt(float y) {
+    float h = clamp(y / uVolume.y, 0.0, 1.0);
+    float r0 = 0.045 * min(uVolume.x, uVolume.z) * uCore * (1.0 + 0.5 * uFeed);
+    return r0 * (0.65 + 0.35 * h + 1.4 * pow(smoothstep(0.55, 1.0, h), 2.0));
+}
+// the flow field seen from the air itself: angle advected by omega(r, y), height by the updraft,
+// streaks stretched along a helix; two regenerating copies, cosine-weighted
+float flow(vec3 p, vec2 c, float r, float rc, float angFreq, float radFreq, float vFreq, float pitch, float seed) {
+    vec2 d = p.xz - c;
+    float phi = atan(d.y, d.x);
+    float omega = 5.0 * (r < rc ? 1.0 : (rc * rc) / (r * r));
+    float up = uLift * (0.6 + 0.8 * exp(-max(r - rc, 0.0) / (2.0 * rc)));
+    float acc = 0.0;
+    for (int k = 0; k < 2; k++) {
+        float t = mod(uSpin + float(k) * ${(REGEN / 2).toFixed(1)}, ${REGEN.toFixed(1)});
+        float w = 0.5 - 0.5 * cos(6.2831853 * t / ${REGEN.toFixed(1)});
+        float a = phi - omega * t;
+        float v = p.y * vFreq - up * uRise * vFreq * 4.0 + a * pitch;   // constant v: a helix
+        vec3 q = vec3(cos(a) * angFreq, v, sin(a) * angFreq) + vec3(r * radFreq) + seed + float(k) * 17.3;
+        acc += w * fbm3(q);
+    }
+    return acc;
+}
+vec4 sliceSample(vec3 p, vec3 rd, float dz) {
+    float H = uVolume.y;
+    float h = p.y / H;
+    vec2 c = axisAt(p.y);
+    float r = length(p.xz - c);
+    float rc = coreAt(p.y);
+    // standalone: the top dissolves into the sky
+    float fade = volumeFade(p, min(10.0, 0.06 * uVolume.x), 0.22 * H);
+    if (fade <= 0.0) return vec4(0.0);
+
+    // The flow field is by far the costliest thing here (two fbm per call, three calls), and most of
+    // the volume is clear air. So first find out, without it, whether anything can be here at all:
+    // the funnel only where the pressure deficit can pass its threshold, the dust only inside its ring.
+
+    // funnel: pressure deficit against a threshold rising toward the ground
+    float reach = clamp(uReach + 0.25 * uFeed, 0.0, 1.2);
+    float thr = mix(0.3, 4.0, pow(clamp(1.0 - h - (reach - 0.5) * 1.1, 0.0, 1.0), 1.5));
+    // the ragged outline moves the radius by at most 0.35 core radii: the deficit is largest there
+    float rIn = max(r - 0.35 * rc, 0.0);
+    bool canFunnel = (rIn < rc ? 2.0 - (rIn * rIn) / (rc * rc) : (rc * rc) / (rIn * rIn)) > thr * 0.75;
+
+    // dust: inflow layer at the ground, a sheath climbing the funnel, clumps and wisps flung round it
+    float spread = uDustSpread * (1.0 + 0.6 * uFeed);
+    float outer = rc * (3.0 + 6.0 * spread);
+    float ring = 0.0, near = 0.0, hp = 0.0;
+    if (uDust > 0.001 && r < outer * 1.2) {
+        ring = smoothstep(0.55 * rc, 1.05 * rc, r) * (1.0 - smoothstep(0.45 * outer, outer, r));
+        near = exp(-max(r - rc, 0.0) / (1.6 * rc));
+        float lift = mix(5.0 + 0.2 * rc, 0.5 * H * uLift, near);
+        hp = exp(-p.y / max(lift, 0.5));
+    }
+    float dustGain = uDust * (1.0 + 0.8 * uFeed) * ring * hp;
+    // without a funnel, dust thinner than the cut below (at its thickest: every clump and wisp) is nothing
+    bool canDust = dustGain > 0.0 && (canFunnel || dustGain * (0.15 + 3.0 + 1.2 * (0.4 + near)) * 0.9 * fade >= 0.003);
+    if (!canFunnel && !canDust) return vec4(0.0);
+
+    float funnel = 0.0;
+    if (canFunnel) {
+        // the condensation surface is ragged: rotating lobes move its outline
+        float s = flow(p, c, r, rc, 0.9, 0.04, 0.12, 0.25, 0.0);
+        float rr = max(r + (s - 0.5) * 0.7 * rc, 0.0);
+        float deficit = rr < rc ? 2.0 - (rr * rr) / (rc * rc) : (rc * rc) / (rr * rr);
+        float edge = smoothstep(thr * 0.75, thr * 1.25, deficit);
+        funnel = edge * (0.2 + 0.8 * smoothstep(0.38, 0.64, s));
+    }
+    float dust = 0.0;
+    if (canDust) {
+        // billowing clumps orbiting at the local angular speed, wound into spiral arms
+        float clumps = smoothstep(0.45, 0.7, flow(p, c, r, rc, 0.7, 0.08, 0.1, 0.35, 31.0));
+        float wisps = smoothstep(0.58, 0.8, flow(p, c, r, rc, 1.8, 0.2, 0.25, 0.5, 71.0));
+        dust = dustGain * (0.15 + 3.0 * clumps + 1.2 * wisps * (0.4 + near));
+    }
+
+    float d = (funnel * 3.0 + dust * 0.9) * fade;
+    if (d < 0.003) return vec4(0.0);
+    float a = 1.0 - exp(-uSigma * d * dz);
+    float sunUp = smoothstep(-0.05, 0.1, uSunDir.y);
+    vec3 nrm = normalize(vec3(p.x - c.x, 0.0, p.z - c.y) + vec3(0.0, 1e-3, 0.0));
+    float lam = 0.45 + 0.55 * dot(nrm, uSunDir);
+    vec3 amb = uSkyAmbient * uShadeColor * 1.3;
+    vec3 sun = uSunColor * sunUp;
+    float dustShare = dust * 0.9 / max(funnel * 3.0 + dust * 0.9, 1e-4);
+    // the foot of the funnel is stained by the dust it is wrapped in
+    float stain = clamp(dustShare + (1.0 - smoothstep(0.0, 0.2, h)) * 0.5, 0.0, 1.0);
+    vec3 funnelCol = mix(uColor, uDustColor, stain * 0.6) * (amb + sun * 0.4 * lam);
+    // dust the cursor feeds in takes the pointer colour
+    vec3 dustCol = mix(uDustColor, uPointerColor, 0.5 * uFeed) * (amb * 1.2 + sun * (0.18 + hgPhase(dot(rd, uSunDir), 0.5) * 0.6));
+    vec3 col = mix(funnelCol, dustCol, dustShare);
+    return vec4(min(col, vec3(1.0)) * a, a);
+}
+`;
+function build(u, c) {
+    u.uSigma.value = 0.06 * Math.max(0.05, c.density ?? 1);
+    // every pixel takes every slice: the funnel's fine rotating structure does not survive interleaving
+    const slices = buildSlices(u, sliceFrag(VORTEX, false), QUALITY[c.quality] || 36, 1);
+    const object = new THREE.Group();
+    object.name = 'tornado';
+    object.add(slices);
+    const target = new THREE.Vector2(), bendTarget = new THREE.Vector3();
+    return {
+        object,
+        materials: [slices.material],
+        apply: function (cfg) { applyConfig(u, cfg); },
+        update: function (dt, camera, viewH, sunWorld, dpr) {
+            updateCommon(u, object, camera, dt, viewH, sunWorld, dpr);
+            const sp = u.uSpeed.value;
+            // spin and updraft integrated on the CPU: animating rotation or lift never jumps
+            u.uSpin.value += dt * sp * u.uRotation.value * (1.0 + 0.4 * u.uFeed.value);
+            u.uRise.value += dt * sp * (1.0 + 0.5 * u.uFeed.value);
+            u.uWanderPhase.value += dt * sp * 0.25;
+            // pointer: steer the foot, feed the inflow, or bend the funnel with a gust
+            const mode = u.uPointerMode.value, act = u.uPointerActive.value * u.uPointerStrength.value;
+            const V = u.uVolume.value, P = u.uPointer.value, PV = u.uPointerVel.value;
+            const lim = 0.35 * Math.min(V.x, V.z);
+            if (mode === 0 && act > 0.001)
+                target.set(P.x * V.x, P.z * V.z).clampLength(0, lim).multiplyScalar(Math.min(act, 1));
+            else
+                target.set(0, 0);
+            const step = Math.min(1, dt * 0.6), maxMove = dt * 9;
+            const dx = (target.x - u.uBase.value.x) * step, dy = (target.y - u.uBase.value.y) * step;
+            const m = Math.hypot(dx, dy), s = m > maxMove ? maxMove / m : 1;
+            u.uBase.value.x += dx * s;
+            u.uBase.value.y += dy * s;
+            const feed = mode === 1 ? Math.min(1, act * (0.5 + 0.08 * PV.length() * V.x)) : 0;
+            u.uFeed.value += (feed - u.uFeed.value) * Math.min(1, dt * (feed > u.uFeed.value ? 1.5 : 0.4));
+            if (mode === 2 && act > 0.001)
+                bendTarget.set(PV.x * V.x * 0.8, P.y * V.y, PV.z * V.z * 0.8);
+            else
+                bendTarget.set(0, u.uBend.value.y, 0);
+            const bl = Math.hypot(bendTarget.x, bendTarget.z), cap = 0.12 * V.x;
+            if (bl > cap) {
+                bendTarget.x *= cap / bl;
+                bendTarget.z *= cap / bl;
+            }
+            const bs = Math.min(1, dt * 1.2);
+            u.uBend.value.x += (bendTarget.x * Math.min(act, 1) - u.uBend.value.x) * bs;
+            u.uBend.value.z += (bendTarget.z * Math.min(act, 1) - u.uBend.value.z) * bs;
+            u.uBend.value.y = bendTarget.y;
+        },
+        dispose: function () { slices.geometry.dispose(); slices.material.dispose(); },
+    };
+}
+// =============================================================================
+// Component
+// =============================================================================
+const DEFAULTS = DEFAULT_ENVIRONMENT_OBJECTS.tornado;
+/** 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.tornado.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 standalone tornado as a Rankine vortex: a condensation funnel on a wandering, rope-like axis with helical streaks that wind by differential rotation and climb on the updraft, and ground dust spiralling in and swirling up a sheath around it. The cursor steers it, feeds it or bends it with a gust. Use for storm and drama scenes.
+ *
+ * The volume is the parent's transform: x / z span its scale, y rises from its origin to scale.y.
+ */
+const Tornado = ({ 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, 60));
+    });
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default Tornado;