@snaptrude/plugin-core 0.5.0 → 0.7.0

package/src/api/design/update/index.ts

@@ -8,6 +8,7 @@ import {
   PluginAreaClass,
   PluginSpaceUpdateResult,
 } from "../../entity/space"
+import { PluginDesignChangeResult } from "../lock"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -44,6 +45,83 @@ export const PluginUpdateSpaceItem = z.object({
 })
 export type PluginUpdateSpaceItem = z.infer<typeof PluginUpdateSpaceItem>
 
+/**
+ * Wire schema for {@linkcode PluginDesignUpdateApi.setLabel}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | `ComponentHandle` | The component to relabel |
+ * | `label` | `string` | New label (non-empty after trimming) |
+ */
+export const PluginDesignSetLabelArgs = z.object({
+  component: ComponentHandle,
+  label: z.string().trim().min(1),
+})
+export type PluginDesignSetLabelArgs = z.infer<typeof PluginDesignSetLabelArgs>
+
+/**
+ * Sparse parametric updates for a staircase (all fields optional; at least one
+ * required). Only the fields you provide change. Consumed by
+ * {@linkcode PluginDesignUpdateApi.staircase}; the paired read is
+ * `design.query.getStaircaseParams`.
+ *
+ * All dimensions are in **engine units** (the same convention as
+ * `design.doors.setWidth`); `steps` is a unitless integer count. Height, riser,
+ * and step count are **coupled** (`staircaseHeight = steps × riser`); the two
+ * lock booleans govern which value recomputes — see the method JSDoc.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `isStoreyHeightUnlocked` | `boolean`? | Unlock the staircase height from the storey height |
+ * | `isStaircaseHeightUnlocked` | `boolean`? | Unlock the height from `steps × riser` |
+ * | `storeyHeight` | `number`? | Storey height the stair sits within (engine units) |
+ * | `staircaseHeight` | `number`? | Total rise (engine units) |
+ * | `steps` | `number`? | Step count (unitless integer) |
+ * | `riser` | `number`? | Riser height (engine units) |
+ * | `tread` | `number`? | Tread depth (engine units) |
+ * | `width` | `number`? | Flight width (engine units) |
+ * | `depth` | `number`? | Slab/waist thickness (engine units) |
+ * | `wellSize` | `number`? | Stairwell gap (dogLegged / openWell / square) |
+ * | `flightStartDistAfterTurn` | `number`? | Flight offset after a turn (dogLegged / lShaped / square) |
+ * | `landingWidth` | `number`? | Landing depth (straight / dogLegged) |
+ * | `baseOffset` | `number`? | Vertical offset from the storey base (engine units) |
+ */
+export const PluginStaircaseParamUpdates = z
+  .object({
+    isStoreyHeightUnlocked: z.boolean().optional(),
+    isStaircaseHeightUnlocked: z.boolean().optional(),
+    storeyHeight: z.number().optional(),
+    staircaseHeight: z.number().optional(),
+    steps: z.number().int().optional(),
+    riser: z.number().optional(),
+    tread: z.number().optional(),
+    width: z.number().optional(),
+    depth: z.number().optional(),
+    wellSize: z.number().optional(),
+    flightStartDistAfterTurn: z.number().optional(),
+    landingWidth: z.number().optional(),
+    baseOffset: z.number().optional(),
+  })
+  .refine((p) => Object.keys(p).length > 0, {
+    message:
+      "PluginStaircaseParamUpdates requires at least one field to change",
+  })
+export type PluginStaircaseParamUpdates = z.infer<typeof PluginStaircaseParamUpdates>
+
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.staircase}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `staircases` | {@linkcode ComponentHandle}`[]` | The staircases to update |
+ * | `params` | {@linkcode PluginStaircaseParamUpdates} | Sparse parametric changes (≥ 1 field) |
+ */
+export const PluginDesignUpdateStaircaseArgs = z.object({
+  staircases: z.array(ComponentHandle),
+  params: PluginStaircaseParamUpdates,
+})
+export type PluginDesignUpdateStaircaseArgs = z.infer<typeof PluginDesignUpdateStaircaseArgs>
+
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
  *
