@snaptrude/plugin-core 0.9.0 → 0.9.1

package/src/api/presentation/sheets.ts

@@ -126,6 +126,34 @@ export abstract class PluginPresentationSheetsApi {
     orientation?: PluginSheetOrientation,
   ): PluginApiReturn<PluginPresentationSheet>
 
+  /**
+   * Set a sheet's print margin.
+   *
+   * Applies one of the canonical margin presets — exactly what the sheet
+   * header's margin dropdown does. `margin` is unit-agnostic: `0 | 0.25 |
+   * 0.5 | 0.75 | 1`, displayed as None / 1/4″ / 1/2″ / 3/4″ / 1″ on imperial
+   * projects and None / 5mm / 10mm / 15mm / 20mm on metric ones. One undo
+   * step. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet.
+   * @param margin - The margin preset ({@linkcode PluginSheetMargin}).
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Set the sheet margin to half an inch
+   * @examplePrompt Remove the margins on sheet_1
+   * @examplePrompt Give the cover sheet a 10mm margin
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.setMargin("sheet_1", 0.5)
+   * ```
+   */
+  public abstract setMargin(
+    sheetId: string,
+    margin: PluginSheetMargin,
+  ): PluginApiReturn<PluginPresentationSheet>
+
   /**
    * Place a saved view onto a sheet.
    *
@@ -331,6 +359,21 @@ export type PluginSheetSize = z.infer<typeof PluginSheetSize>
 export const PluginSheetOrientation = z.enum(["landscape", "portrait"])
 export type PluginSheetOrientation = z.infer<typeof PluginSheetOrientation>
 
+/**
+ * Canonical sheet margin presets — unit-agnostic values matching the sheet
+ * header's margin dropdown: `0` (None), `0.25`, `0.5`, `0.75`, `1`.
+ * Displayed as None / 1/4″ / 1/2″ / 3/4″ / 1″ on imperial projects and
+ * None / 5mm / 10mm / 15mm / 20mm on metric ones.
+ */
+export const PluginSheetMargin = z.union([
+  z.literal(0),
+  z.literal(0.25),
+  z.literal(0.5),
+  z.literal(0.75),
+  z.literal(1),
+])
+export type PluginSheetMargin = z.infer<typeof PluginSheetMargin>
+
 /**
  * A layout sheet in the presentation.
  *
@@ -340,12 +383,14 @@ export type PluginSheetOrientation = z.infer<typeof PluginSheetOrientation>
  * | `name` | `string` | Display name |
  * | `size` | {@linkcode PluginSheetSize}` \| null` | Paper preset (`null` for a legacy sheet without one) |
  * | `orientation` | {@linkcode PluginSheetOrientation}` \| null` | Orientation (`null` for a legacy sheet) |
+ * | `margin` | {@linkcode PluginSheetMargin}` \| null` | Margin preset (`null` when absent/unrecognized) |
  */
 export const PluginPresentationSheet = z.object({
   id: z.string(),
   name: z.string(),
   size: PluginSheetSize.nullable(),
   orientation: PluginSheetOrientation.nullable(),
+  margin: PluginSheetMargin.nullable(),
 })
 export type PluginPresentationSheet = z.infer<typeof PluginPresentationSheet>
 
