@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/types/landscapeConfigs.js

@@ -0,0 +1,256 @@
+/**
+ * Config shapes for the landscape system — a bounded, authored ground tile built
+ * from a heightmap and textured through splat maps.
+ *
+ * This is NOT a mode of the procedural terrain and does not share a config with
+ * it. Terrain is an infinite camera-following clipmap generated from noise; a
+ * landscape is a finite tile whose shape and materials the user supplies. Both
+ * may be enabled in one scene; nothing here reads `terrainConfigs`.
+ *
+ * Declared in the viewer, next to the material that consumes it, for the same
+ * reason `terrainConfigs` and `oceanConfigs` are.
+ */
+// -----------------------------------------------------------------------------
+// Defaults
+// -----------------------------------------------------------------------------
+export const defaultLandscapeSurface = {
+    name: 'Surface',
+    diffuse: '',
+    normal: '',
+    displacement: '',
+    repeat: 200,
+    normalStrength: 0.6,
+    saturation: 1,
+    tint: '#ffffff',
+    roughness: 0.9,
+    metalness: 0,
+    heightBlend: 0.6,
+    aperiodic: true,
+    triplanar: false,
+    flipNormalY: false,
+};
+export const defaultAutoSplat = {
+    bands: [0, 0.35, 0.75],
+    bandWidth: 0.45,
+    slopeStart: 0.35,
+    slopeEnd: 0.62,
+    noise: 0.12,
+    noiseSize: 400,
+};
+export const defaultLandscapeConfig = {
+    enabled: false,
+    host: 'ground',
+    heightMap: '',
+    heightEncoding: 'grayscale',
+    splatSource: 'auto',
+    splatMaps: [],
+    autoSplat: { ...defaultAutoSplat, bands: [...defaultAutoSplat.bands] },
+    aoMap: '',
+    size: 2048,
+    elevationScale: 300,
+    elevationBias: 0,
+    origin: [0, 0, 0],
+    rotationY: 0,
+    smoothness: 1,
+    surfaces: [],
+    surfaceSamples: 3,
+    macroVariation: 0.25,
+    macroSize: 900,
+    aoIntensity: 0.8,
+    envMapIntensity: 0.9,
+    preset: '',
+};
+export const defaultLandscapeQuality = {
+    meshError: 1.5,
+    mobileMeshError: 6,
+    chunks: 4,
+    arrayResolution: 1024,
+    anisotropy: 4,
+    stochastic: true,
+    triplanar: true,
+    castShadows: true,
+    receiveShadows: true,
+    wireframe: false,
+};
+export const defaultLandscapeSettings = {
+    id: '3drise-landscape',
+    type: 'landscape',
+    config: { ...defaultLandscapeConfig },
+    quality: { ...defaultLandscapeQuality },
+};
+/** Hard ceiling. Two splat maps carry four channels each, and the index is packed
+ *  as `i / MAX_SURFACES` in the weight pair. */
+export const MAX_LANDSCAPE_SURFACES = 8;
+/** The object host keeps the same material with a shorter list. */
+export const MAX_OBJECT_SURFACES = 4;
+export const LANDSCAPE_SCHEMA = [
+    { key: 'size', label: 'Size', group: 'form', min: 4, max: 40000, step: 4, unit: 'm', description: 'World units across the tile. The heightmap is square, so this is both sides.' },
+    { key: 'elevationScale', label: 'Elevation', group: 'form', min: 0, max: 4000, step: 1, unit: 'm', description: 'World height of the heightmap’s full range. This is the knob that turns a relief map into mountains.' },
+    { key: 'elevationBias', label: 'Base height', group: 'form', min: -2000, max: 2000, step: 1, unit: 'm', description: 'World Y added after scaling — where the lowest point of the heightmap sits.' },
+    { key: 'rotationY', label: 'Rotation', group: 'form', min: 0, max: 360, step: 1, unit: 'deg', hosts: ['ground'], description: 'Turns the tile about its centre. The placed host uses its own transform instead.' },
+    { key: 'smoothness', label: 'Smoothness', group: 'form', min: 0, max: 8, step: 0.05, description: 'Bicubic filtering of the heightmap over a widened footprint. Above 0 it is what keeps an 8-bit heightmap from rendering as terraced steps.' },
+    { key: 'surfaceSamples', label: 'Surface samples', group: 'surface', min: 1, max: 4, step: 1, description: 'How many of the heaviest surface weights are blended per pixel. The strongest cost dial in the material — 2 is enough almost everywhere, and artefacts only show where three splat channels genuinely overlap.' },
+    { key: 'macroVariation', label: 'Macro variation', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Large-scale albedo break-up, generated rather than sampled. Without it a splat layer is one flat colour across hundreds of metres and the eye reads it as untextured.' },
+    { key: 'macroSize', label: 'Macro size', group: 'surface', min: 50, max: 8000, step: 10, unit: 'm', description: 'World size of that break-up.' },
+    { key: 'aoIntensity', label: 'AO intensity', group: 'surface', min: 0, max: 2, step: 0.01, description: 'Strength of the baked ambient occlusion map, when one is supplied.' },
+    { key: 'envMapIntensity', label: 'Environment', group: 'surface', min: 0, max: 3, step: 0.01, description: 'How much the scene’s HDR environment lights the ground.' },
+];
+export const LANDSCAPE_AUTOSPLAT_SCHEMA = [
+    { key: 'bandWidth', label: 'Band width', group: 'surface', min: 0.05, max: 1.5, step: 0.01, description: 'How far each surface reaches either side of its height band. Wide bands cross-fade; narrow ones stripe.' },
+    { key: 'slopeStart', label: 'Rock from slope', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Slope at which the last surface (rock) starts showing through. Splatting rock by slope rather than height is what makes a cliff read as a cliff at any altitude.' },
+    { key: 'slopeEnd', label: 'Bare rock at slope', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Slope at which the surface is fully rock.' },
+    { key: 'noise', label: 'Band break-up', group: 'surface', min: 0, max: 1, step: 0.005, description: 'Jitters the height before banding, so the boundaries are not contour lines.' },
+    { key: 'noiseSize', label: 'Break-up size', group: 'surface', min: 10, max: 4000, step: 5, unit: 'm', description: 'World size of that jitter.' },
+];
+export const LANDSCAPE_QUALITY_SCHEMA = [
+    { key: 'meshError', label: 'Mesh error', group: 'quality', min: 0, max: 60, step: 0.1, unit: 'm', description: 'The most a triangle may be wrong by, vertically. Lower spends triangles on cliffs; 0 puts a vertex on every heightmap texel. Changing it rebuilds the mesh, so it commits on release.' },
+    { key: 'chunks', label: 'Culling chunks', group: 'quality', min: 1, max: 12, step: 1, description: 'The tile is split into this many chunks per side over one shared vertex buffer, so it frustum-culls instead of drawing whole. More chunks cull better and cost more draw calls.' },
+    { key: 'anisotropy', label: 'Anisotropy', group: 'quality', min: 1, max: 16, step: 1, description: 'Sharpness of ground textures at grazing angles — which on a landscape is most of the screen.' },
+    { key: 'stochastic', label: 'Stochastic tiling', group: 'quality', type: 'boolean', description: 'Breaks the repeat grid on surfaces flagged for it, with a variance-preserving three-tap blend. Doubles the fetches for those surfaces and is the difference between authored ground and wallpaper.' },
+    { key: 'triplanar', label: 'Triplanar', group: 'quality', type: 'boolean', description: 'Enables world-axis projection for surfaces flagged for it, so a cliff face is not a smear of stretched pixels. Biplanar in practice — two planes, not three.' },
+    { key: 'castShadows', label: 'Cast shadows', group: 'quality', type: 'boolean', description: 'The landscape casts into the scene’s shadow map. It is bounded, so the sun’s shadow camera actually covers it — which is why this is possible here and not for the procedural terrain.' },
+    { key: 'receiveShadows', label: 'Receive shadows', group: 'quality', type: 'boolean', description: 'Objects standing on the landscape cast onto it.' },
+    { key: 'wireframe', label: 'Wireframe', group: 'quality', type: 'boolean', description: 'Draw the adaptive mesh itself. The fastest way to see what the error budget is buying.' },
+];
+// -----------------------------------------------------------------------------
+// What can be driven live, and what cannot
+// -----------------------------------------------------------------------------
+//
+// A slider drag fires on every pointer-move. Everything that is only a uniform
+// can be written straight into the renderer at that rate; everything that
+// rebuilds something cannot, and has to wait for the pointer to come up.
+//
+// These sets are the single statement of that split. The controller passes every
+// key it has and the renderer's live handle drops the ones that are not here, so
+// a rebuild key cannot half-apply — which is what `size` did before this existed:
+// the triplanar scale is a uniform and moved during the drag while the mesh,
+// built at the committed size, did not.
+/** Config keys that are uniforms and nothing else. */
+export const LANDSCAPE_LIVE_CONFIG_KEYS = [
+    'elevationScale',
+    'elevationBias',
+    'smoothness',
+    'macroVariation',
+    'macroSize',
+    'aoIntensity',
+    'envMapIntensity',
+    'rotationY',
+];
+/** Quality keys that are uniforms, material flags or texture state. */
+export const LANDSCAPE_LIVE_QUALITY_KEYS = [
+    'wireframe',
+    'castShadows',
+    'receiveShadows',
+    'anisotropy',
+];
+/**
+ * Keys that rebuild something, listed for the panel to explain itself with.
+ *
+ *   meshError, chunks   re-run RTIN and rebuild every index buffer
+ *   arrayResolution     repacks up to sixteen textures
+ *   surfaceSamples      changes a #define, so the shader recompiles
+ *   stochastic, triplanar   likewise
+ *   size, heightMap, splatMaps, heightEncoding, splatSource, surfaces
+ *                       change the mesh or the arrays
+ */
+export const LANDSCAPE_REBUILD_KEYS = [
+    'meshError',
+    'mobileMeshError',
+    'chunks',
+    'arrayResolution',
+    'surfaceSamples',
+    'stochastic',
+    'triplanar',
+    'size',
+    'heightMap',
+    'heightEncoding',
+    'splatSource',
+    'splatMaps',
+    'surfaces',
+];
+/** Every surface field except the three texture slots is a uniform. */
+export const LANDSCAPE_LIVE_SURFACE_KEYS = [
+    'repeat',
+    'normalStrength',
+    'saturation',
+    'tint',
+    'roughness',
+    'metalness',
+    'heightBlend',
+    'aperiodic',
+    'triplanar',
+    'flipNormalY',
+];
+/** Auto-splat is entirely uniforms — all four rows plus the band list. */
+export const LANDSCAPE_LIVE_AUTOSPLAT_KEYS = [
+    'bandWidth',
+    'slopeStart',
+    'slopeEnd',
+    'noise',
+    'noiseSize',
+];
+// =============================================================================
+// Normalisation
+// =============================================================================
+//
+// Same rule as the terrain, not the ocean: a blob with no heightMap renders
+// nothing. There is no legacy landscape shape to migrate, and a landscape with
+// no heightmap is not a landscape.
+//
+// Each block merges over its own defaults SEPARATELY, so a quality edit does not
+// hand the mesh a new config object and re-run RTIN.
+const isRecord = (v) => typeof v === 'object' && v !== null;
+export function normalizeLandscapeSurface(raw, index = 0) {
+    const src = isRecord(raw) ? raw : {};
+    return {
+        ...defaultLandscapeSurface,
+        name: typeof src.name === 'string' ? src.name : `Surface ${index + 1}`,
+        ...src,
+    };
+}
+export function normalizeLandscape(raw) {
+    if (!isRecord(raw))
+        return null;
+    if (typeof raw.heightMap !== 'string' || raw.heightMap.length === 0)
+        return null;
+    const host = raw.host === 'object' ? 'object' : 'ground';
+    const limit = host === 'object' ? MAX_OBJECT_SURFACES : MAX_LANDSCAPE_SURFACES;
+    const surfaces = Array.isArray(raw.surfaces)
+        ? raw.surfaces.slice(0, limit).map((s, i) => normalizeLandscapeSurface(s, i))
+        : [];
+    return {
+        ...defaultLandscapeConfig,
+        ...raw,
+        host,
+        surfaces,
+        splatMaps: Array.isArray(raw.splatMaps)
+            ? raw.splatMaps.filter((s) => typeof s === 'string').slice(0, 2)
+            : [],
+        autoSplat: {
+            ...defaultAutoSplat,
+            ...(isRecord(raw.autoSplat) ? raw.autoSplat : {}),
+            bands: Array.isArray(raw.autoSplat?.bands)
+                ? raw.autoSplat.bands
+                : [...defaultAutoSplat.bands],
+        },
+        origin: Array.isArray(raw.origin) && raw.origin.length === 3
+            ? [...raw.origin]
+            : [...defaultLandscapeConfig.origin],
+    };
+}
+export function normalizeLandscapeQuality(raw) {
+    return {
+        ...defaultLandscapeQuality,
+        ...(isRecord(raw) ? raw : {}),
+    };
+}
+export function normalizeLandscapeSettings(raw) {
+    const source = isRecord(raw) ? raw : {};
+    const config = normalizeLandscape(source.config);
+    return {
+        id: typeof source.id === 'string' ? source.id : defaultLandscapeSettings.id,
+        type: 'landscape',
+        config: config ?? { ...defaultLandscapeConfig },
+        quality: normalizeLandscapeQuality(source.quality),
+    };
+}

package/dist/types/oceanConfigs.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Config shapes for the ocean that lives in this package.
+ *
+ * Declared locally rather than in `@3driseai/3drise-core`, alongside
+ * `terrainConfigs.ts` and `cloudConfigs.ts`, because the material and the
+ * renderer are here and nothing outside the viewer needs to construct these by
+ * hand.
+ *
+ * Core's `OceanSettings` is the retired shape — a flat plane with a
+ * `materialSettings` block picked out of the water material registry — and is
+ * deliberately left alone: a saved project still carries one. Unlike terrain,
+ * where a legacy blob normalises to NOTHING, a legacy ocean normalises to a real
+ * ocean: a project saved before this system existed very possibly had water, and
+ * dropping it would delete it. See `normalizeOcean` at the bottom.
+ *
+ * An ocean is ONE wave model in two containers, not two renderers — the same way
+ * three of the four cloud types share one marcher and all four landforms share
+ * one height field. `waterType` shapes the spectrum; `host` chooses the mesh.
+ */
+/** The four water bodies the spectrum is shaped for. */
+export type WaterType = 'sea' | 'lake' | 'storm' | 'shore';
+/**
+ * Where the water lives.
+ *
+ * `world` is the sea: a camera-following clipmap at `seaLevel`, one per scene,
+ * mounted by the environment. `object` is a placed body of water — a pool, a
+ * pond, a canal — a bounded grid with its own transform, any number of them,
+ * mounted as ordinary scene objects. The clouds' `object` / `layer` split, and
+ * for the same reason: a deck that stops at a sphere is not a deck, and a pool
+ * that follows the camera is not a pool.
+ */
+export type WaterHost = 'world' | 'object';
+/** Gerstner today; the FFT cascades land behind the same interface. */
+export type WaveModel = 'gerstner' | 'fft';
+export type ReflectionMode = 'planar' | 'env' | 'off';
+export type TerrainInteraction = 'auto' | 'on' | 'off';
+/** Fields every water body shares, whatever its type or host. */
+export interface OceanSurfaceConfig {
+    enabled: boolean;
+    host: WaterHost;
+    /** `gerstner` sums analytic trochoids in the vertex shader. `fft` swaps the
+     *  height field for Tessendorf cascades and changes nothing above it — the
+     *  material, the shading, the panel and the saved shape are identical. */
+    waveModel: WaveModel;
+    /** World Y the surface sits at. **World host only** — a placed body takes its
+     *  level from its own transform, which is what makes two water bodies at
+     *  different heights in one scene work without either knowing about the
+     *  other. Nothing here is tied to the terrain's `seaLevel`: the shoreline is
+     *  computed from the difference, never configured. */
+    seaLevel: number;
+    /** Extent of a placed body, in world units. **Object host only.** */
+    size: [number, number];
+    /** Grid resolution of a placed body. **Object host only.** */
+    segments: number;
+    /** Fraction of the half-extent over which displacement tapers to zero at the
+     *  rim of a placed body. **Object host only.** Without it the boundary is a
+     *  sawn-off cliff of water. */
+    edgeFade: number;
+    /** Wind speed at 10 m, in m/s. The whole sea state comes off this: peak
+     *  wavelength goes as U squared and significant wave height with it, so this
+     *  is the one knob that decides whether this is a millpond or a gale. */
+    windSpeed: number;
+    /** Compass bearing the wind blows toward, in degrees. Waves travel with it. */
+    windBearing: number;
+    /** Open water upwind, in km. Short fetch means small, short, steep waves
+     *  however hard it blows — which is exactly why a lake in a storm does not
+     *  look like an ocean in one. */
+    fetch: number;
+    /** Angular spread of the wave train about the wind bearing, in degrees. Zero
+     *  gives a corduroy of parallel crests; real seas run 25-40. */
+    directionalSpread: number;
+    /** Number of trochoidal components summed. Cost is linear in it, and every
+     *  component is a sin and a cos per vertex. */
+    waveComponents: number;
+    /** Artistic multiplier over the physically derived wave height. 1 is the
+     *  Pierson-Moskowitz fit for the given wind and fetch. */
+    amplitudeScale: number;
+    /** Horizontal displacement, as a fraction of the limit where a crest folds
+     *  through itself. This is what makes crests peaked rather than sinusoidal —
+     *  and it is what generates the Jacobian that foam is read from, so at 0
+     *  there are no whitecaps to find. */
+    choppiness: number;
+    /** Energy pushed toward the long, low, narrow-band end of the spectrum.
+     *  Swell is what has travelled out of the weather that made it. */
+    swell: number;
+    /** Extra steepening of the shorter components. Above ~1 the surface starts to
+     *  self-intersect and the wave folds inside out; clamped in the uniforms. */
+    steepness: number;
+    /** How much of the compressing surface reads as whitecap. */
+    foamAmount: number;
+    /** How far foam trails behind the crest that made it. A real whitecap
+     *  persists after the crest has moved on; at 0 it flickers on and off with
+     *  the crest and reads as sparkle rather than as foam. */
+    foamDecay: number;
+    /** Size of the break-up noise in the foam, in world units. */
+    foamSize: number;
+    /** Water seen at depth — the body colour. */
+    deepColor: string;
+    /** Water seen over something close behind it. Until the refraction grab
+     *  exists this is the grazing tint; after it, it is the shallow end of the
+     *  absorption ramp. */
+    shallowColor: string;
+    foamColor: string;
+    /** Beer-Lambert absorption per metre. Higher swallows the bottom sooner. */
+    absorption: number;
+    /** Suspended matter. Lifts the shallow colour and softens the refraction. */
+    clarity: number;
+    /** Widens the specular lobe. Water is smooth; this is fine detail below the
+     *  mesh, not surface finish. */
+    roughness: number;
+    /** Specular strength. The sun glitter path from horizon to camera is most of
+     *  what says "water" at distance, and it comes from here. */
+    specular: number;
+    /** Sun scattering through the body of a wave — crests glowing when the sun is
+     *  behind them. The second-most recognisable water cue after glitter. */
+    sssStrength: number;
+    sssColor: string;
+    /** High-frequency normal detail added per fragment, below mesh resolution.
+     *  This is where the energy lost to the per-ring wave LOD goes. */
+    detailStrength: number;
+    /** Size of that detail, in world units. */
+    detailSize: number;
+    reflection: ReflectionMode;
+    /** Strength of the refracted (see-through) term once the grab exists. */
+    refraction: number;
+    /** Sky-dome fill, from the same atmosphere the sky and clouds use. */
+    ambient: number;
+    /** Rate distant water fades into the sky behind it. Water needs more of this
+     *  than ground, because most of what you see looking at the sea IS the sky. */
+    aerialPerspective: number;
+    /** Radiance scale, so water sits at the same exposure as sky, clouds and
+     *  terrain whether or not the cloud composite is tonemapping the frame. */
+    exposure: number;
+    /** `auto` turns on when the scene has terrain enabled. Off costs nothing:
+     *  every terrain branch in the shader early-outs on one uniform. */
+    terrainInteraction: TerrainInteraction;
+    /** Strength of the terrain shadow marched down the sun vector. Terrain does
+     *  not write into the scene shadow map — its shadow camera is framed around
+     *  objects — so this is the only way a headland shadows the water beside it. */
+    terrainShadow: number;
+    /** Depth over which the shallow colour and the shore foam ramp in. */
+    shoreDepth: number;
+    /** Strength of the foam line where the ground comes up through the surface. */
+    shoreFoam: number;
+}
+/**
+ * A water body, as stored.
+ *
+ * `type` is 'ocean' — the OBJECT type anything routing on object type reads —
+ * with the model kept separately in `waterType` and the container in `host`,
+ * exactly as the clouds keep `deckType` and the terrain keeps `terrainType` apart
+ * from `type`.
+ */
+export type OceanConfig = OceanSurfaceConfig & {
+    type: 'ocean';
+    waterType: WaterType;
+    /** Name of the preset the numbers came from, or '' once any of them is
+     *  edited. Purely a UI bookmark — the renderer never reads it. */
+    preset?: string;
+};
+/** Cost and extent knobs. World-host geometry lives here; a placed body sizes
+ *  itself from its own config, because its extent is a design decision rather
+ *  than a performance one. */
+export interface OceanQualityConfig {
+    /** Clipmap ring count. Each doubles its cell size, so visible radius is
+     *  roughly `cellSize * segments * 2^(levels-1)`. */
+    levels: number;
+    /** Grid resolution per ring side. */
+    segments: number;
+    /** Finest cell, in world units, at the camera. Water is smooth, so this
+     *  matters more than reach: waves are metres, not kilometres. */
+    cellSize: number;
+    /** 1/(2R). Drops the surface away with the square of distance so the sea
+     *  meets a real horizon instead of running flat to the far plane. */
+    curvature: number;
+    /** Resolution of the planar reflection target, as a fraction of the frame.
+     *  0 disables the pass and falls back to `scene.environment`. */
+    reflectionScale: number;
+    /** Resolution of the refraction/depth grab, as a fraction of the frame. */
+    refractionScale: number;
+    /** Steps in the terrain shadow march, nearest the camera. 0 disables it. */
+    terrainShadowSteps: number;
+    /** Range over which that march fades out. It runs per vertex, so lowering
+     *  this drops whole clipmap rings out of it. */
+    terrainShadowDistance: number;
+    /** Distance over which the fragment-stage ripple detail fades out. */
+    detailFadeDistance: number;
+    /** Receive the scene's directional shadow map, so objects cast onto water. */
+    receiveShadows: boolean;
+    wireframe: boolean;
+}
+/** Open ocean. The reference case: long swell under a wind sea, deep colour. */
+export declare const defaultSeaConfig: OceanConfig;
+/**
+ * Inland water. Short fetch is doing all the work here — a lake in a gale still
+ * has small, short, steep waves, because there is no room upwind to build
+ * anything longer. Greener and murkier, because inland water is.
+ */
+export declare const defaultLakeConfig: OceanConfig;
+/** Storm sea. Steep, broken, and mostly foam at the top of the range. */
+export declare const defaultStormConfig: OceanConfig;
+/**
+ * Coastal water. Narrow spread, because waves refract into alignment with the
+ * beach as they shoal, and a much stronger shoreline because that is the whole
+ * point of the type.
+ */
+export declare const defaultShoreConfig: OceanConfig;
+export declare const defaultOceanQuality: OceanQualityConfig;
+/** Per-type defaults, for the controller's type switcher. */
+export declare const OCEAN_DEFAULTS: Record<WaterType, OceanConfig>;
+/** Object-host bodies are small, still and shallow by default — a pool, not a
+ *  shrunken sea. Applied on top of the type when the host is switched. */
+export declare const OBJECT_HOST_OVERRIDES: Partial<OceanSurfaceConfig>;
+export type OceanPropertyGroup = 'form' | 'waves' | 'surface' | 'shore' | 'quality';
+/**
+ * Everything the controller needs to build a row and everything the AI context
+ * builder needs to know what a knob does and where it is safe. The runtime never
+ * reads this — defaults live in the config objects above.
+ *
+ * `kind` exists here and not in the terrain schema because the ocean exposes
+ * colours and choices, not only numbers.
+ */
+export interface OceanPropertySchema {
+    key: string;
+    label: string;
+    group: OceanPropertyGroup;
+    /** How the value is edited and what can carry it. Absent means a ranged
+     *  number, which is the common case. Anything that is not a number cannot
+     *  ride in the agent's numeric changes list, so the agent filters on this
+     *  too — see the ocean catalog in aiAgent. */
+    kind?: 'number' | 'color' | 'boolean' | 'select' | 'vector2';
+    options?: string[];
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    description: string;
+    advanced?: boolean;
+    /** Only show for these water types. Absent means all. */
+    types?: WaterType[];
+    /** Only show on these hosts. A placed pool has no sea level and the sea has
+     *  no size; showing either is worse than hiding it, because a row that does
+     *  nothing reads as a bug in the renderer. */
+    hosts?: WaterHost[];
+}
+export declare const OCEAN_SCHEMA: OceanPropertySchema[];
+export declare const OCEAN_QUALITY_SCHEMA: OceanPropertySchema[];
+/** Transform of a placed body. Same shape the rest of the app uses. */
+export interface OceanMeshSettings {
+    name?: string;
+    visible: boolean;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+}
+/**
+ * A water body, as stored.
+ *
+ * Named `OceanWaterSettings` because core already exports an `OceanSettings` —
+ * the retired flat-plane-plus-material shape — and a saved project may still
+ * carry one. Same reason `ProceduralTerrainSettings` is not `TerrainSettings`.
+ *
+ * `meshSettings` is present only on the object host. The world ocean has no
+ * transform to edit: its clipmap follows the camera, and its one positional
+ * degree of freedom is `config.seaLevel`.
+ */
+export interface OceanWaterSettings {
+    id: string;
+    type: 'ocean';
+    parentid?: string;
+    config: OceanConfig;
+    quality: OceanQualityConfig;
+    /** Object host only. */
+    meshSettings?: OceanMeshSettings;
+    /** Per-domain keyframes. Object host only, like any other scene object. */
+    animations?: unknown;
+    /** Per-domain pointer interactions. Object host only. */
+    mouseMove?: unknown;
+}
+export declare const defaultOceanWaterSettings: OceanWaterSettings;
+/**
+ * Surface block merged over its type's defaults, or null when there is nothing
+ * to render. Unlike the terrain, a legacy blob is mapped rather than dropped —
+ * see the note above.
+ */
+export declare function normalizeOcean(raw: unknown, whole?: unknown): OceanConfig | null;
+export declare function normalizeOceanQuality(raw: unknown): OceanQualityConfig;
+/** A whole settings blob, from a project of any age. */
+export declare function normalizeOceanSettings(raw: unknown): OceanWaterSettings;
+//# sourceMappingURL=oceanConfigs.d.ts.map

package/dist/types/oceanConfigs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oceanConfigs.d.ts","sourceRoot":"","sources":["../../src/types/oceanConfigs.ts"],"names":[],"mappings":"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"}