> ## 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. # DesignBuilder reference > Method-by-method reference for the primary InvariantCAD authoring surface. Create a builder with `design(name, options?)`. Every returned authoring handle is immutable and owned by that builder. ## Document definitions | Method | Returns | Purpose | | ----------------------- | -------------------------- | ---------------------------------------------------- | | `parameter.length` | `Parameter<"length">` | Length default, bounds, label, and description | | `parameter.angle` | `Parameter<"angle">` | Angle parameter | | `parameter.scalar` | `Parameter<"scalar">` | Unitless parameter | | `parameter.massDensity` | `Parameter<"massDensity">` | Density parameter in kg/mm³ base units | | `material` | `MaterialRef` | Named density-aware material definition | | `topologyReference` | `TopologyReferenceRef` | Document-owned detached persistent topology evidence | ## Primitive and profile nodes | Method | Returns | Notes | | ----------------- | ------------ | ---------------------------------------------- | | `box` | `SolidRef` | Positive 3D size; optional centering | | `cylinder` | `SolidRef` | Cylinder or cone/frustum with `radiusTop` | | `sphere` | `SolidRef` | Radius and optional tessellation segments | | `sketch` | `ProfileRef` | Principal plane callback returning one profile | | `polylinePath` | `PathRef` | Open ordered 3D polyline | | `circularArcPath` | `PathRef` | Exact three-point circular arc | | `compositePath` | `PathRef` | Ordered line/arc route | ## Feature nodes | Method | Input | Key options | | ----------- | ------------------ | ------------------------------------------------ | | `extrude` | profile | distance, symmetric, twist, top scale, divisions | | `revolve` | profile | angle, segments | | `loft` | ordered profiles | ruled interpolation | | `sweep` | profile + path | corrected-Frenet, right-corner | | `union` | target + tools | one or more tools | | `subtract` | target + tools | one or more tools | | `intersect` | target + tools | one or more tools | | `transform` | solid + operations | ordered transform list | | `translate` | solid | vector convenience wrapper | | `rotate` | solid | Euler angle-vector wrapper | | `scale` | solid | scalar-vector wrapper | | `mirror` | solid | mirror-plane normal wrapper | | `fillet` | solid | edge selection + radius | | `chamfer` | solid | edge selection + equal distance | | `shell` | solid | face openings + thickness/direction/tolerance | | `offset` | solid | whole-solid distance/direction/tolerance | | `draft` | solid | faces, angle, pull direction, neutral plane | Backend support is checked during evaluation, not authoring. A document may be valid while a selected kernel lacks one of its features. ## Product structure | Method | Returns | Purpose | | --------------- | ------------------------ | ----------------------------------------------------- | | `part` | `PartRef` | Wrap a solid with part/material metadata | | `assembly` | `AssemblyRef` | Define fixed instances of parts or assemblies | | `configuration` | configuration ID | Define parameter, suppression, and material overrides | | `output` | builder | Publish a solid, part, or assembly by output name | | `build` | current `DesignDocument` | Validate authoring closure and emit frozen JSON data | ## Repository-only staged product authoring The source tree contains: ```ts theme={"system"} stagedBodySetDesignV7( name: string, options?: DesignOptions, ): StagedBodySetDesignBuilderV7 ``` This is a deliberately narrow facade for authoring bounded primitive/import/Boolean/transform solid DAGs, acyclic fixed-placement products with one external-document boundary per active path, and datum nodes admitted by the four staged geometry evaluators and the datum resolver. Its implementation lives in `src/internal/document-v7-body-set-authoring.ts`; it is not exported from the package root or any package subpath. The public `design(...)` builder, `DesignDocument` alias, evaluator, and migration target remain on frozen v6. This is repository-only work staged for 0.2, not public 0.1.1 authoring. The facade privately composes the v6 builder for admitted parameters and native primitives, then adds staged configuration, material, resource, imported-body, body-set, part, local assembly, external component, and datum records. Its complete admitted surface is: | Method | Staged result | Boundary | | ------------------------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parameter.length(...)` | `Parameter<"length">` | Length defaults, bounds, labels, and descriptions | | `parameter.angle(...)` | `Parameter<"angle">` | Angle defaults, bounds, labels, and descriptions in the canonical radian base unit | | `parameter.massDensity(...)` | `Parameter<"massDensity">` | Density in the canonical kg/mm³ base unit | | `parameter.scalar(...)` | `Parameter<"scalar">` | Dimensionless defaults, bounds, labels, and descriptions | | `material(id, options)` | `MaterialRef` | Document-owned name, density expression, optional description, and detached metadata | | `configuration(...)` | Configuration ID | Its callback admits typed length/angle/density/scalar `.parameter(...)` overrides, `.partMaterial(part, material)` substitution, and `.instanceSuppressed(assembly, instanceId, suppressed?)` | | `box(...)`, `cylinder(...)`, `sphere(...)` | `StagedBodyLeafRefV7` | Direct primitive leaves with the v6-shaped typed length-expression API | | `resource(id, commitment)` | `StagedResourceRefV7` | Explicit SHA-256 digest, byte length, media type, ordered location hints, and detached metadata | | `importedBody(id, resource, options)` | `StagedImportedBodyRefV7` | Direct STEP or text/binary BREP leaf with a strong single-solid policy | | `union(id, target, tools)` | `StagedSolidRefV7` | Ordered Boolean union of one owned target and one or more owned staged solid tools | | `subtract(id, target, tools)` | `StagedSolidRefV7` | Multi-tool Boolean subtraction that removes the complete authored tool set from one owned target | | `intersect(id, target, tools)` | `StagedSolidRefV7` | Ordered Boolean intersection of one owned target and one or more owned staged solid tools | | `transform(id, solid, operations)` | `StagedSolidRefV7` | One or more ordered translate/rotate/scale/mirror operations over an owned staged solid | | `translate(...)`, `rotate(...)`, `scale(...)`, `mirror(...)` | `StagedSolidRefV7` | Typed one-operation conveniences that can be chained into a solid DAG | | `bodySet(id, members)` | `StagedBodySetRefV7` | Dense non-empty ordered memberships whose roots are owned primitive/import/Boolean/transform solid DAGs | | `part(id, geometry, options?)` | `PartRef` | One owned staged solid DAG root or one owned body set, with part and material intent | | `externalPart(resource, output)` | `StagedExternalPartRefV7` | One named part output in a committed InvariantCAD document, without a local feature node | | `externalAssembly(resource, output)` | `StagedExternalAssemblyRefV7` | One named assembly output in a committed InvariantCAD document, without a local feature node | | `assembly(id, build)` | `AssemblyRef` | Fixed-placement instances of owned local parts, previously completed local assemblies, or owned external component handles through `StagedLocalAssemblyBuilderV7` | | `datumPoint(...)` | Owned datum handle | Parametric position from three length expressions | | `datumAxis(...)` | Owned datum handle | Parametric origin and one scalar direction | | `datumPlane(...)` | Owned datum handle | Parametric origin, scalar positive-X direction, and scalar normal | | `coordinateSystem(...)` | Owned datum handle | Parametric origin plus scalar positive-X and positive-Y directions | | `output(name, reference)` | Builder | Direct imported-body, body-set, part, or staged product-assembly targets | | `build(options?)` | `DesignDocumentV7` | Detached, deeply frozen data accepted by strict v7 parsing and semantic validation | The relevant staged source signatures are: ```ts theme={"system"} parameter.angle( id: string, defaultValue: AngleExpression, options?: ParameterOptions<"angle">, ): Parameter<"angle"> parameter.massDensity( id: string, defaultValue: MassDensityExpression, options?: ParameterOptions<"massDensity">, ): Parameter<"massDensity"> material(id: string, options: MaterialOptions): MaterialRef part( id: string, geometry: StagedSolidRefV7 | StagedBodySetRefV7, options?: PartOptions, ): PartRef union( id: string, target: StagedSolidRefV7, tools: readonly StagedSolidRefV7[], ): StagedSolidRefV7 subtract( id: string, target: StagedSolidRefV7, tools: readonly StagedSolidRefV7[], ): StagedSolidRefV7 intersect( id: string, target: StagedSolidRefV7, tools: readonly StagedSolidRefV7[], ): StagedSolidRefV7 transform( id: string, input: StagedSolidRefV7, operations: readonly TransformOperationIR[], ): StagedSolidRefV7 translate( id: string, input: StagedSolidRefV7, value: Vec3Expression, ): StagedSolidRefV7 rotate( id: string, input: StagedSolidRefV7, value: AngleVec3Expression, ): StagedSolidRefV7 scale( id: string, input: StagedSolidRefV7, value: ScalarVec3Expression, ): StagedSolidRefV7 mirror( id: string, input: StagedSolidRefV7, normal: ScalarVec3Expression, ): StagedSolidRefV7 assembly( id: string, build: (assembly: StagedLocalAssemblyBuilderV7) => void, ): AssemblyRef externalPart( resource: StagedResourceRefV7, output: string, ): StagedExternalPartRefV7 externalAssembly( resource: StagedResourceRefV7, output: string, ): StagedExternalAssemblyRefV7 assembly.instance( id: string, component: | PartRef | AssemblyRef | StagedExternalPartRefV7 | StagedExternalAssemblyRefV7, options?: StagedLocalAssemblyInstanceOptionsV7, ): this interface StagedLocalAssemblyInstanceOptionsV7 { readonly placement?: readonly TransformOperationIR[]; readonly suppressed?: boolean; readonly configuration?: OccurrenceConfigurationIRV7; } configuration.partMaterial(part: PartRef, material: MaterialRef): this configuration.instanceSuppressed( assembly: AssemblyRef, instanceId: string, suppressed?: boolean, ): this output( name: string, reference: | StagedImportedBodyRefV7 | StagedBodySetRefV7 | PartRef | AssemblyRef, ): this ``` Every staged reference is owned by the builder that created it. Resource IDs, parameter IDs, material IDs, configuration IDs, node IDs, output names, and body-member IDs must be valid and unique in their applicable namespace. The facade rejects foreign or forged geometry, material, part, assembly, external-component, resource, and output handles. External handles require an owned resource whose media type is `application/vnd.invariantcad.document+json`; they retain a valid requested output ID and publish no local feature node. The facade constructs canonical references from captured identity rather than dispatching through mutable handle methods. Datum authoring returns owner-bound, frozen handles reserved for later feature consumers; no method in this slice consumes one. A body-set member keeps its stable ID, authored position, optional name, and detached JSON metadata; multiple memberships may deliberately reference the same owned solid DAG root. Every listed member is active, and the facade neither selects nor infers a primary body. A staged part wraps either one owned primitive, imported-body, Boolean, or transformed-solid DAG root, or one owned body set. It cannot wrap another part or assembly, or use a body set, part, or assembly as a Boolean or transform input. `material(...)` authors a document-owned definition with an explicit mass-density expression. `part(...)` accepts the existing `PartOptions` contract: part number, description, detached metadata, optional explicit density, and either a legacy descriptive `material` string or an owned `materialRef`, never both. A configuration can substitute another owned material for an owned part. The selected material determines effective material identity and supplies density when needed; an explicit part density still wins. A legacy label and a material name never perform catalogue lookup. Length, angle, density, and scalar parameters may be specialized by a named configuration and then by bounded caller overrides during evaluation. ### Staged solid Boolean and transform DAGs `StagedSolidRefV7` is the owner-bound handle shared by direct primitive leaves, imported-body leaves, Boolean results, and transform results. `union(...)`, `subtract(...)`, and `intersect(...)` require one target plus a dense, non-empty tool list. Every operand must be a solid handle issued by the same builder. A Boolean result can feed a later Boolean, transform, body-set membership, or part. The evaluator invokes exactly one kernel Boolean with the target plus a frozen tool array in authored order. Backend implementation strategy is kernel-owned, but it may not reorder operands or reinterpret the authored operation. `transform(...)` requires at least one operation and captures its dense ordered operation list as plain own data. `translate(...)`, `rotate(...)`, `scale(...)`, and `mirror(...)` author one typed operation each; their vectors use length, angle, scalar, and scalar expressions respectively. A transform result can feed another transform, a Boolean, body-set membership, or a part's single-solid geometry. The staged evaluator plans the selected closure iteratively, deduplicates shared nodes, and executes every dependency before its consuming Boolean or transform. `maxDistinctSolids` counts primitive and imported leaves. `maxSolidGraphNodes` counts all distinct admitted solid nodes, `maxSolidDependencyLinks` counts every transform input edge plus every Boolean target and tool edge, including repeated tool references, and `maxTransformOperations` counts the ordered operations stored on distinct transform nodes. Each defaults to `100,000` in the staged body-set, part, and product-assembly evaluators. Transform expressions must resolve to finite values. Scale components must be nonzero, and a mirror normal must be finite and nonzero. The selected kernel must advertise and implement `transform`; each transform must return a fresh, valid, positive-volume owned shape. Failure is transactional and releases all shapes created for the graph. The selected kernel must advertise the `boolean` feature and implement the Boolean method before resource resolution or shape acquisition. Every created node must return a fresh, valid owned shape. A subtraction or intersection that returns a null shape or exactly zero volume fails with `EMPTY_RESULT`; an impossible empty union, negative/non-finite volume, or any returned shape that aliases an owned operand or earlier result fails as a kernel protocol violation. Repeated authored operand references remain allowed and are charged as separate dependency edges. Staged evaluation has no `allowEmpty` option. Failure is transactional and releases every acquired intermediate exactly once. Stock OCCT evaluates this graph as exact B-Rep geometry and retains its normal per-solid topology/native-export capabilities. Its Boolean history remains partial unless an owned facade honestly advertises the existing feature-scoped exact indexed-evolution protocol for `boolean`. A present malformed exact-evolution envelope fails before resource or kernel work rather than silently downgrading history. That promise covers the current Boolean operation; it does not upgrade partial history already carried by an imported or otherwise partial operand, and `exact: true` describes geometry rather than complete persistent history. Manifold evaluates native primitive/Boolean/transform graphs as approximate mesh geometry and exposes no topology snapshots. The evaluator never retries an exact failure on Manifold or silently converts an exact graph to a mesh graph. Any imported leaf, transformed or Boolean-composed, additionally requires the strong exact B-Rep single-solid document-import capability, so it cannot fall back to Manifold's weak or absent import path. This is not general shape algebra. A transform input must be an owned `StagedSolidRefV7` created by a primitive, imported body, Boolean, or prior transform, and the same restriction applies to every Boolean operand. A body set, part, or assembly cannot be Boolean-composed or transformed. A generic Boolean or transformed solid also cannot be published directly by `output(...)`: it must be retained by a body set or part. The one exception to generic-solid output is the narrower direct `StagedImportedBodyRefV7` output already admitted by the import evaluator. ### Fixed-placement products The staged `assembly(id, build)` method passes one `StagedLocalAssemblyBuilderV7` to its callback. Each `instance(...)` in this slice references an owned local part, an already-completed owned local assembly, or an owned external-part or external-assembly handle. A local assembly handle is published only after its callback succeeds, so the facade can reference earlier local definitions but cannot author a local cycle. Foreign or forged handles are rejected. `externalPart(resource, output)` and `externalAssembly(resource, output)` require a committed InvariantCAD-document resource owned by the same staged builder. They select a valid named part or assembly output without publishing a local feature node. Product evaluation admits the committed child document before child geometry work. A selected external assembly may contain child-local parts and bounded nested local assemblies; each active occurrence path may cross only one external-document boundary. An instance ID is stable within its containing assembly. Evaluation joins those IDs into a full root-to-leaf path for each emitted part occurrence. Its placement is an ordered list of translate, rotate, scale, or mirror operations, and its configuration selector is exactly one of: * `inherit`, which evaluates a local component in the containing assembly's context and maps root base to child base or a root named ID to the same ID in an external document; * `base`, which evaluates a local component in the root base context or an external component in the child base context; or * `named`, which selects the referenced configuration in the applicable root or child document. Omitted instance options mean an empty placement, `suppressed: false`, and `{ mode: "inherit" }`. The configuration active for every containing assembly controls its definition-scoped instance suppression and placement expressions. `configuration.instanceSuppressed(...)` can target any owned assembly definition. Passing `false` explicitly unsuppresses an instance authored with `suppressed: true`; omission retains the authored value. Suppression is resolved before component support is checked, so suppressing an assembly edge prunes its entire subtree, including external or otherwise unsupported descendants. A suppressed nested external component therefore performs no descendant resolution or kernel work. An active direct external part or fixed subassembly is supported, but an active external descendant inside the admitted child would cross a second document boundary and is rejected before nested resolution or child geometry/kernel work. Occurrence IDs are unique only within their containing assembly. Repeating one part or subassembly in several instances is expected and does not copy its document definition. Iterative evaluation expands active assemblies in authored depth-first leaf order and composes edge placements parent first. Bounded caller parameter overrides apply to root-document contexts only and never cross an external boundary. Per-occurrence `inherit`, `base`, and named selection can therefore produce different geometry, material, or density from a shared part definition. Evaluation reuses local parts for equal `(part, effective configuration)` states and direct external parts for equal `(resource, output, child configuration)` states. Fixed-subassembly leaves share geometry by resource, child part node, and child configuration; distinct assembly output aliases retain separate component, diagnostic, and BOM identity. Direct part evaluation may additionally deduplicate solid-DAG acquisition within a configuration batch. Authoring does not create a persistent or cross-run cache commitment. Product evaluation separately bounds nesting with `maxAssemblyDepth` and the aggregate stored leaf-path length with `maxOccurrencePathSegments`, in addition to its external-document, instance, occurrence, placement, contextual-part, solid, material, document, and resource ceilings. Solid-graph nodes, all solid dependency edges, and transform operations are counted globally across the active product. Repeated occurrences in the same effective context reuse that work, different contexts are charged independently, and suppressed subtrees are pruned before these counters advance. Hand-authored cyclic local dependencies fail strict document admission, and evaluation also rejects a recursive path rather than looping. The four datum methods author ordinary Document v7 nodes with stable node IDs. A point carries a length-valued position. An axis adds one scalar direction. A plane adds scalar positive-X and normal directions, while a coordinate system adds scalar positive-X and positive-Y directions. Their owned handles establish builder identity, but datums are not admitted by `output(...)`: callers pass datum node IDs to the separate source-only datum resolver. That resolver is kernel-independent, normalizes admitted directions, and returns deterministic orthonormal right-handed frames. It rejects non-finite or zero directions and requires each normalized authored direction pair to have an absolute dot product no greater than `1e-12` before deterministic re-orthonormalization. Authoring a datum does not yet make it usable as a sketch plane or shape-algebra input. A resource commitment describes bytes that an application resolver may later supply. Its ordered `locations` are hints only: authoring and evaluation never dereference them. The facade does not read bytes or compute a digest or byte length; the caller supplies those commitments. The imported-body method, rather than `mediaType`, chooses the reader. STEP always uses `{ mode: "from-file" }`. Text and binary BREP require `{ mode: "declared", length: "mm" | "cm" | "m" | "in" }`. All staged imports emit `{ healing: { mode: "none" } }` and `expected: "single-solid"`; there is no healing switch, weak-import fallback, or automatic exact-to-mesh conversion. `build({ limits })` accepts a partial `DesignDocumentLimits` override and strictly parses the completed document. A failed strict result is raised as a `CadError`; no invalid document escapes. During authoring, resources also use the current default ceilings of `10,000` definitions, `100,000` aggregate location hints, and `16 MiB` of aggregate UTF-8 location text. One `bodySet(...)` call is additionally rejected before copying if it exceeds the default `1,000,000` structural-value ceiling, and one instance placement cannot contain more operations than that ceiling. The completed assembly instance list is charged to `maxStructuralValues` during build. Final build limits can be stricter; they do not raise these immediate safeguards. Authoring methods fail immediately when a handle comes from another builder, a namespace is duplicated, a required collection is sparse or empty, member IDs repeat, a commitment is malformed, a configuration references foreign definitions, an immediate authoring ceiling is exceeded, or a parameter, configuration, material, part, assembly instance, placement, resource, import, unit-policy, datum, or body-member option record contains an accessor or unknown field. Those inputs must be plain own-data records; required arrays must be dense own-data arrays. Accessors are not invoked and unsupported semantics are rejected rather than silently discarded. Build then applies caller-selected document limits and strict v7 validation before returning the detached, recursively frozen document. This facade does not author generic solid or direct primitive outputs, recursive external-document graphs, cyclic local assembly graphs, datum-backed sketches, Booleans over body sets/parts/assemblies, transforms over body sets/parts/assemblies, other body-consuming features, per-body materials, or general solid graphs beyond primitive/import/Boolean/transform DAGs. It also does not add datum design outputs, CLI support, location I/O, reader inference, healing, a primary-body rule, cross-body or assembly topology, aggregate geometric measurement, mates, motion, interference/collision, or exact aggregate STEP/BREP export. Part- and product-level STL/OBJ export is an aggregate tessellation view and is explicitly approximate/lossy; exact native export and topology remain per-solid or per-body capabilities. These omissions are product boundaries, not implicit fallbacks. The staged facade remains repository-only work for 0.2, and the public 0.1.1 document alias remains v6. ## ID rules All IDs use the shared stable ID grammar and must be unique in their namespace. Avoid generated array positions or user-facing labels that may change. Prefer IDs such as `housing-side-a`, `left-bearing-seat`, and `manufacturing-assembly`. ## Programmer errors Methods throw `TypeError` or `RangeError` for invalid direct calls, including: * duplicate or malformed IDs * references from another builder * wrong-dimensional expressions * wrong topology kind * invalid option enum/literal values * empty required lists * non-positive tolerances * references targeting the wrong direct solid These failures indicate an invalid model definition or unvalidated UI input, not a geometry-kernel failure.