@snaptrude/plugin-core 0.2.9 → 0.5.0

package/src/api/entity/story.ts

@@ -19,30 +19,32 @@ export abstract class PluginStoryApi {
   /**
    * Get properties of a story by its storey number.
    *
-   * Only the properties listed in {@linkcode PluginStoryGetArgs.properties args.properties}
+   * Only the properties listed in `properties`
    * are returned — unlisted properties will be `undefined` in the result.
    *
-   * @param args - An object containing:
-   *   - {@linkcode PluginStoryGetArgs.storyValue args.storyValue} — Integer storey number
-   *     (e.g. `1` for ground floor, `2` for first floor, `-1` for basement)
-   *   - {@linkcode PluginStoryGetArgs.properties args.properties} — Array of property names
-   *     to retrieve. See {@linkcode PluginStoryGetProperty} for available values.
+   * @param storyValue - Integer storey number
+   *   (e.g. `1` for ground floor, `2` for first floor, `-1` for basement)
+   * @param properties - Array of property names
+   *   to retrieve. See {@linkcode PluginStoryGetProperty} for available values.
    * @returns A partial {@linkcode PluginStoryGetResult} containing only the requested properties
    * @throws If the story with the given value does not exist
    *
+   * @examplePrompt What is the height of the ground floor?
+   * @examplePrompt How many rooms are on the second storey?
+   * @examplePrompt Get the total floor area of level 3
+   * @examplePrompt Is the first floor hidden in the viewport?
+   * @examplePrompt Show me the name and height of story 2
+   *
    * # Example
    * ```ts
-   * const info = await snaptrude.entity.story.get({
-   *   storyValue: 1,
-   *   properties: ["height", "name", "spacesCount"],
-   * })
+   * const info = await snaptrude.entity.story.get(1, ["height", "name", "spacesCount"])
    * console.log(info.name, info.height, info.spacesCount)
    * ```
    */
-  public abstract get({
-    storyValue,
-    properties,
-  }: PluginStoryGetArgs): PluginApiReturn<PluginStoryGetResult>
+  public abstract get(
+    storyValue: number,
+    properties: PluginStoryGetProperty[],
+  ): PluginApiReturn<PluginStoryGetResult>
 
   /**
    * Get all stories in the current project.
@@ -53,6 +55,11 @@ export abstract class PluginStoryApi {
    * @returns A {@linkcode PluginStoryGetAllResult} with a `stories` array,
    *   each entry containing `value`, `id`, and `name`
    *
+   * @examplePrompt How many floors does this building have?
+   * @examplePrompt List all the storeys in the project
+   * @examplePrompt Show me every level with its name
+   * @examplePrompt Which stories exist in this model?
+   *
    * # Example
    * ```ts
    * const { stories } = await snaptrude.entity.story.getAll()
@@ -67,30 +74,31 @@ export abstract class PluginStoryApi {
    * Create a new story (floor) in the project.
    *
    * The new story is inserted at the position specified by
-   * {@linkcode PluginStoryCreateArgs.storyValue args.storyValue}. This
-   * operation is undoable.
+   * `storyValue`. This operation is undoable.
    *
-   * @param args - An object containing:
-   *   - {@linkcode PluginStoryCreateArgs.storyValue args.storyValue} — Integer storey number
-   *     to create (e.g. `3` to add a third floor)
-   *   - {@linkcode PluginStoryCreateArgs.height args.height} — Optional height in Babylon
-   *     units. If omitted, the project's default storey height is used.
+   * @param storyValue - Integer storey number
+   *   to create (e.g. `3` to add a third floor)
+   * @param height - Optional height in Babylon
+   *   units. If omitted, the project's default storey height is used.
    * @returns A {@linkcode PluginStoryCreateResult} with `storyId` and `storyValue`
    * @throws If a story with the given value already exists or creation fails
    *
+   * @examplePrompt Add a third floor to the building
+   * @examplePrompt Create a new storey above the second floor
+   * @examplePrompt Add a basement level to this project
+   * @examplePrompt Insert a new level with a custom floor height
+   * @examplePrompt Add another floor on top of the building
+   *
    * # Example
    * ```ts
    * // Create a new third floor with custom height
-   * const { storyId } = await snaptrude.entity.story.create({
-   *   storyValue: 3,
-   *   height: 4.5,
-   * })
+   * const { storyId } = await snaptrude.entity.story.create(3, 4.5)
    * ```
    */
-  public abstract create({
-    storyValue,
-    height,
-  }: PluginStoryCreateArgs): PluginApiReturn<PluginStoryCreateResult>
+  public abstract create(
+    storyValue: number,
+    height?: number,
+  ): PluginApiReturn<PluginStoryCreateResult>
 
   /**
    * Update a story's height.
@@ -98,27 +106,28 @@ export abstract class PluginStoryApi {
    * Changes the floor-to-floor height of the specified story. This
    * operation is undoable.
    *
-   * @param args - An object containing:
-   *   - {@linkcode PluginStoryUpdateArgs.storyValue args.storyValue} — Integer storey number
-   *     identifying the story to update
-   *   - {@linkcode PluginStoryUpdateArgs.height args.height} — New height value in Babylon
-   *     units
+   * @param storyValue - Integer storey number
+   *   identifying the story to update
+   * @param height - New height value in Babylon
+   *   units
    * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
    * @throws If the story does not exist or the update fails
    *
+   * @examplePrompt Change the ground floor height to 3.5 metres
+   * @examplePrompt Make the second storey taller
+   * @examplePrompt Set the floor-to-floor height of level 1
+   * @examplePrompt Increase the height of the third floor
+   *
    * # Example
    * ```ts
    * // Set ground floor height to 5 Babylon units
-   * const result = await snaptrude.entity.story.update({
-   *   storyValue: 1,
-   *   height: 5,
-   * })
+   * const result = await snaptrude.entity.story.update(1, 5)
    * ```
    */
-  public abstract update({
-    storyValue,
-    height,
-  }: PluginStoryUpdateArgs): PluginApiReturn<PluginStoryUpdateResult>
+  public abstract update(
+    storyValue: number,
+    height: number,
+  ): PluginApiReturn<PluginStoryUpdateResult>
 }
 
 /**
@@ -146,6 +155,8 @@ export const PluginStoryGetProperty = z.enum([
   "totalArea",
 ])
 
+export type PluginStoryGetProperty = z.infer<typeof PluginStoryGetProperty>
+
 /**
  * Arguments for {@linkcode PluginStoryApi.get}.
  *

package/src/api/index.ts

@@ -1,37 +1,37 @@
 import { PluginCoreApi } from "./core"
+import { PluginDesignApi } from "./design"
 import { PluginEntityApi } from "./entity"
-import { PluginToolsApi } from "./tools"
-import { PluginUnitsApi } from "./units"
-import { PluginDocumentationApi } from "./documentation"
+import { PluginProgramApi } from "./program"
+import { PluginPresentationApi } from "./presentation"
 
 /**
  * Root API surface for Snaptrude plugins.
  *
  * Access all plugin capabilities through the namespaced properties:
  *
- * - {@linkcode PluginApi.core} — Math and geometry primitives
+ * - {@linkcode PluginApi.core} — Math, geometry kernel, history, units, zoom, project, comments (infrastructure)
+ * - {@linkcode PluginApi.design} — Author, query & edit BIM geometry
  * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
- * - {@linkcode PluginApi.tools} — Copy, offset, selection, and transform tools
- * - {@linkcode PluginApi.units} — Unit conversion utilities
- * - {@linkcode PluginApi.documentation} — Present documentation APIs
+ * - {@linkcode PluginApi.program} — Program-mode planning reads (departments, metrics)
+ * - {@linkcode PluginApi.presentation} — Presentation preparation (views, AI Inspiration)
  */
 export abstract class PluginApi {
-  /** Core math and geometry primitives. See {@linkcode PluginCoreApi}. */
+  /** Core math, geometry, history, and units primitives. See {@linkcode PluginCoreApi}. */
   public abstract core: PluginCoreApi
-  /** Copy, offset, selection, and transform tools. See {@linkcode PluginToolsApi}. */
-  public abstract tools: PluginToolsApi
+  /** Author, query & edit BIM geometry. See {@linkcode PluginDesignApi}. */
+  public abstract design: PluginDesignApi
   /** CRUD operations on Snaptrude entities. See {@linkcode PluginEntityApi}. */
   public abstract entity: PluginEntityApi
-  /** Unit conversion utilities. See {@linkcode PluginUnitsApi}. */
-  public abstract units: PluginUnitsApi
-  /** Present documentation APIs. See {@linkcode PluginDocumentationApi}. */
-  public abstract documentation: PluginDocumentationApi
+  /** Program-mode planning reads — departments and area metrics. See {@linkcode PluginProgramApi}. */
+  public abstract program: PluginProgramApi
+  /** Presentation preparation reads — saved views. See {@linkcode PluginPresentationApi}. */
+  public abstract presentation: PluginPresentationApi
 
   constructor() {}
 }
 
 export * from "./core"
