OpenCascade backend

Configure exact B-Rep evaluation, stock occt-wasm, custom binaries, and the owned facade.

createOcctKernel() adapts occt-wasm@3.8.0 to InvariantCAD’s exact geometry, topology, and exchange protocols.

Stock runtime

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

const kernel = await createOcctKernel();
const evaluator = await createEvaluator({ kernel });

The stock module supports exact primitives, extrusion, revolution, bounded loft/sweep contracts, Booleans, transforms, fillets, chamfers, shells, offsets, topology snapshots, and STEP/BREP exchange. Draft and several complete-history refinements are not advertised.

OCCT bounds, surface area, and center of mass are measured from the exact native B-Rep. Volume and inertia normally come from the same native shape; the documented validated analytic volume-override path for admitted sweep and revolve cases replaces the volume and rescales density-one inertia. Genus is currently null, not zero: the stock and owned facades do not expose the degenerate-edge predicate needed to evaluate the B-Rep Euler formula correctly for spheres, cones, seams, holes, and disconnected shells.

Load a WASM source explicitly

wasm accepts a URL, string URL/path, ArrayBuffer, or Uint8Array:

const kernel = await createOcctKernel({
  wasm: new URL("/assets/occt-wasm.wasm", location.href),
});

Bytes are copied where required so caller mutation cannot change an in-flight module initialization.

Tessellation and tolerance

const kernel = await createOcctKernel({
  modelingTolerance: 1e-7,
  tessellation: {
    linearDeflection: 0.1,
    angularDeflection: 0.3,
    relative: false,
  },
});

Modeling tolerance is part of topology fingerprints and feature validation. Tessellation options affect mesh() and mesh exports, not the underlying B-Rep. Do not change tolerances merely to force an invalid model through a check.

Native history limits

Owned facade operations can produce large indexed evolution reports. Bound materialization explicitly:

const kernel = await createOcctKernel({
  maxExactBooleanHistoryRecords: 250_000,
  maxExactEdgeTreatmentHistoryRecords: 250_000,
  maxExactSolidOffsetHistoryRecords: 250_000,
});

The defaults are 1,000,000 records per category. Limits apply across WASM and JavaScript transfer. Raise them only after measuring a legitimate workload.

Attested owned facade

For a reviewed bundle, prefer an environment-specific attested loader over pairing the files manually:

import { readFile } from "node:fs/promises";
import { createOcctKernel } from "invariantcad/kernels/occt";
import {
  INVARIANTCAD_OCCT_FACADE_0_9_0_RELEASE_MANIFEST_SHA256,
  loadAttestedOcctRuntime,
} from "invariantcad/kernels/occt/node";

const bundle = "/opt/invariantcad-occt-facade-0.9.0";
const [releaseManifest, javascript, webassembly] = await Promise.all([
  readFile(`${bundle}/metadata/release.json`),
  readFile(`${bundle}/runtime/occt-wasm.js`),
  readFile(`${bundle}/runtime/occt-wasm.wasm`),
]);

const attestedRuntime = await loadAttestedOcctRuntime({
  releaseManifest,
  expectedReleaseManifestSha256:
    INVARIANTCAD_OCCT_FACADE_0_9_0_RELEASE_MANIFEST_SHA256,
  javascript,
  webassembly,
});
const kernel = await createOcctKernel({ attestedRuntime });

The loader copies each caller-owned input, verifies the exact canonical release manifest against an independently trusted SHA-256 pin, then verifies the JavaScript and WASM sizes and digests before importing JavaScript. Kernel creation supplies a fresh verified WASM copy and requires the initialized facade marker to match the trusted manifest. attestedRuntime is mutually exclusive with wasm and moduleFactory.

The opaque pair can be reused to create kernels only through the evaluated InvariantCAD internal module instance that created it; cloning the visible report does not reproduce executable authority. Its exact runtime-pair identity strengthens only the repository-private artifact compatibility fingerprint; it does not change persistent-topology fingerprints or advertise shapeArtifacts. The separate declared-build identity records the manifest, but does not prove that recipe ran or authenticate a publisher. See OCCT runtime attestation for the browser loader, Node module-hook lifecycle, CSP, failure reasons, and complete non-claims.

Direct custom or rebuilt facade

