@snaptrude/plugin-core 0.7.1 → 0.9.0

package/src/api/presentation/diagrams.ts

@@ -2,23 +2,54 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 
 /**
- * Presentation diagrams — place diagram images onto sheets.
+ * Presentation diagrams — generate program diagrams from the model, and place
+ * diagram images onto sheets.
  *
- * {@linkcode PluginPresentationDiagramsApi.place} drops diagram images (by
- * URL) onto a sheet and returns the created canvas shape ids (requires Present
- * mode to be open). Adjacency data itself is read and computed via
+ * {@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.place} drops ready diagram images (by
+ * URL) onto an existing sheet and returns the created canvas shape ids. Both
+ * require Present mode to be open. Adjacency data itself is read and computed via
  * `program.adjacency` (see {@linkcode PluginProgramAdjacencyApi}).
  *
- * A future one-step spec-based `place` — which would render a diagram spec
- * and place it in a single call — awaits a public generator from the
- * documentation engine; until that generator exists, `place` takes ready
- * image `urls` (we do not ship a spec-based `place` that would only throw).
+ * There is intentionally no `generateAdjacency`: the host's adjacency generator
+ * runs its sheet-creation task fire-and-forget internally, so a single call
+ * cannot return the sheets it creates. Use the Present-mode Adjacency menu for
+ * those, then `place` a pre-rendered adjacency image if you need it via the API.
  *
  * Accessed via `snaptrude.presentation.diagrams`.
  */
 export abstract class PluginPresentationDiagramsApi {
   constructor() {}
 
+  /**
+   * Generate the program (space + department) diagrams for the current model,
+   * creating new layout sheets.
+   *
+   * Runs the same auto-generation as the Present-mode **Program** action: reads
+   * the project's spaces and departments, lays them out to scale, and creates one
+   * or more new sheets holding the generated diagram graphics. Unlike
+   * {@linkcode PluginPresentationDiagramsApi.place} (which pastes ready image URLs
+   * onto an existing sheet), this generates the graphics from the model and
+   * creates its own sheets. Requires Present mode to be open.
+   *
+   * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
+   *   `sheetIds` of the sheets created.
+   * @throws If Present mode is not open, or the model has no spaces/departments to
+   *   generate from.
+   *
+   * @examplePrompt Generate the program diagrams for this project
+   * @examplePrompt Auto-generate the space and department diagram sheets
+   * @examplePrompt Create the program layout sheets from the model
+   *
+   * # Example
+   * ```ts
+   * const { sheetIds } = await snaptrude.presentation.diagrams.generateProgram()
+   * ```
+   */
+  public abstract generateProgram(): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
+
   /**
    * Place diagram images onto a sheet.
    *
@@ -82,3 +113,17 @@ export const PluginPresentationDiagramsPlaceResult = z.object({
 export type PluginPresentationDiagramsPlaceResult = z.infer<
   typeof PluginPresentationDiagramsPlaceResult
 >
+
+/**
+ * Result of {@linkcode PluginPresentationDiagramsApi.generateProgram}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetIds` | `string[]` | Ids of the sheets created by the generator |
+ */
+export const PluginPresentationDiagramsGenerateResult = z.object({
+  sheetIds: z.array(z.string()),
+})
+export type PluginPresentationDiagramsGenerateResult = z.infer<
+  typeof PluginPresentationDiagramsGenerateResult
+>

package/src/api/presentation/export.ts

@@ -0,0 +1,108 @@
+import * as z from "zod"
+
+/**
+ * Presentation export — render the Present-mode layout sheets to a downloadable
+ * file (PDF / PNG / JPG) and hand the plugin the bytes as base64.
+ *
+ * This wraps the same pipeline the Present-mode **Export** dialog drives:
+ * each sheet is serialized to an SVG, then either composed into a PDF
+ * (svg2pdf/jspdf) or rasterized to a PNG/JPG. Nothing is written to disk
+ * host-side — the plugin receives the encoded bytes and decides what to do
+ * with them (save, upload, preview).
+ *
+ * Requires **Present mode to be open** (the documentation editor); the call
+ * throws `PRECONDITION_FAILED` when it is not.
+ *
+ * The result is always a uniform `{ files }` array (see
+ * {@linkcode PluginPresentationExportResult}):
+ * - `pdf` with `combine` (the default) → a single multi-page file.
+ * - `pdf` with `combine: false`, or any `png`/`jpg` → one file per sheet.
+ *
+ * Accessed via `snaptrude.presentation.export`.
+ *
+ * For a different export intent, see `core.io.export.model` (the 3D model as a
+ * GLB/OBJ/FBX/3DS file) and `program.spreadsheet.export` (the area-program /
+ * takeoff workbook as XLSX/PDF/CSV).
+ *
+ * The schemas and result types live here; the callable method is declared on
+ * {@linkcode PluginPresentationApi.export}.
+ */
+
+/** Output file format: a vector `pdf`, or a rasterized `png` / `jpg`. */
+export const PluginPresentationExportFormat = z.enum(["pdf", "png", "jpg"])
+export type PluginPresentationExportFormat = z.infer<
+  typeof PluginPresentationExportFormat
+>
+
+/**
+ * Target pixel dimensions for a rasterized (`png`/`jpg`) export. Ignored for
+ * `pdf`, which stays vector and takes its size from the sheet.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `width` | `number` | Output width in pixels |
+ * | `height` | `number` | Output height in pixels |
+ */
+export const PluginPresentationExportResolution = z.object({
+  width: z.number().positive(),
+  height: z.number().positive(),
+})
+export type PluginPresentationExportResolution = z.infer<
+  typeof PluginPresentationExportResolution
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationApi.export}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | `"pdf" \| "png" \| "jpg"` | Output format |
+ * | `sheetIds` | `string[] \| undefined` | Sheets to export (all sheets when omitted) |
+ * | `combine` | `boolean \| undefined` | PDF only: one multi-page file (default `true`) vs one file per sheet |
+ * | `resolution` | {@linkcode PluginPresentationExportResolution}` \| undefined` | Raster target size (`png`/`jpg` only) |
+ * | `fileName` | `string \| undefined` | Base file name (without extension) |
+ */
+export const PluginPresentationExportArgs = z.object({
+  format: PluginPresentationExportFormat,
+  sheetIds: z.array(z.string()).optional(),
+  combine: z.boolean().optional(),
+  resolution: PluginPresentationExportResolution.optional(),
+  fileName: z.string().optional(),
+})
+export type PluginPresentationExportArgs = z.infer<
+  typeof PluginPresentationExportArgs
+>
+
+/**
+ * A single exported file.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `fileName` | `string` | File name including extension |
+ * | `mimeType` | `string` | MIME type (`application/pdf`, `image/png`, `image/jpeg`) |
+ * | `dataBase64` | `string` | The file bytes, base64-encoded (no data-URL prefix) |
+ */
+export const PluginPresentationExportFile = z.object({
+  fileName: z.string(),
+  mimeType: z.string(),
+  dataBase64: z.string(),
+})
+export type PluginPresentationExportFile = z.infer<
+  typeof PluginPresentationExportFile
+>
+
+/**
+ * Result of {@linkcode PluginPresentationApi.export} — always a `files` array.
+ * A combined PDF yields one entry; per-sheet exports yield one entry each, in
+ * sheet order.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `files` | {@linkcode PluginPresentationExportFile}`[]` | The exported files |
+ */
+export const PluginPresentationExportResult = z.object({
+  files: z.array(PluginPresentationExportFile),
+})
+export type PluginPresentationExportResult = z.infer<
+  typeof PluginPresentationExportResult
+>