@@ -406,6 +451,15 @@ export type PluginPresentationSheetsSetSizeArgs = z.infer<
   typeof PluginPresentationSheetsSetSizeArgs
 >
 
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setMargin}. */
+export const PluginPresentationSheetsSetMarginArgs = z.object({
+  sheetId: z.string(),
+  margin: PluginSheetMargin,
+})
+export type PluginPresentationSheetsSetMarginArgs = z.infer<
+  typeof PluginPresentationSheetsSetMarginArgs
+>
+
 /**
  * Arguments for {@linkcode PluginPresentationSheetsApi.place}.
  *

package/src/api/presentation/slideshow.ts

@@ -0,0 +1,134 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation slideshow — run the Present-mode slideshow programmatically.
+ *
+ * The scriptable counterpart of the Present toolbar's slideshow: the
+ * slideshow plays **all** layout sheets in sheet order (hidden sheets are
+ * excluded) — `start` options only pick the slide it opens on. Slide
+ * navigation stays with the user (arrow keys / on-screen controls); there is
+ * intentionally no `next`/`prev`/`goTo`.
+ *
+ * **Fullscreen caveat:** browsers only grant fullscreen on a user gesture. A
+ * plugin-triggered `start` usually fails that check, in which case the
+ * slideshow catches the rejection and runs non-fullscreen (same slides, same
+ * controls, windowed).
+ *
+ * `start`/`stop` are write-gated; `getState` is a never-throw read. Requires
+ * Present mode to be open (except `getState`, which reports not-running).
+ *
+ * Accessed via `snaptrude.presentation.slideshow`.
+ */
+export abstract class PluginPresentationSlideshowApi {
+  constructor() {}
+
+  /**
+   * Start the slideshow.
+   *
+   * Launches the Present-mode slideshow over all layout sheets in sheet
+   * order. `options.startIndex` opens on that slide (clamped into range);
+   * otherwise `options.sheetIds` naming exactly one sheet opens on that
+   * sheet; otherwise it opens on the first slide. May run non-fullscreen —
+   * see the fullscreen caveat on
+   * {@linkcode PluginPresentationSlideshowApi}. Requires Present mode to be
+   * open with at least one sheet.
+   *
+   * @param options - Optional `sheetIds` (open on this sheet when exactly one
+   *   id is given) and `startIndex` (0-based slide to open on; wins over
+   *   `sheetIds`; clamped into range).
+   * @returns The {@linkcode PluginPresentationSlideshowState} after the
+   *   launch (`running: true` and the opening `index`).
+   * @throws If Present mode is not open or there are no sheets to present.
+   *
+   * @examplePrompt Start the slideshow
+   * @examplePrompt Present the sheets from the beginning
+   * @examplePrompt Start the slideshow on sheet 3
+   * @examplePrompt Play the presentation starting at the cover sheet
+   *
+   * # Example
+   * ```ts
+   * const state = await snaptrude.presentation.slideshow.start({ startIndex: 2 })
+   * console.log(state.running, state.index) // true, 2
+   * ```
+   */
+  public abstract start(options?: {
+    sheetIds?: string[]
+    startIndex?: number
+  }): PluginApiReturn<PluginPresentationSlideshowState>
+
+  /**
+   * Stop the slideshow.
+   *
+   * Closes the running slideshow (exiting fullscreen if it entered it) and
+   * returns to the Present canvas. A no-op when no slideshow is running.
+   *
+   * @returns The {@linkcode PluginPresentationSlideshowState} after the stop
+   *   (`running: false`).
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Stop the slideshow
+   * @examplePrompt Exit the presentation
+   * @examplePrompt Close the slideshow and go back to the sheets
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.slideshow.stop()
+   * ```
+   */
+  public abstract stop(): PluginApiReturn<PluginPresentationSlideshowState>
+
+  /**
+   * Read the slideshow state.
+   *
+   * A never-throw read: reports whether a slideshow is running and, when it
+   * is, the current 0-based slide index (`index` is `null` when not
+   * running — including when Present mode is closed).
+   *
+   * @returns The current {@linkcode PluginPresentationSlideshowState}.
+   *
+   * @examplePrompt Is the slideshow running?
+   * @examplePrompt Which slide is the presentation on?
+   * @examplePrompt Check the slideshow state
+   *
+   * # Example
+   * ```ts
+   * const { running, index } = await snaptrude.presentation.slideshow.getState()
+   * ```
+   */
+  public abstract getState(): PluginApiReturn<PluginPresentationSlideshowState>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationSlideshowApi.start}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetIds` | `string[] \| undefined` | Open on this sheet when exactly one id is given |
+ * | `startIndex` | `number \| undefined` | 0-based slide to open on (wins over `sheetIds`; clamped) |
+ */
+export const PluginPresentationSlideshowStartArgs = z.object({
+  sheetIds: z.array(z.string().min(1)).optional(),
+  startIndex: z.number().int().min(0).optional(),
+})
+export type PluginPresentationSlideshowStartArgs = z.infer<
+  typeof PluginPresentationSlideshowStartArgs
+>
+
+/**
+ * The slideshow state — result of {@linkcode PluginPresentationSlideshowApi.start},
+ * {@linkcode PluginPresentationSlideshowApi.stop}, and
+ * {@linkcode PluginPresentationSlideshowApi.getState}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `running` | `boolean` | Whether a slideshow is currently running |
+ * | `index` | `number \| null` | Current 0-based slide index (`null` when not running) |
+ */
+export const PluginPresentationSlideshowState = z.object({
+  running: z.boolean(),
+  index: z.number().int().nullable(),
+})
+export type PluginPresentationSlideshowState = z.infer<
+  typeof PluginPresentationSlideshowState
+>

package/src/api/presentation/tables.ts

@@ -0,0 +1,84 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import type { PluginCanvasShape } from "./placedViews"
+
+/**
+ * Presentation tables — place data tables on Present-mode sheets.
+ *
+ * The scriptable counterpart of the Present canvas's table paste (the flow
+ * that turns a Program-mode / Google Sheets / Excel paste into a table
+ * shape): {@linkcode PluginPresentationTablesApi.place} takes plain string
+ * rows and creates one table shape on a sheet. Requires Present mode to be
+ * open.
+ *
+ * Accessed via `snaptrude.presentation.tables`.
+ */
+export abstract class PluginPresentationTablesApi {
+  constructor() {}
+
+  /**
+   * Place a table on a sheet.
+   *
+   * Creates one table shape from `table.rows` — the same shape the Present
+   * canvas creates when a spreadsheet table is pasted — and returns the
+   * created shape as a canvas-shape record. Cells are plain strings; rows may
+   * be ragged (each row needs at least one cell), capped at 10000 cells
+   * total. `options.position` is sheet-local (relative to the sheet's
+   * top-left, in canvas units — the same convention as `annotate.*`); when
+   * omitted the table lands where the paste flow would auto-place it (the
+   * center of the current viewport). One undo step. Requires Present mode to
+   * be open.
+   *
+   * @param sheetId - The sheet to place the table on.
+   * @param table - The table content: `rows`, an array of string-cell rows.
+   * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
+   *   top-left — defaults to the paste flow's auto-placement).
+   * @returns The created table shape as a {@linkcode PluginCanvasShape}.
+   * @throws If Present mode is not open, the sheet id is invalid, or the
+   *   table is empty / exceeds the 10000-cell cap.
+   *
+   * @examplePrompt Put the area schedule as a table on Sheet 1
+   * @examplePrompt Add a table of the room programs to the cover sheet
+   * @examplePrompt Paste this data as a table on the sheet
+   * @examplePrompt Place a two-column table of space names and areas
+   *
+   * # Example
+   * ```ts
+   * const shape = await snaptrude.presentation.tables.place("sheet_1", {
+   *   rows: [
+   *     ["Room", "Area"],
+   *     ["Kitchen", "12.4 m²"],
+   *     ["Living", "28.0 m²"],
+   *   ],
+   * }, { position: { x: 40, y: 40 } })
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    table: { rows: string[][] },
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginCanvasShape>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationTablesApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place the table on |
+ * | `rows` | `string[][]` | Table cells as string rows (non-empty; ≤ 10000 cells total) |
+ * | `position` | `{ x: number; y: number } \| undefined` | Sheet-local position (default: paste auto-placement) |
+ */
+export const PluginPresentationTablesPlaceArgs = z.object({
+  sheetId: z.string().min(1),
+  rows: z
+    .array(z.array(z.string()).min(1))
+    .min(1)
+    .refine((rows) => rows.reduce((n, r) => n + r.length, 0) <= 10000, {
+      message: "table exceeds the 10000-cell cap",
+    }),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+})
+export type PluginPresentationTablesPlaceArgs = z.infer<
+  typeof PluginPresentationTablesPlaceArgs
+>

