@snaptrude/plugin-core 0.8.0 → 0.9.1

package/src/api/core/geom/create/index.ts

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
-import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle } from "../../../../handles"
+import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, Vec3Components } from "../../../../handles"
 
 /**
  * Curve creation — construct new geometric curves from point handles (all-handle
@@ -177,6 +177,260 @@ export abstract class PluginGeomCreateApi {
     outer: ProfileHandle,
     holes?: ProfileHandle[],
   ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Create a closed solid **B-rep** from explicit face loops. Host API call —
+   * returns a {@linkcode BrepHandle}. Faces are plain arrays of `{x, y, z}`
+   * point components, NOT point handles (bulk-data precedent:
+   * `design.query.geometry.getTriangulatedMeshes`), in raw Babylon units.
+   *
+   * Each face is one planar loop of at least 3 points; at least 4 faces are
+   * required. Loops may be authored in any consistent winding — the host
+   * validates edge coherence (every edge shared by exactly two faces, in
+   * opposite directions) and fixes the global orientation so faces point
+   * outward. Faces must be planar and the solid must be closed; holes in faces
+   * are not supported (v1).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param faces Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if a face is degenerate or non-planar, an edge is not shared by
+   *   exactly two faces (open shell, non-manifold, or inconsistent winding), or
+   *   the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from faces
+   * @examplePrompt Build a custom solid from a set of faces
+   * @examplePrompt Make a pyramid from triangular faces
+   *
+   * # Example
+   * ```ts
+   * // A pyramid: square base + 4 triangular sides
+   * const apex = { x: 0, y: 4, z: 0 }
+   * const a = { x: -2, y: 0, z: -2 }
+   * const b = { x: 2, y: 0, z: -2 }
+   * const c = { x: 2, y: 0, z: 2 }
+   * const d = { x: -2, y: 0, z: 2 }
+   * const brep = await snaptrude.core.geom.create.brepFromFaces([
+   *   [a, d, c, b], // base
+   *   [a, b, apex],
+   *   [b, c, apex],
+   *   [c, d, apex],
+   *   [d, a, apex],
+   * ])
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 5
+   * ```
+   */
+  public abstract brepFromFaces(faces: Vec3Components[][]): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by extruding a contour along a direction.
+   * Host API call — returns a {@linkcode BrepHandle}. The direction is
+   * normalised by the host, so `amount` is the extrusion distance in raw
+   * Babylon units (negative extrudes the opposite way). The contour is copied —
+   * the input handle is never mutated. Holes and arc/circle profiles extrude
+   * natively (a circle profile yields a cylinder).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param contour The cross-section to extrude (outer profile + optional holes)
+   * @param direction Extrusion direction as plain `{x, y, z}` components (non-zero, normalised by the host)
+   * @param amount Extrusion distance (non-zero; negative extrudes opposite to `direction`)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the extrusion is degenerate (zero amount, zero direction, or a
+   *   direction lying in the contour plane) or the contour cannot be extruded
+   *   into a valid solid
+   *
+   * @examplePrompt Extrude this profile 3 metres up
+   * @examplePrompt Make a solid by extruding this outline
+   * @examplePrompt Create a cylinder from a circle profile
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromExtrusion(
+    contour: ContourHandle,
+    direction: Vec3Components,
+    amount: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by lofting between a bottom and a top
+   * contour. Host API call — returns a {@linkcode BrepHandle}. Both contours
+   * must have the same number of edges (and matching hole counts); side faces
+   * connect corresponding edges by authored index. Corresponding edges must
+   * stay coplanar — a twisted loft would produce non-planar side faces and is
+   * rejected. The contours are copied — the input handles are never mutated.
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param bottomContour The bottom cross-section
+   * @param topContour The top cross-section (same edge and hole counts as the bottom)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the contours are coincident, their edge or hole counts differ,
+   *   a side face between corresponding edges would be non-planar, or the
+   *   contours cannot be lofted into a valid solid
+   *
+   * @examplePrompt Make a tapered tower from these two outlines
+   * @examplePrompt Loft between a large base and a smaller top
+   * @examplePrompt Create a frustum from two squares
+   *
+   * # Example
+   * ```ts
+   * // A square frustum: 4m base lofted to a 2m top, 3m up
+   * const base = await snaptrude.core.geom.create.profileRect(4, 4)
+   * const top = await snaptrude.core.geom.create.profileRect(2, 2, await snaptrude.core.math.vec3.new(0, 3, 0))
+   * const brep = await snaptrude.core.geom.create.brepFromLoft(
+   *   await snaptrude.core.geom.create.contourFromProfile(base),
+   *   await snaptrude.core.geom.create.contourFromProfile(top),
+   * )
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromLoft(
+    bottomContour: ContourHandle,
+    topContour: ContourHandle,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** from indexed mesh data: a vertex position
+   * array plus face loops of indices into it. Host API call — returns a
+   * {@linkcode BrepHandle}. The indexed form of
+   * {@linkcode PluginGeomCreateApi.brepFromFaces} — same validation (planar
+   * faces, closed manifold solid, every edge shared by exactly two faces) after
+   * the indices are expanded to point loops.
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param positions Vertex positions as plain `{x, y, z}` components (≥4)
+   * @param faces Face loops — each an ordered array of indices into `positions` (≥3 indices per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if an index is not an integer within `positions` bounds, a face is
+   *   degenerate or non-planar, or the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from mesh vertices and indices
+   * @examplePrompt Turn this indexed mesh into a solid
+   * @examplePrompt Build a solid from vertex positions and face indices
+   *
+   * # Example
+   * ```ts
+   * // A tetrahedron from 4 vertices and 4 triangular faces
+   * const positions = [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 4, y: 0, z: 0 },
+   *   { x: 2, y: 0, z: 4 },
+   *   { x: 2, y: 3, z: 1.5 },
+   * ]
+   * const brep = await snaptrude.core.geom.create.brepFromMesh(positions, [
+   *   [0, 2, 1], // base
+   *   [0, 1, 3],
+   *   [1, 2, 3],
+   *   [2, 0, 3],
+   * ])
+   * const vertexCount = await snaptrude.core.geom.query.brep.getVertexCount(brep) // 4
+   * ```
+   */
+  public abstract brepFromMesh(
+    positions: Vec3Components[],
+    faces: number[][],
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **union** of two breps
+   * (`a ∪ b`). Host API call — returns a new {@linkcode BrepHandle}. Inputs are
+   * read-only and may be authored breps (any `core.geom.create` brep
+   * constructor) or scene-derived breps from `design.query.geometry.getBrep`;
+   * coordinates are combined as-is, so both inputs must share a frame. The
+   * result must be a single solid — disjoint inputs are rejected.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The union as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap or touch (the union would be disjoint
+   *   solids) or the result cannot be built as a valid single solid
+   *
+   * @examplePrompt Union these two solids
+   * @examplePrompt Merge these breps into one mass
+   * @examplePrompt Combine the tower and the podium into a single solid
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.geom.create.brepFromExtrusion(baseContour, { x: 0, y: 1, z: 0 }, 3)
+   * const b = await snaptrude.core.geom.create.brepFromExtrusion(overlappingContour, { x: 0, y: 1, z: 0 }, 5)
+   * const merged = await snaptrude.core.geom.create.brepFromUnion(a, b)
+   * ```
+   */
+  public abstract brepFromUnion(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **subtraction** of two
+   * breps: **`a` minus `b`** — `b` is cut away from `a`. Host API call —
+   * returns a new {@linkcode BrepHandle}. Argument order matters:
+   * `brepFromSubtraction(a, b)` removes `b`'s volume from `a`. Inputs are
+   * read-only and may be authored or scene-derived breps (see
+   * {@linkcode PluginGeomCreateApi.brepFromUnion}); coordinates are combined
+   * as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a The solid to subtract from
+   * @param b The solid to remove from `a`
+   * @returns `a` minus `b` as a new {@linkcode BrepHandle}
+   * @throws if `b` consumes `a` entirely (empty result), the result splits into
+   *   disjoint solids, or it cannot be built as a valid single solid
+   *
+   * @examplePrompt Subtract the courtyard from the building mass
+   * @examplePrompt Cut this solid out of that one
+   * @examplePrompt Punch a hole through the slab with this box
+   *
+   * # Example
+   * ```ts
+   * // buildingBrep minus courtyardBrep — order matters
+   * const carved = await snaptrude.core.geom.create.brepFromSubtraction(buildingBrep, courtyardBrep)
+   * ```
+   */
+  public abstract brepFromSubtraction(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **intersection** of two
+   * breps (`a ∩ b` — the shared volume only). Host API call — returns a new
+   * {@linkcode BrepHandle}. Inputs are read-only and may be authored or
+   * scene-derived breps (see {@linkcode PluginGeomCreateApi.brepFromUnion});
+   * coordinates are combined as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The shared volume as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap (empty intersection), the result
+   *   splits into disjoint solids, or it cannot be built as a valid single
+   *   solid
+   *
+   * @examplePrompt Keep only the overlap of these two solids
+   * @examplePrompt Intersect these two masses
+   * @examplePrompt Clip the tower to the zoning envelope
+   *
+   * # Example
+   * ```ts
+   * const overlap = await snaptrude.core.geom.create.brepFromIntersection(towerBrep, envelopeBrep)
+   * ```
+   */
+  public abstract brepFromIntersection(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
 }
 
 /**
@@ -291,3 +545,92 @@ export const PluginGeomCreateContourFromProfilesArgs = z.object({
 export type PluginGeomCreateContourFromProfilesArgs = z.infer<
   typeof PluginGeomCreateContourFromProfilesArgs
 >
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromFaces}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `faces` | {@linkcode Vec3Components}`[][]` | Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromFacesArgs = z.object({
+  faces: z.array(z.array(Vec3Components).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromFacesArgs = z.infer<
+  typeof PluginGeomCreateBrepFromFacesArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromExtrusion}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The cross-section to extrude |
+ * | `direction` | {@linkcode Vec3Components} | Extrusion direction (non-zero, finite components) |
+ * | `amount` | `number` | Extrusion distance (finite, non-zero) |
+ */
+export const PluginGeomCreateBrepFromExtrusionArgs = z.object({
+  contour: ContourHandle,
+  direction: z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    z: z.number().finite(),
+  }),
+  amount: z
+    .number()
+    .finite()
+    .refine((value) => value !== 0, { message: "amount must be non-zero" }),
+})
+
+export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
+  typeof PluginGeomCreateBrepFromExtrusionArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromLoft}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
+ * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
+ */
+export const PluginGeomCreateBrepFromLoftArgs = z.object({
+  bottomContour: ContourHandle,
+  topContour: ContourHandle,
+})
+
+export type PluginGeomCreateBrepFromLoftArgs = z.infer<typeof PluginGeomCreateBrepFromLoftArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromMesh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `positions` | {@linkcode Vec3Components}`[]` | Vertex positions (≥4) |
+ * | `faces` | `number[][]` | Face loops of indices into `positions` (≥3 indices per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromMeshArgs = z.object({
+  positions: z.array(Vec3Components).min(4),
+  faces: z.array(z.array(z.number()).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromMeshArgs = z.infer<typeof PluginGeomCreateBrepFromMeshArgs>
+
+/**
+ * Arguments for the brep boolean constructors —
+ * {@linkcode PluginGeomCreateApi.brepFromUnion},
+ * {@linkcode PluginGeomCreateApi.brepFromSubtraction} (`a` minus `b`), and
+ * {@linkcode PluginGeomCreateApi.brepFromIntersection}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `a` | {@linkcode BrepHandle} | First solid (the subtraction target) |
+ * | `b` | {@linkcode BrepHandle} | Second solid (the subtraction tool) |
+ */
+export const PluginGeomCreateBrepBooleanArgs = z.object({
+  a: BrepHandle,
+  b: BrepHandle,
+})
+
+export type PluginGeomCreateBrepBooleanArgs = z.infer<typeof PluginGeomCreateBrepBooleanArgs>

package/src/api/core/index.ts

@@ -13,6 +13,8 @@ import { PluginCoreIoApi } from "./io"
 import { PluginCoreHandlesApi } from "./handles"
 import { PluginCoreProposalsApi } from "./proposals"
 import { PluginCameraApi } from "./camera"
+import { PluginCoreStoreysApi } from "./storeys"
+import { PluginCoreModeApi } from "./mode"
 import { PluginUserApi } from "./user"
 
 /**
@@ -29,6 +31,7 @@ import { PluginUserApi } from "./user"
  * - {@linkcode PluginCoreApi.comment} — Comments: create, edit, resolve, tag, list
  * - {@linkcode PluginCoreApi.groups} — Read & edit the group hierarchy
  * - {@linkcode PluginCoreApi.buildings} — Read & edit buildings and their storeys
+ * - {@linkcode PluginCoreApi.storeys} — Create, read & edit storeys (floors)
  * - {@linkcode PluginCoreApi.layers} — Read & toggle storey drawing/reference layers
  * - {@linkcode PluginCoreApi.tags} — Tag catalog + assignment
  * - {@linkcode PluginCoreApi.io} — Import files (image/pdf/cad/model/terrain), poll jobs, manage underlays
@@ -58,6 +61,10 @@ export abstract class PluginCoreApi {
   public abstract groups: PluginCoreGroupsApi
   /** Buildings — read & edit buildings and their storeys. See {@linkcode PluginCoreBuildingsApi}. */
   public abstract buildings: PluginCoreBuildingsApi
+  /** Storeys — create, read & edit storeys (floors). See {@linkcode PluginCoreStoreysApi}. */
+  public abstract storeys: PluginCoreStoreysApi
+  /** Application mode — read & switch the editor's top-bar mode. See {@linkcode PluginCoreModeApi}. */
+  public abstract mode: PluginCoreModeApi
   /** Layers — read & toggle storey drawing/reference layers. See {@linkcode PluginCoreLayersApi}. */
   public abstract layers: PluginCoreLayersApi
   /** Tags — tag catalog + assignment. See {@linkcode PluginCoreTagsApi}. */
@@ -83,6 +90,8 @@ export * from "./project"
 export * from "./comment"
 export * from "./groups"
 export * from "./buildings"
+export * from "./storeys"
+export * from "./mode"
 export * from "./layers"
 export * from "./tags"
 export * from "./io"

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

@@ -39,7 +39,9 @@ export type ExportedFile = z.infer<typeof ExportedFile>
  *
  * `core.io.export.model` hands you the file bytes as base64 — no download
  * dialog opens; the plugin decides what to do with the result (save it, POST
- * it, diff it). Four formats:
+ * it, diff it). For a different export intent, see `presentation.export`
+ * (Present-mode layout sheets to PDF/PNG/JPG) and `program.spreadsheet.export`
+ * (the area-program / takeoff workbook). Four formats:
  *
  * - `"glb"` — binary glTF (`model/gltf-binary`); geometry + materials,
  *   serialized in the browser (nothing is uploaded).

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

@@ -55,6 +55,9 @@ export abstract class PluginCoreIoImportApi {
    * Supported formats: PNG, JPG/JPEG, BMP. The image is placed on the target
    * storey's "Image" layer at ~50% opacity by default.
    *
+   * To place the image on a **Present-mode sheet** instead of the scene, use
+   * `presentation.import.image`.
+   *
    * The plane is placed at the storey origin (the engine's import placement);
    * there is no placement parameter — calibrate size with
    * {@link PluginCoreIoUnderlayApi.setScale} after import.
@@ -308,6 +311,40 @@ export abstract class PluginCoreIoImportApi {
     neighborhood?: boolean,
     parcels?: boolean,
   ): PluginApiReturn<TerrainHandle>
+
+  /**
+   * Import an **EPW weather file** into the project's weather catalog.
+   *
+   * Uploads an EnergyPlus Weather (`.epw`) file and registers it as the
+   * project's site weather, returning its catalog `weatherFileId` — the same id
+   * {@link PluginAnalysisWeatherApi.getSeries}, `program.site.getWeather`, and a
+   * daylight run's provenance report. Uploading a user file makes the site's
+   * `selectionMethod` `"user-upload"`, overriding nearest-station resolution.
+   *
+   * **Mutating**: this writes project state and is subject to the plugin
+   * write-gate — it throws when plugin writes are disabled. Unlike the file
+   * underlay/model importers it returns no scene handle (a weather file is not
+   * a scene object), only the catalog `{ weatherFileId, label }`.
+   *
+   * @param source - The `.epw` file to import: an `https://` URL or a `data:` URL.
+   * @returns A {@linkcode PluginImportEpwResult} — the catalog `weatherFileId`
+   *   and a human-readable `label` (the station/file name).
+   * @throws if writes are disabled, the source can't be loaded, or the file is
+   *   not a valid EPW.
+   *
+   * @examplePrompt Import this EPW weather file for the site
+   * @examplePrompt Upload a custom weather file for the daylight analysis
+   * @examplePrompt Use this .epw as the project's weather source
+   *
+   * # Example
+   * ```ts
+   * const { weatherFileId, label } = await snaptrude.core.io.import.epw(
+   *   "https://example.com/Chicago-OHare.epw",
+   * )
+   * console.log(`Weather set to ${label} (${weatherFileId})`)
+   * ```
+   */
+  public abstract epw(source: string): PluginApiReturn<PluginImportEpwResult>
 }
 
 /**
@@ -430,3 +467,30 @@ export const PluginImportTerrainArgs = z.object({
   parcels: z.boolean().optional(),
 })
 export type PluginImportTerrainArgs = z.infer<typeof PluginImportTerrainArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.epw}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | EPW `https://` URL or `data:` URL |
+ */
+export const PluginImportEpwArgs = z.object({
+  source: ImportSource,
+})
+export type PluginImportEpwArgs = z.infer<typeof PluginImportEpwArgs>
+
+/**
+ * Result of {@link PluginCoreIoImportApi.epw} — the imported weather file's
+ * catalog entry.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `analysis.weather`'s `weatherFileId`) |
+ * | `label` | `string` | Human-readable name (station / file name) |
+ */
+export const PluginImportEpwResult = z.object({
+  weatherFileId: z.string(),
+  label: z.string(),
+})
+export type PluginImportEpwResult = z.infer<typeof PluginImportEpwResult>

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

@@ -168,6 +168,74 @@ export abstract class PluginCoreIoTerrainApi {
    */
   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.
+   *
+   * `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>
   /**
@@ -205,6 +273,81 @@ export const TerrainReport = z.object({
 })
 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>