Holostep configurator runtime: contract 2.0 ​

The engine-neutral API a Holostep configurator page uses through @holostep-configurators/runtime-client: boot a session, change the scene model, restyle parts, move the camera, drag, assemble, capture and export. The package wins over any note.

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated by services/onsite-scripter/scripts/build-contract-docs.mjs; do not edit.

"Spec section N" and the short ids in parentheses (O6, R4, ID8, K47, …) in these pages and in the runtime's messages name the design record a rule comes from. The record is not shipped, and the package is complete without it: read them as provenance, never as something to look up.

Start here ​

• llms.txt: the one file to give an AI agent: the one obvious way, the ten likeliest mistakes, imports, boot and every call path. Each page here is also served as Markdown: swap .html for .md.

• index.json: the machine-readable index: the page layout, every code and every member's call path.

Read next ​

• Read this first: the table, the traps and the conventions (units, kinds of call, order, read classes, errors).
• The full declaration: this file, then configurator-runtime.d.ts, math.d.ts and testing.d.ts byte for byte.
• Migrating from 1.x: every 1.x member, pattern and document key with its 2.0 recipe.
• Examples by area: spec section 5's compiled examples.
• Check it headless: confirm in a headless browser that the product is on screen, lit and framed before hand-off (the fake draws no pixels).
• Accessibility: view controls for keyboard and switch users, status messages, the view's name.

API pages ​

1. Basics ​

