@snaptrude/plugin-core 0.10.0 → 1.0.0

package/src/api/presentation/annotate.ts

@@ -34,14 +34,15 @@ export abstract class PluginPresentationAnnotateApi {
    * falls back to regular. `fontSizePx` sets an exact pixel size, overriding
    * the `size` preset when both are given (`size` alone keeps working).
    *
-   * @param sheetId - The sheet to annotate.
+   * @param sheetId - The sheet to annotate, or `undefined` when `options.drawingId` is used.
    * @param text - The label text.
    * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
    *   top-left, in canvas units — defaults to the sheet's top-left corner),
    *   `size` (`"s" | "m" | "l" | "xl"`, default `"m"`), `color` (a named
    *   palette color, default `"black"`), and typography: `fontFamily`,
    *   `fontWeight` (numeric string, `-italic` suffix allowed), `fontSizePx`
-   *   (positive px size overriding the `size` preset).
+   *   (positive px size overriding the `size` preset), and `drawingId` to parent
+   *   the annotation to a drawing. Pass exactly one parent: `sheetId` or `drawingId`.
    * @returns A {@linkcode PluginPresentationAnnotateTextResult} with the created
    *   `shapeId`.
    * @throws If Present mode is not open or the sheet id is invalid.
@@ -61,7 +62,7 @@ export abstract class PluginPresentationAnnotateApi {
    * ```
    */
   public abstract text(
-    sheetId: string,
+    sheetId: string | undefined,
     text: string,
     options?: {
       position?: { x: number; y: number }
@@ -70,6 +71,7 @@ export abstract class PluginPresentationAnnotateApi {
       fontFamily?: string
       fontWeight?: string
       fontSizePx?: number
+      drawingId?: string
     },
   ): PluginApiReturn<PluginPresentationAnnotateTextResult>
 
@@ -80,11 +82,12 @@ export abstract class PluginPresentationAnnotateApi {
    * top-left, in canvas units — the same Arrow tool as the Present toolbar) and
    * returns the id of the created canvas shape. Requires Present mode to be open.
    *
-   * @param sheetId - The sheet to annotate.
+   * @param sheetId - The sheet to annotate, or `undefined` when `options.drawingId` is used.
    * @param start - Arrow tail position (`{ x, y }`, relative to the sheet's top-left).
    * @param end - Arrow head position (`{ x, y }`, relative to the sheet's top-left).
    * @param options - Optional `color` (a named palette color, default `"black"`)
-   *   and `size` (stroke weight preset, `"s" | "m" | "l" | "xl"`, default `"m"`).
+   *   `size` (stroke weight preset, `"s" | "m" | "l" | "xl"`, default `"m"`),
+   *   and `drawingId` to parent the arrow to a drawing. Pass exactly one parent.
    * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
    *   `shapeId`.
    * @throws If Present mode is not open or the sheet id is invalid.
@@ -104,12 +107,13 @@ export abstract class PluginPresentationAnnotateApi {
    * ```
    */
   public abstract arrow(
-    sheetId: string,
+    sheetId: string | undefined,
     start: { x: number; y: number },
     end: { x: number; y: number },
     options?: {
       color?: PluginAnnotateTextColor
       size?: PluginAnnotateTextSize
+      drawingId?: string
     },
   ): PluginApiReturn<PluginPresentationAnnotateResult>
 
@@ -120,13 +124,14 @@ export abstract class PluginPresentationAnnotateApi {
    * fixed-size sticky square that grows with its text) and returns the id of
    * the created canvas shape. Requires Present mode to be open.
    *
-   * @param sheetId - The sheet to annotate.
+   * @param sheetId - The sheet to annotate, or `undefined` when `options.drawingId` is used.
    * @param text - The note text.
    * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
    *   top-left, in canvas units — defaults to the sheet's top-left corner),
    *   `color` (a named palette color, default `"black"` — rendered as the
    *   note's sticky fill), and `size` (text size preset,
-   *   `"s" | "m" | "l" | "xl"`, default `"m"`).
+   *   `"s" | "m" | "l" | "xl"`, default `"m"`), and `drawingId` to parent
+   *   the note to a drawing. Pass exactly one parent.
    * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
    *   `shapeId`.
    * @throws If Present mode is not open or the sheet id is invalid.
@@ -145,12 +150,13 @@ export abstract class PluginPresentationAnnotateApi {
    * ```
    */
   public abstract note(
-    sheetId: string,
+    sheetId: string | undefined,
     text: string,
     options?: {
       position?: { x: number; y: number }
       color?: PluginAnnotateTextColor
       size?: PluginAnnotateTextSize
+      drawingId?: string
     },
   ): PluginApiReturn<PluginPresentationAnnotateResult>
 
@@ -162,14 +168,15 @@ export abstract class PluginPresentationAnnotateApi {
    * top-left, in canvas units) and returns the id of the created canvas shape.
    * Requires Present mode to be open.
    *
-   * @param sheetId - The sheet to annotate.
+   * @param sheetId - The sheet to annotate, or `undefined` when `options.drawingId` is used.
    * @param kind - The shape kind ({@linkcode PluginAnnotateGeoKind}), e.g.
    *   `"rectangle"`, `"ellipse"`, `"cloud"`.
    * @param bounds - Placement box `{ x, y, w, h }` — `x`/`y` are the shape's
    *   top-left relative to the sheet's top-left; `w`/`h` must be positive.
    * @param options - Optional `color` (a named palette color, default
    *   `"black"`) and `fill` ({@linkcode PluginAnnotateFill}, default `"none"` —
-   *   outline only).
+   *   outline only), and `drawingId` to parent the shape to a drawing. Pass
+   *   exactly one parent: `sheetId` or `drawingId`.
    * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
    *   `shapeId`.
    * @throws If Present mode is not open or the sheet id is invalid.
@@ -189,12 +196,13 @@ export abstract class PluginPresentationAnnotateApi {
    * ```
    */
   public abstract shape(
-    sheetId: string,
+    sheetId: string | undefined,
     kind: PluginAnnotateGeoKind,
     bounds: { x: number; y: number; w: number; h: number },
     options?: {
       color?: PluginAnnotateTextColor
       fill?: PluginAnnotateFill
+      drawingId?: string
     },
   ): PluginApiReturn<PluginPresentationAnnotateResult>
 }
@@ -226,7 +234,8 @@ export type PluginAnnotateTextColor = z.infer<typeof PluginAnnotateTextColor>
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
+ * | `sheetId` | `string \| undefined` | The sheet parent; omit when `drawingId` is set |
+ * | `drawingId` | `string \| undefined` | The drawing parent; mutually exclusive with `sheetId` |
  * | `text` | `string` | The label text |
  * | `position` | `{ x: number; y: number } \| undefined` | Where to place it (relative to the sheet) |
  * | `size` | {@linkcode PluginAnnotateTextSize}` \| undefined` | Text size preset |
@@ -235,22 +244,27 @@ export type PluginAnnotateTextColor = z.infer<typeof PluginAnnotateTextColor>
  * | `fontWeight` | `string \| undefined` | Numeric weight like `"400"`/`"700"`, `-italic` suffix allowed |
  * | `fontSizePx` | `number \| undefined` | Exact px size (overrides the `size` preset) |
  */
-export const PluginPresentationAnnotateTextArgs = z.object({
-  sheetId: z.string(),
-  text: z.string(),
-  position: z.object({ x: z.number(), y: z.number() }).optional(),
-  size: PluginAnnotateTextSize.optional(),
-  color: PluginAnnotateTextColor.optional(),
-  fontFamily: z.string().min(1).optional(),
-  fontWeight: z
-    .string()
-    .regex(
-      /^\d{3}(-italic)?$/,
-      'fontWeight must be a numeric string like "400" or "700", optionally with the "-italic" suffix',
-    )
-    .optional(),
-  fontSizePx: z.number().finite().positive().optional(),
-})
+export const PluginPresentationAnnotateTextArgs = z
+  .object({
+    sheetId: z.string().min(1).optional(),
+    drawingId: z.string().min(1).optional(),
+    text: z.string(),
+    position: z.object({ x: z.number(), y: z.number() }).optional(),
+    size: PluginAnnotateTextSize.optional(),
+    color: PluginAnnotateTextColor.optional(),
+    fontFamily: z.string().min(1).optional(),
+    fontWeight: z
+      .string()
+      .regex(
+        /^\d{3}(-italic)?$/,
+        'fontWeight must be a numeric string like "400" or "700", optionally with the "-italic" suffix',
+      )
+      .optional(),
+    fontSizePx: z.number().finite().positive().optional(),
+  })
+  .refine(({ sheetId, drawingId }) => Boolean(sheetId) !== Boolean(drawingId), {
+    message: "exactly one of sheetId or drawingId is required",
+  })
 export type PluginPresentationAnnotateTextArgs = z.infer<
   typeof PluginPresentationAnnotateTextArgs
 >
@@ -302,19 +316,25 @@ export type PluginAnnotateFill = z.infer<typeof PluginAnnotateFill>
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
+ * | `sheetId` | `string \| undefined` | The sheet parent; omit when `drawingId` is set |
+ * | `drawingId` | `string \| undefined` | The drawing parent; mutually exclusive with `sheetId` |
  * | `start` | `{ x: number; y: number }` | Arrow tail (relative to the sheet) |
  * | `end` | `{ x: number; y: number }` | Arrow head (relative to the sheet) |
  * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Arrow color |
  * | `size` | {@linkcode PluginAnnotateTextSize}` \| undefined` | Stroke weight preset |
  */
-export const PluginPresentationAnnotateArrowArgs = z.object({
-  sheetId: z.string(),
-  start: z.object({ x: z.number(), y: z.number() }),
-  end: z.object({ x: z.number(), y: z.number() }),
-  color: PluginAnnotateTextColor.optional(),
-  size: PluginAnnotateTextSize.optional(),
-})
+export const PluginPresentationAnnotateArrowArgs = z
+  .object({
+    sheetId: z.string().min(1).optional(),
+    drawingId: z.string().min(1).optional(),
+    start: z.object({ x: z.number(), y: z.number() }),
+    end: z.object({ x: z.number(), y: z.number() }),
+    color: PluginAnnotateTextColor.optional(),
+    size: PluginAnnotateTextSize.optional(),
+  })
+  .refine(({ sheetId, drawingId }) => Boolean(sheetId) !== Boolean(drawingId), {
+    message: "exactly one of sheetId or drawingId is required",
+  })
 export type PluginPresentationAnnotateArrowArgs = z.infer<
   typeof PluginPresentationAnnotateArrowArgs
 >
@@ -324,19 +344,25 @@ export type PluginPresentationAnnotateArrowArgs = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
+ * | `sheetId` | `string \| undefined` | The sheet parent; omit when `drawingId` is set |
+ * | `drawingId` | `string \| undefined` | The drawing parent; mutually exclusive with `sheetId` |
  * | `text` | `string` | The note text |
  * | `position` | `{ x: number; y: number } \| undefined` | Where to place it (relative to the sheet) |
  * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Sticky fill color |
  * | `size` | {@linkcode PluginAnnotateTextSize}` \| undefined` | Text size preset |
  */
-export const PluginPresentationAnnotateNoteArgs = z.object({
-  sheetId: z.string(),
-  text: z.string(),
-  position: z.object({ x: z.number(), y: z.number() }).optional(),
-  color: PluginAnnotateTextColor.optional(),
-  size: PluginAnnotateTextSize.optional(),
-})
+export const PluginPresentationAnnotateNoteArgs = z
+  .object({
+    sheetId: z.string().min(1).optional(),
+    drawingId: z.string().min(1).optional(),
+    text: z.string(),
+    position: z.object({ x: z.number(), y: z.number() }).optional(),
+    color: PluginAnnotateTextColor.optional(),
+    size: PluginAnnotateTextSize.optional(),
+  })
+  .refine(({ sheetId, drawingId }) => Boolean(sheetId) !== Boolean(drawingId), {
+    message: "exactly one of sheetId or drawingId is required",
+  })
 export type PluginPresentationAnnotateNoteArgs = z.infer<
   typeof PluginPresentationAnnotateNoteArgs
 >
@@ -346,24 +372,30 @@ export type PluginPresentationAnnotateNoteArgs = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
+ * | `sheetId` | `string \| undefined` | The sheet parent; omit when `drawingId` is set |
+ * | `drawingId` | `string \| undefined` | The drawing parent; mutually exclusive with `sheetId` |
  * | `kind` | {@linkcode PluginAnnotateGeoKind} | The shape kind |
  * | `bounds` | `{ x: number; y: number; w: number; h: number }` | Placement box (relative to the sheet; `w`/`h` positive) |
  * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Outline color |
  * | `fill` | {@linkcode PluginAnnotateFill}` \| undefined` | Fill style |
  */
-export const PluginPresentationAnnotateShapeArgs = z.object({
-  sheetId: z.string(),
-  kind: PluginAnnotateGeoKind,
-  bounds: z.object({
-    x: z.number(),
-    y: z.number(),
-    w: z.number().positive(),
-    h: z.number().positive(),
-  }),
-  color: PluginAnnotateTextColor.optional(),
-  fill: PluginAnnotateFill.optional(),
-})
+export const PluginPresentationAnnotateShapeArgs = z
+  .object({
+    sheetId: z.string().min(1).optional(),
+    drawingId: z.string().min(1).optional(),
+    kind: PluginAnnotateGeoKind,
+    bounds: z.object({
+      x: z.number(),
+      y: z.number(),
+      w: z.number().positive(),
+      h: z.number().positive(),
+    }),
+    color: PluginAnnotateTextColor.optional(),
+    fill: PluginAnnotateFill.optional(),
+  })
+  .refine(({ sheetId, drawingId }) => Boolean(sheetId) !== Boolean(drawingId), {
+    message: "exactly one of sheetId or drawingId is required",
+  })
 export type PluginPresentationAnnotateShapeArgs = z.infer<
   typeof PluginPresentationAnnotateShapeArgs
 >

package/src/api/presentation/camera.ts

@@ -0,0 +1,289 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginPresentationImageFormat } from "./views"
+
+/**
+ * The Present-mode canvas camera — the Present-mode twin of
+ * {@linkcode PluginCameraApi} (`core.camera`).
+ *
+ * Present mode lays sheets out on an infinite 2D canvas; its camera is a pan
+ * (`x`, `y`) and a `zoom`. A plugin can screenshot what that canvas currently
+ * shows, read the camera, pan/zoom it, or frame all sheets or one shape.
+ *
+ * These are transient VIEW-STATE changes: not model edits, so they are not
+ * write-gated and not undoable. Every method requires **Present mode to be
+ * open** (the documentation editor) and throws `PRECONDITION_FAILED` when it is
+ * closed. `capture` is the Present-mode counterpart of
+ * {@linkcode PluginPresentationViewsApi.capture}, which shoots the Design
+ * (3D) canvas; for whole sheets at their own size use
+ * {@linkcode PluginPresentationApi.export}.
+ *
+ * Coordinates are Present canvas page units (pixels at 100% zoom), the same
+ * space `sheets`, `placedViews` and `shapes` report positions in. `zoom` is a
+ * factor: `1` = 100%, `0.5` = zoomed out to half size.
+ *
+ * Accessed via `snaptrude.presentation.camera`.
+ */
+export abstract class PluginPresentationCameraApi {
+  constructor() {}
+
+  /**
+   * Screenshot what the Present canvas currently shows.
+   *
+   * Captures exactly the visible area — the canvas as clipped by the window,
+   * minus the strip under the floating left sidebar — at the current pan and
+   * zoom, rendered
+   * through the same pipeline as the Present-mode Export dialog, so sheets,
+   * placed views, text, annotations and imported images look as they do on
+   * screen. Selection handles, cursors and the UI itself are not part of the
+   * image. Nothing on screen still yields an image (the export backdrop).
+   * Export-pipeline details, as in the Export dialog: sheet frames themselves
+   * are not drawn (no paper, margin guides or name label — editor chrome), the
+   * backdrop is tldraw's near-white export backdrop rather than the on-screen
+   * canvas grey, and with exactly one sheet in view it is white. Only the left
+   * sidebar is subtracted from the view; floating right-hand panels are not.
+   *
+   * @param options - All optional: `format` (`"png"` default, or `"jpeg"`),
+   *   `pixelRatio` (output pixels per screen pixel, `1`–`4`, default `1`;
+   *   `2` for a retina-sharp image).
+   * @returns A {@linkcode PluginPresentationCameraCaptureResult}: the base64
+   *   data URL and its pixel size.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Take a screenshot of the Present canvas
+   * @examplePrompt Capture what I am looking at in Present mode
+   * @examplePrompt Screenshot the presentation canvas as a JPEG
+   * @examplePrompt Grab a high-res image of the current sheet view
+   *
+   * # Example
+   * ```ts
+   * const { image, width, height } = await snaptrude.presentation.camera.capture({
+   *   format: "png",
+   *   pixelRatio: 2,
+   * })
+   * ```
+   */
+  public abstract capture(options?: {
+    format?: PluginPresentationImageFormat
+    pixelRatio?: number
+  }): PluginApiReturn<PluginPresentationCameraCaptureResult>
+
+  /**
+   * Read the Present camera: pan, zoom, the visible page-space rectangle and
+   * the sheet under the centre of the view.
+   *
+   * @returns The current {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Where is the Present canvas camera?
+   * @examplePrompt What zoom level is Present mode at?
+   * @examplePrompt Which sheet is on screen right now?
+   * @examplePrompt Read the visible area of the presentation canvas
+   *
+   * # Example
+   * ```ts
+   * const { zoom, sheetId } = await snaptrude.presentation.camera.get()
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginPresentationCameraState>
+
+  /**
+   * Pan and/or zoom the Present canvas. Fields left out keep their current
+   * value, so `{ zoom: 2 }` changes only the zoom (the page point at the
+   * viewport's top-left corner stays put) and `{ x, y }` pans at the current
+   * zoom. `zoom` is clamped to the editor's range (1% to 1000%); the requested
+   * `x`/`y` are always honoured. Immediate (no animation). View-state only —
+   * not undoable.
+   *
+   * `x`/`y` are the camera offset in page units: the page point that lands at
+   * the viewport's top-left corner is `(-x, -y)`. Read them back from
+   * {@linkcode PluginPresentationCameraApi.get} to reproduce a framing later.
+   *
+   * @param camera - Any of `x`, `y`, `zoom` ({@linkcode PluginPresentationCameraSetArgs}); at least one.
+   * @returns The resulting {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open, or another Present-mode control has
+   *   locked the camera (an open style dropdown, AI Inspiration's layout mode).
+   *
+   * @examplePrompt Zoom the Present canvas to 50%
+   * @examplePrompt Pan the presentation canvas to the right
+   * @examplePrompt Restore the Present camera I saved earlier
+   * @examplePrompt Set the Present zoom to 200% without moving
+   *
+   * # Example
+   * ```ts
+   * const saved = await snaptrude.presentation.camera.get()
+   * await snaptrude.presentation.camera.set({ zoom: 0.5 })
+   * // …later, restore the exact framing
+   * await snaptrude.presentation.camera.set({ x: saved.x, y: saved.y, zoom: saved.zoom })
+   * ```
+   */
+  public abstract set(camera: {
+    x?: number
+    y?: number
+    zoom?: number
+  }): PluginApiReturn<PluginPresentationCameraState>
+
+  /**
+   * Frame everything on the Present canvas — every sheet and loose shape — the
+   * Present-mode "zoom to fit". View-state only — not undoable.
+   *
+   * @returns The resulting {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open, or the camera is locked.
+   *
+   * @examplePrompt Zoom out to see all the sheets
+   * @examplePrompt Fit the whole presentation in the Present view
+   * @examplePrompt Zoom to fit in Present mode
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.camera.zoomToFit()
+   * ```
+   */
+  public abstract zoomToFit(): PluginApiReturn<PluginPresentationCameraState>
+
+  /**
+   * Frame one shape on the Present canvas: a sheet, a placed view, a keyed
+   * shape or an annotation — any id the other `presentation` namespaces hand
+   * out. Pair with {@linkcode PluginPresentationCameraApi.capture} to
+   * screenshot a single sheet or placed view as it appears on screen.
+   * Immediate, unlike `sheets.setActive`, which animates its move over half a
+   * second. View-state only — not undoable.
+   *
+   * @param shapeId - The id of the sheet or shape to frame.
+   * @returns The resulting {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open, the id is unknown, or the camera is locked.
+   *
+   * @examplePrompt Zoom in on sheet 2 in Present mode
+   * @examplePrompt Frame this placed view on the Present canvas
+   * @examplePrompt Go to the cover sheet and screenshot it
+   * @examplePrompt Centre the presentation view on that table
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.presentation.sheets.list()
+   * await snaptrude.presentation.camera.zoomTo(sheets[1].id)
+   * const { image } = await snaptrude.presentation.camera.capture()
+   * ```
+   */
+  public abstract zoomTo(
+    shapeId: string,
+  ): PluginApiReturn<PluginPresentationCameraState>
+}
+
+/**
+ * The visible area of the Present canvas in page units — the canvas as
+ * clipped by the window, minus the strip under the floating left sidebar.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number` | Left edge (page units) |
+ * | `y` | `number` | Top edge (page units) |
+ * | `width` | `number` | Width (page units) |
+ * | `height` | `number` | Height (page units) |
+ */
+export const PluginPresentationCameraViewport = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  width: z.number().finite().nonnegative(),
+  height: z.number().finite().nonnegative(),
+})
+export type PluginPresentationCameraViewport = z.infer<
+  typeof PluginPresentationCameraViewport
+>
+
+/**
+ * The Present canvas camera as returned by every
+ * {@linkcode PluginPresentationCameraApi} method.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number` | Camera pan offset (page units): the page point at the tldraw viewport's top-left corner (under the sidebar) is `(-x, -y)` |
+ * | `y` | `number` | Camera pan offset (page units) |
+ * | `zoom` | `number` | Zoom factor, `1` = 100% |
+ * | `viewport` | {@linkcode PluginPresentationCameraViewport} | The visible page-space rectangle |
+ * | `sheetId` | `string \| null` | The sheet under the centre of the view, or `null` when none |
+ */
+export const PluginPresentationCameraState = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  zoom: z.number().finite().positive(),
+  viewport: PluginPresentationCameraViewport,
+  sheetId: z.string().nullable(),
+})
+export type PluginPresentationCameraState = z.infer<
+  typeof PluginPresentationCameraState
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationCameraApi.set}. All optional, at
+ * least one required; omitted fields keep their current value.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number \| undefined` | Camera pan offset (page units) |
+ * | `y` | `number \| undefined` | Camera pan offset (page units) |
+ * | `zoom` | `number \| undefined` | Zoom factor, `> 0` (`1` = 100%); clamped to the editor's range (`0.01`–`10`), `x`/`y` still honoured |
+ */
+export const PluginPresentationCameraSetArgs = z
+  .object({
+    x: z.number().finite().optional(),
+    y: z.number().finite().optional(),
+    zoom: z.number().finite().positive().optional(),
+  })
+  .refine(
+    (c) => c.x !== undefined || c.y !== undefined || c.zoom !== undefined,
+    {
+      message: "Pass at least one of x, y, zoom",
+    },
+  )
+export type PluginPresentationCameraSetArgs = z.infer<
+  typeof PluginPresentationCameraSetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationCameraApi.zoomTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The sheet or shape to frame |
+ */
+export const PluginPresentationCameraZoomToArgs = z.object({
+  shapeId: z.string().min(1),
+})
+export type PluginPresentationCameraZoomToArgs = z.infer<
+  typeof PluginPresentationCameraZoomToArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationCameraApi.capture}. All optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | `"png" \| "jpeg" \| undefined` | Output image format (default `"png"`) |
+ * | `pixelRatio` | `number \| undefined` | Output pixels per screen pixel, `1`–`4` (default `1`) |
+ */
+export const PluginPresentationCameraCaptureArgs = z.object({
+  format: PluginPresentationImageFormat.optional(),
+  pixelRatio: z.number().finite().min(1).max(4).optional(),
+})
+export type PluginPresentationCameraCaptureArgs = z.infer<
+  typeof PluginPresentationCameraCaptureArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationCameraApi.capture}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `image` | `string` | The screenshot as a base64 data URL (`data:image/png;base64,…`) |
+ * | `width` | `number` | Image width in pixels |
+ * | `height` | `number` | Image height in pixels |
+ */
+export const PluginPresentationCameraCaptureResult = z.object({
+  image: z.string(),
+  width: z.number().int().nonnegative(),
+  height: z.number().int().nonnegative(),
+})
+export type PluginPresentationCameraCaptureResult = z.infer<
+  typeof PluginPresentationCameraCaptureResult
+>

package/src/api/presentation/drawingContract.ts

@@ -0,0 +1,70 @@
+import * as z from "zod"
+
+/**
+ * Metric architectural scale denominators (`100` means 1:100), the metric
+ * values of the placed view's Scale dropdown.
+ */
+export const METRIC_DRAWING_SCALES = [
+  10, 20, 50, 100, 150, 200, 250, 500, 1000,
+] as const
+
+/**
+ * Imperial detail scale denominators, 1" = 1' (12) to 1/128" = 1' (1536):
+ * `48` is 1/4" = 1', `96` is 1/8" = 1'.
+ */
+export const IMPERIAL_DETAIL_DRAWING_SCALES = [
+  12, 16, 24, 32, 48, 64, 96, 128, 192, 384, 768, 1536,
+] as const
+
+/** Imperial site (engineering) scale denominators, 1" = 10' (120) to 1" = 400' (4800). */
+export const IMPERIAL_SITE_DRAWING_SCALES = [
+  120, 240, 360, 480, 600, 1200, 2400, 3600, 4800,
+] as const
+
+/**
+ * Imperial architectural scale denominators, ascending: the imperial detail
+ * and site values of the placed view's Scale dropdown.
+ */
+export const IMPERIAL_DRAWING_SCALES: readonly number[] = [
+  ...IMPERIAL_DETAIL_DRAWING_SCALES,
+  ...IMPERIAL_SITE_DRAWING_SCALES,
+].sort((a, b) => a - b)
+
+/**
+ * Every standard architectural scale denominator, metric and imperial,
+ * ascending. Drawing and placed-view scale arguments accept only these; the
+ * host may further restrict them to the project's unit system.
+ */
+export const STANDARD_DRAWING_SCALES: readonly number[] = [
+  ...METRIC_DRAWING_SCALES,
+  ...IMPERIAL_DRAWING_SCALES,
+].sort((a, b) => a - b)
+
+const standardScaleSet = new Set<number>(STANDARD_DRAWING_SCALES)
+
+/** A standard architectural scale denominator; anything else is rejected with the allowed list. */
+export const PluginStandardDrawingScale = z
+  .number()
+  .finite()
+  .refine((scale) => standardScaleSet.has(scale), {
+    message: `Scale must be a standard architectural scale denominator in the project's unit system. Metric: ${METRIC_DRAWING_SCALES.join(", ")}; imperial detail: ${IMPERIAL_DETAIL_DRAWING_SCALES.join(", ")}; imperial site: ${IMPERIAL_SITE_DRAWING_SCALES.join(", ")}. Pick the largest standard scale (smallest denominator) at which the view fits its frame or sheet and its room labels stay readable (usually 1:50 to 1:200 for a building plan).`,
+  })
+
+const EXTENSION = /\.(pdf|svg|png|jpe?g)$/i
+// The host appends ".<ext>", so a trailing dot yields "a.pdf..pdf" and trailing
+// whitespace yields "plan .pdf".
+const TRAILING_DOT_OR_SPACE = /[.\s]$/
+
+/**
+ * An export base file name without an extension, not ending in a dot or
+ * whitespace; the host adds `.pdf`, `.svg`, `.png` or `.jpg`.
+ */
+export const PluginExportFileName = z
+  .string()
+  .refine(
+    (name) => !EXTENSION.test(name.trim()) && !TRAILING_DOT_OR_SPACE.test(name),
+    {
+      message:
+        "fileName must be a base name without an extension and not ending in a dot or a space (for example \"Ground Floor Plan\", not \"Ground Floor Plan.pdf\" or \"Ground Floor Plan.\"); the export adds the extension for the format.",
+    },
+  )