@threenative/terrain 0.0.0-stage → 0.1.1

package/AGENT_GUIDE.md

@@ -0,0 +1,194 @@
+# Strata: instructions for a coding agent
+
+## Read this first
+
+Use the typed public `@threenative/terrain` imports to author terrain. The headless implementation is recovered from the owner-supplied Strata source. An operation records intent; `evaluate()` produces disposable data. Never modify an evaluated height array expecting to edit the recipe.
+
+World units are metres. Y is up. X and Z range from `-size/2` to `+size/2`. Brush centres and masks use `[x,z]`; spline points use `[x,y,z]`. Rotation and slope thresholds use degrees. **Placement output yaw uses radians.** Heights are absolute world elevations, not normalized texture values.
+
+Prefer stable semantic IDs: `base`, `north-peak`, `camp-pad`, `access-road`, `river-main`, `forest`. Repeating an operation with an existing ID replaces it **in place**. It does not append another layer. Use `label` for a human-readable name in fluent calls; the saved layer uses `name`. In `biome()` the `name` parameter is the biome key, not the display name.
+
+## Workflow
+
+1. Establish world size, seed, and a low preview resolution. Add base noise and large landforms.
+2. Add erosion before fine roads/building pads. Roads and pads take their elevation from the ground they cross unless you pin one.
+3. Add surface/biome rules and population. Put rules after the geometry changes whose slopes they should see. Road painting can override earlier surface rules; a later reset-material pass can also erase a road's paint.
+4. Inspect the result and diagnostics. Modify known IDs, keeping the source stack small.
+5. Export the recipe and derived runtime data at an explicit resolution. Verify the high-resolution result; resolution-dependent simulation is not guaranteed to match the preview exactly.
+
+Use `transaction()` for a synchronous semantic edit that should undo as a unit. Validation failure rolls back the entire batch. `applyPatch()` accepts JSON-only atomic commands, useful for a tool-calling agent:
+
+```js
+terrain.applyPatch([
+  { op: 'update', id: 'north-peak', patch: { params: { amplitude: 120 } } },
+  { op: 'update', id: 'river-main', patch: { params: { width: 22 } } },
+  { op: 'toggle', id: 'erosion', enabled: true },
+]);
+```
+
+Allowed patch commands: `upsert` with `layer`, `update` with `id` and `patch`, `remove` with `id`, `move` with `id` and zero-based `index`, `toggle` with `id` and optional `enabled`. Do not invent methods such as `terrain.generate()`, `terrain.bake()` or `terrain.saveGLB()`. Use `evaluate()`, `bakeTerrain()` and `makeExport()`.
+
+## API patterns
+
+```js
+import { Terrain, Mask, bakeMesh, bakeTerrain, makeExport } from '@threenative/terrain';
+const t = new Terrain({ size: 512, resolution: 129, seed: 73 });
+
+t.noise({ id: 'base', base: 15, amplitude: 20, scale: 140, octaves: 5, warp: 30 });
+t.sculpt({ id: 'hill', at: [0,0], radius: 45, strength: 12, falloff: .7 });
+t.sculpt({ id: 'ditch', points: [[-40,10],[0,30],[40,35]], radius: 10, strength: -5 });
+t.smooth({ id: 'soften', at: [0,0], radius: 65, strength: .6, iterations: 4 });
+t.flatten({ id: 'pad', at: [-70,50], radius: 28, height: 22, strength: 1 });
+t.ramp({ id: 'ramp', from: [-70,22,50], to: [-20,38,50], width: 15, shoulder: 10 });
+t.stamp({ id: 'cliff-mass', shape: 'mesa', at: [90,-70], radius: [70,40], amplitude: 50, rotation: 30 });
+t.erode({ id: 'thermal', method: 'thermal', iterations: 15, talus: 32, rate: .22 });
+t.erode({ id: 'hydraulic', method: 'hydraulic', droplets: 5000, maxSteps: 40 });
+t.terrace({ id: 'strata', step: 8, softness: .22, strength: .7 });
+```
+
+A `flatten` with no `height` levels the pad to the ground already under it and lets the blend reach as far as its deepest cut or fill, so it is a bench rather than a mesa.
+
+Stroke tools accept `at` or a polyline `points`. Brush radius is a **radius**, not diameter. Strength is signed metres for sculpt; `0..1` for smoothing, flattening and paint. Stroke coverage uses maximum falloff coverage, not repeated accumulation at every mouse event. Holding a brush stationary does not keep adding height. Points are interpolated at `2 * radius * spacing`; jitter is seeded. Procedural stamps use `amplitude` in metres. `opacity` is available on every layer.
+
+Masks are serializable expressions, never callbacks:
+
+```js
+const forest = Mask.and(
+  Mask.height(8, 85, 10),       // altitude band, feathered boundaries
+  Mask.slope(0, 34, 6),        // slope degrees
+  Mask.not(Mask.material('road')),
+  Mask.not(Mask.circle([-70, 50], 38, .3)),
+);
+
+t.biome({ id: 'forest-zone', label: 'Conifer biome', name: 'forest', mask: forest });
+t.scatter({ id: 'trees', asset: 'pine', count: 900, minDistance: 5,
+  scale: [.75,1.25], maxSlope: 35, mask: Mask.biome('forest') });
+t.clear({ id: 'clear-camp', target: 'scatter', mask: Mask.circle([-70,50],35) });
+```
+
+Additional masks: `Mask.rectangle(at, size, rotation, falloff)`, `Mask.noise(scale, threshold, seed, fade)`, `Mask.or(...)`, `Mask.all()`, `Mask.none()`. Slope/height masks are evaluated against the terrain at that operation's stage. Population is deferred: scatter rules sample the **final** heights/materials/biomes and re-evaluate their mask there, so later height edits do not leave trees floating. Clear-scatter masks affect preceding rules only. Minimum distance is guaranteed **within each rule**, not across different scatter rules. The bounded rejection sampler may place fewer than requested; inspect diagnostics rather than assuming an exact count.
+
+Materials are exactly `grass`, `dirt`, `rock`, `snow`, `sand`, `mud`, `road`, `moss`. Splat arrays are sample-major: `splat[sampleIndex * 8 + channel]`. Weights sum to one. `paint()` blends and renormalizes; `materials()` applies ordered rules. A later rule can override an earlier one.
+
+```js
+t.materials({ id: 'surfaces', base: 'grass', rules: [
+  { material: 'sand', mask: Mask.height(-100, 5, 3) },
+  { material: 'rock', mask: Mask.slope(42, 90, 8) },
+  { material: 'snow', mask: Mask.height(95, 1000, 15) },
+] });
+t.paint({ id: 'camp-dirt', at: [-70,50], radius: 27, material: 'dirt', strength: .9 });
+```
+
+## Roads, rivers and water
+
+A road, river or ramp **grades itself to the ground it crosses** when a control point leaves its elevation out (`null`, or `NaN` in code) or when it sets `followTerrain: true`. The elevation is sampled along the centreline, low-passed along arc length, then held inside `maxGrade` (default 0.12) and `maxCut`/`maxFill` (default 2.5 m / 1.5 m); the shoulder widens into a batter with the cut or fill, so a corridor never stands on a retaining step. Leaving the ground is the hard limit: where the ground itself is steeper than `maxGrade`, the road is steep too. Absolute elevations are still honoured exactly, so existing documents keep their meaning. Horizontal spline interpolation is Catmull–Rom; vertical interpolation is linear between controls to avoid vertical overshoot. Use `smooth:false` for a polyline.
+
+```js
+t.road({ id: 'access-road', points: [[-220,null,100],[-150,null,70],[-70,null,50]], width: 12, shoulder: 8 });
+t.river({ id: 'river-main', points: [[20,14,-240],[35,8,0],[80,3,240]], width: 18, depth: 4, enforceDownhill: true });
+t.water({ id: 'lake', kind: 'lake', at: [80,210], radius: 75, level: 4 });
+```
+
+`enforceDownhill:true` validates non-increasing Y, rather than silently changing elevations in the API. River carving only lowers terrain. The water surface is a ribbon, not a flow simulation. Keep profiles sensible and avoid self-intersecting splines.
+
+Lake flood fill starts at the supplied location, follows connected samples below `level`, and is limited by `radius`/mask. A seed above water level produces an empty mask and a diagnostic. Oceans flood from map boundaries. Water placement does not itself excavate a basin: lower the basin first. Scatter avoids flooded lake/ocean samples and submerged river ribbons by default.
+
+## Copy/paste and external heightfields
+
+```js
+const heights = t.copyRegion({ at: [90,-70], size: 110, resolution: 65 });
+t.paste({ id: 'copied-mass', data: heights, at: [-120,-90], size: 110,
+  rotation: 90, mirrorX: true, blend: 'replace', falloff: .2 });
+```
+
+The copy contains heights only. Paste/stamp data is `{width,height,values}` in world metres. Fluent `heightmap()` / `paste()` / `stamp()` normalize typed arrays to plain arrays; raw recipe JSON must already contain plain arrays. RAW files have no self-describing dimensions/range. Preserve sidecars. PNG import accepts non-interlaced grayscale 8/16-bit images only, not RGB/palette images, and reports `hasEmbeddedRange`.
+
+Stamp and paste footprints use `at: [x,z]`, `radius: [halfWidth,halfDepth]` or
+`size: [width,depth]`, and `rotation` in degrees (positive turns +X towards +Z).
+Existing `radius` takes precedence over `size`. All three landform operations use
+positive `scale` for vertical gain and `offset` in metres after that gain;
+additive blends add both the scaled height and offset. Heightmap accepts optional
+`at`, `size`, `rotation` and `falloff` to place a bounded rectangular footprint.
+Without these footprint fields it retains the supplied full-world sampling.
+Outside a bounded footprint, existing terrain remains unchanged. Samples must
+all be finite numbers. X/Z rotations that create overhangs have no heightfield
+representation. These transforms change recipe parameters, not an independent
+solid hidden inside the evaluated terrain.
+
+## Inspect and export
+
+```js
+console.log(t.inspect({ resolution: 129 }));
+const recipe = t.toJSON();
+const same = Terrain.fromJSON(recipe);
+const result = same.evaluate({ resolution: 257 });
+const runtime = bakeTerrain(result, { chunkCells: 64, lodSteps: [1,2,4], skirtDepth: 6 });
+const archive = await makeExport(result, recipe, 'runtime');
+// Node: await writeFile(archive.name, archive.bytes)
+```
+
+`makeExport` kinds are `project`, `png`, `raw`, `splat`, `glb`, `runtime`; all return `{name,type,bytes}`. Exporting does not mutate the authoring recipe. Collision height samples are row-major from Z=-size/2 to Z=+size/2, with X increasing along each row. Grid vertices are `(x/(N-1)-.5)*size, height[z*N+x], (z/(N-1)-.5)*size`.
+
+Do not promise navmesh, physics registration, EXR, seamless mixed-LOD stitching, procedural caves, true water simulation, or production art from this version. GLB exports terrain only; load placement assets separately. Native-engine integration is via arrays/manifests and still needs an engine-specific adapter.
+
+## Bounds and operational safety
+
+Valid grid resolutions: 17, 33, 65, 129, 257, 513, 1025 **vertices per side**. Use 129 or 257 while iterating, and inspect before moving to 513/1025. Changing resolution can change erosion and population. No cross-resolution exactness guarantee exists.
+
+Maximum recipe layers: 512; maximum requested instances per scatter rule: 20,000; hydraulic droplets: 200,000; steps per droplet: 128; thermal/smooth iterations: 200; noise octaves: 10; spline/brush input points: 8192; interpolated brush centres per stroke: 65,536. These are input safeguards, not real-time performance targets. Do not choose all maximums together.
+
+The evaluator is synchronous. An AbortSignal is checked between operations, not inside a long erosion pass. For real cancellation of a headless job, isolate it in a Node worker/process and terminate the worker. A prefix cache stores private snapshots, up to 48 MiB of counted height/splat/biome arrays by default; JavaScript metadata and output arrays are additional memory.
+
+Never execute untrusted JavaScript from a recipe. The editor parses data only. Surface validation errors and preserve the previous valid recipe. Save the recipe, not just the baked mesh, before destructive project housekeeping.
+
+Splatmaps are linear data, not color images: use a non-sRGB/NoColorSpace texture setting and renormalize sampled weights in the consuming shader. Do not use an 8-bit canvas conversion to read a PNG16 heightfield; the supplied decoder preserves its 16-bit samples.
+
+## Live editor: environment, assets and surfaces
+
+The running editor exposes three revision-checked operations beside the document, each also behind a GUI
+panel that calls the same code. A write names `baseRevision`; a stale one is a 409 and nothing changes.
+
+- `controller.environment({ op: "get" | "patch" | "reset" }, revision)`: sun azimuth/elevation/intensity/colour,
+  sky fill, sky colour or image, `exp2` haze, exposure, sea colours, and an independent `lighting` image.
+  `null` returns a field to the project's own value; an unsupported fog mode is refused by name. The
+  project's `src/render/` decides what each value does. Nothing here evaluates the terrain.
+- `controller.asset({ op: "register" | "upload" | "adjust" | "remove" | "list" | "map" | "unmap" }, revision)`:
+  `register` takes an absolute local path (an asset-MCP download result), `upload` takes base64 bytes. Files
+  are stored as `<kind>/<sha12>-<id>.<ext>` so a replacement is a new URL; GLB, PNG, JPEG, WebP, HDR and EXR are
+  recognised by their bytes, measured, and refused by name when damaged, over the project's limits, or when a
+  GLB points outside itself. Same id with other bytes needs `replace: true`. `remove` drops the entry, never
+  the file, and is refused while a surface or an environment still uses it.
+- `map` binds an image to a `<surface>.<channel>` input the project exposes (`bark.albedo`, `stone.normal`);
+  albedo is read as sRGB, every other channel as linear data. Placing a model is a `scatter` layer whose
+  `asset` is its id; `adjust` sets the file's unit scale and pivot without editing it.
+
+## Three.js ownership
+
+`@threenative/terrain/three` exports `toGeometry(bakeMesh(state))`. It creates only ordinary indexed geometry using your installed Three.js. Create the mesh/material in your own `src/render/`, register collision through the existing engine API, and dispose the geometry yourself. Baked vertex colours are absent by default; pass an explicit eight-channel sRGB `palette` to `bakeMesh` or `bakeTerrain` when wanted. The addon supplies no palette or material. The legacy `makeExport(..., "glb")` contains terrain only; use the separate static-world encoder below for resolved models and baked surfaces. The default GUI full-world action, chosen-resolution material/deformation baking and five final starter exports remain pending.
+
+
+## Resolved static-world GLB
+
+Import `exportWorldGLB` from `@threenative/terrain/export` in browser authoring source. Its import is DOM-free; encoding requires FileReader and canvas. Root and `/three` remain headless. This entry uses the installed Three.js GLTFExporter rather than a terrain-specific loader format.
+
+```ts
+import { exportWorldGLB } from '@threenative/terrain/export';
+const output = await exportWorldGLB({
+  revision,             // accepted document's 64-character content hash
+  snapshotTime,         // finite seconds, pinned across all baked deformations
+  state,                // evaluated committed recipe with applied override records
+  terrain,              // canonical metre-frame Mesh with UVs and prepared PBR maps
+  assets,               // Map<assetId, Object3D>: actual static models
+  transforms,           // Map<placementId, Matrix4>: actual final grounded root matrices
+  water,                // [{ id, object, time: snapshotTime, staleFrames: 0 }]
+});
+// output.bytes is the self-contained world.glb; persist only after success.
+```
+
+Game source owns all geometry, materials and images. The terrain needs albedo `map`, `normalMap`, `roughnessMap` and `aoMap`; vertex colours alone are insufficient. MeshStandardMaterial metallic/roughness surfaces are supported. Colour/emissive images are sRGB, data maps are NoColorSpace. Supply decoded byte images (at most 16 megapixels); DataTexture images need complete RGBA bytes. Bake alpha into the colour image. Bake displacement, bump/light maps, node shaders, skinning/morphing and wind into the supplied static geometry/material first. Use tangent-space normal maps with equal X/Y scale magnitudes; bake object-space/anisotropic maps first. MeshPhysicalMaterial extensions are outside this bounded encoder's contract.
+
+All final matrices use metres, Y-up, positive scale and no shear. Keys are durable placement IDs, never instance indices; unmatched matrices fail. Ordinary glTF nodes share model mesh data without requiring EXT_mesh_gpu_instancing. Source geometry, images and material values are copied before asynchronous encoding, so later source edits cannot mix the export snapshot. Input objects remain owned by the caller.
+
+Every evaluated water body/river needs its actual baked object at exactly `snapshotTime` with `staleFrames: 0`. A low-resolution or stale ocean CPU height sample does not satisfy this contract. Missing/unbaked content rejects before producing a download; preserve the previous valid export and document. Encoding does not perform the project's material bake, chosen-resolution re-evaluation or ocean readback for you.
+
+`output.report` records revision, resolution, time and placement/water IDs. Model cameras/lights and source userData are excluded. The receiving game supplies its own lighting, sky/environment, fog, exposure, post and live water/wind; GLB does not carry those running systems. A vanilla Three.js GLTFLoader or a normal game model loader can consume the bytes without this addon.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ThreeNative contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @threenative/terrain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional, headless terrain authoring recovered from Strata. One seeded recipe produces
+height/splat arrays, resolved placements, baked LOD chunks and numerical exports.
+Games consume baked data and own appearance, collision registration and disposal.
+
+```ts
+import { Terrain, Mask, bakeMesh } from '@threenative/terrain';
+import { toGeometry } from '@threenative/terrain/three';
+
+const terrain = new Terrain({ size: 512, resolution: 257, seed: 73 })
+  .noise({ id: 'hills', amplitude: 35 })
+  .flatten({ id: 'camp', height: 12, mask: Mask.circle([20, 30], 15) });
+const geometry = toGeometry(bakeMesh(terrain.evaluate()));
+// Your game creates the Mesh/material and disposes geometry.
+```
+
+Repeating an operation ID replaces that layer in place. `applyPatch` batches edits
+atomically; malformed writes preserve the previous recipe. Evaluation is synchronous
+and belongs in authoring/build jobs. Browser/editor dependencies are absent from
+root and geometry imports. Three.js is a peer, never a bundled second copy.
+
+The recovered `makeExport` GLB/runtime archives contain terrain geometry. The separate
+`@threenative/terrain/export` entry exports resolved static worlds through Three.js
+GLTFExporter: the caller supplies final models/matrices, baked UV PBR maps and
+coherent water snapshots. It requires browser FileReader/canvas for encoding,
+embeds images/buffers, excludes model cameras/lights, and uses ordinary shared
+mesh nodes. Missing models/maps, shader deformation or stale water fail by name.
+The default GUI full-world action, chosen-resolution baking and five final starter
+world exports remain pending. See the agent guide for the explicit contract.
+No browser/native terrain-game acceptance result is claimed by these library tests.
+
+See [agent guide](AGENT_GUIDE.md) and [source provenance](THIRD_PARTY_NOTICES.md).
+
+Optional live authoring uses `@threenative/terrain/editor/server` in the project's
+Vite configuration and `@threenative/terrain/editor` in its browser authoring entry.
+`terrainEditor({ documentPath })` mounts revisioned JSON/SSE endpoints on the
+existing loopback server. The configured file contains `{ version: 1, recipe }`;
+agent patches and GUI changes share that authority. Invalid external saves retain
+the last valid document with a diagnostic, and stale writes return conflict.
+
+The project provides `/terrain-editor/index.html` and calls `mountTerrainEditor`
+with its own `IEditorView` and material colours. The addon creates no renderer or
+scene. `TerrainEditorController(editorUrl)` exposes `activate`, `snapshot` and
+atomic `commit`; the activation result names the actually bound URL, project,
+session and revision. Use a configured forwarded viewer URL for remote access;
+the loopback API does not become a public write service.
+
+Scatter placement `id` identifies the layer, unsigned seed and candidate attempt,
+not the accepted array index. Mask/spacing changes can remove candidates without
+retargeting surviving keys or their seeded scale/yaw. Changing a seed creates new
+identities. Save keys rather than mesh instance indices for later authoring edits.
+
+The authoring document may also contain `placementOverrides`, keyed by those IDs.
+`validatePlacementOverrides()` validates finite position/quaternion/positive scale
+and defaults omitted `grounding` to true. `applyPlacementOverrides(state, overrides)`
+attaches each requested transform to its placement and reports retained unmatched
+keys. `bakeTerrain()` preserves those records. The game applies grounding against
+its actual mesh bounds and terrain triangles; disabling grounding retains measured
+clearance. The example's Select tool uses ordinary Three.js TransformControls and
+numeric fields, saves once per drag, and preserves newer edits on conflict.
+
+`mountTerrainEditor` passes `(host, controller)` to `createView`. The view implements
+`setDocument(document, revision)` for metadata changes without terrain evaluation;
+its `update(state)` may return the resolved state for inspection and data bakes.
+
+The example also selects stamp, paste and heightmap layers by stable ID. One proxy
+edits recipe footprints and vertical gain/offset; its line follows the visible
+terrain, with rebuilding on commit. X/Z rotation is disabled because a heightfield
+cannot overhang. `stamp`/`paste` accept positive vertical `scale`; `heightmap` also
+accepts optional metre `at`/`size`, degree `rotation` and `falloff` for a bounded
+footprint. The original full-world heightmap path remains the default.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,38 @@
+# Strata source provenance
+
+João supplied `strata-terrain.html` and `AGENT_GUIDE.md` and explicitly confirmed
+on 2026-09-30: “I own it; use MIT.” The recovered modules and their integration
+are distributed under the accompanying MIT license. The supplied files contained
+no earlier copyright/license notice; no upstream license or attribution is invented.
+
+Source SHA-256:
+
+- `strata-terrain.html`: `c0230e6891db829a5196d93ff7c9d714a8f2d964cac4722eb8ce4b2f723d794b`.
+- `AGENT_GUIDE.md`: `487453218f870c5e829d58aea3fe9323e74ea93e0aecef8d5c329ecf56972d06`.
+
+Recovery used the HTML's named `sources` module map, rather than its duplicated
+worker blob or minified viewer. The algorithms, validation and transactions are
+maintained as TypeScript source. Viewer appearance/renderer code is excluded;
+baking takes optional caller-owned colours and exports no chosen material.
+
+The optional `src/editor/` tooling also recovers the supplied app, icons, starter
+recipes, worker and static UI shell. Local-storage authority and the separate
+Three.js viewer are replaced by a revisioned project document and a required
+project-owned view. Formatting changes preserve the recovered controls; GUI
+swatches receive the game's explicit colours. Root and `/three` imports do not
+load this tooling.
+
+Maintained behavior difference: scatter candidates use layer/unsigned-seed/attempt
+keys and consume the same five seeded draws even when rejected. This fixes the
+supplied accepted-index identity and conditional-RNG defect. Placement lists
+intentionally differ from the supplied source; the supplied noise/erosion
+regression remains unchanged. The adapter's pine, boulder and grass shapes are
+adapted in the example's editable `src/render/props.ts`, using installed merge and
+instance mechanisms; no addon material or renderer is introduced.
+
+Landform extensions add positive vertical gain to stamp/paste and a bounded,
+translated/rotated rectangular footprint to heightmap. Additive stamp/paste now
+honor the supplied vertical offset, which the recovered additive branch ignored.
+Height data validation rejects missing or nonnumeric samples. Default gain/offset and heightmaps without
+footprint fields retain the recovered sampling; the numerical noise/erosion
+golden remains unchanged.

