@snaptrude/plugin-core 0.9.7 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,17 +16,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "ts-morph": "^28.0.0",
-    "tsup": "^8.5.1",
-    "typescript": "^5.5.4"
-  },
-  "dependencies": {
-    "zod": "^4.3.6"
-  },
-  "peerDependencies": {
-    "zod": "^3.25.0 || ^4.0.0"
-  },
   "scripts": {
     "check-types": "tsc --noEmit",
     "build": "tsup --clean",
@@ -37,5 +26,16 @@
     "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
     "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
     "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
+  },
+  "devDependencies": {
+    "ts-morph": "^28.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
   }
-}
+}

package/src/api/core/tags.ts

@@ -163,6 +163,40 @@ export abstract class PluginCoreTagsApi {
     componentId: ComponentHandle,
   ): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>
 
+  /**
+   * List the tags carried by many components in one call.
+   *
+   * The plural of {@linkcode PluginCoreTagsApi.listForComponent}: pass
+   * `componentIds` to read specific components (unknown ids are skipped), or
+   * omit it to read **every** taggable component (Mass/Floor space) in the
+   * project. Each entry carries the component id and its tags — one per tagged
+   * category, with the tag's `color` — so a plugin can color every space by a
+   * chosen category's tag in a single round-trip.
+   *
+   * @param componentIds - Optional `Component.id`s to read; omit for all spaces.
+   * @returns A {@linkcode PluginCoreTagsListForComponentsResult} with a
+   *   `components` array, one entry per component (in input order when
+   *   `componentIds` is given).
+   *
+   * @performance One round-trip for any number of components — use this instead of a `listForComponent` loop.
+   *
+   * @examplePrompt Get the tags of every space with their colors
+   * @examplePrompt List the tags on all rooms so I can color them by Occupancy
+   * @examplePrompt Which tag does each selected space carry?
+   *
+   * # Example
+   * ```ts
+   * const { components } = await snaptrude.core.tags.listForComponents()
+   * for (const c of components) {
+   *   const occupancy = c.tags.find((t) => t.categoryName === "Occupancy")
+   *   if (occupancy) paint(c.componentId, occupancy.color)
+   * }
+   * ```
+   */
+  public abstract listForComponents(
+    componentIds?: ComponentHandle[],
+  ): PluginApiReturn<PluginCoreTagsListForComponentsResult>
+
   /**
    * List the components carrying a given tag or category.
    *
@@ -588,6 +622,48 @@ export type PluginCoreTagsGetTagsForComponentResult = z.infer<
   typeof PluginCoreTagsGetTagsForComponentResult
 >
 
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]?` | Components to read; omit for every taggable component |
+ */
+export const PluginCoreTagsListForComponentsArgs = z.object({
+  componentIds: z.array(ComponentHandle).optional(),
+})
+export type PluginCoreTagsListForComponentsArgs = z.infer<
+  typeof PluginCoreTagsListForComponentsArgs
+>
+
+/**
+ * One component's tags, for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The component's id |
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | Its tags, one per tagged category (empty when none) |
+ */
+export const PluginCoreComponentTags = z.object({
+  componentId: ComponentHandle,
+  tags: z.array(PluginCoreComponentTag),
+})
+export type PluginCoreComponentTags = z.infer<typeof PluginCoreComponentTags>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode PluginCoreComponentTags}`[]` | One entry per component |
+ */
+export const PluginCoreTagsListForComponentsResult = z.object({
+  components: z.array(PluginCoreComponentTags),
+})
+export type PluginCoreTagsListForComponentsResult = z.infer<
+  typeof PluginCoreTagsListForComponentsResult
+>
+
 /**
  * Arguments for {@linkcode PluginCoreTagsApi.listComponents}. Provide exactly one
  * of `tagId`, `categoryId`. `untagged` is valid only with `categoryId`.

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,

package/src/api/program/departments.ts

@@ -7,7 +7,7 @@ import { ComponentHandle } from "../../handles"
  * Program departments — read the department groupings of the active program.
  *
  * In program mode a **department** is a named, colored grouping of spaces with an
- * optional area **target**. This is the program-planning view of departments
+ * optional gross area **target** and a unit **count** target. This is the program-planning view of departments
  * (their identity, color, and target area); the underlying space geometry is read
  * and edited through the geometry namespaces, not here.
  *
@@ -203,6 +203,33 @@ export abstract class PluginProgramDepartmentsApi {
     units?: PluginAreaUnit,
   ): PluginApiReturn<PluginProgramDepartmentsSetTargetAreaResult>
 
+  /**
+   * Set a department's target unit count.
+   *
+   * The number of units (program blocks) the department is planned for — the
+   * count twin of {@linkcode PluginProgramDepartmentsApi.setTargetArea}, stored
+   * beside the gross area target on the department. Read it back from
+   * {@linkcode PluginProgramDepartmentsApi.get} (`targetCount`).
+   *
+   * @param departmentId - The id of the department whose count to set.
+   * @param targetCount - The target number of units (a non-negative integer).
+   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Set the Bedrooms department unit count to 12
+   * @examplePrompt The program needs 4 clinic blocks — update the department count
+   * @examplePrompt Update the target count for department dep_123
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.setTargetCount("dep_123", 12)
+   * ```
+   */
+  public abstract setTargetCount(
+    departmentId: string,
+    targetCount: number,
+  ): PluginApiReturn<PluginProgramDepartmentsSetTargetCountResult>
+
   /**
    * Delete a department.
    *
@@ -239,13 +266,15 @@ export abstract class PluginProgramDepartmentsApi {
  * | `id` | `string` | Unique department id |
  * | `name` | `string` | Display name |
  * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
- * | `targetArea` | `number \| null` | Target area in the response's `units`, or `null` if no target is set |
+ * | `targetArea` | `number \| null` | Gross target area in the response's `units`, or `null` if no target is set |
+ * | `targetCount` | `number` | Target number of units / program blocks (`0` when unset) |
  */
 export const PluginProgramDepartment = z.object({
   id: z.string(),
   name: z.string(),
   color: z.string(),
   targetArea: z.number().nullable(),
+  targetCount: z.number(),
 })
 export type PluginProgramDepartment = z.infer<typeof PluginProgramDepartment>
 
