@crystaldesign/real-time-viewer-next 26.11.0-beta.18

package/build/esm/WaterSurface-93383fdf.js

@@ -0,0 +1,2041 @@
+import { w as withRenderTarget, s as setCausticReceiversSuspended, a as waterUniforms, d as disableWaterUniforms, u as useRTVStore, F as FRAME_ORDER, c as sunAnglesToDirection, l as lightingSunTowardDirection } from './index-920dd901.js';
+import { useRef, useMemo, useEffect, useCallback } from 'react';
+import { useThree, useFrame } from '@react-three/fiber';
+import { Vector3, WebGLRenderTarget, HalfFloatType, RGBAFormat, LinearFilter, OrthographicCamera, ShaderMaterial, DoubleSide, MeshStandardMaterial, Box3, NoToneMapping, Frustum, Matrix4, Vector4, Vector2, Plane, Scene, Mesh, PlaneGeometry, ClampToEdgeWrapping, UnsignedByteType, MeshBasicMaterial, Color } from 'three';
+import _classCallCheck from '@babel/runtime/helpers/classCallCheck';
+import _createClass from '@babel/runtime/helpers/createClass';
+import _defineProperty from '@babel/runtime/helpers/defineProperty';
+import _toConsumableArray from '@babel/runtime/helpers/toConsumableArray';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import '@crystaldesign/diva-core';
+import '@babel/runtime/helpers/slicedToArray';
+import '@babel/runtime/helpers/asyncToGenerator';
+import '@babel/runtime/regenerator';
+import 'three/examples/jsm/loaders/DRACOLoader.js';
+import 'three/examples/jsm/loaders/GLTFLoader.js';
+import 'zustand';
+import 'zustand/middleware';
+import '@babel/runtime/helpers/typeof';
+import 'postprocessing';
+import '@react-three/drei';
+import '@babel/runtime/helpers/possibleConstructorReturn';
+import '@babel/runtime/helpers/getPrototypeOf';
+import '@babel/runtime/helpers/inherits';
+import 'classnames';
+import 'three-mesh-bvh';
+import '@babel/runtime/helpers/objectWithoutProperties';
+import 'three/examples/jsm/environments/RoomEnvironment.js';
+import 'three/examples/jsm/loaders/RGBELoader.js';
+import 'three/examples/jsm/loaders/EXRLoader.js';
+import '@react-three/postprocessing';
+import '@babel/runtime/helpers/construct';
+import 'detect-gpu';
+
+function _createForOfIteratorHelper$2(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray$2(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t["return"] || t["return"](); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray$2(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray$2(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray$2(r, a) : void 0; } }
+function _arrayLikeToArray$2(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+
+/** Output resolution per side — ~2-4 cm/texel for typical pool footprints. */
+var HEIGHT_MAP_SIZE = 256;
+
+/**
+ * Backstop cadence (frames) for content changes that bump no version —
+ * HQRS geos stream in asynchronously after assembly. One tiny pass every
+ * ~2 s at 60 fps is negligible and guarantees eventual convergence.
+ */
+var REFRESH_INTERVAL_FRAMES = 120;
+
+/**
+ * Capture range above the waterline: rim tops slightly above the water
+ * still register (their overhang shadows the geo beneath) while roofs and
+ * terrace slabs higher up fall outside the near plane.
+ */
+var ABOVE_WATER_MARGIN = 0.3;
+
+/** Capture range below the volume floor. */
+var BELOW_FLOOR_MARGIN = 0.5;
+
+/**
+ * Override-pass vertex shader. MUST use real camera matrices — the
+ * renderer's CPU frustum culling tests mesh bounds against the camera, so
+ * a hand-written gl_Position would cull an arbitrary subset of meshes.
+ */
+var HEIGHT_VERTEX = /* glsl */"\n  uniform vec3 uVolumeCenter;\n  uniform vec3 uPoolHalf;\n  varying float vHeightEncoded;\n  void main() {\n    vec4 worldPosition = vec4(position, 1.0);\n    #ifdef USE_INSTANCING\n      worldPosition = instanceMatrix * worldPosition;\n    #endif\n    worldPosition = modelMatrix * worldPosition;\n    vHeightEncoded = (worldPosition.y - uVolumeCenter.y + uPoolHalf.y) / (3.0 * uPoolHalf.y);\n    gl_Position = projectionMatrix * viewMatrix * worldPosition;\n  }\n";
+var HEIGHT_FRAGMENT = /* glsl */"\n  varying float vHeightEncoded;\n  void main() {\n    gl_FragColor = vec4(vHeightEncoded, 0.0, 0.0, 1.0);\n  }\n";
+
+/** Duck-type guards for renderables that must not draw into the pass. */
+
+var PoolHeightMap = /*#__PURE__*/function () {
+  function PoolHeightMap() {
+    _classCallCheck(this, PoolHeightMap);
+    _defineProperty(this, "rt", void 0);
+    _defineProperty(this, "overrideMaterial", void 0);
+    _defineProperty(this, "camera", void 0);
+    _defineProperty(this, "lastCenter", new Vector3(Infinity, Infinity, Infinity));
+    _defineProperty(this, "lastHalf", new Vector3(0, 0, 0));
+    _defineProperty(this, "lastGeometryVersion", -1);
+    _defineProperty(this, "age", REFRESH_INTERVAL_FRAMES);
+    this.rt = new WebGLRenderTarget(HEIGHT_MAP_SIZE, HEIGHT_MAP_SIZE, {
+      type: HalfFloatType,
+      format: RGBAFormat,
+      depthBuffer: true,
+      stencilBuffer: false,
+      minFilter: LinearFilter,
+      magFilter: LinearFilter
+    });
+
+    // Re-fitted to the volume in `updateCamera` per render; its frustum
+    // culls out-of-volume meshes, roofs (near plane) and terrain (far
+    // plane) for free.
+    this.camera = new OrthographicCamera(-1, 1, 1, -1, 0.01, 1);
+    this.overrideMaterial = new ShaderMaterial({
+      vertexShader: HEIGHT_VERTEX,
+      fragmentShader: HEIGHT_FRAGMENT,
+      uniforms: {
+        uVolumeCenter: {
+          value: new Vector3()
+        },
+        uPoolHalf: {
+          value: new Vector3(1, 1, 1)
+        }
+      },
+      // CAD-exported pool GLBs can carry inconsistent winding; the depth
+      // test keeps the topmost surface regardless, so double-sided is the
+      // safe choice.
+      side: DoubleSide
+    });
+  }
+
+  /** Output texture handle — stable reference across re-renders. */
+  return _createClass(PoolHeightMap, [{
+    key: "texture",
+    get: function get() {
+      return this.rt.texture;
+    }
+
+    /**
+     * Fit the top-down camera to the volume. The axis mapping must reproduce
+     * the read formula `uv = local.xz / (2 * poolHalf.xz) + 0.5`: with
+     * `up = (0, 0, -1)` camera-right is world +X, and the swapped
+     * `top`/`bottom` flip NDC y back to world +Z. Depth increases downward,
+     * so the topmost surface wins the depth test.
+     */
+  }, {
+    key: "updateCamera",
+    value: function updateCamera(volumeCenter, poolHalf) {
+      var cam = this.camera;
+      cam.up.set(0, 0, -1);
+      cam.position.set(volumeCenter.x, volumeCenter.y + ABOVE_WATER_MARGIN, volumeCenter.z);
+      cam.lookAt(volumeCenter.x, volumeCenter.y - poolHalf.y, volumeCenter.z);
+      cam.left = -poolHalf.x;
+      cam.right = poolHalf.x;
+      cam.top = -poolHalf.z;
+      cam.bottom = poolHalf.z;
+      cam.near = 0.01;
+      cam.far = ABOVE_WATER_MARGIN + poolHalf.y + BELOW_FLOOR_MARGIN;
+      cam.updateProjectionMatrix();
+      cam.updateMatrixWorld(true);
+    }
+
+    /**
+     * Re-render the height map when it is stale, otherwise do nothing.
+     * Call once per frame BEFORE `CausticsTexture.render` so the caustics
+     * pass never samples a blank first-frame target.
+     *
+     * @param volumeCenter World-space water-volume center (surface Y).
+     * @param poolHalf     (halfX, depth, halfZ) in world meters.
+     * @param geometryVersion Article + decor version sum — a change forces a render.
+     * @param excluded     Subtrees hidden for the pass (the water group).
+     * @returns true when a render actually happened.
+     */
+  }, {
+    key: "renderIfNeeded",
+    value: function renderIfNeeded(renderer, scene, volumeCenter, poolHalf, geometryVersion, excluded) {
+      var _this = this;
+      this.age += 1;
+      var stale = geometryVersion !== this.lastGeometryVersion || !volumeCenter.equals(this.lastCenter) || !poolHalf.equals(this.lastHalf) || this.age >= REFRESH_INTERVAL_FRAMES;
+      if (!stale) return false;
+      this.overrideMaterial.uniforms.uVolumeCenter.value.copy(volumeCenter);
+      this.overrideMaterial.uniforms.uPoolHalf.value.copy(poolHalf);
+      this.updateCamera(volumeCenter, poolHalf);
+
+      // Hide everything that is not receiving geometry: explicit exclusions,
+      // non-mesh renderables (the override material would rasterize lines /
+      // sprites / points into the map), and non-opaque materials. Same
+      // hide/restore mechanism as SceneCapture.
+      var hidden = [];
+      var _iterator = _createForOfIteratorHelper$2(excluded),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var _obj = _step.value;
+          if (_obj && _obj.visible) {
+            _obj.visible = false;
+            hidden.push(_obj);
+          }
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      scene.traverse(function (node) {
+        var flags = node;
+        if (!node.visible) return;
+        if (flags.isLine || flags.isPoints || flags.isSprite) {
+          node.visible = false;
+          hidden.push(node);
+          return;
+        }
+        if (!flags.isMesh) return;
+        var mesh = node;
+        var material = mesh.material;
+        // Receiving geometry = opaque standard material. `transparent` AND
+        // `transmission` must both be checked — glass/water materials carry
+        // transmission > 0 with transparent still false, and light passes
+        // through them (e.g. the pool article's own water plane, which would
+        // otherwise cap every landing at the waterline).
+        var receives = function receives(m) {
+          if (!(m instanceof MeshStandardMaterial)) return false;
+          if (m.transparent || m.opacity < 1) return false;
+          var transmission = m.transmission;
+          return !(typeof transmission === 'number' && transmission > 0);
+        };
+        var isReceiver = Array.isArray(material) ? material.some(receives) : receives(material);
+        if (!isReceiver) {
+          mesh.visible = false;
+          hidden.push(mesh);
+        }
+      });
+      var prevOverride = scene.overrideMaterial;
+      // A scene background draws its OWN pass: a colour background forces a clear in its own colour,
+      // a texture/cube background draws a mesh flagged `allowOverride: false`. Either paints over the
+      // black clear this encoding depends on, so no-geometry texels stop decoding to the floor plane.
+      var prevBackground = scene.background;
+      try {
+        // Clear color 0 decodes to the floor plane — the no-geometry fallback.
+        withRenderTarget(renderer, {
+          target: this.rt,
+          clearColor: 0x000000,
+          clearAlpha: 1
+        }, function () {
+          renderer.clear(true, true, false);
+          scene.background = null;
+          scene.overrideMaterial = _this.overrideMaterial;
+          renderer.render(scene, _this.camera);
+        });
+      } finally {
+        // Restored here rather than after `renderer.render`: a throw inside the draw would otherwise
+        // leave the height shader as the scene's override material — and the receiving geometry
+        // hidden — for every subsequent frame, since R3F schedules the next frame before running us.
+        scene.overrideMaterial = prevOverride;
+        scene.background = prevBackground;
+        for (var _i = 0, _hidden = hidden; _i < _hidden.length; _i++) {
+          var obj = _hidden[_i];
+          obj.visible = true;
+        }
+      }
+      this.lastCenter.copy(volumeCenter);
+      this.lastHalf.copy(poolHalf);
+      this.lastGeometryVersion = geometryVersion;
+      this.age = 0;
+      return true;
+    }
+  }, {
+    key: "dispose",
+    value: function dispose() {
+      this.rt.dispose();
+      this.overrideMaterial.dispose();
+    }
+  }]);
+}();
+
+function _createForOfIteratorHelper$1(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray$1(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t["return"] || t["return"](); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray$1(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray$1(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray$1(r, a) : void 0; } }
+function _arrayLikeToArray$1(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+
+/** Scratch for the per-mesh world-space bounds test in the cull pass. */
+var _meshWorldBox = new Box3();
+var SceneCapture = /*#__PURE__*/function () {
+  function SceneCapture() {
+    var _opts$format;
+    var opts = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    _classCallCheck(this, SceneCapture);
+    _defineProperty(this, "rt", void 0);
+    /** Drawing-buffer pixel width currently allocated for the RT. */
+    _defineProperty(this, "width", 0);
+    /** Drawing-buffer pixel height currently allocated for the RT. */
+    _defineProperty(this, "height", 0);
+    // Start at 1x1; the host will resize on the first frame via
+    // `resizeIfNeeded` so we never allocate a needlessly-large RT before
+    // the canvas mounts.
+    //
+    // Depth buffer is REQUIRED for opaque depth testing. Without it the
+    // renderer paints meshes in scene-graph / sort order with no Z
+    // comparison, so far geometry overwrites near geometry — e.g. the
+    // far pool wall painted after a nearer underwater mesh ends up
+    // covering it, and the SSR sample shows wall where that mesh
+    // should be. Keep it a PLAIN depth buffer — attaching a sampleable
+    // DepthTexture instead dims the captured colour.
+    this.rt = new WebGLRenderTarget(1, 1, {
+      type: HalfFloatType,
+      format: (_opts$format = opts.format) !== null && _opts$format !== void 0 ? _opts$format : RGBAFormat,
+      depthBuffer: true,
+      stencilBuffer: false,
+      // LinearFilter — the screen UV in the water shader is offset by
+      // sub-pixel amounts to simulate refraction, so we want smooth
+      // interpolation rather than nearest-neighbor blockiness.
+      minFilter: LinearFilter,
+      magFilter: LinearFilter
+    });
+    this.width = 1;
+    this.height = 1;
+  }
+
+  /**
+   * Output texture handle. Stable reference across frames — the
+   * WebGLRenderTarget keeps the same `.texture` even after we render into
+   * it, so consumers can assign this once and stop worrying about
+   * per-frame refreshes (unlike the heightfield ping-pong).
+   */
+  return _createClass(SceneCapture, [{
+    key: "texture",
+    get: function get() {
+      return this.rt.texture;
+    }
+
+    /**
+     * Resize the render target if `(w, h, pr, scale)` differs from the
+     * currently allocated extent. Pass DRAWING-BUFFER pixels (CSS pixels *
+     * pixelRatio). The host typically gets this from `useThree(s => s.size)`
+     * and `renderer.getPixelRatio()`.
+     *
+     * `resolutionScale` renders the capture BELOW the canvas resolution.
+     * Consumers sample it with a normalized UV, so a smaller target costs
+     * nothing but sharpness — and refraction is a blur, so half-res is
+     * effectively free while cutting fill and bandwidth by 4x.
+     *
+     * Returns true when the target was actually reallocated. Its contents
+     * are gone at that point, so a consumer that skips captures on idle
+     * frames must treat this as "must re-capture now".
+     */
+  }, {
+    key: "resizeIfNeeded",
+    value: function resizeIfNeeded(cssWidth, cssHeight, pixelRatio) {
+      var resolutionScale = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 1;
+      var w = Math.max(1, Math.round(cssWidth * pixelRatio * resolutionScale));
+      var h = Math.max(1, Math.round(cssHeight * pixelRatio * resolutionScale));
+      if (w === this.width && h === this.height) return false;
+      this.rt.setSize(w, h);
+      this.width = w;
+      this.height = h;
+      return true;
+    }
+
+    /**
+     * Render `scene` to the offscreen target with `excluded` meshes
+     * temporarily hidden. Renderer state is taken over and put back via
+     * {@link withRenderTarget} so the main R3F render is undisturbed.
+     *
+     * `excluded` is typically `[surfaceMeshRef.current]` so the water
+     * surface excludes itself from the captured scene (otherwise we'd
+     * refract through the water and see... the same water).
+     *
+     * `scissor` (in RENDER-TARGET pixels, GL bottom-left origin) restricts
+     * the pass to the screen region the consumer can actually sample. The
+     * full target is still cleared first, so everything outside the rect
+     * stays at alpha 0 and reads as a miss — exactly like a clipped pixel.
+     *
+     * `cullBox` (world space) hides every Mesh whose world bounds miss the
+     * box for the duration of the pass. The clip planes already discard
+     * out-of-volume FRAGMENTS, but each mesh still costs a draw call and its
+     * full vertex work — for a pool inside a large scene this skips almost
+     * all of it. Caveat: an InstancedMesh is tested by its BASE geometry
+     * bounds, so instanced content meant to appear underwater would be
+     * over-culled (none exists today).
+     */
+  }, {
+    key: "render",
+    value: function render(renderer, scene, camera, excluded, clippingPlanes, scissor, cullBox) {
+      var _this = this;
+      // Hide the requested meshes for the capture pass. Tracked so we can
+      // restore visibility even if the underlying mesh is null on this
+      // frame (defensive — R3F refs can be transiently null around mount).
+      var hidden = [];
+      var _iterator = _createForOfIteratorHelper$1(excluded),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var _obj = _step.value;
+          if (_obj && _obj.visible) {
+            _obj.visible = false;
+            hidden.push(_obj);
+          }
+        }
+
+        // Volume cull — same hide/restore mechanism as `excluded`. Only meshes
+        // that are currently visible are touched so the restore loop can't
+        // accidentally reveal something else's hidden mesh. World matrices are
+        // at worst one frame stale here (the capture runs before the main
+        // render updates them), which the caller's box margin absorbs.
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      if (cullBox) {
+        scene.traverse(function (node) {
+          var mesh = node;
+          if (!mesh.isMesh || !mesh.visible) return;
+          var geometry = mesh.geometry;
+          if (!geometry) return;
+          if (geometry.boundingBox === null) geometry.computeBoundingBox();
+          var bounds = geometry.boundingBox;
+          if (!bounds) return;
+          _meshWorldBox.copy(bounds).applyMatrix4(mesh.matrixWorld);
+          if (!_meshWorldBox.intersectsBox(cullBox)) {
+            mesh.visible = false;
+            hidden.push(mesh);
+          }
+        });
+      }
+
+      // Scissor state lives on the RENDER TARGET, not the renderer: with a
+      // target bound, `setRenderTarget` copies `renderTarget.scissor` /
+      // `.scissorTest` into the GL state and ignores `renderer.setScissor`
+      // entirely (WebGLRenderer.js, the `_currentScissor.copy( renderTarget
+      // .scissor )` branch). So we bind twice — once scissor-free to clear
+      // the whole target, once with the rect to restrict the draw. The
+      // scissor-free state has to be set before the pass binds the target.
+      this.rt.scissorTest = false;
+
+      // The scene background draws its own pass — a colour background forces an opaque clear in its
+      // own colour, a texture/cube background draws a mesh flagged `allowOverride: false`. Either one
+      // lands on top of the `clearAlpha: 0` this capture depends on, so the consumer's "alpha 0 (or
+      // near-black) = capture miss" test could never fire and the refraction fallback colour was
+      // unreachable. Null it for the pass; restored in the `finally` below.
+      var prevBackground = scene.background;
+      scene.background = null;
+      try {
+        withRenderTarget(renderer, {
+          target: this.rt,
+          // The main R3F render typically uses ACESFilmic or another
+          // tone-mapping curve. For the SSR sample we want the LINEAR colour
+          // of the scene so the water shader's downstream math (Fresnel mix,
+          // waterColor tint) operates in the same space as the rest of the
+          // water uniforms. Tone mapping is re-applied to the FINAL
+          // R3F render — not this intermediate.
+          toneMapping: NoToneMapping,
+          // Clear with transparent black so any pixel the scene doesn't write
+          // (above-horizon sky, off-canvas regions, AND pixels removed by the
+          // water-Y clip plane below) ends up as 0,0,0,0. The shader's alpha
+          // check turns those zero-alpha samples into "capture miss, use the
+          // fallback colour" so refraction never blends in the clipped geo.
+          // Alpha only — the clear colour's RGB is irrelevant at alpha 0 and
+          // leaving it alone keeps the restore to a single property.
+          clearAlpha: 0,
+          // Used by WaterSurfaceRenderer to install a horizontal plane at the
+          // water surface Y: every fragment above water is discarded, leaving
+          // the captured framebuffer alpha=0 in those screen regions. The
+          // surface shader then samples the alpha — if 0 there is no underwater
+          // geo behind this fragment (e.g. a wave crest peeking above the water
+          // line) and we use the refraction fallback colour. This is the only
+          // way to detect screen-space-adjacent-but-3D-far bleed (which a pure
+          // depth ordering test can't catch).
+          clippingPlanes: clippingPlanes
+        }, function () {
+          // Clear BOTH color and depth. Color so any pixel the scene doesn't
+          // write stays alpha=0 for the shader's miss-detect; depth so the
+          // capture pass starts from a fresh Z-buffer each frame (otherwise
+          // stale depth values from the previous capture would block writes
+          // and produce flickering / missing geometry).
+          //
+          // This has to cover the WHOLE target even when a scissor follows —
+          // otherwise the region outside the rect keeps last frame's pixels and
+          // the consumer samples stale geometry instead of detecting a miss.
+          renderer.clear(true, true, false);
+          if (scissor) {
+            _this.rt.scissor.copy(scissor);
+            _this.rt.scissorTest = true;
+            renderer.setRenderTarget(_this.rt);
+          }
+          try {
+            renderer.render(scene, camera);
+          } finally {
+            // Leave the scissor off so the next frame's clear covers everything even if that frame
+            // passes no rect — or if this draw threw, which would otherwise scissor the target
+            // permanently and defeat the alpha-0 miss detection.
+            _this.rt.scissorTest = false;
+          }
+        });
+      } finally {
+        // Restore AFTER the renderer restore so the main R3F render — which runs right after this
+        // useFrame returns — sees the proper scene graph, and in a `finally` so a throw inside the
+        // pass cannot leave the scene half-hidden or without its background.
+        scene.background = prevBackground;
+        for (var _i = 0, _hidden = hidden; _i < _hidden.length; _i++) {
+          var obj = _hidden[_i];
+          obj.visible = true;
+        }
+      }
+    }
+  }, {
+    key: "dispose",
+    value: function dispose() {
+      this.rt.dispose();
+    }
+  }]);
+}();
+
+/**
+ * Capture resolution as a fraction of the canvas drawing buffer.
+ * Refraction is a blur and the shader samples with a normalized UV, so
+ * half-res costs no visible sharpness and quarters fill + bandwidth.
+ */
+var CAPTURE_RESOLUTION_SCALE = 0.5;
+
+/**
+ * Minimum frames between captures while something that affects the capture is
+ * actually changing. MUST stay 1 while the capture is sampled at the live
+ * camera pose: the surface is redrawn every frame, so a capture from an older
+ * pose makes the pool interior visibly lag behind the rim during orbits.
+ * Affordable because the pass is half-res, scissored to the pool's screen rect
+ * and volume-culled — raise it only if pose-lag is an acceptable trade.
+ */
+var CAPTURE_FRAME_INTERVAL = 1;
+
+/**
+ * Frames between captures when nothing we track has changed. The texture
+ * EXCLUDES the water surface (wave motion only moves the sampling UV) and is
+ * rendered with the caustic receivers SUSPENDED, so on a still camera over a
+ * still scene it is identical frame after frame.
+ *
+ * A self-heal interval, not the correctness mechanism — the dirty checks in
+ * `update` are. It bounds how long a mutation we DON'T track (a material
+ * tweak, a lighting slider) can leave the refraction stale.
+ */
+var CAPTURE_IDLE_FRAME_INTERVAL = 15;
+
+/**
+ * Extra world-metre margin above/below the water plane when fitting the
+ * capture's screen rect, so a wave crest (or trough) can't produce fragments
+ * outside the scissored region.
+ */
+var CAPTURE_WAVE_MARGIN = 0.4;
+
+/**
+ * Extra world-metre margin on the capture's SIDE clip planes. Pool geo at the
+ * basin edge (stair blocks, benches) pokes slightly outside the water
+ * footprint; clipping it makes those pixels capture misses that render as
+ * dark fallback-color patches.
+ */
+var CAPTURE_XZ_MARGIN = 0.25;
+
+/**
+ * Screen-UV padding on the scissor rect. Covers the camera motion on the
+ * frames BETWEEN two captures: the surface is redrawn every frame, so without
+ * this its leading edge would drift outside the stale rect during an orbit and
+ * sample the cleared (miss) region for a frame.
+ */
+var CAPTURE_SCISSOR_MOTION_PAD_UV = 0.03;
+
+/**
+ * Tolerance for "the camera did not move". Damped orbit controls approach
+ * their target asymptotically, so an exact matrix compare could stay
+ * marginally dirty forever; 1e-6 on view-projection elements is far below a
+ * sub-pixel change at any sane scene scale.
+ */
+var CAPTURE_VIEW_EPSILON = 1e-6;
+
+/** Scratch state for the per-frame capture bookkeeping. */
+var CAPTURE_BOX = new Box3();
+var CAPTURE_FRUSTUM = new Frustum();
+var CAPTURE_VIEW_PROJ = new Matrix4();
+var CAPTURE_SCISSOR = new Vector4();
+var CAPTURE_CORNER = new Vector4();
+var CAPTURE_DRAWING_BUFFER = new Vector2();
+/**
+ * Capture-throttle decision. A reallocated target is blank, so it can't wait
+ * out an interval — the surface would sample the cleared texture and flash
+ * the refraction fallback colour.
+ */
+function isCaptureDue(framesSinceCapture, dirty, targetResized) {
+  return targetResized || framesSinceCapture >= (dirty ? CAPTURE_FRAME_INTERVAL : CAPTURE_IDLE_FRAME_INTERVAL);
+}
+var RefractionCapture = /*#__PURE__*/function () {
+  function RefractionCapture() {
+    _classCallCheck(this, RefractionCapture);
+    _defineProperty(this, "capture", new SceneCapture());
+    /**
+     * Six planes installed on the renderer ONLY during the capture pass, so
+     * EVERY fragment outside the water volume — above water, below the pool
+     * floor, beside the pool — is discarded and the surface shader can detect
+     * the resulting alpha=0 pixels as capture misses.
+     *
+     * Three.js keeps a point P iff `dot(normal, P) + constant >= 0`, so every
+     * plane here points INWARD. Allocated once and mutated per frame;
+     * SceneCapture saves and restores `renderer.clippingPlanes` so they never
+     * leak into the main R3F render.
+     */
+    _defineProperty(this, "clipPlanes", [new Plane(new Vector3(-1, 0, 0), 0),
+    // right  face (normal points -X)
+    new Plane(new Vector3(1, 0, 0), 0),
+    // left   face (normal points +X)
+    new Plane(new Vector3(0, -1, 0), 0),
+    // top    face (normal points -Y)
+    new Plane(new Vector3(0, 1, 0), 0),
+    // bottom face (normal points +Y)
+    new Plane(new Vector3(0, 0, -1), 0),
+    // front  face (normal points -Z)
+    new Plane(new Vector3(0, 0, 1), 0) // back   face (normal points +Z)
+    ]);
+    /**
+     * Frames since the last capture, and the state that capture was taken with.
+     * Together they answer "is the texture we already have still a correct
+     * picture of the scene?". Starts due so the first frame captures.
+     */
+    _defineProperty(this, "framesSinceCapture", CAPTURE_IDLE_FRAME_INTERVAL);
+    _defineProperty(this, "capturedViewProj", new Matrix4());
+    _defineProperty(this, "capturedBox", new Box3());
+    _defineProperty(this, "capturedGeometryVersion", -1);
+  }
+  return _createClass(RefractionCapture, [{
+    key: "texture",
+    get: function get() {
+      return this.capture.texture;
+    }
+
+    /**
+     * Publish the refraction uniforms and re-render the capture if it is stale
+     * and the water is on screen. Call once per frame from the water frame
+     * stage, after the heightfield/caustics passes and before the composite.
+     */
+  }, {
+    key: "update",
+    value: function update(frame) {
+      var renderer = frame.renderer,
+        camera = frame.camera,
+        material = frame.material,
+        volumeCenter = frame.volumeCenter,
+        poolHalf = frame.poolHalf;
+
+      // The renderer's drawing-buffer size = CSS size × pixelRatio; SceneCapture
+      // does that multiplication so it can decide whether a real resize is needed.
+      var targetResized = this.capture.resizeIfNeeded(frame.cssWidth, frame.cssHeight, renderer.getPixelRatio(), CAPTURE_RESOLUTION_SCALE);
+      material.uniforms.uSceneColor.value = this.capture.texture;
+
+      // uResolution is the INVERSE of the MAIN drawing-buffer extent — NOT the
+      // capture's. The shader builds its UV from `gl_FragCoord`, which is in
+      // canvas pixels when the surface is drawn; the UV is normalized, so a
+      // lower-resolution capture samples correctly and only costs sharpness.
+      renderer.getDrawingBufferSize(CAPTURE_DRAWING_BUFFER);
+      material.uniforms.uResolution.value.set(1 / Math.max(1, CAPTURE_DRAWING_BUFFER.x), 1 / Math.max(1, CAPTURE_DRAWING_BUFFER.y));
+
+      // Clip-plane constants for the current volume. With inward-pointing
+      // normals the constant is the box bound projected onto the negated normal:
+      //   right face  at x = cx + hX, normal (-1,0,0): constant = cx + hX
+      //   left face   at x = cx - hX, normal (+1,0,0): constant = hX - cx
+      //   top face    at y = cy,      normal (0,-1,0): constant = cy
+      //   bottom face at y = cy - hY, normal (0,+1,0): constant = hY - cy
+      //   front face  at z = cz + hZ, normal (0,0,-1): constant = cz + hZ
+      //   back face   at z = cz - hZ, normal (0,0,+1): constant = hZ - cz
+      var cx = volumeCenter.x;
+      var cy = volumeCenter.y;
+      var cz = volumeCenter.z;
+      var hX = poolHalf.x + CAPTURE_XZ_MARGIN;
+      var hY = poolHalf.y;
+      var hZ = poolHalf.z + CAPTURE_XZ_MARGIN;
+      this.clipPlanes[0].constant = cx + hX;
+      this.clipPlanes[1].constant = hX - cx;
+      this.clipPlanes[2].constant = cy;
+      this.clipPlanes[3].constant = hY - cy;
+      this.clipPlanes[4].constant = cz + hZ;
+      this.clipPlanes[5].constant = hZ - cz;
+
+      // Water volume in world space, with a margin for wave displacement.
+      // Doubles as the frustum-cull test and the source of the scissor rect.
+      CAPTURE_BOX.min.set(cx - hX, cy - hY - CAPTURE_WAVE_MARGIN, cz - hZ);
+      CAPTURE_BOX.max.set(cx + hX, cy + CAPTURE_WAVE_MARGIN, cz + hZ);
+
+      // The camera's world matrix is still last frame's at this point in the
+      // frameloop (`useCameraSmoothing` moved it at priority 1 and only
+      // `renderer.render` refreshes it), so bring it current before deriving the
+      // frustum — otherwise the scissor lags a frame behind the orbit.
+      camera.updateMatrixWorld();
+      CAPTURE_VIEW_PROJ.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+      CAPTURE_FRUSTUM.setFromProjectionMatrix(CAPTURE_VIEW_PROJ);
+
+      // Does the texture we already hold still depict the scene correctly? It
+      // excludes the water and suspends the receiver caustics, so neither waves
+      // nor the dancing light invalidate it — only a moved camera, a moved
+      // volume, or changed scene content does.
+      var dirty = frame.sceneMutating || frame.geometryVersion !== this.capturedGeometryVersion || !CAPTURE_BOX.equals(this.capturedBox) || !matricesApproxEqual(CAPTURE_VIEW_PROJ, this.capturedViewProj, CAPTURE_VIEW_EPSILON);
+      this.framesSinceCapture += 1;
+      if (!isCaptureDue(this.framesSinceCapture, dirty, targetResized)) return;
+      // Off-frustum deliberately does NOT reset the age, so the capture
+      // refreshes on the first frame the water comes back into view.
+      if (!CAPTURE_FRUSTUM.intersectsBox(CAPTURE_BOX)) return;
+
+      // Restrict the pass to the water's screen footprint plus the camera-motion
+      // pad. Refraction is flat, so the shader samples the surface's own screen
+      // UV and needs no displacement pad on top of that.
+      var fitted = fitScissorToBox(CAPTURE_BOX, CAPTURE_VIEW_PROJ, this.capture.width, this.capture.height, CAPTURE_SCISSOR_MOTION_PAD_UV, CAPTURE_SCISSOR);
+
+      // Receivers are suspended for the capture: their caustic term animates
+      // every frame, which would (a) get double-applied once the surface shader
+      // composites the live pattern onto the sample and (b) make a still scene's
+      // captures differ frame to frame, defeating the idle throttle. CAPTURE_BOX
+      // doubles as the volume cull so only pool-intersecting meshes are drawn.
+      setCausticReceiversSuspended(true);
+      try {
+        this.capture.render(renderer, frame.scene, camera, [frame.surfaceMesh], this.clipPlanes, fitted ? CAPTURE_SCISSOR : null, CAPTURE_BOX);
+      } finally {
+        // A module singleton shared by every receiver program: a throw inside the capture would gate
+        // their caustics off for the rest of the session.
+        setCausticReceiversSuspended(false);
+      }
+      this.framesSinceCapture = 0;
+      this.capturedViewProj.copy(CAPTURE_VIEW_PROJ);
+      this.capturedBox.copy(CAPTURE_BOX);
+      this.capturedGeometryVersion = frame.geometryVersion;
+    }
+  }, {
+    key: "dispose",
+    value: function dispose() {
+      this.capture.dispose();
+    }
+  }]);
+}();
+
+/** Element-wise matrix compare with a tolerance. */
+function matricesApproxEqual(a, b, epsilon) {
+  var ae = a.elements;
+  var be = b.elements;
+  for (var i = 0; i < 16; i++) {
+    if (Math.abs(ae[i] - be[i]) > epsilon) return false;
+  }
+  return true;
+}
+
+/**
+ * Fit `box`'s screen-space extent into `out` (render-target pixels, GL
+ * bottom-left origin), padded by `marginUV` in each axis to cover the camera
+ * motion between two captures.
+ *
+ * Returns false when the box straddles the camera plane — a corner with
+ * w <= 0 projects to garbage, so the caller must fall back to capturing the
+ * full target rather than trusting a bogus rect.
+ */
+function fitScissorToBox(box, viewProj, width, height, marginUV, out) {
+  var minX = Infinity;
+  var minY = Infinity;
+  var maxX = -Infinity;
+  var maxY = -Infinity;
+  for (var i = 0; i < 8; i++) {
+    CAPTURE_CORNER.set(i & 1 ? box.max.x : box.min.x, i & 2 ? box.max.y : box.min.y, i & 4 ? box.max.z : box.min.z, 1).applyMatrix4(viewProj);
+    if (CAPTURE_CORNER.w <= 1e-6) return false;
+    var ndcX = CAPTURE_CORNER.x / CAPTURE_CORNER.w;
+    var ndcY = CAPTURE_CORNER.y / CAPTURE_CORNER.w;
+    if (ndcX < minX) minX = ndcX;
+    if (ndcX > maxX) maxX = ndcX;
+    if (ndcY < minY) minY = ndcY;
+    if (ndcY > maxY) maxY = ndcY;
+  }
+
+  // NDC [-1, 1] → pixels. The margin is in UV units (the shader offsets a
+  // normalized UV), so it scales by the target extent. +1 px covers the
+  // LinearFilter tap at the edge.
+  var padX = marginUV * width + 1;
+  var padY = marginUV * height + 1;
+  var x0 = Math.max(0, Math.floor((minX * 0.5 + 0.5) * width - padX));
+  var y0 = Math.max(0, Math.floor((minY * 0.5 + 0.5) * height - padY));
+  var x1 = Math.min(width, Math.ceil((maxX * 0.5 + 0.5) * width + padX));
+  var y1 = Math.min(height, Math.ceil((maxY * 0.5 + 0.5) * height + padY));
+  if (x1 <= x0 || y1 <= y0) return false;
+  out.set(x0, y0, x1 - x0, y1 - y0);
+  return true;
+}
+
+/*
+ * Water-surface shaders — port of evanw/webgl-water `renderer.js` (the
+ * realistic-water demo), refactored to operate ENTIRELY in WORLD METERS (no
+ * normalized-pool space inside the shaders).
+ *
+ * https://github.com/evanw/webgl-water/blob/master/renderer.js
+ *
+ * --- Coordinate system ---
+ *
+ *   All `vWaterPos`, `point`, `eye`, `light`, etc. inside the
+ *   shaders are in WORLD METERS, in the pool's local frame (origin at the
+ *   water-surface centre, +Y up). The mapping to the demo's normalized
+ *   `[-1, +1]³` cube is:
+ *
+ *       world.xz = normalized.xz * uPoolHalf.xz
+ *       world.y  = normalized.y  * uPoolHalf.y     (negative = below surface)
+ *
+ *   Hardcoded `±1` / `poolHeight = 1` literals from the demo have all been
+ *   replaced with `uPoolHalf.{x,y,z}` (the pool's world half-extents — note
+ *   `.y` is the FULL depth, since Y is asymmetric: surface at 0, floor at
+ *   `-uPoolHalf.y`).
+ *
+ *   The "rim height" literal `2.0/12.0` (= `poolHeight / 6.0` in the demo)
+ *   becomes `uPoolHalf.y / 6.0`.
+ *
+ * --- Substitutions from the upstream GLSL ---
+ *
+ *   1. `texture2D(tiles, ...)` → `uWallColor` flat-color uniform (the pool
+ *      carries no tile texture). Everything else in `getWallColor` (caustics
+ *      multiplier, AO falloff, rim shadow) is preserved.
+ *
+ *   2. `textureCube(sky, ray).rgb` → `sampleProceduralSky(ray)`.
+ *      We don't have a scene cubemap. `sampleProceduralSky` is a 2-color
+ *      vertical gradient so the surface still has a sky to reflect into. The
+ *      demo's sun-specular highlight is appended after it, identical to the
+ *      demo.
+ *
+ *   3. `gl_Vertex` / `gl_ModelViewProjectionMatrix` → Three's `position`
+ *      attribute and pre-bound `projectionMatrix * modelViewMatrix`. Two-line
+ *      mechanical rename — no math changed.
+ *
+ *   4. `info.ba *= 0.5` (hard-coded caustic dampening in CAUSTICS_VERTEX)
+ *      → `info.ba *= uCausticIntensity` uniform so the look is tunable per
+ *      scene.
+ *
+ *   6. (new in this refactor) `uPoolHalf : vec3` everywhere; geometry in
+ *      world meters; caustic projection scales by `uPoolHalf.xz` so the
+ *      caustic texture's [-1,+1] clip range maps to the full pool floor.
+ *
+ *   7. Geometry-aware caustics: CAUSTICS_VERTEX `project()` lands rays on
+ *      the real receiving geometry via a top-down height map
+ *      (PoolHeightMap.ts), CAUSTICS_FRAGMENT stores the landing height in
+ *      the blue channel, and consumers (receivers + SSR composite) occlude
+ *      fragments below the surface that caught the light.
+ */
+
+/**
+ * Core block — pasted into EVERY shader here (surface and caustics): the IOR
+ * constants, the uniforms both programs read and `intersectCube`.
+ *
+ * `uPoolHalf` semantics:
+ *   .x — pool half-width  in world meters (X axis half-extent)
+ *   .y — pool full depth  in world meters (distance from water surface to
+ *        floor; water surface lives at local Y = 0, floor at Y = -uPoolHalf.y)
+ *   .z — pool half-length in world meters (Z axis half-extent)
+ */
+var SHADER_CORE = /* glsl */"\n  const float IOR_AIR = 1.0;\n  const float IOR_WATER = 1.333;\n  uniform vec3 light;\n  uniform vec3 uPoolHalf;          // (halfX, depth, halfZ) \u2014 see file header\n  uniform sampler2D water;\n\n  vec2 intersectCube(vec3 origin, vec3 ray, vec3 cubeMin, vec3 cubeMax) {\n    vec3 tMin = (cubeMin - origin) / ray;\n    vec3 tMax = (cubeMax - origin) / ray;\n    vec3 t1 = min(tMin, tMax);\n    vec3 t2 = max(tMin, tMax);\n    float tNear = max(max(t1.x, t1.y), t1.z);\n    float tFar = min(min(t2.x, t2.y), t2.z);\n    return vec2(tNear, tFar);\n  }\n";
+
+/**
+ * GLSL for the decoded receiving-geometry height at a footprint position
+ * (volume-local Y): a `float <name>(vec2 xz)` reading `<sampler>`.
+ *
+ * The clamp keeps landings inside the water column — rim geo above the surface
+ * reads as a waterline hit, and sentinel texels (0 = cleared / no geo) decode to
+ * the analytic volume floor, so an empty map reproduces the flat-floor behaviour.
+ */
+function heightSamplerGLSL(name, sampler) {
+  return /* glsl */"\n  float ".concat(name, "(vec2 xz) {\n    float encoded = texture2D(").concat(sampler, ", xz / (2.0 * uPoolHalf.xz) + 0.5).r;\n    return clamp(encoded * 3.0 * uPoolHalf.y - uPoolHalf.y, -uPoolHalf.y, 0.0);\n  }\n");
+}
+/**
+ * GLSL for landing a straight ray on the pool's receiving geometry by marching
+ * it against the height map (the analytic AABB's faces do not coincide with the
+ * real wall/floor: square box vs rounded pool, stairs, benches).
+ *
+ * `coarseSteps` samples bound the first crossing and 4 bisection steps refine
+ * it; samples past a wall read the high rim value, so the coarse pass cannot
+ * tunnel through. Glancing rays can straddle EVERY coarse sample (stair
+ * envelopes especially) — those fall back to 3 fixed-point iterations onto the
+ * field, which land on the geometry instead of tunneling to the analytic cube
+ * exit (which would store the `b == 0` no-data sentinel).
+ */
+function heightFieldMarchGLSL(_ref) {
+  var name = _ref.name,
+    sampler = _ref.sampler,
+    coarseSteps = _ref.coarseSteps,
+    guardShallowRays = _ref.guardShallowRays;
+  var fixedPoint = ['for (int k = 0; k < 3; k++) {', "  p += ray * ((".concat(sampler, "(p.xz) - p.y) / ray.y);"), '}'];
+  var fallback = guardShallowRays ? ['if (ray.y < -0.001) {'].concat(_toConsumableArray(fixedPoint.map(function (line) {
+    return "  ".concat(line);
+  })), ['}']) : fixedPoint;
+  return /* glsl */"\n  vec3 ".concat(name, "(vec3 origin, vec3 ray) {\n    vec2 t = intersectCube(origin, ray, vec3(-uPoolHalf.x, -uPoolHalf.y, -uPoolHalf.z), vec3(uPoolHalf.x, 2.0 * uPoolHalf.y, uPoolHalf.z));\n    float tEnd = max(t.y, 0.0);\n    float lo = 0.0;\n    float hi = tEnd;\n    bool crossed = false;\n    for (int i = 1; i <= ").concat(coarseSteps, "; i++) {\n      float ti = tEnd * float(i) / ").concat(coarseSteps.toFixed(1), ";\n      vec3 p = origin + ray * ti;\n      if (p.y <= ").concat(sampler, "(p.xz)) {\n        hi = ti;\n        crossed = true;\n        break;\n      }\n      lo = ti;\n    }\n    if (!crossed) {\n      vec3 p = origin + ray * tEnd;\n").concat(fallback.map(function (line) {
+    return "      ".concat(line);
+  }).join('\n'), "\n      return p;\n    }\n    for (int j = 0; j < 4; j++) {\n      float mid = 0.5 * (lo + hi);\n      vec3 pm = origin + ray * mid;\n      if (pm.y <= ").concat(sampler, "(pm.xz)) {\n        hi = mid;\n      } else {\n        lo = mid;\n      }\n    }\n    return origin + ray * (0.5 * (lo + hi));\n  }\n");
+}
+
+/**
+ * Surface-only block — the demo's remaining `helperFunctions` with all
+ * substitutions inline. The caustics programs never call any of it, so they
+ * get `SHADER_CORE` alone and none of these uniforms.
+ */
+var SURFACE_HELPERS = /* glsl */"\n  uniform float uWaterClarity;\n  uniform vec3 uWallColor;         // MOD #1: replaces sampler2D tiles\n  uniform vec3 uSkyHorizonColor;   // MOD #2: drives sampleProceduralSky\n  uniform vec3 uSkyZenithColor;    // MOD #2: drives sampleProceduralSky\n  uniform sampler2D causticTex;\n\n  // MOD #2: replaces textureCube(sky, ray). Two-color vertical gradient.\n  vec3 sampleProceduralSky(vec3 ray) {\n    float t = clamp(ray.y * 0.5 + 0.5, 0.0, 1.0);\n    return mix(uSkyHorizonColor, uSkyZenithColor, pow(t, 1.5));\n  }\n\n  // Sample the heightfield at a WORLD-METER xz position. The heightfield\n  // texture's UV [0, 1]\xB2 spans the full pool footprint [-halfX, +halfX] \xD7\n  // [-halfZ, +halfZ].\n  vec4 sampleWaterAt(vec2 worldXZ) {\n    return texture2D(water, worldXZ / (2.0 * uPoolHalf.xz) + 0.5);\n  }\n\n  // Sample the caustic texture for a point at WORLD-METER position. The\n  // caustic texture indexes by \"where would the light from this point have\n  // come from at the water surface\", projected back along refractedLight.\n  // Mapping mirrors the caustics-vertex gl_Position write:\n  //   clip_xz = 0.75 * (point.xz - point.y * slope) / uPoolHalf.xz\n  // Both vertex and fragment use this identical formula so reading and\n  // writing into the texture are consistent across the full pool.\n  vec4 sampleCausticAt(vec3 point, vec3 refractedLight) {\n    vec2 lookup = (point.xz - point.y * refractedLight.xz / refractedLight.y) / uPoolHalf.xz;\n    return texture2D(causticTex, 0.75 * lookup * 0.5 + 0.5);\n  }\n\n  vec3 getWallColor(vec3 point) {\n    float scale = 0.5;\n\n    vec3 wallColor;\n    vec3 normal;\n    // Wall detection: a tiny relative epsilon (0.1% of pool half-extent) so\n    // we still recognise points sitting exactly on the wall geometry while\n    // being tolerant of floating-point noise in the ray-march hit positions.\n    if (abs(point.x) > uPoolHalf.x * 0.999) {\n      wallColor = uWallColor;                          // MOD #1\n      normal = vec3(-point.x, 0.0, 0.0);\n    } else if (abs(point.z) > uPoolHalf.z * 0.999) {\n      wallColor = uWallColor;                          // MOD #1\n      normal = vec3(0.0, 0.0, -point.z);\n    } else {\n      wallColor = uWallColor;                          // MOD #1\n      normal = vec3(0.0, 1.0, 0.0);\n    }\n\n    scale /= mix(length(point), 1.0, uWaterClarity); /* pool ambient occlusion */\n\n    /* caustics */\n    vec3 refractedLight = -refract(-light, vec3(0.0, 1.0, 0.0), IOR_AIR / IOR_WATER);\n    float diffuse = max(0.0, dot(refractedLight, normal));\n    vec4 info = sampleWaterAt(point.xz);\n    if (point.y < info.r) {\n      vec4 caustic = sampleCausticAt(point, refractedLight);\n      scale += diffuse * caustic.r * 2.0 * caustic.g;\n    } else {\n      /* shadow for the rim of the pool */\n      vec2 t = intersectCube(point, refractedLight, vec3(-uPoolHalf.x, -uPoolHalf.y, -uPoolHalf.z), vec3(uPoolHalf.x, 2.0 * uPoolHalf.y, uPoolHalf.z));\n      diffuse *= 1.0 / (1.0 + exp(-200.0 / (1.0 + 10.0 * (t.y - t.x)) * (point.y + refractedLight.y * t.y - uPoolHalf.y / 6.0)));\n\n      scale += diffuse * 0.5;\n    }\n\n    return wallColor * scale;\n  }\n";
+
+/**
+ * Water surface vertex shader.
+ *
+ * Geometry is pre-rotated into XZ (`rotateX(PI/2)` at construction) so AO
+ * override passes see a horizontal plane. position.xz = pool XZ in world
+ * meters; position.y = 0. Wave height displaces Y.
+ */
+var WATER_SURFACE_VERTEX = /* glsl */"\n  uniform sampler2D water;\n  uniform vec3 uPoolHalf;\n  varying vec3 vWaterPos;\n  void main() {\n    vec4 info = texture2D(water, position.xz / (2.0 * uPoolHalf.xz) + 0.5);\n    vWaterPos = vec3(position.x, info.r, position.z);\n    gl_Position = projectionMatrix * modelViewMatrix * vec4(position.x, info.r, position.z, 1.0);\n  }\n";
+
+/** Water surface fragment shader — above-water branch. */
+var WATER_SURFACE_FRAGMENT_ABOVE = /* glsl */"\n  ".concat(SHADER_CORE, "\n  ").concat(SURFACE_HELPERS, "\n  uniform vec3 eye;\n  // Screen-space refraction inputs. The host renders the scene minus the\n  // water surface itself to uSceneColor once per frame (SceneCapture.ts);\n  // the surface then samples that texture at its own screen UV. This\n  // replaces the demo's in-shader intersectCube + getWallColor AABB\n  // raytrace so the underwater view shows the ACTUAL pool geo in the scene.\n  uniform sampler2D uSceneColor;\n  uniform vec2 uResolution;\n  uniform float uUseScreenSpaceRefraction;\n  uniform vec3 uRefractionFallbackColor;\n  // Grazing-angle ceiling of the Schlick fresnel, in [fresnelBase, 1.0]. The\n  // standard formula reaches 1.0 at cosI = 0, which on steep wave fronts reads\n  // as harsh bright streaks (env.water.fresnelMax).\n  uniform float uFresnelMax;\n  // MOD #7 debug views (0 in production):\n  //   4 = LANDING \u2014 ramp of the landing height the caustic composite\n  //       anchors to at this pixel (caustic texture .b at the marched\n  //       view-ray hit). Downstream of the height map AND caustics pass.\n  //   5 = HEIGHTMAP \u2014 the raw PoolHeightMap capture painted over the pool\n  //       footprint. Upstream: exactly what the top-down pass recorded.\n  uniform float uCausticDebugMode;\n  // Pool receiving-geometry height map (PoolHeightMap.ts) \u2014 PRODUCTION\n  // input: the SSR composite marches the view ray against it to find the\n  // displayed wall/floor point. Also drives debug view 5.\n  uniform sampler2D uPoolHeightMap;\n  varying vec3 vWaterPos;\n\n  // Landing-height debug ramp. Magenta = no data (encoded 0: cleared height\n  // map texel, or a caustic ray that landed at the analytic volume floor);\n  // blue = volume floor, green = mid-depth, red = waterline.\n  vec3 rtvLandingRamp(float encoded) {\n    if (encoded < 0.002) return vec3(1.0, 0.0, 1.0);\n    float t = clamp(encoded * 3.0, 0.0, 1.0);\n    return t < 0.5 ? mix(vec3(0.0, 0.2, 1.0), vec3(0.0, 1.0, 0.2), t * 2.0) : mix(vec3(0.0, 1.0, 0.2), vec3(1.0, 0.1, 0.0), t * 2.0 - 1.0);\n  }\n\n  ").concat(heightSamplerGLSL('rtvSampleHeight', 'uPoolHeightMap'), "\n\n  // Height-field normal from central differences. Steep wall bands in the\n  // map tilt it toward horizontal, so walls get a proper light-incidence\n  // term without any analytic-AABB face detection.\n  vec3 rtvHeightFieldNormal(vec2 xz) {\n    float eps = uPoolHalf.x / 128.0;\n    float hxp = rtvSampleHeight(xz + vec2(eps, 0.0));\n    float hxm = rtvSampleHeight(xz - vec2(eps, 0.0));\n    float hzp = rtvSampleHeight(xz + vec2(0.0, eps));\n    float hzm = rtvSampleHeight(xz - vec2(0.0, eps));\n    return normalize(vec3(hxm - hxp, 2.0 * eps, hzm - hzp));\n  }\n\n  /* MOD #7 \u2014 find the displayed geometry point along the straight view ray by\n     marching it against the pool height map. Runs per FRAGMENT, hence the\n     coarser 12-step pass; see heightFieldMarchGLSL for the algorithm. */\n  ").concat(heightFieldMarchGLSL({
+  name: 'rtvMarchViewRay',
+  sampler: 'rtvSampleHeight',
+  coarseSteps: 12,
+  guardShallowRays: true
+}), "\n\n  /*\n   * Screen-space refraction sampler.\n   *\n   * gl_FragCoord.xy * uResolution (with uResolution = 1/drawingBuffer)\n   * gives the current fragment's screen UV \u2014 the same UV the SceneCapture\n   * target was written with, and the UV we sample at. Refraction is flat:\n   * the sample is never displaced by the wave normal.\n   *\n   * The SceneCapture pass clips everything outside the water bbox via\n   * six clipping planes installed on the renderer, so any fragment of\n   * geometry that sits outside the water volume (above, below, beside\n   * the pool) is discarded \u2014 those screen pixels stay at the cleared\n   * alpha = 0 in the capture.\n   *\n   * When the sample is alpha=0 (or near-black, since a cleared capture\n   * pixel reads as opaque-but-zero on some drivers) \u2014 a tall wave crest\n   * peeking above the original waterline, so behind it on screen there's\n   * no captured geo \u2014 return uRefractionFallbackColor, a host-configurable\n   * deep-water tint surfaced as a Leva colour picker.\n   */\n  // Treat cleared / clipped capture pixels as a miss even if alpha is wrong.\n  bool rtvSceneCaptureMissed(vec4 s) {\n    return s.a < 0.5 || (s.r + s.g + s.b) < 0.02;\n  }\n\n  vec3 sampleScreenSpaceRefraction(vec3 viewRay, vec3 waterColor) {\n    vec2 sampleUV = gl_FragCoord.xy * uResolution;\n    vec4 sceneSample = texture2D(uSceneColor, sampleUV);\n\n    // Live caustic composite. The capture is rendered with the caustic\n    // receivers SUSPENDED (see setCausticReceiversSuspended) so still-scene\n    // captures stay byte-identical for the throttle; the animated caustic\n    // term is applied here every frame instead.\n    //\n    // MOD #7 \u2014 the hit marches the STRAIGHT view ray, not the refracted\n    // one: the capture is an unrefracted straight-view render sampled at\n    // the fragment's own screen UV, so the geometry displayed at this\n    // fragment lies along the camera ray.\n    float causticBoost = 1.0;\n    vec3 refractedLight = -refract(-light, vec3(0.0, 1.0, 0.0), IOR_AIR / IOR_WATER);\n    vec3 hit = rtvMarchViewRay(vWaterPos, viewRay);\n    vec3 hitNormal = rtvHeightFieldNormal(hit.xz);\n    float diffuseTerm = max(0.0, dot(refractedLight, hitNormal));\n    vec4 info = sampleWaterAt(hit.xz);\n    if (hit.y < info.r) {\n      vec4 caustic = sampleCausticAt(hit, refractedLight);\n      // Landing-height shadow, same rule as the receivers: a hit clearly\n      // below the ray's landing is behind the surface that caught the\n      // light. b == 0 is the no-data sentinel \u2192 no occlusion.\n      float landingY = caustic.b * 3.0 * uPoolHalf.y - uPoolHalf.y;\n      float occlusion = 1.0 - step(0.002, caustic.b) * smoothstep(0.05, 0.2, landingY - hit.y);\n      // Hard ceiling on the contribution: at concave edges the tilted\n      // height-field normal and the fold-compressed caustic can multiply\n      // into an outline far brighter than the open-floor pattern.\n      causticBoost += min(diffuseTerm * caustic.r * 2.0 * caustic.g * occlusion, 0.8);\n    }\n\n    // The fallback gets the boost too so a caustic band doesn't cut off\n    // abruptly at the valid-sample/fallback boundary.\n    if (rtvSceneCaptureMissed(sceneSample)) {\n      return uRefractionFallbackColor * causticBoost;\n    }\n    return sceneSample.rgb * causticBoost * waterColor;\n  }\n\n  vec3 getSurfaceRayColor(vec3 origin, vec3 ray, vec3 waterColor) {\n    vec3 color;\n    if (ray.y < 0.0) {\n      vec2 t = intersectCube(origin, ray, vec3(-uPoolHalf.x, -uPoolHalf.y, -uPoolHalf.z), vec3(uPoolHalf.x, 2.0 * uPoolHalf.y, uPoolHalf.z));\n      color = getWallColor(origin + ray * t.y);\n    } else {\n      vec2 t = intersectCube(origin, ray, vec3(-uPoolHalf.x, -uPoolHalf.y, -uPoolHalf.z), vec3(uPoolHalf.x, 2.0 * uPoolHalf.y, uPoolHalf.z));\n      vec3 hit = origin + ray * t.y;\n      if (hit.y < uPoolHalf.y / 6.0) {\n        color = getWallColor(hit);\n      } else {\n        color = sampleProceduralSky(ray);            // MOD #2\n        color += vec3(pow(max(0.0, dot(light, ray)), 5000.0)) * vec3(10.0, 8.0, 6.0);\n      }\n    }\n    if (ray.y < 0.0) color *= waterColor;\n    return color;\n  }\n\n  void main() {\n    vec2 coord = vWaterPos.xz / (2.0 * uPoolHalf.xz) + 0.5;\n    vec4 info = texture2D(water, coord);\n\n    // HEIGHTMAP debug view \u2014 the raw PoolHeightMap capture over the pool\n    // footprint (same UV the caustics pass samples with).\n    if (uCausticDebugMode > 4.5) {\n      gl_FragColor = vec4(rtvLandingRamp(texture2D(uPoolHeightMap, coord).r), 1.0);\n      return;\n    }\n\n    /* make water look more \"peaked\" */\n    for (int i = 0; i < 5; i++) {\n      coord += info.ba * 0.005;\n      info = texture2D(water, coord);\n    }\n\n    vec3 normal = vec3(info.b, sqrt(max(0.0, 1.0 - dot(info.ba, info.ba))), info.a);\n    vec3 incomingRay = normalize(vWaterPos - eye);\n\n    /* above water */\n    vec3 reflectedRay = reflect(incomingRay, normal);\n    vec3 refractedRay = refract(incomingRay, normal, IOR_AIR / IOR_WATER);\n\n    // LANDING debug view \u2014 the landing height the composite uses at this\n    // pixel, computed with the same view-ray march as production.\n    if (uCausticDebugMode > 3.5) {\n      vec3 dbgRefractedLight = -refract(-light, vec3(0.0, 1.0, 0.0), IOR_AIR / IOR_WATER);\n      vec3 dbgHit = rtvMarchViewRay(vWaterPos, incomingRay);\n      gl_FragColor = vec4(rtvLandingRamp(sampleCausticAt(dbgHit, dbgRefractedLight).b), 1.0);\n      return;\n    }\n\n    float fresnelBase = mix(0.25, 0.05, uWaterClarity);\n    // Schlick fresnel. CRITICAL: clamp the cos-incidence term to [0, 1]\n    // BEFORE the pow(). On steep wave fronts dot(normal, -incomingRay)\n    // can slip slightly above 1.0 (fp error) \u2014 then 1.0 - dot becomes\n    // negative and pow(negative, 3.0) is undefined in GLSL \u2192 NaN.\n    // The NaN propagates into fresnel and into mix(refracted, reflected,\n    // fresnel), and the framebuffer write clamps NaN to 0, producing\n    // pure-black wave-front streaks. The clamp keeps fresnel a well-\n    // defined float in [fresnelBase, uFresnelMax] everywhere.\n    float cosI = clamp(dot(normal, -incomingRay), 0.0, 1.0);\n    float fresnel = mix(fresnelBase, uFresnelMax, pow(1.0 - cosI, 3.0));\n\n    vec3 abovewaterColor = mix(vec3(0.25, 1.0, 1.25), vec3(1.0), uWaterClarity);\n    vec3 reflectedColor = getSurfaceRayColor(vWaterPos, reflectedRay, abovewaterColor);\n    // Refraction path: screen-space sample of the captured scene texture when\n    // uUseScreenSpaceRefraction is on, falling back to the demo's in-shader\n    // AABB raytrace otherwise. Both paths share the same abovewaterColor tint\n    // so toggling between them doesn't shift the overall hue.\n    vec3 refractedColor;\n    if (uUseScreenSpaceRefraction > 0.5) {\n      refractedColor = sampleScreenSpaceRefraction(incomingRay, abovewaterColor);\n    } else {\n      refractedColor = getSurfaceRayColor(vWaterPos, refractedRay, abovewaterColor);\n    }\n\n    gl_FragColor = vec4(mix(refractedColor, reflectedColor, fresnel), 1.0);\n  }\n");
+
+/**
+ * Caustics vertex/fragment.
+ *
+ * The caustic-mesh plane is sized `2*halfX × 2*halfZ` in world meters so
+ * `position.xy` here is the WORLD XZ of a water-surface point. The
+ * projection logic refracts the (world-space) light direction through the
+ * wave normal and lands on the pool floor at world Y = -uPoolHalf.y.
+ *
+ * `gl_Position.xy` is written in caustic-clip space (range [-1, +1]) using
+ * the SAME `(p.xz - p.y * slope) / uPoolHalf.xz` formula the fragment
+ * lookup uses, so write and read are consistent at any pool aspect.
+ *
+ * MOD #4: `info.ba *= 0.5` → `info.ba *= uCausticIntensity` so the strength
+ * of the wave-normal contribution is tunable.
+ */
+var CAUSTICS_VERTEX = /* glsl */"\n  ".concat(SHADER_CORE, "\n  uniform float uCausticIntensity;            // MOD #4\n  // MOD #7 \u2014 receiving-geometry height map (PoolHeightMap.ts). R channel:\n  // volume-local height as (y + poolHalf.y) / (3 * poolHalf.y); the cleared\n  // texture (0) decodes to the floor plane.\n  uniform sampler2D uHeightMap;\n  uniform float uHeightMapEnabled;\n  varying vec3 oldPos;\n  varying vec3 newPos;\n  varying vec3 vRay;\n  varying float vEdgeFade;\n\n  ").concat(heightSamplerGLSL('causticSampleHeight', 'uHeightMap'), "\n\n  /* Runs per VERTEX of the caustic mesh, so it affords a 24-step coarse pass;\n     see heightFieldMarchGLSL for the algorithm. */\n  ").concat(heightFieldMarchGLSL({
+  name: 'causticMarchLightRay',
+  sampler: 'causticSampleHeight',
+  coarseSteps: 24,
+  guardShallowRays: false
+}), "\n\n  /* Land the ray on the receiving geometry. Without a height map: the\n     demo's AABB clip + flat-floor projection. With one: march the ray\n     against the height map \u2014 walls, ROUNDED CORNERS and stairs all\n     terminate rays at their real position. (The analytic AABB attributes\n     corner rays to the wrong wall face: square box vs rounded pool.)\n     The caustic-clip lookup is invariant to where along the ray we stop. */\n  vec3 project(vec3 origin, vec3 ray, vec3 refractedLight) {\n    if (uHeightMapEnabled < 0.5) {\n      vec2 tcube = intersectCube(origin, ray, vec3(-uPoolHalf.x, -uPoolHalf.y, -uPoolHalf.z), vec3(uPoolHalf.x, 2.0 * uPoolHalf.y, uPoolHalf.z));\n      origin += ray * tcube.y;\n      float tplane = (-origin.y - uPoolHalf.y) / refractedLight.y;\n      return origin + refractedLight * tplane;\n    }\n    return causticMarchLightRay(origin, ray);\n  }\n\n  void main() {\n    vec4 info = texture2D(water, position.xy / (2.0 * uPoolHalf.xz) + 0.5);\n    info.ba *= uCausticIntensity;             // MOD #4: was *= 0.5\n    vec3 normal = vec3(info.b, sqrt(max(0.0, 1.0 - dot(info.ba, info.ba))), info.a);\n\n    /* project the vertices along the refracted vertex ray */\n    vec3 refractedLight = refract(-light, vec3(0.0, 1.0, 0.0), IOR_AIR / IOR_WATER);\n    vRay = refract(-light, normal, IOR_AIR / IOR_WATER);\n    oldPos = project(position.xzy, refractedLight, refractedLight);\n    newPos = project(position.xzy + vec3(0.0, info.r, 0.0), vRay, refractedLight);\n\n    // Concave-edge fade. Grazing light makes the landing mapping\n    // near-singular at riser bases and wall coves \u2014 wave-normal jitter\n    // funnels rays onto the exact corner line, which the area-ratio math\n    // rewards with harsh max-brightness dashes. Fade landings that are\n    // FLAT at their own position (small-radius gradient) but have a STEEP\n    // feature nearby (large-radius gradient) \u2014 the signature of a concave\n    // base line. Wall-FACE landings are steep at both radii and therefore\n    // never faded; open floor is flat at both and also untouched.\n    vEdgeFade = 1.0;\n    if (uHeightMapEnabled > 0.5) {\n      float epsNear = uPoolHalf.x / 128.0;\n      float epsFar = uPoolHalf.x / 24.0;\n      float gxN = causticSampleHeight(newPos.xz + vec2(epsNear, 0.0)) - causticSampleHeight(newPos.xz - vec2(epsNear, 0.0));\n      float gzN = causticSampleHeight(newPos.xz + vec2(0.0, epsNear)) - causticSampleHeight(newPos.xz - vec2(0.0, epsNear));\n      float gxF = causticSampleHeight(newPos.xz + vec2(epsFar, 0.0)) - causticSampleHeight(newPos.xz - vec2(epsFar, 0.0));\n      float gzF = causticSampleHeight(newPos.xz + vec2(0.0, epsFar)) - causticSampleHeight(newPos.xz - vec2(0.0, epsFar));\n      float flatHere = 1.0 - smoothstep(0.2, 0.6, length(vec2(gxN, gzN)) / (2.0 * epsNear));\n      float steepNearby = smoothstep(0.25, 0.6, length(vec2(gxF, gzF)) / (2.0 * epsFar));\n      vEdgeFade = 1.0 - steepNearby * flatHere;\n    }\n\n    // Caustic-clip output mirrors sampleCausticAt exactly: same projection,\n    // same uPoolHalf.xz divide, same 0.75 margin. With slope = 0 (vertical\n    // sun) this lands the pool floor [-uPoolHalf.xz, +uPoolHalf.xz] in\n    // caustic-clip [-0.75, +0.75], leaving a 25% border for slanted-sun\n    // projection drift.\n    vec2 lookup = (newPos.xz - newPos.y * refractedLight.xz / refractedLight.y) / uPoolHalf.xz;\n    gl_Position = vec4(0.75 * lookup, 0.0, 1.0);\n  }\n");
+
+// Three's ShaderMaterial prepends the GL_OES_standard_derivatives extension
+// directive when `material.extensions.derivatives = true`, so we omit it here.
+var CAUSTICS_FRAGMENT = /* glsl */"\n  ".concat(SHADER_CORE, "\n  varying vec3 oldPos;\n  varying vec3 newPos;\n  varying vec3 vRay;\n  varying float vEdgeFade;\n\n  void main() {\n    /* if the triangle gets smaller, it gets brighter, and vice versa */\n    float oldArea = length(dFdx(oldPos)) * length(dFdy(oldPos));\n    float newArea = length(dFdx(newPos)) * length(dFdy(newPos));\n    // vEdgeFade suppresses the fold-caustic line at concave height-field\n    // edges (riser bases, wall coves) \u2014 see CAUSTICS_VERTEX.\n    gl_FragColor = vec4(oldArea / newArea * 0.2 * vEdgeFade, 1.0, 0.0, 0.0);\n\n    vec3 refractedLight = refract(-light, vec3(0.0, 1.0, 0.0), IOR_AIR / IOR_WATER);\n\n    /* shadow for the rim of the pool */\n    vec2 t = intersectCube(newPos, -refractedLight, vec3(-uPoolHalf.x, -uPoolHalf.y, -uPoolHalf.z), vec3(uPoolHalf.x, 2.0 * uPoolHalf.y, uPoolHalf.z));\n    gl_FragColor.r *= 1.0 / (1.0 + exp(-200.0 / (1.0 + 10.0 * (t.y - t.x)) * (newPos.y - refractedLight.y * t.y - uPoolHalf.y / 6.0)));\n\n    // MOD #7 \u2014 landing height into the blue channel (same normalization as\n    // the height map). Consumers occlude fragments clearly below it.\n    gl_FragColor.b = clamp((newPos.y + uPoolHalf.y) / (3.0 * uPoolHalf.y), 0.0, 1.0);\n  }\n");
+var WATER_SURFACE_SHADER_ABOVE = {
+  vertex: WATER_SURFACE_VERTEX,
+  fragment: WATER_SURFACE_FRAGMENT_ABOVE
+};
+var CAUSTICS_SHADER = {
+  vertex: CAUSTICS_VERTEX,
+  fragment: CAUSTICS_FRAGMENT
+};
+
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function buildSharedUniformValues(initial) {
+  var _initial$light, _initial$water, _initial$causticTex, _initial$uPoolHalf, _initial$uWallColor, _initial$uSkyHorizonC, _initial$uSkyZenithCo, _initial$uWaterClarit;
+  return {
+    light: {
+      value: ((_initial$light = initial.light) !== null && _initial$light !== void 0 ? _initial$light : new Vector3(0.7071, 0.7071, 0.0)).clone()
+    },
+    water: {
+      value: (_initial$water = initial.water) !== null && _initial$water !== void 0 ? _initial$water : null
+    },
+    causticTex: {
+      value: (_initial$causticTex = initial.causticTex) !== null && _initial$causticTex !== void 0 ? _initial$causticTex : null
+    },
+    // (halfX, depth, halfZ) — pool half-extents in WORLD METERS.
+    // Default reproduces the demo's unit-cube behaviour.
+    uPoolHalf: {
+      value: ((_initial$uPoolHalf = initial.uPoolHalf) !== null && _initial$uPoolHalf !== void 0 ? _initial$uPoolHalf : new Vector3(1, 1, 1)).clone()
+    },
+    uWallColor: {
+      value: ((_initial$uWallColor = initial.uWallColor) !== null && _initial$uWallColor !== void 0 ? _initial$uWallColor : new Vector3(0.7, 0.78, 0.85)).clone()
+    },
+    uSkyHorizonColor: {
+      value: ((_initial$uSkyHorizonC = initial.uSkyHorizonColor) !== null && _initial$uSkyHorizonC !== void 0 ? _initial$uSkyHorizonC : new Vector3(0.78, 0.85, 0.95)).clone()
+    },
+    uSkyZenithColor: {
+      value: ((_initial$uSkyZenithCo = initial.uSkyZenithColor) !== null && _initial$uSkyZenithCo !== void 0 ? _initial$uSkyZenithCo : new Vector3(0.18, 0.36, 0.78)).clone()
+    },
+    uWaterClarity: {
+      value: (_initial$uWaterClarit = initial.uWaterClarity) !== null && _initial$uWaterClarit !== void 0 ? _initial$uWaterClarit : 0
+    }
+  };
+}
+function createWaterSurfaceAboveMaterial() {
+  var _initial$eye;
+  var initial = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return new ShaderMaterial({
+    vertexShader: WATER_SURFACE_SHADER_ABOVE.vertex,
+    fragmentShader: WATER_SURFACE_SHADER_ABOVE.fragment,
+    uniforms: _objectSpread(_objectSpread({}, buildSharedUniformValues(initial)), {}, {
+      eye: {
+        value: ((_initial$eye = initial.eye) !== null && _initial$eye !== void 0 ? _initial$eye : new Vector3(0, 5, 5)).clone()
+      },
+      // Screen-space refraction source: the scene minus the water surface,
+      // captured each frame by SceneCapture.ts. Sampled at the fragment's screen
+      // UV, so the underwater view shows the ACTUAL pool geo instead of the
+      // demo's synthetic AABB walls.
+      uSceneColor: {
+        value: null
+      },
+      // Drawing-buffer pixel size — used to convert `gl_FragCoord.xy` into a
+      // [0, 1] UV for the scene-color sample. WaterSurfaceRenderer syncs
+      // this against the live canvas size on every resize.
+      uResolution: {
+        value: new Vector2(1, 1)
+      },
+      // 1.0 → screen-space refraction (SceneCapture); 0.0 → AABB raytrace.
+      uUseScreenSpaceRefraction: {
+        value: 0.0
+      },
+      // Returned by sampleScreenSpaceRefraction when the sampled UV lands on a
+      // clipped / empty capture pixel (tall wave crests). Live value comes from
+      // env.water.refractionFallbackColor.
+      uRefractionFallbackColor: {
+        value: new Vector3(0.039, 0.145, 0.251)
+      },
+      // Grazing-angle ceiling of the Schlick fresnel (env.water.fresnelMax).
+      uFresnelMax: {
+        value: 1.0
+      },
+      // MOD #7 debug views (4 = landing-height ramp, 5 = raw height map);
+      // 0 in production. These live in the surface shader because receiver
+      // debug modes never reach the screen underwater in SSR mode.
+      uCausticDebugMode: {
+        value: 0.0
+      },
+      // Pool receiving-geometry height map — production input for the SSR
+      // composite's view-ray march; bound every frame by the host.
+      uPoolHeightMap: {
+        value: null
+      }
+    }),
+    transparent: false,
+    // DoubleSide so the surface is visible from both above and below the water
+    // plane. Single-sided FrontSide can cause one side of the surface to vanish
+    // depending on camera angle (visible as a missing-quadrant artifact).
+    side: DoubleSide
+  });
+}
+
+/**
+ * Update the shared uniforms in one go. Pass whichever subset changed this
+ * frame; everything else is left alone.
+ */
+function updateSharedUniforms(mat, patch) {
+  var u = mat.uniforms;
+  if (patch.light) u.light.value.copy(patch.light);
+  if (patch.water !== undefined) u.water.value = patch.water;
+  if (patch.causticTex !== undefined) u.causticTex.value = patch.causticTex;
+  if (patch.uPoolHalf) u.uPoolHalf.value.copy(patch.uPoolHalf);
+  if (patch.uWallColor) u.uWallColor.value.copy(patch.uWallColor);
+  if (patch.uSkyHorizonColor) u.uSkyHorizonColor.value.copy(patch.uSkyHorizonColor);
+  if (patch.uSkyZenithColor) u.uSkyZenithColor.value.copy(patch.uSkyZenithColor);
+  if (patch.uWaterClarity !== undefined) u.uWaterClarity.value = patch.uWaterClarity;
+}
+
+var VERTEX_SHADER = /* glsl */"\n  varying vec2 coord;\n  void main() {\n    coord = position.xy * 0.5 + 0.5;\n    gl_Position = vec4(position.xyz, 1.0);\n  }\n";
+
+// NOTE on the `tSrc` uniform name:
+//   The demo names this uniform `texture`. That works in GLSL ES 1.00 (WebGL1)
+//   but `texture` is a reserved keyword in GLSL ES 3.00, which is what Three.js
+//   v0.176 emits by default for ShaderMaterial in WebGL2. With the demo's name
+//   the kernel fragments fail to compile silently and the heightfield never
+//   updates. Renaming to `tSrc` is the minimal change that keeps the rest of
+//   the GLSL character-for-character verbatim.
+
+// MOD #A1: world-meter distance in the drop falloff.
+//
+//   The demo's pool is a unit cube so a UV-space drop circle is also a circle
+//   in world space. Our pools are rectangular boxes (e.g. 2×10) and the
+//   heightfield's UV [0,1]² spans a rectangle in world meters, so a
+//   UV-distance circle is an ellipse in world. To keep a "circular drop in
+//   world space" property, we convert both the texel position and the drop
+//   center into world meters (via the `poolHalf` uniform = pool's
+//   half-extents in world meters) before measuring distance. `radius` is
+//   then naturally interpreted as a world-meter falloff radius and stays
+//   isotropic across any pool aspect.
+var DROP_FRAGMENT = /* glsl */"\n  const float PI = 3.141592653589793;\n  uniform sampler2D tSrc;\n  uniform vec2 center;        // pool-normalized [-1, 1]\n  uniform float radius;       // WORLD METERS\n  uniform float strength;\n  uniform vec2 poolHalf;      // (vx, vz) world half-extents (meters)\n  varying vec2 coord;\n  void main() {\n    vec4 info = texture2D(tSrc, coord);\n\n    vec2 texelWorld = (coord * 2.0 - 1.0) * poolHalf;\n    vec2 centerWorld = center * poolHalf;\n    float drop = max(0.0, 1.0 - distance(texelWorld, centerWorld) / radius);\n    drop = 0.5 - cos(drop * PI) * 0.5;\n    info.r += drop * strength;\n\n    gl_FragColor = info;\n  }\n";
+
+// Derived from water.js updateShader fragment. One change vs. the demo:
+//   the demo's hard-coded `info.g *= 0.995` becomes `info.g *= damping`.
+//
+// Rationale: the demo runs 2 substeps per frame at 60 fps for a fixed 256²
+// heightfield → 120 substeps/sec, with 0.995^120 ≈ 0.547 per-second damping.
+// In our component the substep count auto-scales with the heightfield
+// resolution (so waves propagate the same world meters per frame at any
+// resolution); if we kept `* 0.995` per substep, doubling the resolution
+// would more than double the substep rate and waves would die before they
+// finished spreading across the pool. JS picks a per-substep damping each
+// frame such that the per-SECOND damping stays at the demo's 0.547.
+//
+// The acceleration coefficient stays at the demo's `* 2.0` literal — it
+// sets the wave equation's `c² · dt² / Δx²` ratio at exactly 0.5, well
+// inside the CFL stability bound. Tweaking it without re-deriving the
+// stability regime breaks the simulation.
+var UPDATE_FRAGMENT = /* glsl */"\n  uniform sampler2D tSrc;\n  uniform vec2 delta;\n  uniform float damping;\n  varying vec2 coord;\n  void main() {\n    /* get vertex info */\n    vec4 info = texture2D(tSrc, coord);\n\n    /* calculate average neighbor height */\n    vec2 dx = vec2(delta.x, 0.0);\n    vec2 dy = vec2(0.0, delta.y);\n    float average = (\n      texture2D(tSrc, coord - dx).r +\n      texture2D(tSrc, coord - dy).r +\n      texture2D(tSrc, coord + dx).r +\n      texture2D(tSrc, coord + dy).r\n    ) * 0.25;\n\n    /* change the velocity to move toward the average */\n    info.g += (average - info.r) * 2.0;\n\n    /* attenuate the velocity a little so waves do not last forever */\n    info.g *= damping;\n\n    /* move the vertex along the velocity */\n    info.r += info.g;\n\n    gl_FragColor = info;\n  }\n";
+
+// VERBATIM from water.js normalShader fragment (uniform `texture` → `tSrc`).
+var NORMAL_FRAGMENT = /* glsl */"\n  uniform sampler2D tSrc;\n  uniform vec2 delta;\n  varying vec2 coord;\n  void main() {\n    /* get vertex info */\n    vec4 info = texture2D(tSrc, coord);\n\n    /* update the normal */\n    vec3 dx = vec3(delta.x, texture2D(tSrc, vec2(coord.x + delta.x, coord.y)).r - info.r, 0.0);\n    vec3 dy = vec3(0.0, texture2D(tSrc, vec2(coord.x, coord.y + delta.y)).r - info.r, delta.y);\n    info.ba = normalize(cross(dy, dx)).xz;\n\n    gl_FragColor = info;\n  }\n";
+/**
+ * GPU heightfield with a ping-pong pair of float render targets. Constructed
+ * without a renderer; the per-frame calls take one.
+ *
+ * Rectangular pools need no kernel change: all three shaders sample through
+ * the `coord` varying (UV ∈ [0,1]²) and `delta` (per-axis texel size), both of
+ * which work unchanged on non-square textures. The only physically-relevant
+ * difference is the drop falloff math — see MOD #A1 in this file.
+ */
+var Heightfield = /*#__PURE__*/function () {
+  function Heightfield() {
+    var _opts$sizeX, _opts$sizeY;
+    var opts = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    _classCallCheck(this, Heightfield);
+    _defineProperty(this, "sizeX", void 0);
+    _defineProperty(this, "sizeY", void 0);
+    _defineProperty(this, "delta", void 0);
+    _defineProperty(this, "poolHalf", void 0);
+    _defineProperty(this, "rtA", void 0);
+    _defineProperty(this, "rtB", void 0);
+    _defineProperty(this, "scene", void 0);
+    _defineProperty(this, "camera", void 0);
+    _defineProperty(this, "quad", void 0);
+    _defineProperty(this, "dropMat", void 0);
+    _defineProperty(this, "updateMat", void 0);
+    _defineProperty(this, "normalMat", void 0);
+    _defineProperty(this, "clearedOnce", false);
+    this.sizeX = (_opts$sizeX = opts.sizeX) !== null && _opts$sizeX !== void 0 ? _opts$sizeX : 256;
+    this.sizeY = (_opts$sizeY = opts.sizeY) !== null && _opts$sizeY !== void 0 ? _opts$sizeY : this.sizeX;
+    this.delta = new Vector2(1 / this.sizeX, 1 / this.sizeY);
+    this.poolHalf = new Vector2(1, 1);
+    if (opts.poolHalf) this.poolHalf.copy(opts.poolHalf);
+
+    // ClampToEdge prevents the kernel from sampling the opposite side of the
+    // heightfield (which would manifest as ghost ripples wrapping around the
+    // pool). LinearFilter is the visual win: the surface vertex shader
+    // samples this texture at 200×200 plane vertices (and the fragment
+    // shader peaks-loop adds another 5 taps per pixel), so the difference
+    // between Nearest and Linear shows up as visible chunky pixelation when
+    // Nearest is used. WebGL2 + half-float linear is universally supported
+    // via OES_texture_half_float_linear (auto-enabled on WebGL2 contexts).
+    var rtParams = {
+      type: HalfFloatType,
+      format: RGBAFormat,
+      wrapS: ClampToEdgeWrapping,
+      wrapT: ClampToEdgeWrapping,
+      magFilter: LinearFilter,
+      minFilter: LinearFilter,
+      depthBuffer: false,
+      stencilBuffer: false
+    };
+    this.rtA = new WebGLRenderTarget(this.sizeX, this.sizeY, rtParams);
+    this.rtB = new WebGLRenderTarget(this.sizeX, this.sizeY, rtParams);
+    this.scene = new Scene();
+    this.camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    this.quad = new Mesh(new PlaneGeometry(2, 2));
+    this.scene.add(this.quad);
+    this.dropMat = new ShaderMaterial({
+      vertexShader: VERTEX_SHADER,
+      fragmentShader: DROP_FRAGMENT,
+      uniforms: {
+        tSrc: {
+          value: null
+        },
+        center: {
+          value: new Vector2(0, 0)
+        },
+        radius: {
+          value: 0.1
+        },
+        strength: {
+          value: 0.01
+        },
+        poolHalf: {
+          value: this.poolHalf
+        }
+      },
+      depthTest: false,
+      depthWrite: false
+    });
+    this.updateMat = new ShaderMaterial({
+      vertexShader: VERTEX_SHADER,
+      fragmentShader: UPDATE_FRAGMENT,
+      uniforms: {
+        tSrc: {
+          value: null
+        },
+        delta: {
+          value: this.delta
+        },
+        // Per-substep damping. Caller is expected to set this each frame
+        // via `setDamping(value)` so it matches the actual substep rate;
+        // 0.995 is the demo baseline (2 substeps/frame on a 256² grid).
+        damping: {
+          value: 0.995
+        }
+      },
+      depthTest: false,
+      depthWrite: false
+    });
+    this.normalMat = new ShaderMaterial({
+      vertexShader: VERTEX_SHADER,
+      fragmentShader: NORMAL_FRAGMENT,
+      uniforms: {
+        tSrc: {
+          value: null
+        },
+        delta: {
+          value: this.delta
+        }
+      },
+      depthTest: false,
+      depthWrite: false
+    });
+  }
+
+  /**
+   * Read-only handle of the front-buffer (the one that holds the latest simulation
+   * state). Sample this texture from the surface and caustics shaders.
+   */
+  return _createClass(Heightfield, [{
+    key: "currentTexture",
+    get: function get() {
+      return this.rtA.texture;
+    }
+
+    /**
+     * Clear both ping-pong RTs to (0,0,0,0) on the first frame so neither buffer
+     * starts with garbage. Stability bug guard: skipping this gives the kernel
+     * uninitialized data and the wave amplitude blows up.
+     */
+  }, {
+    key: "ensureCleared",
+    value: function ensureCleared(renderer) {
+      var _this = this;
+      if (this.clearedOnce) return;
+      withRenderTarget(renderer, {
+        target: this.rtA,
+        clearColor: 0x000000,
+        clearAlpha: 0
+      }, function () {
+        renderer.clear(true, true, true);
+        // Second buffer of the ping-pong. Re-binding inside the pass is safe —
+        // the restore uses the target captured before it.
+        renderer.setRenderTarget(_this.rtB);
+        renderer.clear(true, true, true);
+      });
+      this.clearedOnce = true;
+    }
+
+    /**
+     * One ping-pong step: draw the quad into the back buffer, then swap.
+     *
+     * Deliberately not a `withRenderTarget` pass — it touches no clear/tone-mapping
+     * state and unbinds to the default framebuffer rather than restoring whatever
+     * was bound. Callers run it from the water frame stage, where nothing is bound.
+     */
+  }, {
+    key: "renderPass",
+    value: function renderPass(renderer, mat) {
+      this.quad.material = mat;
+      renderer.setRenderTarget(this.rtB);
+      renderer.render(this.scene, this.camera);
+      renderer.setRenderTarget(null);
+      var _ref = [this.rtB, this.rtA];
+      this.rtA = _ref[0];
+      this.rtB = _ref[1];
+    }
+
+    /**
+     * Add a drop. Center is in pool-normalized [-1, 1] coordinates so the same
+     * call site works across pool sizes. `radius` is in WORLD METERS — see the
+     * MOD #A1 comment above DROP_FRAGMENT — so a 0.2 m drop has the same
+     * physical size on a 4×4 pool and a 2×10 pool. Strength is unitless
+     * (height delta applied at the drop centre).
+     */
+  }, {
+    key: "addDrop",
+    value: function addDrop(renderer, center) {
+      var radius = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 0.1;
+      var strength = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 0.01;
+      this.ensureCleared(renderer);
+      this.dropMat.uniforms.tSrc.value = this.rtA.texture;
+      this.dropMat.uniforms.center.value.copy(center);
+      this.dropMat.uniforms.radius.value = radius;
+      this.dropMat.uniforms.strength.value = strength;
+      this.renderPass(renderer, this.dropMat);
+    }
+
+    /** Advance the wave simulation one substep. */
+  }, {
+    key: "step",
+    value: function step(renderer) {
+      this.ensureCleared(renderer);
+      this.updateMat.uniforms.tSrc.value = this.rtA.texture;
+      this.renderPass(renderer, this.updateMat);
+    }
+
+    /**
+     * Per-substep damping coefficient applied to the velocity channel after
+     * each `step()`. With more substeps per second (e.g. when the host
+     * component auto-scales substep count for higher-resolution
+     * heightfields) this value must be closer to 1.0 to keep amplitude
+     * decay constant in real time. The host component computes this as
+     *   `damping = (perSecondDamping) ^ (1 / substepsPerSecond)`
+     * and pushes it every frame.
+     */
+  }, {
+    key: "setDamping",
+    value: function setDamping(value) {
+      this.updateMat.uniforms.damping.value = value;
+    }
+
+    /** Recompute surface normals into channels (b, a). */
+  }, {
+    key: "updateNormals",
+    value: function updateNormals(renderer) {
+      this.ensureCleared(renderer);
+      this.normalMat.uniforms.tSrc.value = this.rtA.texture;
+      this.renderPass(renderer, this.normalMat);
+    }
+  }, {
+    key: "dispose",
+    value: function dispose() {
+      this.rtA.dispose();
+      this.rtB.dispose();
+      this.dropMat.dispose();
+      this.updateMat.dispose();
+      this.normalMat.dispose();
+      this.quad.geometry.dispose();
+    }
+  }]);
+}();
+
+var CausticsTexture = /*#__PURE__*/function () {
+  function CausticsTexture() {
+    var _opts$size, _opts$detail, _opts$poolHalf;
+    var opts = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    _classCallCheck(this, CausticsTexture);
+    _defineProperty(this, "size", void 0);
+    _defineProperty(this, "poolHalf", void 0);
+    _defineProperty(this, "rt", void 0);
+    _defineProperty(this, "scene", void 0);
+    _defineProperty(this, "camera", void 0);
+    _defineProperty(this, "quad", void 0);
+    _defineProperty(this, "material", void 0);
+    this.size = (_opts$size = opts.size) !== null && _opts$size !== void 0 ? _opts$size : 1024;
+    var detail = (_opts$detail = opts.detail) !== null && _opts$detail !== void 0 ? _opts$detail : 200;
+    this.poolHalf = ((_opts$poolHalf = opts.poolHalf) !== null && _opts$poolHalf !== void 0 ? _opts$poolHalf : new Vector3(1, 1, 1)).clone();
+    this.rt = new WebGLRenderTarget(this.size, this.size, {
+      type: UnsignedByteType,
+      format: RGBAFormat,
+      depthBuffer: false,
+      stencilBuffer: false
+    });
+    this.scene = new Scene();
+    // The caustics vertex shader writes gl_Position directly, ignoring the
+    // camera's projection / view matrices. Any camera works — this one is
+    // chosen to match the [-1, 1] clip-space range of the shader output.
+    this.camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    this.material = new ShaderMaterial({
+      vertexShader: CAUSTICS_SHADER.vertex,
+      fragmentShader: CAUSTICS_SHADER.fragment,
+      uniforms: {
+        light: {
+          value: new Vector3(0.7071, 0.7071, 0.0)
+        },
+        water: {
+          value: null
+        },
+        uPoolHalf: {
+          value: this.poolHalf.clone()
+        },
+        // Demo's hard-coded `info.ba *= 0.5` lifted to a uniform — see MOD #4
+        // in waterShaders.ts. Lower values mute small-amplitude ripple
+        // caustics that look like static noise on the pool floor at higher
+        // simulation resolutions.
+        uCausticIntensity: {
+          value: 0.5
+        },
+        // MOD #7 — receiving-geometry height map; while unset the vertex
+        // shader keeps the flat-floor projection.
+        uHeightMap: {
+          value: null
+        },
+        uHeightMapEnabled: {
+          value: 0
+        }
+      },
+      depthTest: false,
+      depthWrite: false
+      // dFdx / dFdy in the caustics fragment are part of GLSL ES 3.00 (WebGL2);
+      // Three v0.176 emits GLSL ES 3.00 by default, so no `extensions` flag is
+      // needed. The shader stays portable to WebGL1 as long as Three injects
+      // the GL_OES_standard_derivatives directive itself when it falls back.
+    });
+
+    // Plane mesh: sized in world meters so `position.xy` in the vertex
+    // shader is the WORLD XZ of a water-surface point. Segment count scales
+    // with each axis independently from a longest-axis "200 / 2m" budget
+    // (≈ the demo density), floored at 32 so we never degenerate to a
+    // 1-segment strip on extreme aspect ratios.
+    var vx = this.poolHalf.x;
+    var vz = this.poolHalf.z;
+    var longer = Math.max(vx, vz);
+    var segsPerMeter = detail / Math.max(0.001, 2 * longer);
+    var segsX = Math.max(32, Math.round(2 * vx * segsPerMeter));
+    var segsZ = Math.max(32, Math.round(2 * vz * segsPerMeter));
+    this.quad = new Mesh(new PlaneGeometry(2 * vx, 2 * vz, segsX, segsZ), this.material);
+    this.scene.add(this.quad);
+  }
+
+  /** Output texture handle. Bind this where the demo bound `causticTex`. */
+  return _createClass(CausticsTexture, [{
+    key: "texture",
+    get: function get() {
+      return this.rt.texture;
+    }
+
+    /**
+     * Render the caustics for the current heightfield + light. Should
+     * be called once per frame, after `Heightfield.updateNormals()` so the
+     * normals sampled here are in sync with the displaced surface.
+     *
+     * Inputs are read from the uniform setters below — pass updates BEFORE
+     * calling render().
+     */
+  }, {
+    key: "render",
+    value: function render(renderer) {
+      var _this = this;
+      withRenderTarget(renderer, {
+        target: this.rt,
+        clearColor: 0x000000,
+        clearAlpha: 0
+      }, function () {
+        renderer.clear(true, false, false);
+        renderer.render(_this.scene, _this.camera);
+      });
+    }
+  }, {
+    key: "setHeightfield",
+    value: function setHeightfield(tex) {
+      this.material.uniforms.water.value = tex;
+    }
+  }, {
+    key: "setLight",
+    value: function setLight(x, y, z) {
+      this.material.uniforms.light.value.set(x, y, z);
+    }
+
+    /** MOD #4 — caustic intensity multiplier (replaces demo's `info.ba *= 0.5`). */
+  }, {
+    key: "setIntensity",
+    value: function setIntensity(intensity) {
+      this.material.uniforms.uCausticIntensity.value = intensity;
+    }
+
+    /** MOD #7 — bind (or clear) the receiving-geometry height map. */
+  }, {
+    key: "setHeightMap",
+    value: function setHeightMap(tex) {
+      this.material.uniforms.uHeightMap.value = tex;
+      this.material.uniforms.uHeightMapEnabled.value = tex ? 1 : 0;
+    }
+  }, {
+    key: "dispose",
+    value: function dispose() {
+      this.rt.dispose();
+      this.material.dispose();
+      this.quad.geometry.dispose();
+    }
+  }]);
+}();
+
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t["return"] || t["return"](); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+
+/** Per-second amplitude decay: the demo's `0.995` per substep at its 120 substeps/s. */
+var PER_SECOND_DAMPING = 0.547;
+
+/**
+ * Longest frame the accumulator integrates. A paused tab, a JIT pause or an
+ * fps-cap resume hands us a huge delta; unclamped it becomes a burst of
+ * hundreds of substeps that visually snaps the wave field. 1/15 s is up to
+ * 4 substeps per resumption at the default `substeps = 2`.
+ */
+var MAX_STEP_SECONDS = 1 / 15;
+
+/**
+ * First-frame seed: a handful of large, slow drops so the surface starts
+ * alive without high-frequency content (which would project into many tiny
+ * caustic stripes on the pool walls). ~0.3 m matches the demo's normalized
+ * 0.15 on the default 4×2×4 pool.
+ */
+var SEED_DROP_COUNT = 10;
+var SEED_DROP_RADIUS = 0.3;
+var SEED_DROP_STRENGTH = 0.04;
+var AMBIENT_DROP_RADIUS = 0.24;
+var AMBIENT_DROP_STRENGTH = 0.04;
+
+/** Smallest heightfield extent per axis, so a thin pool still simulates. */
+var MIN_HEIGHTFIELD_TEXELS = 32;
+
+/**
+ * Fractional fixed-step accumulator. `take` turns a frame delta into a whole
+ * number of substeps at the requested per-second rate and carries the
+ * remainder, so the rate is exact on average and wave speed is INDEPENDENT
+ * of rendered fps — a 30 fps frame runs twice the substeps of a 60 fps one.
+ */
+var SubstepAccumulator = /*#__PURE__*/function () {
+  function SubstepAccumulator() {
+    _classCallCheck(this, SubstepAccumulator);
+    _defineProperty(this, "leftover", 0);
+  }
+  return _createClass(SubstepAccumulator, [{
+    key: "take",
+    value: function take(substepsPerSecond, delta) {
+      this.leftover += substepsPerSecond * Math.min(delta, MAX_STEP_SECONDS);
+      var steps = Math.floor(this.leftover);
+      this.leftover -= steps;
+      return steps;
+    }
+  }, {
+    key: "reset",
+    value: function reset() {
+      this.leftover = 0;
+    }
+  }]);
+}();
+function useWaveSimulation(_ref) {
+  var poolHalf = _ref.poolHalf,
+    heightfieldSize = _ref.heightfieldSize,
+    causticTextureSize = _ref.causticTextureSize,
+    substeps = _ref.substeps,
+    ambientDropPeriod = _ref.ambientDropPeriod;
+  var renderer = useThree(function (s) {
+    return s.gl;
+  });
+  var heightfieldRef = useRef(null);
+  var causticsRef = useRef(null);
+  var pendingDrops = useRef([]);
+  var seededRef = useRef(false);
+  var ambientTimerRef = useRef(0);
+  var accumulatorRef = useRef(new SubstepAccumulator());
+
+  // Rectangular heightfield with the texel-per-meter resolution matched on
+  // both axes, so wave propagation is isotropic in world space.
+  var heightfieldShape = useMemo(function () {
+    var vx = poolHalf.x;
+    var vz = poolHalf.z;
+    var texelsPerMeter = heightfieldSize / (2 * Math.max(vx, vz));
+    return {
+      sizeX: Math.max(MIN_HEIGHTFIELD_TEXELS, Math.round(2 * vx * texelsPerMeter)),
+      sizeY: Math.max(MIN_HEIGHTFIELD_TEXELS, Math.round(2 * vz * texelsPerMeter)),
+      poolHalfX: vx,
+      poolHalfZ: vz,
+      poolDepth: poolHalf.y
+    };
+  }, [poolHalf.x, poolHalf.y, poolHalf.z, heightfieldSize]);
+
+  // Both get rebuilt when the pool aspect changes — losing wave state is
+  // acceptable, the seed drops restock the surface within one frame.
+  useEffect(function () {
+    var hf = new Heightfield({
+      sizeX: heightfieldShape.sizeX,
+      sizeY: heightfieldShape.sizeY,
+      poolHalf: new Vector2(heightfieldShape.poolHalfX, heightfieldShape.poolHalfZ)
+    });
+    var cx = new CausticsTexture({
+      poolHalf: new Vector3(heightfieldShape.poolHalfX, heightfieldShape.poolDepth, heightfieldShape.poolHalfZ),
+      size: causticTextureSize
+    });
+    heightfieldRef.current = hf;
+    causticsRef.current = cx;
+    seededRef.current = false;
+    // A fresh sim must not inherit the previous resolution's fractional
+    // leftover, or the first frame runs an accumulated burst of steps.
+    accumulatorRef.current.reset();
+    return function () {
+      hf.dispose();
+      cx.dispose();
+      heightfieldRef.current = null;
+      causticsRef.current = null;
+    };
+  }, [heightfieldShape, causticTextureSize]);
+  var queueDrop = useCallback(function (center, radius, strength) {
+    pendingDrops.current.push({
+      center: center,
+      radius: radius,
+      strength: strength
+    });
+  }, []);
+  var advance = function advance(delta) {
+    var hf = heightfieldRef.current;
+    var cx = causticsRef.current;
+    if (!hf || !cx) return false;
+    if (!seededRef.current) {
+      for (var i = 0; i < SEED_DROP_COUNT; i++) {
+        var dx = Math.random() * 2 - 1;
+        var dy = Math.random() * 2 - 1;
+        hf.addDrop(renderer, new Vector2(dx, dy), SEED_DROP_RADIUS, i & 1 ? SEED_DROP_STRENGTH : -SEED_DROP_STRENGTH);
+      }
+      seededRef.current = true;
+    }
+    if (ambientDropPeriod > 0) {
+      ambientTimerRef.current += delta;
+      if (ambientTimerRef.current >= ambientDropPeriod) {
+        ambientTimerRef.current = 0;
+        var _dx = Math.random() * 2 - 1;
+        var _dy = Math.random() * 2 - 1;
+        hf.addDrop(renderer, new Vector2(_dx, _dy), AMBIENT_DROP_RADIUS, AMBIENT_DROP_STRENGTH);
+      }
+    }
+    if (pendingDrops.current.length > 0) {
+      var _iterator = _createForOfIteratorHelper(pendingDrops.current),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var drop = _step.value;
+          hf.addDrop(renderer, drop.center, drop.radius, drop.strength);
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      pendingDrops.current.length = 0;
+    }
+
+    // The wave kernel propagates exactly one cell per substep, so wave speed
+    // in world meters per second is
+    //   c_world = substepsPerSecond × (2 × poolHalf.x / sizeX).
+    var substepsPerSecond = substeps * 60;
+    if (substepsPerSecond > 0) {
+      // Damping is a per-SECOND target, so the per-substep factor has to be
+      // derived from the actual substep rate.
+      hf.setDamping(Math.pow(PER_SECOND_DAMPING, 1 / substepsPerSecond));
+      var stepsThisFrame = accumulatorRef.current.take(substepsPerSecond, delta);
+      for (var _i = 0; _i < stepsThisFrame; _i++) {
+        hf.step(renderer);
+      }
+    }
+    hf.updateNormals(renderer);
+    return true;
+  };
+  var setHeightMap = function setHeightMap(texture) {
+    var _causticsRef$current;
+    (_causticsRef$current = causticsRef.current) === null || _causticsRef$current === void 0 || _causticsRef$current.setHeightMap(texture);
+  };
+  var renderCaustics = function renderCaustics(light, intensity) {
+    var hf = heightfieldRef.current;
+    var cx = causticsRef.current;
+    if (!hf || !cx) return;
+    cx.setHeightfield(hf.currentTexture);
+    cx.setLight(light.x, light.y, light.z);
+    cx.setIntensity(intensity);
+    cx.render(renderer);
+  };
+  return {
+    queueDrop: queueDrop,
+    advance: advance,
+    setHeightMap: setHeightMap,
+    renderCaustics: renderCaustics,
+    get heightTexture() {
+      var _heightfieldRef$curre, _heightfieldRef$curre2;
+      return (_heightfieldRef$curre = (_heightfieldRef$curre2 = heightfieldRef.current) === null || _heightfieldRef$curre2 === void 0 ? void 0 : _heightfieldRef$curre2.currentTexture) !== null && _heightfieldRef$curre !== void 0 ? _heightfieldRef$curre : null;
+    },
+    get causticTexture() {
+      var _causticsRef$current$, _causticsRef$current2;
+      return (_causticsRef$current$ = (_causticsRef$current2 = causticsRef.current) === null || _causticsRef$current2 === void 0 ? void 0 : _causticsRef$current2.texture) !== null && _causticsRef$current$ !== void 0 ? _causticsRef$current$ : null;
+    }
+  };
+}
+
+/**
+ * Pointer drop radius in WORLD METERS — the demo's normalized 0.05 on the
+ * default 4×2×4 pool, now the same physical size on any pool aspect.
+ */
+var POINTER_DROP_RADIUS = 0.1;
+
+/**
+ * Base drop strengths, on the gentle side of the demo (~0.01 hover / ~0.03
+ * click): `pointermove` fires per pointer sample, so a single drag across the
+ * pool stacks 50+ drops and anything above ~0.02 looks like a tsunami after a
+ * few hundred ms of motion.
+ */
+var HOVER_DROP_STRENGTH = 0.01;
+var PRESS_DROP_STRENGTH = 0.04;
+/**
+ * `queueDrop` receives pool-normalized `[-1, +1]` centers. The raycast plane
+ * is rotated -π/2 about X, so its local +Y aligns with world -Z: the v
+ * coordinate is flipped to put the drop under the cursor.
+ */
+function useWaterPointer(queueDrop, pointerStrength) {
+  var queueAt = useCallback(function (event, strength) {
+    if (!event.uv) return;
+    queueDrop(new Vector2(event.uv.x * 2 - 1, 1 - event.uv.y * 2), POINTER_DROP_RADIUS, strength);
+  }, [queueDrop]);
+  var onPointerMove = useCallback(function (event) {
+    return queueAt(event, HOVER_DROP_STRENGTH * pointerStrength);
+  }, [queueAt, pointerStrength]);
+  var onPointerDown = useCallback(function (event) {
+    return queueAt(event, PRESS_DROP_STRENGTH * pointerStrength);
+  }, [queueAt, pointerStrength]);
+  return {
+    onPointerMove: onPointerMove,
+    onPointerDown: onPointerDown
+  };
+}
+
+/**
+ * Debug visualization mode. `'overlay' | 'isolate' | 'mask'` are RECEIVER
+ * views; `'landing' | 'heightmap'` are SURFACE-shader views, because receiver
+ * views never reach the screen underwater in screen-space-refraction mode.
+ */
+
+/** Mode → the float code both shader families compare against. */
+var CAUSTIC_DEBUG_CODE = {
+  off: 0,
+  overlay: 1,
+  isolate: 2,
+  mask: 3,
+  landing: 4,
+  heightmap: 5
+};
+
+/** Highest code the receiver shader understands; above it are surface views. */
+var HIGHEST_RECEIVER_CODE = 3;
+
+/**
+ * Publish `mode` to the surface material and to the receiver singleton.
+ * Surface-only modes hand the receivers 0 so they keep their production look
+ * while a surface view is up.
+ */
+function publishCausticDebugMode(material, mode) {
+  var code = CAUSTIC_DEBUG_CODE[mode];
+  waterUniforms.causticDebugMode = code <= HIGHEST_RECEIVER_CODE ? code : 0;
+  material.uniforms.uCausticDebugMode.value = code;
+}
+
+/**
+ * Drop the demo's self-contained pool world into the scene at the configured
+ * AABB. EVERY internal coordinate is in WORLD METERS in the pool's local
+ * frame (origin at the water-surface centre, +Y up):
+ *
+ *   xz ∈ [-poolHalf.x, +poolHalf.x] × [-poolHalf.z, +poolHalf.z]   (pool footprint)
+ *   y  ∈ [-poolHalf.y, +2 * poolHalf.y]                            (floor → sky ceiling)
+ *
+ * The parent `<group>` carries ONLY a `position` (no scale) so non-cubic pools
+ * don't introduce anisotropic stretching to the inside-the-pool view (wall
+ * caustics, etc.); the shaders get a `uPoolHalf` uniform so their internal
+ * math (intersectCube, caustic projection, wall detection, rim shadow) runs in
+ * the same world-meter frame.
+ *
+ * The above-water surface is rendered; the pool interior is ray-traced inside
+ * the surface shader. The underwater pass is intentionally skipped (the camera
+ * never goes below the water in the host scene).
+ */
+function WaterSurfaceRenderer(_ref) {
+  var position = _ref.position,
+    volumeSize = _ref.volumeSize,
+    sunDirection = _ref.sunDirection,
+    wallColor = _ref.wallColor,
+    skyHorizonColor = _ref.skyHorizonColor,
+    skyZenithColor = _ref.skyZenithColor,
+    heightfieldSize = _ref.heightfieldSize,
+    causticTextureSize = _ref.causticTextureSize,
+    substeps = _ref.substeps,
+    ambientDropPeriod = _ref.ambientDropPeriod,
+    pointerStrength = _ref.pointerStrength,
+    causticIntensity = _ref.causticIntensity,
+    waterClarity = _ref.waterClarity,
+    useScreenSpaceRefraction = _ref.useScreenSpaceRefraction,
+    refractionFallbackColor = _ref.refractionFallbackColor,
+    fresnelMax = _ref.fresnelMax,
+    causticDebugMode = _ref.causticDebugMode;
+  var groupRef = useRef(null);
+  var surfaceMeshRef = useRef(null);
+  var renderer = useThree(function (s) {
+    return s.gl;
+  });
+  var camera = useThree(function (s) {
+    return s.camera;
+  });
+  var sceneR3F = useThree(function (s) {
+    return s.scene;
+  });
+  // CSS pixels; the capture applies the pixel ratio itself each frame, so its
+  // texture tracks the live canvas without a React re-render.
+  var r3fSize = useThree(function (s) {
+    return s.size;
+  });
+
+  /** Screen-space-refraction capture; resizes itself with the canvas. */
+  var refractionRef = useRef(null);
+  if (refractionRef.current === null) {
+    refractionRef.current = new RefractionCapture();
+  }
+  /**
+   * Top-down height map of the caustic-receiving geometry, feeding the caustics
+   * pass and the SSR composite (see PoolHeightMap.ts for its refresh policy).
+   */
+  var poolHeightMapRef = useRef(null);
+  if (poolHeightMapRef.current === null) {
+    poolHeightMapRef.current = new PoolHeightMap();
+  }
+
+  // The `uPoolHalf : vec3` uniform every shader gets, in WORLD METERS:
+  //   .x — half-width   (X axis)
+  //   .y — full depth   (Y axis, asymmetric: surface at 0, floor at -.y)
+  //   .z — half-length  (Z axis)
+  var poolHalf = useMemo(function () {
+    return new Vector3(volumeSize[0] / 2, volumeSize[1], volumeSize[2] / 2);
+  }, [volumeSize[0], volumeSize[1], volumeSize[2]]);
+  var sim = useWaveSimulation({
+    poolHalf: poolHalf,
+    heightfieldSize: heightfieldSize,
+    causticTextureSize: causticTextureSize,
+    substeps: substeps,
+    ambientDropPeriod: ambientDropPeriod
+  });
+  var pointer = useWaterPointer(sim.queueDrop, pointerStrength);
+
+  // Water plane: flat in XZ (baked rotateX so AO override passes see a
+  // horizontal surface in the depth buffer).
+  var waterGeom = useMemo(function () {
+    var segs = function segs(extent) {
+      return Math.max(32, Math.min(256, Math.round(50 * extent)));
+    };
+    var geom = new PlaneGeometry(2 * poolHalf.x, 2 * poolHalf.z, segs(2 * poolHalf.x), segs(2 * poolHalf.z));
+    geom.rotateX(Math.PI / 2);
+    var nArr = geom.attributes.normal.array;
+    for (var i = 1; i < nArr.length; i += 3) nArr[i] = 1;
+    return geom;
+  }, [poolHalf.x, poolHalf.z]);
+  var raycastGeom = useMemo(function () {
+    return new PlaneGeometry(2 * poolHalf.x, 2 * poolHalf.z);
+  }, [poolHalf.x, poolHalf.z]);
+  var raycastMat = useMemo(function () {
+    return new MeshBasicMaterial({
+      colorWrite: false,
+      depthWrite: false,
+      side: DoubleSide
+    });
+  }, []);
+
+  // Surface material. Shares the wall/sky/light uniform schema plus the
+  // `uPoolHalf` uniform; per-material uniforms (eye) are bound separately.
+  var surfaceMaterial = useMemo(function () {
+    return createWaterSurfaceAboveMaterial({
+      uPoolHalf: poolHalf.clone(),
+      uWallColor: colorToVec3(wallColor),
+      uSkyHorizonColor: colorToVec3(skyHorizonColor),
+      uSkyZenithColor: colorToVec3(skyZenithColor)
+    });
+  },
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  []);
+  useEffect(function () {
+    return function () {
+      waterGeom.dispose();
+      raycastGeom.dispose();
+    };
+  }, [waterGeom, raycastGeom]);
+
+  // Both materials are memoized for the component's lifetime, so their disposal has to be too:
+  // sharing the geometries' effect freed the LIVE material on every pool resize, forcing three to
+  // re-link the water shader on the very frame the pool changes size.
+  useEffect(function () {
+    return function () {
+      raycastMat.dispose();
+      surfaceMaterial.dispose();
+    };
+  }, [raycastMat, surfaceMaterial]);
+
+  // The material outlives pool-aspect changes, and out-of-tree caustic
+  // receivers must sample the right AABB on the very first frame after a
+  // resize — so both copies of uPoolHalf are refreshed here.
+  useEffect(function () {
+    updateSharedUniforms(surfaceMaterial, {
+      uPoolHalf: poolHalf
+    });
+    waterUniforms.poolHalf.copy(poolHalf);
+  }, [poolHalf, surfaceMaterial]);
+
+  // Flip the receiver singleton off when this water instance unmounts so
+  // receivers stop reading stale (disposed) texture refs. The publish path
+  // below sets `enabled = true` once the first frame's heightfield is ready.
+  useEffect(function () {
+    return function () {
+      disableWaterUniforms();
+    };
+  }, []);
+
+  // Dispose the capture and height-map render targets on unmount. Both are
+  // recreated on the next mount via the lazy `null` inits above.
+  useEffect(function () {
+    return function () {
+      var _refractionRef$curren, _poolHeightMapRef$cur;
+      (_refractionRef$curren = refractionRef.current) === null || _refractionRef$curren === void 0 || _refractionRef$curren.dispose();
+      refractionRef.current = null;
+      (_poolHeightMapRef$cur = poolHeightMapRef.current) === null || _poolHeightMapRef$cur === void 0 || _poolHeightMapRef$cur.dispose();
+      poolHeightMapRef.current = null;
+    };
+  }, []);
+  useEffect(function () {
+    var wc = colorToVec3(wallColor);
+    var hc = colorToVec3(skyHorizonColor);
+    var zc = colorToVec3(skyZenithColor);
+    updateSharedUniforms(surfaceMaterial, {
+      uWallColor: wc,
+      uSkyHorizonColor: hc,
+      uSkyZenithColor: zc,
+      uWaterClarity: waterClarity
+    });
+  }, [wallColor, skyHorizonColor, skyZenithColor, waterClarity, surfaceMaterial]);
+  useEffect(function () {
+    var c = colorToVec3(refractionFallbackColor);
+    surfaceMaterial.uniforms.uRefractionFallbackColor.value.copy(c);
+  }, [refractionFallbackColor, surfaceMaterial]);
+
+  // Scratch vectors for per-frame conversions — kept outside useFrame to avoid
+  // GC pressure at 60+ fps.
+  var eyeLocal = useRef(new Vector3());
+  var lightLocal = useRef(new Vector3());
+  useFrame(function (_state, delta) {
+    if (!sim.advance(delta)) return;
+
+    // World-space camera + sun direction → pool's local frame.
+    //   eye:   subtract group world position (identity scale, no division).
+    //   light: direction vector — no offset, no scaling, just normalize.
+    var group = groupRef.current;
+    if (group) {
+      var gp = group.position;
+      eyeLocal.current.set(camera.position.x - gp.x, camera.position.y - gp.y, camera.position.z - gp.z);
+    } else {
+      eyeLocal.current.copy(camera.position);
+    }
+    lightLocal.current.set(sunDirection[0], sunDirection[1], sunDirection[2]).normalize();
+
+    // Refreshed EARLY: the height map and caustics passes below need it, and
+    // the capture and the singleton consumers read it later this same frame.
+    if (group) {
+      group.getWorldPosition(waterUniforms.volumeCenter);
+    }
+
+    // Receiving geometry is article AND deck, so either version invalidates
+    // the height map and the refraction capture.
+    var store = useRTVStore.getState();
+    var geometryVersion = store.articleVersion + store.decorVersion;
+
+    // Keep the height map current and bind it to the caustics pass. The water
+    // group is excluded — none of its meshes are receiving geometry.
+    var heightMap = poolHeightMapRef.current;
+    if (heightMap) {
+      heightMap.renderIfNeeded(renderer, sceneR3F, waterUniforms.volumeCenter, poolHalf, geometryVersion, [group]);
+      sim.setHeightMap(heightMap.texture);
+    }
+    sim.renderCaustics(lightLocal.current, causticIntensity);
+    updateSharedUniforms(surfaceMaterial, {
+      water: sim.heightTexture,
+      causticTex: sim.causticTexture,
+      light: lightLocal.current
+    });
+    surfaceMaterial.uniforms.eye.value.copy(eyeLocal.current);
+
+    // Scene capture for screen-space refraction: after the heightfield and
+    // caustics passes above, before the composite.
+    var refraction = refractionRef.current;
+    if (refraction && useScreenSpaceRefraction) {
+      refraction.update({
+        renderer: renderer,
+        scene: sceneR3F,
+        camera: camera,
+        material: surfaceMaterial,
+        surfaceMesh: surfaceMeshRef.current,
+        volumeCenter: waterUniforms.volumeCenter,
+        poolHalf: poolHalf,
+        cssWidth: r3fSize.width,
+        cssHeight: r3fSize.height,
+        geometryVersion: geometryVersion,
+        // Per-frame transform mutations that never bump a version.
+        sceneMutating: store.isDragging || store.accessoryMove !== null
+      });
+    }
+    // Pushed every frame: both are live config knobs, and a direct uniform
+    // write keeps them in sync without depending on a re-render.
+    surfaceMaterial.uniforms.uUseScreenSpaceRefraction.value = useScreenSpaceRefraction ? 1.0 : 0.0;
+    surfaceMaterial.uniforms.uFresnelMax.value = fresnelMax;
+
+    // Publish into the singleton so out-of-tree caustic receivers sample the
+    // same heightfield + caustic texture this frame.
+    waterUniforms.waterTex = sim.heightTexture;
+    waterUniforms.causticTex = sim.causticTexture;
+    waterUniforms.light.copy(lightLocal.current);
+    publishCausticDebugMode(surfaceMaterial, causticDebugMode);
+    surfaceMaterial.uniforms.uPoolHeightMap.value = heightMap ? heightMap.texture : null;
+    waterUniforms.enabled = true;
+  }, FRAME_ORDER.WATER_CAPTURE);
+  return /*#__PURE__*/jsxs("group", {
+    ref: groupRef,
+    position: position,
+    children: [/*#__PURE__*/jsx("mesh", {
+      ref: surfaceMeshRef,
+      geometry: waterGeom,
+      material: surfaceMaterial,
+      raycast: NOOP_RAYCAST
+    }), /*#__PURE__*/jsx("mesh", {
+      geometry: raycastGeom,
+      material: raycastMat,
+      rotation: [-Math.PI / 2, 0, 0],
+      onPointerMove: pointer.onPointerMove,
+      onPointerDown: pointer.onPointerDown
+    })]
+  });
+}
+var NOOP_RAYCAST = function NOOP_RAYCAST() {};
+
+/** `'#rrggbb'` → linear-RGB Vector3 in [0, 1]. */
+function colorToVec3(hex) {
+  var c = new Color(hex);
+  return new Vector3(c.r, c.g, c.b);
+}
+
+function WaterSurface() {
+  var _waterVolumeOverride$, _waterVolumeOverride$2;
+  var water = useRTVStore(function (s) {
+    return s.resolvedEnvironment.water;
+  });
+  var lightingSun = useRTVStore(function (s) {
+    return s.resolvedEnvironment.lighting.sun;
+  });
+  // Article-derived volume from `DeckCutoutArticleSync` (deckCutout.waterSync);
+  // wins over the configured volume while set.
+  var waterVolumeOverride = useRTVStore(function (s) {
+    return s.waterVolumeOverride;
+  });
+
+  // Caustic light follows the scene sun unless the preset overrides it
+  // (`water.causticSun`) — e.g. villa-cliff's 2.2° sunset disc is too
+  // grazing to steer the underwater rim shadow with.
+  var causticSun = water.causticSun;
+  var causticSunDirection = useMemo(function () {
+    return causticSun ? sunAnglesToDirection(causticSun.azimuth, causticSun.elevation) : lightingSunTowardDirection(lightingSun);
+  }, [causticSun, lightingSun]);
+
+  // The renderer owns its own world transform via volume.center / .size.
+  return /*#__PURE__*/jsx(WaterSurfaceRenderer, {
+    position: (_waterVolumeOverride$ = waterVolumeOverride === null || waterVolumeOverride === void 0 ? void 0 : waterVolumeOverride.center) !== null && _waterVolumeOverride$ !== void 0 ? _waterVolumeOverride$ : water.volume.center,
+    volumeSize: (_waterVolumeOverride$2 = waterVolumeOverride === null || waterVolumeOverride === void 0 ? void 0 : waterVolumeOverride.size) !== null && _waterVolumeOverride$2 !== void 0 ? _waterVolumeOverride$2 : water.volume.size,
+    sunDirection: causticSunDirection,
+    wallColor: water.wallColor,
+    skyHorizonColor: water.skyHorizonColor,
+    skyZenithColor: water.skyZenithColor,
+    waterClarity: water.waterClarity,
+    ambientDropPeriod: water.ambientDropPeriod,
+    pointerStrength: water.pointerStrength,
+    heightfieldSize: water.heightfieldSize,
+    causticTextureSize: water.causticTextureSize,
+    causticIntensity: water.causticIntensity,
+    useScreenSpaceRefraction: water.useScreenSpaceRefraction,
+    refractionFallbackColor: water.refractionFallbackColor,
+    fresnelMax: water.fresnelMax,
+    causticDebugMode: water.causticDebugMode,
+    substeps: water.waveSpeed
+  });
+}
+
+export { WaterSurface };