ParaShape

Model JSON

The persisted schema is the set of Rust serde structs in crates/model/src/document, with ModelJson as the root. The TypeScript types are generated from them by ts-rs into packages/model/src/generated; nothing is declared by hand. Every shape rejects unknown keys, so a misspelled field fails validation instead of being ignored.

Document shape

ModelJson = { version?, title, description?, settings?, materials?, layers?, patterns?,
              parameters?, behaviors?, objects?, views?, components?, onClick? }
FieldMeaning
titlePlain text, verbatim.
descriptionVerbatim allowlisted HTML or plain text; never a parameter.
versionThe platform's publish counter. 0 means never published; a save never changes it.
settings{ units?, environment? }. Absent units means millimetres; the unit only changes how a host displays lengths.
parametersRoot parameters: the values a user can change. See Parameters and expressions.
objectsThe objects of the model. See Objects and components.
behaviorsStanding acts on the siblings of the document's objects (an opening that cuts a wall).
materials, layers, patternsRecord lanes referenced by key.
viewsCamera records. The views lane is in the schema, but no surface lists or edits views and the viewport uses the free camera.
componentsDocuments this document places, as functions of their parameters.
onClickAn expression evaluating to click actions for the root parameters.

The document type is derived and never stored: a document that has only materials or only patterns is a library, anything else is a component. Internal units are millimetres, Z is up, rotations are in degrees.

One shape for every node

Every node in every lane has the same shape:

{ method, args?, steps?, properties?, behaviors?, objects? }   // plus chrome: key?, label?
FieldHolds
methodA method of the catalog.
argsArguments, matched by key, each an expression string.
stepsA chain: steps run in order and the data kind may change mid-chain. Steps have no keys.
objectsKeyed nodes: the body of a nest, of the root, of a component.
propertiesPaint, identity, placement and onClick of one object. Each method appears once; copies repeats the placement.
behaviorsActs on siblings. Blocks only; each method once, except opening, which may repeat (one cut per entry).

There is no enabled, locked, flag, cache or fifth body. A node with a key is addressable across the whole model, and there is one key namespace per document across all lanes; renaming a key rewrites every reference.

Arguments

An argument is { key, input }. input is an expression string: a literal ('20', '[0,0,0]'), a parameter name, or any expression over parameters and the stream. Arguments are matched by key, not by position. Text literals use single quotes. An argument that is JSON array or object text, or exactly one quoted string literal, is data and is exempt from the expression length and step budgets.

Steps: the chain

An object's steps form one chain over one data kind at a time. Producers create geometry or records (a rectangle, a circle, a mesh literal, a placed component). Transforms take the stream and return it changed; they carry their input type as a prefix: curve*, face*, solid*, vertex*, mesh*. Curve booleans are 2D and per plane; solid* booleans are 3D and need closed, outward-oriented operands. The evaluated shapes are Curve (N unshared chains) and Mesh (vertices, edges, faces), and every mesh is a closed solid or empty.

Two shapes are final: Curve { vertices, edges } and Mesh { vertices, edges, faces }. A face has loops: loops[0] is the outer loop, the rest are holes, even-odd, planar within tolerance and simple at load.

Properties: placement and appearance

An object has two tiers: the definition (steps or objects, in the object's local frame) and the instance (properties). The twelve placement scalars are translateX/Y/Z (mm), rotateX/Y/Z (degrees), scaleX/Y/Z and pivotX/Y/Z, composed as M = T(t) T(p) Rz Ry Rx S T(-p). Defaults: translate 0, rotate 0, scale 1; an absent pivot axis is the content's bounding-box minimum on that axis (0 for a chain-produced block). There is no vector translation, rotation, scale or pivot property.

Every instance property accepts a per-copy arrow (i) => ... where i is the copy index. copies is the number of copies added. visible is true, false, a list of view keys, or the arrow (i) => boolean, or (i, camera) => boolean when a model chooses to read the camera. Other instance properties: name, material, layer, attributes (engine-blind third-party data) and onClick.

Behaviors

behaviors act on the siblings of their block after the set evaluates. opening cuts every mesh of its siblings, including meshes inside a placed component or nest at any depth, through the composed placements: one extruded profile and direction per entry, each cutting on its own. faceCamera may appear at most once. A behavior never leaves its set. A cut travels as a behavior (the document root's behaviors), never as a placement argument.

Click actions

An object's onClick (or the root onClick) evaluates to one action or an array of actions: Property.animate(name, seconds, [v1...vn]) tweens a numeric property and Property.set(name, [v1...vn]) switches a value. The engine never plays them: it returns plain data and the host executes it. Click state and pose overrides are session state, never document fields. Time is not a document fact: there are no keyframes, timeline or clock.

Validation

engine_load rejects a document with error diagnostics and returns warnings as Changes.diagnostics. Publishing additionally runs the audit (engine_audit): four ordered stages (static, evaluated, settled, shells), the first stage with findings stops the pipeline, and every finding blocks. The closed code list is in the Engine API.

  • A createBlock nest with no properties and no behaviors is the static finding bare_nest: a nest exists to carry a placement, copies, paint, visibility, a click action or behaviors for its children.
  • A declared sizeX/Y/Z must equal the visible box's extent on its axis, and a settable size must drive the box (size_mismatch, size_not_driven).
  • A consumer model's visible bounding box must contain the origin, the attachment point (origin_outside_box).
  • One closed shell must not cross itself (self_intersect). Parts may pass through each other.

Edit on GitHub