@snaptrude/plugin-core 0.9.13 → 0.9.14-networks-20261001.1

package/src/api/design/index.ts

@@ -19,6 +19,7 @@ import { PluginDesignTypesApi } from "./types"
 import { PluginDesignFamilyApi } from "./family"
 import { PluginDesignGridsApi } from "./grids"
 import { PluginDesignChangeResult } from "./lock"
+import { PluginElectricalApi, PluginPlumbingApi } from "./networks"
 
 /**
  * `snaptrude.design.*` — author, query & edit BIM geometry.
@@ -80,6 +81,11 @@ export abstract class PluginDesignApi {
   /** Structural edits on a grid's line structure. See {@linkcode PluginDesignGridsApi}. */
   public abstract grids: PluginDesignGridsApi
 
+  /** Persistent electrical equipment, routes and circuit graphs. */
+  public abstract electrical: PluginElectricalApi
+  /** Persistent plumbing equipment and directed pipe graphs. */
+  public abstract plumbing: PluginPlumbingApi
+
   /**
    * Lock entities so they cannot be edited. Undoable. Cascades to void/door/window
    * children, stacked-wall companions, and terrain neighborhood; skips
@@ -272,3 +278,4 @@ export * from "./dimensions"
 export * from "./types"
 export * from "./family"
 export * from "./grids"
+export * from "./networks"

package/src/api/design/networks.ts

@@ -0,0 +1,315 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+
+const id = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,79}$/)
+const vector = z.tuple([
+  z.number().finite(),
+  z.number().finite(),
+  z.number().finite(),
+])
+const positive = z.number().finite().positive()
+const endpoint = z.object({ node: id, port: id }).strict()
+
+/** Authored world-space connector. This is not a claim of certified family connector metadata. */
+export const NetworkPort = z
+  .object({
+    id,
+    positionMm: vector,
+    direction: vector,
+    system: z.string().min(1).max(80),
+    /** Diameter for round ports; width when heightMm is supplied (rectangular port). */
+    sizeMm: positive,
+    heightMm: positive.optional(),
+  })
+  .strict()
+
+/** The agent supplies every route and section. The host does not size or route a network. */
+export const NetworkGeometry = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("family"),
+      definitionId: z.string().min(1).max(200),
+      version: z.number().int().positive(),
+      values: z.record(
+        z.string(),
+        z.union([z.number().finite(), z.string(), z.boolean()]),
+      ),
+      positionMm: vector,
+      rotationDeg: vector,
+      ports: z.array(NetworkPort).max(64),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("route"),
+      pathMm: z.array(vector).min(2).max(256),
+      system: z.string().min(1).max(80),
+      section: z.discriminatedUnion("kind", [
+        z
+          .object({
+            kind: z.literal("round"),
+            diameterMm: positive,
+            wallMm: z.number().finite().nonnegative(),
+          })
+          .strict(),
+        z
+          .object({
+            kind: z.literal("rectangular"),
+            widthMm: positive,
+            heightMm: positive,
+            wallMm: z.number().finite().nonnegative(),
+          })
+          .strict(),
+      ]),
+    })
+    .strict(),
+])
+
+// Storey is scene membership, not a coordinate offset. A route can span multiple elevations.
+const node = z
+  .object({ id, storey: z.number().int(), geometry: NetworkGeometry })
+  .strict()
+const electricalNode = node.extend({
+  kind: z.enum([
+    "transformer",
+    "mainBoard",
+    "distributionBoard",
+    "mcbBox",
+    "junctionBox",
+    "switch",
+    "outlet",
+    "light",
+    "load",
+    "equipment",
+    "fitting",
+    "wire",
+    "cable",
+    "conduit",
+    "cableDuct",
+    "cableTray",
+  ]),
+})
+const plumbingNode = node.extend({
+  kind: z.enum([
+    "fixture",
+    "equipment",
+    "tank",
+    "pump",
+    "valve",
+    "manifold",
+    "fitting",
+    "pipe",
+    "riser",
+  ]),
+})
+const document = z
+  .object({
+    schemaVersion: z.literal(1),
+    label: z.string().min(1).max(120),
+    /** Revision from context(); invalidated when the source architectural graph changes. */
+    architectureRevision: z.string().min(1).max(80),
+    connections: z
+      .array(
+        z
+          .object({ id, from: endpoint, to: endpoint, directed: z.boolean() })
+          .strict(),
+      )
+      .max(4000),
+    relationships: z
+      .array(
+        z
+          .object({
+            node: id,
+            relation: z.enum(["mountedOn", "within", "serves", "penetrates"]),
+            target: z
+              .object({
+                kind: z.enum(["component", "topology"]),
+                id: z.string().min(1).max(200),
+              })
+              .strict(),
+          })
+          .strict(),
+      )
+      .max(4000),
+  })
+  .strict()
+
+/** Electrical connectivity and circuit membership are distinct from physical route occupancy. */
+export const ElectricalGraphDocument = document.extend({
+  domain: z.literal("electrical"),
+  nodes: z.array(electricalNode).min(1).max(1000),
+  circuits: z
+    .array(
+      z
+        .object({
+          id,
+          source: id,
+          loads: z.array(id).min(1).max(1000),
+          routes: z.array(id).max(1000),
+          voltage: positive,
+          phases: z.number().int().min(1).max(3),
+          ratedAmps: positive,
+        })
+        .strict(),
+    )
+    .max(1000),
+})
+
+/** Plumbing uses explicit directed port connections; touching geometry never creates a connection. */
+export const PlumbingGraphDocument = document.extend({
+  domain: z.literal("plumbing"),
+  nodes: z.array(plumbingNode).min(1).max(1000),
+})
+export const NetworkGraphDocument = z.discriminatedUnion("domain", [
+  ElectricalGraphDocument,
+  PlumbingGraphDocument,
+])
+export type NetworkGraphDocument = z.infer<typeof NetworkGraphDocument>
+export type NetworkNode = NetworkGraphDocument["nodes"][number]
+export type NetworkPort = z.infer<typeof NetworkPort>
+export type NetworkDomain = NetworkGraphDocument["domain"]
+
+/** JSON is an authored document, not a transport for live geometry handles. Maximum 2 MB characters. */
+export const NetworkValidateArgs = z
+  .object({ graphJson: z.string().max(2_000_000) })
+  .strict()
+export const NetworkCreateArgs = NetworkValidateArgs.extend({
+  requestId: z.string().uuid(),
+})
+export const NetworkGetArgs = z.object({ graphId: z.string().uuid() }).strict()
+export const NetworkContextArgs = z
+  .object({
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().min(1).max(100).default(30),
+  })
+  .strict()
+export const NetworkQueryArgs = NetworkGetArgs.extend({
+  revision: z.number().int().positive(),
+  queryJson: z.string().max(16000),
+})
+export const NetworkQuery = z
+  .object({
+    kind: z.enum([
+      "nodes",
+      "connected",
+      "upstream",
+      "downstream",
+      "ports",
+      "nearestPort",
+      "circuits",
+      "relationships",
+    ]),
+    node: id.optional(),
+    pointMm: vector.optional(),
+    radiusMm: positive.optional(),
+    system: z.string().optional(),
+    sizeMm: positive.optional(),
+    heightMm: positive.optional(),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().min(1).max(100).default(30),
+  })
+  .strict()
+export type NetworkQuery = z.infer<typeof NetworkQuery>
+
+export interface NetworkDiagnostic {
+  path: string
+  message: string
+}
+export interface NetworkValidation {
+  ok: boolean
+  diagnostics: NetworkDiagnostic[]
+  nodeCount: number
+}
+/** Durable node-to-scene mapping. Each node owns one component and its pinned generated recipe. */
+export const NetworkComponentBinding = z
+  .object({
+    nodeId: id,
+    componentId: z.string().min(1),
+    definitionId: z.string().min(1),
+    definitionVersion: z.number().int().positive(),
+  })
+  .strict()
+export type NetworkComponentBinding = z.infer<typeof NetworkComponentBinding>
+export interface SavedNetworkGraph {
+  id: string
+  domain: NetworkDomain
+  revision: 1
+  requestId: string
+  document: NetworkGraphDocument
+  components: NetworkComponentBinding[]
+}
+export interface NetworkCreateResult {
+  graphId: string
+  revision: number
+  components: NetworkComponentBinding[]
+  alreadyCreated: boolean
+  /** Queue acceptance is not a durable database acknowledgement. */
+  saveStatus: "queued" | "existing"
+}
+export interface NetworkContextResult {
+  proposalId: string
+  buildingId: string | null
+  revision: string
+  /** PG2's native serialization uses Snaptrude units (1 SU = 254 mm). */
+  topologyUnits: "SU"
+  topologyJson: string
+  nextOffset: number | null
+  total: number
+  storeys: { number: number; elevationMm: number }[]
+  components: {
+    id: string
+    type: string
+    storey: number
+    minMm: number[]
+    maxMm: number[]
+  }[]
+  /** Saved graph inventory, paged with topology/components. Use these IDs after reopening a project. */
+  networks: {
+    graphId: string
+    domain: NetworkDomain
+    revision: number
+    label: string
+    componentCount: number
+  }[]
+}
+export interface NetworkQueryResult {
+  revision: number
+  resultJson: string
+  nextOffset: number | null
+  total: number
+}
+
+/** Shared transport only. Electrical and plumbing documents retain separate schemas and semantics. */
+export abstract class PluginDomainNetworkApi {
+  /** Read the active proposal's architectural context before authoring. Keep one revision across pages. */
+  abstract context(
+    args?: z.input<typeof NetworkContextArgs>,
+  ): PluginApiReturn<NetworkContextResult>
+  /** Validate authored JSON, pinned families and recipe evaluation without placing or saving anything.
+   * This does not build kernel meshes or certify engineering/code compliance.
+   */
+  abstract validate(
+    args: z.input<typeof NetworkValidateArgs>,
+  ): PluginApiReturn<NetworkValidation>
+  /** Construct each node on its authored storey, with one undo command and queued project persistence.
+   * Networks can span storeys. Reuse requestId on retry; components returns the durable node mapping.
+   * Coordinates are world millimetres, Y-up; rotations are degrees. No engineering rules are inferred.
+   * Throws for stale architecture, invalid references/geometry or conflicting retries.
+   */
+  abstract create(
+    args: z.input<typeof NetworkCreateArgs>,
+  ): PluginApiReturn<NetworkCreateResult>
+  /** Read one saved graph in the active proposal; null on miss. IDs are durable, not worker handles. */
+  abstract get(
+    args: z.input<typeof NetworkGetArgs>,
+  ): PluginApiReturn<SavedNetworkGraph | null>
+  /** Read bounded authored topology in graph revision. Crossings do not connect. No clash/compliance claims. */
+  abstract query(
+    args: z.input<typeof NetworkQueryArgs>,
+  ): PluginApiReturn<NetworkQueryResult>
+}
+
+/** Electrical equipment, physical routes and logical circuits, constructed from agent-authored intent. */
+export abstract class PluginElectricalApi extends PluginDomainNetworkApi {}
+/** Plumbing equipment and routed pipe networks, constructed from agent-authored intent. */
+export abstract class PluginPlumbingApi extends PluginDomainNetworkApi {}

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,
@@ -137,6 +138,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
@@ -462,6 +479,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**

