brepjs 18.66.2 → 18.68.0

package/dist/implicit/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Field-first implicit CAD domain (ADR-0013, brepjs-implicit Phase 1).
+ *
+ * An analytic SDF expression tree that rasterizes DIRECTLY into the voxel
+ * substrate's dense grid with no input mesh — the field-first twin of the
+ * mesh-first voxel path. Primitives compose through CSG / smooth / domain
+ * combinators into an {@link SdfHandle}, which rasterizes to a banded-SDF
+ * {@link VoxelFieldHandle} for contour / offset / shell.
+ */
+export type { SdfHandle, SdfBounds } from './sdfFns.js';
+export { sphere, box, roundedBox, cylinder, cone, capsule, torus, plane } from './sdfFns.js';

package/dist/implicit/sdfFns.d.ts

@@ -0,0 +1,59 @@
+import { Result } from '../core/result.js';
+import { WasmSdf } from '../voxel/engine.js';
+import { VoxelFieldHandle, VoxelFieldOptions } from '../voxel/fieldFns.js';
+/** Explicit world bounds `[min..max]` for {@link SdfHandle.rasterizeIn}. */
+export interface SdfBounds {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+/**
+ * A disposable handle around an analytic SDF expression. Every combinator clones
+ * into a NEW wasm node and returns a NEW handle (the wasm `Sdf` is a value, not a
+ * mutable builder), so an `SdfHandle` is immutable — the receiver stays valid and
+ * must be disposed independently. `rasterize` produces a banded-SDF
+ * {@link VoxelFieldHandle} you can boolean / offset / shell / contour.
+ *
+ * Dispose is mandatory: use `using`, or call `[Symbol.dispose]()`, to free the
+ * WASM expression tree. Intermediate handles in a chain (`a.union(b).shell(t)`)
+ * each own a wasm allocation; bind them to `using` or dispose them explicitly.
+ */
+export interface SdfHandle {
+    /** The wrapped WASM expression. Throws if the handle has been disposed. */
+    readonly value: WasmSdf;
+    /** Whether the backing WASM expression has been freed. */
+    readonly disposed: boolean;
+    [Symbol.dispose](): void;
+    union(other: SdfHandle): SdfHandle;
+    intersection(other: SdfHandle): SdfHandle;
+    difference(other: SdfHandle): SdfHandle;
+    smoothUnion(other: SdfHandle, k: number): SdfHandle;
+    smoothIntersection(other: SdfHandle, k: number): SdfHandle;
+    smoothDifference(other: SdfHandle, k: number): SdfHandle;
+    offset(distance: number): SdfHandle;
+    round(radius: number): SdfHandle;
+    shell(thickness: number): SdfHandle;
+    onion(thickness: number): SdfHandle;
+    translate(x: number, y: number, z: number): SdfHandle;
+    rotate(ax: number, ay: number, az: number, angle: number): SdfHandle;
+    scale(s: number): SdfHandle;
+    /** Rasterize into a banded-SDF field over the expression's analytic bounds. */
+    rasterize(opts?: VoxelFieldOptions): Result<VoxelFieldHandle>;
+    /** Rasterize over explicit world bounds (clips unbounded primitives). */
+    rasterizeIn(bounds: SdfBounds, opts?: VoxelFieldOptions): Result<VoxelFieldHandle>;
+}
+/** A sphere of radius `r`, centered at the origin. */
+export declare function sphere(r: number, id?: string): Result<SdfHandle>;
+/** An axis-aligned box of half-extents `(hx, hy, hz)`, centered at the origin. */
+export declare function box(hx: number, hy: number, hz: number, id?: string): Result<SdfHandle>;
+/** A box with rounded edges of radius `r`. */
+export declare function roundedBox(hx: number, hy: number, hz: number, r: number, id?: string): Result<SdfHandle>;
+/** A capped cylinder, axis +Z, radius `r`, total height `h`, centered at origin. */
+export declare function cylinder(r: number, h: number, id?: string): Result<SdfHandle>;
+/** A capped cone centered at the origin: base radius `r` at z = −h/2 tapering to an apex at z = +h/2. */
+export declare function cone(r: number, h: number, id?: string): Result<SdfHandle>;
+/** A capsule: a line segment `a`→`b` of radius `r`. */
+export declare function capsule(a: [number, number, number], b: [number, number, number], r: number, id?: string): Result<SdfHandle>;
+/** A torus in the XY plane (axis +Z): a `minor`-radius tube on a `major` circle. */
+export declare function torus(major: number, minor: number, id?: string): Result<SdfHandle>;
+/** A half-space: the plane through `h·n` with outward normal `n` (normalized). */
+export declare function plane(n: [number, number, number], h: number, id?: string): Result<SdfHandle>;

package/dist/index.d.ts

@@ -38,8 +38,10 @@ export { exportDXF, blueprintToDXF, type DXFEntity, type DXFExportOptions, } fro
 export { exportThreeMF, type ThreeMFExportOptions, type ThreeMFMaterial, } from './io/threemfExportFns.js';
 export { importSVGPathD, importSVG, type SVGImportOptions } from './io/svgImportFns.js';
 export { exportSTEPConfigured, type StepExportOptions, type StepExportPart, } from './io/stepConfigFns.js';
-export { initVoxel, registerVoxel, getVoxel, getActiveVoxelId, windingNumbers, pointsInside, repairMesh, offsetMesh, shellMesh, voxelBoolean, offsetShape, shellShape, voxelBooleanShapes, shapeToMeshInput, } from './voxel/index.js';
-export type { VoxelEngine, VoxelMeshInput, VoxelRepairResult, RepairOptions, VoxelOpOptions, } from './voxel/index.js';
+export { initVoxel, registerVoxel, getVoxel, getActiveVoxelId, windingNumbers, pointsInside, repairMesh, offsetMesh, shellMesh, voxelBoolean, offsetShape, shellShape, voxelBooleanShapes, voxelField, voxelBooleanField, fieldBoolean, fieldOffset, fieldShell, fieldReinit, fieldContour, voxelFieldFromShape, voxelBooleanFieldShapes, shapeToMeshInput, } from './voxel/index.js';
+export type { VoxelEngine, VoxelMeshInput, VoxelRepairResult, RepairOptions, VoxelOpOptions, VoxelFieldHandle, VoxelFieldOptions, VoxelBooleanOp, } from './voxel/index.js';
+export { sphere as sdfSphere, box as sdfBox, roundedBox as sdfRoundedBox, cylinder as sdfCylinder, cone as sdfCone, capsule as sdfCapsule, torus as sdfTorus, plane as sdfPlane, } from './implicit/index.js';
+export type { SdfHandle, SdfBounds } from './implicit/index.js';
 export { latticeInfill, latticeInfillShape, tpmsLattice } from './lattice/index.js';
 export type { LatticeType, LatticeOptions, LatticeBounds } from './lattice/index.js';
 export { default as Sketcher } from './sketching/sketcher.js';

package/dist/voxel/engine.d.ts

@@ -23,9 +23,103 @@ export interface VoxelEngine {
     shell_mesh(verts: Float32Array, tris: Uint32Array, thickness: number, resolution: number, padding: number): VoxelRepairResult;
     /** Voxel CSG of two meshes (op: 0=union, 1=intersection, 2=difference A−B). */
     voxel_boolean(verts_a: Float32Array, tris_a: Uint32Array, verts_b: Float32Array, tris_b: Uint32Array, op: number, resolution: number, padding: number): VoxelRepairResult;
+    /**
+     * Persistent dense voxel-field class, for same-grid op chains: voxelize a mesh
+     * once, then boolean/offset/shell/reinit in place, contour once. Structurally
+     * satisfied by the generated `VoxelField` wasm-bindgen class.
+     */
+    VoxelField: WasmVoxelFieldConstructor;
+    /**
+     * Field-first analytic SDF builder (ADR-0013). Static primitive constructors
+     * and combinator methods compose an opaque expression tree that rasterizes
+     * directly into a {@link WasmVoxelField} with no input mesh. Structurally
+     * satisfied by the generated `Sdf` wasm-bindgen class.
+     */
+    Sdf: WasmSdfConstructor;
     /** Engine artifact version, for loader/artifact compatibility checks. */
     version(): string;
 }
+/**
+ * Static surface of the wasm `Sdf` class: the primitive constructors that seed an
+ * expression tree (centered at the origin unless noted). Each returns a fresh
+ * {@link WasmSdf}. Structurally satisfied by the generated `Sdf` class.
+ */
+export interface WasmSdfConstructor {
+    sphere(r: number): WasmSdf;
+    box_(hx: number, hy: number, hz: number): WasmSdf;
+    rounded_box(hx: number, hy: number, hz: number, r: number): WasmSdf;
+    cylinder(r: number, h: number): WasmSdf;
+    cone(r: number, h: number): WasmSdf;
+    capsule(ax: number, ay: number, az: number, bx: number, by: number, bz: number, r: number): WasmSdf;
+    torus(major: number, minor: number): WasmSdf;
+    plane(nx: number, ny: number, nz: number, h: number): WasmSdf;
+}
+/**
+ * An opaque analytic SDF expression. Every combinator CLONES into a new node and
+ * returns a fresh `WasmSdf` (wasm-bindgen has no shared borrow across calls), so an
+ * `Sdf` is a value, not a mutable builder. `rasterize` builds a banded-SDF
+ * {@link WasmVoxelField}; `free()` releases the backing WASM expression tree.
+ * Structurally satisfied by the generated `Sdf` wasm-bindgen class.
+ */
+export interface WasmSdf {
+    union(other: WasmSdf): WasmSdf;
+    intersection(other: WasmSdf): WasmSdf;
+    difference(other: WasmSdf): WasmSdf;
+    smooth_union(other: WasmSdf, k: number): WasmSdf;
+    smooth_intersection(other: WasmSdf, k: number): WasmSdf;
+    smooth_difference(other: WasmSdf, k: number): WasmSdf;
+    offset(d: number): WasmSdf;
+    round(r: number): WasmSdf;
+    shell(t: number): WasmSdf;
+    onion(t: number): WasmSdf;
+    translate(x: number, y: number, z: number): WasmSdf;
+    rotate(ax: number, ay: number, az: number, angle: number): WasmSdf;
+    scale(s: number): WasmSdf;
+    /** Rasterize into a banded-SDF dense field over the expression's analytic bounds. */
+    rasterize(resolution: number, padding: number): WasmVoxelField;
+    /** Rasterize over explicit `[min..max]` bounds (clips unbounded primitives). */
+    rasterize_in(min_x: number, min_y: number, min_z: number, max_x: number, max_y: number, max_z: number, resolution: number, padding: number): WasmVoxelField;
+    /** Release the backing WASM expression-tree allocation (wasm-bindgen lifecycle). */
+    free(): void;
+    [Symbol.dispose](): void;
+}
+/**
+ * Constructor of the wasm `VoxelField` class. `new VoxelField(verts, tris, res,
+ * padding)` voxelizes a mesh into a persistent dense field. Throws (as a JS
+ * exception) on a non-dense grid or a grid over the voxel cap.
+ */
+export interface WasmVoxelFieldConstructor {
+    new (verts: Float32Array, tris: Uint32Array, resolution: number, padding: number): WasmVoxelField;
+    /**
+     * Boolean two meshes onto ONE co-registered dense field (union bbox → voxelize
+     * both onto a shared grid → combine), ready to chain. The correct path for
+     * "boolean then offset/shell" two independently-described meshes, where
+     * {@link WasmVoxelField.boolean} requires the operands to already share grid
+     * geometry. `op`: 0=union, 1=intersection, 2=difference A−B.
+     */
+    boolean_of(verts_a: Float32Array, tris_a: Uint32Array, verts_b: Float32Array, tris_b: Uint32Array, op: number, resolution: number, padding: number): WasmVoxelField;
+}
+/**
+ * A persistent dense voxel field. All ops MUTATE IN PLACE (return void), so the
+ * same grid persists across a chain. `contour()` reads the zero set into a fresh
+ * {@link VoxelRepairResult}; `free()` releases the backing WASM grid (mandatory).
+ * Structurally satisfied by the generated `VoxelField` wasm-bindgen class.
+ */
+export interface WasmVoxelField {
+    /** CSG-combine in place (op: 0=union, 1=intersection, 2=difference self−B). */
+    boolean(other: WasmVoxelField, op: number): void;
+    /** Offset the surface in place (>0 outward, <0 inward); auto-reinits if dirty. */
+    offset(distance: number): void;
+    /** Hollow into an inward shell in place (thickness > 0); auto-reinits if dirty. */
+    shell(thickness: number): void;
+    /** Reinitialize φ to a true SDF (|∇φ|=1) while preserving the zero set. */
+    reinit(): void;
+    /** Surface-Nets contour the current field to a triangle mesh. */
+    contour(): VoxelRepairResult;
+    /** Release the backing WASM grid allocation (wasm-bindgen lifecycle). */
+    free(): void;
+    [Symbol.dispose](): void;
+}
 /**
  * The repaired-mesh handle the wasm `repair_mesh` returns. Flat xyz
  * `positions`/`normals` (length 3·V) and a triangle-list `indices` (3 per tri),

package/dist/voxel/fieldFns.d.ts

@@ -0,0 +1,121 @@
+import { Result } from '../core/result.js';
+import { KernelMeshResult } from '../kernel/types.js';
+import { AnyShape, Dimension } from '../core/shapeTypes.js';
+import { VoxelMeshInput } from './signFns.js';
+import { WasmVoxelField } from './engine.js';
+/** Field tuning. `resolution` sizes the longest bbox axis in voxels; `padding`
+ *  is the air-margin ring (>= 1) Surface Nets needs AND the headroom an outward
+ *  offset has before it clips at the grid boundary (the grid is fixed at
+ *  voxelize time — size both for the intended maximum offset). */
+export interface VoxelFieldOptions {
+    resolution?: number;
+    padding?: number;
+}
+/** Boolean op selector for {@link fieldBoolean} / {@link VoxelFieldHandle.boolean}. */
+export type VoxelBooleanOp = 'union' | 'intersection' | 'difference';
+/**
+ * A persistent, disposable voxel field. Carries the wrapped WASM field as
+ * `value` and a fluent op-chain (`.boolean().offset().shell().contour()`) that
+ * throws on the rare WASM error (mirroring the `shape()` facade's
+ * throw-on-`Err` convention), so a `using`-scoped chain reads cleanly:
+ *
+ * ```ts
+ * using field = voxelField(meshA).unwrap();
+ * using other = voxelField(meshB).unwrap();
+ * const mesh = field.boolean(other, 'union').offset(2).contour();
+ * ```
+ *
+ * Dispose is mandatory (FinalizationRegistry is an unreliable safety net): use
+ * `using`, or call `[Symbol.dispose]()` explicitly, to free the WASM grid.
+ */
+export interface VoxelFieldHandle {
+    /** The wrapped WASM field. Throws if the handle has been disposed. */
+    readonly value: WasmVoxelField;
+    /** Whether the backing WASM grid has been freed. */
+    readonly disposed: boolean;
+    [Symbol.dispose](): void;
+    /** CSG-combine with `other` in place (marks the field for lazy reinit). */
+    boolean(other: VoxelFieldHandle, op: VoxelBooleanOp): VoxelFieldHandle;
+    /** Offset the surface in place (>0 outward, <0 inward); auto-reinits if dirty. */
+    offset(distance: number): VoxelFieldHandle;
+    /** Hollow into an inward shell in place (thickness > 0); auto-reinits if dirty. */
+    shell(thickness: number): VoxelFieldHandle;
+    /** Reinitialize φ to a true SDF while preserving the zero set. */
+    reinit(): VoxelFieldHandle;
+    /** Surface-Nets contour the current field to a mesh (the field stays alive). */
+    contour(): KernelMeshResult;
+}
+export declare function makeFieldHandle(raw: WasmVoxelField): VoxelFieldHandle;
+/**
+ * Voxelize a mesh into a persistent dense {@link VoxelFieldHandle}: one grid you
+ * can boolean / offset / shell / reinit in place, then contour once. The handle
+ * is disposable — free the WASM grid with `using` (or `[Symbol.dispose]()`).
+ *
+ * `resolution` sizes the longest bbox axis; `padding` is the air-margin ring.
+ * Errors on an empty/invalid mesh, or if the grid would exceed the dense budget
+ * (the persistent path is dense-only) or the voxel cap.
+ */
+export declare function voxelField(mesh: VoxelMeshInput, opts?: VoxelFieldOptions, id?: string): Result<VoxelFieldHandle>;
+/**
+ * Boolean two meshes into ONE co-registered, chainable {@link VoxelFieldHandle}:
+ * voxelize both onto a single shared grid sized to their union bbox, combine by
+ * `op`, and keep the field. This is THE correct way to "boolean then chain
+ * offset/shell" two independently-described meshes — unlike {@link fieldBoolean},
+ * which requires the operands to already share grid geometry. The result is
+ * dirty (the blend drifts the gradient), so a subsequent offset/shell
+ * auto-reinitializes. The handle is disposable — free it with `using`.
+ *
+ * `op` is `'difference'` = A − B. Errors on an empty/invalid mesh, or if the
+ * shared grid would exceed the dense budget (the persistent path is dense-only).
+ */
+export declare function voxelBooleanField(a: VoxelMeshInput, b: VoxelMeshInput, op: VoxelBooleanOp, opts?: VoxelFieldOptions, id?: string): Result<VoxelFieldHandle>;
+/**
+ * CSG-combine two fields IN PLACE, returning the SAME `handle` for chaining. The
+ * min/max blend keeps the zero set exact but drifts the gradient near the join,
+ * so a subsequent {@link fieldOffset}/{@link fieldShell} auto-reinitializes.
+ *
+ * PRECONDITION: both operands must be CO-REGISTERED — same origin, spacing, AND
+ * dims. Two fields built by {@link voxelField} from DIFFERENT meshes generally do
+ * NOT share geometry (each sizes its grid to its own bbox), and the WASM guard
+ * rejects that mismatch as an `err(...)` rather than silently blending mismatched
+ * coordinate frames. For the easy co-registered path, build the field directly
+ * from both meshes with {@link voxelBooleanField}.
+ */
+export declare function fieldBoolean(handle: VoxelFieldHandle, other: VoxelFieldHandle, op: VoxelBooleanOp): Result<VoxelFieldHandle>;
+/**
+ * Offset the field's surface IN PLACE (>0 outward, <0 inward), returning the
+ * SAME `handle`. Auto-reinitializes first if the field is dirty (post-boolean),
+ * so the iso-shift always rides a true SDF.
+ */
+export declare function fieldOffset(handle: VoxelFieldHandle, distance: number): Result<VoxelFieldHandle>;
+/**
+ * Hollow the field into an inward shell of `thickness` IN PLACE, returning the
+ * SAME `handle`. Auto-reinitializes first if dirty; the result is dirty again
+ * (the shell re-introduces a kink).
+ */
+export declare function fieldShell(handle: VoxelFieldHandle, thickness: number): Result<VoxelFieldHandle>;
+/**
+ * Explicitly reinitialize φ to a true SDF (|∇φ|=1) while preserving the zero
+ * set, returning the SAME `handle`. Idempotent on a clean field. Offset/shell
+ * already auto-reinitialize, so this is for advanced control only.
+ */
+export declare function fieldReinit(handle: VoxelFieldHandle): Result<VoxelFieldHandle>;
+/**
+ * Surface-Nets contour the current field to a {@link KernelMeshResult}. The
+ * field stays alive and chainable afterwards (contour borrows it). An empty
+ * contour surfaces as `VOXEL_DEGENERATE_RESULT`.
+ */
+export declare function fieldContour(handle: VoxelFieldHandle): Result<KernelMeshResult>;
+/**
+ * Voxelize a B-rep shape into a persistent {@link VoxelFieldHandle}: tessellate
+ * it, then run {@link voxelField}. Threads a meshing failure back as an
+ * `err(...)`. The handle is disposable — free it with `using`.
+ */
+export declare function voxelFieldFromShape(shape: AnyShape<Dimension>, opts?: VoxelFieldOptions, id?: string): Result<VoxelFieldHandle>;
+/**
+ * Boolean two B-rep shapes into one co-registered, chainable
+ * {@link VoxelFieldHandle}: tessellate both, then run {@link voxelBooleanField}.
+ * `op` is `'difference'` = A − B. Threads either meshing failure back as an
+ * `err(...)`. The handle is disposable — free it with `using`.
+ */
+export declare function voxelBooleanFieldShapes(a: AnyShape<Dimension>, b: AnyShape<Dimension>, op: VoxelBooleanOp, opts?: VoxelFieldOptions, id?: string): Result<VoxelFieldHandle>;

package/dist/voxel/index.d.ts

@@ -9,8 +9,10 @@ export type { VoxelEngine, VoxelRepairResult } from './engine.js';
 export type { VoxelMeshInput } from './signFns.js';
 export type { RepairOptions } from './repairFns.js';
 export type { VoxelOpOptions } from './meshOpsFns.js';
+export type { VoxelFieldHandle, VoxelFieldOptions, VoxelBooleanOp } from './fieldFns.js';
 export { registerVoxel, getVoxel, getActiveVoxelId, initVoxel } from './registry.js';
 export { windingNumbers, pointsInside } from './signFns.js';
 export { repairMesh } from './repairFns.js';
 export { offsetMesh, shellMesh, voxelBoolean, offsetShape, shellShape, voxelBooleanShapes, } from './meshOpsFns.js';
+export { voxelField, voxelBooleanField, fieldBoolean, fieldOffset, fieldShell, fieldReinit, fieldContour, voxelFieldFromShape, voxelBooleanFieldShapes, } from './fieldFns.js';
 export { shapeToMeshInput } from './shapeMesh.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brepjs",
-  "version": "18.66.2",
+  "version": "18.68.0",
   "description": "Web CAD library with pluggable geometry kernel",
   "keywords": [
     "cad",