@snaptrude/plugin-core 0.9.15 → 0.9.16-networks-20261009.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.15",
+  "version": "0.9.16-networks-20261009.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/scripts/generate-manifest.mjs

@@ -115,6 +115,11 @@ export function buildManifest({ includeOptional = false } = {}) {
     const cls = classes.get(className)
     if (!cls) return
 
+    // Domain network namespaces inherit their transport methods. Include these
+    // leaves so discovery exposes the same API as the generic worker proxy.
+    const base = cls.getExtends()?.getExpression().getText()
+    if (base && classes.has(base)) walk(base, pathPrefix)
+
     // Leaf methods on this namespace.
     for (const method of cls.getMethods()) {
       const name = method.getName()

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { Vec3Handle } from "../../../handles"
+import { Vec3Components, Vec3Handle } from "../../../handles"
 
 /**
  * Camera controls.
@@ -10,6 +10,13 @@ import { Vec3Handle } from "../../../handles"
  * canvas view menu and the 2D/3D toggle. Like {@linkcode PluginZoomApi}, these
  * are transient VIEW-STATE changes: they are not model edits, so they are not
  * write-gated and are not undoable. Accessed via `snaptrude.core.camera`.
+ *
+ * Read and set the full camera pose (`getPose`/`setPose`), walk and turn it the
+ * way the arrow keys do (`move`/`rotate`), and read or change the arrow-key
+ * navigation settings (`getNavigationSettings`/`updateNavigationSettings`).
+ * Positions are world coordinates in internal `babylon` units (1 unit =
+ * 0.254 m, Y up); yaw is degrees clockwise from +z seen from above, pitch is
+ * degrees above level.
  */
 export abstract class PluginCameraApi {
   constructor() {}
@@ -184,6 +191,180 @@ export abstract class PluginCameraApi {
    * ```
    */
   public abstract zoomSelection(): PluginApiReturn<boolean>
+
+  /**
+   * Read where the camera is and where it looks: the eye and target positions
+   * (world coordinates, internal `babylon` units), the view direction as yaw
+   * and pitch, the vertical field of view, the projection and the 2D/3D mode.
+   * Paired with {@linkcode PluginCameraApi.setPose}.
+   *
+   * @returns The current {@linkcode PluginCameraPose}.
+   * @throws PRECONDITION_FAILED when there is no active camera.
+   *
+   * @examplePrompt Where is the camera right now?
+   * @examplePrompt Remember this viewpoint so we can come back to it
+   * @examplePrompt Which way is the camera facing?
+   * @examplePrompt How high above the ground is the camera?
+   *
+   * # Example
+   * ```ts
+   * const pose = await snaptrude.core.camera.getPose()
+   * console.log(pose.eye, pose.yawInDegrees, pose.pitchInDegrees)
+   * ```
+   */
+  public abstract getPose(): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Place the camera, optionally easing there over `options.durationInSeconds`,
+   * and resolve once the new view has been drawn, so a capture that follows sees
+   * it without a fixed wait. `pose` is one of:
+   *
+   * - `{ eye, target }`: stand at `eye` looking at `target`, as
+   *   {@linkcode PluginCameraApi.lookFrom} does with handles;
+   * - `{ eye, yawInDegrees, pitchInDegrees }`: stand at `eye` looking along a
+   *   direction;
+   * - `{ standAt, yawInDegrees? }`: stand on the floor, stair, terrain or
+   *   ground at or below `standAt`, at the user's eye height above it (the `I`
+   *   key), facing `yawInDegrees` (the current yaw when omitted).
+   *
+   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
+   * View-state only: not write-gated, not undoable.
+   *
+   * @param pose - Where to put the camera ({@linkcode PluginCameraPoseInput})
+   * @param options - `durationInSeconds`: ease over this long (0 to 10, default 0 jumps)
+   * @returns The camera's {@linkcode PluginCameraPose} once it has arrived.
+   * @throws PRECONDITION_FAILED when there is no active camera, while a
+   *   walkthrough export is recording, or when `standAt` lies below the ground
+   *   with nothing under it. VALIDATION when `eye` and `target` coincide or a
+   *   pitch is beyond ±89°.
+   *
+   * @examplePrompt Stand in the living room at eye level facing the window
+   * @examplePrompt Move the camera to (40, 12, 30) looking at the entrance
+   * @examplePrompt Fly the camera smoothly over to the courtyard
+   * @examplePrompt Put me back at the viewpoint we saved earlier
+   *
+   * # Example
+   * ```ts
+   * const { camera } = snaptrude.core
+   * await camera.setPose({ standAt: { x: 20, y: 0, z: 35 }, yawInDegrees: 90 })
+   * await camera.setPose(
+   *   { eye: { x: 60, y: 25, z: 60 }, target: { x: 0, y: 5, z: 0 } },
+   *   { durationInSeconds: 1.5 },
+   * )
+   * ```
+   */
+  public abstract setPose(
+    pose: PluginCameraPoseInput,
+    options?: PluginCameraSetPoseOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Walk or fly the camera by a displacement in its own frame: `forward` along
+   * the level view direction, `right` to its side and `up` vertically, in
+   * internal `babylon` units. The view direction does not change. With
+   * `options.followsFloor` the camera keeps its height above the floor as it
+   * goes, climbing and descending stairs and ramps the way the arrow keys do.
+   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
+   * View-state only: not write-gated, not undoable.
+   *
+   * @param displacement - {@linkcode PluginCameraMoveDisplacement}; omitted components are 0
+   * @param options - `followsFloor` (default `false`) and `durationInSeconds` (0 to 10, default 0)
+   * @returns The camera's {@linkcode PluginCameraPose} after the move.
+   * @throws PRECONDITION_FAILED when there is no active camera, or while a
+   *   walkthrough export is recording.
+   *
+   * @examplePrompt Walk forward 3 metres
+   * @examplePrompt Step to the right a little
+   * @examplePrompt Walk up the stairs ahead
+   * @examplePrompt Raise the camera by 2 metres
+   *
+   * # Example
+   * ```ts
+   * const metre = 1 / 0.254
+   * await snaptrude.core.camera.move(
+   *   { forward: 3 * metre },
+   *   { followsFloor: true, durationInSeconds: 2 },
+   * )
+   * ```
+   */
+  public abstract move(
+    displacement: PluginCameraMoveDisplacement,
+    options?: PluginCameraMoveOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Turn the camera in place by signed angles: `yawInDegrees` to the right
+   * (clockwise seen from above) and `pitchInDegrees` up. The eye does not move;
+   * the resulting pitch is kept within ±89°. Stops a playing walkthrough and
+   * switches from 2D plan view to 3D first. View-state only: not write-gated,
+   * not undoable.
+   *
+   * @param yawInDegrees - Turn to the right by this much (negative turns left)
+   * @param pitchInDegrees - Tilt up by this much (negative tilts down; default 0)
+   * @param options - `durationInSeconds` (0 to 10, default 0)
+   * @returns The camera's {@linkcode PluginCameraPose} after turning.
+   * @throws PRECONDITION_FAILED when there is no active camera, or while a
+   *   walkthrough export is recording.
+   *
+   * @examplePrompt Turn around
+   * @examplePrompt Look 45 degrees to the left
+   * @examplePrompt Tilt the camera down a bit
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.rotate(180, 0, { durationInSeconds: 1 })
+   * ```
+   */
+  public abstract rotate(
+    yawInDegrees: number,
+    pitchInDegrees?: number,
+    options?: PluginCameraRotateOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Read the arrow-key navigation settings: whether the arrow keys walk the
+   * camera, the eye height used by `setPose`'s `standAt` and by walkthroughs
+   * that follow the floor, the walking speed, and whether walking stops at
+   * walls. Paired with {@linkcode PluginCameraApi.updateNavigationSettings}.
+   *
+   * @returns The current {@linkcode PluginCameraNavigationSettings}.
+   *
+   * @examplePrompt Is arrow-key navigation on?
+   * @examplePrompt What eye height does the camera use?
+   *
+   * # Example
+   * ```ts
+   * const { isKeyboardNavigationEnabled } =
+   *   await snaptrude.core.camera.getNavigationSettings()
+   * ```
+   */
+  public abstract getNavigationSettings(): PluginApiReturn<PluginCameraNavigationSettings>
+
+  /**
+   * Change arrow-key navigation settings; only the fields given change.
+   * `isKeyboardNavigationEnabled` is the user's Project Settings switch and is
+   * saved on this device; the other settings last for the session.
+   * Write-gated: this changes the user's preferences, not just the view.
+   *
+   * @param patch - The settings to change ({@linkcode PluginCameraNavigationSettingsPatch})
+   * @returns The {@linkcode PluginCameraNavigationSettings} after the change.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled.
+   *
+   * @examplePrompt Turn off arrow-key navigation
+   * @examplePrompt Use a 1.6 m eye height
+   * @examplePrompt Make walking stop at walls
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.updateNavigationSettings({
+   *   eyeHeight: 1.6 / 0.254,
+   *   isCollisionEnabled: true,
+   * })
+   * ```
+   */
+  public abstract updateNavigationSettings(
+    patch: PluginCameraNavigationSettingsPatch,
+  ): PluginApiReturn<PluginCameraNavigationSettings>
 }
 
 /**
@@ -266,3 +447,221 @@ export const PluginCameraSetProjectionArgs = z.object({
 export type PluginCameraSetProjectionArgs = z.infer<
   typeof PluginCameraSetProjectionArgs
 >
+
+// Plain {x, y, z} record with finite components (the brepFromRevolution `axisOrigin` pattern).
+const FiniteVec3Components = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  z: z.number().finite(),
+})
+
+/** Pitch is kept off the vertical, where yaw has no meaning. */
+const PitchInDegrees = z.number().finite().min(-89).max(89)
+
+/** How long a camera move eases for; 0 jumps. */
+const DurationInSeconds = z.number().finite().min(0).max(10)
+
+/**
+ * The camera's pose — result of {@linkcode PluginCameraApi.getPose},
+ * {@linkcode PluginCameraApi.setPose}, {@linkcode PluginCameraApi.move} and
+ * {@linkcode PluginCameraApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `eye` | `{ x, y, z }` | Camera position (world, `babylon` units) |
+ * | `target` | `{ x, y, z }` | Point the camera looks at |
+ * | `yawInDegrees` | `number` | View direction, degrees clockwise from +z seen from above (-180 to 180) |
+ * | `pitchInDegrees` | `number` | View direction, degrees above level (negative looks down) |
+ * | `fieldOfViewInDegrees` | `number` | Vertical field of view |
+ * | `projection` | {@linkcode PluginCameraProjection} | `"perspective"` or `"orthographic"` |
+ * | `mode` | {@linkcode PluginCameraMode} | `"2d"` or `"3d"` |
+ */
+export const PluginCameraPose = z.object({
+  eye: Vec3Components,
+  target: Vec3Components,
+  yawInDegrees: z.number(),
+  pitchInDegrees: z.number(),
+  fieldOfViewInDegrees: z.number(),
+  projection: PluginCameraProjection,
+  mode: PluginCameraMode,
+})
+export type PluginCameraPose = z.infer<typeof PluginCameraPose>
+
+/**
+ * Where {@linkcode PluginCameraApi.setPose} puts the camera — exactly one of:
+ *
+ * | Shape | Meaning |
+ * |---|---|
+ * | `{ eye, target }` | Stand at `eye` looking at `target` |
+ * | `{ eye, yawInDegrees, pitchInDegrees }` | Stand at `eye` looking along a direction (pitch within ±89°) |
+ * | `{ standAt, yawInDegrees? }` | Stand at eye height on the floor, stair, terrain or ground at or below `standAt`, facing `yawInDegrees` (default: current yaw) |
+ *
+ * Points are plain `{ x, y, z }` world coordinates in `babylon` units.
+ */
+export const PluginCameraPoseInput = z.union([
+  z
+    .object({ eye: FiniteVec3Components, target: FiniteVec3Components })
+    .strict(),
+  z
+    .object({
+      eye: FiniteVec3Components,
+      yawInDegrees: z.number().finite(),
+      pitchInDegrees: PitchInDegrees,
+    })
+    .strict(),
+  z
+    .object({
+      standAt: FiniteVec3Components,
+      yawInDegrees: z.number().finite().optional(),
+    })
+    .strict(),
+])
+export type PluginCameraPoseInput = z.infer<typeof PluginCameraPoseInput>
+
+/**
+ * Options for {@linkcode PluginCameraApi.setPose}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `durationInSeconds` | `number \| undefined` | Ease to the pose over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraSetPoseOptions = z
+  .object({ durationInSeconds: DurationInSeconds.optional() })
+  .strict()
+export type PluginCameraSetPoseOptions = z.infer<
+  typeof PluginCameraSetPoseOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.setPose}.
+ */
+export const PluginCameraSetPoseArgs = z.object({
+  pose: PluginCameraPoseInput,
+  options: PluginCameraSetPoseOptions.optional(),
+})
+export type PluginCameraSetPoseArgs = z.infer<typeof PluginCameraSetPoseArgs>
+
+/**
+ * A displacement in the camera's own frame, for {@linkcode PluginCameraApi.move}
+ * (`babylon` units; omitted components are 0).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `forward` | `number \| undefined` | Along the level view direction (negative walks back) |
+ * | `right` | `number \| undefined` | To the camera's right (negative steps left) |
+ * | `up` | `number \| undefined` | Vertically (negative descends) |
+ */
+export const PluginCameraMoveDisplacement = z
+  .object({
+    forward: z.number().finite().optional(),
+    right: z.number().finite().optional(),
+    up: z.number().finite().optional(),
+  })
+  .strict()
+export type PluginCameraMoveDisplacement = z.infer<
+  typeof PluginCameraMoveDisplacement
+>
+
+/**
+ * Options for {@linkcode PluginCameraApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `followsFloor` | `boolean \| undefined` | Keep the height above the floor, climbing stairs and ramps (default `false`) |
+ * | `durationInSeconds` | `number \| undefined` | Walk over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraMoveOptions = z
+  .object({
+    followsFloor: z.boolean().optional(),
+    durationInSeconds: DurationInSeconds.optional(),
+  })
+  .strict()
+export type PluginCameraMoveOptions = z.infer<typeof PluginCameraMoveOptions>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.move}.
+ */
+export const PluginCameraMoveArgs = z.object({
+  displacement: PluginCameraMoveDisplacement,
+  options: PluginCameraMoveOptions.optional(),
+})
+export type PluginCameraMoveArgs = z.infer<typeof PluginCameraMoveArgs>
+
+/**
+ * Options for {@linkcode PluginCameraApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `durationInSeconds` | `number \| undefined` | Turn over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraRotateOptions = z
+  .object({ durationInSeconds: DurationInSeconds.optional() })
+  .strict()
+export type PluginCameraRotateOptions = z.infer<
+  typeof PluginCameraRotateOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.rotate}.
+ */
+export const PluginCameraRotateArgs = z.object({
+  yawInDegrees: z.number().finite(),
+  pitchInDegrees: z.number().finite().optional(),
+  options: PluginCameraRotateOptions.optional(),
+})
+export type PluginCameraRotateArgs = z.infer<typeof PluginCameraRotateArgs>
+
+/**
+ * How fast the arrow keys walk: the Slow / Normal / Fast navigation setting.
+ */
+export const PluginCameraWalkSpeed = z.enum(["slow", "normal", "fast"])
+export type PluginCameraWalkSpeed = z.infer<typeof PluginCameraWalkSpeed>
+
+/**
+ * The arrow-key navigation settings — result of
+ * {@linkcode PluginCameraApi.getNavigationSettings} and
+ * {@linkcode PluginCameraApi.updateNavigationSettings}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `isKeyboardNavigationEnabled` | `boolean` | Whether the arrow keys walk the camera (Project Settings) |
+ * | `eyeHeight` | `number` | Eye height above the floor, `babylon` units |
+ * | `walkSpeed` | {@linkcode PluginCameraWalkSpeed} | Arrow-key walking speed |
+ * | `isCollisionEnabled` | `boolean` | Whether walking stops at walls |
+ */
+export const PluginCameraNavigationSettings = z.object({
+  isKeyboardNavigationEnabled: z.boolean(),
+  eyeHeight: z.number(),
+  walkSpeed: PluginCameraWalkSpeed,
+  isCollisionEnabled: z.boolean(),
+})
+export type PluginCameraNavigationSettings = z.infer<
+  typeof PluginCameraNavigationSettings
+>
+
+/**
+ * The settings to change in {@linkcode PluginCameraApi.updateNavigationSettings};
+ * omitted fields keep their value. `eyeHeight` is in `babylon` units, between
+ * 0.8 m and 2.5 m (3.15 to 9.84 units).
+ */
+export const PluginCameraNavigationSettingsPatch = z
+  .object({
+    isKeyboardNavigationEnabled: z.boolean().optional(),
+    eyeHeight: z.number().finite().min(3.15).max(9.84).optional(),
+    walkSpeed: PluginCameraWalkSpeed.optional(),
+    isCollisionEnabled: z.boolean().optional(),
+  })
+  .strict()
+export type PluginCameraNavigationSettingsPatch = z.infer<
+  typeof PluginCameraNavigationSettingsPatch
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.updateNavigationSettings}.
+ */
+export const PluginCameraUpdateNavigationSettingsArgs = z.object({
+  patch: PluginCameraNavigationSettingsPatch,
+})
+export type PluginCameraUpdateNavigationSettingsArgs = z.infer<
+  typeof PluginCameraUpdateNavigationSettingsArgs
+>

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>
+}

package/src/api/design/catalog.ts

@@ -0,0 +1,128 @@
+import * as z from "zod"
+import { ContourHandle, LineHandle, Vec3Handle } from "../../handles"
+import type { PluginApiReturn } from "../../types"
+import { PluginFamilyDefinitionParameter, PluginFamilyBundleSchema } from "./family"
+import { NetworkFamilyContract } from "./networks"
+
+/** Exact saved family identity. A label or a selected Draw type is not an identity. */
+export const PluginSavedFamilyReference = z
+  .object({
+    id: z.string().min(1),
+    version: z.number().int().positive(),
+  })
+  .strict()
+export type PluginSavedFamilyReference = z.infer<
+  typeof PluginSavedFamilyReference
+>
+
+/** Public overrides: physical lengths use mm, angles use degrees. Omitted values retain defaults. */
+export const PluginFamilyValues = z.record(
+  z.string(),
+  z.union([z.number().finite(), z.string(), z.boolean()]),
+)
+export type PluginFamilyValues = z.infer<typeof PluginFamilyValues>
+
+/** Native construction uses a saved family or a project assembly token from the catalogue. */
+export const PluginConstructionType = z.union([
+  PluginSavedFamilyReference,
+  z.string().min(1),
+])
+export type PluginConstructionType = z.infer<typeof PluginConstructionType>
+
+/** Family owns its layers/section. Geometry owns the footprint/axis; it is never a values override. */
+export const PluginFamilyPlacement = z
+  .object({
+    type: PluginConstructionType,
+    values: PluginFamilyValues.optional(),
+  })
+  .strict()
+export type PluginFamilyPlacement = z.infer<typeof PluginFamilyPlacement>
+
+/** Sparse native family edit. Omitted type keeps the component's exact saved reference. */
+export const PluginFamilyUpdates = PluginFamilyPlacement.partial().refine(
+  (updates) => updates.type !== undefined || updates.values !== undefined,
+  { message: "Supply a type or parameter values" },
+)
+export type PluginFamilyUpdates = z.infer<typeof PluginFamilyUpdates>
+
+export const PluginFamilyFloorOptions = PluginFamilyPlacement.extend({
+  position: Vec3Handle.optional(),
+})
+export type PluginFamilyFloorOptions = z.infer<typeof PluginFamilyFloorOptions>
+export const PluginFamilySlabOptions = PluginFamilyPlacement.extend({
+  direction: z.enum(["up", "down"]).optional(),
+})
+export type PluginFamilySlabOptions = z.infer<typeof PluginFamilySlabOptions>
+export const PluginFamilyCeilingOptions = PluginFamilyPlacement.extend({
+  heightFromFloor: z.number().finite().optional(),
+})
+export type PluginFamilyCeilingOptions = z.infer<
+  typeof PluginFamilyCeilingOptions
+>
+export const PluginFamilyContourArgs = z.object({
+  contour: ContourHandle,
+  options: PluginFamilyPlacement,
+})
+export const PluginFamilyAxisArgs = z.object({
+  axis: LineHandle,
+  options: PluginFamilyPlacement,
+})
+
+/** Inventory includes architectural recipes, ordinary PCs, and the existing placement libraries. */
+export const PluginCatalogKind = z.enum([
+  "wall",
+  "floor",
+  "slab",
+  "roof",
+  "ceiling",
+  "beam",
+  "column",
+  "component",
+  "door",
+  "window",
+  "furniture",
+])
+export type PluginCatalogKind = z.infer<typeof PluginCatalogKind>
+export const PluginCatalogReference = z.union([
+  PluginSavedFamilyReference,
+  // Project assemblies retain kind:name; asset tokens retain the underlying library identity.
+  z.string().min(1),
+])
+export type PluginCatalogReference = z.infer<typeof PluginCatalogReference>
+
+/** Read-only capability record. Availability is checked again on every mutation. */
+export const PluginCatalogEntry = z.object({
+  reference: PluginCatalogReference,
+  label: z.string(),
+  kind: PluginCatalogKind,
+  source: z.enum(["native", "revit", "project", "asset"]),
+  createMethods: z.array(z.string()),
+  updateMethods: z.array(z.string()),
+  requirements: z.array(z.string()),
+  unsupportedReason: z.string().optional(),
+  parameters: z.array(PluginFamilyDefinitionParameter).optional(),
+  /** Parameter keys owned by native placement geometry, never accepted as values overrides. */
+  geometryParameters: z.array(z.string()),
+  network: NetworkFamilyContract.optional(),
+  /** get() includes the native wall recipe without opening a Family Studio draft.
+   * Bare recipe lengths use SU; parameter metadata and public values overrides use mm.
+   */
+  construction: PluginFamilyBundleSchema.optional(),
+})
+export type PluginCatalogEntry = z.infer<typeof PluginCatalogEntry>
+export const PluginCatalogListArgs = z.object({
+  kind: PluginCatalogKind.optional(),
+})
+export const PluginCatalogGetArgs = z.object({
+  reference: PluginCatalogReference,
+})
+
+/** Shared read surface over existing libraries. Does not publish, register, or place definitions. */
+export abstract class PluginDesignCatalogApi {
+  /** @param kind Optional element filter. @returns Accessible entries and their supported API paths. */
+  abstract list(kind?: PluginCatalogKind): PluginApiReturn<PluginCatalogEntry[]>
+  /** @param reference Exact reference from list. @returns The current entry, or null when unavailable. */
+  abstract get(
+    reference: PluginCatalogReference,
+  ): PluginApiReturn<PluginCatalogEntry | null>
+}