partforge 0.55.0 → 0.56.0

package/src/framework/lint/rules-build.js

@@ -28,7 +28,7 @@ export const BUILD_RULES = [
   {
     id: "unknown-solid-op",
     run: ({ probe }) => unique(probe().issues
-      .filter((i) => i.kind === "unknown-op" && i.scope === "solid").map((i) => i.op))
+      .filter((i) => i.kind === "unknown-op" && i.scope !== "kernel").map((i) => i.op))
       .map((op) => err("unknown-solid-op", `\`.${op}(…)\` is not a Solid or Shape2D method`,
         `Remove the call or correct the name — see the Solid and Shape2D method tables in docs/AUTHORING-PARTS.md.`,
         "parts")),
@@ -52,7 +52,10 @@ export const BUILD_RULES = [
     id: "manifold-backend-uses-occt-op",
     run: ({ part, probe }) => {
       if (part?.meta?.backend !== "manifold") return [];
-      return [...probe().used].filter((op) => OCCT_ONLY.has(op))
+      // solidUsed, not used: `Shape2D.fillet`/`.chamfer` are backend-identical pure
+      // JS and are fine under a pinned Manifold backend; only Solid-handle uses of
+      // these names are CAD-only.
+      return [...probe().solidUsed].filter((op) => OCCT_ONLY.has(op))
         .map((op) => err("manifold-backend-uses-occt-op",
           `\`meta.backend\` pins Manifold, but the build calls \`${op}\`, which only OCCT implements`,
           `Remove \`meta.backend: "manifold"\` and let the probe route this part to OCCT, or replace \`${op}\` with a mesh-friendly construction — as written the build throws KernelCapabilityError.`,

package/src/gasket-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/gasket.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/parts/gasket.js

@@ -0,0 +1,111 @@
+// Reference part for the 2-D editing surface (docs/AUTHORING-PARTS.md "Editing
+// profiles"): a gasket plate whose outline is a curve-native `pathProfile` (one cubic
+// bulge edge), with two bolt bosses unioned onto the bottom edge — their circular tabs
+// centered exactly ON that edge, the coincident-edge boolean case paper.js has known
+// rough edges around (see the design doc's "two carve-outs"). The corners are then
+// rounded with `.fillet(…, { corners: "convex" })`, the bolt holes cut, an optional
+// print-clearance offset applied, and the whole profile extruded.
+//
+// No `meta.backend` override needed: the probe tracks which handle kind an op ran
+// on, so this build's `Shape2D.fillet` (backend-identical pure JS — KERNEL-CONTRACT.md
+// "One shared implementation") does not read as a CAD-only op, and the part
+// auto-routes to fast Manifold like any other non-B-rep part.
+import { pathProfile, circleProfile } from "partforge/geometry";
+
+// Pure dimension math shared with test/gasket-part.test.js, which re-derives the same
+// 2-D profile with the free contour-ops/paper-bridge functions (no kernel) to check
+// validateProfile/profileCorners/toContours-shaped output independent of the build.
+// Exported alongside the default PartDefinition — still DOM-free and side-effect-free.
+export function gasketGeometry(p) {
+  const w2 = p.w / 2;
+  const dep = p.w * 0.6;          // plate depth (top edge sits at y = dep)
+  const bulge = p.w * 0.18;       // how far the top edge's cubic bulges outward
+  const tabR = p.boltR + 1.5;     // boss radius — enough wall around the hole
+  const tabX = p.w * 0.25;        // boss centers, symmetric about x = 0
+  const tabSegs = 12;             // low-poly boss facets — a fillet needs a chord it can fit inside
+  // Deterministic backoff (AUTHORING-PARTS "Editing profiles" — fillet throws rather
+  // than clamping) so cornerR never overruns a boss's own facets or the margins/gap
+  // between the outline and a boss, at any width/bolt-radius in the sliders' range.
+  // The 0.5 factor covers `fillet`'s "soft cap" halving an edge's share whenever BOTH
+  // its neighboring corners are selected too — true here, since `corners: "convex"`
+  // selects every convex corner at once, including each boss's own facet corners.
+  const marginX = w2 - tabX - tabR;   // material outboard of each boss
+  const gapX = tabX - tabR;           // half the gap between the two bosses
+  const filletR = Math.max(0, Math.min(p.cornerR, (marginX - 0.3) / 2, (gapX - 0.3) / 2, dep * 0.2, tabR * 0.4));
+  return { w2, dep, bulge, tabR, tabX, tabSegs, filletR };
+}
+
+export default {
+  meta: { title: "Gasket", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "gasket",
+      title: "Gasket",
+      description: "A curvy gasket plate with two bolt bosses. Demonstrates `pathProfile`, `Shape2D.union`/`.fillet`/`.cut`/`.offset`, and a coincident-edge boolean (the bosses straddle the outline's bottom edge).",
+      controls: [
+        { key: "w", label: "Width", unit: "mm", min: 24, max: 80, step: 1,
+          description: "Overall plate width. The plate's depth, bulge, and boss spacing all scale from this one dimension." },
+        { key: "h", label: "Thickness", unit: "mm", min: 1, max: 8, step: 0.5,
+          description: "Plate thickness (the extrusion height)." },
+        { key: "boltR", label: "Bolt hole radius", unit: "mm", min: 1, max: 2.5, step: 0.1,
+          description: "Radius of each mounting hole, cut through the boss at the end." },
+        { key: "cornerR", label: "Corner radius", unit: "mm", min: 0, max: 4, step: 0.25,
+          description: "Fillet applied to every convex corner (`Shape2D.fillet`). Automatically backed off if the plate/bosses are too small to fit it — see the build's `filletR` clamp." },
+        { key: "clearance", label: "Print-clearance offset", unit: "mm", min: 0, max: 1, step: 0.1,
+          description: "Grows the whole outline outward (round corners) for a looser slip fit. 0 = none." },
+      ],
+    },
+  ],
+  defaults: { w: 44, h: 3, boltR: 1.6, cornerR: 2, clearance: 0 },
+  parts: {
+    gasket: {
+      label: "Gasket",
+      views: ["gasket"],
+      export: { name: "gasket" },
+      build: (k, p) => {
+        const { w2, dep, bulge, tabR, tabX, tabSegs, filletR } = gasketGeometry(p);
+
+        // Curve-native outline: straight sides and bottom, one cubic bulge across the
+        // top. `close()` leaves the bottom-left→start edge implicit; contour-ops
+        // re-closes it explicitly wherever that matters (corner/fillet math).
+        const outline = pathProfile([-w2, 0])
+          .lineTo([w2, 0])
+          .lineTo([w2, dep])
+          .cubicTo([-w2, dep], [w2 * 0.5, dep + bulge], [-w2 * 0.5, dep + bulge])
+          .close();
+
+        // Boss centers sit exactly ON the bottom edge (y = 0) — the coincident-edge
+        // union case: each tab straddles the existing straight edge rather than
+        // merely touching it at a point.
+        const tabs = [[-tabX, 0], [tabX, 0]].map(([cx, cy]) => circleProfile(tabR, [cx, cy], tabSegs));
+
+        // Fillet the outer convex corners, THEN cut the bolt holes. Note this ordering
+        // trades away the STEP-CIRCLE fidelity the "fillet after booleans" rule buys
+        // (AUTHORING-PARTS.md "Editing profiles"): the hole cuts are themselves paper.js
+        // booleans, so they degrade the fillet's true `{to,via}` arcs back to cubic
+        // approximations before export. That's fine here — the fillet still reads as a
+        // rounded corner (curve-exact until the cut, faceted-cubic after) — but a part
+        // that needs an exact STEP CIRCLE on a filleted corner should cut first and
+        // fillet last instead.
+        let plate = k.shape2d(outline).union(tabs[0]).union(tabs[1]);
+        if (filletR > 0) plate = plate.fillet(filletR, { corners: "convex" });
+        plate = plate.cut(circleProfile(p.boltR, [-tabX, 0])).cut(circleProfile(p.boltR, [tabX, 0]));
+        if (p.clearance) plate = plate.offset(p.clearance);
+
+        return plate.extrude({ h: p.h });
+      },
+    },
+  },
+  views: { gasket: { label: "Gasket" } },
+  // Now that Shape2D.fillet no longer routes the part to OCCT, this builds on
+  // Manifold and can gate `holes` directly (Manifold-only topology —
+  // ERROR-PATTERNS.md#occt-holes-watertight-na); test/gasket-part.test.js's
+  // genus() === 2 check pins the same fact against a directly-booted kernel.
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      gasket: { bbox: "<=[60,50,6]", holes: 2 },
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/types/geometry.d.ts

@@ -3,9 +3,29 @@
 // DOM-free and kernel-free: this is the entry a part's build functions import
 // (importing "partforge" inside a worker throws `document is not defined`).
 
-import type { ArcContour, Point2, Point3, PointsContour, Region2D, Solid } from "./kernel.js";
+import type {
+  ArcContour,
+  Contour,
+  Corner2D,
+  CornerSelector,
+  MirrorAxis2,
+  Point2,
+  Point3,
+  PointsContour,
+  Region2D,
+  Solid,
+} from "./kernel.js";
+
+export type { ArcContour, Contour, Corner2D, CornerSelector, MirrorAxis2, Point2, Point3, PointsContour, Region2D, Solid };
 
-export type { ArcContour, Point2, Point3, PointsContour, Region2D, Solid };
+/**
+ * Anything the 2-D editing ops below accept: a plain point list, a curve-native
+ * contour, a `{outer, holes}` region, or a region array. Every op returns the
+ * same shape of input it was given (a bare point list stays a point list, unless
+ * the op introduces curves — e.g. a non-uniform `scaleProfile` on an arc — in
+ * which case it upgrades to a `Contour`).
+ */
+export type ProfileInput = number[][] | Contour | Region2D | Region2D[];
 
 /** A pie/sector wedge with its tip at the origin. */
 export function piePolygon(tipR: number, arcDeg: number, segs?: number): PointsContour;
@@ -115,3 +135,102 @@ export function circularPattern(
     rotateCopies?: boolean;
   },
 ): Solid[];
+
+// ── 2-D editing ops ──────────────────────────────────────────────────────────
+// Polymorphic input contract: every op below accepts a point list, a curve-native
+// contour, a region, or a region array, and returns the same shape of input it
+// was given — except the arc-length queries (profileLength/profilePointAt/
+// profileTangentAt), which are single-contour by nature and throw on a region.
+
+/** Translate every contour by `[dx, dy]`. Exact on all segment types. */
+export function translateProfile(input: ProfileInput, delta: Point2): ProfileInput;
+
+/** Rotate `deg` degrees about `center` (default the origin). Arcs stay arcs. */
+export function rotateProfile(input: ProfileInput, deg: number, center?: Point2): ProfileInput;
+
+/**
+ * Scale by a uniform or per-axis factor about `center` (default the origin).
+ * A non-uniform `[sx, sy]` converts `{to, via}` arcs to cubics (an ellipse is
+ * not a circular arc). Scale factors must be finite and non-zero.
+ */
+export function scaleProfile(input: ProfileInput, s: number | Point2, center?: Point2): ProfileInput;
+
+/** Reflect across `"x"`, `"y"`, or an arbitrary `{point, dir}` line. */
+export function mirrorProfile(input: ProfileInput, axis: MirrorAxis2): ProfileInput;
+
+/**
+ * Round selected corners with true arcs. `r` may be an array paired
+ * positionally with `{indices}`. Throws if no corner matches, or if `r`
+ * does not fit against its neighboring segments.
+ */
+export function filletProfile(input: ProfileInput, r: number | number[], opts?: { corners?: CornerSelector }): ProfileInput;
+
+/**
+ * Bevel selected corners with a straight chord (symmetric setback). `dist`
+ * may be an array paired positionally with `{indices}`. Throws if no corner
+ * matches, or if `dist` does not fit against its neighboring segments.
+ */
+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.
+ */
+export function profileCorners(input: ProfileInput): Corner2D[];
+
+/** Total arc length of a single contour, in mm. */
+export function profileLength(contour: Contour): number;
+
+/** The point at normalized position `t` (0..1) or absolute arc `length` along a single contour. */
+export function profilePointAt(contour: Contour, opts: { t: number } | { length: number }): Point2;
+
+/** The unit tangent at normalized position `t` (0..1) or absolute arc `length` along a single contour. */
+export function profileTangentAt(contour: Contour, opts: { t: number } | { length: number }): Point2;
+
+/**
+ * The closest point on `input` to `[x, y]` — the pick-resolution primitive.
+ * Accepts regions (unlike the arc-length queries above); `contourIndex`/
+ * `segmentIndex` follow the same flattened outer-then-holes-per-region order
+ * `validateProfile` uses. `t` is normalized 0..1, but for a `{to, via}` arc
+ * segment (expanded internally into ≤90° cubic pieces that share one
+ * `segmentIndex`) it is local to whichever piece the nearest point landed
+ * on, not a position along the arc's full sweep.
+ */
+export function profileNearestPoint(
+  input: ProfileInput,
+  p: Point2,
+): { point: Point2; distance: number; contourIndex: number; segmentIndex: number; t: number };
+
+/** Curve-exact axis-aligned bounds across every contour in `input`. */
+export function profileBounds(input: ProfileInput): { min: Point2; max: Point2 };
+
+/** Net curve-exact area (Σ|outers| − Σ|holes|), mm². */
+export function profileArea(input: ProfileInput): number;
+
+/** Curve-aware point-in-shape test (inside an outer, not inside a hole). */
+export function profileContains(input: ProfileInput, p: Point2): boolean;
+
+/**
+ * Corner-preserving decimation/refit within `tolerance` mm: splits at corners,
+ * then reduces or refits each run independently, reassembling with corner
+ * points bit-exact preserved. A run that gains curves upgrades a point-list
+ * input to a `Contour`.
+ */
+export function simplifyProfile(input: ProfileInput, tolerance: number): ProfileInput;
+
+/** One issue `validateProfile` reports. Never thrown — only returned. */
+export interface ProfileIssue {
+  type: "degenerate" | "self-intersection" | "winding" | "nesting";
+  contourIndex: number;
+  segmentIndex?: number;
+  point?: Point2;
+  message: string;
+}
+
+/**
+ * Geometric sanity checks (degenerate segments/area, self-intersection,
+ * winding, nesting) against `input`'s sampled approximation. Never throws on
+ * geometric badness — only an unrecognized `input` shape throws.
+ */
+export function validateProfile(input: ProfileInput): { ok: boolean; issues: ProfileIssue[] };

package/types/kernel.d.ts

@@ -95,6 +95,39 @@ export type AxisName = "X" | "Y" | "Z";
 /** Convex-corner style for an offset. */
 export type OffsetCorners = "round" | "chamfer" | "sharp";
 
+/** A stored contour-IR region: curve-native contours, nothing flattened. */
+export interface ContourRegion {
+  outer: ArcContour;
+  holes: ArcContour[];
+}
+
+/** One corner of a `Shape2D`, as `Shape2D.corners()` reports it. */
+export interface Corner2D {
+  /** Index of the joint within its own contour. */
+  index: number;
+  point: Point2;
+  interiorAngleDeg: number;
+  convex: boolean;
+  /** Segment kinds meeting here, incoming then outgoing. */
+  segTypes: Array<"line" | "arc" | "cubic">;
+  /** Present only for multi-region shapes. */
+  regionIndex?: number;
+  /** Present only for multi-region shapes. */
+  ring?: "outer" | { hole: number };
+}
+
+/** Which corners a `Shape2D` `fillet`/`chamfer` applies to. Default `"all"`. */
+export type CornerSelector =
+  | "all"
+  | "convex"
+  | "concave"
+  /** Positional indices into `corners()`; a per-corner `r`/`d` array pairs with these. */
+  | { indices: number[] }
+  | { near: Point2; count?: number };
+
+/** A mirror line for `Shape2D.mirror`. */
+export type MirrorAxis2 = "x" | "y" | { point: Point2; dir: Point2 };
+
 // --- edge / face selectors (OCCT-only ops) ---------------------------------
 
 /**
@@ -115,8 +148,13 @@ export type FaceSelector = EdgeSelector;
 // --- Shape2D ----------------------------------------------------------------
 
 /**
- * An opaque 2-D boolean value (Manifold wraps a CrossSection, OCCT a replicad
- * Drawing). `_`-prefixed keys are backend internals and are not declared.
+ * A 2-D sketch value: booleans, transforms, corner ops and queries. ONE shared
+ * implementation on both backends — storage is the curve-native contour IR, so
+ * arcs and béziers survive every op and results are backend-identical except
+ * `offset`. No backend geometry exists until the shape is extruded/revolved or
+ * materialized via `toRegions()`. `_`-prefixed keys are internals, not declared.
+ *
+ * Every op returns a NEW `Shape2D`; no operand is ever mutated.
  */
 export interface Shape2D {
   union(other: Shape2D | Contour): Shape2D;
@@ -125,20 +163,42 @@ export interface Shape2D {
   cutAll(others: Array<Shape2D | Contour>): Shape2D;
   intersect(other: Shape2D | Contour): Shape2D;
   /**
-   * Grow (`delta > 0`) or inset (`delta < 0`). Curve-preserving on OCCT,
-   * faceted at mesh LOD on Manifold. Throws if the offset collapses the shape.
+   * Grow (`delta > 0`) or inset (`delta < 0`). The one backend-specific op:
+   * curve-preserving on OCCT, faceted at mesh LOD on Manifold. Throws if the
+   * offset collapses the shape.
    */
   offset(delta: number, opts?: { corners?: OffsetCorners; segs?: number }): Shape2D;
-  /** Net area (outers minus holes), mm². */
+  /** Net area (outers minus holes), mm². Curve-exact — not measured off a tessellation. */
   area(): number;
+  /** Axis-aligned 2-D bounds, curve-exact. */
   boundingBox(): BoundingBox2;
-  /** Materialize into region arrays. */
+  /** Materialize into point-ring region arrays, tessellating curves at the backend's LOD. */
   toRegions(): MaterializedRegion[];
+  /** The stored contour IR — curve-native and lossless. A deep copy, safe to mutate. */
+  toContours(): ContourRegion[];
   /** `toRegions()` unwrapped — throws unless there is exactly one region. */
   simple(): MaterializedRegion;
   /** Scission: each disjoint region as its own live `Shape2D`. */
   regions(): Shape2D[];
   clone(): Shape2D;
+  /** Translate by `[dx, dy]`. */
+  translate(v: Point2): Shape2D;
+  /** Rotate `deg` about `center` (default the origin). */
+  rotate(deg: number, center?: Point2): Shape2D;
+  /** Scale about `center` (default the origin). A single `number` scales uniformly; `[sx, sy]` scales each axis independently. */
+  scale(factor: number | [number, number], center?: Point2): Shape2D;
+  /** Reflect across an axis line. */
+  mirror(axis: MirrorAxis2): Shape2D;
+  /** Round selected corners with true arcs. `r` may be an array paired with `{ indices }`. */
+  fillet(r: number | number[], opts?: { corners?: CornerSelector }): Shape2D;
+  /** Bevel selected corners with straight chords. `d` may be an array paired with `{ indices }`. */
+  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. */
+  corners(): Corner2D[];
+  /** Is `[x, y]` inside the shape (inside an outer, not inside a hole)? */
+  contains(p: Point2): boolean;
   /** Sugar for `k.extrude({ profile: this, ... })`. */
   extrude(opts: { h: number; twist?: number; scaleTop?: number }): Solid;
   /** Sugar for `k.revolve({ profile: this, ... })`. */