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

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

@@ -3,6 +3,91 @@ 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 const PluginSelectionEntityType = z.enum([
+  "wall",
+  "slab",
+  "floor",
+  "door",
+  "window",
+  "beam",
+  "column",
+  "ceiling",
+  "roof",
+  "staircase",
+  "furniture",
+  "pergola",
+  "sunshade",
+  "referenceLine",
+  "space",
+  "site",
+  "terrain",
+  "cad",
+  "pdf",
+  "image",
+  "dimensionLine",
+  "model3d",
+  "neighborhoodBuilding",
+  "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 const PluginSelectionFilter = z
+  .object({
+    storeys: z.array(z.number()).optional(),
+    types: z.array(PluginSelectionEntityType).optional(),
+  })
+  .refine((f) => (f.storeys?.length ?? 0) + (f.types?.length ?? 0) > 0, {
+    message:
+      "PluginSelectionFilter requires at least one non-empty field (storeys or types); use design.selection.clear() to deselect everything",
+  })
+export type PluginSelectionFilter = z.infer<typeof PluginSelectionFilter>
+
 /**
  * `snaptrude.design.selection` — read and mutate the current scene selection.
  *
@@ -123,6 +208,50 @@ export abstract class PluginDesignSelectionApi {
    * ```
    */
   public 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"],
+   * })
+   * ```
+   */
+  public abstract setByFilter(
+    filter: PluginSelectionFilter
+  ): PluginApiReturn<PluginDesignChangeResult>
 }
 
 /**

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

@@ -6,11 +6,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 abstract class PluginDesignTransformApi {
   constructor() {}
@@ -30,6 +32,9 @@ export 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
@@ -43,33 +48,158 @@ export abstract class PluginDesignTransformApi {
   ): 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) })
    * ```
    */
   public abstract rotate(
     components: ComponentHandle[],
     angleInDegrees: number,
-    options?: { axis?: Vec3Handle; is2D?: boolean },
+    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 })
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public 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 const PluginTransformMirrorAxis = z.enum(["x", "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 const PluginAlignEdge = z.enum([
+  "left",
+  "right",
+  "center",
+  "top",
+  "bottom",
+  "middle",
+])
+export type PluginAlignEdge = z.infer<typeof PluginAlignEdge>
+
 /**
  * Arguments for {@linkcode PluginDesignTransformApi.move} (options flattened).
  */
@@ -89,5 +219,36 @@ export const PluginDesignRotateArgs = z.object({
   angleInDegrees: z.number(),
   axis: Vec3Handle.optional(),
   is2D: z.boolean().optional(),
+  pivot: Vec3Handle.optional(),
 })
 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 const PluginDesignAlignArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  edge: PluginAlignEdge,
+  reference: ComponentHandle.optional(),
+})
+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 const PluginDesignMirrorArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  axis: PluginTransformMirrorAxis,
+})
+export type PluginDesignMirrorArgs = z.infer<typeof PluginDesignMirrorArgs>

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

