@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

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

@@ -1,254 +1,254 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
-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); `mirror`
- * flips components in place about a horizontal axis. All ops are undoable and return
- * {@linkcode PluginDesignChangeResult} `{ affected }`; failures throw (RPC rejects).
- *
- * `getPosition` / `setPosition` (and `scale`, an engine gap) are NOT in this surface
- * yet — they are a later pass.
- */
-export abstract class PluginDesignTransformApi {
-  constructor() {}
-
-  /**
-   * Translate entities by a **relative** displacement vector (added to the first
-   * component's absolute position as the anchor). Undoable.
-   *
-   * @param components - Entities to move
-   * @param displacement - Relative translation as a {@linkcode Vec3Handle}
-   * @param options - `is2D`, `trackParentChange`
-   * @returns {@linkcode PluginDesignChangeResult}
-   *
-   * @examplePrompt Move the selected room 5 metres to the right
-   * @examplePrompt Shift these walls 3m along the x axis
-   * @examplePrompt Nudge this space 500mm north
-   * @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
-   * await snaptrude.design.transform.move(["space-id"], vec3.new(10, 0, 0))
-   * ```
-   */
-  public abstract move(
-    components: ComponentHandle[],
-    displacement: Vec3Handle,
-    options?: { is2D?: boolean; trackParentChange?: boolean },
-  ): PluginApiReturn<PluginDesignChangeResult>
-
-  /**
-   * 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), `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; 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).
- */
-export const PluginDesignMoveArgs = z.object({
-  components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Handle,
-  is2D: z.boolean().optional(),
-  trackParentChange: z.boolean().optional(),
-})
-export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>
-
-/**
- * Arguments for {@linkcode PluginDesignTransformApi.rotate} (options flattened).
- */
-export const PluginDesignRotateArgs = z.object({
-  components: z.array(ComponentHandle).min(1),
-  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>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+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); `mirror`
+ * flips components in place about a horizontal axis. All ops are undoable and return
+ * {@linkcode PluginDesignChangeResult} `{ affected }`; failures throw (RPC rejects).
+ *
+ * `getPosition` / `setPosition` (and `scale`, an engine gap) are NOT in this surface
+ * yet — they are a later pass.
+ */
+export abstract class PluginDesignTransformApi {
+  constructor() {}
+
+  /**
+   * Translate entities by a **relative** displacement vector (added to the first
+   * component's absolute position as the anchor). Undoable.
+   *
+   * @param components - Entities to move
+   * @param displacement - Relative translation as a {@linkcode Vec3Handle}
+   * @param options - `is2D`, `trackParentChange`
+   * @returns {@linkcode PluginDesignChangeResult}
+   *
+   * @examplePrompt Move the selected room 5 metres to the right
+   * @examplePrompt Shift these walls 3m along the x axis
+   * @examplePrompt Nudge this space 500mm north
+   * @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
+   * await snaptrude.design.transform.move(["space-id"], vec3.new(10, 0, 0))
+   * ```
+   */
+  public abstract move(
+    components: ComponentHandle[],
+    displacement: Vec3Handle,
+    options?: { is2D?: boolean; trackParentChange?: boolean },
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * 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), `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; 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).
+ */
+export const PluginDesignMoveArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  displacement: Vec3Handle,
+  is2D: z.boolean().optional(),
+  trackParentChange: z.boolean().optional(),
+})
+export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignTransformApi.rotate} (options flattened).
+ */
+export const PluginDesignRotateArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  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>