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

Stock runtime

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. Assembly measure() aggregates those occurrence measurements, so a single unplaced occurrence reports the same area, bounds, and tolerance as its part; see assembly aggregation. Volume and inertia normally come from the same native shape; the documented validated analytic volume-override path for admitted circular-arc and composite sweep results, and for transforms of those results, replaces the volume and rescales density-one inertia. Revolve and other features use the native volume. A compound that repeats the same solid occurrence counts it once per occurrence in volume, inertia, and surface area alike, matching classifyBodyResult(). Measuring a compound shares that classifier’s bound of 1,000,000 visited plus queued occurrences; a larger compound fails with RangeError and every traversal handle is released. 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:
Bytes are copied where required so caller mutation cannot change an in-flight module initialization. An explicit source changes runtime identity, not only asset location. Unless the loaded module exposes the owned facade ABI, the kernel omits the persistent topology signature declaration (capabilities.topology.signatures and signatureProfiles), even for the identical stock bytes. Documents that store persistent topology references then fail with KERNEL_CAPABILITY_MISSING for capability persistent-topology-signatures, although the mechanical-exact preflight still passes. Supplying wasm or moduleFactory also omits the deterministic STEP envelope described under Exact exchange. Prefer the zero-override createOcctKernel() call when the bundler can place occt-wasm.wasm next to its JavaScript glue.

Tessellation and tolerance

Modeling tolerance is part of topology fingerprints and feature validation. It is a length in model units and must be a finite number greater than zero; the default is 1e-7. createOcctKernel() rejects any other value before it loads WebAssembly, with TypeError for a non-number and RangeError for NaN, zero, a negative value, or infinity. Tessellation deflections must likewise be finite and positive, and relative must be a boolean. The kernel checks the creation-time defaults and every per-call mesh() override before native meshing starts. It reads each tessellation field once from an own data property: an accessor or a field inherited from a caller-defined prototype fails with TypeError, and Object.prototype entries are ignored. The tolerance applies only to lengths. It never relaxes dimensionless values: a transform scale is treated as uniform only when its three factors agree to within floating-point rounding, and any other factors use the exact affine map. Exact extrusion requires a twist of exactly 0 and a top scale of exactly [1, 1]; any other value fails with KERNEL_ERROR instead of producing a straight prism. 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:
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:
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

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

The deterministic metadata and byte contract below was added in 0.2.0 and is not in 0.1.1.
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. For a single solid or part, 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. OCCT writes a shape that holds several disjoint solids, such as a union of separated boxes or a subtraction that splits its target, as an assembly with several PRODUCT records. That shape is outside the single-product contract. output.export("step") with no second argument then returns the weak native STEP bytes, as 0.1.1 did. Passing any options object requests the strong contract and throws CadError with EXPORT_UNSUPPORTED and details.reason === "multiple-products". A low-level kernel.exportShape(shape, "step") call without context.stepExport follows the same weak fallback; with context.stepExport it throws the same CadError. 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. Explicit caller metadata that contains control characters or unpaired UTF-16 surrogates is rejected. Defaults derived from authored text never make an export fail. In each defaulted field, control characters become spaces and unpaired surrogates become U+FFFD. An empty required field uses InvariantCAD Shape. When the resolved strings would exceed the metadata budget, the longest defaulted values are truncated at Unicode scalar boundaries until they fit. 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. Exceeding maxOutputBytes, the default output ceiling, or the fixed input, scan, or entity ceilings throws CadError with RESOURCE_LIMIT_EXCEEDED; details.resource names the ceiling and details.limit gives its value. 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.