partforge 0.118.0 → 0.119.0

package/docs/AUTHORING-PARTS.md

@@ -1534,20 +1534,32 @@ its coordinates, and the max that would work — rather than silently clamping:
 |---|---|
 | `filletProfile(input, r, opts?)` | `r`: number, or an array matched positionally with `opts.corners.indices` |
 | `chamferProfile(input, dist, opts?)` | symmetric setback, straight connector |
-| `profileCorners(input)` | `[{index, point, interiorAngleDeg, convex, segTypes}]` |
+| `profileCorners(input)` | `[{index, position, point, interiorAngleDeg, convex, segTypes}]` — `position` is the entry's place in this list, `index` the joint's vertex number within its contour |
 
 `opts.corners` selects which corners an op touches (default `"all"`):
 
 - `"all"` · `"convex"` · `"concave"`
-- `{indices: [...]}` — positions into `profileCorners(input)`'s own return order; pair
-  with an array `r`/`dist` for per-corner radii (the `roundedProfile` pattern)
-- `{near: [x,y], count?: 1}` — nearest-corner selection; the hook for a human pick or
-  an agent resolving "the top-left corner" from bbox reasoning
+- `{indices: [...]}` — each corner's **`position`** in `profileCorners(input)`'s return
+  list, never its `index`; pair with an array `r`/`dist` for per-corner radii (the
+  `roundedProfile` pattern). Any entry out of range throws, naming the range.
+- `{near: [x,y], count?: 1, within?: mm}` — nearest-corner selection; the hook for a
+  human pick or an agent resolving "the top-left corner" from bbox reasoning. **Without
+  `within` the nearest corner is always selected, however far away** — `count: 4`
+  applied around a small pocket rounds the four corners nearest it, which may all
+  belong to the outer wall. Pass `within` when the pick must be local; a `near` with
+  nothing inside `within` throws instead of reaching further.
+
+**`index` and `position` are different numbers.** `index` is the vertex number within
+the contour; `position` is the corner's place in the returned list. They agree only
+while every joint is a corner — the moment a contour has a smooth joint (a collinear
+midpoint, a G1 arc-to-line join, a fillet already applied) the vertex numbers skip
+ahead of the positions, and `.map((c) => c.index)` fed to `{indices}` fillets the
+wrong corners or throws out of range. Always map to `c.position`.
 
 ```js
 // Fillet only the two corners nearest the profile's top edge, 3mm and 1.5mm:
 const corners = profileCorners(outline);
-const top = corners.filter((c) => c.point[1] > 20).map((c) => c.index);
+const top = corners.filter((c) => c.point[1] > 20).map((c) => c.position);   // position, NOT index
 const rounded = filletProfile(outline, [3, 1.5], { corners: { indices: top } });
 
 // Fillet every convex corner of a Shape2D by the same amount:

package/docs/KERNEL-CONTRACT.md

@@ -614,9 +614,9 @@ backwards for the holes (see the migration note below).
 | `simple()` | `toRegions()` unwrapped — throws unless the result is exactly one region. |
 | `regions()` | Scission: each disjoint region as its own live `Shape2D[]` (each further boolean-able), vs `toRegions()` which returns raw `{outer, holes}` data. Goes through `toRegions()`, so the pieces are tessellated at the backend's LOD — curves do not survive scission. |
 | `translate([dx,dy])` / `rotate(deg, center?)` / `scale(f\|[sx,sy], center?)` / `mirror(axis)` | Rigid/similarity transforms on the contours (curve-preserving). `center` defaults to the origin; `axis` is `"x"`, `"y"`, or `{point, dir}`. `scale`'s factor is uniform when a bare number, per-axis when `[sx,sy]`. |
-| `fillet(r, {corners?})` / `chamfer(d, {corners?})` | Round (true arcs) or bevel (straight chords) selected corners. `corners` = `"all"` (default) / `"convex"` / `"concave"` / `{indices}` / `{near, count?}`; `r`/`d` may be an array paired positionally with `{indices}`. Throws when no corner matches. |
+| `fillet(r, {corners?})` / `chamfer(d, {corners?})` | Round (true arcs) or bevel (straight chords) selected corners. `corners` = `"all"` (default) / `"convex"` / `"concave"` / `{indices}` / `{near, count?, within?}`; `r`/`d` may be an array paired positionally with `{indices}`. `{indices}` entries are each corner's `position` in `corners()` and any entry out of range throws (never silently dropped). `{near}` takes the `count` (default 1) nearest corners; without `within` (mm) the nearest is always selected however far away, with it a pick that finds nothing inside the radius throws. Throws when no corner matches. |
 | `simplify(tolerance)` | Corner-preserving decimation/refit within `tolerance` mm — dense point rings become fewer segments (and refit arcs/cubics) without moving corners. |
-| `corners()` | The corner list — `{index, point, interiorAngleDeg, convex, segTypes}[]`. This positional order is what `fillet`/`chamfer`'s `{indices}` selects into. |
+| `corners()` | The corner list — `{index, position, point, interiorAngleDeg, convex, segTypes}[]`. `position` is the entry's place in this list and is what `fillet`/`chamfer`'s `{indices}` selects by; `index` is the joint's vertex number within its own contour (what smooth joints are skipped from), and the two diverge past any smooth joint. |
 | `contains([x,y])` | Point-in-shape test (inside an outer, not inside a hole). |
 | `isEmpty()` | `true` when the shape has no regions at all — a `cut`/`intersect` legitimately removed everything. Pure JS on the stored IR, backend-identical. See "Empty shapes" below. |
 | `extrude({h, twist?, scaleTop?})` | Sugar for `k.extrude({profile: this, …})` → `Solid`. Throws on an empty shape (see "Empty shapes"). |
@@ -766,7 +766,7 @@ being single-contour by nature, they throw on a region. The full set: `translate
 | | `mirrorProfile(input, axis)` | `axis: "x" \| "y" \| {point, dir}` |
 | Corners | `filletProfile(input, r, opts?)` | `r` may be an array paired with `{indices}` |
 | | `chamferProfile(input, dist, opts?)` | symmetric setback, straight connector |