-export * from "./documentation"
+export * from "./design"
 export * from "./entity"
-export * from "./tools"
-export * from "./units"
+export * from "./program"
+export * from "./presentation"

package/src/api/presentation/aiInspiration.ts

@@ -0,0 +1,362 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+
+const JsonPrimitive = z.union([z.string(), z.number(), z.boolean(), z.null()])
+type JsonValue =
+  | z.infer<typeof JsonPrimitive>
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+const JsonValue: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([JsonPrimitive, z.array(JsonValue), z.record(z.string(), JsonValue)]),
+)
+
+export const PluginAIInspirationOutputKind = z.enum([
+  "source",
+  "image",
+  "video",
+])
+export type PluginAIInspirationOutputKind = z.infer<
+  typeof PluginAIInspirationOutputKind
+>
+
+export const PluginAIInspirationModelOutput = z.enum(["image", "video"])
+export type PluginAIInspirationModelOutput = z.infer<
+  typeof PluginAIInspirationModelOutput
+>
+
+export const PluginAIInspirationShapeKind = z.enum(["image", "view", "video"])
+export type PluginAIInspirationShapeKind = z.infer<
+  typeof PluginAIInspirationShapeKind
+>
+
+export const PluginAIInspirationVideoMode = z.enum([
+  "animate",
+  "references",
+  "keyframes",
+])
+export type PluginAIInspirationVideoMode = z.infer<
+  typeof PluginAIInspirationVideoMode
+>
+
+export const PluginAIInspirationVideoMotion = z.enum([
+  "auto",
+  "slow-dolly",
+  "subtle-orbit",
+  "reveal",
+])
+export type PluginAIInspirationVideoMotion = z.infer<
+  typeof PluginAIInspirationVideoMotion
+>
+
+export const PluginAIInspirationVideoDuration = z.enum(["4s", "6s", "8s"])
+export type PluginAIInspirationVideoDuration = z.infer<
+  typeof PluginAIInspirationVideoDuration
+>
+
+export const PluginAIInspirationRegionHint = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  w: z.number().finite().positive(),
+  h: z.number().finite().positive(),
+})
+export type PluginAIInspirationRegionHint = z.infer<
+  typeof PluginAIInspirationRegionHint
+>
+
+export const PluginAIInspirationPoint = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+})
+export type PluginAIInspirationPoint = z.infer<typeof PluginAIInspirationPoint>
+
+export const PluginAIInspirationTextAnnotation = z.object({
+  text: z.string().min(1),
+  x: z.number().finite().optional(),
+  y: z.number().finite().optional(),
+})
+export type PluginAIInspirationTextAnnotation = z.infer<
+  typeof PluginAIInspirationTextAnnotation
+>
+
+export const PluginAIInspirationSketchGuidance = z.object({
+  visualShapeIds: z.array(z.string()).optional(),
+  textAnnotations: z.array(PluginAIInspirationTextAnnotation).optional(),
+})
+export type PluginAIInspirationSketchGuidance = z.infer<
+  typeof PluginAIInspirationSketchGuidance
+>
+
+export const PluginAIInspirationSiteOptions = z.object({
+  includeSatellite: z.boolean().optional(),
+  includeStreetView: z.boolean().optional(),
+  includeAerial: z.boolean().optional(),
+  aerialBearing: z.number().finite().optional(),
+  aerialPitch: z.number().finite().optional(),
+  selectedDiagramIds: z.array(z.string()).optional(),
+  location: z
+    .object({
+      lat: z.number().finite(),
+      lng: z.number().finite(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationSiteOptions = z.infer<
+  typeof PluginAIInspirationSiteOptions
+>
+
+export const PluginAIInspirationAppliedPreset = z.object({
+  source: z.enum(["curated", "user"]),
+  presetId: z.string().min(1),
+  name: z.string().min(1),
+  savedPresetKind: z.enum(["prompt", "style"]).optional(),
+  stylePrompt: z.string().optional(),
+  modelId: z.string().optional(),
+  referenceImages: z
+    .array(
+      z.object({
+        url: z.string().min(1),
+        label: z.string().optional(),
+        weight: z.number().finite().optional(),
+      }),
+    )
+    .optional(),
+  siteDefaults: z
+    .object({
+      includeSatellite: z.boolean().optional(),
+      includeStreetView: z.boolean().optional(),
+      includeAerial: z.boolean().optional(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationAppliedPreset = z.infer<
+  typeof PluginAIInspirationAppliedPreset
+>
+
+export const PluginAIInspirationVideoOptions = z.object({
+  mode: PluginAIInspirationVideoMode.optional(),
+  endFrameShapeId: z.string().optional(),
+  motion: PluginAIInspirationVideoMotion.optional(),
+  duration: PluginAIInspirationVideoDuration.optional(),
+})
+export type PluginAIInspirationVideoOptions = z.infer<
+  typeof PluginAIInspirationVideoOptions
+>
+
+export const PluginAIInspirationModel = z.object({
+  id: z.string(),
+  label: z.string(),
+  supportsMultiImage: z.boolean(),
+  output: PluginAIInspirationModelOutput,
+  isDefault: z.boolean().optional(),
+})
+export type PluginAIInspirationModel = z.infer<typeof PluginAIInspirationModel>
+
+export const PluginAIInspirationListModelsResult = z.object({
+  defaultModelId: z.string(),
+  models: z.array(PluginAIInspirationModel),
+})
+export type PluginAIInspirationListModelsResult = z.infer<
+  typeof PluginAIInspirationListModelsResult
+>
+
+export const PluginAIInspirationShapeRef = z.object({
+  shapeId: z.string(),
+  assetId: z.string().optional(),
+  kind: PluginAIInspirationShapeKind,
+  name: z.string().optional(),
+  width: z.number().finite().optional(),
+  height: z.number().finite().optional(),
+  outputType: PluginAIInspirationOutputKind.optional(),
+  sourceUrl: z.string().optional(),
+})
+export type PluginAIInspirationShapeRef = z.infer<
+  typeof PluginAIInspirationShapeRef
+>
+
+export const PluginAIInspirationListSourcesArgs = z.object({
+  includeGenerated: z.boolean().optional(),
+  includeSourceUrl: z.boolean().optional(),
+})
+export type PluginAIInspirationListSourcesArgs = z.infer<
+  typeof PluginAIInspirationListSourcesArgs
+>
+
+export const PluginAIInspirationListSourcesResult = z.object({
+  sources: z.array(PluginAIInspirationShapeRef),
+})
+export type PluginAIInspirationListSourcesResult = z.infer<
+  typeof PluginAIInspirationListSourcesResult
+>
+
+export const PluginAIInspirationOutput = z.object({
+  outputType: z.enum(["image", "video"]),
+  shapeId: z.string(),
+  assetId: z.string(),
+  outputUrl: z.string().optional(),
+  position: PluginAIInspirationPoint.optional(),
+})
+export type PluginAIInspirationOutput = z.infer<
+  typeof PluginAIInspirationOutput
+>
+
+export const PluginAIInspirationDebugSummary = z.record(z.string(), JsonValue)
+export type PluginAIInspirationDebugSummary = z.infer<
+  typeof PluginAIInspirationDebugSummary
+>
+
+export const PluginAIInspirationRunMetadata = z.object({
+  geometryFidelity: z.string().optional(),
+  debugSummary: PluginAIInspirationDebugSummary.optional(),
+  streetViewComposite: z
+    .object({
+      used: z.boolean(),
+      renderMode: z.enum(["prompt_refs_default", "masked_composite_pilot"]),
+      backgroundLabel: z.string().optional(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationRunMetadata = z.infer<
+  typeof PluginAIInspirationRunMetadata
+>
+
+export const PluginAIInspirationGenerateArgs = z.object({
+  sourceShapeId: z.string().min(1),
+  prompt: z.string().min(1).max(8000),
+  modelId: z.string().optional(),
+  referenceShapeIds: z.array(z.string()).max(12).optional(),
+  referenceStrength: z.enum(["low", "medium", "high"]).optional(),
+  appliedPreset: PluginAIInspirationAppliedPreset.optional(),
+  site: PluginAIInspirationSiteOptions.optional(),
+  regionHint: PluginAIInspirationRegionHint.optional(),
+  sketchGuidance: PluginAIInspirationSketchGuidance.optional(),
+  video: PluginAIInspirationVideoOptions.optional(),
+})
+export type PluginAIInspirationGenerateArgs = z.infer<
+  typeof PluginAIInspirationGenerateArgs
+>
+
+export const PluginAIInspirationRunResult = z.object({
+  outputs: z.array(PluginAIInspirationOutput).min(1),
+  metadata: PluginAIInspirationRunMetadata.optional(),
+})
+export type PluginAIInspirationRunResult = z.infer<
+  typeof PluginAIInspirationRunResult
+>
+
+export const PluginAIInspirationRefineArgs = z.object({
+  sourceShapeId: z.string().min(1),
+  upscaleFactor: z
+    .union([z.literal(1.5), z.literal(2), z.literal(4)])
+    .optional(),
+})
+export type PluginAIInspirationRefineArgs = z.infer<
+  typeof PluginAIInspirationRefineArgs
+>
+
+/**
+ * Present-mode AI Inspiration APIs.
+ *
+ * These APIs operate on Present canvas shape IDs and inherit the current user's
+ * AI quota. They create outputs on the Present canvas; pure backend generation
+ * without canvas output is intentionally out of scope.
+ *
+ * Accessed via `snaptrude.presentation.aiInspiration`.
+ */
+export abstract class PluginPresentationAIInspirationApi {
+  constructor() {}
+
+  /**
+   * List AI Inspiration models that can be used for generation.
+   *
+   * @returns The default model ID and available model descriptors.
+   *
+   * @examplePrompt What AI inspiration models can I use?
+   * @examplePrompt List the available image and video models
+   * @examplePrompt Which generation model is the default?
+   *
+   * # Example
+   * ```ts
+   * const { defaultModelId, models } = await snaptrude.presentation.aiInspiration.listModels()
+   * const videoModels = models.filter((m) => m.output === "video")
+   * console.log(defaultModelId, videoModels.map((m) => m.id))
+   * ```
+   */
+  public abstract listModels(): PluginApiReturn<PluginAIInspirationListModelsResult>
+
+  /**
+   * List image/view/video sources on the current Present page.
+   *
+   * @param args - Optional filters. Set `includeGenerated` to include AI outputs.
+   * @returns Serializable shape references using Present canvas shape IDs.
+   *
+   * @examplePrompt List the images I can generate from on this page
+   * @examplePrompt What source shapes are on the present canvas?
+   * @examplePrompt Show me the reference images available for AI generation
+   *
+   * # Example
+   * ```ts
+   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })
+   * for (const s of sources) console.log(s.kind, s.shapeId, s.name)
+   * ```
+   */
+  public abstract listSources(
+    args: PluginAIInspirationListSourcesArgs,
+  ): PluginApiReturn<PluginAIInspirationListSourcesResult>
+
+  /**
+   * Generate an image or video from a Present canvas source.
+   *
+   * @param args - Generation options including source, prompt, model, references, site context,
+   * region guidance, sketch guidance, and video options.
+   * @returns The created canvas output(s).
+   *
+   * @examplePrompt Generate an image from this sketch
+   * @examplePrompt Render the selected view as a photorealistic image
+   * @examplePrompt Make an AI image of a modern facade from this source
+   * @examplePrompt Generate a video from this image
+   * @examplePrompt Turn this massing into a rendered street view
+   *
+   * # Example
+   * ```ts
+   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({})
+   * const [source, ...refs] = sources
+   * const { outputs } = await snaptrude.presentation.aiInspiration.generate({
+   *   sourceShapeId: source.shapeId,
+   *   prompt: "Photorealistic render of a modern timber facade at dusk",
+   *   referenceShapeIds: refs.slice(0, 2).map((r) => r.shapeId),
+   *   referenceStrength: "medium",
+   * })
+   * for (const out of outputs) console.log(out.outputType, out.shapeId, out.outputUrl)
+   * ```
+   */
+  public abstract generate(
+    args: PluginAIInspirationGenerateArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+
+  /**
+   * Refine/upscale an AI Inspiration source image.
+   *
+   * @param args - Source shape and optional upscale factor.
+   * @returns The refined canvas output(s).
+   *
+   * @examplePrompt Upscale this AI image
+   * @examplePrompt Refine and sharpen the selected render
+   * @examplePrompt Make this generated image higher resolution
+   *
+   * # Example
+   * ```ts
+   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })
+   * const image = sources.find((s) => s.kind === "image")
+   * if (image) {
+   *   const { outputs } = await snaptrude.presentation.aiInspiration.refine({
+   *     sourceShapeId: image.shapeId,
+   *     upscaleFactor: 2,
+   *   })
+   *   console.log(outputs[0].shapeId)
+   * }
+   * ```
+   */
+  public abstract refine(
+    args: PluginAIInspirationRefineArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+}

package/src/api/presentation/diagrams.ts

@@ -0,0 +1,84 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation diagrams — place diagram images onto sheets.
+ *
+ * {@linkcode PluginPresentationDiagramsApi.place} drops diagram images (by
+ * URL) onto a sheet and returns the created canvas shape ids (requires Present
+ * mode to be open). Adjacency data itself is read and computed via
+ * `program.adjacency` (see {@linkcode PluginProgramAdjacencyApi}).
+ *
+ * A future one-step spec-based `place` — which would render a diagram spec
+ * and place it in a single call — awaits a public generator from the
+ * documentation engine; until that generator exists, `place` takes ready
+ * image `urls` (we do not ship a spec-based `place` that would only throw).
+ *
+ * Accessed via `snaptrude.presentation.diagrams`.
+ */
+export abstract class PluginPresentationDiagramsApi {
+  constructor() {}
+
+  /**
+   * Place diagram images onto a sheet.
+   *
+   * Drops the given diagram image URLs onto a sheet and returns the ids of the
+   * created canvas shapes. Requires Present mode to be open.
+   *
+   * @param sheetId - The sheet to place onto.
+   * @param urls - Diagram image URLs to place.
+   * @param options - Optional `position` (`{ x, y }`, relative to the sheet)
+   *   for the placed images.
+   * @returns A {@linkcode PluginPresentationDiagramsPlaceResult} with the created
+   *   `shapeIds`.
+   * @throws If Present mode is not open or the sheet id is invalid.
+   *
+   * @examplePrompt Place the adjacency diagram on Sheet 1
+   * @examplePrompt Add the program diagram to the cover sheet
+   * @examplePrompt Drop these diagram images onto the layout
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.diagrams.place("sheet_1", [
+   *   "https://example.com/program-diagram.png",
+   * ])
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    urls: string[],
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginPresentationDiagramsPlaceResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationDiagramsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place onto |
+ * | `urls` | `string[]` | Diagram image URLs |
+ * | `position` | `{ x: number; y: number } \| undefined` | Where to place them |
+ */
+export const PluginPresentationDiagramsPlaceArgs = z.object({
+  sheetId: z.string(),
+  urls: z.array(z.string()),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+})
+export type PluginPresentationDiagramsPlaceArgs = z.infer<
+  typeof PluginPresentationDiagramsPlaceArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationDiagramsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeIds` | `string[]` | Ids of the created canvas shapes |
+ */
+export const PluginPresentationDiagramsPlaceResult = z.object({
+  shapeIds: z.array(z.string()),
+})
+export type PluginPresentationDiagramsPlaceResult = z.infer<
+  typeof PluginPresentationDiagramsPlaceResult
+>