@snaptrude/plugin-core 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,17 +16,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "ts-morph": "^28.0.0",
-    "tsup": "^8.5.1",
-    "typescript": "^5.5.4"
-  },
-  "dependencies": {
-    "zod": "^4.3.6"
-  },
-  "peerDependencies": {
-    "zod": "^3.25.0 || ^4.0.0"
-  },
   "scripts": {
     "check-types": "tsc --noEmit",
     "build": "tsup --clean",
@@ -37,5 +26,16 @@
     "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
     "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
     "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
+  },
+  "devDependencies": {
+    "ts-morph": "^28.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
   }
-}
+}

package/src/api/core/geom/create/index.ts

@@ -264,28 +264,52 @@ export abstract class PluginGeomCreateApi {
   /**
    * 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}. All sections must have the same number
-   * of edges; side faces connect corresponding edges by authored index.
-   * Corresponding edges must stay coplanar segment to segment (matching hole
-   * counts allowed in the two-section form) — a twisted loft would produce
-   * non-planar side faces and is rejected. 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.
+   * 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.
    *
    * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
    * with `design.create.massFromBrep`.
    *
    * @param bottomContour The bottom cross-section
-   * @param topContour The top cross-section (same edge count as the bottom)
+   * @param topContour The top cross-section (edge count may differ from the
+   *   bottom — sections are auto-matched)
    * @param intermediateContours Optional in-between cross-sections, ordered
-   *   bottom to top (hole-free, same edge count as the bottom and top)
+   *   bottom to top (hole-free; edge counts may differ — every section is
+   *   normalized to the largest)
+   * @param options Optional behavior switches. `compatibility` — `"auto"`
+   *   (default) inserts vertices to match differing edge counts; `"strict"`
+   *   skips normalization and throws VALIDATION when outer edge counts (or,
+   *   in the two-section form, hole-pair counts) differ. `seamAlignment` —
+   *   `"auto"` (default) searches seam rotations on straight-edge sections to
+   *   avoid a twist; `"authored"` keeps the authored start-vertex
+   *   correspondence unchanged (a twisted correspondence then builds through
+   *   the triangulated lane for hole-free straight-edged pairs).
+   *   `{ compatibility: "strict", seamAlignment: "authored" }` reproduces
+   *   pre-0.9.4 lofting exactly.
    * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws VALIDATION if the contours are coincident, their edge or hole
-   *   counts differ, any section has holes when intermediates are present
+   * @throws VALIDATION if the contours are coincident, their hole counts
+   *   differ, any section has holes when intermediates are present
    *   (multi-section lofts take hole-free sections), a section is non-planar,
-   *   or a side face between corresponding edges would be non-planar (a
-   *   twisted section pair — the error names the offending sections)
+   *   sections are too dissimilar to auto-match, auto-matching would pair an
+   *   arc with a straight edge, or — for arc-bearing or holed pairs only — no vertex correspondence avoids a twist (a
+   *   side face between corresponding edges would be non-planar — the error
+   *   names the offending sections); with `compatibility: "strict"`, if
+   *   section edge counts (or hole-pair counts) differ — the error names the
+   *   sections and counts and points at `compatibility: "auto"`
    * @throws OPERATION_FAILED if the lofted segments cannot be joined into a
    *   valid solid
    *
@@ -293,6 +317,10 @@ export abstract class PluginGeomCreateApi {
    * @examplePrompt Loft between a large base and a smaller top
    * @examplePrompt Create a frustum from two squares
    * @examplePrompt Loft the tower through these three floor outlines
+   * @examplePrompt Loft a four-sided base to a five-sided top
+   * @examplePrompt Loft these outlines even though their corners don't line up
+   * @examplePrompt Loft these outlines exactly as authored, corner to corner
+   * @examplePrompt Fail the loft if my sections don't have matching edge counts
    *
    * # Example
    * ```ts
@@ -310,6 +338,7 @@ export abstract class PluginGeomCreateApi {
     bottomContour: ContourHandle,
     topContour: ContourHandle,
     intermediateContours?: ContourHandle[],
+    options?: { compatibility?: "strict" | "auto"; seamAlignment?: "authored" | "auto" },
   ): PluginApiReturn<BrepHandle>
 
   /**
@@ -636,24 +665,59 @@ export abstract class PluginGeomCreateApi {
   ): PluginApiReturn<BrepHandle>
 
   /**
-   * Sweeps a planar profile along an open polyline path, with mitred corners
-   * at each bend. Host API call — returns a new {@linkcode BrepHandle}; the
+   * 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.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
-   * tens of MB — expect a pause of seconds).
+   * 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;
+   * `{ 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.
+   *
+   * Open paths run on the OpenCascade kernel (the first kernel call loads a
+   * wasm of tens of MB — expect a pause of seconds); closed paths are
+   * computed host-side and never load the kernel.
    *
    * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
    * with `design.create.massFromBrep`.
    *
    * @param profile The cross-section to sweep (hole-free contour)
-   * @param path The polyline path as plain `{x, y, z}` points (≥2, open — first ≠ last)
+   * @param path The polyline path as plain `{x, y, z}` points (≥2; repeat the
+   *   first point as the last to close the path into a ring)
+   * @param options Optional scale law and corner transition. Scale law:
+   *   `startScale`/`endScale` (linear taper by arc length) or `scales` (one
+   *   factor per path point; mutually exclusive with
+   *   `startScale`/`endScale`); every factor must be finite and within
+   *   1e-3..1e3. `transition`: `"miter"` (default, sharp corners) or
+   *   `{ bevel: b }` (chamfered corners, `b` finite within 1e-3..1e3; open
+   *   and closed paths)
    * @returns The swept solid as a new {@linkcode BrepHandle}
    * @throws VALIDATION if the profile has holes, the path has fewer than 2
-   *   points, consecutive path points coincide, the path is closed (open
-   *   paths only in v1), a coordinate is not finite, or the profile plane
-   *   contains the first path segment's direction (degenerate sweep)
+   *   points, consecutive path points coincide, a coordinate is not finite,
+   *   or the profile plane contains the first path segment's direction
+   *   (degenerate sweep); for closed paths, if the ring has fewer than 3
+   *   distinct corners, the path is non-planar, a corner doubles back, the
+   *   profile has an arc edge, or the profile is too large for a mitred
+   *   corner; for scale options, if a factor is outside 1e-3..1e3, `scales`
+   *   is combined with `startScale`/`endScale`, `scales` does not match the
+   *   path length, or a varying scale is used on a bent or closed path or
+   *   with an arc-edged profile; for `{ bevel }`, if a leg is too short for
+   *   the cuts its beveled corners take from it or a corner nearly doubles
+   *   back so its chamfer collapses (the errors name the corner)
    * @throws OPERATION_FAILED if the kernel cannot sweep the profile into a
    *   valid solid or a transition patch is a curved surface Snaptrude cannot
    *   represent
@@ -661,6 +725,10 @@ export abstract class PluginGeomCreateApi {
    * @examplePrompt Sweep this profile along the corridor path
    * @examplePrompt Extrude the railing section along this route
    * @examplePrompt Run a duct profile through these points
+   * @examplePrompt Sweep a frame profile around a closed rectangular loop
+   * @examplePrompt Taper this duct from 1x1 to 2x2 along its run
+   * @examplePrompt Sweep a column section that narrows toward the top
+   * @examplePrompt Chamfer the corners of this swept frame by 200mm
    *
    * # Example
    * ```ts
@@ -673,11 +741,34 @@ export abstract class PluginGeomCreateApi {
    *   { x: 0, y: 2.8, z: 0 },
    *   { x: 10, y: 2.8, z: 0 },
    * ])
+   * // A closed ring (picture frame): repeat the first point as the last
+   * const frame = await snaptrude.core.geom.create.brepFromSweep(profile, [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 0, y: 3, z: 0 },
+   *   { x: 4, y: 3, z: 0 },
+   *   { x: 4, y: 0, z: 0 },
+   *   { x: 0, y: 0, z: 0 },
+   * ])
+   * // A tapered straight run: 0.4x0.4 at the start, 0.8x0.8 at the end
+   * const flue = await snaptrude.core.geom.create.brepFromSweep(
+   *   profile,
+   *   [
+   *     { x: 0, y: 0, z: 0 },
+   *     { x: 0, y: 10, z: 0 },
+   *   ],
+   *   { startScale: 1, endScale: 2 },
+   * )
    * ```
    */
   public abstract brepFromSweep(
     profile: ContourHandle,
     path: Vec3Components[],
+    options?: {
+      startScale?: number
+      endScale?: number
+      scales?: number[]
+      transition?: "miter" | { bevel: number }
+    },
   ): PluginApiReturn<BrepHandle>
 
   /**
@@ -897,11 +988,18 @@ export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
  * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
  * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
  * | `intermediateContours` | {@linkcode ContourHandle}`[]`? | Optional in-between cross-sections, ordered bottom to top |
+ * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`) and `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) |
  */
 export const PluginGeomCreateBrepFromLoftArgs = z.object({
   bottomContour: ContourHandle,
   topContour: ContourHandle,
   intermediateContours: z.array(ContourHandle).optional(),
+  options: z
+    .object({
+      compatibility: z.enum(["strict", "auto"]).optional(),
+      seamAlignment: z.enum(["authored", "auto"]).optional(),
+    })
+    .optional(),
 })
 
 export type PluginGeomCreateBrepFromLoftArgs = z.infer<typeof PluginGeomCreateBrepFromLoftArgs>
@@ -1034,18 +1132,53 @@ export type PluginGeomCreateBrepFromChamferArgs = z.infer<
   typeof PluginGeomCreateBrepFromChamferArgs
 >
 
+// Taper scale factor — bounded so a near-zero scale cannot pinch a section
+// into a degenerate sliver the downstream planarity gates would miss.
+const SweepScaleFactor = z.number().finite().min(1e-3).max(1e3)
+
 /**
  * Arguments for {@linkcode PluginGeomCreateApi.brepFromSweep}.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
- * | `path` | {@linkcode Vec3Components}`[]` | The open polyline path (≥2 points, finite components) |
+ * | `path` | {@linkcode Vec3Components}`[]` | The polyline path (≥2 points, finite components; repeating the first point as the last closes it into a ring — closed paths must be flat and straight-segmented and take a straight-edged profile) |
+ * | `options` | `object`? | Optional scale law: `startScale`/`endScale` (linear taper by arc length) or per-point `scales` (mutually exclusive; factors finite, 1e-3..1e3; `scales.length` must equal `path.length`). Optional corner `transition`: `"miter"` (default) or `{ bevel }` (chamfered corners; finite, 1e-3..1e3) |
  */
-export const PluginGeomCreateBrepFromSweepArgs = z.object({
-  profile: ContourHandle,
-  path: z.array(FiniteVec3Components).min(2),
-})
+export const PluginGeomCreateBrepFromSweepArgs = z
+  .object({
+    profile: ContourHandle,
+    path: z.array(FiniteVec3Components).min(2),
+    options: z
+      .object({
+        startScale: SweepScaleFactor.optional(),
+        endScale: SweepScaleFactor.optional(),
+        scales: z.array(SweepScaleFactor).optional(),
+        transition: z
+          .union([
+            z.literal("miter"),
+            z.object({ bevel: z.number().finite().min(1e-3).max(1e3) }),
+          ])
+          .optional(),
+      })
+      .optional(),
+  })
+  .superRefine((a, ctx) => {
+    const options = a.options
+    if (!options || options.scales === undefined) return
+    if (options.startScale !== undefined || options.endScale !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "scales is mutually exclusive with startScale/endScale",
+      })
+    }
+    if (options.scales.length !== a.path.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "scales must have exactly one entry per path point",
+      })
+    }
+  })
 
 export type PluginGeomCreateBrepFromSweepArgs = z.infer<typeof PluginGeomCreateBrepFromSweepArgs>
 

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

