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

package/src/api/core/units/index.ts

@@ -1,164 +1,164 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-
-/**
- * Unit-type queries and conversion.
- *
- * Snaptrude stores all geometry in an internal `babylon` unit. These methods
- * read the available unit types, the internal (`babylon`) type, and the current
- * project type; set the current project type; and convert values between any two
- * unit types.
- *
- * Accessed via `snaptrude.core.units`.
- */
-export abstract class PluginUnitsApi {
-  constructor() {}
-
-  /**
-   * List the selectable real-world unit types (excludes the internal `babylon`
-   * storage type, which is read via {@linkcode PluginUnitsApi.getBabylonType}).
-   *
-   * @examplePrompt What units can I use in this project?
-   * @examplePrompt List all the available measurement units
-   * @examplePrompt Which unit systems does Snaptrude support?
-   * @examplePrompt Show the unit options I could switch the model to
-   *
-   * # Example
-   * ```ts
-   * const types = await snaptrude.core.units.listTypes()
-   * console.log(types) // ["meters", "feet-inches", "inches", ...]
-   * ```
-   */
-  public abstract listTypes(): PluginApiReturn<PUnitType[]>
-
-  /**
-   * Get the internal storage unit type that all geometry is kept in — always
-   * `"babylon"` — for use as one side of a {@linkcode PluginUnitsApi.convert} call.
-   *
-   * @examplePrompt What unit does Snaptrude store geometry in internally?
-   * @examplePrompt Get the internal babylon unit type
-   * @examplePrompt Which unit are raw model coordinates saved in?
-   *
-   * # Example
-   * ```ts
-   * const babylon = await snaptrude.core.units.getBabylonType() // "babylon"
-   * const meters = await snaptrude.core.units.convert(10, babylon, "meters")
-   * ```
-   */
-  public abstract getBabylonType(): PluginApiReturn<PUnitType>
-
-  /**
-   * Get the current project's unit type — the unit lengths are displayed and
-   * entered in. Paired with {@linkcode PluginUnitsApi.setType}.
-   *
-   * @examplePrompt What units is this project using?
-   * @examplePrompt Are we working in metric or imperial?
-   * @examplePrompt Check the current measurement unit of the model
-   * @examplePrompt Is the file set to millimetres or feet and inches?
-   *
-   * # Example
-   * ```ts
-   * const type = await snaptrude.core.units.getType()
-   * console.log(type) // e.g. "millimeters"
-   * ```
-   */
-  public abstract getType(): PluginApiReturn<PUnitType>
-
-  /**
-   * Set the current project's unit type. Paired with {@linkcode PluginUnitsApi.getType}.
-   *
-   * @param type - The unit type to set as the project unit.
-   * @returns `true` if applied; `false` if `type` is not a settable project unit
-   *   (e.g. `kilometers`, `miles`, `babylon`).
-   *
-   * @examplePrompt Change the project units to millimeters
-   * @examplePrompt Switch this model to feet and inches
-   * @examplePrompt Set the working units to metric
-   * @examplePrompt Make the drawing use centimetres instead of meters
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.units.setType("meters")
-   * ```
-   */
-  public abstract setType(type: PUnitType): PluginApiReturn<boolean>
-
-  /**
-   * Convert a value between two unit types.
-   *
-   * @param value - The numeric value to convert.
-   * @param from - Source unit type.
-   * @param to - Target unit type.
-   * @param degree - (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1.
-   * @returns The converted numeric value.
-   *
-   * @examplePrompt Convert 5 meters to feet and inches
-   * @examplePrompt How many millimetres is 12 feet?
-   * @examplePrompt Change this area from internal units to square metres
-   * @examplePrompt Turn 2500 mm into meters
-   * @examplePrompt Convert a volume value from babylon units to cubic feet
-   *
-   * # Example
-   * ```ts
-   * // 5 meters → internal babylon units
-   * const b = await snaptrude.core.units.convert(5, "meters", "babylon")
-   * // an internal area → square metres
-   * const m2 = await snaptrude.core.units.convert(area, "babylon", "meters", 2)
-   * ```
-   */
-  public abstract convert(
-    value: number,
-    from: PUnitType,
-    to: PUnitType,
-    degree?: number,
-  ): PluginApiReturn<number>
-}
-
-/**
- * Supported unit types. `babylon` is Snaptrude's internal storage unit; the rest
- * are real-world units. Mirrors the engine `Converter.UNITS` vocabulary.
- */
-export const PUnitType = z.enum([
-  "meters",
-  "feet-inches",
-  "inches",
-  "centimeters",
-  "millimeters",
-  "kilometers",
-  "miles",
-  "babylon",
-])
-
-export type PUnitType = z.infer<typeof PUnitType>
-
-/**
- * Arguments for {@linkcode PluginUnitsApi.setType}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `type` | {@linkcode PUnitType} | The unit type to set as the project unit |
- */
-export const PluginUnitsSetTypeArgs = z.object({
-  type: PUnitType,
-})
-
-export type PluginUnitsSetTypeArgs = z.infer<typeof PluginUnitsSetTypeArgs>
-
-/**
- * Arguments for {@linkcode PluginUnitsApi.convert}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `value` | `number` | The numeric value to convert |
- * | `from` | {@linkcode PUnitType} | Source unit type |
- * | `to` | {@linkcode PUnitType} | Target unit type |
- * | `degree` | `1 \| 2 \| 3` | (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1 |
- */
-export const PluginUnitsConvertArgs = z.object({
-  value: z.number(),
-  from: PUnitType,
-  to: PUnitType,
-  degree: z.number().int().min(1).max(3).optional(),
-})
-
-export type PluginUnitsConvertArgs = z.infer<typeof PluginUnitsConvertArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Unit-type queries and conversion.
+ *
+ * Snaptrude stores all geometry in an internal `babylon` unit. These methods
+ * read the available unit types, the internal (`babylon`) type, and the current
+ * project type; set the current project type; and convert values between any two
+ * unit types.
+ *
+ * Accessed via `snaptrude.core.units`.
+ */
+export abstract class PluginUnitsApi {
+  constructor() {}
+
+  /**
+   * List the selectable real-world unit types (excludes the internal `babylon`
+   * storage type, which is read via {@linkcode PluginUnitsApi.getBabylonType}).
+   *
+   * @examplePrompt What units can I use in this project?
+   * @examplePrompt List all the available measurement units
+   * @examplePrompt Which unit systems does Snaptrude support?
+   * @examplePrompt Show the unit options I could switch the model to
+   *
+   * # Example
+   * ```ts
+   * const types = await snaptrude.core.units.listTypes()
+   * console.log(types) // ["meters", "feet-inches", "inches", ...]
+   * ```
+   */
+  public abstract listTypes(): PluginApiReturn<PUnitType[]>
+
+  /**
+   * Get the internal storage unit type that all geometry is kept in — always
+   * `"babylon"` — for use as one side of a {@linkcode PluginUnitsApi.convert} call.
+   *
+   * @examplePrompt What unit does Snaptrude store geometry in internally?
+   * @examplePrompt Get the internal babylon unit type
+   * @examplePrompt Which unit are raw model coordinates saved in?
+   *
+   * # Example
+   * ```ts
+   * const babylon = await snaptrude.core.units.getBabylonType() // "babylon"
+   * const meters = await snaptrude.core.units.convert(10, babylon, "meters")
+   * ```
+   */
+  public abstract getBabylonType(): PluginApiReturn<PUnitType>
+
+  /**
+   * Get the current project's unit type — the unit lengths are displayed and
+   * entered in. Paired with {@linkcode PluginUnitsApi.setType}.
+   *
+   * @examplePrompt What units is this project using?
+   * @examplePrompt Are we working in metric or imperial?
+   * @examplePrompt Check the current measurement unit of the model
+   * @examplePrompt Is the file set to millimetres or feet and inches?
+   *
+   * # Example
+   * ```ts
+   * const type = await snaptrude.core.units.getType()
+   * console.log(type) // e.g. "millimeters"
+   * ```
+   */
+  public abstract getType(): PluginApiReturn<PUnitType>
+
+  /**
+   * Set the current project's unit type. Paired with {@linkcode PluginUnitsApi.getType}.
+   *
+   * @param type - The unit type to set as the project unit.
+   * @returns `true` if applied; `false` if `type` is not a settable project unit
+   *   (e.g. `kilometers`, `miles`, `babylon`).
+   *
+   * @examplePrompt Change the project units to millimeters
+   * @examplePrompt Switch this model to feet and inches
+   * @examplePrompt Set the working units to metric
+   * @examplePrompt Make the drawing use centimetres instead of meters
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.units.setType("meters")
+   * ```
+   */
+  public abstract setType(type: PUnitType): PluginApiReturn<boolean>
+
+  /**
+   * Convert a value between two unit types.
+   *
+   * @param value - The numeric value to convert.
+   * @param from - Source unit type.
+   * @param to - Target unit type.
+   * @param degree - (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1.
+   * @returns The converted numeric value.
+   *
+   * @examplePrompt Convert 5 meters to feet and inches
+   * @examplePrompt How many millimetres is 12 feet?
+   * @examplePrompt Change this area from internal units to square metres
+   * @examplePrompt Turn 2500 mm into meters
+   * @examplePrompt Convert a volume value from babylon units to cubic feet
+   *
+   * # Example
+   * ```ts
+   * // 5 meters → internal babylon units
+   * const b = await snaptrude.core.units.convert(5, "meters", "babylon")
+   * // an internal area → square metres
+   * const m2 = await snaptrude.core.units.convert(area, "babylon", "meters", 2)
+   * ```
+   */
+  public abstract convert(
+    value: number,
+    from: PUnitType,
+    to: PUnitType,
+    degree?: number,
+  ): PluginApiReturn<number>
+}
+
+/**
+ * Supported unit types. `babylon` is Snaptrude's internal storage unit; the rest
+ * are real-world units. Mirrors the engine `Converter.UNITS` vocabulary.
+ */
+export const PUnitType = z.enum([
+  "meters",
+  "feet-inches",
+  "inches",
+  "centimeters",
+  "millimeters",
+  "kilometers",
+  "miles",
+  "babylon",
+])
+
+export type PUnitType = z.infer<typeof PUnitType>
+
+/**
+ * Arguments for {@linkcode PluginUnitsApi.setType}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `type` | {@linkcode PUnitType} | The unit type to set as the project unit |
+ */
+export const PluginUnitsSetTypeArgs = z.object({
+  type: PUnitType,
+})
+
+export type PluginUnitsSetTypeArgs = z.infer<typeof PluginUnitsSetTypeArgs>
+
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The numeric value to convert |
+ * | `from` | {@linkcode PUnitType} | Source unit type |
+ * | `to` | {@linkcode PUnitType} | Target unit type |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1 |
+ */
+export const PluginUnitsConvertArgs = z.object({
+  value: z.number(),
+  from: PUnitType,
+  to: PUnitType,
+  degree: z.number().int().min(1).max(3).optional(),
+})
+
+export type PluginUnitsConvertArgs = z.infer<typeof PluginUnitsConvertArgs>