package/src/api/program/site.ts

@@ -10,8 +10,10 @@ import { PluginAreaUnit } from "./metrics"
  * in Snaptrude units — the same plan space as a space's `planPoints`), and —
  * when the project is geo-located on terrain — their geographic
  * (latitude/longitude) rings. This is the program-planning view of the site;
- * zoning numbers (setbacks, FAR/FSI, height limits) live in the site-analysis
- * sheet and are not read here.
+ * zoning numbers (FAR/FSI, height limits) live in the site-analysis sheet and
+ * are not read here — with one exception: `listEdges` reads each parcel's
+ * per-edge front/side/rear classification and effective base setbacks, the
+ * same resolution the buildable-envelope setback pills show on canvas.
  *
  * All methods are reads: they return plain records and never throw — `get`
  * returns an empty snapshot (zero totals) when there is no site, and the `list`
@@ -85,6 +87,47 @@ export abstract class PluginProgramSiteApi {
    */
   public abstract listPolygons(): PluginApiReturn<PluginProgramSiteListPolygonsResult>
 
+  /**
+   * 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.
+   *
+   * Role resolution mirrors the canvas exactly: the user's per-edge overrides
+   * (set via the setback pills) win over the tangent heuristic
+   * (`roleSource: "override"` vs `"heuristic"`). `"street"` never appears — it
+   * resolves to `front`. When a parcel has a linked zoning buildable envelope,
+   * `setbackMeters` is the effective base setback of the edge (a per-edge
+   * exception when one exists, else the role's value); parcels without a
+   * zoning envelope classify by heuristic alone and report
+   * `setbackMeters: null`.
+   *
+   * Coordinates are **world meters** (`lengthUnit: "m"`) — unlike
+   * {@linkcode PluginProgramSiteApi.listPolygons} footprints, which are
+   * Snaptrude units. `edgeIndex` is keyed to the canonicalized (sanitized,
+   * CCW) boundary, the same index space the envelope's `edgeOverrides` use.
+   * `staleOverridesDropped: true` means the site was edited after the
+   * envelope was configured and the persisted overrides no longer align with
+   * the live boundary — the heuristic classification is reported instead.
+   *
+   * @returns A {@linkcode PluginProgramSiteListEdgesResult} with one entry per
+   *   parcel. Empty when the project has no site.
+   *
+   * @examplePrompt Which edge of my site is the front?
+   * @examplePrompt Read the front / side / rear edges of the plot
+   * @examplePrompt What setback applies to each site edge?
+   * @examplePrompt Get the site edges the way the setback pills show them
+   *
+   * # Example
+   * ```ts
+   * const { sites } = await snaptrude.program.site.listEdges()
+   * for (const site of sites)
+   *   for (const e of site.edges)
+   *     console.log(e.edgeIndex, e.role, e.roleSource, e.setbackMeters)
+   * ```
+   */
+  public abstract listEdges(): PluginApiReturn<PluginProgramSiteListEdgesResult>
+
   /**
    * List the site parcels as geographic latitude/longitude rings.
    *
@@ -515,3 +558,68 @@ export const PluginProgramSiteWeatherResult =
 export type PluginProgramSiteWeatherResult = z.infer<
   typeof PluginProgramSiteWeatherResult
 >
+
+/**
+ * Front / side / rear classification of one site-boundary edge. `"street"`
+ * never appears — the backend synonym resolves to `front`.
+ */
+export const PluginProgramSiteEdgeRole = z.enum(["front", "side", "rear"])
+export type PluginProgramSiteEdgeRole = z.infer<typeof PluginProgramSiteEdgeRole>
+
+/**
+ * One boundary edge of a site parcel, as {@linkcode PluginProgramSiteApi.listEdges}
+ * returns it. Coordinates and lengths are world meters.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `edgeIndex` | `number` | Index in the canonicalized (sanitized, CCW) boundary — the same index space the envelope's `edgeOverrides` use |
+ * | `start` / `end` | `{ x, z }` | Edge endpoints, world XZ meters |
+ * | `lengthMeters` | `number` | Edge length in meters |
+ * | `role` | `"front" \| "side" \| "rear"` | Resolved classification (user override wins over the heuristic) |
+ * | `roleSource` | `"override" \| "heuristic"` | Whether the user reassigned this edge's role or the tangent heuristic classified it |
+ * | `setbackMeters` | `number \| null` | Effective base setback (per-edge exception ?? role value); `null` when the parcel has no zoning envelope |
+ */
+export const PluginProgramSiteEdge = z.object({
+  edgeIndex: z.number().int().nonnegative(),
+  start: z.object({ x: z.number(), z: z.number() }),
+  end: z.object({ x: z.number(), z: z.number() }),
+  lengthMeters: z.number(),
+  role: PluginProgramSiteEdgeRole,
+  roleSource: z.enum(["override", "heuristic"]),
+  setbackMeters: z.number().nullable(),
+})
+export type PluginProgramSiteEdge = z.infer<typeof PluginProgramSiteEdge>
+
+/**
+ * Per-parcel entry of {@linkcode PluginProgramSiteApi.listEdges}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `siteId` | `string` | The parcel's component id (same id space as `listPolygons`) |
+ * | `buildableEnvelopeId` | `string \| null` | Linked zoning envelope, when one exists |
+ * | `usingLiveSiteBoundary` | `boolean` | `true` when edges come from the live site boundary; `false` when only the envelope's persisted source polygon was resolvable |
+ * | `staleOverridesDropped` | `boolean` | `true` when persisted edge overrides no longer index-align with the live boundary and were ignored |
+ * | `edges` | `PluginProgramSiteEdge[]` | The classified boundary edges |
+ */
+export const PluginProgramSiteEdgesEntry = z.object({
+  siteId: z.string(),
+  buildableEnvelopeId: z.string().nullable(),
+  usingLiveSiteBoundary: z.boolean(),
+  staleOverridesDropped: z.boolean(),
+  edges: z.array(PluginProgramSiteEdge),
+})
+export type PluginProgramSiteEdgesEntry = z.infer<
+  typeof PluginProgramSiteEdgesEntry
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.listEdges} — one entry per site
+ * parcel; empty when the project has no site. `lengthUnit` is always `"m"`.
+ */
+export const PluginProgramSiteListEdgesResult = z.object({
+  lengthUnit: z.literal("m"),
+  sites: z.array(PluginProgramSiteEdgesEntry),
+})
+export type PluginProgramSiteListEdgesResult = z.infer<
+  typeof PluginProgramSiteListEdgesResult
+>

