@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/dist/api/design/query/spaces.d.ts

@@ -66,6 +66,52 @@ export declare abstract class PluginDesignQuerySpacesApi {
      * ```
      */
     abstract getFootprint(space: ComponentHandle): PluginApiReturn<ContourHandle | null>;
+    /**
+     * Get the **enclosure** of a space — the floor and ceiling that cap it, the
+     * bounding walls around it (with each wall's door/window openings), and the
+     * neighbouring spaces it shares a boundary with.
+     *
+     * **Geometric v1 — best effort.** The engine has no persisted space→surface
+     * topology, so this read is derived purely from *plan geometry*: the space
+     * footprint is matched against the plan footprints/baselines of the slabs and
+     * walls on the same storey. Consequences a caller must account for:
+     *
+     * - `faceIndices` is **always `[]`**. The triangle→B-rep-face provenance that
+     *   would populate it is a separate engine capability that does not exist yet;
+     *   read a surface's full geometry via
+     *   {@linkcode PluginDesignQueryGeometryApi.getBrep} on its `component` instead.
+     * - After heavy edits (move / stretch / boolean) or on imported models the plan
+     *   match can miss or mis-attribute a surface — treat the result as advisory,
+     *   not authoritative.
+     * - `adjacentSpaces` comes from the same adjacency data as
+     *   {@linkcode PluginProgramAdjacencyApi.getMatrix} (so the two agree on which
+     *   spaces neighbour). `sharedEdgeLength` is `0` because that data exposes no
+     *   edge length, and `sharedSurface` is the common boundary wall only when one
+     *   is found geometrically (else `null`).
+     *
+     * Read-only; never mutates the model.
+     *
+     * @param space - The space (room mass) to read
+     * @returns the {@linkcode PluginSpaceEnclosure}, or `null` when `space` is not a
+     *   space (room mass) or has no extractable plan footprint
+     *
+     * @examplePrompt What walls, floor and ceiling enclose this room?
+     * @examplePrompt Which of this room's walls are external?
+     * @examplePrompt List the doors and windows around the selected space
+     * @examplePrompt Which spaces are adjacent to this room, and through which wall?
+     *
+     * # Example
+     * ```ts
+     * const [space] = await snaptrude.design.query.listSpaces()
+     * const enclosure = await snaptrude.design.query.spaces.getEnclosure(space)
+     * if (enclosure) {
+     *   const walls = enclosure.surfaces.filter((s) => s.role === "wall")
+     *   const external = walls.filter((s) => s.isExternal)
+     *   console.log(`${walls.length} walls, ${external.length} external`)
+     * }
+     * ```
+     */
+    abstract getEnclosure(space: ComponentHandle): PluginApiReturn<PluginSpaceEnclosure | null>;
 }
 /**
  * Arguments for {@linkcode PluginDesignQuerySpacesApi.getFootprint}.
@@ -87,9 +133,10 @@ export type PluginDesignQueryGetFootprintArgs = z.infer<typeof PluginDesignQuery
 export declare const PluginDesignQuerySpacesGetProperty: z.ZodEnum<{
     profile: "profile";
     type: "type";
-    position: "position";
     id: "id";
+    position: "position";
     name: "name";
+    storey: "storey";
     height: "height";
     depth: "depth";
     innerProfiles: "innerProfiles";
@@ -99,7 +146,6 @@ export declare const PluginDesignQuerySpacesGetProperty: z.ZodEnum<{
     massType: "massType";
     spaceType: "spaceType";
     areaClass: "areaClass";
-    storey: "storey";
     departmentId: "departmentId";
     departmentName: "departmentName";
     departmentColor: "departmentColor";
@@ -123,9 +169,10 @@ export declare const PluginDesignQuerySpacesGetArgs: z.ZodObject<{
     properties: z.ZodArray<z.ZodEnum<{
         profile: "profile";
         type: "type";
-        position: "position";
         id: "id";
+        position: "position";
         name: "name";
+        storey: "storey";
         height: "height";
         depth: "depth";
         innerProfiles: "innerProfiles";
@@ -135,7 +182,6 @@ export declare const PluginDesignQuerySpacesGetArgs: z.ZodObject<{
         massType: "massType";
         spaceType: "spaceType";
         areaClass: "areaClass";
-        storey: "storey";
         departmentId: "departmentId";
         departmentName: "departmentName";
         departmentColor: "departmentColor";
@@ -153,18 +199,19 @@ export type PluginDesignQuerySpacesGetArgs = z.infer<typeof PluginDesignQuerySpa
  * requested properties are present.
  */
 export declare const PluginDesignQuerySpacesGetResult: z.ZodObject<{
-    profile: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../../..").Handle<"line">, string>>, z.ZodPipe<z.ZodString, z.ZodTransform<import("../../..").Handle<"arc">, string>>]>>>;
+    profile: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"line">, string>>, z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"arc">, string>>]>>>;
     type: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
     position: z.ZodOptional<z.ZodObject<{
         x: z.ZodNumber;
         y: z.ZodNumber;
         z: z.ZodNumber;
     }, z.core.$strip>>;
-    id: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
+    storey: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     height: z.ZodOptional<z.ZodNumber>;
     depth: z.ZodOptional<z.ZodNumber>;
-    innerProfiles: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../../..").Handle<"line">, string>>, z.ZodPipe<z.ZodString, z.ZodTransform<import("../../..").Handle<"arc">, string>>]>>>>;
+    innerProfiles: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"line">, string>>, z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"arc">, string>>]>>>>;
     room_type: z.ZodOptional<z.ZodString>;
     area: z.ZodOptional<z.ZodNumber>;
     breadth: z.ZodOptional<z.ZodNumber>;
@@ -186,7 +233,6 @@ export declare const PluginDesignQuerySpacesGetResult: z.ZodObject<{
         GROSS: "GROSS";
         EXCLUDED: "EXCLUDED";
     }>>;
-    storey: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     departmentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     departmentName: z.ZodOptional<z.ZodString>;
     departmentColor: z.ZodOptional<z.ZodString>;
@@ -218,4 +264,131 @@ export declare const PluginDesignQuerySpacesGetResult: z.ZodObject<{
     }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type PluginDesignQuerySpacesGetResult = z.infer<typeof PluginDesignQuerySpacesGetResult>;
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.getEnclosure}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ */
+export declare const PluginDesignQuerySpacesGetEnclosureArgs: z.ZodObject<{
+    space: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+}, z.core.$strip>;
+export type PluginDesignQuerySpacesGetEnclosureArgs = z.infer<typeof PluginDesignQuerySpacesGetEnclosureArgs>;
+/**
+ * The role a bounding surface plays in a {@linkcode PluginSpaceEnclosure}:
+ * `"floor"` (slab below), `"ceiling"` (slab/roof above), or `"wall"`.
+ */
+export declare const PluginEnclosureRole: z.ZodEnum<{
+    floor: "floor";
+    wall: "wall";
+    ceiling: "ceiling";
+}>;
+export type PluginEnclosureRole = z.infer<typeof PluginEnclosureRole>;
+/** The kind of opening hosted in a bounding wall. */
+export declare const PluginEnclosureOpeningKind: z.ZodEnum<{
+    void: "void";
+    door: "door";
+    window: "window";
+}>;
+export type PluginEnclosureOpeningKind = z.infer<typeof PluginEnclosureOpeningKind>;
+/**
+ * One opening (door / window / void) in a bounding wall.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginEnclosureOpeningKind} | `"door"`, `"window"`, or `"void"` |
+ * | `component` | {@linkcode ComponentHandle} | The opening entity |
+ */
+export declare const PluginEnclosureOpening: z.ZodObject<{
+    kind: z.ZodEnum<{
+        void: "void";
+        door: "door";
+        window: "window";
+    }>;
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+}, z.core.$strip>;
+export type PluginEnclosureOpening = z.infer<typeof PluginEnclosureOpening>;
+/**
+ * One bounding surface of a space's enclosure.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `role` | {@linkcode PluginEnclosureRole} | `"floor"`, `"ceiling"`, or `"wall"` |
+ * | `component` | {@linkcode ComponentHandle} | The wall / slab / roof entity |
+ * | `faceIndices` | `number[]` | B-rep face indices facing the space. **Always `[]` in geometric v1** (no triangle→face provenance yet) |
+ * | `isExternal` | `boolean` | No space on the other side — for a wall, no other room bounds it; for a floor/ceiling, no room caps the storey below/above |
+ * | `openings` | {@linkcode PluginEnclosureOpening}`[]` | Doors/windows/voids in the surface (walls only; `[]` for floor/ceiling in v1) |
+ */
+export declare const PluginEnclosureSurface: z.ZodObject<{
+    role: z.ZodEnum<{
+        floor: "floor";
+        wall: "wall";
+        ceiling: "ceiling";
+    }>;
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    faceIndices: z.ZodArray<z.ZodNumber>;
+    isExternal: z.ZodBoolean;
+    openings: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            void: "void";
+            door: "door";
+            window: "window";
+        }>;
+        component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginEnclosureSurface = z.infer<typeof PluginEnclosureSurface>;
+/**
+ * A space that neighbours the queried space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The neighbouring space |
+ * | `sharedSurface` | {@linkcode ComponentHandle}` \| null` | The common boundary wall when one is found geometrically, else `null` (e.g. an open-plan or non-physical adjacency) |
+ * | `sharedEdgeLength` | `number` | Plan-unit length of the shared boundary — **always `0` in geometric v1** (the adjacency data exposes no edge length) |
+ */
+export declare const PluginAdjacentSpace: z.ZodObject<{
+    space: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    sharedSurface: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    sharedEdgeLength: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginAdjacentSpace = z.infer<typeof PluginAdjacentSpace>;
+/**
+ * Result of {@linkcode PluginDesignQuerySpacesApi.getEnclosure} — the geometric
+ * v1 enclosure of a space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The queried space |
+ * | `surfaces` | {@linkcode PluginEnclosureSurface}`[]` | Floor + ceiling + bounding walls, as a flat list (any of the three may be absent when no plan match is found) |
+ * | `adjacentSpaces` | {@linkcode PluginAdjacentSpace}`[]` | Neighbouring spaces from the adjacency data (`[]` when adjacency was never computed) |
+ */
+export declare const PluginSpaceEnclosure: z.ZodObject<{
+    space: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    surfaces: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            floor: "floor";
+            wall: "wall";
+            ceiling: "ceiling";
+        }>;
+        component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        faceIndices: z.ZodArray<z.ZodNumber>;
+        isExternal: z.ZodBoolean;
+        openings: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                void: "void";
+                door: "door";
+                window: "window";
+            }>;
+            component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    adjacentSpaces: z.ZodArray<z.ZodObject<{
+        space: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        sharedSurface: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+        sharedEdgeLength: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginSpaceEnclosure = z.infer<typeof PluginSpaceEnclosure>;
 //# sourceMappingURL=spaces.d.ts.map

package/dist/api/design/query/spaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spaces.d.ts","sourceRoot":"","sources":["../../../../src/api/design/query/spaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGjE;;;;;;;;;;;GAWG;AACH,8BAAsB,0BAA0B;;IAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;aACa,GAAG,CACjB,KAAK,EAAE,eAAe,EACtB,UAAU,EAAE,8BAA8B,CAAC,YAAY,CAAC,GACvD,eAAe,CAAC,gCAAgC,CAAC;IAEpD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,YAAY,CAC1B,KAAK,EAAE,eAAe,GACrB,eAAe,CAAC,aAAa,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC;;iBAE5C,CAAA;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CACrD,OAAO,iCAAiC,CACzC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;EACA,CAAA;AAC/C,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CACtD,OAAO,kCAAkC,CAC1C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAE3C,CAAA;AACF,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CACpD,OAAO,gCAAgC,CACxC,CAAA"}
+{"version":3,"file":"spaces.d.ts","sourceRoot":"","sources":["../../../../src/api/design/query/spaces.ts"],"names":[],"mappings":"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"}

package/dist/api/design/selection/index.d.ts

@@ -2,6 +2,109 @@ import * as z from "zod";
 import { PluginApiReturn } from "../../../types";
 import { ComponentHandle } from "../../../handles";
 import { PluginDesignChangeResult } from "../lock";
+/**
+ * The entity kinds {@linkcode PluginDesignSelectionApi.setByFilter} can select —
+ * the union of the editor's "Filter selection" menus (Design tab + BIM tab).
+ * Tokens mirror {@linkcode PluginEntityType} where a kind exists on the query
+ * surface; the rest are selection-only kinds the query surface cannot reach
+ * (layer-backed and annotation objects).
+ *
+ * | Value | Entity (menu label) |
+ * |---|---|
+ * | `"wall"` | Wall |
+ * | `"slab"` | Floor slab |
+ * | `"floor"` | Flooring |
+ * | `"door"` | Door |
+ * | `"window"` | Window |
+ * | `"beam"` | Beam |
+ * | `"column"` | Column |
+ * | `"ceiling"` | Ceiling |
+ * | `"roof"` | Roof |
+ * | `"staircase"` | Staircase |
+ * | `"furniture"` | Furniture |
+ * | `"pergola"` | Pergola |
+ * | `"sunshade"` | Sunshade |
+ * | `"referenceLine"` | Reference line |
+ * | `"space"` | Space (room mass) |
+ * | `"site"` | Site |
+ * | `"terrain"` | Terrain |
+ * | `"cad"` | CAD import |
+ * | `"pdf"` | PDF import |
+ * | `"image"` | Image import |
+ * | `"dimensionLine"` | Dimension line |
+ * | `"model3d"` | Imported 3D model |
+ * | `"neighborhoodBuilding"` | Neighborhood building |
+ * | `"programBlock"` | Program block (department mass) |
+ */
+export declare const PluginSelectionEntityType: z.ZodEnum<{
+    terrain: "terrain";
+    floor: "floor";
+    wall: "wall";
+    ceiling: "ceiling";
+    image: "image";
+    cad: "cad";
+    pdf: "pdf";
+    door: "door";
+    window: "window";
+    furniture: "furniture";
+    space: "space";
+    slab: "slab";
+    roof: "roof";
+    column: "column";
+    beam: "beam";
+    staircase: "staircase";
+    referenceLine: "referenceLine";
+    pergola: "pergola";
+    sunshade: "sunshade";
+    site: "site";
+    dimensionLine: "dimensionLine";
+    model3d: "model3d";
+    neighborhoodBuilding: "neighborhoodBuilding";
+    programBlock: "programBlock";
+}>;
+export type PluginSelectionEntityType = z.infer<typeof PluginSelectionEntityType>;
+/**
+ * The filter for {@linkcode PluginDesignSelectionApi.setByFilter}. At least one
+ * field must be non-empty (to empty the selection use
+ * {@linkcode PluginDesignSelectionApi.clear}). Fields **AND**-combine; values
+ * within a field **OR**-combine — `{ storeys: [2], types: ["furniture"] }`
+ * selects only the furniture on storey 2.
+ *
+ * | Field | Type | Selects entities where |
+ * |---|---|---|
+ * | `storeys` | `number[]` | storey/floor level ∈ `storeys` (negative = basement) |
+ * | `types` | {@linkcode PluginSelectionEntityType}`[]` | entity kind ∈ `types` |
+ */
+export declare const PluginSelectionFilter: z.ZodObject<{
+    storeys: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        terrain: "terrain";
+        floor: "floor";
+        wall: "wall";
+        ceiling: "ceiling";
+        image: "image";
+        cad: "cad";
+        pdf: "pdf";
+        door: "door";
+        window: "window";
+        furniture: "furniture";
+        space: "space";
+        slab: "slab";
+        roof: "roof";
+        column: "column";
+        beam: "beam";
+        staircase: "staircase";
+        referenceLine: "referenceLine";
+        pergola: "pergola";
+        sunshade: "sunshade";
+        site: "site";
+        dimensionLine: "dimensionLine";
+        model3d: "model3d";
+        neighborhoodBuilding: "neighborhoodBuilding";
+        programBlock: "programBlock";
+    }>>>;
+}, z.core.$strip>;
+export type PluginSelectionFilter = z.infer<typeof PluginSelectionFilter>;
 /**
  * `snaptrude.design.selection` — read and mutate the current scene selection.
  *
@@ -115,6 +218,47 @@ export declare abstract class PluginDesignSelectionApi {
      * ```
      */
     abstract clear(): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Replace the selection with every visible entity of the active building that
+     * matches the filter — the programmatic equivalent of the editor's
+     * **Story selection** (`storeys`) and **Filter selection** (`types`) menus
+     * under the select tool, including their combination (fields AND, values
+     * within a field OR). Reaches selection-only kinds the query surface cannot
+     * (sites, terrain, CAD/PDF/image imports, dimension lines, 3D models,
+     * neighborhood buildings) and selects whole groups the way the editor does.
+     *
+     * This is a one-shot bulk select, not a persistent mode: the user's next
+     * canvas click resets the underlying filter state (the selection it made
+     * stays until changed). Results honor the ambient view — active building,
+     * hidden objects/buckets, and in 2D the active storey.
+     *
+     * @param filter Which entities to select — {@linkcode PluginSelectionFilter};
+     *   at least one field must be non-empty
+     * @returns The resulting selection snapshot
+     *
+     * @examplePrompt Select everything on storey 2
+     * @examplePrompt Select all the walls and doors
+     * @examplePrompt Story selection: select the ground floor and first floor
+     * @examplePrompt Filter selection: select all furniture in the model
+     * @examplePrompt Select only the furniture on the second storey
+     * @examplePrompt Select all the spaces so I can recolor them
+     *
+     * # Example
+     * ```ts
+     * // "Story selection": everything on storeys 1 and 2
+     * await snaptrude.design.selection.setByFilter({ storeys: [1, 2] })
+     *
+     * // "Filter selection": all walls and doors
+     * await snaptrude.design.selection.setByFilter({ types: ["wall", "door"] })
+     *
+     * // Combined: only the furniture on storey 2
+     * const { affected } = await snaptrude.design.selection.setByFilter({
+     *   storeys: [2],
+     *   types: ["furniture"],
+     * })
+     * ```
+     */
+    abstract setByFilter(filter: PluginSelectionFilter): PluginApiReturn<PluginDesignChangeResult>;
 }
 /**
  * Arguments for {@linkcode PluginDesignSelectionApi.set}.

package/dist/api/design/selection/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/design/selection/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAElD;;;;;;;;GAQG;AACH,8BAAsB,wBAAwB;;IAG5C;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,GAAG,IAAI,eAAe,CAAC,eAAe,EAAE,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,GAAG,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,eAAe,CAAC,wBAAwB,CAAC;IAE7F;;;;;;;;;;;;;;;;;;;OAmBG;aACa,GAAG,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,eAAe,CAAC,wBAAwB,CAAC;IAE7F;;;;;;;;;;;;;;;;;;OAkBG;aACa,MAAM,CACpB,UAAU,EAAE,eAAe,EAAE,GAC5B,eAAe,CAAC,wBAAwB,CAAC;IAE5C;;;;;;;;;;;;;;;OAeG;aACa,KAAK,IAAI,eAAe,CAAC,wBAAwB,CAAC;CACnE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF,eAAO,MAAM,4BAA4B;;iBAA+B,CAAA;AACxE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF,eAAO,MAAM,+BAA+B;;iBAA+B,CAAA;AAC3E,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/design/selection/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;EAyBpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQ9B,CAAA;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;;GAQG;AACH,8BAAsB,wBAAwB;;IAG5C;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,GAAG,IAAI,eAAe,CAAC,eAAe,EAAE,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,GAAG,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,eAAe,CAAC,wBAAwB,CAAC;IAE7F;;;;;;;;;;;;;;;;;;;OAmBG;aACa,GAAG,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,eAAe,CAAC,wBAAwB,CAAC;IAE7F;;;;;;;;;;;;;;;;;;OAkBG;aACa,MAAM,CACpB,UAAU,EAAE,eAAe,EAAE,GAC5B,eAAe,CAAC,wBAAwB,CAAC;IAE5C;;;;;;;;;;;;;;;OAeG;aACa,KAAK,IAAI,eAAe,CAAC,wBAAwB,CAAC;IAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;aACa,WAAW,CACzB,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAAC,wBAAwB,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF,eAAO,MAAM,4BAA4B;;iBAA+B,CAAA;AACxE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF,eAAO,MAAM,+BAA+B;;iBAA+B,CAAA;AAC3E,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA"}

package/dist/api/design/transform/index.d.ts

@@ -5,11 +5,13 @@ import { PluginDesignChangeResult } from "../lock";
 /**
  * `snaptrude.design.transform` — rigid transforms on scene entities.
  *
- * Migrated from the removed `tools.transform.*`. All ops are undoable and return
+ * `move` / `rotate` migrated from the removed `tools.transform.*`; `align` snaps a
+ * set of components' bounding-box edges to each other (or to a reference); `mirror`
+ * flips components in place about a horizontal axis. All ops are undoable and return
  * {@linkcode PluginDesignChangeResult} `{ affected }`; failures throw (RPC rejects).
  *
- * `mirror` / `getPosition` / `setPosition` (and `scale`, an engine gap) are NOT in
- * this surface yet — they are a later, non-migration pass.
+ * `getPosition` / `setPosition` (and `scale`, an engine gap) are NOT in this surface
+ * yet — they are a later pass.
  */
 export declare abstract class PluginDesignTransformApi {
     constructor();
@@ -28,6 +30,9 @@ export declare abstract class PluginDesignTransformApi {
      * @examplePrompt Translate the furniture block by (10, 0, 5)
      * @examplePrompt Move these masses up one storey
      *
+     * @performance Array API — one host round-trip for the whole set. Pass every target in a
+     *   single call; never loop `design.transform.move` per entity.
+     *
      * # Example
      * ```ts
      * const { vec3 } = snaptrude.core.math
@@ -39,37 +44,155 @@ export declare abstract class PluginDesignTransformApi {
         trackParentChange?: boolean;
     }): PluginApiReturn<PluginDesignChangeResult>;
     /**
-     * Rotate entities by a **signed angle in DEGREES**, anchored at the combined
-     * bounding-box centre (positive = CCW about +Y). NOTE: unlike the removed
-     * `tools.transform.rotate` (radians + caller pivot), this canonical form takes
-     * DEGREES and has NO caller pivot — the pivot is always the bbox centre. Undoable.
+     * Rotate entities by a **signed angle in DEGREES** (positive = CCW about +Y).
+     * The pivot defaults to the combined bounding-box centre; pass `options.pivot`
+     * to rotate about an explicit world-space point instead. NOTE: unlike the
+     * removed `tools.transform.rotate` (radians), this canonical form takes
+     * DEGREES. Undoable.
      *
      * @param components - Entities to rotate
      * @param angleInDegrees - Signed rotation angle in degrees
-     * @param options - `axis` (defaults to world +Y), `is2D`
+     * @param options - `axis` (defaults to world +Y), `pivot` (world-space rotation
+     *   centre as a {@linkcode Vec3Handle}; defaults to the combined bbox centre),
+     *   `is2D`
      * @returns {@linkcode PluginDesignChangeResult}
      *
      * @examplePrompt Rotate the selected building 90 degrees
      * @examplePrompt Turn this room 45 degrees clockwise
      * @examplePrompt Spin the furniture block 180 degrees about its centre
      * @examplePrompt Rotate these masses 30 degrees around the vertical axis
+     * @examplePrompt Rotate these walls 90 degrees about the origin
+     *
+     * @performance Array API — one host round-trip for the whole set. Pass every target in a
+     *   single call; never loop `design.transform.rotate` per entity.
      *
      * # Example
      * ```ts
      * await snaptrude.design.transform.rotate(["space-id"], 90)
+     * // …or rotate about an explicit pivot point
+     * const { vec3 } = snaptrude.core.math
+     * await snaptrude.design.transform.rotate(["space-id"], 90, { pivot: vec3.new(0, 0, 0) })
      * ```
      */
     abstract rotate(components: ComponentHandle[], angleInDegrees: number, options?: {
         axis?: Vec3Handle;
+        pivot?: Vec3Handle;
         is2D?: boolean;
     }): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Align a set of components by snapping one bounding-box edge to a common value
+     * — the classic Left/Center/Right/Top/Middle/Bottom align. Purely **world-axis**
+     * (deterministic and headless — the UI's camera-relative remap is bypassed):
+     *
+     * - `left` / `right` / `center` → world **X** min / max / mid
+     * - `top` / `bottom` / `middle` → world **Z** max / min / mid
+     *
+     * There is **no vertical (Y) alignment** in v1 (the UI only reaches it via a
+     * side-elevation camera remap, which this API does not replicate). Doors and
+     * windows are **rejected** in v1 — if any component in `components` (or the
+     * `reference`) is a door or window, the whole call **throws**; nothing is
+     * silently dropped. A group aligns as **one rigid body** (its whole-group
+     * bounding box moves together). Undoable.
+     *
+     * Requires **at least 2 components** unless a `reference` is supplied; with a
+     * reference, every component aligns to that reference's edge (the reference does
+     * not move) and a single component is allowed. Y (height) is preserved.
+     *
+     * @param components - Entities to align (≥2 without a `reference`)
+     * @param edge - Which bounding-box edge to snap ({@linkcode PluginAlignEdge})
+     * @param options - `reference`: a component whose edge is the fixed target
+     * @returns {@linkcode PluginDesignChangeResult}
+     *
+     * @examplePrompt Align the selected rooms to the left
+     * @examplePrompt Line up these masses along their top edges
+     * @examplePrompt Center these columns horizontally
+     * @examplePrompt Align all the walls to the left edge of this reference wall
+     * @examplePrompt Snap the bottom edges of these spaces together
+     *
+     * @performance Array API — one host round-trip for the whole set. Pass every target in a
+     *   single call; never loop `design.transform.align` per entity.
+     *
+     * # Example
+     * ```ts
+     * const rooms = await snaptrude.design.selection.get()
+     * // align every room's left (world -X) edge to a common minimum
+     * await snaptrude.design.transform.align(rooms, "left")
+     * // …or align them to a fixed reference component's left edge
+     * const [anchor] = await snaptrude.design.query.listWalls({ storeys: [1] })
+     * await snaptrude.design.transform.align(rooms, "left", { reference: anchor })
+     * ```
+     */
+    abstract align(components: ComponentHandle[], edge: PluginAlignEdge, options?: {
+        reference?: ComponentHandle;
+    }): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Mirror components **in place** about a horizontal axis, flipping their geometry
+     * across that axis through the combined bounding-box centre (the mesh's
+     * world-matrix flip + brep inversion + CAD/dimension-line/parametric handling
+     * commit atomically). Nothing moves off-centre — this is the toolbar "flip", not
+     * a translate-and-reflect. Undoable.
+     *
+     * `axis` names the axis the geometry mirrors **across** (world axes, Y is up):
+     * - `'x'` — mirror across world X (a front↔back flip in plan; reflects the Z coord)
+     * - `'z'` — mirror across world Z (a left↔right flip in plan; reflects the X coord)
+     *
+     * Vertical (`'y'`) mirroring is intentionally not exposed. Locked, bucket-locked
+     * and ineligible entries (terrain, plinths, reference/dimension lines,
+     * neighbourhood buildings) are **silently dropped**; the call only throws if
+     * nothing mirrorable remains. `affected` echoes the supplied handles.
+     *
+     * @param components - Entities to mirror (≥1)
+     * @param axis - Axis to mirror across ({@linkcode PluginTransformMirrorAxis})
+     * @returns {@linkcode PluginDesignChangeResult}
+     *
+     * @examplePrompt Mirror the selected building across the x axis
+     * @examplePrompt Flip these rooms left to right
+     * @examplePrompt Mirror this furniture block horizontally
+     * @examplePrompt Flip the selected walls front to back
+     * @examplePrompt Create a mirror image of these masses about the z axis
+     *
+     * @performance Array API — one host round-trip for the whole set. Pass every target in a
+     *   single call; never loop `design.transform.mirror` per entity.
+     *
+     * # Example
+     * ```ts
+     * const rooms = await snaptrude.design.selection.get()
+     * await snaptrude.design.transform.mirror(rooms, "x")
+     * ```
+     */
+    abstract mirror(components: ComponentHandle[], axis: PluginTransformMirrorAxis): PluginApiReturn<PluginDesignChangeResult>;
 }
+/**
+ * The horizontal axis a {@linkcode PluginDesignTransformApi.mirror} flips **across**
+ * (world axes, Y up): `'x'` mirrors across world X (front↔back in plan; reflects Z),
+ * `'z'` mirrors across world Z (left↔right in plan; reflects X). Vertical (`'y'`)
+ * mirroring is not exposed.
+ */
+export declare const PluginTransformMirrorAxis: z.ZodEnum<{
+    x: "x";
+    z: "z";
+}>;
+export type PluginTransformMirrorAxis = z.infer<typeof PluginTransformMirrorAxis>;
+/**
+ * The bounding-box edge an {@linkcode PluginDesignTransformApi.align} snaps to.
+ * Mirrors the engine's align `DirectionType`. World-axis mapping: `left`/`right`/`center`
+ * → world X min/max/mid; `top`/`bottom`/`middle` → world Z max/min/mid.
+ */
+export declare const PluginAlignEdge: z.ZodEnum<{
+    center: "center";
+    top: "top";
+    left: "left";
+    right: "right";
+    bottom: "bottom";
+    middle: "middle";
+}>;
+export type PluginAlignEdge = z.infer<typeof PluginAlignEdge>;
 /**
  * Arguments for {@linkcode PluginDesignTransformApi.move} (options flattened).
  */
 export declare const PluginDesignMoveArgs: z.ZodObject<{
     components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
-    displacement: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
+    displacement: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
     is2D: z.ZodOptional<z.ZodBoolean>;
     trackParentChange: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
@@ -80,8 +203,47 @@ export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>;
 export declare const PluginDesignRotateArgs: z.ZodObject<{
     components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
     angleInDegrees: z.ZodNumber;
-    axis: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
+    axis: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
     is2D: z.ZodOptional<z.ZodBoolean>;
+    pivot: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
 }, z.core.$strip>;
 export type PluginDesignRotateArgs = z.infer<typeof PluginDesignRotateArgs>;
+/**
+ * Arguments for {@linkcode PluginDesignTransformApi.align} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to align (≥2 unless `reference` is set — host-enforced) |
+ * | `edge` | {@linkcode PluginAlignEdge} | Which bounding-box edge to snap |
+ * | `reference` | {@linkcode ComponentHandle} | A fixed component whose edge is the target (optional) |
+ */
+export declare const PluginDesignAlignArgs: z.ZodObject<{
+    components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    edge: z.ZodEnum<{
+        center: "center";
+        top: "top";
+        left: "left";
+        right: "right";
+        bottom: "bottom";
+        middle: "middle";
+    }>;
+    reference: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+}, z.core.$strip>;
+export type PluginDesignAlignArgs = z.infer<typeof PluginDesignAlignArgs>;
+/**
+ * Arguments for {@linkcode PluginDesignTransformApi.mirror}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to mirror (≥1) |
+ * | `axis` | {@linkcode PluginTransformMirrorAxis} | Horizontal axis to mirror across (`'x'` \| `'z'`) |
+ */
+export declare const PluginDesignMirrorArgs: z.ZodObject<{
+    components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    axis: z.ZodEnum<{
+        x: "x";
+        z: "z";
+    }>;
+}, z.core.$strip>;
+export type PluginDesignMirrorArgs = z.infer<typeof PluginDesignMirrorArgs>;
 //# sourceMappingURL=index.d.ts.map