Read this first ​

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated from configurator-runtime.d.ts (its header) by services/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.

Holostep configurator runtime: tenant contract 2.0. Vendored into @holostep-configurators/runtime-client by runtime:types from an immutable release manifest. Never edit by hand.

Read this first. You want to… → use … → not …

One obvious way ​

Traps ​

The traps agents fell into, with only the declaration:

• A Pose read is not a PoseInput (it has both rotations): copy { position, quaternion, scale } (a mirror reads its −1 on scale.x); leave scale out only when it holds a 0, which no write takes. A partial write keeps the omitted fields as that read shows them, so a positive absolute scale on a mirrored part names its rotation too.
• undo: 'rebase' erases every earlier undo step, the shopper's included. Label a sync instead.
• capture() draws committed state only: a pick the shopper just made may still be loading, and it is not in the image unless you await session.idle() first. It rejects HoloBusyError('capture-held') while a transaction holds the display: idle(), then again.
• A write queued behind a transaction settles when it closes: a stalled one at its timeoutMs (10 s by default), one holding the display within 14 s of its hold, later while it still loads. Show what you wrote.
• Rules a beforeCommit hook wrote outlive the hook: reset them when you unregister it.
• getSceneModel() is null until the first model is placed, and its type says so: guard it (const m = session.getSceneModel(); if (!m) return;), never getSceneModel()!, which compiles and then fails on a page whose model has not arrived yet.
• One scene-model writer (spec section 11.2). In an app with its own store, an add, removal or swap goes into the store, and the store's one sync writes the model. A second writer that adds nodes (tx.setSceneModel(withNode(…))) is rolled back by a supersede: true sync, or the store never receives its node (placement merges only nodes it has) and the next sync drops it.
• commit: 'app': an equal store write releases nothing. Call input.revert(part) when the drop resolves to where the node already is.
• A second find(q).set({ material }) merges into the first: a field only the earlier look set stays where the GLB's should show. Switch partial looks with apply({ rules }), or null the old look's other fields in the same write (MaterialPatch).
• Never wait with setTimeout or a debounce: await the write's Promise, the event that follows its commit, or idle(), and abort an older write's signal for newest wins (Session.idle lists what to wait on).

Conventions ​

They hold for every member; members repeat the ones that matter.

