@snaptrude/plugin-core 0.9.13 → 0.9.14

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

@@ -174,16 +174,26 @@ 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
    * @returns The curve data as a discriminated union on `type` (see table above)
    * @throws VALIDATION if the edge is not on `brep`
+   * @throws PRECONDITION_FAILED if the edge is a RATIONAL (weighted) spline —
+   *   e.g. a NURBS-converted elliptical intersection edge. The wire form
+   *   carries no weights, so such an edge is refused rather than reported as a
+   *   different curve; sample it instead.
    *
    * @examplePrompt Read the radius of this curved edge
    * @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 +229,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
+      }
   >
 
   /**
@@ -263,7 +283,10 @@ export abstract class PluginGeomQueryBrepApi {
   public abstract listVertexPositions(brep: BrepHandle): PluginApiReturn<Vec3Components[]>
 
   /**
-   * Get the centroid (mean of all vertex positions) of a brep.
+   * Get the centroid of a brep: the mean of its vertex positions for planar
+   * and cylinder-sided solids; for a solid with sphere, cone, torus or spline
+   * geometry, its exact centre of mass (integrated over the surfaces; the
+   * vertex mean again if the kernel cannot integrate it, e.g. an open brep).
    * @param brep The brep to query
    * @returns The centroid as {@linkcode Vec3Components}
    *
@@ -366,6 +389,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 internal length 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
@@ -388,7 +442,7 @@ export abstract class PluginGeomQueryBrepApi {
   public abstract isEqual(brepA: BrepHandle, brepB: BrepHandle): PluginApiReturn<boolean>
 
   /**
-   * Measures the minimum distance between two solids, with the closest witness
+   * Measures the minimum distance between two solids, with the closest
    * point on each. Touching or overlapping solids report a distance of 0 with
    * contact points.
    *
@@ -534,6 +588,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.
  *
  * Every method takes opaque curve handles ({@linkcode CurveHandle}/{@linkcode LineHandle})
  * and point handles ({@linkcode Vec3Handle}) and returns plain values — points as
@@ -13,6 +13,30 @@ 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` / `splineFromControlPoints`, and returned by
+ * `edge.getCurve`, `profile.listCurves` and `update.curve.reverse` for a spline run). 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
@@ -257,6 +300,56 @@ export abstract class PluginGeomQueryFaceApi {
     brep: BrepHandle,
   ): PluginApiReturn<Vec3Components[]>
 
+  /**
+   * Exact surface area of one face of `brep`, in internal length units SQUARED —
+   * integrated off the face's own surface, not its facets, so a curved patch
+   * reads exactly rather than as its triangles. Needs the parent brep: a face
+   * handle cannot name its own solid.
+   * @param face The face to measure
+   * @param brep The parent brep (owner last, as in
+   *   {@linkcode PluginGeomQueryFaceApi.listVertexPositions})
+   * @returns The area as a `number`
+   * @throws VALIDATION if `face` is not a face of `brep`
+   * @throws OPERATION_FAILED if the kernel could not measure the face
+   *
+   * @examplePrompt How big is this roof patch?
+   * @examplePrompt Which face of this mass has the largest area?
+   *
+   * # 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 areas = await Promise.all(
+   *     faces.map((f) => snaptrude.core.geom.query.face.getArea(f, brep)),
+   *   )
+   * }
+   * ```
+   */
+  public abstract getArea(face: FaceHandle, brep: BrepHandle): PluginApiReturn<number>
+
+  /**
+   * Centre of area of one face of `brep`, as a point in that brep's frame
+   * (internal length units). On a solid whose every face reads `"spline"` this
+   * is the read that tells two patches apart — the top of a thickened patch from
+   * its bottom, one quarter of a closed surface from the next.
+   * @param face The face to measure
+   * @param brep The parent brep (owner last)
+   * @returns The centroid as {@linkcode Vec3Components}
+   * @throws VALIDATION if `face` is not a face of `brep`
+   * @throws OPERATION_FAILED if the kernel could not measure the face
+   *
+   * @examplePrompt Where is the middle of this face?
+   * @examplePrompt Pick the topmost face of this curved mass
+   *
+   * # Example
+   * ```ts
+   * const centre = await snaptrude.core.geom.query.face.getCentroid(face, brep)
+   * ```
+   */
+  public abstract getCentroid(face: FaceHandle, brep: BrepHandle): PluginApiReturn<Vec3Components>
+
   /**
    * List the tessellated boundary points of a face's outer loop (arcs sampled,
    * sense-corrected). Not cardinality-equal to {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.
@@ -301,6 +394,7 @@ export abstract class PluginGeomQueryFaceApi {
 }
 
 const faceArg = z.object({ face: FaceHandle })
+const faceWithBrepArg = z.object({ face: FaceHandle, brep: BrepHandle })
 
 /** Arguments for {@linkcode PluginGeomQueryFaceApi.getIndex}. `{ face: FaceHandle }` */
 export const PluginGeomQueryFaceGetIndexArgs = faceArg