package/src/api/presentation/import.ts

@@ -20,6 +20,9 @@ export abstract class PluginPresentationImportApi {
   /**
    * Import a reference image onto the current Present sheet.
    *
+   * To place the image as a **scene** underlay to trace over — on a storey,
+   * not the Present canvas — use `core.io.import.image` instead.
+   *
    * @param source - The asset to import: exactly one of `url` or `dataUrl`.
    * @param options - Optional `position` — where to place the image on the
    *   sheet.
@@ -50,6 +53,9 @@ export abstract class PluginPresentationImportApi {
    *
    * Each page is converted to vector SVG and placed as a canvas shape.
    *
+   * To bring the PDF into the **scene** as a traceable underlay — on a storey,
+   * not the Present canvas — use `core.io.import.pdf` instead.
+   *
    * @param source - The asset to import: exactly one of `url` or `dataUrl`.
    * @param options - Optional `position` — where to place the pages on the
    *   sheet.

package/src/api/presentation/index.ts

@@ -1,8 +1,17 @@
+import { PluginApiReturn } from "../../types"
 import { PluginPresentationViewsApi } from "./views"
 import { PluginPresentationAIInspirationApi } from "./aiInspiration"
 import { PluginPresentationSheetsApi } from "./sheets"
+import { PluginPresentationPlacedViewsApi } from "./placedViews"
 import { PluginPresentationDiagramsApi } from "./diagrams"
+import { PluginPresentationAnnotateApi } from "./annotate"
+import { PluginPresentationShapesApi } from "./shapes"
 import { PluginPresentationImportApi } from "./import"
+import {
+  PluginPresentationExportResult,
+  type PluginPresentationExportFormat,
+  type PluginPresentationExportResolution,
+} from "./export"
 
 /**
  * Presentation APIs — prepare and assemble presentations.
@@ -16,6 +25,7 @@ import { PluginPresentationImportApi } from "./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.import} — Import reference images/PDFs onto the canvas
  * - {@linkcode PluginPresentationApi.aiInspiration} — Present-mode AI image/video generation
@@ -27,8 +37,14 @@ export abstract class PluginPresentationApi {
   public abstract views: PluginPresentationViewsApi
   /** Layout sheets — list/get/create and place views (Present mode). See {@linkcode PluginPresentationSheetsApi}. */
   public abstract sheets: PluginPresentationSheetsApi
+  /** Placed views — layout of the view shapes on the canvas: move/scale/setScale/setCrop (Present mode). See {@linkcode PluginPresentationPlacedViewsApi}. */
+  public abstract placedViews: PluginPresentationPlacedViewsApi
   /** Program/adjacency/site diagrams — place images on sheets. See {@linkcode PluginPresentationDiagramsApi}. */
   public abstract diagrams: PluginPresentationDiagramsApi
+  /** Annotations on Present-mode sheets — text/arrows/notes/geo shapes. See {@linkcode PluginPresentationAnnotateApi}. */
+  public abstract annotate: PluginPresentationAnnotateApi
+  /** Plugin-owned keyed shapes — upsert/remove/list so reruns update instead of duplicating. See {@linkcode PluginPresentationShapesApi}. */
+  public abstract shapes: PluginPresentationShapesApi
   /** Import reference images/PDFs onto the Present canvas. See {@linkcode PluginPresentationImportApi}. */
   public abstract import: PluginPresentationImportApi
   /**
@@ -37,11 +53,50 @@ export abstract class PluginPresentationApi {
    */
   public abstract aiInspiration: PluginPresentationAIInspirationApi
 
+  /**
+   * Export the presentation's layout sheets to a downloadable file (PDF / PNG /
+   * JPG) and return the encoded bytes as base64. Wraps the Present-mode Export
+   * dialog pipeline headlessly. Requires Present mode to be open.
+   *
+   * @param format - Output format: `"pdf"`, `"png"`, or `"jpg"`.
+   * @param options - Optional `sheetIds` (all sheets when omitted), `combine`
+   *   (PDF only — one multi-page file vs one per sheet, default `true`),
+   *   `resolution` (raster target size for `png`/`jpg`), and `fileName`.
+   * @returns A {@linkcode PluginPresentationExportResult} — always a `files`
+   *   array (one entry for a combined PDF, one per sheet otherwise).
+   * @throws If Present mode is not open, a `sheetId` is unknown, or a sheet
+   *   fails to serialize/encode.
+   *
+   * @examplePrompt Export the presentation as a PDF
+   * @examplePrompt Download all sheets as a single PDF
+   * @examplePrompt Export sheet 1 as a PNG
+   * @examplePrompt Save the presentation sheets as JPG images
+   * @examplePrompt Export these sheets to PDF at high resolution
+   *
+   * # Example
+   * ```ts
+   * const { files } = await snaptrude.presentation.export("pdf")
+   * ```
+   */
+  public abstract export(
+    format: PluginPresentationExportFormat,
+    options?: {
+      sheetIds?: string[]
+      combine?: boolean
+      resolution?: PluginPresentationExportResolution
+      fileName?: string
+    },
+  ): PluginApiReturn<PluginPresentationExportResult>
+
   constructor() {}
 }
 
 export * from "./views"
 export * from "./sheets"
