@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/types/terrainConfigs.js

@@ -0,0 +1,292 @@
+/**
+ * Config shapes for the procedural terrain system that lives in this package.
+ *
+ * Declared locally rather than in `@3driseai/3drise-core`, alongside
+ * `cloudConfigs.ts` and `gridConfigs.ts`, because the material and the renderer
+ * are here and nothing outside the viewer needs to construct these by hand.
+ *
+ * Core's `TerrainSettings` is the retired flat shape (`visible` +
+ * `displacementScale`) and is deliberately left alone: a saved project still
+ * carries it, and `normalizeTerrain` below is what turns one into nothing rather
+ * than into a mountain range the scene was never authored with.
+ *
+ * A terrain is ONE landform model with per-type shaping, not four renderers —
+ * the same way three of the four cloud types share one marcher. What separates
+ * mountains from dunes is the operator applied to the fBm and the numbers around
+ * it, so the type is a config field the shader branches on.
+ */
+// -----------------------------------------------------------------------------
+// Defaults
+// -----------------------------------------------------------------------------
+const surfaceBase = {
+    elevation: 1200,
+    seaLevel: 0,
+    featureSize: 2600,
+    octaves: 9,
+    lacunarity: 2.06,
+    gain: 0.52,
+    ridgeSharpness: 0.62,
+    warpStrength: 0.28,
+    warpSize: 0.6,
+    erosion: 0.7,
+    terraces: 0,
+    terraceSharpness: 0.6,
+    bearing: 78,
+    duneWavelength: 320,
+    duneAsymmetry: 0.6,
+    plateau: 0,
+    valleyDepth: 0,
+    valleyWidth: 0.25,
+    lowColor: '#4a4636',
+    midColor: '#6b6248',
+    rockColor: '#6a6259',
+    peakColor: '#eef1f6',
+    slopeRockStart: 0.35,
+    slopeRockEnd: 0.62,
+    peakLevel: 0.62,
+    peakBlend: 0.12,
+    peakSlopeFalloff: 1.4,
+    macroVariation: 0.22,
+    macroSize: 2400,
+    detailStrength: 0.45,
+    detailSize: 9,
+    roughness: 0.82,
+    specular: 0.06,
+    ambient: 1,
+    bounce: 0.35,
+    sunShadow: 1,
+    shadowSoftness: 12,
+    aerialPerspective: 0.00007,
+};
+export const defaultMountainsConfig = {
+    ...surfaceBase,
+    type: 'terrain',
+    terrainType: 'mountains',
+    preset: '',
+    enabled: true,
+};
+export const defaultHillsConfig = {
+    ...surfaceBase,
+    type: 'terrain',
+    terrainType: 'hills',
+    preset: '',
+    enabled: true,
+    elevation: 300,
+    featureSize: 2200,
+    octaves: 8,
+    gain: 0.46,
+    ridgeSharpness: 0.05,
+    warpStrength: 0.35,
+    erosion: 0.45,
+    lowColor: '#3f5326',
+    midColor: '#55663a',
+    rockColor: '#7a7266',
+    peakColor: '#8d9a6a',
+    slopeRockStart: 0.5,
+    slopeRockEnd: 0.78,
+    peakLevel: 0.78,
+    peakBlend: 0.2,
+    macroVariation: 0.3,
+    macroSize: 1400,
+    detailStrength: 0.5,
+    detailSize: 6,
+    roughness: 0.9,
+    specular: 0.03,
+    aerialPerspective: 0.00009,
+};
+export const defaultDunesConfig = {
+    ...surfaceBase,
+    type: 'terrain',
+    terrainType: 'dunes',
+    preset: '',
+    enabled: true,
+    elevation: 150,
+    featureSize: 3000,
+    octaves: 6,
+    gain: 0.42,
+    ridgeSharpness: 0.15,
+    warpStrength: 0.2,
+    warpSize: 0.8,
+    erosion: 0.2,
+    duneWavelength: 340,
+    duneAsymmetry: 0.62,
+    lowColor: '#b08a53',
+    midColor: '#d6b077',
+    rockColor: '#9c7a4c',
+    peakColor: '#f0dcb4',
+    slopeRockStart: 0.62,
+    slopeRockEnd: 0.9,
+    peakLevel: 0.7,
+    peakBlend: 0.24,
+    peakSlopeFalloff: 0.6,
+    macroVariation: 0.14,
+    macroSize: 3600,
+    detailStrength: 0.3,
+    detailSize: 3.5,
+    roughness: 0.55,
+    specular: 0.16,
+    ambient: 1.1,
+    bounce: 0.55,
+    shadowSoftness: 22,
+    aerialPerspective: 0.00008,
+};
+export const defaultCanyonConfig = {
+    ...surfaceBase,
+    type: 'terrain',
+    terrainType: 'canyon',
+    preset: '',
+    enabled: true,
+    elevation: 700,
+    featureSize: 2600,
+    octaves: 8,
+    gain: 0.48,
+    ridgeSharpness: 0.3,
+    warpStrength: 0.18,
+    erosion: 0.85,
+    terraces: 14,
+    terraceSharpness: 0.72,
+    plateau: 0.55,
+    valleyDepth: 0.8,
+    valleyWidth: 0.22,
+    lowColor: '#7a4a30',
+    midColor: '#a4643c',
+    rockColor: '#c07a4a',
+    peakColor: '#d9a877',
+    slopeRockStart: 0.28,
+    slopeRockEnd: 0.5,
+    peakLevel: 0.72,
+    peakBlend: 0.08,
+    peakSlopeFalloff: 0.9,
+    macroVariation: 0.26,
+    macroSize: 1800,
+    detailStrength: 0.4,
+    detailSize: 7,
+    roughness: 0.86,
+    specular: 0.05,
+    shadowSoftness: 8,
+    aerialPerspective: 0.000075,
+};
+export const defaultTerrainQuality = {
+    levels: 9,
+    segments: 128,
+    cellSize: 2,
+    curvature: 1 / (2 * 6371000),
+    shadowSteps: 12,
+    shadowDistance: 5000,
+    detailFadeDistance: 1200,
+    receiveShadows: true,
+    exposure: 1,
+    wireframe: false,
+};
+/** Per-type defaults, for the controller's type switcher. */
+export const TERRAIN_DEFAULTS = {
+    mountains: defaultMountainsConfig,
+    dunes: defaultDunesConfig,
+    hills: defaultHillsConfig,
+    canyon: defaultCanyonConfig,
+};
+export const TERRAIN_SCHEMA = [
+    { key: 'elevation', label: 'Elevation', group: 'form', min: 5, max: 6000, step: 5, unit: 'm', description: 'Peak height above sea level. Every height-keyed splat threshold is a fraction of this, so raising it does not move the snow line.' },
+    { key: 'seaLevel', label: 'Sea level', group: 'form', min: -2000, max: 2000, step: 5, unit: 'm', description: 'World Y the terrain is built around — where flat ground sits, and where a placed object meets it.' },
+    { key: 'featureSize', label: 'Feature size', group: 'form', min: 200, max: 40000, step: 50, unit: 'm', description: 'Horizontal size of the primary landform. The one knob that decides whether this reads as a mountain range or a gravel pile.' },
+    { key: 'octaves', label: 'Octaves', group: 'form', min: 3, max: 12, step: 1, description: 'fBm detail levels. Past ~10 the extra octaves are finer than the closest clipmap cell and only cost; distant rings drop them automatically.' },
+    { key: 'lacunarity', label: 'Lacunarity', group: 'form', min: 1.7, max: 2.6, step: 0.01, advanced: true, description: 'Frequency step per octave. Slightly off 2.0 breaks the grid alignment that otherwise shows as a faint square lattice.' },
+    { key: 'gain', label: 'Gain', group: 'form', min: 0.25, max: 0.72, step: 0.005, description: 'Amplitude step per octave. Below 0.5 smooth and rolling, above it jagged and fractal.' },
+    { key: 'ridgeSharpness', label: 'Ridge sharpness', group: 'form', min: 0, max: 1, step: 0.005, description: '0 gives rounded billow hills, 1 knife ridges. The strongest single cue between a mountain and a dune field.' },
+    { key: 'warpStrength', label: 'Domain warp', group: 'form', min: 0, max: 1, step: 0.005, description: 'Bends ridge lines into curved, branching shapes. At 0 the silhouette reads as noise rather than landscape.' },
+    { key: 'warpSize', label: 'Warp size', group: 'form', min: 0.1, max: 2, step: 0.01, advanced: true, description: 'Scale of the warp field relative to feature size. Above ~1 it drifts the terrain instead of bending it.' },
+    { key: 'erosion', label: 'Erosion', group: 'form', min: 0, max: 1, step: 0.005, description: 'Damps octaves where slope is already steep — flattens valley floors, sharpens flanks. The cheapest approximation of erosion there is.' },
+    { key: 'terraces', label: 'Strata', group: 'form', min: 0, max: 40, step: 1, types: ['canyon', 'mountains'], description: 'Sedimentary banding step count. 0 is off. Most of what makes a mesa read as a mesa.' },
+    { key: 'terraceSharpness', label: 'Strata hardness', group: 'form', min: 0, max: 1, step: 0.01, types: ['canyon', 'mountains'], description: '0 is a smooth ramp between bands, 1 a near-vertical riser.' },
+    { key: 'plateau', label: 'Plateau', group: 'form', min: 0, max: 1, step: 0.005, types: ['canyon'], description: 'Fraction of the height range flattened into mesa tops.' },
+    { key: 'valleyDepth', label: 'Incision depth', group: 'form', min: 0, max: 1.5, step: 0.005, types: ['canyon'], description: 'Depth of the carved channel network as a fraction of elevation. At 0 the mesas have nothing between them.' },
+    { key: 'valleyWidth', label: 'Incision width', group: 'form', min: 0.03, max: 1, step: 0.005, types: ['canyon'], description: 'Narrow cuts slot canyons; wide ones cut broad washes.' },
+    { key: 'bearing', label: 'Wind bearing', group: 'form', min: 0, max: 360, step: 1, unit: 'deg', types: ['dunes'], description: 'Dunes are transverse to the wind, so this rotates the whole crest train.' },
+    { key: 'duneWavelength', label: 'Dune wavelength', group: 'form', min: 40, max: 2000, step: 5, unit: 'm', types: ['dunes'], description: 'Crest-to-crest distance of the dune train.' },
+    { key: 'duneAsymmetry', label: 'Slip face', group: 'form', min: 0, max: 1, step: 0.005, types: ['dunes'], description: 'Lee-slope steepening. At 0 the dunes are sine waves; real ones have a long windward ramp and a short face at the angle of repose.' },
+    { key: 'slopeRockStart', label: 'Rock from slope', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Slope at which rock starts showing through. Splatting rock by slope rather than height is what makes a cliff read as a cliff at any altitude.' },
+    { key: 'slopeRockEnd', label: 'Bare rock at slope', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Slope at which the surface is fully bare rock.' },
+    { key: 'peakLevel', label: 'Peak line', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Height fraction where the peak layer (snow, salt, bleached stone) begins.' },
+    { key: 'peakBlend', label: 'Peak blend', group: 'surface', min: 0.01, max: 0.5, step: 0.005, description: 'Width of that transition. A hard line is physically right for temperature but reads as a decal.' },
+    { key: 'peakSlopeFalloff', label: 'Peak slope falloff', group: 'surface', min: 0, max: 3, step: 0.01, description: 'Peak coverage lost per unit slope. Snow does not sit on a vertical face; without this a summit looks dipped in paint.' },
+    { key: 'macroVariation', label: 'Macro variation', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Large-scale albedo break-up. Without it a splat layer is one flat colour across kilometres and reads as untextured.' },
+    { key: 'macroSize', label: 'Macro size', group: 'surface', min: 200, max: 12000, step: 50, unit: 'm', description: 'Size of that variation.' },
+    { key: 'detailStrength', label: 'Detail bump', group: 'surface', min: 0, max: 1.5, step: 0.005, description: 'High-frequency normal detail added per fragment — bumps far below the mesh resolution.' },
+    { key: 'detailSize', label: 'Detail size', group: 'surface', min: 0.5, max: 60, step: 0.25, unit: 'm', description: 'Size of that detail. Below about a metre it aliases before it fades.' },
+    { key: 'roughness', label: 'Roughness', group: 'surface', min: 0.05, max: 1, step: 0.005, description: 'Widens the specular lobe. Rock is nearly matte; wet sand and snow are not.' },
+    { key: 'specular', label: 'Specular', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Specular strength. The grazing sheen on sand at low sun comes from here.' },
+    { key: 'ambient', label: 'Ambient', group: 'lighting', min: 0, max: 3, step: 0.01, description: 'Sky-dome fill, taken from the same atmosphere the sky and clouds use, so it darkens and warms as the sun sets instead of freezing.' },
+    { key: 'bounce', label: 'Ground bounce', group: 'lighting', min: 0, max: 2, step: 0.01, description: 'Fill on downward-facing surfaces, tinted by the low colour. Keeps overhangs and north faces off pure black.' },
+    { key: 'sunShadow', label: 'Self shadow', group: 'lighting', min: 0, max: 1, step: 0.01, description: 'Strength of the analytic shadow marched down the sun vector. This is what puts a mountain shadow in its own valley, with no shadow-map resolution to run out of.' },
+    { key: 'shadowSoftness', label: 'Shadow softness', group: 'lighting', min: 1, max: 60, step: 0.5, description: 'Penumbra width of that shadow. Larger reads as a hazier day.' },
+    { key: 'aerialPerspective', label: 'Aerial perspective', group: 'lighting', min: 0, max: 0.0004, step: 0.000002, unit: '1/m', description: 'Rate distant terrain fades into the sky behind it. The main cue for how large the landscape reads, and what makes the horizon a horizon rather than a cut-out.' },
+];
+export const TERRAIN_QUALITY_SCHEMA = [
+    { key: 'levels', label: 'Clipmap levels', group: 'quality', min: 2, max: 12, step: 1, description: 'Each ring doubles its cell size, so visible radius is roughly cellSize x segments x 2^(levels-1). 9 levels of 192 at 2 m reaches ~98 km, which is past where haze has dissolved the ground.' },
+    { key: 'segments', label: 'Ring resolution', group: 'quality', min: 32, max: 320, step: 8, description: 'Grid resolution per ring side, and the one knob that sets how polygonal the terrain looks: a clipmap triangle subtends about 2/segments radians whatever the distance, so 192 is roughly 12 px at 1080p. Vertex cost is levels x segments^2 x 0.75, since every ring above the first is hollow.' },
+    { key: 'cellSize', label: 'Cell size', group: 'quality', min: 0.25, max: 32, step: 0.25, unit: 'm', description: 'Finest cell, at the camera. Lower it for a walkable scene, raise it for a flyover.' },
+    { key: 'shadowSteps', label: 'Shadow steps', group: 'quality', min: 0, max: 48, step: 1, description: 'Steps in the analytic sun-shadow march, nearest the camera. 0 disables terrain self-shadowing entirely, which is the single biggest thing you can turn off; below ~12 long shadows at low sun start to leak.' },
+    { key: 'shadowDistance', label: 'Shadow distance', group: 'quality', min: 0, max: 40000, step: 100, unit: 'm', description: 'Range over which the self-shadow fades out. The march runs per vertex, so lowering this drops whole clipmap rings out of it — the cheapest quality dial there is after turning shadows off.' },
+    { key: 'detailFadeDistance', label: 'Detail fade distance', group: 'quality', min: 50, max: 8000, step: 25, unit: 'm', description: 'Distance over which fragment-stage bump fades out. Removes far-field shimmer and buys back most of its own cost.' },
+    { key: 'curvature', label: 'Planetary curvature', group: 'quality', min: 0, max: 0.0000012, step: 0.00000001, advanced: true, description: '1/(2R). Drops the surface with the square of distance so it meets a real horizon. Zero gives a flat world, which at these extents looks wrong long before it looks flat.' },
+    { key: 'exposure', label: 'Exposure', group: 'quality', min: 0.2, max: 4, step: 0.01, description: 'Radiance scale, so terrain matches the sky and clouds whether or not the cloud composite is what tonemaps the frame.' },
+];
+export const defaultProceduralTerrainSettings = {
+    id: '3drise-terrain',
+    type: 'terrain',
+    config: { ...defaultHillsConfig, enabled: false },
+    quality: { ...defaultTerrainQuality },
+};
+// =============================================================================
+// Normalisation
+// =============================================================================
+//
+// A published scene loads whatever was in the database the day it was saved, and
+// a scene saved before this system existed carries core's flat TerrainSettings
+// (`visible` + `displacementScale`) under the same key. Reading that straight
+// into the renderer is how an embed dies: the clipmap sizes its rings from
+// `quality.segments` on its first frame.
+//
+// Each block merges over its own defaults SEPARATELY, not through one merge over
+// the settings object, so a quality edit does not hand the surface a new config
+// object and rebuild the clipmap geometry.
+const TERRAIN_TYPES = ['mountains', 'dunes', 'hills', 'canyon'];
+const isRecord = (v) => typeof v === 'object' && v !== null;
+/**
+ * Surface block merged over its type's defaults, or null when there is nothing to
+ * render — including the retired flat shape, which has no `config` and must draw
+ * nothing rather than a landscape the project was never authored with.
+ *
+ * An unknown or missing `terrainType` falls back to hills rather than rendering
+ * nothing: a scene that says `enabled: true` should show ground.
+ */
+export function normalizeTerrain(raw) {
+    if (!isRecord(raw))
+        return null;
+    const terrainType = TERRAIN_TYPES.includes(raw.terrainType)
+        ? raw.terrainType
+        : 'hills';
+    return {
+        ...TERRAIN_DEFAULTS[terrainType],
+        ...raw,
+        type: 'terrain',
+        terrainType,
+    };
+}
+export function normalizeTerrainQuality(raw) {
+    return { ...defaultTerrainQuality, ...(isRecord(raw) ? raw : {}) };
+}
+/**
+ * A whole settings blob, from a project of any age. The flat legacy shape has no
+ * `config`, so it normalises to a disabled terrain rather than to a default one.
+ */
+export function normalizeTerrainSettings(raw) {
+    const source = isRecord(raw) ? raw : {};
+    const config = normalizeTerrain(source.config);
+    return {
+        id: typeof source.id === 'string' ? source.id : defaultProceduralTerrainSettings.id,
+        type: 'terrain',
+        config: config ?? { ...defaultHillsConfig, enabled: false },
+        quality: normalizeTerrainQuality(source.quality),
+    };
+}

package/dist/utils/cloudUniforms.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from 'three';
+import type { CloudDeckConfig, CirrusLayerConfig, CloudsQualityConfig } from '../types/cloudConfigs';
+import type { CloudSunState } from '../hooks/useCloudSun';
+export declare function applyDeckUniforms(material: THREE.ShaderMaterial, deck: CloudDeckConfig, quality: CloudsQualityConfig): void;
+export declare function applyCirrusUniforms(material: THREE.ShaderMaterial, cirrus: CirrusLayerConfig, quality: CloudsQualityConfig): void;
+/** Sun and atmosphere. Every cloud material and the sky background share these. */
+export declare function applySunUniforms(material: THREE.ShaderMaterial, sun: CloudSunState, intensity: number): void;
+/**
+ * Camera basis for the ray reconstruction. `invProj` is passed in rather than read
+ * off the camera because the cloud pass uses a sub-pixel jittered projection that
+ * the scene pass must not see.
+ */
+export declare function applyCameraUniforms(material: THREE.ShaderMaterial, camera: THREE.PerspectiveCamera, invProj: THREE.Matrix4, width: number, height: number): void;
+//# sourceMappingURL=cloudUniforms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloudUniforms.d.ts","sourceRoot":"","sources":["../../src/utils/cloudUniforms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACrG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA0B1D,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CA0C3H;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAkBjI;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAY5G;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,iBAAiB,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUhK"}

package/dist/utils/cloudUniforms.js

@@ -0,0 +1,122 @@
+import * as THREE from 'three';
+/**
+ * Config to uniform mapping for the cloud materials.
+ *
+ * The config speaks in the units a person thinks in — "600 m features", "wind
+ * bearing 78 degrees" — and the shader wants reciprocals and direction vectors.
+ * Doing that conversion here rather than storing shader-space numbers means the
+ * settings panel, the presets and the AI agent all read in world units.
+ *
+ * These mutate the material in place and are called every frame. A 50-uniform
+ * shader driven through React props would re-render the tree once per frame.
+ */
+const _dir = new THREE.Vector2();
+function bearingToVector(degrees, out) {
+    const a = THREE.MathUtils.degToRad(degrees);
+    return out.set(Math.sin(a), Math.cos(a)).normalize();
+}
+/** Guard against a zero or negative size producing an infinite scale. */
+function inverse(size, fallback) {
+    return size > 1e-6 ? 1 / size : 1 / fallback;
+}
+export function applyDeckUniforms(material, deck, quality) {
+    const u = material.uniforms;
+    if (!u)
+        return;
+    u.u_coverage.value = deck.coverage;
+    u.u_density.value = deck.density;
+    u.u_cloudType.value = deck.profile;
+    u.u_layerBottom.value = deck.baseAltitude;
+    u.u_layerTop.value = Math.max(deck.topAltitude, deck.baseAltitude + 50);
+    u.u_baseScale.value = inverse(deck.featureSize, 2600);
+    u.u_detailScale.value = inverse(deck.detailSize, 400);
+    u.u_detailStrength.value = deck.detailStrength;
+    u.u_curlStrength.value = deck.curlStrength;
+    u.u_weatherScale.value = inverse(deck.weatherCellSize, 24000);
+    u.u_shear.value = deck.shear;
+    u.u_anvil.value = deck.anvil;
+    u.u_precip.value = deck.precipitation;
+    u.u_windDir.value.copy(bearingToVector(deck.windBearing, _dir));
+    u.u_windSpeed.value = deck.windSpeed;
+    u.u_rise.value = deck.rise;
+    u.u_churn.value = deck.churn;
+    u.u_evolution.value = deck.evolution;
+    u.u_sigmaT.value = deck.extinction;
+    u.u_g1.value = deck.forwardLobe;
+    u.u_g2.value = deck.backLobe;
+    u.u_msExtinction.value = deck.msExtinction;
+    u.u_msEnergy.value = deck.msEnergy;
+    u.u_msPhase.value = deck.msPhase;
+    u.u_powder.value = deck.powder;
+    u.u_silver.value = deck.silverLining;
+    u.u_ambient.value = deck.ambient;
+    u.u_fogDensity.value = deck.aerialPerspective;
+    u.u_steps.value = Math.round(quality.steps);
+    u.u_lightSteps.value = Math.round(quality.lightSteps);
+    u.u_lightStep.value = quality.lightStep;
+    u.u_stepGrowth.value = quality.stepGrowth;
+    u.u_maxSpan.value = quality.maxSpan;
+    u.u_detailFade.value = inverse(quality.detailFadeDistance, 16000);
+    u.u_curvature.value = quality.curvature;
+}
+export function applyCirrusUniforms(material, cirrus, quality) {
+    const u = material.uniforms;
+    if (!u)
+        return;
+    u.u_altitude.value = cirrus.altitude;
+    u.u_thickness.value = cirrus.thickness;
+    u.u_coverage.value = cirrus.coverage;
+    u.u_opticalDepth.value = cirrus.opticalDepth;
+    u.u_featureScale.value = inverse(cirrus.featureSize, 44000);
+    u.u_anisotropy.value = cirrus.anisotropy;
+    u.u_windDir.value.copy(bearingToVector(cirrus.windBearing, _dir));
+    u.u_windSpeed.value = cirrus.windSpeed;
+    u.u_halo.value = cirrus.halo;
+    u.u_g1.value = cirrus.forwardLobe;
+    u.u_g2.value = cirrus.secondaryLobe;
+    u.u_ambient.value = cirrus.ambient;
+    u.u_fogDensity.value = cirrus.aerialPerspective;
+    u.u_curvature.value = quality.curvature;
+}
+/** Sun and atmosphere. Every cloud material and the sky background share these. */
+export function applySunUniforms(material, sun, intensity) {
+    const u = material.uniforms;
+    if (!u)
+        return;
+    if (u.u_sunDir)
+        u.u_sunDir.value.copy(sun.direction);
+    if (u.u_sunColor)
+        u.u_sunColor.value.copy(sun.color);
+    if (u.u_skyAmbient)
+        u.u_skyAmbient.value.copy(sun.skyAmbient);
+    if (u.u_groundAmbient)
+        u.u_groundAmbient.value.copy(sun.groundAmbient);
+    if (u.u_sunIntensity)
+        u.u_sunIntensity.value = intensity;
+    if (u.u_turbidity)
+        u.u_turbidity.value = sun.turbidity;
+    if (u.u_rayleigh)
+        u.u_rayleigh.value = sun.rayleigh;
+    if (u.u_mieCoefficient)
+        u.u_mieCoefficient.value = sun.mieCoefficient;
+    if (u.u_mieG)
+        u.u_mieG.value = sun.mieG;
+}
+const _fwd = new THREE.Vector3();
+/**
+ * Camera basis for the ray reconstruction. `invProj` is passed in rather than read
+ * off the camera because the cloud pass uses a sub-pixel jittered projection that
+ * the scene pass must not see.
+ */
+export function applyCameraUniforms(material, camera, invProj, width, height) {
+    const u = material.uniforms;
+    if (!u)
+        return;
+    u.u_camPos.value.copy(camera.position);
+    u.u_camWorld.value.copy(camera.matrixWorld);
+    u.u_invProj.value.copy(invProj);
+    u.u_camFwd.value.copy(_fwd.set(0, 0, -1).applyQuaternion(camera.quaternion).normalize());
+    u.u_near.value = camera.near;
+    u.u_far.value = camera.far;
+    u.u_resolution.value.set(width, height);
+}

package/dist/utils/frameRenderer.d.ts

@@ -0,0 +1,33 @@
+import type * as THREE from 'three';
+/**
+ * Who is allowed to say what a finished frame looks like.
+ *
+ * Most of the scene is the scene graph, so `gl.render(scene, camera)` is the whole
+ * picture. A full-screen pass breaks that. VolumetricCloudsPass runs at
+ * `useFrame(…, 1)`, which takes rendering away from R3F: it draws the scene into an
+ * HDR target, marches the clouds at half resolution, resolves them temporally and
+ * composites the result to the canvas. The clouds exist only in that composite —
+ * there is no cloud geometry in the scene graph to find.
+ *
+ * So anything that renders a frame for its own purposes — a screenshot, a thumbnail,
+ * an export — must not call `gl.render(scene, camera)` directly. It gets everything
+ * except the clouds, which is worse than failing, because it looks like it worked.
+ *
+ * The registry is the same shape as `useCloudLive`: the pass publishes a handle, the
+ * consumer resolves it at call time and falls back to plain rendering when nothing
+ * has taken the frame over. Keyed on the renderer (like the cloud-noise cache) rather
+ * than React context, so a capture component mounted anywhere inside the Canvas
+ * finds it without being a descendant of the environment tree.
+ */
+/** Produce one complete frame to the currently bound target. */
+export type FrameRenderer = (camera: THREE.Camera) => void;
+/** Claim the frame. Returns the release function; call it on unmount. */
+export declare function registerFrameRenderer(gl: THREE.WebGLRenderer, renderer: FrameRenderer): () => void;
+/** True when a full-screen pass owns the frame, so `gl.render` alone is incomplete. */
+export declare function hasFrameRenderer(gl: THREE.WebGLRenderer): boolean;
+/**
+ * Render one complete frame. Use this instead of `gl.render(scene, camera)` anywhere
+ * you need the canvas to hold a finished image — screenshots, thumbnails, exports.
+ */
+export declare function renderFrame(gl: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera): void;
+//# sourceMappingURL=frameRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frameRenderer.d.ts","sourceRoot":"","sources":["../../src/utils/frameRenderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC;AAI3D,yEAAyE;AACzE,wBAAgB,qBAAqB,CACjC,EAAE,EAAE,KAAK,CAAC,aAAa,EACvB,QAAQ,EAAE,aAAa,GACxB,MAAM,IAAI,CAKZ;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,KAAK,CAAC,aAAa,GAAG,OAAO,CAEjE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACvB,EAAE,EAAE,KAAK,CAAC,aAAa,EACvB,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,GACrB,IAAI,CAIN"}

package/dist/utils/frameRenderer.js

@@ -0,0 +1,24 @@
+const registry = new WeakMap();
+/** Claim the frame. Returns the release function; call it on unmount. */
+export function registerFrameRenderer(gl, renderer) {
+    registry.set(gl, renderer);
+    return () => {
+        if (registry.get(gl) === renderer)
+            registry.delete(gl);
+    };
+}
+/** True when a full-screen pass owns the frame, so `gl.render` alone is incomplete. */
+export function hasFrameRenderer(gl) {
+    return registry.has(gl);
+}
+/**
+ * Render one complete frame. Use this instead of `gl.render(scene, camera)` anywhere
+ * you need the canvas to hold a finished image — screenshots, thumbnails, exports.
+ */
+export function renderFrame(gl, scene, camera) {
+    const owner = registry.get(gl);
+    if (owner)
+        owner(camera);
+    else
+        gl.render(scene, camera);
+}

package/dist/utils/handleCloudsAnimations.d.ts

@@ -0,0 +1,16 @@
+import type { AnimationOptions, MouseMoveProperty } from '@3driseai/3drise-core';
+import type { CloudDeckConfig } from '../types/cloudConfigs';
+export type CloudPropertyOverride = Partial<Record<string, number>>;
+/** Cache of the value a property started at, so `from`-less keyframes have an origin. */
+export type CloudStartValues = Record<string, number>;
+export declare function applyCloudsKeyframeAnimations(animations: AnimationOptions[] | undefined, startValues: CloudStartValues, deck: CloudDeckConfig, override: CloudPropertyOverride, currentTime: number): void;
+export declare function applyCloudsMouseMove(properties: MouseMoveProperty[] | undefined, deck: CloudDeckConfig, override: CloudPropertyOverride, pointer: {
+    x: number;
+    y: number;
+}): void;
+/**
+ * Merge the frame's overrides into a deck config. Returns `deck` untouched when
+ * nothing is animating, so the common case allocates nothing.
+ */
+export declare function resolveDeckConfig(deck: CloudDeckConfig, override: CloudPropertyOverride): CloudDeckConfig;
+//# sourceMappingURL=handleCloudsAnimations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handleCloudsAnimations.d.ts","sourceRoot":"","sources":["../../src/utils/handleCloudsAnimations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAmB7D,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEpE,yFAAyF;AACzF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtD,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAiB1M;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,qBAAqB,EAAE,OAAO,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUjL;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,qBAAqB,GAAG,eAAe,CAOzG"}

package/dist/utils/handleCloudsAnimations.js

@@ -0,0 +1,64 @@
+import { calculateTimeProgress, applyEasing, gsapEasingMap, interpolateValue, interpolateMouseMoveProperty, } from '@3driseai/3drise-core';
+import { CLOUD_ANIMATABLE_PROPERTIES } from '../types/cloudConfigs.js';
+/**
+ * The `clouds` animation and mouse-move domains, applied to a deck config.
+ *
+ * Same shape as the legacy Clouds.tsx helpers — keyframes first, then mouse-move
+ * on top of the keyframed value — but over the whole animatable property set
+ * rather than just `speed`.
+ *
+ * Only scalars that can be interpolated per frame without rebuilding anything are
+ * eligible. Altitudes and feature sizes are excluded on purpose: the vertical
+ * profile is measured as a fraction of base-to-top, so animating an altitude
+ * restretches the entire density field and the cloud appears to pump rather than
+ * move.
+ */
+const ANIMATABLE = new Set(CLOUD_ANIMATABLE_PROPERTIES);
+export function applyCloudsKeyframeAnimations(animations, startValues, deck, override, currentTime) {
+    if (!animations?.length)
+        return;
+    for (const anim of animations) {
+        const { property, to, duration, ease, loop = false, yoyo = false, active } = anim;
+        if (!active || to === undefined || !ANIMATABLE.has(property))
+            continue;
+        let from = anim.from;
+        if (from === undefined) {
+            from = startValues[property] ??= deck[property];
+        }
+        let p = calculateTimeProgress(currentTime, duration, yoyo, loop);
+        if (ease) {
+            const fn = gsapEasingMap[ease] || ease;
+            p = applyEasing(fn, p);
+        }
+        override[property] = interpolateValue(property, from, to, p);
+    }
+}
+export function applyCloudsMouseMove(properties, deck, override, pointer) {
+    if (!properties?.length)
+        return;
+    for (const { property, enabled, propertySettings } of properties) {
+        if (!enabled || !ANIMATABLE.has(property))
+            continue;
+        const { axis = 'both', sensitivity = 1, inverted = false, min, max } = propertySettings || {};
+        // Layer on top of the keyframed value when there is one, so the two compose
+        // instead of the pointer snapping back to the config every frame.
+        const base = override[property] ?? deck[property];
+        override[property] = interpolateMouseMoveProperty(base, min, max, pointer, axis, sensitivity, inverted);
+    }
+}
+/**
+ * Merge the frame's overrides into a deck config. Returns `deck` untouched when
+ * nothing is animating, so the common case allocates nothing.
+ */
+export function resolveDeckConfig(deck, override) {
+    let dirty = false;
+    for (const k in override) {
+        if (override[k] !== undefined) {
+            dirty = true;
+            break;
+        }
+    }
+    if (!dirty)
+        return deck;
+    return { ...deck, ...override };
+}

package/dist/utils/landscapeGeometry.d.ts

@@ -0,0 +1,61 @@
+import * as THREE from 'three';
+import { type RtinTile } from './rtin';
+import type { DecodedHeightmap } from './landscapeTextures';
+/**
+ * Heightmap to drawable geometry.
+ *
+ * Two decisions worth knowing:
+ *
+ * **Y stays zero in the buffer.** The mesh carries XZ and UV only; the height is
+ * applied in the vertex shader from the heightmap texture. That keeps
+ * `elevationScale` and `smoothness` live-draggable without re-running RTIN, and
+ * it is what lets the depth material displace identically for shadow casting.
+ * The cost is that object-space bounds describe a flat plate, which is why the
+ * per-chunk bounding boxes below are built by hand from the heightmap's own
+ * min/max rather than from the vertex buffer.
+ *
+ * **The tile is chunked.** One tile is one draw call in the reference, with
+ * culling disabled. Here the index buffer is split into an N x N grid over ONE
+ * shared vertex buffer: each chunk gets real bounds and culls independently, and
+ * because neighbouring chunks share vertices exactly there is no crack risk. The
+ * shared buffer is also why disposal is centralised — disposing every chunk
+ * geometry would free the same attribute N^2 times.
+ */
+export interface LandscapeChunk {
+    geometry: THREE.BufferGeometry;
+    /** Normalised height range of the vertices this chunk references, so the
+     *  bounding box can be rebuilt when the elevation scale changes without
+     *  touching the geometry. */
+    minH01: number;
+    maxH01: number;
+}
+export interface LandscapeGeometry {
+    chunks: LandscapeChunk[];
+    /** Shared across every chunk. Disposed once. */
+    position: THREE.BufferAttribute;
+    uv: THREE.BufferAttribute;
+    vertexCount: number;
+    triangleCount: number;
+    /** World size the XZ coordinates were built for. */
+    size: number;
+    dispose(): void;
+}
+export interface BuildLandscapeGeometryOptions {
+    /** World units across the tile. */
+    size: number;
+    /** N x N culling chunks. */
+    chunks: number;
+    /** RTIN budget in NORMALISED height units — world error divided by the
+     *  elevation scale. Keeping the error map normalised is what lets a change
+     *  of elevation scale re-run `getMesh` instead of rebuilding the map. */
+    maxError: number;
+}
+/** The error map depends only on the heightfield, so it is built once per
+ *  decoded heightmap and reused for every error budget. */
+export declare function rtinTileFor(height: DecodedHeightmap): RtinTile;
+export declare function buildLandscapeGeometry(height: DecodedHeightmap, options: BuildLandscapeGeometryOptions): LandscapeGeometry;
+/** Rewrite the vertical extent of every chunk's bounds. Called whenever the
+ *  elevation scale or bias changes; without it a raised landscape culls against
+ *  the flat plate it was built as and disappears when the camera tilts. */
+export declare function setLandscapeBounds(geometry: LandscapeGeometry, scale: number, bias: number): void;
+//# sourceMappingURL=landscapeGeometry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"landscapeGeometry.d.ts","sourceRoot":"","sources":["../../src/utils/landscapeGeometry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,cAAc;IAC3B,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAA;IAC9B;;iCAE6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,gDAAgD;IAChD,QAAQ,EAAE,KAAK,CAAC,eAAe,CAAA;IAC/B,EAAE,EAAE,KAAK,CAAC,eAAe,CAAA;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,IAAI,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,6BAA6B;IAC1C,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd;;6EAEyE;IACzE,QAAQ,EAAE,MAAM,CAAA;CACnB;AAID;2DAC2D;AAC3D,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ,CAM9D;AAED,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,6BAA6B,GACvC,iBAAiB,CAiGnB;AAED;;2EAE2E;AAC3E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAYjG"}