package/src/api/core/user.ts

@@ -1,46 +1,46 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * User locale.
- *
- * Read the viewer's timezone and language — for date/number formatting and
- * localized labels. This is locale only: NO precise geolocation, no IP, no
- * account identity. Accessed via `snaptrude.core.user`.
- */
-export abstract class PluginUserApi {
-  constructor() {}
-
-  /**
-   * Get the viewer's locale: IANA timezone and BCP-47 language tag, resolved
-   * from the browser (`Intl.DateTimeFormat().resolvedOptions().timeZone` and
-   * `navigator.language`). Locale only — no precise location.
-   *
-   * @returns `{ timezone, language }` — e.g. `{ timezone: "Asia/Kolkata", language: "en-US" }`.
-   *
-   * @examplePrompt What timezone is the user in?
-   * @examplePrompt Get the viewer's language for localized labels
-   * @examplePrompt Format the report date in the user's local timezone
-   * @examplePrompt Which locale should I use for this plugin's UI?
-   *
-   * # Example
-   * ```ts
-   * const { timezone, language } = await snaptrude.core.user.getLocale()
-   * ```
-   */
-  public abstract getLocale(): PluginApiReturn<PluginUserLocale>
-}
-
-/**
- * The viewer's locale.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `timezone` | `string` | IANA timezone id (e.g. `"Asia/Kolkata"`) |
- * | `language` | `string` | BCP-47 language tag (e.g. `"en-US"`) |
- */
-export const PluginUserLocale = z.object({
-  timezone: z.string(),
-  language: z.string(),
-})
-export type PluginUserLocale = z.infer<typeof PluginUserLocale>
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * User locale.
+ *
+ * Read the viewer's timezone and language — for date/number formatting and
+ * localized labels. This is locale only: NO precise geolocation, no IP, no
+ * account identity. Accessed via `snaptrude.core.user`.
+ */
+export abstract class PluginUserApi {
+  constructor() {}
+
+  /**
+   * Get the viewer's locale: IANA timezone and BCP-47 language tag, resolved
+   * from the browser (`Intl.DateTimeFormat().resolvedOptions().timeZone` and
+   * `navigator.language`). Locale only — no precise location.
+   *
+   * @returns `{ timezone, language }` — e.g. `{ timezone: "Asia/Kolkata", language: "en-US" }`.
+   *
+   * @examplePrompt What timezone is the user in?
+   * @examplePrompt Get the viewer's language for localized labels
+   * @examplePrompt Format the report date in the user's local timezone
+   * @examplePrompt Which locale should I use for this plugin's UI?
+   *
+   * # Example
+   * ```ts
+   * const { timezone, language } = await snaptrude.core.user.getLocale()
+   * ```
+   */
+  public abstract getLocale(): PluginApiReturn<PluginUserLocale>
+}
+
+/**
+ * The viewer's locale.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `timezone` | `string` | IANA timezone id (e.g. `"Asia/Kolkata"`) |
+ * | `language` | `string` | BCP-47 language tag (e.g. `"en-US"`) |
+ */
+export const PluginUserLocale = z.object({
+  timezone: z.string(),
+  language: z.string(),
+})
+export type PluginUserLocale = z.infer<typeof PluginUserLocale>

