@snaptrude/plugin-core 0.9.16 → 0.9.18-voids-20261016.1

package/src/api/presentation/sheets.ts

@@ -1,5 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import { PluginStandardDrawingScale } from "./drawingContract"
 
 /**
  * Presentation sheets — the layout sheets a presentation is assembled on.
@@ -10,9 +11,16 @@ import { PluginApiReturn } from "../../types"
  *
  * `list`/`get` are reads; the rest mutate and require Present mode to be open:
  * `create` adds a sheet, `place` drops a saved view onto a sheet as a live
- * linked view shape, `rename` relabels a sheet, `delete` removes one, `reorder`
- * moves one in the sheet order, `setActive` navigates to one, and
- * `updatePlacedView` re-renders placed views to the current model.
+ * linked view shape (fitted to that sheet), `placeDrawing` moves an existing
+ * drawing onto a sheet (scaled down to fit by default), `rename` relabels a
+ * sheet, `delete` removes one, `reorder` moves one in the sheet order,
+ * `setActive` navigates to one, and `updatePlacedView` re-renders placed views
+ * to the current model.
+ *
+ * `presentation.drawings.create` never puts a drawing on a sheet: it makes the
+ * drawing beside its source view on the canvas. To put a view on a sheet, call
+ * `place(sheetId, viewId)`; to move a drawing you already made, call
+ * `placeDrawing(sheetId, drawingId)`.
  *
  * Accessed via `snaptrude.presentation.sheets`.
  */