package/dist/editor/index.d.ts

@@ -0,0 +1,231 @@
+import { P as PatchCommand } from '../terrain-gPnkCU6S.js';
+import { I as ITerrainState } from '../types-Ant8-Axc.js';
+import { I as IAuthoringDocument, a as ISavedCamera, b as IFocusRequest, c as IFocusOutcome, d as IFocusBounds, e as IEnvironment, f as IEditorActivation, g as IEditorSnapshot, h as ISpatialQuery, i as ISpatialObservation, j as ICameraOperation, k as ICameraResult, l as IEnvironmentOperation, m as IEnvironmentResult, n as IAssetOperation, o as IAssetResult } from '../server-ByM2hmYJ.js';
+export { p as IAssetAdjust, q as IAssetBounds, r as IAssetKind, s as IAssetLimits, t as ICameraPose, u as ICameraSet, v as IFocusFraming, w as IFocusResolver, x as IFocusTarget, y as IHexColour, z as IPointObservation, A as IProfileObservation, B as IProfileSample, C as IProjectAsset, D as IReferenceObservation, E as ISavedSpatialReference, F as ISpatialControlPoint, G as ISpatialReference, H as ISurfaceMapping, J as ISurfaceMappings, K as ISurfaceReading, L as checkEnvironmentAssets, M as focusCamera, N as inspectSpatial, O as probeTerrain, P as runCameraOperation, Q as runEnvironmentOperation, R as sniff, S as surfaceSpace, T as validateAsset, U as validateAssets, V as validateCamera, W as validateCameras, X as validateEnvironment, Y as validateSpatialReference, Z as validateSurfaces } from '../server-ByM2hmYJ.js';
+import 'vite';
+
+/**
+ * Image header inspection for registered files: the real format, the real pixel size and whether the
+ * container is whole. It reads headers, never pixels, and never decodes into a texture: the project's
+ * render source loads the image through `ctx.assets` with the colour space its channel needs.
+ */
+interface IImageReport {
+    readonly format: "png" | "jpeg" | "webp" | "hdr" | "exr";
+    readonly width: number;
+    readonly height: number;
+    readonly diagnostics: string[];
+}
+/**
+ * What an image's pixels mean once a game binds them. Colour is stored in sRGB and decoded to linear
+ * when sampled; every other channel is a number and must never be decoded.
+ */
+/**
+ * The colour space of each surface channel.
+ * @summary Map a PBR channel name to the colour space its pixels are read in
+ * @requires npm i -D @threenative/terrain
+ * @situation load an imported albedo as sRGB and a normal, roughness, ao, height, opacity or metalness map as linear data
+ * @constraint a table only; the project's render source loads and binds the texture
+ * @example const space = SURFACE_CHANNELS.normal;
+ * @override the project owns which surface inputs exist and what they draw
+ */
+declare const SURFACE_CHANNELS: {
+    readonly albedo: "srgb";
+    readonly ao: "linear";
+    readonly height: "linear";
+    readonly metalness: "linear";
+    readonly normal: "linear";
+    readonly opacity: "linear";
+    readonly roughness: "linear";
+};
+type ISurfaceChannel = keyof typeof SURFACE_CHANNELS;
+/**
+ * Validate a PNG, JPEG, WebP, Radiance HDR or OpenEXR container and read its pixel size.
+ * @summary Inspect an image file's container and pixel size without decoding it
+ * @requires npm i -D @threenative/terrain
+ * @situation check an imported surface or environment image for damage and for the project's size limit
+ * @constraint headers and checksums only; throws by name for a damaged, truncated or oversize file
+ * @example const report = inspectImage(bytes, "png", { maxDimension: 8192 });
+ * @override the project sets the dimension limit
+ */
+declare function inspectImage(bytes: Uint8Array, format: string, limits: {
+    maxDimension: number;
+}): IImageReport;
+
+/** The live view's own camera surface, shared by the GUI list and a controller. */
+interface IViewCamera {
+    /** The actual current viewer pose, not the last saved bookmark. */
+    read(): IViewerPose;
+    /** Apply a saved pose to the real camera, or the ordinary editor camera when given null. */
+    apply(camera: ISavedCamera | null): void;
+    /**
+     * Frame a target for the live viewport; an unknown target keeps the last valid camera and
+     * reports why. The view measures the aspect itself, so a caller cannot save a stale one.
+     */
+    focus(request: Omit<IFocusRequest, "aspect">): IFocusOutcome;
+    /** Resolves a non-point target against the live world; the view owns the world matrices. */
+    resolve(target: {
+        kind: "prop" | "landmark" | "region";
+        id: string;
+    }): IFocusBounds | undefined;
+    /** Clip-square extent of bounds under the live camera, so a framing can be measured, not assumed. */
+    measure(bounds: IFocusBounds): {
+        x: number;
+        y: number;
+        z: boolean;
+    };
+}
+/** The live view's environment surface: bind saved overrides to the project's own render source. */
+interface IViewEnvironment {
+    /**
+     * Apply saved overrides to the real lights, haze, sky, exposure and sea. Absent fields restore
+     * the project's own value; a field this source cannot honour throws by name and the scene keeps
+     * its last valid look.
+     */
+    apply(environment: IEnvironment | undefined): void;
+    /** The effective values now in use: the project's own, with the saved overrides on top. */
+    read(): IEnvironment;
+}
+interface IViewerPose {
+    readonly position: readonly [number, number, number];
+    readonly target: readonly [number, number, number];
+    readonly up: readonly [number, number, number];
+    readonly projection: "perspective" | "orthographic";
+    readonly fov: number | null;
+    readonly extent: number | null;
+    readonly zoom: number | null;
+    readonly near: number;
+    readonly far: number;
+    readonly aspect: number;
+    readonly activeCamera: string | null;
+}
+interface IEditorView {
+    readonly backend: string;
+    update(state: ITerrainState): ITerrainState | undefined;
+    setDocument(document: IAuthoringDocument, revision: string): void;
+    pick(clientX: number, clientY: number): [number, number, number] | null;
+    setMode(mode: string): void;
+    setBrush(brush: {
+        at: [number, number];
+        radius: number;
+        rotation?: number;
+        shape?: string;
+    } | null): void;
+    showSpline(points: readonly [number, number, number][]): void;
+    setNavigation(enabled: boolean): void;
+    setSelection?(enabled: boolean): void;
+    selectLayer?(id: string): void;
+    setView(view: string): void;
+    frame(): void;
+    registerAsset?(id: string, object: unknown): void;
+    /**
+     * The asset IDs this project can place and scatter. The recovered palette asks the view rather
+     * than shipping a starter list, so a game's own props and its registered imports are what the
+     * scatter and clear controls offer.
+     */
+    propAssets?(): readonly string[];
+    /**
+     * Settles once every registered model the view started loading is placeable or has failed. The
+     * preview waits on it before drawing a revision, so a placement of a model still arriving is
+     * not reported as a missing asset.
+     */
+    assetsReady?(): Promise<void>;
+    /**
+     * The texture inputs of this project's render source that an imported image can replace, named
+     * `<surface>.<channel>`. The project decides what exists; the GUI offers exactly this list.
+     */
+    surfaceInputs?(): readonly {
+        input: string;
+        channel: string;
+    }[];
+    cameras?(): IViewCamera;
+    environment?(): IViewEnvironment;
+    /**
+     * The whole rendered revision as a portable GLB: terrain, resolved models with their final
+     * transforms, this game's baked water and its portable PBR surfaces. Optional because a headless
+     * or DOM-free view has nothing to encode from; the export card then says so rather than quietly
+     * falling back to the terrain-only worker export.
+     */
+    exportCurrentWorld?(): Promise<{
+        name: string;
+        mime: string;
+        bytes: Uint8Array;
+    }>;
+    dispose(): void;
+}
+/**
+ * HTTP controller for the project-local terrain editor.
+ * @requires npm i -D @threenative/terrain
+ * @situation inspect and atomically edit the terrain editor from an agent
+ * @constraint optional tooling; only subscribe/mount touches DOM; stale revisions fail explicitly
+ * @example const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();
+ * @override editorUrl is the activation-returned project URL
+ */
+declare class TerrainEditorController {
+    #private;
+    readonly baseUrl: string;
+    constructor(editorUrl: string);
+    activate(): Promise<IEditorActivation>;
+    snapshot(): Promise<IEditorSnapshot>;
+    /**
+     * Answer a read-only spatial query against one exact revision, GUI or headless.
+     * @param query a `point`, `profile` or `reference` query from the saved document revision
+     */
+    inspect(query: ISpatialQuery, baseRevision: string): Promise<{
+        result: ISpatialObservation;
+    }>;
+    /**
+     * Run one create / get / list / update / delete / activate camera operation against one exact
+     * revision. Editor observation cameras only: gameplay cameras belong to the consuming game.
+     * @param operation a camera operation from {@link ICameraOperation}
+     */
+    camera(operation: ICameraOperation, baseRevision: string): Promise<ICameraResult & {
+        revision: string;
+    }>;
+    /**
+     * Run one get / patch / reset against the saved preview environment at one exact revision.
+     * Appearance only: terrain, collision and placements are never re-evaluated.
+     * @param operation an environment operation from {@link IEnvironmentOperation}
+     */
+    environment(operation: IEnvironmentOperation, baseRevision: string): Promise<IEnvironmentResult & {
+        revision: string;
+    }>;
+    /**
+     * Register, upload, adjust, remove or list project assets at one exact revision. `register`
+     * takes a local file path, the shape an asset-MCP download returns; `upload` takes bytes a
+     * browser read. Both store the file under a content-hashed name and measure it.
+     * @param operation an asset operation from {@link IAssetOperation}
+     */
+    asset(operation: IAssetOperation, baseRevision: string): Promise<IAssetResult & {
+        revision: string;
+    }>;
+    commit(transaction: {
+        baseRevision: string;
+        document: IAuthoringDocument;
+    } | {
+        baseRevision: string;
+        commands: readonly PatchCommand[];
+    }): Promise<IEditorSnapshot>;
+    subscribe(listener: (snapshot: IEditorSnapshot) => void, onError: () => void): () => void;
+}
+/**
+ * Mount recovered terrain controls around the project-owned ThreeNative view.
+ * @requires npm i -D @threenative/terrain
+ * @situation open the terrain brush and layer GUI around game-owned rendering
+ * @constraint browser authoring only; createView and materialColours are required game choices
+ * @example await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });
+ * @override createView owns the renderer scene, materials, lighting and camera
+ */
+declare function mountTerrainEditor(options: {
+    createView(host: HTMLElement, controller: TerrainEditorController): Promise<IEditorView>;
+    materialColours: readonly (readonly [number, number, number])[];
+    onEvaluated?(event: {
+        revision: string;
+        state: ITerrainState;
+        ms: number;
+    }): void;
+}): Promise<{
+    controller: TerrainEditorController;
+    dispose(): void;
+}>;
+
+export { IAssetOperation, IAssetResult, ICameraOperation, ICameraResult, type IEditorView, IEnvironment, IEnvironmentOperation, IEnvironmentResult, IFocusBounds, IFocusOutcome, IFocusRequest, type IImageReport, ISavedCamera, ISpatialObservation, ISpatialQuery, type ISurfaceChannel, type IViewCamera, type IViewEnvironment, type IViewerPose, SURFACE_CHANNELS, TerrainEditorController, inspectImage, mountTerrainEditor };