@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803 → 0.0.0-bimsvg-20260929092811

package/CHANGELOG.md

@@ -1,10 +1,43 @@
 # @snaptrude/plugin-core
 
-## 0.0.0-bimsvg-20260928124803
+## 0.9.14
 
-### Minor Changes
+### Patch Changes
 
-- 95fbff4: Add first-class drawing contracts, reusable view presets, drawing placement on sheets, and drawing-parented annotations.
+- 22c919b: Curved-geometry contracts — spline curves, primitive solids, curved-surface reads, and the shared mass-parameter record.
+  - **`spline` handle kind** — `SplineHandle` joins `CurveHandle` (`line | arc | spline`), so every `core.geom.query.curve` member and `profileFromCurves` take a spline, and joins `ArenaKind`, so `core.handles.release`, `releaseAll("spline")` and `endScope`'s `retain` list accept one. Closed spline loops never exist as a single handle: a closed run is authored directly as a profile.
+  - **`core.geom.create.splineFromPoints`** — an open NURBS curve passing exactly THROUGH 3..256 ordered points (interpolated, not control points).
+  - **`core.geom.create.profileFromSplinePoints`** — the closed counterpart: a smooth closed profile through the points, ready for `contourFromProfile` → extrude/loft/sweep. No mixed straight/spline input in v1 — compose those with `profileFromCurves`.
+  - **Primitive solids** — `brepFromSphere`, `brepFromCylinder`, `brepFromCone` (optional `topRadius`, default 0 = apex) and `brepFromTorus`. Positional plain `{x, y, z}` args matching the `brepFromRevolution` family; `base` is the bottom-cap centre for cylinder/cone, `centre` for sphere/torus. Each result carries an exact analytic surface and a creation recipe.
+  - **`core.geom.create.brepFromSweep`** — `options.transition` gains `"round"` beside `"miter"` and `{ bevel }`: corners carried around a tangent circular arc, so the corner patch is a real curved surface.
+  - **`core.geom.create.brepFromRevolution`** — JSDoc rewritten to the implemented gate: segments may run at any angle to the axis (an incline revolves into a cone, an arc into a sphere or torus section). Two rules, checked in this order: the axis must lie in the profile's plane or run parallel to it (a parallel axis offset from the plane is judged by its projection into the plane, as 0.9.13 built it; a skew axis is `PRECONDITION_FAILED`), then the whole profile must stay on one side of the axis — touching it is legal (dome poles, cylinder inner edges), crossing it is not (`VALIDATION`).
+  - **`core.geom.query.brep.getEdgeCurve`** — a fourth `"spline"` variant (`degree`, `controlPoints`, expanded `knots`, endpoints, `length`), so reading back a spline edge no longer throws.
+  - **`core.geom.query.brep.getVolume`** — exact enclosed volume integrated from the surfaces, free of tessellation error.
+  - **`core.geom.query.face.getSurfaceKind`** — `"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null`: the one read that tells a real curved face from a faceted approximation of one.
+  - **`core.geom.query.curve`** — class JSDoc gains the per-member spline support table; unsupported members refuse with `PRECONDITION_FAILED` rather than answering wrongly.
+  - **`design.query.getParameters`** — read a mass's creation-parameter record (`kind` + values, world coordinates), or `null` for geometry with no honest recipe.
+  - **`massParameters`** (new module, exported from the package root) — `MassParametersRecord` / `ContourRecord` / `ProfileRecord` / `CurveRecord` / `XYZ` types and Zod schemas, shared verbatim by plugin-core, the host and the agent runtime. Pure JSON, one `{x, y, z}` point shape, array bounds as contract (through-points ≤ 256, spline poles ≤ 512, sweep path ≤ 512, loft sections ≤ 32, profile curves ≤ 256, contour holes ≤ 64).
+
+  Editing what was made, and rounding it:
+  - **`design.update.parameters(component, patch)`** — the write pair of `design.query.getParameters`: patch a parametric mass's creation recipe and the solid rebuilds in place, keeping its id, storey, materials, position and linked copies. `patch` is a partial of the record's `values` (keys you omit are unchanged; 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) or the whole record read back and edited; `kind` and `version` are immutable; the reply is the complete post-edit record in world coordinates. `PRECONDITION_FAILED` when the component is not a mass (a family instance: use `design.family.setParameters`), when the mass carries no live recipe, when it was scaled (undo the scale and call again), when it or a linked copy is locked (unlock them — the recipe is intact, and `getParameters` cannot see the lock), when a recorded operation's selectors no longer resolve, or when the edit is the first twist or taper, or the straightening, of an extrusion that carries a shell, fillet or chamfer (the faces renumber: send the twist keys with `operations: []` first, then re-apply), `VALIDATION` for argument errors, `OPERATION_FAILED` for a kernel refusal that leaves the model unchanged.
+  - **`core.geom.create.splineFromControlPoints(controlPoints, { degree? })`** — an open NURBS curve DEFINED BY 3..512 control points (pulled toward, not through, the interior ones), degree 2 or 3, clamped uniform knots computed host-side. It is the write pair of a `splinePoles` curve record, so a curve read back off a mass can have its poles moved and be rebuilt.
+  - **`brepFromFillet` / `brepFromChamfer` / `brepFromShell` / `brepFromOffset` accept CURVED solids.** The straight-edges-only and no-shared-vertex rules are gone: edges may be straight, circular or spline, and adjacent edges (corner blends) are allowed. The JSDoc carries the rim-selection recipe — `brep.listEdges` → `edge.listFaces` → `face.getSurfaceKind` on both faces (`listEdgesBetween` takes two VERTEX indices and is not a face-pair lookup) — and the new refusals: `VALIDATION` where there is no crease (a seam, or two patches of one smooth surface), and — for `brepFromFillet` alone, the one operation with a per-edge kernel verdict — `PRECONDITION_FAILED` naming the edge the kernel could not blend. An over-size chamfer, shell or offset is `OPERATION_FAILED` with a hint asking for a smaller distance/thickness and no edge or face named. Selection caps are RECORD caps, not call caps: the wire schemas accept any selection size, exactly as 0.9.x did — a fillet/chamfer of more than 64 edges or a shell opening more than 32 faces still builds, but the result carries no parameter record (the recipe-less fallback).
+  - **`MassParametersRecord` gains an optional `operations` list** (`version` stays 1) — a fillet, chamfer, shell or offset of a recorded solid keeps the record, with `kind` still the base constructor and the operation appended. `OperationRecord`, `EdgeSelector`, `FaceSelector`, `TopologyCounts`, `SurfaceKind`, `CurveKind`, `ParameterPatchValue` and `MassParametersPatch` join the module, with caps `MAX_OPERATIONS` 8, `MAX_OPERATION_EDGES` 64, `MAX_OPERATION_FACES` 32. Selectors are TOPOLOGICAL (edge index + its face pair + curve kind; face index + surface kind + edge count) so they survive a scalar edit of the base and trip on a reorder.
+  - **`design.query.geometry.getBrep`** — additive `options.frame` (`"local"` default, unchanged 0.9.x behaviour; `"world"` places the solid where it sits in the scene, for booleans between scene masses and for fillet/shell/offset/chamfer results committed back beside their source).
+
+  Freeform surfaces, sweeps, patches and variable blends:
+  - **`core.geom.create.brepFromSweepAlongCurve(profile, path, options?)`** — sweeps a cross-section along a SMOOTH path of 1..64 curves (splines, arcs and lines chained end to end), where `brepFromSweep` takes a polyline. `options.orientation` picks how the profile turns: `"upright"` (default) keeps its up aligned with world up, `"frenet"` rolls it with the curvature, `"fixed"` carries the authored frame along unchanged — which is a pure translation, and so is also how a footprint is bent along an arc. `options.rail`, a second guide curve, carries the profile along a second path; a closed rail, or a rail together with `orientation`, is `VALIDATION`, and a railed sweep records nothing (`getParameters` answers `null`). Otherwise it records as the one new kind `sweepAlongCurve` (`{ profile, path: CurveRecord[], options? }`, `version` still 1), so the orientation stays editable through `design.update.parameters`; the shipped `sweep` kind and its `XYZ[]` path are untouched.
+  - **`core.geom.create.brepFromPatch(boundary, thickness, options?)`** — stretches a surface across a closed loop of 3..16 boundary items and thickens it into a SOLID in one call: a roof over four curves, a canopy between two rails, a blend across a gap. A boundary item is a curve or an `OwnedEdge` (`{ edge, brep, face? }` — an edge handle cannot name its own solid, and one patch may meet two of them). `options.continuity: "tangent"` leaves the named face smoothly and then REQUIRES `face` on every item, because a solid edge lies between two faces and only the caller knows which one to continue; `interiorPoints` (≤ 64) pull the surface through them, and `side` picks which way the solid grows. There is no sheet handle and no surface object: only solids reach the canvas. The result carries no recipe — `design.query.getParameters` is `null` and the mass label is its provenance.
+  - **`core.geom.create.brepsFromSplitByFace(brep, toolFace, toolBrep)`** — the curved twin of `brepsFromSplit`, which cuts with a plane: cuts a solid with a FACE of another solid and returns the pieces largest first. Both breps must be in the same frame — read scene masses with `getBrep(x, { frame: "world" })`. A cut that does not pass all the way through is a `VALIDATION`, not a silent single piece.
+  - **`core.geom.create.curvesFromProjection(curve, face, faceBrep)`** — drops a curve onto a face along its normal and returns the runs that land on it, one curve per connected run, or `[]` when the curve misses the face; `VALIDATION` when the curve's midpoint lies on the face's surface (no drop direction).
+  - **`core.geom.query.face.getArea(face, brep)` / `.getCentroid(face, brep)`** — exact area (internal units squared) and centre of area of one face, integrated off its surface rather than its facets. These are the two reads that tell freeform faces apart, where every face answers `"spline"` and a kind census returns nothing. Both take the parent brep, owner last, exactly like `listVertexPositions(face, brep)`.
+  - **`brepFromLoft`** gains `options.smoothing` — `"ruled"` (default) is today's straight-sided loft byte for byte; `"smooth"` lofts every section in ONE pass, so the sides curve continuously through the intermediates. `LoftOptions` carries it into the record.
+  - **`brepFromExtrusion`** gains a trailing `options?: { twistInDegrees?, topScale?, levels? }`, and the shipped `extrusion` record gains the same three optional values (`version` still 1) — a twisted or tapered tower stays the SAME kind, so "twist this tower" is an edit rather than a delete-and-rebuild. `twistInDegrees` is an angle and `topScale` a ratio: neither is ever converted by a unit factor. `levels` is a count (each step may turn at most 22.5°), resolved at create time and written into the record, so an existing mass regenerates from the record and never from a heuristic that may change under it. All three absent is the straight extrusion, byte for byte.
+  - **`brepFromFillet`** gains a trailing `options?: { endRadius?, radii? }` — a VARIABLE blend. `endRadius` interpolates linearly from `radius` along the whole tangent chain the one edge you pass belongs to (an open chain: on a closed rim a law whose two ends differ is refused, for `endRadius` and `radii` alike). `radii` is the sampled form instead: 2..32 rows of `{ position, radius }` with `position` the normalised ARC LENGTH along that contour from the passed edge's start — a ratio, never converted — strictly increasing. Either form takes exactly ONE edge, they are mutually exclusive, and both round-trip on the fillet `OperationRecord`.
+  - **Face and edge selectors gain `at?`** — where the face or edge sits inside its solid, its centroid (an edge's midpoint) over the solid's bounding-box extent, a ratio per axis. It is written only when index, kind and counts cannot tell two of them apart, which on a freeform solid is the common case, and it is verified — never searched — on replay, so a record written without it resolves byte-identically.
+  - **`ParameterPatchValue`** widens with `SweepAlongCurveRecordOptions` and `CurveRecord[]` (the `sweepAlongCurve` path). It only ever widens; every value it took before it still takes.
+  - **`massParameters.ops` — a second record module.** `EdgeSelector`, `FaceSelector`, `TopologyCounts`, `OperationRecord`, `ParameterPatchValue` and the operation caps (plus the new `MAX_FILLET_LAW_SAMPLES` 32) move into `src/massParameters.ops.ts` and are re-exported from `massParameters` and from the package root — no import path changes. The split keeps each module small enough for an agent to read whole. New caps beside the shipped ones: `MAX_PATH_CURVES` 64, `MAX_TWIST_LEVELS` 64, and — on the creator, because a patch has no record — `MAX_PATCH_BOUNDARY_CURVES` 16 and `MAX_PATCH_INTERIOR_POINTS` 64.
+  - **`design.family.getParameters`** gains an optional `parts: PluginFamilyPart[]` — each placed part's `name`, the `engine` that built it (`"kernel"` for a curved sketch built exactly, `"mesh"` otherwise) and, on kernel parts, a read-only part-local `brep` for the face-kind census. `design.query.geometry.getBrep` keeps returning `null` for a family.
 
 ## 0.9.13
 

package/api-manifest.json

@@ -817,7 +817,7 @@
   {
     "path": "core.geom.create.brepFromLoft",
     "namespace": "core.geom.create",
-    "summary": "Create a closed solid **B-rep** by lofting between a bottom and a top contour, optionally through intermediate cross-sections. Host API call — returns a {@linkcode BrepHandle}. Sections with different edge counts are auto-matched: vertices are deterministically inserted on the smaller sections at the larger section's perimeter positions, so the same input always yields the same solid. For straight-edge (all-line) sections the seam is auto-aligned too — winding and start-vertex correspondence are chosen to avoid a twist, so outlines authored from any starting corner loft cleanly; arc-bearing sections keep the authored correspondence unchanged. A pair whose side faces would be non-planar under every correspondence still builds for hole-free straight-edged pairs — planar side quads stay quads and warped ones split into planar triangles (the triangulated lane); arc-bearing or holed twisted pairs are rejected, as is auto-matching that would pair an arc with a straight edge. Matching hole counts are allowed in the two-section form. With intermediates the loft is a chain of ruled segments folded into one solid: sections must be planar and hole-free, ordered bottom → intermediates → top. The contours are copied — the input handles are never mutated.",
+    "summary": "Create a closed solid **B-rep** by lofting between a bottom and a top contour, optionally through intermediate cross-sections. Host API call — returns a {@linkcode BrepHandle}. Sections with different edge counts are auto-matched: vertices are deterministically inserted on the smaller sections at the larger section's perimeter positions, so the same input always yields the same solid. For straight-edge (all-line) sections the seam is auto-aligned too — winding and start-vertex correspondence are chosen to avoid a twist, so outlines authored from any starting corner loft cleanly; arc-bearing sections keep the authored correspondence unchanged. A pair whose side faces would be non-planar under every correspondence still builds for hole-free straight-edged pairs — planar side quads stay quads and warped ones split into planar triangles (the triangulated fallback); arc-bearing or holed twisted pairs are rejected, as is auto-matching that would pair an arc with a straight edge. Matching hole counts are allowed in the two-section form. With intermediates the loft is a chain of ruled segments folded into one solid: sections must be planar and hole-free, ordered bottom → intermediates → top. The contours are copied — the input handles are never mutated.",
     "examplePrompts": [
       "Make a tapered tower from these two outlines",
       "Loft between a large base and a smaller top",
@@ -863,7 +863,7 @@
     "summary": "Stretches a surface across a closed loop of boundary curves and thickens it into a SOLID in one call — a roof over four curves, a canopy between two rails, a blend across a gap. `thickness` is in internal length units and is required: only solids reach the canvas, and there is no separate surface object to keep. Pass edges as `{ edge, brep, face }` with `continuity: \"tangent\"` to leave the named face smoothly. The result carries NO recipe (`design.query.getParameters` returns `null`) — label it when you commit it, because the label is all the provenance there is.",
     "examplePrompts": [
       "Patch a roof over these four boundary curves, 250 mm thick",
-      "Span a canopy between these two curved rails, 300 mm thick\n\n# Example\n```ts\n// A roof over four curves\nconst roof = await snaptrude.core.geom.create.brepFromPatch(\n[curveA, curveB, curveC, curveD],\n0.25,\n)\nconst mass = await snaptrude.design.create.massFromBrep(roof, \"Roof patch\")\n```\n\n```ts\n// A canopy between two towers' rims, leaving every wall it meets smoothly:\n// with `continuity: \"tangent\"` EVERY item is an edge naming its face.\nconst canopy = await snaptrude.core.geom.create.brepFromPatch(\n[\n{ edge: rimA, brep: towerA, face: wallA },\n{ edge: sideA, brep: towerA, face: endA },\n{ edge: rimB, brep: towerB, face: wallB },\n{ edge: sideB, brep: towerB, face: endB },\n],\n0.3,\n{ continuity: \"tangent\" },\n)\n```"
+      "Span a canopy between these two curved rails, 300 mm thick\n\n# Example\n```ts\n// A roof over four curves\nconst roof = await snaptrude.core.geom.create.brepFromPatch(\n[curveA, curveB, curveC, curveD],\n0.984, // 250 mm\n)\nconst mass = await snaptrude.design.create.massFromBrep(roof, \"Roof patch\")\n```\n\n```ts\n// A canopy between two towers' rims, leaving every wall it meets smoothly:\n// with `continuity: \"tangent\"` EVERY item is an edge naming its face.\nconst canopy = await snaptrude.core.geom.create.brepFromPatch(\n[\n{ edge: rimA, brep: towerA, face: wallA },\n{ edge: sideA, brep: towerA, face: endA },\n{ edge: rimB, brep: towerB, face: wallB },\n{ edge: sideB, brep: towerB, face: endB },\n],\n1.181, // 300 mm\n{ continuity: \"tangent\" },\n)\n```"
     ],
     "argsType": "(CurveHandle | OwnedEdge)[]",
     "resultType": "BrepHandle"
@@ -898,7 +898,7 @@
   {
     "path": "core.geom.create.brepFromSphere",
     "namespace": "core.geom.create",
-    "summary": "Create a solid **sphere** B-rep from a centre and radius. Host API call — returns a {@linkcode BrepHandle}; commit it to the scene with `design.create.massFromBrep`. The result carries an exact spherical surface (not a faceted approximation) and a creation recipe — read the committed mass's parameters back with `design.query.getParameters` and edit them with `design.update.parameters`.",
+    "summary": "Create a solid **sphere** B-rep (boundary representation: the solid's exact faces, edges and vertices) from a centre and radius. Host API call — returns a {@linkcode BrepHandle}; commit it to the scene with `design.create.massFromBrep`. The result carries an exact spherical surface (not a faceted approximation) and a creation recipe — read the committed mass's parameters back with `design.query.getParameters` and edit them with `design.update.parameters`.",
     "examplePrompts": [
       "Create a sphere of radius 5 at the origin",
       "Add a 3m ball on top of the tower\n\n# Example\n```ts\nconst brep = await snaptrude.core.geom.create.brepFromSphere({ x: 0, y: 5, z: 0 }, 5)\nconst mass = await snaptrude.design.create.massFromBrep(brep, \"Sphere\")\n```"
@@ -921,7 +921,7 @@
   {
     "path": "core.geom.create.brepFromSweep",
     "namespace": "core.geom.create",
-    "summary": "Sweeps a planar profile along a polyline path, with mitred corners at each bend. Host API call — returns a new {@linkcode BrepHandle}; the input contour is read-only. The profile must be hole-free and must not lie in a plane containing the first path segment's direction. Repeating the first point as the last closes the path into a ring solid (a picture frame): closed paths must be flat and straight-segmented and take a straight-edged (arc-free) profile — the ring's cross-section is the authored profile projected along the first leg onto the first mitre plane, so a profile not perpendicular to the first leg appears sheared. An optional scale law tapers the sweep: `startScale`/`endScale` interpolate linearly by arc length, or `scales` gives one factor per path point (scaling is about the profile centroid). A uniform scale (all factors equal) works on any path today's sweep accepts; a varying scale takes straight (collinear) open paths with straight-edged profiles — tapering across a bend or along an arc edge would create faces Snaptrude cannot represent and throws (sweep each straight run separately and union the results instead). An optional `transition` picks the corner treatment: `\"miter\"` (default) is today's sharp mitred bend; `\"round\"` carries the section around each turning corner on a tangent circular arc, so the corner patch is a real curved (cylindrical) surface rather than a flat cut (open paths only — `\"round\"` on a closed ring path is refused); `{ bevel: b }` chamfers each turning corner by cutting `b` back along both adjacent legs (works on open and closed paths — each leg must be long enough for its cuts). On a corner-less path `transition` has no effect, and the varying-scale lane takes straight paths, so it never sees a corner.",
+    "summary": "Sweeps a planar profile along a polyline path, with mitred corners at each bend. Host API call — returns a new {@linkcode BrepHandle}; the input contour is read-only. The profile must be hole-free and must not lie in a plane containing the first path segment's direction. Repeating the first point as the last closes the path into a ring solid (a picture frame): closed paths must be flat and straight-segmented and take a straight-edged (arc-free) profile — the ring's cross-section is the authored profile projected along the first leg onto the first mitre plane, so a profile not perpendicular to the first leg appears sheared. An optional scale law tapers the sweep: `startScale`/`endScale` interpolate linearly by arc length, or `scales` gives one factor per path point (scaling is about the profile centroid). A uniform scale (all factors equal) works on any path today's sweep accepts; a varying scale takes straight (collinear) open paths with straight-edged profiles — tapering across a bend or along an arc edge would create faces Snaptrude cannot represent and throws (sweep each straight run separately and union the results instead). An optional `transition` picks the corner treatment: `\"miter\"` (default) is a sharp mitred bend; `\"round\"` carries the section around each turning corner on a tangent circular arc, so the corner patch is a real curved surface (geometrically cylindrical; `getSurfaceKind` reports it as `\"spline\"`) rather than a flat cut (open paths only — `\"round\"` on a closed ring path is refused); `{ bevel: b }` chamfers each turning corner by cutting `b` back along both adjacent legs (works on open and closed paths — each leg must be long enough for its cuts). On a corner-less path `transition` has no effect, and a varying scale only accepts straight paths, so it never meets a corner.",
     "examplePrompts": [
       "Sweep this profile along the corridor path",
       "Extrude the railing section along this route",
@@ -938,7 +938,7 @@
   {
     "path": "core.geom.create.brepFromSweepAlongCurve",
     "namespace": "core.geom.create",
-    "summary": "Sweeps a cross-section along a SMOOTH path — splines, arcs and lines chained end to end — with control of how the profile turns. {@linkcode PluginGeomCreateApi.brepFromSweep} takes a polyline path; this takes curves. Host API call — returns a new {@linkcode BrepHandle}; the inputs are read-only. Records as `sweepAlongCurve`, so the orientation stays editable through `design.update.parameters` (agent-editable; the panel shows it read-only — a string is not a scalar row).",
+    "summary": "Sweeps a cross-section along a SMOOTH path — splines, arcs and lines chained end to end — with control of how the profile turns. {@linkcode PluginGeomCreateApi.brepFromSweep} takes a polyline path; this takes curves. Host API call — returns a new {@linkcode BrepHandle}; the inputs are read-only. Records as `sweepAlongCurve`, so the orientation stays editable through `design.update.parameters`. The properties panel shows it read-only, because it is a text value, not a number. A railed sweep records nothing (`getParameters` answers `null`).",
     "examplePrompts": [
       "Sweep a 600x400 duct along this curved route and keep it upright",
       "Run this handrail along the curved stair edge",
@@ -1077,7 +1077,7 @@
   {
     "path": "core.geom.create.profileRect",
     "namespace": "core.geom.create",
-    "summary": "Create an axis-aligned **rectangle** profile (XZ plane) of `width` × `depth`, centred at `center` (defaults to the origin). Host API call — returns a handle.",
+    "summary": "Create an axis-aligned **rectangle** profile in the XZ plane, `width` × `depth`, centred at `center` (defaults to the origin). Host API call — returns a handle.",
     "examplePrompts": [
       "Draw a 4m by 3m rectangle",
       "Make a rectangular outline for a room footprint"
@@ -1090,8 +1090,7 @@
     "namespace": "core.geom.create",
     "summary": "Create an open NURBS curve DEFINED BY control points — the curve is pulled TOWARD the interior points, not through them; it starts at the first point and ends at the last. Knots are computed for you (clamped, uniform) — there is no knot-vector argument. For a curve that must pass THROUGH given points use {@linkcode PluginGeomCreateApi.splineFromPoints}.",
     "examplePrompts": [
-      "Draw a smooth curve controlled by these four points",
-      "Rebuild this edge from its control polygon\n\n# Example\n```ts\nconst curve = await snaptrude.core.geom.create.splineFromControlPoints([p0, p1, p2, p3])\n// Quadratic instead of the default cubic\nconst tighter = await snaptrude.core.geom.create.splineFromControlPoints(\n[p0, p1, p2, p3],\n{ degree: 2 },\n)\n```"
+      "Draw a smooth curve controlled by these four points\n\n# Example\n```ts\nconst curve = await snaptrude.core.geom.create.splineFromControlPoints([p0, p1, p2, p3])\n// Quadratic instead of the default cubic\nconst tighter = await snaptrude.core.geom.create.splineFromControlPoints(\n[p0, p1, p2, p3],\n{ degree: 2 },\n)\n```"
     ],
     "argsType": "Vec3Handle[]",
     "resultType": "SplineHandle"
@@ -1189,7 +1188,7 @@
   {
     "path": "core.geom.query.brep.getCentroid",
     "namespace": "core.geom.query.brep",
-    "summary": "Get the centroid (mean of all vertex positions) of a brep.",
+    "summary": "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).",
     "examplePrompts": [
       "Find the centre point of this shape",
       "What is the centroid of the selected object?\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst centroid = await snaptrude.core.geom.query.brep.getCentroid(brep)\nconsole.log(centroid.x, centroid.y, centroid.z)\n}\n```"
@@ -1200,7 +1199,7 @@
   {
     "path": "core.geom.query.brep.getDistance",
     "namespace": "core.geom.query.brep",
-    "summary": "Measures the minimum distance between two solids, with the closest witness point on each. Touching or overlapping solids report a distance of 0 with contact points.",
+    "summary": "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.",
     "examplePrompts": [
       "What is the clearance between these two masses?",
       "How far apart are the tower and the neighbouring building?",
@@ -5140,7 +5139,7 @@
   {
     "path": "design.family.create",
     "namespace": "design.family",
-    "summary": "Commit the prepared bundle to the project's parametric-definition library, so it survives the session and appears in the Families panel.",
+    "summary": "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.",
     "examplePrompts": [
       "Save this as a family called Vertical Louvre",
       "Add it to my library\n\n# Example\n```ts\nconst { definitionId } = await snaptrude.design.family.create({ name: \"Louvre Screen\" })\n```"
@@ -5173,13 +5172,10 @@
   {
     "path": "design.family.get",
     "namespace": "design.family",
-    "summary": "A family's spec bundle: the prepared draft's, or — to CHANGE a saved family — that family's recipe, opened as the new draft.",
-    "examplePrompts": [
-      "Make the chairs I placed 50 mm wider",
-      "Change the Louvre Screen family so its blades are deeper\n\n# Example\n```ts\nconst draft = await snaptrude.design.family.get()\nconst family = await snaptrude.design.family.get({ component })\n// family.editing → { familyId, version, name, library }\n```"
-    ],
-    "argsType": "PluginDesignFamilyGetArgs",
-    "resultType": "PluginFamilyGetResult | null"
+    "summary": "The prepared family's spec bundle, or `null` when nothing is prepared.",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "PluginFamilyBundle | null"
   },
   {
     "path": "design.family.getParameters",
@@ -5220,7 +5216,7 @@
     "examplePrompts": [
       "Place it in the model",
       "Put a louvre screen at the origin",
-      "Copy that table two metres to the right\n\n# Example\n```ts\n// positioned — geometry exists when this resolves\nconst { component } = await snaptrude.design.family.place({\nid: \"revit:gypsum-stud-partition~90ad72\",\nposition: { x: 0, y: 0, z: 0 },\nrotation: 90,\n})\nawait snaptrude.design.transform.move([component], { x: 2, y: 0, z: 0 })\n\n// interactive — the user clicks\nawait snaptrude.design.family.place()\n\n// hosted — a door in a wall, near a point along it\nawait snaptrude.design.family.place({ id: doorId, host: wall, position: { x: 3, y: 0, z: 0 } })\n```"
+      "Copy that table two metres to the right\n\n# Example\n```ts\n// positioned — geometry exists when this resolves\nconst { component } = await snaptrude.design.family.place({\nid: \"revit:gypsum-stud-partition~90ad72\",\nposition: { x: 0, y: 0, z: 0 },\nrotation: 90,\n})\nawait snaptrude.design.transform.move([component], { x: 2, y: 0, z: 0 })\n\n// interactive — the user clicks\nawait snaptrude.design.family.place()\n```"
     ],
     "argsType": "PluginDesignFamilyPlaceArgs",
     "resultType": "PluginFamilyPlaceResult"
@@ -5228,11 +5224,12 @@
   {
     "path": "design.family.prepare",
     "namespace": "design.family",
-    "summary": "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.",
+    "summary": "Validate, compile and preview a family spec. Nothing is committed to the model or the library — call {@linkcode PluginDesignFamilyApi.place} to put it in the model, which also saves it.",
     "examplePrompts": [
       "Make a louvre screen with adjustable blade count and tilt",
       "Design a curtain wall panel family with 8 bays",
-      "Create a railing family I can adjust\n\n# Example\n```ts\nconst r = await snaptrude.design.family.prepare({ bundle })\nif (!r.ok) console.error(r.errors[0].path, r.errors[0].message)\n```"
+      "Create a railing family I can adjust",
+      "Make a pendant lamp family with a domed shade I can resize\n\n# Example\n```ts\nconst r = await snaptrude.design.family.prepare({ bundle })\nif (!r.ok) console.error(r.errors[0].path, r.errors[0].message)\n```"
     ],
     "argsType": "PluginDesignFamilyPrepareArgs",
     "resultType": "PluginFamilyPrepareResult"
@@ -5243,7 +5240,7 @@
     "summary": "Change a placed component's parameters and rebuild its geometry in place.",
     "examplePrompts": [
       "Make that table seat 8",
-      "Change the stud spacing to 400\n\n# Example\n```ts\nawait snaptrude.design.family.setParameters({ component, values: { seats: 8 } })\nawait snaptrude.design.family.setParameters({ component, children: { chair: { width: \"380mm\" } } })\nawait snaptrude.design.family.setParameters({\ncomponent: railing,\nlinks: { steps: { from: stair, expr: \"steps\" }, side: { from: stair, expr: \"width - 40mm\" } },\n})\nawait snaptrude.design.family.setParameters({\ncomponent: post,\nrelations: { add: [{ kind: \"attach\", side: \"top\", to: slab, bind: { height: \"reach\" } }] },\n})\n```"
+      "Change the stud spacing to 400\n\n# Example\n```ts\nawait snaptrude.design.family.setParameters({ component, values: { seats: 8 } })\n```"
     ],
     "argsType": "PluginDesignFamilySetParametersArgs",
     "resultType": "PluginFamilyInstanceParameters"
@@ -5712,7 +5709,7 @@
   {
     "path": "design.query.geometry.getTriangulatedMeshes",
     "namespace": "design.query.geometry",
-    "summary": "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.",
+    "summary": "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. The result is `{ meshes }`, not a bare array — destructure it before iterating.",
     "examplePrompts": [
       "Export the selected masses as a triangle mesh",
       "Get the raw vertices and triangles of this wall in world coordinates",
@@ -7161,7 +7158,7 @@
       "Add a red arrow from the title to the plan view",
       "Point an arrow at the top-left view on the cover sheet\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.arrow(\n\"sheet_1\",\n{ x: 100, y: 200 },\n{ x: 300, y: 250 },\n{ color: \"red\" },\n)\n```"
     ],
-    "argsType": "string",
+    "argsType": "string | undefined",
     "resultType": "PluginPresentationAnnotateResult"
   },
   {
@@ -7173,7 +7170,7 @@
       "Put a yellow note on the cover sheet",
       "Leave a note next to the ground floor plan\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.note(\n\"sheet_1\",\n\"Review this wall\",\n{ position: { x: 60, y: 120 }, color: \"yellow\" },\n)\n```"
     ],
-    "argsType": "string",
+    "argsType": "string | undefined",
     "resultType": "PluginPresentationAnnotateResult"
   },
   {
@@ -7185,7 +7182,7 @@
       "Add a red rectangle highlight to the sheet",
       "Draw an ellipse around the entrance on the cover sheet\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.shape(\n\"sheet_1\",\n\"cloud\",\n{ x: 80, y: 80, w: 240, h: 160 },\n{ color: \"red\" },\n)\n```"
     ],
-    "argsType": "string",
+    "argsType": "string | undefined",
     "resultType": "PluginPresentationAnnotateResult"
   },
   {
@@ -7198,7 +7195,7 @@
       "Caption this view with \"Proposed layout\"",
       "Put a red note on the sheet\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.text(\n\"sheet_1\",\n\"Ground Floor\",\n{ position: { x: 40, y: 40 }, size: \"xl\", color: \"blue\" },\n)\n```"
     ],
-    "argsType": "string",
+    "argsType": "string | undefined",
     "resultType": "PluginPresentationAnnotateTextResult"
   },
   {
@@ -7237,20 +7234,242 @@
     "argsType": "string",
     "resultType": "PluginPresentationDiagramsPlaceResult"
   },
+  {
+    "path": "presentation.drawings.applyPreset",
+    "namespace": "presentation.drawings",
+    "summary": "Bind a kernel plan to a preset and clear declared overrides; local title text is retained.",
+    "examplePrompts": [
+      "Apply the presentation plan preset to this drawing"
+    ],
+    "argsType": "string",
+    "resultType": "PluginDrawing"
+  },
+  {
+    "path": "presentation.drawings.copy",
+    "namespace": "presentation.drawings",
+    "summary": "Copy a drawing and its annotations with native duplication; returns the new drawing.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawing"
+  },
+  {
+    "path": "presentation.drawings.create",
+    "namespace": "presentation.drawings",
+    "summary": "Generate a saved source view on the canvas. Options use page coordinates and a standard scale denominator.",
+    "examplePrompts": [
+      "Create a drawing from the ground floor view"
+    ],
+    "argsType": "string",
+    "resultType": "PluginDrawing"
+  },
+  {
+    "path": "presentation.drawings.delete",
+    "namespace": "presentation.drawings",
+    "summary": "Delete a drawing and its children as one Present undo step.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.drawings.export",
+    "namespace": "presentation.drawings",
+    "summary": "Export the drawing including labels/annotations, no sheet required. PDF size follows its canvas bounds. download:true starts a browser download and returns metadata only (never send large base64 to an agent). Otherwise files contain dataBase64. downloadStarted means initiated, not proof of an OS-saved file. SVG/PDF preserve vector content; raster fallbacks remain raster. Layout warnings are returned.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawingExportResult"
+  },
+  {
+    "path": "presentation.drawings.get",
+    "namespace": "presentation.drawings",
+    "summary": "Read a drawing by its stable id; null if it no longer exists.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawing | null"
+  },
+  {
+    "path": "presentation.drawings.getCapabilities",
+    "namespace": "presentation.drawings",
+    "summary": "Read actual renderer and supported operations; presets are kernel-plan-only.",
+    "examplePrompts": [
+      "What editing capabilities does this drawing support?"
+    ],
+    "argsType": "string",
+    "resultType": "PluginDrawingCapabilities"
+  },
+  {
+    "path": "presentation.drawings.getStatus",
+    "namespace": "presentation.drawings",
+    "summary": "Wait at most waitMs (0 by default) for export readiness and upload; returns current status on timeout.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawingStatus"
+  },
+  {
+    "path": "presentation.drawings.getStyles",
+    "namespace": "presentation.drawings",
+    "summary": "Read effective categories/controls before editing; absent categories reject writes.",
+    "examplePrompts": [
+      "Show the editable styles for this drawing"
+    ],
+    "argsType": "string",
+    "resultType": "PluginDrawingStyles"
+  },
+  {
+    "path": "presentation.drawings.labels.getLayout",
+    "namespace": "presentation.drawings.labels",
+    "summary": "Read collision diagnostics, suggested scales and pin counts without hiding failed labels.",
+    "examplePrompts": [
+      "Check this drawing for overlapping labels"
+    ],
+    "argsType": "string",
+    "resultType": "PluginDrawingLabelLayout"
+  },
+  {
+    "path": "presentation.drawings.labels.list",
+    "namespace": "presentation.drawings.labels",
+    "summary": "List every text label on a drawing, including hidden labels.",
+    "examplePrompts": [
+      "List all labels in this drawing"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabel[]"
+  },
+  {
+    "path": "presentation.drawings.labels.move",
+    "namespace": "presentation.drawings.labels",
+    "summary": "Move a label; room labels retain the chosen position at the current architectural scale.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabel"
+  },
+  {
+    "path": "presentation.drawings.labels.place",
+    "namespace": "presentation.drawings.labels",
+    "summary": "Pin an unclean room label at its best available position. May wait up to ten seconds for fitting.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "presentation.drawings.labels.reset",
+    "namespace": "presentation.drawings.labels",
+    "summary": "Clear pins at this scale (default) or every scale. Returns the number cleared.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "number"
+  },
+  {
+    "path": "presentation.drawings.labels.setHidden",
+    "namespace": "presentation.drawings.labels",
+    "summary": "Set user visibility, independently of layout/crop visibility.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabel"
+  },
+  {
+    "path": "presentation.drawings.list",
+    "namespace": "presentation.drawings",
+    "summary": "List drawing deliverables on the current Present page.",
+    "examplePrompts": [
+      "List all drawings in this presentation"
+    ],
+    "argsType": null,
+    "resultType": "PluginDrawing[]"
+  },
+  {
+    "path": "presentation.drawings.listFonts",
+    "namespace": "presentation.drawings",
+    "summary": "List available font families from the native catalog (including DEFAULT).",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "string[]"
+  },
+  {
+    "path": "presentation.drawings.listPatterns",
+    "namespace": "presentation.drawings",
+    "summary": "List pattern ids accepted by the native hatch catalog.",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "{ id: string; label: string; group: string }[]"
+  },
+  {
+    "path": "presentation.drawings.rename",
+    "namespace": "presentation.drawings",
+    "summary": "Rename the drawing title without renaming its source saved view.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawing"
+  },
+  {
+    "path": "presentation.drawings.resetOverrides",
+    "namespace": "presentation.drawings",
+    "summary": "Reset declared overrides to the bound preset, preserving local title/proposal/building text.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawing"
+  },
+  {
+    "path": "presentation.drawings.setCrop",
+    "namespace": "presentation.drawings",
+    "summary": "Set normalized crop corners (0–1), or null to remove the crop.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawing"
+  },
+  {
+    "path": "presentation.drawings.setScale",
+    "namespace": "presentation.drawings",
+    "summary": "Set a standard architectural scale; perspective/isometric drawings reject this.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawing"
+  },
+  {
+    "path": "presentation.drawings.updateContent",
+    "namespace": "presentation.drawings",
+    "summary": "Regenerate specified drawings. Reports actual changed assets, not merely submitted ids.",
+    "examplePrompts": [],
+    "argsType": "string[]",
+    "resultType": "{ drawingId: string; updated: boolean }[]"
+  },
+  {
+    "path": "presentation.drawings.updateStyles",
+    "namespace": "presentation.drawings",
+    "summary": "Merge a typed category patch as one undo step. Invalid/unsupported fields reject the whole call.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginDrawingStyles"
+  },
   {
     "path": "presentation.export",
     "namespace": "presentation",
-    "summary": "Export the presentation's layout sheets to a downloadable file (PDF / PNG / JPG) and return the encoded bytes as base64. Wraps the Present-mode Export dialog pipeline headlessly. Requires Present mode to be open.",
+    "summary": "Export the presentation's layout sheets to a downloadable file (PDF / PNG / JPG). Return base64 by default; `download: true` initiates browser downloads and returns metadata without base64. Requires Present mode to be open.",
     "examplePrompts": [
       "Export the presentation as a PDF",
       "Download all sheets as a single PDF",
       "Export sheet 1 as a PNG",
       "Save the presentation sheets as JPG images",
-      "Export these sheets to PDF at high resolution\n\n# Example\n```ts\nconst { files } = await snaptrude.presentation.export(\"pdf\")\n```"
+      "Export these sheets to PDF at high resolution\n\n# Example\n```ts\nconst { files } = await snaptrude.presentation.export(\"pdf\")\nconst download = await snaptrude.presentation.export(\"pdf\", { download: true })\n```"
     ],
     "argsType": "PluginPresentationExportFormat",
     "resultType": "PluginPresentationExportResult"
   },
+  {
+    "path": "presentation.export",
+    "namespace": "presentation",
+    "summary": "",
+    "examplePrompts": [],
+    "argsType": "PluginPresentationExportFormat",
+    "resultType": "PluginPresentationExportDownloadResult"
+  },
+  {
+    "path": "presentation.export",
+    "namespace": "presentation",
+    "summary": "",
+    "examplePrompts": [],
+    "argsType": "PluginPresentationExportFormat",
+    "resultType": "PluginPresentationExportResult | PluginPresentationExportDownloadResult"
+  },
   {
     "path": "presentation.import.image",
     "namespace": "presentation.import",
@@ -7664,6 +7883,17 @@
     "argsType": "string",
     "resultType": "PluginPresentationSheetsPlaceResult"
   },
+  {
+    "path": "presentation.sheets.placeDrawing",
+    "namespace": "presentation.sheets",
+    "summary": "Move an existing drawing onto a sheet without copying or regenerating it.",
+    "examplePrompts": [
+      "Move this drawing onto the cover sheet",
+      "Place drawing_1 at the center of sheet_2"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheetsPlaceResult"
+  },
   {
     "path": "presentation.sheets.rename",
     "namespace": "presentation.sheets",
@@ -7787,6 +8017,68 @@
     "argsType": "string",
     "resultType": "PluginCanvasShape"
   },
+  {
+    "path": "presentation.viewPresets.copy",
+    "namespace": "presentation.viewPresets",
+    "summary": "Copy a preset with a native unique name, without changing drawing bindings.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginViewPreset"
+  },
+  {
+    "path": "presentation.viewPresets.create",
+    "namespace": "presentation.viewPresets",
+    "summary": "Capture a drawing's effective styles and bind it to the new preset. Names must be unique.",
+    "examplePrompts": [
+      "Save this drawing's styles as a new preset"
+    ],
+    "argsType": "string",
+    "resultType": "PluginViewPreset"
+  },
+  {
+    "path": "presentation.viewPresets.delete",
+    "namespace": "presentation.viewPresets",
+    "summary": "Delete a custom preset, rebinding its drawings to a different existing replacement.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.viewPresets.get",
+    "namespace": "presentation.viewPresets",
+    "summary": "Read a preset, or null when missing.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginViewPreset | null"
+  },
+  {
+    "path": "presentation.viewPresets.list",
+    "namespace": "presentation.viewPresets",
+    "summary": "List built-ins first, then custom presets by name.",
+    "examplePrompts": [
+      "List the available drawing style presets"
+    ],
+    "argsType": null,
+    "resultType": "PluginViewPreset[]"
+  },
+  {
+    "path": "presentation.viewPresets.rename",
+    "namespace": "presentation.viewPresets",
+    "summary": "Rename a custom preset. Built-ins reject this operation.",
+    "examplePrompts": [],
+    "argsType": "string",
+    "resultType": "PluginViewPreset"
+  },
+  {
+    "path": "presentation.viewPresets.update",
+    "namespace": "presentation.viewPresets",
+    "summary": "Update a custom preset from a drawing bound to it; refresh all bound drawings.",
+    "examplePrompts": [
+      "Update this preset from the current drawing styles"
+    ],
+    "argsType": "string",
+    "resultType": "PluginViewPreset"
+  },
   {
     "path": "presentation.views.capture",
     "namespace": "presentation.views",
@@ -7869,7 +8161,7 @@
     "summary": "List the saved views in the active project.",
     "examplePrompts": [
       "List all the saved views",
-      "What 2D and 3D views are in this project?",
+      "What plan, 3D, and elevation views are in this project?",
       "Which view is currently active?",
       "Get the names of every presentation view",
       "Show me the 3D views I can put on a sheet\n\n# Example\n```ts\nconst { views } = await snaptrude.presentation.views.list()\nconst active = views.find((v) => v.isActive)\nconst plans = views.filter((v) => v.type === \"2d\")\n```"