Engine API
The engine is the Rust crate crates/model compiled to wasm. It exposes a set of functions called doors (engine_*, in crates/model/src/wasm.rs). packages/model wraps them in a typed client and a reflected view. The lists on this page are generated from those sources at build time.
Rules of the engine
- The engine never waits and never does IO. A missing font or component is a
ResourceRequestinChanges.pending; the host fetches it and hands it back throughengine_add_fontorengine_add_components. - A mutating door returns
Changes. Every other door is a read-only or session-free preview with no history step. engine_takeoffis the single measurement path;engine_auditis the single blocking-check path.- There is one JavaScript boundary pair,
to_jsandfrom_js, a native JSON round trip. Render buffers travel as zero-copy typed arrays. - No geometry is computed in TypeScript.
packages/modelmirrors a door's result.
The Changes contract
Mutating doors (engine_load, engine_add_*, engine_set_*, engine_node_edit, engine_end_group, engine_undo, engine_redo) return Changes, the diff since the last snapshot. Each field is classed in its doc comment: geometry, identity, intent or derived; a door response carries derived fields unless they are geometry or identity. The definitions below are the generated TypeScript types.
/**
* The diff every door hands back. `nodes`/`removed` are only what changed;
* `render` lists only objects whose cells or placements changed, including
* `cells: Some([])` when a remaining node drops out of `scene()`; a deleted
* object appears in `removed`.
*/
export type Changes = {
/**
* derived — the node states that changed since the last snapshot.
*/
nodes: Array<NodeState>,
/**
* identity — ids of nodes that no longer exist.
*/
removed: Array<number>,
/**
* derived — objects whose cells or placements changed.
*/
render: Array<RenderChange>,
/**
* derived — every layer's visibility under the current sight, resolved
* by `Model::hidden_layers` (the rule `render::placement_shown` merges
* into `Instance.visible`); the full list on every rendering snapshot,
* absent on a flags-only `Changes` and on a session that does not render.
*/
layers?: Array<LayerVisibility>,
/**
* derived — findings resolved off the current document.
*/
diagnostics: Array<NodeDiagnostic>,
/**
* derived — the resolved lanes, only when they differ from the last
* snapshot shipped.
*/
lanes?: Lanes,
/**
* derived — the document after a structural edit, a key rename, a
* settings write or a record-lane arg/label write (`ships_document`);
* absent when only a node-graph arg or label changed.
*/
document?: ModelJson,
/**
* derived — `EditHistory.past` is non-empty.
*/
canUndo: boolean,
/**
* derived — `EditHistory.future` is non-empty.
*/
canRedo: boolean,
/**
* identity — the session's active view key; absent = the free camera.
*/
activeView?: string,
/**
* derived — every resource a step is waiting on right now, deduplicated;
* the host fetches each and hands it back through `engine_add_font` /
* `engine_add_components`.
*/
pending: Array<ResourceRequest>,
/**
* derived — `ModelJson::document_type` of the session's document.
*/
documentType: DocumentType, };Render sync
Changes.render lists one RenderChange per object whose cells or placements changed. cells: null means geometry is unchanged, so a placement-only edit never re-tessellates. Every object at any depth ships its own RenderChange, with parent naming the nest above it. Repeated geometry is referenced: local geometry plus a per-cell transform, with byte-identical buffers shipped once. A hidden object is not drawn and not handed to a host.
/**
* One object's render diff. `cells` is `None` when tessellation is unchanged,
* `Some([])` when the object left `scene()` while its node stayed.
* `placements` is the current instances. A deleted object is in
* `Changes.removed`, not a missing render entry.
*/
export type RenderChange = {
/**
* identity — the object node this diff belongs to.
*/
object: number,
/**
* identity — the `createBlock` nest this object's node sits in; absent
* at the root. A nest is the SAME mechanism as the model root containing
* objects, recursively: every object node at any depth ships its own
* `RenderChange`, `parent` naming the nest one level up.
*/
parent?: number,
/**
* geometry — `None` when tessellation is unchanged; `Some([])` when the
* object left `scene()` while its node stayed, or every placement of it is hidden.
*/
cells: Array<RenderCell> | null,
/**
* geometry — this object's current instance matrices (plus per-instance
* paint/identity), always shipped current.
*/
placements: Array<Instance>,
/**
* geometry — this object's resolved placement pivot
* (`graph::property::place`), this object's own local frame BEFORE
* placement — a record resolves the same way: bbox min corner when its
* content has one (Image, Leader), else ORIGIN (Section/Hatch/
* dimensions have none). Current like `placements`; `[0,0,0]` once absent.
*/
pivot: [number, number, number], };/**
* One drawable unit; `positions` (below) states its own frame. `uvs` is
* `[u,v,…]` (mesh only) — `Face.uvTransform` maps through that 4×4, absent
* falls back to face-plane coordinates. `indices` triangulates `positions`;
* `lines` is the hard-edge / wire overlay.
*/
export type RenderCell = {
/**
* geometry — `[x,y,z,…]`; this cell's own frame, BEFORE `RenderChange.
* placements` applies — mesh/curve: pre-placement local pose, and for a
* flattened block's leaf its own frame, `transform` lifting it into the
* object's; a RECORD cell (Section/Hatch/dimension/Leader/Image) bakes
* its OWN placement in here already (AGENTS.md "RECORDS"), leaving only
* the ancestor nest's placement in `placements`. Wired as a typed array,
* never JSON.
*/
positions: Float32Array,
/**
* geometry — `[x,y,z,…]`, absent for a record cell (no shading).
*/
normals?: Float32Array,
/**
* geometry — `[u,v,…]`, mesh only.
*/
uvs: Float32Array,
/**
* geometry — triangulates `positions`.
*/
indices: Uint32Array,
/**
* geometry — the hard-edge / wire overlay, index pairs into `positions`.
*/
lines: Uint32Array,
/**
* geometry — a mesh's smooth edges between two shown faces, index pairs
* into `positions`: the candidates for a profile line, drawn where one
* face turns toward the viewer and the other away (SketchUp "Profiles").
*/
profileLines: Uint32Array,
/**
* geometry — per `profile_lines` pair, the unit normals of its two
* faces, `[ax, ay, az, bx, by, bz, …]`, object-local.
*/
profileNormals: Float32Array,
/**
* derived — a `CurveEdge`/`MeshEdge`-drawing style; `None` for a mesh
* triangle cell, which has no line of its own to style.
*/
lineStyle?: LineStyle,
/**
* identity — the resolved material's key; a cell paints one material.
*/
material?: string,
/**
* identity — a decimal string on the wire (JS numbers only carry 53
* safe bits, short of this key's 64); unchanged means "skip re-tessellate".
*/
contentKey: string,
/**
* geometry — object-local pivot + face normal the renderer yaws about
* world Z so the face meets the viewer (SketchUp "always face camera").
* Absent = this cell does not turn. A `faceCamera` behavior stamps it
* on every cell it governs (spec/architecture/concepts.md §Behaviors).
*/
faceCamera?: FaceCamera,
/**
* identity — nest path from the first child of this `RenderChange`'s
* object down to the `SceneObject` that produced the cell; absent = the
* object's own geometry (no nest). Set only for a FLATTENED `clone` /
* `placeComponent` block's content (`stamp_block_cells`) — a real
* `createBlock` nest ships each child as its own `RenderChange` instead.
*/
objectKeys?: Array<string>,
/**
* geometry — cell-space points a selection box or marquee measures in
* place of the drawn linework: a mark's authored points, its furniture
* (arrows, extension lines, text) left out (`CellType::anchors`). Absent
* = the drawn geometry is the extent.
*/
anchors?: Array<[number, number, number]>,
/**
* derived — a drafting mark's texts, which the renderer draws facing
* the viewer at a fixed screen size (`annotation::Text`); absent = the
* cell writes no text.
*/
texts?: Array<Text>,
/**
* derived — a drafting mark's endpoints (arrows, slashes, dots), drawn
* like its texts (`annotation::Endpoint`); absent = none.
*/
endpoints?: Array<Endpoint>,
/**
* geometry — this cell's placement inside its object's frame
* (column-major, same layout as `Instance.transformation`), composed down
* a flattened `placeComponent`/`clone` block outer·inner; absent =
* identity. A reader draws the cell at `placement.transformation ·
* transform`.
*/
transform?: number[],
/**
* derived — an EARLIER cell of this same payload (the `render` list of one
* door result, in order) whose buffers this cell draws; this cell's own
* `positions` / `normals` / `uvs` / `indices` / `lines` / `profile_lines`
* / `profile_normals` are then empty (set only when byte-identical).
*/
buffersOf?: BufferSource, } & ({ "type": "mesh" } | { "type": "curve" } | { "type": "section" } & SectionRecord | { "type": "hatch" } & HatchRecord | { "type": "linearDimension" } & LinearDimensionRecord | { "type": "radialDimension" } & RadialDimensionRecord | { "type": "angularDimension" } & AngularDimensionRecord | { "type": "leader" } & LeaderRecord | { "type": "image" } & ImageRecord);The doors
43 doors, in source order. Parameters and return types are the Rust signatures; JsValue is a structured value crossing the JavaScript boundary.
| Door | Parameters | Returns | Summary |
|---|---|---|---|
engine_add_font | url: String, bytes: Vec<u8> | Result<JsValue, JsError> | Hands the session a font a step asked for (Changes.pending) — geometry_curve::text::font_parse validates and builds the shaping tables; the session marks the waiting steps dirty and re-evaluates. |
engine_add_components | entries: JsValue | Result<JsValue, JsError> | Hands the session every component document a loadComponent asked for (Changes.pending), one wave at a time — entries is [url, document][], each validated like engine_load's document. |
engine_load | document: JsValue, preload: JsValue | Result<JsValue, JsError> | Opens a session. |
engine_set_arg | id: u32, key: String, input: Option<String> | Result<JsValue, JsError> | |
engine_set_key | id: u32, key: String | Result<JsValue, JsError> | |
engine_set_label | id: u32, label: Option<String> | Result<JsValue, JsError> | |
engine_set_active_view | key: Option<String> | Result<JsValue, JsError> | |
engine_set_camera | camera: JsValue | Result<JsValue, JsError> | Reports the pose of the host's free camera (null = none), the camera a visible function reads while no view is active. |
engine_set_settings | patch: JsValue, replace: bool | Result<JsValue, JsError> | Merges patch into settings (or replaces it whole), one undo step. |
engine_set_description | description: Option<String> | Result<JsValue, JsError> | Writes the definition's verbatim description (null clears it), one undo step. |
engine_flip_objects | objects: JsValue, from: JsValue, to: JsValue | Result<JsValue, JsError> | Mirrors objects across the perpendicular bisector of from→to (from maps onto to), one undo step (EngineSession::flip_objects). |
engine_node_edit | call: JsValue | Result<JsValue, JsError> | |
engine_component_render | key: String, args: JsValue | Result<JsValue, JsError> | Read-only preview: one RenderChange per object of key's isolated evaluation (engine::EngineSession::component_render) — the 2D component canvas. |
engine_begin_group | Result<(), JsError> | Brackets a gesture (a drag, a multi-field commit) so every mutating door call in between collapses into ONE undo step. | |
engine_end_group | Result<JsValue, JsError> | ||
engine_undo | Result<JsValue, JsError> | ||
engine_redo | Result<JsValue, JsError> | ||
engine_save | Result<JsValue, JsError> | ||
engine_catalog | Result<JsValue, JsError> | ||
engine_evaluate | node: u32, expression: String | Result<JsValue, JsError> | Read-only preview: parse and evaluate expression in node's scope (parameters, namespaces as fallback), returning the Value as JSON — EvaluatePreview on engine::EngineSession's doc comment. |
engine_clickables | Result<JsValue, JsError> | Read-only: every clickable (object, copy path) with its evaluated actions, current index per action and world-box anchor (EngineSession::clickables). | |
engine_click | target: JsValue | Result<JsValue, JsError> | Advances target's click counter and returns the steps the host plays (EngineSession::click); no evaluation, no history step. |
engine_set_pose | entries: JsValue | Result<JsValue, JsError> | Sets or clears a batch of session pose overrides with ONE evaluate (EngineSession::set_pose); session state, no history step. |
engine_reset_pose | Result<JsValue, JsError> | Clears every pose override and click counter (EngineSession::reset_pose). | |
engine_record_copy | record_type: String, key: String | Result<JsValue, JsError> | Read-only: the copy the session built for a JOINED (component-brought) material/layer/pattern — every arg already a literal of what it evaluated to, ready to engine_node_edit an Insert under the SAME key (COMPONENT LAW "a joined record is edited by adopting it"). |
engine_select | node: u32, filter: String | Result<JsValue, JsError> | Read-only preview: evaluate filter against node's INPUT stream's first Mesh/Curve piece, calling it the way node's own method calls its filter arg, and returning SelectPreview (indices plus overlay points/segments for vertices/corners/edges). |
engine_step_preview | step: u32 | Result<JsValue, JsError> | Read-only preview: the stream a chain step produced, placed where its object sits, as one RenderChange (the builder's step preview). |
engine_hidden_preview | object: u32 | Result<JsValue, JsError> | Read-only preview: the object object as if shown, as one RenderChange (EngineSession::hidden_preview; empty cells when the object is shown). |
engine_pattern_preview | key: String | Result<JsValue, JsError> | Read-only preview: the patterns[] record key hatched over a square, as one RenderChange (the builder's Patterns lane thumbnail). |
engine_patterns_from_pat | text: String | Result<JsValue, JsError> | Session-free text codec: a CAD .pat file -> patterns[] records in mm (document::pat::parse). |
engine_patterns_to_pat | patterns: JsValue | Result<String, JsError> | Session-free text codec: patterns[] records -> .pat text (document::pat::write). |
engine_arg_preview | node: u32, key: String, row: Option<u32> | Result<JsValue, JsError> | Read-only preview: arg key of node (or its list element row), drawn where it sits (the builder's argument preview) as one RenderChange. |
engine_placement_levels | step: u32, path: Vec<String> | Result<JsValue, JsError> | Read-only preview: the document chain step's pick resolved to, one level per hop through a further placeComponent (engine::EngineSession:: placement_levels's doc comment) — the tray's per-depth parameters, since only the engine can walk a hop whose loadComponent(url: <formula>) reads a parameter (COMPONENT LAW). |
engine_size_parameters | target: Option<u32> | Result<JsValue, JsError> | Read-only, no history step (ADR 0041 S5): the declared size axes of the root document (target absent) or of the document a placeComponent step places, as that placement sees it (engine::EngineSession::size_parameters). |
engine_takeoff | Result<JsValue, JsError> | Read-only, no history step, no RenderState cache write: the scene's quantity takeoff (engine::EngineSession::takeoff's doc comment) — every keyed object node at every depth as one TakeoffInstance, plus one TakeoffGeometry row per (instance, material, layer) group of that instance's own content, measured in world space over the settled scene. | |
engine_audit | attachment: String | Result<JsValue, JsError> | Read-only, no history step: the blocking audit of the authored scene (engine::EngineSession::audit). |
engine_export_glb | images: js_sys::Array | Result<Vec<u8>, JsError> | Read-only, no history step, no RenderState cache write: the visible scene as GLB bytes (engine::EngineSession::export_glb's doc comment), mesh cells only. |
engine_export_stl | Result<Vec<u8>, JsError> | Binary STL bytes of the visible scene (engine::EngineSession::export_stl). | |
engine_export_obj | Result<Vec<u8>, JsError> | OBJ text as UTF-8 bytes of the visible scene (engine::EngineSession::export_obj). | |
engine_triangle_count | Result<f64, JsError> | Read-only, no history step, no RenderState cache write: the number of triangles engine_export_glb would write (engine::EngineSession::triangle_count). | |
engine_sun | site: JsValue, moment: JsValue | Result<JsValue, JsError> | Read-only, session-free: Model::sun_of for a site/moment pair not yet saved to the document — the shadow-study slider's per-frame preview. |
engine_fit_curve | points: JsValue, closed: bool, tolerance: f64 | Result<JsValue, JsError> | Read-only, session-free: geometry_curve::curve::fit_curve reduces a dense sampled point chain (a tessellated arc exported from SketchUp, say) to the fewest primitive steps within tolerance (mm) — polyline / arcThreePoints nodes with literal point arguments (catalog/curve.rs's own arg names), chained end to end once inserted by graph::fold::join_curves's endpoint matching. |
engine_selection_inputs | request: JsValue | Result<JsValue, JsError> | Read-only, session-free: a host selection (faces, edges; world mm) as the values of a face / points parameter plus the placement that maps each to world (selection_inputs::SelectionInputRequest::resolve). |
Audit
engine_audit(attachment) returns { stage, findings, cost, open_limit_milliseconds }. attachment is click for a consumer model (attached at the user's click) or slot for a part (attached by its host); it decides the origin check. There are four stages in order: the first stage with findings stops the pipeline and every finding inside it is collected. Every finding blocks. The code list is closed:
| Stage | Codes |
|---|---|
static (JSON only) | bare_nest, expression_invalid, size_unread |
evaluated | evaluation_error, evaluation_warning, size_mismatch, material_missing, layer_missing, pattern_missing |
settled | origin_outside_box (click only), size_not_driven |
shells | self_intersect |
EngineClient
EngineClient (packages/model/src/classes/EngineClient.ts) is the typed client of the doors. EngineClient.create() runs the wasm in a worker (browser); EngineClient.inProcess({ wasmBytes }) runs it in the current process (Node, tests, the MCP server). One wasm instance serves one session: load replaces it.
| Member | Returns | Summary |
|---|---|---|
EngineClient.create(options?: { worker?: Worker }) | Promise<EngineClient> | |
EngineClient.inProcess(options?: { wasmBytes?: Uint8Array }) | Promise<EngineClient> | |
EngineClient.wasmUrl() | URL | |
client.addFont(url: string, bytes: Uint8Array) | Promise<Changes> | Registers bytes under url into the SESSION's resource table (requires engine_load first), marks every step waiting on it dirty, and re-evaluates — a session door, not a pre-load step. |
client.addComponents(entries: readonly { url: string; document: ModelJson }[]) | Promise<Changes> | Registers every {url, document} pair into the SESSION's component table (each a loadComponent(url) step was waiting on), marks every waiting step dirty and re-evaluates ONCE (engine_add_components's doc comment — no compat door, this replaced the old single-entry addComponent). |
client.load(document: ModelJson, preload: readonly { url: string; document: ModelJson }[] = []) | Promise<Changes> | preload is every {url, document} pair the host already holds before this session evaluates for the first time (the api's component CLOSURE, AGENTS.md COMPONENT LAW) — seeded into the resource table BEFORE the one evaluate engine_load runs, so a fully-covered document opens with Changes.pending already empty instead of discovering and delivering its components wave by wave through addComponents. |
client.setArg(id: NodeId, key: string, input: string | null) | Promise<Changes> | |
client.setKey(id: NodeId, key: string) | Promise<Changes> | |
client.setLabel(id: NodeId, label: string | null) | Promise<Changes> | |
client.setActiveView(key: string | null) | Promise<Changes> | null = the free camera. |
client.setCamera(camera: Camera | null) | Promise<Changes | null> | Reports the pose of the host's free camera (null = none): the camera a visible function reads while no view is active. |
client.setSettings(patch: unknown, replace: boolean) | Promise<Changes> | Merges patch into settings (replace: swaps it whole); one undo step. |
client.setDescription(description: string | null) | Promise<Changes> | The definition's verbatim description (null clears it); one undo step. |
client.nodeEdit(call: NodeEditCall) | Promise<Changes> | |
client.flipObjects(objects: NodeId[], from: Point, to: Point) | Promise<Changes> | Mirrors objects across the perpendicular bisector of from→to (from maps onto to) by rewriting each one's translation, rotation and scale; one undo step. |
client.componentRender(key: string, args: [string, string][]) | Promise<ComponentRender> | Read-only preview: one RenderChange per object of the components lane node key's isolated evaluation, under args — the 2D component canvas. |
client.placementLevels(step: NodeId, path: readonly string[]) | Promise<PlacementLevel[]> | Read-only preview: the document chain step's pick resolved to, one level per hop through a further placeComponent — levels[0] is the step's own placed document (path: []); only the engine can walk a hop whose loadComponent(url: <formula>) reads a parameter (COMPONENT LAW). |
client.sizeParameters(target?: NodeId) | Promise<SizeParameters> | Read-only, no history step (ADR 0041 S5): the declared size axes of the root document (target absent) or of the document a placeComponent step places, as that placement sees it (its overrides applied). |
client.undo() | Promise<Changes> | |
client.redo() | Promise<Changes> | |
client.save() | Promise<ModelJson> | |
client.catalog() | Promise<Catalog> | |
client.beginGroup() | Promise<void> | Brackets a gesture (a drag, a multi-field commit) so every mutating door call in between collapses into one undo step. |
client.endGroup() | Promise<Changes> | |
client.evaluate(node: NodeId, expression: string) | Promise<EvaluatePreview> | Read-only preview: parses and evaluates expression in node's scope. |
client.select(node: NodeId, filter: string) | Promise<SelectPreview> | Read-only preview: evaluates filter against node's input stream's first mesh/curve piece, called the way node's own method calls its filter arg. |
client.stepPreview(step: NodeId) | Promise<RenderChange> | Read-only preview: step's output stream as one RenderChange (cells always an array, placements world matrices; a step that produced nothing returns cells: []). |
client.hiddenPreview(object: NodeId) | Promise<RenderChange> | Read-only preview: the object object as if shown, one RenderChange with world placements; cells: [] when the object is currently shown (only a hidden object gets geometry). |
client.patternPreview(key: string) | Promise<RenderChange> | Read-only preview: the patterns[] record key hatched over a 100 mm square in the z = 0 plane, one RenderChange with identity placement. |
client.patternsFromPat(text: string) | Promise<PatternNode[]> | Session-free text codec: a CAD .pat file into patterns[] records in mm (;%UNITS=INCH x 25.4). |
client.patternsToPat(patterns: readonly PatternNode[]) | Promise<string> | Session-free text codec: patterns[] records into .pat text in mm. |
client.argPreview(node: NodeId, key: string, row?: number) | Promise<RenderChange> | Read-only preview: node's key argument's evaluated value, already placed in world space, as one RenderChange (cells: [] when the value is not geometry or the arg is absent). |
client.sun(site: Site, moment: SunMoment) | Promise<Sun> | Pure: the sun direction for a site and moment, no session mutation. |
client.fitCurve(points: [number, number, number][], closed: boolean, tolerance: number) | Promise<StepNode[]> | Pure: reduces a dense sampled point chain (e.g. |
client.selectionInputs(request: SelectionInputRequest) | Promise<SelectionInputs> | Pure: a host selection (faces, edges; world mm) as face / points parameter values plus the placement that maps each to world. |
client.clickables() | Promise<Clickable[]> | Read-only: every clickable (object copy) with its evaluated onClick actions, current index per action and world-box anchor. |
client.click(target: ClickTarget) | Promise<ClickStep[]> | Counts one click on target and returns the steps the host plays. |
client.setPose(entries: PoseSet[]) | Promise<Changes> | Sets (value) or clears (absent) a batch of session pose overrides with one evaluate; Changes.render carries placements only. |
client.resetPose() | Promise<Changes> | Clears every pose override and click counter. |
client.recordCopy(type: "material" | "layer" | "pattern", key: string) | Promise<unknown> | Read-only: the copy the session built for a JOINED (component-brought) material/layer/pattern — every arg already a literal of what it evaluated to, ready to nodeEdit an Insert under the same key (COMPONENT LAW "a joined record is edited by adopting it"). |
client.takeoff() | Promise<Takeoff> | Read-only: the scene's quantity takeoff (ADR 0019 — engine_takeoff is the single measurement path, one final pass over the already-settled scene). |
client.audit(attachment: Attachment) | Promise<Audit> | Read-only: the blocking audit of the settled document (engine_audit, staged static, evaluated, settled, interference; every finding blocks). |
client.exportGlb(images: readonly [string, Uint8Array][]) | Promise<Uint8Array> | Read-only: the visible scene as GLB bytes (mesh cells only). |
client.exportStl() | Promise<Uint8Array> | Read-only: the visible scene as binary STL (mm, Z-up, mesh cells only). |
client.exportObj() | Promise<Uint8Array> | Read-only: the visible scene as OBJ text in UTF-8 bytes (mm, Z-up, mesh cells only). |
client.triangleCount() | Promise<number> | Read-only: how many triangles exportGlb would write, without needing any texture bytes. |
client.dispose() | void |
ModelView
ModelView (packages/model/src/classes/ModelView.ts) is the JavaScript-side reflection of a loaded document: NodeView and ArgView objects over the node graph, a resource resolver that answers Changes.pending, edit methods that go through the doors, and read-only access to the evaluated records. It holds no geometry logic. ModelView.open(client, document, resolver) opens a document.
| Method | Returns | Summary |
|---|---|---|
view.open(client: EngineClient, document: ModelJson, resolver: ResourceResolver, preload?: ReadonlyMap<string, ModelJson>) | Promise<ModelView> | preload is every component document the caller already holds for this document's placements (the api's CLOSURE fetch) — handed to client.load so the FIRST evaluate sees them and reports no pending for a url it covers, instead of a wave of addComponents calls discovering and delivering them one document-nesting level at a time. |
view.setDisplayUnit(unit: LengthUnit | "yd" | null) | void | A host that has its own length unit (SketchUp's model units) shows and takes lengths in it instead of the author's settings.units. |
view.node(id: NodeId) | NodeView | undefined | |
view.byKey(key: string) | NodeView | undefined | The parameter or object keyed key (one model-wide namespace). |
view.records(type: RecordCategory) | readonly NodeView[] | One record lane's nodes, in lane order. |
view.record(type: RecordCategory, key: string) | NodeView | undefined | The record keyed key in its lane (one key namespace across every lane). |
view.keyFromLabel(label: string) | string | A key candidate from a label, in the engine's key grammar (is_valid_key_shape); dedupe with uniqueKey. |
view.uniqueKey(base: string, except?: string) | string | A key no node of the document holds — one namespace, every lane. |
view.insertRecord(type: RecordCategory, head: NodeDefinition, extraArgs: Argument[] = []) | Promise<string> | Inserts a new record-lane node under head (one of type's catalog head methods — the caller resolves which, RecordLanes.heads in the builder's own lookup): seeds every arg with its catalog default, extraArgs add or override on top, mints a fresh doc-wide key, and (for a pattern) starts it with one line family. |
view.patternsFromPat(text: string) | Promise<PatternNode[]> | Read-only: the patterns[] records a CAD .pat text spells (engine_patterns_from_pat) — nothing joins the document until insertPatterns. |
view.insertPatterns(patterns: PatternNode[]) | Promise<string[]> | Inserts patterns at the end of the lane as ONE undo step; a key the document already holds takes the next free one (uniqueKey, the same rule as insertRecord). |
view.exportPat() | Promise<string> | The document's OWN patterns[] as .pat text (engine_patterns_to_pat); records joined from placed components are not this document's to export. |
view.insertLoadComponent(url: string, title: string) | Promise<string> | Reuses an existing loadComponent lane entry whose url arg is the SAME quoted literal, else inserts a fresh one — dedupe by literal url, never by a second url-collision check of its own. |
view.setArg(id: NodeId, key: string, input: string | null) | Promise<void> | |
view.setKey(id: NodeId, key: string) | Promise<void> | |
view.setLabel(id: NodeId, label: string | null) | Promise<void> | |
view.setActiveView(key: string | null) | Promise<void> | |
view.setCamera(camera: Camera | null) | Promise<void> | The host's free-camera pose, reported whenever it changes (the host debounces; the engine re-ships only the placements whose visible function flipped). |
view.setDescription(description: string) | Promise<void> | |
view.setSettings(patch: unknown, replace = false) | Promise<void> | |
view.nodeEdit(call: NodeEditCall) | Promise<void> | An insert notifies "insert" with the new subtree's top node, after the mirror holds it. |
view.flipObjects(objects: NodeId[], from: Point, to: Point) | Promise<Changes> | Mirrors objects across the perpendicular bisector of from→to (from maps onto to), one undo step; the mirror holds the result before it is returned. |
view.adoptRecord(type: "material" | "layer" | "pattern", key: string) | Promise<void> | Adopts a JOINED material/layer/pattern (component-brought, first-wins by name — ADR 0010) into this document's own lane under the SAME key: engine_record_copy hands back the source node with every arg already a literal (the placing component's own parameters do not exist here), then an ordinary Insert appends it — host-first, so it paints scene-wide from here on (COMPONENT LAW "a joined record is edited by adopting it"). |
view.componentRender(key: string, args: [string, string][]) | Promise<RenderChange[]> | Components lane entry key evaluated on its own; resolves what it waits on, one document-nesting level at a time, then retries. |
view.placedComponentDocument(step: NodeView) | ModelJson | undefined | The ModelJson a placeComponent step CURRENTLY resolves to — the components[] entry its component arg's evaluated key names, resolved the way that entry resolves itself (COMPONENT LAW): createComponent's inline data (parsed as the JSON literal it is — the engine reads it the same way, serde_json, never the expression grammar) or loadComponent's fetched document, keyed by its evaluated url (loadedComponents). |
view.placedComponentAt(step: NodeView, path: readonly string[]) | Promise<PlacementLevel | undefined> | placedComponentDocument, walked path.length further placements deep (spec/architecture/concepts.md §Components "Any depth, by override path" — placeComponent('outerPart', { innerObject: {...} }) addresses the placed part's OWN innerObject by key). |
view.componentLevels(step: NodeView, path: readonly string[]) | Promise<PlacementLevel[]> | Every level of placementLevels that DECLARES parameters, outermost first — the breadcrumb SelectionSection.ts renders above the parameter grid so a pick landing on a deeply nested part can still reach an outer placement's own parameters (the slab choice on a door unit, say) without losing the deepest one (§Components "Any depth, by override path"). |
view.resolvedComponentAt(step: NodeView, path: readonly string[]) | Promise< | The document to SHOW for a pick's path: the deepest placement it resolves to, walked back UP to the shallowest ancestor that actually DECLARES parameters (§Components "Any depth, by override path" — "walk up from the deepest placement only when it has no parameters"). |
view.settled() | Promise<void> | Resolves once no resource fetch is in flight (api, scripts, thumbnails await it). |
view.retryResources() | void | Fetches every request the resolver rejected again (a page's Retry) — every failed component retried as one wave, same as a fresh delivery. |
view.undo() | Promise<void> | |
view.redo() | Promise<void> | |
view.save() | Promise<ModelJson> | |
view.beginGesture() | Promise<void> | Brackets a gesture into one undo step; endGesture applies only the history flags. |
view.endGesture() | Promise<void> | |
view.evaluate(id: NodeId, expression: string) | Promise<EvaluatePreview> | |
view.select(id: NodeId, filter: string) | Promise<SelectPreview> | |
view.stepPreview(id: NodeId) | Promise<RenderChange> | |
view.hiddenPreview(id: NodeId) | Promise<RenderChange> | |
view.patternPreview(key: string) | Promise<RenderChange> | |
view.argPreview(id: NodeId, key: string, row?: number) | Promise<RenderChange> | |
view.sunFor(site: Site, moment: SunMoment) | Promise<Sun> | Previews the sun for a site/moment not yet saved (the sun getter is the saved one). |
view.clickables() | Promise<Clickable[]> | Every clickable object copy with its onClick actions, indexes and world-box anchor (AGENTS.md "onClick and Property"). |
view.click(target: ClickTarget) | Promise<ClickStep[]> | Counts one click on target; returns the steps the host plays through setPose. |
view.setPose(entries: PoseSet[]) | Promise<void> | Sets or clears pose overrides in one evaluate; session state like the camera, never in EditHistory. |
view.resetPose() | Promise<void> | Clears every pose override and click counter. |
view.takeoff() | Promise<Takeoff> | Read-only: the scene's quantity takeoff (ADR 0019) — every keyed object as one instance row plus one geometry row per (instance, material, layer) group of its own content, in world space over the settled scene (ADR 0019, the single measurement path). |
view.audit(attachment: Attachment) | Promise<Audit> | Read-only: the blocking audit of the settled document (EngineClient.audit). |
view.triangleCount() | Promise<number> | Read-only: the triangles of the visible scene (the GLB's count, see EngineClient.triangleCount). |
view.apply(changes: Changes) | void |
Read-only properties:
| Property | Type | Summary |
|---|---|---|
roots | readonly NodeView[] | |
objects | readonly NodeView[] | |
behaviors | readonly NodeView[] | ModelJson.behaviors[] — acts this model performs where it is placed. |
parameters | readonly NodeView[] | |
render | ReadonlyMap<NodeId, RenderChange> | |
diagnostics | readonly NodeDiagnostic[] | |
document | ModelJson | |
lengthUnit | LengthUnit | "yd" | The unit a host displays and types lengths in: the host's own override, else settings.units, absent = mm (evaluation is always mm). |
documentType | DocumentType | Component, or a material / pattern library — read off the lanes the document fills. |
materials | readonly ResolvedMaterial[] | |
layers | readonly ResolvedLayer[] | |
layerVisibility | readonly LayerVisibility[] | Every layer's visibility under the session's active view, as the engine resolved it (Changes.layers). |
patterns | readonly ResolvedPattern[] | |
views | readonly ResolvedView[] | |
environment | ResolvedEnvironment | undefined | |
sun | Sun | undefined | |
catalog | readonly NodeDefinition[] | |
activeView | string | null | The session's active view; null = the free camera. |
canUndo | boolean | |
canRedo | boolean | |
poseRender | boolean | True while the render listeners run for a render a click's pose caused (setPose, resetPose: session state, ADR 0054), false for one an edit or a resource caused. |
description | string | The definition's own text beside title; empty clears it. |
loadingResources | number | How many resource fetches are in flight; changes are announced by the "resources" event. |
loadedComponents | ReadonlyMap<string, ModelJson> | Every document the resolver returned, by loadComponent url ("Make unique" seeds from one; the thumbnail render fallback ships them all). |
One edit path
Every node edit goes through NodeEditCall: Insert { parent?, type, entry, index? }, Remove { id, force? }, Move { id, index } and Replace { id, entry }, plus engine_set_arg, engine_set_key, engine_set_label, engine_set_settings and engine_set_description. Each returns its inverse, and undo and redo replay through the same path. A reference removal is refused while consumers point at the record unless force is set, and every record edit is probe-validated.
Exports
engine_export_glb, engine_export_stl (binary) and engine_export_obj (text) are read-only; units are millimetres and Z is up. engine_triangle_count counts what each would write. The STEP reader crates/step is authoring-time only and is not part of the wasm.