@3driseai/3drise-viewer 0.1.42 → 0.1.44

package/dist/utils/sharedParts.js

@@ -0,0 +1,268 @@
+// =============================================================================
+// sharedParts — draw one master object at many places, sharing its geometry and material
+// =============================================================================
+//
+// The machinery behind layouts (InstancedLayout) and linked instances (LinkedSource).
+// A master is an object rendered once, as itself, so material application, material
+// clips, model-part tracks and object effects keep working on it untouched. Its
+// meshes stay in the graph but are taken off the render layers (layers.mask = 0).
+//
+// For each master mesh (a "part") the drawing is either
+//   - instanced: one InstancedMesh for every slot, sharing the part's geometry and
+//     material by reference (instance matrix = slot × the part's place in its master);
+//   - mirrors: one plain Mesh per slot sharing geometry, material and depth materials
+//     — for objects that instance their own insides (vegetation's leaves are
+//     InstancedBufferGeometry with per-leaf attributes) and cannot be instanced again.
+//     Every part of such a master is mirrored, so the parts of one slot stay together.
+//
+// Each frame `sync` copies over whatever the master swapped (material, geometry,
+// visibility, shadow flags) and rewrites matrices only when a slot or a part moved.
+// Drawn meshes carry __opFxHelper (effects act on the master; the copies show the
+// result through the shared material). The draw root carries SELF_OWNED_MATERIAL_KEY
+// (useMaterialApplication skips it: no material clones per copy).
+import { Color, InstancedMesh, Matrix4, Mesh } from 'three';
+import { SELF_OWNED_MATERIAL_KEY, traverseSkippingEdgesAndEffects } from '@3driseai/3drise-core';
+import { instancingSupported } from './instancingSupport.js';
+const _rel = new Matrix4();
+const _inv = new Matrix4();
+const _m = new Matrix4();
+const ZERO = new Matrix4().makeScale(0, 0, 0);
+const _c = new Color();
+const _base = new Color();
+const _hsl = { h: 0, s: 0, l: 0 };
+export const sameMatrix = (a, b) => {
+    const x = a.elements, y = b.elements;
+    for (let i = 0; i < 16; i++)
+        if (Math.abs(x[i] - y[i]) > 1e-6)
+            return false;
+    return true;
+};
+/** Visibility of a part inside its master: its own flag and every ancestor up to the master. */
+function partVisible(mesh, master) {
+    for (let o = mesh; o && o !== master; o = o.parent)
+        if (!o.visible)
+            return false;
+    return true;
+}
+const colorOf = (material) => {
+    const m = (Array.isArray(material) ? material.find((x) => x?.color?.isColor) : material);
+    return m?.color?.isColor ? m.color : null;
+};
+/** The meshes of a master, whether they must be mirrored, and why they cannot be shared (if they cannot). */
+export function collectParts(master, forceMirrors) {
+    const meshes = [];
+    let reason;
+    traverseSkippingEdgesAndEffects(master, true, (c) => {
+        if (reason || c === master || c.userData?.__opFxHelper)
+            return;
+        if (c.isSkinnedMesh)
+            reason = 'a skinned (animated-rig) mesh';
+        else if (c.isPoints || c.isLine)
+            reason = 'a points / line part';
+        else if (c.isMesh && !c.isInstancedMesh && c.geometry?.attributes?.position)
+            meshes.push(c); // not an empty wrapper
+    });
+    // an object that instances its own insides is mirrored, whole
+    const mirrors = forceMirrors || meshes.some(m => m.geometry.isInstancedBufferGeometry);
+    if (!reason && !mirrors) {
+        for (const c of meshes) {
+            const mats = Array.isArray(c.material) ? c.material : [c.material];
+            if (mats.some((m) => m && !instancingSupported(m))) {
+                reason = `a shader material without instancing (${mats.map((m) => m?.type).join(', ')})`;
+                break;
+            }
+        }
+    }
+    return { meshes, mirrors, reason };
+}
+function syncMirror(m, source) {
+    if (m.material !== source.material)
+        m.material = source.material;
+    if (m.geometry !== source.geometry)
+        m.geometry = source.geometry;
+    m.customDepthMaterial = source.customDepthMaterial;
+    m.customDistanceMaterial = source.customDistanceMaterial;
+    m.castShadow = source.castShadow;
+    m.receiveShadow = source.receiveShadow;
+    m.frustumCulled = source.frustumCulled;
+    m.renderOrder = source.renderOrder;
+    // a part may install per-copy behaviour on each of its mirrors (vegetation detail levels: per-draw
+    // callbacks and a per-copy bounding sphere), once per mirror
+    const setup = source.userData.mirrorSetup;
+    if (setup && m.userData.mirrorSetupFor !== setup) {
+        setup(m);
+        m.userData.mirrorSetupFor = setup;
+    }
+}
+/** Draws one master at `count` slots under `drawRoot`. One per master (a layout's variant, a link source). */
+export class SharedParts {
+    drawRoot;
+    tag;
+    forceMirrors;
+    parts = [];
+    /** Bumps when the part set changes (pick proxies rebuild on it). */
+    version = 0;
+    signature = '';
+    count = 0;
+    constructor(drawRoot, 
+    /** tagged on every drawn mesh as userData.layoutVariant (picking maps a hit back to its slot) */
+    tag, forceMirrors = false) {
+        this.drawRoot = drawRoot;
+        this.tag = tag;
+        this.forceMirrors = forceMirrors;
+        drawRoot.userData[SELF_OWNED_MATERIAL_KEY] = true;
+    }
+    /** Draws the master at every slot. Returns why it cannot be shared (the caller falls back), or null. */
+    sync(master, input) {
+        let slotsDirty = input.slotsDirty;
+        if (input.checkParts || !this.signature || input.count !== this.count) {
+            const { meshes, mirrors, reason } = collectParts(master, this.forceMirrors);
+            if (reason) {
+                this.dispose();
+                return reason;
+            }
+            const sig = (mirrors ? 'm' : 'i') + input.count + '|' + meshes.map(m => m.uuid + ':' + m.geometry.uuid).join(';');
+            if (sig !== this.signature) {
+                this.signature = sig;
+                this.count = input.count;
+                this.rebuild(meshes, mirrors, input.count);
+                slotsDirty = true;
+            }
+        }
+        master.updateWorldMatrix(true, false);
+        _inv.copy(master.matrixWorld).invert();
+        for (const p of this.parts) {
+            const { source, inst, mirrors } = p;
+            if (source.layers.mask !== 0)
+                source.layers.disableAll(); // something re-enabled it
+            source.updateWorldMatrix(false, false);
+            _rel.multiplyMatrices(_inv, source.matrixWorld);
+            const relDirty = !p.relValid || !sameMatrix(_rel, p.rel);
+            if (relDirty) {
+                p.rel.copy(_rel);
+                p.relValid = true;
+            }
+            const vis = partVisible(source, master);
+            if (mirrors) {
+                for (let k = 0; k < mirrors.length; k++) {
+                    const m = mirrors[k];
+                    syncMirror(m, source);
+                    const slot = input.slot(k);
+                    m.visible = vis && !!slot;
+                    if (slot && (relDirty || slotsDirty)) {
+                        m.matrix.multiplyMatrices(slot, p.rel);
+                        m.matrixWorldNeedsUpdate = true;
+                    }
+                }
+                continue;
+            }
+            if (!inst)
+                continue;
+            if (inst.material !== source.material) {
+                inst.material = source.material;
+                p.tintFor = '';
+            }
+            if (inst.geometry !== source.geometry) {
+                inst.geometry = source.geometry;
+                inst.boundingSphere = null;
+                inst.boundingBox = null;
+            }
+            inst.visible = vis;
+            inst.castShadow = source.castShadow;
+            inst.receiveShadow = source.receiveShadow;
+            inst.customDepthMaterial = source.customDepthMaterial;
+            inst.customDistanceMaterial = source.customDistanceMaterial;
+            if (relDirty || slotsDirty) {
+                for (let k = 0; k < input.count; k++) {
+                    const slot = input.slot(k);
+                    inst.setMatrixAt(k, slot ? _m.multiplyMatrices(slot, p.rel) : ZERO);
+                }
+                inst.instanceMatrix.needsUpdate = true;
+                inst.boundingSphere = null; // frustum culling / picking recompute over the instances
+                inst.boundingBox = null;
+            }
+            this.writeTint(p, input);
+        }
+        return null;
+    }
+    rebuild(meshes, mirrored, count) {
+        this.disposeParts(false);
+        for (const source of meshes) {
+            if (mirrored) {
+                const list = [];
+                for (let k = 0; k < count; k++) {
+                    const m = new Mesh(source.geometry, source.material);
+                    m.name = `layout:${source.name || 'part'}#${k}`;
+                    m.userData.__opFxHelper = true;
+                    m.userData.layoutVariant = this.tag;
+                    m.userData.layoutCopy = k;
+                    m.matrixAutoUpdate = false;
+                    syncMirror(m, source);
+                    this.drawRoot.add(m);
+                    list.push(m);
+                }
+                source.layers.disableAll();
+                this.parts.push({ source, inst: null, mirrors: list, rel: new Matrix4(), relValid: false, tintFor: '', tintKey: null });
+                continue;
+            }
+            const inst = new InstancedMesh(source.geometry, source.material, Math.max(1, count));
+            inst.count = count;
+            inst.name = `layout:${source.name || 'part'}`;
+            inst.userData.__opFxHelper = true;
+            inst.userData.layoutVariant = this.tag;
+            inst.castShadow = source.castShadow;
+            inst.receiveShadow = source.receiveShadow;
+            inst.renderOrder = source.renderOrder;
+            this.drawRoot.add(inst);
+            source.layers.disableAll();
+            this.parts.push({ source, inst, mirrors: null, rel: new Matrix4(), relValid: false, tintFor: '', tintKey: null });
+        }
+        this.version++;
+    }
+    writeTint(p, input) {
+        const inst = p.inst;
+        const tinted = !!input.tint?.amount;
+        const base = colorOf(inst.material);
+        const hex = tinted && base ? base.getHexString() : '-';
+        const key = input.tint?.key ?? null;
+        if (p.tintFor === hex && p.tintKey === key)
+            return;
+        p.tintFor = hex;
+        p.tintKey = key;
+        if (!tinted || !base) {
+            // no instanceColor at all: three switches the program back (USE_INSTANCING_COLOR off)
+            if (inst.instanceColor)
+                inst.instanceColor = null;
+            return;
+        }
+        _base.copy(base).getHSL(_hsl);
+        for (let k = 0; k < input.count; k++) {
+            const [dh, dl] = input.tint.of(k);
+            _c.setHSL((((_hsl.h + dh) % 1) + 1) % 1, _hsl.s, Math.min(1, Math.max(0, _hsl.l + dl)));
+            // instanceColor multiplies the material colour: store the ratio
+            _c.setRGB(_base.r > 1e-4 ? _c.r / _base.r : _c.r, _base.g > 1e-4 ? _c.g / _base.g : _c.g, _base.b > 1e-4 ? _c.b / _base.b : _c.b);
+            inst.setColorAt(k, _c);
+        }
+        if (inst.instanceColor)
+            inst.instanceColor.needsUpdate = true;
+    }
+    disposeParts(restore) {
+        for (const p of this.parts) {
+            if (p.inst) {
+                p.inst.removeFromParent();
+                p.inst.dispose();
+            } // instance buffers only: geometry / material are the master's
+            p.mirrors?.forEach(m => m.removeFromParent()); // share everything: nothing to dispose
+            if (restore)
+                p.source.layers.enableAll(); // back on the render layers
+        }
+        this.parts = [];
+    }
+    /** Takes the drawing down and puts the master's meshes back on the render layers. */
+    dispose() {
+        this.disposeParts(true);
+        this.signature = '';
+        this.count = 0;
+        this.version++;
+    }
+}

