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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/api-manifest.json +151 -12
  2. package/dist/api/core/geom/create/index.d.ts +559 -86
  3. package/dist/api/core/geom/create/index.d.ts.map +1 -1
  4. package/dist/api/core/geom/query/brep.d.ts +50 -0
  5. package/dist/api/core/geom/query/brep.d.ts.map +1 -1
  6. package/dist/api/core/geom/query/curve.d.ts +58 -35
  7. package/dist/api/core/geom/query/curve.d.ts.map +1 -1
  8. package/dist/api/core/geom/query/edge.d.ts +2 -2
  9. package/dist/api/core/geom/query/face.d.ts +45 -0
  10. package/dist/api/core/geom/query/face.d.ts.map +1 -1
  11. package/dist/api/core/geom/update/curve.d.ts +5 -5
  12. package/dist/api/core/geom/update/profile.d.ts +1 -1
  13. package/dist/api/design/query/geometry/index.d.ts +27 -1
  14. package/dist/api/design/query/geometry/index.d.ts.map +1 -1
  15. package/dist/api/design/query/index.d.ts +47 -0
  16. package/dist/api/design/query/index.d.ts.map +1 -1
  17. package/dist/api/design/query/spaces.d.ts +5 -5
  18. package/dist/api/design/update/index.d.ts +87 -0
  19. package/dist/api/design/update/index.d.ts.map +1 -1
  20. package/dist/api/entity/referenceLine.d.ts +2 -2
  21. package/dist/api/entity/referenceLine.d.ts.map +1 -1
  22. package/dist/api/entity/space.d.ts +5 -4
  23. package/dist/api/entity/space.d.ts.map +1 -1
  24. package/dist/api/entity/story.d.ts +4 -4
  25. package/dist/api/program/spreadsheet.d.ts +4 -4
  26. package/dist/handles.d.ts +12 -3
  27. package/dist/handles.d.ts.map +1 -1
  28. package/dist/index.cjs +3030 -2715
  29. package/dist/index.cjs.map +1 -1
  30. package/dist/index.d.ts +1 -0
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +2996 -2715
  33. package/dist/index.js.map +1 -1
  34. package/dist/massParameters.d.ts +319 -0
  35. package/dist/massParameters.d.ts.map +1 -0
  36. package/package.json +1 -1
  37. package/src/api/core/geom/create/index.ts +588 -84
  38. package/src/api/core/geom/query/brep.ts +51 -0
  39. package/src/api/core/geom/query/curve.ts +25 -2
  40. package/src/api/core/geom/query/edge.ts +2 -2
  41. package/src/api/core/geom/query/face.ts +49 -0
  42. package/src/api/design/query/geometry/index.ts +29 -0
  43. package/src/api/design/query/index.ts +50 -0
  44. package/src/api/design/update/index.ts +94 -0
  45. package/src/handles.ts +15 -3
  46. package/src/index.ts +1 -0
  47. package/src/massParameters.ts +472 -0
  48. package/test/massParameters.test.mjs +500 -0
