@snaptrude/plugin-core 0.5.0 → 0.7.0

package/src/api/design/lock.ts

@@ -40,3 +40,30 @@ export const PluginDesignIsLockedArgs = z.object({
   includeInherited: z.boolean().optional(),
 })
 export type PluginDesignIsLockedArgs = z.infer<typeof PluginDesignIsLockedArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignApi.lockArea} / {@linkcode PluginDesignApi.unlockArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaces` | {@linkcode ComponentHandle}`[]` | Room / Department mass spaces to area-lock / unlock |
+ */
+export const PluginDesignLockAreaArgs = z.object({
+  spaces: z.array(ComponentHandle),
+})
+export type PluginDesignLockAreaArgs = z.infer<typeof PluginDesignLockAreaArgs>
+
+export const PluginDesignUnlockAreaArgs = PluginDesignLockAreaArgs
+export type PluginDesignUnlockAreaArgs = z.infer<typeof PluginDesignUnlockAreaArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignApi.isAreaLocked}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space to test |
+ */
+export const PluginDesignIsAreaLockedArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignIsAreaLockedArgs = z.infer<typeof PluginDesignIsAreaLockedArgs>

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

@@ -10,8 +10,15 @@ import { ComponentHandle, MaterialHandle } from "../../../handles"
  * scene (undoable via `save`, default `true`). `create` mints a material from a
  * {@linkcode PluginMaterialSpec} (idempotent by name).
  *
- * Face-targeted apply, per-face reads (`listByFace`), and `copy` (needs an undo
- * wrapper) land in a later pass.
+ * Per-face assignment — {@linkcode PluginDesignMaterialsApi.applyToFaces} /
+ * {@linkcode PluginDesignMaterialsApi.resetFaces} plus per-face reads
+ * ({@linkcode PluginDesignMaterialsApi.getByFace} / {@linkcode PluginDesignMaterialsApi.listByFace})
+ * — targets **BREP faces by durable face index** and is **BREP-only** (furniture,
+ * doors/windows, and Revit imports are rejected) and **visual-only** in v1 (the
+ * per-face finish is not carried into BIM schedules / cost layers). A face index
+ * is durable only while the component's BREP topology (face count/order) is unchanged.
+ *
+ * `copy` (needs an undo wrapper) lands in a later pass.
  */
 export abstract class PluginDesignMaterialsApi {
   constructor() {}
@@ -112,6 +119,120 @@ export abstract class PluginDesignMaterialsApi {
     save?: boolean
   ): PluginApiReturn<PluginMaterialResult>
 
+  /**
+   * Paint specific **BREP faces** of a component with a material — an existing
+   * project material by handle, or a new one described inline as a
+   * {@linkcode PluginMaterialSpec}. Faces are addressed by **durable BREP face
+   * index** (their 0-based position in the component's BREP face list).
+   * Undoable when `save` is true (the default).
+   *
+   * Per-face materials are **BREP-only** (walls, floors, slabs, roofs, masses,
+   * columns, beams; furniture, doors/windows, and Revit imports are rejected) and
+   * **visual-only in v1** — the finish is not carried into BIM schedules / cost
+   * layers. A face index is durable only while the BREP topology (face count/order)
+   * is unchanged; a face index at or beyond the face count is rejected.
+   *
+   * @param component The (BREP) component to paint
+   * @param faces BREP face indices to paint (nonnegative integers)
+   * @param material Material handle, or an inline {@linkcode PluginMaterialSpec}
+   * @param save Commit as an undoable command (default `true`)
+   * @returns The number of faces painted
+   *
+   * @examplePrompt Paint the top face of this slab red
+   * @examplePrompt Apply the brick material to faces 0 and 2 of this wall
+   * @examplePrompt Put a wood finish on just the front face of this column
+   * @examplePrompt Colour face 4 of the selected mass with #ff8800
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * // faces are addressed by durable 0-based BREP face index
+   * const { count } = await snaptrude.design.materials.applyToFaces(wall, [0, 1], { name: "Accent", color: "#b04a3a" })
+   * console.log("painted", count, "faces")
+   * ```
+   */
+  public abstract applyToFaces(
+    component: ComponentHandle,
+    faces: number[],
+    material: MaterialHandle | PluginMaterialSpec,
+    save?: boolean
+  ): PluginApiReturn<PluginMaterialResult>
+
+  /**
+   * Reset specific BREP faces of a component back to the component/type default,
+   * removing any per-face finish. The inverse of
+   * {@linkcode PluginDesignMaterialsApi.applyToFaces}; undoable when `save` is true
+   * (the default). BREP-only (see `applyToFaces`).
+   *
+   * @param component The (BREP) component
+   * @param faces BREP face indices to reset (nonnegative integers)
+   * @param save Commit as an undoable command (default `true`)
+   * @returns The number of faces reset
+   *
+   * @examplePrompt Remove the paint from the top face of this slab
+   * @examplePrompt Reset faces 0 and 2 of this wall to their default material
+   * @examplePrompt Clear the custom finish on the front face of this column
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { count } = await snaptrude.design.materials.resetFaces(wall, [0, 1])
+   * console.log("reset", count, "faces")
+   * ```
+   */
+  public abstract resetFaces(
+    component: ComponentHandle,
+    faces: number[],
+    save?: boolean
+  ): PluginApiReturn<PluginMaterialResult>
+
+  /**
+   * Read the material applied to a single BREP face.
+   *
+   * @param component The (BREP) component
+   * @param face The BREP face index (a nonnegative integer)
+   * @returns The face's material as a {@linkcode MaterialHandle}, or `null` if the
+   * face carries no explicit per-face material (or the component has no BREP)
+   *
+   * @examplePrompt What material is on the top face of this slab?
+   * @examplePrompt Get the finish applied to face 2 of this wall
+   * @examplePrompt Which material is painted on the front face of this column?
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const material = await snaptrude.design.materials.getByFace(wall, 0)
+   * if (material) console.log(await snaptrude.design.materials.getInfo(material))
+   * ```
+   */
+  public abstract getByFace(
+    component: ComponentHandle,
+    face: number
+  ): PluginApiReturn<MaterialHandle | null>
+
+  /**
+   * List the per-face materials of a component — one entry per BREP face, in face
+   * index order. A face carrying no explicit per-face material reports `null`.
+   *
+   * @param component The (BREP) component
+   * @returns The per-face materials as {@linkcode PluginFaceMaterial}`[]` (`[]` for a
+   * component with no BREP)
+   *
+   * @examplePrompt List the material on every face of this wall
+   * @examplePrompt Show me which faces of this slab are painted and with what
+   * @examplePrompt Break down the per-face finishes of the selected mass
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const faces = await snaptrude.design.materials.listByFace(wall)
+   * for (const f of faces) console.log(f.faceIndex, f.material ?? "(default)")
+   * ```
+   */
+  public abstract listByFace(
+    component: ComponentHandle
+  ): PluginApiReturn<PluginFaceMaterial[]>
+
   /**
    * Create a new material in the project from a spec — a color, texture URL,
    * opacity, and/or name. Idempotent by name: creating with the name of an
@@ -257,6 +378,20 @@ export type PluginMaterialSpec = z.infer<typeof PluginMaterialSpec>
 export const PluginMaterialResult = z.object({ count: z.number() })
 export type PluginMaterialResult = z.infer<typeof PluginMaterialResult>
 
+/**
+ * A single component face's material assignment (value record — not a handle).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `faceIndex` | `number` | Durable BREP face index (0-based position in the face list) |
+ * | `material` | {@linkcode MaterialHandle} \| `null` | The applied material, or `null` for the default |
+ */
+export const PluginFaceMaterial = z.object({
+  faceIndex: z.number().int().nonnegative(),
+  material: MaterialHandle.nullable(),
+})
+export type PluginFaceMaterial = z.infer<typeof PluginFaceMaterial>
+
 /** Arguments for {@linkcode PluginDesignMaterialsApi.list}. */
 export const PluginDesignMaterialsListArgs = z.object({
   scope: z.enum(["project", "preset"]).optional(),
@@ -299,3 +434,48 @@ export type PluginDesignMaterialsResetArgs = z.infer<typeof PluginDesignMaterial
 /** Arguments for {@linkcode PluginDesignMaterialsApi.create}. */
 export const PluginDesignMaterialsCreateArgs = z.object({ spec: PluginMaterialSpec })
 export type PluginDesignMaterialsCreateArgs = z.infer<typeof PluginDesignMaterialsCreateArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignMaterialsApi.applyToFaces}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The (BREP) component to paint |
+ * | `faces` | `number[]` | BREP face indices to paint (nonnegative integers) |
+ * | `material` | {@linkcode MaterialHandle} \| {@linkcode PluginMaterialSpec} | Material handle, or an inline spec |
+ * | `save` | `boolean` | Commit as an undoable command (default `true`) |
+ */
+export const PluginDesignMaterialsApplyToFacesArgs = z.object({
+  component: ComponentHandle,
+  faces: z.array(z.number().int().nonnegative()),
+  material: z.union([MaterialHandle, PluginMaterialSpec]),
+  save: z.boolean().optional(),
+})
+export type PluginDesignMaterialsApplyToFacesArgs = z.infer<
+  typeof PluginDesignMaterialsApplyToFacesArgs
+>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.resetFaces}. */
+export const PluginDesignMaterialsResetFacesArgs = z.object({
+  component: ComponentHandle,
+  faces: z.array(z.number().int().nonnegative()),
+  save: z.boolean().optional(),
+})
+export type PluginDesignMaterialsResetFacesArgs = z.infer<
+  typeof PluginDesignMaterialsResetFacesArgs
+>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.getByFace}. */
+export const PluginDesignMaterialsGetByFaceArgs = z.object({
+  component: ComponentHandle,
+  face: z.number().int().nonnegative(),
+})
+export type PluginDesignMaterialsGetByFaceArgs = z.infer<
+  typeof PluginDesignMaterialsGetByFaceArgs
+>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.listByFace} (component only). */
+export const PluginDesignMaterialsListByFaceArgs = PluginDesignMaterialsComponentArgs
+export type PluginDesignMaterialsListByFaceArgs = z.infer<
+  typeof PluginDesignMaterialsListByFaceArgs
+>

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

