@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

package/src/api/core/io/terrain/index.ts

@@ -1,360 +1,360 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import { TerrainHandle } from "../../../../handles"
-
-/**
- * Terrain — inspect and manage the project's site terrain (the singleton created
- * by `core.io.import.terrain`).
- *
- * There is at most one terrain per project. These methods read and edit it: the
- * vertical **datum**, elevation/satellite layers, opacity, the cut/fill report,
- * and removal. All edits are undoable.
- *
- * ## Datum
- * The **datum** is the terrain's vertical position relative to where it was
- * imported. {@link PluginCoreIoTerrainApi.setDatum} shifts the whole terrain
- * vertically by a **relative** offset (each call moves it further — calls are
- * cumulative, not absolute); {@link PluginCoreIoTerrainApi.getDatum} reads the
- * current vertical offset from the imported position.
- *
- * Accessed via `snaptrude.core.io.terrain`.
- */
-export abstract class PluginCoreIoTerrainApi {
-  constructor() {}
-
-  /**
-   * Whether the project has a site terrain.
-   *
-   * @examplePrompt Does this project have site terrain?
-   * @examplePrompt Is there a terrain imported?
-   * @examplePrompt Check if the site topography exists
-   * @examplePrompt Has a terrain been added yet?
-   *
-   * # Example
-   * ```ts
-   * if (!(await snaptrude.core.io.terrain.exists())) {
-   *   await snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)
-   * }
-   * ```
-   */
-  public abstract exists(): PluginApiReturn<boolean>
-
-  /**
-   * Resolve the project's terrain handle, or `null` if there is none. The same
-   * handle {@link core.io.import.terrain} returns — use it to obtain the handle
-   * without re-importing.
-   *
-   * @examplePrompt Get the terrain handle
-   * @examplePrompt Give me the site terrain
-   * @examplePrompt Fetch the current terrain
-   * @examplePrompt Return the topography handle if it exists
-   */
-  public abstract get(): PluginApiReturn<TerrainHandle | null>
-
-  /**
-   * Read the terrain's current vertical position (world Y, internal units).
-   * `null` if there is no terrain. Import places the terrain so its highest
-   * point sits at `y = 0`, so a never-shifted terrain reads a negative
-   * baseline, not `0`; each {@link PluginCoreIoTerrainApi.setDatum} shift
-   * moves this value.
-   *
-   * @examplePrompt What's the terrain's datum?
-   * @examplePrompt Read the current site elevation reference
-   * @examplePrompt Get the terrain vertical offset
-   * @examplePrompt How far has the datum been shifted?
-   */
-  public abstract getDatum(): PluginApiReturn<number | null>
-
-  /**
-   * Shift the terrain's **datum** — move the whole terrain vertically DOWN by
-   * `offset` (internal units) from its current position; pass a negative value to
-   * raise it. Undoable.
-   *
-   * **Relative and cumulative**, not absolute: `setDatum(5)` called twice shifts
-   * the terrain down by 10 total, it does not settle at a fixed level. Read the
-   * terrain's resulting vertical position (world Y — not the accumulated
-   * shift) back with {@link PluginCoreIoTerrainApi.getDatum}.
-   *
-   * @param offset - How far to shift the terrain down, in internal units
-   *   (negative raises it).
-   * @throws if writes are disabled, there is no terrain, or the terrain is
-   *   **locked** (unlock it in the app first).
-   *
-   * @examplePrompt Shift the terrain datum down by 12
-   * @examplePrompt Lower the site terrain by 10
-   * @examplePrompt Raise the terrain a little
-   * @examplePrompt Nudge the terrain datum down
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.io.terrain.setDatum(12)   // shift terrain down by 12 (relative)
-   * ```
-   */
-  public abstract setDatum(offset: number): PluginApiReturn<void>
-
-  /**
-   * Delete the site terrain. Undoable.
-   *
-   * @throws if writes are disabled, there is no terrain, or the terrain is
-   *   **locked** (unlock it in the app first).
-   *
-   * @examplePrompt Delete the site terrain
-   * @examplePrompt Remove the topography
-   * @examplePrompt Clear the imported site
-   * @examplePrompt Get rid of the terrain
-   */
-  public abstract delete(): PluginApiReturn<void>
-
-  /**
-   * The terrain cut/fill earthwork report — cut, fill, and net volumes — or
-   * `null` if there is no terrain.
-   *
-   * @examplePrompt What are the cut and fill volumes for the site?
-   * @examplePrompt Get the terrain earthwork report
-   * @examplePrompt How much cut and fill does the grading need?
-   * @examplePrompt Show the net volume of the terrain edits
-   *
-   * # Example
-   * ```ts
-   * const r = await snaptrude.core.io.terrain.getReport()
-   * if (r) console.log(`cut ${r.cutVolume}, fill ${r.fillVolume}, net ${r.netVolume}`)
-   * ```
-   */
-  public abstract getReport(): PluginApiReturn<TerrainReport | null>
-
-  /** Whether terrain elevation (DEM height) is on. `null` if no terrain. */
-  public abstract isElevationEnabled(): PluginApiReturn<boolean | null>
-  /**
-   * Turn terrain elevation (DEM height) ON — a real 3D topography surface. Undoable.
-   * @throws if writes are disabled, there is no terrain, or the terrain is
-   *   **locked** (unlock it in the app first).
-   * @examplePrompt Turn on terrain elevation
-   * @examplePrompt Enable the site heightmap
-   * @examplePrompt Make the terrain 3D
-   * @examplePrompt Show the topography relief
-   */
-  public abstract enableElevation(): PluginApiReturn<void>
-  /**
-   * Turn terrain elevation OFF — flatten to a plane. Undoable.
-   * @throws if writes are disabled, there is no terrain, or the terrain is
-   *   **locked** (unlock it in the app first).
-   * @examplePrompt Flatten the terrain
-   * @examplePrompt Turn off site elevation
-   * @examplePrompt Disable the heightmap
-   * @examplePrompt Make the terrain flat
-   */
-  public abstract disableElevation(): PluginApiReturn<void>
-
-  /** Whether satellite imagery is draped on the terrain. `null` if no terrain. */
-  public abstract isSatelliteEnabled(): PluginApiReturn<boolean | null>
-  /**
-   * Turn satellite imagery ON. Undoable.
-   * @throws if writes are disabled, there is no terrain, or the terrain is
-   *   **locked** (unlock it in the app first).
-   * @examplePrompt Show satellite imagery on the site
-   * @examplePrompt Enable the satellite texture
-   * @examplePrompt Turn on aerial imagery
-   * @examplePrompt Drape satellite over the terrain
-   */
-  public abstract enableSatellite(): PluginApiReturn<void>
-  /**
-   * Turn satellite imagery OFF. Undoable.
-   * @throws if writes are disabled, there is no terrain, or the terrain is
-   *   **locked** (unlock it in the app first).
-   * @examplePrompt Hide the satellite imagery
-   * @examplePrompt Turn off the aerial texture
-   * @examplePrompt Disable satellite on the site
-   * @examplePrompt Remove the satellite drape
-   */
-  public abstract disableSatellite(): PluginApiReturn<void>
-
-  /**
-   * Replace the terrain surface with a caller-supplied triangle mesh. Undoable
-   * (one step), and the replacement persists with the project. The returned
-   * promise resolves only after the surface is fully applied and recorded —
-   * it is safe to toggle terrain resolution or read the surface back the
-   * moment it resolves.
-   *
-   * `positions` is a flat `[x, y, z, …]` array in **world space** — the same
-   * frame `design.query.geometry.getTriangulatedMeshes` reads — so a
-   * read-modify-write round trip needs no conversion. `indices` is a flat
-   * triangle list into `positions` (three indices per triangle). A
-   * predominantly down-facing surface is flipped automatically (reported in
-   * `warnings`), and zero-area sliver triangles are tolerated and counted.
-   *
-   * **What survives the replacement:** the datum, geolocation, opacity, lock
-   * state, and the elevation/satellite toggles. The map/satellite texture is
-   * re-projected onto the new surface from above (best effort — alignment is
-   * approximate, reported in `warnings`). **What resets:** cut/fill history
-   * and the earthwork report — the replaced surface starts with a clean
-   * grading slate.
-   *
-   * Limits: at most 500,000 triangles and 500,000 vertices; every coordinate
-   * must be finite and within the scene bound.
-   *
-   * @param positions - Flat `[x, y, z, …]` world-space vertex positions.
-   * @param indices - Flat triangle list into `positions`.
-   * @param units - `"world"` (default): coordinates are raw internal units;
-   *   `"meters"`: coordinates are metres and are converted on the way in.
-   * @param options - Optional {@linkcode PluginTerrainReplaceMeshOptions}:
-   *   optimistic-concurrency expectations (`expectedTerrain`,
-   *   `expectedModelRevision`), `preserve` opt-outs, idempotent replay via
-   *   `clientMutationId`, and the `coordinateSpace`/`baseline` declarations.
-   * @throws if writes are disabled, there is no terrain (import one first),
-   *   the terrain is **locked**, the mesh fails validation (non-finite or
-   *   out-of-bound coordinates, bad indices, degenerate-only geometry, over
-   *   the size caps), `expectedTerrain` does not match the live terrain, or
-   *   `expectedModelRevision` is stale.
-   *
-   * @examplePrompt Replace the terrain with this surveyed mesh
-   * @examplePrompt Flatten a building pad into the site surface
-   * @examplePrompt Load a custom DEM surface onto the terrain
-   * @examplePrompt Regrade the terrain from these points
-   *
-   * # Example
-   * ```ts
-   * // Projects with no terrain yet: import first, then replace.
-   * if (!(await snaptrude.core.io.terrain.exists())) {
-   *   await snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)
-   * }
-   * const result = await snaptrude.core.io.terrain.replaceMesh(
-   *   positions, // [x0, y0, z0, x1, y1, z1, …] — world space
-   *   indices,   // [a0, b0, c0, a1, b1, c1, …]
-   *   "meters",
-   *   {
-   *     coordinateSpace: "world",
-   *     expectedTerrain: await snaptrude.core.io.terrain.get(),
-   *     baseline: "make-replacement-original",
-   *     preserve: { datum: true, geolocation: true, satellite: true, material: true },
-   *     clientMutationId: "survey-2026-08-05-r1",
-   *   },
-   * )
-   * // result.modelRevision — pass back as expectedModelRevision on the next call
-   * ```
-   */
-  public abstract replaceMesh(
-    positions: number[],
-    indices: number[],
-    units?: "world" | "meters",
-    options?: PluginTerrainReplaceMeshOptions,
-  ): PluginApiReturn<PluginTerrainReplaceMeshResult>
-
-  /** Read the terrain opacity, `0`..`1`, or `null` if no terrain. */
-  public abstract getOpacity(): PluginApiReturn<number | null>
-  /**
-   * Set the terrain opacity (`0` transparent .. `1` opaque). Undoable.
-   * @param opacity - Target opacity, `0`..`1`.
-   * @throws if writes are disabled, there is no terrain, or the terrain is
-   *   **locked** (unlock it in the app first).
-   * @examplePrompt Fade the terrain to 50%
-   * @examplePrompt Make the site semi-transparent
-   * @examplePrompt Set terrain opacity to 0.3
-   * @examplePrompt Dim the topography
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.io.terrain.setOpacity(0.5)
-   * ```
-   */
-  public abstract setOpacity(opacity: number): PluginApiReturn<void>
-}
-
-/**
- * Terrain cut/fill earthwork report. Volumes are in the **project's display
- * volume unit** (what the UI shows), not internal units.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `cutVolume` | `number` | Total excavated (cut) volume |
- * | `fillVolume` | `number` | Total added (fill) volume |
- * | `netVolume` | `number` | Net volume (`fill − cut`) |
- */
-export const TerrainReport = z.object({
-  cutVolume: z.number(),
-  fillVolume: z.number(),
-  netVolume: z.number(),
-})
-export type TerrainReport = z.infer<typeof TerrainReport>
-
-/**
- * Result of {@link PluginCoreIoTerrainApi.replaceMesh}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `terrain` | `TerrainHandle` | The terrain (unchanged singleton handle) |
- * | `modelRevision` | `number` | Session-scoped terrain-mesh revision after this replace — pass back as `expectedModelRevision` for compare-and-swap semantics |
- * | `vertexCount` | `number` | Vertices in the applied mesh |
- * | `triangleCount` | `number` | Triangles in the applied mesh |
- * | `warnings` | `string[]` | Non-fatal notes: winding flipped, sliver triangles, approximate texture re-projection |
- */
-export type PluginTerrainReplaceMeshResult = {
-  terrain: TerrainHandle
-  modelRevision: number
-  vertexCount: number
-  triangleCount: number
-  warnings: string[]
-}
-
-/**
- * Options for {@link PluginCoreIoTerrainApi.replaceMesh}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `coordinateSpace` | `"world"`? | Declares the input frame. `world` is the only supported space (the same frame `getTriangulatedMeshes` reads) |
- * | `expectedTerrain` | `TerrainHandle`? | Optimistic check: throws `HANDLE_INVALID` if the live terrain is not this handle (session-scoped — handles do not survive reloads) |
- * | `expectedModelRevision` | `number`? | Optimistic check against the session terrain-mesh revision (starts at `0`, increments per successful `replaceMesh`; the result returns the new value). Stale → `PRECONDITION_FAILED` with the current revision in `details` |
- * | `baseline` | `"make-replacement-original"`? | Declares replacement semantics. This is the only (and default) behavior: the replacement becomes the persisted surface; the app's terrain Reset restores the original map heightmap as the escape hatch |
- * | `preserve` | object? | Opt-outs, all defaulting `true`. `datum: false` resets the terrain transform (authored coordinates become the local frame). `satellite: false` switches the drape off after the replace. `material: false` skips texture re-projection — the whole surface takes the ground material. `geolocation: false` is rejected (`VALIDATION`): geolocation is always preserved in this version |
- * | `clientMutationId` | `string`? | Session-scoped idempotency: a repeated call with the same id returns the original result without re-executing |
- */
-export const PluginTerrainReplaceMeshOptions = z
-  .object({
-    coordinateSpace: z.literal("world").optional(),
-    expectedTerrain: z.string().min(1).optional(),
-    expectedModelRevision: z.number().int().nonnegative().optional(),
-    baseline: z.literal("make-replacement-original").optional(),
-    preserve: z
-      .object({
-        datum: z.boolean().optional(),
-        geolocation: z.boolean().optional(),
-        satellite: z.boolean().optional(),
-        material: z.boolean().optional(),
-      })
-      .strict()
-      .optional(),
-    clientMutationId: z.string().min(1).max(128).optional(),
-  })
-  .strict()
-export type PluginTerrainReplaceMeshOptions = z.infer<typeof PluginTerrainReplaceMeshOptions>
-
-/**
- * Arguments for {@link PluginCoreIoTerrainApi.replaceMesh}. The caps are the
- * plugin surface's explicit payload ceiling: 500k vertices / 500k triangles.
- */
-export const PluginTerrainReplaceMeshArgs = z.object({
-  positions: z
-    .array(z.number().finite())
-    .min(9)
-    .max(1_500_000)
-    .refine((a) => a.length % 3 === 0, {
-      message: "positions must be a flat [x, y, z, …] array (length a multiple of 3)",
-    }),
-  indices: z
-    .array(z.number().int().nonnegative())
-    .min(3)
-    .max(1_500_000)
-    .refine((a) => a.length % 3 === 0, {
-      message: "indices must be a flat triangle list (length a multiple of 3)",
-    }),
-  units: z.enum(["world", "meters"]).optional(),
-  options: PluginTerrainReplaceMeshOptions.optional(),
-})
-export type PluginTerrainReplaceMeshArgs = z.infer<typeof PluginTerrainReplaceMeshArgs>
-
-/** Arguments for {@link PluginCoreIoTerrainApi.setDatum}. */
-export const PluginTerrainSetDatumArgs = z.object({ offset: z.number().finite() })
-export type PluginTerrainSetDatumArgs = z.infer<typeof PluginTerrainSetDatumArgs>
-
-/** Arguments for {@link PluginCoreIoTerrainApi.setOpacity}. */
-export const PluginTerrainSetOpacityArgs = z.object({ opacity: z.number().min(0).max(1) })
-export type PluginTerrainSetOpacityArgs = z.infer<typeof PluginTerrainSetOpacityArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { TerrainHandle } from "../../../../handles"
+
+/**
+ * Terrain — inspect and manage the project's site terrain (the singleton created
+ * by `core.io.import.terrain`).
+ *
+ * There is at most one terrain per project. These methods read and edit it: the
+ * vertical **datum**, elevation/satellite layers, opacity, the cut/fill report,
+ * and removal. All edits are undoable.
+ *
+ * ## Datum
+ * The **datum** is the terrain's vertical position relative to where it was
+ * imported. {@link PluginCoreIoTerrainApi.setDatum} shifts the whole terrain
+ * vertically by a **relative** offset (each call moves it further — calls are
+ * cumulative, not absolute); {@link PluginCoreIoTerrainApi.getDatum} reads the
+ * current vertical offset from the imported position.
+ *
+ * Accessed via `snaptrude.core.io.terrain`.
+ */
+export abstract class PluginCoreIoTerrainApi {
+  constructor() {}
+
+  /**
+   * Whether the project has a site terrain.
+   *
+   * @examplePrompt Does this project have site terrain?
+   * @examplePrompt Is there a terrain imported?
+   * @examplePrompt Check if the site topography exists
+   * @examplePrompt Has a terrain been added yet?
+   *
+   * # Example
+   * ```ts
+   * if (!(await snaptrude.core.io.terrain.exists())) {
+   *   await snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)
+   * }
+   * ```
+   */
+  public abstract exists(): PluginApiReturn<boolean>
+
+  /**
+   * Resolve the project's terrain handle, or `null` if there is none. The same
+   * handle {@link core.io.import.terrain} returns — use it to obtain the handle
+   * without re-importing.
+   *
+   * @examplePrompt Get the terrain handle
+   * @examplePrompt Give me the site terrain
+   * @examplePrompt Fetch the current terrain
+   * @examplePrompt Return the topography handle if it exists
+   */
+  public abstract get(): PluginApiReturn<TerrainHandle | null>
+
+  /**
+   * Read the terrain's current vertical position (world Y, internal units).
+   * `null` if there is no terrain. Import places the terrain so its highest
+   * point sits at `y = 0`, so a never-shifted terrain reads a negative
+   * baseline, not `0`; each {@link PluginCoreIoTerrainApi.setDatum} shift
+   * moves this value.
+   *
+   * @examplePrompt What's the terrain's datum?
+   * @examplePrompt Read the current site elevation reference
+   * @examplePrompt Get the terrain vertical offset
+   * @examplePrompt How far has the datum been shifted?
+   */
+  public abstract getDatum(): PluginApiReturn<number | null>
+
+  /**
+   * Shift the terrain's **datum** — move the whole terrain vertically DOWN by
+   * `offset` (internal units) from its current position; pass a negative value to
+   * raise it. Undoable.
+   *
+   * **Relative and cumulative**, not absolute: `setDatum(5)` called twice shifts
+   * the terrain down by 10 total, it does not settle at a fixed level. Read the
+   * terrain's resulting vertical position (world Y — not the accumulated
+   * shift) back with {@link PluginCoreIoTerrainApi.getDatum}.
+   *
+   * @param offset - How far to shift the terrain down, in internal units
+   *   (negative raises it).
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   *
+   * @examplePrompt Shift the terrain datum down by 12
+   * @examplePrompt Lower the site terrain by 10
+   * @examplePrompt Raise the terrain a little
+   * @examplePrompt Nudge the terrain datum down
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.io.terrain.setDatum(12)   // shift terrain down by 12 (relative)
+   * ```
+   */
+  public abstract setDatum(offset: number): PluginApiReturn<void>
+
+  /**
+   * Delete the site terrain. Undoable.
+   *
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   *
+   * @examplePrompt Delete the site terrain
+   * @examplePrompt Remove the topography
+   * @examplePrompt Clear the imported site
+   * @examplePrompt Get rid of the terrain
+   */
+  public abstract delete(): PluginApiReturn<void>
+
+  /**
+   * The terrain cut/fill earthwork report — cut, fill, and net volumes — or
+   * `null` if there is no terrain.
+   *
+   * @examplePrompt What are the cut and fill volumes for the site?
+   * @examplePrompt Get the terrain earthwork report
+   * @examplePrompt How much cut and fill does the grading need?
+   * @examplePrompt Show the net volume of the terrain edits
+   *
+   * # Example
+   * ```ts
+   * const r = await snaptrude.core.io.terrain.getReport()
+   * if (r) console.log(`cut ${r.cutVolume}, fill ${r.fillVolume}, net ${r.netVolume}`)
+   * ```
+   */
+  public abstract getReport(): PluginApiReturn<TerrainReport | null>
+
+  /** Whether terrain elevation (DEM height) is on. `null` if no terrain. */
+  public abstract isElevationEnabled(): PluginApiReturn<boolean | null>
+  /**
+   * Turn terrain elevation (DEM height) ON — a real 3D topography surface. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Turn on terrain elevation
+   * @examplePrompt Enable the site heightmap
+   * @examplePrompt Make the terrain 3D
+   * @examplePrompt Show the topography relief
+   */
+  public abstract enableElevation(): PluginApiReturn<void>
+  /**
+   * Turn terrain elevation OFF — flatten to a plane. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Flatten the terrain
+   * @examplePrompt Turn off site elevation
+   * @examplePrompt Disable the heightmap
+   * @examplePrompt Make the terrain flat
+   */
+  public abstract disableElevation(): PluginApiReturn<void>
+
+  /** Whether satellite imagery is draped on the terrain. `null` if no terrain. */
+  public abstract isSatelliteEnabled(): PluginApiReturn<boolean | null>
+  /**
+   * Turn satellite imagery ON. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Show satellite imagery on the site
+   * @examplePrompt Enable the satellite texture
+   * @examplePrompt Turn on aerial imagery
+   * @examplePrompt Drape satellite over the terrain
+   */
+  public abstract enableSatellite(): PluginApiReturn<void>
+  /**
+   * Turn satellite imagery OFF. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Hide the satellite imagery
+   * @examplePrompt Turn off the aerial texture
+   * @examplePrompt Disable satellite on the site
+   * @examplePrompt Remove the satellite drape
+   */
+  public abstract disableSatellite(): PluginApiReturn<void>
+
+  /**
+   * Replace the terrain surface with a caller-supplied triangle mesh. Undoable
+   * (one step), and the replacement persists with the project. The returned
+   * promise resolves only after the surface is fully applied and recorded —
+   * it is safe to toggle terrain resolution or read the surface back the
+   * moment it resolves.
+   *
+   * `positions` is a flat `[x, y, z, …]` array in **world space** — the same
+   * frame `design.query.geometry.getTriangulatedMeshes` reads — so a
+   * read-modify-write round trip needs no conversion. `indices` is a flat
+   * triangle list into `positions` (three indices per triangle). A
+   * predominantly down-facing surface is flipped automatically (reported in
+   * `warnings`), and zero-area sliver triangles are tolerated and counted.
+   *
+   * **What survives the replacement:** the datum, geolocation, opacity, lock
+   * state, and the elevation/satellite toggles. The map/satellite texture is
+   * re-projected onto the new surface from above (best effort — alignment is
+   * approximate, reported in `warnings`). **What resets:** cut/fill history
+   * and the earthwork report — the replaced surface starts with a clean
+   * grading slate.
+   *
+   * Limits: at most 500,000 triangles and 500,000 vertices; every coordinate
+   * must be finite and within the scene bound.
+   *
+   * @param positions - Flat `[x, y, z, …]` world-space vertex positions.
+   * @param indices - Flat triangle list into `positions`.
+   * @param units - `"world"` (default): coordinates are raw internal units;
+   *   `"meters"`: coordinates are metres and are converted on the way in.
+   * @param options - Optional {@linkcode PluginTerrainReplaceMeshOptions}:
+   *   optimistic-concurrency expectations (`expectedTerrain`,
+   *   `expectedModelRevision`), `preserve` opt-outs, idempotent replay via
+   *   `clientMutationId`, and the `coordinateSpace`/`baseline` declarations.
+   * @throws if writes are disabled, there is no terrain (import one first),
+   *   the terrain is **locked**, the mesh fails validation (non-finite or
+   *   out-of-bound coordinates, bad indices, degenerate-only geometry, over
+   *   the size caps), `expectedTerrain` does not match the live terrain, or
+   *   `expectedModelRevision` is stale.
+   *
+   * @examplePrompt Replace the terrain with this surveyed mesh
+   * @examplePrompt Flatten a building pad into the site surface
+   * @examplePrompt Load a custom DEM surface onto the terrain
+   * @examplePrompt Regrade the terrain from these points
+   *
+   * # Example
+   * ```ts
+   * // Projects with no terrain yet: import first, then replace.
+   * if (!(await snaptrude.core.io.terrain.exists())) {
+   *   await snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)
+   * }
+   * const result = await snaptrude.core.io.terrain.replaceMesh(
+   *   positions, // [x0, y0, z0, x1, y1, z1, …] — world space
+   *   indices,   // [a0, b0, c0, a1, b1, c1, …]
+   *   "meters",
+   *   {
+   *     coordinateSpace: "world",
+   *     expectedTerrain: await snaptrude.core.io.terrain.get(),
+   *     baseline: "make-replacement-original",
+   *     preserve: { datum: true, geolocation: true, satellite: true, material: true },
+   *     clientMutationId: "survey-2026-08-05-r1",
+   *   },
+   * )
+   * // result.modelRevision — pass back as expectedModelRevision on the next call
+   * ```
+   */
+  public abstract replaceMesh(
+    positions: number[],
+    indices: number[],
+    units?: "world" | "meters",
+    options?: PluginTerrainReplaceMeshOptions,
+  ): PluginApiReturn<PluginTerrainReplaceMeshResult>
+
+  /** Read the terrain opacity, `0`..`1`, or `null` if no terrain. */
+  public abstract getOpacity(): PluginApiReturn<number | null>
+  /**
+   * Set the terrain opacity (`0` transparent .. `1` opaque). Undoable.
+   * @param opacity - Target opacity, `0`..`1`.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Fade the terrain to 50%
+   * @examplePrompt Make the site semi-transparent
+   * @examplePrompt Set terrain opacity to 0.3
+   * @examplePrompt Dim the topography
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.io.terrain.setOpacity(0.5)
+   * ```
+   */
+  public abstract setOpacity(opacity: number): PluginApiReturn<void>
+}
+
+/**
+ * Terrain cut/fill earthwork report. Volumes are in the **project's display
+ * volume unit** (what the UI shows), not internal units.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `cutVolume` | `number` | Total excavated (cut) volume |
+ * | `fillVolume` | `number` | Total added (fill) volume |
+ * | `netVolume` | `number` | Net volume (`fill − cut`) |
+ */
+export const TerrainReport = z.object({
+  cutVolume: z.number(),
+  fillVolume: z.number(),
+  netVolume: z.number(),
+})
+export type TerrainReport = z.infer<typeof TerrainReport>
+
+/**
+ * Result of {@link PluginCoreIoTerrainApi.replaceMesh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `terrain` | `TerrainHandle` | The terrain (unchanged singleton handle) |
+ * | `modelRevision` | `number` | Session-scoped terrain-mesh revision after this replace — pass back as `expectedModelRevision` for compare-and-swap semantics |
+ * | `vertexCount` | `number` | Vertices in the applied mesh |
+ * | `triangleCount` | `number` | Triangles in the applied mesh |
+ * | `warnings` | `string[]` | Non-fatal notes: winding flipped, sliver triangles, approximate texture re-projection |
+ */
+export type PluginTerrainReplaceMeshResult = {
+  terrain: TerrainHandle
+  modelRevision: number
+  vertexCount: number
+  triangleCount: number
+  warnings: string[]
+}
+
+/**
+ * Options for {@link PluginCoreIoTerrainApi.replaceMesh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `coordinateSpace` | `"world"`? | Declares the input frame. `world` is the only supported space (the same frame `getTriangulatedMeshes` reads) |
+ * | `expectedTerrain` | `TerrainHandle`? | Optimistic check: throws `HANDLE_INVALID` if the live terrain is not this handle (session-scoped — handles do not survive reloads) |
+ * | `expectedModelRevision` | `number`? | Optimistic check against the session terrain-mesh revision (starts at `0`, increments per successful `replaceMesh`; the result returns the new value). Stale → `PRECONDITION_FAILED` with the current revision in `details` |
+ * | `baseline` | `"make-replacement-original"`? | Declares replacement semantics. This is the only (and default) behavior: the replacement becomes the persisted surface; the app's terrain Reset restores the original map heightmap as the escape hatch |
+ * | `preserve` | object? | Opt-outs, all defaulting `true`. `datum: false` resets the terrain transform (authored coordinates become the local frame). `satellite: false` switches the drape off after the replace. `material: false` skips texture re-projection — the whole surface takes the ground material. `geolocation: false` is rejected (`VALIDATION`): geolocation is always preserved in this version |
+ * | `clientMutationId` | `string`? | Session-scoped idempotency: a repeated call with the same id returns the original result without re-executing |
+ */
+export const PluginTerrainReplaceMeshOptions = z
+  .object({
+    coordinateSpace: z.literal("world").optional(),
+    expectedTerrain: z.string().min(1).optional(),
+    expectedModelRevision: z.number().int().nonnegative().optional(),
+    baseline: z.literal("make-replacement-original").optional(),
+    preserve: z
+      .object({
+        datum: z.boolean().optional(),
+        geolocation: z.boolean().optional(),
+        satellite: z.boolean().optional(),
+        material: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    clientMutationId: z.string().min(1).max(128).optional(),
+  })
+  .strict()
+export type PluginTerrainReplaceMeshOptions = z.infer<typeof PluginTerrainReplaceMeshOptions>
+
+/**
+ * Arguments for {@link PluginCoreIoTerrainApi.replaceMesh}. The caps are the
+ * plugin surface's explicit payload ceiling: 500k vertices / 500k triangles.
+ */
+export const PluginTerrainReplaceMeshArgs = z.object({
+  positions: z
+    .array(z.number().finite())
+    .min(9)
+    .max(1_500_000)
+    .refine((a) => a.length % 3 === 0, {
+      message: "positions must be a flat [x, y, z, …] array (length a multiple of 3)",
+    }),
+  indices: z
+    .array(z.number().int().nonnegative())
+    .min(3)
+    .max(1_500_000)
+    .refine((a) => a.length % 3 === 0, {
+      message: "indices must be a flat triangle list (length a multiple of 3)",
+    }),
+  units: z.enum(["world", "meters"]).optional(),
+  options: PluginTerrainReplaceMeshOptions.optional(),
+})
+export type PluginTerrainReplaceMeshArgs = z.infer<typeof PluginTerrainReplaceMeshArgs>
+
+/** Arguments for {@link PluginCoreIoTerrainApi.setDatum}. */
+export const PluginTerrainSetDatumArgs = z.object({ offset: z.number().finite() })
+export type PluginTerrainSetDatumArgs = z.infer<typeof PluginTerrainSetDatumArgs>
+
+/** Arguments for {@link PluginCoreIoTerrainApi.setOpacity}. */
+export const PluginTerrainSetOpacityArgs = z.object({ opacity: z.number().min(0).max(1) })
+export type PluginTerrainSetOpacityArgs = z.infer<typeof PluginTerrainSetOpacityArgs>