package/src/api/core/zoom/index.ts

@@ -1,51 +1,64 @@
-import { PluginApiReturn } from "../../../types"
-
-/**
- * Camera zoom controls.
- *
- * Frame the viewport camera onto scene geometry — mirrors the canvas zoom menu
- * ("Zoom extents" / "Zoom to selection"). Accessed via `snaptrude.core.zoom`.
- */
-export abstract class PluginZoomApi {
-  constructor() {}
-
-  /**
-   * Zoom (fit) the camera to all geometry in the scene — the "zoom extents" action.
-   *
-   * @returns `true` once the camera has been framed to the scene.
-   *
-   * @examplePrompt Zoom out so I can see the whole model
-   * @examplePrompt Fit everything in the view
-   * @examplePrompt Frame the entire building in the viewport
-   * @examplePrompt Do a zoom extents on the canvas
-   * @examplePrompt Show me the full scene
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.zoom.extents()
-   * ```
-   *
-   * @deprecated Use `core.camera.zoomExtents`
-   */
-  public abstract extents(): PluginApiReturn<boolean>
-
-  /**
-   * Zoom (fit) the camera to the current selection.
-   *
-   * @returns `true` if there was a selection to frame; `false` if nothing is
-   *   selected (no-op).
-   *
-   * @examplePrompt Zoom in on what I have selected
-   * @examplePrompt Frame the selected walls in the view
-   * @examplePrompt Focus the camera on my current selection
-   * @examplePrompt Fit the view to the selected room
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.zoom.selection()
-   * ```
-   *
-   * @deprecated Use `core.camera.zoomSelection`
-   */
-  public abstract selection(): PluginApiReturn<boolean>
-}
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Camera zoom controls.
+ *
+ * Frame the viewport camera onto scene geometry — mirrors the canvas zoom menu
+ * ("Zoom extents" / "Zoom to selection"). Accessed via `snaptrude.core.zoom`.
+ *
+ * While Present mode is open these calls set the Design frame a view saved in
+ * Present (`presentation.views.create`) is taken from; they never move the
+ * Present sheet canvas. To pan, zoom or screenshot the Present canvas, use
+ * {@linkcode PluginPresentationCameraApi} (`presentation.camera`).
+ */
+export abstract class PluginZoomApi {
+  constructor() {}
+
+  /**
+   * Zoom (fit) the camera to all geometry in the scene — the "zoom extents" action.
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @returns `true` once the camera has been framed to the scene.
+   *
+   * @examplePrompt Zoom out so I can see the whole model
+   * @examplePrompt Fit everything in the view
+   * @examplePrompt Frame the entire building in the viewport
+   * @examplePrompt Do a zoom extents on the canvas
+   * @examplePrompt Show me the full scene
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.zoom.extents()
+   * ```
+   *
+   * @deprecated Use `core.camera.zoomExtents`
+   */
+  public abstract extents(): PluginApiReturn<boolean>
+
+  /**
+   * Zoom (fit) the camera to the current selection.
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @returns `true` if there was a selection to frame; `false` if nothing is
+   *   selected (no-op).
+   *
+   * @examplePrompt Zoom in on what I have selected
+   * @examplePrompt Frame the selected walls in the view
+   * @examplePrompt Focus the camera on my current selection
+   * @examplePrompt Fit the view to the selected room
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.zoom.selection()
+   * ```
+   *
+   * @deprecated Use `core.camera.zoomSelection`
+   */
+  public abstract selection(): PluginApiReturn<boolean>
+}

