@snaptrude/plugin-core 0.9.16-networks-20261012.1 → 0.9.17

package/src/api/presentation/drawings.ts

@@ -1,1179 +0,0 @@
-import * as z from "zod"
-import type { PluginApiReturn } from "../../types"
-import {
-  PluginPlacedView,
-  PluginPlacedViewCrop,
-  PluginPlacedViewStylePatch,
-  PluginViewLineStyle,
-  PluginPlacedViewLabel,
-} from "./placedViews"
-import { PluginSheetPosition } from "./sheets"
-import { PluginPresentationExportResolution } from "./export"
-import {
-  PluginExportFileName,
-  PluginStandardDrawingScale,
-} from "./drawingContract"
-
-/** Drawing ids are existing Present view-shape ids, stable across reload and undo. */
-export const PluginDrawingIdArgs = z
-  .object({ drawingId: z.string().min(1) })
-  .strict()
-export const PluginDrawingNameArgs = PluginDrawingIdArgs.extend({
-  name: z.string().trim().min(1),
-})
-export const PluginDrawingIdsArgs = z
-  .object({ drawingIds: z.array(z.string().min(1)).min(1).max(100) })
-  .strict()
-export const PluginDrawingCreateOptions = z
-  .object({
-    position: PluginSheetPosition.optional(),
-    scale: PluginStandardDrawingScale.optional(),
-  })
-  .strict()
-export type PluginDrawingCreateOptions = z.infer<
-  typeof PluginDrawingCreateOptions
->
-export const PluginDrawingCreateArgs = PluginDrawingCreateOptions.extend({
-  viewId: z.string().min(1),
-})
-export type PluginDrawingCreateArgs = z.infer<typeof PluginDrawingCreateArgs>
-export type PluginDrawingIdArgs = z.infer<typeof PluginDrawingIdArgs>
-export type PluginDrawingNameArgs = z.infer<typeof PluginDrawingNameArgs>
-export type PluginDrawingIdsArgs = z.infer<typeof PluginDrawingIdsArgs>
-export const PluginDrawingScaleArgs = PluginDrawingIdArgs.extend({
-  scale: PluginStandardDrawingScale,
-})
-export type PluginDrawingScaleArgs = z.infer<typeof PluginDrawingScaleArgs>
-export const PluginDrawingCropArgs = PluginDrawingIdArgs.extend({
-  crop: PluginPlacedViewCrop.nullable(),
-})
-export type PluginDrawingCropArgs = z.infer<typeof PluginDrawingCropArgs>
-export const PluginDrawingPresetArgs = PluginDrawingIdArgs.extend({
-  presetId: z.string().min(1),
-})
-export type PluginDrawingPresetArgs = z.infer<typeof PluginDrawingPresetArgs>
-
-/** Architectural scale is a denominator (100 means 1:100); positions are Present canvas units. */
-export const PluginDrawing = PluginPlacedView.extend({
-  id: z.string(),
-  presetId: z.string().nullable(),
-  kind: z.enum(["plan", "sitePlan", "threeD", "elevation"]),
-  direction: z.enum(["north", "east", "south", "west"]).nullable(),
-})
-export type PluginDrawing = z.infer<typeof PluginDrawing>
-
-const color = z.string().regex(/^#[0-9a-fA-F]{6}$/)
-const weight = z.number().finite().min(0).max(2.11)
-const opacity = z.number().finite().min(0).max(100)
-const pattern = z
-  .object({
-    id: z.string().min(1).optional(),
-    scale: z.number().finite().min(0.25).max(4).optional(),
-    color: color.optional(),
-    background: color.optional(),
-    weight: weight.optional(),
-  })
-  .strict()
-const face = z
-  .object({
-    fontStyle: z.enum(["400", "500", "700", "italic"]).optional(),
-    fontSize: z.enum(["12px", "16px", "24px", "2.5", "3.5", "5"]).optional(),
-    color: color.optional(),
-  })
-  .strict()
-const part = z
-  .object({
-    show: z.boolean().optional(),
-    lineStyle: PluginViewLineStyle.optional(),
-    weight: weight.optional(),
-  })
-  .strict()
-const title = z
-  .object({
-    show: z.boolean().optional(),
-    text: z.string().max(2000).optional(),
-  })
-  .strict()
-const material = z
-  .object({
-    show: z.boolean().optional(),
-    color: color.optional(),
-    pattern: pattern.optional(),
-  })
-  .strict()
-
-/**
- * Vector-plan row patch. Only controls returned by getStyles are accepted for that row.
- * Paper weights are mm; opacity is 0–100. Nested values merge, never replace the whole row.
- * Presets apply to kernel plans only; other drawings use the legacy category patch.
- */
-export const PluginDrawingVectorStylePatch = z
-  .object({
-    hide: z.boolean().optional(),
-    lineStyle: PluginViewLineStyle.optional(),
-    lineColor: color.optional(),
-    cutWidth: weight.optional(),
-    projectionWidth: weight.optional(),
-    weight: weight.optional(),
-    fillMode: z.string().optional(),
-    fillColor: color.optional(),
-    opacity: opacity.optional(),
-    pattern: pattern.optional(),
-    mask: z.boolean().optional(),
-    materials: z
-      .object({
-        brick: material.optional(),
-        glass: material.optional(),
-        concrete: material.optional(),
-        metalFrame: material.optional(),
-        woodFrame: material.optional(),
-        plaster: material.optional(),
-        paint: material.optional(),
-        insulation: material.optional(),
-      })
-      .strict()
-      .optional(),
-    components: z
-      .object({
-        frame: z.boolean().optional(),
-        leaf: z.boolean().optional(),
-        jambs: z.boolean().optional(),
-        glazing: z.boolean().optional(),
-        track: z.boolean().optional(),
-        operation: z.boolean().optional(),
-        operationStyle: PluginViewLineStyle.optional(),
-      })
-      .strict()
-      .optional(),
-    tag: z
-      .object({
-        show: z.boolean().optional(),
-        fontFamily: z.string().min(1).optional(),
-        fontStyle: z.enum(["400", "500", "700", "italic"]).optional(),
-        fontSize: z.enum(["12px", "16px", "24px"]).optional(),
-        frame: z.enum(["pill", "hexagon"]).optional(),
-        color: color.optional(),
-        opacity: opacity.optional(),
-        outline: weight.optional(),
-      })
-      .strict()
-      .optional(),
-    text: z
-      .object({
-        show: z.boolean().optional(),
-        labels: z.boolean().optional(),
-        areas: z.boolean().optional(),
-        department: z.boolean().optional(),
-        fontFamily: z.string().min(1).optional(),
-        color: color.optional(),
-        fontSize: z.enum(["12px", "16px", "24px"]).optional(),
-        label: face.optional(),
-        metrics: face.optional(),
-        title: face.optional(),
-        scale: face.optional(),
-      })
-      .strict()
-      .optional(),
-    detail: z
-      .object({ show: z.boolean().optional(), weight: weight.optional() })
-      .strict()
-      .optional(),
-    belowCut: part.optional(),
-    aboveCut: part.optional(),
-    underlay: part.optional(),
-    walkLine: part.optional(),
-    breakLine: part.optional(),
-    overlay: part.optional(),
-    title: title.optional(),
-    proposal: title.optional(),
-    building: title.optional(),
-    scale: z
-      .object({
-        show: z.boolean().optional(),
-        format: z.enum(["automatic", "ratio", "text"]).optional(),
-      })
-      .strict()
-      .optional(),
-    scaleBar: z
-      .object({
-        show: z.boolean().optional(),
-        format: z.enum(["divided", "simple"]).optional(),
-        length: z.enum(["1", "2", "5", "10"]).optional(),
-      })
-      .strict()
-      .optional(),
-    extension: z
-      .object({
-        show: z.boolean().optional(),
-        length: z.enum(["underTitle", "fullWidth"]).optional(),
-        weight: weight.optional(),
-        color: color.optional(),
-      })
-      .strict()
-      .optional(),
-    position: z.enum(["bottomLeft", "bottomCentre", "topLeft"]).optional(),
-  })
-  .strict()
-export const PluginDrawingStylePatch = z.union([
-  PluginDrawingVectorStylePatch,
-  PluginPlacedViewStylePatch,
-])
-export type PluginDrawingStylePatch = z.infer<typeof PluginDrawingStylePatch>
-export const PluginDrawingStylesArgs = PluginDrawingIdArgs.extend({
-  category: z.string().min(1),
-  patch: PluginDrawingStylePatch,
-})
-export type PluginDrawingStylesArgs = z.infer<typeof PluginDrawingStylesArgs>
-
-/** One selectable value exposed by a native drawing style control. */
-export const PluginDrawingStyleControlOption = z.object({
-  label: z.string(),
-  value: z.string(),
-})
-export type PluginDrawingStyleControlOption = z.infer<
-  typeof PluginDrawingStyleControlOption
->
-
-/** Numeric bounds exposed by a native drawing style control. */
-export const PluginDrawingStyleControlRange = z.object({
-  min: z.number().finite(),
-  max: z.number().finite(),
-  step: z.number().finite().positive(),
-})
-export type PluginDrawingStyleControlRange = z.infer<
-  typeof PluginDrawingStyleControlRange
->
-
-/** Description of one editable control returned by `drawings.getStyles`. */
-export const PluginDrawingStyleControl = z.object({
-  key: z.string(),
-  kind: z.string(),
-  options: z.array(PluginDrawingStyleControlOption).optional(),
-  range: PluginDrawingStyleControlRange.optional(),
-})
-export type PluginDrawingStyleControl = z.infer<
-  typeof PluginDrawingStyleControl
->
-
-/**
- * Read values differ from write patches: legacy renderers use -1 for an unset opacity and
- * include the read-only `disable` flag. These values must not be echoed as an update patch.
- */
-export const PluginDrawingStyleValues = z.union([
-  PluginDrawingVectorStylePatch,
-  z
-    .object({
-      ...PluginPlacedViewStylePatch.shape,
-      disable: z.boolean().optional(),
-      opacity: z.number().finite().min(-1).max(100).optional(),
-      mapOpacity: z.number().finite().min(-1).max(100).optional(),
-      buildingOpacity: z.number().finite().min(-1).max(100).optional(),
-    })
-    .strict(),
-])
-export type PluginDrawingStyleValues = z.infer<typeof PluginDrawingStyleValues>
-
-/** Read-only effective settings and editable controls for one drawing category. */
-export const PluginDrawingStyleCategory = z.object({
-  category: z.string(),
-  absent: z.boolean(),
-  settings: PluginDrawingStyleValues,
-  controls: z.array(PluginDrawingStyleControl),
-})
-export type PluginDrawingStyleCategory = z.infer<
-  typeof PluginDrawingStyleCategory
->
-
-/** Effective style categories and their native editing capabilities. */
-export const PluginDrawingStyles = z.object({
-  categories: z.array(PluginDrawingStyleCategory),
-})
-export type PluginDrawingStyles = z.infer<typeof PluginDrawingStyles>
-export const PluginDrawingStatus = z.object({
-  drawingId: z.string(),
-  generation: z.enum(["ready", "updating", "missing"]),
-  assetSave: z.enum(["uploading", "retrying", "uploaded", "missing"]),
-  layout: z.enum(["pending", "ready", "unsupported"]),
-  exportReady: z.boolean(),
-  warnings: z.array(z.string()),
-})
-export type PluginDrawingStatus = z.infer<typeof PluginDrawingStatus>
-export const PluginDrawingStatusArgs = PluginDrawingIdArgs.extend({
-  waitMs: z.number().finite().int().min(0).max(30000).optional(),
-})
-export type PluginDrawingStatusArgs = z.infer<typeof PluginDrawingStatusArgs>
-export const PluginDrawingExportFormat = z.enum(["pdf", "svg", "png", "jpg"])
-export type PluginDrawingExportFormat = z.infer<
-  typeof PluginDrawingExportFormat
->
-/** Renderer-specific operations and formats supported by a drawing. */
-export const PluginDrawingCapabilities = z.object({
-  renderer: z.enum(["vector", "hybrid", "raster", "unknown"]),
-  presets: z.boolean(),
-  labelLayout: z.boolean(),
-  architecturalScale: z.boolean(),
-  standardScales: z.array(
-    z.object({ label: z.string(), value: z.number().finite().positive() }),
-  ),
-  exportFormats: z.array(PluginDrawingExportFormat),
-})
-export type PluginDrawingCapabilities = z.infer<
-  typeof PluginDrawingCapabilities
->
-export const PluginDrawingExportOptions = z
-  .object({
-    fileName: PluginExportFileName.trim().min(1).max(200).optional(),
-    resolution: PluginPresentationExportResolution.optional(),
-    download: z.boolean().optional(),
-  })
-  .strict()
-export type PluginDrawingExportOptions = z.infer<
-  typeof PluginDrawingExportOptions
->
-export const PluginDrawingExportArgs = PluginDrawingIdArgs.extend({
-  format: PluginDrawingExportFormat,
-  ...PluginDrawingExportOptions.shape,
-})
-export type PluginDrawingExportArgs = z.infer<typeof PluginDrawingExportArgs>
-export const PluginDrawingExportResult = z.object({
-  files: z.array(
-    z.object({
-      fileName: z.string(),
-      mimeType: z.string(),
-      byteLength: z.number(),
-      dataBase64: z.string().optional(),
-    }),
-  ),
-  downloadStarted: z.boolean(),
-  warnings: z.array(z.string()),
-})
-export type PluginDrawingExportResult = z.infer<
-  typeof PluginDrawingExportResult
->
-
-export const PluginDrawingLabelArgs = z
-  .object({ labelId: z.string().min(1) })
-  .strict()
-export type PluginDrawingLabelArgs = z.infer<typeof PluginDrawingLabelArgs>
-export const PluginDrawingLabelMoveArgs = PluginDrawingLabelArgs.extend({
-  position: PluginSheetPosition,
-})
-export type PluginDrawingLabelMoveArgs = z.infer<
-  typeof PluginDrawingLabelMoveArgs
->
-export const PluginDrawingLabelHiddenArgs = PluginDrawingLabelArgs.extend({
-  hidden: z.boolean(),
-})
-export type PluginDrawingLabelHiddenArgs = z.infer<
-  typeof PluginDrawingLabelHiddenArgs
->
-export const PluginDrawingLabelResetArgs = PluginDrawingIdArgs.extend({
-  scope: z.enum(["scale", "all"]).optional(),
-})
-export type PluginDrawingLabelResetArgs = z.infer<
-  typeof PluginDrawingLabelResetArgs
->
-
-/**
- * Collision-layout diagnostics for drawing labels, including actionable scale suggestions.
- * `suggestedScale` is a larger standard scale (smaller denominator) at which the label would fit.
- */
-export const PluginDrawingLabelLayout = z.object({
-  pending: z.boolean(),
-  pinned: z.number().int().nonnegative(),
-  unplaced: z.array(
-    z.object({
-      labelId: z.string(),
-      name: z.string(),
-      reason: z.string(),
-      suggestedScale: z.number().finite().positive().nullable(),
-    }),
-  ),
-  duplicatesMerged: z.number().int().nonnegative(),
-  rowsDropped: z.object({
-    department: z.number().int().nonnegative(),
-    area: z.number().int().nonnegative(),
-    wrapped: z.number().int().nonnegative(),
-  }),
-})
-export type PluginDrawingLabelLayout = z.infer<typeof PluginDrawingLabelLayout>
-
-/**
- * The text labels of one drawing — room names, areas, tags — and the native
- * label layout that fits them.
- *
- * Label ids are the text-shape ids {@linkcode PluginDrawingLabelsApi.list}
- * returns. Positions are drawing-local canvas units. Room-label moves and
- * pins are stored per architectural scale, so a label moved at 1:100 keeps
- * its spot at 1:100 and is laid out afresh at 1:50. Every method requires
- * **Present mode to be open** and throws `PRECONDITION_FAILED` ("Present mode
- * is not open") when it is closed; writes use native Present undo.
- *
- * Accessed via `snaptrude.presentation.drawings.labels`.
- */
-export abstract class PluginDrawingLabelsApi {
-  /**
-   * List every text label on a drawing, including labels the user or the
-   * layout has hidden. An agent's own annotations under the drawing are not
-   * labels and are not listed.
-   *
-   * @param drawingId - The drawing to read.
-   * @returns The drawing's {@linkcode PluginPlacedViewLabel} rows
-   *   (`labelId`, `category`, `text`, `position`, `scale`, `hidden`).
-   * @throws `PRECONDITION_FAILED` if Present mode is not open;
-   *   `HANDLE_INVALID` if `drawingId` is not a drawing.
-   *
-   * @examplePrompt List all labels in this drawing
-   * @examplePrompt Which room labels are hidden on the ground floor drawing?
-   * @examplePrompt Show me the text of every label on this plan
-   *
-   * # Example
-   * ```ts
-   * const labels = await snaptrude.presentation.drawings.labels.list(drawing.id)
-   * const hidden = labels.filter((label) => label.hidden)
-   * ```
-   */
-  public abstract list(
-    drawingId: string,
-  ): PluginApiReturn<PluginPlacedViewLabel[]>
-
-  /**
-   * Read the label-layout diagnostics of a drawing: labels that could not be
-   * placed cleanly (each with a `suggestedScale` at which it would fit),
-   * pinned labels, merged duplicates and dropped rows. Reading never hides a
-   * label: an unplaced label is still shown at a best-effort position.
-   *
-   * @param drawingId - The drawing to read.
-   * @returns A {@linkcode PluginDrawingLabelLayout}. `pending: true` means
-   *   fitting is still running; read again after
-   *   {@linkcode PluginPresentationDrawingsApi.getStatus} with a `waitMs`.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open;
-   *   `HANDLE_INVALID` if `drawingId` is not a drawing.
-   *
-   * @examplePrompt Check this drawing for overlapping labels
-   * @examplePrompt Do all the room names fit on the ground floor drawing?
-   * @examplePrompt Which scale would make the labels on this plan readable?
-   *
-   * # Example
-   * ```ts
-   * const layout = await snaptrude.presentation.drawings.labels.getLayout(drawing.id)
-   * const suggested = layout.unplaced.find((row) => row.suggestedScale)?.suggestedScale
-   * if (suggested) await snaptrude.presentation.drawings.setScale(drawing.id, suggested)
-   * ```
-   */
-  public abstract getLayout(
-    drawingId: string,
-  ): PluginApiReturn<PluginDrawingLabelLayout>
-
-  /**
-   * Move a label within its drawing. A room label keeps the new position as a
-   * native pin at the drawing's current architectural scale; other labels
-   * move as plain text shapes. One Present undo step.
-   *
-   * @param labelId - The label to move (a `labelId` from `labels.list`).
-   * @param position - The new position, drawing-local canvas units.
-   * @returns The moved {@linkcode PluginPlacedViewLabel}.
-   * @throws `VALIDATION` for a malformed position; `PRECONDITION_FAILED` if
-   *   Present mode is not open, the document is read-only, the label or its
-   *   drawing is locked, or the label has not been laid out yet (each with a
-   *   hint); `HANDLE_INVALID` if `labelId` is not a drawing label.
-   *
-   * @examplePrompt Move the Kitchen label up a little
-   * @examplePrompt Put the living room name in the middle of the room
-   * @examplePrompt Nudge this label to the left
-   *
-   * # Example
-   * ```ts
-   * const [label] = await snaptrude.presentation.drawings.labels.list(drawing.id)
-   * await snaptrude.presentation.drawings.labels.move(label.labelId, {
-   *   x: label.position.x,
-   *   y: label.position.y - 20,
-   * })
-   * ```
-   */
-  public abstract move(
-    labelId: string,
-    position: z.infer<typeof PluginSheetPosition>,
-  ): PluginApiReturn<PluginPlacedViewLabel>
-
-  /**
-   * Hide or show a label. This is the user's own visibility, independent of
-   * labels the layout or a crop hides. One Present undo step.
-   *
-   * @param labelId - The label to change (a `labelId` from `labels.list`).
-   * @param hidden - `true` to hide the label, `false` to show it.
-   * @returns The updated {@linkcode PluginPlacedViewLabel}.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, or the label or its drawing is locked (each with a hint);
-   *   `HANDLE_INVALID` if `labelId` is not a drawing label.
-   *
-   * @examplePrompt Hide the Store label on this drawing
-   * @examplePrompt Show the corridor label again
-   * @examplePrompt Turn off the label for the plant room
-   *
-   * # Example
-   * ```ts
-   * const labels = await snaptrude.presentation.drawings.labels.list(drawing.id)
-   * const store = labels.find((label) => label.text.startsWith("Store"))
-   * if (store) await snaptrude.presentation.drawings.labels.setHidden(store.labelId, true)
-   * ```
-   */
-  public abstract setHidden(
-    labelId: string,
-    hidden: boolean,
-  ): PluginApiReturn<PluginPlacedViewLabel>
-
-  /**
-   * Pin a room label that could not be placed cleanly at the best position
-   * the native layout solver finds, at the current architectural scale. May
-   * wait up to ten seconds for a reloaded drawing's fit data. One Present undo
-   * step.
-   *
-   * @param labelId - An unplaced room label (a `labelId` from
-   *   `labels.getLayout(drawingId).unplaced`).
-   * @returns `true` when the label was pinned; `false` when it was already
-   *   placed cleanly or the solver found no position (nothing changes).
-   * @throws `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, or the label or its drawing is locked (each with a hint);
-   *   `HANDLE_INVALID` if `labelId` is not a drawing label.
-   *
-   * @examplePrompt Place the labels that do not fit
-   * @examplePrompt Pin the Kitchen label where it fits best
-   * @examplePrompt Fix the overlapping room names on this drawing
-   *
-   * # Example
-   * ```ts
-   * const { unplaced } = await snaptrude.presentation.drawings.labels.getLayout(drawing.id)
-   * for (const row of unplaced) {
-   *   await snaptrude.presentation.drawings.labels.place(row.labelId)
-   * }
-   * ```
-   */
-  public abstract place(labelId: string): PluginApiReturn<boolean>
-
-  /**
-   * Clear room-label pins (from `move`, `place` or the user) so the native
-   * layout places those labels again: at the current architectural scale by
-   * default, or at every scale with `{ scope: "all" }`. One Present undo step.
-   *
-   * @param drawingId - The drawing whose pins to clear.
-   * @param options - Optional `scope`: `"scale"` (default, the current scale)
-   *   or `"all"` (every scale).
-   * @returns The number of pins cleared (`0` when there were none; nothing changes).
-   * @throws `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, or the drawing is locked (each with a hint); `HANDLE_INVALID`
-   *   if `drawingId` is not a drawing.
-   *
-   * @examplePrompt Reset the label positions on this drawing
-   * @examplePrompt Undo all my label moves at every scale
-   * @examplePrompt Let the room labels lay themselves out again
-   *
-   * # Example
-   * ```ts
-   * const cleared = await snaptrude.presentation.drawings.labels.reset(drawing.id, {
-   *   scope: "all",
-   * })
-   * ```
-   */
-  public abstract reset(
-    drawingId: string,
-    options?: { scope?: "scale" | "all" },
-  ): PluginApiReturn<number>
-}
-
-/**
- * Drawing deliverables on the Present canvas: plans, site plans, elevations
- * and 3D drawings generated from saved {@linkcode PluginPresentationViewsApi}
- * views, independent of sheet composition.
- *
- * A drawing is the native Present view shape. It needs no sheet: it can stay
- * loose on the canvas, be exported on its own, or be put on a sheet with
- * {@linkcode PluginPresentationSheetsApi.placeDrawing} (scaled down to fit).
- * `create` never puts a drawing on a sheet; to make a drawing of a view on a
- * sheet in one call use {@linkcode PluginPresentationSheetsApi.place}. Drawing ids are stable
- * across reload and undo. Native shape history and sync are reused: writes are
- * gated and use Present undo.
- *
- * **Drawings or placed views?** A drawing id is the same shape id
- * {@linkcode PluginPresentationPlacedViewsApi} addresses, so both namespaces
- * reach the same view shape. `drawings` is the drawing-deliverable surface:
- * kernel-plan styles and presets, label layout, status and single-drawing
- * export. Use it for drawings made with `drawings.create`; keep `placedViews`
- * for views placed with `sheets.place` and for its generic canvas-shape calls.
- * Do not mix the two for one shape in the same task: `drawings.setScale` also
- * moves a drawing clear of a neighbour it grew over, `placedViews.setScale`
- * does not.
- *
- * **Looking at a drawing.** These calls change drawings, not the Present
- * camera. To see a result, frame it and screenshot the Present canvas:
- * `presentation.camera.zoomTo(drawing.id)` then
- * `presentation.camera.capture()`. `presentation.views.capture` and
- * `core.camera` look at the Design (3D) canvas, not this one.
- *
- * Every method, including the catalog reads, requires **Present mode to be
- * open** and throws `PRECONDITION_FAILED` ("Present mode is not open") when it
- * is closed or closes during the call; no method switches tabs. Every
- * `PRECONDITION_FAILED` carries a `hint` saying what to do next. Creating does
- * not wait for the asset upload: read {@linkcode PluginPresentationDrawingsApi.getStatus}.
- * `assetSave: "uploaded"` describes the asset, not a server acknowledgement of
- * document sync.
- *
- * Accessed via `snaptrude.presentation.drawings`.
- */
-export abstract class PluginPresentationDrawingsApi {
-  /** The drawing's text labels and label layout. See {@linkcode PluginDrawingLabelsApi}. */
-  public abstract labels: PluginDrawingLabelsApi
-
-  /**
-   * Generate a drawing from a saved view. Creates the drawing beside its
-   * source view on the canvas, never on a sheet; to put a drawing on a sheet use
-   * `presentation.sheets.place(sheetId, viewId)` (fits it to the sheet) or
-   * `presentation.sheets.placeDrawing(sheetId, drawingId)` (moves this drawing
-   * onto the sheet, scaled down to fit).
-   * Omit `position` unless the user asked for a specific place: the host puts
-   * the new drawing next to its source view, clear of other drawings. An
-   * explicit `position` (page coordinates, the drawing's centre) is kept and
-   * can land on top of an existing drawing. The user's selection is left as
-   * it was.
-   * Changes the drawing, not the Present camera. The Present view may follow
-   * the drawing as a courtesy to a user watching (never zooming in, not while
-   * the camera is locked); to look at it, call
-   * `presentation.camera.zoomTo(drawing.id)` then
-   * `presentation.camera.capture()`.
-   * `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.
-   * `scale` applies to plans, site plans and elevations; leave it out for a 3D view.
-   * After creating, read `labels.getLayout(drawingId)`: when labels are unplaced and carry
-   * a `suggestedScale`, move to that larger scale with `setScale`. To apply a
-   * preset, create first and then call `applyPreset`.
-   *
-   * @param viewId - The saved view to draw (an id from `presentation.views.list`).
-   * @param options - Optional `position` (page coordinates) and `scale`
-   *   (a standard denominator).
-   * @returns The new {@linkcode PluginDrawing}.
-   * @throws `VALIDATION` for a non-standard `scale` (the message lists the
-   *   allowed ones); `PRECONDITION_FAILED` if Present mode is not open, the
-   *   document is read-only, or a `scale` is given for a 3D view (each with a
-   *   hint); `HANDLE_INVALID` if `viewId` is not a saved view;
-   *   `OPERATION_FAILED` if generation produced no drawing.
-   *
-   * @examplePrompt Create a drawing from the ground floor view
-   * @examplePrompt Make a 1:100 plan drawing of level 2
-   * @examplePrompt Draw the north elevation at 1/8" = 1'
-   * @examplePrompt Put the site plan view on the Present canvas as a drawing
-   *
-   * # Example
-   * ```ts
-   * const { views } = await snaptrude.presentation.views.list()
-   * const plan = views.find((view) => view.kind === "plan")!
-   * const drawing = await snaptrude.presentation.drawings.create(plan.id, { scale: 100 })
-   * await snaptrude.presentation.camera.zoomTo(drawing.id)
-   * const { image } = await snaptrude.presentation.camera.capture()
-   * // To put it on a sheet: await snaptrude.presentation.sheets.placeDrawing(sheet.id, drawing.id)
-   * ```
-   */
-  public abstract create(
-    viewId: string,
-    options?: PluginDrawingCreateOptions,
-  ): PluginApiReturn<PluginDrawing>
-
-  /**
-   * List the drawings on the current Present page, loose or on sheets.
-   *
-   * @returns Every {@linkcode PluginDrawing} on the page (empty when there are none).
-   * @throws `PRECONDITION_FAILED` if Present mode is not open.
-   *
-   * @examplePrompt List all drawings in this presentation
-   * @examplePrompt Which drawings are not on a sheet yet?
-   * @examplePrompt What scale is each plan drawing at?
-   *
-   * # Example
-   * ```ts
-   * const drawings = await snaptrude.presentation.drawings.list()
-   * const loose = drawings.filter((drawing) => !drawing.sheetId)
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginDrawing[]>
-
-  /**
-   * Read one drawing by its stable id.
-   *
-   * @param drawingId - The drawing to read.
-   * @returns The {@linkcode PluginDrawing}, or `null` if no drawing has that id
-   *   (for example, it was deleted).
-   * @throws `PRECONDITION_FAILED` if Present mode is not open.
-   *
-   * @examplePrompt Does the ground floor drawing still exist?
-   * @examplePrompt What preset is this drawing using?
-   * @examplePrompt Read the scale and crop of this drawing
-   *
-   * # Example
-   * ```ts
-   * const current = await snaptrude.presentation.drawings.get(drawing.id)
-   * if (current) console.log(current.scale, current.presetId)
-   * ```
-   */
-  public abstract get(drawingId: string): PluginApiReturn<PluginDrawing | null>
-
-  /**
-   * Duplicate a drawing with its labels and annotations (native duplication,
-   * offset slightly from the original). One Present undo step. The copy keeps
-   * the original's source view, scale, crop, styles and preset binding.
-   *
-   * @param drawingId - The drawing to copy.
-   * @returns The new {@linkcode PluginDrawing}.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, or the drawing is locked (each with a hint); `HANDLE_INVALID`
-   *   if `drawingId` is not a drawing; `OPERATION_FAILED` if the copy failed.
-   *
-   * @examplePrompt Duplicate this drawing
-   * @examplePrompt Make a copy of the ground floor plan drawing
-   * @examplePrompt Copy this drawing so I can try a different style
-   *
-   * # Example
-   * ```ts
-   * const copy = await snaptrude.presentation.drawings.copy(drawing.id)
-   * await snaptrude.presentation.drawings.rename(copy.id, "Ground Floor (option B)")
-   * ```
-   */
-  public abstract copy(drawingId: string): PluginApiReturn<PluginDrawing>
-
-  /**
-   * Set the drawing's own title text. The source saved view keeps its name.
-   * One Present undo step.
-   *
-   * @param drawingId - The drawing to rename.
-   * @param name - The new title (non-empty after trimming).
-   * @returns The updated {@linkcode PluginDrawing}.
-   * @throws `VALIDATION` for an empty name; `PRECONDITION_FAILED` if Present
-   *   mode is not open, the document is read-only, or the drawing is locked
-   *   (each with a hint); `HANDLE_INVALID` if `drawingId` is not a drawing.
-   *
-   * @examplePrompt Rename this drawing to Ground Floor Plan
-   * @examplePrompt Change the title of the elevation drawing
-   * @examplePrompt Call this drawing Level 2 General Arrangement
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.drawings.rename(drawing.id, "Ground Floor Plan")
-   * ```
-   */
-  public abstract rename(
-    drawingId: string,
-    name: string,
-  ): PluginApiReturn<PluginDrawing>
-
-  /**
-   * Delete a drawing with its labels and annotations, as one Present undo
-   * step. The source saved view is not deleted.
-   *
-   * @param drawingId - The drawing to delete.
-   * @returns Nothing.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, or the drawing is locked (each with a hint); `HANDLE_INVALID`
-   *   if `drawingId` is not a drawing.
-   *
-   * @examplePrompt Delete this drawing
-   * @examplePrompt Remove the old elevation drawing from the canvas
-   * @examplePrompt Get rid of the duplicate plan drawing
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.drawings.delete(drawing.id)
-   * ```
-   */
-  public abstract delete(drawingId: string): PluginApiReturn<void>
-
-  /**
-   * Regenerate one to 100 drawings from their source views, after the model
-   * or the view changed. Waits for the update to finish.
-   *
-   * @param drawingIds - The drawings to regenerate (1 to 100 ids).
-   * @returns One `{ drawingId, updated }` row per drawing; `updated` means the
-   *   drawing's asset actually changed, not merely that the id was submitted.
-   * @throws `VALIDATION` for an empty list or more than 100 ids;
-   *   `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, a drawing is locked, or another drawing update is running
-   *   (each with a hint); `HANDLE_INVALID` if an id is not a drawing.
-   *
-   * @examplePrompt Update this drawing with my latest model changes
-   * @examplePrompt Refresh all the drawings
-   * @examplePrompt Regenerate the ground floor plan drawing
-   *
-   * # Example
-   * ```ts
-   * const drawings = await snaptrude.presentation.drawings.list()
-   * const results = await snaptrude.presentation.drawings.updateContent(
-   *   drawings.map((drawing) => drawing.id),
-   * )
-   * ```
-   */
-  public abstract updateContent(
-    drawingIds: string[],
-  ): PluginApiReturn<{ drawingId: string; updated: boolean }[]>
-
-  /**
-   * Read what a drawing supports: its actual renderer, whether it takes
-   * presets (native kernel plans only), label layout and an architectural
-   * scale, the standard scales for this project, and its export formats. Read
-   * this before preset, scale, label-layout, style or export writes instead of
-   * inferring support from the source view.
-   *
-   * @param drawingId - The drawing to read.
-   * @returns A {@linkcode PluginDrawingCapabilities}.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open;
-   *   `HANDLE_INVALID` if `drawingId` is not a drawing.
-   *
-   * @examplePrompt What editing capabilities does this drawing support?
-   * @examplePrompt Can I apply a preset to this drawing?
-   * @examplePrompt Which scales can this drawing use?
-   *
-   * # Example
-   * ```ts
-   * const capabilities = await snaptrude.presentation.drawings.getCapabilities(drawing.id)
-   * if (capabilities.presets) {
-   *   await snaptrude.presentation.drawings.applyPreset(drawing.id, preset.id)
-   * }
-   * ```
-   */
-  public abstract getCapabilities(
-    drawingId: string,
-  ): PluginApiReturn<PluginDrawingCapabilities>
-
-  /**
-   * Read a drawing's generation, label-layout and asset-upload state,
-   * optionally waiting up to `waitMs` (0 by default, at most 30,000) for it
-   * to become export-ready and uploaded. A timeout is not an error: the
-   * current state is returned. Read this before export or before closing
-   * Present mode.
-   *
-   * @param drawingId - The drawing to read.
-   * @param options - Optional `waitMs` (0 to 30,000 ms).
-   * @returns A {@linkcode PluginDrawingStatus}.
-   * @throws `VALIDATION` for a `waitMs` out of range; `PRECONDITION_FAILED` if
-   *   Present mode is not open or closes while waiting; `HANDLE_INVALID` if
-   *   `drawingId` is not a drawing.
-   *
-   * @examplePrompt Is this drawing ready to export?
-   * @examplePrompt Wait for the new drawing to finish generating
-   * @examplePrompt Has the drawing been uploaded yet?
-   *
-   * # Example
-   * ```ts
-   * const status = await snaptrude.presentation.drawings.getStatus(drawing.id, {
-   *   waitMs: 10_000,
-   * })
-   * if (!status.exportReady) console.warn(status.warnings)
-   * ```
-   */
-  public abstract getStatus(
-    drawingId: string,
-    options?: { waitMs?: number },
-  ): PluginApiReturn<PluginDrawingStatus>
-
-  /**
-   * Set a drawing's architectural scale; perspective/isometric drawings reject this.
-   * `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.
-   * A loose drawing that grows over a neighbour it did not cover before moves
-   * to the nearest free spot, which `placedViews.setScale` does not do; an
-   * overlap the user made stays, and a drawing on a sheet never moves.
-   * Changes the drawing, not the Present camera. The Present view may follow
-   * the drawing as a courtesy to a user watching (never zooming in, not while
-   * the camera is locked); to look at it, call
-   * `presentation.camera.zoomTo(drawing.id)` then
-   * `presentation.camera.capture()`.
-   *
-   * @param drawingId - The drawing to rescale.
-   * @param scale - A standard architectural scale denominator.
-   * @returns The updated {@linkcode PluginDrawing}.
-   * @throws `VALIDATION` for a non-standard `scale` (the message lists the
-   *   allowed ones); `PRECONDITION_FAILED` if Present mode is not open, the
-   *   document is read-only, the drawing is locked, or it is a 3D
-   *   (perspective/isometric) drawing (each with a hint); `HANDLE_INVALID` if
-   *   `drawingId` is not a drawing.
-   *
-   * @examplePrompt Set this drawing to 1:50
-   * @examplePrompt Change the plan drawing scale to 1/4" = 1'
-   * @examplePrompt Make the ground floor drawing bigger so the labels fit
-   *
-   * # Example
-   * ```ts
-   * const layout = await snaptrude.presentation.drawings.labels.getLayout(drawing.id)
-   * const suggested = layout.unplaced.find((row) => row.suggestedScale)?.suggestedScale
-   * await snaptrude.presentation.drawings.setScale(drawing.id, suggested ?? 50)
-   * ```
-   */
-  public abstract setScale(
-    drawingId: string,
-    scale: number,
-  ): PluginApiReturn<PluginDrawing>
-
-  /**
-   * Crop a drawing to a window of itself, or pass `null` to remove the crop.
-   * Crop corners are 0–1 fractions of the uncropped drawing and must satisfy
-   * `topLeft < bottomRight` on both axes. One Present undo step.
-   * A loose drawing that grows over a neighbour it did not cover before (for
-   * example when the crop is removed) moves to the nearest free spot, which
-   * `placedViews.setCrop` does not do; an overlap the user made stays, and a
-   * drawing on a sheet never moves.
-   * Changes the drawing, not the Present camera. The Present view may follow
-   * the drawing as a courtesy to a user watching (never zooming in, not while
-   * the camera is locked); to look at it, call
-   * `presentation.camera.zoomTo(drawing.id)` then
-   * `presentation.camera.capture()`.
-   *
-   * @param drawingId - The drawing to crop.
-   * @param crop - `{ topLeft, bottomRight }` normalized corners, or `null` to
-   *   remove the crop.
-   * @returns The updated {@linkcode PluginDrawing}.
-   * @throws `VALIDATION` for corners outside 0–1 or out of order;
-   *   `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, or the drawing is locked (each with a hint);
-   *   `HANDLE_INVALID` if `drawingId` is not a drawing.
-   *
-   * @examplePrompt Crop this drawing to the left half
-   * @examplePrompt Remove the crop from the site plan drawing
-   * @examplePrompt Show only the top-right corner of this plan
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.drawings.setCrop(drawing.id, {
-   *   topLeft: { x: 0, y: 0 },
-   *   bottomRight: { x: 0.5, y: 1 },
-   * })
-   * await snaptrude.presentation.drawings.setCrop(drawing.id, null)
-   * ```
-   */
-  public abstract setCrop(
-    drawingId: string,
-    crop: z.infer<typeof PluginPlacedViewCrop> | null,
-  ): PluginApiReturn<PluginDrawing>
-
-  /**
-   * Read a drawing's effective style categories (preset plus its own
-   * overrides) and the controls each category accepts. Always read this
-   * before {@linkcode PluginPresentationDrawingsApi.updateStyles}: accepted
-   * categories and controls depend on the drawing, and an `absent` category
-   * rejects writes. Do not echo a whole `settings` record as a patch (legacy
-   * reads may include the read-only `disable` flag and `-1` for unset opacity).
-   *
-   * @param drawingId - The drawing to read.
-   * @returns A {@linkcode PluginDrawingStyles} with one row per category.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open;
-   *   `HANDLE_INVALID` if `drawingId` is not a drawing.
-   *
-   * @examplePrompt Show the editable styles for this drawing
-   * @examplePrompt What line weight are the walls drawn with?
-   * @examplePrompt Which categories can I restyle on this plan?
-   *
-   * # Example
-   * ```ts
-   * const styles = await snaptrude.presentation.drawings.getStyles(drawing.id)
-   * const editable = styles.categories.filter((row) => !row.absent)
-   * ```
-   */
-  public abstract getStyles(
-    drawingId: string,
-  ): PluginApiReturn<PluginDrawingStyles>
-
-  /**
-   * Merge a sparse style patch into one category of a drawing, as one Present
-   * undo step. Nested objects merge rather than replace the row. Line and
-   * outline weights are paper millimetres (0–2.11); opacity is 0–100; colours
-   * are `#rrggbb`. On a kernel plan the patch becomes the drawing's own
-   * overrides of its preset; other drawings take the legacy placed-view
-   * category patch. An absent category, an unsupported field or an invalid
-   * value rejects the whole write.
-   *
-   * @param drawingId - The drawing to restyle.
-   * @param category - A category id from `getStyles` whose `absent` is false.
-   * @param patch - A sparse {@linkcode PluginDrawingStylePatch} using only the
-   *   controls `getStyles` lists for that category.
-   * @returns The drawing's {@linkcode PluginDrawingStyles} after the write.
-   * @throws `VALIDATION` for an unsupported field or a value outside its
-   *   range; `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, the drawing is locked, or the category is absent on this
-   *   drawing (each with a hint); `HANDLE_INVALID` if `drawingId` is not a
-   *   drawing.
-   *
-   * @examplePrompt Make the walls on this drawing thicker
-   * @examplePrompt Fill the rooms at 60% opacity with a larger hatch
-   * @examplePrompt Turn off the door tags on this plan
-   *
-   * # Example
-   * ```ts
-   * const styles = await snaptrude.presentation.drawings.getStyles(drawing.id)
-   * const space = styles.categories.find((row) => row.category === "Space")
-   * if (space && !space.absent && space.controls.some((control) => control.key === "opacity")) {
-   *   await snaptrude.presentation.drawings.updateStyles(drawing.id, "Space", {
-   *     opacity: 60,
-   *     pattern: { scale: 1.5 },
-   *   })
-   * }
-   * ```
-   */
-  public abstract updateStyles(
-    drawingId: string,
-    category: string,
-    patch: PluginDrawingStylePatch,
-  ): PluginApiReturn<PluginDrawingStyles>
-
-  /**
-   * Bind a native kernel plan to a view preset and clear its declared
-   * overrides, so it takes the preset's styles. Local title, proposal and
-   * building text is kept. One Present undo step. Presets apply only to
-   * drawings whose `getCapabilities(drawingId).presets` is `true`.
-   *
-   * @param drawingId - The kernel-plan drawing to bind.
-   * @param presetId - The preset to apply (an id from `viewPresets.list`).
-   * @returns The updated {@linkcode PluginDrawing} (its `presetId` is set).
-   * @throws `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, the drawing is locked, or it is not a kernel vector plan
-   *   (each with a hint); `VALIDATION` if the catalog has no preset
-   *   `presetId` (with a hint); `HANDLE_INVALID` if `drawingId` is not a
-   *   drawing.
-   *
-   * @examplePrompt Apply the presentation plan preset to this drawing
-   * @examplePrompt Use the Planning Issue style on every plan drawing
-   * @examplePrompt Make this drawing look like the other plans
-   *
-   * # Example
-   * ```ts
-   * const presets = await snaptrude.presentation.viewPresets.list()
-   * const preset = presets.find((each) => each.name === "Planning Issue")
-   * if (preset) await snaptrude.presentation.drawings.applyPreset(drawing.id, preset.id)
-   * ```
-   */
-  public abstract applyPreset(
-    drawingId: string,
-    presetId: string,
-  ): PluginApiReturn<PluginDrawing>
-
-  /**
-   * Drop a kernel plan's own style overrides so it matches its bound preset
-   * again. Local title, proposal and building text is kept. One Present undo
-   * step.
-   *
-   * @param drawingId - The kernel-plan drawing to reset.
-   * @returns The updated {@linkcode PluginDrawing}.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open, the document is
-   *   read-only, the drawing is locked, or it is not a kernel vector plan
-   *   (each with a hint); `HANDLE_INVALID` if `drawingId` is not a drawing.
-   *
-   * @examplePrompt Reset this drawing to its preset styles
-   * @examplePrompt Undo my style changes on the ground floor plan
-   * @examplePrompt Clear the overrides on this drawing
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.drawings.resetOverrides(drawing.id)
-   * ```
-   */
-  public abstract resetOverrides(
-    drawingId: string,
-  ): PluginApiReturn<PluginDrawing>
-
-  /**
-   * List the hatch patterns the native pattern catalog offers. Use these ids
-   * in a style patch's `pattern.id` instead of inventing one.
-   *
-   * @returns `{ id, label, group }` rows, one per pattern.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open.
-   *
-   * @examplePrompt What hatch patterns can I use?
-   * @examplePrompt List the brick and concrete patterns
-   * @examplePrompt Which fill patterns are available for rooms?
-   *
-   * # Example
-   * ```ts
-   * const patterns = await snaptrude.presentation.drawings.listPatterns()
-   * const brick = patterns.find((pattern) => pattern.label.toLowerCase().includes("brick"))
-   * ```
-   */
-  public abstract listPatterns(): PluginApiReturn<
-    { id: string; label: string; group: string }[]
-  >
-
-  /**
-   * List the font families drawing text can use, from the native catalog
-   * (`"DEFAULT"` first). Use these names in a style patch's `fontFamily`
-   * instead of inventing one.
-   *
-   * @returns Font family names.
-   * @throws `PRECONDITION_FAILED` if Present mode is not open.
-   *
-   * @examplePrompt Which fonts can I use for drawing labels?
-   * @examplePrompt Is Inter available as a drawing font?
-   * @examplePrompt List the fonts for the title block
-   *
-   * # Example
-   * ```ts
-   * const fonts = await snaptrude.presentation.drawings.listFonts()
-   * const family = fonts.includes("Inter") ? "Inter" : "DEFAULT"
-   * ```
-   */
-  public abstract listFonts(): PluginApiReturn<string[]>
-
-  /**
-   * Export one drawing, with its labels and annotations, without a sheet.
-   * PDF size follows the drawing's canvas bounds; SVG and PDF keep vector
-   * content, raster fallbacks stay raster. `resolution` applies to raster
-   * formats. It does not wait for the canvas to paint, so it works while the
-   * user is on another browser tab.
-   * `download: true` starts a browser download and returns metadata only
-   * (never send large base64 to an agent); otherwise `files` carry
-   * `dataBase64`. `downloadStarted` means initiated, not proof of an OS-saved
-   * file. Layout warnings are returned.
-   * `fileName` is a base name WITHOUT an extension ("Floor Pattern View", never
-   * "Floor Pattern View.pdf"): the host appends .pdf/.svg/.png/.jpg for the
-   * format, and a name ending in .pdf, .svg, .png, .jpg or .jpeg, a dot or a
-   * space is rejected.
-   *
-   * @param drawingId - The drawing to export.
-   * @param format - `"pdf"`, `"svg"`, `"png"` or `"jpg"`.
-   * @param options - Optional `fileName` (base name, no extension),
-   *   `resolution` (raster formats) and `download`.
-   * @returns A {@linkcode PluginDrawingExportResult}: the files, whether a
-   *   download started, and layout warnings.
-   * @throws `VALIDATION` for a `fileName` with an extension or ending in a dot
-   *   or space, or a bad `resolution`; `PRECONDITION_FAILED` if Present mode is
-   *   not open or the drawing's asset is not ready yet (each with a hint);
-   *   `HANDLE_INVALID` if `drawingId` is not a drawing; `OPERATION_FAILED` if
-   *   the export failed.
-   *
-   * @examplePrompt Export this drawing as a PDF
-   * @examplePrompt Download the ground floor plan drawing as an SVG
-   * @examplePrompt Save this drawing as a high-resolution PNG
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.drawings.getStatus(drawing.id, { waitMs: 10_000 })
-   * const result = await snaptrude.presentation.drawings.export(drawing.id, "pdf", {
-   *   fileName: "Ground Floor Plan",
-   *   download: true,
-   * })
-   * ```
-   */
-  public abstract export(
-    drawingId: string,
-    format: PluginDrawingExportFormat,
-    options?: PluginDrawingExportOptions,
-  ): PluginApiReturn<PluginDrawingExportResult>
-}