@faicad/cq-compat 0.13.0

package/dist/gear-test-harness.js

@@ -0,0 +1,112 @@
+/**
+ * Shared harness for the E1–E4 gear-extension ops.
+ *
+ * These ops call the occt-wasm kernel directly via `getKernel()` (the native
+ * singleton that `registerOcctBrepEngine()` initializes) and wrap results with
+ * `fromHandle`. `fromHandle` needs `getBackends().kernel.brep` to be a MESHABLE
+ * kernel — the raw occt-wasm `OcctKernel` exposes `meshShape`, so we wire it
+ * straight into `configureBackends`. This is intentionally the SAME native
+ * instance the ops use, so handles stay consistent (no second kernel, no
+ * `createRuntime`, which only lazily builds its brep chain inside `execute`).
+ *
+ * This file is NOT a test (no `*.test.ts`); it is imported by the E1–E4 specs.
+ */
+import { registerOcctBrepEngine, configureBackends, CONTRACT_VERSION } from '@faicad/faijs';
+import { getKernel } from '@faicad/faijs/occt-kernel/occtKernel';
+import { brepOf } from '@faicad/faijs/shape';
+export { brepOf };
+/**
+ * Initialise the native occt-wasm kernel for the E1–E4 specs.
+ *
+ * Calls `registerOcctBrepEngine()` (which boots the kernel singleton and
+ * registers the OCCT engine) and then wires that SAME instance into the
+ * backend registry via `configureBackends`, so `fromHandle` can resolve a
+ * meshable kernel. Must be awaited in `beforeAll` before any op is invoked.
+ *
+ * @returns a promise that resolves once the kernel and backends are ready
+ */
+export async function setupNativeKernel() {
+    await registerOcctBrepEngine();
+    const k = getKernel();
+    configureBackends({
+        contractVersion: CONTRACT_VERSION,
+        // Mirror the OCCT engine capabilities declared in registerOcctBrepEngine so
+        // dual-ops that gate on a capability (e.g. cut → 'evolution') dispatch to
+        // brep instead of throwing E_BREP_UNSUPPORTED in the bare-kernel test path.
+        config: {
+            mode: 'brep',
+            brepEngineId: 'occt',
+            brepCapabilities: {
+                evolution: true,
+                heal: true,
+                directEdit: true,
+                advSurface: true,
+                assembly: true,
+                meshLift: true,
+            },
+        },
+        kernel: { brep: k, csg: undefined, sdf: undefined },
+        fonts: undefined,
+        texture: undefined,
+        assets: undefined,
+        events: undefined,
+    });
+}
+/**
+ * Return the shared native occt-wasm kernel singleton.
+ *
+ * The same instance the E1–E4 ops obtain internally via `getKernel()`, so
+ * fixtures built here and op outputs share one handle space.
+ *
+ * @returns the live `OcctKernel` instance (valid after {@link setupNativeKernel})
+ */
+export function kernel() {
+    return getKernel();
+}
+/**
+ * Build a minimal valid root `Workplane` without touching the `cad.*` backend.
+ *
+ * Defaults to the XY plane at the origin (normal +Z, xDir +X, yDir +Y) with no
+ * shape and no pending wires; pass `over` to override any field (e.g.
+ * `{ shape }` or `{ normal, origin }`).
+ *
+ * @param over - partial overrides merged onto the default workplane
+ * @returns a `Workplane` literal suitable as the first argument of an op
+ */
+export function mkWP(over = {}) {
+    return {
+        __cq: true,
+        plane: 'XY',
+        origin: [0, 0, 0],
+        normal: [0, 0, 1],
+        xDir: [1, 0, 0],
+        yDir: [0, 1, 0],
+        shape: null,
+        faceSel: null,
+        edgeSel: null,
+        vertexSel: null,
+        pts: [],
+        forConstruction: false,
+        ...over,
+    };
+}
+/**
+ * Compute the axis-aligned bounding box of a shape through the native kernel.
+ *
+ * @param shape - a faijs `Shape` carrying a BREP handle (see `brepOf`)
+ * @returns the six-field bounding box
+ */
+export function bbox(shape) {
+    return kernel().getBoundingBox(brepOf(shape));
+}
+/**
+ * Surface area of a face (or total area of a shell/solid), via the native
+ * kernel's `getSurfaceArea`.
+ *
+ * @param shape - a faijs `Shape` carrying a BREP handle (see `brepOf`)
+ * @returns the area in model units squared
+ */
+export function area(shape) {
+    return kernel().getSurfaceArea(brepOf(shape));
+}
+//# sourceMappingURL=gear-test-harness.js.map