@@ -155,37 +163,75 @@ export abstract class PluginPresentationSheetsApi {
   ): PluginApiReturn<PluginPresentationSheet>
 
   /**
-   * Place a saved view onto a sheet.
+   * Place a saved view onto a sheet. This is the call that puts a view on a
+   * sheet (`presentation.drawings.create` makes a drawing beside its source
+   * view, not on a sheet). When `scale` is omitted the view is fitted to the
+   * target sheet: a 2D or site-plan view is placed at the largest
+   * standard scale at which it fits inside the target sheet's margin, and
+   * never at a larger scale than the normal view drop would pick; a 3D view
+   * has no scale, so it is shrunk evenly to fit instead. This is the same fit
+   * as `placeDrawing`. Omit `position` unless the user asked for a specific
+   * place.
+   * Without a `position` the drawing goes to the sheet centre when that is
+   * free, otherwise to the nearest free spot to the centre inside the margin,
+   * beside the drawings already there; when there is no free spot it is
+   * centred anyway and the result has `overlaps: true`. With a `position` it
+   * is placed as given, and the result has `overlaps: true` when it covers
+   * another drawing, but it is not moved. In both cases only other drawings
+   * count (placed views and their title blocks and labels): text, images and
+   * other shapes on the sheet are ignored. Each call fits one view to the
+   * whole sheet, so a second fitted view often has no free spot: when several
+   * views should share a sheet, pass a `scale` small enough for all of them;
+   * otherwise use `sheets.create` per view. When the result's `overlaps` is
+   * true, move the drawing or put it on its own sheet.
+   * An explicit `scale` is always kept, even when the drawing (title block
+   * included) does not fit inside the sheet's margin at that scale; the result
+   * then has `overflows: true`. When it is true, pass a smaller scale (larger
+   * denominator), omit `scale` to fit, or use a larger sheet.
+   * `scale` must be a standard architectural scale denominator (100 means 1:100)
+   * in the project's unit system; any other value is rejected. Metric: 10, 20, 50,
+   * 100, 150, 200, 250, 500, 1000. Imperial detail: 12, 16, 24, 32, 48, 64, 96, 128,
+   * 192, 384, 768, 1536 (1" = 1' to 1/128" = 1'; 48 is 1/4" = 1', 96 is 1/8" = 1').
+   * Imperial site: 120, 240, 360, 480, 600, 1200, 2400, 3600, 4800 (1" = 10' to
+   * 1" = 400'). Pick the LARGEST standard scale (smallest denominator) at which the
+   * view still fits its frame or sheet and its room labels stay readable: for a
+   * building floor plan that is usually 1:50 to 1:200 (1/4" = 1' to 1/16" = 1').
+   * Never use a site-sized scale (1:500 and up, 1/64" = 1' (768) and smaller,
+   * 1" = 20' (240) and up) for a single building plan unless the user asked for it.
    *
    * Drops the given view onto the sheet through the **native view drop** — the
    * placed shape is a live linked view (the same shape the Present views panel's
    * drag-drop creates), re-rendered from the current model, so
    * {@linkcode PluginPresentationSheetsApi.updatePlacedView} refreshes it later.
-   * 2D and site-plan views are placed at an architectural scale: the closest
-   * standard scale by default (the native auto-fit), or the explicit `scale`
-   * when given — one of the standard values the placed view's Scale dropdown
-   * offers for the project's unit system (metric `10, 20, 50, 100, 150, 200,
-   * 250, 500, 1000`; imperial e.g. `48` for 1/4″ = 1′, `96` for 1/8″ = 1′,
-   * `120` for 1″ = 10′). 3D views have no scale — passing `scale` for one
-   * throws. Requires Present mode to be open.
+   * 2D and site-plan views are placed at an architectural scale: the fitted
+   * standard scale described above by default, or the explicit `scale` when
+   * given (one of the standard values above). 3D views have no scale; passing
+   * `scale` for one throws. Requires Present mode to be open.
    *
    * @param sheetId - The id of the sheet to place onto.
    * @param viewId - The id of the saved view to place.
    * @param options - Optional `position` ({@linkcode PluginSheetPosition}) —
-   *   where to place it (sheet centre when omitted) — and `scale` — a standard
-   *   scale value for the project's unit system (2D/site-plan views only;
-   *   auto-fit when omitted).
+   *   where to place it (when omitted, the sheet centre or the nearest free
+   *   spot) — and `scale` — a standard scale value for the project's unit system (2D/site-plan views only;
+   *   fitted to the target sheet when omitted).
    * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
-   *   `shapeId`.
+   *   `shapeId`, the `scale` used (`null` for a 3D view), whether the fit
+   *   `rescaled` it, whether it `overlaps` another drawing on the sheet, and
+   *   whether it `overflows` the sheet's margin at an explicit `scale`.
+   *   (Hosts older than the fit return only `shapeId`.)
    * @throws If Present mode is not open, the sheet/view id is invalid, `scale`
    *   is not a standard value for the project's unit system, or `scale` is
-   *   passed for a 3D view.
+   *   passed for a 3D view. `PRECONDITION_FAILED` when the view does not fit
+   *   the sheet even at the smallest standard scale, or the title block alone
+   *   is larger than the sheet's drawable area (use a larger sheet); no
+   *   drawing is left on the sheet.
    *
    * @examplePrompt Place the floor plan on Sheet 1
    * @examplePrompt Add this 3D view to the cover sheet
    * @examplePrompt Drop the site plan onto the layout sheet at 100, 200
    * @examplePrompt Put the Ground Floor view on sheet_1 at 1:100 scale
    * @examplePrompt Place the plan on the cover sheet at quarter-inch scale
+   * @examplePrompt Add a floor plan drawing of each storey to this sheet
    *
    * # Example
    * ```ts
@@ -200,6 +246,72 @@ export abstract class PluginPresentationSheetsApi {
     options?: { position?: PluginSheetPosition; scale?: number },
   ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
 
+  /**
+   * Move an existing drawing onto a sheet without copying or regenerating it,
+   * scaled down to fit the sheet when it is too big. `presentation.drawings.create`
+   * leaves a drawing beside its source view, not on a sheet; this is the call
+   * that puts it on one. To place a saved view on a sheet in one call, use
+   * `sheets.place(sheetId, viewId)`, which fits it the same way.
+   * By default (`fit` true or omitted) a drawing larger than the sheet's
+   * drawable area (the sheet inside its margin) is moved to the LARGEST standard
+   * architectural scale at which it fits; a drawing that already fits keeps its
+   * scale, and a drawing is never scaled up. A 3D drawing has no architectural
+   * scale, so it is shrunk uniformly to fit instead. With `fit: false` the scale
+   * is kept and a drawing that does not fit is rejected with an error naming the
+   * drawing, the sheet and the scale, and saying to call `placeDrawing` without
+   * `fit: false` to fit it, or use a larger sheet. When even
+   * the smallest standard scale does not fit, the call is rejected with an error
+   * suggesting a larger sheet size.
+   * Without a `position` the drawing goes to the sheet centre when that is
+   * free, otherwise to the nearest free spot to the centre inside the margin,
+   * beside the drawings already there; when there is no free spot it is
+   * centred anyway and the result has `overlaps: true`. With a `position` it
+   * is placed as given, and the result has `overlaps: true` when it covers
+   * another drawing, but it is not moved. In both cases only other drawings
+   * count (placed views and their title blocks and labels): text, images and
+   * other shapes on the sheet are ignored. Each call fits one drawing to the
+   * whole sheet, so a second fitted drawing often has no free spot: when
+   * several drawings should share a sheet, give them scales small enough for
+   * all of them; otherwise use `sheets.create` per drawing.
+   * The position is sheet-local. The drawing's
+   * stable id remains unchanged; `shapeId` therefore identifies the moved
+   * drawing. The result reports the architectural scale the drawing has on the
+   * sheet and whether this call changed it; a host that reports it also says
+   * whether the drawing `overlaps` another drawing on the sheet (move it or
+   * put it on its own sheet when true).
+   *
+   * @param sheetId - The id of the destination sheet.
+   * @param drawingId - The id of an existing drawing deliverable.
+   * @param options - Optional sheet-local `position` (when omitted, the sheet centre or the nearest free spot)
+   *   and `fit` (default `true`: scale a drawing that does not fit down to fit;
+   *   `false`: keep its scale and reject a drawing that does not fit).
+   * @returns A {@linkcode PluginPresentationSheetsPlaceDrawingResult} with the
+   *   drawing's `shapeId`, the `scale` used (`null` for a 3D drawing),
+   *   `rescaled`, and optionally `overlaps`.
+   * @throws `PRECONDITION_FAILED` if Present mode is closed, the sheet is locked,
+   *   the drawing does not fit with `fit: false`, or it does not fit even at the
+   *   smallest standard scale; `HANDLE_INVALID` if either id is invalid or the
+   *   shape is not a drawing.
+   *
+   * @examplePrompt Move this drawing onto the cover sheet
+   * @examplePrompt Place drawing_1 at the center of sheet_2
+   * @examplePrompt Put the level 2 plan drawing on the Level 2 Plan sheet
+   * @examplePrompt Add the floor plan drawings to this sheet
+   *
+   * # Example
+   * ```ts
+   * const { scale, rescaled } = await snaptrude.presentation.sheets.placeDrawing(
+   *   sheet.id,
+   *   drawing.id,
+   * )
+   * ```
+   */
+  public abstract placeDrawing(
+    sheetId: string,
+    drawingId: string,
+    options?: { position?: PluginSheetPosition; fit?: boolean },
+  ): PluginApiReturn<PluginPresentationSheetsPlaceDrawingResult>
+
   /**
    * Rename a layout sheet.
    *
@@ -467,33 +579,82 @@ export type PluginPresentationSheetsSetMarginArgs = z.infer<
  * |---|---|---|
  * | `sheetId` | `string` | The sheet to place onto |
  * | `viewId` | `string` | The saved view to place |
- * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (sheet centre when omitted) |
- * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; auto-fit to the closest standard scale when omitted) |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (when omitted, the sheet centre or the nearest free spot) |
+ * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; when omitted, the largest standard scale that fits inside the target sheet's margin, never larger than the normal view drop's) |
  */
 export const PluginPresentationSheetsPlaceArgs = z.object({
   sheetId: z.string(),
   viewId: z.string(),
   position: PluginSheetPosition.optional(),
-  scale: z.number().positive().optional(),
+  scale: PluginStandardDrawingScale.optional(),
 })
 export type PluginPresentationSheetsPlaceArgs = z.infer<
   typeof PluginPresentationSheetsPlaceArgs
 >
 
 /**
- * Result of {@linkcode PluginPresentationSheetsApi.place}.
+ * Arguments for {@linkcode PluginPresentationSheetsApi.placeDrawing}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The destination sheet |
+ * | `drawingId` | `string` | The existing drawing to move |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Sheet-local position (when omitted, the sheet centre or the nearest free spot) |
+ * | `fit` | `boolean \| undefined` | `true` (default) scales a drawing that does not fit down to fit; `false` keeps its scale and rejects a drawing that does not fit |
+ */
+export const PluginPresentationSheetsPlaceDrawingArgs = z.object({
+  sheetId: z.string().min(1),
+  drawingId: z.string().min(1),
+  position: PluginSheetPosition.optional(),
+  fit: z.boolean().optional(),
+})
+export type PluginPresentationSheetsPlaceDrawingArgs = z.infer<
+  typeof PluginPresentationSheetsPlaceDrawingArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.place}. The host returns
+ * `scale` and `rescaled` (and `overlaps`, `overflows`); they are optional only
+ * because hosts that predate the fit report `shapeId` alone.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `shapeId` | `string` | Id of the created canvas shape |
+ * | `scale` | `number \| null \| undefined` | Architectural scale denominator the view has on the sheet (`null` for a 3D view) |
+ * | `rescaled` | `boolean \| undefined` | Whether the fit changed the view's size from the normal view drop's |
+ * | `overlaps` | `boolean \| undefined` | Whether the placed drawing overlaps another drawing on the sheet (only drawings count, not text, images or other shapes) |
+ * | `overflows` | `boolean \| undefined` | `true` when the drawing, title block included, does not fit inside the sheet's margin at the explicit `scale` passed (the scale is kept); absent otherwise |
  */
 export const PluginPresentationSheetsPlaceResult = z.object({
   shapeId: z.string(),
+  scale: z.number().finite().nullable().optional(),
+  rescaled: z.boolean().optional(),
+  overlaps: z.boolean().optional(),
+  overflows: z.boolean().optional(),
 })
 export type PluginPresentationSheetsPlaceResult = z.infer<
   typeof PluginPresentationSheetsPlaceResult
 >
 
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.placeDrawing}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the moved drawing (the drawing id, unchanged) |
+ * | `scale` | `number \| null` | Architectural scale denominator the drawing has on the sheet (`null` for a 3D drawing) |
+ * | `rescaled` | `boolean` | Whether this call changed the drawing's size to fit the sheet |
+ * | `overlaps` | `boolean \| undefined` | Whether the drawing overlaps another drawing on the sheet (only drawings count, not text, images or other shapes) |
+ */
+export const PluginPresentationSheetsPlaceDrawingResult =
+  PluginPresentationSheetsPlaceResult.omit({ overflows: true }).extend({
+    scale: z.number().finite().nullable(),
+    rescaled: z.boolean(),
+  })
+export type PluginPresentationSheetsPlaceDrawingResult = z.infer<
+  typeof PluginPresentationSheetsPlaceDrawingResult
+>
+
 /**
  * Arguments for {@linkcode PluginPresentationSheetsApi.rename}.
  *

package/src/api/presentation/viewPresets.ts

@@ -0,0 +1,241 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+
+/** Presets are document-local. Their ids are stable across reload; built-ins are immutable. */
+export const PluginViewPreset = z.object({
+  id: z.string(),
+  name: z.string(),
+  builtIn: z.boolean(),
+  revision: z.number().int().nonnegative(),
+})
+export type PluginViewPreset = z.infer<typeof PluginViewPreset>
+export const PluginViewPresetIdArgs = z
+  .object({ presetId: z.string().min(1) })
+  .strict()
+export type PluginViewPresetIdArgs = z.infer<typeof PluginViewPresetIdArgs>
+export const PluginViewPresetCreateArgs = z
+  .object({ name: z.string().trim().min(1), fromDrawingId: z.string().min(1) })
+  .strict()
+export type PluginViewPresetCreateArgs = z.infer<
+  typeof PluginViewPresetCreateArgs
+>
+export const PluginViewPresetRenameArgs = PluginViewPresetIdArgs.extend({
+  name: z.string().trim().min(1),
+})
+export type PluginViewPresetRenameArgs = z.infer<
+  typeof PluginViewPresetRenameArgs
+>
+export const PluginViewPresetUpdateArgs = PluginViewPresetIdArgs.extend({
+  fromDrawingId: z.string().min(1),
+})
+export type PluginViewPresetUpdateArgs = z.infer<
+  typeof PluginViewPresetUpdateArgs
+>
+export const PluginViewPresetDeleteArgs = PluginViewPresetIdArgs.extend({
+  replacementId: z.string().min(1),
+})
+export type PluginViewPresetDeleteArgs = z.infer<
+  typeof PluginViewPresetDeleteArgs
+>
+
+/**
+ * Reusable styles for kernel-plan drawings, stored in the Present document.
+ *
+ * A preset holds every style category of a native kernel plan. A drawing is
+ * bound to one with {@linkcode PluginPresentationDrawingsApi.applyPreset}; its
+ * own style changes are overrides on top, dropped by
+ * {@linkcode PluginPresentationDrawingsApi.resetOverrides}. Presets apply only
+ * to drawings whose `drawings.getCapabilities(drawingId).presets` is `true`.
+ * Local title text is excluded from preset values.
+ *
+ * Presets are document-local; their ids survive reload. Built-in presets are
+ * immutable. Catalog writes (`create`, `copy`, `rename`, `update`, `delete`)
+ * are native document metadata and are **not undoable**; binding a drawing or
+ * changing its overrides uses Present undo. Every method requires **Present
+ * mode to be open** and throws `PRECONDITION_FAILED` ("Present mode is not
+ * open") when it is closed; no method switches tabs.
+ *
+ * Accessed via `snaptrude.presentation.viewPresets`.
+ */
+export abstract class PluginPresentationViewPresetsApi {
+  /**
+   * List the preset catalog: built-ins first, then custom presets by name.
+   *
+   * @returns Every {@linkcode PluginViewPreset}.
+   * @throws `PRECONDITION_FAILED` if Present mode is not open.
+   *
+   * @examplePrompt List the available drawing style presets
+   * @examplePrompt Which custom presets does this presentation have?
+   * @examplePrompt Is there a Planning Issue preset?
+   *
+   * # Example
+   * ```ts
+   * const presets = await snaptrude.presentation.viewPresets.list()
+   * const custom = presets.filter((preset) => !preset.builtIn)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginViewPreset[]>
+
+  /**
+   * Read one preset by id.
+   *
+   * @param presetId - The preset to read.
+   * @returns The {@linkcode PluginViewPreset}, or `null` if no preset has that id.
+   * @throws `PRECONDITION_FAILED` if Present mode is not open.
+   *
+   * @examplePrompt Which preset is this drawing using?
+   * @examplePrompt Is this preset a built-in one?
+   * @examplePrompt Read the preset bound to the ground floor plan
+   *
+   * # Example
+   * ```ts
+   * const drawing = await snaptrude.presentation.drawings.get(drawingId)
+   * const preset = drawing?.presetId
+   *   ? await snaptrude.presentation.viewPresets.get(drawing.presetId)
+   *   : null
+   * ```
+   */
+  public abstract get(
+    presetId: string,
+  ): PluginApiReturn<PluginViewPreset | null>
+
+  /**
+   * Save a kernel-plan drawing's effective styles as a new custom preset and
+   * bind that drawing to it. Not undoable (catalog write).
+   *
+   * @param name - A unique preset name (non-empty after trimming).
+   * @param options - `fromDrawingId`: the kernel-plan drawing to take styles from.
+   * @returns The new {@linkcode PluginViewPreset}.
+   * @throws `VALIDATION` for an empty or duplicate name (with a hint);
+   *   `PRECONDITION_FAILED` if Present mode is not open, the document is
+   *   read-only, or the drawing is not a kernel vector plan (each with a
+   *   hint); `HANDLE_INVALID` if `fromDrawingId` is not a drawing.
+   *
+   * @examplePrompt Save this drawing's styles as a new preset
+   * @examplePrompt Make a preset called Planning Issue from this plan
+   * @examplePrompt Turn my restyled drawing into a reusable style
+   *
+   * # Example
+   * ```ts
+   * const capabilities = await snaptrude.presentation.drawings.getCapabilities(drawing.id)
+   * if (capabilities.presets) {
+   *   const preset = await snaptrude.presentation.viewPresets.create("Planning Issue", {
+   *     fromDrawingId: drawing.id,
+   *   })
+   * }
+   * ```
+   */
+  public abstract create(
+    name: string,
+    options: { fromDrawingId: string },
+  ): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Duplicate a preset under a native-generated unique name. Drawing bindings
+   * do not change. Not undoable (catalog write). Built-ins can be copied.
+   *
+   * @param presetId - The preset to copy.
+   * @returns The new custom {@linkcode PluginViewPreset}.
+   * @throws `PRECONDITION_FAILED` if Present mode is not open or the document
+   *   is read-only (each with a hint); `HANDLE_INVALID` if `presetId` does not
+   *   exist.
+   *
+   * @examplePrompt Duplicate this preset
+   * @examplePrompt Make an editable copy of the built-in preset
+   * @examplePrompt Copy the Planning Issue preset so I can change it
+   *
+   * # Example
+   * ```ts
+   * const copy = await snaptrude.presentation.viewPresets.copy(preset.id)
+   * await snaptrude.presentation.viewPresets.rename(copy.id, "Planning Issue B")
+   * ```
+   */
+  public abstract copy(presetId: string): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Rename a custom preset. Names must stay unique; built-ins cannot be
+   * renamed. Not undoable (catalog write).
+   *
+   * @param presetId - The custom preset to rename.
+   * @param name - The new unique name (non-empty after trimming).
+   * @returns The renamed {@linkcode PluginViewPreset}.
+   * @throws `VALIDATION` when the catalog refuses: an empty or duplicate name,
+   *   a built-in preset, or an unknown `presetId` (with a hint);
+   *   `PRECONDITION_FAILED` if Present mode is not open or the document is
+   *   read-only (each with a hint).
+   *
+   * @examplePrompt Rename this preset to Client Review
+   * @examplePrompt Call the copied preset Planning Issue B
+   * @examplePrompt Change the name of my custom drawing style
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.viewPresets.rename(preset.id, "Client Review")
+   * ```
+   */
+  public abstract rename(
+    presetId: string,
+    name: string,
+  ): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Replace a custom preset's values with the effective styles of a drawing
+   * already bound to it, then refresh every bound drawing. Built-ins cannot
+   * be updated. Not undoable (catalog write).
+   *
+   * @param presetId - The custom preset to update.
+   * @param options - `fromDrawingId`: a kernel-plan drawing bound to this preset.
+   * @returns The updated {@linkcode PluginViewPreset} (its `revision` grows).
+   * @throws `VALIDATION` when the catalog refuses: a built-in preset (with a
+   *   hint); `PRECONDITION_FAILED` if Present mode is not open, the document
+   *   is read-only, or the drawing is not a kernel vector plan bound to this
+   *   preset (each with a hint); `HANDLE_INVALID` if `fromDrawingId` is not a
+   *   drawing.
+   *
+   * @examplePrompt Update this preset from the current drawing styles
+   * @examplePrompt Push my style changes to every drawing using this preset
+   * @examplePrompt Save these overrides into the Planning Issue preset
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.viewPresets.update(drawing.presetId!, {
+   *   fromDrawingId: drawing.id,
+   * })
+   * ```
+   */
+  public abstract update(
+    presetId: string,
+    options: { fromDrawingId: string },
+  ): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Delete a custom preset and rebind its drawings to another existing
+   * preset. Built-ins cannot be deleted. Not undoable (catalog write).
+   *
+   * @param presetId - The custom preset to delete.
+   * @param options - `replacementId`: the existing preset its drawings move to
+   *   (not the deleted one).
+   * @returns Nothing.
+   * @throws `VALIDATION` when the catalog refuses: a built-in or unknown
+   *   `presetId`, or an unknown `replacementId` (with a hint);
+   *   `PRECONDITION_FAILED` if Present mode is not open or the document is
+   *   read-only (each with a hint).
+   *
+   * @examplePrompt Delete this preset
+   * @examplePrompt Remove the old style preset and switch its drawings to the default
+   * @examplePrompt Get rid of the Planning Issue B preset
+   *
+   * # Example
+   * ```ts
+   * const presets = await snaptrude.presentation.viewPresets.list()
+   * const replacement = presets.find((each) => each.builtIn)!
+   * await snaptrude.presentation.viewPresets.delete(customPreset.id, {
+   *   replacementId: replacement.id,
+   * })
+   * ```
+   */
+  public abstract delete(
+    presetId: string,
+    options: { replacementId: string },
+  ): PluginApiReturn<void>
+}

