@threenative/terrain 0.0.0-stage → 0.1.1

package/dist/server-ByM2hmYJ.d.ts

@@ -0,0 +1,630 @@
+import { Plugin } from 'vite';
+import { I as ITerrainState, d as ITerrainDocument, h as IPlacementOverride } from './types-Ant8-Axc.js';
+
+type IAssetKind = "model" | "image" | "environment";
+interface IAssetBounds {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+}
+/** Source-unit scale and pivot applied when a model is placed; the file itself is never edited. */
+interface IAssetAdjust {
+    /** Multiplies the model's own units to metres. 1 means the file is already in metres. */
+    readonly scale: number;
+    /** Which point of the bounds sits on the placement: the base centre, the centre or the origin. */
+    readonly pivot: "base" | "centre" | "origin";
+}
+/** One registered file, as saved in the authoring document. */
+interface IProjectAsset {
+    readonly id: string;
+    readonly kind: IAssetKind;
+    readonly name: string;
+    /** Relative to the project's assets directory; the file's name carries its content hash. */
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+    readonly status: "ready";
+    readonly license?: string;
+    readonly source?: string;
+    readonly bounds?: IAssetBounds;
+    readonly triangles?: number;
+    readonly adjust?: IAssetAdjust;
+    /** Authoring diagnostics, e.g. an imported light that stays inactive. */
+    readonly diagnostics?: readonly string[];
+    readonly width?: number;
+    readonly height?: number;
+    /** An image's declared format: `png`, `jpeg`, `webp`, `hdr` or `exr`. */
+    readonly format?: string;
+}
+interface IAssetLimits {
+    /** File size cap in bytes. */
+    readonly maxBytes: number;
+    /** Decoded image width/height cap in pixels. */
+    readonly maxDimension: number;
+    /** Triangle cap for one model. */
+    readonly maxTriangles: number;
+}
+/**
+ * Validate one saved asset registration exactly as a document commit stores it.
+ * @summary Validate a registered terrain-editor asset entry
+ * @requires npm i -D @threenative/terrain
+ * @situation check a model, image or environment asset entry before saving it in the authoring document
+ * @constraint authoring metadata only; ids, content-hashed paths, bounds and unit adjustments are checked, files are not read
+ * @example const asset = validateAsset({ id: "oak", kind: "model", name: "oak.glb", path: "models/0123456789ab-oak.glb", sha256: "0123456789ab".padEnd(64, "0"), bytes: 2180, status: "ready" });
+ * @override the project owns its asset directory and which entries it keeps
+ */
+declare function validateAsset(input: unknown): IProjectAsset;
+/**
+ * Validate the whole asset list of an authoring document.
+ * @summary Validate the registered terrain-editor assets
+ * @requires npm i -D @threenative/terrain
+ * @situation check every registered model, image and environment entry together, with unique ids
+ * @constraint at most 64 entries; unique ids; each entry as validateAsset
+ * @example const assets = validateAssets(document.assets ?? []);
+ * @override the project owns its asset directory and which entries it keeps
+ */
+declare function validateAssets(input: unknown): IProjectAsset[];
+type IAssetOperation = {
+    readonly op: "list";
+}
+/** The agent path: a local file, as an asset-MCP download result returns it. */
+ | {
+    readonly op: "register";
+    readonly id: string;
+    readonly kind?: IAssetKind;
+    readonly path: string;
+    readonly license?: string;
+    readonly source?: string;
+    readonly replace?: boolean;
+}
+/** The GUI path: bytes the browser read from a picked or dropped file. */
+ | {
+    readonly op: "upload";
+    readonly id: string;
+    readonly kind?: IAssetKind;
+    readonly name: string;
+    readonly data: string;
+    readonly license?: string;
+    readonly source?: string;
+    readonly replace?: boolean;
+} | {
+    readonly op: "adjust";
+    readonly id: string;
+    readonly adjust: unknown;
+}
+/** Bind an image asset to one named surface input of the project's render source. */
+ | {
+    readonly op: "map";
+    readonly input: string;
+    readonly asset: string;
+}
+/** Return one surface input to the project's own art. */
+ | {
+    readonly op: "unmap";
+    readonly input: string;
+}
+/** Removes the palette entry only; the stored file is never erased. */
+ | {
+    readonly op: "remove";
+    readonly id: string;
+};
+/** One surface input and the registered image that replaces its starter art. */
+interface ISurfaceMapping {
+    readonly asset: string;
+}
+type ISurfaceMappings = Record<string, ISurfaceMapping>;
+interface IAssetResult {
+    readonly op: string;
+    readonly assets: readonly IProjectAsset[];
+    readonly surfaces: ISurfaceMappings;
+    readonly asset: IProjectAsset | null;
+}
+/**
+ * The kind and format a file's own bytes declare, whatever its name says.
+ * @summary Identify a GLB, PNG, JPEG, WebP, HDR or EXR file by its header
+ * @requires npm i -D @threenative/terrain
+ * @situation decide whether a dropped or downloaded file is a model, surface image or environment image
+ * @constraint reads only the first bytes; a file it cannot name returns undefined and must be refused
+ * @example const kind = sniff(new Uint8Array(await file.arrayBuffer()))?.kind;
+ * @override the caller decides what to do with an unknown file
+ */
+declare function sniff(bytes: Uint8Array): {
+    kind: IAssetKind;
+    ext: string;
+    format: string;
+} | undefined;
+/**
+ * The colour space an input's pixels are read in, from the channel its name ends with.
+ * @summary Resolve a surface input name to sRGB or linear
+ * @requires npm i -D @threenative/terrain
+ * @situation decide how an imported image bound to a named surface input must be sampled
+ * @constraint throws by name for an input that is not <surface>.<channel> with a known channel
+ * @example const space = surfaceSpace("bark.normal");
+ * @override the project owns which surface inputs exist
+ */
+declare function surfaceSpace(input: string): "srgb" | "linear";
+/**
+ * Validate surface mappings against the registered images they name.
+ * @summary Validate terrain-editor surface image mappings
+ * @requires npm i -D @threenative/terrain
+ * @situation save which imported PBR image replaces which named surface input of the project's render source
+ * @constraint authoring metadata only; each input is <surface>.<channel>; every asset must be a registered image
+ * @example const surfaces = validateSurfaces({ "bark.normal": { asset: "my-normal" } }, document.assets ?? []);
+ * @override the project's render source defines which surface inputs exist and what they draw
+ */
+declare function validateSurfaces(input: unknown, assets: readonly IProjectAsset[]): ISurfaceMappings;
+
+/** Position/target/planes of one named observation camera. */
+interface ICameraPose {
+    /** Stable across renames and reloads; selection and saves address the camera by it. */
+    readonly id: string;
+    readonly name: string;
+    /** Local metres, Y up, centred on the terrain origin. */
+    readonly position: readonly [number, number, number];
+    readonly target: readonly [number, number, number];
+    readonly up: readonly [number, number, number];
+    readonly near: number;
+    readonly far: number;
+}
+/** A saved camera: perspective with a field of view, or orthographic with an extent and zoom. */
+type ISavedCamera = ICameraPose & ({
+    readonly projection: "perspective";
+    readonly fov: number;
+} | {
+    readonly projection: "orthographic";
+    readonly extent: number;
+    readonly zoom: number;
+});
+/** The camera list saved with the authoring document, plus which one is live. */
+interface ICameraSet {
+    readonly cameras: readonly ISavedCamera[];
+    /** `null` is the ordinary editor camera, not a saved bookmark. */
+    readonly activeCamera: string | null;
+}
+type ICameraOperation = {
+    readonly op: "create";
+    readonly camera: unknown;
+} | {
+    readonly op: "get";
+    readonly id: string;
+} | {
+    readonly op: "list";
+} | {
+    readonly op: "update";
+    readonly id: string;
+    readonly patch: unknown;
+} | {
+    readonly op: "delete";
+    readonly id: string;
+} | {
+    readonly op: "activate";
+    readonly id: string | null;
+};
+interface ICameraResult {
+    readonly op: string;
+    readonly cameras: readonly ISavedCamera[];
+    readonly activeCamera: string | null;
+    /** The camera the operation addresses: the created, read or changed one. */
+    readonly camera: ISavedCamera | null;
+    /** `editor-camera` when this operation left the ordinary editor camera live. */
+    readonly fallback: string | null;
+}
+/**
+ * Normalise and validate one saved camera, exactly as a document commit would store it.
+ * @summary Validate an editor observation camera bookmark
+ * @requires npm i -D @threenative/terrain
+ * @situation create or update a named terrain-editor camera in the shared authoring document
+ * @constraint authoring metadata only; finite noncoincident poses, usable up, valid projection, ordered planes
+ * @example const camera = validateCamera({ id: "survey", name: "Survey", position: [40, 60, 40], target: [0, 12, 0], up: [0, 1, 0], projection: "perspective", fov: 50, near: 0.5, far: 900 });
+ * @override the caller owns the document revision and the live viewport aspect
+ */
+declare function validateCamera(input: unknown, existing?: readonly ISavedCamera[]): ISavedCamera;
+/**
+ * Validate a document's saved camera list, keeping ids unique across it.
+ * @summary Validate the saved editor camera list of an authoring document
+ * @requires npm i -D @threenative/terrain
+ * @situation reject a disk document whose saved cameras are malformed or duplicated
+ * @constraint authoring metadata only; the same validation the camera operations apply
+ * @example const cameras = validateCameras(JSON.parse(saved).cameras ?? []);
+ * @override the document owns how many cameras it keeps; the list bound is the editor's own
+ */
+declare function validateCameras(input: unknown): ISavedCamera[];
+/**
+ * Run one create / get / list / update / delete / activate operation over saved cameras.
+ * @summary Apply an editor camera operation to a saved camera set
+ * @requires npm i -D @threenative/terrain
+ * @situation drive the terrain editor camera list from an agent or the GUI through one shared dispatch
+ * @constraint pure: the input set is never mutated, an unknown id throws, and deleting the live camera falls back
+ * @example const next = runCameraOperation(set, { op: "activate", id: "survey" });
+ * @override the caller persists the returned set against its own revision
+ */
+declare function runCameraOperation(set: ICameraSet, operation: unknown): ICameraResult;
+/** World-space bounds of whatever a focus target resolved to. */
+interface IFocusBounds {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+}
+type IFocusTarget = {
+    readonly kind: "point";
+    readonly at: readonly [number, number, number];
+} | {
+    readonly kind: "prop" | "landmark" | "region";
+    readonly id: string;
+};
+/**
+ * Resolves a non-point focus target to real world bounds. The view owns this because only it holds
+ * the live instance matrices, the registered landmarks and the evaluated terrain extent.
+ */
+type IFocusResolver = (target: {
+    readonly kind: "prop" | "landmark" | "region";
+    readonly id: string;
+}) => IFocusBounds | undefined;
+interface IFocusRequest {
+    readonly target: IFocusTarget;
+    /** Measured from the live viewport; a saved browser aspect would frame the wrong picture. */
+    readonly aspect: number;
+    /** Extra room around the target as a multiplier of its own size. */
+    readonly margin?: number;
+    /** Heading kept from the current view, so focusing never spins the camera. */
+    readonly direction?: readonly [number, number, number];
+}
+interface IFocusFraming {
+    readonly centre: readonly [number, number, number];
+    readonly radiusMetres: number;
+    readonly distanceMetres: number;
+    readonly margin: number;
+    readonly aspect: number;
+    readonly near: number;
+    readonly far: number;
+    /** Orthographic only: the extent the viewport aspect needs to contain the target. */
+    readonly extent: number | null;
+}
+interface IFocusOutcome {
+    /** `null` keeps the last valid camera; the diagnostic then says why. */
+    readonly camera: ISavedCamera | null;
+    readonly framing: IFocusFraming | null;
+    readonly diagnostic: string | null;
+}
+/**
+ * Frame a point, prop, landmark or region for the live viewport and projection.
+ * @summary Frame a focus target with an editor observation camera
+ * @requires npm i -D @threenative/terrain
+ * @situation frame one selected prop, a registered landmark, a terrain region or a local point
+ * @constraint framing only; an unknown target returns a named diagnostic and no camera
+ * @example const outcome = focusCamera(camera, { target: { kind: "prop", id: "pine-3" }, aspect: 16 / 9 }, resolve);
+ * @override the view supplies target bounds, the live aspect and the camera to keep
+ */
+declare function focusCamera(camera: ISavedCamera, request: IFocusRequest, resolve: IFocusResolver): IFocusOutcome;
+
+/**
+ * Preview environment settings: validated values the editor binds to project-owned render source.
+ *
+ * This file decides nothing about how the world looks. Every field is optional and an absent field
+ * means "the project's own starter value", so the document carries only deliberate overrides and
+ * the view reports the effective values it started from.
+ */
+/** Hex colour as saved: `#rrggbb`. */
+type IHexColour = string;
+interface IEnvironment {
+    /** Direction towards the sun, as angles; intensity in the project's light units. */
+    readonly sun?: {
+        /** Degrees, `atan2(z, x)` of the horizontal part of the direction towards the sun. */
+        readonly azimuth?: number;
+        /** Degrees above the horizon, 0 to 90. */
+        readonly elevation?: number;
+        readonly intensity?: number;
+        readonly colour?: IHexColour;
+    };
+    /** Sky fill: the hemisphere light's intensity. */
+    readonly fill?: {
+        readonly intensity?: number;
+    };
+    /**
+     * What is drawn behind the world: a procedural colour, or a registered environment/image asset.
+     * An image replaces the colour; remove it (null) and the colour is back.
+     */
+    readonly sky?: {
+        readonly colour?: IHexColour;
+        /** A registered HDR/EXR or ordinary equirectangular image id. */
+        readonly image?: string;
+        /** Degrees about the vertical axis. */
+        readonly rotation?: number;
+        /** Multiplies the image's radiance. */
+        readonly intensity?: number;
+    };
+    /**
+     * Illumination from an image, chosen independently of the background. When it is set and the
+     * sky fill is not, the hemisphere fill is 0 so the image is the one fill and light is not
+     * counted twice; the sun is its own, explicit contribution.
+     */
+    readonly lighting?: {
+        readonly image?: string;
+        readonly rotation?: number;
+        readonly intensity?: number;
+    };
+    /** Distance haze. `mode` names a fog this source supports; anything else is refused by name. */
+    readonly fog?: {
+        readonly mode?: "exp2";
+        readonly colour?: IHexColour;
+        /** Per metre. */
+        readonly density?: number;
+    };
+    /** Linear exposure multiplier (2^EV). */
+    readonly exposure?: number;
+    /** The sea's shallow and deep colour; wave behaviour is project render source. */
+    readonly ocean?: {
+        readonly shallow?: IHexColour;
+        readonly deep?: IHexColour;
+    };
+}
+type IEnvironmentOperation = {
+    readonly op: "get";
+}
+/** Deep-merge validated values; a `null` field returns that field to the project's value. */
+ | {
+    readonly op: "patch";
+    readonly values: unknown;
+} | {
+    readonly op: "reset";
+};
+interface IEnvironmentResult {
+    readonly op: string;
+    /** The saved overrides after this operation. */
+    readonly environment: IEnvironment;
+}
+/**
+ * Validate a complete overrides object exactly as a document commit stores it.
+ * @summary Validate preview environment overrides
+ * @requires npm i -D @threenative/terrain
+ * @situation save sun, sky, haze, exposure or ocean overrides in the shared authoring document
+ * @constraint authoring metadata only; unknown fields and unsupported fog modes are refused by name
+ * @example const environment = validateEnvironment({ sun: { elevation: 25, intensity: 3 } });
+ * @override the project's render source defines what each value does; absent fields keep its own
+ */
+declare function validateEnvironment(input: unknown): IEnvironment;
+/**
+ * Apply one get / patch / reset against the saved environment overrides; the caller commits it.
+ * @summary Run one preview-environment operation
+ * @requires npm i -D @threenative/terrain
+ * @situation patch sun, haze, exposure or sea overrides from a controller or the editor GUI
+ * @constraint authoring metadata only; a null field returns to the project's own value
+ * @example const result = runEnvironmentOperation({}, { op: "patch", values: { sun: { elevation: 25 } } });
+ * @override the project's render source decides what each value does
+ */
+declare function runEnvironmentOperation(current: IEnvironment, operation: unknown): IEnvironmentResult;
+/**
+ * Check that the images an environment names are registered environment or image assets.
+ * @summary Validate the assets a preview environment refers to
+ * @requires npm i -D @threenative/terrain
+ * @situation refuse a saved environment whose sky or lighting image is not a registered file
+ * @constraint throws by name; HDR/EXR environment files and ordinary images are accepted, models are not
+ * @example checkEnvironmentAssets({ sky: { image: "dusk" } }, document.assets ?? []);
+ * @override the project owns which images it registers
+ */
+declare function checkEnvironmentAssets(environment: IEnvironment, assets: readonly {
+    id: string;
+    kind: string;
+}[]): void;
+
+/** A labelled point shared between a reference image and local world metres. */
+interface ISpatialControlPoint {
+    readonly id: string;
+    /** `[u, v]` image pixels. */
+    readonly image: readonly [number, number];
+    /** `[x, z]` local metres, Y up, centred on the terrain origin. */
+    readonly world: readonly [number, number];
+}
+/**
+ * A bounded local reference image saved with the document.
+ * `screenshot` is a perspective view reference; only a `top-down-map` is metric.
+ */
+interface ISpatialReference {
+    readonly id: string;
+    readonly kind: "top-down-map" | "screenshot";
+    /** Content hash of the imported image; different pixels are a different reference. */
+    readonly hash: string;
+    /** Where the image came from, in the author's words. */
+    readonly source: string;
+    /** Vertical datum. `null` means unknown, never zero. */
+    readonly datum?: string | null;
+    /** Horizontal residual budget for a checkpoint to count as aligned. Defaults to 1 m. */
+    readonly toleranceMetres?: number;
+    /** Two distinct controls fit scale, rotation and translation; more are reported, not fitted. */
+    readonly controls: readonly ISpatialControlPoint[];
+    /** An independent check point, never used to fit. Without one the fit is uncalibrated. */
+    readonly checkpoint?: ISpatialControlPoint | null;
+}
+/** A validated reference: every optional field resolved, unknown datum kept as `null`. */
+type ISavedSpatialReference = ISpatialReference & {
+    readonly datum: string | null;
+    readonly toleranceMetres: number;
+    readonly checkpoint: ISpatialControlPoint | null;
+};
+type ISpatialQuery = {
+    readonly kind: "point";
+    readonly at: readonly number[];
+} | {
+    readonly kind: "profile";
+    readonly from: readonly number[];
+    readonly to: readonly number[];
+    readonly samples?: number;
+} | {
+    readonly kind: "reference";
+    readonly reference: ISpatialReference;
+};
+/** One measured surface value, labelled with the sampler that produced it. */
+interface ISurfaceReading {
+    readonly source: "bilinear-heightfield" | "evaluated-triangle";
+    readonly height: number;
+    readonly slopeDeg: number;
+    /** Compass degrees clockwise from -Z. `null` on flat ground, where it is undefined. */
+    readonly aspectDeg: number | null;
+    readonly normal: readonly [number, number, number];
+}
+interface IPointObservation {
+    readonly kind: "point";
+    readonly revision: string;
+    readonly units: "metres";
+    readonly resolution: number;
+    readonly at: readonly [number, number];
+    readonly bilinear: ISurfaceReading;
+    readonly triangle: ISurfaceReading;
+    /** `triangle.height - bilinear.height`; non-zero inside a non-planar cell. */
+    readonly difference: number;
+    readonly datum: string | null;
+    readonly labels: readonly string[];
+}
+interface IProfileSample {
+    /** Horizontal distance from `from`, in metres. */
+    readonly distance: number;
+    /** Distance walked along the measured surface so far. */
+    readonly surfaceDistance: number;
+    readonly height: number;
+    readonly slopeDeg: number;
+}
+interface IProfileObservation {
+    readonly kind: "profile";
+    readonly revision: string;
+    readonly units: "metres";
+    readonly resolution: number;
+    readonly from: readonly [number, number];
+    readonly to: readonly [number, number];
+    readonly sampleCount: number;
+    readonly horizontalDistance: number;
+    readonly surfaceDistance: number;
+    readonly minElevation: number;
+    readonly maxElevation: number;
+    readonly maxGradeDeg: number;
+    readonly samples: readonly IProfileSample[];
+    readonly datum: string | null;
+    readonly labels: readonly string[];
+}
+interface IReferenceObservation {
+    readonly kind: "reference";
+    readonly revision: string;
+    readonly units: "metres";
+    readonly id: string;
+    readonly source: string;
+    readonly hash: string;
+    readonly metric: boolean;
+    /** Smallest 2D similarity from the two fit controls. `null` until two distinct ones exist. */
+    readonly fit: {
+        readonly scaleMetresPerPixel: number | null;
+        readonly rotationDegrees: number | null;
+        /** The fit never mirrors an image; a mirrored sheet is reported, not silently applied. */
+        readonly mirrored: false;
+    } | null;
+    readonly controlResidualMetres: number | null;
+    readonly landmarks: readonly {
+        readonly id: string;
+        readonly role: "control" | "checkpoint";
+        readonly image: readonly [number, number];
+        readonly world: readonly [number, number];
+        /** `null` until two distinct controls exist; never a fabricated zero. */
+        readonly fitted: readonly [number, number] | null;
+        readonly horizontalResidualMetres: number | null;
+    }[];
+    readonly checkpoint: {
+        readonly id: string;
+        readonly residualMetres: number;
+        readonly withinTolerance: boolean;
+    } | null;
+    readonly toleranceMetres: number;
+    /** Fitted controls alone are not calibration; an independent checkpoint within tolerance is. */
+    readonly calibrated: boolean;
+    readonly datum: string | null;
+    readonly labels: readonly string[];
+}
+type ISpatialObservation = IPointObservation | IProfileObservation | IReferenceObservation;
+/**
+ * Probe the evaluated surface at one world point, separating bilinear from triangle values.
+ * @requires npm i -D @threenative/terrain
+ * @situation measure an authored terrain point with provenance and a revision identity
+ * @constraint authoring data only; non-finite, malformed and out-of-extent queries throw
+ * @example const probe = probeTerrain(state, revision, [12, -4]);
+ * @override the caller owns the revision identity and the evaluated state being inspected
+ */
+declare function probeTerrain(state: ITerrainState, revision: string, at: readonly number[]): IPointObservation;
+/**
+ * Normalise and validate one saved reference, exactly as a document commit would store it.
+ * @requires npm i -D @threenative/terrain
+ * @situation accept a bounded local reference image registration into the shared document
+ * @constraint authoring metadata only; rejects unknown fields, malformed points and unknown scale
+ * @example const reference = validateSpatialReference(JSON.parse(saved));
+ * @override a project owns the image file; only its hash and provenance travel in the document
+ */
+declare function validateSpatialReference(input: unknown): ISavedSpatialReference;
+/**
+ * Read-only spatial inspection of one evaluated terrain revision.
+ * @requires npm i -D @threenative/terrain
+ * @situation measure a point, profile a transect or score a saved reference against the world
+ * @constraint authoring data only; queries outside the extent or without observations throw
+ * @example const observation = inspectSpatial(state, revision, { kind: "point", at: [0, 0] });
+ * @override the caller owns the revision identity and the evaluated state being inspected
+ */
+declare function inspectSpatial(state: ITerrainState, revision: string, query: ISpatialQuery): ISpatialObservation;
+
+interface IAuthoringDocument {
+    version: 1;
+    recipe: ITerrainDocument;
+    placementOverrides?: Record<string, IPlacementOverride>;
+    /** Saved reference registrations. Authoring metadata: never evaluated, never exported. */
+    references?: ReturnType<typeof validateSpatialReference>[];
+    /** Saved editor observation cameras. Authoring metadata: never evaluated, never exported. */
+    cameras?: ISavedCamera[];
+    /** Which saved camera is live; absent or `null` is the ordinary editor camera. */
+    activeCamera?: string | null;
+    /** Preview environment overrides; absent fields keep the project's own render-source values. */
+    environment?: IEnvironment;
+    /** Registered models, images and environment files: metadata only, the files live on disk. */
+    assets?: IProjectAsset[];
+    /** Imported images that replace named surface inputs of the project's render source. */
+    surfaces?: ISurfaceMappings;
+}
+interface IEditorSnapshot {
+    revision: string;
+    document: IAuthoringDocument;
+    diagnostic: string | null;
+}
+interface IEditorActivation {
+    editorUrl: string;
+    projectId: string;
+    sessionId: string;
+    revision: string;
+}
+/**
+ * Project-local terrain document authority; no renderer or game dependency.
+ * @requires npm i -D @threenative/terrain
+ * @situation validate atomic revision-based project-local terrain document edits
+ * @constraint Node authoring only; documentPath is a configured absolute regular file; input is bounded to 64 MiB
+ * @example const document = new TerrainEditorDocument("/project/terrain/world.json"); const snapshot = document.snapshot();
+ * @override the project chooses its document path; revisions come from validated content
+ */
+declare class TerrainEditorDocument {
+    #private;
+    readonly path: string;
+    constructor(path: string);
+    snapshot(): IEditorSnapshot;
+    subscribe(listener: (snapshot: IEditorSnapshot) => void): () => void;
+    refresh(): void;
+    commit(input: unknown): IEditorSnapshot;
+}
+/**
+ * Mount the optional terrain document API on an existing loopback Vite server.
+ * @requires npm i -D @threenative/terrain vite
+ * @situation share terrain recipe edits between an agent and the live terrain editor
+ * @constraint dev tooling only; serve a project-owned /terrain-editor/index.html; no runtime import
+ * @example const editor = terrainEditor({ documentPath: resolve("terrain/world.json") });
+ * @override documentPath and optional configured viewerUrl belong to the project
+ */
+declare function terrainEditor(options: {
+    documentPath: string;
+    viewerUrl?: string;
+    /** Where registered files are stored; defaults to `assets/` beside the document. */
+    assetsDir?: string;
+    /** Explicit byte, decoded-dimension and triangle limits for imports. */
+    assetLimits?: Partial<IAssetLimits>;
+}): Plugin & {
+    activate(): Promise<IEditorActivation>;
+};
+
+export { terrainEditor as $, type IProfileObservation as A, type IProfileSample as B, type IProjectAsset as C, type IReferenceObservation as D, type ISavedSpatialReference as E, type ISpatialControlPoint as F, type ISpatialReference as G, type ISurfaceMapping as H, type IAuthoringDocument as I, type ISurfaceMappings as J, type ISurfaceReading as K, checkEnvironmentAssets as L, focusCamera as M, inspectSpatial as N, probeTerrain as O, runCameraOperation as P, runEnvironmentOperation as Q, sniff as R, surfaceSpace as S, validateAsset as T, validateAssets as U, validateCamera as V, validateCameras as W, validateEnvironment as X, validateSpatialReference as Y, validateSurfaces as Z, TerrainEditorDocument as _, type ISavedCamera as a, type IFocusRequest as b, type IFocusOutcome as c, type IFocusBounds as d, type IEnvironment as e, type IEditorActivation as f, type IEditorSnapshot as g, type ISpatialQuery as h, type ISpatialObservation as i, type ICameraOperation as j, type ICameraResult as k, type IEnvironmentOperation as l, type IEnvironmentResult as m, type IAssetOperation as n, type IAssetResult as o, type IAssetAdjust as p, type IAssetBounds as q, type IAssetKind as r, type IAssetLimits as s, type ICameraPose as t, type ICameraSet as u, type IFocusFraming as v, type IFocusResolver as w, type IFocusTarget as x, type IHexColour as y, type IPointObservation as z };