@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/presentation/sheets.ts

@@ -1,585 +1,746 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Presentation sheets — the layout sheets a presentation is assembled on.
- *
- * A **sheet** is a page in Present mode that views and diagrams are placed onto.
- * These methods require **Present mode to be open** (the documentation editor) —
- * reads return `[]`/`null` and writes throw when it is not.
- *
- * `list`/`get` are reads; the rest mutate and require Present mode to be open:
- * `create` adds a sheet, `place` drops a saved view onto a sheet as a live
- * linked view shape, `rename` relabels a sheet, `delete` removes one, `reorder`
- * moves one in the sheet order, `setActive` navigates to one, and
- * `updatePlacedView` re-renders placed views to the current model.
- *
- * Accessed via `snaptrude.presentation.sheets`.
- */
-export abstract class PluginPresentationSheetsApi {
-  constructor() {}
-
-  /**
-   * List the layout sheets in the presentation.
-   *
-   * @returns A {@linkcode PluginPresentationSheetsListResult} with a `sheets`
-   *   array (empty when Present mode is closed or there are no sheets).
-   *
-   * @examplePrompt List all the sheets
-   * @examplePrompt How many layout sheets are there?
-   * @examplePrompt Show me the presentation sheets
-   * @examplePrompt What sheets can I place views on?
-   *
-   * # Example
-   * ```ts
-   * const { sheets } = await snaptrude.presentation.sheets.list()
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginPresentationSheetsListResult>
-
-  /**
-   * Get a single sheet by id.
-   *
-   * @param sheetId - The id of the sheet to read.
-   * @returns The matching {@linkcode PluginPresentationSheet}, or `null`.
-   *
-   * @examplePrompt Get the sheet with id sheet_1
-   * @examplePrompt Find the sheet called Cover
-   * @examplePrompt Look up a layout sheet by id
-   *
-   * # Example
-   * ```ts
-   * const sheet = await snaptrude.presentation.sheets.get("sheet_1")
-   * ```
-   */
-  public abstract get(
-    sheetId: string,
-  ): PluginApiReturn<PluginPresentationSheetsGetResult>
-
-  /**
-   * Create a new layout sheet.
-   *
-   * Optionally sets the paper size and orientation — the same presets as the
-   * sheet header's size dropdown (ANSI A–E, Arch A–E1, ISO A4–A0). When `size`
-   * is omitted the sheet inherits the editor session's last-used size
-   * (initially ANSI B) in landscape, so pass `size` explicitly whenever the
-   * output format matters.
-   *
-   * Requires Present mode to be open.
-   *
-   * @param name - Display name for the new sheet (optional).
-   * @param options - Optional `size` ({@linkcode PluginSheetSize} paper preset)
-   *   and `orientation` ({@linkcode PluginSheetOrientation}; `"landscape"` when
-   *   omitted).
-   * @returns The newly created {@linkcode PluginPresentationSheet}.
-   * @throws If Present mode is not open.
-   *
-   * @examplePrompt Create a new sheet called Cover
-   * @examplePrompt Add an A3 landscape layout sheet
-   * @examplePrompt Make a new ANSI D presentation sheet named Floor Plans
-   * @examplePrompt Create a portrait A4 sheet
-   *
-   * # Example
-   * ```ts
-   * const sheet = await snaptrude.presentation.sheets.create("Cover", {
-   *   size: "ISO_A3",
-   *   orientation: "landscape",
-   * })
-   * ```
-   */
-  public abstract create(
-    name?: string,
-    options?: { size?: PluginSheetSize; orientation?: PluginSheetOrientation },
-  ): PluginApiReturn<PluginPresentationSheet>
-
-  /**
-   * Set a sheet's paper size and/or orientation.
-   *
-   * Applies one of the standard paper presets — exactly what the sheet header's
-   * size dropdown and orientation toggle do. Content that no longer fits inside
-   * the resized sheet is moved out onto the canvas (matching the native
-   * behavior). Undoable. Does not change the user's remembered default size for
-   * new sheets.
-   *
-   * Requires Present mode to be open.
-   *
-   * @param sheetId - The id of the sheet to resize.
-   * @param size - The paper preset ({@linkcode PluginSheetSize}).
-   * @param orientation - Optional {@linkcode PluginSheetOrientation}; keeps the
-   *   sheet's current orientation when omitted.
-   * @returns The updated {@linkcode PluginPresentationSheet}.
-   * @throws If Present mode is not open, or the sheet id is invalid.
-   *
-   * @examplePrompt Resize sheet_1 to A1
-   * @examplePrompt Make the cover sheet ANSI B portrait
-   * @examplePrompt Change this sheet to Arch D landscape
-   * @examplePrompt Set the sheet size to A3
-   *
-   * # Example
-   * ```ts
-   * const sheet = await snaptrude.presentation.sheets.setSize("sheet_1", "ISO_A1", "portrait")
-   * ```
-   */
-  public abstract setSize(
-    sheetId: string,
-    size: PluginSheetSize,
-    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.
-   *
-   * Drops the given view onto the sheet through the **native view drop** — the
-   * placed shape is a live linked view (the same shape the Present views panel's
-   * drag-drop creates), re-rendered from the current model, so
-   * {@linkcode PluginPresentationSheetsApi.updatePlacedView} refreshes it later.
-   * 2D and site-plan views are placed at an architectural scale: the closest
-   * standard scale by default (the native auto-fit), or the explicit `scale`
-   * when given — one of the standard values the placed view's Scale dropdown
-   * offers 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′). 3D views have no scale — passing `scale` for one
-   * throws. Requires Present mode to be open.
-   *
-   * @param sheetId - The id of the sheet to place onto.
-   * @param viewId - The id of the saved view to place.
-   * @param options - Optional `position` ({@linkcode PluginSheetPosition}) —
-   *   where to place it (sheet centre when omitted) — and `scale` — a standard
-   *   scale value for the project's unit system (2D/site-plan views only;
-   *   auto-fit when omitted).
-   * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
-   *   `shapeId`.
-   * @throws If Present mode is not open, the sheet/view id is invalid, `scale`
-   *   is not a standard value for the project's unit system, or `scale` is
-   *   passed for a 3D view.
-   *
-   * @examplePrompt Place the floor plan on Sheet 1
-   * @examplePrompt Add this 3D view to the cover sheet
-   * @examplePrompt Drop the site plan onto the layout sheet at 100, 200
-   * @examplePrompt Put the Ground Floor view on sheet_1 at 1:100 scale
-   * @examplePrompt Place the plan on the cover sheet at quarter-inch scale
-   *
-   * # Example
-   * ```ts
-   * const { shapeId } = await snaptrude.presentation.sheets.place("sheet_1", "view_123", {
-   *   scale: 100, // 1:100 (metric project)
-   * })
-   * ```
-   */
-  public abstract place(
-    sheetId: string,
-    viewId: string,
-    options?: { position?: PluginSheetPosition; scale?: number },
-  ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
-
-  /**
-   * Rename a layout sheet.
-   *
-   * Sets the sheet's display name — the same label the sheets panel shows and
-   * that `list`/`get` read back. Requires Present mode to be open.
-   *
-   * @param sheetId - The id of the sheet to rename.
-   * @param name - The new display name (non-empty after trimming).
-   * @returns The updated {@linkcode PluginPresentationSheet}.
-   * @throws If Present mode is not open, or the sheet id is invalid.
-   *
-   * @examplePrompt Rename sheet_1 to Cover
-   * @examplePrompt Call the first sheet Ground Floor
-   * @examplePrompt Change this sheet's name to Site Plan
-   *
-   * # Example
-   * ```ts
-   * const sheet = await snaptrude.presentation.sheets.rename("sheet_1", "Cover")
-   * ```
-   */
-  public abstract rename(
-    sheetId: string,
-    name: string,
-  ): PluginApiReturn<PluginPresentationSheet>
-
-  /**
-   * Delete a layout sheet.
-   *
-   * Removes the sheet (and its placed content) from the presentation and
-   * renumbers the remaining sheets. Requires Present mode to be open. Auto-diagram
-   * sheets cannot be deleted through the API — remove those from the Present UI.
-   *
-   * @param sheetId - The id of the sheet to delete.
-   * @returns The id of the deleted sheet
-   *   (a {@linkcode PluginPresentationSheetsDeleteResult}).
-   * @throws If Present mode is not open, the sheet id is invalid, or the sheet is
-   *   an auto-diagram sheet.
-   *
-   * @examplePrompt Delete sheet_2
-   * @examplePrompt Remove the Cover sheet
-   * @examplePrompt Get rid of the last layout sheet
-   *
-   * # Example
-   * ```ts
-   * const { id } = await snaptrude.presentation.sheets.delete("sheet_2")
-   * ```
-   */
-  public abstract delete(
-    sheetId: string,
-  ): PluginApiReturn<PluginPresentationSheetsDeleteResult>
-
-  /**
-   * Move a sheet to a new position in the sheet order.
-   *
-   * Reorders the sheet to the given zero-based `index` (as the sheets panel does
-   * when a sheet is dragged) and renumbers the rest. `index` is clamped to the
-   * valid range. Requires Present mode to be open.
-   *
-   * @param sheetId - The id of the sheet to move.
-   * @param index - Zero-based target position in the sheet order.
-   * @returns The sheets in their new order
-   *   (a {@linkcode PluginPresentationSheetsListResult}).
-   * @throws If Present mode is not open, or the sheet id is invalid.
-   *
-   * @examplePrompt Move sheet_3 to the front
-   * @examplePrompt Make the Cover sheet the first sheet
-   * @examplePrompt Reorder this sheet to position 2
-   *
-   * # Example
-   * ```ts
-   * const { sheets } = await snaptrude.presentation.sheets.reorder("sheet_3", 0)
-   * ```
-   */
-  public abstract reorder(
-    sheetId: string,
-    index: number,
-  ): PluginApiReturn<PluginPresentationSheetsListResult>
-
-  /**
-   * Make a sheet the active sheet.
-   *
-   * Selects the sheet in the sheets panel and navigates the Present canvas to it
-   * (the same as clicking it in the panel). Requires Present mode to be open.
-   *
-   * @param sheetId - The id of the sheet to activate.
-   * @returns The now-active {@linkcode PluginPresentationSheet}.
-   * @throws If Present mode is not open, or the sheet id is invalid.
-   *
-   * @examplePrompt Go to sheet_1
-   * @examplePrompt Open the Cover sheet
-   * @examplePrompt Switch to the Site Plan sheet
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.sheets.setActive("sheet_1")
-   * ```
-   */
-  public abstract setActive(
-    sheetId: string,
-  ): PluginApiReturn<PluginPresentationSheet>
-
-  /**
-   * Refresh placed views to the current model state.
-   *
-   * Re-renders the presentation's placed **views** — the live linked view shapes —
-   * from the current model (the "Update views" action). Views placed with
-   * {@linkcode PluginPresentationSheetsApi.place} are live view shapes too, so
-   * they refresh along with panel-dropped ones. Pass `sheetId` to refresh only
-   * the views on that sheet, or omit it to refresh every placed view. Requires
-   * Present mode to be open.
-   *
-   * @param options - Optional `sheetId` — restrict the refresh to one sheet's
-   *   placed views (all placed views when omitted).
-   * @returns The ids of the placed view shapes submitted for refresh
-   *   (a {@linkcode PluginPresentationSheetsUpdatePlacedViewResult}).
-   * @throws If Present mode is not open, or `sheetId` is given but invalid.
-   *
-   * @examplePrompt Update all the placed views to the latest model
-   * @examplePrompt Refresh the views on sheet_1
-   * @examplePrompt Re-render the placed views after my edits
-   *
-   * # Example
-   * ```ts
-   * const { shapeIds } = await snaptrude.presentation.sheets.updatePlacedView()
-   * ```
-   */
-  public abstract updatePlacedView(options?: {
-    sheetId?: string
-  }): PluginApiReturn<PluginPresentationSheetsUpdatePlacedViewResult>
-}
-
-/**
- * Standard paper-size presets for layout sheets — identical to the sheet
- * header's size dropdown in Present mode.
- */
-export const PluginSheetSize = z.enum([
-  "ANSI_A",
-  "ANSI_B",
-  "ANSI_C",
-  "ANSI_D",
-  "ANSI_E",
-  "ARCH_A",
-  "ARCH_B",
-  "ARCH_C",
-  "ARCH_D",
-  "ARCH_E",
-  "ARCH_E1",
-  "ISO_A4",
-  "ISO_A3",
-  "ISO_A2",
-  "ISO_A1",
-  "ISO_A0",
-])
-export type PluginSheetSize = z.infer<typeof PluginSheetSize>
-
-/** Sheet orientation. */
-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.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Unique sheet id |
- * | `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>
-
-/**
- * A position on a sheet/canvas (sheet coordinates).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `x` | `number` | X coordinate |
- * | `y` | `number` | Y coordinate |
- */
-export const PluginSheetPosition = z.object({
-  x: z.number(),
-  y: z.number(),
-})
-export type PluginSheetPosition = z.infer<typeof PluginSheetPosition>
-
-/** Result of {@linkcode PluginPresentationSheetsApi.list}. */
-export const PluginPresentationSheetsListResult = z.object({
-  sheets: z.array(PluginPresentationSheet),
-})
-export type PluginPresentationSheetsListResult = z.infer<
-  typeof PluginPresentationSheetsListResult
->
-
-/** Arguments for {@linkcode PluginPresentationSheetsApi.get}. */
-export const PluginPresentationSheetsGetArgs = z.object({
-  id: z.string(),
-})
-export type PluginPresentationSheetsGetArgs = z.infer<
-  typeof PluginPresentationSheetsGetArgs
->
-
-/** Result of {@linkcode PluginPresentationSheetsApi.get} — the sheet, or `null`. */
-export const PluginPresentationSheetsGetResult =
-  PluginPresentationSheet.nullable()
-export type PluginPresentationSheetsGetResult = z.infer<
-  typeof PluginPresentationSheetsGetResult
->
-
-/** Arguments for {@linkcode PluginPresentationSheetsApi.create}. */
-export const PluginPresentationSheetsCreateArgs = z.object({
-  name: z.string().optional(),
-  size: PluginSheetSize.optional(),
-  orientation: PluginSheetOrientation.optional(),
-})
-export type PluginPresentationSheetsCreateArgs = z.infer<
-  typeof PluginPresentationSheetsCreateArgs
->
-
-/** Arguments for {@linkcode PluginPresentationSheetsApi.setSize}. */
-export const PluginPresentationSheetsSetSizeArgs = z.object({
-  sheetId: z.string(),
-  size: PluginSheetSize,
-  orientation: PluginSheetOrientation.optional(),
-})
-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}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to place onto |
- * | `viewId` | `string` | The saved view to place |
- * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (sheet centre when omitted) |
- * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; auto-fit to the closest standard scale when omitted) |
- */
-export const PluginPresentationSheetsPlaceArgs = z.object({
-  sheetId: z.string(),
-  viewId: z.string(),
-  position: PluginSheetPosition.optional(),
-  scale: z.number().positive().optional(),
-})
-export type PluginPresentationSheetsPlaceArgs = z.infer<
-  typeof PluginPresentationSheetsPlaceArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationSheetsApi.place}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `shapeId` | `string` | Id of the created canvas shape |
- */
-export const PluginPresentationSheetsPlaceResult = z.object({
-  shapeId: z.string(),
-})
-export type PluginPresentationSheetsPlaceResult = z.infer<
-  typeof PluginPresentationSheetsPlaceResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationSheetsApi.rename}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to rename |
- * | `name` | `string` | New display name (non-empty after trimming) |
- */
-export const PluginPresentationSheetsRenameArgs = z.object({
-  sheetId: z.string(),
-  name: z.string().trim().min(1),
-})
-export type PluginPresentationSheetsRenameArgs = z.infer<
-  typeof PluginPresentationSheetsRenameArgs
->
-
-/** Arguments for {@linkcode PluginPresentationSheetsApi.delete}. */
-export const PluginPresentationSheetsDeleteArgs = z.object({
-  sheetId: z.string(),
-})
-export type PluginPresentationSheetsDeleteArgs = z.infer<
-  typeof PluginPresentationSheetsDeleteArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationSheetsApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Id of the deleted sheet |
- */
-export const PluginPresentationSheetsDeleteResult = z.object({
-  id: z.string(),
-})
-export type PluginPresentationSheetsDeleteResult = z.infer<
-  typeof PluginPresentationSheetsDeleteResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationSheetsApi.reorder}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to move |
- * | `index` | `number` | Zero-based target position (clamped to range) |
- */
-export const PluginPresentationSheetsReorderArgs = z.object({
-  sheetId: z.string(),
-  index: z.number().int().min(0),
-})
-export type PluginPresentationSheetsReorderArgs = z.infer<
-  typeof PluginPresentationSheetsReorderArgs
->
-
-/** Arguments for {@linkcode PluginPresentationSheetsApi.setActive}. */
-export const PluginPresentationSheetsSetActiveArgs = z.object({
-  sheetId: z.string(),
-})
-export type PluginPresentationSheetsSetActiveArgs = z.infer<
-  typeof PluginPresentationSheetsSetActiveArgs
->
-
-/**
- * Arguments for {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string`? | Restrict the refresh to one sheet's placed views |
- */
-export const PluginPresentationSheetsUpdatePlacedViewArgs = z.object({
-  sheetId: z.string().optional(),
-})
-export type PluginPresentationSheetsUpdatePlacedViewArgs = z.infer<
-  typeof PluginPresentationSheetsUpdatePlacedViewArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `shapeIds` | `string[]` | Ids of the placed view shapes submitted for refresh |
- */
-export const PluginPresentationSheetsUpdatePlacedViewResult = z.object({
-  shapeIds: z.array(z.string()),
-})
-export type PluginPresentationSheetsUpdatePlacedViewResult = z.infer<
-  typeof PluginPresentationSheetsUpdatePlacedViewResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginStandardDrawingScale } from "./drawingContract"
+
+/**
+ * Presentation sheets — the layout sheets a presentation is assembled on.
+ *
+ * A **sheet** is a page in Present mode that views and diagrams are placed onto.
+ * These methods require **Present mode to be open** (the documentation editor) —
+ * reads return `[]`/`null` and writes throw when it is not.
+ *
+ * `list`/`get` are reads; the rest mutate and require Present mode to be open:
+ * `create` adds a sheet, `place` drops a saved view onto a sheet as a live
+ * linked view shape (fitted to that sheet), `placeDrawing` moves an existing
+ * drawing onto a sheet (scaled down to fit by default), `rename` relabels a
+ * sheet, `delete` removes one, `reorder` moves one in the sheet order,
+ * `setActive` navigates to one, and `updatePlacedView` re-renders placed views
+ * to the current model.
+ *
+ * `presentation.drawings.create` never puts a drawing on a sheet: it makes the
+ * drawing beside its source view on the canvas. To put a view on a sheet, call
+ * `place(sheetId, viewId)`; to move a drawing you already made, call
+ * `placeDrawing(sheetId, drawingId)`.
+ *
+ * Accessed via `snaptrude.presentation.sheets`.
+ */
+export abstract class PluginPresentationSheetsApi {
+  constructor() {}
+
+  /**
+   * List the layout sheets in the presentation.
+   *
+   * @returns A {@linkcode PluginPresentationSheetsListResult} with a `sheets`
+   *   array (empty when Present mode is closed or there are no sheets).
+   *
+   * @examplePrompt List all the sheets
+   * @examplePrompt How many layout sheets are there?
+   * @examplePrompt Show me the presentation sheets
+   * @examplePrompt What sheets can I place views on?
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.presentation.sheets.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginPresentationSheetsListResult>
+
+  /**
+   * Get a single sheet by id.
+   *
+   * @param sheetId - The id of the sheet to read.
+   * @returns The matching {@linkcode PluginPresentationSheet}, or `null`.
+   *
+   * @examplePrompt Get the sheet with id sheet_1
+   * @examplePrompt Find the sheet called Cover
+   * @examplePrompt Look up a layout sheet by id
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.get("sheet_1")
+   * ```
+   */
+  public abstract get(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheetsGetResult>
+
+  /**
+   * Create a new layout sheet.
+   *
+   * Optionally sets the paper size and orientation — the same presets as the
+   * sheet header's size dropdown (ANSI A–E, Arch A–E1, ISO A4–A0). When `size`
+   * is omitted the sheet inherits the editor session's last-used size
+   * (initially ANSI B) in landscape, so pass `size` explicitly whenever the
+   * output format matters.
+   *
+   * Requires Present mode to be open.
+   *
+   * @param name - Display name for the new sheet (optional).
+   * @param options - Optional `size` ({@linkcode PluginSheetSize} paper preset)
+   *   and `orientation` ({@linkcode PluginSheetOrientation}; `"landscape"` when
+   *   omitted).
+   * @returns The newly created {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Create a new sheet called Cover
+   * @examplePrompt Add an A3 landscape layout sheet
+   * @examplePrompt Make a new ANSI D presentation sheet named Floor Plans
+   * @examplePrompt Create a portrait A4 sheet
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.create("Cover", {
+   *   size: "ISO_A3",
+   *   orientation: "landscape",
+   * })
+   * ```
+   */
+  public abstract create(
+    name?: string,
+    options?: { size?: PluginSheetSize; orientation?: PluginSheetOrientation },
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Set a sheet's paper size and/or orientation.
+   *
+   * Applies one of the standard paper presets — exactly what the sheet header's
+   * size dropdown and orientation toggle do. Content that no longer fits inside
+   * the resized sheet is moved out onto the canvas (matching the native
+   * behavior). Undoable. Does not change the user's remembered default size for
+   * new sheets.
+   *
+   * Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to resize.
+   * @param size - The paper preset ({@linkcode PluginSheetSize}).
+   * @param orientation - Optional {@linkcode PluginSheetOrientation}; keeps the
+   *   sheet's current orientation when omitted.
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Resize sheet_1 to A1
+   * @examplePrompt Make the cover sheet ANSI B portrait
+   * @examplePrompt Change this sheet to Arch D landscape
+   * @examplePrompt Set the sheet size to A3
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.setSize("sheet_1", "ISO_A1", "portrait")
+   * ```
+   */
+  public abstract setSize(
+    sheetId: string,
+    size: PluginSheetSize,
+    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. This is the call that puts a view on a
+   * sheet (`presentation.drawings.create` makes a drawing beside its source
+   * view, not on a sheet). When `scale` is omitted the view is fitted to the
+   * target sheet: a 2D or site-plan view is placed at the largest
+   * standard scale at which it fits inside the target sheet's margin, and
+   * never at a larger scale than the normal view drop would pick; a 3D view
+   * has no scale, so it is shrunk evenly to fit instead. This is the same fit
+   * as `placeDrawing`. Omit `position` unless the user asked for a specific
+   * place.
+   * Without a `position` the drawing goes to the sheet centre when that is
+   * free, otherwise to the nearest free spot to the centre inside the margin,
+   * beside the drawings already there; when there is no free spot it is
+   * centred anyway and the result has `overlaps: true`. With a `position` it
+   * is placed as given, and the result has `overlaps: true` when it covers
+   * another drawing, but it is not moved. In both cases only other drawings
+   * count (placed views and their title blocks and labels): text, images and
+   * other shapes on the sheet are ignored. Each call fits one view to the
+   * whole sheet, so a second fitted view often has no free spot: when several
+   * views should share a sheet, pass a `scale` small enough for all of them;
+   * otherwise use `sheets.create` per view. When the result's `overlaps` is
+   * true, move the drawing or put it on its own sheet.
+   * An explicit `scale` is always kept, even when the drawing (title block
+   * included) does not fit inside the sheet's margin at that scale; the result
+   * then has `overflows: true`. When it is true, pass a smaller scale (larger
+   * denominator), omit `scale` to fit, or use a larger sheet.
+   * `scale` must be a standard architectural scale denominator (100 means 1:100)
+   * in the project's unit system; any other value is rejected. Metric: 10, 20, 50,
+   * 100, 150, 200, 250, 500, 1000. Imperial detail: 12, 16, 24, 32, 48, 64, 96, 128,
+   * 192, 384, 768, 1536 (1" = 1' to 1/128" = 1'; 48 is 1/4" = 1', 96 is 1/8" = 1').
+   * Imperial site: 120, 240, 360, 480, 600, 1200, 2400, 3600, 4800 (1" = 10' to
+   * 1" = 400'). Pick the LARGEST standard scale (smallest denominator) at which the
+   * view still fits its frame or sheet and its room labels stay readable: for a
+   * building floor plan that is usually 1:50 to 1:200 (1/4" = 1' to 1/16" = 1').
+   * Never use a site-sized scale (1:500 and up, 1/64" = 1' (768) and smaller,
+   * 1" = 20' (240) and up) for a single building plan unless the user asked for it.
+   *
+   * Drops the given view onto the sheet through the **native view drop** — the
+   * placed shape is a live linked view (the same shape the Present views panel's
+   * drag-drop creates), re-rendered from the current model, so
+   * {@linkcode PluginPresentationSheetsApi.updatePlacedView} refreshes it later.
+   * 2D and site-plan views are placed at an architectural scale: the fitted
+   * standard scale described above by default, or the explicit `scale` when
+   * given (one of the standard values above). 3D views have no scale; passing
+   * `scale` for one throws. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to place onto.
+   * @param viewId - The id of the saved view to place.
+   * @param options - Optional `position` ({@linkcode PluginSheetPosition}) —
+   *   where to place it (when omitted, the sheet centre or the nearest free
+   *   spot) — and `scale` — a standard scale value for the project's unit system (2D/site-plan views only;
+   *   fitted to the target sheet when omitted).
+   * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
+   *   `shapeId`, the `scale` used (`null` for a 3D view), whether the fit
+   *   `rescaled` it, whether it `overlaps` another drawing on the sheet, and
+   *   whether it `overflows` the sheet's margin at an explicit `scale`.
+   *   (Hosts older than the fit return only `shapeId`.)
+   * @throws If Present mode is not open, the sheet/view id is invalid, `scale`
+   *   is not a standard value for the project's unit system, or `scale` is
+   *   passed for a 3D view. `PRECONDITION_FAILED` when the view does not fit
+   *   the sheet even at the smallest standard scale, or the title block alone
+   *   is larger than the sheet's drawable area (use a larger sheet); no
+   *   drawing is left on the sheet.
+   *
+   * @examplePrompt Place the floor plan on Sheet 1
+   * @examplePrompt Add this 3D view to the cover sheet
+   * @examplePrompt Drop the site plan onto the layout sheet at 100, 200
+   * @examplePrompt Put the Ground Floor view on sheet_1 at 1:100 scale
+   * @examplePrompt Place the plan on the cover sheet at quarter-inch scale
+   * @examplePrompt Add a floor plan drawing of each storey to this sheet
+   *
+   * # Example
+   * ```ts
+   * const { shapeId } = await snaptrude.presentation.sheets.place("sheet_1", "view_123", {
+   *   scale: 100, // 1:100 (metric project)
+   * })
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    viewId: string,
+    options?: { position?: PluginSheetPosition; scale?: number },
+  ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
+
+  /**
+   * Move an existing drawing onto a sheet without copying or regenerating it,
+   * scaled down to fit the sheet when it is too big. `presentation.drawings.create`
+   * leaves a drawing beside its source view, not on a sheet; this is the call
+   * that puts it on one. To place a saved view on a sheet in one call, use
+   * `sheets.place(sheetId, viewId)`, which fits it the same way.
+   * By default (`fit` true or omitted) a drawing larger than the sheet's
+   * drawable area (the sheet inside its margin) is moved to the LARGEST standard
+   * architectural scale at which it fits; a drawing that already fits keeps its
+   * scale, and a drawing is never scaled up. A 3D drawing has no architectural
+   * scale, so it is shrunk uniformly to fit instead. With `fit: false` the scale
+   * is kept and a drawing that does not fit is rejected with an error naming the
+   * drawing, the sheet and the scale, and saying to call `placeDrawing` without
+   * `fit: false` to fit it, or use a larger sheet. When even
+   * the smallest standard scale does not fit, the call is rejected with an error
+   * suggesting a larger sheet size.
+   * Without a `position` the drawing goes to the sheet centre when that is
+   * free, otherwise to the nearest free spot to the centre inside the margin,
+   * beside the drawings already there; when there is no free spot it is
+   * centred anyway and the result has `overlaps: true`. With a `position` it
+   * is placed as given, and the result has `overlaps: true` when it covers
+   * another drawing, but it is not moved. In both cases only other drawings
+   * count (placed views and their title blocks and labels): text, images and
+   * other shapes on the sheet are ignored. Each call fits one drawing to the
+   * whole sheet, so a second fitted drawing often has no free spot: when
+   * several drawings should share a sheet, give them scales small enough for
+   * all of them; otherwise use `sheets.create` per drawing.
+   * The position is sheet-local. The drawing's
+   * stable id remains unchanged; `shapeId` therefore identifies the moved
+   * drawing. The result reports the architectural scale the drawing has on the
+   * sheet and whether this call changed it; a host that reports it also says
+   * whether the drawing `overlaps` another drawing on the sheet (move it or
+   * put it on its own sheet when true).
+   *
+   * @param sheetId - The id of the destination sheet.
+   * @param drawingId - The id of an existing drawing deliverable.
+   * @param options - Optional sheet-local `position` (when omitted, the sheet centre or the nearest free spot)
+   *   and `fit` (default `true`: scale a drawing that does not fit down to fit;
+   *   `false`: keep its scale and reject a drawing that does not fit).
+   * @returns A {@linkcode PluginPresentationSheetsPlaceDrawingResult} with the
+   *   drawing's `shapeId`, the `scale` used (`null` for a 3D drawing),
+   *   `rescaled`, and optionally `overlaps`.
+   * @throws `PRECONDITION_FAILED` if Present mode is closed, the sheet is locked,
+   *   the drawing does not fit with `fit: false`, or it does not fit even at the
+   *   smallest standard scale; `HANDLE_INVALID` if either id is invalid or the
+   *   shape is not a drawing.
+   *
+   * @examplePrompt Move this drawing onto the cover sheet
+   * @examplePrompt Place drawing_1 at the center of sheet_2
+   * @examplePrompt Put the level 2 plan drawing on the Level 2 Plan sheet
+   * @examplePrompt Add the floor plan drawings to this sheet
+   *
+   * # Example
+   * ```ts
+   * const { scale, rescaled } = await snaptrude.presentation.sheets.placeDrawing(
+   *   sheet.id,
+   *   drawing.id,
+   * )
+   * ```
+   */
+  public abstract placeDrawing(
+    sheetId: string,
+    drawingId: string,
+    options?: { position?: PluginSheetPosition; fit?: boolean },
+  ): PluginApiReturn<PluginPresentationSheetsPlaceDrawingResult>
+
+  /**
+   * Rename a layout sheet.
+   *
+   * Sets the sheet's display name — the same label the sheets panel shows and
+   * that `list`/`get` read back. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to rename.
+   * @param name - The new display name (non-empty after trimming).
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Rename sheet_1 to Cover
+   * @examplePrompt Call the first sheet Ground Floor
+   * @examplePrompt Change this sheet's name to Site Plan
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.rename("sheet_1", "Cover")
+   * ```
+   */
+  public abstract rename(
+    sheetId: string,
+    name: string,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Delete a layout sheet.
+   *
+   * Removes the sheet (and its placed content) from the presentation and
+   * renumbers the remaining sheets. Requires Present mode to be open. Auto-diagram
+   * sheets cannot be deleted through the API — remove those from the Present UI.
+   *
+   * @param sheetId - The id of the sheet to delete.
+   * @returns The id of the deleted sheet
+   *   (a {@linkcode PluginPresentationSheetsDeleteResult}).
+   * @throws If Present mode is not open, the sheet id is invalid, or the sheet is
+   *   an auto-diagram sheet.
+   *
+   * @examplePrompt Delete sheet_2
+   * @examplePrompt Remove the Cover sheet
+   * @examplePrompt Get rid of the last layout sheet
+   *
+   * # Example
+   * ```ts
+   * const { id } = await snaptrude.presentation.sheets.delete("sheet_2")
+   * ```
+   */
+  public abstract delete(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheetsDeleteResult>
+
+  /**
+   * Move a sheet to a new position in the sheet order.
+   *
+   * Reorders the sheet to the given zero-based `index` (as the sheets panel does
+   * when a sheet is dragged) and renumbers the rest. `index` is clamped to the
+   * valid range. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to move.
+   * @param index - Zero-based target position in the sheet order.
+   * @returns The sheets in their new order
+   *   (a {@linkcode PluginPresentationSheetsListResult}).
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Move sheet_3 to the front
+   * @examplePrompt Make the Cover sheet the first sheet
+   * @examplePrompt Reorder this sheet to position 2
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.presentation.sheets.reorder("sheet_3", 0)
+   * ```
+   */
+  public abstract reorder(
+    sheetId: string,
+    index: number,
+  ): PluginApiReturn<PluginPresentationSheetsListResult>
+
+  /**
+   * Make a sheet the active sheet.
+   *
+   * Selects the sheet in the sheets panel and navigates the Present canvas to it
+   * (the same as clicking it in the panel). Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to activate.
+   * @returns The now-active {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Go to sheet_1
+   * @examplePrompt Open the Cover sheet
+   * @examplePrompt Switch to the Site Plan sheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.sheets.setActive("sheet_1")
+   * ```
+   */
+  public abstract setActive(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Refresh placed views to the current model state.
+   *
+   * Re-renders the presentation's placed **views** — the live linked view shapes —
+   * from the current model (the "Update views" action). Views placed with
+   * {@linkcode PluginPresentationSheetsApi.place} are live view shapes too, so
+   * they refresh along with panel-dropped ones. Pass `sheetId` to refresh only
+   * the views on that sheet, or omit it to refresh every placed view. Requires
+   * Present mode to be open.
+   *
+   * @param options - Optional `sheetId` — restrict the refresh to one sheet's
+   *   placed views (all placed views when omitted).
+   * @returns The ids of the placed view shapes submitted for refresh
+   *   (a {@linkcode PluginPresentationSheetsUpdatePlacedViewResult}).
+   * @throws If Present mode is not open, or `sheetId` is given but invalid.
+   *
+   * @examplePrompt Update all the placed views to the latest model
+   * @examplePrompt Refresh the views on sheet_1
+   * @examplePrompt Re-render the placed views after my edits
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.sheets.updatePlacedView()
+   * ```
+   */
+  public abstract updatePlacedView(options?: {
+    sheetId?: string
+  }): PluginApiReturn<PluginPresentationSheetsUpdatePlacedViewResult>
+}
+
+/**
+ * Standard paper-size presets for layout sheets — identical to the sheet
+ * header's size dropdown in Present mode.
+ */
+export const PluginSheetSize = z.enum([
+  "ANSI_A",
+  "ANSI_B",
+  "ANSI_C",
+  "ANSI_D",
+  "ANSI_E",
+  "ARCH_A",
+  "ARCH_B",
+  "ARCH_C",
+  "ARCH_D",
+  "ARCH_E",
+  "ARCH_E1",
+  "ISO_A4",
+  "ISO_A3",
+  "ISO_A2",
+  "ISO_A1",
+  "ISO_A0",
+])
+export type PluginSheetSize = z.infer<typeof PluginSheetSize>
+
+/** Sheet orientation. */
+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.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Unique sheet id |
+ * | `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>
+
+/**
+ * A position on a sheet/canvas (sheet coordinates).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number` | X coordinate |
+ * | `y` | `number` | Y coordinate |
+ */
+export const PluginSheetPosition = z.object({
+  x: z.number(),
+  y: z.number(),
+})
+export type PluginSheetPosition = z.infer<typeof PluginSheetPosition>
+
+/** Result of {@linkcode PluginPresentationSheetsApi.list}. */
+export const PluginPresentationSheetsListResult = z.object({
+  sheets: z.array(PluginPresentationSheet),
+})
+export type PluginPresentationSheetsListResult = z.infer<
+  typeof PluginPresentationSheetsListResult
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.get}. */
+export const PluginPresentationSheetsGetArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationSheetsGetArgs = z.infer<
+  typeof PluginPresentationSheetsGetArgs
+>
+
+/** Result of {@linkcode PluginPresentationSheetsApi.get} — the sheet, or `null`. */
+export const PluginPresentationSheetsGetResult =
+  PluginPresentationSheet.nullable()
+export type PluginPresentationSheetsGetResult = z.infer<
+  typeof PluginPresentationSheetsGetResult
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.create}. */
+export const PluginPresentationSheetsCreateArgs = z.object({
+  name: z.string().optional(),
+  size: PluginSheetSize.optional(),
+  orientation: PluginSheetOrientation.optional(),
+})
+export type PluginPresentationSheetsCreateArgs = z.infer<
+  typeof PluginPresentationSheetsCreateArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setSize}. */
+export const PluginPresentationSheetsSetSizeArgs = z.object({
+  sheetId: z.string(),
+  size: PluginSheetSize,
+  orientation: PluginSheetOrientation.optional(),
+})
+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}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place onto |
+ * | `viewId` | `string` | The saved view to place |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (when omitted, the sheet centre or the nearest free spot) |
+ * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; when omitted, the largest standard scale that fits inside the target sheet's margin, never larger than the normal view drop's) |
+ */
+export const PluginPresentationSheetsPlaceArgs = z.object({
+  sheetId: z.string(),
+  viewId: z.string(),
+  position: PluginSheetPosition.optional(),
+  scale: PluginStandardDrawingScale.optional(),
+})
+export type PluginPresentationSheetsPlaceArgs = z.infer<
+  typeof PluginPresentationSheetsPlaceArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.placeDrawing}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The destination sheet |
+ * | `drawingId` | `string` | The existing drawing to move |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Sheet-local position (when omitted, the sheet centre or the nearest free spot) |
+ * | `fit` | `boolean \| undefined` | `true` (default) scales a drawing that does not fit down to fit; `false` keeps its scale and rejects a drawing that does not fit |
+ */
+export const PluginPresentationSheetsPlaceDrawingArgs = z.object({
+  sheetId: z.string().min(1),
+  drawingId: z.string().min(1),
+  position: PluginSheetPosition.optional(),
+  fit: z.boolean().optional(),
+})
+export type PluginPresentationSheetsPlaceDrawingArgs = z.infer<
+  typeof PluginPresentationSheetsPlaceDrawingArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.place}. The host returns
+ * `scale` and `rescaled` (and `overlaps`, `overflows`); they are optional only
+ * because hosts that predate the fit report `shapeId` alone.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the created canvas shape |
+ * | `scale` | `number \| null \| undefined` | Architectural scale denominator the view has on the sheet (`null` for a 3D view) |
+ * | `rescaled` | `boolean \| undefined` | Whether the fit changed the view's size from the normal view drop's |
+ * | `overlaps` | `boolean \| undefined` | Whether the placed drawing overlaps another drawing on the sheet (only drawings count, not text, images or other shapes) |
+ * | `overflows` | `boolean \| undefined` | `true` when the drawing, title block included, does not fit inside the sheet's margin at the explicit `scale` passed (the scale is kept); absent otherwise |
+ */
+export const PluginPresentationSheetsPlaceResult = z.object({
+  shapeId: z.string(),
+  scale: z.number().finite().nullable().optional(),
+  rescaled: z.boolean().optional(),
+  overlaps: z.boolean().optional(),
+  overflows: z.boolean().optional(),
+})
+export type PluginPresentationSheetsPlaceResult = z.infer<
+  typeof PluginPresentationSheetsPlaceResult
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.placeDrawing}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the moved drawing (the drawing id, unchanged) |
+ * | `scale` | `number \| null` | Architectural scale denominator the drawing has on the sheet (`null` for a 3D drawing) |
+ * | `rescaled` | `boolean` | Whether this call changed the drawing's size to fit the sheet |
+ * | `overlaps` | `boolean \| undefined` | Whether the drawing overlaps another drawing on the sheet (only drawings count, not text, images or other shapes) |
+ */
+export const PluginPresentationSheetsPlaceDrawingResult =
+  PluginPresentationSheetsPlaceResult.omit({ overflows: true }).extend({
+    scale: z.number().finite().nullable(),
+    rescaled: z.boolean(),
+  })
+export type PluginPresentationSheetsPlaceDrawingResult = z.infer<
+  typeof PluginPresentationSheetsPlaceDrawingResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to rename |
+ * | `name` | `string` | New display name (non-empty after trimming) |
+ */
+export const PluginPresentationSheetsRenameArgs = z.object({
+  sheetId: z.string(),
+  name: z.string().trim().min(1),
+})
+export type PluginPresentationSheetsRenameArgs = z.infer<
+  typeof PluginPresentationSheetsRenameArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.delete}. */
+export const PluginPresentationSheetsDeleteArgs = z.object({
+  sheetId: z.string(),
+})
+export type PluginPresentationSheetsDeleteArgs = z.infer<
+  typeof PluginPresentationSheetsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Id of the deleted sheet |
+ */
+export const PluginPresentationSheetsDeleteResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationSheetsDeleteResult = z.infer<
+  typeof PluginPresentationSheetsDeleteResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.reorder}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to move |
+ * | `index` | `number` | Zero-based target position (clamped to range) |
+ */
+export const PluginPresentationSheetsReorderArgs = z.object({
+  sheetId: z.string(),
+  index: z.number().int().min(0),
+})
+export type PluginPresentationSheetsReorderArgs = z.infer<
+  typeof PluginPresentationSheetsReorderArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setActive}. */
+export const PluginPresentationSheetsSetActiveArgs = z.object({
+  sheetId: z.string(),
+})
+export type PluginPresentationSheetsSetActiveArgs = z.infer<
+  typeof PluginPresentationSheetsSetActiveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string`? | Restrict the refresh to one sheet's placed views |
+ */
+export const PluginPresentationSheetsUpdatePlacedViewArgs = z.object({
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationSheetsUpdatePlacedViewArgs = z.infer<
+  typeof PluginPresentationSheetsUpdatePlacedViewArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeIds` | `string[]` | Ids of the placed view shapes submitted for refresh |
+ */
+export const PluginPresentationSheetsUpdatePlacedViewResult = z.object({
+  shapeIds: z.array(z.string()),
+})
+export type PluginPresentationSheetsUpdatePlacedViewResult = z.infer<
+  typeof PluginPresentationSheetsUpdatePlacedViewResult
+>