const kernel = await createOcctKernel({
  moduleFactory: createOwnedOcctModule,
  wasm: ownedWasmBytes,
  onOutput: (message) => logger.info(message),
  onError: (message) => logger.error(message),
});

The repository can build and verify a package-neutral facade bundle. The bundle contains matched JavaScript/WASM, SHA-256 digests, source and relinking instructions, ordered patches, notices, build provenance, and an SBOM.

Raw moduleFactory plus wasm overrides remain available for an intentionally trusted custom or rebuilt pair. They do not perform release-manifest attestation or acquire an attested runtime-pair identity.

Never combine the owned JavaScript factory with stock WASM, or vice versa. Facade capability probing is not a license to mix binaries from different builds.

Exact exchange

const output = evaluated.output("body");

const step = output.export("step");
const textBrep = output.export("brep");
const binaryBrep = output.export("brep-binary");

The deterministic metadata and byte contract below is implemented for the unreleased 0.2 line, not the current 0.1.1 npm package.

The bundled zero-override stock kernel’s optional capabilities.stepExport envelope advertises KERNEL_STEP_EXPORT_PROTOCOL_VERSION === 1, schema AP214IS, byte scope same-shape-representation-and-metadata, a 64 MiB output ceiling, and a 64 KiB metadata ceiling. This is a distinct, stronger declaration than nativeExports containing "step"; the latter promises format availability, not deterministic bytes. inspectKernelStepExportCapabilities(...) snapshots and validates this optional envelope without invoking accessors.

Supplying wasm, moduleFactory, or attestedRuntime omits this envelope and retains weak raw STEP export. Even an explicitly supplied stock-derived artifact is unqualified until a separate exact-writer probe or attestation contract exists.

At the evaluated-output boundary, output.export("step", { metadata?, signal?, maxOutputBytes? }) supplies a complete resolved metadata request to a supporting kernel. The qualified bundled stock runtime writes one AP214IS product, then a purpose-built structural Part 21 transformer replaces only the relevant FILE_NAME and PRODUCT string tokens. It validates the exchange envelope, section structure, record arity, one-product assumption, exact EOF, metadata, entity count, scan work, and resulting byte size. It does not use a regular expression or reinterpret geometry.

Default metadata uses the document name for FILE_NAME, the fixed 1970-01-01T00:00:00 timestamp, and the output alias for an ordinary solid’s product ID and name. Parts use the part number or part-node ID for product ID, the part-node ID for product name, and the authored part description. A caller timestamp is accepted only as a valid YYYY-MM-DDTHH:MM:SS calendar value and is deterministic because it is explicit input. Protocol v1 accepts Unicode scalar text in the four identity/description fields: apostrophes are doubled for STEP, while literal backslashes and non-ASCII scalars use ISO-10303-21 \X2\...\X0\ or \X4\...\X0\ directives. Control characters and unpaired UTF-16 surrogates are rejected.

Material identity, configuration selection, arbitrary document metadata, and arbitrary part metadata are not representable through this current mapping. Aggregate assembly and body-set exact STEP export remains unsupported.

InvariantCAD validates and encodes metadata before starting the stock occt-wasm writer. That writer is synchronous and then materializes its original complete STEP string. JavaScript output limits and cancellation cannot interrupt the native call. Once it returns, InvariantCAD checks cancellation and applies bounded, cancellable scanning, entity/work limits, and the final output ceiling. maxOutputBytes bounds only the transformed bytes returned to JavaScript; it does not bound the native writer’s peak allocation.

The 64 KiB metadata budget measures the five resolved strings as UTF-8. Part 21 escaping can expand Unicode or backslash text, and that expanded form counts toward the 64 MiB returned-output ceiling.

The byte guarantee is deliberately narrow: identical bytes require the same backend shape representation, options, metadata, implementation, and exact runtime artifact. It is not geometric canonicalization, cross-runtime cache identity, or a canonicalizer for imported or third-party STEP files.

These methods return bytes or text synchronously from a live evaluated output. Generic BREP exchange does not preserve InvariantCAD wrapper lineage, topology annotations, cached evaluator state, or durable artifact identity.

Licensing boundary

occt-wasm is MIT-licensed glue around OpenCascade Technology, which is LGPL 2.1 with the Open CASCADE exception. Distributors must preserve the applicable notices, source/relinking path, and replacement rights. Read THIRD_PARTY_NOTICES.md before redistributing a runtime bundle.