Skip to main content
Configurations are definition-scoped named overrides stored inside the design document. They do not clone the feature graph.

Complete executable workflow

This canonical module builds a two-instance assembly, selects a named configuration that changes its width, suppresses one occurrence, substitutes its material, and verifies the resulting BOM.
The release gate compiles and executes the source module from examples/docs/assembly-configuration-bom.ts. A configuration must contain at least one override; duplicate overrides inside one configuration are rejected during authoring. After serialization, applications select the same variant by its stable ID:
EvaluatedDesign.configurationId records the active configuration or is null for the default document context.

Override categories

Configuration overrides are definition-scoped. If the same subassembly is instanced twice, suppressing an instance inside that subassembly definition affects both placements. Per-occurrence effectivity is roadmap work.

Deterministic BOM

The BOM:
  • excludes suppressed occurrences
  • groups shared part definitions deterministically
  • rolls nested quantities through the occurrence tree
  • includes part number, description, material identity, density source, occurrence IDs, and mass information when available
  • composes affine placement for physical-property aggregation
Missing density does not invent a zero mass. Physical-property methods return a diagnostic result explaining which part or material prevented a complete rollup.

Repository-only Document v7 part authoring and evaluation

The source tree contains a staged authoring and evaluation path for Document v7 outputs that directly reference a part. stagedBodySetDesignV7(...) now exposes source-only length, angle, mass-density, and scalar parameters; union(...), subtract(...), and intersect(...) solid authoring; transform(...), translate(...), rotate(...), scale(...), and mirror(...) solid authoring; material(...); part(...); configuration .partMaterial(...); and direct part output(...). This is executable protocol evidence, not a public package workflow: the package-root builder, document alias, evaluator aliases, CLI, and migration target remain v6. A staged part’s geometry must be one owned solid DAG rooted in a box, cylinder, sphere, or imported-body leaf, or one owned body set composed from those solid DAG roots. Internal solid nodes are target-first, authored-tool-order Booleans or ordered transforms. Primitive, imported, transformed, or prior Boolean solids can feed a Boolean; Boolean and transform results can feed one another. Transforms can be chained and parameterized by length, angle, or scalar expressions. Parts cannot wrap another part, and the facade does not admit a body set, part, or assembly as a Boolean or transform input. Materials and parts are builder-owned typed handles; foreign or forged handles are rejected. New option records must be exact plain own-data records, and accessor-backed or unknown fields are rejected without invoking them. Part, material, configuration, and membership metadata is detached before the document is deeply frozen. The staged result preserves part number, description, detached metadata, legacy material label, effective material definition, density, and density source. Its geometry is explicitly either one retained solid or one retained body set; the evaluator never chooses a primary body. Named configuration material overrides select the effective material identity. Authored or configured density parameters resolve in the selected configuration and may be further specialized by bounded caller overrides. An explicit part density takes precedence over the effective material’s density, while a legacy material label and material name remain descriptive and never supply inferred density. billOfMaterials() returns one deterministic part row with quantity one. Missing density leaves its mass incomplete and produces a warning rather than inventing zero. physicalMassProperties() requires one finite positive density and, for a body set, applies it uniformly to every authored membership before combining independent-body mass, center of mass, and inertia. Shared solid aliases and spatially overlapping bodies each count once per membership—the operation performs neither deduplication nor a Boolean union. The numeric properties inherit the selected geometry backend’s measurement quality. The part facade can merge tessellations and export STL or OBJ, all explicitly approximate/lossy. Exact export and topology remain per-solid or per-body capabilities. Aggregate geometric measurement, cross-body topology, exact aggregate STEP/BREP, assemblies, occurrence rollups, interference handling, per-body materials, Boolean/transform inputs that are body sets, parts, or assemblies, and general part graphs beyond primitive/import/Boolean/transform DAGs are outside this staged slice. A primitive, Boolean, or transformed solid cannot be a direct staged output; it must be retained by a part or body set. Stock OCCT evaluates native and imported Boolean/transform DAGs as exact B-Rep when every imported leaf satisfies the strong exact single-solid document-import contract. Stock Boolean history is partial; a matched owned facade supplies complete bounded evolution for the current Boolean only when it proves the feature-scoped protocol, without upgrading partial operand history. Manifold evaluates native primitive/Boolean/transform DAGs as approximate mesh geometry with no topology snapshot and cannot stand in for the import boundary. Evaluation never falls back between the two backends. Body-set and part evaluation separately bound distinct leaves, all solid-graph nodes, every Boolean target/tool and transform input edge, and authored transform operations with maxDistinctSolids, maxSolidGraphNodes, maxSolidDependencyLinks, and maxTransformOperations. A present malformed exact-evolution capability envelope fails before resolver or kernel work; it is not silently treated as partial history.

