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

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>