@snaptrude/plugin-core 0.9.17 → 0.9.18-voids-20261016.1

package/src/api/design/create/opening-fields.ts

@@ -6,27 +6,30 @@ import { ComponentHandle, Vec3Handle } from "../../../handles"
  * {@linkcode PluginDesignCreateOpeningOptions} and by the bulk item schemas in
  * `bulk-items.ts`, so singular and plural openings validate identically.
  *
- * `facing` and `hinge` are WORLD POINTS, not directions: `facing` sits on the
- * side of the wall the leaf swings open to (where the plan symbol draws the
- * swing arc); `hinge` sits near the jamb the leaf is hinged on — the item is
- * reflected along the wall so its hinged jamb is the one nearer that point.
- * Either may be omitted (engine-chosen side / the catalog item's authored
- * hinge side). Neither has a visible effect on symmetric items such as
- * sliders or fixed windows.
+ * PC-only placement. The family recipe owns dimensions and geometry. Overrides
+ * are applied before fit checks and cutting, never by scaling generated meshes.
+ * `facing` selects the host frame's +Z side. `hinge` selects the declared
+ * `hand` parameter (left/right); families without that control reject it.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted parametric definition ID, not a mesh catalog ID |
+ * | `version` | `number`? | Exact family version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Authored instance parameters; numeric lengths use Snaptrude units |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the opening |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the opening swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the opening is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires the recipe's hand parameter |
  * | `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) |
+ * | `width` | `number`? | Sets the declared width parameter, not the opening's evaluated envelope |
+ * | `height` | `number`? | Sets the declared height parameter |
  */
 export const PluginOpeningBaseOptions = {
-  catalogId: z.string().min(1),
+  familyId: z.string().min(1),
+  version: z.number().int().positive().optional(),
+  values: z
+    .record(z.string(), z.union([z.number().finite(), z.string()]))
+    .optional(),
   hostWall: ComponentHandle,
   position: Vec3Handle,
   facing: Vec3Handle.optional(),

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

@@ -55,6 +55,7 @@ export abstract class PluginDesignDeleteApi {
    * @examplePrompt Get rid of this mass entirely
    * @examplePrompt Delete all the furniture I picked
    * @examplePrompt Remove the door and window I just created
+   * @examplePrompt Remove the void I cut in this slab
    *
    * @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.

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

@@ -8,18 +8,15 @@ import { PluginDesignChangeResult } from "../lock"
  * `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).
+ * PC-only: dimensions read the evaluated opening. Setters write declared width/height
+ * parameters, never mesh scale. Missing or derived controls reject. Linked copies follow
+ * the shared edit. Use design.family.setParameters for other parameters.
+ * getSwingDirection reads hand. mirror changes declared swing or hand controls.
  *
  * 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}
