Public library surface

InvariantCAD intentionally exposes a small number of package entry points and a large typed surface within them. Import only through these declared exports; physical files under dist/ are not public subpaths.

`invariantcad`

The root entry point contains ordinary application APIs.

Results and diagnostics

CadResult, Diagnostic, DiagnosticCode, CadError, success, failure, diagnostic, and hasErrors define structured operation outcomes.

Authoring

design, DesignBuilder, model reference classes, AssemblyBuilder, ConfigurationBuilder, plane, and tf create immutable design documents.

Expressions and units

Expression, Parameter, mm, cm, meters, inch, rad, deg, scalar, density constructors, vector constructors, expr, and expression conversion or inspection helpers create serializable formulas.

Sketching

SketchBuilder, entity reference classes, ProfileDefinition, and sketch option types describe planar constrained profiles. ReferenceSketchSolver and the solver protocol support evaluation or backend replacement. The evaluator checks a replacement solver’s advertised entity and constraint capabilities before solving and treats its returned status as authoritative; see Create an evaluator.

Documents

Current and frozen document constants/types, node kinds, IR types, Zod schemas, validateDocument, parsing, canonical serialization, cloning, migration, document hashing, and resource limits form the versioned document boundary.

Evaluation

createEvaluator, Evaluator, EvaluatedDesign, evaluated output classes, evaluation options, mesh/export formats, measurements, materials, BOMs, and physical-property types execute documents and expose owned results. Evaluator profiles (EvaluatorProfile, EVALUATOR_PROFILES) and inspectEvaluatorProfile check a kernel against the mesh-preview or mechanical-exact runtime contract.

Geometry kernels

GeometryKernel and its capability/protocol types support custom backends. createManifoldKernel and ManifoldKernel implement the bundled default. Direct OpenCascade kernel construction and its options live on the invariantcad/kernels/occt subpath. The root createEvaluator({ profile: "mechanical-exact" }) also creates the stock OCCT kernel, loading that module only when the profile is requested.

Topology

topology, topology query/selection classes, resolution/explanation helpers, semantic role constants, snapshot/descriptor protocols, persistent capture and resolution sessions, and topology limits cover current and durable selection intent.

Analysis and incremental foundations

Mass-property helpers, design impact, feature hashes, artifact-cache records and stores, and capability inspection support build systems and backend conformance without exposing transparent evaluator reuse. Semantic shape observations are not root exports; import them from invariantcad/conformance, described below. The repository’s direct-box OCCT cache experiment remains package-private and does not add an evaluator option or kernel capability.

Exporters

exportBinaryStl, exportAsciiStl, exportObj, and exportMesh can encode any compatible MeshData, including meshes produced outside an evaluated output. Binary STL writes the supplied name, which is the output name for evaluated outputs, into the 80-byte header. The UTF-8 bytes are cut on a character boundary to fit, and a name that starts with solid (ignoring case and leading whitespace) is written as InvariantCAD: <name> so readers do not mistake the file for ASCII STL.

`invariantcad/kernels/occt`

This entry point exposes createOcctKernel, OCCT initialization options, custom module-factory types, attested-runtime integration types, and documented OCCT-specific diagnostics/refinements. It loads the larger exact backend only when imported.

import { createOcctKernel } from "invariantcad/kernels/occt";

`invariantcad/kernels/occt/browser`

This entry point verifies exact owned-facade release-manifest, JavaScript, and WASM bytes, then imports the verified JavaScript through a Blob module URL in a browser or module worker.

import { loadAttestedOcctRuntime } from "invariantcad/kernels/occt/browser";

`invariantcad/kernels/occt/node`

This entry point exposes the same attested-runtime protocol through Node’s module-hook loader. The returned opaque runtime is consumed by createOcctKernel.

import { loadAttestedOcctRuntime } from "invariantcad/kernels/occt/node";

Both loaders require caller-acquired bytes and an independently trusted release-manifest digest. See OCCT runtime attestation for their security boundary and environment requirements.

`invariantcad/conformance`

Backend authors use this entry point for shape-artifact codec audits and semantic observation contracts. observeKernelShapeSemantics and the semantic-observation encoders, hashes, limits, protocol versions, and types are exported only here; 0.2.0 adds V2 variants alongside them. Candidate mode tests a codec without letting a kernel advertise it; advertised mode verifies the capability already exposed by the kernel.

import {
  auditKernelShapeArtifactCodec,
  observeKernelShapeSemantics,
} from "invariantcad/conformance";

Application code normally does not need this entry point.

Versioned names

Many exported IR, schema, topology, and protocol names carry V1 through V6. Those exports exist so tools can read, validate, migrate, and preserve frozen historical documents. New authoring should use the unversioned current aliases unless it is intentionally targeting an older protocol.

Stability in 0.x

Document versions are frozen independently of the semver stability of the TypeScript convenience API. Before 1.0, a minor package release may change public TypeScript APIs, but it must not reinterpret an already frozen document version. Read the changelog during every 0.x upgrade. The generated export index inventories every named export from the five JavaScript package entry points and is checked against source and the API Extractor reports during CI.

Library reference

Tools and formats

Exhaustive guide