• References: "spec section N" and the short ids in parentheses (O6, R4, ID8, K47, …) 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.
• Units: lengths in metres; angles in degrees (names end in Deg), except the stored rotation of a scene-model node (IModelNode.rotation), which is Euler XYZ in radians, the stored format: rotation: { x: 90 } turns a part 90 rad, so convert with angle.degToRad (/math); durations in milliseconds (names end in Ms); exposure in stops (Ev); screen points in CSS px from the viewer element's top-left corner.
• Space: right-handed, +Y up. rotationDeg is intrinsic X, then Y, then Z. The contract assumes no product front: read it from describe(node).manifest.front.
• Colours: '#rgb' or '#rrggbb' (sRGB, type HexColor), or { linear: { r, g, b } } with components 0..1.
• URLs: the scene model's resolve against assetBaseUrl (a .holo's bare twin name beside the .holo), and the viewer document's must be absolute; every other URL (collection items, Collection.load, textures in rules, materials and apply, stage images and HDRs) resolves as fetch() resolves it, against the page's document.baseURI. A scene-model URL without a scheme or host resolves beneath assetBaseUrl, leading '/' dropped (SceneModelOptions).
• Kinds of call. A write (an operation) returns Promise<Report> and has a commit point; it can be queued, staged, superseded or rolled back. A lifecycle call (collection(), materials.create, on, onFrame, beforeCommit, follow, input.drag, labs.lightLinking) is immediate and returns a handle or a disposer, never a Report; it is never queued, and a rollback empties its owner of staged content but never removes the handle, which ends only through its disposer, its owner or its signal (spec section 6.5). An engine query (Collection.load, labs.geometry.read, input.pick, input.raycast) is asynchronous and resolves with data; Collection.load also adds its item, which through session commits on its own once loaded. Enlisted means started through a tx (a write, Collection.load, labs.geometry.read; input is on the session only), awaited or not: a rejection that work never observed rolls the transaction back ('enlisted-failed', spec section 6.1, O6). A configuration call (applyDocument) replaces a layer; it is not an operation and carries no op or cause.
• Writes take effect at the call, or when the open transaction closes if they are queued behind it, and return Promise<Report>. The Promise resolves at the write's commit point (irrevocable), not when it is shown. A write with durationMs or fadeMs, a camera move and a clip resolve when they finish, and open-ended motion once it starts (spec section 6.3). No other write waits for a frame.
• On-demand code: capture, export, activateAR, assembly.attach, the overlays, the drag body, labs and the patch apply of undo and redo load their code after the first complete frame. A call before then waits for it, a synchronous one taking effect at the first frame after it loads; an AR tap is routed at once (spec section 5.11). A failed load fails the call as an internal failure does (a write rolls back; another Promise rejects HoloBusyError('code-unavailable')), and a later call retries it (spec section 6.3). candidates() is start-up code: it never waits and never throws for code.
• Order: outside a transaction, recorded writes (setSceneModel, select, applyPatch, attach, detach, undo, redo), apply, Collection.set, stage.set and transaction form one first-in, first-out queue per session and commit in call order. Two pending replacing writes to the same target coalesce only when they are adjacent in that queue (spec section 6.10, R4); a merging write or a dry run is never coalesced. Other writes (rules, camera, clips) commit as soon as they are ready, and queue only behind an open transaction; two writes to one rule both commit, in call order (spec section 6.1, O2b): the older one shows until the newer commits. For newest wins, give each write its own AbortController and abort the previous one when a new write starts (it rejects AbortError; catch it). A transaction opens only after every write called before it, queued or not, has passed its commit point.
• Reads are synchronous and see your own writes (an engine query, above, returns a Promise), with one exception: a write queued behind an open transaction. Until it applies, a read of its target is unspecified (old or queued value). Await that write's Promise before reading it back. That Promise settles only when the transaction closes: within timeoutMs + readyTimeoutMs (14 s by default) of its hold, and later while it still loads (timeoutMs re-arms on progress until the hold). For UI that must change at once, show the value you wrote and correct it from the Report ('superseded' means a newer write won).
• Read classes (spec section 6.7): authored (fixed per loaded asset), intent (the latest accepted state, staged and queued writes included), derived (computed on read, never last-rendered), observed (stamped frame: a sync read is as of the last drawn frame, while a capture renders committed state anew). Each read names its class. Intent is not what is shown: for that, keep the latest 'scene-model:changed' payload.
• A write whose result equals the current state commits nothing: it resolves 'committed' with changed: false and no seq, revision, undo step or event.
• Events fire after the frame that shows a commit. Payloads are frozen snapshots of that commit. State events (those a commit causes) carry cause.
• What to wait on: a write's Promise (its commit point), the event after a commit (once shown), a transaction's Promise (all or nothing), idle() (everything loaded, eased and drawn) and an onFrame hook (each frame). Never a timer (Session.idle).
• Output unions are open. A value newer than your declared contract arrives as 'other'.
• Stability: every member is tagged @stability stable or @stability labs. A field inherits the tag of its interface unless it carries its own. A labs member at a stable path is also tagged @experimental; an experimental method is optional here, and app code reaches it through has(session, id). A labs member may change in a minor release after one minor of 'deprecated' problems; a stable member only grows.
• Since: every declaration is tagged @since 2.0.0. A member inherits its declaration's version unless it carries its own.
• Errors: a Promise-returning member reports invalid input by rejecting with HoloInputError, created at the call before anything runs. Three transaction-scope misuses throw at the call instead: HoloScopeError, HoloTransactionClosedError and HoloInputError('option-in-transaction'). A lifecycle call returns no Promise, so it throws HoloInputError at the call (collection(), materials.create, on, onFrame, beforeCommit, follow, input.drag): session.collection('c', bad).set(…).catch(…) never reaches its .catch, so wrap such a call in try. A query that matches nothing resolves with matched: 0 and records 'target-unmatched', deferred while a scene write called before it is pending (Report.matched, Report.pending). Asset failures in declarative writes are reported in Report.problems, never thrown. instanceof against this package's Holo*Error classes holds for errors the loaded runtime build throws, although the two are different class objects: each class checks a brand (Symbol.for('holo.error') and its name) that the runtime sets on every error it throws.
• Look writes (rules, collections, materials, stage, camera, overlays) are presentation only. They are never priced and never part of a saved configuration.
• Two documents. The viewer document (session.document) holds page defaults: stage, camera, limits and lens; "the document's" value means its merged value. The stored configurator (IConfigurator; the runtime's copy is the scene model, getSceneModel()) holds nodes, their poses and the selected materials; "the scene model's" means that.
• Examples compile under strict TypeScript with noUncheckedIndexedAccess (an indexed read may be undefined: check it before use) and run on the fake (/testing). They assume session: Session and signal: AbortSignal in scope and this package's exports imported; the app functions they call are written as declare lines. The imports are left out for brevity only: app code imports every name it uses, values (has, validate, the Holo*Error classes, the pure helpers) from the package root and types from /contract: import { has, HoloAssetError } from '@holostep-configurators/runtime-client'; and import type { Session, CameraView } from '@holostep-configurators/runtime-client/contract';. /math and /testing names come from those entry points. Besides the root's app-side boot helpers (loadRuntimeAtFloor, the channel constants, bootFailureAdvice) and /server (spec section 9.1), the package exports only what this file declares: a type your page defines (a store value, an option of your own UI) is your app's even when a runtime call takes it, so declare it in your app and never import it from the package.
• boot, RUNTIME_CONTRACT and RUNTIME_VERSION are not exported by the package root: they are the runtime module's, which the root's loadRuntimeAtFloor(runtimeUrl, required) resolves to once it has checked your floor (src/runtime/REQUIRED_CONTRACT.json). Write const runtime = await loadRuntimeAtFloor(runtimeUrl, required), then runtime.boot(…).