package/dist/utils/svgAsset.d.ts

@@ -0,0 +1,6 @@
+/** The markup when it is already loaded, else null (and the fetch is started). */
+export declare function svgAssetSync(url: string | undefined): string | null;
+export declare const svgAssetError: (url: string | undefined) => string | undefined;
+/** Loads (once) and caches an .svg file's markup. */
+export declare function loadSvgAsset(url: string): Promise<string>;
+//# sourceMappingURL=svgAsset.d.ts.map

package/dist/utils/svgAsset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svgAsset.d.ts","sourceRoot":"","sources":["../../src/utils/svgAsset.ts"],"names":[],"mappings":"AAcA,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMnE;AAED,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAAgD,CAAC;AAElH,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBzD"}

package/dist/utils/svgAsset.js

@@ -0,0 +1,46 @@
+// =============================================================================
+// SVG assets for the `svg` mesh shape — fetched once, read synchronously by the shape generator
+// =============================================================================
+//
+// Shape generators are synchronous (utils/shapes.ts); an uploaded .svg is a URL, so its
+// markup is cached here. The first build with an unloaded URL yields an empty geometry
+// and starts the fetch; GeometryShape re-renders when it lands (useAsyncShapeTick).
+//
+import { toCdn } from '@3driseai/3drise-core';
+const loaded = new Map();
+const pending = new Map();
+const failed = new Map();
+/** The markup when it is already loaded, else null (and the fetch is started). */
+export function svgAssetSync(url) {
+    if (!url)
+        return null;
+    const hit = loaded.get(url);
+    if (hit !== undefined)
+        return hit;
+    if (!failed.has(url))
+        void loadSvgAsset(url).catch(() => undefined);
+    return null;
+}
+export const svgAssetError = (url) => (url ? failed.get(url) : undefined);
+/** Loads (once) and caches an .svg file's markup. */
+export function loadSvgAsset(url) {
+    const hit = loaded.get(url);
+    if (hit !== undefined)
+        return Promise.resolve(hit);
+    let p = pending.get(url);
+    if (!p) {
+        p = fetch(toCdn(url)).then(async (r) => {
+            if (!r.ok)
+                throw new Error(`SVG file: HTTP ${r.status}`);
+            const text = await r.text();
+            if (!/<svg[\s>]/i.test(text))
+                throw new Error('The file is not an SVG.');
+            loaded.set(url, text);
+            failed.delete(url);
+            pending.delete(url);
+            return text;
+        }).catch((e) => { failed.set(url, e?.message ?? String(e)); pending.delete(url); throw e; });
+        pending.set(url, p);
+    }
+    return p;
+}

