@snaptrude/plugin-core 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/design/create/bulk-items.ts

@@ -156,6 +156,9 @@ export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
  * Values are evaluated before cutting. Numeric lengths use SU; unit strings
  * are accepted in values. `facing` selects local +Z; `hinge` sets the declared
  * hand enum (left = local -X, right = +X). Both are world points.
+ * A door between a room and a corridor, lobby or hall swings into the room:
+ * pass `facing` inside the room it serves, never in the corridor. Toilets,
+ * cupboards, shafts and exits on an escape route open outward instead.
  *
  * | Property | Type | Description |
  * |---|---|---|
@@ -164,7 +167,7 @@ export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
  * | `values` | `Record<string, number \| string>`? | Authored parameter overrides |
  * | `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) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door swings open to: inside the room it serves (default engine-chosen) |
  * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  * | `label` | `string`? | Instance name (optional) |
  * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |

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

@@ -1047,6 +1047,12 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Put three doors on this wall in a single undo step
    * @examplePrompt Add all the doors for this floor plan together
    *
+   * A width/height (top-level, or under the family's own keys in `values`) on a family that
+   * takes its size from its Type while Custom Sizes is off is never dropped: the Type within
+   * 25 mm is chosen, else Custom Sizes is turned on and that size is built, leaving the Type
+   * label stale. `design.doors.checkPlacement` reports which as `sizing`; `customSizes: "No"`
+   * with a size no Type matches is refused.
+   *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
    *   entry. Always prefer this over
    *   calling `design.create.door` in a loop: build the full `items[]` array first
@@ -1152,6 +1158,12 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Put four windows on this wall in a single undo step
    * @examplePrompt Add all the windows with a 0.9m sill height together
    *
+   * A width/height (top-level, or under the family's own keys in `values`) on a family that
+   * takes its size from its Type while Custom Sizes is off is never dropped: the Type within
+   * 25 mm is chosen, else Custom Sizes is turned on and that size is built, leaving the Type
+   * label stale. `design.windows.checkPlacement` reports which as `sizing`; `customSizes: "No"`
+   * with a size no Type matches is refused.
+   *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
    *   entry. Always prefer this over
    *   calling `design.create.window` in a loop: build the full `items[]` array first

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

@@ -2,6 +2,10 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
+import type {
+  PluginOpeningPlacementArgs,
+  PluginOpeningPlacementResult,
+} from "../opening-placement"
 
 /**
  * `snaptrude.design.doors` — door-specific reads + edits. Creation lives at
@@ -22,6 +26,33 @@ import { PluginDesignChangeResult } from "../lock"
 export abstract class PluginDesignDoorsApi {
   constructor() {}
 
+  /**
+   * Trial the native host fit and geometry rebuild, then restore the model without publishing commands.
+   * The first result uses the creation options; subsequent results use candidateWidths in input order.
+   * Widths are authored parameters, not physical envelopes or a guaranteed maximum width.
+   * No catalog save, history entry or model persistence occurs. Rerun after model edits.
+   * A failed fit leaves cut unverified. Family-host cuts are also unverified: their rebuild
+   * cannot supply a reversible, authoritative trial result. Material clearance checks evaluated
+   * parts against physical neighbours across hosts. The intended host uses native fit/cut checks.
+   * Creation repeats clearance immediately before placement; this report grants no later approval.
+   * Editing permission is required; locked hosts and an active opening tool reject.
+   * It does not say which room the door opens into: read `opensInto` from
+   * `design.validation.access()` after placement (see {@linkcode getSwingDirection}).
+   * A requested width/height on a family sized by its Type (Custom Sizes off) picks the Type
+   * within 25 mm, else turns Custom Sizes on; each result's `sizing` says which. Creation
+   * (`design.create.door(s)`) applies the same rule, so the size you pass is the size built.
+   * @param options Door creation options and up to 12 alternative widths; numeric lengths use SU.
+   * @returns Separate fit/cut/clearance evidence, evaluated bounds and explicit limitations.
+   * @examplePrompt Check which door widths fit this host without placing a door
+   * @example
+   * const result = await snaptrude.design.doors.checkPlacement({
+   *   familyId, version, hostWall, position, width: 3.5, candidateWidths: [3, 2.5],
+   * })
+   */
+  public abstract checkPlacement(
+    options: PluginOpeningPlacementArgs,
+  ): PluginApiReturn<PluginOpeningPlacementResult>
+
   /**
    * Get the type name of a door — the label that identifies which kind of door
    * the instance is, as shown in its properties.
@@ -163,6 +194,12 @@ export abstract class PluginDesignDoorsApi {
    * Read the saved hand parameter. left means local -X; right means local +X.
    * Returns null when the recipe does not declare that control.
    *
+   * Hand is the hinge side, not the room the leaf swings into. For that, read
+   * `(await design.validation.access()).topology.rooms[].doors[].opensInto`: a
+   * converted room or `"outside"`. A door whose wall is not a room edge is listed
+   * in `topology.unresolvedDoors` instead. To make it open into the other room,
+   * call {@linkcode mirror} (axis `x`) and read access again.
+   *
    * @param door The door to query
    * @returns `'left'` / `'right'`, or `null` if indeterminate
    *
@@ -170,12 +207,16 @@ export abstract class PluginDesignDoorsApi {
    * @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?
+   * @examplePrompt Which room does this door open into?
    *
    * # 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")
+   * // Which room it opens into
+   * const { topology } = await snaptrude.design.validation.access()
+   * const side = topology.rooms.flatMap((r) => r.doors).find((d) => d.door === door)?.opensInto
    * ```
    */
   public abstract getSwingDirection(
@@ -188,6 +229,8 @@ export abstract class PluginDesignDoorsApi {
    * 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.
+   * The same side decides `opensInto` in `design.validation.access()`; read it
+   * there to confirm which room the door now opens into.
    *
    * @param door The door to mirror
    * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis)

package/src/api/design/index.ts

@@ -288,6 +288,7 @@ export * from "./query"
 export * from "./selection"
 export * from "./doors"
 export * from "./windows"
+export * from "./opening-placement"
 export * from "./furniture"
 export * from "./materials"
 export * from "./lock"

package/src/api/design/opening-placement.ts

@@ -0,0 +1,79 @@
+import * as z from "zod"
+import { PluginOpeningBaseOptions } from "./create/opening-fields"
+
+/** Creation options plus bounded alternative widths. Each trial starts from the same model. */
+export const PluginOpeningPlacementArgs = z.object({
+  ...PluginOpeningBaseOptions,
+  sillHeight: z.number().finite().nonnegative().optional(),
+  candidateWidths: z.array(z.number().finite().positive()).max(12).optional(),
+})
+export type PluginOpeningPlacementArgs = z.infer<
+  typeof PluginOpeningPlacementArgs
+>
+
+/** A failed fit leaves the cut unverified: no geometry trial was attempted. */
+export const PluginOpeningPlacementCheck = z.object({
+  status: z.enum(["pass", "fail", "unverified"]),
+  reason: z.string(),
+})
+
+const bounds = z.object({
+  min: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }),
+  max: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }),
+})
+
+/** Fit, cut and material clearance are independent checks, not an accessibility certificate. */
+export const PluginOpeningPlacementResult = z.object({
+  units: z.literal("SU"),
+  results: z.array(
+    z.object({
+      requestedWidth: z.number().finite().positive().optional(),
+      requestedHeight: z.number().finite().positive().optional(),
+      /** Original parameter overrides. Evaluated bounds can differ from these values. */
+      requestedValues: z.record(z.string(), z.union([z.number().finite(), z.string()])).optional(),
+      /**
+       * Present when the family sizes itself from a Type unless Custom Sizes is on, and a width
+       * or height was requested. `type`: the Type within 25 mm was chosen (its label stays true).
+       * `custom`: none matched, so Custom Sizes was turned on and the requested size is built;
+       * `type` then names the Type that no longer describes it. Creation applies the same rule.
+       */
+      sizing: z
+        .object({
+          mode: z.enum(["type", "custom"]),
+          typeKey: z.string(),
+          type: z.string(),
+          note: z.string(),
+        })
+        .optional(),
+      /** World-space bounds of evaluated material parts, never the opening proxy. */
+      physicalBounds: bounds.optional(),
+      /** Only present when the recipe declares semantic frame anatomy. */
+      frameBounds: bounds.optional(),
+      /** World enclosure of the authored cut envelope; not frame or clear passage width. */
+      roughOpeningBounds: bounds.optional(),
+      dimensions: z
+        .object({
+          width: z.number().finite().positive(),
+          height: z.number().finite().positive(),
+          thickness: z.number().finite().nonnegative(),
+        })
+        .optional(),
+      fit: PluginOpeningPlacementCheck,
+      cut: PluginOpeningPlacementCheck,
+      clearance: PluginOpeningPlacementCheck.extend({
+        candidatePairs: z.number().int().nonnegative(),
+        checkedPairs: z.number().int().nonnegative(),
+        obstructions: z.array(z.object({
+          entity: z.string(),
+          status: z.enum(["fail", "unverified"]),
+          reason: z.string(),
+          intersectionVolume: z.number().finite().nonnegative().optional(),
+        })),
+      }),
+    }),
+  ),
+  limitations: z.array(z.string()),
+})
+export type PluginOpeningPlacementResult = z.infer<
+  typeof PluginOpeningPlacementResult
+>

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

