@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/dist/api/design/update/index.d.ts

@@ -0,0 +1,803 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+import { ComponentHandle } from "../../../handles";
+import { PluginSpaceUpdateResult } from "../../entity/space";
+import { PluginDesignChangeResult } from "../lock";
+import { PluginBuildableEnvelopePolygonVertex, PluginBuildableEnvelopeSetbackTier, PluginBuildableEnvelopeVerticalCap, PluginBuildableEnvelopeUpdateResult } from "../../entity/buildableEnvelope";
+/**
+ * Sparse property updates for a space. Only provided fields change.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `room_type` | `string`? | Room label |
+ * | `massType` | `PluginMassType`? | Mass type |
+ * | `spaceType` | `PluginSpaceType`? | Space type |
+ * | `areaClass` | `PluginAreaClass`? | Area class (NET/GROSS/EXCLUDED) |
+ * | `departmentId` | `PluginDepartmentId`? | Department |
+ */
+export declare const PluginSpacePropertyUpdates: z.ZodObject<{
+    room_type: z.ZodOptional<z.ZodString>;
+    massType: z.ZodOptional<z.ZodEnum<{
+        Room: "Room";
+        Plinth: "Plinth";
+        Void: "Void";
+        Pergola: "Pergola";
+        Furniture: "Furniture";
+        "Facade element": "Facade element";
+        "Generic mass": "Generic mass";
+        Department: "Department";
+        Building: "Building";
+        "Revit Import": "Revit Import";
+        Mass: "Mass";
+        Site: "Site";
+    }>>;
+    spaceType: z.ZodOptional<z.ZodEnum<{
+        Room: "Room";
+        "Program Block": "Program Block";
+        Balcony: "Balcony";
+        Road: "Road";
+        Garden: "Garden";
+        Deck: "Deck";
+        Pool: "Pool";
+        Walkway: "Walkway";
+        Envelope: "Envelope";
+        Parking: "Parking";
+    }>>;
+    areaClass: z.ZodOptional<z.ZodEnum<{
+        NET: "NET";
+        GROSS: "GROSS";
+        EXCLUDED: "EXCLUDED";
+    }>>;
+    departmentId: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        DEFAULT: "DEFAULT";
+        SITE: "SITE";
+        ENVELOPE: "ENVELOPE";
+        CORE: "CORE";
+    }>, z.ZodUUID]>>;
+}, z.core.$strip>;
+export type PluginSpacePropertyUpdates = z.infer<typeof PluginSpacePropertyUpdates>;
+/** Geometry replacement for a space — re-extrude a profile. */
+export declare const PluginSpaceGeometryUpdate: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"profile">, string>>;
+    extrudeHeight: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginSpaceGeometryUpdate = z.infer<typeof PluginSpaceGeometryUpdate>;
+/** One space to update via {@linkcode PluginDesignUpdateApi.spaces}. */
+export declare const PluginUpdateSpaceItem: z.ZodObject<{
+    space: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    properties: z.ZodOptional<z.ZodObject<{
+        room_type: z.ZodOptional<z.ZodString>;
+        massType: z.ZodOptional<z.ZodEnum<{
+            Room: "Room";
+            Plinth: "Plinth";
+            Void: "Void";
+            Pergola: "Pergola";
+            Furniture: "Furniture";
+            "Facade element": "Facade element";
+            "Generic mass": "Generic mass";
+            Department: "Department";
+            Building: "Building";
+            "Revit Import": "Revit Import";
+            Mass: "Mass";
+            Site: "Site";
+        }>>;
+        spaceType: z.ZodOptional<z.ZodEnum<{
+            Room: "Room";
+            "Program Block": "Program Block";
+            Balcony: "Balcony";
+            Road: "Road";
+            Garden: "Garden";
+            Deck: "Deck";
+            Pool: "Pool";
+            Walkway: "Walkway";
+            Envelope: "Envelope";
+            Parking: "Parking";
+        }>>;
+        areaClass: z.ZodOptional<z.ZodEnum<{
+            NET: "NET";
+            GROSS: "GROSS";
+            EXCLUDED: "EXCLUDED";
+        }>>;
+        departmentId: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            DEFAULT: "DEFAULT";
+            SITE: "SITE";
+            ENVELOPE: "ENVELOPE";
+            CORE: "CORE";
+        }>, z.ZodUUID]>>;
+    }, z.core.$strip>>;
+    geometry: z.ZodOptional<z.ZodObject<{
+        profile: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"profile">, string>>;
+        extrudeHeight: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginDesignSetLabelArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    label: z.ZodString;
+}, z.core.$strip>;
+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 declare const PluginStaircaseParamUpdates: z.ZodObject<{
+    isStoreyHeightUnlocked: z.ZodOptional<z.ZodBoolean>;
+    isStaircaseHeightUnlocked: z.ZodOptional<z.ZodBoolean>;
+    storeyHeight: z.ZodOptional<z.ZodNumber>;
+    staircaseHeight: z.ZodOptional<z.ZodNumber>;
+    steps: z.ZodOptional<z.ZodNumber>;
+    riser: z.ZodOptional<z.ZodNumber>;
+    tread: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    wellSize: z.ZodOptional<z.ZodNumber>;
+    flightStartDistAfterTurn: z.ZodOptional<z.ZodNumber>;
+    landingWidth: z.ZodOptional<z.ZodNumber>;
+    baseOffset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+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 declare const PluginDesignUpdateStaircaseArgs: z.ZodObject<{
+    staircases: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    params: z.ZodObject<{
+        isStoreyHeightUnlocked: z.ZodOptional<z.ZodBoolean>;
+        isStaircaseHeightUnlocked: z.ZodOptional<z.ZodBoolean>;
+        storeyHeight: z.ZodOptional<z.ZodNumber>;
+        staircaseHeight: z.ZodOptional<z.ZodNumber>;
+        steps: z.ZodOptional<z.ZodNumber>;
+        riser: z.ZodOptional<z.ZodNumber>;
+        tread: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNumber>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        wellSize: z.ZodOptional<z.ZodNumber>;
+        flightStartDistAfterTurn: z.ZodOptional<z.ZodNumber>;
+        landingWidth: z.ZodOptional<z.ZodNumber>;
+        baseOffset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginDesignUpdateStaircaseArgs = z.infer<typeof PluginDesignUpdateStaircaseArgs>;
+/**
+ * Sparse edits for a wall (all optional; at least one required). Only the
+ * fields you provide change. Dimensions are in **engine units** (the same
+ * convention as `design.doors.setWidth`). Consumed by
+ * {@linkcode PluginDesignUpdateApi.wall}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `thickness` | `number`? | Wall thickness, engine units (> 0) |
+ * | `height` | `number`? | Wall height, engine units (> 0) |
+ * | `type` | `string`? | Convert the wall to another wall type — a name (or `wall:`-prefixed id) from `design.types.list("wall")` |
+ */
+export declare const PluginWallUpdates: z.ZodObject<{
+    thickness: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginWallUpdates = z.infer<typeof PluginWallUpdates>;
+/**
+ * Sparse dimension edits for a slab-family element (slab / floor / roof /
+ * ceiling). All values are engine units, the same convention as
+ * `design.doors.setWidth`. Consumed by {@linkcode PluginDesignUpdateApi.slab},
+ * `floor`, `roof`, and `ceiling`.
+ *
+ * `overhang` is only available on **slabs and roofs** (the panel's Overhang
+ * slider) — floors and ceilings reject it with `PRECONDITION_FAILED`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `thickness` | `number`? | Element thickness, engine units (> 0) |
+ * | `overhang` | `number`? | Absolute overhang offset, engine units (slab / roof only) |
+ */
+export declare const PluginSlabUpdates: z.ZodObject<{
+    thickness: z.ZodOptional<z.ZodNumber>;
+    overhang: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginSlabUpdates = z.infer<typeof PluginSlabUpdates>;
+/** Arguments for {@linkcode PluginDesignUpdateApi.wall}. */
+export declare const PluginDesignUpdateWallArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    updates: z.ZodObject<{
+        thickness: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginDesignUpdateWallArgs = z.infer<typeof PluginDesignUpdateWallArgs>;
+/**
+ * Arguments for the slab-family updaters —
+ * {@linkcode PluginDesignUpdateApi.slab}, `floor`, `roof`, `ceiling`.
+ */
+export declare const PluginDesignUpdateSlabArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    updates: z.ZodObject<{
+        thickness: z.ZodOptional<z.ZodNumber>;
+        overhang: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginDesignUpdateSlabArgs = z.infer<typeof PluginDesignUpdateSlabArgs>;
+/** Arguments for {@linkcode PluginDesignUpdateApi.setElevation}. */
+export declare const PluginDesignSetElevationArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    elevation: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDesignSetElevationArgs = z.infer<typeof PluginDesignSetElevationArgs>;
+/** Arguments for {@linkcode PluginDesignUpdateApi.setBaseOffset}. */
+export declare const PluginDesignSetBaseOffsetArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    offset: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDesignSetBaseOffsetArgs = z.infer<typeof PluginDesignSetBaseOffsetArgs>;
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.setStorey}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The components to reassign |
+ * | `storey` | `number` | Target integer storey number (`entity.story` convention; must exist) |
+ */
+export declare const PluginDesignSetStoreyArgs: z.ZodObject<{
+    components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    storey: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDesignSetStoreyArgs = z.infer<typeof PluginDesignSetStoreyArgs>;
+/**
+ * The sparse GROUP-LEVEL patch accepted by {@linkcode PluginDesignUpdateApi.grid}.
+ * Only provided fields change. Wing- and line-level updates live on the grids
+ * entity family: `design.grids.updateWings` / `design.grids.updateLines`.
+ */
+export declare const PluginGridPatch: z.ZodObject<{
+    angle: z.ZodOptional<z.ZodNumber>;
+    props: z.ZodOptional<z.ZodObject<{
+        style: z.ZodOptional<z.ZodEnum<{
+            SOLID: "SOLID";
+            DASHED: "DASHED";
+            DOT_DASH: "DOT_DASH";
+        }>>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        color: z.ZodOptional<z.ZodString>;
+        showStart: z.ZodOptional<z.ZodBoolean>;
+        showEnd: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    storeyVisibility: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        storey: z.ZodNumber;
+        visible: z.ZodBoolean;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PluginGridPatch = z.infer<typeof PluginGridPatch>;
+/** Arguments for {@linkcode PluginDesignUpdateApi.grid}. */
+export declare const PluginDesignUpdateGridArgs: z.ZodObject<{
+    grid: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    patch: z.ZodObject<{
+        angle: z.ZodOptional<z.ZodNumber>;
+        props: z.ZodOptional<z.ZodObject<{
+            style: z.ZodOptional<z.ZodEnum<{
+                SOLID: "SOLID";
+                DASHED: "DASHED";
+                DOT_DASH: "DOT_DASH";
+            }>>;
+            weight: z.ZodOptional<z.ZodNumber>;
+            color: z.ZodOptional<z.ZodString>;
+            showStart: z.ZodOptional<z.ZodBoolean>;
+            showEnd: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        storeyVisibility: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            storey: z.ZodNumber;
+            visible: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginDesignUpdateGridArgs = z.infer<typeof PluginDesignUpdateGridArgs>;
+/**
+ * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
+ *
+ * Migrated from the removed `entity.space.{update, updateGeometryFromProfile, bulkUpdate}`.
+ * Only provided fields change; each call is undoable. Failures throw (RPC rejects).
+ */
+export declare 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")}`)
+     * }
+     * ```
+     */
+    abstract setLabel(component: ComponentHandle, label: string): PluginApiReturn<boolean>;
+    /**
+     * Update a structural grid's **group-level** fields with a sparse patch —
+     * default line styling, absolute angle, and per-storey 2D visibility. Only
+     * provided fields change. Wing- and line-level updates live on the grids
+     * entity family: {@linkcode PluginDesignGridsApi.updateWings} /
+     * {@linkcode PluginDesignGridsApi.updateLines}.
+     *
+     * Every change routes through the exact setters the native panel uses —
+     * each changed field commits its own undoable command, identical to editing
+     * that field in the panel. `angle` is an absolute target in degrees (CCW
+     * about +Y).
+     *
+     * @param grid - The grid group to update
+     * @param patch - The sparse {@linkcode PluginGridPatch}
+     * @returns `true` once applied
+     *
+     * @examplePrompt Rotate the grid to 45 degrees
+     * @examplePrompt Make this grid's lines dashed and grey
+     * @examplePrompt Hide this grid on storey 3's plan
+     *
+     * # Example
+     * ```ts
+     * const [grid] = await snaptrude.design.query.listGrids()
+     * await snaptrude.design.update.grid(grid, { angle: 45, props: { style: "DASHED" } })
+     * ```
+     */
+    abstract grid(grid: ComponentHandle, patch: PluginGridPatch): 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
+     * re-extruding a profile to a new height. Sparse and undoable: only the
+     * fields you provide change.
+     *
+     * @param space - The space to update
+     * @param options - `properties` (sparse) and/or `geometry` ({ profile, extrudeHeight })
+     * @returns the updated space's echoed {@linkcode PluginSpaceUpdateResult}
+     *
+     * @examplePrompt Rename this room to Office
+     * @examplePrompt Change this space's room type to Meeting Room
+     * @examplePrompt Set the height of this room to 3 metres
+     * @examplePrompt Move this space into the Circulation department
+     * @examplePrompt Exclude this room from the area calculations
+     *
+     * @performance For MORE THAN ONE space, call `design.update.spaces(items[])` — the whole
+     *   batch is one host round-trip. Looping this single-space updater is N round-trips.
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.design.update.space("space-id", { properties: { room_type: "Office" } })
+     * ```
+     */
+    abstract space(space: ComponentHandle, options: {
+        properties?: PluginSpacePropertyUpdates;
+        geometry?: PluginSpaceGeometryUpdate;
+    }): PluginApiReturn<PluginSpaceUpdateResult>;
+    /**
+     * Update many spaces (rooms) in one undoable operation — the bulk form of
+     * {@linkcode space}. Each item pairs a space with the sparse property
+     * changes and/or geometry re-extrude to apply; every item is validated up
+     * front, then all changes are applied as a single command.
+     *
+     * Migrated from `entity.space.bulkUpdate`.
+     *
+     * @param items - One {@linkcode PluginUpdateSpaceItem} per space
+     * @returns one {@linkcode PluginSpaceUpdateResult} per item, in input order
+     *
+     * @examplePrompt Label all the selected rooms as Bedrooms
+     * @examplePrompt Change the room type of these five spaces at once
+     * @examplePrompt Set every room on this floor to a 3m height in one go
+     * @examplePrompt Bulk-assign these spaces to the Service department
+     * @examplePrompt Mark all of these rooms as excluded from area in one update
+     *
+     * @performance Bulk update — the whole batch is ONE host round-trip. Prefer over looping
+     *   `design.update.space`: build the `items[]` array first, then make one call.
+     *
+     * # Example
+     * ```ts
+     * // Re-label every selected room and mark it NET area — one undoable bulk update
+     * const rooms = await snaptrude.design.query.listSpaces({ isSelected: true })
+     * const results = await snaptrude.design.update.spaces(
+     *   rooms.map((space) => ({
+     *     space,
+     *     properties: { room_type: "Bedroom", areaClass: "NET" },
+     *   })),
+     * )
+     * // One result per item, in input order
+     * console.log(results.map((r) => r.spaceId))
+     * ```
+     */
+    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")
+     * ```
+     */
+    abstract staircase(staircases: ComponentHandle[], params: PluginStaircaseParamUpdates): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Edit a **wall** — its thickness and/or height (the same command the
+     * properties panel's Thickness/Height fields drive) and/or its **wall type**
+     * (the panel's Wall Types dropdown: converts the wall to another type,
+     * rebuilding its layer stack and materials). Sparse: only the fields you
+     * provide change. Undoable; the geometry rebuilds and any dimension lines
+     * refresh. Stacked-wall companions and hosted fenestration are handled
+     * exactly as the panel does.
+     *
+     * Thickness/height are in **engine units** (the same convention as
+     * `design.doors.setWidth`) and must be `> 0`. Shrinking a wall past its
+     * openings is rejected by the engine (the wall is skipped with no change).
+     * `type` accepts a type name from `design.types.list("wall")` (or its
+     * `wall:`-prefixed id); when combined with dimensions, the type conversion
+     * is applied first so an explicit thickness/height wins over the type's
+     * defaults. Re-applying the wall's current type is a no-op.
+     *
+     * Throws when the handle is not a wall, when the wall is locked, when the
+     * handle is gone/forged, when `type` names an unknown wall type, when the
+     * engine rejects the conversion (e.g. a curved wall thinner than the new
+     * type's minimum thickness), or when no field is provided.
+     *
+     * A type conversion (and a thickness edit on a parametric wall) REBUILDS the
+     * wall, replacing it with a new component: the input handle is then dead
+     * (further calls throw HANDLE_INVALID) and `affected[0]` carries the
+     * replacement's handle — use it for any follow-up calls.
+     *
+     * @param component - The wall to edit
+     * @param updates - Sparse {@linkcode PluginWallUpdates} (at least one field)
+     * @returns the affected wall — after a rebuild, the REPLACEMENT wall's handle
+     *
+     * @examplePrompt Make this wall 230mm thick
+     * @examplePrompt Set the selected wall's height to 3 metres
+     * @examplePrompt Thicken every exterior wall to 300
+     * @examplePrompt Change this wall to a Glass Wall
+     * @examplePrompt Convert all the partitions on this floor to Brick Wall
+     *
+     * # Example
+     * ```ts
+     * // Convert every wall on storey 1 to the first listed wall type
+     * const [wallType] = await snaptrude.design.types.list("wall")
+     * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+     * for (const wall of walls) {
+     *   await snaptrude.design.update.wall(wall, { type: wallType.id })
+     * }
+     * ```
+     */
+    abstract wall(component: ComponentHandle, updates: PluginWallUpdates): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Edit a **slab's** thickness and/or overhang — the same commands the
+     * properties panel's Thickness field and Overhang slider drive. Sparse: only
+     * the fields you provide change. Undoable; the slab rebuilds and dimension
+     * lines refresh. Both values are in **engine units** (the same convention as
+     * `design.doors.setWidth`); thickness must be `> 0`, overhang is an absolute
+     * offset (negative insets the slab) and re-applying the current overhang is
+     * a no-op.
+     *
+     * Throws when the handle is not a slab, when it is locked, when the handle is
+     * gone/forged, when `overhang` is set on a slab that has no overhang (plinth /
+     * basement slabs, or overhang disabled), or when no field is provided.
+     *
+     * @param component - The slab to edit
+     * @param updates - Sparse {@linkcode PluginSlabUpdates} (at least one field)
+     * @returns the affected slab
+     *
+     * @examplePrompt Set this slab's thickness to 250mm
+     * @examplePrompt Make the floor slab 300 thick
+     * @examplePrompt Give this slab a 200 overhang
+     * @examplePrompt Remove the overhang on every slab on level 2
+     *
+     * # Example
+     * ```ts
+     * const [slab] = await snaptrude.design.query.listSlabs()
+     * await snaptrude.design.update.slab(slab, { thickness: 250, overhang: 200 })
+     * ```
+     */
+    abstract slab(component: ComponentHandle, updates: PluginSlabUpdates): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Edit a **floor's** thickness — the slab-family updater for floors (shares
+     * the slab thickness command). Undoable. Thickness is in **engine units**
+     * (the `design.doors.setWidth` convention) and must be `> 0`. Floors have no
+     * Overhang control, so `overhang` is rejected with `PRECONDITION_FAILED`.
+     *
+     * Throws when the handle is not a floor, when it is locked, when the handle
+     * is gone/forged, when `overhang` is provided, or when no field is provided.
+     *
+     * @param component - The floor to edit
+     * @param updates - {@linkcode PluginSlabUpdates} (a `thickness`)
+     * @returns the affected floor
+     *
+     * @examplePrompt Make this floor 200mm thick
+     * @examplePrompt Set every floor to a 250 thickness
+     * @examplePrompt Thicken the ground floor slab to 300
+     *
+     * # Example
+     * ```ts
+     * const [floor] = await snaptrude.design.query.listFloors()
+     * await snaptrude.design.update.floor(floor, { thickness: 200 })
+     * ```
+     */
+    abstract floor(component: ComponentHandle, updates: PluginSlabUpdates): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Edit a **roof's** thickness and/or overhang — the same commands the roof
+     * panel's Thickness field and Overhang slider drive (shares the slab-family
+     * machinery). Sparse: only the fields you provide change. Undoable. Both
+     * values are in **engine units** (the `design.doors.setWidth` convention);
+     * thickness must be `> 0`, overhang is an absolute offset (negative insets
+     * the roof) and re-applying the current overhang is a no-op.
+     *
+     * Throws when the handle is not a roof, when it is locked, when the handle is
+     * gone/forged, when `overhang` is set on a roof whose overhang is disabled,
+     * or when no field is provided.
+     *
+     * @param component - The roof to edit
+     * @param updates - Sparse {@linkcode PluginSlabUpdates} (at least one field)
+     * @returns the affected roof
+     *
+     * @examplePrompt Make this roof 300mm thick
+     * @examplePrompt Set the roof slab thickness to 250
+     * @examplePrompt Give the roof a 600 overhang
+     * @examplePrompt Pull the roof overhang back to 0
+     *
+     * # Example
+     * ```ts
+     * const [roof] = await snaptrude.design.query.listRoofs()
+     * await snaptrude.design.update.roof(roof, { overhang: 600 })
+     * ```
+     */
+    abstract roof(component: ComponentHandle, updates: PluginSlabUpdates): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Edit a **ceiling's** thickness — the slab-family updater for ceilings
+     * (shares the slab thickness command). Undoable. Thickness is in **engine
+     * units** (the `design.doors.setWidth` convention) and must be `> 0`.
+     * Ceilings have no Overhang control, so `overhang` is rejected with
+     * `PRECONDITION_FAILED`.
+     *
+     * Throws when the handle is not a ceiling, when it is locked, when the handle
+     * is gone/forged, when `overhang` is provided, or when no field is provided.
+     *
+     * @param component - The ceiling to edit
+     * @param updates - {@linkcode PluginSlabUpdates} (a `thickness`)
+     * @returns the affected ceiling
+     *
+     * @examplePrompt Make this ceiling 150mm thick
+     * @examplePrompt Set every ceiling to a 100 thickness
+     * @examplePrompt Thicken the ceiling to 200
+     *
+     * # Example
+     * ```ts
+     * const [ceiling] = await snaptrude.design.query.listCeilings()
+     * await snaptrude.design.update.ceiling(ceiling, { thickness: 150 })
+     * ```
+     */
+    abstract ceiling(component: ComponentHandle, updates: PluginSlabUpdates): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Set a component's **absolute world elevation** — moves it vertically so its
+     * base (the bounding-box bottom, world Y) lands at `elevation`. Composed over
+     * the canonical command-backed move machinery, so it is undoable and persisted
+     * exactly like dragging the element up or down; per-type invariants (e.g. a
+     * staircase's base offset) stay in sync. `elevation` is in **engine units**
+     * (the `design.doors.setWidth` convention). Re-applying the current elevation
+     * is a no-op.
+     *
+     * Throws when the component is locked or the handle is gone/forged.
+     *
+     * @param component - The component to move vertically
+     * @param elevation - Target world elevation of the component's base (engine units)
+     * @returns the affected component
+     *
+     * @examplePrompt Set this element's elevation to 3000
+     * @examplePrompt Raise this mass so its base sits at 3 metres
+     * @examplePrompt Drop the selected slab to elevation 0
+     * @examplePrompt Put this staircase's base at 3200
+     *
+     * # Example
+     * ```ts
+     * // Sit the roof slab exactly at the top of a 3m storey
+     * const [roof] = await snaptrude.design.query.listRoofs()
+     * await snaptrude.design.update.setElevation(roof, 3000)
+     * ```
+     */
+    abstract setElevation(component: ComponentHandle, elevation: number): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Set a component's **base offset** — its vertical distance above its own
+     * storey's base level. Moves the component so its base lands at
+     * `storeyBase + offset`, composed over the same command-backed move machinery
+     * as {@linkcode setElevation} (undoable, persisted, per-type invariants kept
+     * in sync). Use this instead of {@linkcode setElevation} when you want an
+     * offset relative to the storey rather than an absolute world height.
+     * `offset` is in **engine units** (the `design.doors.setWidth` convention);
+     * `0` sits the base flush with the storey base. Re-applying the current
+     * offset is a no-op.
+     *
+     * Throws when the component is locked, when it has no storey to offset from,
+     * or when the handle is gone/forged.
+     *
+     * @param component - The component to offset
+     * @param offset - Distance of the component's base above its storey base (engine units)
+     * @returns the affected component
+     *
+     * @examplePrompt Lift this element 300 above its floor
+     * @examplePrompt Set this staircase's base offset to 0
+     * @examplePrompt Raise the selected mass 500 off the storey base
+     * @examplePrompt Offset this slab 150 above the floor level
+     *
+     * # Example
+     * ```ts
+     * const [stair] = await snaptrude.design.query.listStaircases()
+     * await snaptrude.design.update.setBaseOffset(stair, 0)
+     * ```
+     */
+    abstract setBaseOffset(component: ComponentHandle, offset: number): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Reassign one or more components to another **storey** — the same operation
+     * as the properties panel's Story dropdown, and it works across element kinds
+     * exactly like the panel (walls, slabs, masses, furniture, staircases, ...).
+     * Each component is moved vertically to the target storey's level (per-kind
+     * placement rules — e.g. a slab sits at the storey base, a wall on it) and
+     * its storey assignment, children, and dimension lines update together as
+     * **one undoable operation**.
+     *
+     * `storey` is an integer storey number in the `entity.story` convention
+     * (`1` is the ground storey, `-1` the first basement; `0` does not exist)
+     * and **must already exist** in each component's building — this call never
+     * creates storeys (use `core.storeys.create` first). Components already on
+     * the target storey are skipped (no-op) and are not echoed in `affected`.
+     *
+     * Throws when the target storey does not exist, when any component is
+     * locked, or when a handle is gone/forged — all before anything moves
+     * (all-or-nothing).
+     *
+     * @param components - The components to reassign
+     * @param storey - Target storey number (integer, `entity.story` convention)
+     * @returns the components actually reassigned
+     *
+     * @examplePrompt Move this sofa to storey 2
+     * @examplePrompt Put the selected walls on the first basement level
+     * @examplePrompt Send everything on this storey up one level
+     * @examplePrompt Reassign these slabs to storey 3
+     *
+     * # Example
+     * ```ts
+     * // Move the current selection up to storey 2
+     * const selection = await snaptrude.design.selection.get()
+     * const { affected } = await snaptrude.design.update.setStorey(selection, 2)
+     * console.log("moved", affected.length, "components")
+     * ```
+     */
+    abstract setStorey(components: ComponentHandle[], storey: number): PluginApiReturn<PluginDesignChangeResult>;
+    /**
+     * Update an existing parametric buildable envelope — regenerate the zoning
+     * volume from a revised site polygon, setbacks, vertical cap, or FAR and
+     * lot-coverage limits, keeping the same envelope id. Canonical home of the
+     * update formerly at `entity.buildableEnvelope.update` (now deprecated).
+     *
+     * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
+     *   must match an existing envelope on the canvas.
+     * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
+     * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
+     * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
+     * @param verticalCap - Maximum height or floor count.
+     * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
+     * @param farRatio - Optional FAR value, positive when provided.
+     * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
+     * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
+     *   `buildableEnvelopeId` of the updated envelope.
+     * @throws If validation fails, the envelope does not exist, or generation
+     *   produces no renderable geometry.
+     *
+     * @examplePrompt Change the envelope's height limit to 175 feet
+     * @examplePrompt Update the setbacks on the buildable envelope
+     * @examplePrompt Regenerate the zoning envelope with a new site boundary
+     * @examplePrompt Increase the FAR on the buildable volume
+     *
+     * # Example
+     * ```ts
+     * const { buildableEnvelopeId } = await snaptrude.design.update.buildableEnvelope(
+     *   existingId,
+     *   [
+     *     { x: 0, z: 0 },
+     *     { x: 100, z: 0 },
+     *     { x: 100, z: 80 },
+     *     { x: 0, z: 80 },
+     *   ],
+     *   "ft",
+     *   [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
+     *   { kind: "max_height", maxHeight: 175 },
+     *   12,
+     * )
+     * ```
+     */
+    abstract buildableEnvelope(buildableEnvelopeId: string, sitePolygon: PluginBuildableEnvelopePolygonVertex[], lengthUnit: "ft" | "m", setbacks: PluginBuildableEnvelopeSetbackTier[], verticalCap: PluginBuildableEnvelopeVerticalCap, floorToFloor: number, farRatio?: number, lotCoverageMaxPct?: number): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>;
+}
+//# sourceMappingURL=index.d.ts.map