package/dist/utils/waterLight.d.ts

@@ -0,0 +1,29 @@
+import * as THREE from 'three';
+import type { SkySettings, TimeSettings } from '@3driseai/3drise-core';
+import type { CloudSunState } from '../hooks/useCloudSun';
+import { type MoonState } from './skyMoon';
+/** Moonlight on the water relative to the sun's (sunIntensity 1). The key light
+ *  runs the moon at ~0.1 of the sun; the water gets a little more so the glitter
+ *  path reads at night. Tuning knob. */
+export declare const MOON_WATER_STRENGTH = 0.15;
+export interface WaterLightScratch {
+    moon: MoonState;
+}
+export declare function createWaterLightScratch(): WaterLightScratch;
+/**
+ * Light every water surface the same way: the scene sun (`useCloudSun`, so it
+ * follows the Environment clock — day, dusk, night) with the sky actually drawn
+ * as the ambient, and the moon's glitter path once the sun is down. Shared by
+ * the ocean surface and the `water` material family; a material that reads only
+ * some of these uniforms simply ignores the rest.
+ *
+ * Writes: u_sunDir, u_sunColor, u_sunIntensity, u_skyAmbient, u_groundAmbient
+ * (and the Preetham parameters, for shaders that draw the sky), u_skyBrightness,
+ * u_moonDir, u_moonColor.
+ *
+ * The two ambients and u_skyBrightness carry the sky dome's own brightness
+ * (skyBrightnessForSunElevation, what SkyMesh multiplies by): the analytic sky
+ * never darkens on its own after sunset, and water is mostly reflected sky.
+ */
+export declare function applyWaterLight(material: THREE.ShaderMaterial, sun: CloudSunState, sunIntensity: number, timeSettings: TimeSettings | undefined, skySettings: SkySettings | undefined, scratch: WaterLightScratch): void;
+//# sourceMappingURL=waterLight.d.ts.map

