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

package/src/api/presentation/views.ts

@@ -1,673 +1,742 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Presentation views — read the saved 2D/3D views used to prepare presentations.
- *
- * A **view** is a saved camera/plan: a sheet-ready 2D plan or a saved 3D view.
- * A plugin can list and read views, capture them to images, activate one (move
- * the camera to it), save the current camera as a new view, rename or delete a
- * saved view, and read/update a view's display settings (background, color
- * mode, view mode, axis, edges, labels). Each view carries the `storey` it was
- * saved on.
- *
- * `list`/`get`/`getActive`/`capture`/`getSettings` are reads;
- * `setActive`/`create`/`rename`/`delete`/`updateSettings` are writes (a view is
- * a camera bookmark — not geometry).
- *
- * Accessed via `snaptrude.presentation.views`.
- */
-export abstract class PluginPresentationViewsApi {
-  constructor() {}
-
-  /**
-   * List the saved views in the active project.
-   *
-   * @returns A {@linkcode PluginPresentationViewsListResult} with a `views` array
-   *   of 2D and 3D views (empty when the project has none).
-   *
-   * @examplePrompt List all the saved views
-   * @examplePrompt What 2D and 3D views are in this project?
-   * @examplePrompt Which view is currently active?
-   * @examplePrompt Get the names of every presentation view
-   * @examplePrompt Show me the 3D views I can put on a sheet
-   *
-   * # Example
-   * ```ts
-   * const { views } = await snaptrude.presentation.views.list()
-   * const active = views.find((v) => v.isActive)
-   * const plans = views.filter((v) => v.type === "2d")
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginPresentationViewsListResult>
-
-  /**
-   * Get a single saved view by id.
-   *
-   * @param viewId - The id of the view to read.
-   * @returns The matching {@linkcode PluginPresentationView}, or `null` if no view
-   *   has that id.
-   *
-   * @examplePrompt Get the view with id view_12345
-   * @examplePrompt Find the saved view called Ground Floor Plan
-   * @examplePrompt Look up a presentation view by its id
-   *
-   * # Example
-   * ```ts
-   * const view = await snaptrude.presentation.views.get("view_123")
-   * ```
-   */
-  public abstract get(
-    viewId: string,
-  ): PluginApiReturn<PluginPresentationViewsGetResult>
-
-  /**
-   * Get the currently active view.
-   *
-   * @returns The active {@linkcode PluginPresentationView}, or `null` if none is
-   *   active.
-   *
-   * @examplePrompt Which view is active right now?
-   * @examplePrompt Get the current view
-   * @examplePrompt What view am I looking at?
-   *
-   * # Example
-   * ```ts
-   * const active = await snaptrude.presentation.views.getActive()
-   * ```
-   */
-  public abstract getActive(): PluginApiReturn<PluginPresentationViewsGetResult>
-
-  /**
-   * Capture a screenshot of a view as a base64 image.
-   *
-   * Captures the **current** viewport by default; pass `viewId` to capture a
-   * specific saved view (which briefly applies that view to the scene). Use
-   * `format`/`resolution` to control the output. This shoots the Design (3D)
-   * canvas; to screenshot the Present canvas use
-   * {@linkcode PluginPresentationCameraApi.capture}.
-   *
-   * @param options - All optional: `viewId` (capture this saved view; omit for the
-   *   current viewport), `format` (default `"png"`), `resolution` (e.g. `"1280x720"`).
-   * @returns A {@linkcode PluginPresentationViewsCaptureResult} with the base64
-   *   `image` data URL.
-   * @throws If a given `viewId` does not exist.
-   *
-   * @examplePrompt Take a screenshot of the current view
-   * @examplePrompt Capture this view as a PNG
-   * @examplePrompt Render the Site Plan view to an image
-   * @examplePrompt Export a high-res image of what I'm looking at
-   *
-   * # Example
-   * ```ts
-   * const { image } = await snaptrude.presentation.views.capture({ format: "png" })
-   * ```
-   */
-  public abstract capture(options?: {
-    viewId?: string
-    format?: "png" | "jpeg"
-    resolution?: string
-  }): PluginApiReturn<PluginPresentationViewsCaptureResult>
-
-  /**
-   * Activate a saved view — move the camera to it and restore its scene state.
-   *
-   * Applies the view's camera, visibility, and storey state to the live scene.
-   * Paired with {@linkcode PluginPresentationViewsApi.getActive}.
-   *
-   * @param viewId - The id of the view to activate.
-   * @returns The id of the now-active view.
-   * @throws If no view has the given id.
-   *
-   * @examplePrompt Switch to the Ground Floor plan view
-   * @examplePrompt Make the 3D view active
-   * @examplePrompt Go to the view named Entrance
-   * @examplePrompt Load the site plan view
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.views.setActive("view_123")
-   * ```
-   */
-  public abstract setActive(
-    viewId: string,
-  ): PluginApiReturn<PluginPresentationViewsSetActiveResult>
-
-  /**
-   * Save the current camera/scene state as a new named view.
-   *
-   * Creates a camera bookmark (not geometry) from where the camera is now.
-   *
-   * @param name - Name for the new view (a default is used when omitted).
-   * @param options - Optional `kind` (what kind of view to save, default
-   *   `"view"`) and `storey` (save the view on a specific storey — the storey is
-   *   activated first, matching the storey the view is captured on; when omitted
-   *   the current active storey is used).
-   * @returns The newly created {@linkcode PluginPresentationView}.
-   * @throws If `storey` is given but no such storey exists, or the view could
-   *   not be saved.
-   *
-   * @examplePrompt Save the current view as Lobby Perspective
-   * @examplePrompt Create a new saved view from where I'm looking
-   * @examplePrompt Bookmark this camera angle
-   * @examplePrompt Save the current 2D plan as a view
-   * @examplePrompt Save a view on the second storey
-   *
-   * # Example
-   * ```ts
-   * const view = await snaptrude.presentation.views.create("Lobby")
-   * // …or capture the view on a specific storey
-   * const level2 = await snaptrude.presentation.views.create("Level 2", { storey: 2 })
-   * ```
-   */
-  public abstract create(
-    name?: string,
-    options?: { kind?: "view" | "sitePlan"; storey?: number },
-  ): PluginApiReturn<PluginPresentationViewsCreateResult>
-
-  /**
-   * Read a saved view's display settings (background, color mode, view mode,
-   * axis, edges, labels).
-   *
-   * @param viewId - The id of the view to read settings for.
-   * @returns The view's {@linkcode PluginPresentationViewSettings}, or `null` if
-   *   no view has that id.
-   *
-   * @examplePrompt What color mode is the Ground Floor view using?
-   * @examplePrompt Get the display settings for this view
-   * @examplePrompt Does the site plan view show axes and labels?
-   * @examplePrompt Read the background color of the active view
-   *
-   * # Example
-   * ```ts
-   * const settings = await snaptrude.presentation.views.getSettings("view_123")
-   * if (settings) console.log(settings.colorMode, settings.backgroundColor)
-   * ```
-   */
-  public abstract getSettings(
-    viewId: string,
-  ): PluginApiReturn<PluginPresentationViewsGetSettingsResult>
-
-  /**
-   * Update a saved view's display settings (partial patch — only the fields you
-   * pass change).
-   *
-   * Persists and broadcasts the change; if the view is currently active, the
-   * scene updates live. **Not Ctrl+Z-undoable** — view-metadata edits publish
-   * directly and do not land on the local undo stack; this matches how the
-   * product's own view-settings UI behaves.
-   *
-   * Label patch semantics (mirroring the product, which stores no label
-   * selection while labels are off):
-   *
-   * - `{ showLabels: true }` alone turns labels on; if the view has no stored
-   *   selection, the product defaults (`objectLabels`, `areas`) are applied —
-   *   labels are never "on" with an empty selection (the product has no such
-   *   state; labels render only while the selection is non-empty).
-   * - `{ labels: [...] }` alone sets the selection **and turns labels on**.
-   * - `{ showLabels: false }` turns labels off and **clears the stored
-   *   selection** — a later read returns `labels: []`.
-   * - `{ showLabels: false, labels: [...] }` with a non-empty list is
-   *   contradictory and **rejected** (nothing is silently discarded).
-   * - `{ showLabels: true, labels: [] }` is likewise contradictory and
-   *   **rejected** — pass a non-empty list, or omit `labels` to get the
-   *   defaults.
-   *
-   * `colorMode` accepts the `tag:<categoryId>` scheme strings returned by
-   * {@linkcode PluginPresentationViewsApi.getSettings}, so read-then-write
-   * round-trips a tag-based color scheme unchanged.
-   *
-   * `viewMode` (`"perspective"` | `"isometric"`) applies to **3D views only** —
-   * a 2D plan is always orthographic, so a `viewMode: "perspective"` patch on a
-   * 2D view is rejected. `"isometric"` on a 2D plan is accepted as a no-op (the
-   * plan is already orthographic), so writing back exactly what
-   * {@linkcode PluginPresentationViewsApi.getSettings} returned is always a
-   * no-op. On the active view the camera switches projection live (the same
-   * toggle the view-settings modal runs); on other views the mode is applied
-   * the next time the view is activated.
-   *
-   * @param viewId - The id of the view to update.
-   * @param settings - A partial {@linkcode PluginPresentationViewSettings}; any
-   *   omitted field is left unchanged.
-   * @returns The updated view's `id`.
-   * @throws If writes are disabled, no view has the given id, the patch is
-   *   contradictory (`showLabels: false` with a non-empty `labels`, or
-   *   `showLabels: true` with an explicitly empty `labels` list), or
-   *   `viewMode: "perspective"` is patched on a 2D plan view.
-   *
-   * @examplePrompt Switch this view to monochrome color mode
-   * @examplePrompt Turn off the axis in the Ground Floor view
-   * @examplePrompt Set the background of the active view to white
-   * @examplePrompt Show area labels on this view
-   * @examplePrompt Enable hidden-line mode for the section view
-   * @examplePrompt Make the 3D view orthographic instead of perspective
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.views.updateSettings("view_123", {
-   *   colorMode: "monochrome",
-   *   showAxis: false,
-   * })
-   * // switch a 3D view to an isometric (orthographic) projection
-   * await snaptrude.presentation.views.updateSettings("view_123", {
-   *   viewMode: "isometric",
-   * })
-   * ```
-   */
-  public abstract updateSettings(
-    viewId: string,
-    settings: Partial<PluginPresentationViewSettings>,
-  ): PluginApiReturn<PluginPresentationViewsUpdateSettingsResult>
-
-  /**
-   * Rename a saved view.
-   *
-   * Sets the view's display name — the same label the views panel shows and
-   * that `list`/`get` read back. Names must be unique within the proposal and
-   * cannot contain the characters `\ : { } [ ] | ; < > ? ~`.
-   *
-   * @param viewId - The id of the view to rename.
-   * @param name - The new display name (non-empty after trimming).
-   * @returns The updated {@linkcode PluginPresentationView}.
-   * @throws If writes are disabled, no view has the given id, the name is
-   *   empty/invalid, or another view in the proposal already has that name.
-   *
-   * @examplePrompt Rename the view Lobby to Entrance Lobby
-   * @examplePrompt Call this view Ground Floor Plan
-   * @examplePrompt Change the active view's name to Final
-   *
-   * # Example
-   * ```ts
-   * const view = await snaptrude.presentation.views.rename("view_123", "Entrance")
-   * ```
-   */
-  public abstract rename(
-    viewId: string,
-    name: string,
-  ): PluginApiReturn<PluginPresentationViewsRenameResult>
-
-  /**
-   * Delete a saved view.
-   *
-   * Removes the view from the project and the views panel (the panel's own
-   * delete action). If the deleted view was active, the product falls back to
-   * the default plan/3D view. Default views (the built-in plan/3D/site-plan
-   * entries) cannot be deleted.
-   *
-   * @param viewId - The id of the view to delete.
-   * @returns The id of the deleted view
-   *   (a {@linkcode PluginPresentationViewsDeleteResult}).
-   * @throws If writes are disabled, no view has the given id, or the view is a
-   *   default view.
-   *
-   * @examplePrompt Delete the view named Old Draft
-   * @examplePrompt Remove this saved view
-   * @examplePrompt Get rid of the Lobby camera bookmark
-   *
-   * # Example
-   * ```ts
-   * const { id } = await snaptrude.presentation.views.delete("view_123")
-   * ```
-   */
-  public abstract delete(
-    viewId: string,
-  ): PluginApiReturn<PluginPresentationViewsDeleteResult>
-}
-
-/**
- * The kind of a saved view: a 2D plan view or a 3D view.
- */
-export const PluginPresentationViewType = z.enum(["2d", "3d"])
-export type PluginPresentationViewType = z.infer<
-  typeof PluginPresentationViewType
->
-
-/**
- * A saved presentation view.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Unique view id |
- * | `name` | `string` | Display name |
- * | `type` | `"2d" \| "3d"` | Whether this is a 2D plan view or a 3D view |
- * | `isActive` | `boolean` | Whether this view is the currently active view |
- * | `storey` | `number \| null` | The storey this view was saved on (`null` on older views saved without one) |
- */
-export const PluginPresentationView = z.object({
-  id: z.string(),
-  name: z.string(),
-  type: PluginPresentationViewType,
-  isActive: z.boolean(),
-  storey: z.number().nullable(),
-})
-export type PluginPresentationView = z.infer<typeof PluginPresentationView>
-
-/**
- * Result of {@linkcode PluginPresentationViewsApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `views` | {@linkcode PluginPresentationView}`[]` | All saved views in the project |
- */
-export const PluginPresentationViewsListResult = z.object({
-  views: z.array(PluginPresentationView),
-})
-export type PluginPresentationViewsListResult = z.infer<
-  typeof PluginPresentationViewsListResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The id of the view to read |
- */
-export const PluginPresentationViewsGetArgs = z.object({
-  id: z.string(),
-})
-export type PluginPresentationViewsGetArgs = z.infer<
-  typeof PluginPresentationViewsGetArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationViewsApi.get} and
- * {@linkcode PluginPresentationViewsApi.getActive} — the view, or `null` when
- * there is no match / no active view.
- */
-export const PluginPresentationViewsGetResult =
-  PluginPresentationView.nullable()
-export type PluginPresentationViewsGetResult = z.infer<
-  typeof PluginPresentationViewsGetResult
->
-
-/** Image format for {@linkcode PluginPresentationViewsApi.capture}. */
-export const PluginPresentationImageFormat = z.enum(["png", "jpeg"])
-export type PluginPresentationImageFormat = z.infer<
-  typeof PluginPresentationImageFormat
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.capture}. All optional.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `viewId` | `string \| undefined` | Capture this saved view; omit to capture the current viewport |
- * | `format` | `"png" \| "jpeg" \| undefined` | Output image format (default `"png"`) |
- * | `resolution` | `string \| undefined` | Optional resolution hint (e.g. `"1280x720"`) |
- */
-export const PluginPresentationViewsCaptureArgs = z.object({
-  viewId: z.string().optional(),
-  format: PluginPresentationImageFormat.optional(),
-  resolution: z.string().optional(),
-})
-export type PluginPresentationViewsCaptureArgs = z.infer<
-  typeof PluginPresentationViewsCaptureArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationViewsApi.capture}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `image` | `string` | The captured image as a base64 data URL |
- */
-export const PluginPresentationViewsCaptureResult = z.object({
-  image: z.string(),
-})
-export type PluginPresentationViewsCaptureResult = z.infer<
-  typeof PluginPresentationViewsCaptureResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.setActive}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The id of the view to activate |
- */
-export const PluginPresentationViewsSetActiveArgs = z.object({
-  id: z.string(),
-})
-export type PluginPresentationViewsSetActiveArgs = z.infer<
-  typeof PluginPresentationViewsSetActiveArgs
->
-
-/** Result of {@linkcode PluginPresentationViewsApi.setActive} — the active view's id. */
-export const PluginPresentationViewsSetActiveResult = z.object({
-  id: z.string(),
-})
-export type PluginPresentationViewsSetActiveResult = z.infer<
-  typeof PluginPresentationViewsSetActiveResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.create}. All optional.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `name` | `string \| undefined` | Name for the new view (a default is used when omitted) |
- * | `kind` | `"view" \| "sitePlan" \| undefined` | What kind of view to save (default `"view"`). `"plan"` is not offered — the host cannot create a plan view without a `planId` this API does not carry. |
- * | `storey` | `number \| undefined` | Save the view on this storey (activated before capture); defaults to the current active storey |
- */
-export const PluginPresentationViewsCreateArgs = z.object({
-  name: z.string().optional(),
-  kind: z.enum(["view", "sitePlan"]).optional(),
-  storey: z.number().optional(),
-})
-export type PluginPresentationViewsCreateArgs = z.infer<
-  typeof PluginPresentationViewsCreateArgs
->
-
-/** Result of {@linkcode PluginPresentationViewsApi.create} — the saved view. */
-export const PluginPresentationViewsCreateResult = PluginPresentationView
-export type PluginPresentationViewsCreateResult = z.infer<
-  typeof PluginPresentationViewsCreateResult
->
-
-/**
- * How the scene is colored in a view.
- *
- * | Value | Meaning |
- * |---|---|
- * | `monochrome` | Flat single-tone shading |
- * | `texture` | Material textures/colors |
- * | `department` | Colored by department |
- * | `tag:<categoryId>` | Colored by a project tag category (e.g. `tag:ZONE`) |
- *
- * The `tag:<categoryId>` form carries the product's tag-based color schemes
- * losslessly — reading a view that uses one returns the `tag:` string as-is,
- * and writing it back preserves the scheme (read-then-write is safe).
- */
-export const PluginPresentationViewColorMode = z.union([
-  z.enum(["monochrome", "texture", "department"]),
-  z.templateLiteral(["tag:", z.string()]),
-])
-export type PluginPresentationViewColorMode = z.infer<
-  typeof PluginPresentationViewColorMode
->
-
-/**
- * A category of on-canvas labels a view can show.
- *
- * | Value | Meaning |
- * |---|---|
- * | `objectLabels` | Per-object name labels |
- * | `areas` | Area/room labels |
- * | `department` | Department labels |
- */
-export const PluginPresentationViewLabel = z.enum([
-  "objectLabels",
-  "areas",
-  "department",
-])
-export type PluginPresentationViewLabel = z.infer<
-  typeof PluginPresentationViewLabel
->
-
-/**
- * A view's camera projection: perspective, or isometric (orthographic).
- *
- * | Value | Meaning |
- * |---|---|
- * | `perspective` | Perspective projection (vanishing points) |
- * | `isometric` | Orthographic projection (no perspective distortion) |
- *
- * Applies to 3D views; a 2D plan view is always orthographic and reads
- * `"isometric"`.
- */
-export const PluginPresentationViewMode = z.enum(["perspective", "isometric"])
-export type PluginPresentationViewMode = z.infer<
-  typeof PluginPresentationViewMode
->
-
-/**
- * A view's display settings.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `backgroundColor` | `string` | Canvas background as a hex color (e.g. `#ffffff`) |
- * | `colorMode` | {@linkcode PluginPresentationViewColorMode} | How the scene is colored (including `tag:<categoryId>` schemes) |
- * | `viewMode` | {@linkcode PluginPresentationViewMode} | Camera projection — `"perspective"` or `"isometric"` (orthographic). Writable on 3D views only; a 2D plan always reads `"isometric"` and accepts only `"isometric"` (a no-op) |
- * | `showAxis` | `boolean` | Whether the X/Y/Z axes are shown |
- * | `showEdges` | `boolean` | Whether edges are shown; `false` = hidden-line rendering |
- * | `showLabels` | `boolean` | Master label switch — whether on-canvas labels are shown at all. `true` always pairs with a non-empty `labels` selection (labels render only while the selection is non-empty; there is no labels-on-with-empty-selection state) |
- * | `labels` | {@linkcode PluginPresentationViewLabel}`[]` | Which label categories are selected. When `showLabels` is `false` the view stores no selection and this reads `[]` |
- */
-export const PluginPresentationViewSettings = z.object({
-  backgroundColor: z.string(),
-  colorMode: PluginPresentationViewColorMode,
-  viewMode: PluginPresentationViewMode,
-  showAxis: z.boolean(),
-  showEdges: z.boolean(),
-  showLabels: z.boolean(),
-  labels: z.array(PluginPresentationViewLabel),
-})
-export type PluginPresentationViewSettings = z.infer<
-  typeof PluginPresentationViewSettings
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.getSettings}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The id of the view to read settings for |
- */
-export const PluginPresentationViewsGetSettingsArgs = z.object({
-  id: z.string(),
-})
-export type PluginPresentationViewsGetSettingsArgs = z.infer<
-  typeof PluginPresentationViewsGetSettingsArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationViewsApi.getSettings} — the settings,
- * or `null` when no view has that id.
- */
-export const PluginPresentationViewsGetSettingsResult =
-  PluginPresentationViewSettings.nullable()
-export type PluginPresentationViewsGetSettingsResult = z.infer<
-  typeof PluginPresentationViewsGetSettingsResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.updateSettings}. The
- * `settings` patch is partial — any omitted field is left unchanged. A patch
- * pairing `showLabels: false` with a non-empty `labels` list, or
- * `showLabels: true` with an explicitly empty `labels` list, is rejected as
- * contradictory (see the method JSDoc for the full label patch semantics).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The id of the view to update |
- * | `settings` | `Partial<`{@linkcode PluginPresentationViewSettings}`>` | The fields to change |
- */
-export const PluginPresentationViewsUpdateSettingsArgs = z
-  .object({
-    id: z.string(),
-    settings: PluginPresentationViewSettings.partial(),
-  })
-  .refine(
-    (v) =>
-      !(
-        v.settings.showLabels === false && (v.settings.labels?.length ?? 0) > 0
-      ),
-    {
-      message:
-        "Contradictory patch: labels cannot be set while showLabels is false",
-    },
-  )
-  .refine(
-    (v) =>
-      !(
-        v.settings.showLabels === true &&
-        v.settings.labels !== undefined &&
-        v.settings.labels.length === 0
-      ),
-    {
-      message:
-        "Contradictory patch: showLabels cannot be true with an explicitly empty labels list — pass a non-empty list, or omit labels to apply the defaults",
-    },
-  )
-export type PluginPresentationViewsUpdateSettingsArgs = z.infer<
-  typeof PluginPresentationViewsUpdateSettingsArgs
->
-
-/** Result of {@linkcode PluginPresentationViewsApi.updateSettings} — the updated view's id. */
-export const PluginPresentationViewsUpdateSettingsResult = z.object({
-  id: z.string(),
-})
-export type PluginPresentationViewsUpdateSettingsResult = z.infer<
-  typeof PluginPresentationViewsUpdateSettingsResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.rename}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The id of the view to rename |
- * | `name` | `string` | New display name (non-empty after trimming) |
- */
-export const PluginPresentationViewsRenameArgs = z.object({
-  id: z.string(),
-  name: z.string().trim().min(1),
-})
-export type PluginPresentationViewsRenameArgs = z.infer<
-  typeof PluginPresentationViewsRenameArgs
->
-
-/** Result of {@linkcode PluginPresentationViewsApi.rename} — the renamed view. */
-export const PluginPresentationViewsRenameResult = PluginPresentationView
-export type PluginPresentationViewsRenameResult = z.infer<
-  typeof PluginPresentationViewsRenameResult
->
-
-/**
- * Arguments for {@linkcode PluginPresentationViewsApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The id of the view to delete |
- */
-export const PluginPresentationViewsDeleteArgs = z.object({
-  id: z.string(),
-})
-export type PluginPresentationViewsDeleteArgs = z.infer<
-  typeof PluginPresentationViewsDeleteArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationViewsApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Id of the deleted view |
- */
-export const PluginPresentationViewsDeleteResult = z.object({
-  id: z.string(),
-})
-export type PluginPresentationViewsDeleteResult = z.infer<
-  typeof PluginPresentationViewsDeleteResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation views — read the saved plan, 3D, and elevation views used to prepare presentations.
+ *
+ * A **view** is a saved camera/plan: a sheet-ready 2D plan or a saved 3D view.
+ * A plugin can list and read views, capture them to images, activate one (move
+ * the camera to it), save the current camera as a new view, rename or delete a
+ * saved view, and read/update a view's display settings (background, color
+ * mode, view mode, axis, edges, labels). Each view carries the `storey` it was
+ * saved on.
+ *
+ * `list`/`get`/`getActive`/`capture`/`getSettings` are reads;
+ * `setActive`/`create`/`rename`/`delete`/`updateSettings` are writes (a view is
+ * a camera bookmark — not geometry).
+ *
+ * Accessed via `snaptrude.presentation.views`.
+ */
+export abstract class PluginPresentationViewsApi {
+  constructor() {}
+
+  /**
+   * List the saved views in the active project.
+   *
+   * @returns A {@linkcode PluginPresentationViewsListResult} with a `views` array
+   *   of plan, 3D, and elevation views (empty when the project has none).
+   *
+   * @examplePrompt List all the saved views
+   * @examplePrompt What plan, 3D, and elevation views are in this project?
+   * @examplePrompt Which view is currently active?
+   * @examplePrompt Get the names of every presentation view
+   * @examplePrompt Show me the 3D views I can put on a sheet
+   *
+   * # Example
+   * ```ts
+   * const { views } = await snaptrude.presentation.views.list()
+   * const active = views.find((v) => v.isActive)
+   * const plans = views.filter((v) => v.type === "2d")
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginPresentationViewsListResult>
+
+  /**
+   * Get a single saved view by id.
+   *
+   * @param viewId - The id of the view to read.
+   * @returns The matching {@linkcode PluginPresentationView}, or `null` if no view
+   *   has that id.
+   *
+   * @examplePrompt Get the view with id view_12345
+   * @examplePrompt Find the saved view called Ground Floor Plan
+   * @examplePrompt Look up a presentation view by its id
+   *
+   * # Example
+   * ```ts
+   * const view = await snaptrude.presentation.views.get("view_123")
+   * ```
+   */
+  public abstract get(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsGetResult>
+
+  /**
+   * Get the currently active view.
+   *
+   * @returns The active {@linkcode PluginPresentationView}, or `null` if none is
+   *   active.
+   *
+   * @examplePrompt Which view is active right now?
+   * @examplePrompt Get the current view
+   * @examplePrompt What view am I looking at?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.presentation.views.getActive()
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<PluginPresentationViewsGetResult>
+
+  /**
+   * Capture a screenshot of a view as a base64 image.
+   *
+   * Captures the **current** viewport by default; pass `viewId` to capture a
+   * specific saved view (which briefly applies that view to the scene). Use
+   * `format`/`resolution` to control the output. This shoots the Design (3D)
+   * canvas; to screenshot the Present canvas use
+   * {@linkcode PluginPresentationCameraApi.capture}.
+   *
+   * @param options - All optional: `viewId` (capture this saved view; omit for the
+   *   current viewport), `format` (default `"png"`), `resolution` (e.g. `"1280x720"`).
+   * @returns A {@linkcode PluginPresentationViewsCaptureResult} with the base64
+   *   `image` data URL.
+   * @throws If a given `viewId` does not exist.
+   *
+   * @examplePrompt Take a screenshot of the current view
+   * @examplePrompt Capture this view as a PNG
+   * @examplePrompt Render the Site Plan view to an image
+   * @examplePrompt Export a high-res image of what I'm looking at
+   *
+   * # Example
+   * ```ts
+   * const { image } = await snaptrude.presentation.views.capture({ format: "png" })
+   * ```
+   */
+  public abstract capture(options?: {
+    viewId?: string
+    format?: "png" | "jpeg"
+    resolution?: string
+  }): PluginApiReturn<PluginPresentationViewsCaptureResult>
+
+  /**
+   * Activate a saved view — move the camera to it and restore its scene state.
+   *
+   * Applies the view's camera, visibility, and storey state to the live scene.
+   * Paired with {@linkcode PluginPresentationViewsApi.getActive}.
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @param viewId - The id of the view to activate.
+   * @returns The id of the now-active view.
+   * @throws If no view has the given id.
+   *
+   * @examplePrompt Switch to the Ground Floor plan view
+   * @examplePrompt Make the 3D view active
+   * @examplePrompt Go to the view named Entrance
+   * @examplePrompt Load the site plan view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.views.setActive("view_123")
+   * ```
+   */
+  public abstract setActive(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsSetActiveResult>
+
+  /**
+   * Save the current camera/scene state as a new named view.
+   *
+   * Creates a camera bookmark (not geometry) from where the camera is now.
+   *
+   * Works while Present mode is open. Present draws its drawings on the same
+   * 3D scene, so a view saved in Present takes its framing (camera, 2D or 3D
+   * mode, projection, storey, building) from the Design frame instead: the one
+   * the user had when Present opened, or one a plugin set since with
+   * `setActive`, `updateSettings({ viewMode })`, `core.camera`, `core.zoom`,
+   * `core.storeys.setActive`, `core.storeys.layers.setActive` or
+   * `core.buildings.setActive`. It never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @param name - Name for the new view (a default is used when omitted).
+   * @param options - Optional `kind` (what kind of view to save, default
+   *   `"view"`) and `storey` (save the view on a specific storey — the storey is
+   *   activated first, matching the storey the view is captured on; when omitted
+   *   the current active storey is used).
+   * @returns The newly created {@linkcode PluginPresentationView}.
+   * @throws If `storey` is given but no such storey exists, or the view could
+   *   not be saved.
+   *
+   * @examplePrompt Save the current view as Lobby Perspective
+   * @examplePrompt Create a new saved view from where I'm looking
+   * @examplePrompt Bookmark this camera angle
+   * @examplePrompt Save the current 2D plan as a view
+   * @examplePrompt Save a view on the second storey
+   *
+   * # Example
+   * ```ts
+   * const view = await snaptrude.presentation.views.create("Lobby")
+   * // …or capture the view on a specific storey
+   * const level2 = await snaptrude.presentation.views.create("Level 2", { storey: 2 })
+   * ```
+   */
+  public abstract create(
+    name?: string,
+    options?: { kind?: "view" | "sitePlan"; storey?: number },
+  ): PluginApiReturn<PluginPresentationViewsCreateResult>
+
+  /**
+   * Read a saved view's display settings (background, color mode, view mode,
+   * axis, edges, labels).
+   *
+   * @param viewId - The id of the view to read settings for.
+   * @returns The view's {@linkcode PluginPresentationViewSettings}, or `null` if
+   *   no view has that id. A plan view also reports its `cutPlaneHeight`,
+   *   `viewDepthStorey` and `showOverheadObjects` (saved values, or the product
+   *   defaults for a plan saved before cut ranges existed); other views omit them.
+   *
+   * @examplePrompt What color mode is the Ground Floor view using?
+   * @examplePrompt Get the display settings for this view
+   * @examplePrompt Does the site plan view show axes and labels?
+   * @examplePrompt Read the background color of the active view
+   * @examplePrompt What is the cut height of this plan?
+   * @examplePrompt How deep does this plan look below the cut?
+   *
+   * # Example
+   * ```ts
+   * const settings = await snaptrude.presentation.views.getSettings("view_123")
+   * if (settings) console.log(settings.colorMode, settings.backgroundColor)
+   * ```
+   */
+  public abstract getSettings(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsGetSettingsResult>
+
+  /**
+   * Update a saved view's display settings (partial patch — only the fields you
+   * pass change).
+   *
+   * Persists and broadcasts the change; if the view is currently active, the
+   * scene updates live. **Not Ctrl+Z-undoable** — view-metadata edits publish
+   * directly and do not land on the local undo stack; this matches how the
+   * product's own view-settings UI behaves.
+   *
+   * Label patch semantics (mirroring the product, which stores no label
+   * selection while labels are off):
+   *
+   * - `{ showLabels: true }` alone turns labels on; if the view has no stored
+   *   selection, the product defaults (`objectLabels`, `areas`) are applied —
+   *   labels are never "on" with an empty selection (the product has no such
+   *   state; labels render only while the selection is non-empty).
+   * - `{ labels: [...] }` alone sets the selection **and turns labels on**.
+   * - `{ showLabels: false }` turns labels off and **clears the stored
+   *   selection** — a later read returns `labels: []`.
+   * - `{ showLabels: false, labels: [...] }` with a non-empty list is
+   *   contradictory and **rejected** (nothing is silently discarded).
+   * - `{ showLabels: true, labels: [] }` is likewise contradictory and
+   *   **rejected** — pass a non-empty list, or omit `labels` to get the
+   *   defaults.
+   *
+   * `colorMode` accepts the `tag:<categoryId>` scheme strings returned by
+   * {@linkcode PluginPresentationViewsApi.getSettings}, so read-then-write
+   * round-trips a tag-based color scheme unchanged.
+   *
+   * `viewMode` (`"perspective"` | `"isometric"`) applies to **3D views only** —
+   * a 2D plan is always orthographic, so a `viewMode: "perspective"` patch on a
+   * 2D view is rejected. `"isometric"` on a 2D plan is accepted as a no-op (the
+   * plan is already orthographic), so writing back exactly what
+   * {@linkcode PluginPresentationViewsApi.getSettings} returned is always a
+   * no-op. On the active view the camera switches projection live (the same
+   * toggle the view-settings modal runs); on other views the mode is applied
+   * the next time the view is activated.
+   *
+   * `cutPlaneHeight`, `viewDepthStorey` and `showOverheadObjects` set the plan's
+   * cut range and apply to **plan views only** (patching them on a 3D, elevation
+   * or site-plan view is rejected). `cutPlaneHeight` is in engine units, the same
+   * unit as `story.height`, and must be greater than 0 and less than the plan
+   * storey's height. `viewDepthStorey` must be an existing storey at or below the
+   * plan's storey. A sparse patch leaves the other two range fields as they
+   * were; on the active plan the canvas redraws live.
+   *
+   * @param viewId - The id of the view to update.
+   * @param settings - A partial {@linkcode PluginPresentationViewSettings}; any
+   *   omitted field is left unchanged.
+   * @returns The updated view's `id`.
+   * @throws If writes are disabled, no view has the given id, the patch is
+   *   contradictory (`showLabels: false` with a non-empty `labels`, or
+   *   `showLabels: true` with an explicitly empty `labels` list),
+   *   `viewMode: "perspective"` is patched on a 2D plan view, a plan-range
+   *   field is patched on a view that is not a plan, or the cut height / depth
+   *   is out of range.
+   *
+   * @examplePrompt Switch this view to monochrome color mode
+   * @examplePrompt Turn off the axis in the Ground Floor view
+   * @examplePrompt Set the background of the active view to white
+   * @examplePrompt Show area labels on this view
+   * @examplePrompt Enable hidden-line mode for the section view
+   * @examplePrompt Make the 3D view orthographic instead of perspective
+   * @examplePrompt Raise the cut plane of the Ground Floor plan to 1.8 m
+   * @examplePrompt Show the basement below in this plan
+   * @examplePrompt Hide the overhead objects in this plan
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.views.updateSettings("view_123", {
+   *   colorMode: "monochrome",
+   *   showAxis: false,
+   * })
+   * // switch a 3D view to an isometric (orthographic) projection
+   * await snaptrude.presentation.views.updateSettings("view_123", {
+   *   viewMode: "isometric",
+   * })
+   * // set a plan's range: cut 1.2 m up, show the basement below, no overhead
+   * await snaptrude.presentation.views.updateSettings("plan_1", {
+   *   cutPlaneHeight: 4.72,
+   *   viewDepthStorey: -1,
+   *   showOverheadObjects: false,
+   * })
+   * ```
+   */
+  public abstract updateSettings(
+    viewId: string,
+    settings: Partial<PluginPresentationViewSettings>,
+  ): PluginApiReturn<PluginPresentationViewsUpdateSettingsResult>
+
+  /**
+   * Rename a saved view.
+   *
+   * Sets the view's display name — the same label the views panel shows and
+   * that `list`/`get` read back. Names must be unique within the proposal and
+   * cannot contain the characters `\ : { } [ ] | ; < > ? ~`.
+   *
+   * @param viewId - The id of the view to rename.
+   * @param name - The new display name (non-empty after trimming).
+   * @returns The updated {@linkcode PluginPresentationView}.
+   * @throws If writes are disabled, no view has the given id, the name is
+   *   empty/invalid, or another view in the proposal already has that name.
+   *
+   * @examplePrompt Rename the view Lobby to Entrance Lobby
+   * @examplePrompt Call this view Ground Floor Plan
+   * @examplePrompt Change the active view's name to Final
+   *
+   * # Example
+   * ```ts
+   * const view = await snaptrude.presentation.views.rename("view_123", "Entrance")
+   * ```
+   */
+  public abstract rename(
+    viewId: string,
+    name: string,
+  ): PluginApiReturn<PluginPresentationViewsRenameResult>
+
+  /**
+   * Delete a saved view.
+   *
+   * Removes the view from the project and the views panel (the panel's own
+   * delete action). If the deleted view was active, the product falls back to
+   * the default plan/3D view. Default views (the built-in plan/3D/site-plan
+   * entries) cannot be deleted.
+   *
+   * @param viewId - The id of the view to delete.
+   * @returns The id of the deleted view
+   *   (a {@linkcode PluginPresentationViewsDeleteResult}).
+   * @throws If writes are disabled, no view has the given id, or the view is a
+   *   default view.
+   *
+   * @examplePrompt Delete the view named Old Draft
+   * @examplePrompt Remove this saved view
+   * @examplePrompt Get rid of the Lobby camera bookmark
+   *
+   * # Example
+   * ```ts
+   * const { id } = await snaptrude.presentation.views.delete("view_123")
+   * ```
+   */
+  public abstract delete(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsDeleteResult>
+}
+
+/**
+ * The rendering category of a saved view. Existing plan/3D values are preserved;
+ * elevations are identified independently of their orthographic 3D camera.
+ */
+export const PluginPresentationViewType = z.enum(["2d", "3d", "elevation"])
+export type PluginPresentationViewType = z.infer<
+  typeof PluginPresentationViewType
+>
+
+/** The native semantic kind persisted for a saved view. */
+export const PluginPresentationViewKind = z.enum([
+  "plan",
+  "sitePlan",
+  "threeD",
+  "elevation",
+])
+export type PluginPresentationViewKind = z.infer<
+  typeof PluginPresentationViewKind
+>
+
+/** Cardinal direction for an elevation; non-elevation views return `null`. */
+export const PluginPresentationElevationDirection = z.enum([
+  "north",
+  "east",
+  "south",
+  "west",
+])
+export type PluginPresentationElevationDirection = z.infer<
+  typeof PluginPresentationElevationDirection
+>
+
+/**
+ * A saved presentation view.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Unique view id |
+ * | `name` | `string` | Display name |
+ * | `type` | `"2d" \| "3d" \| "elevation"` | Rendering category; elevations are distinct from ordinary 3D views |
+ * | `kind` | {@linkcode PluginPresentationViewKind} | Native semantic view kind |
+ * | `direction` | {@linkcode PluginPresentationElevationDirection}` \| null` | Cardinal direction for elevations; otherwise `null` |
+ * | `isActive` | `boolean` | Whether this view is the currently active view |
+ * | `storey` | `number \| null` | The storey this view was saved on (`null` on older views saved without one) |
+ */
+export const PluginPresentationView = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: PluginPresentationViewType,
+  kind: PluginPresentationViewKind,
+  direction: PluginPresentationElevationDirection.nullable(),
+  isActive: z.boolean(),
+  storey: z.number().nullable(),
+})
+export type PluginPresentationView = z.infer<typeof PluginPresentationView>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `views` | {@linkcode PluginPresentationView}`[]` | All saved views in the project |
+ */
+export const PluginPresentationViewsListResult = z.object({
+  views: z.array(PluginPresentationView),
+})
+export type PluginPresentationViewsListResult = z.infer<
+  typeof PluginPresentationViewsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to read |
+ */
+export const PluginPresentationViewsGetArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsGetArgs = z.infer<
+  typeof PluginPresentationViewsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.get} and
+ * {@linkcode PluginPresentationViewsApi.getActive} — the view, or `null` when
+ * there is no match / no active view.
+ */
+export const PluginPresentationViewsGetResult =
+  PluginPresentationView.nullable()
+export type PluginPresentationViewsGetResult = z.infer<
+  typeof PluginPresentationViewsGetResult
+>
+
+/** Image format for {@linkcode PluginPresentationViewsApi.capture}. */
+export const PluginPresentationImageFormat = z.enum(["png", "jpeg"])
+export type PluginPresentationImageFormat = z.infer<
+  typeof PluginPresentationImageFormat
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.capture}. All optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `viewId` | `string \| undefined` | Capture this saved view; omit to capture the current viewport |
+ * | `format` | `"png" \| "jpeg" \| undefined` | Output image format (default `"png"`) |
+ * | `resolution` | `string \| undefined` | Optional resolution hint (e.g. `"1280x720"`) |
+ */
+export const PluginPresentationViewsCaptureArgs = z.object({
+  viewId: z.string().optional(),
+  format: PluginPresentationImageFormat.optional(),
+  resolution: z.string().optional(),
+})
+export type PluginPresentationViewsCaptureArgs = z.infer<
+  typeof PluginPresentationViewsCaptureArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.capture}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `image` | `string` | The captured image as a base64 data URL |
+ */
+export const PluginPresentationViewsCaptureResult = z.object({
+  image: z.string(),
+})
+export type PluginPresentationViewsCaptureResult = z.infer<
+  typeof PluginPresentationViewsCaptureResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to activate |
+ */
+export const PluginPresentationViewsSetActiveArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsSetActiveArgs = z.infer<
+  typeof PluginPresentationViewsSetActiveArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.setActive} — the active view's id. */
+export const PluginPresentationViewsSetActiveResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsSetActiveResult = z.infer<
+  typeof PluginPresentationViewsSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.create}. All optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Name for the new view (a default is used when omitted) |
+ * | `kind` | `"view" \| "sitePlan" \| undefined` | What kind of view to save (default `"view"`). `"plan"` is not offered — the host cannot create a plan view without a `planId` this API does not carry. |
+ * | `storey` | `number \| undefined` | Save the view on this storey (activated before capture); defaults to the current active storey |
+ */
+export const PluginPresentationViewsCreateArgs = z.object({
+  name: z.string().optional(),
+  kind: z.enum(["view", "sitePlan"]).optional(),
+  storey: z.number().optional(),
+})
+export type PluginPresentationViewsCreateArgs = z.infer<
+  typeof PluginPresentationViewsCreateArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.create} — the saved view. */
+export const PluginPresentationViewsCreateResult = PluginPresentationView
+export type PluginPresentationViewsCreateResult = z.infer<
+  typeof PluginPresentationViewsCreateResult
+>
+
+/**
+ * How the scene is colored in a view.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `monochrome` | Flat single-tone shading |
+ * | `texture` | Material textures/colors |
+ * | `department` | Colored by department |
+ * | `tag:<categoryId>` | Colored by a project tag category (e.g. `tag:ZONE`) |
+ *
+ * The `tag:<categoryId>` form carries the product's tag-based color schemes
+ * losslessly — reading a view that uses one returns the `tag:` string as-is,
+ * and writing it back preserves the scheme (read-then-write is safe).
+ */
+export const PluginPresentationViewColorMode = z.union([
+  z.enum(["monochrome", "texture", "department"]),
+  z.templateLiteral(["tag:", z.string()]),
+])
+export type PluginPresentationViewColorMode = z.infer<
+  typeof PluginPresentationViewColorMode
+>
+
+/**
+ * A category of on-canvas labels a view can show.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `objectLabels` | Per-object name labels |
+ * | `areas` | Area/room labels |
+ * | `department` | Department labels |
+ */
+export const PluginPresentationViewLabel = z.enum([
+  "objectLabels",
+  "areas",
+  "department",
+])
+export type PluginPresentationViewLabel = z.infer<
+  typeof PluginPresentationViewLabel
+>
+
+/**
+ * A view's camera projection: perspective, or isometric (orthographic).
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `perspective` | Perspective projection (vanishing points) |
+ * | `isometric` | Orthographic projection (no perspective distortion) |
+ *
+ * Applies to 3D views; a 2D plan view is always orthographic and reads
+ * `"isometric"`.
+ */
+export const PluginPresentationViewMode = z.enum(["perspective", "isometric"])
+export type PluginPresentationViewMode = z.infer<
+  typeof PluginPresentationViewMode
+>
+
+/**
+ * A view's display settings.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `backgroundColor` | `string` | Canvas background as a hex color (e.g. `#ffffff`) |
+ * | `colorMode` | {@linkcode PluginPresentationViewColorMode} | How the scene is colored (including `tag:<categoryId>` schemes) |
+ * | `viewMode` | {@linkcode PluginPresentationViewMode} | Camera projection — `"perspective"` or `"isometric"` (orthographic). Writable on 3D views only; a 2D plan always reads `"isometric"` and accepts only `"isometric"` (a no-op) |
+ * | `showAxis` | `boolean` | Whether the X/Y/Z axes are shown |
+ * | `showEdges` | `boolean` | Whether edges are shown; `false` = hidden-line rendering |
+ * | `showLabels` | `boolean` | Master label switch — whether on-canvas labels are shown at all. `true` always pairs with a non-empty `labels` selection (labels render only while the selection is non-empty; there is no labels-on-with-empty-selection state) |
+ * | `labels` | {@linkcode PluginPresentationViewLabel}`[]` | Which label categories are selected. When `showLabels` is `false` the view stores no selection and this reads `[]` |
+ * | `cutPlaneHeight` | `number`? | **Plan views only.** Height of the plan's cut plane above its storey base, in engine units (the unit `story.height` uses). Absent on 3D and elevation views |
+ * | `viewDepthStorey` | `number`? | **Plan views only.** The lowest storey the plan shows below the cut; defaults to the plan's own storey. Absent on 3D and elevation views |
+ * | `showOverheadObjects` | `boolean`? | **Plan views only.** Whether objects above the cut are drawn as dashed overhead linework. Absent on 3D and elevation views |
+ */
+export const PluginPresentationViewSettings = z.object({
+  backgroundColor: z.string(),
+  colorMode: PluginPresentationViewColorMode,
+  viewMode: PluginPresentationViewMode,
+  showAxis: z.boolean(),
+  showEdges: z.boolean(),
+  showLabels: z.boolean(),
+  labels: z.array(PluginPresentationViewLabel),
+  cutPlaneHeight: z.number().finite().positive().optional(),
+  viewDepthStorey: z.number().int().optional(),
+  showOverheadObjects: z.boolean().optional(),
+})
+export type PluginPresentationViewSettings = z.infer<
+  typeof PluginPresentationViewSettings
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.getSettings}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to read settings for |
+ */
+export const PluginPresentationViewsGetSettingsArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsGetSettingsArgs = z.infer<
+  typeof PluginPresentationViewsGetSettingsArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.getSettings} — the settings,
+ * or `null` when no view has that id.
+ */
+export const PluginPresentationViewsGetSettingsResult =
+  PluginPresentationViewSettings.nullable()
+export type PluginPresentationViewsGetSettingsResult = z.infer<
+  typeof PluginPresentationViewsGetSettingsResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.updateSettings}. The
+ * `settings` patch is partial — any omitted field is left unchanged. A patch
+ * pairing `showLabels: false` with a non-empty `labels` list, or
+ * `showLabels: true` with an explicitly empty `labels` list, is rejected as
+ * contradictory (see the method JSDoc for the full label patch semantics).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to update |
+ * | `settings` | `Partial<`{@linkcode PluginPresentationViewSettings}`>` | The fields to change |
+ */
+export const PluginPresentationViewsUpdateSettingsArgs = z
+  .object({
+    id: z.string(),
+    settings: PluginPresentationViewSettings.partial(),
+  })
+  .refine(
+    (v) =>
+      !(
+        v.settings.showLabels === false && (v.settings.labels?.length ?? 0) > 0
+      ),
+    {
+      message:
+        "Contradictory patch: labels cannot be set while showLabels is false",
+    },
+  )
+  .refine(
+    (v) =>
+      !(
+        v.settings.showLabels === true &&
+        v.settings.labels !== undefined &&
+        v.settings.labels.length === 0
+      ),
+    {
+      message:
+        "Contradictory patch: showLabels cannot be true with an explicitly empty labels list — pass a non-empty list, or omit labels to apply the defaults",
+    },
+  )
+export type PluginPresentationViewsUpdateSettingsArgs = z.infer<
+  typeof PluginPresentationViewsUpdateSettingsArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.updateSettings} — the updated view's id. */
+export const PluginPresentationViewsUpdateSettingsResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsUpdateSettingsResult = z.infer<
+  typeof PluginPresentationViewsUpdateSettingsResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to rename |
+ * | `name` | `string` | New display name (non-empty after trimming) |
+ */
+export const PluginPresentationViewsRenameArgs = z.object({
+  id: z.string(),
+  name: z.string().trim().min(1),
+})
+export type PluginPresentationViewsRenameArgs = z.infer<
+  typeof PluginPresentationViewsRenameArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.rename} — the renamed view. */
+export const PluginPresentationViewsRenameResult = PluginPresentationView
+export type PluginPresentationViewsRenameResult = z.infer<
+  typeof PluginPresentationViewsRenameResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to delete |
+ */
+export const PluginPresentationViewsDeleteArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsDeleteArgs = z.infer<
+  typeof PluginPresentationViewsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Id of the deleted view |
+ */
+export const PluginPresentationViewsDeleteResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsDeleteResult = z.infer<
+  typeof PluginPresentationViewsDeleteResult
+>