@faicad/cq-compat 0.13.0

package/dist/workplane.d.ts

@@ -0,0 +1,1216 @@
+/**
+ * @faicad/cq-compat — CadQuery API compatibility layer for faijs.
+ *
+ * Implements a Workplane carrier (geometry hidden in .shape) and
+ * CadQuery-style methods. All methods are async and return a new Workplane
+ * (immutable updates). The carrier uses a custom prototype so compatOp's
+ * `borrowDeep` does not traverse its fields when the library is auto-lifted.
+ *
+ * Design doc: docs/plans/2026-09-06-cadquery-compat-and-multifile-faijs.md
+ */
+import type { Shape } from '@faicad/faijs/mesh/types';
+/**
+ * 把可能是借用视图的几何输入归一为真实 faijs Shape（见上方注释）。
+ * @param v 真实 Shape、借用视图（`{ wrapped }`）或其他原样透传的输入。
+ * @returns 真实 faijs `Shape`（借用视图经 `fromHandle` 还原并缓存）。
+ */
+export declare function asBrepShape(v: unknown): Shape;
+/** RGB color (sRGB 0..1). */
+export type RGB = [number, number, number];
+/**
+ * A pending 2D profile wire (CadQuery `ctx.pendingWires` analogue).
+ *
+ * Upstream keeps a LIST of wires, and `extrude()` turns them into one face per
+ * outermost wire with the enclosed wires punched as holes — verified against
+ * cadquery 2.8.0 (two columns per pushPoint, and a plate with four holes):
+ *
+ *   `circle(4).circle(2).extrude(4)`                 -> annulus, vol 150.796
+ *   `pushPoints([p1,p2]).circle(4).circle(2)`        -> TWO annuli (2 solids)
+ *   `rect(2,2).rect(1.3,1.3,fc).vertices()`
+ *     `.circle(0.125).extrude(0.5)`                  -> ONE plate, vol 1.901825
+ *
+ * `cx`/`cy` are workplane-LOCAL coordinates (a wire created under `pushPoints`
+ * or after `vertices()` is already positioned at its point). `group` is the
+ * index of the point it was created at, kept only for diagnostics.
+ */
+/** Snapshot of the plane a pending wire was created on (world coordinates). */
+export interface WirePlane {
+    origin: [number, number, number];
+    xDir: [number, number, number];
+    yDir: [number, number, number];
+    normal: [number, number, number];
+}
+/**
+ * A 2D profile wire queued on a Workplane until a solid op (extrude / revolve /
+ * loft / …) consumes it. Every variant records its local 2D placement plus a
+ * snapshot of the creation plane, so a later `workplane(offset)` or transformed
+ * move does not retro-actively relocate wires that are already queued.
+ */
+export type PendingWire = {
+    kind: 'rect';
+    w: number;
+    d: number;
+    cx: number;
+    cy: number;
+    construction: boolean;
+    plane?: WirePlane;
+} | {
+    kind: 'circle';
+    radius: number;
+    cx: number;
+    cy: number;
+    construction: boolean;
+    plane?: WirePlane;
+} | {
+    kind: 'ellipse';
+    majorRadius: number;
+    minorRadius: number;
+    cx: number;
+    cy: number;
+    construction: boolean;
+    plane?: WirePlane;
+    /** True when the caller's y_radius exceeds x_radius (see {@link ellipse}). */
+    flip?: boolean;
+} | {
+    kind: 'polygon';
+    n: number;
+    d: number;
+    cx: number;
+    cy: number;
+    construction: boolean;
+    plane?: WirePlane;
+}
+/** Open/closed ring produced by moveTo/lineTo/arcs/polyline + close()/wire(). */
+ | {
+    kind: 'path';
+    pts: [number, number][];
+    edges?: PendingEdge[];
+    construction: boolean;
+    plane?: WirePlane;
+};
+/**
+ * One drafted 2D edge, in workplane-LOCAL coordinates — the CadQuery
+ * `ctx.pendingEdges` analogue. All descriptors keep `from`/`to` so generic
+ * consumers (vertex ring, close()) can treat every kind uniformly.
+ */
+export type PendingEdge = {
+    kind: 'line';
+    from: [number, number];
+    to: [number, number];
+} | {
+    kind: 'arc3';
+    from: [number, number];
+    mid: [number, number];
+    to: [number, number];
+} | {
+    kind: 'tangentArc';
+    from: [number, number];
+    tgt: [number, number];
+    to: [number, number];
+} | {
+    kind: 'spline';
+    from: [number, number];
+    pts: [number, number][];
+    to: [number, number];
+    endTgt?: [number, number];
+    builtEdge?: unknown;
+};
+/**
+ * Workplane carrier — object with a custom prototype so compatOp's
+ * `borrowDeep` does NOT traverse its fields (it only walks objects whose
+ * prototype === Object.prototype). This prevents .shape from being replaced
+ * by a borrowed brepjs view when the library is auto-lifted.
+ */
+export interface Workplane {
+    __cq: true;
+    /** Plane name: "XY" | "XZ" | "YZ". */
+    plane: string;
+    /** Workplane origin in world coordinates. */
+    origin: [number, number, number];
+    /** Workplane normal (unit vector, local +Z). */
+    normal: [number, number, number];
+    /** Workplane local +X in world coordinates (CadQuery Plane.xDir convention). */
+    xDir: [number, number, number];
+    /** Workplane local +Y in world coordinates (= normal × xDir). */
+    yDir: [number, number, number];
+    /** Current geometry (faijs Shape), or null for empty workplane. */
+    shape: Shape | null;
+    /** Pending face selector (e.g. ">Z", "<X"). Set by .faces(). */
+    faceSel: string | null;
+    /** Pending edge selector (e.g. "|Z", ""). Set by .edges(). */
+    edgeSel: string | null;
+    /** Pending vertex selector. Set by .vertices(). */
+    vertexSel: string | null;
+    /** Accumulated pushPoints (2D offsets in workplane coords). */
+    pts: [number, number][];
+    /** Edge midpoints for construction rect (set by .edges()). */
+    edgePts?: [number, number][];
+    /** forConstruction flag — next rect/circle is construction geometry. */
+    forConstruction: boolean;
+    /** Pending 2D rect profile (set by .rect(), consumed by .extrude()/.cutBlind()). */
+    pendingRect?: {
+        w: number;
+        d: number;
+    };
+    /** Pending 2D circle profile (set by .circle(), consumed by .extrude()/.cutBlind()). */
+    pendingCircle?: {
+        radius: number;
+    };
+    /** Pending regular polygon profile (set by .polygon(), consumed by .extrude()/.cutBlind()). */
+    pendingPolygon?: {
+        n: number;
+        d: number;
+    };
+    /**
+     * Pending 2D profile wires — the CadQuery `pendingWires` LIST.
+     * `rect`/`circle`/`polygon` APPEND; `extrude` consumes. The single-slot
+     * fields above are kept for the (single-wire) legacy path.
+     */
+    pendingWires?: PendingWire[];
+    /**
+     * Drafted 2D edges waiting to be combined into a wire — CadQuery
+     * `ctx.pendingEdges`. Consumed by `wire()` / `close()`.
+     */
+    pendingEdges?: PendingEdge[];
+    /**
+     * Current drawing point in local coords — end of the last drafted edge, or
+     * the plane origin when nothing has been drawn yet (upstream
+     * `_findFromPoint`: last stack object, else `plane.origin`).
+     */
+    currentPoint?: [number, number];
+    /**
+     * First point of the wire currently being drafted, local coords — CadQuery
+     * `ctx.firstPoint`. Set by the first non-construction edge, cleared by
+     * `close()`.
+     */
+    firstPoint?: [number, number];
+    /** Optional color (sRGB 0..1) for this part. */
+    color?: RGB;
+}
+/**
+ * Resolve a CadQuery-style face selector string to the selected face's center
+ * point and outward normal.
+ *
+ * Supported forms: ">Z", "<Z", ">X", "<X", ">Y", "<Y", each with an optional
+ * CadQuery-style index suffix like ">Z[-2]", plus the six named views
+ * ("front"/"back"/"left"/"right"/"top"/"bottom") which are aliases for the
+ * corresponding axis selectors per cadquery/selectors.py:687-694.
+ * @param shape - Shape whose BREP faces are enumerated for selection.
+ * @param sel - Selector string, e.g. ">Z", "front", ">Z[-2]".
+ * @param centerOption - Optional center computation option forwarded to the
+ *   face-center evaluation.
+ * @returns Promise resolving to the selected face's center point and outward
+ *   normal.
+ * @throws Error when the selector matches no face or has unknown syntax
+ *   (never falls back silently).
+ */
+export declare function resolveFaceSelector(shape: Shape, sel: string, centerOption?: string): Promise<{
+    center: [number, number, number];
+    normal: [number, number, number];
+}>;
+/** CadQuery `centered` parameter: bool or per-axis triple. */
+type Centered3 = boolean | [boolean, boolean, boolean];
+/**
+ * Workplane
+ * @param plane - string
+ * @returns Workplane
+ */
+export declare function Workplane(plane?: string): Workplane;
+/**
+ * add
+ * @param wp - Workplane
+ * @param shape - Shape
+ * @returns Promise<Workplane>
+ */
+export declare function add(wp: Workplane, shape: Shape): Promise<Workplane>;
+/**
+ * box
+ * @param wp - Workplane
+ * @param w - number
+ * @param d - number
+ * @param h - number
+ * @param opts - { centered?; combine? }
+ * @returns Promise<Workplane>
+ *
+ * CadQuery semantics (verified vs cadquery 2.8.0 `Workplane.box`): with the
+ * default `centered=(True, True, True)` the box is centered on the workplane
+ * origin in ALL three axes — including the normal direction. The old
+ * "sit on the face" behaviour belonged to the makeBoxAt tool-body helper and
+ * leaked into this public op (found by the parity harness, testBoxDefaults).
+ *
+ * Each-point semantics (verified vs 2.8.0): box() is eachpoint-based — with
+ * points pushed on the stack a box is created at every point; `combine=True`
+ * (default) fuses them with the existing solid, `combine=False` leaves them
+ * as separate solids in a compound (test_getitem / testBoxPointList).
+ */
+export declare function box(wp: Workplane, w: number, d: number, h: number, opts?: {
+    centered?: Centered3;
+    combine?: boolean;
+}): Promise<Workplane>;
+/**
+ * sphere
+ * @param wp - Workplane
+ * @param radius - number
+ * @param opts - { centered?; combine? }
+ * @returns Promise<Workplane>
+ *
+ * CadQuery semantics (verified vs cadquery 2.8.0 `Workplane.sphere`): a sphere
+ * is created for every point on the stack (or the workplane origin); per-axis
+ * `centered=false` puts the sphere's bbox corner on the point. Only full
+ * spheres are supported (angle1/angle2/angle3 partial sweeps are not
+ * expressible with the cad.sphere primitive — upstream testSphereCustom stays
+ * blocked on that).
+ */
+export declare function sphere(wp: Workplane, radius: number, opts?: {
+    centered?: Centered3;
+    combine?: boolean;
+}): Promise<Workplane>;
+/**
+ * wedge — CadQuery `Workplane.wedge` parity.
+ *
+ * OCCT `BRepPrimAPI_MakeWedge(dx, dy, dz, xmin, zmin, xmax, zmax)` geometry:
+ * the bottom face (local y=0) spans the full [0,dx]×[0,dz] rectangle and the
+ * top face (local y=dy) spans [xmin,xmax]×[zmin,zmax]; all six faces are
+ * planar. Built here as a RULED loft between the two rectangles — geometrically
+ * identical to the OCCT primitive (verified vs cadquery 2.8.0: testClean
+ * wedge-with-sphere union vol 9.079922 / testNoClean 10.650718).
+ *
+ * `centered=True` (default) shifts by (−dx/2, −dy/2, −dz/2) along the LOCAL
+ * workplane axes, mirroring upstream's `offset` computation. Limitation: the
+ * kernel has no makeWedge primitive, and upstream composes the wedge in WORLD
+ * axes before the eachpoint location transform — for the default XY plane the
+ * two agree; rotated planes are not exercised by any current mirror.
+ *
+ * @param wp - Workplane acting as the eachpoint carrier
+ * @param dx - Bottom-face extent along local X
+ * @param dy - Wedge height along local Y
+ * @param dz - Bottom-face extent along local Z
+ * @param xmin - Top-face minimum along local X
+ * @param zmin - Top-face minimum along local Z
+ * @param xmax - Top-face maximum along local X
+ * @param zmax - Top-face maximum along local Z
+ * @param opts - { centered?: Centered3; combine?: boolean; clean?: boolean }
+ * @returns Promise<Workplane> carrying the wedge solid
+ */
+export declare function wedge(wp: Workplane, dx: number, dy: number, dz: number, xmin: number, zmin: number, xmax: number, zmax: number, opts?: {
+    centered?: Centered3;
+    combine?: boolean;
+    clean?: boolean;
+}): Promise<Workplane>;
+/**
+ * cylinder
+ * @param wp - Workplane
+ * @param height - number
+ * @param radius - number
+ * @param opts - { direct?; centered?; combine? }
+ * @returns Promise<Workplane>
+ *
+ * CadQuery semantics (verified vs cadquery 2.8.0 `Workplane.cylinder`): a
+ * cylinder for every point on the stack; per-axis `centered` offsets are
+ * applied in the LOCAL frame (xDir/yDir/normal), then rotated by the
+ * `direct` plane orientation (ax3Rotation table), then mapped by the
+ * workplane basis. `angle != 360` pie-slice sweeps are not supported.
+ */
+export declare function cylinder(wp: Workplane, height: number, radius: number, opts?: {
+    direct?: [number, number, number];
+    angle?: number;
+    centered?: Centered3;
+    combine?: boolean;
+}): Promise<Workplane>;
+/**
+ * torus — CadQuery free-function analogue (occ_impl.shapes.torus).
+ *
+ * Upstream takes DIAMETERS and builds a full torus centred at the origin,
+ * axis +Z: `torus(d1, d2)` -> R = d1/2, r = d2/2, V = 2π²·R·r²
+ * (`torus(10, 2)` -> 98.696, ref-verified against cadquery 2.8.0).
+ *
+ * @param wp - Workplane carrier (fresh `Workplane()` for the free function).
+ * @param d1 - Major DIAMETER.
+ * @param d2 - Minor DIAMETER.
+ * @param opts - { combine?: boolean }
+ * @returns Promise<Workplane> carrying the torus solid.
+ */
+export declare function torus(wp: Workplane, d1: number, d2: number, opts?: {
+    combine?: boolean;
+}): Promise<Workplane>;
+/**
+ * cone — CadQuery free-function analogue (occ_impl.shapes.cone).
+ *
+ * Upstream takes DIAMETERS with the base centred on the origin at z=0, axis
+ * +Z: `cone(d1, d2, h)` -> R = d1/2, r = d2/2, V = π/3·h·(R²+Rr+r²)
+ * (`cone(2, 1, 1)` -> 1.8326, ref-verified against cadquery 2.8.0). The
+ * 2-arg upstream form `cone(d, h)` is the full cone — pass `d2 = 0`.
+ *
+ * @param wp - Workplane carrier (fresh `Workplane()` for the free function).
+ * @param d1 - Base DIAMETER.
+ * @param d2 - Top DIAMETER (0 for a full cone).
+ * @param h - Height along +Z.
+ * @param opts - { combine?: boolean }
+ * @returns Promise<Workplane> carrying the cone solid.
+ */
+export declare function cone(wp: Workplane, d1: number, d2: number, h: number, opts?: {
+    combine?: boolean;
+}): Promise<Workplane>;
+/**
+ * rarray
+ * @param wp - Workplane
+ * @param xSpacing - number
+ * @param ySpacing - number
+ * @param xCount - number
+ * @param yCount - number
+ * @param center - boolean | [boolean, boolean]
+ * @returns Workplane
+ *
+ * CadQuery semantics (verified vs cadquery 2.8.0 `Workplane.rarray`): pushes
+ * an xCount×yCount grid of points; per-axis `center=true` centers the grid on
+ * the workplane origin, `false` puts the lower corner on it.
+ */
+export declare function rarray(wp: Workplane, xSpacing: number, ySpacing: number, xCount: number, yCount: number, center?: boolean | [boolean, boolean]): Workplane;
+/**
+ * rect
+ * @param wp - Workplane
+ * @param w - number
+ * @param d - number
+ * @param opts - { forConstruction?: boolean }
+ * @returns Workplane
+ */
+export declare function rect(wp: Workplane, w: number, d: number, opts?: {
+    forConstruction?: boolean;
+    centered?: boolean | [boolean, boolean];
+}): Workplane;
+/**
+ * circle
+ * @param wp - Workplane
+ * @param radius - number
+ * @returns Workplane
+ */
+export declare function circle(wp: Workplane, radius: number): Workplane;
+/**
+ * ellipse — CadQuery `Workplane.ellipse(x_radius, y_radius)` parity.
+ *
+ * `x_radius` lies on the workplane X axis and `y_radius` on Y — upstream puts
+ * no ordering constraint on them (`testEdgeTypesFilter` uses `ellipse(3, 4)`).
+ * The kernel's `makeEllipseEdge` requires major >= minor, ignores the plane's
+ * own axes and lays the major axis on the global X direction, so a "tall"
+ * ellipse is built as a wide one and then rotated 90° about the workplane
+ * normal through its centre (see `buildProfileWire`).
+ *
+ * @param wp - Workplane
+ * @param x_radius - radius along the workplane X axis
+ * @param y_radius - radius along the workplane Y axis
+ * @returns Workplane
+ */
+export declare function ellipse(wp: Workplane, x_radius: number, y_radius: number): Workplane;
+/**
+ * polygon
+ * @param wp - Workplane
+ * @param n - number
+ * @param d - number
+ * @returns Workplane
+ */
+export declare function polygon(wp: Workplane, n: number, d: number): Workplane;
+/**
+ * threePointArc — draft an arc from the current point through `point1`,
+ * ending at `point2` (CadQuery `Workplane.threePointArc`).
+ * @param wp - Workplane
+ * @param point1 - intermediate point the arc passes through (local 2D)
+ * @param point2 - end point of the arc (local 2D)
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function threePointArc(wp: Workplane, point1: [number, number], point2: [number, number], forConstruction?: boolean): Workplane;
+/**
+ * sagittaArc — arc from the current point to `endPoint` with sagitta `sag`
+ * (CadQuery `Workplane.sagittaArc`). Positive sag bulges to the LEFT of the
+ * start→end direction (convex for a clockwise contour), negative to the right.
+ * Mirrors the upstream sag-vector rotation in cq.py sagittaArc.
+ * @param wp - Workplane
+ * @param endPoint - end point (local 2D)
+ * @param sag - sagitta (perpendicular distance from arc midpoint to the chord)
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function sagittaArc(wp: Workplane, endPoint: [number, number], sag: number, forConstruction?: boolean): Workplane;
+/**
+ * radiusArc — arc from the current point to `endPoint` with radius `radius`
+ * (CadQuery `Workplane.radiusArc`). Positive radius = convex arc (for a
+ * clockwise contour), negative = concave. The sagitta is derived exactly as
+ * upstream: sag = |r| − sqrt(r² − (len/2)²).
+ * @param wp - Workplane
+ * @param endPoint - end point (local 2D)
+ * @param radius - arc radius (sign selects the bulge side)
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function radiusArc(wp: Workplane, endPoint: [number, number], radius: number, forConstruction?: boolean): Workplane;
+/**
+ * tangentArcPoint — arc tangent to the end of the last drafted edge, ending at
+ * `endpoint` (CadQuery `Workplane.tangentArcPoint`).
+ * @param wp - Workplane
+ * @param endpoint - end point (local 2D; relative to the current point when
+ *   `relative` is true)
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @param relative - interpret `endpoint` relative to the current point (default true)
+ * @returns Workplane
+ */
+export declare function tangentArcPoint(wp: Workplane, endpoint: [number, number], forConstruction?: boolean, relative?: boolean): Workplane;
+/**
+ * spline — cubic B-spline edge interpolated exactly through `points`
+ * (CadQuery `Workplane.spline`, includeCurrent=false default: the edge starts
+ * at points[0], NOT at the current point — upstream `_toVectors` only prepends
+ * the current point when includeCurrent is set). The current point becomes the
+ * spline end. `includeCurrent` prepends the current point; the resulting edge
+ * stores its kernel-measured end tangent so a following tangentArcPoint can
+ * continue the curve.
+ * @param wp - Workplane
+ * @param points - interpolation points (local 2D; 3D z=0)
+ * @param opts - { forConstruction?; includeCurrent?; periodic?; makeWire? }
+ * @returns Workplane
+ */
+export declare function spline(wp: Workplane, points: [number, number][], opts?: {
+    forConstruction?: boolean;
+    includeCurrent?: boolean;
+    periodic?: boolean;
+    makeWire?: boolean;
+}): Workplane;
+/**
+ * moveTo — move the current point without drawing (CadQuery `Workplane.moveTo`).
+ * @param wp - Workplane
+ * @param x - target x in local coords (default 0)
+ * @param y - target y in local coords (default 0)
+ * @returns Workplane
+ */
+export declare function moveTo(wp: Workplane, x?: number, y?: number): Workplane;
+/**
+ * move2D — relative version of `moveTo` (CadQuery `Workplane.move`).
+ *
+ * NOTE: upstream spells this `move`, but the Shape-level `move` (the in-place
+ * twin of `moved`, which takes `Location` arguments) already owns that name in
+ * cq-compat, so the 2D drafting variant is exported as `move2D`.
+ *
+ * @param wp - Workplane
+ * @param xDist - x offset from the current point (default 0)
+ * @param yDist - y offset from the current point (default 0)
+ * @returns Workplane
+ */
+export declare function move2D(wp: Workplane, xDist?: number, yDist?: number): Workplane;
+/**
+ * lineTo — draft a straight edge to an absolute local point
+ * (CadQuery `Workplane.lineTo`).
+ * @param wp - Workplane
+ * @param x - target x in local coords
+ * @param y - target y in local coords
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function lineTo(wp: Workplane, x: number, y: number, forConstruction?: boolean): Workplane;
+/**
+ * line — draft a straight edge by a relative offset (CadQuery `Workplane.line`).
+ * @param wp - Workplane
+ * @param xDist - x offset from the current point
+ * @param yDist - y offset from the current point
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function line(wp: Workplane, xDist: number, yDist: number, forConstruction?: boolean): Workplane;
+/**
+ * vLine — vertical (local +Y) relative line (CadQuery `Workplane.vLine`).
+ *
+ * @param wp - Workplane
+ * @param distance - signed length along local +Y
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function vLine(wp: Workplane, distance: number, forConstruction?: boolean): Workplane;
+/**
+ * hLine — horizontal (local +X) relative line (CadQuery `Workplane.hLine`).
+ *
+ * @param wp - Workplane
+ * @param distance - signed length along local +X
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function hLine(wp: Workplane, distance: number, forConstruction?: boolean): Workplane;
+/**
+ * vLineTo — vertical line to an absolute local y (CadQuery `Workplane.vLineTo`).
+ *
+ * @param wp - Workplane
+ * @param yCoord - absolute local y to end at
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function vLineTo(wp: Workplane, yCoord: number, forConstruction?: boolean): Workplane;
+/**
+ * hLineTo — horizontal line to an absolute local x (CadQuery `Workplane.hLineTo`).
+ *
+ * @param wp - Workplane
+ * @param xCoord - absolute local x to end at
+ * @param forConstruction - edge is reference geometry only (default false)
+ * @returns Workplane
+ */
+export declare function hLineTo(wp: Workplane, xCoord: number, forConstruction?: boolean): Workplane;
+/**
+ * polyline — draft a chain of edges through the given local points
+ * (CadQuery `Workplane.polyline`).
+ *
+ * `includeCurrent=false` (upstream default) treats the FIRST point as an
+ * implicit moveTo and only draws from it onward.
+ *
+ * @param wp - Workplane
+ * @param pts - local 2D points
+ * @param forConstruction - edges are reference geometry only (default false)
+ * @param includeCurrent - start from the current point (default false)
+ * @returns Workplane
+ */
+export declare function polyline(wp: Workplane, pts: [number, number][], forConstruction?: boolean, includeCurrent?: boolean): Workplane;
+/**
+ * wire — combine all pending edges into one pending wire
+ * (CadQuery `Workplane.wire`). No-op when there are no free edges (upstream
+ * returns self unchanged in that case).
+ *
+ * @param wp - Workplane
+ * @param forConstruction - keep the wire out of the solid profile (default false)
+ * @returns Workplane
+ */
+export declare function wire(wp: Workplane, forConstruction?: boolean): Workplane;
+/**
+ * close — end drafting and build a closed wire (CadQuery `Workplane.close`).
+ * Appends the closing segment when the end point is more than 1e-6 away from
+ * the first point (upstream threshold), then delegates to `wire()`.
+ *
+ * @param wp - Workplane
+ * @returns Workplane
+ */
+export declare function close(wp: Workplane): Workplane;
+/**
+ * extrude — CadQuery `Workplane.extrude` parity.
+ *
+ * Pulls the pending profile wire(s) along the workplane normal by `height`;
+ * a negative height extrudes the other way. `taper` (degrees, default 0)
+ * narrows the section towards the top and is limited to a single
+ * non-construction pending wire.
+ *
+ * @param wp - Workplane
+ * @param height - extrusion distance along the workplane normal
+ * @param combine - fuse the result with the carried shape (default true)
+ * @param opts - { taper?: number } draft angle in degrees
+ * @returns Promise<Workplane>
+ */
+export declare function extrude(wp: Workplane, height: number, combine?: boolean, opts?: {
+    taper?: number;
+}): Promise<Workplane>;
+/**
+ * revolve — CadQuery `Workplane.revolve` parity.
+ *
+ * Consumes the pending wire LIST (same grouping as extrude: one holed face per
+ * outermost wire) and revolves each face around an axis. Axis endpoints are
+ * LOCAL workplane coordinates (verified against cadquery 2.8.0
+ * `Workplane.revolve`): start defaults to the plane origin; when only start is
+ * given, end defaults to `(0, start.y)` if `start.y != 0` else `(0, 1)` — i.e.
+ * the local +Y direction. Angle 0 is normalized to 360 (OCCT cannot do a
+ * 0-degree revolve).
+ *
+ * @param wp - Workplane
+ * @param angleDegrees - revolution angle (default 360)
+ * @param axisStart - axis start point in local 2D coords
+ * @param axisEnd - axis end point in local 2D coords
+ * @param combine - true: fuse with base; "cut": subtract from base; false: keep separate
+ * @returns Promise<Workplane>
+ */
+export declare function revolve(wp: Workplane, angleDegrees?: number, axisStart?: [number, number] | [number, number, number], axisEnd?: [number, number] | [number, number, number], combine?: boolean | 'cut'): Promise<Workplane>;
+/** Options accepted by {@link loft}. */
+export interface LoftOptions {
+    ruled?: boolean;
+    combine?: boolean | 'cut';
+    /** Degenerate start point (upstream `loft(vertex(...), ...)`) — world coordinates. */
+    startPoint?: [number, number, number];
+    /** Degenerate end point (upstream `loft(..., vertex(...))`) — world coordinates. */
+    endPoint?: [number, number, number];
+}
+/**
+ * loft — CadQuery `Workplane.loft` parity.
+ *
+ * Consumes the pending wire LIST as loft sections (each wire built on its own
+ * creation-plane snapshot, so intermediate workplane(offset)/transformed moves
+ * are honored). Upstream default is a smooth (ruled=False) loft.
+ *
+ * Additional workplanes may be passed positionally (upstream free-function form
+ * `loft(w1, w2, w3)`): each contributes its own pending wires, or — when it
+ * carries no pending wire — the outer wires of its stacked faces.
+ *
+ * @param wp - Workplane
+ * @param rest - extra section workplanes, plus at most one options object
+ * @returns Promise<Workplane>
+ */
+export declare function loft(wp: Workplane, ...rest: (Workplane | LoftOptions)[]): Promise<Workplane>;
+/**
+ * cutBlind
+ * @param wp - Workplane
+ * @param depth - number
+ * @param opts - { w?: number; d?: number; radius?: number }
+ * @returns Promise<Workplane>
+ */
+export declare function cutBlind(wp: Workplane, depth: number, opts?: {
+    w?: number;
+    d?: number;
+    radius?: number;
+    taper?: number;
+}): Promise<Workplane>;
+/**
+ * cutThruAll
+ * @param wp - Workplane
+ * @returns Promise<Workplane>
+ *
+ * CadQuery semantics (verified vs cadquery 2.8.0 `Workplane.cutThruAll`):
+ * uses the pending 2D profile to cut through ALL material in BOTH normal
+ * directions of the workplane. The tool body spans the whole solid along
+ * the workplane normal (computed from the shape bounding box), so it is
+ * exact for any profile depth.
+ */
+export declare function cutThruAll(wp: Workplane): Promise<Workplane>;
+/**
+ * hole
+ * @param wp - Workplane
+ * @param diameter - number
+ * @param depth - number
+ * @returns Promise<Workplane>
+ */
+export declare function hole(wp: Workplane, diameter: number, depth?: number): Promise<Workplane>;
+/**
+ * cboreHole
+ * @param wp - Workplane
+ * @param diameter - number
+ * @param cboreDiameter - number
+ * @param cboreDepth - number
+ * @param depth - number | undefined (bore depth; undefined drills through, upstream depth=None)
+ * @returns Promise<Workplane>
+ */
+export declare function cboreHole(wp: Workplane, diameter: number, cboreDiameter: number, cboreDepth: number, depth?: number): Promise<Workplane>;
+/**
+ * cskHole
+ * @param wp - Workplane
+ * @param diameter - number
+ * @param cskDiameter - number
+ * @param cskAngle - number
+ * @returns Promise<Workplane>
+ */
+export declare function cskHole(wp: Workplane, diameter: number, cskDiameter: number, cskAngle: number): Promise<Workplane>;
+/**
+ * threadedHole
+ * @param wp - Workplane
+ * @param diameterOrFastener - number | unknown
+ * @param depth - number
+ * @returns Promise<Workplane>
+ */
+export declare function threadedHole(wp: Workplane, diameterOrFastener: number | unknown, depth?: number): Promise<Workplane>;
+/**
+ * faces
+ * @param wp - Workplane
+ * @param sel - string
+ * @returns Workplane
+ */
+export declare function faces(wp: Workplane, sel: string): Workplane;
+/**
+ * edges
+ * @param wp - Workplane
+ * @param sel - string | { slice?: [number, number]; index?: number }
+ * @returns Workplane
+ */
+export declare function edges(wp: Workplane, sel?: string | {
+    slice?: [number, number];
+    index?: number;
+}): Workplane;
+/**
+ * vertices
+ * @param wp - Workplane
+ * @param sel - string | { slice?: [number, number]; index?: number }
+ * @returns Workplane
+ */
+export declare function vertices(wp: Workplane, sel?: string | {
+    slice?: [number, number];
+    index?: number;
+}): Workplane;
+/**
+ * solids — CadQuery `Workplane.solids(selector)` parity (selector forms not
+ * supported; bare `solids()` only).
+ *
+ * Upstream returns a new Workplane whose stack holds each solid of the current
+ * compound as a separate object, so `val()` is the FIRST solid (verified vs
+ * cadquery 2.8.0: test_map_apply_filter_sort w.val() = vol 1.0 solid). The
+ * cq-compat carrier keeps a single `.shape`, so `solids()` mirrors the
+ * observable contract: the carrier shape becomes the first solid of the
+ * compound (a single-solid shape passes through unchanged).
+ *
+ * @param wp - Workplane
+ * @returns Workplane whose carried shape is the compound's first solid
+ */
+export declare function solids(wp: Workplane): Workplane;
+/**
+ * workplane
+ * @param wp - Workplane
+ * @param opts - { centerOption?: string; offset?: number }
+ * @returns Promise<Workplane>
+ */
+export declare function workplane(wp: Workplane, opts?: {
+    centerOption?: string;
+    offset?: number;
+    invert?: boolean;
+}): Promise<Workplane>;
+/**
+ * center
+ * @param wp - Workplane
+ * @param x - number
+ * @param y - number
+ * @returns Workplane
+ */
+export declare function center(wp: Workplane, x: number, y: number): Workplane;
+/**
+ * pushPoints
+ * @param wp - Workplane
+ * @param pts - [number, number][]
+ * @returns Workplane
+ */
+export declare function pushPoints(wp: Workplane, pts: [number, number][]): Workplane;
+/**
+ * translate
+ * @param wp - Workplane
+ * @param v - [number, number, number]
+ * @returns Promise<Workplane>
+ */
+export declare function translate(wp: Workplane, v: [number, number, number]): Promise<Workplane>;
+/**
+ * rotate
+ * @param wp - Workplane
+ * @param axis - [number, number, number]
+ * @param angle - number
+ * @returns Promise<Workplane>
+ */
+export declare function rotate(wp: Workplane, axis: [number, number, number], angle: number): Promise<Workplane>;
+/**
+ * mirror — full upstream `Workplane.mirror` semantics (cadquery 2.8.0, verified
+ * against cq.py:1113):
+ *   - string form: 'XY'..'ZY' named mirror planes
+ *   - vector form: plane normal, mirrored about `basePointVector` (default origin)
+ *   - Workplane form (upstream Face form): normal + center of the selected face;
+ *     basePointVector only overrides the center when explicitly given
+ *   - `union`: fuse the mirrored copy with the original (upstream `self.union(newS)`)
+ *
+ * The kernel projection is `cad.mirror(shape, { normal, at })` — the previous
+ * implementation passed `{ plane }`, which MirrorOptions does not know, so every
+ * mirror silently used the default normal [1,0,0] (latent bug, found while
+ * writing the test_mirror mirrors).
+ *
+ * @param wp - Workplane
+ * @param mirrorPlane - 'XY'..'ZY' | plane normal vector | Workplane carrying a face selection (default 'XY')
+ * @param basePointVector - point the mirror plane passes through (default: the selected face centre for the Workplane form, otherwise the world origin)
+ * @param union - fuse the mirrored copy with the original (default false)
+ * @returns Promise<Workplane> carrying the mirrored (or unioned) shape
+ */
+export declare function mirror(wp: Workplane, mirrorPlane?: string | number[] | Workplane, basePointVector?: [number, number, number], union?: boolean): Promise<Workplane>;
+/**
+ * faceCompound — extract the faces picked by a direction selector as a
+ * standalone compound Shape (upstream module-level `Shape.faces(">Z")`, which
+ * returns a Compound of faces — unlike `Workplane.faces()`, which only records
+ * the selection). Needed by test_single_ent_selector where the exported var IS
+ * the face compound (ref: Compound, area 2 = two unit-box top faces).
+ *
+ * `sel = 'all'` picks EVERY face of the shape — the upstream
+ * `compound(shape.Faces())` free-function form (test_constructors c1/c2).
+ *
+ * @param wp - Workplane
+ * @param sel - direction selector (">Z", "<X", …) or 'all' for every face
+ * @returns Promise<Workplane> carrying the face compound
+ */
+export declare function faceCompound(wp: Workplane, sel: string): Promise<Workplane>;
+/**
+ * edgeCompound — extract the edges picked by a direction selector as a
+ * standalone compound Shape (upstream `shape.edges(">Z")` on a Solid, which
+ * returns a Compound of edges). Needed by TestCQSelectors.testShape where the
+ * exported var IS the edge compound (ref: Compound of the 4 top edges).
+ *
+ * Semantics (upstream DirectionMinMaxSelector = CenterNthSelector n=-1):
+ * order ALL edges by their center-of-mass projection onto the axis and take
+ * the extremum cluster (ties included). For a centered box the vertical edges'
+ * centers sit at z=0 while the top edges sit at z=+h/2 — so `">Z"` picks
+ * exactly the 4 top edges.
+ *
+ * @param wp - Workplane
+ * @param sel - direction selector (">Z", "<X", …) picking the extremum edge cluster
+ * @returns Promise<Workplane> carrying the edge compound
+ */
+export declare function edgeCompound(wp: Workplane, sel: string): Promise<Workplane>;
+/**
+ * Minimal analogue of CadQuery's `Location`.
+ *
+ * Upstream (`cadquery/occ_impl/geom.py::Location`) builds a `gp_Trsf` from a
+ * translation plus an Euler rotation using **degrees** and
+ * `gp_Extrinsic_XYZ` order, then maps `p -> R·p + t` (rotate first, translate
+ * second). We keep exactly those two fields; rotation is stored in degrees so
+ * mirrors can pass upstream angle literals verbatim.
+ *
+ * Not modelled: the `Location(Plane)` / `Location(Plane, VectorLike)` overloads
+ * and `TopLoc_Location` composition — no mirror case needs them yet.
+ */
+export interface CqLocation {
+    readonly __cqLocation: true;
+    /** Translation (mm). */
+    readonly pos: [number, number, number];
+    /** Euler rotation in degrees (upstream gp_Extrinsic_XYZ). */
+    readonly rot: [number, number, number];
+}
+/**
+ * Type guard for a `Location` produced by {@link Location}.
+ *
+ * @param v - value to test
+ * @returns True when `v` is a cq-compat Location
+ */
+export declare function isLocation(v: unknown): v is CqLocation;
+/**
+ * Location — CadQuery `Location` constructor.
+ *
+ * Accepted forms (all verified against the upstream overloads used by
+ * `tests/test_free_functions.py::test_moved`):
+ *   `Location([x, y, z])`
+ *   `Location([x, y, z], [rx, ry, rz])`
+ *   `Location(x, y, z)` / `Location(x, y, z, rx, ry, rz)`
+ *   `Location({ x, y, z, rx, ry, rz })`   ← the `.moved(z=-1)` keyword form
+ *
+ * @param args - overload payload: `[pos]`, `[pos, rot]`, `(x, y, z[, rx, ry, rz])`, or the keyword object
+ * @returns CqLocation (position in mm, rotation in degrees)
+ */
+export declare function Location(...args: unknown[]): CqLocation;
+/**
+ * composeLocations(a, b) — the Location product `a * b` (upstream `Location.__mul__`):
+ * apply `b` first, then `a`. Result: R = Ra·Rb, t = Ra·t_b + t_a.
+ *
+ * Mirrors need this because a Workplane whose carried shape is a **compound**
+ * cannot be fed back into `moved` — the faijs runtime only re-attaches the BREP
+ * handle across statement boundaries for solids (see `moved`'s KNOWN LIMITATION
+ * note), so `bs1.moved(l3, l4)` has to be written as one `moved` over the
+ * composed locations instead of two chained ones.
+ *
+ * @param a - outer location (applied second)
+ * @param b - inner location (applied first)
+ * @returns CqLocation holding the product a·b
+ */
+export declare function composeLocations(a: CqLocation, b: CqLocation): CqLocation;
+/**
+ * moved — apply one or more Locations to the carried geometry.
+ *
+ * Upstream is `Shape.moved(*locs)`: one location returns a moved copy, several
+ * return a **compound** holding one copy per location (no boolean union —
+ * `test_moved` asserts `bs1.Volume() == 2` and `len(bs1.Solids()) == 2` for two
+ * disjoint unit boxes, which only holds for a compound).
+ *
+ * @param wp - Workplane
+ * @param locs - Location | [x,y,z] | {x,y,z,rx,ry,rz} | list thereof
+ * @returns Promise<Workplane>
+ */
+export declare function moved(wp: Workplane, ...locs: unknown[]): Promise<Workplane>;
+/**
+ * move — upstream mutates the shape in place; cq-compat carriers are immutable
+ * so this is an alias of {@link moved}.
+ *
+ * @param wp - Workplane
+ * @param locs - same forms as {@link moved}
+ * @returns Promise<Workplane>
+ */
+export declare function move(wp: Workplane, ...locs: unknown[]): Promise<Workplane>;
+/**
+ * union
+ * @param wp - Workplane
+ * @param other - Workplane | Shape
+ * @returns Promise<Workplane>
+ */
+export declare function union(wp: Workplane, other: Workplane | Shape): Promise<Workplane>;
+/**
+ * combine
+ * @param wp - Workplane
+ * @returns Promise<Workplane>
+ *
+ * CadQuery semantics note (verified vs cadquery 2.8.0): upstream `combine()`
+ * fuses all stack items. cq-compat fuses eagerly inside the building ops
+ * (extrude / eachpoint with combine=True), so by the time combine() runs the
+ * stack holds a single fused solid — the op degenerates to a `clean()` pass
+ * (same-face merge), which matches the upstream test expectations
+ * (testCombine: 11 faces either way).
+ */
+export declare function combine(wp: Workplane): Promise<Workplane>;
+/**
+ * cut
+ * @param wp - Workplane
+ * @param other - Workplane | Shape
+ * @returns Promise<Workplane>
+ */
+export declare function cut(wp: Workplane, other: Workplane | Shape): Promise<Workplane>;
+/**
+ * face — materialize the pending wire LIST as one planar face per outermost
+ * wire (upstream module-level `face(*wires)` free function). Enclosed wires
+ * become holes of the enclosing face — the same outer/hole grouping `extrude`
+ * uses. Several disjoint outer wires yield a Compound of faces.
+ *
+ * @param wp - Workplane carrying the pending wires
+ * @returns Promise<Workplane> whose shape is the face (or face compound)
+ */
+export declare function face(wp: Workplane): Promise<Workplane>;
+/**
+ * vertex — upstream module-level `vertex(x, y, z)` free function: a single
+ * point shape. Used as a degenerate loft section (`loft(face, vertex(0,0,1))`)
+ * and inside compounds.
+ *
+ * @param x - world x (default 0)
+ * @param y - world y (default 0)
+ * @param z - world z (default 0)
+ * @returns Shape holding the vertex
+ */
+export declare function vertex(x?: number, y?: number, z?: number): Shape;
+/**
+ * compound — upstream module-level `compound(*shapes)` free function: bundle
+ * several shapes into a single Compound WITHOUT any boolean operation. Needed
+ * by test_history_bool (imprint result = base solid + tool solid as a
+ * compound) and test_union_compound-style cases.
+ *
+ * Accepts Shapes and Workplanes (their current shape is used); null/empty
+ * entries are skipped. Returns a Shape whose value is the compound itself, so
+ * mirrors write `let result = c` directly.
+ *
+ * @param items - Shapes and/or Workplanes to bundle (null/undefined entries are skipped)
+ * @returns Compound Shape, or null when no item carries geometry
+ */
+export declare function compound(...items: (Workplane | Shape | null | undefined)[]): Shape | null;
+/**
+ * intersect
+ * @param wp - Workplane
+ * @param other - Workplane | Shape
+ * @returns Promise<Workplane>
+ */
+export declare function intersect(wp: Workplane, other: Workplane | Shape): Promise<Workplane>;
+/**
+ * Fillet selected edges of the current shape.
+ *
+ * Edge resolution mirrors chamfer: an explicit `|Z`-style / empty edgeSel goes
+ * through `resolveEdgeSelection`; a pending face selection
+ * (`.faces(">Z").fillet(r)`) fillets THE SELECTED FACE's edges via
+ * `resolveFaceEdgeSelection` (upstream `.faces("+Z").edges().fillet(r)`
+ * semantics — the missing faceSel branch made testTopFaceFillet fillet all 12
+ * edges instead of the 4 top ones). Failures propagate — silently returning
+ * the unfilleted shape previously produced plates whose fillets were missing
+ * entirely (bp/mb/mt/tp diagnosis, 2026-09-08).
+ *
+ * @param wp - Workplane whose current shape is filleted; consumes `edgeSel`/`faceSel`.
+ * @param radius - Fillet radius in world units.
+ * @returns Promise resolving to a new Workplane holding the filleted shape.
+ */
+export declare function fillet(wp: Workplane, radius: number): Promise<Workplane>;
+/**
+ * chamfer
+ * @param wp - Workplane
+ * @param length - number
+ * @param length2 - number | undefined
+ * @returns Promise<Workplane>
+ *
+ * CadQuery semantics (verified vs cadquery 2.8.0 `Workplane.chamfer`):
+ * chamfers the selected edges of the current shape. Edge resolution order:
+ * explicit `edges("|Z")` selector; else, if a face selector is pending
+ * (`.faces(">Z").chamfer(l)`), the edges OF the selected face; else all
+ * edges. LIMITATION: asymmetric `length2` is NOT supported — the occt-wasm
+ * kernel chamfer takes a single uniform distance (resolveUniformRadius
+ * degrades a pair to d1), so length2 throws instead of silently producing a
+ * symmetric chamfer.
+ */
+export declare function chamfer(wp: Workplane, length: number, length2?: number): Promise<Workplane>;
+/**
+ * shell
+ *
+ * CadQuery `Workplane.shell(thickness)` parity: shells the solid found on the
+ * stack, removing the faces selected by a preceding `faces(sel)` (empty
+ * selection = `Shape.hollow` — no faces removed, the solid is hollowed into a
+ * closed shell, verified vs cadquery 2.8.0: `box(2,2,2).shell(-0.1)` → 12
+ * faces, vol 2.168). The kernel call is `OcctKernel.shell` =
+ * `BRepOffsetAPI_MakeThickSolidByJoin` (negative thickness → walls inward,
+ * positive → walls outward, mirroring upstream sign semantics).
+ *
+ * Face removal set: single-axis selectors (">Z"/"<Z"/"+Z"/"-Z" …) pick the
+ * faces perpendicular to the axis whose bbox center sits at the extreme —
+ * the same criteria `resolveFaceSelector` uses. Multi-axis and indexed
+ * selectors are not supported here yet (the blocked mirrors that need them
+ * are out of this phase's scope).
+ *
+ * @param wp - Workplane
+ * @param thickness - number (negative: inward hollow)
+ * @returns Promise<Workplane>
+ */
+export declare function shell(wp: Workplane, thickness: number): Promise<Workplane>;
+/**
+ * val
+ * @param wp - Workplane
+ * @returns Shape | null
+ */
+export declare function val(wp: Workplane): Shape | null;
+/**
+ * vals
+ * @param wp - Workplane
+ * @returns (Shape | null)[]
+ */
+export declare function vals(wp: Workplane): (Shape | null)[];
+/**
+ * transformed
+ * @param wp - Workplane
+ * @param opts - { offset?: [number, number, number]; rotate?: [number, number, number] }
+ * @returns Promise<Workplane>
+ */
+export declare function transformed(wp: Workplane, opts: {
+    offset?: [number, number, number];
+    rotate?: [number, number, number];
+}): Promise<Workplane>;
+/**
+ * setColor
+ * @param wp - Workplane
+ * @param color - RGB
+ * @returns Workplane
+ */
+export declare function setColor(wp: Workplane, color: RGB): Workplane;
+/**
+ * splineFace — build a B-spline surface face from a regular point grid and set
+ * it as the workplane's current shape. CadQuery analog: `Face.makeSplineApprox`
+ * (`Part.makeSplineSurface`) over the same `rows × cols` point grid.
+ *
+ * Two strategies are available via `opts.strategy`:
+ *
+ * - `'row-approx-loft'` (**default**): each grid row becomes a curve through
+ *   `approximatePoints(row, tolerance)`, the row wires are skinned with
+ *   `loft(wires, false, false)`, and the single resulting face is returned.
+ *   This matches CadQuery `makeSplineApprox` to 4.2e-11 (straight) / 5.6e-7
+ *   (helical) relative area on gear tooth grids — ≈3 orders better than
+ *   `'grid'` — because the curve-level tolerance carries the same meaning as
+ *   CadQuery's `spline_approx_tol`.
+ * - `'grid'`: one-shot `bsplineSurface(flat, rows, cols)` over the whole grid.
+ *   occt-wasm exposes no DegMin/DegMax/Tol3D arguments here, so it runs with
+ *   kernel defaults; that measurably diverges from CadQuery's explicit
+ *   `(3, 8, 1e-2)` (≈2.3e-4 relative area on a gear tooth grid).
+ *
+ * Points are world-space and row-major (length `rows * cols`); the workplane's
+ * plane/origin are not consulted — it is only the returned carrier.
+ *
+ * @param wp - Workplane carrier
+ * @param grid - world-space points, row-major (length must equal `rows*cols`)
+ * @param opts - `{ rows; cols; tolerance?; strategy? }`. `tolerance` is the
+ *   per-row curve approximation tolerance (default `1e-2`, matching CadQuery's
+ *   `spline_approx_tol`); `strategy` defaults to `'row-approx-loft'`
+ * @returns Workplane with the spline face as `.shape`
+ */
+export declare function splineFace(wp: Workplane, grid: [number, number, number][], opts: {
+    rows: number;
+    cols: number;
+    tolerance?: number;
+    strategy?: 'row-approx-loft' | 'grid';
+}): Promise<Workplane>;
+/**
+ * helix — create a helical wire on the workplane (origin = `wp.origin`, axis =
+ * `wp.normal`). Equivalent to CadQuery `Workplane().makeHelix(pitch, height,
+ * radius, ...)`.
+ *
+ * @param wp - Workplane (origin + normal define the helix axis)
+ * @param pitch - axial advance per full turn (mm)
+ * @param height - total helix height (mm)
+ * @param radius - helix radius (mm)
+ * @param opts - `{ leftHanded?: boolean }` (default right-handed)
+ * @returns Workplane with the helix wire as `.shape`
+ */
+export declare function helix(wp: Workplane, pitch: number, height: number, radius: number, opts?: {
+    leftHanded?: boolean;
+}): Promise<Workplane>;
+/**
+ * splitFace — split the workplane's current shape by a plane and keep one side.
+ * Equivalent to CadQuery `face.split(plane)` / `split(keepTop)`.
+ *
+ * Internally builds a half-space tool (`occt-wasm` `halfSpace`) from the plane
+ * and runs `BOPAlgo_Splitter` (`split`); the kept fragment is selected by the
+ * signed distance of its bounding-box centre to the plane.
+ *
+ * @param wp - Workplane whose `.shape` is the face/solid to split
+ * @param plane - splitting plane as `{ origin: Vec3; normal: Vec3 }`
+ * @param keep - `'top'` (normal side, default) | `'bottom'` (opposite side)
+ * @returns Workplane with the kept fragment as `.shape`
+ */
+export declare function splitFace(wp: Workplane, plane: {
+    origin: [number, number, number];
+    normal: [number, number, number];
+}, keep?: 'top' | 'bottom'): Promise<Workplane>;
+/**
+ * twistExtrude — extrude a profile while twisting it about the extrusion axis
+ * by `angle` (deg) over `height` (mm). Equivalent to CadQuery
+ * `Workplane().twistExtrude(profile, angle, height, ...)`.
+ *
+ * Implemented by sweeping `steps`+1 rotated+translated copies of the profile
+ * through `loft` (a smooth, ruled=False loft). The twist axis is `wp.normal`.
+ *
+ * @param wp - Workplane carrying the profile: either `.shape` (face/wire) or a
+ *   pending 2D profile (`rect`/`circle`/`pendingWires`), as upstream accepts
+ * @param angle - total twist angle over height (deg)
+ * @param height - extrusion height (mm)
+ * @param opts - `{ steps?: number }` (section count; default scales with |angle|)
+ * @returns Workplane with the twisted solid as `.shape`
+ */
+export declare function twistExtrude(wp: Workplane, angle: number, height: number, opts?: {
+    steps?: number;
+}): Promise<Workplane>;
+/**
+ * solidFromFaces — sew a closed set of faces into a solid on the workplane.
+ * Equivalent to CadQuery `cq.Shell.makeShell(faces)` + `Solid.makeSolid(...)`
+ * (BRepBuilderAPI_Sewing + BRepBuilderAPI_MakeSolid + orientation fix).
+ *
+ * This is cq-compat extension E5 (fai_cq_gears port plan §13-6): the existing
+ * `shell` op is hollowing (thickening a solid), not sewing face patches into
+ * a solid, and gears need the latter after their tooth-face/cap faces are built.
+ *
+ * @param wp - Workplane providing the result's coordinate frame (origin/normal)
+ * @param faces - Workplanes whose `.shape` are the faces to sew (each must be a face)
+ * @param opts - `{ sewingTolerance?: number (default 1e-2, cq shell_sewing_tol);
+ *   fixOrientations?: boolean (default true) }`. `sew` does not guarantee
+ *   consistent face orientation — a loft-skinned tooth face can come out
+ *   inward-facing, making the sewn solid carry negative volume — so
+ *   `fixFaceOrientations` runs by default. If the fixed shape degrades back to
+ *   a shell (observed on micro-gap shells that only close via the sewing
+ *   tolerance), the pre-fix `makeSolid` result is kept instead.
+ * @returns Workplane with the sewn solid as `.shape`
+ */
+export declare function solidFromFaces(wp: Workplane, faces: Workplane[], opts?: {
+    sewingTolerance?: number;
+    fixOrientations?: boolean;
+}): Promise<Workplane>;
+/**
+ * planarCap — build a planar cap face from the boundary edges of the given
+ * faces that lie on the plane `origin · normal = d`, then set it as the
+ * workplane shape. Equivalent to CadQuery gears' `planarCapAtZ` /
+ * `Face.makeFromWires(Wire.combine(boundaryEdges, tol))`.
+ *
+ * This is cq-compat extension E6 (fai_cq_gears port plan §13-6): the existing
+ * `wire`/`face` ops only consume pending drawing descriptors, not edges that
+ * already exist inside kernel shapes — gears need to close their tooth-face
+ * patches with end caps built from those edges.
+ *
+ * Edge chaining ports the proven TS re-implementation of OCCT's
+ * `ShapeAnalysis_FreeBounds::ConnectEdgesToWires`: unordered edges are chained
+ * by endpoint proximity within `tol` (kernel `makeWire` silently drops edges
+ * when gaps exceed OCCT precision, so in-tolerance gaps are bridged with a
+ * line segment — same as upstream).
+ *
+ * @param wp - Workplane providing the result's coordinate frame
+ * @param faces - Workplanes whose `.shape` are the faces supplying boundary edges
+ * @param plane - cap plane: `{ origin, normal }`; the plane offset is taken
+ *   from `origin` (edges whose bounding box lies within `pickTolerance` of the
+ *   plane are collected)
+ * @param opts - `{ combineTolerance?: number (default 1e-2, cq wire_comb_tol);
+ *   pickTolerance?: number (default 1e-6) }`
+ * @returns Workplane with the cap face as `.shape`
+ */
+export declare function planarCap(wp: Workplane, faces: Workplane[], plane: {
+    origin: [number, number, number];
+    normal: [number, number, number];
+}, opts?: {
+    combineTolerance?: number;
+    pickTolerance?: number;
+}): Promise<Workplane>;
+export {};
+//# sourceMappingURL=workplane.d.ts.map