package/src/api/presentation/views.ts

@@ -2,7 +2,7 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 
 /**
- * Presentation views — read the saved 2D/3D views used to prepare presentations.
+ * 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
@@ -24,10 +24,10 @@ export abstract class PluginPresentationViewsApi {
    * 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).
+   *   of plan, 3D, and elevation views (empty when the project has none).
    *
    * @examplePrompt List all the saved views
-   * @examplePrompt What 2D and 3D views are in this project?
+   * @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
@@ -115,6 +115,10 @@ export abstract class PluginPresentationViewsApi {
    * 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.
@@ -138,6 +142,15 @@ export abstract class PluginPresentationViewsApi {
    *
    * 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
@@ -315,13 +328,36 @@ export abstract class PluginPresentationViewsApi {
 }
 
 /**
- * The kind of a saved view: a 2D plan view or a 3D view.
+ * 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"])
+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.
  *
@@ -329,7 +365,9 @@ export type PluginPresentationViewType = z.infer<
  * |---|---|---|
  * | `id` | `string` | Unique view id |
  * | `name` | `string` | Display name |
- * | `type` | `"2d" \| "3d"` | Whether this is a 2D plan view or a 3D view |
+ * | `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) |
  */
@@ -337,6 +375,8 @@ 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(),
 })