@@ -7,6 +7,7 @@ import {
   PluginDepartmentId,
   PluginAreaClass,
 } from "../../entity/space"
+import { PluginStaircasePreset } from "../create"
 import { PluginDesignQueryGeometryApi } from "./geometry"
 import { PluginDesignQuerySpacesApi } from "./spaces"
 
@@ -215,6 +216,56 @@ export const PluginEntityMeasurements = z.object({
 })
 export type PluginEntityMeasurements = z.infer<typeof PluginEntityMeasurements>
 
+/**
+ * The parametric properties of a staircase — the same editable fields the
+ * staircase properties panel exposes. Returned by
+ * {@linkcode PluginDesignQueryApi.getStaircaseParams}; the write side is
+ * `design.update.staircase`. Engine internals (block schema, min well size,
+ * square-well padding) are deliberately excluded.
+ *
+ * All dimensions are in **engine units** (the same convention as
+ * `design.doors.getWidth`); `steps` is a unitless count. The invariant
+ * `staircaseHeight = steps × riser` is governed by the two lock booleans — see
+ * `design.update.staircase`. Type-specific fields (`wellSize`, `landingWidth`,
+ * `flightStartDistAfterTurn`) are present only when the preset uses them.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `staircaseType` | {@linkcode PluginStaircasePreset} | Base staircase type |
+ * | `staircasePreset` | {@linkcode PluginStaircasePreset} | Named parametric preset |
+ * | `staircaseHeight` | `number` | Total rise (engine units) |
+ * | `steps` | `number` | Step count (unitless) |
+ * | `riser` | `number` | Riser height (engine units) |
+ * | `tread` | `number` | Tread depth (engine units) |
+ * | `width` | `number` | Flight width (engine units) |
+ * | `depth` | `number` | Slab/waist thickness (engine units) |
+ * | `wellSize` | `number`? | Stairwell gap (dogLegged / openWell / square) |
+ * | `landingWidth` | `number`? | Landing depth (straight / dogLegged) |
+ * | `flightStartDistAfterTurn` | `number`? | Flight offset after a turn (dogLegged / lShaped / square) |
+ * | `baseOffset` | `number` | Vertical offset from the storey base (engine units) |
+ * | `isStoreyHeightUnlocked` | `boolean` | When `false`, height is tied to the storey height |
+ * | `isStaircaseHeightUnlocked` | `boolean` | When `false`, height recomputes from steps × riser |
+ * | `storey` | `number` | Storey/floor level the staircase sits on |
+ */
+export const PluginStaircaseParams = z.object({
+  staircaseType: PluginStaircasePreset,
+  staircasePreset: PluginStaircasePreset,
+  staircaseHeight: z.number(),
+  steps: z.number(),
+  riser: z.number(),
+  tread: z.number(),
+  width: z.number(),
+  depth: z.number(),
+  wellSize: z.number().optional(),
+  landingWidth: z.number().optional(),
+  flightStartDistAfterTurn: z.number().optional(),
+  baseOffset: z.number(),
+  isStoreyHeightUnlocked: z.boolean(),
+  isStaircaseHeightUnlocked: z.boolean(),
+  storey: z.number(),
+})
+export type PluginStaircaseParams = z.infer<typeof PluginStaircaseParams>
+
 // ---------------------------------------------------------------------------
 // The query API
 // ---------------------------------------------------------------------------
