Choosing a geometry kernel

Compare the default Manifold mesh backend, stock OpenCascade, and the optional owned OCCT facade.

InvariantCAD documents are kernel-neutral, but geometry capabilities are not. Choose the backend based on representation, exchange, topology, performance, and deployment needs.

Comparison

	Manifold	Stock OCCT	Owned OCCT facade
Representation	Watertight triangle mesh	Exact B-Rep	Exact B-Rep
Default	Yes	No	No
Package source	Bundled core runtime	occt-wasm@3.8.0	Locally built matched runtime
STL/OBJ	Yes	Yes, through tessellation	Yes, through tessellation
STEP/BREP	No	Yes	Yes
Exact topology snapshot	No	Yes	Yes
Genus	Exact per connected mesh component	Unsupported (null)	Unsupported (null)
Draft	No	No	Yes, bounded ABI contract
Complete exact feature evolution	No	Partial	Selected Boolean/treatment/offset feature slices
Browser release test	Chromium	Chromium	Repository/local conformance only

Default Manifold

const evaluator = await createEvaluator();
const gatedPreview = await createEvaluator({ profile: "mesh-preview" });

Choose Manifold for fast, robust mesh-first workflows, ordinary parametric modeling, browser evaluation, and STL/OBJ output. It supports twist and top-scale extrusion, which the exact backend does not currently advertise.

Stock OpenCascade

const evaluator = await createEvaluator({ profile: "mechanical-exact" });

Choose stock OCCT for analytic B-Rep geometry, topology snapshots, exact bounded lofts/sweeps, fillets/chamfers/shells/offsets, and STEP/BREP exchange. Stock history for several complex features remains partial.

The profile is stronger than checking representation === "brep": creation also requires the documented primitive and feature baseline, native exchange methods, exactness, and face/edge/vertex topology. For custom loading, create the kernel explicitly and request the same preflight:

const kernel = await createOcctKernel({ wasm: customWasmSource });
const evaluator = await createEvaluator({
  profile: "mechanical-exact",
  kernel,
});

Owned OCCT facade

const kernel = await createOcctKernel({
  moduleFactory: ownedModuleFactory,
  wasm: ownedWasmUrl,
});

The facade is a matched extension built from pinned source and repository patches. The JavaScript factory and WASM binary must come from the same verified bundle. InvariantCAD probes its versioned ABI and advertises only the refinements that probe succeeds.

It is not bundled with the npm package, not selected automatically, and not downloaded at runtime.

Capability preflight

The evaluator treats capabilities as data contracts. Before executing a feature, it checks:

• protocol version
• primitive or feature name
• exact composite-sweep refinements
• native import/export format
• strong single-body import format and unit mode
• topology evidence surfaces and signature fingerprint
• exact indexed topology evolution when a stronger contract is required
• versioned measurement semantics such as exact or unsupported genus
• deterministic single-shape STEP metadata, bounds, and byte scope

Malformed metadata fails separately from absent support. A kernel cannot obtain behavior merely by defining an unadvertised method.

Use inspectKernelMeasurementCapabilities(...) or kernelSupports(capabilities, "measurement", "genus") for discovery. A numeric measurement is exact for the backend representation; null means unsupported. The following strong STEP envelope is implemented for the unreleased 0.2 line, not the current 0.1.1 npm package. Use inspectKernelStepExportCapabilities(...) for the optional strong STEP envelope. nativeExports containing "step" promises only that bytes can be written. Calling output.export("step") without a second argument remains compatible with weak kernels; supporting kernels use their deterministic defaults. Passing any second argument, including {}, requires a valid stepExport envelope or throws CadError with KERNEL_CAPABILITY_MISSING.

nativeImports is the weak exchange declaration. Document-backed imported bodies require the separate versioned documentBodyImport envelope and a callable importDocumentBody(...) method. Stock OCCT currently makes only these stronger promises:

Format	Unit mode	Strong result
STEP	from-file	One valid positive solid, using the file’s units
Text BREP	declared	One valid positive solid, scaled from the declared unit
Binary BREP	declared	One valid positive solid, scaled from the declared unit

The strong path rejects multiple solids, shells, and wrappers containing loose topology. It unwraps a pure one-solid compound, normalizes reversed orientation, uses fatal UTF-8 for text BREP, and releases provisional native handles on failure or cancellation. It does not claim healing, assembly import, stable feature lineage, or containment of an untrusted native parser.

The unreleased public ImportedBodyDocument workflow composes this kernel contract with a caller-supplied SHA-256/byte-length commitment and resolver. It accepts only STEP + model/step + file units, text BREP + text/plain + declared units, or binary BREP + application/octet-stream + declared units. Its explicit format chooses the reader; the media type is provenance rather than inference. The high-level workflow fails before native parsing when resolution or commitment verification fails and never falls back to importShape(...) or Manifold. See Import and export.

Do not equate these guarantees

• A B-Rep kernel is not automatically exact for every authored feature.
• Construction support does not imply complete topology history.
• STEP/BREP exchange does not imply safe backend-owned shape artifact caching.
• Native STEP export does not imply deterministic metadata or byte equality.
• Weak native import does not imply the strong document-body import contract.
• A topology snapshot does not imply persistent signature support.
• Successful tessellation does not make mesh coordinates analytically exact.

Use the support matrix for the feature-level boundary and the architecture for protocol rationale.