package/src/errors/codes.ts

@@ -7,6 +7,8 @@
  * (`HANDLE_INVALID`) so error responses cannot be used as an existence /
  * ownership oracle (PLUGIN_HANDLE_MIGRATION_HLD §6). `HANDLE_KIND_MISMATCH`
  * stays distinct because the kind is information the caller already holds.
+ * `HANDLE_STALE` is the one deliberate exception: a handle the caller
+ * legitimately held whose entity was since retired (deleted or rebuilt).
  */
 export const PLUGIN_ERROR_CODES = [
   "VALIDATION",
@@ -34,6 +36,7 @@ export const PLUGIN_ERROR_CODES = [
   "PROPOSAL_SWITCH_BLOCKED",
   "INTERNAL",
   "UNKNOWN",
+  "HANDLE_STALE",
 ] as const
 
 export type PluginErrorCode = (typeof PLUGIN_ERROR_CODES)[number]
@@ -85,6 +88,10 @@ export const CODE_META: Record<PluginErrorCode, CodeMeta> = {
     hintTemplate: "Re-query the entity; do not cache handles across undo/reload.",
   },
   HANDLE_KIND_MISMATCH: { category: "handle" },
+  HANDLE_STALE: {
+    category: "handle",
+    hintTemplate: "The entity was deleted or rebuilt; re-query it for a fresh handle.",
+  },
   RESOURCE_QUOTA_EXCEEDED: {
     category: "quota",
     hintTemplate: "Release unused handles (core.handles.release) or use scopes.",