package/src/handles.ts

@@ -145,8 +145,17 @@ export type Vec3Handle = Handle<"vec3">
 export type QuatHandle = Handle<"quat">
 export type LineHandle = Handle<"line">
 export type ArcHandle = Handle<"arc">
-/** A curve is a line or an arc — its handle is one of those kinds. */
-export type CurveHandle = LineHandle | ArcHandle
+/**
+ * A NURBS curve value handle (open B-spline curve). Minted by
+ * `core.geom.create.splineFromPoints` / `splineFromControlPoints`, and returned by
+ * `edge.getCurve`, `profile.listCurves` and `update.curve.reverse` for a spline run;
+ * accepted everywhere a {@linkcode CurveHandle} is (profileFromCurves, query.curve.*).
+ * Closed spline loops never exist as a single handle — a closed run is built
+ * directly as a profile via `core.geom.create.profileFromSplinePoints`.
+ */
+export type SplineHandle = Handle<"spline">
+/** A curve is a line, an arc, or a spline — its handle is one of those kinds. */
+export type CurveHandle = LineHandle | ArcHandle | SplineHandle
 /**
  * A circle value handle. A circle is a CLOSED curve — it deliberately does NOT
  * join {@linkcode CurveHandle} (it has no stable start/end and would break the
@@ -262,7 +271,13 @@ export const Vec3Handle = handleSchema("vec3")
 export const QuatHandle = handleSchema("quat")
 export const LineHandle = handleSchema("line")
 export const ArcHandle = handleSchema("arc")
-export const CurveHandle = z.union([LineHandle, ArcHandle])
+export const SplineHandle = handleSchema("spline")
+// Explicitly typed (rather than inferred): the inferred union type prints its
+// three fully-expanded member schemas into handles.d.ts, which is served to
+// agents whole and has a size budget. ZodUnion (not ZodType) keeps `.options`.
+export const CurveHandle: z.ZodUnion<
+  readonly [typeof LineHandle, typeof ArcHandle, typeof SplineHandle]
+> = z.union([LineHandle, ArcHandle, SplineHandle])
 export const CircleHandle = handleSchema("circle")
 
 // BREP topology handle schemas (§2A.2.1). Prefix-shape validation only; existence,

package/src/index.ts

@@ -2,4 +2,6 @@ export * from "./api"
 export * from "./types"
 export * from "./host-utils"
 export * from "./handles"
+export * from "./massParameters"
+export * from "./massParameters.ops"
 export * from "./errors"