@@ -312,6 +406,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>
@@ -382,14 +482,19 @@ export type PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs = z.infer<
  * | `face` | {@linkcode FaceHandle} | The face to query |
  * | `brep` | {@linkcode BrepHandle} | The parent brep (source of vertex coordinates) |
  */
-export const PluginGeomQueryFaceListVertexPositionsArgs = z.object({
-  face: FaceHandle,
-  brep: BrepHandle,
-})
+export const PluginGeomQueryFaceListVertexPositionsArgs = faceWithBrepArg
 export type PluginGeomQueryFaceListVertexPositionsArgs = z.infer<
   typeof PluginGeomQueryFaceListVertexPositionsArgs
 >
 
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getArea}. `{ face: FaceHandle, brep: BrepHandle }` */
+export const PluginGeomQueryFaceGetAreaArgs = faceWithBrepArg
+export type PluginGeomQueryFaceGetAreaArgs = z.infer<typeof PluginGeomQueryFaceGetAreaArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getCentroid}. `{ face: FaceHandle, brep: BrepHandle }` */
+export const PluginGeomQueryFaceGetCentroidArgs = faceWithBrepArg
+export type PluginGeomQueryFaceGetCentroidArgs = z.infer<typeof PluginGeomQueryFaceGetCentroidArgs>
+
 /** Arguments for {@linkcode PluginGeomQueryFaceApi.listVertexPositionsWithCurves}. `{ face: FaceHandle }` */
 export const PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = faceArg
 export type PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = z.infer<

package/src/api/core/geom/update/contour.ts

@@ -29,6 +29,8 @@ export abstract class PluginGeomUpdateContourApi {
    * @param contour The contour to offset
    * @param distance Signed offset distance (outward when positive, inward when negative)
    * @returns The offset contour as a NEW {@linkcode ContourHandle}
+   * @throws PRECONDITION_FAILED if the outline or a hole has a spline run
+   *   (splines cannot be offset yet)
    *
    * @examplePrompt Offset this boundary 500mm inward
    * @examplePrompt Shrink this floor outline by half a metre all around

package/src/api/core/geom/update/profile.ts

@@ -28,6 +28,8 @@ export abstract class PluginGeomUpdateProfileApi {
    * @param profile The closed profile to offset
    * @param distance Signed offset distance (outward when positive, inward when negative)
    * @returns The offset profile as a NEW {@linkcode ProfileHandle}
+   * @throws PRECONDITION_FAILED if the profile has a spline run (splines cannot
+   *   be offset yet)
    *
    * @examplePrompt Offset this outline 300mm inward
    * @examplePrompt Inset this boundary by a foot all around

package/src/api/core/handles/index.ts

@@ -6,7 +6,7 @@ import type { AnyArenaHandle } from "../../../handles"
 import { Handle } from "../../../handles"
 
 /**
- * The 12 registry-arena handle kinds — the releasable families. Entity-style
+ * The 13 registry-arena handle kinds — the releasable families. Entity-style
  * handles (component / material / underlay / terrain / importJob / comment) are
  * raw engine ids with no arena entry and therefore no lifecycle: passing one to
  * `release` is a silent no-op like any other unknown id.
@@ -16,6 +16,7 @@ export const ArenaKind = z.enum([
   "quat",
   "line",
   "arc",
+  "spline",
   "circle",
   "profile",
   "contour",
@@ -216,7 +217,7 @@ export type PluginHandlesEndScopeArgs = z.infer<typeof PluginHandlesEndScopeArgs
  * | Property | Type | Description |
  * |---|---|---|
  * | `resources` | `number` | Live resource-arena entries (profile/contour) |
- * | `values` | `number` | Live value-arena entries (vec3/quat/line/arc/circle) |
+ * | `values` | `number` | Live value-arena entries (vec3/quat/line/arc/spline/circle) |
  * | `topology` | `number` | Live topology-arena entries (brep/face/edge/halfedge/vertex) |
  * | `scopes` | `number` | Currently open handle scopes |
  * | `hostHeapUsedBytes` | `number \| null` | Host page `usedJSHeapSize` (null where unsupported) |

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<