partforge 0.117.1 → 0.119.0

package/docs/AUTHORING-PARTS.md

@@ -1060,12 +1060,41 @@ export function tilePicker(host) {
    listener you attach yourself with `addEventListener`, rather than through `host.h`,
    is **not** guarded — wire listeners through `host.h`, or wrap your own in try/catch.
 
-**Looking native.** The slot inherits the rail's font, colours and light/dark theme.
-Bare `<button>`, `<input>` and `<select>` elements pick up the built-in looks
-automatically; the built-in classes are available by name for the exact thing:
+**Looking native.** The slot inherits the rail's font and text colour, and the
+built-in looks come for free: bare `<button>`, `<input>` and `<select>` elements
+are already styled, the built-in classes are there by name for the exact thing —
 `row`, `seg` (a segmented row of buttons), `action`, `ghost`, `num`, `text-input`,
-`select-input`; and for SVG, `pf-hit` (clickable, with a `selected` state) and
-`pf-drag`. Sub-controls mounted through `host.controls` *are* the built-in widgets.
+`select-input` — and sub-controls mounted through `host.controls` *are* the
+built-in widgets. For SVG there are two classes: `pf-hit` (a clickable region,
+with a `selected` state) and `pf-drag`.
+
+**Colour only with the rail's tokens.** Inheriting the rail's colours covers the
+text you did not style; it does not cover anything you colour yourself. For that,
+use a `--pf-*` custom property and never a hex literal or a named colour — the
+tokens flip with the light/dark theme and a literal cannot, so a `#333` border is
+a widget that is unreadable in one of the two themes. The ones worth knowing:
+`var(--pf-text)` and `var(--pf-text-2)` for text, `var(--pf-muted)` for a
+secondary label, `var(--pf-border)` for a rule or an outline,
+`var(--pf-surface-2)` for a filled chip, `var(--pf-accent)` with
+`var(--pf-on-accent)` for the selected or primary thing, and `var(--pf-err)` for
+a problem. That palette is the whole palette: the accent blue for the one thing
+that is chosen or primary, the surface and border greys for everything else. A
+widget that reaches past it for a red or a green is a widget that has stopped
+looking like the rest of the panel.
+
+**Nest a region's label inside the region.** The common case then needs no colour
+from you at all: an SVG shape you leave unfilled inherits `var(--pf-text-2)`
+rather than SVG's own black, a `pf-hit` region is filled and outlined at rest,
+and a `<text>` *inside* that region stays readable through all three states —
+the rail gives it `var(--pf-text-2)` at rest and `var(--pf-on-accent)` once the
+region is selected and has gone solid accent underneath it, and clears the
+stroke it would otherwise inherit from the region's outline (SVG paints that
+around every glyph, which at label sizes leaves a pale ghost of the number).
+Draw the label as a sibling instead and none of that reaches it: a dark number
+sitting on the selected blue is the result, and you have to colour it yourself.
+To colour a
+region from your own data, set an inline `style` — a `fill="…"` attribute loses
+to the rail's rule.
 
 **Reading the part's own files.** Artwork can live beside the code (the tree is text,
 so an SVG, a `partforge-vector` JSON document or a JSON data file — not a PNG).
@@ -1505,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.117.1",
+  "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/app.css

@@ -387,10 +387,10 @@ button.action:disabled { opacity: .5; cursor: default; }
 /* Custom controls (type: "custom"): a part-authored widget in the rail. The
    slot inherits the rail's cascade (font, colours, --pf-* tokens); these rules
    give BARE elements the built-in controls' look so a widget written with
-   plain <button>/<input>/<select> still reads as native, and provide two
-   opt-in classes for SVG: .pf-hit (a clickable region) and .pf-drag (a
-   dragged one — touch-action: none is what lets a finger drag it on a phone
-   instead of scrolling the sheet). */
+   plain <button>/<input>/<select> still reads as native, supply a themed
+   floor for hand-drawn SVG, and provide two opt-in classes for SVG: .pf-hit
+   (a clickable region) and .pf-drag (a dragged one — touch-action: none is
+   what lets a finger drag it on a phone instead of scrolling the sheet). */
 .pf-custom { margin: 9px 0; }
 .pf-custom.hidden { display: none; }
 .pf-custom-slot { display: flow-root; }