-| | `profileCorners(input)` | `[{index, point, interiorAngleDeg, convex, segTypes}]` |
+| | `profileCorners(input)` | `[{index, position, point, interiorAngleDeg, convex, segTypes}]`; `{indices}` selects by `position` |
 | Queries | `profileLength(contour)` | mm; single contour only |
 | | `profilePointAt(contour, {t} \| {length})` | single contour only |
 | | `profileTangentAt(contour, {t} \| {length})` | unit vector; single contour only |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.118.0",
+  "version": "0.119.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/geometry/contour-ops.js

@@ -188,15 +188,23 @@ function contourCorners(contour) {
   return out;
 }
 
+// Two numbers on every corner, and they are NOT interchangeable. `index` is the joint's
+// vertex number within its own contour (what buildCornerOpRing, simplify and the lofts
+// key on); `position` is the corner's place in THIS returned list — the one
+// `{corners: {indices}}` selects by. They diverge as soon as a contour has a smooth
+// joint (a collinear midpoint, a G1 arc-line join), and on region input `index`
+// restarts per ring while `position` runs on through the flattened order.
+const withPositions = (corners) => corners.map((c, position) => ({ ...c, position }));
+
 export function profileCorners(input) {
   const { kind, regions } = liftProfile(input);
-  if (kind === "points" || kind === "contour") return contourCorners(regions[0].outer);
+  if (kind === "points" || kind === "contour") return withPositions(contourCorners(regions[0].outer));
   const out = [];
   regions.forEach((rg, regionIndex) => {
     for (const c of contourCorners(rg.outer)) out.push({ regionIndex, ring: "outer", ...c });
     rg.holes.forEach((h, hi) => { for (const c of contourCorners(h)) out.push({ regionIndex, ring: { hole: hi }, ...c }); });
   });
-  return out;
+  return withPositions(out);
 }
 
 // ── Fillet / chamfer ─────────────────────────────────────────────────────────
