@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

package/src/api/entity/buildableEnvelope.ts

@@ -1,5 +1,9 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import {
+  PluginProgramSiteEdgeRole,
+  PluginProgramSiteEdgesEntry,
+} from "../program/site"
 
 /**
  * Buildable Envelope management — create and update parametric zoning envelopes.
@@ -72,6 +76,11 @@ export abstract class PluginBuildableEnvelopeApi {
    * volume from a revised site polygon, setbacks, vertical cap, or FAR and
    * lot-coverage limits, keeping the same envelope id.
    *
+   * Edge state is preserved, like the right panel: every edge's type
+   * (front/side/rear) is kept. For each type whose value changed (by more than
+   * 2 mm), the per-edge custom distances on edges of that type are cleared;
+   * custom distances on types whose value did not change are kept.
+   *
    * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
    *   must match an existing envelope on the canvas.
    * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
@@ -82,9 +91,15 @@ export abstract class PluginBuildableEnvelopeApi {
    * @param farRatio - Optional FAR value, positive when provided.
    * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
    * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
-   *   `buildableEnvelopeId` of the updated envelope.
+   *   `buildableEnvelopeId` of the updated envelope and `clearedEdgeSetbacks`,
+   *   the `edgeIndex` of each edge that lost its custom distance (empty when
+   *   none). Tell the user about any cleared edges.
    * @throws If validation fails, the envelope does not exist, or generation
-   *   produces no renderable geometry.
+   *   produces no renderable geometry. Also throws `PRECONDITION_FAILED`
+   *   (`details.reason: "STALE_EDGE_SETTINGS"`, nothing changes) when the site
+   *   outline changed since the edge settings were made. Tell the user;
+   *   editing any edge on the canvas setback pills resets the edge settings
+   *   to the new outline (dropping the old ones), after which you can retry.
    *
    * @examplePrompt Change the envelope's height limit to 175 feet
    * @examplePrompt Update the setbacks on the buildable envelope
@@ -312,11 +327,71 @@ export type PluginBuildableEnvelopeUpdateArgs = z.infer<
  * | Property | Type | Description |
  * |---|---|---|
  * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the updated buildable envelope |
+ * | `clearedEdgeSetbacks` | `number[]` | `edgeIndex` of every edge whose own custom distance was cleared because its type's (front/side/rear) value changed; empty when none |
  */
 export const PluginBuildableEnvelopeUpdateResult = z.object({
   buildableEnvelopeId: z.string().min(1),
+  clearedEdgeSetbacks: z.array(z.number().int().nonnegative()),
 }).strict()
 
 export type PluginBuildableEnvelopeUpdateResult = z.infer<
   typeof PluginBuildableEnvelopeUpdateResult
 >
+
+/**
+ * Patch for one site edge, as taken by `design.update.siteEdge`.
+ *
+ * Strict schema. Provide `role`, `setback`, or both. A numeric `setback`
+ * requires `lengthUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `role` | `"front" \| "side" \| "rear"`? | New edge type. Setting it clears the edge's own distance |
+ * | `setback` | `number \| null`? | This edge's own setback distance in `lengthUnit` (finite, nonnegative); `null` clears it so the edge falls back to its type's distance |
+ * | `lengthUnit` | `"m" \| "ft"`? | Unit of `setback`; required when `setback` is a number |
+ */
+export const PluginSiteEdgePatch = z
+  .object({
+    role: PluginProgramSiteEdgeRole.optional(),
+    // null = clear this edge's own distance
+    setback: z.number().finite().nonnegative().nullable().optional(),
+    lengthUnit: z.enum(["m", "ft"]).optional(),
+  })
+  .strict()
+  .refine(
+    (p) => p.role !== undefined || p.setback !== undefined,
+    "patch must set role and/or setback"
+  )
+  .refine(
+    (p) => typeof p.setback !== "number" || p.lengthUnit !== undefined,
+    "lengthUnit is required with a numeric setback"
+  )
+
+export type PluginSiteEdgePatch = z.infer<typeof PluginSiteEdgePatch>
+
+/**
+ * Result of `design.update.siteEdge` — the refreshed edge entry for the
+ * site, exactly as `program.site.listEdges()` returns it.
+ */
+export const PluginDesignUpdateSiteEdgeResult = PluginProgramSiteEdgesEntry
+
+export type PluginDesignUpdateSiteEdgeResult = z.infer<
+  typeof PluginDesignUpdateSiteEdgeResult
+>
+
+/**
+ * Result of `design.create.buildableEnvelopeFromSite`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | ID of the created buildable envelope |
+ */
+export const PluginDesignCreateBuildableEnvelopeFromSiteResult = z
+  .object({
+    buildableEnvelopeId: z.string(),
+  })
+  .strict()
+
+export type PluginDesignCreateBuildableEnvelopeFromSiteResult = z.infer<
+  typeof PluginDesignCreateBuildableEnvelopeFromSiteResult
+>