• Point2: A 2D point or size.
• Point3: A 3D point, vector or size.
• ReadonlyPoint3: An out-only position, never accepted as input: Readonly<Point3>, as Pose reads Readonly<Quat>.
• Quat: Unit quaternion.
• ScreenPoint: A Point2 in CSS px from the viewer element's top-left corner; y grows downwards.
• ProjectedPoint: A projected point.
• Bounds: Axis-aligned world bounds, metres.
• Ray: A ray in world space.
• Insets: CSS px.
• HexColor: '#rgb' or '#rrggbb', sRGB.
• ColorValue: A HexColor, or linear Rec.709 components 0..1.
• JsonPrimitive: A JSON leaf value.
• JsonValue: Any JSON value: what state(), the commit feed, meta and checkpoints hold.
• Easing: The time curve of a tween (pose, camera): the CSS Easing Functions Level 1 curves.
• DeepReadonly: A value you may read and must not change: every property and array is readonly, at every depth.
• PoseInput: A pose to write, with at most one rotation: rotationDeg or quaternion, never both (a type error; an untyped call with both rejects HoloInputError…
• Pose: A pose read.

2. Operations, reports, causes, problems ​

• Actor: Who made a write.
• OpId: Session-unique, increasing, assigned at the call.
• Outcome: Where an operation ended.
• Reason: Why an operation did not commit.
• ReportFields: The fields every Report has.
• Report: The one result of every write, discriminated by outcome.
• TransactionReport: A transaction's report.
• Cause: What caused a commit.
• ProblemCode: Open set: handle codes you don't know.
• Problem: Data, never an Error: safe to store, send and render.

3. Errors ​

• InputErrorCode: What a HoloInputError reports.
• HoloInputError: Invalid input to a call; nothing ran.
• HoloScopeError: A write through the wrong writer.
• HoloTransactionClosedError: A write through a tx (or a handle obtained from it) after that transaction closed.
• HoloAssetError: An imperative load failed.
• HoloBusyError: The runtime cannot serve the call now.
• HoloBootError: boot could not start the renderer.

4. Boot ​

• boot: Starts a session in el.
• BootOptions: What boot takes.
• RuntimeContract: The compatibility facts of this runtime build.
• RUNTIME_CONTRACT: This runtime's contract, also exported by the bootstrap so an app can check it before boot.
• RUNTIME_VERSION: The runtime build's version, e.g. '2.0.3'.

5. Writers, transactions, session ​

• CommitOptions: The options of a commit.
• CheckpointOption: Page state stored atomically with a recorded commit.
• NoCommitOptions: What a write through a tx accepts in place of the commit options: none of them.
• RecordedOptions: Recorded writes through session also take checkpoint.
• CameraCommitOptions: The commit options a camera write takes: origin, actor and expectRevision.
• SignalOption: The cancel option every write takes, through session and through a tx; registrations and waits take it too.
• WriteOptions: The options of a plain write through session.
• TransactionOptions: The options of session.transaction: the commit options, a checkpoint, a signal and two time limits.
• SessionState: Recorded state plus the look.
• JsonPatchOp: RFC 6902 over SessionState.
• SceneModelOptions: The member options of setSceneModel.
• Writer: The write surface Session and Tx share.
• Tx: A transaction's scoped writer.
• BeforeCommitContext: What a beforeCommit function receives.
• HistoryGroupOptions: What history.group takes.
• HistoryGroup: The handle history.group() returns.
• History: Undo state and grouping.
• FrameOptions: What onFrame takes.
• NotAsync: A callback's return type with Promises excluded, so an async callback fails to compile.
• Session: A configurator session.

6. Queries, rules and parts ​

• Role: product: the configured thing (fit, AR, export, dimensions, picking).
• Query: All fields are ANDed; an array of queries matches any of them.
• PartState: What a write through find() (a rule) may change.
• PartWriteOptions: The member options of a rule write (set on Parts or a Part).
• FollowOptions: What follow takes.
• PartActions: The actions that exist on one part and on a set of parts.
• Parts: A saved search.
• Part: One part of a loaded model or a collection.
• Placement: Where and how an imperatively created part sits.
• Hit: A hit, on the session's input (so its part takes commit options).

7. Collections and shapes ​

• CollectionOptions: What collection(name, options) takes.
• Collection: Content you create.
• CollectionReport: updated: keys of items changed in place.
• CollectionSpec: JSON form of a collection's content.
• ItemBase: The fields every collection item has.
• ItemSpec: One collection item: ItemBase plus one kind.
• Outline2D: Outline segments in 2D.
• ShapeRef: How reads return a mesh shape: JSON, as an ImageRef is for an image, so state(), the feed's patch and inverse, undo steps and event payloads carry…
• Shape: Built shapes.
• LinesSpec: A lines item: a polyline in item-local metres.
• LabelSpec: A label drawn in the scene (text or image on a quad facing the camera).
• LightSpec: Light intensity: KHR_lights_punctual units ×1, relative and not photometric (a sun of 3 lights white to about 1).
• ShadowSpec: The runtime owns the shadow map and its filter per quality tier (info().renderer.tier): high 2048 px, medium 1024 px, low 1024 px with a tighter filter…

8. Materials and textures ​

• MaterialInput: A MaterialSpec, however complete, merges field by field (RFC 7396) over what the part wears (authored maps such as baked AO stay).
• MapSlot: The map slots of a material (glTF and KHR names).
• TextureSlot: A map slot: a texture; 'none' (no map, whatever is underneath); or null (remove your value and show what is underneath).
• Wrap: How a texture repeats outside 0..1.
• TextureSampling: How a texture is filtered.
• TextureInput: A URL, or a texture with placement.
• ImageRef: How reads return a texture you wrote as an image: JSON, so state(), the feed, applyPatch and sceneHash stay JSON.
• TextureSpec: At most one of url and image.
• MaterialSpec: glTF 2.0 and KHR names.
• MaterialPatch: A MaterialSpec as a JSON Merge Patch (RFC 7396): what a rule's material takes.
• Material: A material parts wear: one Part.material reads, or one materials.create makes.
• Materials: Create reusable materials and read stored ones.

9. Stage ​

• BackgroundSpec: What is drawn behind the scene, in the colour pipeline.
• StageSettings: Colour pipeline: shading is linear Rec.709 in a frame of at least half-float.
• StageWriteOptions: The member options of stage.set.
• Stage: The stage: layered settings over the document's.
• RuleSpec: One persistent rule in JSON form: what find(query).set(set) creates.
• SceneSpec: The look as one JSON document: what apply() writes (state().look reads it back as a LookState).
• LookState: The look as state().look reads it: a read, not apply()'s input, so every key is present and none means "unchanged".

10. Camera ​

• CameraView: Orbit view.
• LookAtView: A view by eye point and target.
• CameraState: Observed: as of the last drawn frame (this frame's inside onFrame({ phase: 'late' })).
• CameraLimits: A JSON Merge Patch (RFC 7396) over your app limits, which lie over the document's.
• CameraLens: The camera's lens.
• CameraMoveOptions: The member options of a camera move.
• Camera: Camera writes are look-only and never undo steps; of the commit options they take only origin, actor and expectRevision (CameraCommitOptions).

11. Input and drag ​

• PickOptions: What input.pick takes.
• RaycastOptions: What input.raycast takes.
• DragMove: One frame of a drag.
• DragOptions: What input.drag takes.
• Input: Picking, raycasts and drags on the canvas.

12. Assembly ​

• ConnectorRef: One connector of one placed node.
• Connection: Stored top-level in IConfigurator.connections.
• Connector: Authored facts plus derived world positions (computed on read).
• AttachOptions: The member options of assembly.attach.
• AttachReport: attached: false comes with outcome: 'refused' and a reason of 'no-candidate', 'occupied', 'rejected' or 'not-loaded': the first that applies, in the…
• Assembly: Connectors and connections between placed models (spec section 6.12).

13. Overlays ​

• HotspotBadge: A badge the runtime draws as a <button>.
• HotspotReference: Which badge an event is about.
• AnchorSpec: A point the runtime tracks on screen for your own DOM.
• AnchorOptions: What overlays.anchors.set takes.
• AnchorPosition: Where an anchor is on screen now.
• DimensionFormat: How rulers print a length: the number to decimals places, a space and unit ('120 cm'), as 1.x printed its unit.
• DimensionOptions: What overlays.dimensions takes.
• Overlays: Screen overlays.

14. Animations ​

• ClipRef: Which clip: where its GLB sits and its name.
• ClipInfo: One authored clip of a loaded model.
• PlayOptions: The member options of animations.play.
• Animations: Clip writes are look-only and not in the write queue: outside a transaction each starts at once, so plays called in the same task start in the same frame.

15. Frame writer ​

• Frame: The synchronous per-frame writer for onFrame and drag constrain.

16. Capture, export, AR ​

• CaptureSpec: What capture takes.
• CaptureResult: What a capture returns.
• ExportOptions: What export takes.
• ExportResult: What export returns.
• ActivateAROptions: What activateAR takes.
• ActivateARReport: How an AR launch went.
• TryOnKind: The kind of try-on a product's rig is for: 'face' (glasses), 'foot' (shoes), 'wrist' (watches and bracelets), 'finger' (rings), 'ear' (earrings), 'head' (hats).
• TryOnMode: Where try-on runs: 'here' in this page, 'handoff' on another device, a phone that opens the hand-off's link (TryOnReport.handoffUrl).
• TryOnUnavailable: Why try-on isn't available: 'not-enabled' (the account offers no try-on of this kind, or has not set its consent mode, which every kind needs; a page document…
• TryOnAvailability: canTryOn()'s answer for the product on screen, now.
• TryOnOptions: What tryOn takes.
• TryOnReport: What tryOn resolves with once try-on closed or could not open.

17. Assets: describe, manifest, validation ​

• AssetInfo: The GLB a ModelNode shows.
• ManifestPart: One authored part.
• ManifestSlot: One authored material slot.
• ManifestConnector: Local frame of the GLB.
• AssetManifest: The per-GLB manifest (asset.extras.holostep.manifest, and the sidecar).
• ModelDescription: What describe(node) returns.
• ValidationKind: Open registry: later kinds ('product') are added without a breaking change.
• ValidationResult: What validate returns.
• IssueCode: What an Issue reports: an InputErrorCode, a checkAsset check, or a value the stored format can't hold.
• Issue: One failed check at a path: what validate and checkAsset return, and what a HoloInputError carries.

18. Events ​

• Events: Typed events.

19. Info and capabilities ​

• InfoReport: A diagnostic snapshot (session.info()).
• KnownCapability: Capability ids, one per capability in the coverage ledger (coverage.json).
• Capability: Open, so an app built against a newer contract can ask about ids this runtime lacks.

20. Labs ​

• GeometryAttribute: A vertex attribute labs.geometry.read can return.
• GeometryData: Local space of the part (for a skinned mesh: its bind space).
• GeometryWrite: New vertex data for labs.geometry.write: same vertex count and order as the part's.
• SkinBinding: Binds a collection mesh to a loaded model's skeleton.
• DecalSpec: A projected decal with depth.
• FireSpec: Volumetric fire, as labs.fire draws it.
• ShadingUniformType: The type of a shading graph input.
• ShadingNode: A node output in a shading graph, typed by what it carries.
• ShadingNodes: 2.0's node set, by MaterialX 1.38's node and input names (stdlib_defs.mtlx): add, subtract, multiply, divide, power, absval, clamp, min, …
• ShadingOutputs: The camelCased gltf_pbr inputs; omitted ones keep the material's.
• ShadingValue: What Shading.set takes for a uniform of type T: a number for 'float', a Point2 for 'vector2', a Point3 for 'vector3', a ColorValue or linear…
• Shading: A shading graph, worn through MaterialSpec.labs.shading.
• Labs: Members that serve one app or wrap an engine-shaped capability.

21. Stored data (vendored; replaces @holo/interfaces) ​

• IPrice: A stored price of a MaterialNode (the product envelope; the runtime never prices).
• IGradientColorStop: A stored gradient stop.
• GradientDirection: The direction of a stored gradient background.
• IGradientBackground: A stored gradient background.
• BackgroundValue: A stored background: a 0xRRGGBB number, null (no stored background), or a gradient.
• IDefaultView: Stored angles are degrees.
• IGlobalMaterialListEntry: A stored binding of meshes to a global-material GroupNode.
• IMagneticPlaneConfig: A stored connector-plane config, matched to a connector plane by meshName.
• IMagneticPlaneRule: A stored rule that gives a GroupNode's child models plane configs by mesh-name pattern.
• IChildDefaults: Stored defaults a GroupNode gives its children.
• IPresetNode: One node's state in a stored preset.
• IPreset: A stored preset: a named set of node states.
• IConfiguratorNode: The fields every stored node has.
• IGroupNode: A stored group: a choice among its children, or a global-material group (globalMaterial: true) that select writes.
• IModelNode: Stored GLB node.
• TextureChannel: The texture channels of a stored MaterialNode ({channel}TextureUrl); materialSpecFromNode maps them to MapSlots.
• IMaterialNode: Stored MaterialNode (format unchanged).
• ConfiguratorNode: Any stored node.
• IConfigurator: The stored configurator document.
• SceneModel: What the runtime renders: the IConfigurator fields it reads.
• ViewerDocumentJson: The viewer document, version 2: the page's defaults for the typed members, as JSON.
• ApplyReport: The result of applying a document layer.

22. Pure helpers (root of the package; run in Node and the fake) ​

• duplicateNodes: Copies nodes with new ids.
• LegacyNode: A node as old saves store it: nodeId may be missing or repeated.
• LegacyDocument: A document as old saves store it.
• normalizeNodeIds: Repairs old saves: mints missing ids, re-mints duplicates, remaps defaultNodeId, preset node ids, globalMaterialList[].globalMaterial and connections, and…
• connectionsBasis: The basis fingerprint to store beside connections, as IConfigurator.connectionsBasis: sha256 (hex) of the canonical JSON (RFC 8785) of nodeId, glbUrl…
• cameraViewFromStored: A stored defaultView (IConfigurator.defaultView, SceneModel.defaultView: degrees, named azimuth, polar, radius) as the CameraView camera.set…
• materialSpecFromNode: Stored MaterialNode → partial MaterialSpec.
• materialNodeFromSpec: MaterialSpec → stored MaterialNode fields, applied over base (envelope, prices and opt… URLs kept).
• validate: Validates a value against the package's JSON Schemas.
• CapabilityMembers: The members each experimental capability id unlocks.
• has: How app code reaches an experimental member: a type guard over session.supports(id).
• AssetContract: What an app needs from an asset.
• checkAsset: The shared check(): the server stampers, Asset Library QA, the Blender helper and the runtime run this one function.

23. /math ​

• math.Mat4: A 4×4 affine matrix: 16 values, column-major (as glTF and Shape.transform).
• math.vec3: 3D vectors and points.
• math.quat: Unit quaternions.
• math.mat4: 4×4 matrices.
• math.box3: Axis-aligned boxes.
• math.ray: Rays.
• math.plane: Planes as { normal, constant }: the points p with dot(normal, p) + constant = 0.
• math.outline: 2D outlines for shapes.
• math.color: sRGB hex colours and linear components.
• math.angle: Angles.
• math.projection: Projection through a camera you describe, not the live one (camera.project projects through camera.state only): where points land in a capture before you…

24. /testing ​

• testing.FakeModel: A GLB as the fake knows it: its node tree, connectors, manifest, clips and load behaviour.
• testing.FakeSessionOptions: What createFakeSession takes.
• testing.TraceEntry: One step of an operation through the states of spec section 6.2.
• testing.FakeSession: A Session that runs in Node with fake timers, plus controls for tests.
• testing.createFakeSession: A fake session: the runtime's own implementation of the spec's section 6 tables, without a renderer.
• testing.fakeModelFromGlb: A FakeModel read from a GLB with no browser, so a test drives the fake with the product it ships instead of a hand-written tree: nodes in the scene's…
• testing.ManifestFromGlbOptions: What manifestFromGlb takes besides the bytes.
• testing.manifestFromGlb: A GLB's manifest, read with no browser and no engine (Node 20 or later, or a page), for an author with a file and no human: its parts, slots, connector…

Codes ​

Problem codes (ProblemCode) ​

• target-unmatched: A query matched nothing, or a placed model's globalMaterialList meshName matches none of its meshes but is close to one (a typo; once, at the commit that places the model); …
• target-ambiguous: A single-part member (follow target, attachTo) matched several parts; nothing applied.
• asset-failed: A GLB, texture or HDR failed in a declarative write; the write committed without it.
• asset-degraded: A preferred asset failed to fetch, decrypt or parse and a fallback was drawn instead: a .holo's plain twin (url the .holo, spec section 8.5), or glbUrl after optGlbUrl…
• ready-timeout: Readiness expired: the commit shows with stand-ins or old looks until assets decode.
• transaction-timeout: A transaction made no progress for timeoutMs, or hit the hold cap; it rolled back.
• write-after-close: A write through a closed tx or its handles (HoloTransactionClosedError).
• beforeCommit-threw: A beforeCommit function threw, or was pending after 10 s; its writes were undone.
• beforeCommit-slow: A beforeCommit function averaged over about 5 ms across its last 10 commits; recorded at most once per function per 10 s, with the count and the mean in message.
• connection-stale: A connection's planes no longer meet (0.5 mm, 0.5°); it was dropped.
• handle-disposed: A disposed handle or removed part was used; nothing happened.
• owner-disposed: Undo or redo skipped a change made by an owner that is disposed: listed in that undo's or redo's problems, path the owner's address (/look/collections/{name} for a…
• unsupported-spec: A value this runtime or device can't apply (a UV channel, sizeM without uvMetres, a shading node, a linked light past the limit, a material ref no apply() defines), or an…
• not-storable: Reserved: a value the stored format can't hold is an Issue of validate and an unstorable entry of materialNodeFromSpec (IssueCode 'not-storable'), never a Problem in…
• space-not-storable: Reserved: space: 'parent' in a document meant to be saved is an Issue of validate('configurator') (IssueCode 'space-not-storable'), never a Problem in 2.0.0.
• frame-needs-compile: A Frame.material value needs a new shader; it was skipped.
• frame-budget: Frame hooks together averaged over 3 ms per frame across the last 60 drawn frames, or a constrain over 1 ms across its last 60 calls; recorded at most once per 10 s for each,…
• handler-threw: An event handler or frame hook threw (a hook that throws 3 frames in a row is removed: 'hook-removed').
• hook-removed: A frame hook threw on 3 frames in a row and the runtime removed it: recorded once, right after that third 'handler-threw', with path 'onFrame' and the function's name, when…
• handler-async: An event handler returned a Promise (an untyped call); it was not awaited.
• handler-rejected: A Promise an event handler returned rejected.
• engine-conflict: Another 3D engine instance on the page conflicts with the runtime's (info().renderer.engineConflict).
• tenant-document-absent: No stored viewer-document layer for configuratorId (a 404; info().document.layers 'tenant'): the layers below apply.
• tenant-document-unavailable: The stored viewer-document layer couldn't be fetched (any failure but a 404); the session runs with the layers below.
• defaults-unavailable: The platform or account defaults couldn't be fetched; built-in defaults apply.
• document-error: A document layer has an invalid or version-1 key; didYouMean names its 2.0 home.
• apply-failed: The runtime failed while applying a document layer, not for a bad key ('document-error'): one entry with layer and no path in ApplyReport.problems (applyDocument, …
• sync-failed: An internal failure while the runtime applied a state write, recorded or look-only (setSceneModel, undo, Collection.set, stage.set, attach, a rule), through session…
• host-disconnected: el left the document after boot, which freed the renderer for good (spec section 6.5).
• render-lost: The view stopped drawing: the graphics context was lost and came back neither on its own nor on a fresh canvas.
• host-unsized: el has no size to draw at: under 64 CSS px on a side, or not rendered (display: none on it or an ancestor), at the first drawn frame or a resize; once until it has a size again.
• unknown-boot-option: boot got an option this contract doesn't have; it was ignored.
• unknown-event: on() got an event name that doesn't exist; it subscribed to nothing.
• invalid-input: A call rejected or threw HoloInputError; recorded so an unawaited one is never silent.
• hotspot-id-taken: Two hotspot badges share an id; the later one is skipped.
• deprecated: Reserved for a labs member or value that will change; the strict fake throws on it.
• not-permitted: A gated capability this account may not use (permits() is false).
• unknown-capability: supports() got an id not in this runtime's KnownCapability, once per id per session; didYouMean names a 1.4 id's 2.0 id (none when the member is always present), else close…
• connections-outdated: Stored connections whose connectionsBasis no longer matches their nodes: none restored.
• read-while-queued: Strict fake only: code read a target that still had a write queued behind a transaction.

Input-error codes (InputErrorCode) ​

• invalid-input: A value or combination the member refuses, e.g. a zero PoseInput.scale component.
• missing-node-id: A node without a nodeId (spec section 6.9, ID9).
• duplicate-node-id: Two nodes share a nodeId (ID9); normalizeNodeIds repairs an old save.
• rotation-twice: An untyped pose or patch with both rotations, rotationDeg and quaternion.
• unknown-field: A field the spec or schema of the page's declared contract doesn't have, or an applyPatch node field path whose field the stored node format doesn't have and the node doesn't…
• unknown-id: An id that names nothing the member takes, e.g. a select group that is no global-material GroupNode, a view not in camera.views, an ImageRef or ShapeRef that is not live,…
• option-in-transaction: A commit option passed through a tx by an untyped call; always thrown at the call.
• collection-role-mismatch: collection() on a live name with another role.
• collection-options-mismatch: collection() on a live name with another attachTo.
• duplicate-rule-id: Two rules of one apply() rules list share an id (spec section 6.10, R3).
• checkpoint-rejected: Page state over 256 KB of canonical JSON (CheckpointOption).
• capture-displayed-fixed: source: 'displayed' with a view, size, pixelRatio or a background other than 'scene'.
• not-draggable: startDrag on a unit that no live registration names.

Issue codes (IssueCode) ​

• element: checkAsset: the manifest's element matches none of the contract's globs.
• part: checkAsset: a contract part is missing where required, or has another tag, or a slot that is neither its slot nor one of its slots.
• slot: checkAsset: a contract slot the manifest lacks, or one without uvMetres where realSize asks for it.
• connector: checkAsset: fewer connectors of a type than the contract's count.
• animation: checkAsset: a contract clip name the asset lacks.
• connector-name-collision: checkAsset: two connector planes whose authored names clean to the same name (spec section 6.9, ID1).
• connector-id: checkAsset: an extras.holostep.connector.id that contains ':' (ID1).
• not-storable: validate: a value the stored format can't hold.
• space-not-storable: validate('configurator'): space: 'parent' in a document meant to be saved.