@3driseai/3drise-viewer 0.1.41 → 0.1.43

package/dist/utils/waterReflection.js

@@ -0,0 +1,616 @@
+import * as THREE from 'three';
+/** 0 off, 1 the sky, 2 the planar target, 3 the baked probe. What the shaders switch on. */
+export const WATER_REFLECTION_UNIFORM = { off: 0, env: 1, planar: 2, baked: 3 };
+/**
+ * When a planar mirror is worth rendering for a placed body: it must be on
+ * screen and not hidden (the occlusion query), and big enough on screen that a
+ * mirrored scene reads differently from the sky. Below ~0.5 % of the view a
+ * pond far away or seen edge-on shows the sky either way, so it gets the sky
+ * (free). Measured as the solid angle the water subtends — area x |height| /
+ * distance³ for a horizontal patch — with hysteresis so it does not flicker on
+ * the threshold.
+ */
+const COVERAGE_ON = 0.008; // steradians (~0.5 % of a 50 deg 16:9 view)
+const COVERAGE_OFF = 0.005;
+const eligible = new WeakMap();
+/**
+ * Where the camera that actually draws the frame is. The studio renders with
+ * its own view camera, which is not R3F's `state.camera` (that one can sit
+ * anywhere — the authored pose), so the election must not measure from it.
+ * Noted by every water surface as it is drawn (onBeforeRender, outside a mirror
+ * pass); the election, which runs before the next render, reads it.
+ */
+const _viewer = new THREE.Vector3();
+let viewerKnown = false;
+export function noteWaterViewer(camera) {
+    if (mirrorPass)
+        return;
+    _viewer.setFromMatrixPosition(camera.matrixWorld);
+    viewerKnown = true;
+}
+/** The view camera's position as last noted, or null before the first draw. */
+export function waterViewerPosition() {
+    return viewerKnown ? _viewer : null;
+}
+const surfaces = new Map();
+let electedId = null;
+let electedAt = -1;
+const _pos = new THREE.Vector3();
+const _scl = new THREE.Vector3();
+/** Register a surface for the per-frame election. Returns the unregister. */
+export function registerWaterSurface(surface) {
+    surfaces.set(surface.id, surface);
+    return () => {
+        surfaces.delete(surface.id);
+        if (electedId === surface.id)
+            electedId = null;
+    };
+}
+/**
+ * Which surface owns the reflection this frame. Computed once per frame (keyed
+ * on the frame clock, which R3F advances once before any useFrame runs), so every
+ * surface asking in the same frame gets the same answer.
+ */
+export function electedWaterSurface(state) {
+    const t = state.clock.elapsedTime;
+    if (t === electedAt)
+        return electedId;
+    electedAt = t;
+    electedId = null;
+    let best = -1;
+    const cam = viewerKnown ? _viewer : state.camera.position;
+    for (const s of surfaces.values()) {
+        if (s.mode() !== 'planar')
+            continue;
+        if (s.world) {
+            electedId = s.id;
+            return electedId;
+        }
+        // Hidden behind something (or off screen) last frame: no mirror.
+        if (s.visible && !s.visible()) {
+            eligible.set(s, false);
+            continue;
+        }
+        s.object.getWorldPosition(_pos);
+        s.object.getWorldScale(_scl);
+        const [w, d] = s.size();
+        const area = Math.abs(w * _scl.x) * Math.abs(d * _scl.z);
+        const dist = Math.max(_pos.distanceTo(cam), 1e-3);
+        const halfDiag = 0.5 * Math.sqrt(area * 2);
+        const solid = dist <= halfDiag ? Infinity : (area * Math.abs(cam.y - _pos.y)) / (dist * dist * dist);
+        const was = eligible.get(s) ?? false;
+        const on = solid >= (was ? COVERAGE_OFF : COVERAGE_ON);
+        eligible.set(s, on);
+        if (!on)
+            continue;
+        const score = area / (dist * dist);
+        if (score > best) {
+            best = score;
+            electedId = s.id;
+        }
+    }
+    return electedId;
+}
+// -----------------------------------------------------------------------------
+// Visibility: did any of the water's pixels survive the depth test?
+// -----------------------------------------------------------------------------
+/** True while a mirror pass is rendering: queries and nested passes stand down. */
+let mirrorPass = false;
+export function isWaterMirrorPass() { return mirrorPass; }
+/**
+ * A WebGL2 occlusion query around a water body's draw (begin at the end of its
+ * onBeforeRender, end in onAfterRender). The answer arrives a frame or two later
+ * and drives the election: a pond hidden behind the city is drawn (it is in the
+ * view frustum) but none of its pixels pass, so it gets no mirror. A body whose
+ * mesh was not drawn at all last frame (frustum-culled) is not visible either.
+ * WebGL1, or before the first answer: visible.
+ */
+export class WaterVisibility {
+    gl = null;
+    active = null;
+    pending = [];
+    free = [];
+    passed = true;
+    frame = 0;
+    drawnAt = -10;
+    /** Once per frame, before the render (useFrame). */
+    tick() { this.frame++; }
+    /** Visible as of the latest answer, and drawn in the last frame or two. */
+    isVisible() { return this.passed && this.frame - this.drawnAt <= 2; }
+    begin(renderer) {
+        if (mirrorPass || this.active)
+            return;
+        this.drawnAt = this.frame;
+        const gl = renderer.getContext();
+        if (typeof WebGL2RenderingContext === 'undefined' || !(gl instanceof WebGL2RenderingContext))
+            return;
+        this.gl = gl;
+        this.poll();
+        if (this.pending.length >= 4)
+            return; // the GPU is behind; ask again later
+        const q = this.free.pop() ?? gl.createQuery();
+        if (!q)
+            return;
+        gl.beginQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE, q);
+        this.active = q;
+    }
+    end() {
+        if (!this.active || !this.gl)
+            return;
+        this.gl.endQuery(this.gl.ANY_SAMPLES_PASSED_CONSERVATIVE);
+        this.pending.push(this.active);
+        this.active = null;
+    }
+    poll() {
+        const gl = this.gl;
+        if (!gl)
+            return;
+        while (this.pending.length) {
+            const q = this.pending[0];
+            if (!gl.getQueryParameter(q, gl.QUERY_RESULT_AVAILABLE))
+                break;
+            this.passed = !!gl.getQueryParameter(q, gl.QUERY_RESULT);
+            this.free.push(this.pending.shift());
+        }
+    }
+    dispose() {
+        const gl = this.gl;
+        if (!gl)
+            return;
+        if (this.active) {
+            gl.endQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE);
+            this.active = null;
+        }
+        for (const q of [...this.pending, ...this.free])
+            gl.deleteQuery(q);
+        this.pending.length = 0;
+        this.free.length = 0;
+    }
+}
+// -----------------------------------------------------------------------------
+// The planar pass
+// -----------------------------------------------------------------------------
+const _normal = new THREE.Vector3();
+const _point = new THREE.Vector3();
+const _camPos = new THREE.Vector3();
+const _view = new THREE.Vector3();
+const _target = new THREE.Vector3();
+const _lookAt = new THREE.Vector3();
+const _rot = new THREE.Matrix4();
+const _plane = new THREE.Plane();
+const _clip = new THREE.Vector4();
+const _q = new THREE.Vector4();
+const _size = new THREE.Vector2();
+const _origin = new THREE.Vector3(0, 0, 0);
+const _up = new THREE.Vector3(0, 1, 0);
+const _forward = new THREE.Vector3(0, 0, -1);
+const _corner = new THREE.Vector3();
+/** Margin around the water's screen rectangle, in NDC: room for the ripple
+ *  distortion of the lookup and for the waves standing above the flat plane. */
+const RECT_MARGIN = 0.08;
+/**
+ * Mirrors the camera about a horizontal plane and renders the scene into a
+ * target (the three.js Reflector construction: mirrored camera, oblique near
+ * plane so nothing under the water leaks into the mirror, bias matrix so the
+ * fragment shader can project a world position straight into the texture).
+ */
+export class PlanarReflector {
+    target;
+    textureMatrix = new THREE.Matrix4();
+    camera = new THREE.PerspectiveCamera();
+    rendering = false;
+    /** Scratch for the outline clip (4 corners in, at most 8 points out). */
+    viewPts = Array.from({ length: 4 }, () => new THREE.Vector3());
+    clipped = Array.from({ length: 8 }, () => new THREE.Vector3());
+    /** True after a pass this frame actually drew; false when the camera was
+     *  under the plane and the target holds nothing to sample. */
+    valid = false;
+    constructor() {
+        this.target = new THREE.WebGLRenderTarget(256, 256, {
+            minFilter: THREE.LinearFilter,
+            magFilter: THREE.LinearFilter,
+            depthBuffer: true,
+            stencilBuffer: false,
+        });
+    }
+    dispose() { this.target.dispose(); }
+    /**
+     * @param hide   the water mesh (or its root) — invisible while the mirror renders
+     * @param point  a world point on the water plane (the body's root position)
+     * @param scale  target size as a fraction of the drawing buffer (quality.reflectionScale)
+     * @param corners the water's outline on the plane, world space (a placed body's
+     *        four corners). The mirror is then rendered only for the rectangle they
+     *        cover in the mirror view — a sub-frustum (setViewOffset) and a target
+     *        that size — so everything not reflected in THIS water is frustum-culled
+     *        by the renderer and the target holds no unused pixels. null (the world
+     *        ocean, which covers everything below the horizon) renders the full view.
+     */
+    render(renderer, scene, camera, hide, point, scale, corners = null) {
+        if (this.rendering || scale <= 0) {
+            this.valid = false;
+            return false;
+        }
+        renderer.getDrawingBufferSize(_size);
+        _normal.set(0, 1, 0);
+        _point.copy(point);
+        _camPos.setFromMatrixPosition(camera.matrixWorld);
+        _view.subVectors(_point, _camPos);
+        // Camera under the water: the mirror would show the sky from below.
+        if (_view.dot(_normal) > 0) {
+            this.valid = false;
+            return false;
+        }
+        _view.reflect(_normal).negate().add(_point);
+        _rot.extractRotation(camera.matrixWorld);
+        _lookAt.copy(_forward).applyMatrix4(_rot).add(_camPos);
+        _target.subVectors(_point, _lookAt).reflect(_normal).negate().add(_point);
+        const vc = this.camera;
+        vc.position.copy(_view);
+        vc.up.copy(_up).applyMatrix4(_rot).reflect(_normal);
+        vc.lookAt(_target);
+        const pc = camera;
+        vc.near = pc.near ?? 0.1;
+        vc.far = pc.far ?? 2000;
+        vc.updateMatrixWorld();
+        vc.layers.mask = camera.layers.mask;
+        // The mirror's projection: the main camera's, narrowed to the water's
+        // rectangle when its outline is known (the "reflect only what is seen" cut).
+        let rx = 0, ry = 0, rw = 1, rh = 1;
+        if (pc.isPerspectiveCamera) {
+            vc.fov = pc.fov;
+            vc.aspect = pc.aspect;
+            vc.zoom = pc.zoom;
+            vc.clearViewOffset();
+            vc.updateProjectionMatrix();
+            if (corners) {
+                const rect = this.screenRect(corners);
+                if (rect === 'offscreen') {
+                    this.valid = false;
+                    return false;
+                }
+                if (rect) {
+                    [rx, ry, rw, rh] = rect;
+                    vc.setViewOffset(_size.x, _size.y, rx * _size.x, ry * _size.y, rw * _size.x, rh * _size.y);
+                    vc.updateProjectionMatrix();
+                }
+            }
+        }
+        else {
+            vc.projectionMatrix.copy(camera.projectionMatrix);
+        }
+        // Target: ONE allocation at the frame's size x scale (reallocated only when
+        // the window or the resolution changes — resizing it every frame as the
+        // water's rectangle moves made the reflection hitch). The rectangle is
+        // drawn into its lower-left w x h through viewport + scissor, and the
+        // texture matrix maps into that corner.
+        const W = Math.max(16, Math.round(_size.x * scale));
+        const H = Math.max(16, Math.round(_size.y * scale));
+        if (this.target.width !== W || this.target.height !== H)
+            this.target.setSize(W, H);
+        const w = Math.max(1, Math.min(W, Math.round(W * rw)));
+        const h = Math.max(1, Math.min(H, Math.round(H * rh)));
+        this.target.viewport.set(0, 0, w, h);
+        this.target.scissor.set(0, 0, w, h);
+        this.target.scissorTest = w < W || h < H;
+        const sx = w / W, sy = h / H;
+        // bias * proj * view: world -> texture space ([0, sx] x [0, sy], the drawn corner).
+        this.textureMatrix.set(0.5 * sx, 0.0, 0.0, 0.5 * sx, 0.0, 0.5 * sy, 0.0, 0.5 * sy, 0.0, 0.0, 0.5, 0.5, 0.0, 0.0, 0.0, 1.0);
+        this.textureMatrix.multiply(vc.projectionMatrix).multiply(vc.matrixWorldInverse);
+        // Oblique near plane: clip everything below the water in the mirror view
+        // (Lengyel), so the floor of a pool does not reflect in its own surface.
+        _plane.setFromNormalAndCoplanarPoint(_normal, _point);
+        _plane.applyMatrix4(vc.matrixWorldInverse);
+        _clip.set(_plane.normal.x, _plane.normal.y, _plane.normal.z, _plane.constant);
+        const p = vc.projectionMatrix;
+        _q.x = (Math.sign(_clip.x) + p.elements[8]) / p.elements[0];
+        _q.y = (Math.sign(_clip.y) + p.elements[9]) / p.elements[5];
+        _q.z = -1.0;
+        _q.w = (1.0 + p.elements[10]) / p.elements[14];
+        _clip.multiplyScalar(2.0 / _clip.dot(_q));
+        p.elements[2] = _clip.x;
+        p.elements[6] = _clip.y;
+        p.elements[10] = _clip.z + 1.0;
+        p.elements[14] = _clip.w;
+        // Render, with everything the main pass set put back afterwards.
+        this.rendering = true;
+        mirrorPass = true;
+        const wasVisible = hide.visible;
+        hide.visible = false;
+        const prevTarget = renderer.getRenderTarget();
+        const prevXr = renderer.xr.enabled;
+        const prevShadow = renderer.shadowMap.autoUpdate;
+        const prevAutoClear = renderer.autoClear;
+        renderer.xr.enabled = false;
+        renderer.shadowMap.autoUpdate = false;
+        renderer.autoClear = true;
+        try {
+            renderer.setRenderTarget(this.target);
+            renderer.state.buffers.depth.setMask(true);
+            renderer.render(scene, vc);
+            this.valid = true;
+        }
+        catch {
+            // A disposed material mid-swap throws inside three's caches; the
+            // frame is skipped and the next one resolves it.
+            this.valid = false;
+        }
+        finally {
+            renderer.setRenderTarget(prevTarget);
+            renderer.xr.enabled = prevXr;
+            renderer.shadowMap.autoUpdate = prevShadow;
+            renderer.autoClear = prevAutoClear;
+            hide.visible = wasVisible;
+            this.rendering = false;
+            mirrorPass = false;
+        }
+        return this.valid;
+    }
+    /**
+     * The rectangle the water's outline covers in the mirror view, as fractions
+     * of the frame [x, y (from the top), w, h], grown by RECT_MARGIN; null when it
+     * is most of the frame or a corner is behind the mirror camera (use the full
+     * view), 'offscreen' when none of it is in view.
+     */
+    screenRect(corners) {
+        const vc = this.camera;
+        // The outline in view space, clipped at the near plane (Sutherland-Hodgman
+        // against z = -near): standing on the bank of a long pond, its near corners
+        // are behind the camera, and only the part in front can be in the mirror.
+        const zNear = -vc.near * 1.001;
+        const view = this.viewPts;
+        for (let i = 0; i < corners.length; i++)
+            view[i].copy(corners[i]).applyMatrix4(vc.matrixWorldInverse);
+        let clippedN = 0;
+        for (let i = 0; i < corners.length; i++) {
+            const a = view[i], b = view[(i + 1) % corners.length];
+            const aIn = a.z <= zNear, bIn = b.z <= zNear;
+            if (aIn)
+                this.clipped[clippedN++].copy(a);
+            if (aIn !== bIn) {
+                const t = (zNear - a.z) / (b.z - a.z);
+                this.clipped[clippedN++].copy(a).lerp(b, t);
+            }
+        }
+        if (clippedN === 0)
+            return 'offscreen';
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (let i = 0; i < clippedN; i++) {
+            _corner.copy(this.clipped[i]).applyMatrix4(vc.projectionMatrix);
+            minX = Math.min(minX, _corner.x);
+            maxX = Math.max(maxX, _corner.x);
+            minY = Math.min(minY, _corner.y);
+            maxY = Math.max(maxY, _corner.y);
+        }
+        minX = Math.max(minX - RECT_MARGIN, -1);
+        maxX = Math.min(maxX + RECT_MARGIN, 1);
+        minY = Math.max(minY - RECT_MARGIN, -1);
+        maxY = Math.min(maxY + RECT_MARGIN, 1);
+        if (minX >= maxX || minY >= maxY)
+            return 'offscreen';
+        const w = (maxX - minX) / 2, h = (maxY - minY) / 2;
+        if (w * h > 0.85)
+            return null;
+        return [(minX + 1) / 2, (1 - maxY) / 2, w, h];
+    }
+}
+// -----------------------------------------------------------------------------
+// The baked probe ('baked' mode)
+// -----------------------------------------------------------------------------
+/**
+ * A reflection probe: the scene captured ONCE into a cubemap from just above
+ * the water, and sampled by the water every frame with a texture lookup.
+ *
+ * Why it is cheap: a planar mirror depends on where the camera is, so it must be
+ * re-rendered every frame the camera moves. The probe belongs to the WATER, not
+ * the view — the reflected ray from each fragment is looked up in it — so it
+ * stays valid while the camera moves and costs nothing per frame. It is
+ * re-captured only when it goes stale (the sun turned, the body moved, a slow
+ * refresh for scene edits), one cube face per frame so no frame pays for six.
+ *
+ * Why it is not exact: a cubemap is a picture from one point. The lookup is
+ * parallax-corrected against a sphere around the probe (`radius`), so the bank
+ * and the skyline sit roughly where they should across a large pond, but things
+ * close to the water and far from its centre are slightly off, and anything that
+ * moves is frozen until the next capture. Under ripples this reads the same as
+ * the mirror at a fraction of the cost; calm hero water seen close is what
+ * 'planar' is for. Every baked body has its own probe — no election.
+ */
+export class WaterProbe {
+    size;
+    target;
+    cube;
+    /** Where the last COMPLETE capture was taken: the centre of the lookup. */
+    position = new THREE.Vector3();
+    /** Parallax sphere radius, metres; 0 = everything infinitely far (the world ocean). */
+    radius = 0;
+    /** True once all six faces have been drawn; until then the water shows the sky. */
+    valid = false;
+    /** Next face to draw; 6 = up to date. */
+    face = 6;
+    again = false;
+    pending = new THREE.Vector3();
+    lastPos = new THREE.Vector3(Infinity, Infinity, Infinity);
+    lastSun = new THREE.Vector3();
+    sunScratch = new THREE.Vector3();
+    lastAt = -Infinity;
+    constructor(size) {
+        this.size = size;
+        this.target = new THREE.WebGLCubeRenderTarget(size, {
+            type: THREE.HalfFloatType,
+            generateMipmaps: true,
+            minFilter: THREE.LinearMipmapLinearFilter,
+            magFilter: THREE.LinearFilter,
+        });
+        this.cube = new THREE.CubeCamera(0.5, 10000, this.target);
+    }
+    dispose() { this.target.dispose(); }
+    /**
+     * Once per frame: where the probe should be and what the sun is doing. Marks
+     * the capture stale when the probe moved more than `moveTolerance` metres,
+     * the sun turned more than ~0.5 degrees, or `refreshSec` passed since the last
+     * capture (scene edits). A request while a capture is in flight finishes that
+     * capture first, then starts again.
+     */
+    request(pos, sun, moveTolerance, nowSec, refreshSec = 10) {
+        const moved = this.lastPos.distanceToSquared(pos) > moveTolerance * moveTolerance;
+        // Normalized here: the rendered sky's sun direction is not always unit
+        // length, and a short vector reads as "turned" every frame (a capture
+        // that never stops).
+        const s = sun && sun.lengthSq() > 1e-8 ? this.sunScratch.copy(sun).normalize() : null;
+        const turned = !!s && this.lastSun.dot(s) < SUN_STALE_COS;
+        const old = nowSec - this.lastAt > refreshSec;
+        if (!moved && !turned && !old)
+            return;
+        // At most one capture every MIN_INTERVAL_SEC: with the clock playing fast
+        // the sun turns half a degree every frame, and re-capturing on every one
+        // of them is a face per frame forever (a quarter of the scene, always).
+        if (this.lastAt > -Infinity && nowSec - this.lastAt < MIN_INTERVAL_SEC)
+            return;
+        this.lastPos.copy(pos);
+        if (s)
+            this.lastSun.copy(s);
+        this.lastAt = nowSec;
+        if (this.face < 6) {
+            this.again = true;
+            this.pending.copy(pos);
+            return;
+        }
+        this.pending.copy(pos);
+        this.face = 0;
+    }
+    /** True while faces are still to be drawn. */
+    get stale() { return this.face < 6; }
+    /**
+     * Draw the next stale face (at most one per call; the host calls once per
+     * frame from onBeforeRender). `hide` is the water itself.
+     */
+    step(renderer, scene, hide, layers) {
+        if (this.face >= 6 || mirrorPass)
+            return;
+        const cc = this.cube;
+        if (this.face === 0) {
+            cc.position.copy(this.pending);
+            cc.updateMatrixWorld(true);
+        }
+        if (cc.coordinateSystem !== renderer.coordinateSystem) {
+            cc.coordinateSystem = renderer.coordinateSystem;
+            cc.updateCoordinateSystem();
+            cc.updateMatrixWorld(true);
+        }
+        const cam = cc.children[this.face];
+        cam.layers.mask = layers;
+        mirrorPass = true;
+        const wasVisible = hide.visible;
+        hide.visible = false;
+        const prevTarget = renderer.getRenderTarget();
+        const prevFace = renderer.getActiveCubeFace();
+        const prevMip = renderer.getActiveMipmapLevel();
+        const prevXr = renderer.xr.enabled;
+        const prevShadow = renderer.shadowMap.autoUpdate;
+        const prevAutoClear = renderer.autoClear;
+        renderer.xr.enabled = false;
+        renderer.shadowMap.autoUpdate = false;
+        renderer.autoClear = true;
+        // Mipmaps once, on the last face (the CubeCamera.update trick).
+        this.target.texture.generateMipmaps = this.face === 5;
+        try {
+            renderer.setRenderTarget(this.target, this.face);
+            renderer.state.buffers.depth.setMask(true);
+            renderer.render(scene, cam);
+            this.face++;
+        }
+        catch {
+            // A disposed material mid-swap: try this face again next frame.
+        }
+        finally {
+            this.target.texture.generateMipmaps = true;
+            renderer.setRenderTarget(prevTarget, prevFace, prevMip);
+            renderer.xr.enabled = prevXr;
+            renderer.shadowMap.autoUpdate = prevShadow;
+            renderer.autoClear = prevAutoClear;
+            hide.visible = wasVisible;
+            mirrorPass = false;
+        }
+        if (this.face === 6) {
+            this.valid = true;
+            this.position.copy(cc.position);
+            if (this.again) {
+                this.again = false;
+                this.face = 0;
+            }
+        }
+    }
+}
+/** Shortest time between two captures of one probe, seconds. */
+const MIN_INTERVAL_SEC = 1.5;
+/** Sun movement that makes a capture stale (~0.5 degrees). */
+const SUN_STALE_COS = Math.cos((0.5 * Math.PI) / 180);
+/** Cube face size for a reflection resolution (quality.reflectionScale): 0.5 -> 256. */
+export function waterProbeSize(scale) {
+    const px = Math.max(64, Math.min(1024, 512 * Math.max(scale, 0.1)));
+    return 2 ** Math.round(Math.log2(px));
+}
+/**
+ * Push the reflection state into a water material. `mode` is what the surface
+ * asked for; the pass is only handed over when this surface won the election
+ * and its pass drew, otherwise planar falls back to the sky for this frame.
+ */
+export function applyWaterReflection(uniforms, mode, reflector, probe = null) {
+    if (mode === 'baked') {
+        const ok = !!probe && probe.valid;
+        if (uniforms.u_reflectionMode)
+            uniforms.u_reflectionMode.value = ok ? 3 : 1;
+        if (uniforms.u_reflectionCube)
+            uniforms.u_reflectionCube.value = ok ? probe.target.texture : null;
+        if (ok && uniforms.u_probePos)
+            uniforms.u_probePos.value.copy(probe.position);
+        if (ok && uniforms.u_probeRadius)
+            uniforms.u_probeRadius.value = probe.radius;
+        return;
+    }
+    const planar = mode === 'planar' && !!reflector && reflector.valid;
+    if (uniforms.u_reflectionMode)
+        uniforms.u_reflectionMode.value = planar ? 2 : WATER_REFLECTION_UNIFORM[mode === 'planar' ? 'env' : mode];
+    if (uniforms.u_reflectionMap)
+        uniforms.u_reflectionMap.value = planar ? reflector.target.texture : null;
+    if (uniforms.u_reflectionMatrix && planar)
+        uniforms.u_reflectionMatrix.value.copy(reflector.textureMatrix);
+}
+/** GLSL shared by both water shaders: the three uniforms and the projected sample. */
+export const waterReflectionGlsl = /* glsl */ `
+uniform int u_reflectionMode;        // 0 off, 1 sky, 2 planar target, 3 baked probe
+uniform sampler2D u_reflectionMap;
+uniform mat4 u_reflectionMatrix;
+uniform samplerCube u_reflectionCube;
+uniform vec3 u_probePos;
+uniform float u_probeRadius;         // parallax sphere; 0 = infinitely far
+
+/** The baked probe along the reflected ray. The normal is flattened by
+ *  'distortion' (0 flat, 1 the full ripple) so the probe wobbles like the mirror
+ *  rather than like a physically rough sea. The lookup direction is corrected
+ *  against a sphere around the probe, so a fragment far from the probe still
+ *  sees the bank where it is. Only valid when u_reflectionMode == 3. */
+vec3 waterProbeReflection(vec3 worldPos, vec3 viewDir, vec3 n, float distortion){
+  vec3 nb = normalize(vec3(n.x * distortion, max(n.y, 1e-3), n.z * distortion));
+  vec3 r = reflect(viewDir, nb);
+  r.y = max(r.y, 0.005);
+  r = normalize(r);
+  vec3 dir = r;
+  if (u_probeRadius > 0.0) {
+    vec3 o = worldPos - u_probePos;
+    float b = dot(o, r);
+    float c = dot(o, o) - u_probeRadius * u_probeRadius;
+    dir = o + r * (-b + sqrt(max(b * b - c, 0.0)));
+  }
+  return textureCube(u_reflectionCube, dir).rgb;
+}
+
+/** The mirrored scene at a world point, with the surface normal bending the
+ *  lookup (the ripple distortion). Only valid when u_reflectionMode == 2. */
+vec3 waterPlanarReflection(vec3 worldPos, vec3 n, float distortion){
+  vec4 rc = u_reflectionMatrix * vec4(worldPos, 1.0);
+  vec2 uv = rc.xy / max(rc.w, 1e-4) + n.xz * distortion;
+  uv = clamp(uv, vec2(0.002), vec2(0.998));
+  return texture2D(u_reflectionMap, uv).rgb;
+}
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-viewer",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,7 @@
     "@gsap/react": "^2.1.2",
     "@react-three/drei": "^10",
     "@react-three/fiber": "^9",
+    "@react-three/postprocessing": "^3",
     "@react-three/rapier": "^2",
     "react": "^18 || ^19",
     "three": "^0.170"
@@ -32,14 +33,14 @@
   "devDependencies": {
     "@react-three/drei": "^10.0.0",
     "@react-three/fiber": "^9.0.0",
+    "@react-three/postprocessing": "^3.0.0",
     "@types/react": "^19.0.0",
     "react": "^19.0.0",
     "three": "^0.170.0",
     "typescript": "^5.7.2"
   },
   "dependencies": {
-    "@3driseai/3drise-common": "^1.0.1",
-    "@3driseai/3drise-core": "^1.0.30",
+    "@3driseai/3drise-core": "^1.0.31",
     "three-mesh-bvh": "^0.8.3"
   }
 }