@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,500 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * `snaptrude.design.doors` — door-specific reads + edits. Creation lives at
+ * `design.create.door`; generic reads (`listDoors`/`getHost`/`getProperties`) live at
+ * `design.query.*`. Door targets are {@linkcode ComponentHandle}s.
+ *
+ * `getSwingDirection` is a DERIVED read (no persisted field) — computed from the placed
+ * mesh's orientation: stand on the side the door swings open to, facing it; `'left'`
+ * when the hinged jamb is on your left. `mirror` reflects the door about one of its own
+ * axes (undoable, one command): `'x'` flips the swing side, `'z'` swaps the hinged jamb;
+ * `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() {}
+
+  /**
+   * Get the type name of a door — the label that identifies which kind of door
+   * the instance is, as shown in its properties.
+   *
+   * @param door The door to query
+   * @returns The type as a `string`, or `null`
+   *
+   * @examplePrompt What type of door is this?
+   * @examplePrompt Tell me the door type of the selected door
+   * @examplePrompt Is this a single or a double door?
+   * @examplePrompt Check what kind of door is on this wall
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const type = await snaptrude.design.doors.getType(door)
+   * if (type) console.log("door type:", type)
+   * ```
+   */
+  public abstract getType(door: ComponentHandle): PluginApiReturn<string | null>
+
+  /**
+   * Get the family name of a door — the Revit or native family the door
+   * instance comes from.
+   *
+   * @param door The door to query
+   * @returns The family as a `string`, or `null`
+   *
+   * @examplePrompt Which family does this door belong to?
+   * @examplePrompt What's the Revit family of the selected door?
+   * @examplePrompt Show the family name for this door
+   * @examplePrompt Find out which door family the imported door uses
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors()
+   * const family = await snaptrude.design.doors.getFamily(door)
+   * if (family) console.log("family:", family)
+   * ```
+   */
+  public abstract getFamily(door: ComponentHandle): PluginApiReturn<string | null>
+
+  /**
+   * Get the width of a door — how wide its opening is along the host wall.
+   *
+   * @param door The door to query
+   * @returns The width as a `number`, or `null`
+   *
+   * @examplePrompt How wide is this door?
+   * @examplePrompt What's the width of the selected door?
+   * @examplePrompt Measure the width of the entrance door
+   * @examplePrompt Check whether this door is 900mm wide
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const width = await snaptrude.design.doors.getWidth(door)
+   * if (width !== null) console.log("door width:", width)
+   * ```
+   */
+  public abstract getWidth(door: ComponentHandle): PluginApiReturn<number | null>
+
+  /**
+   * Get the height of a door — how tall its opening is from base to head.
+   *
+   * @param door The door to query
+   * @returns The height as a `number`, or `null`
+   *
+   * @examplePrompt How tall is this door?
+   * @examplePrompt What's the height of the selected door?
+   * @examplePrompt Check the door height for this opening
+   * @examplePrompt Is the front door 2100mm high?
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors()
+   * const height = await snaptrude.design.doors.getHeight(door)
+   * if (height !== null) console.log("door height:", height)
+   * ```
+   */
+  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.
+   *
+   * @param door The door to query
+   * @returns The support floor {@linkcode ComponentHandle}, or `null`
+   *
+   * @examplePrompt Which floor is this door on?
+   * @examplePrompt What storey does the selected door belong to?
+   * @examplePrompt Find the level that hosts this door
+   * @examplePrompt Tell me which floor the entrance door sits on
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const floor = await snaptrude.design.doors.getSupportFloor(door)
+   * if (floor) {
+   *   const props = await snaptrude.design.query.getProperties(floor)
+   *   console.log("hosted on storey:", props.storey)
+   * }
+   * ```
+   */
+  public abstract getSupportFloor(door: ComponentHandle): PluginApiReturn<ComponentHandle | null>
+
+  /**
+   * Get a door's swing (hinge) handedness. Stand on the side the door swings
+   * open to, facing the door: `'left'` when the hinged jamb is on your left,
+   * `'right'` when it is on your right. Derived from the placed mesh's
+   * orientation (the same reflection `mirror` and the `hinge` placement option
+   * apply), not a persisted field.
+   *
+   * @param door The door to query
+   * @returns `'left'` / `'right'`, or `null` if indeterminate
+   *
+   * @examplePrompt Which way does this door swing?
+   * @examplePrompt Is the selected door left-handed or right-handed?
+   * @examplePrompt Check the hinge side of this door
+   * @examplePrompt Does the entrance door open to the left or the right?
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const swing = await snaptrude.design.doors.getSwingDirection(door)
+   * if (swing) console.log("opens as a", swing, "hand door")
+   * ```
+   */
+  public abstract getSwingDirection(
+    door: ComponentHandle
+  ): PluginApiReturn<"left" | "right" | null>
+
+  /**
+   * Mirror a door about its own axes. `'x'` (default) flips the swing side —
+   * the door opens to the other side of the wall; `'z'` swaps the hinged jamb
+   * (left-hand ↔ right-hand, same swing side); `'y'` turns it upside down.
+   * Undoable as a single command.
+   *
+   * @param door The door to mirror
+   * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis)
+   * @returns The affected door(s)
+   *
+   * @examplePrompt Flip this door's swing
+   * @examplePrompt Mirror the selected door
+   * @examplePrompt Make this door open the other way
+   * @examplePrompt Reverse the hinge side of the entrance door
+   * @examplePrompt Change the door to swing from the other side
+   *
+   * # Example
+   * ```ts
+   * // Flip the selected door's swing side — axis defaults to "x"
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const { affected } = await snaptrude.design.doors.mirror(door)
+   * // …or swap the hinged jamb instead (keeps the swing side)
+   * await snaptrude.design.doors.mirror(door, "z")
+   * ```
+   */
+  public abstract mirror(
+    door: ComponentHandle,
+    axis?: PluginMirrorAxis
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set the width of one or more doors, resizing each opening and re-cutting
+   * the host wall. Width is in engine units; the change is undoable.
+   *
+   * @param doors The doors to resize
+   * @param width New width (engine units)
+   * @returns The affected doors
+   *
+   * @examplePrompt Make this door 900mm wide
+   * @examplePrompt Widen the selected doors to 1 metre
+   * @examplePrompt Change the door width to 3 feet
+   * @examplePrompt Resize all the bathroom doors to 750 wide
+   * @examplePrompt Narrow the entrance door a bit
+   *
+   * # Example
+   * ```ts
+   * // Resize every ground-floor door to a common width (engine units)
+   * const doors = await snaptrude.design.query.listDoors({ storeys: [1] })
+   * const { affected } = await snaptrude.design.doors.setWidth(doors, 900)
+   * console.log("resized", affected.length, "doors")
+   * ```
+   */
+  public abstract setWidth(
+    doors: ComponentHandle[],
+    width: number
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set the height of one or more doors, resizing each opening and re-cutting
+   * the host wall. Height is in engine units; the change is undoable.
+   *
+   * @param doors The doors to resize
+   * @param height New height (engine units)
+   * @returns The affected doors
+   *
+   * @examplePrompt Make this door 2100mm tall
+   * @examplePrompt Change the door height to 7 feet
+   * @examplePrompt Raise the selected doors to 2.4m high
+   * @examplePrompt Set all the doors on this storey to 2100 high
+   *
+   * # Example
+   * ```ts
+   * // setHeight takes an array — wrap a single door
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * await snaptrude.design.doors.setHeight([door], 2100)
+   * ```
+   */
+  public abstract setHeight(
+    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>
+}
+
+/**
+ * Arguments for the single-door read methods.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `door` | {@linkcode ComponentHandle} | The door to query |
+ */
+export const PluginDesignDoorArgs = z.object({
+  door: ComponentHandle,
+})
+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: `'x'` flips the swing side, `'z'` swaps the hinged jamb, `'y'` turns the door upside down. */
+export const PluginMirrorAxis = z.enum(["x", "y", "z"])
+export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.mirror}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `door` | {@linkcode ComponentHandle} | The door to mirror |
+ * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis) |
+ */
+export const PluginDesignDoorMirrorArgs = z.object({
+  door: ComponentHandle,
+  axis: PluginMirrorAxis.optional(),
+})
+export type PluginDesignDoorMirrorArgs = z.infer<typeof PluginDesignDoorMirrorArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.setWidth}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `doors` | {@linkcode ComponentHandle}`[]` | The doors to resize |
+ * | `width` | `number` | New width (engine units) |
+ */
+export const PluginDesignDoorSetWidthArgs = z.object({
+  doors: z.array(ComponentHandle),
+  width: z.number(),
+})
+export type PluginDesignDoorSetWidthArgs = z.infer<typeof PluginDesignDoorSetWidthArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.setHeight}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `doors` | {@linkcode ComponentHandle}`[]` | The doors to resize |
+ * | `height` | `number` | New height (engine units) |
+ */
+export const PluginDesignDoorSetHeightArgs = z.object({
+  doors: z.array(ComponentHandle),
+  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/edit/index.ts

@@ -0,0 +1,54 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { OffsetSplitOutcome } from "../shared"
+
+/**
+ * STAGED (LLD Wave 2) — abstract shell only. NOT yet wired into `PluginDesignApi`
+ * and has no host implementation. `offsetSplit` migrates off `tools.offset` (adding
+ * the previously-dropped `offsetValue` to the result).
+ *
+ * `snaptrude.design.edit` — non-create geometry edits (offset-split, and later
+ * push-pull / topology edits). Undoable.
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignEditApi {
+  constructor() {}
+
+  /**
+   * Offset the top profile of a component by a distance and split the face along
+   * the offset curve. Positive distances offset outward, negative inward.
+   * Single-component only (the engine rejects batches).
+   * @param component - The component whose top profile is offset-split.
+   * @param offsetDistance - Offset distance; positive = outward, negative = inward.
+   * @param options - Optional settings: `profilePickPoint` picks the profile when ambiguous.
+   * @returns {@linkcode OffsetSplitOutcome} `{ createdIds, deletedIds, offsetValue }`
+   *
+   * @examplePrompt Offset the top face of this mass inward by 2 metres and split it
+   * @examplePrompt Create a 1m setback border on top of the selected mass
+   * @examplePrompt Split the roof profile with a 500mm inward offset
+   * @examplePrompt Offset-split the slab's top profile outward by 3 feet
+   *
+   * # Example
+   * ```ts
+   * // Offset the top profile inward by 2 units and split the face along it
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const { createdIds, offsetValue } = await snaptrude.design.edit.offsetSplit(mass, -2)
+   * // offsetValue is the post-clamp distance the engine actually applied
+   * ```
+   */
+  public abstract offsetSplit(
+    component: ComponentHandle,
+    offsetDistance: number,
+    options?: { profilePickPoint?: Vec3Handle },
+  ): PluginApiReturn<OffsetSplitOutcome>
+}
+
+// Positional target: offsetSplit(component, offsetDistance, options?)
+export const PluginDesignOffsetSplitArgs = z.object({
+  component: ComponentHandle,
+  offsetDistance: z.number(),
+  profilePickPoint: Vec3Handle.optional(),
+})
+export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>