@snaptrude/plugin-core 0.0.0-dev-20260908074328 → 0.0.0-dev-20260921132444

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.0.0-dev-20260908074328",
+  "version": "0.0.0-dev-20260921132444",
   "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/core/mode/index.ts

@@ -29,10 +29,14 @@ export interface PluginCoreModeSetResult {
  * Not to be confused with the viewport's 2D/3D camera mode
  * (`core.camera.setMode`) or saved presentation views (`presentation.views`).
  *
- * `set` covers `design`, `bim`, and `present` — in-page switches.
- * `program` opens in its own browser tab in the product, which a plugin worker
- * cannot do, so `set("program")` fails with `PRECONDITION_FAILED`; `get()`
- * still reports `"program"` for code running in the Program tab.
+ * `set` covers `design`, `bim`, and `present` — in-page switches — and
+ * `program`, which opens the Program tab (a paired browser window) through the
+ * same path as the top bar's Program button. Because the open happens outside a
+ * user gesture the browser may block the pop-up; the editor then shows its
+ * "Allow pop-up to continue" modal and the tab opens when the user confirms.
+ * `get()` reports `"program"` only for code running in the Program tab itself.
+ * Prefer {@linkcode PluginWorkspaceApi.openProgramMode} when you need to know
+ * the tab is ready before calling `program.spreadsheet.*`.
  */
 export abstract class PluginCoreModeApi {
   constructor() {}
@@ -74,16 +78,24 @@ export abstract class PluginCoreModeApi {
    * Switch the editor to another application mode — the same action as
    * clicking that tab in the top menu bar.
    *
-   * Supported: `"design"`, `"bim"`, `"present"`. Switching to
-   * `"program"` is rejected with `PRECONDITION_FAILED` (the Program surface
-   * opens in its own browser tab in the product; a plugin cannot open one).
+   * `"design"`, `"bim"` and `"present"` switch in place. `"program"` opens
+   * the Program tab (a paired browser window) exactly as the top bar's Program
+   * button does, and resolves once that tab has connected to the editor (up to
+   * ~90s — the browser may block the pop-up, in which case the editor shows an
+   * "Allow pop-up to continue" modal and waits for the user to confirm).
+   * Idempotent when the Program tab is already open. Note `get()` in the model
+   * tab keeps reporting the model tab's own mode afterwards; the Program tab is
+   * a separate window.
    *
    * @param mode - Target mode token from {@linkcode PluginAppMode}
    * @returns The committed `{ mode }` after the switch.
+   * @throws `PRECONDITION_FAILED` for `"program"` when the user dismisses the
+   *   pop-up modal or the tab does not connect within the timeout.
    *
    * @examplePrompt Switch to present mode
    * @examplePrompt Open BIM mode
    * @examplePrompt Go back to design mode
+   * @examplePrompt Open program mode
    *
    * # Example
    * ```ts

package/src/api/core/tags.ts

@@ -163,6 +163,40 @@ export abstract class PluginCoreTagsApi {
     componentId: ComponentHandle,
   ): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>
 
+  /**
+   * List the tags carried by many components in one call.
+   *
+   * The plural of {@linkcode PluginCoreTagsApi.listForComponent}: pass
+   * `componentIds` to read specific components (unknown ids are skipped), or
+   * omit it to read **every** taggable component (Mass/Floor space) in the
+   * project. Each entry carries the component id and its tags — one per tagged
+   * category, with the tag's `color` — so a plugin can color every space by a
+   * chosen category's tag in a single round-trip.
+   *
+   * @param componentIds - Optional `Component.id`s to read; omit for all spaces.
+   * @returns A {@linkcode PluginCoreTagsListForComponentsResult} with a
+   *   `components` array, one entry per component (in input order when
+   *   `componentIds` is given).
+   *
+   * @performance One round-trip for any number of components — use this instead of a `listForComponent` loop.
+   *
+   * @examplePrompt Get the tags of every space with their colors
+   * @examplePrompt List the tags on all rooms so I can color them by Occupancy
+   * @examplePrompt Which tag does each selected space carry?
+   *
+   * # Example
+   * ```ts
+   * const { components } = await snaptrude.core.tags.listForComponents()
+   * for (const c of components) {
+   *   const occupancy = c.tags.find((t) => t.categoryName === "Occupancy")
+   *   if (occupancy) paint(c.componentId, occupancy.color)
+   * }
+   * ```
+   */
+  public abstract listForComponents(
+    componentIds?: ComponentHandle[],
+  ): PluginApiReturn<PluginCoreTagsListForComponentsResult>
+
   /**
    * List the components carrying a given tag or category.
    *
@@ -588,6 +622,48 @@ export type PluginCoreTagsGetTagsForComponentResult = z.infer<
   typeof PluginCoreTagsGetTagsForComponentResult
 >
 
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]?` | Components to read; omit for every taggable component |
+ */
+export const PluginCoreTagsListForComponentsArgs = z.object({
+  componentIds: z.array(ComponentHandle).optional(),
+})
+export type PluginCoreTagsListForComponentsArgs = z.infer<
+  typeof PluginCoreTagsListForComponentsArgs
+>
+
+/**
+ * One component's tags, for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The component's id |
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | Its tags, one per tagged category (empty when none) |
+ */
+export const PluginCoreComponentTags = z.object({
+  componentId: ComponentHandle,
+  tags: z.array(PluginCoreComponentTag),
+})
+export type PluginCoreComponentTags = z.infer<typeof PluginCoreComponentTags>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode PluginCoreComponentTags}`[]` | One entry per component |
+ */
+export const PluginCoreTagsListForComponentsResult = z.object({
+  components: z.array(PluginCoreComponentTags),
+})
+export type PluginCoreTagsListForComponentsResult = z.infer<
+  typeof PluginCoreTagsListForComponentsResult
+>
+
 /**
  * Arguments for {@linkcode PluginCoreTagsApi.listComponents}. Provide exactly one
  * of `tagId`, `categoryId`. `untagged` is valid only with `categoryId`.

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

package/src/api/design/create/grids.ts

@@ -0,0 +1,137 @@
+import * as z from "zod"
+import { ComponentHandle, CurveHandle, Vec3Handle } from "../../../handles"
+
+// ---------------------------------------------------------------------------
+// Shared grid style vocabulary
+// ---------------------------------------------------------------------------
+
+/**
+ * Grid line style (mirrors the engine `LineMode` values verbatim — the same
+ * vocabulary as {@linkcode PluginReferenceLineStyle}).
+ */
+export const PluginGridLineStyle = z.enum(["SOLID", "DASHED", "DOT_DASH"])
+export type PluginGridLineStyle = z.infer<typeof PluginGridLineStyle>
+
+/**
+ * Optional visual styling shared by every grid creator (and reused as the
+ * patch shape by `design.update.grid`). All fields optional; engine defaults
+ * apply when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginGridLineStyle}? | Line style |
+ * | `weight` | `number`? | Line weight (> 0) |
+ * | `color` | `string`? | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean`? | Show the start-end tag bubble |
+ * | `showEnd` | `boolean`? | Show the end-end tag bubble |
+ */
+export const PluginGridStyleOptions = z.object({
+  style: PluginGridLineStyle.optional(),
+  weight: z.number().positive().optional(),
+  color: z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/, "color must be a #rrggbb hex string")
+    .optional(),
+  showStart: z.boolean().optional(),
+  showEnd: z.boolean().optional(),
+})
+export type PluginGridStyleOptions = z.infer<typeof PluginGridStyleOptions>
+
+// ---------------------------------------------------------------------------
+// create.grid — free rectangular grid
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.grid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `linesX` | `number` | Line count of the first family (integer ≥ 1) |
+ * | `linesY` | `number` | Line count of the second family (integer ≥ 1) |
+ * | `spacingX` | `number` | Spacing of the first family (Snaptrude units, > 0) |
+ * | `spacingY` | `number` | Spacing of the second family (Snaptrude units, > 0) |
+ * | `angle` | `number`? | Rotation in degrees, CCW about +Y (default 0) |
+ * | `center` | {@linkcode Vec3Handle}? | Placement centre; defaults to the native viewport-centre behavior |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridArgs = z
+  .object({
+    linesX: z.number().int().min(1),
+    linesY: z.number().int().min(1),
+    spacingX: z.number().positive().finite(),
+    spacingY: z.number().positive().finite(),
+    angle: z.number().finite().optional(),
+    center: Vec3Handle.optional(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridArgs = z.infer<typeof PluginDesignCreateGridArgs>
+
+// ---------------------------------------------------------------------------
+// create.gridFromCurve — single-curve grid
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.gridFromCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The grid line's geometry — a line or arc (circles are rejected) |
+ * | `tag` | `string`? | The line's grid tag (defaults to the draw tool's next tag) |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridFromCurveArgs = z
+  .object({
+    curve: CurveHandle,
+    tag: z.string().min(1).optional(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridFromCurveArgs = z.infer<
+  typeof PluginDesignCreateGridFromCurveArgs
+>
+
+// ---------------------------------------------------------------------------
+// create.gridsFromMasses — fitted grids
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.gridsFromMasses}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `masses` | {@linkcode ComponentHandle}`[]` | Masses whose footprints seat the grids |
+ * | `spacingX` | `number` | First-family spacing (Snaptrude units, > 0) |
+ * | `spacingY` | `number` | Second-family spacing (Snaptrude units, > 0) |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridsFromMassesArgs = z
+  .object({
+    masses: z.array(ComponentHandle).min(1),
+    spacingX: z.number().positive().finite(),
+    spacingY: z.number().positive().finite(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridsFromMassesArgs = z.infer<
+  typeof PluginDesignCreateGridsFromMassesArgs
+>
+
+// ---------------------------------------------------------------------------
+// create.columnsFromGrids — columns at line intersections
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.columnsFromGrids}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `grids` | {@linkcode ComponentHandle}`[]` | Grid groups whose line intersections seat the columns |
+ * | `width` | `number` | Column width (Snaptrude units, > 0) |
+ * | `depth` | `number` | Column depth (Snaptrude units, > 0) |
+ */
+export const PluginDesignCreateColumnsFromGridsArgs = z.object({
+  grids: z.array(ComponentHandle).min(1),
+  width: z.number().positive().finite(),
+  depth: z.number().positive().finite(),
+})
+export type PluginDesignCreateColumnsFromGridsArgs = z.infer<
+  typeof PluginDesignCreateColumnsFromGridsArgs
+>