Objects and components
Objects
ObjectNode = { key, label?, method: createObject | createBlock, args? (always empty),
properties?, behaviors?, steps? | objects? }createObject has a body of steps and produces geometry. createBlock is a nest: its body is objects, it shares the parent's scope, and it exists to carry a placement, copies, paint, visible, a click action or behaviors for the objects under it. key is required and unique in the document. Record kinds such as dimensions, leaders, hatches, images and sections are producer steps. clone(source) and placeComponent(component, parameters) are producer steps that yield a block and carry no placement argument.
Names: an object is one objects[] entry, a nest is a createBlock, a component is a components[] entry placed by placeComponent, and a block is an evaluated nest or placed component.
Components
A components[] entry is a function: isolated, values enter through arguments, and it evaluates to a whole ModelJson. createComponent takes the document inline as data; loadComponent takes an https url, always resolving to the latest published version. placeComponent(component, parameters) places one by the key of the enclosing lane.
parametersmay be an arrow(copy) => ({ sizeX: widths[copy] }), called with the copy index, so one placement can vary per copy.- A key in
parametersthat names an object of the placed document routes to that object's own overrides, at any depth. - A placed document's own
componentslane is private. Its materials, layers and patterns join the host's lanes after the host's own; views and settings are ignored. - A component is read-only to the host:
lib.objectsis an error, and a host reads only the records andoptionsrows a part publishes. - Resources resolve lazily: an unresolved url is reported in
Changes.pendingand the step reports 'is loading' until the host delivers the document throughengine_add_components. The engine never performs IO. - A url placed inside itself fails by name, and nesting is bounded by the document depth limit.
Materials, layers and patterns
materials, layers and patterns are node lanes. A record's key is its identity; a reference argument (material, layer, pattern) is an expression that evaluates to the record's key, and deleting a record that is still referenced is refused. A material resolves with catalog defaults for every field (base color, tile size, roughness, metallic, opacity), so a reader never substitutes its own. A layer carries properties.visible; a pattern is a hatch pattern, and the .pat text codec is available as an engine door.
A library document holds only materials or only patterns. A library placed as a component joins the host's records first-wins after the host's own, and a chooser can list a library's records with options: 'library.materials'.
Views
A view is one node, method view, with position, target, up, projection, field of view and height. The active view is session state and never a document field. Objects and layers choose what a view shows through their own visible property (All, a list of view keys, or a camera arrow).
Where each concept is specified
| Concept | Source in the repository |
|---|---|
| Laws and the settled model JSON | AGENTS.md |
| Concepts: expressions, components, objects, behaviors | spec/architecture/concepts.md |
| Persisted schema | crates/model/src/document |
| Per-method behavior | spec/requirements/catalog-geometry.md, spec/requirements/catalog-data.md |
| Expression grammar | spec/requirements/expression.md |