@@ -205,6 +213,19 @@ export function profileCorners(input) {
 // indexes this array POSITIONALLY, matching profileCorners' documented contract).
 // r/dist may be an array paired positionally with {indices}; every other selector
 // broadcasts the scalar to every match. Throws when nothing matches.
+//
+// {indices} REJECTS any entry outside 0…corners.length-1 rather than dropping it.
+// It used to filter silently, and the author who wrote `.map((c) => c.index)` —
+// a vertex number, not a position — then filleted the wrong corners with no error
+// once the out-of-range ones fell away (partforge-cloud feedback #95: ~15 applies
+// chasing an L-bend whose arcs would not come out concentric). A throw that names
+// the two fields is the coaching that ends that loop on the first attempt.
+//
+// {near} takes an optional `within` (mm). WITHOUT it the nearest `count` corners
+// are always selected, however far away — "round the four outer corners" applied per
+// compartment happily rounds the four corners nearest a small pocket that touches
+// none of them. `within` turns a far pick into the same no-match error as any
+// other empty selector.
 function resolveCornerSelector(corners, param, opts, label) {
   const sel = (opts && opts.corners) ?? "all";
   const isArrayParam = Array.isArray(param);
@@ -218,14 +239,28 @@ function resolveCornerSelector(corners, param, opts, label) {
     const perCorner = isArrayParam ? param : null;
     if (perCorner && perCorner.length !== sel.indices.length)
       throw new Error(`${label}: per-corner radius array has ${perCorner.length} entries but {indices} has ${sel.indices.length}`);
-    picked = sel.indices
-      .map((idx, j) => ({ corner: corners[idx], param: perCorner ? perCorner[j] : param }))
-      .filter((p) => p.corner);
+    const n = corners.length;
+    picked = sel.indices.map((idx, j) => {
+      if (!Number.isInteger(idx))
+        throw new Error(`${label}: {indices} entry ${idx} is not an integer — {indices} takes each corner's \`position\` from profileCorners()`);
+      if (idx < 0 || idx >= n)
+        throw new Error(
+          `${label}: {indices} entry ${idx} is out of range — profileCorners() reported ${n} corner${n === 1 ? "" : "s"} (positions 0…${Math.max(0, n - 1)}). ` +
+          "{indices} takes each corner's `position` (its place in that list), not its `index` (its vertex number within the contour)",
+        );
+      return { corner: corners[idx], param: perCorner ? perCorner[j] : param };
+    });
   } else if (sel && Array.isArray(sel.near)) {
     const [nx, ny] = sel.near;
     const count = sel.count ?? 1;
+    const within = sel.within;
+    if (within !== undefined && !(Number.isFinite(within) && within > 0))
+      throw new Error(`${label}: {near} within must be a positive number of mm (got ${within})`);
     const distSq = (c) => (c.point[0] - nx) ** 2 + (c.point[1] - ny) ** 2;
-    picked = corners.slice().sort((a, b) => distSq(a) - distSq(b)).slice(0, count).map((corner) => ({ corner, param }));
+    const candidates = within === undefined ? corners.slice() : corners.filter((c) => distSq(c) <= within * within);
+    if (candidates.length === 0)
+      throw new Error(`${label}: no corner within ${within}mm of (${nx}, ${ny}) — the nearest is ${Math.sqrt(Math.min(...corners.map(distSq))).toFixed(3)}mm away`);
+    picked = candidates.sort((a, b) => distSq(a) - distSq(b)).slice(0, count).map((corner) => ({ corner, param }));
   } else picked = [];
   if (picked.length === 0) throw new Error(`${label}: no corner matched selector ${JSON.stringify(sel)}`);
   return picked;

package/types/geometry.d.ts

@@ -175,9 +175,11 @@ export function filletProfile(input: ProfileInput, r: number | number[], opts?:
 export function chamferProfile(input: ProfileInput, dist: number | number[], opts?: { corners?: CornerSelector }): ProfileInput;
 
 /**
- * The corner list — `{index, point, interiorAngleDeg, convex, segTypes}[]`,
- * plus `{regionIndex, ring}` for region/regions input. This positional order
- * is what `filletProfile`/`chamferProfile`'s `{indices}` selects into.
+ * The corner list — `{index, position, point, interiorAngleDeg, convex,
+ * segTypes}[]`, plus `{regionIndex, ring}` for region/regions input. `position`
+ * (the entry's place in this list) is what `filletProfile`/`chamferProfile`'s
+ * `{indices}` selects by; `index` is the joint's vertex number within its
+ * contour, and the two diverge past any smooth joint.
  */
 export function profileCorners(input: ProfileInput): Corner2D[];
 

package/types/kernel.d.ts

@@ -103,8 +103,15 @@ export interface ContourRegion {
 
 /** One corner of a `Shape2D`, as `Shape2D.corners()` reports it. */
 export interface Corner2D {
-  /** Index of the joint within its own contour. */
+  /**
+   * The joint's vertex number within its own contour. NOT what `fillet`/
+   * `chamfer`'s `{ indices }` takes — that is `position`. The two diverge as
+   * soon as a contour has a smooth joint (a collinear midpoint, a G1 arc-line
+   * join), and on region input `index` restarts per ring.
+   */
   index: number;
+  /** This corner's place in the `corners()` list — what `{ indices }` selects by. */
+  position: number;
   point: Point2;
   interiorAngleDeg: number;
   convex: boolean;
@@ -121,9 +128,17 @@ export type CornerSelector =
   | "all"
   | "convex"
   | "concave"
-  /** Positional indices into `corners()`; a per-corner `r`/`d` array pairs with these. */
+  /**
+   * Each corner's `position` in `corners()` (never its `index`); a per-corner
+   * `r`/`d` array pairs with these. Any entry out of range throws.
+   */
   | { indices: number[] }
-  | { near: Point2; count?: number };
+  /**
+   * The `count` (default 1) corners nearest `near`, optionally only those
+   * `within` mm of it. Without `within` the nearest corner is always selected,
+   * however far away it is.
+   */
+  | { near: Point2; count?: number; within?: number };
 
 /** A mirror line for `Shape2D.mirror`. */
 export type MirrorAxis2 = "x" | "y" | { point: Point2; dir: Point2 };
@@ -195,7 +210,7 @@ export interface Shape2D {
   chamfer(d: number | number[], opts?: { corners?: CornerSelector }): Shape2D;
   /** Corner-preserving decimation/refit within `tolerance` mm. */
   simplify(tolerance: number): Shape2D;
-  /** The corner list — the positional order `fillet`/`chamfer`'s `{ indices }` selects into. */
+  /** The corner list; each entry's `position` is what `fillet`/`chamfer`'s `{ indices }` selects by. */
   corners(): Corner2D[];
   /** Is `[x, y]` inside the shape (inside an outer, not inside a hole)? */
   contains(p: Point2): boolean;