package/src/api/workspace/index.ts

@@ -10,10 +10,13 @@ import { PluginApiReturn } from "../../types"
  * Teams are **read-only** here (no create/invite/delete in v1, a deliberate
  * safety decision); there are no folders in v1. A `projectId` is the project's
  * floorkey. Plan limits are enforced by the backend — a limit rejection surfaces
- * as a normal host error.
+ * as a normal host error. It also carries the workspace-level mode switch for
+ * Present mode ({@linkcode PluginWorkspaceApi.openPresentMode} /
+ * {@linkcode PluginWorkspaceApi.closePresentMode}).
  *
  * - {@linkcode PluginWorkspaceApi.projects} — Create, copy, list, read & rename projects
  * - {@linkcode PluginWorkspaceApi.teams} — Read teams and their members
+ * - {@linkcode PluginWorkspaceApi.openPresentMode} / {@linkcode PluginWorkspaceApi.closePresentMode} — Open/close the Present-mode documentation editor
  */
 export abstract class PluginWorkspaceApi {
   /** Projects — create, copy, list, read & rename. See {@linkcode PluginWorkspaceProjectsApi}. */
@@ -21,6 +24,50 @@ export abstract class PluginWorkspaceApi {
   /** Teams — read teams and their members. See {@linkcode PluginWorkspaceTeamsApi}. */
   public abstract teams: PluginWorkspaceTeamsApi
 
+  /**
+   * Open Present mode — the documentation editor the `presentation.*`
+   * namespaces operate on.
+   *
+   * Switches the workspace into Present mode and resolves only once the
+   * Present canvas has finished mounting (waits up to ~15s; a mount that
+   * never completes is refused with a typed `PRECONDITION_FAILED`), so a
+   * `presentation.*` call issued right after this resolves finds Present
+   * mode open. Idempotent — resolves immediately when Present mode is
+   * already open. Write-gated: switching the mode under the user's feet is
+   * approval-controlled by design.
+   *
+   * @throws `PRECONDITION_FAILED` if the Present canvas does not mount within
+   *   the timeout.
+   *
+   * @examplePrompt Open present mode
+   * @examplePrompt Switch to the presentation editor
+   * @examplePrompt Open the sheets so I can lay out views
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.openPresentMode()
+   * const { sheets } = await snaptrude.presentation.sheets.list()
+   * ```
+   */
+  public abstract openPresentMode(): PluginApiReturn<void>
+
+  /**
+   * Close Present mode and return to the modeling canvas.
+   *
+   * Idempotent — a no-op when Present mode is not open. Write-gated, like
+   * {@linkcode PluginWorkspaceApi.openPresentMode}.
+   *
+   * @examplePrompt Close present mode
+   * @examplePrompt Exit the presentation editor
+   * @examplePrompt Go back to the modeling canvas
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.closePresentMode()
+   * ```
+   */
+  public abstract closePresentMode(): PluginApiReturn<void>
+
   constructor() {}
 }