@snaptrude/plugin-core 0.9.13 → 0.9.15

package/src/api/design/family.ts

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
-import { ComponentHandle, Vec3Components } from "../../handles"
+import { BrepHandle, ComponentHandle, Vec3Components } from "../../handles"
 
 /**
  * `snaptrude.design.family.*` — author NATIVE parametric families from a JSON spec.
@@ -18,15 +18,21 @@ import { ComponentHandle, Vec3Components } from "../../handles"
  * getReference()        read the spec DSL once — grammar, ops, expressions, example
  * prepare({ bundle })   validate + compile + show a live ghost; nothing committed
  * flex({ values })      re-run at new values; returns the geometry delta
- * place()               arm placement — the USER clicks to drop it
- * create({ name })      commit it to the project's family library
+ * place({ position })   put it in the model — saves the family as the first instance drops
+ * place()               save the family, then arm placement — the USER clicks to drop it
+ * create({ teamId })    share with a team; a save with nothing placed also drops one instance
  * ```
  *
+ * `place` saves the prepared family to the user's personal library, so it
+ * survives reload with no extra step; finish on `place`, not on `create`.
+ *
  * ## Read getReference() first
  *
  * The spec DSL is a closed expression language with its own op set, coordinate
- * convention (**+Y up, Snaptrude units** — the scene's own unit, 1 SU = 254 mm;
- * literals may carry a unit suffix such as `600mm` or `2ft`)
+ * convention (**+Y up, Snaptrude units** — the scene's own unit, 1 SU = 254 mm,
+ * the same unit `core.units.getBabylonType()` names and every geometry API
+ * takes; literals inside spec expressions may carry a unit suffix such as
+ * `600mm` or `2ft`)
  * and part-naming law. It is deliberately NOT duplicated in these types:
  * {@linkcode PluginDesignFamilyApi.getReference} returns the whole reference,
  * generated from a family that is actually registered in the host, so the
@@ -41,6 +47,18 @@ import { ComponentHandle, Vec3Components } from "../../handles"
  * leaves the previous good draft standing, so it costs nothing but the node you
  * broke. Re-authoring from scratch throws away everything already correct.
  *
+ * ## Curved parts are exact
+ *
+ * A part whose sketch has a curved edge — any `revolve`, or an `extrude` /
+ * `sweep` / `loft` with an arc or circle in its profile (or an arc in a sweep
+ * path) — is built by the exact geometry kernel, the same one behind curved
+ * masses. Straight-edged parts keep the fast mesh builder. `getParameters` on a
+ * placed component reports which built each part in `parts[].engine`, and a
+ * kernel part carries a `brep`: read it with `core.geom.query.brep.*` and
+ * `core.geom.query.face.getSurfaceKind` — the same face-kind check as for a
+ * curved mass. If the kernel is unavailable a part falls back to the mesh
+ * builder (`engine: "mesh"`) rather than failing the family.
+ *
  * Accessed via `snaptrude.design.family`.
  */
 export abstract class PluginDesignFamilyApi {
@@ -68,20 +86,25 @@ export abstract class PluginDesignFamilyApi {
 
   /**
    * Validate, compile and preview a family spec. Nothing is committed to the
-   * model or the library — call {@linkcode PluginDesignFamilyApi.place} or
-   * {@linkcode PluginDesignFamilyApi.create} for that.
+   * model or the library — call {@linkcode PluginDesignFamilyApi.place} to put
+   * it in the model, which also saves it.
    *
    * Safe to call repeatedly while iterating. On success, check `partCount` and
    * `bbox` against what you intended before treating the family as correct — a
    * facade that built 3 parts, or a 3 m screen reporting 40 m of height, is a
    * visible bug the validator cannot catch.
    *
+   * Lengths — the spec's bare numbers, `bbox`, the sheet's `length` values — are
+   * Snaptrude units: the same 254 mm unit as the kernel's internal (`"babylon"`)
+   * unit. A unit suffix (`600mm`) is legal only inside a spec expression.
+   *
    * @param args The spec bundle, as `{ bundle }` or `{ spec }`
    * @returns Build report, or `{ ok: false, errors }` with JSON-pointer paths
    *
    * @examplePrompt Make a louvre screen with adjustable blade count and tilt
    * @examplePrompt Design a curtain wall panel family with 8 bays
    * @examplePrompt Create a railing family I can adjust
+   * @examplePrompt Make a pendant lamp family with a domed shade I can resize
    *
    * # Example
    * ```ts
@@ -147,6 +170,9 @@ export abstract class PluginDesignFamilyApi {
    * Put a family into the model — either the prepared draft or any family from
    * {@linkcode PluginDesignFamilyApi.list}.
    *
+   * Placing the prepared draft saves it to the user's personal library first,
+   * so its instances survive reload.
+   *
    * Two modes, chosen by whether you pass `position`:
    *
    * **With `position`** the component is created there and then, undoably. Use
@@ -195,6 +221,9 @@ export abstract class PluginDesignFamilyApi {
    * label the user says, and a Revit-imported family carries parameters that
    * do not drive geometry at all.
    *
+   * `length` values are Snaptrude units: the same 254 mm unit as the kernel's
+   * internal (`"babylon"`) unit — convert with `core.units.convert` to report.
+   *
    * @param args The component to read
    * @returns Its definition, current values, and the parameter sheet
    *
@@ -220,6 +249,11 @@ export abstract class PluginDesignFamilyApi {
    * that does not is accepted and stored (it round-trips to Revit) but nothing
    * visible happens — say so rather than claiming a change the user cannot see.
    *
+   * `length` values are Snaptrude units: the same 254 mm unit as the kernel's
+   * internal (`"babylon"`) unit — convert the user's number with
+   * `core.units.convert` first; a bare `400` is 400 SU, not 400 mm. Kernel part
+   * breps read before the edit are stale: re-read `getParameters`.
+   *
    * @param args The component and the values to change
    * @returns The values now in effect
    *
@@ -236,8 +270,11 @@ export abstract class PluginDesignFamilyApi {
   ): PluginApiReturn<PluginFamilyInstanceParameters>
 
   /**
-   * Commit the prepared bundle to the project's parametric-definition library,
-   * so it survives the session and appears in the Families panel.
+   * Save the prepared bundle to the library — the user's personal library
+   * unless `teamId` is given. {@linkcode PluginDesignFamilyApi.place} already
+   * saves, so `create` is for sharing with a team. When nothing of the family is
+   * in the model yet, one instance is also dropped at the centre of the current
+   * view on the active storey (`placed: true`), so a save is never invisible.
    *
    * @param args Optional library name and team scope
    * @returns The catalogued definition's id and version
@@ -318,7 +355,7 @@ export interface PluginFamilyParameter {
   key: string
   label: string
   type: "length" | "integer" | "enum" | "text" | "boolean"
-  /** Current value. `length`/`integer` are numbers; the rest are strings. */
+  /** Current value. `length` (Snaptrude units) and `integer` are numbers; the rest are strings. */
   value: string | number
   default: string | number
   /**
@@ -354,6 +391,25 @@ export interface PluginFamilyDiagnostic {
   hint?: string
 }
 
+/**
+ * One placed part and which engine built it, from `getParameters`. `"kernel"` —
+ * a curved sketch built exactly; `"mesh"` — straight-edged, or the kernel
+ * fallback.
+ */
+export interface PluginFamilyPart {
+  name: string
+  engine: "kernel" | "mesh"
+  /**
+   * Kernel parts only: the part's exact solid, for `core.geom.query.brep.*` /
+   * `core.geom.query.face.getSurfaceKind`. READ-ONLY and PART-LOCAL — in the
+   * part's own frame, not where the component sits, so never pass it to a
+   * boolean or `design.create.massFromBrep` (a family changes only through
+   * `setParameters`). Valid until the next parameter change: re-read
+   * `getParameters` after `setParameters`.
+   */
+  brep?: BrepHandle
+}
+
 /** What `prepare` reports. */
 export interface PluginFamilyPrepareResult {
   /** `false` means the spec was rejected — read `errors`, fix, re-prepare. */
@@ -455,6 +511,8 @@ export interface PluginFamilyInstanceParameters {
   values: Record<string, number | string>
   /** The sheet: what each key means, its bounds, and whether it moves geometry. */
   parameters: PluginFamilyParameter[]
+  /** The placed parts; kernel parts carry their exact `brep`. */
+  parts?: PluginFamilyPart[]
   /** Present when `getParameters` was asked for a `snapshot`. */
   snapshot?: PluginFamilySnapshot
 }

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

@@ -19,8 +19,8 @@ import {
  * {@linkcode PluginDesignQueryGeometryApi.getCenterline} mints a
  * {@linkcode CurveHandle} for a wall's core curve.
  * {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes} is the
- * handle-free exception: it returns the triangulated render meshes as plain
- * world-space arrays.
+ * handle-free exception: it returns `{ meshes }` — the triangulated render
+ * meshes as plain world-space arrays, wrapped in an object, never bare.
  *
  * Returned handles are session-ephemeral and go stale on undo/redo/re-topologize
  * — re-fetch a fresh one after edits.
@@ -34,10 +34,26 @@ export abstract class PluginDesignQueryGeometryApi {
    * scene entity, as a reusable {@linkcode BrepHandle} for the
    * `core.geom.query.brep.*` reads.
    *
+   * **Frame.** By default the brep comes back in the component's own LOCAL frame
+   * (its vertices are relative to the mesh origin, exactly as stored). This is
+   * the long-standing default, and existing callers rely on it. Pass
+   * `{ frame: "world" }` to get the same solid placed where it sits in the
+   * scene (world coordinates, like
+   * `getBottomContour` / `getTriangulatedMeshes` and every `design.query.measure`
+   * read). Use `"world"` whenever the handle will be COMBINED with other scene
+   * geometry or committed back beside its source: booleans between two scene
+   * masses, `brepFromFillet` / `brepFromShell` / `brepFromOffset` /
+   * `brepFromChamfer` on a scene mass followed by `massFromBrep`, or comparing
+   * its vertices with a bounding box. A world-frame handle from a parametrically
+   * live mass also carries that mass's recipe, so an operation result keeps an
+   * editable record.
+   *
    * @param component - The scene component to read
-   * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry
+   * @param options - `frame`: `"local"` (default, mesh-local coordinates) or `"world"` (scene coordinates)
+   * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry — also `null` for a parametric family: read `design.family.getParameters({ component }).parts[].brep`
    *
    * @examplePrompt Get the 3D solid geometry of the selected wall
+   * @examplePrompt Round the top rim of this column and put it back where it is
    * @examplePrompt How many faces does this mass have?
    * @examplePrompt Inspect the mesh of this slab so I can look at its faces and edges
    * @examplePrompt Read the vertices of the selected column's geometry
@@ -48,10 +64,16 @@ export abstract class PluginDesignQueryGeometryApi {
    * if (brep) {
    *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
    * }
+   *
+   * // Operate on a scene mass and commit the result where the mass sits:
+   * const placed = await snaptrude.design.query.geometry.getBrep(mass, { frame: "world" })
+   * const rounded = await snaptrude.core.geom.create.brepFromFillet(placed, edges, 0.2)
+   * await snaptrude.design.create.massFromBrep(rounded, "Rounded")
    * ```
    */
   public abstract getBrep(
     component: ComponentHandle,
+    options?: PluginDesignQueryGeometryGetBrepOptions,
   ): PluginApiReturn<BrepHandle | null>
 
   /**
@@ -126,7 +148,8 @@ export abstract class PluginDesignQueryGeometryApi {
    * Get the **triangulated render meshes** of scene components as plain,
    * serializable arrays — flat world-space vertex `positions` (`[x0, y0, z0,
    * x1, …]`) and triangle `indices` (three per triangle), one record per
-   * requested component.
+   * requested component. The result is `{ meshes }`, not a bare array —
+   * destructure it before iterating.
    *
    * Unlike the other `geometry.*` reads this does NOT mint kernel handles — the
    * raw arrays cross the boundary directly, ready for export, custom analysis,
@@ -189,8 +212,16 @@ export abstract class PluginDesignQueryGeometryApi {
  * |---|---|---|
  * | `component` | {@linkcode ComponentHandle} | The scene component to read |
  */
+/** Options for {@linkcode PluginDesignQueryGeometryApi.getBrep}: `frame` defaults to `"local"`. */
+export type PluginDesignQueryGeometryGetBrepOptions = { frame?: "local" | "world" }
+export const PluginDesignQueryGeometryGetBrepOptions: z.ZodType<
+  PluginDesignQueryGeometryGetBrepOptions,
+  PluginDesignQueryGeometryGetBrepOptions
+> = z.object({ frame: z.enum(["local", "world"]).optional() })
+
 export const PluginDesignQueryGeometryGetBrepArgs = z.object({
   component: ComponentHandle,
+  options: PluginDesignQueryGeometryGetBrepOptions.optional(),
 })
 
 export type PluginDesignQueryGeometryGetBrepArgs = z.infer<

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

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle, BBoxComponents } from "../../../handles"
+import type { MassParametersRecord } from "../../../massParameters"
 import {
   PluginSpaceType,
   PluginMassType,
@@ -1040,6 +1041,55 @@ export abstract class PluginDesignQueryApi {
     staircase: ComponentHandle,
   ): PluginApiReturn<PluginStaircaseParams | null>
 
+  /**
+   * Read a mass's creation-parameter record — the recipe it was built from
+   * (`kind` plus the values that constructor was called with). Present on
+   * masses committed from a `core.geom.create` brep constructor that carries a
+   * recipe: {@linkcode MassParametersRecord} covers the four primitives
+   * (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.
+   *
+   * A fillet, chamfer, shell or offset of a recorded solid keeps the record
+   * too: `kind` stays the base constructor and the operation is appended to the
+   * record's `operations` list. Edit any of it with `design.update.parameters`.
+   *
+   * `null` for everything else — drawn masses, imported geometry, booleans,
+   * split parts, `brepFromFaces` / `brepFromMesh`, and results built on a
+   * source that carried no record — and for a mass whose record no longer
+   * matches what is on
+   * screen (a later free-form edit dropped the recipe, or the mass carries a
+   * baked scale). `null` too when the recipe was not recordable: the record
+   * schema has its own caps (a sweep path of at most 512 points, a loft of at
+   * most 32 sections, at most 8 chained `operations`, at most 256 curves in one
+   * profile loop and 64 holes in one contour), and a mass built past one of
+   * them — through a route that does not enforce the matching creator cap —
+   * commits as ordinary geometry carrying no record. The `operations` cap is
+   * the one an agent can walk into by accident: a 9th chained
+   * fillet/chamfer/shell/offset drops the record silently, so the result
+   * commits as ordinary geometry and reads back `null` here. A record is never
+   * reported unless it is still the truth.
+   *
+   * Points and axes come back in **world** coordinates. Pure read — nothing is
+   * created or modified.
+   *
+   * @param component - the mass's {@linkcode ComponentHandle}
+   * @returns the {@linkcode MassParametersRecord}, or `null`
+   *
+   * @examplePrompt What radius is this sphere?
+   * @examplePrompt Is this mass parametric?
+   * @examplePrompt Read back the dome's creation parameters
+   * @examplePrompt How tall was this cylinder made?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses({ isSelected: true })
+   * const params = await snaptrude.design.query.getParameters(mass)
+   * if (params?.kind === "sphere") console.log("radius:", params.values.radius)
+   * ```
+   */
+  public abstract getParameters(
+    component: ComponentHandle,
+  ): PluginApiReturn<MassParametersRecord | null>
+
   /**
    * Get the **union** axis-aligned bounding box enclosing a set of entities.
    *

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

@@ -9,6 +9,7 @@ import {
   PluginSpaceUpdateResult,
 } from "../../entity/space"
 import { PluginDesignChangeResult } from "../lock"
+import { MassParametersPatch, type MassParametersRecord } from "../../../massParameters"
 import {
   PluginBuildableEnvelopePolygonVertex,
   PluginBuildableEnvelopeSetbackTier,
@@ -16,6 +17,7 @@ import {
   PluginBuildableEnvelopeUpdateResult,
 } from "../../entity/buildableEnvelope"
 import { PluginGridStyleOptions } from "../create/grids"
+import { PluginEntityType } from "../query"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -137,6 +139,22 @@ 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
@@ -239,6 +257,34 @@ 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
@@ -258,7 +304,9 @@ export const PluginDesignUpdateGridArgs = z.object({
   grid: ComponentHandle,
   patch: PluginGridPatch,
 })
-export type PluginDesignUpdateGridArgs = z.infer<typeof PluginDesignUpdateGridArgs>
+export type PluginDesignUpdateGridArgs = z.infer<
+  typeof PluginDesignUpdateGridArgs
+>
 
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
@@ -462,6 +510,95 @@ export abstract class PluginDesignUpdateApi {
     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**
@@ -743,6 +880,54 @@ export abstract class PluginDesignUpdateApi {
     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