@snaptrude/plugin-core 0.8.0 → 0.9.1

package/src/api/presentation/placedViews.ts

@@ -0,0 +1,1120 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginSheetPosition } from "./sheets"
+
+/**
+ * Placed views — the view shapes already laid out on the Present canvas.
+ *
+ * A **placed view** is a saved view that has been dropped onto a layout sheet
+ * (or the open canvas) — the live linked view shape
+ * {@linkcode PluginPresentationSheetsApi.place} and the Present views panel's
+ * drag-drop create. These methods read and edit the **layout** of those
+ * shapes: where they sit, how big they are, their rotation, their
+ * architectural scale, and their crop. To refresh a placed view's **content** from the current model,
+ * use `sheets.updatePlacedView` — content refresh lives on `sheets`,
+ * layout lives here.
+ *
+ * Reads (`list`) return `[]` when Present mode is closed; `get` and every
+ * write require Present mode to be open.
+ *
+ * Accessed via `snaptrude.presentation.placedViews`.
+ */
+export abstract class PluginPresentationPlacedViewsApi {
+  constructor() {}
+
+  /**
+   * List the placed views in the presentation.
+   *
+   * Returns every placed view shape on the Present canvas — those nested on a
+   * layout sheet (with that sheet's id) and those sitting loose on the canvas
+   * (`sheetId: null`). Pass `sheetId` to list only the views placed on that
+   * sheet.
+   *
+   * @param sheetId - Optional sheet id to filter by.
+   * @returns A {@linkcode PluginPresentationPlacedViewsListResult} with a
+   *   `placedViews` array (empty when Present mode is closed or nothing is
+   *   placed).
+   * @throws If `sheetId` is given but is not a sheet (with Present mode open).
+   *
+   * @examplePrompt Which views are placed on this sheet?
+   * @examplePrompt List all the placed views in the presentation
+   * @examplePrompt What's laid out on sheet 2?
+   * @examplePrompt Show me every view on the Present canvas
+   *
+   * # Example
+   * ```ts
+   * const { placedViews } = await snaptrude.presentation.placedViews.list("sheet_1")
+   * ```
+   */
+  public abstract list(
+    sheetId?: string,
+  ): PluginApiReturn<PluginPresentationPlacedViewsListResult>
+
+  /**
+   * Get a single placed view by its shape id.
+   *
+   * `shapeId` is the id `sheets.place` returned (also reported by `list`).
+   *
+   * @param shapeId - The id of the placed view shape to read.
+   * @returns The matching {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, or `shapeId` is unknown or is not a
+   *   placed view.
+   *
+   * @examplePrompt Get the placed view I just dropped on the sheet
+   * @examplePrompt Read the position and scale of this placed view
+   * @examplePrompt What's the crop on shape_123?
+   *
+   * # Example
+   * ```ts
+   * const placed = await snaptrude.presentation.placedViews.get(shapeId)
+   * console.log(placed.position, placed.scale)
+   * ```
+   */
+  public abstract get(shapeId: string): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Move a placed view.
+   *
+   * Repositions the placed view on its sheet — `position` is the new top-left
+   * in sheet coordinates (page coordinates when the view is not on a sheet).
+   * Pass `options.sheetId` to move it onto another sheet: the view is
+   * reparented to that sheet and then positioned at `position` in the new
+   * sheet's coordinates. A grouped placed view (e.g. a sustainability 3D view
+   * with its legend) moves as one unit. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to move.
+   * @param position - New top-left position (sheet-local; page coordinates
+   *   when off-sheet).
+   * @param options - Optional `sheetId` — move the view onto that sheet.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `options.sheetId` is given but is not a sheet.
+   *
+   * @examplePrompt Move the site plan view to the top-left of sheet 2
+   * @examplePrompt Reposition this placed view to 100, 200
+   * @examplePrompt Move the hero perspective onto the cover sheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.move(shapeId, { x: 50, y: 50 }, {
+   *   sheetId: "sheet_2",
+   * })
+   * ```
+   */
+  public abstract move(
+    shapeId: string,
+    position: PluginSheetPosition,
+    options?: { sheetId?: string },
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Resize a placed view by a uniform factor.
+   *
+   * Scales the placed view about its top-left corner — the same resize as
+   * dragging a corner handle, aspect ratio held. Works for 2D and 3D views;
+   * labels and grouped legends resize with it. For a 2D view the **printed
+   * architectural scale changes proportionally** (doubling the size of a
+   * 1:100 plan makes it a 1:50 plan) — use
+   * {@linkcode PluginPresentationPlacedViewsApi.setScale} to land on an exact
+   * standard scale instead. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to resize.
+   * @param factor - Uniform scale factor, between `0.01` and `100`
+   *   (`2` doubles the size, `0.5` halves it).
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `factor` is not a finite number between 0.01 and 100.
+   *
+   * @examplePrompt Make this placed view twice as big
+   * @examplePrompt Shrink the placed 3D view to half its size
+   * @examplePrompt Scale the placed plan up by 50%
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.scale(shapeId, 2)
+   * ```
+   */
+  public abstract scale(
+    shapeId: string,
+    factor: number,
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Set a placed view's architectural scale.
+   *
+   * Applies a standard architectural scale — the same write the placed view's
+   * Scale dropdown performs. The view (and its labels) is resized about its
+   * top-left corner so it prints at the given scale. `scale` must be one of
+   * the standard values for the project's unit system (metric `10, 20, 50,
+   * 100, 150, 200, 250, 500, 1000`; imperial e.g. `48` for 1/4″ = 1′, `96`
+   * for 1/8″ = 1′, `120` for 1″ = 10′) — the same validation as
+   * `sheets.place`. 3D views have no architectural scale — calling this on
+   * one throws. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to set the scale of.
+   * @param scale - A standard scale value for the project's unit system.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, `scale` is not a standard value for the project's unit
+   *   system, or the placed view is a 3D view.
+   *
+   * @examplePrompt Set the plan to 1:100
+   * @examplePrompt Change the placed floor plan to 1:50 scale
+   * @examplePrompt Make this view print at quarter-inch scale
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.setScale(shapeId, 100) // 1:100
+   * ```
+   */
+  public abstract setScale(
+    shapeId: string,
+    scale: number,
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Crop a placed view, or clear its crop.
+   *
+   * `crop` selects the visible window as **fractions (0–1) of the uncropped
+   * view** — `topLeft` must be strictly less than `bottomRight` on both axes.
+   * The visible region stays anchored on the page (the same behavior as the
+   * interactive crop), labels that fall outside the crop are hidden, and the
+   * view's architectural scale is untouched. Pass `null` to clear the crop
+   * and restore the full view in its uncropped footprint (the interactive
+   * double-click-edge reset). The crop **survives a content refresh**
+   * (`sheets.updatePlacedView` recomputes it against the refreshed content
+   * and only clears it when the refreshed view no longer overlaps the cropped
+   * region). Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to crop.
+   * @param crop - The crop window ({@linkcode PluginPlacedViewCrop},
+   *   fractions of the uncropped view), or `null` to clear.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `crop` is not a valid 0–1 rectangle with
+   *   `topLeft < bottomRight` on both axes.
+   *
+   * @examplePrompt Crop the placed view to its left half
+   * @examplePrompt Crop this view to the top-right quarter
+   * @examplePrompt Remove the crop from the placed plan
+   *
+   * # Example
+   * ```ts
+   * // keep the left half of the view
+   * await snaptrude.presentation.placedViews.setCrop(shapeId, {
+   *   topLeft: { x: 0, y: 0 },
+   *   bottomRight: { x: 0.5, y: 1 },
+   * })
+   * await snaptrude.presentation.placedViews.setCrop(shapeId, null) // clear
+   * ```
+   */
+  public abstract setCrop(
+    shapeId: string,
+    crop: PluginPlacedViewCrop | null,
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Set a placed view's rotation.
+   *
+   * `rotation` is the **absolute** angle in radians (tldraw convention) — the
+   * value the record's `rotation` field reads back. Values are canonicalized
+   * into `[0, 2π)`, so pass values in that range for an exact round-trip
+   * (`setRotation(-0.1)` reads back as `2π − 0.1`). The view rotates about
+   * its bounds center (the same pivot as the UI rotation handle). One undo
+   * step. Joins the absolute-setter family
+   * `setScale`/`setCrop`/`setOpacity`/`setMask`.
+   *
+   * **3D placed views only.** 2D and site-plan views cannot rotate — the
+   * canvas hides their rotate handle and reverts any rotation applied to
+   * them — so calling this on one is refused with a typed
+   * `PRECONDITION_FAILED` instead of silently no-opping. Requires Present
+   * mode to be open.
+   *
+   * @param shapeId - The placed view shape to rotate.
+   * @param rotation - Absolute rotation in radians.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, `rotation` is not a finite number, or the placed view is
+   *   a 2D/site-plan view (`PRECONDITION_FAILED` — only 3D views rotate).
+   *
+   * @examplePrompt Rotate the placed plan 90 degrees
+   * @examplePrompt Set this view's rotation to 45 degrees
+   * @examplePrompt Straighten the placed view back to zero rotation
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.setRotation(shapeId, Math.PI / 2)
+   * ```
+   */
+  public abstract setRotation(
+    shapeId: string,
+    rotation: number,
+  ): PluginApiReturn<PluginPlacedView>
+
+  // ── Present-mode styling ──────────────────────────────────────────────────
+
+  /**
+   * Read a placed view's (or sheet's) per-category presentation styles.
+   *
+   * Returns one entry per style category (Site, Topography, Space, Department,
+   * Envelope, Facade/Mass, Dimension, Reference Line, Adjacency Line,
+   * Landscape elements — sheets/auto-diagrams use their 3-category subset)
+   * with the **fully-resolved** setting values (defaults merged with this
+   * shape's overrides), which setting ids the category supports, whether the
+   * category is currently disabled (not visible in the view), and — where the
+   * category has a Text tab — its label font styles. Styles are stored **per
+   * placed shape instance**: the same saved view placed twice can read
+   * differently. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view (or sheet) shape to read.
+   * @throws If Present mode is not open or `shapeId` is not a styleable shape.
+   *
+   * @examplePrompt What line weights is this placed plan using?
+   * @examplePrompt Read the styling of the placed view
+   * @examplePrompt Which categories can I restyle on this sheet?
+   *
+   * # Example
+   * ```ts
+   * const styles = await snaptrude.presentation.placedViews.getStyles(shapeId)
+   * const space = styles.categories.find((c) => c.category === "Space")
+   * console.log(space?.settings.cutWidth, space?.settings.lineStyle)
+   * ```
+   */
+  public abstract getStyles(
+    shapeId: string,
+  ): PluginApiReturn<PluginPlacedViewStylesResult>
+
+  /**
+   * Update one style category on a placed view (or sheet) — the same writes
+   * the Present sidebar's per-category configure panel performs.
+   *
+   * The patch may set any subset of the category's settings: line style (7
+   * dash patterns), line color, dash-length multiplier, line weights in mm
+   * (`cutWidth` vs `projectionWidth` — Revit-style cut/projection distinction;
+   * `lineWidth` where the category has a single weight; `treeLineWidth` /
+   * `parkingLineWidth` for Landscape), fill `colorMode` (`department`,
+   * `texture`, `monochrome`, or `tag:<tagCategoryId>`), per-category fill
+   * `opacity` (0–100), category `hide` (cascades to that category's labels),
+   * the shape restyle `viewStyle` (`NONE` block / `FILLET` rounded with
+   * `radius` / `BUBBLE`) with `radius` and `inset`, and Topography's
+   * map/building sub-controls. Settings a category does not support are
+   * rejected. Writes are validated, undoable (one history stop per call), and
+   * re-render immediately; on an auto-diagram sheet the write fans out to
+   * every sheet in its diagram set. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view (or sheet) shape to restyle.
+   * @param category - The style category to update.
+   * @param patch - The settings to change (at least one).
+   * @returns The category's resolved styles after the update.
+   * @throws If Present mode is not open, `shapeId` is not a styleable shape,
+   *   the category does not apply to this shape, or a patched setting is not
+   *   supported by the category or fails validation.
+   *
+   * @examplePrompt Set the Space cut line weight to 0.5 mm
+   * @examplePrompt Make the Department lines dashed
+   * @examplePrompt Color the plan by department
+   * @examplePrompt Hide the dimension lines on this view
+   * @examplePrompt Round the space corners with a 2 ft radius
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.updateStyles(shapeId, "Space", {
+   *   cutWidth: 0.5,
+   *   projectionWidth: 0.18,
+   *   lineStyle: "dashed",
+   *   colorMode: "department",
+   * })
+   * ```
+   */
+  public abstract updateStyles(
+    shapeId: string,
+    category: PluginViewSettingCategory,
+    patch: PluginPlacedViewStylePatch,
+  ): PluginApiReturn<PluginPlacedViewCategoryStyles>
+
+  /**
+   * Reset a placed view's styling to defaults — the sidebar's Reset button:
+   * clears every per-category override and view-style restyle, resets font
+   * styles, and un-hides labels hidden by styling. Undoable. Requires Present
+   * mode to be open.
+   *
+   * @param shapeId - The placed view (or sheet) shape to reset.
+   * @throws If Present mode is not open or `shapeId` is not a styleable shape.
+   *
+   * @examplePrompt Reset this view's styling
+   * @examplePrompt Clear all the style overrides on the placed plan
+   * @examplePrompt Put the sheet styles back to default
+   */
+  public abstract resetStyles(shapeId: string): PluginApiReturn<void>
+
+  /**
+   * Update a category's label typography on a placed view (or sheet) — the
+   * configure panel's Text tab.
+   *
+   * Each category carries font styles per label type — `objectLabels` (the
+   * name), `department`, and `areas` — with `fontFamily` (system families or
+   * any Google Font; the font is loaded automatically and the weight is
+   * coerced to an available variant), `fontWeight` (numeric string, e.g.
+   * `"700"`), `fontStyle` (`normal`/`italic`), and `fontSize` in px.
+   * `visibleTypes` controls which label types render (an empty array hides
+   * all). Not every category has a Text tab — Topography, Facade/Mass,
+   * Reference Line and Adjacency Line reject font writes. Undoable. Requires
+   * Present mode to be open.
+   *
+   * @param shapeId - The placed view (or sheet) shape.
+   * @param category - The style category whose labels to restyle.
+   * @param patch - The font styles to change (at least one field).
+   * @throws If Present mode is not open, `shapeId` is not a styleable shape,
+   *   or the category has no Text tab.
+   *
+   * @examplePrompt Set the space labels to Roboto 24px bold
+   * @examplePrompt Hide the area values on this plan
+   * @examplePrompt Make the department labels italic
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.updateFontStyles(shapeId, "Space", {
+   *   objectLabels: { fontFamily: "Roboto", fontWeight: "700", fontSize: 24 },
+   *   visibleTypes: ["objectLabels", "areas"],
+   * })
+   * ```
+   */
+  public abstract updateFontStyles(
+    shapeId: string,
+    category: PluginViewSettingCategory,
+    patch: PluginPlacedViewFontStylesPatch,
+  ): PluginApiReturn<void>
+
+  // ── Labels ────────────────────────────────────────────────────────────────
+
+  /**
+   * List a placed view's labels — the text children generated from the view's
+   * content (space names, departments, areas, dimension texts). Each label is
+   * individually addressable: it can be moved and hidden. Returns `[]` when
+   * the view has no labels. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape whose labels to list.
+   * @throws If Present mode is not open or `shapeId` is not a placed view.
+   *
+   * @examplePrompt List the labels on this placed plan
+   * @examplePrompt Where are the space labels on this view?
+   * @examplePrompt Show every label with its position
+   *
+   * # Example
+   * ```ts
+   * const { labels } = await snaptrude.presentation.placedViews.listLabels(shapeId)
+   * for (const l of labels) console.log(l.text, l.position, l.hidden)
+   * ```
+   */
+  public abstract listLabels(
+    shapeId: string,
+  ): PluginApiReturn<PluginPlacedViewLabelsResult>
+
+  /**
+   * Move a label to a new position (coordinates relative to its placed view,
+   * the same space `listLabels` reports). The manual position survives style
+   * changes. Undoable. Requires Present mode to be open.
+   *
+   * @param labelId - The label to move (from `listLabels`).
+   * @param position - New position, parent-view-relative.
+   * @throws If Present mode is not open or `labelId` is not a view label.
+   *
+   * @examplePrompt Move the kitchen label out of the hatched area
+   * @examplePrompt Nudge this label 20 units right
+   * @examplePrompt Reposition the area text
+   */
+  public abstract moveLabel(
+    labelId: string,
+    position: PluginSheetPosition,
+  ): PluginApiReturn<PluginPlacedViewLabel>
+
+  /**
+   * Hide or show a single label (independent of the category-level label
+   * visibility). Undoable. Requires Present mode to be open.
+   *
+   * @param labelId - The label to hide/show (from `listLabels`).
+   * @param hidden - `true` to hide, `false` to show.
+   * @throws If Present mode is not open or `labelId` is not a view label.
+   *
+   * @examplePrompt Hide the corridor label
+   * @examplePrompt Show that label again
+   */
+  public abstract setLabelHidden(
+    labelId: string,
+    hidden: boolean,
+  ): PluginApiReturn<PluginPlacedViewLabel>
+
+  // ── Canvas shapes (generated outputs, images, annotations) ────────────────
+
+  /**
+   * List the top-level shapes on the Present canvas — not just placed views:
+   * AI-generated outputs, placed diagram images, plugin-created shapes, and
+   * annotations, each with an `origin` classification. Sheets (frames) are
+   * not listed — use `sheets.list`. Pass `sheetId` to list only shapes on
+   * that sheet. Returns `[]` when Present mode is closed.
+   *
+   * @param sheetId - Optional sheet id to filter by.
+   *
+   * @examplePrompt List everything on the Present canvas
+   * @examplePrompt What AI outputs are on this sheet?
+   * @examplePrompt Show all the shapes with their positions
+   *
+   * # Example
+   * ```ts
+   * const { shapes } = await snaptrude.presentation.placedViews.listShapes()
+   * const aiOutputs = shapes.filter((s) => s.origin === "aiOutput")
+   * ```
+   */
+  public abstract listShapes(
+    sheetId?: string,
+  ): PluginApiReturn<PluginCanvasShapesListResult>
+
+  /**
+   * Get one Present-canvas shape by id — works for any top-level shape
+   * (placed view, AI output, diagram image, plugin shape, annotation), unlike
+   * `get` which requires a placed view. Requires Present mode to be open.
+   *
+   * @param shapeId - The shape to read.
+   * @throws If Present mode is not open or `shapeId` is unknown or a sheet.
+   *
+   * @examplePrompt Inspect the AI render I just generated
+   * @examplePrompt Get the bounds of that diagram image
+   */
+  public abstract getShape(shapeId: string): PluginApiReturn<PluginCanvasShape>
+
+  /**
+   * Move any Present-canvas shape (AI outputs, diagram images, plugin shapes,
+   * annotations — placed views too). Same coordinate semantics as `move`:
+   * sheet-local when on a sheet, page coordinates otherwise; pass
+   * `options.sheetId` to reparent onto a sheet. Undoable. Requires Present
+   * mode to be open.
+   *
+   * @param shapeId - The shape to move.
+   * @param position - New top-left position.
+   * @param options - Optional `sheetId` to move the shape onto that sheet.
+   * @throws If Present mode is not open, `shapeId` is unknown or a sheet, or
+   *   `options.sheetId` is not a sheet.
+   *
+   * @examplePrompt Move the AI render to the top of the sheet
+   * @examplePrompt Put the diagram image at 100, 200
+   */
+  public abstract moveShape(
+    shapeId: string,
+    position: PluginSheetPosition,
+    options?: { sheetId?: string },
+  ): PluginApiReturn<PluginCanvasShape>
+
+  /**
+   * Resize any Present-canvas shape by a uniform factor about its top-left
+   * corner (aspect ratio held) — the generic counterpart of `scale`, which
+   * requires a placed view. Undoable. Requires Present mode to be open.
+   *
+   * @param shapeId - The shape to resize.
+   * @param factor - Uniform scale factor, between `0.01` and `100`.
+   * @throws If Present mode is not open, `shapeId` is unknown or a sheet, or
+   *   `factor` is out of range.
+   *
+   * @examplePrompt Make the AI output half its size
+   * @examplePrompt Double the size of that image
+   */
+  public abstract resizeShape(
+    shapeId: string,
+    factor: number,
+  ): PluginApiReturn<PluginCanvasShape>
+
+  /**
+   * Rotate any Present-canvas shape (AI outputs, diagram images, plugin
+   * shapes, annotations — placed views too) — the generic counterpart of
+   * `setRotation`, same target rules as `moveShape`. Same semantics:
+   * **absolute** angle in radians (tldraw convention) about the shape's
+   * bounds center, canonicalized into `[0, 2π)` (pass values in that range
+   * for an exact round-trip via `getShape`), one undo step. A placed view
+   * passed here falls under the same 3D-only rule as `setRotation`: 2D and
+   * site-plan views cannot rotate and are refused with a typed
+   * `PRECONDITION_FAILED`. Requires Present mode to be open.
+   *
+   * @param shapeId - The shape to rotate.
+   * @param rotation - Absolute rotation in radians.
+   * @throws If Present mode is not open, `shapeId` is unknown or a sheet,
+   *   `rotation` is not a finite number, or the target is a 2D/site-plan
+   *   placed view (`PRECONDITION_FAILED` — only 3D views rotate).
+   *
+   * @examplePrompt Rotate the AI render 15 degrees
+   * @examplePrompt Turn that image sideways
+   * @examplePrompt Reset the diagram image's rotation
+   */
+  public abstract rotateShape(
+    shapeId: string,
+    rotation: number,
+  ): PluginApiReturn<PluginCanvasShape>
+
+  /**
+   * Delete Present-canvas shapes. One undoable step for the whole batch, and
+   * the batch is atomic — if any id is rejected, nothing is deleted.
+   *
+   * Deletable: placed views, AI-generated outputs, placed diagram images, and
+   * shapes created by plugins. **Not deletable here:** sheets (use
+   * `sheets.delete`) and user-drawn annotations (draw, geo, arrow, note,
+   * text, highlight, line shapes without a plugin ownership stamp) — those
+   * reject with a validation error. Requires Present mode to be open.
+   *
+   * @param shapeIds - The shapes to delete (at least one).
+   * @returns The deleted shape ids.
+   * @throws If Present mode is not open, or any id is unknown, a sheet, or a
+   *   protected user annotation.
+   *
+   * @examplePrompt Delete the old AI renders from the sheet
+   * @examplePrompt Remove that placed view
+   * @examplePrompt Clear the diagram images I placed
+   *
+   * # Example
+   * ```ts
+   * const { deleted } = await snaptrude.presentation.placedViews.deleteShapes([
+   *   out1.shapeId,
+   *   out2.shapeId,
+   * ])
+   * ```
+   */
+  public abstract deleteShapes(
+    shapeIds: string[],
+  ): PluginApiReturn<PluginCanvasShapesDeleteResult>
+
+  /**
+   * Set a Present-canvas shape's opacity (`0` transparent .. `1` opaque) —
+   * the sidebar's whole-shape opacity slider (distinct from the per-category
+   * fill opacity in `updateStyles`). Works for any top-level shape. Undoable.
+   * Requires Present mode to be open.
+   *
+   * @param shapeId - The shape to change.
+   * @param opacity - Target opacity, `0`..`1`.
+   * @throws If Present mode is not open or `shapeId` is unknown or a sheet.
+   *
+   * @examplePrompt Fade the placed view to 50%
+   * @examplePrompt Make the AI render semi-transparent
+   */
+  public abstract setOpacity(
+    shapeId: string,
+    opacity: number,
+  ): PluginApiReturn<void>
+
+  /**
+   * Toggle "mask context buildings" on a placed view — mutes the inactive
+   * proposal buildings in the view (the sidebar checkbox). Views only.
+   * Undoable. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape.
+   * @param enabled - `true` to mask context buildings.
+   * @throws If Present mode is not open or `shapeId` is not a placed view.
+   *
+   * @examplePrompt Mask the context buildings in this view
+   * @examplePrompt Show the neighboring proposals again in the placed view
+   */
+  public abstract setMask(
+    shapeId: string,
+    enabled: boolean,
+  ): PluginApiReturn<void>
+}
+
+/** A point in crop space — fractions (0–1) of the uncropped view. */
+const PluginPlacedViewCropPoint = z.object({
+  x: z.number().min(0).max(1),
+  y: z.number().min(0).max(1),
+})
+
+/**
+ * A crop window on a placed view, as fractions (0–1) of the **uncropped**
+ * view. `topLeft` must be strictly less than `bottomRight` on both axes.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `topLeft` | `{ x: number, y: number }` | Top-left of the visible window (fractions 0–1) |
+ * | `bottomRight` | `{ x: number, y: number }` | Bottom-right of the visible window (fractions 0–1) |
+ */
+export const PluginPlacedViewCrop = z
+  .object({
+    topLeft: PluginPlacedViewCropPoint,
+    bottomRight: PluginPlacedViewCropPoint,
+  })
+  .refine(
+    (c) => c.topLeft.x < c.bottomRight.x && c.topLeft.y < c.bottomRight.y,
+    { message: "topLeft must be strictly less than bottomRight on both axes" },
+  )
+export type PluginPlacedViewCrop = z.infer<typeof PluginPlacedViewCrop>
+
+/**
+ * A view placed on the Present canvas.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the placed view shape (the id `sheets.place` returns) |
+ * | `sheetId` | `string \| null` | The sheet it sits on (`null` when placed loose on the canvas) |
+ * | `title` | `string` | The saved view's title |
+ * | `viewId` | `string` | Id of the saved view it was placed from |
+ * | `position` | {@linkcode PluginSheetPosition} | Top-left position — sheet-local when on a sheet, page coordinates otherwise |
+ * | `size` | `{ width: number, height: number }` | Displayed size on the canvas |
+ * | `scale` | `number \| null` | Architectural scale (e.g. `100` = 1:100); `null` for 3D views |
+ * | `is3d` | `boolean` | Whether it is a 3D view (no architectural scale) |
+ * | `rotation` | `number` | Rotation in radians, `[0, 2π)` (nonzero only for 3D views — 2D views cannot rotate; set with `setRotation`) |
+ * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | Crop window (`null` when uncropped) |
+ * | `isUnlinked` | `boolean` | Whether the source proposal was removed (an unlinked view no longer refreshes) |
+ */
+export const PluginPlacedView = z.object({
+  shapeId: z.string(),
+  sheetId: z.string().nullable(),
+  title: z.string(),
+  viewId: z.string(),
+  position: PluginSheetPosition,
+  size: z.object({ width: z.number(), height: z.number() }),
+  scale: z.number().nullable(),
+  is3d: z.boolean(),
+  rotation: z.number(),
+  crop: PluginPlacedViewCrop.nullable(),
+  isUnlinked: z.boolean(),
+})
+export type PluginPlacedView = z.infer<typeof PluginPlacedView>
+
+/** Arguments for {@linkcode PluginPresentationPlacedViewsApi.list}. */
+export const PluginPresentationPlacedViewsListArgs = z.object({
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationPlacedViewsListArgs = z.infer<
+  typeof PluginPresentationPlacedViewsListArgs
+>
+
+/** Result of {@linkcode PluginPresentationPlacedViewsApi.list}. */
+export const PluginPresentationPlacedViewsListResult = z.object({
+  placedViews: z.array(PluginPlacedView),
+})
+export type PluginPresentationPlacedViewsListResult = z.infer<
+  typeof PluginPresentationPlacedViewsListResult
+>
+
+/** Arguments for {@linkcode PluginPresentationPlacedViewsApi.get}. */
+export const PluginPresentationPlacedViewsGetArgs = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationPlacedViewsGetArgs = z.infer<
+  typeof PluginPresentationPlacedViewsGetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to move |
+ * | `position` | {@linkcode PluginSheetPosition} | New top-left position (sheet-local; page coordinates when off-sheet) |
+ * | `sheetId` | `string`? | Move the view onto this sheet |
+ */
+export const PluginPresentationPlacedViewsMoveArgs = z.object({
+  shapeId: z.string(),
+  position: PluginSheetPosition,
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationPlacedViewsMoveArgs = z.infer<
+  typeof PluginPresentationPlacedViewsMoveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.scale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to resize |
+ * | `factor` | `number` | Uniform scale factor (0.01–100) |
+ */
+export const PluginPresentationPlacedViewsScaleArgs = z.object({
+  shapeId: z.string(),
+  factor: z.number().finite().min(0.01).max(100),
+})
+export type PluginPresentationPlacedViewsScaleArgs = z.infer<
+  typeof PluginPresentationPlacedViewsScaleArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.setScale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to set the scale of |
+ * | `scale` | `number` | A standard scale value for the project's unit system |
+ */
+export const PluginPresentationPlacedViewsSetScaleArgs = z.object({
+  shapeId: z.string(),
+  scale: z.number().positive(),
+})
+export type PluginPresentationPlacedViewsSetScaleArgs = z.infer<
+  typeof PluginPresentationPlacedViewsSetScaleArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.setCrop}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to crop |
+ * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | The crop window, or `null` to clear |
+ */
+export const PluginPresentationPlacedViewsSetCropArgs = z.object({
+  shapeId: z.string(),
+  crop: PluginPlacedViewCrop.nullable(),
+})
+export type PluginPresentationPlacedViewsSetCropArgs = z.infer<
+  typeof PluginPresentationPlacedViewsSetCropArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.setRotation}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to rotate |
+ * | `rotation` | `number` | Absolute rotation in radians (tldraw convention) |
+ */
+export const PluginPresentationPlacedViewsSetRotationArgs = z.object({
+  shapeId: z.string().min(1),
+  rotation: z.number().finite(),
+})
+export type PluginPresentationPlacedViewsSetRotationArgs = z.infer<
+  typeof PluginPresentationPlacedViewsSetRotationArgs
+>
+
+// ── Styling ─────────────────────────────────────────────────────────────────
+
+/**
+ * A Present-mode style category — mirrors the host's view-settings CATEGORIES
+ * exactly. Sheets/auto-diagrams use the subset Space / Department /
+ * Adjacency Line.
+ */
+export const PluginViewSettingCategory = z.enum([
+  "Site",
+  "Topography",
+  "Space",
+  "Department",
+  "Envelope",
+  "Facade/Mass",
+  "Dimension",
+  "Reference Line",
+  "Adjacency Line",
+  "Landscape elements",
+])
+export type PluginViewSettingCategory = z.infer<typeof PluginViewSettingCategory>
+
+/** The 7 line dash styles (mirrors the host's LINE_STYLES). */
+export const PluginViewLineStyle = z.enum([
+  "solid",
+  "dashed",
+  "dashdot",
+  "hidden",
+  "center",
+  "phantom",
+  "propertyLine",
+])
+export type PluginViewLineStyle = z.infer<typeof PluginViewLineStyle>
+
+/**
+ * A style patch for one category — any subset of the category's settings.
+ * Line weights are in **mm** (the printed weight); `opacity` values are 0–100;
+ * `colorMode` is `department` / `texture` / `monochrome` or `tag:<tagCategoryId>`
+ * (color by a project tag category).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `hide` | `boolean`? | Hide the category (cascades to its labels) |
+ * | `lineStyle` | {@linkcode PluginViewLineStyle}? | Dash pattern |
+ * | `lineColor` | `string`? | Line color, 6-digit hex (`#` optional) |
+ * | `dashLength` | `number`? | Dash-length multiplier (> 0; `1` = default) |
+ * | `lineWidth` | `number`? | Single line weight in mm (categories without cut/projection) |
+ * | `cutWidth` | `number`? | Cut-line weight in mm |
+ * | `projectionWidth` | `number`? | Projection-line weight in mm |
+ * | `treeLineWidth` | `number`? | Tree line weight in mm (Landscape) |
+ * | `parkingLineWidth` | `number`? | Parking line weight in mm (Landscape) |
+ * | `colorMode` | `string`? | `department` \| `texture` \| `monochrome` \| `tag:<id>` |
+ * | `opacity` | `number`? | Category fill opacity, 0–100 |
+ * | `mapOpacity` | `number`? | Topography: map image opacity, 0–100 |
+ * | `buildingOpacity` | `number`? | Topography: context-building opacity, 0–100 |
+ * | `mapHide` | `boolean`? | Topography: hide the map image |
+ * | `buildingHide` | `boolean`? | Topography: hide context buildings |
+ * | `noBuilding` | `boolean`? | Topography: suppress buildings entirely |
+ * | `viewStyle` | `"NONE" \| "FILLET" \| "BUBBLE"`? | Shape restyle: block / rounded corner / bubble |
+ * | `radius` | `number`? | Corner radius for `FILLET` (feet) |
+ * | `inset` | `number`? | Shape inset/offset |
+ */
+export const PluginPlacedViewStylePatch = z
+  .object({
+    hide: z.boolean().optional(),
+    lineStyle: PluginViewLineStyle.optional(),
+    lineColor: z
+      .string()
+      .regex(/^#?[0-9a-fA-F]{6}$/, "lineColor must be a 6-digit hex color")
+      .optional(),
+    dashLength: z.number().finite().positive().optional(),
+    lineWidth: z.number().finite().min(0).optional(),
+    cutWidth: z.number().finite().min(0).optional(),
+    projectionWidth: z.number().finite().min(0).optional(),
+    treeLineWidth: z.number().finite().min(0).optional(),
+    parkingLineWidth: z.number().finite().min(0).optional(),
+    colorMode: z
+      .string()
+      .refine(
+        (v) => ["department", "texture", "monochrome"].includes(v) || v.startsWith("tag:"),
+        { message: "colorMode must be department, texture, monochrome, or tag:<tagCategoryId>" },
+      )
+      .optional(),
+    opacity: z.number().finite().min(0).max(100).optional(),
+    mapOpacity: z.number().finite().min(0).max(100).optional(),
+    buildingOpacity: z.number().finite().min(0).max(100).optional(),
+    mapHide: z.boolean().optional(),
+    buildingHide: z.boolean().optional(),
+    noBuilding: z.boolean().optional(),
+    viewStyle: z.enum(["NONE", "FILLET", "BUBBLE"]).optional(),
+    radius: z.number().finite().min(0).optional(),
+    inset: z.number().finite().min(0).optional(),
+  })
+  .strict()
+  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one setting" })
+export type PluginPlacedViewStylePatch = z.infer<typeof PluginPlacedViewStylePatch>
+
+/** Label types that carry typography in a category's Text tab. */
+export const PluginViewLabelType = z.enum(["objectLabels", "department", "areas"])
+export type PluginViewLabelType = z.infer<typeof PluginViewLabelType>
+
+/** Typography patch for one label type. `fontSize` is in px. */
+const PluginViewFontVariantPatch = z
+  .object({
+    fontFamily: z.string().min(1).optional(),
+    fontWeight: z
+      .string()
+      .regex(/^\d{3}$/, 'fontWeight must be a numeric string like "400" or "700"')
+      .optional(),
+    fontStyle: z.enum(["normal", "italic"]).optional(),
+    fontSize: z.number().finite().positive().max(200).optional(),
+  })
+  .strict()
+
+/**
+ * Font-styles patch for one category's Text tab.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `visibleTypes` | {@linkcode PluginViewLabelType}`[]`? | Which label types render (`[]` hides all) |
+ * | `objectLabels` | variant? | Typography for the name label |
+ * | `department` | variant? | Typography for the department label |
+ * | `areas` | variant? | Typography for the area/tag values |
+ */
+export const PluginPlacedViewFontStylesPatch = z
+  .object({
+    visibleTypes: z.array(PluginViewLabelType).optional(),
+    objectLabels: PluginViewFontVariantPatch.optional(),
+    department: PluginViewFontVariantPatch.optional(),
+    areas: PluginViewFontVariantPatch.optional(),
+  })
+  .strict()
+  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one field" })
+export type PluginPlacedViewFontStylesPatch = z.infer<typeof PluginPlacedViewFontStylesPatch>
+
+/** Resolved font styles for one label type (fontSize in px). */
+export type PluginViewFontVariant = {
+  fontFamily?: string
+  fontWeight?: string
+  fontStyle?: "normal" | "italic"
+  fontSize?: number
+}
+
+/**
+ * One category's resolved styles on a placed view or sheet.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `category` | {@linkcode PluginViewSettingCategory} | The category |
+ * | `disabled` | `boolean` | Not visible in this view — settings are inert |
+ * | `supported` | `string[]` | Setting ids this category accepts in `updateStyles` |
+ * | `settings` | {@linkcode PluginPlacedViewStylePatch} | Fully-resolved values (defaults + overrides) |
+ * | `fontStyles` | object? | Resolved Text-tab typography (absent when the category has no Text tab) |
+ */
+export type PluginPlacedViewCategoryStyles = {
+  category: PluginViewSettingCategory
+  disabled: boolean
+  supported: string[]
+  settings: PluginPlacedViewStylePatch
+  fontStyles?: {
+    visibleTypes: PluginViewLabelType[]
+    objectLabels?: PluginViewFontVariant
+    department?: PluginViewFontVariant
+    areas?: PluginViewFontVariant
+  }
+}
+
+/**
+ * Result of {@link PluginPresentationPlacedViewsApi.getStyles}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The styleable shape read |
+ * | `kind` | `"view" \| "sheet"` | Placed view or auto-diagram sheet |
+ * | `categories` | {@linkcode PluginPlacedViewCategoryStyles}`[]` | One entry per applicable category |
+ */
+export type PluginPlacedViewStylesResult = {
+  shapeId: string
+  kind: "view" | "sheet"
+  categories: PluginPlacedViewCategoryStyles[]
+}
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.updateStyles}. */
+export const PluginPlacedViewsUpdateStylesArgs = z.object({
+  shapeId: z.string().min(1),
+  category: PluginViewSettingCategory,
+  patch: PluginPlacedViewStylePatch,
+})
+export type PluginPlacedViewsUpdateStylesArgs = z.infer<typeof PluginPlacedViewsUpdateStylesArgs>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.updateFontStyles}. */
+export const PluginPlacedViewsUpdateFontStylesArgs = z.object({
+  shapeId: z.string().min(1),
+  category: PluginViewSettingCategory,
+  patch: PluginPlacedViewFontStylesPatch,
+})
+export type PluginPlacedViewsUpdateFontStylesArgs = z.infer<
+  typeof PluginPlacedViewsUpdateFontStylesArgs
+>
+
+// ── Labels ──────────────────────────────────────────────────────────────────
+
+/**
+ * A label on a placed view — a text child generated from the view content.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `labelId` | `string` | The label's shape id (addressable in `moveLabel`/`setLabelHidden`) |
+ * | `category` | `string \| null` | The style category it belongs to (`null` when untagged) |
+ * | `text` | `string` | The rendered text |
+ * | `position` | {@linkcode PluginSheetPosition} | Position relative to the placed view |
+ * | `scale` | `number` | The label's scale factor |
+ * | `hidden` | `boolean` | Whether it is currently hidden |
+ */
+export type PluginPlacedViewLabel = {
+  labelId: string
+  category: string | null
+  text: string
+  position: PluginSheetPosition
+  scale: number
+  hidden: boolean
+}
+
+/** Result of {@link PluginPresentationPlacedViewsApi.listLabels}. */
+export type PluginPlacedViewLabelsResult = {
+  labels: PluginPlacedViewLabel[]
+}
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.moveLabel}. */
+export const PluginPlacedViewsMoveLabelArgs = z.object({
+  labelId: z.string().min(1),
+  position: PluginSheetPosition,
+})
+export type PluginPlacedViewsMoveLabelArgs = z.infer<typeof PluginPlacedViewsMoveLabelArgs>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.setLabelHidden}. */
+export const PluginPlacedViewsSetLabelHiddenArgs = z.object({
+  labelId: z.string().min(1),
+  hidden: z.boolean(),
+})
+export type PluginPlacedViewsSetLabelHiddenArgs = z.infer<
+  typeof PluginPlacedViewsSetLabelHiddenArgs
+>
+
+// ── Canvas shapes ───────────────────────────────────────────────────────────
+
+/**
+ * Origin classification of a Present-canvas shape: a placed view, an
+ * AI-generated output, a placed diagram image, a plugin-created shape, a
+ * user annotation, a plain image, or other.
+ */
+export const PluginCanvasShapeOrigin = z.enum([
+  "view",
+  "aiOutput",
+  "diagram",
+  "pluginShape",
+  "annotation",
+  "image",
+  "other",
+])
+export type PluginCanvasShapeOrigin = z.infer<typeof PluginCanvasShapeOrigin>
+
+/**
+ * A top-level shape on the Present canvas.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The shape id |
+ * | `type` | `string` | The canvas shape type (`view`, `image`, `geo`, `text`, …) |
+ * | `origin` | {@linkcode PluginCanvasShapeOrigin} | What created it |
+ * | `sheetId` | `string \| null` | The sheet it sits on (`null` when loose on the canvas) |
+ * | `position` | {@linkcode PluginSheetPosition} | Top-left position (sheet-local; page coordinates off-sheet) |
+ * | `size` | `{ width: number, height: number }` | Displayed size |
+ * | `rotation` | `number` | Rotation in radians |
+ * | `opacity` | `number` | Whole-shape opacity, 0–1 |
+ */
+export type PluginCanvasShape = {
+  shapeId: string
+  type: string
+  origin: PluginCanvasShapeOrigin
+  sheetId: string | null
+  position: PluginSheetPosition
+  size: { width: number; height: number }
+  rotation: number
+  opacity: number
+}
+
+/** Result of {@link PluginPresentationPlacedViewsApi.listShapes}. */
+export type PluginCanvasShapesListResult = {
+  shapes: PluginCanvasShape[]
+}
+
+/** Result of {@link PluginPresentationPlacedViewsApi.deleteShapes}. */
+export type PluginCanvasShapesDeleteResult = {
+  deleted: string[]
+}
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.moveShape}. */
+export const PluginPlacedViewsMoveShapeArgs = z.object({
+  shapeId: z.string().min(1),
+  position: PluginSheetPosition,
+  sheetId: z.string().optional(),
+})
+export type PluginPlacedViewsMoveShapeArgs = z.infer<typeof PluginPlacedViewsMoveShapeArgs>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.resizeShape}. */
+export const PluginPlacedViewsResizeShapeArgs = z.object({
+  shapeId: z.string().min(1),
+  factor: z.number().finite().min(0.01).max(100),
+})
+export type PluginPlacedViewsResizeShapeArgs = z.infer<typeof PluginPlacedViewsResizeShapeArgs>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.rotateShape}. */
+export const PluginPresentationPlacedViewsRotateShapeArgs = z.object({
+  shapeId: z.string().min(1),
+  rotation: z.number().finite(),
+})
+export type PluginPresentationPlacedViewsRotateShapeArgs = z.infer<
+  typeof PluginPresentationPlacedViewsRotateShapeArgs
+>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.deleteShapes}. */
+export const PluginPlacedViewsDeleteShapesArgs = z.object({
+  shapeIds: z.array(z.string().min(1)).min(1).max(500),
+})
+export type PluginPlacedViewsDeleteShapesArgs = z.infer<typeof PluginPlacedViewsDeleteShapesArgs>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.setOpacity}. */
+export const PluginPlacedViewsSetOpacityArgs = z.object({
+  shapeId: z.string().min(1),
+  opacity: z.number().finite().min(0).max(1),
+})
+export type PluginPlacedViewsSetOpacityArgs = z.infer<typeof PluginPlacedViewsSetOpacityArgs>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.setMask}. */
+export const PluginPlacedViewsSetMaskArgs = z.object({
+  shapeId: z.string().min(1),
+  enabled: z.boolean(),
+})
+export type PluginPlacedViewsSetMaskArgs = z.infer<typeof PluginPlacedViewsSetMaskArgs>