@snaptrude/plugin-core 0.6.0 → 0.7.1

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/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>

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

@@ -8,6 +8,7 @@ import {
   PluginAreaClass,
   PluginSpaceUpdateResult,
 } from "../../entity/space"
+import { PluginDesignChangeResult } from "../lock"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -44,6 +45,83 @@ export const PluginUpdateSpaceItem = z.object({
 })
 export type PluginUpdateSpaceItem = z.infer<typeof PluginUpdateSpaceItem>
 
+/**
+ * Wire schema for {@linkcode PluginDesignUpdateApi.setLabel}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | `ComponentHandle` | The component to relabel |
+ * | `label` | `string` | New label (non-empty after trimming) |
+ */
+export const PluginDesignSetLabelArgs = z.object({
+  component: ComponentHandle,
+  label: z.string().trim().min(1),
+})
+export type PluginDesignSetLabelArgs = z.infer<typeof PluginDesignSetLabelArgs>
+
+/**
+ * Sparse parametric updates for a staircase (all fields optional; at least one
+ * required). Only the fields you provide change. Consumed by
+ * {@linkcode PluginDesignUpdateApi.staircase}; the paired read is
+ * `design.query.getStaircaseParams`.
+ *
+ * All dimensions are in **engine units** (the same convention as
+ * `design.doors.setWidth`); `steps` is a unitless integer count. Height, riser,
+ * and step count are **coupled** (`staircaseHeight = steps × riser`); the two
+ * lock booleans govern which value recomputes — see the method JSDoc.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `isStoreyHeightUnlocked` | `boolean`? | Unlock the staircase height from the storey height |
+ * | `isStaircaseHeightUnlocked` | `boolean`? | Unlock the height from `steps × riser` |
+ * | `storeyHeight` | `number`? | Storey height the stair sits within (engine units) |
+ * | `staircaseHeight` | `number`? | Total rise (engine units) |
+ * | `steps` | `number`? | Step count (unitless integer) |
+ * | `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) |
+ * | `flightStartDistAfterTurn` | `number`? | Flight offset after a turn (dogLegged / lShaped / square) |
+ * | `landingWidth` | `number`? | Landing depth (straight / dogLegged) |
+ * | `baseOffset` | `number`? | Vertical offset from the storey base (engine units) |
+ */
+export const PluginStaircaseParamUpdates = z
+  .object({
+    isStoreyHeightUnlocked: z.boolean().optional(),
+    isStaircaseHeightUnlocked: z.boolean().optional(),
+    storeyHeight: z.number().optional(),
+    staircaseHeight: z.number().optional(),
+    steps: z.number().int().optional(),
+    riser: z.number().optional(),
+    tread: z.number().optional(),
+    width: z.number().optional(),
+    depth: z.number().optional(),
+    wellSize: z.number().optional(),
+    flightStartDistAfterTurn: z.number().optional(),
+    landingWidth: z.number().optional(),
+    baseOffset: z.number().optional(),
+  })
+  .refine((p) => Object.keys(p).length > 0, {
+    message:
+      "PluginStaircaseParamUpdates requires at least one field to change",
+  })
+export type PluginStaircaseParamUpdates = z.infer<typeof PluginStaircaseParamUpdates>
+
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.staircase}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `staircases` | {@linkcode ComponentHandle}`[]` | The staircases to update |
+ * | `params` | {@linkcode PluginStaircaseParamUpdates} | Sparse parametric changes (≥ 1 field) |
+ */
+export const PluginDesignUpdateStaircaseArgs = z.object({
+  staircases: z.array(ComponentHandle),
+  params: PluginStaircaseParamUpdates,
+})
+export type PluginDesignUpdateStaircaseArgs = z.infer<typeof PluginDesignUpdateStaircaseArgs>
+
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
  *
