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.0 is 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 invariantcad

InvariantCAD 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:

This is the beginning of the README. Read the rest at the original. Read the full README ↗