package/src/api/design/bim.ts

@@ -0,0 +1,121 @@
+import * as z from "zod"
+import { ComponentHandle } from "../../handles"
+import type { PluginApiReturn } from "../../types"
+import { PluginConstructionType, PluginFamilyValues } from "./catalog"
+import { PluginFamilyBundleSchema } from "./family"
+
+const id = z.string().min(1).max(300)
+const spaces = z.array(ComponentHandle).min(1).max(1000)
+
+/** Read scope. Omit spaces to inspect the active proposal's sketch spaces. */
+export const PluginBimContextArgs = z.object({ spaces: spaces.optional() }).strict()
+export type PluginBimContextArgs = z.infer<typeof PluginBimContextArgs>
+
+/** Directed graph edge. Side A lies along world-up × curve-direction; side B is opposite.
+ * Region IDs are snapshot identifiers, not component handles. Null means no adjacent region.
+ */
+export const PluginBimEdge = z.object({
+  id,
+  startMm: z.tuple([z.number(), z.number(), z.number()]),
+  endMm: z.tuple([z.number(), z.number(), z.number()]),
+  lengthMm: z.number(),
+  heightMm: z.number(),
+  sideA: id.nullable(),
+  sideB: id.nullable(),
+  wall: ComponentHandle.nullable(),
+  supported: z.boolean(),
+})
+export type PluginBimEdge = z.infer<typeof PluginBimEdge>
+
+/** Construction context is detached. Revision covers geometry, room metadata and construction state. */
+export const PluginBimContext = z.object({
+  revision: id,
+  proposalId: id,
+  units: z.literal("mm"),
+  spaces: z.array(z.object({
+    component: ComponentHandle,
+    label: z.string(),
+    storey: z.number(),
+    eligible: z.boolean(),
+    reason: z.string().optional(),
+  })),
+  regions: z.array(z.object({ id, spaces: z.array(ComponentHandle) })),
+  edges: z.array(PluginBimEdge),
+})
+export type PluginBimContext = z.infer<typeof PluginBimContext>
+
+/** Plan-local key selects either an existing construction or a new project-only native recipe.
+ * Bundles use the native DSL's SU/unit-expression rules; values overrides use mm/degrees.
+ */
+export const PluginBimConstruction = z.union([
+  z.object({ key: id, reference: PluginConstructionType }).strict(),
+  z.object({ key: id, bundle: PluginFamilyBundleSchema }).strict(),
+])
+export type PluginBimConstruction = z.infer<typeof PluginBimConstruction>
+
+/** Every unwalled edge in the selected scope needs exactly one assignment.
+ * The first authored layer faces sideA unless reversed. Alignment sets the initial core-centre offset.
+ * Later parameter edits preserve the offset and reject invalid core alignment.
+ */
+export const PluginBimWallAssignment = z.object({
+  edgeId: id,
+  construction: id,
+  values: PluginFamilyValues.optional(),
+  reversed: z.boolean(),
+  alignment: z.literal("coreCentre"),
+}).strict()
+export type PluginBimWallAssignment = z.infer<typeof PluginBimWallAssignment>
+
+export const PluginBimPrepareArgs = z.object({
+  revision: id,
+  spaces,
+  constructions: z.array(PluginBimConstruction).max(1000),
+  walls: z.array(PluginBimWallAssignment).max(10000),
+}).strict()
+export type PluginBimPrepareArgs = z.infer<typeof PluginBimPrepareArgs>
+
+/** Expected recipe/plan failures are diagnostics. No scene or library change occurs during prepare. */
+export const PluginBimPreparation = z.object({
+  ok: z.boolean(),
+  preparationId: id.optional(),
+  diagnostics: z.array(z.object({ path: z.string(), message: z.string() })),
+})
+export type PluginBimPreparation = z.infer<typeof PluginBimPreparation>
+export const PluginBimCreateArgs = z.object({ preparationId: id }).strict()
+
+/** Source IDs identify removed sketch spaces, not live handles. Successful storeys share one undo step.
+ * Failed storeys remain spaces. Cancellation rolls back the whole conversion. Persistence is queued
+ * through normal model commands; this result is not a durable server-save acknowledgement.
+ */
+export const PluginBimResult = z.object({
+  status: z.enum(["created", "partial", "cancelled", "unchanged"]),
+  convertedSpaceIds: z.array(z.string()),
+  created: z.array(ComponentHandle),
+  kept: z.array(z.object({ space: ComponentHandle, reason: z.string() })),
+})
+export type PluginBimResult = z.infer<typeof PluginBimResult>
+
+/** Agent-driven Sketch-to-BIM. Uses PG2 topology; never redraws routes or publishes library families. */
+export abstract class PluginDesignBimApi {
+  /** Read room adjacency and native conversion eligibility in the active proposal.
+   * @param options Optional explicit spaces; filters edges but keeps adjacent room metadata.
+   * @returns Rooms, directed boundaries in mm, eligibility and revision.
+   * @examplePrompt Inspect the rooms on each side of these sketch wall boundaries
+   */
+  abstract getContext(options?: PluginBimContextArgs): PluginApiReturn<PluginBimContext>
+
+  /** Stage a complete wall-construction assignment. A new prepare replaces this plugin's prior plan.
+   * @param plan Exact context revision, selected spaces, constructions and edge assignments.
+   * @returns Diagnostics or an opaque preparation ID, scoped to the caller and current project.
+   * @examplePrompt Validate wall layer assignments before converting sketch rooms to BIM
+   */
+  abstract prepare(plan: PluginBimPrepareArgs): PluginApiReturn<PluginBimPreparation>
+
+  /** Execute native Sketch-to-BIM. Revalidates scope, catalogue access and construction before mutation.
+   * Uses native progress/cancel controls and worker cancellation. Floors/roofs retain project defaults.
+   * @param preparationId ID returned by prepare. Consumed once; stale or foreign IDs throw PRECONDITION_FAILED.
+   * @returns Created component handles and explicit converted/kept outcomes, including partial success.
+   * @examplePrompt Convert these sketch rooms to BIM with wall layers chosen for each room boundary
+   */
+  abstract create(preparationId: string): PluginApiReturn<PluginBimResult>
+}