+export * from "./placedViews"
 export * from "./diagrams"
+export * from "./annotate"
+export * from "./shapes"
 export * from "./import"
 export * from "./aiInspiration"
+export * from "./export"

package/src/api/presentation/placedViews.ts

@@ -0,0 +1,363 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginSheetPosition } from "./sheets"
+
+/**
+ * Placed views — the view shapes already laid out on the Present canvas.
+ *
+ * A **placed view** is a saved view that has been dropped onto a layout sheet
+ * (or the open canvas) — the live linked view shape
+ * {@linkcode PluginPresentationSheetsApi.place} and the Present views panel's
+ * drag-drop create. These methods read and edit the **layout** of those
+ * shapes: where they sit, how big they are, their architectural scale, and
+ * their crop. To refresh a placed view's **content** from the current model,
+ * use `sheets.updatePlacedView` — content refresh lives on `sheets`,
+ * layout lives here.
+ *
+ * Reads (`list`) return `[]` when Present mode is closed; `get` and every
+ * write require Present mode to be open.
+ *
+ * Accessed via `snaptrude.presentation.placedViews`.
+ */
+export abstract class PluginPresentationPlacedViewsApi {
+  constructor() {}
+
+  /**
+   * List the placed views in the presentation.
+   *
+   * Returns every placed view shape on the Present canvas — those nested on a
+   * layout sheet (with that sheet's id) and those sitting loose on the canvas
+   * (`sheetId: null`). Pass `sheetId` to list only the views placed on that
+   * sheet.
+   *
+   * @param sheetId - Optional sheet id to filter by.
+   * @returns A {@linkcode PluginPresentationPlacedViewsListResult} with a
+   *   `placedViews` array (empty when Present mode is closed or nothing is
+   *   placed).
+   * @throws If `sheetId` is given but is not a sheet (with Present mode open).
+   *
+   * @examplePrompt Which views are placed on this sheet?
+   * @examplePrompt List all the placed views in the presentation
+   * @examplePrompt What's laid out on sheet 2?
+   * @examplePrompt Show me every view on the Present canvas
+   *
+   * # Example
+   * ```ts
+   * const { placedViews } = await snaptrude.presentation.placedViews.list("sheet_1")
+   * ```
+   */
+  public abstract list(
+    sheetId?: string,
+  ): PluginApiReturn<PluginPresentationPlacedViewsListResult>
+
+  /**
+   * Get a single placed view by its shape id.
+   *
+   * `shapeId` is the id `sheets.place` returned (also reported by `list`).
+   *
+   * @param shapeId - The id of the placed view shape to read.
+   * @returns The matching {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, or `shapeId` is unknown or is not a
+   *   placed view.
+   *
+   * @examplePrompt Get the placed view I just dropped on the sheet
+   * @examplePrompt Read the position and scale of this placed view
+   * @examplePrompt What's the crop on shape_123?
+   *
+   * # Example
+   * ```ts
+   * const placed = await snaptrude.presentation.placedViews.get(shapeId)
+   * console.log(placed.position, placed.scale)
+   * ```
+   */
+  public abstract get(shapeId: string): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Move a placed view.
+   *
+   * Repositions the placed view on its sheet — `position` is the new top-left
+   * in sheet coordinates (page coordinates when the view is not on a sheet).
+   * Pass `options.sheetId` to move it onto another sheet: the view is
+   * reparented to that sheet and then positioned at `position` in the new
+   * sheet's coordinates. A grouped placed view (e.g. a sustainability 3D view
+   * with its legend) moves as one unit. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to move.
+   * @param position - New top-left position (sheet-local; page coordinates
+   *   when off-sheet).
+   * @param options - Optional `sheetId` — move the view onto that sheet.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `options.sheetId` is given but is not a sheet.
+   *
+   * @examplePrompt Move the site plan view to the top-left of sheet 2
+   * @examplePrompt Reposition this placed view to 100, 200
+   * @examplePrompt Move the hero perspective onto the cover sheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.move(shapeId, { x: 50, y: 50 }, {
+   *   sheetId: "sheet_2",
+   * })
+   * ```
+   */
+  public abstract move(
+    shapeId: string,
+    position: PluginSheetPosition,
+    options?: { sheetId?: string },
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Resize a placed view by a uniform factor.
+   *
+   * Scales the placed view about its top-left corner — the same resize as
+   * dragging a corner handle, aspect ratio held. Works for 2D and 3D views;
+   * labels and grouped legends resize with it. For a 2D view the **printed
+   * architectural scale changes proportionally** (doubling the size of a
+   * 1:100 plan makes it a 1:50 plan) — use
+   * {@linkcode PluginPresentationPlacedViewsApi.setScale} to land on an exact
+   * standard scale instead. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to resize.
+   * @param factor - Uniform scale factor, between `0.01` and `100`
+   *   (`2` doubles the size, `0.5` halves it).
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `factor` is not a finite number between 0.01 and 100.
+   *
+   * @examplePrompt Make this placed view twice as big
+   * @examplePrompt Shrink the placed 3D view to half its size
+   * @examplePrompt Scale the placed plan up by 50%
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.scale(shapeId, 2)
+   * ```
+   */
+  public abstract scale(
+    shapeId: string,
+    factor: number,
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Set a placed view's architectural scale.
+   *
+   * Applies a standard architectural scale — the same write the placed view's
+   * Scale dropdown performs. The view (and its labels) is resized about its
+   * top-left corner so it prints at the given scale. `scale` must be one of
+   * the standard values for the project's unit system (metric `10, 20, 50,
+   * 100, 150, 200, 250, 500, 1000`; imperial e.g. `48` for 1/4″ = 1′, `96`
+   * for 1/8″ = 1′, `120` for 1″ = 10′) — the same validation as
+   * `sheets.place`. 3D views have no architectural scale — calling this on
+   * one throws. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to set the scale of.
+   * @param scale - A standard scale value for the project's unit system.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, `scale` is not a standard value for the project's unit
+   *   system, or the placed view is a 3D view.
+   *
+   * @examplePrompt Set the plan to 1:100
+   * @examplePrompt Change the placed floor plan to 1:50 scale
+   * @examplePrompt Make this view print at quarter-inch scale
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.setScale(shapeId, 100) // 1:100
+   * ```
+   */
+  public abstract setScale(
+    shapeId: string,
+    scale: number,
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Crop a placed view, or clear its crop.
+   *
+   * `crop` selects the visible window as **fractions (0–1) of the uncropped
+   * view** — `topLeft` must be strictly less than `bottomRight` on both axes.
+   * The visible region stays anchored on the page (the same behavior as the
+   * interactive crop), labels that fall outside the crop are hidden, and the
+   * view's architectural scale is untouched. Pass `null` to clear the crop
+   * and restore the full view in its uncropped footprint (the interactive
+   * double-click-edge reset). The crop **survives a content refresh**
+   * (`sheets.updatePlacedView` recomputes it against the refreshed content
+   * and only clears it when the refreshed view no longer overlaps the cropped
+   * region). Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to crop.
+   * @param crop - The crop window ({@linkcode PluginPlacedViewCrop},
+   *   fractions of the uncropped view), or `null` to clear.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `crop` is not a valid 0–1 rectangle with
+   *   `topLeft < bottomRight` on both axes.
+   *
+   * @examplePrompt Crop the placed view to its left half
+   * @examplePrompt Crop this view to the top-right quarter
+   * @examplePrompt Remove the crop from the placed plan
+   *
+   * # Example
+   * ```ts
+   * // keep the left half of the view
+   * await snaptrude.presentation.placedViews.setCrop(shapeId, {
+   *   topLeft: { x: 0, y: 0 },
+   *   bottomRight: { x: 0.5, y: 1 },
+   * })
+   * await snaptrude.presentation.placedViews.setCrop(shapeId, null) // clear
+   * ```
+   */
+  public abstract setCrop(
+    shapeId: string,
+    crop: PluginPlacedViewCrop | null,
+  ): PluginApiReturn<PluginPlacedView>
+}
+
+/** A point in crop space — fractions (0–1) of the uncropped view. */
+const PluginPlacedViewCropPoint = z.object({
+  x: z.number().min(0).max(1),
+  y: z.number().min(0).max(1),
+})
+
+/**
+ * A crop window on a placed view, as fractions (0–1) of the **uncropped**
+ * view. `topLeft` must be strictly less than `bottomRight` on both axes.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `topLeft` | `{ x: number, y: number }` | Top-left of the visible window (fractions 0–1) |
+ * | `bottomRight` | `{ x: number, y: number }` | Bottom-right of the visible window (fractions 0–1) |
+ */
+export const PluginPlacedViewCrop = z
+  .object({
+    topLeft: PluginPlacedViewCropPoint,
+    bottomRight: PluginPlacedViewCropPoint,
+  })
+  .refine(
+    (c) => c.topLeft.x < c.bottomRight.x && c.topLeft.y < c.bottomRight.y,
+    { message: "topLeft must be strictly less than bottomRight on both axes" },
+  )
+export type PluginPlacedViewCrop = z.infer<typeof PluginPlacedViewCrop>
+
+/**
+ * A view placed on the Present canvas.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the placed view shape (the id `sheets.place` returns) |
+ * | `sheetId` | `string \| null` | The sheet it sits on (`null` when placed loose on the canvas) |
+ * | `title` | `string` | The saved view's title |
+ * | `viewId` | `string` | Id of the saved view it was placed from |
+ * | `position` | {@linkcode PluginSheetPosition} | Top-left position — sheet-local when on a sheet, page coordinates otherwise |
+ * | `size` | `{ width: number, height: number }` | Displayed size on the canvas |
+ * | `scale` | `number \| null` | Architectural scale (e.g. `100` = 1:100); `null` for 3D views |
+ * | `is3d` | `boolean` | Whether it is a 3D view (no architectural scale) |
+ * | `rotation` | `number` | Rotation in radians (nonzero only for 3D views) |
+ * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | Crop window (`null` when uncropped) |
+ * | `isUnlinked` | `boolean` | Whether the source proposal was removed (an unlinked view no longer refreshes) |
+ */
+export const PluginPlacedView = z.object({
+  shapeId: z.string(),
+  sheetId: z.string().nullable(),
+  title: z.string(),
+  viewId: z.string(),
+  position: PluginSheetPosition,
+  size: z.object({ width: z.number(), height: z.number() }),
+  scale: z.number().nullable(),
+  is3d: z.boolean(),
+  rotation: z.number(),
+  crop: PluginPlacedViewCrop.nullable(),
+  isUnlinked: z.boolean(),
+})
+export type PluginPlacedView = z.infer<typeof PluginPlacedView>
+
+/** Arguments for {@linkcode PluginPresentationPlacedViewsApi.list}. */
+export const PluginPresentationPlacedViewsListArgs = z.object({
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationPlacedViewsListArgs = z.infer<
+  typeof PluginPresentationPlacedViewsListArgs
+>
+
+/** Result of {@linkcode PluginPresentationPlacedViewsApi.list}. */
+export const PluginPresentationPlacedViewsListResult = z.object({
+  placedViews: z.array(PluginPlacedView),
+})
+export type PluginPresentationPlacedViewsListResult = z.infer<
+  typeof PluginPresentationPlacedViewsListResult
+>
+
+/** Arguments for {@linkcode PluginPresentationPlacedViewsApi.get}. */
+export const PluginPresentationPlacedViewsGetArgs = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationPlacedViewsGetArgs = z.infer<
+  typeof PluginPresentationPlacedViewsGetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to move |
+ * | `position` | {@linkcode PluginSheetPosition} | New top-left position (sheet-local; page coordinates when off-sheet) |
+ * | `sheetId` | `string`? | Move the view onto this sheet |
+ */
+export const PluginPresentationPlacedViewsMoveArgs = z.object({
+  shapeId: z.string(),
+  position: PluginSheetPosition,
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationPlacedViewsMoveArgs = z.infer<
+  typeof PluginPresentationPlacedViewsMoveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.scale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to resize |
+ * | `factor` | `number` | Uniform scale factor (0.01–100) |
+ */
+export const PluginPresentationPlacedViewsScaleArgs = z.object({
+  shapeId: z.string(),
+  factor: z.number().finite().min(0.01).max(100),
+})
+export type PluginPresentationPlacedViewsScaleArgs = z.infer<
+  typeof PluginPresentationPlacedViewsScaleArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.setScale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to set the scale of |
+ * | `scale` | `number` | A standard scale value for the project's unit system |
+ */
+export const PluginPresentationPlacedViewsSetScaleArgs = z.object({
+  shapeId: z.string(),
+  scale: z.number().positive(),
+})
+export type PluginPresentationPlacedViewsSetScaleArgs = z.infer<
+  typeof PluginPresentationPlacedViewsSetScaleArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.setCrop}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to crop |
+ * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | The crop window, or `null` to clear |
+ */
+export const PluginPresentationPlacedViewsSetCropArgs = z.object({
+  shapeId: z.string(),
+  crop: PluginPlacedViewCrop.nullable(),
+})
+export type PluginPresentationPlacedViewsSetCropArgs = z.infer<
+  typeof PluginPresentationPlacedViewsSetCropArgs
+>