@snaptrude/plugin-core 0.9.7 → 0.9.8

package/package.json

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

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

@@ -77,15 +77,17 @@ export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
  * One door to place via {@linkcode PluginDesignCreateApi.doors} — the same
  * fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}, so the
  * size overrides singular {@linkcode PluginDesignCreateApi.door} lacks are
- * available per item. `facing` is a WORLD POINT on the side of the wall the
- * door opens into, not a direction. Rejects unknown fields.
+ * available per item. `facing` and `hinge` are WORLD POINTS, not directions:
+ * `facing` on the side of the wall the door swings open to, `hinge` near the
+ * jamb it is hinged on. Rejects unknown fields.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
  * | `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 faces (default engine-chosen) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door 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) |
@@ -106,8 +108,9 @@ export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
  * One window to place via {@linkcode PluginDesignCreateApi.windows} — the same
  * fields as a `"window"` {@linkcode PluginDesignCreateOpeningOptions}.
  * `sillHeight` is a nonnegative Snaptrude-unit distance from the host wall's
- * base to the BOTTOM of the window, not to its center. `facing` is a WORLD
- * POINT on the desired side of the wall, not a direction. Rejects unknown
+ * base to the BOTTOM of the window, not to its center. `facing` and `hinge`
+ * are WORLD POINTS, not directions: `facing` on the side of the wall the
+ * window opens to, `hinge` near the jamb it is hinged on. Rejects unknown
  * fields.
  *
  * | Property | Type | Description |
@@ -115,7 +118,8 @@ export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
  * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
- * | `facing` | {@linkcode Vec3Handle}? | World point on the side the window faces (default engine-chosen) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the window opens to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window 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) |

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

@@ -753,12 +753,15 @@ export abstract class PluginDesignCreateApi {
    * @param catalogId - Library id: team `_id` or general `fullName`
    * @param hostWall - The wall to host the door
    * @param position - World point projected onto the wall to locate the opening
-   * @param options - Optional placement options: `label` — instance name
-   * @param facing - World point selecting which side of the wall the door faces
-   *   (the room it opens into) — the same convention as approaching the wall
-   *   from that side with the cursor in the interactive tool. Any point clearly
-   *   on that side works (e.g. the room's center). Default: the engine picks a
-   *   side (nondeterministic when `position` sits on the wall centerline).
+   * @param options - Optional placement options: `label` — instance name;
+   *   `hinge` — world point near the jamb the door is hinged on (the door is
+   *   reflected along the wall so its hinged jamb is the one nearer this
+   *   point; default the catalog item's authored hinge side)
+   * @param facing - World point on the side of the wall the door swings open
+   *   to (the room it opens into — where the plan symbol draws the swing arc).
+   *   Any point clearly on that side works (e.g. the room's center). Default:
+   *   the engine picks a side (nondeterministic when `position` sits on the
+   *   wall centerline).
    * @returns the {@linkcode ComponentHandle} of the placed door
    * @throws if the catalog id is unknown, the host is not a wall, the source
    *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -769,6 +772,7 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Insert the entrance door into this wall
    * @examplePrompt Add a door to the wall and call it Entry-01
    * @examplePrompt Add a door that opens into the living room
+   * @examplePrompt Put a door here hinged on the north jamb
    *
    * # Example
    * ```ts
@@ -788,6 +792,14 @@ export abstract class PluginDesignCreateApi {
    *   undefined,
    *   await snaptrude.core.math.vec3.new(3, 0, 9),
    * )
