@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/hooks/useLandscapeMaps.js

@@ -0,0 +1,138 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import * as THREE from 'three';
+import { buildFieldTexture, buildTextureArray, decodeHeightmap, loadImage, smoothHeightfield, textureFromImage, } from '../utils/landscapeTextures.js';
+const EMPTY = {
+    height: null,
+    heightSize: new THREE.Vector2(1, 1),
+    field: null,
+    fieldSize: new THREE.Vector2(1, 1),
+    gradScale: 1,
+    diffuse: null,
+    normal: null,
+    splat0: null,
+    splat1: null,
+    ao: null,
+    means: [],
+    heightField: null,
+    ready: false,
+    error: null,
+    layerCount: 0,
+};
+function disposeState(state) {
+    state.height?.dispose();
+    state.field?.dispose();
+    state.diffuse?.dispose();
+    state.normal?.dispose();
+    state.splat0?.dispose();
+    state.splat1?.dispose();
+    state.ao?.dispose();
+}
+/** Only the URLs and the packing size matter; nothing here should re-run because
+ *  a slider moved. */
+function mapsKey(config, quality) {
+    return JSON.stringify([
+        config.heightMap,
+        config.heightEncoding,
+        config.splatMaps,
+        config.aoMap ?? '',
+        quality.arrayResolution,
+        quality.anisotropy,
+        config.surfaces.map((s) => [s.diffuse, s.normal ?? '', s.displacement ?? '']),
+    ]);
+}
+export function useLandscapeMaps(config, quality) {
+    const key = useMemo(() => mapsKey(config, quality), [config, quality]);
+    const [state, setState] = useState(EMPTY);
+    const current = useRef(EMPTY);
+    useEffect(() => {
+        let cancelled = false;
+        const surfaces = config.surfaces.filter((s) => !!s.diffuse);
+        if (!config.heightMap || surfaces.length === 0) {
+            setState({ ...EMPTY, error: null });
+            return () => { cancelled = true; };
+        }
+        const run = async () => {
+            const size = quality.arrayResolution;
+            const [heightImage, splatImages, aoImage, diffuseImages, normalImages, heightImages] = await Promise.all([
+                loadImage(config.heightMap),
+                Promise.all(config.splatMaps.slice(0, 2).map((url) => loadImage(url))),
+                config.aoMap ? loadImage(config.aoMap) : Promise.resolve(null),
+                Promise.all(surfaces.map((s) => loadImage(s.diffuse))),
+                Promise.all(surfaces.map((s) => (s.normal ? loadImage(s.normal) : Promise.resolve(null)))),
+                Promise.all(surfaces.map((s) => (s.displacement ? loadImage(s.displacement) : Promise.resolve(null)))),
+            ]);
+            if (cancelled)
+                return;
+            // Smoothed before anything else uses it. An 8-bit heightmap's own
+            // quantisation is a 1.33 m staircase over 340 m of relief, which is
+            // what RTIN's error metric measures instead of the terrain, and what
+            // the surface gradient would otherwise be computed from.
+            const raw = decodeHeightmap(heightImage, config.heightEncoding);
+            const heightField = smoothHeightfield(raw, 1);
+            const field = buildFieldTexture(heightField);
+            const height = textureFromImage(heightImage, THREE.NoColorSpace);
+            // No mips and no filtering surprises: the vertex stage samples this
+            // at lod 0 and the bicubic filter does its own footprint widening.
+            height.minFilter = THREE.LinearFilter;
+            height.magFilter = THREE.LinearFilter;
+            height.generateMipmaps = false;
+            const diffuse = buildTextureArray(diffuseImages, size, THREE.SRGBColorSpace);
+            const normal = buildTextureArray(normalImages, size, THREE.NoColorSpace, heightImages, 
+            // A flat normal for a surface with no normal map.
+            [128, 128, 255, 128]);
+            diffuse.texture.anisotropy = quality.anisotropy;
+            normal.texture.anisotropy = quality.anisotropy;
+            const splats = splatImages.map((image) => {
+                const texture = textureFromImage(image, THREE.NoColorSpace);
+                texture.generateMipmaps = false;
+                texture.minFilter = THREE.LinearFilter;
+                return texture;
+            });
+            const ao = aoImage ? textureFromImage(aoImage, THREE.NoColorSpace) : null;
+            if (cancelled) {
+                height.dispose();
+                field.texture.dispose();
+                diffuse.texture.dispose();
+                normal.texture.dispose();
+                splats.forEach((t) => t.dispose());
+                ao?.dispose();
+                return;
+            }
+            const next = {
+                height,
+                heightSize: new THREE.Vector2(heightField.tileSize, heightField.tileSize),
+                field: field.texture,
+                fieldSize: new THREE.Vector2(heightField.tileSize, heightField.tileSize),
+                gradScale: field.gradScale,
+                diffuse: diffuse.texture,
+                normal: normal.texture,
+                splat0: splats[0] ?? null,
+                splat1: splats[1] ?? null,
+                ao,
+                means: diffuse.means,
+                heightField,
+                ready: true,
+                error: null,
+                layerCount: surfaces.length,
+            };
+            const previous = current.current;
+            current.current = next;
+            setState(next);
+            // Only now — swapping first would blink the ground away mid-edit.
+            disposeState(previous);
+        };
+        run().catch((error) => {
+            if (cancelled)
+                return;
+            const message = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.error('[landscape] map load failed:', message);
+            setState({ ...EMPTY, error: message });
+        });
+        return () => { cancelled = true; };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    useEffect(() => () => { disposeState(current.current); }, []);
+    return state;
+}
+export default useLandscapeMaps;

package/dist/hooks/useOceanLive.d.ts

@@ -0,0 +1,29 @@
+import type { Object3D } from 'three';
+/**
+ * Live ocean editing, the counterpart to `useTerrainLive` and `useCloudLive`.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux would
+ * dispatch and re-render the tree sixty times a second, and for `quality` it is
+ * worse than that: a new quality object rebuilds every clipmap ring. So the
+ * controller finds the water with `findById(id)` and writes straight into the
+ * renderer; Redux only hears about it on slider end.
+ *
+ *   const live = useOceanLive(settings.id);
+ *   <BaseControllerUi onLiveChange={live.config} onSettingsChange={dispatch} ... />
+ *
+ * Pass the ID, not a resolved Object3D. The panel is routinely open before the
+ * thing it controls exists — water ships disabled, so the group is not in the
+ * scene at all until the section toggle is flipped — and a findById() memoised
+ * in the controller resolves to null exactly once and stays null for the rest of
+ * the session, after which every slider silently does nothing. Resolving here,
+ * at call time, is what makes that impossible.
+ */
+/** Where the renderer stashes its handle on the root object's userData. */
+export declare const OCEAN_LIVE_KEY = "__oceanLive";
+export interface OceanLiveHandle {
+    config(key: string, value: number | boolean | string): void;
+    quality(key: string, value: number | boolean | string): void;
+}
+export declare function useOceanLive(target?: Object3D | string | null): OceanLiveHandle;
+export default useOceanLive;
+//# sourceMappingURL=useOceanLive.d.ts.map

package/dist/hooks/useOceanLive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOceanLive.d.ts","sourceRoot":"","sources":["../../src/hooks/useOceanLive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC5B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CAChE;AAID,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,eAAe,CAY/E;AAED,eAAe,YAAY,CAAC"}

package/dist/hooks/useOceanLive.js

@@ -0,0 +1,38 @@
+import { useMemo } from 'react';
+import { findById } from '../utils/sceneQuery.js';
+/**
+ * Live ocean editing, the counterpart to `useTerrainLive` and `useCloudLive`.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux would
+ * dispatch and re-render the tree sixty times a second, and for `quality` it is
+ * worse than that: a new quality object rebuilds every clipmap ring. So the
+ * controller finds the water with `findById(id)` and writes straight into the
+ * renderer; Redux only hears about it on slider end.
+ *
+ *   const live = useOceanLive(settings.id);
+ *   <BaseControllerUi onLiveChange={live.config} onSettingsChange={dispatch} ... />
+ *
+ * Pass the ID, not a resolved Object3D. The panel is routinely open before the
+ * thing it controls exists — water ships disabled, so the group is not in the
+ * scene at all until the section toggle is flipped — and a findById() memoised
+ * in the controller resolves to null exactly once and stays null for the rest of
+ * the session, after which every slider silently does nothing. Resolving here,
+ * at call time, is what makes that impossible.
+ */
+/** Where the renderer stashes its handle on the root object's userData. */
+export const OCEAN_LIVE_KEY = '__oceanLive';
+const NOOP = { config: () => { }, quality: () => { } };
+export function useOceanLive(target) {
+    return useMemo(() => {
+        const resolve = () => {
+            const object = typeof target === 'string' ? findById(target) : target;
+            const handle = object?.userData?.[OCEAN_LIVE_KEY];
+            return handle ?? NOOP;
+        };
+        return {
+            config: (key, value) => resolve().config(key, value),
+            quality: (key, value) => resolve().quality(key, value),
+        };
+    }, [target]);
+}
+export default useOceanLive;

package/dist/hooks/useOceanMaterial.d.ts

@@ -0,0 +1,39 @@
+import * as THREE from 'three';
+import { type RootState } from '@react-three/fiber';
+import type { SkySettings, TimeSettings } from '@3driseai/3drise-core';
+import { OceanSurfaceMaterial } from '../shaders/ocean/OceanSurfaceMaterial';
+import type { OceanConfig, OceanQualityConfig } from '../types/oceanConfigs';
+/**
+ * Everything the two water hosts share: the material, the live-edit handle, and
+ * the per-frame uniform push.
+ *
+ * It exists so the world ocean and a placed body cannot drift apart. They differ
+ * in exactly one thing — the mesh — and the moment the frame loop is written
+ * twice, one of them gets a fix the other does not. That is the same mistake the
+ * environment made with two `SkySystem`s, documented in
+ * `claude/connector-pattern.md`.
+ *
+ * The caller owns the mesh (or meshes) and does whatever positioning its host
+ * needs; this owns the shading.
+ */
+export interface UseOceanMaterialOptions {
+    id: string;
+    config: OceanConfig;
+    quality: OceanQualityConfig;
+    skySettings?: SkySettings;
+    timeSettings?: TimeSettings;
+    sunIntensity?: number;
+    /** Runs after the uniforms are pushed, with the live overrides already
+     *  merged in — where a host does its own per-frame work (snapping the
+     *  clipmap to the camera, say) with the config it is actually rendering. */
+    onFrame?(config: OceanConfig, quality: OceanQualityConfig, state: RootState): void;
+}
+export interface OceanMaterialHandle {
+    material: OceanSurfaceMaterial;
+    /** Attach to the host's root group: it carries the scene id and the live
+     *  handle a controller reaches through `findById`. */
+    rootRef: React.RefObject<THREE.Group | null>;
+}
+export declare function useOceanMaterial({ id, config, quality, skySettings, timeSettings, sunIntensity, onFrame, }: UseOceanMaterialOptions): OceanMaterialHandle;
+export default useOceanMaterial;
+//# sourceMappingURL=useOceanMaterial.d.ts.map

package/dist/hooks/useOceanMaterial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOceanMaterial.d.ts","sourceRoot":"","sources":["../../src/hooks/useOceanMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAI7E,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE7E;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,uBAAuB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;gFAE4E;IAC5E,OAAO,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACtF;AAED,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;0DACsD;IACtD,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;CAChD;AAED,wBAAgB,gBAAgB,CAAC,EAC7B,EAAE,EACF,MAAM,EACN,OAAO,EACP,WAAW,EACX,YAAY,EACZ,YAAgB,EAChB,OAAO,GACV,EAAE,uBAAuB,GAAG,mBAAmB,CAkE/C;AAED,eAAe,gBAAgB,CAAC"}

package/dist/hooks/useOceanMaterial.js

@@ -0,0 +1,65 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { useCloudSun } from './useCloudSun.js';
+import { OCEAN_LIVE_KEY } from './useOceanLive.js';
+import { OceanSurfaceMaterial } from '../shaders/ocean/OceanSurfaceMaterial.js';
+import { applySunUniforms } from '../utils/cloudUniforms.js';
+import { applyTerrainAmbient } from '../utils/terrainUniforms.js';
+import { applyOceanUniforms } from '../utils/oceanUniforms.js';
+export function useOceanMaterial({ id, config, quality, skySettings, timeSettings, sunIntensity = 1, onFrame, }) {
+    const { state: sun, update: updateSun } = useCloudSun({ skySettings, timeSettings });
+    const material = useMemo(() => new OceanSurfaceMaterial(), []);
+    useEffect(() => () => { material.dispose(); }, [material]);
+    // Live controller overrides. A slider drag writes here on every pointer-move
+    // and the frame loop reads it on top of the config, so the water responds
+    // without a dispatch per frame — which for `quality` also means without
+    // rebuilding every clipmap ring sixty times a second. Cleared when the config
+    // identity changes, which is exactly slider-end committing the same value.
+    const liveConfig = useRef({});
+    const liveQuality = useRef({});
+    useEffect(() => { liveConfig.current = {}; }, [config]);
+    useEffect(() => { liveQuality.current = {}; }, [quality]);
+    const rootRef = useRef(null);
+    // Set in an effect, never as a userData JSX prop: R3F replaces the whole
+    // userData object on every render, which would drop the handle whenever
+    // anything above re-rendered.
+    const liveHandle = useMemo(() => ({
+        config: (key, value) => { liveConfig.current[key] = value; },
+        quality: (key, value) => { liveQuality.current[key] = value; },
+    }), []);
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        root.userData.id = id;
+        root.userData[OCEAN_LIVE_KEY] = liveHandle;
+        return () => { delete root.userData[OCEAN_LIVE_KEY]; };
+    }, [id, liveHandle]);
+    useFrame((state) => {
+        const shader = material;
+        updateSun();
+        applySunUniforms(shader, 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(shader, sun);
+        const cfg = { ...config, ...liveConfig.current };
+        const qual = { ...quality, ...liveQuality.current };
+        applyOceanUniforms(shader, cfg, qual);
+        shader.uniforms.u_time.value = state.clock.getElapsedTime();
+        // World size of one pixel at unit distance. The detail fade and the
+        // specular filtering are both screen-space decisions — whether a ripple
+        // is a shape or a shimmer depends on the field of view and the
+        // resolution, not on the distance — so the shader needs to know how big
+        // a pixel is. Recomputed per frame because a camera can zoom.
+        const camera = state.camera;
+        if (camera.isPerspectiveCamera) {
+            const height = Math.max(state.size.height * state.viewport.dpr, 1);
+            shader.uniforms.u_pixelScale.value = (2 * Math.tan((camera.fov * Math.PI) / 360)) / height;
+        }
+        onFrame?.(cfg, qual, state);
+    });
+    return { material, rootRef };
+}
+export default useOceanMaterial;

package/dist/hooks/useTerrainClipmap.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Terrain's view of the shared clipmap.
+ *
+ * The ring builder moved to `useClipmap` when the ocean started using it — the
+ * geometry, the geomorph attributes and the shared snapped origin were never
+ * terrain-specific, only the height field on top of them is. This file stays so
+ * existing imports and the package's public surface keep working; there is no
+ * terrain-only behaviour left in it.
+ */
+export { useClipmap, useClipmap as useTerrainClipmap, default } from './useClipmap';
+export type { Clipmap as TerrainClipmap, ClipmapLevel as TerrainClipmapLevel, Clipmap, ClipmapLevel } from './useClipmap';
+//# sourceMappingURL=useTerrainClipmap.d.ts.map

package/dist/hooks/useTerrainClipmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTerrainClipmap.d.ts","sourceRoot":"","sources":["../../src/hooks/useTerrainClipmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,IAAI,iBAAiB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACpF,YAAY,EAAE,OAAO,IAAI,cAAc,EAAE,YAAY,IAAI,mBAAmB,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/hooks/useTerrainClipmap.js

@@ -0,0 +1,10 @@
+/**
+ * Terrain's view of the shared clipmap.
+ *
+ * The ring builder moved to `useClipmap` when the ocean started using it — the
+ * geometry, the geomorph attributes and the shared snapped origin were never
+ * terrain-specific, only the height field on top of them is. This file stays so
+ * existing imports and the package's public surface keep working; there is no
+ * terrain-only behaviour left in it.
+ */
+export { useClipmap, useClipmap as useTerrainClipmap, default } from './useClipmap.js';

package/dist/hooks/useTerrainLive.d.ts

@@ -0,0 +1,34 @@
+import type { Object3D } from 'three';
+/**
+ * Live terrain editing, the counterpart to `useCloudLive`.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux would
+ * dispatch and re-render the tree sixty times a second — and here it is worse
+ * than for the clouds, because a new `quality` object rebuilds every clipmap ring
+ * from scratch. So the controller finds the terrain with `findById(id)` and
+ * writes straight into the renderer; Redux only hears about it on slider end.
+ *
+ *   const live = useTerrainLive(settings.id);
+ *   <BaseControllerUi onLiveChange={live.config} onSettingsChange={dispatchToRedux} ... />
+ *
+ * Pass the ID, not a resolved Object3D. The panel is routinely open before the
+ * thing it controls exists — terrain ships disabled, so the group is not in the
+ * scene at all until the section toggle is flipped — and a findById() memoised in
+ * the controller resolves to null exactly once and stays null for the rest of the
+ * session. Every slider then silently does nothing until the controller happens to
+ * remount. Resolving here, at call time, is what makes that impossible.
+ */
+/** Where TerrainSurface stashes its handle on the root object's userData. */
+export declare const TERRAIN_LIVE_KEY = "__terrainLive";
+export interface TerrainLiveHandle {
+    config(key: string, value: number | boolean | string): void;
+    quality(key: string, value: number | boolean | string): void;
+}
+/**
+ * Safe before the terrain mounts and after it unmounts: the handle is resolved at
+ * call time, not at hook time, so a controller opened before the scene is ready
+ * still works once it is, and a stale reference degrades to a no-op.
+ */
+export declare function useTerrainLive(target?: Object3D | string | null): TerrainLiveHandle;
+export default useTerrainLive;
+//# sourceMappingURL=useTerrainLive.d.ts.map

package/dist/hooks/useTerrainLive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTerrainLive.d.ts","sourceRoot":"","sources":["../../src/hooks/useTerrainLive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAC9B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CAChE;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,iBAAiB,CAcnF;AAED,eAAe,cAAc,CAAC"}

package/dist/hooks/useTerrainLive.js

@@ -0,0 +1,45 @@
+import { useMemo } from 'react';
+import { findById } from '../utils/sceneQuery.js';
+/**
+ * Live terrain editing, the counterpart to `useCloudLive`.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux would
+ * dispatch and re-render the tree sixty times a second — and here it is worse
+ * than for the clouds, because a new `quality` object rebuilds every clipmap ring
+ * from scratch. So the controller finds the terrain with `findById(id)` and
+ * writes straight into the renderer; Redux only hears about it on slider end.
+ *
+ *   const live = useTerrainLive(settings.id);
+ *   <BaseControllerUi onLiveChange={live.config} onSettingsChange={dispatchToRedux} ... />
+ *
+ * Pass the ID, not a resolved Object3D. The panel is routinely open before the
+ * thing it controls exists — terrain ships disabled, so the group is not in the
+ * scene at all until the section toggle is flipped — and a findById() memoised in
+ * the controller resolves to null exactly once and stays null for the rest of the
+ * session. Every slider then silently does nothing until the controller happens to
+ * remount. Resolving here, at call time, is what makes that impossible.
+ */
+/** Where TerrainSurface stashes its handle on the root object's userData. */
+export const TERRAIN_LIVE_KEY = '__terrainLive';
+const NOOP = { config: () => { }, quality: () => { } };
+/**
+ * Safe before the terrain mounts and after it unmounts: the handle is resolved at
+ * call time, not at hook time, so a controller opened before the scene is ready
+ * still works once it is, and a stale reference degrades to a no-op.
+ */
+export function useTerrainLive(target) {
+    return useMemo(() => {
+        const resolve = () => {
+            // Resolved per call, never cached. See the note above: the scene object
+            // usually does not exist yet when the controller first renders.
+            const object = typeof target === 'string' ? findById(target) : target;
+            const handle = object?.userData?.[TERRAIN_LIVE_KEY];
+            return handle ?? NOOP;
+        };
+        return {
+            config: (key, value) => resolve().config(key, value),
+            quality: (key, value) => resolve().quality(key, value),
+        };
+    }, [target]);
+}
+export default useTerrainLive;

package/dist/index.d.ts

@@ -11,7 +11,33 @@ export * from './utils/shapes';
 export { applyGenerativeAnimations } from './utils/handleGenerativeEffectsAnimations';
 export { hasHoverAnimation } from './utils/hasHoverAnimation';
 export { findById } from './utils/sceneQuery';
+export { hasFrameRenderer, registerFrameRenderer, renderFrame } from './utils/frameRenderer';
+export type { FrameRenderer } from './utils/frameRenderer';
 export { resolveObject3D } from './utils/resolveObject3D';
 export type { Object3DRefLike, Object3DSource } from './utils/resolveObject3D';
 export * from './utils/textEffects';
+export { applyTerrainUniforms } from './utils/terrainUniforms';
+export { applyLandscapeMaps, applyLandscapeUniforms } from './utils/landscapeUniforms';
+export type { LandscapeMapUniforms } from './utils/landscapeUniforms';
+export { getLandscapeHeightAt, registerLandscapeHeightField, sampleLandscapeHeight, snapToLandscape, unregisterLandscapeHeightField, } from './utils/landscapeHeight';
+export type { LandscapeHeightField } from './utils/landscapeHeight';
+export { buildLandscapeGeometry, rtinTileFor, setLandscapeBounds } from './utils/landscapeGeometry';
+export type { LandscapeChunk, LandscapeGeometry } from './utils/landscapeGeometry';
+export { Rtin, RtinTile } from './utils/rtin';
+export { buildTextureArray, decodeHeightmap, loadImage } from './utils/landscapeTextures';
+export type { DecodedHeightmap } from './utils/landscapeTextures';
+export { applyOceanUniforms, buildWaveTable, seaState } from './utils/oceanUniforms';
+export type { WaveTable } from './utils/oceanUniforms';
+export { applyCameraUniforms, applyCirrusUniforms, applyDeckUniforms, applySunUniforms, } from './utils/cloudUniforms';
+export { applyCloudsKeyframeAnimations, applyCloudsMouseMove, resolveDeckConfig, } from './utils/handleCloudsAnimations';
+export { volumetricCloudPresets, cirrusPresets, getCloudPresetsForType, getCloudPresetByName, getCirrusPresetByName, searchCloudPresetsByTags, } from './presets/volumetricCloudPresets';
+export type { VolumetricCloudPreset, CirrusPreset } from './presets/volumetricCloudPresets';
+export { terrainPresets, getTerrainPresetsForType, getTerrainPresetByName, searchTerrainPresetsByTags, } from './presets/terrainPresets';
+export type { TerrainPreset } from './presets/terrainPresets';
+export { getLandscapePresetByName, landscapePresetAssetNames, landscapePresets, resolveLandscapePreset, searchLandscapePresetsByTags, } from './presets/landscapePresets';
+export type { LandscapeAssetResolver, LandscapePreset, ResolvedLandscapePreset, } from './presets/landscapePresets';
+export { LANDSCAPE_DETAIL, detectLandscapeDetail, getLandscapeShape, getLandscapeType, landscapeQualityForDetail, landscapeShapes, landscapeTypePacks, landscapeTypeAvailability, landscapeTypes, repeatForMetres, resolveLandscapeType, } from './presets/landscapeTypes';
+export type { LandscapeAssetIndex, LandscapeDetail, LandscapePackRef, LandscapeShapeDef, LandscapeTypeAvailability, LandscapeTypeDef, ResolvedLandscapeType, } from './presets/landscapeTypes';
+export { oceanSurfacePresets, getOceanPresetsForType, getOceanPresetByName, searchOceanPresetsByTags, } from './presets/oceanSurfacePresets';
+export type { OceanPreset } from './presets/oceanSurfacePresets';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG1F,OAAO,EAAE,iBAAiB,IAAI,iBAAiB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAG5F,cAAc,SAAS,CAAC;AAGxB,cAAc,cAAc,CAAC;AAG7B,cAAc,SAAS,CAAC;AAExB,YAAY,EAAE,oBAAoB,IAAI,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAGjG,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,GAAG,MAAM,iBAAiB,CAAC;AACrG,OAAO,EAAE,mBAAmB,IAAI,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACvF,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC/E,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -14,5 +14,21 @@ export * from './utils/shapes.js';
 export { applyGenerativeAnimations } from './utils/handleGenerativeEffectsAnimations.js';
 export { hasHoverAnimation } from './utils/hasHoverAnimation.js';
 export { findById } from './utils/sceneQuery.js';
+export { hasFrameRenderer, registerFrameRenderer, renderFrame } from './utils/frameRenderer.js';
 export { resolveObject3D } from './utils/resolveObject3D.js';
 export * from './utils/textEffects.js';
+export { applyTerrainUniforms } from './utils/terrainUniforms.js';
+export { applyLandscapeMaps, applyLandscapeUniforms } from './utils/landscapeUniforms.js';
+export { getLandscapeHeightAt, registerLandscapeHeightField, sampleLandscapeHeight, snapToLandscape, unregisterLandscapeHeightField, } from './utils/landscapeHeight.js';
+export { buildLandscapeGeometry, rtinTileFor, setLandscapeBounds } from './utils/landscapeGeometry.js';
+export { Rtin, RtinTile } from './utils/rtin.js';
+export { buildTextureArray, decodeHeightmap, loadImage } from './utils/landscapeTextures.js';
+export { applyOceanUniforms, buildWaveTable, seaState } from './utils/oceanUniforms.js';
+export { applyCameraUniforms, applyCirrusUniforms, applyDeckUniforms, applySunUniforms, } from './utils/cloudUniforms.js';
+export { applyCloudsKeyframeAnimations, applyCloudsMouseMove, resolveDeckConfig, } from './utils/handleCloudsAnimations.js';
+// Presets
+export { volumetricCloudPresets, cirrusPresets, getCloudPresetsForType, getCloudPresetByName, getCirrusPresetByName, searchCloudPresetsByTags, } from './presets/volumetricCloudPresets.js';
+export { terrainPresets, getTerrainPresetsForType, getTerrainPresetByName, searchTerrainPresetsByTags, } from './presets/terrainPresets.js';
+export { getLandscapePresetByName, landscapePresetAssetNames, landscapePresets, resolveLandscapePreset, searchLandscapePresetsByTags, } from './presets/landscapePresets.js';
+export { LANDSCAPE_DETAIL, detectLandscapeDetail, getLandscapeShape, getLandscapeType, landscapeQualityForDetail, landscapeShapes, landscapeTypePacks, landscapeTypeAvailability, landscapeTypes, repeatForMetres, resolveLandscapeType, } from './presets/landscapeTypes.js';
+export { oceanSurfacePresets, getOceanPresetsForType, getOceanPresetByName, searchOceanPresetsByTags, } from './presets/oceanSurfacePresets.js';

package/dist/presets/landscapePresets.d.ts

@@ -0,0 +1,60 @@
+import type { LandscapeConfig, LandscapeSurface } from '../types/landscapeConfigs';
+/**
+ * Starter landscapes.
+ *
+ * **A preset names files, not URLs.** Where those files actually live is the
+ * client's business — they are uploaded assets served from Digital Ocean Spaces,
+ * and the viewer has no idea what a bucket is. So each preset carries bare file
+ * names and `resolveLandscapePreset` turns them into a config once the caller
+ * supplies a lookup. That is the same rule as everywhere else in this package:
+ * rendering lives here, everything that knows about the app lives in the client.
+ *
+ * A preset is also a PATCH over the defaults, never a whole config, so a knob
+ * added later is picked up by every preset instead of being frozen at whatever
+ * the preset was written with.
+ */
+export interface LandscapePreset {
+    name: string;
+    description: string;
+    tags: string[];
+    /** File names this preset needs. Resolution happens in the client. */
+    assets: {
+        heightMap: string;
+        splatMaps?: string[];
+        aoMap?: string;
+    };
+    /** Surfaces with `diffuse` / `normal` / `displacement` as FILE NAMES. */
+    surfaces: LandscapeSurface[];
+    /** Everything that is not an asset reference. */
+    settings: Partial<LandscapeConfig>;
+}
+export declare const landscapePresets: LandscapePreset[];
+/** Turns one file name into a URL, or null when the asset is not there. */
+export type LandscapeAssetResolver = (fileName: string) => string | null;
+export interface ResolvedLandscapePreset {
+    /** The config patch, with every asset reference resolved to a URL. */
+    config: Partial<LandscapeConfig>;
+    /** File names the resolver could not find. Empty means the preset is whole. */
+    missing: string[];
+}
+/**
+ * Fill a preset's file names in from wherever the caller keeps its assets.
+ *
+ * Surfaces whose diffuse cannot be resolved are dropped rather than rendered as
+ * a hole — a surface with no albedo is skipped by the renderer anyway, and an
+ * empty slot in the middle of the list would silently shift every splat channel
+ * after it. A missing normal or height map is not fatal: those degrade to a flat
+ * normal and a linear blend, which is what the reference implementation does for
+ * every surface always.
+ *
+ * The heightmap is the one thing that cannot be missing — without it there is no
+ * landscape — so an unresolved heightmap returns a config with `enabled: false`
+ * and the name in `missing`, for the panel to say so.
+ */
+export declare function resolveLandscapePreset(preset: LandscapePreset, resolve: LandscapeAssetResolver): ResolvedLandscapePreset;
+export declare function getLandscapePresetByName(name: string): LandscapePreset | undefined;
+/** Every file name the built-in presets need, for a client that wants to check
+ *  what is uploaded before offering them. */
+export declare function landscapePresetAssetNames(): string[];
+export declare function searchLandscapePresetsByTags(tags: string[]): LandscapePreset[];
+//# sourceMappingURL=landscapePresets.d.ts.map

package/dist/presets/landscapePresets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscapePresets.d.ts","sourceRoot":"","sources":["../../src/presets/landscapePresets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAGlF;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,sEAAsE;IACtE,MAAM,EAAE;QACJ,SAAS,EAAE,MAAM,CAAA;QACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;QACpB,KAAK,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;IACD,yEAAyE;IACzE,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;CACrC;AAkED,eAAO,MAAM,gBAAgB,EAAE,eAAe,EAwD7C,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,sBAAsB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;AAExE,MAAM,WAAW,uBAAuB;IACpC,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;IAChC,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAA;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,sBAAsB,GAChC,uBAAuB,CAwCzB;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAElF;AAED;6CAC6C;AAC7C,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAapD;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,EAAE,CAK9E"}