package/dist/utils/waterLight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waterLight.d.ts","sourceRoot":"","sources":["../../src/utils/waterLight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAkD,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3F;;wCAEwC;AACxC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAWxC,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,SAAS,CAAC;CACnB;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,GAAG,EAAE,aAAa,EAClB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,OAAO,EAAE,iBAAiB,GAC3B,IAAI,CA0BN"}

package/dist/utils/waterLight.js

@@ -0,0 +1,67 @@
+import * as THREE from 'three';
+import { skyBrightnessForSunElevation } from '@3driseai/3drise-core';
+import { applySunUniforms } from './cloudUniforms.js';
+import { applyTerrainAmbient } from './terrainUniforms.js';
+import { resolveMoon, moonlightFactor, MOON_LIGHT_COLOR } from './skyMoon.js';
+/** Moonlight on the water relative to the sun's (sunIntensity 1). The key light
+ *  runs the moon at ~0.1 of the sun; the water gets a little more so the glitter
+ *  path reads at night. Tuning knob. */
+export const MOON_WATER_STRENGTH = 0.15;
+/** Sun elevation (deg) over which direct sunlight on the water fades out — the
+ *  same window SunLight uses for the key light. */
+const SUN_FADE_START = -1;
+const SUN_FADE_END = 4;
+const smooth01 = (edge0, edge1, x) => {
+    const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));
+    return t * t * (3 - 2 * t);
+};
+export function createWaterLightScratch() {
+    return { moon: { direction: new THREE.Vector3(), illumination: 0 } };
+}
+/**
+ * Light every water surface the same way: the scene sun (`useCloudSun`, so it
+ * follows the Environment clock — day, dusk, night) with the sky actually drawn
+ * as the ambient, and the moon's glitter path once the sun is down. Shared by
+ * the ocean surface and the `water` material family; a material that reads only
+ * some of these uniforms simply ignores the rest.
+ *
+ * Writes: u_sunDir, u_sunColor, u_sunIntensity, u_skyAmbient, u_groundAmbient
+ * (and the Preetham parameters, for shaders that draw the sky), u_skyBrightness,
+ * u_moonDir, u_moonColor.
+ *
+ * The two ambients and u_skyBrightness carry the sky dome's own brightness
+ * (skyBrightnessForSunElevation, what SkyMesh multiplies by): the analytic sky
+ * never darkens on its own after sunset, and water is mostly reflected sky.
+ */
+export function applyWaterLight(material, sun, sunIntensity, timeSettings, skySettings, scratch) {
+    applySunUniforms(material, sun, sunIntensity);
+    // Overwrites the two ambient colours applySunUniforms just set. Those are
+    // the cloud curve, tuned for cloud interiors; water has to be lit by — and
+    // reflect — the sky actually being drawn behind it, or a sunset sea comes
+    // out black under a blazing sky.
+    applyTerrainAmbient(material, sun);
+    // The moon's glitter path and light on the water, from the same moon as the
+    // key light and the disc (resolveMoon), and the same strength curve
+    // (moonlightFactor), so all three appear and fade together.
+    const m = resolveMoon(timeSettings, sun.direction, scratch.moon);
+    const sunElevation = THREE.MathUtils.radToDeg(Math.asin(THREE.MathUtils.clamp(sun.direction.y, -1, 1)));
+    const k = MOON_WATER_STRENGTH * moonlightFactor(sunElevation, m) * (skySettings?.sunSystem?.moonIntensity ?? 1);
+    const u = material.uniforms;
+    // The sun's own light dies at the horizon, as the key light's does (SunLight
+    // fades over the same degrees): computeCloudSun's colour stays bright for a
+    // sun well below it, and a quarter of that lit every water body at midnight.
+    const sunUp = smooth01(SUN_FADE_START, SUN_FADE_END, sunElevation);
+    if (u.u_sunIntensity)
+        u.u_sunIntensity.value = sunIntensity * sunUp;
+    const bright = skyBrightnessForSunElevation(sunElevation);
+    if (u.u_skyBrightness)
+        u.u_skyBrightness.value = bright;
+    if (u.u_skyAmbient)
+        u.u_skyAmbient.value.multiplyScalar(bright);
+    if (u.u_groundAmbient)
+        u.u_groundAmbient.value.multiplyScalar(bright);
+    if (u.u_moonDir)
+        u.u_moonDir.value.copy(m.direction);
+    if (u.u_moonColor)
+        u.u_moonColor.value.setRGB(MOON_LIGHT_COLOR.r * k, MOON_LIGHT_COLOR.g * k, MOON_LIGHT_COLOR.b * k);
+}