@@ -434,6 +463,29 @@ export type PluginProgramDepartmentsSetTargetAreaResult = z.infer<
   typeof PluginProgramDepartmentsSetTargetAreaResult
 >
 
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetCount}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department whose count to set |
+ * | `targetCount` | `number` | Target number of units (non-negative integer) |
+ */
+export const PluginProgramDepartmentsSetTargetCountArgs = z.object({
+  departmentId: z.string(),
+  targetCount: z.number().int().nonnegative(),
+})
+export type PluginProgramDepartmentsSetTargetCountArgs = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.setTargetCount} — the updated record with `units`. */
+export const PluginProgramDepartmentsSetTargetCountResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsSetTargetCountResult = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountResult
+>
+
 /**
  * Arguments for {@linkcode PluginProgramDepartmentsApi.delete}.
  *

package/src/api/program/index.ts

@@ -7,22 +7,26 @@ import { PluginProgramSiteApi } from "./site"
 import { PluginProgramCoresApi } from "./cores"
 import { PluginProgramClassificationApi } from "./classification"
 import { PluginProgramAreasApi } from "./areas"
+import { PluginProgramMetadataApi } from "./metadata"
+import { PluginProgramLabelsApi } from "./labels"
 
 /**
  * Program-mode planning APIs.
  *
  * The program is the space-planning layer: department groupings with area targets,
- * the metrics that track allocated area against those targets, and the reports
- * that render program/takeoff data to spreadsheet sheets. Reads describe the
- * *plan* (intent + targets); the geometry that realizes the plan is authored
- * through the geometry namespaces.
+ * the labels (program rows) inside them, the metrics that track allocated area
+ * against those targets, and the reports that render program/takeoff data to
+ * spreadsheet sheets. Reads describe the *plan* (intent + targets); the geometry
+ * that realizes the plan is authored through the geometry namespaces.
  *
  * - {@linkcode PluginProgramApi.departments} — Read & edit program departments (groupings + targets)
+ * - {@linkcode PluginProgramApi.labels} — Read & edit program labels (program rows: per-type area/count targets)
+ * - {@linkcode PluginProgramApi.metadata} — Read & edit program metadata (custom columns) on spaces
  * - {@linkcode PluginProgramApi.adjacency} — Read & compute the department/space adjacency matrix
  * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope
  * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
  * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
- * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
+ * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets, custom grouped sheets, read back
  * - {@linkcode PluginProgramApi.site} — Read site/plot context and read/update Site Analysis
  * - {@linkcode PluginProgramApi.cores} — Read & predicate vertical-circulation cores (reads only)
  * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
@@ -32,6 +36,10 @@ import { PluginProgramAreasApi } from "./areas"
 export abstract class PluginProgramApi {
   /** Program departments — groupings, area targets, and space assignment. See {@linkcode PluginProgramDepartmentsApi}. */
   public abstract departments: PluginProgramDepartmentsApi
+  /** Program labels — the program rows with per-type area/count targets. See {@linkcode PluginProgramLabelsApi}. */
+  public abstract labels: PluginProgramLabelsApi
+  /** Program metadata — custom columns and their per-space values. See {@linkcode PluginProgramMetadataApi}. */
+  public abstract metadata: PluginProgramMetadataApi
   /** Adjacency matrix — read & compute proximity relationships. See {@linkcode PluginProgramAdjacencyApi}. */
   public abstract adjacency: PluginProgramAdjacencyApi
   /** Arrange/pack spaces in the envelope (async job family). See {@linkcode PluginProgramLayoutApi}. */
@@ -40,7 +48,7 @@ export abstract class PluginProgramApi {
   public abstract metrics: PluginProgramMetricsApi
   /** FAR / built-up-area rollup and groupings. See {@linkcode PluginProgramAreasApi}. */
   public abstract areas: PluginProgramAreasApi
-  /** Spreadsheet reports — render tables to sheets, export, list, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
+  /** Spreadsheet reports — render tables to sheets, custom grouped sheets, export, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
   public abstract spreadsheet: PluginProgramSpreadsheetApi
   /** Site/plot context and persisted Site Analysis. See {@linkcode PluginProgramSiteApi}. */
   public abstract site: PluginProgramSiteApi
@@ -61,3 +69,5 @@ export * from "./site"
 export * from "./cores"
 export * from "./classification"
 export * from "./areas"
+export * from "./metadata"
+export * from "./labels"