@@ -163,6 +163,64 @@ export abstract class PluginGeomQueryBrepApi {
     vertexIndexB: number
   ): PluginApiReturn<EdgeHandle[]>
 
+  /**
+   * Read the exact curve of a brep edge as plain values — a discriminated
+   * union on `type`. Pure read: no geometry kernel is loaded. Points and
+   * directions are {@linkcode Vec3Components}; lengths and radii are raw
+   * Babylon units.
+   *
+   * | `type` | Fields |
+   * |---|---|
+   * | `"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) |
+   *
+   * @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`
+   *
+   * @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
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   for (const edge of edges) {
+   *     const curve = await snaptrude.core.geom.query.brep.getEdgeCurve(brep, edge)
+   *     if (curve.type === "arc") console.log("arc radius:", curve.radius)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getEdgeCurve(
+    brep: BrepHandle,
+    edge: EdgeHandle
+  ): PluginApiReturn<
+    | { type: "line"; startPoint: Vec3Components; endPoint: Vec3Components; length: number }
+    | {
+        type: "arc"
+        startPoint: Vec3Components
+        endPoint: Vec3Components
+        centre: Vec3Components
+        axis: Vec3Components
+        radius: number
+        length: number
+      }
+    | {
+        type: "circle"
+        centre: Vec3Components
+        axis: Vec3Components
+        radius: number
+        length: number
+      }
+  >
+
   /**
    * Get the position of a vertex within a brep.
    * @param brep The brep to query
@@ -408,6 +466,22 @@ export type PluginGeomQueryBrepListEdgesBetweenArgs = z.infer<
   typeof PluginGeomQueryBrepListEdgesBetweenArgs
 >
 
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.getEdgeCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The brep the edge belongs to |
+ * | `edge` | {@linkcode EdgeHandle} | The edge whose curve to read |
+ */
+export const PluginGeomQueryBrepGetEdgeCurveArgs = z.object({
+  brep: BrepHandle,
+  edge: EdgeHandle,
+})
+export type PluginGeomQueryBrepGetEdgeCurveArgs = z.infer<
+  typeof PluginGeomQueryBrepGetEdgeCurveArgs
+>
+
 /**
  * Arguments for {@linkcode PluginGeomQueryBrepApi.getVertexPosition}.
  *