@@ -0,0 +1,156 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * `snaptrude.design.types` — READ-ONLY reference over the project's building
+ * **type / assembly** system (the Project Properties layer stacks: External /
+ * Internal walls, slabs, floors, ceilings, roofs). A type bundles a labelled
+ * layer stack — each layer's role, thickness (engine units) and material — plus a
+ * summed total thickness. Both the built-in defaults and any team/user-added types
+ * are surfaced.
+ *
+ * Types are plain value records ({@linkcode PluginBuildingType}) — NOT scene
+ * entities/handles. A type's `id` is a stable `"<kind>:<name>"` token
+ * (e.g. `"wall:brickWithPlasterAndPaint"`) returned by
+ * {@linkcode PluginDesignTypesApi.list} and consumed by
+ * {@linkcode PluginDesignTypesApi.get}. Reads never throw — an unknown id yields
+ * `null`; a kind with no types yields `[]`.
+ *
+ * These are reads only: there is no engine seam to author a type from a plugin
+ * (types are created through the construction/project-properties UI).
+ */
+export abstract class PluginDesignTypesApi {
+  constructor() {}
+
+  /**
+   * List the building types of one `kind` (wall / slab / floor / ceiling / roof)
+   * — the built-in defaults plus any team/user-added types. Returns lightweight
+   * summaries; call {@linkcode PluginDesignTypesApi.get} for the full layer stack.
+   *
+   * @param kind Which family of types to list
+   * @returns The type summaries as {@linkcode PluginBuildingTypeSummary}`[]` (`[]` when none)
+   *
+   * @examplePrompt What wall types does this project have?
+   * @examplePrompt List the available slab assemblies
+   * @examplePrompt Show me every roof type in the project
+   * @examplePrompt Which floor types can I use?
+   *
+   * # Example
+   * ```ts
+   * const wallTypes = await snaptrude.design.types.list("wall")
+   * for (const t of wallTypes) console.log(t.id, t.label, t.thickness)
+   * ```
+   */
+  public abstract list(
+    kind: PluginBuildingTypeKind
+  ): PluginApiReturn<PluginBuildingTypeSummary[]>
+
+  /**
+   * Get one building type by its `"<kind>:<name>"` id — its labelled layer stack
+   * (each layer's role, thickness and material) plus the summed total thickness.
+   *
+   * @param typeId The type id from {@linkcode PluginDesignTypesApi.list} (e.g. `"wall:exposedConcrete"`)
+   * @returns The full type, or `null` if no type matches
+   *
+   * @examplePrompt What layers make up this wall type?
+   * @examplePrompt Show the construction of the exposed-concrete wall
+   * @examplePrompt What's the total thickness of this slab type?
+   * @examplePrompt Which materials are in this roof assembly?
+   *
+   * # Example
+   * ```ts
+   * const [first] = await snaptrude.design.types.list("wall")
+   * const type = await snaptrude.design.types.get(first.id)
+   * if (type) for (const layer of type.layers) console.log(layer.name, layer.thickness)
+   * ```
+   */
+  public abstract get(typeId: string): PluginApiReturn<PluginBuildingType | null>
+}
+
+/** The building-type families exposed by {@linkcode PluginDesignTypesApi}. */
+export const PluginBuildingTypeKind = z.enum(["wall", "slab", "floor", "ceiling", "roof"])
+export type PluginBuildingTypeKind = z.infer<typeof PluginBuildingTypeKind>
+
+/**
+ * One layer of a building type's assembly.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Layer name (e.g. `"RCC"`, `"Paint"`) |
+ * | `role` | `string` | Layer role (e.g. `"Structure"`, `"Finish"`) |
+ * | `thickness` | `number` | Layer thickness in engine units (project's active unit mode) |
+ * | `material` | `object`? | Layer material — `{ name, type }` (optional) |
+ */
+export const PluginTypeLayer = z.object({
+  name: z.string(),
+  role: z.string(),
+  thickness: z.number(),
+  material: z
+    .object({
+      name: z.string(),
+      type: z.string(),
+    })
+    .optional(),
+})
+export type PluginTypeLayer = z.infer<typeof PluginTypeLayer>
+
+/**
+ * A lightweight building-type summary (no layer stack).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable `"<kind>:<name>"` token — pass to `design.types.get` |
+ * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
+ * | `label` | `string` | Human-readable label |
+ * | `isDefault` | `boolean` | `true` for a built-in type, `false` for a team/user type |
+ * | `thickness` | `number` | Summed layer thickness in engine units |
+ */
+export const PluginBuildingTypeSummary = z.object({
+  id: z.string(),
+  kind: PluginBuildingTypeKind,
+  label: z.string(),
+  isDefault: z.boolean(),
+  thickness: z.number(),
+})
+export type PluginBuildingTypeSummary = z.infer<typeof PluginBuildingTypeSummary>
+
+/**
+ * A full building type — a {@linkcode PluginBuildingTypeSummary} plus its layer stack.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable `"<kind>:<name>"` token |
+ * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
+ * | `label` | `string` | Human-readable label |
+ * | `isDefault` | `boolean` | `true` for a built-in type |
+ * | `thickness` | `number` | Summed layer thickness in engine units |
+ * | `layers` | {@linkcode PluginTypeLayer}`[]` | The ordered layer stack |
+ */
+export const PluginBuildingType = PluginBuildingTypeSummary.extend({
+  layers: z.array(PluginTypeLayer),
+})
+export type PluginBuildingType = z.infer<typeof PluginBuildingType>
+
+/**
+ * Arguments for {@linkcode PluginDesignTypesApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family of types to list |
+ */
+export const PluginDesignTypesListArgs = z.object({
+  kind: PluginBuildingTypeKind,
+})
+export type PluginDesignTypesListArgs = z.infer<typeof PluginDesignTypesListArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignTypesApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `typeId` | `string` | The `"<kind>:<name>"` id from `design.types.list` |
+ */
+export const PluginDesignTypesGetArgs = z.object({
+  typeId: z.string(),
+})
+export type PluginDesignTypesGetArgs = z.infer<typeof PluginDesignTypesGetArgs>