Repository-only staged product assemblies

The staged facade can wrap admitted local parts and already-completed local assemblies in an acyclic fixed-placement graph through assembly(...). externalPart(resource, output) binds one named part output from a committed InvariantCAD document, while externalAssembly(resource, output) binds one named assembly output for fixed-subassembly placement. The source-only evaluateProductAssemblyOutputsV7(...) operation evaluates the resulting product. A staged configuration can call instanceSuppressed(assembly, instanceId, suppressed?); the configuration active for each containing assembly overrides that definition’s authored suppression, and false reactivates an instance authored as suppressed. This entire section describes repository-only work staged for 0.2. It is not available from the public 0.1.1 package root, a package subpath, the public builder/evaluator, or the CLI, and the public document alias and migration target remain v6. Each staged instance carries one child configuration selector. Local and external components interpret the same selector at different document boundaries: For a direct external part, the chosen child context controls that part’s geometry, material, density, and product intent. For a fixed external subassembly, it establishes the selected child assembly context; configuration selectors on child-local descendants are then interpreted inside the child document. Child configuration suppression and placement expressions apply to their own assembly definitions. Root caller parameter overrides specialize selected contexts in the root document only. They never cross the external document boundary, so a same-named child parameter keeps the value defined by the child’s base or named configuration. A selected child configuration that does not exist returns CONFIGURATION_MISSING with parent occurrence and child configuration-path provenance after document admission and before geometry work; evaluation does not fall back to base. Active part leaves retain full root-to-leaf occurrence paths, including all segments inside a selected external subassembly. Placement operations execute in authored order on each edge and compose parent first into a root-relative transform. Local parts reuse one evaluated result for equal (part, effective configuration) states. Direct external parts reuse one result for equal (resource, output, effective child configuration) states. Leaves reached through an external subassembly reuse geometry by (resource, child part node, effective child configuration). Neither rule collapses occurrences or quantities, and neither is a cross-run cache or geometric-equivalence claim. Different child output names retain distinct component, diagnostic, and BOM identity even when both select the same part or assembly and share evaluated geometry. The contextual BOM keeps unlike component/configuration states in separate, deterministically ordered rows. A local component records its part node. An external component additionally records the committed document resource, digest, byte length, requested output and output kind, admitted source version, and child part node. One external assembly may therefore contribute several BOM rows, one for each distinct child part/configuration state. Repeated occurrences of the same external output and child context aggregate quantity normally; distinct output aliases retain separate BOM rows. Every row records stable occurrence paths, effective material and density provenance, definition mass, placed total mass, and quantity. Missing density leaves the affected row and overall total incomplete, with diagnostics instead of an invented zero. Physical mass applies each context’s density to every single- or multibody part membership, then uses the root-relative affine placement before combining mass, center of mass, and inertia. The numeric result inherits backend measurement quality rather than gaining an independent exactness guarantee. Aliases and overlaps still count per authored membership and occurrence; this is not interference subtraction or a Boolean union. Suppression is decided before descendant admission, so a suppressed edge prunes its entire subtree without resolving its external document. Traversal is bounded by maxAssemblyDepth, maxOccurrencePathSegments, scanned-instance, active-occurrence, placement, contextual-part, maxExternalDocuments, and downstream document/part/resource ceilings. Solid nodes, Boolean target/tool and transform input edges, and authored transform operations remain bounded across the active product. Repeated occurrences in one effective context share that work, different contexts are charged independently, and suppressed subtrees contribute nothing. A direct external output must be a part admitted by the staged part evaluator. An external-assembly handle must select a direct assembly output; that child may contain bounded acyclic local parts and nested local assemblies whose leaves are admitted by the same part evaluator. For example, a migrated v6 part backed by an extrusion still fails with EVALUATION_UNSUPPORTED before child geometry or scoped resource work rather than silently widening the supported feature set. Each active occurrence path may cross at most one external-document boundary. A suppressed nested external component is inert, while an active one is rejected before nested resolution or child geometry/kernel work. Recursive external products, cross-document parameter overrides, per-body materials, mates, joints, DOF, motion, contact, interference/collision, product topology, aggregate geometric measurement, and exact aggregate STEP/BREP export remain unsupported. Product mesh, binary/ASCII STL, and OBJ are approximate/lossy aggregate tessellation views.

Runtime parameter overrides

Explicit EvaluationOptions.parameters can further specialize the selected configuration. This is useful for one-off builds without adding a permanent named variant. Keep named release/manufacturing variants in the document when they need reviewable identity and repeatability.

Impact and caching contexts

Each named configuration is an independent effective evaluation context for design-impact and feature-hash analysis. A material or suppression change may affect only some contexts. See design impact and hashes.