@snaptrude/plugin-core 0.0.0-dev-20260827135706 → 0.0.0-dev-20260907135026

package/src/api/core/geom/query/brep.ts

@@ -174,6 +174,11 @@ export abstract class PluginGeomQueryBrepApi {
    * | `"line"` | `startPoint`, `endPoint`, `length` |
    * | `"arc"` | `startPoint`, `endPoint`, `centre`, `axis`, `radius`, `length` |
    * | `"circle"` | `centre`, `axis`, `radius`, `length` — a full-circle edge (e.g. a cylinder cap rim) |
+   * | `"spline"` | `startPoint`, `endPoint`, `degree`, `controlPoints`, `knots`, `length` — a free-form NURBS edge |
+   *
+   * For a `"spline"` edge, `knots` is the **expanded** knot vector — each knot
+   * repeated by its multiplicity, the textbook NURBS form — so
+   * `knots.length === controlPoints.length + degree + 1`.
    *
    * @param brep The brep the edge belongs to
    * @param edge The edge whose curve to read
@@ -184,6 +189,7 @@ export abstract class PluginGeomQueryBrepApi {
    * @examplePrompt Is this edge straight or an arc?
    * @examplePrompt Get the exact start and end points of this edge
    * @examplePrompt Measure the length of each edge of this mass
+   * @examplePrompt Read the control points of this curved edge
    *
    * # Example
    * ```ts
@@ -219,6 +225,16 @@ export abstract class PluginGeomQueryBrepApi {
         radius: number
         length: number
       }
+    | {
+        type: "spline"
+        startPoint: Vec3Components
+        endPoint: Vec3Components
+        degree: number
+        controlPoints: Vec3Components[]
+        /** Expanded by multiplicity: `controlPoints.length + degree + 1` entries. */
+        knots: number[]
+        length: number
+      }
   >
 
   /**
@@ -366,6 +382,37 @@ export abstract class PluginGeomQueryBrepApi {
    */
   public abstract getBoundingBox(brep: BrepHandle): PluginApiReturn<BBoxComponents>
 
+  /**
+   * Get the enclosed **volume** of a closed solid, integrated from its exact
+   * surfaces. Curved faces are measured analytically, not from their
+   * tessellation — a real sphere of radius 5 reports 523.6, whatever its
+   * triangle count. That makes this the reliable way to confirm a solid is the
+   * shape you intended (a torus should measure 2·π²·R·r²).
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param brep The solid to measure
+   * @returns The enclosed volume in cubic raw Babylon units
+   * @throws OPERATION_FAILED if the kernel cannot compute the volume (the brep
+   *   is not a closed solid)
+   *
+   * @examplePrompt What is the volume of this mass?
+   * @examplePrompt How much concrete is in this shape?
+   * @examplePrompt Check the volume of the dome I just made
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const volume = await snaptrude.core.geom.query.brep.getVolume(brep)
+   *   console.log("volume:", volume)
+   * }
+   * ```
+   */
+  public abstract getVolume(brep: BrepHandle): PluginApiReturn<number>
+
   /**
    * Test whether two breps are geometrically equal.
    * @param brepA First brep
@@ -534,6 +581,10 @@ export type PluginGeomQueryBrepGetBoundingBoxArgs = z.infer<
   typeof PluginGeomQueryBrepGetBoundingBoxArgs
 >
 
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getVolume}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetVolumeArgs = brepArg
+export type PluginGeomQueryBrepGetVolumeArgs = z.infer<typeof PluginGeomQueryBrepGetVolumeArgs>
+
 /**
  * Arguments for {@linkcode PluginGeomQueryBrepApi.isEqual}.
  *

package/src/api/core/geom/query/curve.ts

@@ -3,8 +3,8 @@ import { PluginApiReturn } from "../../../../types"
 import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../../handles"
 
 /**
- * Curve queries — read-only geometric questions about curves (lines and arcs)
- * and the relationships between two curves (all-handle model, §11).
+ * Curve queries — read-only geometric questions about curves (lines, arcs and
+ * splines) and the relationships between two curves (all-handle model, §11).
  *
  * Every method takes opaque curve handles ({@linkcode CurveHandle}/{@linkcode LineHandle})
  * and point handles ({@linkcode Vec3Handle}) and returns plain values — points as
@@ -13,6 +13,29 @@ import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../..
  * {@linkcode CurveHandle} (or `null` when there is no result). No query mutates its
  * inputs.
  *
+ * ## Splines
+ *
+ * A {@linkcode CurveHandle} is a line, an arc, or a NURBS spline (minted by
+ * `core.geom.create.splineFromPoints`). Every method here accepts a spline at
+ * compile time, but only the reads backed by the engine's spline math answer
+ * for one today. The rest throw `PRECONDITION_FAILED` ("not supported for
+ * splines yet") — a typed refusal, never a quietly wrong answer.
+ *
+ * | Splines | Members |
+ * |---|---|
+ * | **supported** | {@linkcode PluginGeomQueryCurveApi.getStartPoint}, {@linkcode PluginGeomQueryCurveApi.getEndPoint}, {@linkcode PluginGeomQueryCurveApi.getLength}, {@linkcode PluginGeomQueryCurveApi.getTangent}, {@linkcode PluginGeomQueryCurveApi.listPoints}, {@linkcode PluginGeomQueryCurveApi.getNearestPoint} |
+ * | **not yet** | `getMidPoint`, `getChordLength`, `getNormal`, `getProjection`, `getPointAtDistance`, `getParameterAtPoint`, `getCurvature`, `getDistanceToPoint`, `getDistanceAlong`, `listSubdivisions`, `isLinear`, `isOnCurve`, `hasPoint`, `isEqual`, `isOverlapping`, `getCommonPart`, `listIntersections`, `getMergedCurve`, `isContinuous`, `isParallel`, `getShortestGap`, `getDistanceBetween` |
+ *
+ * {@linkcode PluginGeomQueryCurveApi.isOverlapping} is deliberately in the
+ * second row: its line/arc path falls back to structural equality, which would
+ * answer a spline pair wrongly rather than not at all.
+ *
+ * To work around the second row, sample the curve —
+ * {@linkcode PluginGeomQueryCurveApi.listPoints} then the ordinary
+ * `core.math.vec3` operations — or read a spline brep edge exactly with
+ * `core.geom.query.brep.getEdgeCurve`, which returns its degree, control points
+ * and knots.
+ *
  * Accessed via `snaptrude.core.geom.query.curve`.
  */
 export abstract class PluginGeomQueryCurveApi {

package/src/api/core/geom/query/edge.ts

@@ -69,9 +69,9 @@ export abstract class PluginGeomQueryEdgeApi {
   public abstract listVertices(edge: EdgeHandle): PluginApiReturn<VertexHandle[]>
 
   /**
-   * Get the underlying curve geometry of an edge (a line or arc).
+   * Get the underlying curve geometry of an edge (a line, arc or spline).
    * @param edge The edge to query
-   * @returns The curve as a {@linkcode CurveHandle}, or `null` if it is a circle or unset
+   * @returns The curve as a {@linkcode CurveHandle} (`line_`, `arc_` or `spline_`), or `null` if it is a circle or unset
    *
    * # Example
    * ```ts

package/src/api/core/geom/query/face.ts

@@ -59,6 +59,49 @@ export abstract class PluginGeomQueryFaceApi {
    */
   public abstract getMaterialIndex(face: FaceHandle): PluginApiReturn<number>
 
+  /**
+   * Read what KIND of surface a face lies on. This is the one read that tells a
+   * genuinely curved face from a faceted approximation of one: every face of a
+   * 200-triangle "dome" answers `"plane"`, while a real dome has faces
+   * answering `"sphere"`. Use it to confirm a curved solid actually came out
+   * curved.
+   *
+   * | Value | Surface |
+   * |---|---|
+   * | `"plane"` | Flat face |
+   * | `"cylinder"` | Cylindrical face — constant radius about an axis |
+   * | `"cone"` | Conical face — a tapered ring (a cone or frustum side) |
+   * | `"sphere"` | Spherical face |
+   * | `"torus"` | Toroidal face — the ring surface of a donut |
+   * | `"spline"` | Free-form NURBS face |
+   *
+   * Pure read: no geometry kernel is loaded.
+   *
+   * @param face The face to query
+   * @returns The surface kind (see the table), or `null` when the face carries
+   *   no surface classification
+   *
+   * @examplePrompt Is this face flat or curved?
+   * @examplePrompt Check that this dome is a real sphere, not a faceted approximation
+   * @examplePrompt What kind of surface is this face?
+   * @examplePrompt How many curved faces does this mass have?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const kinds = []
+   *   for (const face of faces) kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face))
+   *   console.log("spherical faces:", kinds.filter((k) => k === "sphere").length)
+   * }
+   * ```
+   */
+  public abstract getSurfaceKind(
+    face: FaceHandle,
+  ): PluginApiReturn<"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null>
+
   /**
    * Get a seed half-edge of a face's outer loop.
    * @param face The face to query
@@ -312,6 +355,12 @@ export type PluginGeomQueryFaceGetMaterialIndexArgs = z.infer<
   typeof PluginGeomQueryFaceGetMaterialIndexArgs
 >
 
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getSurfaceKind}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceGetSurfaceKindArgs = faceArg
+export type PluginGeomQueryFaceGetSurfaceKindArgs = z.infer<
+  typeof PluginGeomQueryFaceGetSurfaceKindArgs
+>
+
 /** Arguments for {@linkcode PluginGeomQueryFaceApi.getHalfEdge}. `{ face: FaceHandle }` */
 export const PluginGeomQueryFaceGetHalfEdgeArgs = faceArg
 export type PluginGeomQueryFaceGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryFaceGetHalfEdgeArgs>

package/src/api/design/family.ts

@@ -1,5 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import { ComponentHandle, Vec3Components } from "../../handles"
 
 /**
  * `snaptrude.design.family.*` — author NATIVE parametric families from a JSON spec.
@@ -142,23 +143,96 @@ export abstract class PluginDesignFamilyApi {
   public abstract list(): PluginApiReturn<PluginFamilySummary[]>
 
   /**
-   * Arm placement with the prepared family.
+   * Put a family into the model — either the prepared draft or any family from
+   * {@linkcode PluginDesignFamilyApi.list}.
    *
-   * This does **not** create geometry. It puts the editor into placement mode
-   * with a ghost on the cursor; the user clicks in the canvas to drop it, the
-   * same as for any other family. Tell the user to click.
+   * Two modes, chosen by whether you pass `position`:
    *
-   * @returns Which family was armed
+   * **With `position`** the component is created there and then, undoably. Use
+   * this when you know where it goes — you were given coordinates, or you are
+   * copying an existing instance. The returned `component` handle works with
+   * `design.transform.move` / `.rotate` and with
+   * {@linkcode PluginDesignFamilyApi.setParameters}.
+   *
+   * **Without `position`** it arms placement mode with a ghost on the cursor
+   * and returns immediately — no geometry yet. The USER clicks to drop it, so
+   * tell them to. Prefer this when the location is a judgement call.
+   *
+   * To COPY a placed component, place its family again at the new position with
+   * the same `values` — there is no separate copy call.
+   *
+   * @param args Which family, where, and at what parameter values
+   * @returns What was placed; `component` is present only in positioned mode
    *
    * @examplePrompt Place it in the model
-   * @examplePrompt Let me put this on the facade
+   * @examplePrompt Put a louvre screen at the origin
+   * @examplePrompt Copy that table two metres to the right
    *
    * # Example
    * ```ts
+   * // positioned — geometry exists when this resolves
+   * const { component } = await snaptrude.design.family.place({
+   *   id: "revit:gypsum-stud-partition~90ad72",
+   *   position: { x: 0, y: 0, z: 0 },
+   *   rotation: 90,
+   * })
+   * await snaptrude.design.transform.move([component], { x: 2, y: 0, z: 0 })
+   *
+   * // interactive — the user clicks
    * await snaptrude.design.family.place()
    * ```
    */
-  public abstract place(): PluginApiReturn<PluginFamilyPlaceResult>
+  public abstract place(
+    args?: PluginDesignFamilyPlaceArgs,
+  ): PluginApiReturn<PluginFamilyPlaceResult>
+
+  /**
+   * Read a placed component's current parameter values and its sheet.
+   *
+   * Use before {@linkcode PluginDesignFamilyApi.setParameters} so you change
+   * what is actually there: parameter KEYS are the family's own, not the
+   * label the user says, and a Revit-imported family carries parameters that
+   * do not drive geometry at all.
+   *
+   * @param args The component to read
+   * @returns Its definition, current values, and the parameter sheet
+   *
+   * @examplePrompt What size is that table?
+   * @examplePrompt Show me the parameters on this partition
+   *
+   * # Example
+   * ```ts
+   * const { values, parameters } = await snaptrude.design.family.getParameters({ component })
+   * ```
+   */
+  public abstract getParameters(
+    args: PluginDesignFamilyGetParametersArgs,
+  ): PluginApiReturn<PluginFamilyInstanceParameters | null>
+
+  /**
+   * Change a placed component's parameters and rebuild its geometry in place.
+   *
+   * Partial: pass only what changes. The component keeps its position,
+   * rotation and identity — this is an edit, not a replace, and it is undoable.
+   *
+   * Only parameters with `drivesGeometry` actually move the mesh. Setting one
+   * 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.
+   *
+   * @param args The component and the values to change
+   * @returns The values now in effect
+   *
+   * @examplePrompt Make that table seat 8
+   * @examplePrompt Change the stud spacing to 400
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.family.setParameters({ component, values: { seats: 8 } })
+   * ```
+   */
+  public abstract setParameters(
+    args: PluginDesignFamilySetParametersArgs,
+  ): PluginApiReturn<PluginFamilyInstanceParameters>
 
   /**
    * Commit the prepared bundle to the project's parametric-definition library,
@@ -301,7 +375,7 @@ export interface PluginFamilyFlexResult {
   error?: string
 }
 
-/** One registered parametric family. */
+/** One family available to place — from the session registry or the catalog. */
 export interface PluginFamilySummary {
   id: string
   version: number
@@ -309,6 +383,18 @@ export interface PluginFamilySummary {
   category?: string
   /** Number of rows on the family's parameter sheet. */
   parameters: number
+  /**
+   * Where the family came from, which decides how far you can edit it.
+   *
+   * `"native"` — authored from a JSON spec through this API. Its recipe is
+   * data, so every parameter genuinely re-runs the geometry.
+   *
+   * `"revit"` — imported from a Revit family. Parameters exist and are
+   * editable, but only those the importer could bind to geometry actually
+   * change the mesh; the rest are carried for round-tripping. Check
+   * `drivesGeometry` on the parameter before promising the user a change.
+   */
+  kind: "native" | "revit"
 }
 
 /** What `place` reports. */
@@ -316,9 +402,27 @@ export interface PluginFamilyPlaceResult {
   ok: boolean
   familyId?: string
   version?: number
+  /**
+   * The created component — present ONLY when `position` was given. In
+   * interactive mode nothing exists yet, so there is nothing to hand back;
+   * the user has not clicked.
+   */
+  component?: ComponentHandle
   error?: string
 }
 
+/** A placed component's parameter state, from `getParameters` / `setParameters`. */
+export interface PluginFamilyInstanceParameters {
+  /** The definition this instance is pinned to. */
+  familyId: string
+  version: number
+  label: string
+  /** Current values, keyed by parameter key. */
+  values: Record<string, number | string>
+  /** The sheet: what each key means, its bounds, and whether it moves geometry. */
+  parameters: PluginFamilyParameter[]
+}
+
 /** What `create` reports. */
 export interface PluginFamilyCreateResult {
   ok: boolean
@@ -386,3 +490,55 @@ export const PluginDesignFamilyCreateArgs = z.object({
   teamId: z.string().optional(),
 })
 export type PluginDesignFamilyCreateArgs = z.infer<typeof PluginDesignFamilyCreateArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Family to place, from {@linkcode PluginDesignFamilyApi.list}. Omit to place the prepared draft |
+ * | `version` | `number` | Exact version; defaults to the newest known |
+ * | `position` | `{ x, y, z }` | Place HERE, without user interaction. Omit to arm the cursor instead |
+ * | `rotation` | `number` | Yaw in degrees about +Y. Only with `position` |
+ * | `values` | `Record<string, number \| string>` | Parameter values for THIS instance |
+ * | `storey` | `number` | Storey to place on; defaults to the active one |
+ */
+export const PluginDesignFamilyPlaceArgs = z.object({
+  id: z.string().optional(),
+  version: z.number().int().positive().optional(),
+  position: Vec3Components.optional(),
+  rotation: z.number().optional(),
+  values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
+  storey: z.number().int().optional(),
+})
+export type PluginDesignFamilyPlaceArgs = z.infer<typeof PluginDesignFamilyPlaceArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.getParameters}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | A placed parametric component |
+ */
+export const PluginDesignFamilyGetParametersArgs = z.object({
+  component: ComponentHandle,
+})
+export type PluginDesignFamilyGetParametersArgs = z.infer<
+  typeof PluginDesignFamilyGetParametersArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.setParameters}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | A placed parametric component |
+ * | `values` | `Record<string, number \| string>` | Values to change (partial) |
+ */
+export const PluginDesignFamilySetParametersArgs = z.object({
+  component: ComponentHandle,
+  values: z.record(z.string(), z.union([z.number(), z.string()])),
+})
+export type PluginDesignFamilySetParametersArgs = z.infer<
+  typeof PluginDesignFamilySetParametersArgs
+>

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

@@ -34,10 +34,25 @@ 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) — the
+   * behaviour every 0.9.x caller relies on. 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
+   * @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
    *
    * @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 +63,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>
 
   /**
@@ -189,8 +210,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,
@@ -41,6 +42,7 @@ import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
  * | `"curtainWall"` | Parametric curtain wall |
  * | `"mullion"` | Curtain-wall mullion |
  * | `"panel"` | Curtain-wall panel |
+ * | `"parametricComponent"` | A placed parametric family instance (native or Revit-imported). Its geometry is rebuilt from `design.family` parameters, so read and drive it through `design.family.getParameters` / `setParameters` rather than editing its meshes. |
  */
 export const PluginEntityType = z.enum([
   "wall",
@@ -60,6 +62,7 @@ export const PluginEntityType = z.enum([
   "curtainWall",
   "mullion",
   "panel",
+  "parametricComponent",
 ])
 export type PluginEntityType = z.infer<typeof PluginEntityType>
 
@@ -1012,6 +1015,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,
@@ -136,6 +137,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
@@ -409,6 +426,83 @@ 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`). Scalars and points MERGE by key (`{ radius: 8 }` changes
+   * only the radius); arrays (`contour`, `sections`, `path`, `profile`,
+   * `operations`) REPLACE WHOLE when present — send the complete new list;
+   * `{ operations: [] }` drops every operation. 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 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.
+   *   Also PRECONDITION_FAILED when the mass is **locked** (the message says
+   *   so). Locking is invisible to `getParameters` — a locked parametric mass
+   *   still reads back a full record — so this is the one PRECONDITION_FAILED
+   *   the read cannot predict. Unlock the mass 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.
+   * @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**