@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

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

@@ -0,0 +1,71 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { CadJsonInput } from "../import"
+
+/**
+ * Import queries — read metadata about a source **before** importing it.
+ *
+ * These reads let a plugin discover a source's shape before importing it:
+ * how many pages a PDF has (for `import.pdf`'s `page`), and which CAD layers a
+ * drawing defines (imports always bring in every layer — there is no filter —
+ * but the names tell you what the drawing contains).
+ *
+ * Accessed via `snaptrude.core.io.query`.
+ */
+export abstract class PluginCoreIoQueryApi {
+  constructor() {}
+
+  /**
+   * Count the pages of a PDF without importing it. `null` if the source can't be
+   * read as a PDF.
+   *
+   * @param source - The PDF: an `https://` URL or a `data:` URL.
+   * @returns the page count, or `null`.
+   *
+   * @examplePrompt How many pages does this PDF have?
+   * @examplePrompt Count the pages in the drawing set before importing
+   * @examplePrompt Get the PDF page count
+   * @examplePrompt Is this a multi-page PDF, and how many?
+   *
+   * # Example
+   * ```ts
+   * const pages = await snaptrude.core.io.query.getPdfPageCount(url)
+   * for (let p = 1; p <= (pages ?? 0); p++) {
+   *   await snaptrude.core.io.import.pdf(url, p, p) // one page per storey
+   * }
+   * ```
+   */
+  public abstract getPdfPageCount(source: string): PluginApiReturn<number | null>
+
+  /**
+   * List the distinct CAD layer names tagged on a parsed CAD JSON's entities.
+   * Read-only inspection: imports always bring in **every** layer (there is no
+   * layer filter on {@link core.io.import.dwg} / {@link core.io.import.cadJson}) —
+   * use the names to decide whether to import at all, or what to tell the user.
+   *
+   * @param cad - Parsed CAD JSON (same shape `import.cadJson` accepts).
+   * @returns the layer names (empty array if none).
+   *
+   * @examplePrompt What CAD layers are in this drawing?
+   * @examplePrompt List the layers before importing the CAD
+   * @examplePrompt Show the DWG layer names so I can pick which to import
+   * @examplePrompt Enumerate the CAD JSON layers
+   *
+   * # Example
+   * ```ts
+   * const layers = await snaptrude.core.io.query.listCadLayers(cad)
+   * if (layers.some((l) => l.toUpperCase().includes("WALL"))) {
+   *   await snaptrude.core.io.import.cadJson(cad, 1) // all layers import together
+   * }
+   * ```
+   */
+  public abstract listCadLayers(cad: CadJsonInput): PluginApiReturn<string[]>
+}
+
+/** Arguments for {@link PluginCoreIoQueryApi.getPdfPageCount}. */
+export const PluginQueryPdfPageCountArgs = z.object({ source: z.string().min(1) })
+export type PluginQueryPdfPageCountArgs = z.infer<typeof PluginQueryPdfPageCountArgs>
+
+/** Arguments for {@link PluginCoreIoQueryApi.listCadLayers}. */
+export const PluginQueryCadLayersArgs = z.object({ cad: CadJsonInput })
+export type PluginQueryCadLayersArgs = z.infer<typeof PluginQueryCadLayersArgs>

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

@@ -0,0 +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>