@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827194031

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

@@ -52,6 +52,9 @@ export abstract class PluginDesignDeleteApi {
    * @examplePrompt Delete all the furniture I picked
    * @examplePrompt Remove the door and window I just created
    *
+   * @performance Array delete — pass every target in one call (one host round-trip). There is
+   *   no per-item delete; collect the whole set and never loop this per entity.
+   *
    * # Example
    * ```ts
    * // Hard-delete every furniture item on storey 2 (a single undo entry)

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

@@ -12,6 +12,13 @@ import { PluginDesignChangeResult } from "../lock"
  * mesh reflection state. `mirror` reflects the door across an axis (undoable, one
  * command); `setType` is intentionally absent (the engine has no in-place re-type —
  * it would require delete+recreate).
+ *
+ * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
+ * browse the placeable door library — plain value records keyed by a library id
+ * (team `_id` or general `fullName`), NOT handles — and feed `design.create.door`.
+ * 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.windows`.
  */
 export abstract class PluginDesignDoorsApi {
   constructor() {}
@@ -98,6 +105,30 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract getHeight(door: ComponentHandle): PluginApiReturn<number | null>
 
+  /**
+   * Get a door's full dimensions in one call — width along the wall, vertical
+   * height, and thickness through the wall — measured in the door's local
+   * oriented space. Parity with {@linkcode PluginDesignWindowsApi.getDimensions}.
+   *
+   * @param door The door to query
+   * @returns The dimensions, or `null`
+   *
+   * @examplePrompt What are the dimensions of this door?
+   * @examplePrompt How big is the selected door?
+   * @examplePrompt Give me the width, height and depth of this door
+   * @examplePrompt Measure the entrance door including its thickness through the wall
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const dims = await snaptrude.design.doors.getDimensions(door)
+   * if (dims) console.log(dims.width, dims.height, dims.thickness)
+   * ```
+   */
+  public abstract getDimensions(
+    door: ComponentHandle
+  ): PluginApiReturn<PluginDoorDimensions | null>
+
   /**
    * Get the floor a door is hosted on — the storey/level component that
    * supports the door.
@@ -224,6 +255,90 @@ export abstract class PluginDesignDoorsApi {
     doors: ComponentHandle[],
     height: number
   ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * List the door catalog **groups** — the placement families (Swing, Sliding,
+   * Folding, Pivot, …), built-in groups merged with any team-custom types.
+   *
+   * @returns The groups as {@linkcode PluginObjectCatalogGroup}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What kinds of doors can I place?
+   * @examplePrompt List the door groups in the catalog
+   * @examplePrompt Show me the door families available in this project
+   * @examplePrompt Which door types does this project support?
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.doors.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
+  /**
+   * List the placeable door catalog (team + general libraries), optionally
+   * restricted to one group by its `dbType` token.
+   *
+   * @param group Restrict to one group's `dbType` (optional; e.g. `"singleDoor"`)
+   * @returns The catalog as {@linkcode PluginObjectCatalogItem}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What doors can I place in this project?
+   * @examplePrompt List every door in the library
+   * @examplePrompt Show me the sliding doors I can add
+   * @examplePrompt Browse the door catalog
+   *
+   * # Example
+   * ```ts
+   * const [group] = await snaptrude.design.doors.listCatalogGroups()
+   * const items = await snaptrude.design.doors.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 door 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 door from the library
+   * @examplePrompt Look up the catalog entry for this door id
+   * @examplePrompt What is the cost of this door item?
+   * @examplePrompt Show me the family name of this door in the catalog
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.doors.listCatalog()
+   * const item = await snaptrude.design.doors.getCatalogItem(entry.id)
+   * if (item) console.log(item.name, item.source, item.dbType)
+   * ```
+   */
+  public abstract getCatalogItem(
+    id: string
+  ): PluginApiReturn<PluginObjectCatalogItem | null>
+
+  /**
+   * Test whether a door catalog item exists for the given library id.
+   *
+   * @param id The catalog library id
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Is this door still in the library?
+   * @examplePrompt Check whether a door catalog item with this id exists
+   * @examplePrompt Does my team library have this door?
+   * @examplePrompt Verify the door is available before placing it
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.doors.listCatalog()
+   * const stillAvailable = await snaptrude.design.doors.exists(entry.id)
+   * console.log(stillAvailable ? "safe to place" : "removed from library")
+   * ```
+   */
+  public abstract exists(id: string): PluginApiReturn<boolean>
 }
 
 /**
@@ -238,6 +353,22 @@ export const PluginDesignDoorArgs = z.object({
 })
 export type PluginDesignDoorArgs = z.infer<typeof PluginDesignDoorArgs>
 
+/**
+ * A door's dimensions (engine units), symmetric with {@linkcode PluginWindowDimensions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `width` | `number` | Along the wall |
+ * | `height` | `number` | Vertical |
+ * | `thickness` | `number` | Through the wall (engine `length` axis) |
+ */
+export const PluginDoorDimensions = z.object({
+  width: z.number(),
+  height: z.number(),
+  thickness: z.number(),
+})
+export type PluginDoorDimensions = z.infer<typeof PluginDoorDimensions>
+
 /** Mirror axis — tokens mirror the engine `FlipDirection` verbatim (§6.1). */
 export const PluginMirrorAxis = z.enum(["x", "y", "z"])
 export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
@@ -283,3 +414,80 @@ export const PluginDesignDoorSetHeightArgs = z.object({
   height: z.number(),
 })
 export type PluginDesignDoorSetHeightArgs = z.infer<typeof PluginDesignDoorSetHeightArgs>
+
+// ---------------------------------------------------------------------------
+// catalog (shared by doors + windows)
+// ---------------------------------------------------------------------------
+
+/**
+ * A door/window catalog **group** — a placement family (e.g. Swing, Sliding,
+ * Casement). Shared by `design.doors` and `design.windows`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dbType` | `string` | Stable engine token (e.g. `singleDoor`, `casementDouble`) |
+ * | `label` | `string` | Human-readable group label (e.g. `"Swing - 1 Shutter"`) |
+ * | `source` | `'default' \| 'team'` | Built-in group or a team-custom type |
+ */
+export const PluginObjectCatalogGroup = z.object({
+  dbType: z.string(),
+  label: z.string(),
+  source: z.enum(["default", "team"]),
+})
+export type PluginObjectCatalogGroup = z.infer<typeof PluginObjectCatalogGroup>
+
+/**
+ * A placeable door/window catalog **item** (value record — not a scene
+ * entity/handle). Shared by `design.doors` and `design.windows`; symmetric with
+ * {@linkcode PluginFurnitureCatalogItem}. The raw mesh (`.babylon`) URL is never
+ * exposed — only `thumbnailUrl`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Library id (team `_id` or general `fullName`) — pass to `design.create.door`/`window` |
+ * | `name` | `string` | Display name |
+ * | `source` | `'team' \| 'general'` | Which library it came from |
+ * | `dbType` | `string` | The group token it belongs to (e.g. `singleDoor`) |
+ * | `subType` | `string`? | Engine sub-type (optional) |
+ * | `thumbnailUrl` | `string`? | Preview thumbnail URL (optional) |
+ * | `cost` | `number`? | Cost (optional; team items) |
+ * | `familyName` | `string`? | Family name (optional) |
+ */
+export const PluginObjectCatalogItem = z.object({
+  id: z.string(),
+  name: z.string(),
+  source: z.enum(["team", "general"]),
+  dbType: z.string(),
+  subType: z.string().optional(),
+  thumbnailUrl: z.string().optional(),
+  cost: z.number().optional(),
+  familyName: z.string().optional(),
+})
+export type PluginObjectCatalogItem = z.infer<typeof PluginObjectCatalogItem>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.listCatalog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `group` | `string`? | Restrict to one group's `dbType` token (optional) |
+ */
+export const PluginDesignDoorListCatalogArgs = z.object({
+  group: z.string().optional(),
+})
+export type PluginDesignDoorListCatalogArgs = z.infer<typeof PluginDesignDoorListCatalogArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.getCatalogItem} / {@linkcode PluginDesignDoorsApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export const PluginDesignDoorGetCatalogItemArgs = z.object({
+  id: z.string(),
+})
+export type PluginDesignDoorGetCatalogItemArgs = z.infer<typeof PluginDesignDoorGetCatalogItemArgs>
+
+export const PluginDesignDoorExistsArgs = PluginDesignDoorGetCatalogItemArgs
+export type PluginDesignDoorExistsArgs = z.infer<typeof PluginDesignDoorExistsArgs>

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

@@ -35,7 +35,7 @@ export const ErasableEdgeRef = z.object({
   strategy: EraseStrategy,
   /** Bottom-graph edge weight: `1` = external boundary edge, `>=2` = internal edge shared between components. */
   edgeWeight: z.number(),
-  /** The components this edge is incident to — one for external (DirectDelete), two for internal (DirectUnion). */
+  /** The components this edge is incident to — one for external (DirectDelete); two or more for internal (DirectUnion; 3+ at T-junctions where several masses share the edge). */
   components: z.array(ComponentHandle),
   /** A representative point on the edge (its head endpoint). Diagnostic only. */
   snapPoint: Vec3Handle,