@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

package/src/api/presentation/annotate.ts

@@ -1,385 +1,417 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Presentation annotate — add annotations to Present-mode sheets.
- *
- * The scriptable counterparts to the Present toolbar's annotation tools (all
- * require Present mode to be open; each returns the created canvas shape id):
- *
- * - {@linkcode PluginPresentationAnnotateApi.text} — text labels (titles, captions)
- * - {@linkcode PluginPresentationAnnotateApi.arrow} — arrows pointing between two points
- * - {@linkcode PluginPresentationAnnotateApi.note} — sticky notes
- * - {@linkcode PluginPresentationAnnotateApi.shape} — geo shapes (rectangle, ellipse, cloud, …)
- *
- * The freehand Draw tool is not scriptable (a stroke is an interactive gesture,
- * not a single call) and is intentionally not exposed here.
- *
- * Accessed via `snaptrude.presentation.annotate`.
- */
-export abstract class PluginPresentationAnnotateApi {
-  constructor() {}
-
-  /**
-   * Add a text label to a sheet.
-   *
-   * Creates a text shape on the given sheet and returns the id of the created
-   * canvas shape. Requires Present mode to be open.
-   *
-   * Typography is optional: `fontFamily` takes a system family or any Google
-   * Font (loaded automatically, the same loader as the Present text panel);
-   * `fontWeight` is a numeric weight string like `"400"` or `"700"`,
-   * optionally with the `-italic` suffix (e.g. `"700-italic"`) — the Present
-   * text panel's value domain; a weight the chosen font does not provide
-   * 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 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).
-   * @returns A {@linkcode PluginPresentationAnnotateTextResult} with the created
-   *   `shapeId`.
-   * @throws If Present mode is not open or the sheet id is invalid.
-   *
-   * @examplePrompt Add a title "Ground Floor" to Sheet 1
-   * @examplePrompt Label the cover sheet with the project name
-   * @examplePrompt Caption this view with "Proposed layout"
-   * @examplePrompt Put a red note on the sheet
-   *
-   * # Example
-   * ```ts
-   * const { shapeId } = await snaptrude.presentation.annotate.text(
-   *   "sheet_1",
-   *   "Ground Floor",
-   *   { position: { x: 40, y: 40 }, size: "xl", color: "blue" },
-   * )
-   * ```
-   */
-  public abstract text(
-    sheetId: string,
-    text: string,
-    options?: {
-      position?: { x: number; y: number }
-      size?: PluginAnnotateTextSize
-      color?: PluginAnnotateTextColor
-      fontFamily?: string
-      fontWeight?: string
-      fontSizePx?: number
-    },
-  ): PluginApiReturn<PluginPresentationAnnotateTextResult>
-
-  /**
-   * Draw an arrow on a sheet.
-   *
-   * Creates an arrow shape from `start` to `end` (both relative to the sheet's
-   * 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 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"`).
-   * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
-   *   `shapeId`.
-   * @throws If Present mode is not open or the sheet id is invalid.
-   *
-   * @examplePrompt Draw an arrow pointing at the entrance on Sheet 1
-   * @examplePrompt Add a red arrow from the title to the plan view
-   * @examplePrompt Point an arrow at the top-left view on the cover sheet
-   *
-   * # Example
-   * ```ts
-   * const { shapeId } = await snaptrude.presentation.annotate.arrow(
-   *   "sheet_1",
-   *   { x: 100, y: 200 },
-   *   { x: 300, y: 250 },
-   *   { color: "red" },
-   * )
-   * ```
-   */
-  public abstract arrow(
-    sheetId: string,
-    start: { x: number; y: number },
-    end: { x: number; y: number },
-    options?: {
-      color?: PluginAnnotateTextColor
-      size?: PluginAnnotateTextSize
-    },
-  ): PluginApiReturn<PluginPresentationAnnotateResult>
-
-  /**
-   * Add a sticky note to a sheet.
-   *
-   * Creates a note shape (the same Note tool as the Present toolbar — a
-   * 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 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"`).
-   * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
-   *   `shapeId`.
-   * @throws If Present mode is not open or the sheet id is invalid.
-   *
-   * @examplePrompt Add a sticky note "Review this wall" to Sheet 1
-   * @examplePrompt Put a yellow note on the cover sheet
-   * @examplePrompt Leave a note next to the ground floor plan
-   *
-   * # Example
-   * ```ts
-   * const { shapeId } = await snaptrude.presentation.annotate.note(
-   *   "sheet_1",
-   *   "Review this wall",
-   *   { position: { x: 60, y: 120 }, color: "yellow" },
-   * )
-   * ```
-   */
-  public abstract note(
-    sheetId: string,
-    text: string,
-    options?: {
-      position?: { x: number; y: number }
-      color?: PluginAnnotateTextColor
-      size?: PluginAnnotateTextSize
-    },
-  ): PluginApiReturn<PluginPresentationAnnotateResult>
-
-  /**
-   * Draw a geo shape (rectangle, ellipse, cloud, …) on a sheet.
-   *
-   * Creates a geo shape of the given `kind` — the same shapes as the Present
-   * toolbar's shape flyout — sized to `bounds` (relative to the sheet's
-   * 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 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).
-   * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
-   *   `shapeId`.
-   * @throws If Present mode is not open or the sheet id is invalid.
-   *
-   * @examplePrompt Draw a revision cloud around the kitchen on Sheet 2
-   * @examplePrompt Add a red rectangle highlight to the sheet
-   * @examplePrompt Draw an ellipse around the entrance on the cover sheet
-   *
-   * # Example
-   * ```ts
-   * const { shapeId } = await snaptrude.presentation.annotate.shape(
-   *   "sheet_1",
-   *   "cloud",
-   *   { x: 80, y: 80, w: 240, h: 160 },
-   *   { color: "red" },
-   * )
-   * ```
-   */
-  public abstract shape(
-    sheetId: string,
-    kind: PluginAnnotateGeoKind,
-    bounds: { x: number; y: number; w: number; h: number },
-    options?: {
-      color?: PluginAnnotateTextColor
-      fill?: PluginAnnotateFill
-    },
-  ): PluginApiReturn<PluginPresentationAnnotateResult>
-}
-
-/** Text size preset (the same s/m/l/xl scale as the Present-mode text tool). */
-export const PluginAnnotateTextSize = z.enum(["s", "m", "l", "xl"])
-export type PluginAnnotateTextSize = z.infer<typeof PluginAnnotateTextSize>
-
-/** Named palette color (the same swatches as the Present-mode style panel). */
-export const PluginAnnotateTextColor = z.enum([
-  "black",
-  "grey",
-  "light-violet",
-  "violet",
-  "blue",
-  "light-blue",
-  "yellow",
-  "orange",
-  "green",
-  "light-green",
-  "light-red",
-  "red",
-  "white",
-])
-export type PluginAnnotateTextColor = z.infer<typeof PluginAnnotateTextColor>
-
-/**
- * Arguments for {@linkcode PluginPresentationAnnotateApi.text}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
- * | `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 |
- * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Text color |
- * | `fontFamily` | `string \| undefined` | System family or any Google Font (loaded automatically) |
- * | `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 type PluginPresentationAnnotateTextArgs = z.infer<
-  typeof PluginPresentationAnnotateTextArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationAnnotateApi.text}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `shapeId` | `string` | Id of the created text shape |
- */
-export const PluginPresentationAnnotateTextResult = z.object({
-  shapeId: z.string(),
-})
-export type PluginPresentationAnnotateTextResult = z.infer<
-  typeof PluginPresentationAnnotateTextResult
->
-
-/**
- * Geo shape kind — the shapes offered by the Present-mode toolbar's shape
- * flyout.
- */
-export const PluginAnnotateGeoKind = z.enum([
-  "rectangle",
-  "ellipse",
-  "triangle",
-  "diamond",
-  "hexagon",
-  "oval",
-  "rhombus",
-  "star",
-  "cloud",
-  "heart",
-  "x-box",
-  "check-box",
-  "arrow-left",
-  "arrow-up",
-  "arrow-right",
-  "arrow-down",
-])
-export type PluginAnnotateGeoKind = z.infer<typeof PluginAnnotateGeoKind>
-
-/** Fill style for geo shapes (the same fills as the Present-mode style panel). */
-export const PluginAnnotateFill = z.enum(["none", "semi", "solid", "pattern"])
-export type PluginAnnotateFill = z.infer<typeof PluginAnnotateFill>
-
-/**
- * Arguments for {@linkcode PluginPresentationAnnotateApi.arrow}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
- * | `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 type PluginPresentationAnnotateArrowArgs = z.infer<
-  typeof PluginPresentationAnnotateArrowArgs
->
-
-/**
- * Arguments for {@linkcode PluginPresentationAnnotateApi.note}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
- * | `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 type PluginPresentationAnnotateNoteArgs = z.infer<
-  typeof PluginPresentationAnnotateNoteArgs
->
-
-/**
- * Arguments for {@linkcode PluginPresentationAnnotateApi.shape}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to annotate |
- * | `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 type PluginPresentationAnnotateShapeArgs = z.infer<
-  typeof PluginPresentationAnnotateShapeArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationAnnotateApi.arrow},
- * {@linkcode PluginPresentationAnnotateApi.note}, and
- * {@linkcode PluginPresentationAnnotateApi.shape}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `shapeId` | `string` | Id of the created canvas shape |
- */
-export const PluginPresentationAnnotateResult = z.object({
-  shapeId: z.string(),
-})
-export type PluginPresentationAnnotateResult = z.infer<
-  typeof PluginPresentationAnnotateResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation annotate — add annotations to Present-mode sheets.
+ *
+ * The scriptable counterparts to the Present toolbar's annotation tools (all
+ * require Present mode to be open; each returns the created canvas shape id):
+ *
+ * - {@linkcode PluginPresentationAnnotateApi.text} — text labels (titles, captions)
+ * - {@linkcode PluginPresentationAnnotateApi.arrow} — arrows pointing between two points
+ * - {@linkcode PluginPresentationAnnotateApi.note} — sticky notes
+ * - {@linkcode PluginPresentationAnnotateApi.shape} — geo shapes (rectangle, ellipse, cloud, …)
+ *
+ * The freehand Draw tool is not scriptable (a stroke is an interactive gesture,
+ * not a single call) and is intentionally not exposed here.
+ *
+ * Accessed via `snaptrude.presentation.annotate`.
+ */
+export abstract class PluginPresentationAnnotateApi {
+  constructor() {}
+
+  /**
+   * Add a text label to a sheet.
+   *
+   * Creates a text shape on the given sheet and returns the id of the created
+   * canvas shape. Requires Present mode to be open.
+   *
+   * Typography is optional: `fontFamily` takes a system family or any Google
+   * Font (loaded automatically, the same loader as the Present text panel);
+   * `fontWeight` is a numeric weight string like `"400"` or `"700"`,
+   * optionally with the `-italic` suffix (e.g. `"700-italic"`) — the Present
+   * text panel's value domain; a weight the chosen font does not provide
+   * 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, 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), 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.
+   *
+   * @examplePrompt Add a title "Ground Floor" to Sheet 1
+   * @examplePrompt Label the cover sheet with the project name
+   * @examplePrompt Caption this view with "Proposed layout"
+   * @examplePrompt Put a red note on the sheet
+   *
+   * # Example
+   * ```ts
+   * const { shapeId } = await snaptrude.presentation.annotate.text(
+   *   "sheet_1",
+   *   "Ground Floor",
+   *   { position: { x: 40, y: 40 }, size: "xl", color: "blue" },
+   * )
+   * ```
+   */
+  public abstract text(
+    sheetId: string | undefined,
+    text: string,
+    options?: {
+      position?: { x: number; y: number }
+      size?: PluginAnnotateTextSize
+      color?: PluginAnnotateTextColor
+      fontFamily?: string
+      fontWeight?: string
+      fontSizePx?: number
+      drawingId?: string
+    },
+  ): PluginApiReturn<PluginPresentationAnnotateTextResult>
+
+  /**
+   * Draw an arrow on a sheet.
+   *
+   * Creates an arrow shape from `start` to `end` (both relative to the sheet's
+   * 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, 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"`)
+   *   `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.
+   *
+   * @examplePrompt Draw an arrow pointing at the entrance on Sheet 1
+   * @examplePrompt Add a red arrow from the title to the plan view
+   * @examplePrompt Point an arrow at the top-left view on the cover sheet
+   *
+   * # Example
+   * ```ts
+   * const { shapeId } = await snaptrude.presentation.annotate.arrow(
+   *   "sheet_1",
+   *   { x: 100, y: 200 },
+   *   { x: 300, y: 250 },
+   *   { color: "red" },
+   * )
+   * ```
+   */
+  public abstract arrow(
+    sheetId: string | undefined,
+    start: { x: number; y: number },
+    end: { x: number; y: number },
+    options?: {
+      color?: PluginAnnotateTextColor
+      size?: PluginAnnotateTextSize
+      drawingId?: string
+    },
+  ): PluginApiReturn<PluginPresentationAnnotateResult>
+
+  /**
+   * Add a sticky note to a sheet.
+   *
+   * Creates a note shape (the same Note tool as the Present toolbar — a
+   * 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, 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"`), 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.
+   *
+   * @examplePrompt Add a sticky note "Review this wall" to Sheet 1
+   * @examplePrompt Put a yellow note on the cover sheet
+   * @examplePrompt Leave a note next to the ground floor plan
+   *
+   * # Example
+   * ```ts
+   * const { shapeId } = await snaptrude.presentation.annotate.note(
+   *   "sheet_1",
+   *   "Review this wall",
+   *   { position: { x: 60, y: 120 }, color: "yellow" },
+   * )
+   * ```
+   */
+  public abstract note(
+    sheetId: string | undefined,
+    text: string,
+    options?: {
+      position?: { x: number; y: number }
+      color?: PluginAnnotateTextColor
+      size?: PluginAnnotateTextSize
+      drawingId?: string
+    },
+  ): PluginApiReturn<PluginPresentationAnnotateResult>
+
+  /**
+   * Draw a geo shape (rectangle, ellipse, cloud, …) on a sheet.
+   *
+   * Creates a geo shape of the given `kind` — the same shapes as the Present
+   * toolbar's shape flyout — sized to `bounds` (relative to the sheet's
+   * 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, 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), 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.
+   *
+   * @examplePrompt Draw a revision cloud around the kitchen on Sheet 2
+   * @examplePrompt Add a red rectangle highlight to the sheet
+   * @examplePrompt Draw an ellipse around the entrance on the cover sheet
+   *
+   * # Example
+   * ```ts
+   * const { shapeId } = await snaptrude.presentation.annotate.shape(
+   *   "sheet_1",
+   *   "cloud",
+   *   { x: 80, y: 80, w: 240, h: 160 },
+   *   { color: "red" },
+   * )
+   * ```
+   */
+  public abstract shape(
+    sheetId: string | undefined,
+    kind: PluginAnnotateGeoKind,
+    bounds: { x: number; y: number; w: number; h: number },
+    options?: {
+      color?: PluginAnnotateTextColor
+      fill?: PluginAnnotateFill
+      drawingId?: string
+    },
+  ): PluginApiReturn<PluginPresentationAnnotateResult>
+}
+
+/** Text size preset (the same s/m/l/xl scale as the Present-mode text tool). */
+export const PluginAnnotateTextSize = z.enum(["s", "m", "l", "xl"])
+export type PluginAnnotateTextSize = z.infer<typeof PluginAnnotateTextSize>
+
+/** Named palette color (the same swatches as the Present-mode style panel). */
+export const PluginAnnotateTextColor = z.enum([
+  "black",
+  "grey",
+  "light-violet",
+  "violet",
+  "blue",
+  "light-blue",
+  "yellow",
+  "orange",
+  "green",
+  "light-green",
+  "light-red",
+  "red",
+  "white",
+])
+export type PluginAnnotateTextColor = z.infer<typeof PluginAnnotateTextColor>
+
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.text}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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 |
+ * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Text color |
+ * | `fontFamily` | `string \| undefined` | System family or any Google Font (loaded automatically) |
+ * | `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().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
+>
+
+/**
+ * Result of {@linkcode PluginPresentationAnnotateApi.text}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the created text shape |
+ */
+export const PluginPresentationAnnotateTextResult = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationAnnotateTextResult = z.infer<
+  typeof PluginPresentationAnnotateTextResult
+>
+
+/**
+ * Geo shape kind — the shapes offered by the Present-mode toolbar's shape
+ * flyout.
+ */
+export const PluginAnnotateGeoKind = z.enum([
+  "rectangle",
+  "ellipse",
+  "triangle",
+  "diamond",
+  "hexagon",
+  "oval",
+  "rhombus",
+  "star",
+  "cloud",
+  "heart",
+  "x-box",
+  "check-box",
+  "arrow-left",
+  "arrow-up",
+  "arrow-right",
+  "arrow-down",
+])
+export type PluginAnnotateGeoKind = z.infer<typeof PluginAnnotateGeoKind>
+
+/** Fill style for geo shapes (the same fills as the Present-mode style panel). */
+export const PluginAnnotateFill = z.enum(["none", "semi", "solid", "pattern"])
+export type PluginAnnotateFill = z.infer<typeof PluginAnnotateFill>
+
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.arrow}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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().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
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.note}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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().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
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.shape}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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().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
+>
+
+/**
+ * Result of {@linkcode PluginPresentationAnnotateApi.arrow},
+ * {@linkcode PluginPresentationAnnotateApi.note}, and
+ * {@linkcode PluginPresentationAnnotateApi.shape}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the created canvas shape |
+ */
+export const PluginPresentationAnnotateResult = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationAnnotateResult = z.infer<
+  typeof PluginPresentationAnnotateResult
+>