invariantcad
v0.2.0
Published
Comprehensive, type-safe CAD-as-code for TypeScript
Maintainers
Readme
InvariantCAD
Comprehensive, type-safe CAD-as-code for TypeScript.
InvariantCAD turns an immutable, versioned design document into mesh or exact B-Rep geometry. Designs stay independent of WebAssembly pointers and kernel-specific objects, so they remain serializable, testable, and suitable for deterministic builds.
Status:
0.2.0is the current public foundation release. Parametric modeling, sketches, assemblies, configurations, topology-aware features, analysis, and interchange are usable today. Draft geometry and some complete exact topology-history guarantees require the separately built owned OCCT facade. Drawings, GD&T, sheet metal, mates, CAM, and CAE remain roadmap work.
Why InvariantCAD
- Native TypeScript authoring with dimension-aware expressions
- Immutable, versioned JSON design documents, validated when parsed or evaluated and checked against the grammar while authoring
- Replaceable geometry kernels: Manifold mesh and OpenCascade B-Rep
- Parametric sketches, primitives, features, transforms, and Booleans
- Semantic topology queries and persistent face, edge, and vertex references
- Parts, nested assemblies, configurations, materials, and deterministic BOMs
- Measurements, physical mass properties, design-impact analysis, and hashes
- STL, OBJ, STEP, and BREP export with explicit resource ownership
- Node.js and browser support with real WebAssembly browser tests
Install
pnpm add invariantcadInvariantCAD is ESM-only and requires Node.js 22.13 or newer. npm, Yarn, and Bun can install the package as well; pnpm is used for repository development.
Quick start
import { createEvaluator, design, mm, vec3 } from "invariantcad";
const cad = design("parametric-box");
const width = cad.parameter.length("width", mm(40), { min: mm(1) });
const body = cad.box("body", {
size: vec3(width, mm(20), mm(5)),
center: true,
});
cad.output("body", body);
async function evaluateParametricBox() {
const evaluator = await createEvaluator();
try {
const result = await evaluator.evaluate(cad.build(), {
parameters: { width: 60 },
outputs: ["body"],
});
if (!result.ok) {
throw new Error(
result.diagnostics.map((item) => item.message).join("\n"),
);
}
try {
const output = result.value.output("body");
return {
volume: output.measure().volume,
stlBytes: output.export("stl").byteLength,
};
} finally {
result.value.dispose();
}
} finally {
evaluator.dispose();
}
}
export const parametricBoxSummary = await evaluateParametricBox();
console.log(parametricBoxSummary);createEvaluator() with no arguments selects the bundled Manifold runtime.
profile: "mesh-preview" checks that same mesh contract explicitly. “Stock
OCCT” names the unmodified exact backend, not the evaluator default; select and
preflight it with profile: "mechanical-exact". Every evaluated design and
evaluator owns native resources, so use the finally boundaries shown above.
Geometry backends
| Backend | Representation | Best for | Exchange | | --- | --- | --- | --- | | Manifold | Watertight triangle mesh | Fast default modeling and STL/OBJ workflows | STL, ASCII STL, OBJ | | OpenCascade | Exact B-Rep | Analytic geometry, topology, STEP, and BREP workflows | STL, ASCII STL, OBJ, STEP, BREP |
Since 0.2.0: The strong deterministic STEP contract described below is implemented and release-gated in the npm package. It was not part of
0.1.1.
The bundled zero-override createOcctKernel() stock runtime advertises the
optional versioned deterministic STEP contract
KERNEL_STEP_EXPORT_PROTOCOL_VERSION === 1, separately from the weaker
nativeExports availability list. Its AP214IS single-product bytes are stable
for the same backend shape representation, export options, metadata, and exact
runtime artifact. An output that OCCT writes as several STEP products, such as
a disjoint union, returns weak native bytes from a plain export("step") and
fails with EXPORT_UNSUPPORTED when STEP options are passed. This is not
geometric canonicalization, a portable cache identity, or canonicalization of
imported or third-party STEP files. See
Import and export for metadata defaults,
Unicode encoding, and the distinction between the returned-output ceiling and
the synchronous native writer's peak allocation.
Supplying wasm, moduleFactory, or attestedRuntime deliberately removes
that strong envelope until the exact writer artifact is separately qualified.
Those runtimes retain their ordinary weak native STEP export.
Automatic defaults map only the document name and output/part identity fields; they do not pass through arbitrary document or part metadata, material identity, or the active configuration.
Use createEvaluator({ profile: "mechanical-exact" }) for the supported stock
OCCT baseline. The
mounting-plate quickstart shows complete
default and exact lifecycles, including STEP export and the caller-owned-kernel
failure path.
Pass an explicit kernel when custom OCCT loading, an owned runtime, or another backend is required. See the kernel guide for the complete capability and deployment differences.
Capability snapshot
InvariantCAD 0.2 includes:
- Length, angle, scalar, vector, and density expressions with dependency checks
- Boxes, cylinders/cones, spheres, sketches, extrudes, revolves, and transforms
- Exact bounded lofts and line/arc path sweeps through OCCT
- Union, subtraction, intersection, fillet, chamfer, shell, and offset, plus draft with the owned OCCT facade only
- Constraint-based sketches with lines, arcs, circles, rectangles, and closed
polylines;
regularPolygonworks since 0.2.0 and always threw in 0.1.1 - Semantic topology set queries plus persistent topology evidence
- Materials, parts, nested assemblies, configurations, suppression, and BOMs
- Volume, area, center of mass, inertia, density-aware mass, and gyration analysis
- Document migration, deterministic serialization, feature hashes, and impact reports
With the reference solver, a radius, diameter, or equalRadius constraint
that changes a loop arc's radius, or a constraint that moves its center, does
not move the adjacent line endpoints, so the loop opens and evaluation fails
with SKETCH_NO_CLOSED_REGION; see
arcs in constrained loops.
Since 0.2.0, that diagnostic's details give the gap and the curves on
either side of it.
The support matrix distinguishes authoring, Manifold, stock OCCT, and owned-facade support feature by feature.
CLI
invariantcad validate model.json
invariantcad inspect model.json --kernel occt
invariantcad bom model.json --output assembly
invariantcad export model.json --output body --to body.stepSee the CLI reference for configuration and parameter overrides, output selection, formats, and exit behavior.
Documentation
Read the hosted documentation, or browse
its versioned source under docs/:
- Installation
- Full quickstart
- Core concepts
- Modeling guides
- Evaluation and kernels
- Topology and persistent references
- Assemblies, configurations, and BOMs
- Measurements and mass properties
- Import and export
- Public library surface and complete export index
- Complete guide
- Architecture and roadmap
Type declarations with their source JSDoc ship with the npm package for editor-level API documentation.
Architecture
TypeScript builder
↓
Versioned JSON design document
↓
Validated evaluator + sketch solver
↓
Manifold mesh kernel or OpenCascade B-Rep kernel
↓
Owned results → measurements, topology, BOM, mesh, and exchange filesThe public document is kernel-neutral. Backend handles never enter serialized design state, and all native lifetime boundaries are explicit.
Development
pnpm install --frozen-lockfile
pnpm check
pnpm lint
pnpm test
pnpm release:checkrelease:check builds the package, runs the complete Node test suite, validates
source correctness and format hygiene, locks every JavaScript export to its
source, declaration, API report, and package target, installs the packed tarball
into a clean consumer, measures checked coverage, executes all six kernel/model
reference benchmarks, validates the Mintlify site and links, audits production
and development dependencies, and executes the production browser bundle in
Chromium.
pnpm release:check, pnpm docs:dev, pnpm docs:validate, and
pnpm docs:links use the pinned Mint CLI, which supports Node.js 20.17 through
24 and exits on Node.js 25 and newer. Run them with Node.js 24, as CI and the
release workflow do.
See CONTRIBUTING.md before submitting a change. Project support and decision-making are documented in SUPPORT.md and GOVERNANCE.md.
Security
Report vulnerabilities privately through GitHub Security Advisories. Do not open a public issue for an undisclosed vulnerability. See SECURITY.md for supported versions and the WASM/native-code threat boundary.
License
InvariantCAD is licensed under Apache-2.0. Its geometry backends have their own notices and redistribution obligations; see THIRD_PARTY_NOTICES.md.