package/dist/utils/waterReflection.d.ts

@@ -0,0 +1,185 @@
+import * as THREE from 'three';
+import type { RootState } from '@react-three/fiber';
+/**
+ * One reflection for all the water in a scene.
+ *
+ * Every water surface — the world ocean, a placed body, a mesh plane with the
+ * `water` material family — used to render the whole scene again for its own
+ * reflection (a six-face cube camera per plane: ~6x the scene's draw calls each,
+ * five pools took a 60 fps city to 11). Now a surface ASKS for a reflection and
+ * at most one gets it per frame:
+ *
+ * - the world ocean, when it asks (`reflection: 'planar'`);
+ * - else the planar-mode body that covers the most screen — area over distance
+ *   squared — as seen from the camera that frame;
+ * - every other surface shades its reflection from the sky it is drawn under
+ *   (`'env'`), or from nothing (`'off'`).
+ *
+ * The winner renders ONE mirrored view of the scene into a half-resolution
+ * target from its mesh's `onBeforeRender` (never a positive-priority useFrame:
+ * the cloud pass owns the render loop, see the ocean plan §9), and samples it
+ * with a world-space texture matrix. The two water shaders read the same three
+ * uniforms (`applyWaterReflection`), so the legacy material and the ocean
+ * surface cannot drift apart on this.
+ */
+export type WaterReflectionMode = 'planar' | 'baked' | 'env' | 'off';
+/** 0 off, 1 the sky, 2 the planar target, 3 the baked probe. What the shaders switch on. */
+export declare const WATER_REFLECTION_UNIFORM: Record<WaterReflectionMode, number>;
+export interface WaterReflectionSurface {
+    id: string;
+    /** The world ocean: wins outright when it asks for planar. */
+    world?: boolean;
+    /** The surface's root. Its world position is the plane's point, its world
+     *  scale sizes the area, and it is what the pass hides while it renders. */
+    object: THREE.Object3D;
+    /** Extent before the transform's scale, in local units (a body's `size`,
+     *  a plane's geometry). Ignored for the world ocean. */
+    size: () => [number, number];
+    /** Read every frame, so a live drag of the knob takes effect at once. */
+    mode: () => WaterReflectionMode;
+    /** Whether any of the surface's pixels passed the depth test last frame
+     *  (a WaterVisibility query). Absent = assumed visible (the world ocean). */
+    visible?: () => boolean;
+}
+export declare function noteWaterViewer(camera: THREE.Camera): void;
+/** The view camera's position as last noted, or null before the first draw. */
+export declare function waterViewerPosition(): THREE.Vector3 | null;
+/** Register a surface for the per-frame election. Returns the unregister. */
+export declare function registerWaterSurface(surface: WaterReflectionSurface): () => void;
+/**
+ * Which surface owns the reflection this frame. Computed once per frame (keyed
+ * on the frame clock, which R3F advances once before any useFrame runs), so every
+ * surface asking in the same frame gets the same answer.
+ */
+export declare function electedWaterSurface(state: RootState): string | null;
+export declare function isWaterMirrorPass(): boolean;
+/**
+ * A WebGL2 occlusion query around a water body's draw (begin at the end of its
+ * onBeforeRender, end in onAfterRender). The answer arrives a frame or two later
+ * and drives the election: a pond hidden behind the city is drawn (it is in the
+ * view frustum) but none of its pixels pass, so it gets no mirror. A body whose
+ * mesh was not drawn at all last frame (frustum-culled) is not visible either.
+ * WebGL1, or before the first answer: visible.
+ */
+export declare class WaterVisibility {
+    private gl;
+    private active;
+    private readonly pending;
+    private readonly free;
+    private passed;
+    private frame;
+    private drawnAt;
+    /** Once per frame, before the render (useFrame). */
+    tick(): void;
+    /** Visible as of the latest answer, and drawn in the last frame or two. */
+    isVisible(): boolean;
+    begin(renderer: THREE.WebGLRenderer): void;
+    end(): void;
+    private poll;
+    dispose(): void;
+}
+/**
+ * Mirrors the camera about a horizontal plane and renders the scene into a
+ * target (the three.js Reflector construction: mirrored camera, oblique near
+ * plane so nothing under the water leaks into the mirror, bias matrix so the
+ * fragment shader can project a world position straight into the texture).
+ */
+export declare class PlanarReflector {
+    readonly target: THREE.WebGLRenderTarget;
+    readonly textureMatrix: THREE.Matrix4;
+    private readonly camera;
+    private rendering;
+    /** Scratch for the outline clip (4 corners in, at most 8 points out). */
+    private readonly viewPts;
+    private readonly clipped;
+    /** True after a pass this frame actually drew; false when the camera was
+     *  under the plane and the target holds nothing to sample. */
+    valid: boolean;
+    constructor();
+    dispose(): void;
+    /**
+     * @param hide   the water mesh (or its root) — invisible while the mirror renders
+     * @param point  a world point on the water plane (the body's root position)
+     * @param scale  target size as a fraction of the drawing buffer (quality.reflectionScale)
+     * @param corners the water's outline on the plane, world space (a placed body's
+     *        four corners). The mirror is then rendered only for the rectangle they
+     *        cover in the mirror view — a sub-frustum (setViewOffset) and a target
+     *        that size — so everything not reflected in THIS water is frustum-culled
+     *        by the renderer and the target holds no unused pixels. null (the world
+     *        ocean, which covers everything below the horizon) renders the full view.
+     */
+    render(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, hide: THREE.Object3D, point: THREE.Vector3, scale: number, corners?: THREE.Vector3[] | null): boolean;
+    /**
+     * The rectangle the water's outline covers in the mirror view, as fractions
+     * of the frame [x, y (from the top), w, h], grown by RECT_MARGIN; null when it
+     * is most of the frame or a corner is behind the mirror camera (use the full
+     * view), 'offscreen' when none of it is in view.
+     */
+    private screenRect;
+}
+/**
+ * A reflection probe: the scene captured ONCE into a cubemap from just above
+ * the water, and sampled by the water every frame with a texture lookup.
+ *
+ * Why it is cheap: a planar mirror depends on where the camera is, so it must be
+ * re-rendered every frame the camera moves. The probe belongs to the WATER, not
+ * the view — the reflected ray from each fragment is looked up in it — so it
+ * stays valid while the camera moves and costs nothing per frame. It is
+ * re-captured only when it goes stale (the sun turned, the body moved, a slow
+ * refresh for scene edits), one cube face per frame so no frame pays for six.
+ *
+ * Why it is not exact: a cubemap is a picture from one point. The lookup is
+ * parallax-corrected against a sphere around the probe (`radius`), so the bank
+ * and the skyline sit roughly where they should across a large pond, but things
+ * close to the water and far from its centre are slightly off, and anything that
+ * moves is frozen until the next capture. Under ripples this reads the same as
+ * the mirror at a fraction of the cost; calm hero water seen close is what
+ * 'planar' is for. Every baked body has its own probe — no election.
+ */
+export declare class WaterProbe {
+    readonly size: number;
+    readonly target: THREE.WebGLCubeRenderTarget;
+    private readonly cube;
+    /** Where the last COMPLETE capture was taken: the centre of the lookup. */
+    readonly position: THREE.Vector3;
+    /** Parallax sphere radius, metres; 0 = everything infinitely far (the world ocean). */
+    radius: number;
+    /** True once all six faces have been drawn; until then the water shows the sky. */
+    valid: boolean;
+    /** Next face to draw; 6 = up to date. */
+    private face;
+    private again;
+    private readonly pending;
+    private readonly lastPos;
+    private readonly lastSun;
+    private readonly sunScratch;
+    private lastAt;
+    constructor(size: number);
+    dispose(): void;
+    /**
+     * Once per frame: where the probe should be and what the sun is doing. Marks
+     * the capture stale when the probe moved more than `moveTolerance` metres,
+     * the sun turned more than ~0.5 degrees, or `refreshSec` passed since the last
+     * capture (scene edits). A request while a capture is in flight finishes that
+     * capture first, then starts again.
+     */
+    request(pos: THREE.Vector3, sun: THREE.Vector3 | null, moveTolerance: number, nowSec: number, refreshSec?: number): void;
+    /** True while faces are still to be drawn. */
+    get stale(): boolean;
+    /**
+     * Draw the next stale face (at most one per call; the host calls once per
+     * frame from onBeforeRender). `hide` is the water itself.
+     */
+    step(renderer: THREE.WebGLRenderer, scene: THREE.Scene, hide: THREE.Object3D, layers: number): void;
+}
+/** Cube face size for a reflection resolution (quality.reflectionScale): 0.5 -> 256. */
+export declare function waterProbeSize(scale: number): number;
+/**
+ * Push the reflection state into a water material. `mode` is what the surface
+ * asked for; the pass is only handed over when this surface won the election
+ * and its pass drew, otherwise planar falls back to the sky for this frame.
+ */
+export declare function applyWaterReflection(uniforms: Record<string, THREE.IUniform>, mode: WaterReflectionMode, reflector: PlanarReflector | null, probe?: WaterProbe | null): void;
+/** GLSL shared by both water shaders: the three uniforms and the projected sample. */
+export declare const waterReflectionGlsl = "\nuniform int u_reflectionMode;        // 0 off, 1 sky, 2 planar target, 3 baked probe\nuniform sampler2D u_reflectionMap;\nuniform mat4 u_reflectionMatrix;\nuniform samplerCube u_reflectionCube;\nuniform vec3 u_probePos;\nuniform float u_probeRadius;         // parallax sphere; 0 = infinitely far\n\n/** The baked probe along the reflected ray. The normal is flattened by\n *  'distortion' (0 flat, 1 the full ripple) so the probe wobbles like the mirror\n *  rather than like a physically rough sea. The lookup direction is corrected\n *  against a sphere around the probe, so a fragment far from the probe still\n *  sees the bank where it is. Only valid when u_reflectionMode == 3. */\nvec3 waterProbeReflection(vec3 worldPos, vec3 viewDir, vec3 n, float distortion){\n  vec3 nb = normalize(vec3(n.x * distortion, max(n.y, 1e-3), n.z * distortion));\n  vec3 r = reflect(viewDir, nb);\n  r.y = max(r.y, 0.005);\n  r = normalize(r);\n  vec3 dir = r;\n  if (u_probeRadius > 0.0) {\n    vec3 o = worldPos - u_probePos;\n    float b = dot(o, r);\n    float c = dot(o, o) - u_probeRadius * u_probeRadius;\n    dir = o + r * (-b + sqrt(max(b * b - c, 0.0)));\n  }\n  return textureCube(u_reflectionCube, dir).rgb;\n}\n\n/** The mirrored scene at a world point, with the surface normal bending the\n *  lookup (the ripple distortion). Only valid when u_reflectionMode == 2. */\nvec3 waterPlanarReflection(vec3 worldPos, vec3 n, float distortion){\n  vec4 rc = u_reflectionMatrix * vec4(worldPos, 1.0);\n  vec2 uv = rc.xy / max(rc.w, 1e-4) + n.xz * distortion;\n  uv = clamp(uv, vec2(0.002), vec2(0.998));\n  return texture2D(u_reflectionMap, uv).rgb;\n}\n";
+//# sourceMappingURL=waterReflection.d.ts.map