@@ -174,6 +174,11 @@ export abstract class PluginGeomQueryBrepApi {
174
174
  * | `"line"` | `startPoint`, `endPoint`, `length` |
175
175
  * | `"arc"` | `startPoint`, `endPoint`, `centre`, `axis`, `radius`, `length` |
176
176
  * | `"circle"` | `centre`, `axis`, `radius`, `length` — a full-circle edge (e.g. a cylinder cap rim) |
177
+ * | `"spline"` | `startPoint`, `endPoint`, `degree`, `controlPoints`, `knots`, `length` — a free-form NURBS edge |
178
+ *
179
+ * For a `"spline"` edge, `knots` is the **expanded** knot vector — each knot
180
+ * repeated by its multiplicity, the textbook NURBS form — so
181
+ * `knots.length === controlPoints.length + degree + 1`.
177
182
  *
178
183
  * @param brep The brep the edge belongs to
179
184
  * @param edge The edge whose curve to read
@@ -184,6 +189,7 @@ export abstract class PluginGeomQueryBrepApi {
184
189
  * @examplePrompt Is this edge straight or an arc?
185
190
  * @examplePrompt Get the exact start and end points of this edge
186
191
  * @examplePrompt Measure the length of each edge of this mass
192
+ * @examplePrompt Read the control points of this curved edge
187
193
  *
188
194
  * # Example
189
195
  * ```ts
@@ -219,6 +225,16 @@ export abstract class PluginGeomQueryBrepApi {
219
225
  radius: number
220
226
  length: number
221
227
  }
228
+ | {
229
+ type: "spline"
230
+ startPoint: Vec3Components
231
+ endPoint: Vec3Components
232
+ degree: number
233
+ controlPoints: Vec3Components[]
234
+ /** Expanded by multiplicity: `controlPoints.length + degree + 1` entries. */
235
+ knots: number[]
236
+ length: number
237
+ }
222
238
  >
223
239
 
224
240
  /**
@@ -366,6 +382,37 @@ export abstract class PluginGeomQueryBrepApi {
366
382
  */
367
383
  public abstract getBoundingBox(brep: BrepHandle): PluginApiReturn<BBoxComponents>
368
384
 
385
+ /**
386
+ * Get the enclosed **volume** of a closed solid, integrated from its exact
387
+ * surfaces. Curved faces are measured analytically, not from their
388
+ * tessellation — a real sphere of radius 5 reports 523.6, whatever its
389
+ * triangle count. That makes this the reliable way to confirm a solid is the
390
+ * shape you intended (a torus should measure 2·π²·R·r²).
391
+ *
392
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
393
+ * of MB — expect a pause of seconds).
394
+ *
395
+ * @param brep The solid to measure
396
+ * @returns The enclosed volume in cubic raw Babylon units
397
+ * @throws OPERATION_FAILED if the kernel cannot compute the volume (the brep
398
+ * is not a closed solid)
399
+ *
400
+ * @examplePrompt What is the volume of this mass?
401
+ * @examplePrompt How much concrete is in this shape?
402
+ * @examplePrompt Check the volume of the dome I just made
403
+ *
404
+ * # Example
405
+ * ```ts
406
+ * const [mass] = await snaptrude.design.query.listMasses()
407
+ * const brep = await snaptrude.design.query.geometry.getBrep(mass)
408
+ * if (brep) {
409
+ * const volume = await snaptrude.core.geom.query.brep.getVolume(brep)
410
+ * console.log("volume:", volume)
411
+ * }
412
+ * ```
413
+ */
414
+ public abstract getVolume(brep: BrepHandle): PluginApiReturn<number>
415
+
369
416
  /**
370
417
  * Test whether two breps are geometrically equal.
371
418
  * @param brepA First brep
@@ -534,6 +581,10 @@ export type PluginGeomQueryBrepGetBoundingBoxArgs = z.infer<
534
581
  typeof PluginGeomQueryBrepGetBoundingBoxArgs
535
582
  >
536
583
 
584
+ /** Arguments for {@linkcode PluginGeomQueryBrepApi.getVolume}. `{ brep: BrepHandle }` */
585
+ export const PluginGeomQueryBrepGetVolumeArgs = brepArg
586
+ export type PluginGeomQueryBrepGetVolumeArgs = z.infer<typeof PluginGeomQueryBrepGetVolumeArgs>
587
+
537
588
  /**
538
589
  * Arguments for {@linkcode PluginGeomQueryBrepApi.isEqual}.
539
590
  *
@@ -3,8 +3,8 @@ import { PluginApiReturn } from "../../../../types"
3
3
  import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../../handles"
4
4
 
5
5
  /**
6
- * Curve queries — read-only geometric questions about curves (lines and arcs)
7
- * and the relationships between two curves (all-handle model, §11).
6
+ * Curve queries — read-only geometric questions about curves (lines, arcs and
7
+ * splines) and the relationships between two curves (all-handle model, §11).
8
8
  *
9
9
  * Every method takes opaque curve handles ({@linkcode CurveHandle}/{@linkcode LineHandle})
10
10
  * and point handles ({@linkcode Vec3Handle}) and returns plain values — points as
@@ -13,6 +13,29 @@ import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../..
13
13
  * {@linkcode CurveHandle} (or `null` when there is no result). No query mutates its
14
14
  * inputs.
15
15
  *
16
+ * ## Splines
17
+ *
18
+ * A {@linkcode CurveHandle} is a line, an arc, or a NURBS spline (minted by
19
+ * `core.geom.create.splineFromPoints`). Every method here accepts a spline at
20
+ * compile time, but only the reads backed by the engine's spline math answer
21
+ * for one today. The rest throw `PRECONDITION_FAILED` ("not supported for
22
+ * splines yet") — a typed refusal, never a quietly wrong answer.
23
+ *
24
+ * | Splines | Members |
25
+ * |---|---|
26
+ * | **supported** | {@linkcode PluginGeomQueryCurveApi.getStartPoint}, {@linkcode PluginGeomQueryCurveApi.getEndPoint}, {@linkcode PluginGeomQueryCurveApi.getLength}, {@linkcode PluginGeomQueryCurveApi.getTangent}, {@linkcode PluginGeomQueryCurveApi.listPoints}, {@linkcode PluginGeomQueryCurveApi.getNearestPoint} |
27
+ * | **not yet** | `getMidPoint`, `getChordLength`, `getNormal`, `getProjection`, `getPointAtDistance`, `getParameterAtPoint`, `getCurvature`, `getDistanceToPoint`, `getDistanceAlong`, `listSubdivisions`, `isLinear`, `isOnCurve`, `hasPoint`, `isEqual`, `isOverlapping`, `getCommonPart`, `listIntersections`, `getMergedCurve`, `isContinuous`, `isParallel`, `getShortestGap`, `getDistanceBetween` |
28
+ *
29
+ * {@linkcode PluginGeomQueryCurveApi.isOverlapping} is deliberately in the
30
+ * second row: its line/arc path falls back to structural equality, which would
31
+ * answer a spline pair wrongly rather than not at all.
32
+ *
33
+ * To work around the second row, sample the curve —
34
+ * {@linkcode PluginGeomQueryCurveApi.listPoints} then the ordinary
35
+ * `core.math.vec3` operations — or read a spline brep edge exactly with
36
+ * `core.geom.query.brep.getEdgeCurve`, which returns its degree, control points
37
+ * and knots.
38
+ *
16
39
  * Accessed via `snaptrude.core.geom.query.curve`.
17
40
  */
18
41
  export abstract class PluginGeomQueryCurveApi {
@@ -69,9 +69,9 @@ export abstract class PluginGeomQueryEdgeApi {
69
69
  public abstract listVertices(edge: EdgeHandle): PluginApiReturn<VertexHandle[]>
70
70
 
71
71
  /**
72
- * Get the underlying curve geometry of an edge (a line or arc).
72
+ * Get the underlying curve geometry of an edge (a line, arc or spline).
73
73
  * @param edge The edge to query
74
- * @returns The curve as a {@linkcode CurveHandle}, or `null` if it is a circle or unset
74
+ * @returns The curve as a {@linkcode CurveHandle} (`line_`, `arc_` or `spline_`), or `null` if it is a circle or unset
75
75
  *
76
76
  * # Example
77
77
  * ```ts
@@ -59,6 +59,49 @@ export abstract class PluginGeomQueryFaceApi {
59
59
  */
60
60
  public abstract getMaterialIndex(face: FaceHandle): PluginApiReturn<number>
61
61
 
62
+ /**
63
+ * Read what KIND of surface a face lies on. This is the one read that tells a
64
+ * genuinely curved face from a faceted approximation of one: every face of a
65
+ * 200-triangle "dome" answers `"plane"`, while a real dome has faces
66
+ * answering `"sphere"`. Use it to confirm a curved solid actually came out
67
+ * curved.
68
+ *
69
+ * | Value | Surface |
70
+ * |---|---|
71
+ * | `"plane"` | Flat face |
72
+ * | `"cylinder"` | Cylindrical face — constant radius about an axis |
73
+ * | `"cone"` | Conical face — a tapered ring (a cone or frustum side) |
74
+ * | `"sphere"` | Spherical face |
75
+ * | `"torus"` | Toroidal face — the ring surface of a donut |
76
+ * | `"spline"` | Free-form NURBS face |
77
+ *
78
+ * Pure read: no geometry kernel is loaded.
79
+ *
80
+ * @param face The face to query
81
+ * @returns The surface kind (see the table), or `null` when the face carries
82
+ * no surface classification
83
+ *
84
+ * @examplePrompt Is this face flat or curved?
85
+ * @examplePrompt Check that this dome is a real sphere, not a faceted approximation
86
+ * @examplePrompt What kind of surface is this face?
87
+ * @examplePrompt How many curved faces does this mass have?
88
+ *
89
+ * # Example
90
+ * ```ts
91
+ * const [mass] = await snaptrude.design.query.listMasses()
92
+ * const brep = await snaptrude.design.query.geometry.getBrep(mass)
93
+ * if (brep) {
94
+ * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
95
+ * const kinds = []
96
+ * for (const face of faces) kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face))
97
+ * console.log("spherical faces:", kinds.filter((k) => k === "sphere").length)
98
+ * }
99
+ * ```
100
+ */
101
+ public abstract getSurfaceKind(
102
+ face: FaceHandle,
103
+ ): PluginApiReturn<"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null>
104
+
62
105
  /**
63
106
  * Get a seed half-edge of a face's outer loop.
64
107
  * @param face The face to query
@@ -312,6 +355,12 @@ export type PluginGeomQueryFaceGetMaterialIndexArgs = z.infer<
312
355
  typeof PluginGeomQueryFaceGetMaterialIndexArgs
313
356
  >
314
357
 
358
+ /** Arguments for {@linkcode PluginGeomQueryFaceApi.getSurfaceKind}. `{ face: FaceHandle }` */
359
+ export const PluginGeomQueryFaceGetSurfaceKindArgs = faceArg
360
+ export type PluginGeomQueryFaceGetSurfaceKindArgs = z.infer<
361
+ typeof PluginGeomQueryFaceGetSurfaceKindArgs
362
+ >
363
+
315
364
  /** Arguments for {@linkcode PluginGeomQueryFaceApi.getHalfEdge}. `{ face: FaceHandle }` */
316
365
  export const PluginGeomQueryFaceGetHalfEdgeArgs = faceArg
317
366
  export type PluginGeomQueryFaceGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryFaceGetHalfEdgeArgs>
@@ -34,10 +34,25 @@ export abstract class PluginDesignQueryGeometryApi {
34
34
  * scene entity, as a reusable {@linkcode BrepHandle} for the
35
35
  * `core.geom.query.brep.*` reads.
36
36
  *
37
+ * **Frame.** By default the brep comes back in the component's own LOCAL frame
38
+ * (its vertices are relative to the mesh origin, exactly as stored) — the
39
+ * behaviour every 0.9.x caller relies on. Pass `{ frame: "world" }` to get the
40
+ * same solid placed where it sits in the scene (world coordinates, like
41
+ * `getBottomContour` / `getTriangulatedMeshes` and every `design.query.measure`
42
+ * read). Use `"world"` whenever the handle will be COMBINED with other scene
43
+ * geometry or committed back beside its source: booleans between two scene
44
+ * masses, `brepFromFillet` / `brepFromShell` / `brepFromOffset` /
45
+ * `brepFromChamfer` on a scene mass followed by `massFromBrep`, or comparing
46
+ * its vertices with a bounding box. A world-frame handle from a parametrically
47
+ * live mass also carries that mass's recipe, so an operation result keeps an
48
+ * editable record.
49
+ *
37
50
  * @param component - The scene component to read
51
+ * @param options - `frame`: `"local"` (default, mesh-local coordinates) or `"world"` (scene coordinates)
38
52
  * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry
39
53
  *
40
54
  * @examplePrompt Get the 3D solid geometry of the selected wall
55
+ * @examplePrompt Round the top rim of this column and put it back where it is
41
56
  * @examplePrompt How many faces does this mass have?
42
57
  * @examplePrompt Inspect the mesh of this slab so I can look at its faces and edges
43
58
  * @examplePrompt Read the vertices of the selected column's geometry
@@ -48,10 +63,16 @@ export abstract class PluginDesignQueryGeometryApi {
48
63
  * if (brep) {
49
64
  * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
50
65
  * }
66
+ *
67
+ * // Operate on a scene mass and commit the result where the mass sits:
68
+ * const placed = await snaptrude.design.query.geometry.getBrep(mass, { frame: "world" })
69
+ * const rounded = await snaptrude.core.geom.create.brepFromFillet(placed, edges, 0.2)
70
+ * await snaptrude.design.create.massFromBrep(rounded, "Rounded")
51
71
  * ```
52
72
  */
53
73
  public abstract getBrep(
54
74
  component: ComponentHandle,
75
+ options?: PluginDesignQueryGeometryGetBrepOptions,
55
76
  ): PluginApiReturn<BrepHandle | null>
56
77
 
57
78
  /**
@@ -189,8 +210,16 @@ export abstract class PluginDesignQueryGeometryApi {
189
210
  * |---|---|---|
190
211
  * | `component` | {@linkcode ComponentHandle} | The scene component to read |
191
212
  */
213
+ /** Options for {@linkcode PluginDesignQueryGeometryApi.getBrep}: `frame` defaults to `"local"`. */
214
+ export type PluginDesignQueryGeometryGetBrepOptions = { frame?: "local" | "world" }
215
+ export const PluginDesignQueryGeometryGetBrepOptions: z.ZodType<
216
+ PluginDesignQueryGeometryGetBrepOptions,
217
+ PluginDesignQueryGeometryGetBrepOptions
218
+ > = z.object({ frame: z.enum(["local", "world"]).optional() })
219
+
192
220
  export const PluginDesignQueryGeometryGetBrepArgs = z.object({
193
221
  component: ComponentHandle,
222
+ options: PluginDesignQueryGeometryGetBrepOptions.optional(),
194
223
  })
195
224
 
196
225
  export type PluginDesignQueryGeometryGetBrepArgs = z.infer<
@@ -1,6 +1,7 @@
1
1
  import * as z from "zod"
2
2
  import { PluginApiReturn } from "../../../types"
3
3
  import { ComponentHandle, BBoxComponents } from "../../../handles"
4
+ import type { MassParametersRecord } from "../../../massParameters"
4
5
  import {
5
6
  PluginSpaceType,
6
7
  PluginMassType,
@@ -1014,6 +1015,55 @@ export abstract class PluginDesignQueryApi {
1014
1015
  staircase: ComponentHandle,
1015
1016
  ): PluginApiReturn<PluginStaircaseParams | null>
1016
1017
 
1018
+ /**
1019
+ * Read a mass's creation-parameter record — the recipe it was built from
1020
+ * (`kind` plus the values that constructor was called with). Present on
1021
+ * masses committed from a `core.geom.create` brep constructor that carries a
1022
+ * recipe: {@linkcode MassParametersRecord} covers the four primitives
1023
+ * (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.
1024
+ *
1025
+ * A fillet, chamfer, shell or offset of a recorded solid keeps the record
1026
+ * too: `kind` stays the base constructor and the operation is appended to the
1027
+ * record's `operations` list. Edit any of it with `design.update.parameters`.
1028
+ *
1029
+ * `null` for everything else — drawn masses, imported geometry, booleans,
1030
+ * split parts, `brepFromFaces` / `brepFromMesh`, and results built on a
1031
+ * source that carried no record — and for a mass whose record no longer
1032
+ * matches what is on
1033
+ * screen (a later free-form edit dropped the recipe, or the mass carries a
1034
+ * baked scale). `null` too when the recipe was not recordable: the record
1035
+ * schema has its own caps (a sweep path of at most 512 points, a loft of at
1036
+ * most 32 sections, at most 8 chained `operations`, at most 256 curves in one
1037
+ * profile loop and 64 holes in one contour), and a mass built past one of
1038
+ * them — through a route that does not enforce the matching creator cap —
1039
+ * commits as ordinary geometry carrying no record. The `operations` cap is
1040
+ * the one an agent can walk into by accident: a 9th chained
1041
+ * fillet/chamfer/shell/offset drops the record silently, so the result
1042
+ * commits as ordinary geometry and reads back `null` here. A record is never
1043
+ * reported unless it is still the truth.
1044
+ *
1045
+ * Points and axes come back in **world** coordinates. Pure read — nothing is
1046
+ * created or modified.
1047
+ *
1048
+ * @param component - the mass's {@linkcode ComponentHandle}
1049
+ * @returns the {@linkcode MassParametersRecord}, or `null`
1050
+ *
1051
+ * @examplePrompt What radius is this sphere?
1052
+ * @examplePrompt Is this mass parametric?
1053
+ * @examplePrompt Read back the dome's creation parameters
1054
+ * @examplePrompt How tall was this cylinder made?
1055
+ *
1056
+ * # Example
1057
+ * ```ts
1058
+ * const [mass] = await snaptrude.design.query.listMasses({ isSelected: true })
1059
+ * const params = await snaptrude.design.query.getParameters(mass)
1060
+ * if (params?.kind === "sphere") console.log("radius:", params.values.radius)
1061
+ * ```
1062
+ */
1063
+ public abstract getParameters(
1064
+ component: ComponentHandle,
1065
+ ): PluginApiReturn<MassParametersRecord | null>
1066
+
1017
1067
  /**
1018
1068
  * Get the **union** axis-aligned bounding box enclosing a set of entities.
1019
1069
  *
@@ -9,6 +9,7 @@ import {
9
9
  PluginSpaceUpdateResult,
10
10
  } from "../../entity/space"
11
11
  import { PluginDesignChangeResult } from "../lock"
12
+ import { MassParametersPatch, type MassParametersRecord } from "../../../massParameters"
12
13
  import {
13
14
  PluginBuildableEnvelopePolygonVertex,
14
15
  PluginBuildableEnvelopeSetbackTier,
@@ -136,6 +137,22 @@ export type PluginDesignUpdateStaircaseArgs = z.infer<
136
137
  typeof PluginDesignUpdateStaircaseArgs
137
138
  >
138
139
 
140
+ /**
141
+ * Arguments for {@linkcode PluginDesignUpdateApi.parameters}.
142
+ *
143
+ * | Property | Type | Description |
144
+ * |---|---|---|
145
+ * | `component` | {@linkcode ComponentHandle} | The parametric mass to edit |
146
+ * | `patch` | {@linkcode MassParametersPatch} | Partial `values` (+ optional `operations`), or the full edited record |
147
+ */
148
+ export const PluginDesignUpdateParametersArgs = z.object({
149
+ component: ComponentHandle,
150
+ patch: MassParametersPatch,
151
+ })
152
+ export type PluginDesignUpdateParametersArgs = z.infer<
153
+ typeof PluginDesignUpdateParametersArgs
154
+ >
155
+
139
156
  /**
140
157
  * Sparse edits for a wall (all optional; at least one required). Only the
141
158
  * fields you provide change. Dimensions are in **engine units** (the same
@@ -409,6 +426,83 @@ export abstract class PluginDesignUpdateApi {
409
426
  params: PluginStaircaseParamUpdates,
410
427
  ): PluginApiReturn<PluginDesignChangeResult>
411
428
 
429
+ /**
430
+ * Edit a parametric mass by patching its creation recipe and rebuilding the
431
+ * solid in place — the mass keeps its id, storey, materials, position and
432
+ * linked copies; only the geometry changes. Read the current record with
433
+ * `design.query.getParameters` first.
434
+ *
435
+ * `patch` is a partial of `record.values` — or the whole record you read
436
+ * back, edited. A key you leave out is unchanged (that includes
437
+ * `operations`). Scalars and points MERGE by key (`{ radius: 8 }` changes
438
+ * only the radius); arrays (`contour`, `sections`, `path`, `profile`,
439
+ * `operations`) REPLACE WHOLE when present — send the complete new list;
440
+ * `{ operations: [] }` drops every operation. A patch that changes nothing
441
+ * returns the current record and records no edit (no undo step). `kind` and
442
+ * `version` are immutable: to change the kind, build a new mass. Keys are the
443
+ * record's `values` keys for its `kind` (sphere: `centre`, `radius`;
444
+ * cylinder: `base`, `axis`, `radius`, `height`; torus: `centre`, `axis`,
445
+ * `majorRadius`, `minorRadius`; …) plus `operations`. To change a fillet
446
+ * radius, edit `operations[i].radius` in the record you read and send
447
+ * `{ operations }` back. Points and axes are WORLD coordinates in internal
448
+ * units, exactly as `getParameters` reports them.
449
+ *
450
+ * Rebuilds in memory first, then swaps onto the SAME component; every linked
451
+ * copy regenerates together. One undo step; saves and syncs to collaborators
452
+ * like any geometry edit. Kernel kinds (revolution, sweep, loft, primitives,
453
+ * any `operations`) run on OpenCascade — expect a short pause.
454
+ *
455
+ * @param component - a mass whose `getParameters` is non-null
456
+ * @param patch - partial `values` (+ optional `operations`), or the full edited record
457
+ * @returns the complete post-edit record, world coordinates (what
458
+ * `getParameters` now returns)
459
+ * @throws PRECONDITION_FAILED when the mass carries no live recipe — built
460
+ * from a boolean, split, `brepFromFaces`/`brepFromMesh` or drawn; edited
461
+ * free-form since (push/pull, move face, boolean); or scaled with the
462
+ * transform tool. `getParameters` returns `null` for exactly these.
463
+ * Do not retry — rebuild it with a recipe constructor and say so.
464
+ * Also PRECONDITION_FAILED when the mass is **locked** (the message says
465
+ * so). Locking is invisible to `getParameters` — a locked parametric mass
466
+ * still reads back a full record — so this is the one PRECONDITION_FAILED
467
+ * the read cannot predict. Unlock the mass and call again; never rebuild
468
+ * it, the recipe is intact.
469
+ * Also PRECONDITION_FAILED when an `operations` entry's edge/face selectors
470
+ * no longer resolve on the rebuilt base (the message names the operation
471
+ * and edge): re-select the edges on the new shape and re-apply that
472
+ * operation.
473
+ * @throws VALIDATION for a key the kind does not have (the message lists the
474
+ * kind's keys), `kind` or `version` in a partial patch, or a value outside
475
+ * the constructor's own rules (torus tube ≥ ring, revolution angle ∉
476
+ * (0, 360], a profile crossing its axis, a spline with fewer than
477
+ * degree + 1 poles).
478
+ * @throws OPERATION_FAILED when the kernel cannot build the edited recipe;
479
+ * the model is left unchanged.
480
+ *
481
+ * @examplePrompt Make the dome's radius 8 metres
482
+ * @examplePrompt Raise the podium to 5 m
483
+ * @examplePrompt Widen the vase — move its profile points 20 cm outward
484
+ * @examplePrompt Change the fillet on the rounded column to 300 mm
485
+ *
486
+ * # Example
487
+ * ```ts
488
+ * // { kind: "sphere", values: { centre, radius: 19.685 }, … }
489
+ * const before = await snaptrude.design.query.getParameters(dome)
490
+ * const after = await snaptrude.design.update.parameters(dome, { radius: 31.496 }) // 8 m in internal units
491
+ *
492
+ * // Fillet radius on a recorded result: read → edit → send the array back
493
+ * const rec = await snaptrude.design.query.getParameters(column)
494
+ * const operations = rec?.operations ?? []
495
+ * if (operations[0]?.op === "fillet") {
496
+ * operations[0].radius = 1.181
497
+ * await snaptrude.design.update.parameters(column, { operations })
498
+ * }
499
+ * ```
500
+ */
501
+ public abstract parameters(
502
+ component: ComponentHandle,
503
+ patch: MassParametersPatch,
504
+ ): PluginApiReturn<MassParametersRecord>
505
+
412
506
  /**
413
507
  * Edit a **wall** — its thickness and/or height (the same command the
414
508
  * properties panel's Thickness/Height fields drive) and/or its **wall type**
package/src/handles.ts CHANGED
@@ -132,8 +132,16 @@ export type Vec3Handle = Handle<"vec3">
132
132
  export type QuatHandle = Handle<"quat">
133
133
  export type LineHandle = Handle<"line">
134
134
  export type ArcHandle = Handle<"arc">
135
- /** A curve is a line or an arc — its handle is one of those kinds. */
136
- export type CurveHandle = LineHandle | ArcHandle
135
+ /**
136
+ * A NURBS curve value handle (open B-spline curve). Minted by
137
+ * `core.geom.create.splineFromPoints` / `splineFromControlPoints`, accepted everywhere a
138
+ * {@linkcode CurveHandle} is (profileFromCurves, query.curve.*).
139
+ * Closed spline loops never exist as a single handle — a closed run is built
140
+ * directly as a profile via `core.geom.create.profileFromSplinePoints`.
141
+ */
142
+ export type SplineHandle = Handle<"spline">
143
+ /** A curve is a line, an arc, or a spline — its handle is one of those kinds. */
144
+ export type CurveHandle = LineHandle | ArcHandle | SplineHandle
137
145
  /**
138
146
  * A circle value handle. A circle is a CLOSED curve — it deliberately does NOT
139
147
  * join {@linkcode CurveHandle} (it has no stable start/end and would break the
@@ -238,7 +246,11 @@ export const Vec3Handle = handleSchema("vec3")
238
246
  export const QuatHandle = handleSchema("quat")
239
247
  export const LineHandle = handleSchema("line")
240
248
  export const ArcHandle = handleSchema("arc")
241
- export const CurveHandle = z.union([LineHandle, ArcHandle])
249
+ export const SplineHandle = handleSchema("spline")
250
+ // Explicitly typed (rather than inferred): the inferred union type prints its
251
+ // three fully-expanded member schemas into handles.d.ts, which is served to
252
+ // agents whole and has a size budget.
253
+ export const CurveHandle: z.ZodType<CurveHandle> = z.union([LineHandle, ArcHandle, SplineHandle])
242
254
  export const CircleHandle = handleSchema("circle")
243
255
 
244
256
  // BREP topology handle schemas (§2A.2.1). Prefix-shape validation only; existence,
package/src/index.ts CHANGED
@@ -2,4 +2,5 @@ export * from "./api"
2
2
  export * from "./types"
3
3
  export * from "./host-utils"
4
4
  export * from "./handles"
5
+ export * from "./massParameters"
5
6
  export * from "./errors"