@snaptrude/plugin-core 0.9.0 → 0.9.2

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

@@ -168,6 +168,77 @@ 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. 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>
   /**
@@ -205,6 +276,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>

package/src/api/presentation/annotate.ts

@@ -26,12 +26,22 @@ export abstract class PluginPresentationAnnotateApi {
    * Creates a text shape on the given sheet and returns the id of the created
    * canvas shape. Requires Present mode to be open.
    *
+   * Typography is optional: `fontFamily` takes a system family or any Google
+   * Font (loaded automatically, the same loader as the Present text panel);
+   * `fontWeight` is a numeric weight string like `"400"` or `"700"`,
+   * optionally with the `-italic` suffix (e.g. `"700-italic"`) — the Present
+   * text panel's value domain; a weight the chosen font does not provide
+   * falls back to regular. `fontSizePx` sets an exact pixel size, overriding
+   * the `size` preset when both are given (`size` alone keeps working).
+   *
    * @param sheetId - The sheet to annotate.
    * @param text - The label text.
    * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
    *   top-left, in canvas units — defaults to the sheet's top-left corner),
-   *   `size` (`"s" | "m" | "l" | "xl"`, default `"m"`), and `color` (a named
-   *   palette color, default `"black"`).
+   *   `size` (`"s" | "m" | "l" | "xl"`, default `"m"`), `color` (a named
+   *   palette color, default `"black"`), and typography: `fontFamily`,
+   *   `fontWeight` (numeric string, `-italic` suffix allowed), `fontSizePx`
+   *   (positive px size overriding the `size` preset).
    * @returns A {@linkcode PluginPresentationAnnotateTextResult} with the created
    *   `shapeId`.
    * @throws If Present mode is not open or the sheet id is invalid.
@@ -57,6 +67,9 @@ export abstract class PluginPresentationAnnotateApi {
       position?: { x: number; y: number }
       size?: PluginAnnotateTextSize
       color?: PluginAnnotateTextColor
+      fontFamily?: string
+      fontWeight?: string
+      fontSizePx?: number
     },
   ): PluginApiReturn<PluginPresentationAnnotateTextResult>
 
@@ -218,6 +231,9 @@ export type PluginAnnotateTextColor = z.infer<typeof PluginAnnotateTextColor>
  * | `position` | `{ x: number; y: number } \| undefined` | Where to place it (relative to the sheet) |
  * | `size` | {@linkcode PluginAnnotateTextSize}` \| undefined` | Text size preset |
  * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Text color |
+ * | `fontFamily` | `string \| undefined` | System family or any Google Font (loaded automatically) |
+ * | `fontWeight` | `string \| undefined` | Numeric weight like `"400"`/`"700"`, `-italic` suffix allowed |
+ * | `fontSizePx` | `number \| undefined` | Exact px size (overrides the `size` preset) |
  */
 export const PluginPresentationAnnotateTextArgs = z.object({
   sheetId: z.string(),
@@ -225,6 +241,15 @@ export const PluginPresentationAnnotateTextArgs = z.object({
   position: z.object({ x: z.number(), y: z.number() }).optional(),
   size: PluginAnnotateTextSize.optional(),
   color: PluginAnnotateTextColor.optional(),
+  fontFamily: z.string().min(1).optional(),
+  fontWeight: z
+    .string()
+    .regex(
+      /^\d{3}(-italic)?$/,
+      'fontWeight must be a numeric string like "400" or "700", optionally with the "-italic" suffix',
+    )
+    .optional(),
+  fontSizePx: z.number().finite().positive().optional(),
 })
 export type PluginPresentationAnnotateTextArgs = z.infer<
   typeof PluginPresentationAnnotateTextArgs

package/src/api/presentation/diagrams.ts

@@ -8,8 +8,10 @@ import { PluginApiReturn } from "../../types"
  * {@linkcode PluginPresentationDiagramsApi.generateProgram} runs the Present-mode
  * **Program** action: it reads the project's spaces and departments and creates
  * new layout sheets holding the generated diagram graphics.
+ * {@linkcode PluginPresentationDiagramsApi.generateSite} runs the site-diagram
+ * flow (location / streetview / climate sheets from the map terrain).
  * {@linkcode PluginPresentationDiagramsApi.place} drops ready diagram images (by
- * URL) onto an existing sheet and returns the created canvas shape ids. Both
+ * URL) onto an existing sheet and returns the created canvas shape ids. All
  * require Present mode to be open. Adjacency data itself is read and computed via
  * `program.adjacency` (see {@linkcode PluginProgramAdjacencyApi}).
  *
@@ -50,6 +52,44 @@ export abstract class PluginPresentationDiagramsApi {
    */
   public abstract generateProgram(): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
 
+  /**
+   * Generate the site diagrams (location, streetview, climate) for the
+   * current model, creating new layout sheets.
+   *
+   * Runs the same auto-generation as the Present-mode site-diagram flow:
+   * each requested type renders its diagram from the project's map terrain
+   * and creates a new sheet holding it. `options.types` selects which
+   * diagrams to generate (default: all three). Generation is tracked
+   * per-proposal — a type whose diagram already exists for the active
+   * proposal is **skipped, not duplicated** (the same semantics as the
+   * mount-time flow; existing site-diagram sheets are never replaced), so
+   * `sheetIds` contains only the sheets created by this call and can be
+   * empty when everything already exists. Requires Present mode to be open
+   * and the project to have a map terrain to generate from.
+   *
+   * @param options - Optional `types` — which site diagrams to generate
+   *   (default: `["location", "streetview", "climate"]`).
+   * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
+   *   `sheetIds` of the sheets created by this call (empty when all requested
+   *   types were already generated).
+   * @throws If Present mode is not open or the project has no map terrain to
+   *   generate from.
+   *
+   * @examplePrompt Generate the site diagrams for this project
+   * @examplePrompt Create the location, streetview and climate sheets
+   * @examplePrompt Add a climate diagram sheet to the presentation
+   *
+   * # Example
+   * ```ts
+   * const { sheetIds } = await snaptrude.presentation.diagrams.generateSite({
+   *   types: ["location", "climate"],
+   * })
+   * ```
+   */
+  public abstract generateSite(options?: {
+    types?: PluginPresentationSiteDiagramType[]
+  }): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
+
   /**
    * Place diagram images onto a sheet.
    *
@@ -114,8 +154,33 @@ export type PluginPresentationDiagramsPlaceResult = z.infer<
   typeof PluginPresentationDiagramsPlaceResult
 >
 
+/** A site diagram type — the three diagrams of the Present-mode site flow. */
+export const PluginPresentationSiteDiagramType = z.enum([
+  "location",
+  "streetview",
+  "climate",
+])
+export type PluginPresentationSiteDiagramType = z.infer<
+  typeof PluginPresentationSiteDiagramType
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationDiagramsApi.generateSite}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `types` | {@linkcode PluginPresentationSiteDiagramType}`[] \| undefined` | Which site diagrams to generate (default: all three) |
+ */
+export const PluginPresentationDiagramsGenerateSiteArgs = z.object({
+  types: z.array(PluginPresentationSiteDiagramType).min(1).optional(),
+})
+export type PluginPresentationDiagramsGenerateSiteArgs = z.infer<
+  typeof PluginPresentationDiagramsGenerateSiteArgs
+>
+
 /**
- * Result of {@linkcode PluginPresentationDiagramsApi.generateProgram}.
+ * Result of {@linkcode PluginPresentationDiagramsApi.generateProgram} and
+ * {@linkcode PluginPresentationDiagramsApi.generateSite}.
  *
  * | Property | Type | Description |
  * |---|---|---|

package/src/api/presentation/index.ts

@@ -6,6 +6,8 @@ import { PluginPresentationPlacedViewsApi } from "./placedViews"
 import { PluginPresentationDiagramsApi } from "./diagrams"
 import { PluginPresentationAnnotateApi } from "./annotate"
 import { PluginPresentationShapesApi } from "./shapes"
+import { PluginPresentationTablesApi } from "./tables"
+import { PluginPresentationSlideshowApi } from "./slideshow"
 import { PluginPresentationImportApi } from "./import"
 import {
   PluginPresentationExportResult,
@@ -26,7 +28,9 @@ import {
  * - {@linkcode PluginPresentationApi.views} — Saved 2D/3D views (list, get, capture, activate, create)
  * - {@linkcode PluginPresentationApi.sheets} — Layout sheets (list, get, create, place views)
  * - {@linkcode PluginPresentationApi.placedViews} — Views already placed on the canvas (move, scale, crop)
- * - {@linkcode PluginPresentationApi.diagrams} — Place program/adjacency/site diagram images on sheets
+ * - {@linkcode PluginPresentationApi.diagrams} — Generate program/site diagram sheets, place diagram images
+ * - {@linkcode PluginPresentationApi.tables} — Place data tables on sheets
+ * - {@linkcode PluginPresentationApi.slideshow} — Run the Present-mode slideshow
  * - {@linkcode PluginPresentationApi.import} — Import reference images/PDFs onto the canvas
  * - {@linkcode PluginPresentationApi.aiInspiration} — Present-mode AI image/video generation
  *
@@ -45,6 +49,10 @@ export abstract class PluginPresentationApi {
   public abstract annotate: PluginPresentationAnnotateApi
   /** Plugin-owned keyed shapes — upsert/remove/list so reruns update instead of duplicating. See {@linkcode PluginPresentationShapesApi}. */
   public abstract shapes: PluginPresentationShapesApi
+  /** Data tables on Present sheets — place string rows as a table shape. See {@linkcode PluginPresentationTablesApi}. */
+  public abstract tables: PluginPresentationTablesApi
+  /** The Present-mode slideshow — start/stop/getState. See {@linkcode PluginPresentationSlideshowApi}. */
+  public abstract slideshow: PluginPresentationSlideshowApi
   /** Import reference images/PDFs onto the Present canvas. See {@linkcode PluginPresentationImportApi}. */
   public abstract import: PluginPresentationImportApi
   /**
@@ -97,6 +105,8 @@ export * from "./placedViews"
 export * from "./diagrams"
 export * from "./annotate"
 export * from "./shapes"
+export * from "./tables"
+export * from "./slideshow"
 export * from "./import"
 export * from "./aiInspiration"
 export * from "./export"