> ## Documentation Index
> Fetch the complete documentation index at: https://invariant-cad.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Parts, materials, and assemblies

> Define reusable parts, density-aware materials, fixed occurrences, nested assemblies, and outputs.

## Parts

A part wraps a solid with manufacturing identity and optional physical data:

```ts theme={"system"}
const aluminum = cad.material("aluminum-6061", {
  name: "6061-T6 Aluminum",
  massDensity: kgPerCubicMeter(2700),
  description: "General-purpose machined aluminum",
  metadata: { standard: "ASTM B221" },
});

const bracket = cad.part("bracket", bracketSolid, {
  partNumber: "INV-BRACKET-001",
  description: "Parameterized mounting bracket",
  materialRef: aluminum,
  metadata: { finish: "clear anodize" },
});
```

A material definition is document-owned and can be referenced by many parts.
Alternatively, a part can provide a direct `massDensity` expression or a legacy
descriptive `material` label. A label is not resolved against the material
registry and does not supply density.

## Fixed-placement assembly

```ts theme={"system"}
const pair = cad.assembly("bracket-pair", (assembly) => {
  assembly.instance("left", bracket);
  assembly.instance("right", bracket, {
    placement: [
      tf.translate(vec3(mm(100), mm(0), mm(0))),
      tf.rotate(angleVec3(deg(0), deg(0), deg(180))),
    ],
  });
});
```

Instances reference part or assembly definitions; they do not duplicate their
component nodes. Placement operations execute in order. An instance can be
suppressed by default with `{ suppressed: true }`.

## Nested assembly

```ts theme={"system"}
const machine = cad.assembly("machine", (assembly) => {
  assembly.instance("front-pair", pair);
  assembly.instance("rear-pair", pair, {
    placement: [tf.translate(vec3(mm(0), mm(200), mm(0)))],
  });
});

cad.output("machine", machine);
```

Evaluation walks the occurrence tree, composes placement transforms, and
preserves a stable instance path for each evaluated occurrence.

## Evaluated occurrences

An evaluated assembly provides occurrence data, aggregate measurements,
physical mass properties when densities are resolvable, mesh/export views, and
a deterministic bill of materials.

```ts theme={"system"}
const output = result.value.output("machine");
if (output instanceof EvaluatedAssembly) {
  console.log(output.instances);
  console.log(output.billOfMaterials());
  console.log(output.measure());
}
```

Assembly measurements apply every occurrence placement and aggregate component
geometry. Shared definitions still contribute once per unsuppressed occurrence.

## Current boundary

Assemblies in 0.1 use fixed authored placements. There is no mate/joint solver,
degrees-of-freedom analysis, motion study, contact, or interference engine yet.
Those are planned as separate protocols rather than hidden behavior inside
fixed transforms.

## Repository-only staged fixed-placement products

The staged facade provides a source-only `assembly(...)` authoring method. Its
callback receives a `StagedLocalAssemblyBuilderV7` and can add fixed-placement
instances of owned local parts, already-completed local assemblies from the same
builder, direct external-part handles, or external-assembly handles. Requiring a
local referenced assembly to be complete makes facade-authored local nesting
acyclic by construction.

`externalPart(resource, output)` binds one named part output from a committed
InvariantCAD document. `externalAssembly(resource, output)` binds one named
assembly output. Neither handle publishes a local feature node. Staged
assemblies can be published as product outputs and selected through
`evaluateProductAssemblyOutputsV7(...)`; the historical local evaluator/result
names remain source aliases during staging. This entire capability is
repository-only work for 0.2. It is not available from the public 0.1.1 package
root, a package subpath, the public evaluator, or the CLI.

Evaluation expands the active root-local graph iteratively. A direct external
part contributes one part leaf. A fixed external subassembly first admits its
committed child document, requires the selected output to directly reference an
assembly, and then expands that assembly's child-local parts and nested local
assemblies in authored depth-first order. Every emitted occurrence retains its
full root-to-leaf instance path; its `id` is the final path segment, while the
complete path supplies stable identity independent of array position or
geometry.

Every leaf part must use geometry admitted by the direct staged part evaluator:
one supported primitive/import/Boolean/transform solid DAG root or one supported
body set, including commitment-verified imported leaves. This product boundary
does not widen the child part feature families.

The configuration active at each containing assembly controls that definition's
instance suppression and placement expressions. A named
`configuration.instanceSuppressed(assembly, instanceId, false)` can explicitly
activate an instance authored as suppressed in that assembly definition. Each
active edge then selects `inherit`, `base`, or a named configuration for its
referenced component. For an external edge, `inherit` maps root base to child
base or a named parent ID to the same ID in the child; `base` and `named` select
the child directly. Descendant selectors are interpreted inside the child
document. Root caller parameter overrides never cross the external boundary.
Placement operations execute in authored order on each edge, then nested
placements compose parent first so every returned matrix is root-relative.

Repeated local instances retain distinct full paths and quantities while
reusing one evaluated part result for equal part/configuration contexts. Direct
external parts reuse equal resource/output/configuration contexts. Leaves
reached through a fixed subassembly share geometry by resource, child part node,
and child configuration; distinct assembly output aliases retain separate
component, diagnostic, and BOM identity. None of those rules creates a
cross-run cache or geometric-equivalence guarantee.

The product result retains ordered active occurrences and their configuration,
material, density, and placement evidence. External occurrences additionally
retain committed component-document evidence. Exact child solids keep
capability-gated per-solid or per-body topology and native export.
Whole-product mesh, binary/ASCII STL, and OBJ are merged placed tessellations
and therefore approximate/lossy even when every retained leaf is exact.
Contextual BOM and physical-mass operations count every occurrence and every
multibody membership, transform mass properties by placement, and never fuse
overlaps or subtract interference.

Traversal is bounded independently by `maxAssemblyDepth` and the aggregate
`maxOccurrencePathSegments` stored across emitted leaves, in addition to the
selected-output, external-document, scanned-instance, active-occurrence,
placement, contextual-part, solid, material, document, and resource ceilings.
Suppression is resolved before descendant admission and prunes an entire nested
subtree, so an effectively suppressed external descendant is inert and charges
no descendant traversal or resolution work.

Each active occurrence path may cross at most one external-document boundary.
Child-local parts and nested local assemblies are supported, but an active
external descendant fails before nested resolution or child geometry/kernel
work. Cyclic local-assembly graphs are also unsupported: the staged facade
cannot construct one, strict document admission rejects hand-authored dependency
cycles, and evaluation fails closed if one reaches traversal. Mates, joints,
DOF, motion, contact, interference, collision, assembly topology, aggregate
geometric `measure()`, and exact aggregate STEP/BREP remain unsupported.

## Ownership rules

Parts, materials, assemblies, and components must belong to the same
`DesignBuilder`. Instance IDs are unique within their containing assembly and
are part of configuration suppression keys, so keep them stable across design
revisions.