+   * // …and hinged on the jamb nearest a point (here the +x end of the opening):
+   * const hingedRight = await snaptrude.design.create.door(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   { hinge: await snaptrude.core.math.vec3.new(3.5, 0, 5) },
+   *   await snaptrude.core.math.vec3.new(3, 0, 9),
+   * )
    * ```
    *
    * @performance For MORE THAN ONE door, call `design.create.doors(items[])` — one host
@@ -798,7 +810,7 @@ export abstract class PluginDesignCreateApi {
     catalogId: string,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string },
+    options?: { label?: string; hinge?: Vec3Handle },
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
@@ -821,8 +833,8 @@ export abstract class PluginDesignCreateApi {
    * @returns the placed doors as {@linkcode ComponentHandle}`[]`, in input order
    * @throws `VALIDATION` if the items fail the schema (empty array, more than
    *   1000 items, unknown fields, a non-positive `width`/`height`);
-   *   `HANDLE_INVALID` if a `position` or `facing` handle is unknown or
-   *   released; `PRECONDITION_FAILED` if a catalog id is unknown, a `hostWall`
+   *   `HANDLE_INVALID` if a `position`, `facing` or `hinge` handle is unknown
+   *   or released; `PRECONDITION_FAILED` if a catalog id is unknown, a `hostWall`
    *   is not a wall / is locked / is not in the active proposal, the projected
    *   point falls outside its host wall, or a door tool is active;
    *   `OPERATION_FAILED` if a source mesh fails to load or placement fails
@@ -870,11 +882,14 @@ export abstract class PluginDesignCreateApi {
    * @param catalogId - Library id: team `_id` or general `fullName`
    * @param hostWall - The wall to host the window
    * @param position - World point projected onto the wall to locate the opening
-   * @param options - Optional placement options: `label` — instance name
-   * @param facing - World point selecting which side of the wall the window
-   *   faces (matters for asymmetric windows, e.g. casement swing) — same
-   *   convention as {@linkcode PluginDesignCreateApi.door}. Default: the engine
-   *   picks a side (nondeterministic when `position` sits on the centerline).
+   * @param options - Optional placement options: `label` — instance name;
+   *   `hinge` — world point near the jamb the window is hinged on (same rule
+   *   as {@linkcode PluginDesignCreateApi.door}; default the catalog item's
+   *   authored side)
+   * @param facing - World point on the side of the wall the window opens to
+   *   (matters for asymmetric windows, e.g. casement swing) — same convention
+   *   as {@linkcode PluginDesignCreateApi.door}. Default: the engine picks a
+   *   side (nondeterministic when `position` sits on the centerline).
    * @returns the {@linkcode ComponentHandle} of the placed window
    * @throws if the catalog id is unknown, the host is not a wall, the source
    *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -906,7 +921,7 @@ export abstract class PluginDesignCreateApi {
     catalogId: string,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string },
+    options?: { label?: string; hinge?: Vec3Handle },
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
@@ -931,8 +946,8 @@ export abstract class PluginDesignCreateApi {
    * @returns the placed windows as {@linkcode ComponentHandle}`[]`, in input order
    * @throws `VALIDATION` if the items fail the schema (empty array, more than
    *   1000 items, unknown fields, a non-positive `width`/`height`, a negative
-   *   `sillHeight`); `HANDLE_INVALID` if a `position` or `facing` handle is
-   *   unknown or released; `PRECONDITION_FAILED` if a catalog id is unknown, a
+   *   `sillHeight`); `HANDLE_INVALID` if a `position`, `facing` or `hinge`
+   *   handle is unknown or released; `PRECONDITION_FAILED` if a catalog id is unknown, a
    *   `hostWall` is not a wall / is locked / is not in the active proposal, the
    *   projected point falls outside its host wall, or a window tool is active;
    *   `OPERATION_FAILED` if a source mesh fails to load or placement fails
@@ -975,7 +990,7 @@ export abstract class PluginDesignCreateApi {
    * its center. Placement is asynchronous and committed as one undoable creation.
    *
    * @param options - Opening kind, catalog and host references, placement, and
-   *   optional facing, label, and dimensions
+   *   optional facing (swing side), hinge (hinged jamb), label, and dimensions
    * @returns the {@linkcode ComponentHandle} of the placed door or window
    * @throws if the options are invalid, the catalog id is unknown, the host is
    *   not a wall, loading fails, or the opening cannot be placed on the host
@@ -1576,7 +1591,8 @@ export type PluginDesignCreateFurnitureArgs = z.infer<
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
- * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door faces (default engine-chosen) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
  */
 export const PluginDesignCreateDoorArgs = z.object({
   catalogId: z.string().min(1),
@@ -1584,12 +1600,13 @@ export const PluginDesignCreateDoorArgs = z.object({
   position: Vec3Handle,
   label: z.string().optional(),
   facing: Vec3Handle.optional(),
+  hinge: Vec3Handle.optional(),
 })
 export type PluginDesignCreateDoorArgs = z.infer<
   typeof PluginDesignCreateDoorArgs
 >
-// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
-//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
+//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label?, hinge? }, facing?: Vec3Handle)
 
 // ---------------------------------------------------------------------------
 // window
@@ -1604,7 +1621,8 @@ export type PluginDesignCreateDoorArgs = z.infer<
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
- * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window faces (default engine-chosen) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window opens to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
  */
 export const PluginDesignCreateWindowArgs = z.object({
   catalogId: z.string().min(1),
@@ -1612,12 +1630,13 @@ export const PluginDesignCreateWindowArgs = z.object({
   position: Vec3Handle,
   label: z.string().optional(),
   facing: Vec3Handle.optional(),
+  hinge: Vec3Handle.optional(),
 })
 export type PluginDesignCreateWindowArgs = z.infer<
   typeof PluginDesignCreateWindowArgs
 >
-// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
-//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
+//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label?, hinge? }, facing?: Vec3Handle)
 
 // ---------------------------------------------------------------------------
 // opening

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

@@ -6,14 +6,21 @@ 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` is a WORLD POINT on the desired side of the wall, not a direction.
+ * `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 faces (default engine-chosen) |
+ * | `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) |
@@ -23,6 +30,7 @@ export const PluginOpeningBaseOptions = {
   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/doors/index.ts

@@ -8,9 +8,11 @@ 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 door
- * 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 —
+ * `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`)
@@ -154,9 +156,11 @@ export abstract class PluginDesignDoorsApi {
   public abstract getSupportFloor(door: ComponentHandle): PluginApiReturn<ComponentHandle | null>
 
   /**
-   * Get a door's swing (hinge) handedness — whether it opens as a left-hand or
-   * right-hand door. Derived from the door mesh's reflection state, not a
-   * persisted field.
+   * 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
@@ -178,11 +182,13 @@ export abstract class PluginDesignDoorsApi {
   ): PluginApiReturn<"left" | "right" | null>
 
   /**
-   * Mirror a door across an axis, flipping its swing so it opens from the
-   * other side. Undoable as a single command.
+   * 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)
+   * @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
@@ -193,10 +199,11 @@ export abstract class PluginDesignDoorsApi {
    *
    * # Example
    * ```ts
-   * // Flip the selected door's swing — axis defaults to "x" (the swing-flip
-   * // axis); pass "y" or "z" to reflect across a different axis
+   * // 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(
@@ -369,7 +376,7 @@ export const PluginDoorDimensions = z.object({
 })
 export type PluginDoorDimensions = z.infer<typeof PluginDoorDimensions>
 
-/** Mirror axis — tokens mirror the engine `FlipDirection` verbatim (§6.1). */
+/** 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>
 
@@ -379,7 +386,7 @@ export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
  * | Property | Type | Description |
  * |---|---|---|
  * | `door` | {@linkcode ComponentHandle} | The door to mirror |
- * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis) |
+ * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis) |
  */
 export const PluginDesignDoorMirrorArgs = z.object({
   door: ComponentHandle,