+ * browse saved hosted door families, keyed by definition ID, and feed design.create.door.
+ * They reject if saved definitions cannot be loaded completely. A missing item returns null.
+ * The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
  * DTOs are shared with `design.windows`.
  */
 export abstract class PluginDesignDoorsApi {
@@ -65,7 +62,9 @@ export abstract class PluginDesignDoorsApi {
    * if (family) console.log("family:", family)
    * ```
    */
-  public abstract getFamily(door: ComponentHandle): PluginApiReturn<string | null>
+  public abstract getFamily(
+    door: ComponentHandle,
+  ): PluginApiReturn<string | null>
 
   /**
    * Get the width of a door — how wide its opening is along the host wall.
@@ -85,7 +84,9 @@ export abstract class PluginDesignDoorsApi {
    * if (width !== null) console.log("door width:", width)
    * ```
    */
-  public abstract getWidth(door: ComponentHandle): PluginApiReturn<number | null>
+  public abstract getWidth(
+    door: ComponentHandle,
+  ): PluginApiReturn<number | null>
 
   /**
    * Get the height of a door — how tall its opening is from base to head.
@@ -105,12 +106,13 @@ export abstract class PluginDesignDoorsApi {
    * if (height !== null) console.log("door height:", height)
    * ```
    */
-  public abstract getHeight(door: ComponentHandle): PluginApiReturn<number | null>
+  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}.
+   * Get evaluated opening width/height and host thickness, in Snaptrude units.
+   * The opening can include allowances beyond the width/height input parameters.
    *
    * @param door The door to query
    * @returns The dimensions, or `null`
@@ -128,12 +130,12 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getDimensions(
-    door: ComponentHandle
+    door: ComponentHandle,
   ): PluginApiReturn<PluginDoorDimensions | null>
 
   /**
-   * Get the floor a door is hosted on — the storey/level component that
-   * supports the door.
+   * Returns null for recipe doors. Room floors own doorway infill; there is
+   * no separate support-floor entity.
    *
    * @param door The door to query
    * @returns The support floor {@linkcode ComponentHandle}, or `null`
@@ -153,14 +155,13 @@ export abstract class PluginDesignDoorsApi {
    * }
    * ```
    */
-  public abstract getSupportFloor(door: ComponentHandle): PluginApiReturn<ComponentHandle | null>
+  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.
+   * Read the saved hand parameter. left means local -X; right means local +X.
+   * Returns null when the recipe does not declare that control.
    *
    * @param door The door to query
    * @returns `'left'` / `'right'`, or `null` if indeterminate
@@ -178,14 +179,15 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getSwingDirection(
-    door: ComponentHandle
+    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.
+   * Change authored controls in one undo step: x (default) toggles swing
+   * front/back; z toggles hand left/right. The recipe must declare these enums.
+   * Axis y rejects. No mesh reflection occurs. Recipes use outputs.swingSide
+   * (1 or -1) for the adjoining room's floor ownership. A door between two
+   * room floors requires this output; a missing or invalid report rejects the cut.
    *
    * @param door The door to mirror
    * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis)
@@ -208,7 +210,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract mirror(
     door: ComponentHandle,
-    axis?: PluginMirrorAxis
+    axis?: PluginMirrorAxis,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -235,7 +237,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract setWidth(
     doors: ComponentHandle[],
-    width: number
+    width: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -260,7 +262,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract setHeight(
     doors: ComponentHandle[],
-    height: number
+    height: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -280,7 +282,9 @@ export abstract class PluginDesignDoorsApi {
    * for (const g of groups) console.log(g.dbType, g.label, g.source)
    * ```
    */
-  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+  public abstract listCatalogGroups(): PluginApiReturn<
+    PluginObjectCatalogGroup[]
+  >
 
   /**
    * List the placeable door catalog (team + general libraries), optionally
@@ -302,7 +306,7 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract listCatalog(
-    group?: string
+    group?: string,
   ): PluginApiReturn<PluginObjectCatalogItem[]>
 
   /**
@@ -324,7 +328,7 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getCatalogItem(
-    id: string
+    id: string,
   ): PluginApiReturn<PluginObjectCatalogItem | null>
 
   /**
@@ -392,7 +396,9 @@ export const PluginDesignDoorMirrorArgs = z.object({
   door: ComponentHandle,
   axis: PluginMirrorAxis.optional(),
 })
-export type PluginDesignDoorMirrorArgs = z.infer<typeof PluginDesignDoorMirrorArgs>
+export type PluginDesignDoorMirrorArgs = z.infer<
+  typeof PluginDesignDoorMirrorArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignDoorsApi.setWidth}.
@@ -406,7 +412,9 @@ export const PluginDesignDoorSetWidthArgs = z.object({
   doors: z.array(ComponentHandle),
   width: z.number(),
 })
-export type PluginDesignDoorSetWidthArgs = z.infer<typeof PluginDesignDoorSetWidthArgs>
+export type PluginDesignDoorSetWidthArgs = z.infer<
+  typeof PluginDesignDoorSetWidthArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignDoorsApi.setHeight}.
@@ -420,7 +428,9 @@ export const PluginDesignDoorSetHeightArgs = z.object({
   doors: z.array(ComponentHandle),
   height: z.number(),
 })
-export type PluginDesignDoorSetHeightArgs = z.infer<typeof PluginDesignDoorSetHeightArgs>
+export type PluginDesignDoorSetHeightArgs = z.infer<
+  typeof PluginDesignDoorSetHeightArgs
+>
 
 // ---------------------------------------------------------------------------
 // catalog (shared by doors + windows)
@@ -482,7 +492,9 @@ export type PluginObjectCatalogItem = z.infer<typeof PluginObjectCatalogItem>
 export const PluginDesignDoorListCatalogArgs = z.object({
   group: z.string().optional(),
 })
-export type PluginDesignDoorListCatalogArgs = z.infer<typeof PluginDesignDoorListCatalogArgs>
+export type PluginDesignDoorListCatalogArgs = z.infer<
+  typeof PluginDesignDoorListCatalogArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignDoorsApi.getCatalogItem} / {@linkcode PluginDesignDoorsApi.exists}.
@@ -494,7 +506,11 @@ export type PluginDesignDoorListCatalogArgs = z.infer<typeof PluginDesignDoorLis
 export const PluginDesignDoorGetCatalogItemArgs = z.object({
   id: z.string(),
 })
-export type PluginDesignDoorGetCatalogItemArgs = z.infer<typeof PluginDesignDoorGetCatalogItemArgs>
+export type PluginDesignDoorGetCatalogItemArgs = z.infer<
+  typeof PluginDesignDoorGetCatalogItemArgs
+>
 
 export const PluginDesignDoorExistsArgs = PluginDesignDoorGetCatalogItemArgs
-export type PluginDesignDoorExistsArgs = z.infer<typeof PluginDesignDoorExistsArgs>
+export type PluginDesignDoorExistsArgs = z.infer<
+  typeof PluginDesignDoorExistsArgs
+>