@snaptrude/plugin-core 0.9.6 → 0.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/core/io/import/index.ts

@@ -183,7 +183,10 @@ export abstract class PluginCoreIoImportApi {
    * if (cad) console.log("DWG imported as CAD underlay:", cad)
    * ```
    */
-  public abstract dwg(source: string, storey?: number): PluginApiReturn<ImportJobHandle>
+  public abstract dwg(
+    source: string,
+    storey?: number,
+  ): PluginApiReturn<ImportJobHandle>
 
   /**
    * Sketch a CAD underlay from **already-parsed CAD JSON** — synchronous, with no
@@ -214,7 +217,10 @@ export abstract class PluginCoreIoImportApi {
    * )
    * ```
    */
-  public abstract cadJson(cad: CadJsonInput, storey?: number): PluginApiReturn<UnderlayHandle>
+  public abstract cadJson(
+    cad: CadJsonInput,
+    storey?: number,
+  ): PluginApiReturn<UnderlayHandle>
 
   /**
    * Import a **3D model** file and place it in the scene as a component.
@@ -239,7 +245,9 @@ export abstract class PluginCoreIoImportApi {
    * @returns the placed {@linkcode ComponentHandle}.
    * @throws if writes are disabled, the source can't be loaded, the format is
    *   unsupported, conversion/placement fails, or the converted model cannot be
-   *   found in the library after upload.
+   *   found in the library after upload; `PRECONDITION_FAILED`
+   *   (`details.engineCode: "TOOL_ACTIVE"`) while the interactive furniture tool is
+   *   active — finish or cancel it first.
    *
    * @examplePrompt Import this SketchUp model onto storey 1
    * @examplePrompt Bring in this OBJ file and place it at the origin

package/src/api/design/create/bulk-items.ts

@@ -0,0 +1,186 @@
+import * as z from "zod"
+import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
+import { PluginOpeningBaseOptions } from "./opening-fields"
+
+/**
+ * Maximum items per bulk `design.create.*` call. A bounded request keeps
+ * validation, command capture and rollback work finite; split a larger import
+ * into separate awaited batches, each with its own undo entry.
+ */
+export const PLUGIN_CREATE_BATCH_LIMIT = 1000
+
+// ---------------------------------------------------------------------------
+// wallRuns
+// ---------------------------------------------------------------------------
+
+/**
+ * One wall run to create via {@linkcode PluginDesignCreateApi.wallRuns} — the
+ * same inputs as {@linkcode PluginDesignCreateApi.walls}, one run per item.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
+ * | `height` | `number`? | Wall height (Snaptrude units, > 0; default engine default) |
+ * | `thickness` | `number`? | Wall thickness (Snaptrude units, > 0; default: `wallType`'s total layer thickness when given, else engine default) |
+ * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
+ * | `storey` | `number`? (int) | Target storey (must exist) — the run's walls are assigned + lifted to its base in the same undo entry (default: geometry-derived) |
+ */
+export const PluginCreateWallRunItem = z.object({
+  profile: ProfileHandle,
+  height: z.number().optional(),
+  thickness: z.number().optional(),
+  wallType: z.string().min(1).optional(),
+  storey: z.number().int().optional(),
+})
+export type PluginCreateWallRunItem = z.infer<typeof PluginCreateWallRunItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.wallRuns} (1…1000). */
+export const PluginCreateWallRunItems = z
+  .array(PluginCreateWallRunItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWallRunItems = z.infer<typeof PluginCreateWallRunItems>
+
+// ---------------------------------------------------------------------------
+// floors
+// ---------------------------------------------------------------------------
+
+/**
+ * One floor to create via {@linkcode PluginDesignCreateApi.floors} — the same
+ * footprint-extrude inputs as {@linkcode PluginDesignCreateApi.floor}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer profile + holes) |
+ * | `thickness` | `number` | Floor thickness (Snaptrude units, > 0) |
+ * | `position` | {@linkcode Vec3Handle}? | Offset from origin (default origin) |
+ */
+export const PluginCreateFloorItem = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+  position: Vec3Handle.optional(),
+})
+export type PluginCreateFloorItem = z.infer<typeof PluginCreateFloorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.floors} (1…1000). */
+export const PluginCreateFloorItems = z
+  .array(PluginCreateFloorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
+
+// ---------------------------------------------------------------------------
+// doors / windows
+// ---------------------------------------------------------------------------
+
+/**
+ * One door to place via {@linkcode PluginDesignCreateApi.doors} — the same
+ * fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}, so the
+ * size overrides singular {@linkcode PluginDesignCreateApi.door} lacks are
+ * available per item. `facing` and `hinge` are WORLD POINTS, not directions:
+ * `facing` on the side of the wall the door swings open to, `hinge` near the
+ * jamb it is hinged on. Rejects unknown fields.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
+ * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
+ */
+export const PluginCreateDoorItem = z
+  .object({ ...PluginOpeningBaseOptions })
+  .strict()
+export type PluginCreateDoorItem = z.infer<typeof PluginCreateDoorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.doors} (1…1000). */
+export const PluginCreateDoorItems = z
+  .array(PluginCreateDoorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
+
+/**
+ * One window to place via {@linkcode PluginDesignCreateApi.windows} — the same
+ * fields as a `"window"` {@linkcode PluginDesignCreateOpeningOptions}.
+ * `sillHeight` is a nonnegative Snaptrude-unit distance from the host wall's
+ * base to the BOTTOM of the window, not to its center. `facing` and `hinge`
+ * are WORLD POINTS, not directions: `facing` on the side of the wall the
+ * window opens to, `hinge` near the jamb it is hinged on. Rejects unknown
+ * fields.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the window opens to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
+ * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
+ * | `sillHeight` | `number`? | Wall base to window bottom (Snaptrude units, ≥ 0; default the catalog item's) |
+ */
+export const PluginCreateWindowItem = z
+  .object({
+    ...PluginOpeningBaseOptions,
+    sillHeight: z.number().finite().nonnegative().optional(),
+  })
+  .strict()
+export type PluginCreateWindowItem = z.infer<typeof PluginCreateWindowItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.windows} (1…1000). */
+export const PluginCreateWindowItems = z
+  .array(PluginCreateWindowItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWindowItems = z.infer<typeof PluginCreateWindowItems>
+
+// ---------------------------------------------------------------------------
+// furnitureItems
+// ---------------------------------------------------------------------------
+
+/**
+ * One furniture instance to place via
+ * {@linkcode PluginDesignCreateApi.furnitureItems} — the same inputs as
+ * {@linkcode PluginDesignCreateApi.furniture} minus `createNewSourceMesh`: in a
+ * batch the host owns source-mesh persistence (a source is recorded once per
+ * call, however many items reuse it).
+ *
+ * `position.y` is the REST elevation: the item is grounded so its bounding-box
+ * base sits exactly at `position.y` (the same surface-flush contract as
+ * interactive drag-drop) — pass the floor/storey elevation to stand furniture
+ * on it; never add half the item's height yourself.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `position` | {@linkcode Vec3Handle} | Absolute world placement point (`y` = rest elevation) |
+ * | `label` | `string`? | Instance name and readable label (default auto `${name}Ins${n}`) |
+ * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
+ */
+export const PluginCreateFurnitureItem = z.object({
+  catalogId: z.string().min(1),
+  position: Vec3Handle,
+  label: z.string().optional(),
+  angleInDegrees: z.number().optional(),
+})
+export type PluginCreateFurnitureItem = z.infer<
+  typeof PluginCreateFurnitureItem
+>
+
+/**
+ * The `items` array of {@linkcode PluginDesignCreateApi.furnitureItems}
+ * (1…1000).
+ */
+export const PluginCreateFurnitureItems = z
+  .array(PluginCreateFurnitureItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateFurnitureItems = z.infer<
+  typeof PluginCreateFurnitureItems
+>