package/dist/gear-test-harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gear-test-harness.js","sourceRoot":"","sources":["../src/gear-test-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAA;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,CAAA;AAKjB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,sBAAsB,EAAE,CAAA;IAC9B,MAAM,CAAC,GAAG,SAAS,EAA2B,CAAA;IAC9C,iBAAiB,CAAC;QAChB,eAAe,EAAE,gBAAgB;QACjC,4EAA4E;QAC5E,0EAA0E;QAC1E,4EAA4E;QAC5E,MAAM,EAAE;YACN,IAAI,EAAE,MAAM;YACZ,YAAY,EAAE,MAAM;YACpB,gBAAgB,EAAE;gBAChB,SAAS,EAAE,IAAI;gBACf,IAAI,EAAE,IAAI;gBACV,UAAU,EAAE,IAAI;gBAChB,UAAU,EAAE,IAAI;gBAChB,QAAQ,EAAE,IAAI;gBACd,QAAQ,EAAE,IAAI;aACf;SACF;QACD,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE;QACnD,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;KAClB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM;IACpB,OAAO,SAAS,EAA2B,CAAA;AAC7C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,IAAI,CAAC,OAA2B,EAAE;IAChD,OAAO;QACL,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACjB,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,IAAI;QACf,GAAG,EAAE,EAAE;QACP,eAAe,EAAE,KAAK;QACtB,GAAG,IAAI;KACR,CAAA;AACH,CAAC;AAiBD;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,KAAY;IAC/B,OAAO,MAAM,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAA2B,CAAS,CAAA;AACjF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAC,KAAY;IAC/B,OAAO,MAAM,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAA2B,CAAC,CAAA;AACzE,CAAC","sourcesContent":["/**\n * Shared harness for the E1–E4 gear-extension ops.\n *\n * These ops call the occt-wasm kernel directly via `getKernel()` (the native\n * singleton that `registerOcctBrepEngine()` initializes) and wrap results with\n * `fromHandle`. `fromHandle` needs `getBackends().kernel.brep` to be a MESHABLE\n * kernel — the raw occt-wasm `OcctKernel` exposes `meshShape`, so we wire it\n * straight into `configureBackends`. This is intentionally the SAME native\n * instance the ops use, so handles stay consistent (no second kernel, no\n * `createRuntime`, which only lazily builds its brep chain inside `execute`).\n *\n * This file is NOT a test (no `*.test.ts`); it is imported by the E1–E4 specs.\n */\n\nimport { registerOcctBrepEngine, configureBackends, CONTRACT_VERSION } from '@faicad/faijs'\nimport { getKernel } from '@faicad/faijs/occt-kernel/occtKernel'\nimport { brepOf } from '@faicad/faijs/shape'\nexport { brepOf }\nimport type { OcctKernel, ShapeHandle } from 'occt-wasm'\nimport type { Shape } from '@faicad/faijs/mesh/types'\nimport type { Workplane } from './workplane'\n\n/**\n * Initialise the native occt-wasm kernel for the E1–E4 specs.\n *\n * Calls `registerOcctBrepEngine()` (which boots the kernel singleton and\n * registers the OCCT engine) and then wires that SAME instance into the\n * backend registry via `configureBackends`, so `fromHandle` can resolve a\n * meshable kernel. Must be awaited in `beforeAll` before any op is invoked.\n *\n * @returns a promise that resolves once the kernel and backends are ready\n */\nexport async function setupNativeKernel(): Promise<void> {\n  await registerOcctBrepEngine()\n  const k = getKernel() as unknown as OcctKernel\n  configureBackends({\n    contractVersion: CONTRACT_VERSION,\n    // Mirror the OCCT engine capabilities declared in registerOcctBrepEngine so\n    // dual-ops that gate on a capability (e.g. cut → 'evolution') dispatch to\n    // brep instead of throwing E_BREP_UNSUPPORTED in the bare-kernel test path.\n    config: {\n      mode: 'brep',\n      brepEngineId: 'occt',\n      brepCapabilities: {\n        evolution: true,\n        heal: true,\n        directEdit: true,\n        advSurface: true,\n        assembly: true,\n        meshLift: true,\n      },\n    },\n    kernel: { brep: k, csg: undefined, sdf: undefined },\n    fonts: undefined,\n    texture: undefined,\n    assets: undefined,\n    events: undefined,\n  })\n}\n\n/**\n * Return the shared native occt-wasm kernel singleton.\n *\n * The same instance the E1–E4 ops obtain internally via `getKernel()`, so\n * fixtures built here and op outputs share one handle space.\n *\n * @returns the live `OcctKernel` instance (valid after {@link setupNativeKernel})\n */\nexport function kernel(): OcctKernel {\n  return getKernel() as unknown as OcctKernel\n}\n\n/**\n * Build a minimal valid root `Workplane` without touching the `cad.*` backend.\n *\n * Defaults to the XY plane at the origin (normal +Z, xDir +X, yDir +Y) with no\n * shape and no pending wires; pass `over` to override any field (e.g.\n * `{ shape }` or `{ normal, origin }`).\n *\n * @param over - partial overrides merged onto the default workplane\n * @returns a `Workplane` literal suitable as the first argument of an op\n */\nexport function mkWP(over: Partial<Workplane> = {}): Workplane {\n  return {\n    __cq: true,\n    plane: 'XY',\n    origin: [0, 0, 0],\n    normal: [0, 0, 1],\n    xDir: [1, 0, 0],\n    yDir: [0, 1, 0],\n    shape: null,\n    faceSel: null,\n    edgeSel: null,\n    vertexSel: null,\n    pts: [],\n    forConstruction: false,\n    ...over,\n  }\n}\n\n/**\n * Axis-aligned bounding box of a shape, in the kernel's field naming.\n *\n * Mirrors the `BoundingBox` record returned by the native\n * `getBoundingBox` call (all six min/max fields, no `minX`-style aliases).\n */\nexport type BBox = {\n  xmin: number\n  xmax: number\n  ymin: number\n  ymax: number\n  zmin: number\n  zmax: number\n}\n\n/**\n * Compute the axis-aligned bounding box of a shape through the native kernel.\n *\n * @param shape - a faijs `Shape` carrying a BREP handle (see `brepOf`)\n * @returns the six-field bounding box\n */\nexport function bbox(shape: Shape): BBox {\n  return kernel().getBoundingBox(brepOf(shape) as unknown as ShapeHandle) as BBox\n}\n\n/**\n * Surface area of a face (or total area of a shell/solid), via the native\n * kernel's `getSurfaceArea`.\n *\n * @param shape - a faijs `Shape` carrying a BREP handle (see `brepOf`)\n * @returns the area in model units squared\n */\nexport function area(shape: Shape): number {\n  return kernel().getSurfaceArea(brepOf(shape) as unknown as ShapeHandle)\n}\n"]}

package/dist/gears.d.ts

@@ -0,0 +1,226 @@
+/**
+ * gears — raw-handle primitives for the cq_gears port (E1–E6 companion layer).
+ *
+ * cq_gears' tooth faces are B-spline patches built from (u,v) point grids and
+ * assembled by sewing — these need raw kernel construction primitives that no
+ * Workplane op exposes (bsplineSurface / approximatePoints / interpolatePoints,
+ * tolerant edge chaining, sew+makeSolid). The fai_cq_gears v1 port probed them
+ * in its own `kernel.ts` / `geom-build.ts` / `spline-face.ts`; per the port
+ * plan (§4) the implementations must live INSIDE cq-compat — this file is that
+ * landing spot. fai_cq_gears only imports from here; it must not touch
+ * occt-wasm directly.
+ *
+ * Everything here is a verbatim port of the proven v1 implementations (same
+ * kernel call sequence → bit-identical geometry).
+ */
+import type { BrepEngineApi, BrepHandle, BrepVec3 } from '@faicad/faijs';
+import type { Vec3 } from './geom-types.js';
+/** Rotation/mirror axis (occt-wasm shape). */
+export interface GearAxis {
+    point: BrepVec3;
+    direction: BrepVec3;
+}
+/**
+ * Raw occt-wasm capability surface — superset of `BrepEngineApi`.
+ *
+ * Declares exactly the methods the cq_gears port consumes; the probe test in
+ * fai_cq_gears asserts each one exists on the live kernel, so a kernel upgrade
+ * that renames a binding turns red immediately instead of failing at runtime
+ * with `undefined is not a function`.
+ */
+export interface GearKernel extends BrepEngineApi {
+    /** `GeomAPI_PointsToBSplineSurface`: point grid → B-spline surface → Face. */
+    bsplineSurface(points: BrepVec3[], rows: number, cols: number): BrepHandle;
+    /** `GeomAPI_PointsToBSpline`: point list → approximated B-spline curve (with Tol3D). */
+    approximatePoints(points: BrepVec3[], tolerance?: number): BrepHandle;
+    /** Cubic B-spline interpolation curve through all points. */
+    interpolatePoints(points: BrepVec3[], periodic?: boolean): BrepHandle;
+    /** `BRepBuilderAPI_Sewing`: faces → sewn shell (cq `make_shell` analogue). */
+    sew(shapes: BrepHandle[], tolerance?: number): BrepHandle;
+    makeSolid(shell: BrepHandle): BrepHandle;
+    /** TopAbs_ShapeEnum type name ("solid" / "shell" / "face" …, for diagnostics/assertions). */
+    getShapeType(shape: BrepHandle): string;
+    buildSolidFromFaces(faces: BrepHandle[], tolerance?: number): BrepHandle;
+    makeNonPlanarFace(wire: BrepHandle): BrepHandle;
+    makeFaceOnSurface(face: BrepHandle, wire: BrepHandle): BrepHandle;
+    outerWire(face: BrepHandle): BrepHandle;
+    healWire(wire: BrepHandle, tolerance?: number): BrepHandle;
+    healFace(face: BrepHandle, tolerance?: number): BrepHandle;
+    rotate(shape: BrepHandle, axis: GearAxis, angleRad: number): BrepHandle;
+    /** `BRepPrimAPI_MakeRevol`: face/wire revolved around `axis` (cq `Workplane.revolve`, 360°=2π). */
+    revolve(shape: BrepHandle, axis: GearAxis, angleRad: number): BrepHandle;
+    mirror(shape: BrepHandle, point: BrepVec3, normal: BrepVec3): BrepHandle;
+    reverseShape(shape: BrepHandle): BrepHandle;
+    vertexPosition(vertex: BrepHandle): BrepVec3;
+    split(shape: BrepHandle, tools: BrepHandle[]): BrepHandle;
+    fillet(solid: BrepHandle, edges: BrepHandle[], radius: number): BrepHandle;
+    shell(solid: BrepHandle, facesToRemove: BrepHandle[], thickness: number, tolerance: number): BrepHandle;
+    thicken(shape: BrepHandle, thickness: number, tolerance: number): BrepHandle;
+    makeCircleArc(center: BrepVec3, normal: BrepVec3, radius: number, startAngle: number, endAngle: number): BrepHandle;
+    makeHelixWire(origin: BrepVec3, axis: BrepVec3, pitch: number, height: number, radius: number): BrepHandle;
+    getSurfaceArea(shape: BrepHandle): number;
+    projectPointOnFace(face: BrepHandle, point: BrepVec3): BrepVec3;
+    surfaceType(face: BrepHandle): string;
+    subShapeCount(shape: BrepHandle, type: 'vertex' | 'edge' | 'wire' | 'face' | 'shell' | 'solid'): number;
+    isFace(shape: BrepHandle): boolean;
+    isWire(shape: BrepHandle): boolean;
+    isShell(shape: BrepHandle): boolean;
+    isEdge(shape: BrepHandle): boolean;
+}
+/**
+ * Get the raw occt-wasm kernel (process-wide singleton).
+ *
+ * Same instance as `initOcctWasm()` — this only asserts the richer
+ * `GearKernel` type, never constructs a second kernel (handles are indices
+ * into one kernel arena and must not cross instances).
+ *
+ * @returns the raw kernel (promise; initializes wasm on first call)
+ */
+export declare function getGearKernel(): Promise<GearKernel>;
+/** The two endpoints of an edge (order = the edge's parameter direction). */
+export interface GearEdgeEnds {
+    edge: BrepHandle;
+    a: Vec3;
+    b: Vec3;
+}
+/**
+ * Endpoints of an edge, via the curve parameter domain.
+ *
+ * ⚠️ Endpoint red line (probed 2026-09-11): `getSubShapes(edge, 'vertex')`
+ * returns fewer than 2 vertices for **B-spline curve edges** (OCCT stores no
+ * explicit vertices on them), which used to make edge chaining treat every
+ * edge as its own wire. The correct path is `curveParameters(edge)` →
+ * `curvePointAtParam(edge, param)` — valid for ALL edge kinds (line / arc /
+ * B-spline); the vertex fallback only covers degenerate edges without an
+ * underlying curve.
+ *
+ * @param kernel raw OCCT kernel
+ * @param edge edge handle
+ * @returns both endpoints (closed edges: first == last)
+ */
+export declare function gearEdgeEnds(kernel: GearKernel, edge: BrepHandle): GearEdgeEnds;
+/**
+ * TS port of OCCT `ShapeAnalysis_FreeBounds::ConnectEdgesToWires` — chain
+ * unordered edges into wires by endpoint proximity within `tol`.
+ *
+ * faijs/occt-wasm has no such binding and `makeWire(edges)` is
+ * `BRepBuilderAPI_MakeWire` — measured (2026-09-08) to silently drop edges on
+ * unordered input (68 edges → 9-edge broken wire). Endpoint pairing is O(n²)
+ * (n = 4·z teeth, at most a few hundred — fine).
+ *
+ * Gaps above OCCT precision (~1e-7) get a bridging line segment, matching
+ * upstream ConnectEdgesToWires behaviour.
+ *
+ * @param kernel raw OCCT kernel
+ * @param edges unordered edge set
+ * @param tol endpoint pairing tolerance (mm); cq uses `wire_comb_tol = 1e-2`
+ * @returns one or more wires, each with its edges chained head-to-tail
+ */
+export declare function connectEdgesToWires(kernel: GearKernel, edges: BrepHandle[], tol: number): BrepHandle[];
+/**
+ * cq `Face.makeFromWires(outer, holes)` analogue.
+ *
+ * @param kernel raw OCCT kernel
+ * @param outer outer wire
+ * @param holes inner hole wires (may be empty)
+ * @returns face handle
+ */
+export declare function gearFaceFromWires(kernel: GearKernel, outer: BrepHandle, holes?: BrepHandle[]): BrepHandle;
+/**
+ * cq `make_shell(faces, tol)` + `Solid.makeSolid(shell)` analogue.
+ *
+ * A non-shell sew result is NOT silently swallowed — that is a construction
+ * failure signal.
+ *
+ * @param kernel raw OCCT kernel
+ * @param faces faces to sew
+ * @param sewingTol sewing tolerance (mm, cq `shell_sewing_tol`)
+ * @returns solid built from the sewn shell
+ */
+export declare function gearShellToSolid(kernel: GearKernel, faces: BrepHandle[], sewingTol: number): BrepHandle;
+/**
+ * Tooth-face B-spline face strategies (mirrors cq `Face.makeSplineApprox`).
+ *
+ * | strategy | how | semantic delta vs cq |
+ * |---|---|---|
+ * | `grid-approx` | `kernel.bsplineSurface(flat, rows, cols)` (also `GeomAPI_PointsToBSplineSurface`) | OCCT default DegMin/DegMax/Tol3D; cq passes 3/8/1e-2 explicitly |
+ * | `row-approx-loft` | per-row `approximatePoints(row, tol)` → `loft(wires, false, false)` | curve-level tol same name/meaning; surface is skinned, not fitted at once |
+ * | `row-interp-loft` | per-row `interpolatePoints(row)` → `loft` | passes through every sample point (interpolation) |
+ */
+export type GearSplineFaceStrategy = 'grid-approx' | 'row-approx-loft' | 'row-interp-loft';
+/** All selectable strategies (tests iterate in this order for the deviation table). */
+export declare const GEAR_SPLINE_FACE_STRATEGIES: readonly GearSplineFaceStrategy[];
+/**
+ * Default strategy chosen by P0 measurement (2026-09-08).
+ *
+ * Per the measured table in the fai_cq_gears spike: S2's area relative
+ * deviation is 5.6e-7 / max sample-point distance 2.6e-6 mm — about three
+ * orders of magnitude better than S1/S3. See
+ * `docs/analysis/2026-09-08-fai-cq-gears-spike.md`.
+ */
+export declare const DEFAULT_GEAR_SPLINE_FACE_STRATEGY: GearSplineFaceStrategy;
+/** Face building options (tolerance + degrees, aligned with cq `makeSplineApprox`). */
+export interface GearSplineFaceOptions {
+    /** Approximation tolerance (mm). cq's `spline_approx_tol`, default 1e-2. */
+    tolerance?: number;
+    /** Surface minimum degree (cq: 3) — only meaningful for grid-approx/row-approx-loft. */
+    minDeg?: number;
+    /** Surface maximum degree (cq: 8). */
+    maxDeg?: number;
+}
+/** A row×col point grid with its dimensions (structural — no gear types here). */
+export interface GearSplineGrid {
+    /** `rows` point rows of `cols` points each. */
+    points: Vec3[][];
+    rows: number;
+    cols: number;
+}
+/**
+ * Build a face from a row×col point grid with the given strategy.
+ *
+ * @throws kernel errors propagate verbatim (never swallowed — red line)
+ *
+ * @param kernel raw OCCT kernel
+ * @param grid row×col point grid
+ * @param strategy face building strategy
+ * @param options tolerance/degree options
+ * @returns single face handle (Face)
+ */
+export declare function buildGearSplineFace(kernel: GearKernel, grid: GearSplineGrid, strategy: GearSplineFaceStrategy, options?: GearSplineFaceOptions): BrepHandle;
+/**
+ * Reduce a "single-face shell" to a Face; a Face passes through unchanged.
+ *
+ * @throws when the face count is not 1 (silently taking the first would mask problems)
+ *
+ * @param kernel raw OCCT kernel
+ * @param shape any shape (Face / single-face shell / …)
+ * @returns the sole Face
+ */
+export declare function soleGearFace(kernel: GearKernel, shape: BrepHandle): BrepHandle;
+/** Distance from a point to a face (`projectPointOnFace`).
+ *
+ * @param kernel raw OCCT kernel
+ * @param face target face
+ * @param p query point
+ * @returns euclidean distance (mm)
+ */
+export declare function gearDistanceToFace(kernel: GearKernel, face: BrepHandle, p: Vec3): number;
+/** Distance statistics (max / RMS / sample count). */
+export interface GearDeviationStats {
+    max: number;
+    rms: number;
+    n: number;
+}
+/**
+ * Distance statistics of reference sample points against a face.
+ *
+ * Parameterization-independent: samples come from the cq side's (u,v) grid, so
+ * the two surfaces may have different parameterizations.
+ *
+ * @param kernel raw OCCT kernel
+ * @param face face under test
+ * @param samplePoints reference sample points (3D)
+ * @returns max distance / RMS / sample count
+ */
+export declare function gearFaceDeviation(kernel: GearKernel, face: BrepHandle, samplePoints: Vec3[]): GearDeviationStats;
+//# sourceMappingURL=gears.d.ts.map

package/dist/gears.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gears.d.ts","sourceRoot":"","sources":["../src/gears.ts"],"names":[],"mappings":"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"}

package/dist/gears.js

@@ -0,0 +1,274 @@
+/**
+ * gears — raw-handle primitives for the cq_gears port (E1–E6 companion layer).
+ *
+ * cq_gears' tooth faces are B-spline patches built from (u,v) point grids and
+ * assembled by sewing — these need raw kernel construction primitives that no
+ * Workplane op exposes (bsplineSurface / approximatePoints / interpolatePoints,
+ * tolerant edge chaining, sew+makeSolid). The fai_cq_gears v1 port probed them
+ * in its own `kernel.ts` / `geom-build.ts` / `spline-face.ts`; per the port
+ * plan (§4) the implementations must live INSIDE cq-compat — this file is that
+ * landing spot. fai_cq_gears only imports from here; it must not touch
+ * occt-wasm directly.
+ *
+ * Everything here is a verbatim port of the proven v1 implementations (same
+ * kernel call sequence → bit-identical geometry).
+ */
+import { initOcctWasm } from '@faicad/faijs';
+let gearKernelPromise = null;
+/**
+ * Get the raw occt-wasm kernel (process-wide singleton).
+ *
+ * Same instance as `initOcctWasm()` — this only asserts the richer
+ * `GearKernel` type, never constructs a second kernel (handles are indices
+ * into one kernel arena and must not cross instances).
+ *
+ * @returns the raw kernel (promise; initializes wasm on first call)
+ */
+export function getGearKernel() {
+    if (!gearKernelPromise) {
+        gearKernelPromise = initOcctWasm().then((k) => k);
+    }
+    return gearKernelPromise;
+}
+function gearDist(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+/**
+ * Endpoints of an edge, via the curve parameter domain.
+ *
+ * ⚠️ Endpoint red line (probed 2026-09-11): `getSubShapes(edge, 'vertex')`
+ * returns fewer than 2 vertices for **B-spline curve edges** (OCCT stores no
+ * explicit vertices on them), which used to make edge chaining treat every
+ * edge as its own wire. The correct path is `curveParameters(edge)` →
+ * `curvePointAtParam(edge, param)` — valid for ALL edge kinds (line / arc /
+ * B-spline); the vertex fallback only covers degenerate edges without an
+ * underlying curve.
+ *
+ * @param kernel raw OCCT kernel
+ * @param edge edge handle
+ * @returns both endpoints (closed edges: first == last)
+ */
+export function gearEdgeEnds(kernel, edge) {
+    try {
+        const { first, last } = kernel.curveParameters(edge);
+        return {
+            edge,
+            a: kernel.curvePointAtParam(edge, first),
+            b: kernel.curvePointAtParam(edge, last),
+        };
+    }
+    catch {
+        // Fallback: rare degenerate edges without an underlying curve.
+        const vs = kernel.getSubShapes(edge, 'vertex');
+        if (vs.length < 2) {
+            const p = kernel.vertexPosition(vs[0]);
+            return { edge, a: p, b: p };
+        }
+        return { edge, a: kernel.vertexPosition(vs[0]), b: kernel.vertexPosition(vs[1]) };
+    }
+}
+/**
+ * TS port of OCCT `ShapeAnalysis_FreeBounds::ConnectEdgesToWires` — chain
+ * unordered edges into wires by endpoint proximity within `tol`.
+ *
+ * faijs/occt-wasm has no such binding and `makeWire(edges)` is
+ * `BRepBuilderAPI_MakeWire` — measured (2026-09-08) to silently drop edges on
+ * unordered input (68 edges → 9-edge broken wire). Endpoint pairing is O(n²)
+ * (n = 4·z teeth, at most a few hundred — fine).
+ *
+ * Gaps above OCCT precision (~1e-7) get a bridging line segment, matching
+ * upstream ConnectEdgesToWires behaviour.
+ *
+ * @param kernel raw OCCT kernel
+ * @param edges unordered edge set
+ * @param tol endpoint pairing tolerance (mm); cq uses `wire_comb_tol = 1e-2`
+ * @returns one or more wires, each with its edges chained head-to-tail
+ */
+export function connectEdgesToWires(kernel, edges, tol) {
+    if (!Number.isFinite(tol) || tol <= 0) {
+        throw new Error(`connectEdgesToWires: tol must be a positive finite number, got ${String(tol)}`);
+    }
+    const pool = edges.map((e) => gearEdgeEnds(kernel, e));
+    const used = new Array(pool.length).fill(false);
+    const wires = [];
+    for (let start = 0; start < pool.length; start++) {
+        if (used[start])
+            continue;
+        used[start] = true;
+        const chain = [pool[start].edge];
+        let tail = pool[start].b;
+        const head = pool[start].a;
+        // Chain forward: find an unused edge whose endpoint touches `tail` within tol.
+        for (;;) {
+            let found = -1;
+            let best = Infinity;
+            for (let j = 0; j < pool.length; j++) {
+                if (used[j])
+                    continue;
+                const dA = gearDist(pool[j].a, tail);
+                const dB = gearDist(pool[j].b, tail);
+                const d = Math.min(dA, dB);
+                if (d <= tol && d < best) {
+                    best = d;
+                    found = j;
+                }
+            }
+            if (found < 0)
+                break;
+            used[found] = true;
+            const e = pool[found];
+            const flip = gearDist(e.a, tail) <= gearDist(e.b, tail);
+            if (best > 1e-7) {
+                chain.push(kernel.makeLineEdge(tail, flip ? e.a : e.b));
+            }
+            // Edge points the wrong way: reverseShape makes a reversed copy.
+            chain.push(flip ? e.edge : kernel.reverseShape(e.edge));
+            tail = flip ? e.b : e.a;
+            // Back at the start ⇒ closed loop, stop.
+            if (gearDist(tail, head) <= tol)
+                break;
+        }
+        // Close the loop: bridge the tail-to-head gap too.
+        const endGap = gearDist(tail, head);
+        if (chain.length > 1 && endGap > 1e-7 && endGap <= tol) {
+            chain.push(kernel.makeLineEdge(tail, head));
+        }
+        wires.push(kernel.makeWire(chain));
+    }
+    return wires;
+}
+/**
+ * cq `Face.makeFromWires(outer, holes)` analogue.
+ *
+ * @param kernel raw OCCT kernel
+ * @param outer outer wire
+ * @param holes inner hole wires (may be empty)
+ * @returns face handle
+ */
+export function gearFaceFromWires(kernel, outer, holes = []) {
+    const f = kernel.makeFace(outer);
+    return holes.length > 0 ? kernel.addHolesInFace(f, holes) : f;
+}
+/**
+ * cq `make_shell(faces, tol)` + `Solid.makeSolid(shell)` analogue.
+ *
+ * A non-shell sew result is NOT silently swallowed — that is a construction
+ * failure signal.
+ *
+ * @param kernel raw OCCT kernel
+ * @param faces faces to sew
+ * @param sewingTol sewing tolerance (mm, cq `shell_sewing_tol`)
+ * @returns solid built from the sewn shell
+ */
+export function gearShellToSolid(kernel, faces, sewingTol) {
+    const shell = kernel.sew(faces, sewingTol);
+    if (!kernel.isShell(shell) && !kernel.isSolid(shell)) {
+        throw new Error(`gearShellToSolid: sew did not produce a shell (got ${String(kernel.getShapeType(shell))})`);
+    }
+    return kernel.makeSolid(shell);
+}
+/** All selectable strategies (tests iterate in this order for the deviation table). */
+export const GEAR_SPLINE_FACE_STRATEGIES = [
+    'grid-approx',
+    'row-approx-loft',
+    'row-interp-loft',
+];
+/**
+ * Default strategy chosen by P0 measurement (2026-09-08).
+ *
+ * Per the measured table in the fai_cq_gears spike: S2's area relative
+ * deviation is 5.6e-7 / max sample-point distance 2.6e-6 mm — about three
+ * orders of magnitude better than S1/S3. See
+ * `docs/analysis/2026-09-08-fai-cq-gears-spike.md`.
+ */
+export const DEFAULT_GEAR_SPLINE_FACE_STRATEGY = 'row-approx-loft';
+/**
+ * Build a face from a row×col point grid with the given strategy.
+ *
+ * @throws kernel errors propagate verbatim (never swallowed — red line)
+ *
+ * @param kernel raw OCCT kernel
+ * @param grid row×col point grid
+ * @param strategy face building strategy
+ * @param options tolerance/degree options
+ * @returns single face handle (Face)
+ */
+export function buildGearSplineFace(kernel, grid, strategy, options = {}) {
+    const tol = options.tolerance ?? 1e-2;
+    switch (strategy) {
+        case 'grid-approx':
+            return buildGearGridApprox(kernel, grid);
+        case 'row-approx-loft':
+            return buildGearRowLoft(kernel, grid, (row) => kernel.approximatePoints(row, tol));
+        case 'row-interp-loft':
+            return buildGearRowLoft(kernel, grid, (row) => kernel.interpolatePoints(row, false));
+    }
+}
+/** S1: fit the whole grid to one B-spline surface at once. */
+function buildGearGridApprox(kernel, grid) {
+    const flat = [];
+    for (const row of grid.points)
+        for (const p of row)
+            flat.push(p);
+    return kernel.bsplineSurface(flat, grid.rows, grid.cols);
+}
+/** S2/S3: per-row curve → `loft` skinning. */
+function buildGearRowLoft(kernel, grid, makeCurve) {
+    const wires = grid.points.map((row) => kernel.makeWire([makeCurve(row)]));
+    // `loft(wires, isSolid=false, ruled=false)` returns a **shell** (measured
+    // 2026-09-08), while cq's tooth face is a TopoDS_Face; downstream sew /
+    // projectPointOnFace require a Face, so extract the sole face.
+    return soleGearFace(kernel, kernel.loft(wires, false, false));
+}
+/**
+ * Reduce a "single-face shell" to a Face; a Face passes through unchanged.
+ *
+ * @throws when the face count is not 1 (silently taking the first would mask problems)
+ *
+ * @param kernel raw OCCT kernel
+ * @param shape any shape (Face / single-face shell / …)
+ * @returns the sole Face
+ */
+export function soleGearFace(kernel, shape) {
+    if (kernel.isFace(shape))
+        return shape;
+    const faces = kernel.getSubShapes(shape, 'face');
+    if (faces.length !== 1) {
+        throw new Error(`soleGearFace: expected a single face, got ${faces.length} (shapeType=${String(kernel.getShapeType(shape))})`);
+    }
+    return faces[0];
+}
+/** Distance from a point to a face (`projectPointOnFace`).
+ *
+ * @param kernel raw OCCT kernel
+ * @param face target face
+ * @param p query point
+ * @returns euclidean distance (mm)
+ */
+export function gearDistanceToFace(kernel, face, p) {
+    const q = kernel.projectPointOnFace(face, p);
+    return Math.hypot(q.x - p.x, q.y - p.y, q.z - p.z);
+}
+/**
+ * Distance statistics of reference sample points against a face.
+ *
+ * Parameterization-independent: samples come from the cq side's (u,v) grid, so
+ * the two surfaces may have different parameterizations.
+ *
+ * @param kernel raw OCCT kernel
+ * @param face face under test
+ * @param samplePoints reference sample points (3D)
+ * @returns max distance / RMS / sample count
+ */
+export function gearFaceDeviation(kernel, face, samplePoints) {
+    let max = 0;
+    let sumSq = 0;
+    for (const p of samplePoints) {
+        const d = gearDistanceToFace(kernel, face, p);
+        if (d > max)
+            max = d;
+        sumSq += d * d;
+    }
+    return { max, rms: Math.sqrt(sumSq / samplePoints.length), n: samplePoints.length };
+}
+//# sourceMappingURL=gears.js.map