@@ -3,6 +3,10 @@ import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
+import type {
+  PluginOpeningPlacementArgs,
+  PluginOpeningPlacementResult,
+} from "../opening-placement"
 
 /**
  * `snaptrude.design.windows` — window-specific reads. Creation lives at
@@ -22,6 +26,31 @@ import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
 export abstract class PluginDesignWindowsApi {
   constructor() {}
 
+  /**
+   * Trial the native host fit and geometry rebuild, then restore the model without publishing commands.
+   * The first result uses the creation options; subsequent results use candidateWidths in input order.
+   * Widths are authored parameters, not physical envelopes or a guaranteed maximum width.
+   * No catalog save, history entry or model persistence occurs. Rerun after model edits.
+   * A failed fit leaves cut unverified. Family-host cuts are also unverified: their rebuild
+   * cannot supply a reversible, authoritative trial result. Material clearance checks evaluated
+   * parts against physical neighbours across hosts. The intended host uses native fit/cut checks.
+   * Creation repeats clearance immediately before placement; this report grants no later approval.
+   * Editing permission is required; locked hosts and an active opening tool reject.
+   * A requested width/height on a family sized by its Type (Custom Sizes off) picks the Type
+   * within 25 mm, else turns Custom Sizes on; each result's `sizing` says which. Creation
+   * (`design.create.window(s)`) applies the same rule, so the size you pass is the size built.
+   * @param options Window creation options and up to 12 alternative widths; numeric lengths use SU.
+   * @returns Separate fit/cut/clearance evidence, evaluated bounds and explicit limitations.
+   * @examplePrompt Check whether this window fits and its host can be cut
+   * @example
+   * const result = await snaptrude.design.windows.checkPlacement({
+   *   familyId, version, hostWall, position, width: 4, sillHeight: 3,
+   * })
+   */
+  public abstract checkPlacement(
+    options: PluginOpeningPlacementArgs,
+  ): PluginApiReturn<PluginOpeningPlacementResult>
+
   /**
    * Get the type name of a window — the label that identifies which kind of
    * window the instance is, as shown in its properties.