@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

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

@@ -1,37 +1,40 @@
-import * as z from "zod"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
-
-/**
- * The shared field bag every hosted opening (door / window) carries — used by
- * {@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.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
- * | `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) |
- * | `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 PluginOpeningBaseOptions = {
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
-  label: z.string().optional(),
-  width: z.number().finite().positive().optional(),
-  height: z.number().finite().positive().optional(),
-}
+import * as z from "zod"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+
+/**
+ * The shared field bag every hosted opening (door / window) carries — used by
+ * {@linkcode PluginDesignCreateOpeningOptions} and by the bulk item schemas in
+ * `bulk-items.ts`, so singular and plural openings validate identically.
+ *
+ * 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 |
+ * |---|---|---|
+ * | `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 hinged jamb; requires the recipe's hand parameter |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Sets the declared width parameter, not the opening's evaluated envelope |
+ * | `height` | `number`? | Sets the declared height parameter |
+ */
+export const PluginOpeningBaseOptions = {
+  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(),
+  hinge: Vec3Handle.optional(),
+  label: z.string().optional(),
+  width: z.number().finite().positive().optional(),
+  height: z.number().finite().positive().optional(),
+}

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

@@ -1,74 +1,75 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle } from "../../../handles"
-import { PluginDesignChangeResult } from "../lock"
-
-/**
- * Arguments for {@linkcode PluginDesignDeleteApi.entities}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | Entities to delete. Unknown/forged handles reject the whole call (fail-fast). |
- *
- * `.min(1)` is deliberately stricter than the shipped `PluginDesignLockArgs`
- * (which allows an empty array) — an empty delete is a caller error, not a no-op.
- *
- * TRANSPORT: positional args — validated host-side as `{ components }`.
- */
-export const PluginDesignDeleteEntitiesArgs = z.object({
-  components: z.array(ComponentHandle).min(1),
-})
-export type PluginDesignDeleteEntitiesArgs = z.infer<typeof PluginDesignDeleteEntitiesArgs>
-
-/**
- * `snaptrude.design.delete.*` — **hard removal** of scene BIM entities.
- *
- * This is hard entity delete — distinct from `design.erase.edge` (a plan-level
- * adjacency-edge topology op) and `design.boolean.subtract` (a CSG geometry
- * delete). The constitution forbids `erase`/`clear`/`remove` as synonyms for
- * `delete`; these are three separate operations.
- *
- * TRANSPORT: positional args per method.
- */
-export abstract class PluginDesignDeleteApi {
-  constructor() {}
-
-  /**
-   * Delete one or more entities. Generic hard delete (backed by the same batched,
-   * undoable path as `entity.space.delete`). Cascade is opinionated by the engine:
-   * children are removed and linked-list neighbours are fixed up — not caller-tunable
-   * in v1. Undoable — commits as a **single** undo entry.
-   *
-   * Dimension lines anchored to a deleted entity are removed with it, in the same undo
-   * entry, exactly as the editor's Delete key does — see `design.dimensions`. They are
-   * NOT listed in `affected`, which reports component handles only.
-   *
-   * @param components - Entities to delete. Unknown/forged handles reject the whole call (fail-fast).
-   * @returns The entities that were deleted, as {@linkcode ComponentHandle}`[]`
-   *   (echoed host-side from the resolved+deleted set — the engine returns no ids).
-   *   Deleted handles are **stale** afterwards: re-resolving one throws `HANDLE_INVALID`.
-   * @throws If any supplied handle is unknown/forged (`HANDLE_INVALID`) — the whole
-   *   call rejects before anything is deleted (all-or-nothing resolution).
-   *
-   * @examplePrompt Delete the selected objects
-   * @examplePrompt Remove these walls from the model
-   * @examplePrompt Get rid of this mass entirely
-   * @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)
-   * const furniture = await snaptrude.design.query.listFurniture({ storeys: [2] })
-   * if (furniture.length > 0) {
-   *   const { affected } = await snaptrude.design.delete.entities(furniture)
-   * }
-   * ```
-   */
-  public abstract entities(
-    components: ComponentHandle[],
-  ): PluginApiReturn<PluginDesignChangeResult>
-}
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * Arguments for {@linkcode PluginDesignDeleteApi.entities}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to delete. Unknown/forged handles reject the whole call (fail-fast). |
+ *
+ * `.min(1)` is deliberately stricter than the shipped `PluginDesignLockArgs`
+ * (which allows an empty array) — an empty delete is a caller error, not a no-op.
+ *
+ * TRANSPORT: positional args — validated host-side as `{ components }`.
+ */
+export const PluginDesignDeleteEntitiesArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+})
+export type PluginDesignDeleteEntitiesArgs = z.infer<typeof PluginDesignDeleteEntitiesArgs>
+
+/**
+ * `snaptrude.design.delete.*` — **hard removal** of scene BIM entities.
+ *
+ * This is hard entity delete — distinct from `design.erase.edge` (a plan-level
+ * adjacency-edge topology op) and `design.boolean.subtract` (a CSG geometry
+ * delete). The constitution forbids `erase`/`clear`/`remove` as synonyms for
+ * `delete`; these are three separate operations.
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignDeleteApi {
+  constructor() {}
+
+  /**
+   * Delete one or more entities. Generic hard delete (backed by the same batched,
+   * undoable path as `entity.space.delete`). Cascade is opinionated by the engine:
+   * children are removed and linked-list neighbours are fixed up — not caller-tunable
+   * in v1. Undoable — commits as a **single** undo entry.
+   *
+   * Dimension lines anchored to a deleted entity are removed with it, in the same undo
+   * entry, exactly as the editor's Delete key does — see `design.dimensions`. They are
+   * NOT listed in `affected`, which reports component handles only.
+   *
+   * @param components - Entities to delete. Unknown/forged handles reject the whole call (fail-fast).
+   * @returns The entities that were deleted, as {@linkcode ComponentHandle}`[]`
+   *   (echoed host-side from the resolved+deleted set — the engine returns no ids).
+   *   Deleted handles are **stale** afterwards: re-resolving one throws `HANDLE_INVALID`.
+   * @throws If any supplied handle is unknown/forged (`HANDLE_INVALID`) — the whole
+   *   call rejects before anything is deleted (all-or-nothing resolution).
+   *
+   * @examplePrompt Delete the selected objects
+   * @examplePrompt Remove these walls from the model
+   * @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.
+   *
+   * # Example
+   * ```ts
+   * // Hard-delete every furniture item on storey 2 (a single undo entry)
+   * const furniture = await snaptrude.design.query.listFurniture({ storeys: [2] })
+   * if (furniture.length > 0) {
+   *   const { affected } = await snaptrude.design.delete.entities(furniture)
+   * }
+   * ```
+   */
+  public abstract entities(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+}