@@ -53,6 +131,46 @@ export type PluginUpdateSpaceItem = z.infer<typeof PluginUpdateSpaceItem>
 export abstract class PluginDesignUpdateApi {
   constructor() {}
 
+  /**
+   * Set a component's **Label** — the same editable Label field the properties
+   * panel shows (doors, windows, furniture, spaces, and every other labelled
+   * component). The paired read is `design.query.getLabel`. Undoable; the
+   * canvas label text updates immediately.
+   *
+   * Strictly **per component**: labelling one door of a placed family never
+   * touches its sibling doors (the panel's Label edit, by contrast, applies to
+   * the whole family). On **legacy masses** without a space type, panel parity
+   * applies — a label matching a room-type preset with a height can also
+   * adjust the mass's height and material, exactly like typing it in the panel.
+   *
+   * Throws when the component is locked, the handle is gone/forged, the label
+   * is empty, or the component has no mesh to label. Re-applying the current
+   * label is a no-op that returns `true` without touching the undo stack.
+   *
+   * @param component - The component to relabel
+   * @param label - New label text (non-empty; leading/trailing whitespace trimmed)
+   * @returns `true` once the label is applied
+   *
+   * @examplePrompt Rename this door to D-101
+   * @examplePrompt Number all doors on storey 2 with a D-2-XX tag
+   * @examplePrompt Set the selected window's label to W-04
+   * @examplePrompt Tag every door with its fire rating
+   *
+   * # Example
+   * ```ts
+   * // Door tag numbering: label every door as D-<storey>-<n>, numbered per storey
+   * await snaptrude.design.selection.setByFilter({ types: ["door"] })
+   * const doors = await snaptrude.design.selection.get()
+   * const counts = {}
+   * for (const door of doors) {
+   *   const { storey = 0 } = await snaptrude.design.query.getProperties(door)
+   *   counts[storey] = (counts[storey] ?? 0) + 1
+   *   await snaptrude.design.update.setLabel(door, `D-${storey}-${String(counts[storey]).padStart(2, "0")}`)
+   * }
+   * ```
+   */
+  public abstract setLabel(component: ComponentHandle, label: string): PluginApiReturn<boolean>
+
   /**
    * Update a single space (room) — change its properties (room label, space
    * type, mass type, area class, department) and/or replace its geometry by
@@ -114,4 +232,53 @@ export abstract class PluginDesignUpdateApi {
    * ```
    */
   public abstract spaces(items: PluginUpdateSpaceItem[]): PluginApiReturn<PluginSpaceUpdateResult[]>
+
+  /**
+   * Update the parameters of one or more staircases — riser, tread, width,
+   * depth, step count, total height, well size, landing depth, base offset,
+   * and the two height locks — in one undoable operation. Sparse: only the
+   * fields you provide change. The paired read is
+   * `design.query.getStaircaseParams`.
+   *
+   * All dimensions are in **engine units** (the same convention as
+   * `design.doors.setWidth`); `steps` is a unitless integer count. The height,
+   * riser, and step count are **coupled** — `staircaseHeight = steps × riser` —
+   * and the two lock booleans govern which value recomputes when another
+   * changes. With `isStoreyHeightUnlocked` false the staircase height follows
+   * the storey height; unlocking it also unlocks the staircase height. Setting
+   * `steps` recomputes `riser` (or the height, once the height is unlocked),
+   * and setting `riser` recomputes `steps`/height in turn.
+   *
+   * Presets-only: this edits the parametric fields of a preset staircase; it
+   * does not change the staircase's type/preset (there is no in-place re-type).
+   * Every edit rebuilds the staircase geometry, so the call is async.
+   *
+   * Throws when a handle is not a staircase, when a staircase is locked, or
+   * when a value falls outside the engine's accepted range (RPC rejects).
+   *
+   * @param staircases - the staircases to update
+   * @param params - sparse {@linkcode PluginStaircaseParamUpdates} (at least one field)
+   * @returns the affected staircases
+   *
+   * @examplePrompt Set the riser of this staircase to 165mm
+   * @examplePrompt Change all the stairs to 14 steps
+   * @examplePrompt Make the selected staircase 1200 wide with a 280 tread
+   * @examplePrompt Widen every staircase on level 1 to 1 metre
+   * @examplePrompt Unlock the height and set this stair to 3200 tall
+   *
+   * # Example
+   * ```ts
+   * // Give every ground-floor staircase a common riser + tread (engine units)
+   * const stairs = await snaptrude.design.query.listStaircases({ storeys: [1] })
+   * const { affected } = await snaptrude.design.update.staircase(stairs, {
+   *   riser: 165,
+   *   tread: 280,
+   * })
+   * console.log("updated", affected.length, "staircases")
+   * ```
+   */
+  public abstract staircase(
+    staircases: ComponentHandle[],
+    params: PluginStaircaseParamUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
 }