@@ -53,6 +131,46 @@ export type PluginUpdateSpaceItem = z.infer<typeof PluginUpdateSpaceItem>
 export abstract class PluginDesignUpdateApi {
   constructor() {}
 
+  /**
+   * Set a component's **Label** — the same editable Label field the properties
+   * panel shows (doors, windows, furniture, spaces, and every other labelled
+   * component). The paired read is `design.query.getLabel`. Undoable; the
+   * canvas label text updates immediately.
+   *
+   * Strictly **per component**: labelling one door of a placed family never
+   * touches its sibling doors (the panel's Label edit, by contrast, applies to
+   * the whole family). On **legacy masses** without a space type, panel parity
+   * applies — a label matching a room-type preset with a height can also
+   * adjust the mass's height and material, exactly like typing it in the panel.
+   *
+   * Throws when the component is locked, the handle is gone/forged, the label
+   * is empty, or the component has no mesh to label. Re-applying the current
+   * label is a no-op that returns `true` without touching the undo stack.
+   *
+   * @param component - The component to relabel
+   * @param label - New label text (non-empty; leading/trailing whitespace trimmed)
+   * @returns `true` once the label is applied
+   *
+   * @examplePrompt Rename this door to D-101
+   * @examplePrompt Number all doors on storey 2 with a D-2-XX tag
+   * @examplePrompt Set the selected window's label to W-04
+   * @examplePrompt Tag every door with its fire rating
+   *
+   * # Example
+   * ```ts
+   * // Door tag numbering: label every door as D-<storey>-<n>, numbered per storey
+   * await snaptrude.design.selection.setByFilter({ types: ["door"] })
+   * const doors = await snaptrude.design.selection.get()
+   * const counts = {}
+   * for (const door of doors) {
+   *   const { storey = 0 } = await snaptrude.design.query.getProperties(door)
+   *   counts[storey] = (counts[storey] ?? 0) + 1
+   *   await snaptrude.design.update.setLabel(door, `D-${storey}-${String(counts[storey]).padStart(2, "0")}`)
+   * }
+   * ```
+   */
+  public abstract setLabel(component: ComponentHandle, label: string): PluginApiReturn<boolean>
+
   /**
    * Update a single space (room) — change its properties (room label, space
    * type, mass type, area class, department) and/or replace its geometry by
@@ -114,4 +232,53 @@ export abstract class PluginDesignUpdateApi {
    * ```
    */
   public abstract spaces(items: PluginUpdateSpaceItem[]): PluginApiReturn<PluginSpaceUpdateResult[]>
+
+  /**
+   * Update the parameters of one or more staircases — riser, tread, width,
+   * depth, step count, total height, well size, landing depth, base offset,
+   * and the two height locks — in one undoable operation. Sparse: only the
+   * fields you provide change. The paired read is
+   * `design.query.getStaircaseParams`.
+   *
+   * All dimensions are in **engine units** (the same convention as
+   * `design.doors.setWidth`); `steps` is a unitless integer count. The height,
+   * riser, and step count are **coupled** — `staircaseHeight = steps × riser` —
+   * and the two lock booleans govern which value recomputes when another
+   * changes. With `isStoreyHeightUnlocked` false the staircase height follows
+   * the storey height; unlocking it also unlocks the staircase height. Setting
+   * `steps` recomputes `riser` (or the height, once the height is unlocked),
+   * and setting `riser` recomputes `steps`/height in turn.
+   *
+   * Presets-only: this edits the parametric fields of a preset staircase; it
+   * does not change the staircase's type/preset (there is no in-place re-type).
+   * Every edit rebuilds the staircase geometry, so the call is async.
+   *
+   * Throws when a handle is not a staircase, when a staircase is locked, or
+   * when a value falls outside the engine's accepted range (RPC rejects).
+   *
+   * @param staircases - the staircases to update
+   * @param params - sparse {@linkcode PluginStaircaseParamUpdates} (at least one field)
+   * @returns the affected staircases
+   *
+   * @examplePrompt Set the riser of this staircase to 165mm
+   * @examplePrompt Change all the stairs to 14 steps
+   * @examplePrompt Make the selected staircase 1200 wide with a 280 tread
+   * @examplePrompt Widen every staircase on level 1 to 1 metre
+   * @examplePrompt Unlock the height and set this stair to 3200 tall
+   *
+   * # Example
+   * ```ts
+   * // Give every ground-floor staircase a common riser + tread (engine units)
+   * const stairs = await snaptrude.design.query.listStaircases({ storeys: [1] })
+   * const { affected } = await snaptrude.design.update.staircase(stairs, {
+   *   riser: 165,
+   *   tread: 280,
+   * })
+   * console.log("updated", affected.length, "staircases")
+   * ```
+   */
+  public abstract staircase(
+    staircases: ComponentHandle[],
+    params: PluginStaircaseParamUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
 }

package/src/api/design/windows/index.ts

@@ -2,14 +2,21 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
+import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
 
 /**
  * `snaptrude.design.windows` — window-specific reads. Creation lives at
  * `design.create.window`; generic reads (`listWindows`/`getHost`/`getProperties`) live
  * at `design.query.*`. Window targets are {@linkcode ComponentHandle}s.
  *
- * `listTypes` (UI-const catalog), `getSillHeight` (bounds-derived), and the
- * command-wired `mirror` land in a later pass.
+ * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
+ * browse the placeable window library — plain value records keyed by a library id
+ * (team `_id` or general `fullName`), NOT handles — and feed `design.create.window`.
+ * They are network-backed but carry no `Async` suffix (§6.6) and never throw
+ * (`[]`/`null`). The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
+ * DTOs are shared with `design.doors` (defined there, re-exported here).
+ *
+ * `getSillHeight` (bounds-derived) and the command-wired `mirror` land in a later pass.
  */
 export abstract class PluginDesignWindowsApi {
   constructor() {}
@@ -148,6 +155,91 @@ export abstract class PluginDesignWindowsApi {
     window: ComponentHandle,
     height: number
   ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * List the window catalog **groups** — the placement families (Fixed,
+   * Casement, Sliding, Folding, …), built-in groups merged with any
+   * team-custom types.
+   *
+   * @returns The groups as {@linkcode PluginObjectCatalogGroup}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What kinds of windows can I place?
+   * @examplePrompt List the window groups in the catalog
+   * @examplePrompt Show me the window families available in this project
+   * @examplePrompt Which window types does this project support?
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.windows.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
+  /**
+   * List the placeable window catalog (team + general libraries), optionally
+   * restricted to one group by its `dbType` token.
+   *
+   * @param group Restrict to one group's `dbType` (optional; e.g. `"casementDouble"`)
+   * @returns The catalog as {@linkcode PluginObjectCatalogItem}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What windows can I place in this project?
+   * @examplePrompt List every window in the library
+   * @examplePrompt Show me the casement windows I can add
+   * @examplePrompt Browse the window catalog
+   *
+   * # Example
+   * ```ts
+   * const [group] = await snaptrude.design.windows.listCatalogGroups()
+   * const items = await snaptrude.design.windows.listCatalog(group?.dbType)
+   * for (const item of items) console.log(item.id, item.name, item.thumbnailUrl)
+   * ```
+   */
+  public abstract listCatalog(
+    group?: string
+  ): PluginApiReturn<PluginObjectCatalogItem[]>
+
+  /**
+   * Get a single window catalog item by its library id.
+   *
+   * @param id The catalog library id
+   * @returns The item, or `null` if no catalog item matches
+   *
+   * @examplePrompt Get the details of this window from the library
+   * @examplePrompt Look up the catalog entry for this window id
+   * @examplePrompt What is the cost of this window item?
+   * @examplePrompt Show me the family name of this window in the catalog
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const item = await snaptrude.design.windows.getCatalogItem(entry.id)
+   * if (item) console.log(item.name, item.source, item.dbType)
+   * ```
+   */
+  public abstract getCatalogItem(
+    id: string
+  ): PluginApiReturn<PluginObjectCatalogItem | null>
+
+  /**
+   * Test whether a window catalog item exists for the given library id.
+   *
+   * @param id The catalog library id
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Is this window still in the library?
+   * @examplePrompt Check whether a window catalog item with this id exists
+   * @examplePrompt Does my team library have this window?
+   * @examplePrompt Verify the window is available before placing it
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const stillAvailable = await snaptrude.design.windows.exists(entry.id)
+   * console.log(stillAvailable ? "safe to place" : "removed from library")
+   * ```
+   */
+  public abstract exists(id: string): PluginApiReturn<boolean>
 }
 
 /**
@@ -205,3 +297,37 @@ export const PluginDesignWindowSetHeightArgs = z.object({
   height: z.number(),
 })
 export type PluginDesignWindowSetHeightArgs = z.infer<typeof PluginDesignWindowSetHeightArgs>
+
+// ---------------------------------------------------------------------------
+// catalog (shared DTOs defined in ../doors, re-exported here for symmetry)
+// ---------------------------------------------------------------------------
+
+// Re-export the shared catalog DTOs imported at the top of this file.
+export { PluginObjectCatalogGroup, PluginObjectCatalogItem }
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.listCatalog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `group` | `string`? | Restrict to one group's `dbType` token (optional) |
+ */
+export const PluginDesignWindowListCatalogArgs = z.object({
+  group: z.string().optional(),
+})
+export type PluginDesignWindowListCatalogArgs = z.infer<typeof PluginDesignWindowListCatalogArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.getCatalogItem} / {@linkcode PluginDesignWindowsApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export const PluginDesignWindowGetCatalogItemArgs = z.object({
+  id: z.string(),
+})
+export type PluginDesignWindowGetCatalogItemArgs = z.infer<typeof PluginDesignWindowGetCatalogItemArgs>
+
+export const PluginDesignWindowExistsArgs = PluginDesignWindowGetCatalogItemArgs
+export type PluginDesignWindowExistsArgs = z.infer<typeof PluginDesignWindowExistsArgs>

package/src/api/entity/story.ts

@@ -1,5 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
 
 /**
  * Story (floor/storey) management.
@@ -101,17 +102,25 @@ export abstract class PluginStoryApi {
   ): PluginApiReturn<PluginStoryCreateResult>
 
   /**
-   * Update a story's height.
+   * Update a story's floor-to-floor height, cascading the full geometry change.
    *
-   * Changes the floor-to-floor height of the specified story. This
-   * operation is undoable.
+   * This is the same operation as editing the height in the Stories panel: the
+   * walls, columns, and masses on the story are **stretched** to the new height,
+   * every story **above shifts up/down** by the delta so the stack stays
+   * contiguous, and coupled elements (staircases, parametric curtain walls,
+   * furniture offsets) are re-fitted. The whole cascade is committed as **one
+   * undo step**. Height-locked elements are left untouched.
    *
    * @param storyValue - Integer storey number
    *   identifying the story to update
-   * @param height - New height value in Babylon
-   *   units
+   * @param height - New floor-to-floor height in
+   *   Babylon units
    * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
-   * @throws If the story does not exist or the update fails
+   * @throws `PRECONDITION_FAILED` if no story has the given value;
+   *   `STORY_HEIGHT_REJECTED` if the engine rejects the height (e.g. out of
+   *   range — the change silently reverts host-side and is surfaced as this
+   *   error); `STORY_UPDATE_FAILED` if the story cannot be re-read after the
+   *   update
    *
    * @examplePrompt Change the ground floor height to 3.5 metres
    * @examplePrompt Make the second storey taller
@@ -120,7 +129,8 @@ export abstract class PluginStoryApi {
    *
    * # Example
    * ```ts
-   * // Set ground floor height to 5 Babylon units
+   * // Set ground floor height to 5 Babylon units — walls stretch and the
+   * // floors above move up to match, all in a single undo step.
    * const result = await snaptrude.entity.story.update(1, 5)
    * ```
    */
@@ -128,6 +138,54 @@ export abstract class PluginStoryApi {
     storyValue: number,
     height: number,
   ): PluginApiReturn<PluginStoryUpdateResult>
+
+  /**
+   * Duplicate a story into the adjacent level, up or down.
+   *
+   * By default the **whole story** is duplicated: every eligible element on the
+   * active story (walls, floors, roofs, masses, columns, beams, staircases,
+   * ceilings, parametric curtain walls, and furniture) is copied into the story
+   * one level `"up"` or `"down"`. Pass `options.components` to duplicate only a
+   * subset instead. The target story is **created automatically** if it does not
+   * yet exist, inheriting the source story's height.
+   *
+   * Copies are **instanced** by default (`unique: false`) — they share geometry
+   * with the source, so later edits propagate. Set `unique: true` for independent
+   * geometry. Doors and windows are never duplicated on their own; they ride along
+   * with their host wall. Locked, throw-away, and unsupported elements are skipped
+   * and counted in `skipped`. The whole operation is a single undo step.
+   *
+   * @param direction - `"up"` to duplicate into the story above, `"down"` for below
+   * @param options - `components` (restrict to a subset of the story's elements;
+   *   omit for the whole story) and `unique` (default `false` = instanced copies;
+   *   `true` = independent geometry)
+   * @returns A {@linkcode PluginStoryDuplicateResult} with the `sourceStory`, the
+   *   `targetStories` the copies landed on, the `created` component handles, the
+   *   `createdStoryValues` for any stories generated to receive them, and the
+   *   `skipped` count of ineligible elements
+   * @throws `NO_ACTIVE_STRUCTURE` if there is no active structure to duplicate
+   *   into; `NO_ELIGIBLE_ELEMENTS` if nothing on the source story (or in
+   *   `options.components`) is duplicable; `HANDLE_INVALID` for a stale or
+   *   foreign supplied handle; or if plugin writes are disabled
+   *
+   * @examplePrompt Duplicate this floor to the storey above
+   * @examplePrompt Copy the ground floor down into a new basement
+   * @examplePrompt Repeat this level upwards with its own independent geometry
+   * @examplePrompt Duplicate just the selected walls onto the next floor up
+   *
+   * # Example
+   * ```ts
+   * // Duplicate the whole active story one level up (instanced copies).
+   * const { targetStories, created, skipped } =
+   *   await snaptrude.entity.story.duplicate("up")
+   * console.log(`Copied ${created.length} elements onto story ${targetStories}`)
+   * if (skipped) console.log(`${skipped} elements were skipped`)
+   * ```
+   */
+  public abstract duplicate(
+    direction: "up" | "down",
+    options?: { components?: ComponentHandle[]; unique?: boolean },
+  ): PluginApiReturn<PluginStoryDuplicateResult>
 }
 
 /**
@@ -271,3 +329,43 @@ export const PluginStoryUpdateResult = z.object({
 })
 
 export type PluginStoryUpdateResult = z.infer<typeof PluginStoryUpdateResult>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.duplicate} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `direction` | `'up' \| 'down'` | Which adjacent story to duplicate into |
+ * | `components` | {@linkcode ComponentHandle}`[]?` | Restrict to a subset; omit for the whole story |
+ * | `unique` | `boolean?` | `false` (default) = instanced copies; `true` = independent geometry |
+ */
+export const PluginStoryDuplicateArgs = z.object({
+  direction: z.enum(["up", "down"]),
+  components: z.array(ComponentHandle).optional(),
+  unique: z.boolean().optional(),
+})
+
+export type PluginStoryDuplicateArgs = z.infer<typeof PluginStoryDuplicateArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.duplicate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sourceStory` | `number` | Storey value the copies were duplicated from |
+ * | `targetStories` | `number[]` | Storey values the copies landed on |
+ * | `created` | {@linkcode ComponentHandle}`[]` | Handles of the newly created components |
+ * | `createdStoryValues` | `number[]` | Storey values that were generated to receive the copies |
+ * | `skipped` | `number` | Count of ineligible elements that were skipped |
+ */
+export const PluginStoryDuplicateResult = z.object({
+  sourceStory: z.number(),
+  targetStories: z.array(z.number()),
+  created: z.array(ComponentHandle),
+  createdStoryValues: z.array(z.number()),
+  skipped: z.number(),
+})
+
+export type PluginStoryDuplicateResult = z.infer<
+  typeof PluginStoryDuplicateResult
+>

package/src/api/index.ts

@@ -3,6 +3,7 @@ import { PluginDesignApi } from "./design"
 import { PluginEntityApi } from "./entity"
 import { PluginProgramApi } from "./program"
 import { PluginPresentationApi } from "./presentation"
+import { PluginAnalysisApi } from "./analysis"
 
 /**
  * Root API surface for Snaptrude plugins.
@@ -14,6 +15,7 @@ import { PluginPresentationApi } from "./presentation"
  * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
  * - {@linkcode PluginApi.program} — Program-mode planning reads (departments, metrics)
  * - {@linkcode PluginApi.presentation} — Presentation preparation (views, AI Inspiration)
+ * - {@linkcode PluginApi.analysis} — Sustainability analysis (sunpath, shadows, sunlight/illuminance heatmaps)
  */
 export abstract class PluginApi {
   /** Core math, geometry, history, and units primitives. See {@linkcode PluginCoreApi}. */
@@ -26,6 +28,8 @@ export abstract class PluginApi {
   public abstract program: PluginProgramApi
   /** Presentation preparation reads — saved views. See {@linkcode PluginPresentationApi}. */
   public abstract presentation: PluginPresentationApi
+  /** Sustainability analysis — sun & daylight studies. See {@linkcode PluginAnalysisApi}. */
+  public abstract analysis: PluginAnalysisApi
 
   constructor() {}
 }
@@ -35,3 +39,4 @@ export * from "./design"
 export * from "./entity"
 export * from "./program"
 export * from "./presentation"
+export * from "./analysis"

package/src/api/presentation/import.ts

@@ -4,9 +4,10 @@ import { PluginApiReturn } from "../../types"
 /**
  * Presentation import — bring external reference assets onto the Present canvas.
  *
- * `import.image` places a reference image and `import.pdf` places a PDF (each
- * page vectorized to SVG) onto the current Present sheet, returning the created
- * canvas shape ids. Requires Present mode to be open.
+ * `import.image` places a reference image, `import.pdf` places a PDF (each
+ * page vectorized to SVG), and `import.svg` places a validated SVG onto
+ * the current Present sheet, returning the created canvas shape ids. Requires
+ * Present mode to be open.
  *
  * The host engine takes a browser `File`, which a plugin worker cannot supply,
  * so these accept a `url`/`dataUrl` that the host adapts into a `File`.
@@ -72,11 +73,51 @@ export abstract class PluginPresentationImportApi {
     source: { url?: string; dataUrl?: string },
     options?: { position?: { x: number; y: number } },
   ): PluginApiReturn<PluginPresentationImportResult>
+
+  /**
+   * Import an SVG onto the current Present sheet as a vector asset.
+   *
+   * An SVG-validating variant of {@linkcode PluginPresentationImportApi.image}:
+   * `import.image` already passes SVG sources through, but this method first
+   * validates that the source really is an SVG and forces the vector mime
+   * type. Throws if the source is not an SVG.
+   *
+   * **Rendering is vector up to a complexity cap.** Simple SVGs (up to ~1500
+   * SVG element nodes and ~2 MB) render true-vector and stay crisp at every
+   * zoom. Beyond that cap the shared canvas renderer **intentionally falls
+   * back to a 1920px raster** to protect canvas performance, so very complex
+   * SVGs can look rasterized when zoomed in. The stored asset is the original
+   * SVG either way; only the on-canvas rendering falls back.
+   *
+   * @param source - The SVG to import: exactly one of `url` or `dataUrl`.
+   * @param options - Optional `position` — where to place the SVG on the sheet.
+   * @returns A {@linkcode PluginPresentationImportResult} with the created
+   *   `shapeIds`.
+   * @throws If Present mode is not open, the source is not an SVG, or it cannot
+   *   be loaded.
+   *
+   * @examplePrompt Import this SVG diagram onto the present canvas
+   * @examplePrompt Add a vector logo to my presentation board
+   * @examplePrompt Place this SVG floor plan on the current sheet as vectors
+   * @examplePrompt Bring a crisp vector graphic into Present mode
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.import.svg({
+   *   url: "https://example.com/diagram.svg",
+   * })
+   * ```
+   */
+  public abstract svg(
+    source: { url?: string; dataUrl?: string },
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginPresentationImportResult>
 }
 
 /**
  * Arguments for {@linkcode PluginPresentationImportApi.image} /
- * {@linkcode PluginPresentationImportApi.pdf}. Provide exactly one source.
+ * {@linkcode PluginPresentationImportApi.pdf} /
+ * {@linkcode PluginPresentationImportApi.svg}. Provide exactly one source.
  *
  * | Property | Type | Description |
  * |---|---|---|