@snaptrude/plugin-core 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @snaptrude/plugin-core
 
+## 0.9.1
+
+### Patch Changes
+
+- Plugin API 0.9.1 — strictly additive: the terrain mesh lane and the Present-mode styling/canvas lane. No signatures changed, no behavior of existing methods changed; deployed plugins are unaffected (`versionGate` compares major.minor only).
+  - **`core.io.terrain.replaceMesh(positions, indices, units?, options?)`** — replace the site terrain surface with a caller-supplied triangle mesh. World-space flat arrays (the `getTriangulatedMeshes` frame, so read-modify-write round-trips); `units: "meters"` converts on the way in. Validated before any engine call (finiteness, index bounds, degenerate topology, scene-bound extents, **500k vertex/triangle caps** — the surface's first explicit payload ceiling); a predominantly down-facing mesh is auto-flipped with a warning. Datum, geolocation, opacity, lock state and the elevation/satellite toggles survive; the map texture is re-projected best-effort; cut/fill history resets by contract. One undo step restores the prior surface exactly (buffers, UVs, submesh layout, cut/fill data, volumes). The replacement **persists with the project**: the mesh uploads to bucket storage and reload applies it instead of the heightmap build. The optional `options` mirrors the requester's contract: `coordinateSpace`, `expectedTerrain` (session optimistic check), `expectedModelRevision` (session terrain-mesh revision, returned as `modelRevision` in the result), `baseline: "make-replacement-original"`, `preserve` opt-outs (`datum`/`satellite`/`material` have real opt-out behavior; `geolocation: false` rejects — always preserved), and `clientMutationId` (session-scoped idempotent replay). For projects without terrain, compose `core.io.import.terrain` + `replaceMesh` (a separate `createFromMesh` was deliberately not added).
+  - **`presentation.placedViews` — per-instance styling** (`getStyles` / `updateStyles` / `resetStyles` / `updateFontStyles`): the Present sidebar's full per-category styling surface — 7 line dash styles, line color, dash-length multiplier, **cut vs projection line weights in mm** (plus tree/parking weights), fills (`department`/`texture`/`monochrome`/`tag:<tagCategoryId>`), per-category opacity, category hide (cascades to labels), view-style restyles (block/rounded/bubble with radius + inset), Topography map/building sub-controls, and Text-tab typography per label type (font family incl. Google Fonts, weight, italic, px size, visible label types). Writes are host-validated (typed VALIDATION with the supported-setting list), land as **one undo step per call**, re-render immediately, and fan out across an auto-diagram sheet's set. `getStyles` returns fully-resolved values plus each category's supported setting ids.
+  - **`presentation.placedViews` — labels** (`listLabels` / `moveLabel` / `setLabelHidden`): a placed view's generated labels (space names, departments, areas, dimensions) as addressable shapes — read text/category/position, reposition them, hide/show individually (independent of category-level hides).
+  - **`presentation.placedViews` — generic canvas shapes** (`listShapes` / `getShape` / `moveShape` / `resizeShape` / `deleteShapes` / `setOpacity` / `setMask`): every top-level Present-canvas shape — AI-generated outputs, placed diagram images, plugin shapes, annotations — addressable by id with an `origin` classification. Previously `aiInspiration.generate` and `diagrams.place` returned shape ids nothing could act on. `deleteShapes` is atomic (any rejected id deletes nothing), protects sheets (use `sheets.delete`) and user-drawn annotations, and closes the placed-view no-delete gap. `setOpacity` is the whole-shape slider; `setMask` toggles context-building masking on views.
+  - **`presentation.sheets.setMargin(sheetId, margin)`** — set a sheet's print margin to one of the canonical unit-agnostic presets `0 | 0.25 | 0.5 | 0.75 | 1` (displayed None / 1/4″ / 1/2″ / 3/4″ / 1″ on imperial projects, None / 5mm / 10mm / 15mm / 20mm on metric) — the sheet header's margin dropdown; one undo step. Sheet reads (`list`/`get`) now report `margin` (`null` when absent/unrecognized).
+  - **`presentation.placedViews.setRotation(shapeId, rotation)`** — set a placed view's **absolute** rotation in radians (tldraw convention) about its bounds center (the UI rotation handle's pivot); one undo step. Angles are canonicalized into `[0, 2π)`, so the round-trip with the record's `rotation` read is exact only in that range (`setRotation(-0.1)` reads back `2π − 0.1`). **3D placed views only** — 2D/site-plan views cannot rotate (the canvas reverts any rotation applied to them) and are refused with a typed `PRECONDITION_FAILED`. Joins the absolute-setter family (`setScale`/`setCrop`/`setOpacity`/`setMask`).
+  - **`presentation.placedViews.rotateShape(shapeId, rotation)`** — the same absolute center-pivot rotation for any top-level Present-canvas shape (AI outputs, diagram images, plugin shapes, annotations — placed views too); targets and refusals mirror `moveShape`. Same `[0, 2π)` canonicalization (exact round-trip only in that range), and a placed view passed here falls under the same 3D-only rule — 2D/site-plan views refuse with a typed `PRECONDITION_FAILED`.
+  - **`presentation.tables.place(sheetId, { rows }, options?)`** — new `tables` namespace: place plain string rows as a table shape on a sheet (the same shape the Present canvas creates when a Program-mode / Google Sheets / Excel table is pasted). Rows may be ragged, capped at 10000 cells total; `options.position` is sheet-local like `annotate.*` (default: the paste flow's viewport-center auto-placement); returns the created shape as a canvas-shape record; one undo step.
+  - **`presentation.slideshow`** (`start` / `stop` / `getState`) — new namespace: run the Present-mode slideshow programmatically. The slideshow plays **all** sheets in order; `start` options only pick the opening slide (`startIndex` wins over a single-entry `sheetIds`, clamped into range). Browsers grant fullscreen only on a user gesture, so a plugin-triggered `start` typically runs **non-fullscreen** (the rejection is caught). `start`/`stop` are write-gated; `getState` is a never-throw read (`running` + current `index`, `null` when not running). No `next`/`prev`/`goTo` — slide navigation stays with the user.
+  - **`workspace.openPresentMode()` / `closePresentMode()`** — open/close the Present-mode documentation editor. `openPresentMode` resolves only once the Present canvas has mounted (up to ~15s, then a typed `PRECONDITION_FAILED`), so follow-up `presentation.*` calls find Present mode open; both are idempotent and **write-gated** (a mode switch under the user's feet is approval-controlled by design). Overlaps `core.mode.set("present")`/`set("design")` but adds the mount-await + idempotency contract.
+  - **`presentation.diagrams.generateSite(options?)`** — run the site-diagram auto-generation (location / streetview / climate sheets from the map terrain) and return the created `sheetIds`. `options.types` selects a subset (default all three); generation is tracked per-proposal — already-generated types are **skipped, not duplicated** (mount-time-flow semantics; existing site-diagram sheets are never replaced), so `sheetIds` can be empty. Requires Present mode and a map terrain.
+  - **`presentation.annotate.text` typography** — the existing text args gain optional `fontFamily` (system family or any Google Font, loaded automatically — the Present text panel's loader), `fontWeight` (numeric string like `"400"`/`"700"`, `-italic` suffix allowed; unavailable weights fall back to regular), and `fontSizePx` (exact pixel size overriding the `size` preset — `size` alone keeps working). Existing calls are unaffected.
+  - **`program.site.listEdges()`** — read each site parcel's boundary edges with their **front / side / rear** classification: the exact resolution the buildable-envelope setback pills show on canvas (user per-edge overrides win over the tangent heuristic; `roleSource` says which applied), so a plugin picks up the user's edge tagging without asking them to set it up again. Per edge: canonical `edgeIndex` (the envelope `edgeOverrides` index space), endpoints and length in **world meters** (`lengthUnit: "m"` — unlike `listPolygons`' Snaptrude-unit footprints), and the **effective base setback** (per-edge exception, else the role value; `null` for parcels with no zoning envelope — those still classify by heuristic). Entries also report the linked `buildableEnvelopeId` and whether stale index-misaligned overrides were dropped. Never throws; `"street"` resolves to `front`.
+
 ## 0.9.0
 
 ### Minor Changes

package/api-manifest.json

@@ -2750,6 +2750,19 @@
     "argsType": null,
     "resultType": "boolean | null"
   },
+  {
+    "path": "core.io.terrain.replaceMesh",
+    "namespace": "core.io.terrain",
+    "summary": "Replace the terrain surface with a caller-supplied triangle mesh. Undoable (one step), and the replacement persists with the project.",
+    "examplePrompts": [
+      "Replace the terrain with this surveyed mesh",
+      "Flatten a building pad into the site surface",
+      "Load a custom DEM surface onto the terrain",
+      "Regrade the terrain from these points\n\n# Example\n```ts\n// Projects with no terrain yet: import first, then replace.\nif (!(await snaptrude.core.io.terrain.exists())) {\nawait snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)\n}\nconst result = await snaptrude.core.io.terrain.replaceMesh(\npositions, // [x0, y0, z0, x1, y1, z1, …] — world space\nindices,   // [a0, b0, c0, a1, b1, c1, …]\n\"meters\",\n{\ncoordinateSpace: \"world\",\nexpectedTerrain: await snaptrude.core.io.terrain.get(),\nbaseline: \"make-replacement-original\",\npreserve: { datum: true, geolocation: true, satellite: true, material: true },\nclientMutationId: \"survey-2026-08-05-r1\",\n},\n)\n// result.modelRevision — pass back as expectedModelRevision on the next call\n```"
+    ],
+    "argsType": "number[]",
+    "resultType": "PluginTerrainReplaceMeshResult"
+  },
   {
     "path": "core.io.terrain.setDatum",
     "namespace": "core.io.terrain",
@@ -6332,6 +6345,18 @@
     "argsType": null,
     "resultType": "PluginPresentationDiagramsGenerateResult"
   },
+  {
+    "path": "presentation.diagrams.generateSite",
+    "namespace": "presentation.diagrams",
+    "summary": "Generate the site diagrams (location, streetview, climate) for the current model, creating new layout sheets.",
+    "examplePrompts": [
+      "Generate the site diagrams for this project",
+      "Create the location, streetview and climate sheets",
+      "Add a climate diagram sheet to the presentation\n\n# Example\n```ts\nconst { sheetIds } = await snaptrude.presentation.diagrams.generateSite({\ntypes: [\"location\", \"climate\"],\n})\n```"
+    ],
+    "argsType": "{\n    types?: PluginPresentationSiteDiagramType[]\n  }",
+    "resultType": "PluginPresentationDiagramsGenerateResult"
+  },
   {
     "path": "presentation.diagrams.place",
     "namespace": "presentation.diagrams",
@@ -6397,6 +6422,18 @@
     "argsType": "{ url?: string; dataUrl?: string }",
     "resultType": "PluginPresentationImportResult"
   },
+  {
+    "path": "presentation.placedViews.deleteShapes",
+    "namespace": "presentation.placedViews",
+    "summary": "Delete Present-canvas shapes. One undoable step for the whole batch, and the batch is atomic — if any id is rejected, nothing is deleted.",
+    "examplePrompts": [
+      "Delete the old AI renders from the sheet",
+      "Remove that placed view",
+      "Clear the diagram images I placed\n\n# Example\n```ts\nconst { deleted } = await snaptrude.presentation.placedViews.deleteShapes([\nout1.shapeId,\nout2.shapeId,\n])\n```"
+    ],
+    "argsType": "string[]",
+    "resultType": "PluginCanvasShapesDeleteResult"
+  },
   {
     "path": "presentation.placedViews.get",
     "namespace": "presentation.placedViews",
@@ -6409,6 +6446,29 @@
     "argsType": "string",
     "resultType": "PluginPlacedView"
   },
+  {
+    "path": "presentation.placedViews.getShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Get one Present-canvas shape by id — works for any top-level shape (placed view, AI output, diagram image, plugin shape, annotation), unlike `get` which requires a placed view. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Inspect the AI render I just generated",
+      "Get the bounds of that diagram image"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
+  {
+    "path": "presentation.placedViews.getStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Read a placed view's (or sheet's) per-category presentation styles.",
+    "examplePrompts": [
+      "What line weights is this placed plan using?",
+      "Read the styling of the placed view",
+      "Which categories can I restyle on this sheet?\n\n# Example\n```ts\nconst styles = await snaptrude.presentation.placedViews.getStyles(shapeId)\nconst space = styles.categories.find((c) => c.category === \"Space\")\nconsole.log(space?.settings.cutWidth, space?.settings.lineStyle)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewStylesResult"
+  },
   {
     "path": "presentation.placedViews.list",
     "namespace": "presentation.placedViews",
@@ -6422,6 +6482,30 @@
     "argsType": "string",
     "resultType": "PluginPresentationPlacedViewsListResult"
   },
+  {
+    "path": "presentation.placedViews.listLabels",
+    "namespace": "presentation.placedViews",
+    "summary": "List a placed view's labels — the text children generated from the view's content (space names, departments, areas, dimension texts). Each label is individually addressable: it can be moved and hidden. Returns `[]` when the view has no labels. Requires Present mode to be open.",
+    "examplePrompts": [
+      "List the labels on this placed plan",
+      "Where are the space labels on this view?",
+      "Show every label with its position\n\n# Example\n```ts\nconst { labels } = await snaptrude.presentation.placedViews.listLabels(shapeId)\nfor (const l of labels) console.log(l.text, l.position, l.hidden)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabelsResult"
+  },
+  {
+    "path": "presentation.placedViews.listShapes",
+    "namespace": "presentation.placedViews",
+    "summary": "List the top-level shapes on the Present canvas — not just placed views: AI-generated outputs, placed diagram images, plugin-created shapes, and annotations, each with an `origin` classification. Sheets (frames) are not listed — use `sheets.list`. Pass `sheetId` to list only shapes on that sheet. Returns `[]` when Present mode is closed.",
+    "examplePrompts": [
+      "List everything on the Present canvas",
+      "What AI outputs are on this sheet?",
+      "Show all the shapes with their positions\n\n# Example\n```ts\nconst { shapes } = await snaptrude.presentation.placedViews.listShapes()\nconst aiOutputs = shapes.filter((s) => s.origin === \"aiOutput\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShapesListResult"
+  },
   {
     "path": "presentation.placedViews.move",
     "namespace": "presentation.placedViews",
@@ -6434,6 +6518,64 @@
     "argsType": "string",
     "resultType": "PluginPlacedView"
   },
+  {
+    "path": "presentation.placedViews.moveLabel",
+    "namespace": "presentation.placedViews",
+    "summary": "Move a label to a new position (coordinates relative to its placed view, the same space `listLabels` reports). The manual position survives style changes. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Move the kitchen label out of the hatched area",
+      "Nudge this label 20 units right",
+      "Reposition the area text"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabel"
+  },
+  {
+    "path": "presentation.placedViews.moveShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Move any Present-canvas shape (AI outputs, diagram images, plugin shapes, annotations — placed views too). Same coordinate semantics as `move`: sheet-local when on a sheet, page coordinates otherwise; pass `options.sheetId` to reparent onto a sheet. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Move the AI render to the top of the sheet",
+      "Put the diagram image at 100, 200"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
+  {
+    "path": "presentation.placedViews.resetStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Reset a placed view's styling to defaults — the sidebar's Reset button: clears every per-category override and view-style restyle, resets font styles, and un-hides labels hidden by styling. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Reset this view's styling",
+      "Clear all the style overrides on the placed plan",
+      "Put the sheet styles back to default"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.resizeShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Resize any Present-canvas shape by a uniform factor about its top-left corner (aspect ratio held) — the generic counterpart of `scale`, which requires a placed view. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Make the AI output half its size",
+      "Double the size of that image"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
+  {
+    "path": "presentation.placedViews.rotateShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Rotate any Present-canvas shape (AI outputs, diagram images, plugin shapes, annotations — placed views too) — the generic counterpart of `setRotation`, same target rules as `moveShape`. Same semantics: **absolute** angle in radians (tldraw convention) about the shape's bounds center, canonicalized into `[0, 2π)` (pass values in that range for an exact round-trip via `getShape`), one undo step. A placed view passed here falls under the same 3D-only rule as `setRotation`: 2D and site-plan views cannot rotate and are refused with a typed `PRECONDITION_FAILED`. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Rotate the AI render 15 degrees",
+      "Turn that image sideways",
+      "Reset the diagram image's rotation"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
   {
     "path": "presentation.placedViews.scale",
     "namespace": "presentation.placedViews",
@@ -6458,6 +6600,51 @@
     "argsType": "string",
     "resultType": "PluginPlacedView"
   },
+  {
+    "path": "presentation.placedViews.setLabelHidden",
+    "namespace": "presentation.placedViews",
+    "summary": "Hide or show a single label (independent of the category-level label visibility). Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Hide the corridor label",
+      "Show that label again"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabel"
+  },
+  {
+    "path": "presentation.placedViews.setMask",
+    "namespace": "presentation.placedViews",
+    "summary": "Toggle \"mask context buildings\" on a placed view — mutes the inactive proposal buildings in the view (the sidebar checkbox). Views only. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Mask the context buildings in this view",
+      "Show the neighboring proposals again in the placed view"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.setOpacity",
+    "namespace": "presentation.placedViews",
+    "summary": "Set a Present-canvas shape's opacity (`0` transparent .. `1` opaque) — the sidebar's whole-shape opacity slider (distinct from the per-category fill opacity in `updateStyles`). Works for any top-level shape. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Fade the placed view to 50%",
+      "Make the AI render semi-transparent"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.setRotation",
+    "namespace": "presentation.placedViews",
+    "summary": "Set a placed view's rotation.",
+    "examplePrompts": [
+      "Rotate the placed plan 90 degrees",
+      "Set this view's rotation to 45 degrees",
+      "Straighten the placed view back to zero rotation\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.setRotation(shapeId, Math.PI / 2)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedView"
+  },
   {
     "path": "presentation.placedViews.setScale",
     "namespace": "presentation.placedViews",
@@ -6470,6 +6657,32 @@
     "argsType": "string",
     "resultType": "PluginPlacedView"
   },
+  {
+    "path": "presentation.placedViews.updateFontStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Update a category's label typography on a placed view (or sheet) — the configure panel's Text tab.",
+    "examplePrompts": [
+      "Set the space labels to Roboto 24px bold",
+      "Hide the area values on this plan",
+      "Make the department labels italic\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.updateFontStyles(shapeId, \"Space\", {\nobjectLabels: { fontFamily: \"Roboto\", fontWeight: \"700\", fontSize: 24 },\nvisibleTypes: [\"objectLabels\", \"areas\"],\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.updateStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Update one style category on a placed view (or sheet) — the same writes the Present sidebar's per-category configure panel performs.",
+    "examplePrompts": [
+      "Set the Space cut line weight to 0.5 mm",
+      "Make the Department lines dashed",
+      "Color the plan by department",
+      "Hide the dimension lines on this view",
+      "Round the space corners with a 2 ft radius\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.updateStyles(shapeId, \"Space\", {\ncutWidth: 0.5,\nprojectionWidth: 0.18,\nlineStyle: \"dashed\",\ncolorMode: \"department\",\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewCategoryStyles"
+  },
   {
     "path": "presentation.shapes.list",
     "namespace": "presentation.shapes",
@@ -6619,6 +6832,18 @@
     "argsType": "string",
     "resultType": "PluginPresentationSheet"
   },
+  {
+    "path": "presentation.sheets.setMargin",
+    "namespace": "presentation.sheets",
+    "summary": "Set a sheet's print margin.",
+    "examplePrompts": [
+      "Set the sheet margin to half an inch",
+      "Remove the margins on sheet_1",
+      "Give the cover sheet a 10mm margin\n\n# Example\n```ts\nconst sheet = await snaptrude.presentation.sheets.setMargin(\"sheet_1\", 0.5)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheet"
+  },
   {
     "path": "presentation.sheets.setSize",
     "namespace": "presentation.sheets",
@@ -6644,6 +6869,56 @@
     "argsType": "{\n    sheetId?: string\n  }",
     "resultType": "PluginPresentationSheetsUpdatePlacedViewResult"
   },
+  {
+    "path": "presentation.slideshow.getState",
+    "namespace": "presentation.slideshow",
+    "summary": "Read the slideshow state.",
+    "examplePrompts": [
+      "Is the slideshow running?",
+      "Which slide is the presentation on?",
+      "Check the slideshow state\n\n# Example\n```ts\nconst { running, index } = await snaptrude.presentation.slideshow.getState()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginPresentationSlideshowState"
+  },
+  {
+    "path": "presentation.slideshow.start",
+    "namespace": "presentation.slideshow",
+    "summary": "Start the slideshow.",
+    "examplePrompts": [
+      "Start the slideshow",
+      "Present the sheets from the beginning",
+      "Start the slideshow on sheet 3",
+      "Play the presentation starting at the cover sheet\n\n# Example\n```ts\nconst state = await snaptrude.presentation.slideshow.start({ startIndex: 2 })\nconsole.log(state.running, state.index) // true, 2\n```"
+    ],
+    "argsType": "{\n    sheetIds?: string[]\n    startIndex?: number\n  }",
+    "resultType": "PluginPresentationSlideshowState"
+  },
+  {
+    "path": "presentation.slideshow.stop",
+    "namespace": "presentation.slideshow",
+    "summary": "Stop the slideshow.",
+    "examplePrompts": [
+      "Stop the slideshow",
+      "Exit the presentation",
+      "Close the slideshow and go back to the sheets\n\n# Example\n```ts\nawait snaptrude.presentation.slideshow.stop()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginPresentationSlideshowState"
+  },
+  {
+    "path": "presentation.tables.place",
+    "namespace": "presentation.tables",
+    "summary": "Place a table on a sheet.",
+    "examplePrompts": [
+      "Put the area schedule as a table on Sheet 1",
+      "Add a table of the room programs to the cover sheet",
+      "Paste this data as a table on the sheet",
+      "Place a two-column table of space names and areas\n\n# Example\n```ts\nconst shape = await snaptrude.presentation.tables.place(\"sheet_1\", {\nrows: [\n[\"Room\", \"Area\"],\n[\"Kitchen\", \"12.4 m²\"],\n[\"Living\", \"28.0 m²\"],\n],\n}, { position: { x: 40, y: 40 } })\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
   {
     "path": "presentation.views.capture",
     "namespace": "presentation.views",
@@ -7183,6 +7458,19 @@
     "argsType": null,
     "resultType": "PluginProgramSiteWeatherResult"
   },
+  {
+    "path": "program.site.listEdges",
+    "namespace": "program.site",
+    "summary": "List each site parcel's boundary edges with their front / side / rear classification — the same per-edge roles the buildable-envelope setback pills show on canvas, so a plugin can pick up the user's edge tagging without asking them to set it up again.",
+    "examplePrompts": [
+      "Which edge of my site is the front?",
+      "Read the front / side / rear edges of the plot",
+      "What setback applies to each site edge?",
+      "Get the site edges the way the setback pills show them\n\n# Example\n```ts\nconst { sites } = await snaptrude.program.site.listEdges()\nfor (const site of sites)\nfor (const e of site.edges)\nconsole.log(e.edgeIndex, e.role, e.roleSource, e.setbackMeters)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSiteListEdgesResult"
+  },
   {
     "path": "program.site.listGeoPolygons",
     "namespace": "program.site",
@@ -7590,6 +7878,30 @@
     "argsType": "PluginSpreadsheetTransactionOp[]",
     "resultType": "PluginProgramSpreadsheetTransactionResult"
   },
+  {
+    "path": "workspace.closePresentMode",
+    "namespace": "workspace",
+    "summary": "Close Present mode and return to the modeling canvas.",
+    "examplePrompts": [
+      "Close present mode",
+      "Exit the presentation editor",
+      "Go back to the modeling canvas\n\n# Example\n```ts\nawait snaptrude.workspace.closePresentMode()\n```"
+    ],
+    "argsType": null,
+    "resultType": "void"
+  },
+  {
+    "path": "workspace.openPresentMode",
+    "namespace": "workspace",
+    "summary": "Open Present mode — the documentation editor the `presentation.*` namespaces operate on.",
+    "examplePrompts": [
+      "Open present mode",
+      "Switch to the presentation editor",
+      "Open the sheets so I can lay out views\n\n# Example\n```ts\nawait snaptrude.workspace.openPresentMode()\nconst { sheets } = await snaptrude.presentation.sheets.list()\n```"
+    ],
+    "argsType": null,
+    "resultType": "void"
+  },
   {
     "path": "workspace.projects.copy",
     "namespace": "workspace.projects",

package/dist/api/core/io/terrain/index.d.ts

@@ -158,6 +158,68 @@ export declare abstract class PluginCoreIoTerrainApi {
      * @examplePrompt Remove the satellite drape
      */
     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
+     * ```
+     */
+    abstract replaceMesh(positions: number[], indices: number[], units?: "world" | "meters", options?: PluginTerrainReplaceMeshOptions): PluginApiReturn<PluginTerrainReplaceMeshResult>;
     /** Read the terrain opacity, `0`..`1`, or `null` if no terrain. */
     abstract getOpacity(): PluginApiReturn<number | null>;
     /**
@@ -193,6 +255,76 @@ export declare const TerrainReport: z.ZodObject<{
     netVolume: z.ZodNumber;
 }, z.core.$strip>;
 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 declare const PluginTerrainReplaceMeshOptions: z.ZodObject<{
+    coordinateSpace: z.ZodOptional<z.ZodLiteral<"world">>;
+    expectedTerrain: z.ZodOptional<z.ZodString>;
+    expectedModelRevision: z.ZodOptional<z.ZodNumber>;
+    baseline: z.ZodOptional<z.ZodLiteral<"make-replacement-original">>;
+    preserve: z.ZodOptional<z.ZodObject<{
+        datum: z.ZodOptional<z.ZodBoolean>;
+        geolocation: z.ZodOptional<z.ZodBoolean>;
+        satellite: z.ZodOptional<z.ZodBoolean>;
+        material: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    clientMutationId: z.ZodOptional<z.ZodString>;
+}, z.core.$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 declare const PluginTerrainReplaceMeshArgs: z.ZodObject<{
+    positions: z.ZodArray<z.ZodNumber>;
+    indices: z.ZodArray<z.ZodNumber>;
+    units: z.ZodOptional<z.ZodEnum<{
+        meters: "meters";
+        world: "world";
+    }>>;
+    options: z.ZodOptional<z.ZodObject<{
+        coordinateSpace: z.ZodOptional<z.ZodLiteral<"world">>;
+        expectedTerrain: z.ZodOptional<z.ZodString>;
+        expectedModelRevision: z.ZodOptional<z.ZodNumber>;
+        baseline: z.ZodOptional<z.ZodLiteral<"make-replacement-original">>;
+        preserve: z.ZodOptional<z.ZodObject<{
+            datum: z.ZodOptional<z.ZodBoolean>;
+            geolocation: z.ZodOptional<z.ZodBoolean>;
+            satellite: z.ZodOptional<z.ZodBoolean>;
+            material: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        clientMutationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type PluginTerrainReplaceMeshArgs = z.infer<typeof PluginTerrainReplaceMeshArgs>;
 /** Arguments for {@link PluginCoreIoTerrainApi.setDatum}. */
 export declare const PluginTerrainSetDatumArgs: z.ZodObject<{
     offset: z.ZodNumber;

package/dist/api/core/io/terrain/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/core/io/terrain/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;;OAcG;aACa,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC;IAElD;;;;;;;;;OASG;aACa,GAAG,IAAI,eAAe,CAAC,aAAa,GAAG,IAAI,CAAC;IAE5D;;;;;;;;;;;OAWG;aACa,QAAQ,IAAI,eAAe,CAAC,MAAM,GAAG,IAAI,CAAC;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC;IAE/D;;;;;;;;;;OAUG;aACa,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC;IAE/C;;;;;;;;;;;;;;OAcG;aACa,SAAS,IAAI,eAAe,CAAC,aAAa,GAAG,IAAI,CAAC;IAElE,0EAA0E;aAC1D,kBAAkB,IAAI,eAAe,CAAC,OAAO,GAAG,IAAI,CAAC;IACrE;;;;;;;;OAQG;aACa,eAAe,IAAI,eAAe,CAAC,IAAI,CAAC;IACxD;;;;;;;;OAQG;aACa,gBAAgB,IAAI,eAAe,CAAC,IAAI,CAAC;IAEzD,gFAAgF;aAChE,kBAAkB,IAAI,eAAe,CAAC,OAAO,GAAG,IAAI,CAAC;IACrE;;;;;;;;OAQG;aACa,eAAe,IAAI,eAAe,CAAC,IAAI,CAAC;IACxD;;;;;;;;OAQG;aACa,gBAAgB,IAAI,eAAe,CAAC,IAAI,CAAC;IAEzD,mEAAmE;aACnD,UAAU,IAAI,eAAe,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5D;;;;;;;;;;;;;;OAcG;aACa,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC;CACnE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa;;;;iBAIxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB;;iBAA4C,CAAA;AAClF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,+DAA+D;AAC/D,eAAO,MAAM,2BAA2B;;iBAAkD,CAAA;AAC1F,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/core/io/terrain/index.ts"],"names":[],"mappings":"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"}