package/dist/utils/waterReflection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waterReflection.d.ts","sourceRoot":"","sources":["../../src/utils/waterReflection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC;AAGrE,4FAA4F;AAC5F,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAA2C,CAAC;AAErH,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;gFAC4E;IAC5E,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB;4DACwD;IACxD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,yEAAyE;IACzE,IAAI,EAAE,MAAM,mBAAmB,CAAC;IAChC;iFAC6E;IAC7E,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CAC3B;AAwBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAI1D;AACD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,KAAK,CAAC,OAAO,GAAG,IAAI,CAE1D;AASD,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAMhF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CA4BnE;AAQD,wBAAgB,iBAAiB,IAAI,OAAO,CAAuB;AAEnE;;;;;;;GAOG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,EAAE,CAAuC;IACjD,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,OAAO,CAAO;IAEtB,oDAAoD;IACpD,IAAI,IAAI,IAAI;IAEZ,2EAA2E;IAC3E,SAAS,IAAI,OAAO;IAEpB,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,GAAG,IAAI;IAc1C,GAAG,IAAI,IAAI;IAOX,OAAO,CAAC,IAAI;IAWZ,OAAO,IAAI,IAAI;CAOlB;AAyBD;;;;;GAKG;AACH,qBAAa,eAAe;IACxB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAC;IACzC,QAAQ,CAAC,aAAa,gBAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,SAAS,CAAS;IAC1B,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwD;IAChF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwD;IAChF;kEAC8D;IAC9D,KAAK,UAAS;;IAWd,OAAO,IAAI,IAAI;IAEf;;;;;;;;;;OAUG;IACH,MAAM,CACF,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,IAAI,EAAE,KAAK,CAAC,QAAQ,EACpB,KAAK,EAAE,KAAK,CAAC,OAAO,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,KAAK,CAAC,OAAO,EAAE,GAAG,IAAW,GACvC,OAAO;IAwHV;;;;;OAKG;IACH,OAAO,CAAC,UAAU;CAiCrB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,UAAU;IAkBP,QAAQ,CAAC,IAAI,EAAE,MAAM;IAjBjC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,qBAAqB,CAAC;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,gBAAuB;IACxC,uFAAuF;IACvF,MAAM,SAAK;IACX,mFAAmF;IACnF,KAAK,UAAS;IACd,yCAAyC;IACzC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmD;IAC3E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,MAAM,CAAa;gBAEN,IAAI,EAAE,MAAM;IAUjC,OAAO,IAAI,IAAI;IAEf;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,SAAK,GAAG,IAAI;IAqBpH,8CAA8C;IAC9C,IAAI,KAAK,IAAI,OAAO,CAA0B;IAE9C;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAgDtG;AAOD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACxC,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,eAAe,GAAG,IAAI,EACjC,KAAK,GAAE,UAAU,GAAG,IAAW,GAChC,IAAI,CAaN;AAED,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,ynDAoC/B,CAAC"}