forgecad 0.9.5 → 0.9.6

package/dist-skill/CONTEXT.md

@@ -3832,7 +3832,15 @@ detectArrangement(): Sketch[]
 #### `detectArrangementRegion()` — Select the single arrangement region that contains the given seed point. Throws if no region contains the seed.
 
 ```ts
-detectArrangementRegion(seed: [ number, number ]): Sketch
+detectArrangementRegion(_seed: [ number, number ]): Sketch
+```
+
+#### `toPolyline()` — Return the solved constrained path as a sampled 2D polyline.
+
+Use this when a construction rail was authored with `constrainedSketch()` and should feed another operation such as `Loft.pathOnXz(...)`. The sketch must contain exactly one profile path.
+
+```ts
+toPolyline(samples?: number): [ number, number ][]
 ```
 
 #### `withUpdatedConstraint()` — Re-solve the sketch after changing the value of one existing constraint.
@@ -4187,7 +4195,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
 - [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
 - [NurbsCurve3D](#nurbscurve3d)
@@ -4230,6 +4238,87 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ### Curves & Surfacing
 
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
+
+`LoftStation`: `{ profile: Sketch, position: number }`
+
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+
+```ts
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+```
+
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+```
+
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+
 #### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
 The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
@@ -4318,10 +4407,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 #### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
 Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
@@ -4999,6 +5084,21 @@ path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
 mirror(axis: "x" | "y" | [ number, number ]): this
 ```
 
+#### `toPolyline()` — Return the open path as a sampled 2D polyline.
+
+This is for construction geometry such as guide rails, measured centerlines, and curve-driven helpers where the authored path should stay open instead of becoming a filled sketch or stroked profile.
+
+```ts
+const rail = path()
+  .moveTo(24, 0)
+  .bezierTo(32, 44, 28, 92, 18, 120)
+  .toPolyline();
+```
+
+```ts
+toPolyline(): [ number, number ][]
+```
+
 #### `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
 
 ```ts
@@ -9287,9 +9387,15 @@ root = largest component by body count, object count, then bbox volume
 rootDistance = shortest accumulated gap distance from root component
 ```
 
+For large scenes the manifest does not materialize the complete component gap
+graph, because that graph is quadratic in the number of components. The
+`gapEdgeCount` field reports the logical complete-graph edge count used by the
+analysis. `gapEdges` stores a compact evidence subset containing nearest-gap
+and root-parent edges.
+
 The PNG colors components from green at the root/near distances through yellow to
 red at the farthest rooted component. The manifest stores the root component,
-maximum rooted distance, complete component gap edge list, nearest-gap data, and
+maximum rooted distance, compact gap edge evidence, nearest-gap data, and
 shortest-path parent fields. The current v1 metric is bbox-based: it measures air
 gaps between component bounding boxes, not exact closest mesh-surface distance.
 
@@ -9306,8 +9412,8 @@ collision = boolean intersection volume > 0.1mm^3
 ```
 
 The manifest stores the inspected objects, collision pair names/ids, overlap
-volume, warnings, render style, and each collision finding's `groupIndex`,
-`color`, and `hex`. Exact interior pixels can be matched against
+volume, broadphase counters, warnings, render style, and each collision finding's
+`groupIndex`, `color`, and `hex`. Exact interior pixels can be matched against
 `manifest.channels.collisions.collisions[].color`; antialiased edges may blend
 with the ghosted source geometry. If `--focus PartA,PartB` is used, everything
 except those objects is hidden, `PartA` and `PartB` are ghosted, and their

package/dist-skill/docs/generated/curves.md

@@ -9,7 +9,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
 - [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
 - [NurbsCurve3D](#nurbscurve3d)
@@ -52,6 +52,87 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ### Curves & Surfacing
 
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
+
+`LoftStation`: `{ profile: Sketch, position: number }`
+
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+
+```ts
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+```
+
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+```
+
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+
 #### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
 The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
@@ -140,10 +221,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 #### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
 Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
@@ -821,6 +898,21 @@ path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
 mirror(axis: "x" | "y" | [ number, number ]): this
 ```
 
+#### `toPolyline()` — Return the open path as a sampled 2D polyline.
+
+This is for construction geometry such as guide rails, measured centerlines, and curve-driven helpers where the authored path should stay open instead of becoming a filled sketch or stroked profile.
+
+```ts
+const rail = path()
+  .moveTo(24, 0)
+  .bezierTo(32, 44, 28, 92, 18, 120)
+  .toPolyline();
+```
+
+```ts
+toPolyline(): [ number, number ][]
+```
+
 #### `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
 
 ```ts

package/dist-skill/docs/generated/sketch.md

@@ -1457,7 +1457,15 @@ detectArrangement(): Sketch[]
 #### `detectArrangementRegion()` — Select the single arrangement region that contains the given seed point. Throws if no region contains the seed.
 
 ```ts
-detectArrangementRegion(seed: [ number, number ]): Sketch
+detectArrangementRegion(_seed: [ number, number ]): Sketch
+```
+
+#### `toPolyline()` — Return the solved constrained path as a sampled 2D polyline.
+
+Use this when a construction rail was authored with `constrainedSketch()` and should feed another operation such as `Loft.pathOnXz(...)`. The sketch must contain exactly one profile path.
+
+```ts
+toPolyline(samples?: number): [ number, number ][]
 ```
 
 #### `withUpdatedConstraint()` — Re-solve the sketch after changing the value of one existing constraint.

package/dist-skill/docs/guides/inspection-bundles.md

@@ -190,9 +190,15 @@ root = largest component by body count, object count, then bbox volume
 rootDistance = shortest accumulated gap distance from root component
 ```
 
+For large scenes the manifest does not materialize the complete component gap
+graph, because that graph is quadratic in the number of components. The
+`gapEdgeCount` field reports the logical complete-graph edge count used by the
+analysis. `gapEdges` stores a compact evidence subset containing nearest-gap
+and root-parent edges.
+
 The PNG colors components from green at the root/near distances through yellow to
 red at the farthest rooted component. The manifest stores the root component,
-maximum rooted distance, complete component gap edge list, nearest-gap data, and
+maximum rooted distance, compact gap edge evidence, nearest-gap data, and
 shortest-path parent fields. The current v1 metric is bbox-based: it measures air
 gaps between component bounding boxes, not exact closest mesh-surface distance.
 
@@ -209,8 +215,8 @@ collision = boolean intersection volume > 0.1mm^3
 ```
 
 The manifest stores the inspected objects, collision pair names/ids, overlap
-volume, warnings, render style, and each collision finding's `groupIndex`,
-`color`, and `hex`. Exact interior pixels can be matched against
+volume, broadphase counters, warnings, render style, and each collision finding's
+`groupIndex`, `color`, and `hex`. Exact interior pixels can be matched against
 `manifest.channels.collisions.collisions[].color`; antialiased edges may blend
 with the ghosted source geometry. If `--focus PartA,PartB` is used, everything
 except those objects is hidden, `PartA` and `PartB` are ghosted, and their

package/dist-skill/docs-dev/generated/curves.md

@@ -9,7 +9,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
 - [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
 - [NurbsCurve3D](#nurbscurve3d)
@@ -52,6 +52,87 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ### Curves & Surfacing
 
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
+
+`LoftStation`: `{ profile: Sketch, position: number }`
+
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+
+```ts
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+```
+
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+```
+
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+
 #### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
 The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
@@ -140,10 +221,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 #### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
 Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
@@ -821,6 +898,21 @@ path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
 mirror(axis: "x" | "y" | [ number, number ]): this
 ```
 
+#### `toPolyline()` — Return the open path as a sampled 2D polyline.
+
+This is for construction geometry such as guide rails, measured centerlines, and curve-driven helpers where the authored path should stay open instead of becoming a filled sketch or stroked profile.
+
+```ts
+const rail = path()
+  .moveTo(24, 0)
+  .bezierTo(32, 44, 28, 92, 18, 120)
+  .toPolyline();
+```
+
+```ts
+toPolyline(): [ number, number ][]
+```
+
 #### `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
 
 ```ts

package/dist-skill/docs-dev/generated/sketch.md

@@ -1457,7 +1457,15 @@ detectArrangement(): Sketch[]
 #### `detectArrangementRegion()` — Select the single arrangement region that contains the given seed point. Throws if no region contains the seed.
 
 ```ts
-detectArrangementRegion(seed: [ number, number ]): Sketch
+detectArrangementRegion(_seed: [ number, number ]): Sketch
+```
+
+#### `toPolyline()` — Return the solved constrained path as a sampled 2D polyline.
+
+Use this when a construction rail was authored with `constrainedSketch()` and should feed another operation such as `Loft.pathOnXz(...)`. The sketch must contain exactly one profile path.
+
+```ts
+toPolyline(samples?: number): [ number, number ][]
 ```
 
 #### `withUpdatedConstraint()` — Re-solve the sketch after changing the value of one existing constraint.

package/dist-skill/docs-dev/guides/inspection-bundles.md

@@ -190,9 +190,15 @@ root = largest component by body count, object count, then bbox volume
 rootDistance = shortest accumulated gap distance from root component
 ```
 
+For large scenes the manifest does not materialize the complete component gap
+graph, because that graph is quadratic in the number of components. The
+`gapEdgeCount` field reports the logical complete-graph edge count used by the
+analysis. `gapEdges` stores a compact evidence subset containing nearest-gap
+and root-parent edges.
+
 The PNG colors components from green at the root/near distances through yellow to
 red at the farthest rooted component. The manifest stores the root component,
-maximum rooted distance, complete component gap edge list, nearest-gap data, and
+maximum rooted distance, compact gap edge evidence, nearest-gap data, and
 shortest-path parent fields. The current v1 metric is bbox-based: it measures air
 gaps between component bounding boxes, not exact closest mesh-surface distance.
 
@@ -209,8 +215,8 @@ collision = boolean intersection volume > 0.1mm^3
 ```
 
 The manifest stores the inspected objects, collision pair names/ids, overlap
-volume, warnings, render style, and each collision finding's `groupIndex`,
-`color`, and `hex`. Exact interior pixels can be matched against
+volume, broadphase counters, warnings, render style, and each collision finding's
+`groupIndex`, `color`, and `hex`. Exact interior pixels can be matched against
 `manifest.channels.collisions.collisions[].color`; antialiased edges may blend
 with the ghosted source geometry. If `--focus PartA,PartB` is used, everything
 except those objects is hidden, `PartA` and `PartB` are ghosted, and their

package/examples/api/guided-loft-olive-oil-bottle.forge.js

@@ -0,0 +1,135 @@
+/**
+ * Guided loft vs ProductSkin: olive oil bottle.
+ *
+ * Left: the new namespaced Loft.withGuideRails(...) primitive. Right: the
+ * equivalent Product.skin(...) authoring style for comparison.
+ */
+
+Product.scenePreset('product');
+
+viewConfig({
+  camera: { position: [190, -250, 150], target: [8, 0, 88], fov: 34 },
+});
+
+const darkOlive = {
+  color: '#34462f',
+  material: {
+    opacity: 0.58,
+    roughness: 0.14,
+    metalness: 0,
+    clearcoat: 1,
+    clearcoatRoughness: 0.04,
+    transmission: 0.28,
+    thickness: 4,
+  },
+};
+const labelStock = Product.materials.mattePlastic('#eee8d8');
+const blackCap = Product.materials.softRubber({ color: '#171a15' });
+
+const guidedStations = [
+  Loft.station(roundedRect(52, 34, 8), 0),
+  Loft.station(roundedRect(60, 38, 11), 78),
+  Loft.station(roundedRect(42, 27, 10), 128),
+  Loft.station(circle2d(12, 64), 166),
+  Loft.station(circle2d(14, 64), 184),
+];
+
+const leftSilhouette = path()
+  .moveTo(-26, 0)
+  .bezierTo(-31, 30, -33, 55, -31, 72)
+  .bezierTo(-30, 90, -27, 107, -25, 118)
+  .bezierTo(-20, 142, -12, 152, -12, 166)
+  .lineTo(-14, 184);
+
+const rightSilhouette = path()
+  .moveTo(26, 0)
+  .bezierTo(31, 30, 33, 55, 31, 72)
+  .bezierTo(30, 90, 27, 107, 25, 118)
+  .bezierTo(20, 142, 12, 152, 12, 166)
+  .lineTo(14, 184);
+
+const backCrown = path()
+  .moveTo(-17, 0)
+  .bezierTo(-21, 30, -22, 56, -20, 72)
+  .bezierTo(-19, 92, -17, 108, -16, 118)
+  .bezierTo(-13, 142, -10, 154, -10, 166)
+  .lineTo(-12, 184);
+
+const frontCrown = path()
+  .moveTo(17, 0)
+  .bezierTo(22, 30, 24, 56, 22, 72)
+  .bezierTo(21, 92, 19, 108, 18, 118)
+  .bezierTo(14, 142, 10, 154, 10, 166)
+  .lineTo(12, 184);
+
+const leftRail = Loft.pathOnXz(leftSilhouette);
+const rightRail = Loft.pathOnXz(rightSilhouette);
+const backRail = Loft.pathOnYz(backCrown);
+const frontRail = Loft.pathOnYz(frontCrown);
+
+const guidedBottle = Loft.withGuideRails(
+  guidedStations,
+  [
+    Loft.leftRail(leftRail),
+    Loft.rightRail(rightRail),
+    Loft.backRail(backRail),
+    Loft.frontRail(frontRail),
+  ],
+  { samples: 19, edgeLength: 1.3 },
+)
+  .as('guided-loft-olive-glass')
+  .material(darkOlive.material)
+  .color(darkOlive.color);
+
+const guidedLabel = Product.applyMaterial(
+  roundedRect(34, 58, 4)
+    .extrude(0.8)
+    .rotateX(90)
+    .translate(0, 22.5, 76)
+    .as('guided-loft-cream-label'),
+  labelStock,
+);
+
+const guidedCap = Product.applyMaterial(cylinder(18, 12, 12, 64).translate(0, 0, 184).as('guided-loft-black-cap'), blackCap);
+
+const guided = group(
+  { name: 'body', shape: guidedBottle },
+  { name: 'label', shape: guidedLabel },
+  { name: 'cap', shape: guidedCap },
+).translate(-52, 0, 0);
+
+const productBottle = Product.skin('product-skin-olive-glass')
+  .axis('Z')
+  .stations([
+    Product.station('base').z(0).roundedRect(52, 34, 8),
+    Product.station('body').z(78).roundedRect(60, 38, 11),
+    Product.station('shoulder').z(128).roundedRect(42, 27, 10),
+    Product.station('neck').z(166).circle(24),
+    Product.station('lip').z(184).circle(28),
+  ])
+  .rails({
+    leftSilhouette: Product.rail.polyline(leftRail),
+    frontCrown: Product.rail.polyline(frontRail),
+  })
+  .material(darkOlive)
+  .edgeLength(1.3)
+  .build();
+
+const productLabel = Product.applyMaterial(
+  roundedRect(34, 58, 4)
+    .extrude(0.8)
+    .rotateX(90)
+    .translate(0, 22.5, 76)
+    .as('product-skin-cream-label'),
+  labelStock,
+);
+
+const productCap = Product.applyMaterial(cylinder(18, 12, 12, 64).translate(0, 0, 184).as('product-skin-black-cap'), blackCap);
+
+const productSkinComparison = group(
+  { name: 'body', shape: productBottle.toShape() },
+  { name: 'label', shape: productLabel },
+  { name: 'cap', shape: productCap },
+).translate(52, 0, 0);
+
+return [guided, productSkinComparison];