@@ -400,7 +400,12 @@ button.action:disabled { opacity: .5; cursor: default; }
    like .text-input (0,1,0) or .row .num (0,2,0). At true zero specificity,
    any class rule wins, so a named built-in class (.seg button, .text-input,
    select.select-input, …) always beats these bare-element defaults. */
-:where(.pf-custom) :where(svg) { display: block; max-width: 100%; height: auto; }
+/* `fill` inherits in SVG, so this is the floor for everything the widget draws
+   and did not colour — including <text>. SVG's own initial fill is BLACK, which
+   is invisible on the dark theme, and that is what an author gets for free
+   unless the rail supplies a token. Inherited rather than matched, so a child
+   carrying its own fill="…" attribute still wins. */
+:where(.pf-custom) :where(svg) { display: block; max-width: 100%; height: auto; fill: var(--pf-text-2); }
 :where(.pf-custom) :where(button) {
   font: inherit; font-size: 12px; padding: 5px 9px; cursor: pointer;
   background: transparent; border: 1px solid var(--pf-border); color: var(--pf-text-2);
@@ -417,9 +422,29 @@ button.action:disabled { opacity: .5; cursor: default; }
   outline: none; border-color: var(--pf-accent);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
 }
-.pf-custom .pf-hit { cursor: pointer; }
+/* A region the reader clicks. The RESTING fill and stroke are what make it read
+   as a control: without them a .pf-hit polygon is a black slab with no border
+   until it is hovered or selected. Zero specificity, so a widget that colours
+   regions from its own data still wins — with an inline `style`, since a
+   `fill="…"` attribute loses to any rule that matches the element, even this
+   one. Hover and selected below keep their own (0,2,x) weight. */
+:where(.pf-custom) :where(.pf-hit) { cursor: pointer; fill: var(--pf-surface-2); stroke: var(--pf-border); }
 .pf-custom .pf-hit:hover { fill: color-mix(in oklab, var(--pf-accent) 25%, transparent); }
-.pf-custom .pf-hit.selected { fill: color-mix(in oklab, var(--pf-accent) 45%, transparent); stroke: var(--pf-accent); }
+/* Selected is the SOLID accent, not a wash of it. A translucent accent lands on a
+   different value in each theme — pale over the light background, dark over the
+   dark one — so no single label colour is readable on both. Solid accent is one
+   colour in both, which is what makes --pf-on-accent below a rule rather than a
+   guess. A widget that would rather tint its own region overrides with `style`. */
+.pf-custom .pf-hit.selected { fill: var(--pf-accent); stroke: var(--pf-accent); }
+/* A label NESTED inside the region — the structure to recommend, because it is the
+   only one where the rail can keep the text readable as the region changes colour
+   underneath it. `fill` inherits, so without these the label takes the region's OWN
+   fill: grey on grey at rest, and accent on accent once selected. `stroke` inherits
+   too, and that one is worse than it looks: the region's outline colour gets painted
+   around every glyph, which at label sizes is most of the glyph — pale ghosts of the
+   numbers at rest, blue ones when selected. Hence stroke: none, not just a fill. */
+:where(.pf-custom) :where(.pf-hit) text { fill: var(--pf-text-2); stroke: none; }
+.pf-custom .pf-hit.selected text { fill: var(--pf-on-accent); }
 .pf-custom .pf-drag { touch-action: none; }
 .pf-custom-error {
   margin: 4px 0; padding: 6px 8px; border: 1px solid var(--pf-err); border-radius: var(--pf-radius-control);

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;