@snaptrude/plugin-core 0.7.0 → 0.8.0

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

@@ -7,12 +7,12 @@ import { PluginDesignChangeResult } from "../lock"
  * `snaptrude.design.transform` — rigid transforms on scene entities.
  *
  * `move` / `rotate` migrated from the removed `tools.transform.*`; `align` snaps a
- * set of components' bounding-box edges to each other (or to a reference). All ops
- * are undoable and return {@linkcode PluginDesignChangeResult} `{ affected }`;
- * failures throw (RPC rejects).
+ * 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() {}
@@ -45,30 +45,37 @@ 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
    *
    * # 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>
 
   /**
@@ -116,14 +123,69 @@ export abstract class PluginDesignTransformApi {
     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
+   *
+   * # 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 const PluginAlignEdge = z.enum([
+  "left",
+  "right",
+  "center",
+  "top",
+  "bottom",
+  "middle",
+])
 export type PluginAlignEdge = z.infer<typeof PluginAlignEdge>
 
 /**
@@ -145,6 +207,7 @@ 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>
 
@@ -163,3 +226,17 @@ export const PluginDesignAlignArgs = z.object({
   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>