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

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

@@ -1,983 +1,1096 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, ProfileHandle } from "../../../handles"
-import {
-  PluginSpaceType,
-  PluginMassType,
-  PluginDepartmentId,
-  PluginAreaClass,
-  PluginSpaceUpdateResult,
-} from "../../entity/space"
-import { PluginDesignChangeResult } from "../lock"
-import { MassParametersPatch, type MassParametersRecord } from "../../../massParameters"
-import {
-  PluginBuildableEnvelopePolygonVertex,
-  PluginBuildableEnvelopeSetbackTier,
-  PluginBuildableEnvelopeVerticalCap,
-  PluginBuildableEnvelopeUpdateResult,
-} from "../../entity/buildableEnvelope"
-import { PluginGridStyleOptions } from "../create/grids"
-import { PluginEntityType } from "../query"
-
-/**
- * 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 const PluginSpacePropertyUpdates = z.object({
-  room_type: z.string().optional(),
-  massType: PluginMassType.optional(),
-  spaceType: PluginSpaceType.optional(),
-  areaClass: PluginAreaClass.optional(),
-  departmentId: PluginDepartmentId.optional(),
-})
-export type PluginSpacePropertyUpdates = z.infer<
-  typeof PluginSpacePropertyUpdates
->
-
-/** Geometry replacement for a space — re-extrude a profile. */
-export const PluginSpaceGeometryUpdate = z.object({
-  profile: ProfileHandle,
-  extrudeHeight: z.number(),
-})
-export type PluginSpaceGeometryUpdate = z.infer<
-  typeof PluginSpaceGeometryUpdate
->
-
-/** One space to update via {@linkcode PluginDesignUpdateApi.spaces}. */
-export const PluginUpdateSpaceItem = z.object({
-  space: ComponentHandle,
-  properties: PluginSpacePropertyUpdates.optional(),
-  geometry: PluginSpaceGeometryUpdate.optional(),
-})
-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
->
-
-/**
- * Arguments for {@linkcode PluginDesignUpdateApi.parameters}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `component` | {@linkcode ComponentHandle} | The parametric mass to edit |
- * | `patch` | {@linkcode MassParametersPatch} | Partial `values` (+ optional `operations`), or the full edited record |
- */
-export const PluginDesignUpdateParametersArgs = z.object({
-  component: ComponentHandle,
-  patch: MassParametersPatch,
-})
-export type PluginDesignUpdateParametersArgs = z.infer<
-  typeof PluginDesignUpdateParametersArgs
->
-
-/**
- * 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 const PluginWallUpdates = z
-  .object({
-    thickness: z.number().positive().optional(),
-    height: z.number().positive().optional(),
-    type: z.string().trim().min(1).optional(),
-  })
-  .refine((p) => Object.keys(p).length > 0, {
-    message: "PluginWallUpdates requires at least one field to change",
-  })
-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 const PluginSlabUpdates = z
-  .object({
-    thickness: z.number().positive().optional(),
-    overhang: z.number().optional(),
-  })
-  .refine((p) => Object.keys(p).length > 0, {
-    message: "PluginSlabUpdates requires at least one field to change",
-  })
-export type PluginSlabUpdates = z.infer<typeof PluginSlabUpdates>
-
-/** Arguments for {@linkcode PluginDesignUpdateApi.wall}. */
-export const PluginDesignUpdateWallArgs = z.object({
-  component: ComponentHandle,
-  updates: PluginWallUpdates,
-})
-export type PluginDesignUpdateWallArgs = z.infer<
-  typeof PluginDesignUpdateWallArgs
->
-
-/**
- * Arguments for the slab-family updaters —
- * {@linkcode PluginDesignUpdateApi.slab}, `floor`, `roof`, `ceiling`.
- */
-export const PluginDesignUpdateSlabArgs = z.object({
-  component: ComponentHandle,
-  updates: PluginSlabUpdates,
-})
-export type PluginDesignUpdateSlabArgs = z.infer<
-  typeof PluginDesignUpdateSlabArgs
->
-
-/** Arguments for {@linkcode PluginDesignUpdateApi.setElevation}. */
-export const PluginDesignSetElevationArgs = z.object({
-  component: ComponentHandle,
-  elevation: z.number(),
-})
-export type PluginDesignSetElevationArgs = z.infer<
-  typeof PluginDesignSetElevationArgs
->
-
-/** Arguments for {@linkcode PluginDesignUpdateApi.setBaseOffset}. */
-export const PluginDesignSetBaseOffsetArgs = z.object({
-  component: ComponentHandle,
-  offset: z.number(),
-})
-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 const PluginDesignSetStoreyArgs = z.object({
-  components: z.array(ComponentHandle),
-  storey: z.number().int(),
-})
-export type PluginDesignSetStoreyArgs = z.infer<
-  typeof PluginDesignSetStoreyArgs
->
-
-/**
- * Object types {@linkcode PluginDesignUpdateApi.setObjectType} can turn a mass
- * into — the `design.query` `type` vocabulary.
- */
-export const PluginObjectType = PluginEntityType.extract([
-  "wall",
-  "roof",
-  "slab",
-  "floor",
-])
-export type PluginObjectType = z.infer<typeof PluginObjectType>
-
-/**
- * Arguments for {@linkcode PluginDesignUpdateApi.setObjectType}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | The masses to convert (>= 1) |
- * | `objectType` | {@linkcode PluginObjectType} | Target object type (`"wall"`, `"roof"`, `"slab"`, `"floor"`) |
- */
-export const PluginDesignSetObjectTypeArgs = z.object({
-  components: z.array(ComponentHandle).min(1),
-  objectType: PluginObjectType,
-})
-export type PluginDesignSetObjectTypeArgs = z.infer<
-  typeof PluginDesignSetObjectTypeArgs
->
-
-/**
- * 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 const PluginGridPatch = z.object({
-  angle: z.number().finite().optional(),
-  props: PluginGridStyleOptions.optional(),
-  storeyVisibility: z
-    .array(z.object({ storey: z.number().int(), visible: z.boolean() }))
-    .optional(),
-})
-export type PluginGridPatch = z.infer<typeof PluginGridPatch>
-
-/** Arguments for {@linkcode PluginDesignUpdateApi.grid}. */
-export const PluginDesignUpdateGridArgs = z.object({
-  grid: ComponentHandle,
-  patch: PluginGridPatch,
-})
-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 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 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" } })
-   * ```
-   */
-  public 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" } })
-   * ```
-   */
-  public 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))
-   * ```
-   */
-  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>
-
-  /**
-   * Edit a parametric mass by patching its creation recipe and rebuilding the
-   * solid in place — the mass keeps its id, storey, materials, position and
-   * linked copies; only the geometry changes. Read the current record with
-   * `design.query.getParameters` first.
-   *
-   * `patch` is a partial of `record.values` — or the whole record you read
-   * back, edited. A key you leave out is unchanged (that includes
-   * `operations`). Each key you send replaces that value whole — a scalar, a
-   * point, a list or a record (`contour`, `profile`, `sections`, `path`,
-   * `options`, `operations`) alike — so send the complete value you read,
-   * edited (a partial `options` drops the switches it leaves out);
-   * `{ operations: [] }` drops every operation. An optional key
-   * the record does not carry yet may be patched in when the kind allows it:
-   * a straight extrusion acquires `twistInDegrees` or `topScale`, an
-   * options-less loft or sweep acquires `options` (`levels` is not one — send
-   * the angle, not the section count). A patch that changes nothing
-   * returns the current record and records no edit (no undo step). `kind` and
-   * `version` are immutable: to change the kind, build a new mass. Keys are the
-   * record's `values` keys for its `kind` (sphere: `centre`, `radius`;
-   * cylinder: `base`, `axis`, `radius`, `height`; torus: `centre`, `axis`,
-   * `majorRadius`, `minorRadius`; …) plus `operations`. To change a fillet
-   * radius, edit `operations[i].radius` in the record you read and send
-   * `{ operations }` back. Points and axes are WORLD coordinates in internal
-   * units, exactly as `getParameters` reports them.
-   *
-   * Rebuilds in memory first, then swaps onto the SAME component; every linked
-   * copy regenerates together. One undo step; saves and syncs to collaborators
-   * like any geometry edit. Kernel kinds (revolution, sweep, loft, primitives,
-   * any `operations`) run on OpenCascade — expect a short pause.
-   *
-   * @param component - a mass whose `getParameters` is non-null
-   * @param patch - partial `values` (+ optional `operations`), or the full edited record
-   * @returns the complete post-edit record, world coordinates (what
-   *   `getParameters` now returns)
-   * @throws PRECONDITION_FAILED when the component is not a mass (a family
-   *   instance: use `design.family.setParameters`).
-   *   Also PRECONDITION_FAILED when the mass carries no live recipe — built
-   *   from a boolean, split, `brepFromFaces`/`brepFromMesh` or drawn; edited
-   *   free-form since (push/pull, move face, boolean); or scaled with the
-   *   transform tool. `getParameters` returns `null` for exactly these.
-   *   Do not retry — rebuild it with a recipe constructor and say so.
-   *   A scaled mass is the exception: undo the scale and call again.
-   *   Also PRECONDITION_FAILED when the mass (or a linked copy) is **locked**
-   *   (the message says so). Locking is invisible to `getParameters` — a
-   *   locked parametric mass still reads back a full record. Unlock it (and
-   *   every linked copy) and call again; never rebuild it, the recipe is intact.
-   *   Also PRECONDITION_FAILED when an `operations` entry's edge/face selectors
-   *   no longer resolve on the rebuilt base (the message names the operation
-   *   and edge): re-select the edges on the new shape and re-apply that
-   *   operation.
-   *   Also PRECONDITION_FAILED when the edit is the first twist or taper — or
-   *   the straightening — of an extrusion that carries a shell, fillet or
-   *   chamfer (the kernel numbers its faces differently): send the twist/taper
-   *   keys with `operations: []` first (the message names them), re-select on
-   *   the new shape, then send `{ operations }` back.
-   * @throws VALIDATION for a key the kind does not have (the message lists the
-   *   kind's keys), `kind` or `version` in a partial patch, or a value outside
-   *   the constructor's own rules (torus tube ≥ ring, revolution angle ∉
-   *   (0, 360], a profile crossing its axis, a spline with fewer than
-   *   degree + 1 poles).
-   * @throws OPERATION_FAILED when the kernel cannot build the edited recipe;
-   *   the model is left unchanged.
-   *
-   * @examplePrompt Make the dome's radius 8 metres
-   * @examplePrompt Raise the podium to 5 m
-   * @examplePrompt Widen the vase — move its profile points 20 cm outward
-   * @examplePrompt Change the fillet on the rounded column to 300 mm
-   *
-   * # Example
-   * ```ts
-   * // { kind: "sphere", values: { centre, radius: 19.685 }, … }
-   * const before = await snaptrude.design.query.getParameters(dome)
-   * const after = await snaptrude.design.update.parameters(dome, { radius: 31.496 }) // 8 m in internal units
-   *
-   * // Fillet radius on a recorded result: read → edit → send the array back
-   * const rec = await snaptrude.design.query.getParameters(column)
-   * const operations = rec?.operations ?? []
-   * if (operations[0]?.op === "fillet") {
-   *   operations[0].radius = 1.181
-   *   await snaptrude.design.update.parameters(column, { operations })
-   * }
-   * ```
-   */
-  public abstract parameters(
-    component: ComponentHandle,
-    patch: MassParametersPatch,
-  ): PluginApiReturn<MassParametersRecord>
-
-  /**
-   * 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 })
-   * }
-   * ```
-   */
-  public 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 })
-   * ```
-   */
-  public 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 })
-   * ```
-   */
-  public 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 })
-   * ```
-   */
-  public 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 })
-   * ```
-   */
-  public 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)
-   * ```
-   */
-  public 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)
-   * ```
-   */
-  public 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")
-   * ```
-   */
-  public abstract setStorey(
-    components: ComponentHandle[],
-    storey: number,
-  ): PluginApiReturn<PluginDesignChangeResult>
-
-  /**
-   * Change the **object type** of one or more masses — turn a mass into a real
-   * wall, roof, slab or floor: the properties panel's Object Type dropdown,
-   * headless. The geometry is kept exactly as it is (a wedge stays a wedge;
-   * nothing is flattened to a default thickness), so a sloped mass built with
-   * `design.create.massFromBrep` becomes a sloped roof or a raked wall. The
-   * component keeps its handle, label and storey; it gains the target type's
-   * construction layers and properties, and the type's default material when
-   * the mass still wore the default. One undoable operation for the whole
-   * list; undo turns them back into masses.
-   *
-   * Instances convert as a family: passing one instance (or the source) of an
-   * instanced mass converts its source and every sibling; `affected` echoes
-   * every visible member (the hidden instancing template converts too but is
-   * not listed). A converted component cannot be converted again (same rule
-   * as the panel). A converted wall has no parametric centerline: it hosts
-   * doors and windows and exports, but neighbours do not re-mitre against it.
-   *
-   * Throws before anything changes (all-or-nothing) when a component is not a
-   * mass, is a plinth, is locked or in a locked bucket, already had its type
-   * changed, or when a handle is gone/forged.
-   *
-   * @param components - The masses to convert
-   * @param objectType - Target type: `"wall"`, `"roof"`, `"slab"` or `"floor"`
-   *   (the `design.query.getEntityType` vocabulary)
-   * @returns the visible components converted — the same handles, plus any
-   *   instance siblings pulled in by family expansion
-   *
-   * @examplePrompt Convert this mass into a wall
-   * @examplePrompt Turn the sloped mass into a roof
-   * @examplePrompt Make these masses real slabs
-   * @examplePrompt Change the object type of the selection to wall
-   * @examplePrompt Convert the wedge I built into a raked wall
-   * @examplePrompt Turn this mass into a floor
-   *
-   * # Example
-   * ```ts
-   * const brep = await snaptrude.core.geom.create.brepFromFaces(wedgeFaces)
-   * const wedge = await snaptrude.design.create.massFromBrep(brep, "Gable end")
-   * const { affected } = await snaptrude.design.update.setObjectType([wedge], "wall")
-   * console.log(await snaptrude.design.query.getEntityType(affected[0])) // "wall"
-   * ```
-   */
-  public abstract setObjectType(
-    components: ComponentHandle[],
-    objectType: PluginObjectType,
-  ): 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,
-   * )
-   * ```
-   */
-  public abstract buildableEnvelope(
-    buildableEnvelopeId: string,
-    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
-    lengthUnit: "ft" | "m",
-    setbacks: PluginBuildableEnvelopeSetbackTier[],
-    verticalCap: PluginBuildableEnvelopeVerticalCap,
-    floorToFloor: number,
-    farRatio?: number,
-    lotCoverageMaxPct?: number,
-  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
-}
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, ProfileHandle } from "../../../handles"
+import {
+  PluginSpaceType,
+  PluginMassType,
+  PluginDepartmentId,
+  PluginAreaClass,
+  PluginSpaceUpdateResult,
+} from "../../entity/space"
+import { PluginDesignChangeResult } from "../lock"
+import {
+  MassParametersPatch,
+  type MassParametersRecord,
+} from "../../../massParameters"
+import {
+  PluginBuildableEnvelopePolygonVertex,
+  PluginBuildableEnvelopeSetbackTier,
+  PluginBuildableEnvelopeVerticalCap,
+  PluginBuildableEnvelopeUpdateResult,
+  PluginSiteEdgePatch,
+  PluginDesignUpdateSiteEdgeResult,
+} from "../../entity/buildableEnvelope"
+import { PluginGridStyleOptions } from "../create/grids"
+import { PluginEntityType } from "../query"
+import { PluginWallType } from "../types"
+import {
+  PluginConstructionType,
+  PluginFamilyValues,
+  type PluginFamilyUpdates,
+} from "../catalog"
+
+/**
+ * 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 const PluginSpacePropertyUpdates = z.object({
+  room_type: z.string().optional(),
+  massType: PluginMassType.optional(),
+  spaceType: PluginSpaceType.optional(),
+  areaClass: PluginAreaClass.optional(),
+  departmentId: PluginDepartmentId.optional(),
+})
+export type PluginSpacePropertyUpdates = z.infer<
+  typeof PluginSpacePropertyUpdates
+>
+
+/** Geometry replacement for a space — re-extrude a profile. */
+export const PluginSpaceGeometryUpdate = z.object({
+  profile: ProfileHandle,
+  extrudeHeight: z.number(),
+})
+export type PluginSpaceGeometryUpdate = z.infer<
+  typeof PluginSpaceGeometryUpdate
+>
+
+/** One space to update via {@linkcode PluginDesignUpdateApi.spaces}. */
+export const PluginUpdateSpaceItem = z.object({
+  space: ComponentHandle,
+  properties: PluginSpacePropertyUpdates.optional(),
+  geometry: PluginSpaceGeometryUpdate.optional(),
+})
+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
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.parameters}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The parametric mass to edit |
+ * | `patch` | {@linkcode MassParametersPatch} | Partial `values` (+ optional `operations`), or the full edited record |
+ */
+export const PluginDesignUpdateParametersArgs = z.object({
+  component: ComponentHandle,
+  patch: MassParametersPatch,
+})
+export type PluginDesignUpdateParametersArgs = z.infer<
+  typeof PluginDesignUpdateParametersArgs
+>
+
+/**
+ * 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` | {@linkcode PluginWallType}? | Legacy name/id or exact authorized native `{ id, version }` pin from `design.types.list("wall")` |
+ */
+export const PluginWallUpdates = z
+  .object({
+    thickness: z.number().positive().optional(),
+    height: z.number().positive().optional(),
+    type: PluginWallType.optional(),
+    values: PluginFamilyValues.optional(),
+  })
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "PluginWallUpdates requires at least one field to change",
+  })
+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 const PluginSlabUpdates = z
+  .object({
+    thickness: z.number().positive().optional(),
+    overhang: z.number().optional(),
+    type: PluginConstructionType.optional(),
+    values: PluginFamilyValues.optional(),
+  })
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "PluginSlabUpdates requires at least one field to change",
+  })
+export type PluginSlabUpdates = z.infer<typeof PluginSlabUpdates>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.wall}. */
+export const PluginDesignUpdateWallArgs = z.object({
+  component: ComponentHandle,
+  updates: PluginWallUpdates,
+})
+export type PluginDesignUpdateWallArgs = z.infer<
+  typeof PluginDesignUpdateWallArgs
+>
+
+/**
+ * Arguments for the slab-family updaters —
+ * {@linkcode PluginDesignUpdateApi.slab}, `floor`, `roof`, `ceiling`.
+ */
+export const PluginDesignUpdateSlabArgs = z.object({
+  component: ComponentHandle,
+  updates: PluginSlabUpdates,
+})
+export type PluginDesignUpdateSlabArgs = z.infer<
+  typeof PluginDesignUpdateSlabArgs
+>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.setElevation}. */
+export const PluginDesignSetElevationArgs = z.object({
+  component: ComponentHandle,
+  elevation: z.number(),
+})
+export type PluginDesignSetElevationArgs = z.infer<
+  typeof PluginDesignSetElevationArgs
+>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.setBaseOffset}. */
+export const PluginDesignSetBaseOffsetArgs = z.object({
+  component: ComponentHandle,
+  offset: z.number(),
+})
+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 const PluginDesignSetStoreyArgs = z.object({
+  components: z.array(ComponentHandle),
+  storey: z.number().int(),
+})
+export type PluginDesignSetStoreyArgs = z.infer<
+  typeof PluginDesignSetStoreyArgs
+>
+
+/**
+ * Object types {@linkcode PluginDesignUpdateApi.setObjectType} can turn a mass
+ * into — the `design.query` `type` vocabulary.
+ */
+export const PluginObjectType = PluginEntityType.extract([
+  "wall",
+  "roof",
+  "slab",
+  "floor",
+])
+export type PluginObjectType = z.infer<typeof PluginObjectType>
+
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.setObjectType}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The masses to convert (>= 1) |
+ * | `objectType` | {@linkcode PluginObjectType} | Target object type (`"wall"`, `"roof"`, `"slab"`, `"floor"`) |
+ */
+export const PluginDesignSetObjectTypeArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  objectType: PluginObjectType,
+})
+export type PluginDesignSetObjectTypeArgs = z.infer<
+  typeof PluginDesignSetObjectTypeArgs
+>
+
+/**
+ * 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 const PluginGridPatch = z.object({
+  angle: z.number().finite().optional(),
+  props: PluginGridStyleOptions.optional(),
+  storeyVisibility: z
+    .array(z.object({ storey: z.number().int(), visible: z.boolean() }))
+    .optional(),
+})
+export type PluginGridPatch = z.infer<typeof PluginGridPatch>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.grid}. */
+export const PluginDesignUpdateGridArgs = z.object({
+  grid: ComponentHandle,
+  patch: PluginGridPatch,
+})
+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).
+ *
+ * Native family edits accept `type` and/or sparse `values` from `design.catalog`.
+ * Length overrides use mm; dimensional arguments use SU. Contours and axes stay unchanged.
+ * Shared/type overrides are refused. A thickness argument must agree with the layer values.
+ * Family roof overhang is unsupported; use the native slab path for family overhang edits.
+ */
+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 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" } })
+   * ```
+   */
+  public 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}
+   * @throws PRECONDITION_FAILED for a void (a hole cut with `design.create.void`): delete it and
+   *   cut a new one
+   *
+   * @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" } })
+   * ```
+   */
+  public 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
+   * @throws PRECONDITION_FAILED for a void, like {@linkcode space}
+   *
+   * @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))
+   * ```
+   */
+  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>
+
+  /**
+   * Edit a parametric mass by patching its creation recipe and rebuilding the
+   * solid in place — the mass keeps its id, storey, materials, position and
+   * linked copies; only the geometry changes. Read the current record with
+   * `design.query.getParameters` first.
+   *
+   * `patch` is a partial of `record.values` — or the whole record you read
+   * back, edited. A key you leave out is unchanged (that includes
+   * `operations`). Each key you send replaces that value whole — a scalar, a
+   * point, a list or a record (`contour`, `profile`, `sections`, `path`,
+   * `options`, `operations`) alike — so send the complete value you read,
+   * edited (a partial `options` drops the switches it leaves out);
+   * `{ operations: [] }` drops every operation. An optional key
+   * the record does not carry yet may be patched in when the kind allows it:
+   * a straight extrusion acquires `twistInDegrees` or `topScale`, an
+   * options-less loft or sweep acquires `options` (`levels` is not one — send
+   * the angle, not the section count). A patch that changes nothing
+   * returns the current record and records no edit (no undo step). `kind` and
+   * `version` are immutable: to change the kind, build a new mass. Keys are the
+   * record's `values` keys for its `kind` (sphere: `centre`, `radius`;
+   * cylinder: `base`, `axis`, `radius`, `height`; torus: `centre`, `axis`,
+   * `majorRadius`, `minorRadius`; …) plus `operations`. To change a fillet
+   * radius, edit `operations[i].radius` in the record you read and send
+   * `{ operations }` back. Points and axes are WORLD coordinates in internal
+   * units, exactly as `getParameters` reports them.
+   *
+   * Rebuilds in memory first, then swaps onto the SAME component; every linked
+   * copy regenerates together. One undo step; saves and syncs to collaborators
+   * like any geometry edit. Kernel kinds (revolution, sweep, loft, primitives,
+   * any `operations`) run on OpenCascade — expect a short pause.
+   *
+   * @param component - a mass whose `getParameters` is non-null
+   * @param patch - partial `values` (+ optional `operations`), or the full edited record
+   * @returns the complete post-edit record, world coordinates (what
+   *   `getParameters` now returns)
+   * @throws PRECONDITION_FAILED when the component is not a mass (a family
+   *   instance: use `design.family.setParameters`).
+   *   Also PRECONDITION_FAILED when the mass carries no live recipe — built
+   *   from a boolean, split, `brepFromFaces`/`brepFromMesh` or drawn; edited
+   *   free-form since (push/pull, move face, boolean); or scaled with the
+   *   transform tool. `getParameters` returns `null` for exactly these.
+   *   Do not retry — rebuild it with a recipe constructor and say so.
+   *   A scaled mass is the exception: undo the scale and call again.
+   *   Also PRECONDITION_FAILED when the mass (or a linked copy) is **locked**
+   *   (the message says so). Locking is invisible to `getParameters` — a
+   *   locked parametric mass still reads back a full record. Unlock it (and
+   *   every linked copy) and call again; never rebuild it, the recipe is intact.
+   *   Also PRECONDITION_FAILED when an `operations` entry's edge/face selectors
+   *   no longer resolve on the rebuilt base (the message names the operation
+   *   and edge): re-select the edges on the new shape and re-apply that
+   *   operation.
+   *   Also PRECONDITION_FAILED when the edit is the first twist or taper — or
+   *   the straightening — of an extrusion that carries a shell, fillet or
+   *   chamfer (the kernel numbers its faces differently): send the twist/taper
+   *   keys with `operations: []` first (the message names them), re-select on
+   *   the new shape, then send `{ operations }` back.
+   *   Graph-bound spaces accept amount-only extrusion edits. Footprint, twist,
+   *   taper and operation edits require the owning boundary tools, so generated
+   *   walls, junctions and hosted openings remain synchronized.
+   * @throws VALIDATION for a key the kind does not have (the message lists the
+   *   kind's keys), `kind` or `version` in a partial patch, or a value outside
+   *   the constructor's own rules (torus tube ≥ ring, revolution angle ∉
+   *   (0, 360], a profile crossing its axis, a spline with fewer than
+   *   degree + 1 poles).
+   * @throws OPERATION_FAILED when the kernel cannot build the edited recipe;
+   *   the model is left unchanged.
+   *
+   * @examplePrompt Make the dome's radius 8 metres
+   * @examplePrompt Raise the podium to 5 m
+   * @examplePrompt Widen the vase — move its profile points 20 cm outward
+   * @examplePrompt Change the fillet on the rounded column to 300 mm
+   *
+   * # Example
+   * ```ts
+   * // { kind: "sphere", values: { centre, radius: 19.685 }, … }
+   * const before = await snaptrude.design.query.getParameters(dome)
+   * const after = await snaptrude.design.update.parameters(dome, { radius: 31.496 }) // 8 m in internal units
+   *
+   * // Fillet radius on a recorded result: read → edit → send the array back
+   * const rec = await snaptrude.design.query.getParameters(column)
+   * const operations = rec?.operations ?? []
+   * if (operations[0]?.op === "fillet") {
+   *   operations[0].radius = 1.181
+   *   await snaptrude.design.update.parameters(column, { operations })
+   * }
+   * ```
+   */
+  public abstract parameters(
+    component: ComponentHandle,
+    patch: MassParametersPatch,
+  ): PluginApiReturn<MassParametersRecord>
+
+  /**
+   * 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 })
+   * }
+   * ```
+   */
+  public 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 })
+   * ```
+   */
+  public 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 })
+   * ```
+   */
+  public 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 })
+   * ```
+   */
+  public 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 })
+   * ```
+   */
+  public abstract ceiling(
+    component: ComponentHandle,
+    updates: PluginSlabUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /** Replace a native beam family while preserving its authored axis. Values use mm/degrees.
+   * @param component Native beam. @param updates Saved family reference and optional instance values.
+   * @returns Affected component IDs. One undoable operation; unsupported geometry fails before mutation.
+   */
+  public abstract beam(
+    component: ComponentHandle,
+    updates: PluginFamilyUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /** Replace a native column family while preserving its authored axis. Values use mm/degrees.
+   * @param component Native column. @param updates Saved family reference and optional instance values.
+   * @returns Affected component IDs. One undoable operation; unsupported geometry fails before mutation.
+   */
+  public abstract column(
+    component: ComponentHandle,
+    updates: PluginFamilyUpdates,
+  ): 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)
+   * ```
+   */
+  public 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)
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public abstract setStorey(
+    components: ComponentHandle[],
+    storey: number,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Change the **object type** of one or more masses — turn a mass into a real
+   * wall, roof, slab or floor: the properties panel's Object Type dropdown,
+   * headless. The geometry is kept exactly as it is (a wedge stays a wedge;
+   * nothing is flattened to a default thickness), so a sloped mass built with
+   * `design.create.massFromBrep` becomes a sloped roof or a raked wall. The
+   * component keeps its handle, label and storey; it gains the target type's
+   * construction layers and properties, and the type's default material when
+   * the mass still wore the default. One undoable operation for the whole
+   * list; undo turns them back into masses.
+   *
+   * Instances convert as a family: passing one instance (or the source) of an
+   * instanced mass converts its source and every sibling; `affected` echoes
+   * every visible member (the hidden instancing template converts too but is
+   * not listed). A converted component cannot be converted again (same rule
+   * as the panel). A converted wall has no parametric centerline: it hosts
+   * doors and windows and exports, but neighbours do not re-mitre against it.
+   *
+   * Throws before anything changes (all-or-nothing) when a component is not a
+   * mass, is a plinth, is locked or in a locked bucket, already had its type
+   * changed, or when a handle is gone/forged.
+   *
+   * @param components - The masses to convert
+   * @param objectType - Target type: `"wall"`, `"roof"`, `"slab"` or `"floor"`
+   *   (the `design.query.getEntityType` vocabulary)
+   * @returns the visible components converted — the same handles, plus any
+   *   instance siblings pulled in by family expansion
+   *
+   * @examplePrompt Convert this mass into a wall
+   * @examplePrompt Turn the sloped mass into a roof
+   * @examplePrompt Make these masses real slabs
+   * @examplePrompt Change the object type of the selection to wall
+   * @examplePrompt Convert the wedge I built into a raked wall
+   * @examplePrompt Turn this mass into a floor
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromFaces(wedgeFaces)
+   * const wedge = await snaptrude.design.create.massFromBrep(brep, "Gable end")
+   * const { affected } = await snaptrude.design.update.setObjectType([wedge], "wall")
+   * console.log(await snaptrude.design.query.getEntityType(affected[0])) // "wall"
+   * ```
+   */
+  public abstract setObjectType(
+    components: ComponentHandle[],
+    objectType: PluginObjectType,
+  ): 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).
+   *
+   * Edge state is preserved, like the right panel: every edge's type
+   * (front/side/rear) is kept. For each type whose value changed (by more than
+   * 2 mm), the per-edge custom distances on edges of that type are cleared;
+   * custom distances on types whose value did not change are kept.
+   *
+   * @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 and `clearedEdgeSetbacks`,
+   *   the `edgeIndex` of each edge that lost its custom distance (empty when
+   *   none). Tell the user about any cleared edges.
+   * @throws If validation fails, the envelope does not exist, or generation
+   *   produces no renderable geometry. Also throws `PRECONDITION_FAILED`
+   *   (`details.reason: "STALE_EDGE_SETTINGS"`, nothing changes) when the site
+   *   outline changed since the edge settings were made. Tell the user;
+   *   editing any edge on the canvas setback pills resets the edge settings
+   *   to the new outline (dropping the old ones), after which you can retry.
+   *
+   * @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,
+   * )
+   * ```
+   */
+  public abstract buildableEnvelope(
+    buildableEnvelopeId: string,
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number,
+  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
+
+  /**
+   * Change one site edge's type (front / side / rear) and/or give that edge
+   * its own setback distance, the same as editing a setback pill on the
+   * canvas. One undo step; the pills and Site Analysis sheet refresh.
+   *
+   * Address the edge with `siteId` and `edgeIndex` from
+   * `program.site.listEdges()`. Setting `role` clears that edge's own
+   * distance. `setback: null` clears the edge's own distance and puts it back
+   * on its type's distance. When `role` and a numeric `setback` are both
+   * given, the role is applied first and then the setback, so the new distance
+   * wins. On the only edge of its type, a numeric setback becomes that type's
+   * value (like the canvas pills), so `null` afterwards has nothing to
+   * clear; set the type's value instead. Only call this when the user asks to
+   * change an edge.
+   *
+   * @param siteId - Site component id, from `program.site.listEdges()`.
+   * @param edgeIndex - Edge index from `program.site.listEdges()`; nonnegative
+   *   integer, upper bound checked by the host.
+   * @param patch - A {@linkcode PluginSiteEdgePatch}: `role`, `setback` (a
+   *   number in `lengthUnit`, or `null` to clear), and `lengthUnit` (required
+   *   with a numeric `setback`). Provide `role` and/or `setback`.
+   * @returns The refreshed {@linkcode PluginDesignUpdateSiteEdgeResult} for the
+   *   site, as `program.site.listEdges()` returns it.
+   * @throws
+   *   - `HANDLE_INVALID`: unknown `siteId` (invalid site handle).
+   *   - `VALIDATION`: `edgeIndex` is out of range or not a nonnegative
+   *     integer; when the index is out of range, `details` include `edgeCount`.
+   *   - `PRECONDITION_FAILED`, with `details.reason` one of:
+   *     - `NO_BUILDABLE_ENVELOPE`: the site has no envelope to store edge
+   *       settings on. Ask the user whether to create a default envelope with
+   *       `design.create.buildableEnvelopeFromSite(siteId)` or to create one
+   *       themselves; do not create one unasked.
+   *     - `MASSING_ENVELOPE`: the site's envelope is a massing envelope. Tell
+   *       the user; change nothing.
+   *     - `ENVELOPE_TRANSFORMED`: the envelope has been rotated or scaled, so
+   *       edge editing is unavailable. Tell the user.
+   *     - `STALE_EDGE_SETTINGS`: the site outline changed since the edge
+   *       settings were made. Tell the user; editing any edge on the canvas
+   *       setback pills resets the edge settings to the new outline (dropping
+   *       the old ones), after which you can retry.
+   *
+   * @examplePrompt Make edge 2 the front
+   * @examplePrompt Set just the north edge setback to 8 m
+   * @examplePrompt Remove the custom setback on edge 3
+   *
+   * # Example
+   * ```ts
+   * const [{ siteId }] = (await snaptrude.program.site.listEdges()).sites
+   * await snaptrude.design.update.siteEdge(siteId, 2, { role: "front" })
+   * await snaptrude.design.update.siteEdge(siteId, 3, { setback: 8, lengthUnit: "m" })
+   * await snaptrude.design.update.siteEdge(siteId, 3, { setback: null })
+   * ```
+   */
+  public abstract siteEdge(
+    siteId: string,
+    edgeIndex: number,
+    patch: PluginSiteEdgePatch,
+  ): PluginApiReturn<PluginDesignUpdateSiteEdgeResult>
+}