@@ -902,6 +953,36 @@ export abstract class PluginDesignQueryApi {
     component: ComponentHandle,
   ): PluginApiReturn<PluginEntityMeasurements | null>
 
+  /**
+   * Read a staircase's parametric properties — its preset, dimensions, step
+   * count, base offset, and height-lock state — as a
+   * {@linkcode PluginStaircaseParams} record. The paired write is
+   * `design.update.staircase`.
+   *
+   * All dimensions are in **engine units** (the same convention as
+   * `design.doors.getWidth`); `steps` is a unitless count. A read — never
+   * throws: returns `null` for a handle that is not a staircase or no longer
+   * resolves.
+   *
+   * @param staircase - the staircase's {@linkcode ComponentHandle}
+   * @returns the {@linkcode PluginStaircaseParams} record, or `null`
+   *
+   * @examplePrompt What's the riser height of this staircase?
+   * @examplePrompt How many steps does the selected stair have?
+   * @examplePrompt Show me the tread and width of this staircase
+   * @examplePrompt Read all the parameters of the stairs on level 1
+   *
+   * # Example
+   * ```ts
+   * const [stair] = await snaptrude.design.query.listStaircases({ isSelected: true })
+   * const params = stair ? await snaptrude.design.query.getStaircaseParams(stair) : null
+   * if (params) console.log(params.steps, params.riser, params.tread)
+   * ```
+   */
+  public abstract getStaircaseParams(
+    staircase: ComponentHandle,
+  ): PluginApiReturn<PluginStaircaseParams | null>
+
   /**
    * Get the **union** axis-aligned bounding box enclosing a set of entities.
    *

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,8 +6,10 @@ import { PluginDesignChangeResult } from "../lock"
 /**
  * `snaptrude.design.transform` — rigid transforms on scene entities.
  *
- * Migrated from the removed `tools.transform.*`. All ops are undoable and return
- * {@linkcode PluginDesignChangeResult} `{ affected }`; failures throw (RPC rejects).
+ * `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).
  *
  * `mirror` / `getPosition` / `setPosition` (and `scale`, an engine gap) are NOT in
  * this surface yet — they are a later, non-migration pass.
@@ -68,8 +70,62 @@ export abstract class PluginDesignTransformApi {
     angleInDegrees: number,
     options?: { axis?: 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
+   *
+   * # 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>
 }
 
+/**
+ * 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).
  */
@@ -91,3 +147,19 @@ export const PluginDesignRotateArgs = z.object({
   is2D: z.boolean().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>