Presentation Annotate

Add annotations to Present-mode sheets. Accessed via snaptrude.presentation.annotate.

The scriptable counterparts to the Present toolbar's annotation tools: text (text labels), arrow (arrows), note (sticky notes), and shape (geo shapes — the same kinds as the toolbar's shape flyout). Every annotation is created as a canvas shape and nested under the sheet frame, so it moves with the sheet; all positions and bounds are relative to the sheet's top-left, in canvas units. Writes are gated on the plugin write floor and require Present (documentation) mode to be open.

The freehand Draw tool is not scriptable (a stroke is an interactive gesture, not a single call) and is intentionally not exposed.

Types

PluginAnnotateTextSize

Size preset — the same s / m / l / xl scale as the Present-mode tools (text size for text/note, stroke weight for arrow).

"s" | "m" | "l" | "xl"

PluginAnnotateTextColor

Named palette color — the same swatches as the Present-mode style panel. Used by all four annotate functions.

"black" | "grey" | "light-violet" | "violet" | "blue" | "light-blue" | "yellow" | "orange" | "green" | "light-green" | "light-red" | "red" | "white"

PluginAnnotateGeoKind

Geo shape kind — the shapes offered by the Present-mode toolbar's shape flyout.

"rectangle" | "ellipse" | "triangle" | "diamond" | "hexagon" | "oval" | "rhombus" | "star" | "cloud" | "heart" | "x-box" | "check-box" | "arrow-left" | "arrow-up" | "arrow-right" | "arrow-down"

PluginAnnotateFill

Fill style for geo shapes (the same fills as the Present-mode style panel).

"none" | "semi" | "solid" | "pattern"

PluginPresentationAnnotateTextResult

Property	Type	Description
shapeId	string	Id of the created text shape

PluginPresentationAnnotateResult

Result of arrow, note, and shape.

Property	Type	Description
shapeId	string	Id of the created canvas shape

Functions

text(sheetId, text, options?)

Add a text label to a sheet. Creates a text shape on the given sheet and returns the id of the created canvas shape.

• Parameters:
  • sheetId: string — The sheet to annotate
  • text: string — The label text
  • options?:
    • position?: { x: number; y: number } — Where to place it, relative to the sheet's top-left, in canvas units (defaults to the sheet's top-left corner)
    • size?: PluginAnnotateTextSize — Text size preset (default "m")
    • color?: PluginAnnotateTextColor — Text color (default "black")
• Returns: PluginPresentationAnnotateTextResult — { shapeId }, the created text shape
• Throws: PRECONDITION_FAILED if Present mode is not open; HANDLE_INVALID if the sheet id is unknown or not a sheet; or if plugin writes are disabled

const { shapeId } = await snaptrude.presentation.annotate.text("sheet_1", "Ground Floor", {
  position: { x: 40, y: 40 },
  size: "xl",
  color: "blue"
});

arrow(sheetId, start, end, options?)

Draw an arrow on a sheet — the same Arrow tool as the Present toolbar. Creates an arrow shape from start (tail) to end (head) and returns the id of the created canvas shape. The arrow is unbound (it points between two positions, not at another shape).

• Parameters:
  • sheetId: string — The sheet to annotate
  • start: { x: number; y: number } — Arrow tail, relative to the sheet's top-left
  • end: { x: number; y: number } — Arrow head, relative to the sheet's top-left
  • options?:
    • color?: PluginAnnotateTextColor — Arrow color (default "black")
    • size?: PluginAnnotateTextSize — Stroke weight preset (default "m")
• Returns: PluginPresentationAnnotateResult — { shapeId }, the created arrow shape
• Throws: same contract as text

const { shapeId } = await snaptrude.presentation.annotate.arrow(
  "sheet_1",
  { x: 100, y: 200 },
  { x: 300, y: 250 },
  { color: "red" }
);

note(sheetId, text, options?)

Add a sticky note to a sheet — the same Note tool as the Present toolbar. Creates a note shape (a fixed-size sticky square that grows with its text) and returns the id of the created canvas shape.

• Parameters:
  • sheetId: string — The sheet to annotate
  • text: string — The note text
  • options?:
    • position?: { x: number; y: number } — Where to place it, relative to the sheet's top-left (defaults to the sheet's top-left corner)
    • color?: PluginAnnotateTextColor — Sticky fill color (default "black")
    • size?: PluginAnnotateTextSize — Text size preset (default "m")
• Returns: PluginPresentationAnnotateResult — { shapeId }, the created note shape
• Throws: same contract as text

const { shapeId } = await snaptrude.presentation.annotate.note("sheet_1", "Review this wall", {
  position: { x: 60, y: 120 },
  color: "yellow"
});

shape(sheetId, kind, bounds, options?)

Draw a geo shape (rectangle, ellipse, cloud, …) on a sheet — the same shapes as the Present toolbar's shape flyout. Creates a geo shape of the given kind sized to bounds and returns the id of the created canvas shape.

• Parameters:
  • sheetId: string — The sheet to annotate
  • kind: PluginAnnotateGeoKind — The shape kind, e.g. "rectangle", "ellipse", "cloud"
  • bounds: { x: number; y: number; w: number; h: number } — Placement box; x/y are the shape's top-left relative to the sheet's top-left, w/h must be positive
  • options?:
    • color?: PluginAnnotateTextColor — Outline color (default "black")
    • fill?: PluginAnnotateFill — Fill style (default "none", outline only)
• Returns: PluginPresentationAnnotateResult — { shapeId }, the created geo shape
• Throws: same contract as text

const { shapeId } = await snaptrude.presentation.annotate.shape(
  "sheet_1",
  "cloud",
  { x: 80, y: 80, w: 240, h: 160 },
  { color: "red" }
);

Errors

Failed calls reject with a typed PluginError — see Error Handling.

Code	When
VALIDATION	Bad arguments (e.g. an unknown size, color, or kind; non-positive w/h)
PRECONDITION_FAILED	Present mode is not open
HANDLE_INVALID	The sheetId is unknown or not a sheet