package/src/api/entity/referenceLine.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { ProfileHandle, CurveHandle } from "../../handles"
+import { PluginGraphicsLineStyleId } from "../presentation/graphics"
 
 /**
  * Reference line management — create, query, and delete reference lines.
@@ -53,7 +54,7 @@ export abstract class PluginReferenceLineApi {
    * @deprecated Use `design.create.referenceLines`
    */
   public abstract createMulti(
-    profile: ProfileHandle
+    profile: ProfileHandle,
   ): PluginApiReturn<PluginReferenceLineCreateMultiResult>
 
   /**
@@ -85,7 +86,7 @@ export abstract class PluginReferenceLineApi {
    */
   public abstract get(
     referenceLineId: string,
-    properties: z.infer<typeof PluginReferenceLineGetProperty>[]
+    properties: z.infer<typeof PluginReferenceLineGetProperty>[],
   ): PluginApiReturn<PluginReferenceLineGetResult>
 
   /**
@@ -135,7 +136,7 @@ export abstract class PluginReferenceLineApi {
    * @deprecated Use `design.delete.entities`
    */
   public abstract delete(
-    referenceLineId: string
+    referenceLineId: string,
   ): PluginApiReturn<PluginReferenceLineDeleteResult>
 }
 
@@ -150,7 +151,9 @@ export const PluginReferenceLineCreateMultiArgs = z.object({
   profile: ProfileHandle,
 })
 
-export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
+export type PluginReferenceLineCreateMultiArgs = z.infer<
+  typeof PluginReferenceLineCreateMultiArgs
+>
 
 /**
  * Result of {@linkcode PluginReferenceLineApi.createMulti}.
@@ -163,7 +166,9 @@ export const PluginReferenceLineCreateMultiResult = z.object({
   referenceLineIds: z.array(z.string()),
 })
 
-export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenceLineCreateMultiResult>
+export type PluginReferenceLineCreateMultiResult = z.infer<
+  typeof PluginReferenceLineCreateMultiResult
+>
 
 /**
  * Available properties that can be queried on a reference line.
@@ -171,10 +176,9 @@ export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenc
  * | Value | Return Type | Description |
  * |---|---|---|
  * | `"curve"` | {@linkcode CurveHandle} | The curve geometry of the reference line, as an opaque handle |
+ * | `"styleId"` | `PluginGraphicsLineStyleId \| null` | Project style, or null for an unstyled legacy line |
  */
-export const PluginReferenceLineGetProperty = z.enum([
-  "curve",
-])
+export const PluginReferenceLineGetProperty = z.enum(["curve", "styleId"])
 
 /**
  * Arguments for {@linkcode PluginReferenceLineApi.get}.
@@ -189,7 +193,9 @@ export const PluginReferenceLineGetArgs = z.object({
   properties: z.array(PluginReferenceLineGetProperty),
 })
 
-export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetArgs>
+export type PluginReferenceLineGetArgs = z.infer<
+  typeof PluginReferenceLineGetArgs
+>
 
 /**
  * Result of {@linkcode PluginReferenceLineApi.get}.
@@ -200,10 +206,13 @@ export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetAr
 export const PluginReferenceLineGetResult = z
   .object({
     curve: CurveHandle,
+    styleId: PluginGraphicsLineStyleId.nullable(),
   })
   .partial()
 
-export type PluginReferenceLineGetResult = z.infer<typeof PluginReferenceLineGetResult>
+export type PluginReferenceLineGetResult = z.infer<
+  typeof PluginReferenceLineGetResult
+>
 
 /**
  * Result of {@linkcode PluginReferenceLineApi.getAll}.
@@ -216,7 +225,9 @@ export const PluginReferenceLineGetAllResult = z.object({
   referenceLineIds: z.array(z.string()),
 })
 
-export type PluginReferenceLineGetAllResult = z.infer<typeof PluginReferenceLineGetAllResult>
+export type PluginReferenceLineGetAllResult = z.infer<
+  typeof PluginReferenceLineGetAllResult
+>
 
 /**
  * Arguments for {@linkcode PluginReferenceLineApi.delete}.
@@ -229,7 +240,9 @@ export const PluginReferenceLineDeleteArgs = z.object({
   referenceLineId: z.string(),
 })
 
-export type PluginReferenceLineDeleteArgs = z.infer<typeof PluginReferenceLineDeleteArgs>
+export type PluginReferenceLineDeleteArgs = z.infer<
+  typeof PluginReferenceLineDeleteArgs
+>
 
 /** Result type for {@linkcode PluginReferenceLineApi.delete} — returns nothing on success. */
 export type PluginReferenceLineDeleteResult = void

package/src/api/entity/space.ts

@@ -434,7 +434,6 @@ export type PluginSpaceUpdateArgs = z.infer<typeof PluginSpaceUpdateArgs>
  * | `massType` | `string?` | Updated mass type (if changed) |
  * | `spaceType` | `string?` | Updated space type (if changed) |
  * | `departmentId` | `string \| null?` | Updated department ID (if changed) |
- * | `rebuilt` | `boolean?` | `true` when a geometry update rebuilt the space's derived BIM — hosted children were re-created and the previous derived handles are retired (re-query them) |
  */
 export const PluginSpaceUpdateResult = z.object({
   spaceId: z.string(),
@@ -443,7 +442,6 @@ export const PluginSpaceUpdateResult = z.object({
   spaceType: z.string().optional(),
   areaClass: PluginAreaClass.optional(),
   departmentId: z.string().nullable().optional(),
-  rebuilt: z.boolean().optional(),
 })
 
 export type PluginSpaceUpdateResult = z.infer<typeof PluginSpaceUpdateResult>

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
 >