# 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.

## One obvious way

You want to… → use … → not … (the declaration header's table):

| You want to… | Use | Not |
| -------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| change a configured material (priced, saved) | select(group, material) | a rule with { materialNodeId }: look only, never priced |
| change a variant, an option's visibility or a position | setSceneModel, or applyPatch with 'replace' ops | find().set({ visible }) or { pose }: a rule, never saved |
| change a connection | assembly.attach / assembly.detach | moving nodes by pose |
| address a placed model as a whole (pose, hide, follow) | node(nodeId) | find({ node }): that matches every part of the model |
| restyle authored parts | find(q).set(…), reset with null | writing the opposite value; writing it every frame |
| build the whole look from app state | one apply(spec); an omitted key stays unchanged | re-applying rules after every sync |
| keep standing rules (hidden planes, ghosts) | find(q).set(…): its block comes after apply()'s | in apply({ rules }): the next apply({ rules }) replaces them |
| show no map on a slot | maps: { slot: 'none' } | null: it removes your value, and the GLB's map shows again |
| preview a flat colour over a textured finish | { baseColor, maps: { baseColor: 'none' } } | baseColor alone: it tints the map (dark wood goes black) |
| switch a whole look, keeping no field of the old one | a Material from materials.create(spec), fadeMs | a MaterialSpec rule write: however complete, it merges |
| switch between partial looks over the GLB's material | apply({ rules }): its block is replaced whole | a second find().set: fields only the old look set stay |
| let the newest write to a rule win | an AbortController per write, abort the previous | call order alone: an older write still shows first |
| retile a texture whose image select() may change | a texture without url: { scale }, { sizeM } | repeating the url: it pins the image |
| generate geometry | collection(name).set(spec) | load() |
| set the page's lighting, background or exposure | the page document's stage; a layer: stage.set | stage.set(s) with no { owner }: it rejects |
| show a GLB you have, with no saved design | setSceneModel({ root: [{ …, enabled: true }] }) | a ModelNode without enabled: true: it is never drawn |
| know a GLB's bounds before placing it | collection(name).load(url, { key }) | mixing load() keys with set() items in one collection |
| make several changes all or nothing, across awaits | transaction(tx => …), writing through tx only | session or its handles inside work |
| make one undo step over time (a drag, an assistant turn) | history.group(), with expectGroup on each write | a transaction: it holds the display |
| undo or redo the last step (a toolbar button) | session.undo() / session.redo() | session.history.undo(): History only reads and groups |
| sync a store into the runtime | setSceneModel with origin, supersede and a label | undo: 'rebase': it erases every earlier step |
| start history clean after a later load (a saved design) | undo: 'rebase' on it; the first model needs none | undo: 'rebase' on a sync that runs after shopper edits |
| show a value you just wrote | the value you wrote, corrected from the Report | reading it back while it is queued (it can take seconds) |
| read the scene model, null before the first one | const m = getSceneModel(); if (!m) … | getSceneModel()!: it hides a page with no model yet |
| capture what the shopper just configured | await idle(); capture(); on HoloBusyError, again | capture() alone: a pick still loading isn't in it |
| move something or the camera every frame | onFrame(f => f.pose(…) / f.camera(…)) | part.set or camera.set in a hook |
| compute layout inside every commit | beforeCommit, through has(); reset its rules | on('committed'): that shows one frame stale |
| use an experimental member or option value | has(session, id); an option value: supports(id) | calling the optional member unguarded |
| check what a frame costs (triangles, draw calls) | if supports('info.scene'): idle(); info().scene | timing frames in onFrame: that measures the device |

## The ten likeliest mistakes

1. **Importing a type your page defines from the package, or leaving out the imports.** Instead: values from the package root, types from `/contract`; declare your own types in your app. The declaration: "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." See [read this first](read-this-first.md#conventions).
2. **Relying on call order for the newest of two writes to one rule.** Instead: an `AbortController` per write; abort the previous one and catch its `AbortError`. The declaration: "For newest wins, give each write its own AbortController and abort the previous one when a new write starts (it rejects AbortError; catch it)". See [`PartActions.set`](api/PartActions.set.md).
3. **Reading a write back while it is queued behind a transaction.** Instead: show the value you wrote and correct it from the Report. The declaration: "Behind an open transaction it settles only when that transaction 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 the value you wrote." See [`Writer.select`](api/Writer.select.md).
4. **Writing through `session` or one of its handles inside a transaction.** Instead: write through the `tx` that `work` receives, and through its handles only. The declaration: "Only writes through `tx` and handles obtained from it belong to it". See [`Session.transaction`](api/Session.transaction.md).
5. **Changing a priced, saved choice with a rule.** Instead: `select(group, material)` for a material; `setSceneModel` or `applyPatch` for a variant. The declaration: "Not for: a priced, saved choice, which is `select(group, material)`." See [`PartState.material`](api/PartState.material.md).
6. **Passing `null` to hide a map.** Instead: `maps: { slot: 'none' }`; `null` only removes your own value. The declaration: "A map slot: a texture; 'none' (no map, whatever is underneath); or null (remove your value and show what is underneath)." See [`TextureSlot`](api/TextureSlot.md).
7. **Writing a `Pose` read straight back as a `PoseInput`.** Instead: copy `{ position, quaternion, scale }`; leave `scale` out only when it holds a 0. The declaration: "Not a `PoseInput`: to write one back, copy `{ position, quaternion, scale }`". See [`Pose`](api/Pose.md).
8. **Passing `undo: 'rebase'` to keep a sync out of history.** Instead: label the sync; a write equal to the current state commits nothing. The declaration: "'rebase' (a reserved label) records no step and rebases history to the result: every earlier step, a shopper's included, can no longer be undone". See [`CommitOptions.undo`](api/CommitOptions.undo.md).
9. **Switching between partial looks with a second `find(q).set({ material })`.** Instead: `apply({ rules })`, whose block is replaced whole, or null the old look's fields. The declaration: "use `apply({ rules })`, whose block is replaced whole, or null that field in the same write". See [`PartActions.set`](api/PartActions.set.md).
10. **Laying out from `on('committed')`, which shows one frame stale.** Instead: `beforeCommit`, reached through `has()`, keeping the `on` branch for a runtime without it. The declaration: "joins each commit, so it never shows one frame stale". See [`Session.beforeCommit`](api/Session.beforeCommit.md).

## Imports

- Values from the root: `import { has, HoloAssetError } from '@holostep-configurators/runtime-client';`
- `boot`, `RUNTIME_CONTRACT` and `RUNTIME_VERSION` from the runtime module the root's loader resolves to: `const runtime = await loadRuntimeAtFloor(runtimeUrl, required);`, then `runtime.boot(…)` (never `import { boot }`).
- Types from `/contract`: `import type { Session, CameraView } from '@holostep-configurators/runtime-client/contract';`
- `/math` and `/testing` names from those entries: `import { mat4 } from '@holostep-configurators/runtime-client/math';`, `import { createFakeSession } from '@holostep-configurators/runtime-client/testing';`
- A type your page defines is your app's: declare it there, never import it from the package.

## Boot a page

The package root's app-side helpers, which `@holostep-configurators/runtime-client` defines beside this declaration (no page of their own under `api/`). Signatures as the package types them:

```ts
// The runtime module at a channel URL, once its RUNTIME_CONTRACT meets your floor (the same major, at
// least `apiVersion`, a document range that holds `documentVersion`); rejects before anything boots.
function loadRuntimeAtFloor(url: string, required: RequiredContract, importer?: (url: string) => Promise<unknown>): Promise<RuntimeModule>;
// Your app's src/runtime/REQUIRED_CONTRACT.json: a 2.0 page requires
// { apiVersion: '2.0.0', documentSchema: 'holo.viewer-document', documentVersion: 2 }.
interface RequiredContract { apiVersion: string; documentSchema: string; documentVersion: number }
// The channels: v1 stable; v2 (the v2 canary for listed accounts, v2 stable for the rest, null
// until 2.0.0 is promoted); the v2 canary for every account, what a 2.0 page uses before that.
// One module per page: the page's first boot picks the channel for every session on it.
const V1_CHANNEL_URL: string, V2_CHANNEL_URL: string, V2_CANARY_CHANNEL_URL: string;
// What to tell the shopper when boot or the module's import failed; sync, pure, never throws.
function bootFailureAdvice(error: unknown, env?: BootEnv): 'update-device' | 'update-browser' | 'enable-3d' | 'retry';
// The browser facts it reads (env defaults to browserBootEnv()).
function browserBootEnv(): BootEnv; // { userAgent: string; maxTouchPoints: number; hasWebGl2: boolean }
// A page document imported as JSON: schema 'holo.viewer-document', version 2, JSON-safe; throws TypeError.
function assertPageDocument(raw: unknown): ViewerDocumentJson;
// Freezes a value and everything it holds, and returns it.
function deepFreeze<T>(value: T): T;
// A stored configurator's id: 24 hex characters.
const OBJECT_ID: RegExp;
```

The boot every page writes: one `try` around the import and the boot, and the advice for the shopper on failure (`HoloBootError.reason` first; an import failure keeps the browser check).

One session per product on screen (`BootOptions.el`): each session holds a WebGL context, and browsers keep about 16 live per page, losing the oldest past that (a boot whose context is lost before its first frame rejects `HoloBootError` 'webgl-context'). A collection grid shows one session and swaps its model, or boots a card's session on hover and destroys it after. Give `el` a CSS size: under 64 CSS px on a side or under `display: none` it records 'host-unsized'.

Log the session's Problems from boot on, one line each: `info().problems` once `boot` resolves, then every `'problem'` event (`console.warn(JSON.stringify(problem))`, or your monitoring). The runtime writes no console line of its own in production, so this log is the only trace of a failed asset, a lost context or a refused write that the page's owner and a support engineer can read. Keep that log in production.

```ts
import { assertPageDocument, bootFailureAdvice, cameraViewFromStored, deepFreeze, loadRuntimeAtFloor, V2_CANARY_CHANNEL_URL } from '@holostep-configurators/runtime-client';
import type { SceneModel, Session } from '@holostep-configurators/runtime-client/contract';
declare const rawPageDocument: unknown; // your page document, imported as JSON
declare function showNotice(advice: 'update-device' | 'update-browser' | 'enable-3d' | 'retry'): void;
const pageDocument = deepFreeze(assertPageDocument(rawPageDocument));
// `scene` is your server's read of the stored configurator, started beside the boot.
export async function start(
  el: HTMLElement,
  accountId: number,
  scene: Promise<SceneModel | null>,
): Promise<Session | null> {
  try {
    const runtime = await loadRuntimeAtFloor(V2_CANARY_CHANNEL_URL, {
      apiVersion: '2.0.0',
      documentSchema: 'holo.viewer-document',
      documentVersion: 2,
    });
    const session = await runtime.boot({ el, accountId, contract: '2.0', document: pageDocument });
    // One line per Problem, production included: the runtime logs none of its own there.
    for (const problem of session.info().problems) console.warn(JSON.stringify(problem));
    session.on('problem', ({ problem }) => console.warn(JSON.stringify(problem)));
    const model = await scene;
    if (!model) showNotice('retry'); // your server could not read it
    else {
      await session.setSceneModel(model); // the session's first model
      // The start view: no scene write moves the camera, so set it after the first model.
      await (model.defaultView
        ? session.camera.set(cameraViewFromStored(model.defaultView), { durationMs: 0 })
        : session.camera.fit(undefined, { durationMs: 0 }));
    }
    return session;
  } catch (error) {
    showNotice(bootFailureAdvice(error));
    return null;
  }
}
```

### Boot without a bundler

A page with no build step (a Shopify theme section, a CMS block, a static HTML page) can't install the package. It imports the runtime module straight from its channel URL, the value of `V2_CANARY_CHANNEL_URL` (`V2_CHANNEL_URL` once 2.0.0 is promoted). That module exports `boot`, `RUNTIME_CONTRACT`, `RUNTIME_VERSION` and the `Holo*Error` classes. The page writes the root helpers it needs inline: `meetsFloor` is `loadRuntimeAtFloor`'s check, `advice` is `bootFailureAdvice`'s table, and `startView` is `cameraViewFromStored` with its camera write: no scene write moves the camera, so after the first model the page sets its start view, the stored `defaultView`, else a fit, or a product much smaller or larger than a metre starts as a speck or cropped. The root's other values (`has`, `validate`, `checkAsset`) are for build-time code and tests. The scene model comes from your own server, as on any page (next section).

```html
<div id="viewer" role="group" aria-label="Product view" style="height: 480px"></div>
<p id="viewer-notice" hidden></p>
<script type="module">
  const RUNTIME_URL = 'https://onsite.holostep.io/serve/runtime/v2-canary/configurator-runtime.js';
  const ACCOUNT_ID = 164; // your Holostep account id
  const CONFIGURATOR_ID = '66f1c0ffee0000000000abcd'; // its stored viewer-document layer
  // Your server's route: it reads the stored configurator with your API key (next section).
  const SCENE_URL = `/apps/holostep/scene/${CONFIGURATOR_ID}`;
  const NOTICE = {
    'update-device': 'Update your device to see this product in 3D.',
    'update-browser': 'Update your browser to see this product in 3D.',
    'enable-3d': 'Turn on hardware acceleration in your browser to see this product in 3D.',
    retry: 'The 3D view did not start. Reload the page to try again.',
  };
  // loadRuntimeAtFloor's check: major 2, at least 2.0.0, and a document range that holds 2.
  function meetsFloor(contract) {
    return (
      /^2\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(String(contract?.apiVersion)) &&
      contract.documentSchema === 'holo.viewer-document' &&
      contract.documentVersions.min <= 2 &&
      contract.documentVersions.max >= 2
    );
  }
  // bootFailureAdvice's table: HoloBootError.reason first; any other error (the import
  // rejected) keeps the browser check.
  function advice(error) {
    const reason = error?.name === 'HoloBootError' ? error.reason
      : typeof WebGL2RenderingContext === 'undefined' ? 'no-webgl2' : 'other';
    if (reason === 'no-webgl2') {
      const apple = /iPhone|iPad|iPod/.test(navigator.userAgent) ||
        (/Macintosh/.test(navigator.userAgent) && navigator.maxTouchPoints > 1);
      return apple ? 'update-device' : 'update-browser';
    }
    return reason === 'webgl-context' ? 'enable-3d' : 'retry';
  }
  function showNotice(key) {
    const notice = document.getElementById('viewer-notice');
    notice.textContent = NOTICE[key];
    notice.hidden = false;
  }
  // The start view: no scene write moves the camera, so the page sets it after the first model.
  // A stored view converts as the package's cameraViewFromStored does (degrees; a stored
  // `position` wins over the angles; points copied as { x, y, z }); none frames the product.
  function startView(session, view) {
    if (!view) return session.camera.fit(undefined, { durationMs: 0 });
    const xyz = (p) => ({ x: p.x, y: p.y, z: p.z });
    const t = xyz(view.target);
    const p = view.position && xyz(view.position);
    const d = p && { x: p.x - t.x, y: p.y - t.y, z: p.z - t.z };
    const deg = 180 / Math.PI;
    const camera = d
      ? {
          azimuthDeg: Math.atan2(d.x, d.z) * deg,
          polarDeg: Math.atan2(Math.hypot(d.x, d.z), d.y) * deg,
          distance: Math.hypot(d.x, d.y, d.z),
        }
      : { azimuthDeg: view.azimuth, polarDeg: view.polar, distance: view.radius };
    const focal = view.focalOffset ? { focalOffset: xyz(view.focalOffset) } : {};
    return session.camera.set({ target: t, ...camera, ...focal }, { durationMs: 0 });
  }
  const el = document.getElementById('viewer');
  // Started beside boot, so it adds no round trip.
  const scene = fetch(SCENE_URL).then((r) => (r.ok ? r.json() : null)).catch(() => null);
  try {
    const runtime = await import(RUNTIME_URL);
    if (!meetsFloor(runtime.RUNTIME_CONTRACT)) {
      throw new Error(`runtime ${runtime.RUNTIME_VERSION} is below this page's floor 2.0.0`);
    }
    const session = await runtime.boot({
      el, accountId: ACCOUNT_ID, configuratorId: CONFIGURATOR_ID, contract: '2.0',
    });
    // One line per Problem, production included: the runtime logs none of its own there.
    for (const problem of session.info().problems) console.warn(JSON.stringify(problem));
    session.on('problem', ({ problem }) => console.warn(JSON.stringify(problem)));
    const model = await scene;
    if (model) {
      await session.setSceneModel(model); // the session's first model
      await startView(session, model.defaultView);
    } else showNotice('retry');
  } catch (error) {
    console.error(error);
    showNotice(advice(error));
  }
</script>
```

What to tell the shopper, by what failed (`advice` above):

| What failed | `reason` | Advice |
| --- | --- | --- |
| `boot` rejected HoloBootError `'no-webgl2'` | `'no-webgl2'` | 'update-device' on an iPhone, iPad or iPod, else 'update-browser' |
| `boot` rejected HoloBootError `'webgl-context'` | `'webgl-context'` | 'enable-3d' |
| `boot` rejected HoloBootError `'disconnected'`, `'other'` or a newer value | `'disconnected'`, `'other'` | 'retry' |
| the import rejected (offline, a blocked script, a browser that can't parse the module) | none: no HoloBootError | 'update-device' or 'update-browser' without WebGL 2, else 'retry' |
| the module is below your floor (`meetsFloor` false) | none | 'retry' |

`HoloBootError` is told by its `name`, since a page with no package has no class to test `instanceof` against before the import resolves. An invalid option rejects HoloInputError and an aborted boot AbortError, as on any page.

### Your server's read of the stored configurator

`boot` reads no scene model: your own server reads the stored configurator with your API key and your page passes it to its first `setSceneModel` (the `boot` example). The route is `GET https://onsite-backend.holostep.io/api/v1/configurator/load/<configuratorId>` with the header `Authorization: Bearer <your API key>`, a key of your account with the `configurator:read` permission. The answer's `configuration` is the stored configurator (`IConfigurator`, which `setSceneModel` takes as its `SceneModel`). Read it on your server only, never from the page: the key must not reach the browser, and a request without it answers 400 'Authentication required'. An invalid or expired key answers 401, a key without `configurator:read` 403, and an id of another account or an inactive configurator 404.

```ts
import type { IConfigurator } from '@holostep-configurators/runtime-client/contract';
declare const HOLOSTEP_API_KEY: string; // from your server's secret store
// On your server (a Node route, an edge function, a Shopify app proxy).
export async function loadStoredConfigurator(configuratorId: string): Promise<IConfigurator> {
  const response = await fetch(
    `https://onsite-backend.holostep.io/api/v1/configurator/load/${encodeURIComponent(configuratorId)}`,
    {
      headers: { authorization: `Bearer ${HOLOSTEP_API_KEY}` },
      signal: AbortSignal.timeout(10_000),
    },
  );
  if (!response.ok) throw new Error(`configurator ${configuratorId}: HTTP ${response.status}`);
  const body = (await response.json()) as { configuration?: IConfigurator };
  if (!body.configuration) throw new Error(`configurator ${configuratorId}: no configuration`);
  return body.configuration; // cache it: the page asks for it on every view
}
```

### Preload the model

Give the page one `<link rel="preload" as="fetch" crossorigin>` per model URL it boots with: the model then downloads beside the runtime module instead of after your first `setSceneModel`. Your server already holds the scene model (previous section), so it writes the links into the page's `<head>`:

```html
<!-- before: the model starts downloading only after the runtime has loaded and booted -->
<script type="module" src="/configurator.js"></script>
<!-- after: one link per model the first frame shows -->
<link rel="preload" as="fetch" crossorigin href="https://cdn.example.com/models/product.glb">
<script type="module" src="/configurator.js"></script>
```

- Measured: the first product frame shows up to about 1.5 s sooner on Fast 4G and 3-4 s sooner on Slow 4G for large models. `boot` itself resolves 0.2-2 s later, since the preload competes with the runtime's own chunks: time the product frame, not `boot`.
- `crossorigin` is required. The runtime fetches models in CORS mode; a preload without it matches in no engine, so the model is requested twice (Chrome, Safari and Firefox).
- The URL is the one the runtime fetches, byte for byte: a model node's `optGlbUrl` when it has one, else its `glbUrl` (a `.holo` too), absolute (a relative one resolves beneath `assetBaseUrl`). Preload only what the first frame shows: a preload the page never uses costs the shopper's bandwidth and a console warning. On slow links Safari can warn that the preload was not used within a few seconds even when the runtime used it: check that the Network panel shows one model request.

## Read next

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

## Call paths

Each call you write from `session` and its page; a write's page is on the interface that declares it (`Writer` for the session's writes, which a `tx` shares). Every member's path is in `index.json`'s `callPaths`.

- `session.activateAR` → [Session.activateAR](api/Session.activateAR.md)
- `session.animations.list` → [Animations.list](api/Animations.list.md)
- `session.animations.pause` → [Animations.pause](api/Animations.pause.md)
- `session.animations.play` → [Animations.play](api/Animations.play.md)
- `session.animations.reset` → [Animations.reset](api/Animations.reset.md)
- `session.animations.stop` → [Animations.stop](api/Animations.stop.md)
- `session.apply` → [Writer.apply](api/Writer.apply.md)
- `session.applyDocument` → [Session.applyDocument](api/Session.applyDocument.md)
- `session.applyPatch` → [Writer.applyPatch](api/Writer.applyPatch.md)
- `session.assembly.attach` → [Assembly.attach](api/Assembly.attach.md)
- `session.assembly.candidates` → [Assembly.candidates](api/Assembly.candidates.md)
- `session.assembly.connections` → [Assembly.connections](api/Assembly.connections.md)
- `session.assembly.connectors` → [Assembly.connectors](api/Assembly.connectors.md)
- `session.assembly.detach` → [Assembly.detach](api/Assembly.detach.md)
- `session.beforeCommit` → [Session.beforeCommit](api/Session.beforeCommit.md)
- `session.camera.autoRotate` → [Camera.autoRotate](api/Camera.autoRotate.md)
- `session.camera.fit` → [Camera.fit](api/Camera.fit.md)
- `session.camera.lens` → [Camera.lens](api/Camera.lens.md)
- `session.camera.limits` → [Camera.limits](api/Camera.limits.md)
- `session.camera.mode` → [Camera.mode](api/Camera.mode.md)
- `session.camera.project` → [Camera.project](api/Camera.project.md)
- `session.camera.ray` → [Camera.ray](api/Camera.ray.md)
- `session.camera.set` → [Camera.set](api/Camera.set.md)
- `session.camera.views.go` → [Camera.views.go](api/Camera.views.go.md)
- `session.canTryOn` → [Session.canTryOn](api/Session.canTryOn.md)
- `session.capture` → [Session.capture](api/Session.capture.md)
- `session.collection` → [Writer.collection](api/Writer.collection.md)
- `session.collection(name, options).dispose` → [Collection.dispose](api/Collection.dispose.md)
- `session.collection(name, options).load` → [Collection.load](api/Collection.load.md)
- `session.collection(name, options).part` → [Collection.part](api/Collection.part.md)
- `session.collection(name, options).part(key).bounds` → [PartActions.bounds](api/PartActions.bounds.md)
- `session.collection(name, options).part(key).find` → [PartActions.find](api/PartActions.find.md)
- `session.collection(name, options).part(key).follow` → [PartActions.follow](api/PartActions.follow.md)
- `session.collection(name, options).part(key).set` → [PartActions.set](api/PartActions.set.md)
- `session.collection(name, options).set` → [Collection.set](api/Collection.set.md)
- `session.describe` → [Session.describe](api/Session.describe.md)
- `session.destroy` → [Session.destroy](api/Session.destroy.md)
- `session.endAR` → [Session.endAR](api/Session.endAR.md)
- `session.export` → [Session.export](api/Session.export.md)
- `session.find` → [Writer.find](api/Writer.find.md)
- `session.find(query).bounds` → [PartActions.bounds](api/PartActions.bounds.md)
- `session.find(query).find` → [PartActions.find](api/PartActions.find.md)
- `session.find(query).first` → [Parts.first](api/Parts.first.md)
- `session.find(query).first().bounds` → [PartActions.bounds](api/PartActions.bounds.md)
- `session.find(query).first().find` → [PartActions.find](api/PartActions.find.md)
- `session.find(query).first().follow` → [PartActions.follow](api/PartActions.follow.md)
- `session.find(query).first().set` → [PartActions.set](api/PartActions.set.md)
- `session.find(query).follow` → [PartActions.follow](api/PartActions.follow.md)
- `session.find(query).list` → [Parts.list](api/Parts.list.md)
- `session.find(query).list().bounds` → [PartActions.bounds](api/PartActions.bounds.md)
- `session.find(query).list().find` → [PartActions.find](api/PartActions.find.md)
- `session.find(query).list().follow` → [PartActions.follow](api/PartActions.follow.md)
- `session.find(query).list().set` → [PartActions.set](api/PartActions.set.md)
- `session.find(query).set` → [PartActions.set](api/PartActions.set.md)
- `session.getSceneModel` → [Writer.getSceneModel](api/Writer.getSceneModel.md)
- `session.history.group` → [History.group](api/History.group.md)
- `session.history.group(options).commit` → [HistoryGroup.commit](api/HistoryGroup.commit.md)
- `session.idle` → [Session.idle](api/Session.idle.md)
- `session.info` → [Session.info](api/Session.info.md)
- `session.input.drag` → [Input.drag](api/Input.drag.md)
- `session.input.pick` → [Input.pick](api/Input.pick.md)
- `session.input.raycast` → [Input.raycast](api/Input.raycast.md)
- `session.input.revert` → [Input.revert](api/Input.revert.md)
- `session.input.startDrag` → [Input.startDrag](api/Input.startDrag.md)
- `session.labs.decal` → [Labs.decal](api/Labs.decal.md)
- `session.labs.fire` → [Labs.fire](api/Labs.fire.md)
- `session.labs.geometry.read` → [Labs.geometry.read](api/Labs.geometry.read.md)
- `session.labs.geometry.write` → [Labs.geometry.write](api/Labs.geometry.write.md)
- `session.labs.lightLinking` → [Labs.lightLinking](api/Labs.lightLinking.md)
- `session.labs.mirror` → [Labs.mirror](api/Labs.mirror.md)
- `session.labs.prefetch` → [Labs.prefetch](api/Labs.prefetch.md)
- `session.labs.shading.graph` → [Labs.shading.graph](api/Labs.shading.graph.md)
- `session.labs.shading.graph(uniforms, build, options).dispose` → [Shading.dispose](api/Shading.dispose.md)
- `session.labs.shading.graph(uniforms, build, options).set` → [Shading.set](api/Shading.set.md)
- `session.labs.skin` → [Labs.skin](api/Labs.skin.md)
- `session.materials.create` → [Materials.create](api/Materials.create.md)
- `session.materials.create(spec, options).dispose` → [Material.dispose](api/Material.dispose.md)
- `session.materials.get` → [Materials.get](api/Materials.get.md)
- `session.node` → [Writer.node](api/Writer.node.md)
- `session.node(nodeId).bounds` → [PartActions.bounds](api/PartActions.bounds.md)
- `session.node(nodeId).find` → [PartActions.find](api/PartActions.find.md)
- `session.node(nodeId).find(query).bounds` → [PartActions.bounds](api/PartActions.bounds.md)
- `session.node(nodeId).find(query).find` → [PartActions.find](api/PartActions.find.md)
- `session.node(nodeId).find(query).first` → [Parts.first](api/Parts.first.md)
- `session.node(nodeId).find(query).follow` → [PartActions.follow](api/PartActions.follow.md)
- `session.node(nodeId).find(query).list` → [Parts.list](api/Parts.list.md)
- `session.node(nodeId).find(query).set` → [PartActions.set](api/PartActions.set.md)
- `session.node(nodeId).follow` → [PartActions.follow](api/PartActions.follow.md)
- `session.node(nodeId).set` → [PartActions.set](api/PartActions.set.md)
- `session.on` → [Session.on](api/Session.on.md)
- `session.on('anchors:moved')` → [Events.anchors:moved](api/Events.anchors_moved.md)
- `session.on('animation:finished')` → [Events.animation:finished](api/Events.animation_finished.md)
- `session.on('animation:started')` → [Events.animation:started](api/Events.animation_started.md)
- `session.on('animation:stopped')` → [Events.animation:stopped](api/Events.animation_stopped.md)
- `session.on('ar:modes')` → [Events.ar:modes](api/Events.ar_modes.md)
- `session.on('ar:status')` → [Events.ar:status](api/Events.ar_status.md)
- `session.on('assembly:changed')` → [Events.assembly:changed](api/Events.assembly_changed.md)
- `session.on('camera:changed')` → [Events.camera:changed](api/Events.camera_changed.md)
- `session.on('camera:control-end')` → [Events.camera:control-end](api/Events.camera_control-end.md)
- `session.on('camera:control-start')` → [Events.camera:control-start](api/Events.camera_control-start.md)
- `session.on('camera:rest')` → [Events.camera:rest](api/Events.camera_rest.md)
- `session.on('click')` → [Events.click](api/Events.click.md)
- `session.on('committed')` → [Events.committed](api/Events.committed.md)
- `session.on('document:applied')` → [Events.document:applied](api/Events.document_applied.md)
- `session.on('drag:end')` → [Events.drag:end](api/Events.drag_end.md)
- `session.on('drag:move')` → [Events.drag:move](api/Events.drag_move.md)
- `session.on('drag:start')` → [Events.drag:start](api/Events.drag_start.md)
- `session.on('history:changed')` → [Events.history:changed](api/Events.history_changed.md)
- `session.on('hotspot:click')` → [Events.hotspot:click](api/Events.hotspot_click.md)
- `session.on('hotspot:hover')` → [Events.hotspot:hover](api/Events.hotspot_hover.md)
- `session.on('hover')` → [Events.hover](api/Events.hover.md)
- `session.on('material:selected')` → [Events.material:selected](api/Events.material_selected.md)
- `session.on('problem')` → [Events.problem](api/Events.problem.md)
- `session.on('resize')` → [Events.resize](api/Events.resize.md)
- `session.on('scene-model:changed')` → [Events.scene-model:changed](api/Events.scene-model_changed.md)
- `session.on('xr:cta')` → [Events.xr:cta](api/Events.xr_cta.md)
- `session.on('xr:end')` → [Events.xr:end](api/Events.xr_end.md)
- `session.on('xr:start')` → [Events.xr:start](api/Events.xr_start.md)
- `session.onFrame` → [Session.onFrame](api/Session.onFrame.md)
- `session.overlays.anchors.clear` → [Overlays.anchors.clear](api/Overlays.anchors.clear.md)
- `session.overlays.anchors.set` → [Overlays.anchors.set](api/Overlays.anchors.set.md)
- `session.overlays.dimensions` → [Overlays.dimensions](api/Overlays.dimensions.md)
- `session.overlays.hotspots.clear` → [Overlays.hotspots.clear](api/Overlays.hotspots.clear.md)
- `session.overlays.hotspots.set` → [Overlays.hotspots.set](api/Overlays.hotspots.set.md)
- `session.permits` → [Session.permits](api/Session.permits.md)
- `session.redo` → [Session.redo](api/Session.redo.md)
- `session.select` → [Writer.select](api/Writer.select.md)
- `session.setSceneModel` → [Writer.setSceneModel](api/Writer.setSceneModel.md)
- `session.stage.get` → [Stage.get](api/Stage.get.md)
- `session.stage.set` → [Stage.set](api/Stage.set.md)
- `session.state` → [Writer.state](api/Writer.state.md)
- `session.supports` → [Session.supports](api/Session.supports.md)
- `session.transaction` → [Session.transaction](api/Session.transaction.md)
- `session.tryOn` → [Session.tryOn](api/Session.tryOn.md)
- `session.undo` → [Session.undo](api/Session.undo.md)

## API pages

### 1. Basics

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

### 2. Operations, reports, causes, problems

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

### 3. Errors

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

### 4. Boot

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

### 5. Writers, transactions, session

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

### 6. Queries, rules and parts

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

### 7. Collections and shapes

- [CollectionOptions](api/CollectionOptions.md): What `collection(name, options)` takes.
- [Collection](api/Collection.md): Content you create.
- [CollectionReport](api/CollectionReport.md): `updated`: keys of items changed in place.
- [CollectionSpec](api/CollectionSpec.md): JSON form of a collection's content.
- [ItemBase](api/ItemBase.md): The fields every collection item has.
- [ItemSpec](api/ItemSpec.md): One collection item: `ItemBase` plus one kind.
- [Outline2D](api/Outline2D.md): Outline segments in 2D.
- [ShapeRef](api/ShapeRef.md): 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](api/Shape.md): Built shapes.
- [LinesSpec](api/LinesSpec.md): A lines item: a polyline in item-local metres.
- [LabelSpec](api/LabelSpec.md): A label drawn in the scene (text or image on a quad facing the camera).
- [LightSpec](api/LightSpec.md): Light intensity: KHR_lights_punctual units ×1, relative and not photometric (a sun of 3 lights white to about 1).
- [ShadowSpec](api/ShadowSpec.md): 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](api/MaterialInput.md): A MaterialSpec, however complete, merges field by field (RFC 7396) over what the part wears (authored maps such as baked AO stay).
- [MapSlot](api/MapSlot.md): The map slots of a material (glTF and KHR names).
- [TextureSlot](api/TextureSlot.md): A map slot: a texture; 'none' (no map, whatever is underneath); or null (remove your value and show what is underneath).
- [Wrap](api/Wrap.md): How a texture repeats outside 0..1.
- [TextureSampling](api/TextureSampling.md): How a texture is filtered.
- [TextureInput](api/TextureInput.md): A URL, or a texture with placement.
- [ImageRef](api/ImageRef.md): How reads return a texture you wrote as an `image`: JSON, so `state()`, the feed, `applyPatch` and `sceneHash` stay JSON.
- [TextureSpec](api/TextureSpec.md): At most one of `url` and `image`.
- [MaterialSpec](api/MaterialSpec.md): glTF 2.0 and KHR names.
- [MaterialPatch](api/MaterialPatch.md): A MaterialSpec as a JSON Merge Patch (RFC 7396): what a rule's `material` takes.
- [Material](api/Material.md): A material parts wear: one `Part.material` reads, or one `materials.create` makes.
- [Materials](api/Materials.md): Create reusable materials and read stored ones.

### 9. Stage

- [BackgroundSpec](api/BackgroundSpec.md): What is drawn behind the scene, in the colour pipeline.
- [StageSettings](api/StageSettings.md): Colour pipeline: shading is linear Rec.709 in a frame of at least half-float.
- [StageWriteOptions](api/StageWriteOptions.md): The member options of `stage.set`.
- [Stage](api/Stage.md): The stage: layered settings over the document's.
- [RuleSpec](api/RuleSpec.md): One persistent rule in JSON form: what `find(query).set(set)` creates.
- [SceneSpec](api/SceneSpec.md): The look as one JSON document: what `apply()` writes (`state().look` reads it back as a `LookState`).
- [LookState](api/LookState.md): 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](api/CameraView.md): Orbit view.
- [LookAtView](api/LookAtView.md): A view by eye point and target.
- [CameraState](api/CameraState.md): Observed: as of the last drawn frame (this frame's inside `onFrame({ phase: 'late' })`).
- [CameraLimits](api/CameraLimits.md): A JSON Merge Patch (RFC 7396) over your app limits, which lie over the document's.
- [CameraLens](api/CameraLens.md): The camera's lens.
- [CameraMoveOptions](api/CameraMoveOptions.md): The member options of a camera move.
- [Camera](api/Camera.md): 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](api/PickOptions.md): What `input.pick` takes.
- [RaycastOptions](api/RaycastOptions.md): What `input.raycast` takes.
- [DragMove](api/DragMove.md): One frame of a drag.
- [DragOptions](api/DragOptions.md): What `input.drag` takes.
- [Input](api/Input.md): Picking, raycasts and drags on the canvas.

### 12. Assembly

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

### 13. Overlays

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

### 14. Animations

- [ClipRef](api/ClipRef.md): Which clip: where its GLB sits and its name.
- [ClipInfo](api/ClipInfo.md): One authored clip of a loaded model.
- [PlayOptions](api/PlayOptions.md): The member options of `animations.play`.
- [Animations](api/Animations.md): 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](api/Frame.md): The synchronous per-frame writer for `onFrame` and drag `constrain`.

### 16. Capture, export, AR

- [CaptureSpec](api/CaptureSpec.md): What `capture` takes.
- [CaptureResult](api/CaptureResult.md): What a capture returns.
- [ExportOptions](api/ExportOptions.md): What `export` takes.
- [ExportResult](api/ExportResult.md): What `export` returns.
- [ActivateAROptions](api/ActivateAROptions.md): What `activateAR` takes.
- [ActivateARReport](api/ActivateARReport.md): How an AR launch went.
- [TryOnKind](api/TryOnKind.md): 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](api/TryOnMode.md): Where try-on runs: 'here' in this page, 'handoff' on another device, a phone that opens the hand-off's link (`TryOnReport.handoffUrl`).
- [TryOnUnavailable](api/TryOnUnavailable.md): 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](api/TryOnAvailability.md): `canTryOn()`'s answer for the product on screen, now.
- [TryOnOptions](api/TryOnOptions.md): What `tryOn` takes.
- [TryOnReport](api/TryOnReport.md): What `tryOn` resolves with once try-on closed or could not open.

### 17. Assets: describe, manifest, validation

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

### 18. Events

- [Events](api/Events.md): Typed events.

### 19. Info and capabilities

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

### 20. Labs

- [GeometryAttribute](api/GeometryAttribute.md): A vertex attribute `labs.geometry.read` can return.
- [GeometryData](api/GeometryData.md): Local space of the part (for a skinned mesh: its bind space).
- [GeometryWrite](api/GeometryWrite.md): New vertex data for `labs.geometry.write`: same vertex count and order as the part's.
- [SkinBinding](api/SkinBinding.md): Binds a collection mesh to a loaded model's skeleton.
- [DecalSpec](api/DecalSpec.md): A projected decal with depth.
- [FireSpec](api/FireSpec.md): Volumetric fire, as `labs.fire` draws it.
- [ShadingUniformType](api/ShadingUniformType.md): The type of a shading graph input.
- [ShadingNode](api/ShadingNode.md): A node output in a shading graph, typed by what it carries.
- [ShadingNodes](api/ShadingNodes.md): 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](api/ShadingOutputs.md): The camelCased `gltf_pbr` inputs; omitted ones keep the material's.
- [ShadingValue](api/ShadingValue.md): 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](api/Shading.md): A shading graph, worn through `MaterialSpec.labs.shading`.
- [Labs](api/Labs.md): Members that serve one app or wrap an engine-shaped capability.

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

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

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

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

### 23. /math

- [math.Mat4](api/math.Mat4.md): A 4×4 affine matrix: 16 values, column-major (as glTF and `Shape.transform`).
- [math.vec3](api/math.vec3.md): 3D vectors and points.
- [math.quat](api/math.quat.md): Unit quaternions.
- [math.mat4](api/math.mat4-value.md): 4×4 matrices.
- [math.box3](api/math.box3.md): Axis-aligned boxes.
- [math.ray](api/math.ray.md): Rays.
- [math.plane](api/math.plane.md): Planes as `{ normal, constant }`: the points p with dot(normal, p) + constant = 0.
- [math.outline](api/math.outline.md): 2D outlines for shapes.
- [math.color](api/math.color.md): sRGB hex colours and linear components.
- [math.angle](api/math.angle.md): Angles.
- [math.projection](api/math.projection.md): 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](api/testing.FakeModel.md): A GLB as the fake knows it: its node tree, connectors, manifest, clips and load behaviour.
- [testing.FakeSessionOptions](api/testing.FakeSessionOptions.md): What `createFakeSession` takes.
- [testing.TraceEntry](api/testing.TraceEntry.md): One step of an operation through the states of spec section 6.2.
- [testing.FakeSession](api/testing.FakeSession.md): A `Session` that runs in Node with fake timers, plus controls for tests.
- [testing.createFakeSession](api/testing.createFakeSession.md): A fake session: the runtime's own implementation of the spec's section 6 tables, without a renderer.
- [testing.fakeModelFromGlb](api/testing.fakeModelFromGlb.md): 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](api/testing.ManifestFromGlbOptions.md): What `manifestFromGlb` takes besides the bytes.
- [testing.manifestFromGlb](api/testing.manifestFromGlb.md): 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](problems/target-unmatched.md): 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](problems/target-ambiguous.md): A single-part member (`follow` target, `attachTo`) matched several parts; nothing applied.
- [asset-failed](problems/asset-failed.md): A GLB, texture or HDR failed in a declarative write; the write committed without it.
- [asset-degraded](problems/asset-degraded.md): 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](problems/ready-timeout.md): Readiness expired: the commit shows with stand-ins or old looks until assets decode.
- [transaction-timeout](problems/transaction-timeout.md): A transaction made no progress for `timeoutMs`, or hit the hold cap; it rolled back.
- [write-after-close](problems/write-after-close.md): A write through a closed `tx` or its handles (HoloTransactionClosedError).
- [beforeCommit-threw](problems/beforeCommit-threw.md): A `beforeCommit` function threw, or was pending after 10 s; its writes were undone.
- [beforeCommit-slow](problems/beforeCommit-slow.md): 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](problems/connection-stale.md): A connection's planes no longer meet (0.5 mm, 0.5°); it was dropped.
- [handle-disposed](problems/handle-disposed.md): A disposed handle or removed part was used; nothing happened.
- [owner-disposed](problems/owner-disposed.md): 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](problems/unsupported-spec.md): 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](problems/not-storable.md): 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](problems/space-not-storable.md): 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](problems/frame-needs-compile.md): A `Frame.material` value needs a new shader; it was skipped.
- [frame-budget](problems/frame-budget.md): 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](problems/handler-threw.md): An event handler or frame hook threw (a hook that throws 3 frames in a row is removed: 'hook-removed').
- [hook-removed](problems/hook-removed.md): 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](problems/handler-async.md): An event handler returned a Promise (an untyped call); it was not awaited.
- [handler-rejected](problems/handler-rejected.md): A Promise an event handler returned rejected.
- [engine-conflict](problems/engine-conflict.md): Another 3D engine instance on the page conflicts with the runtime's (`info().renderer.engineConflict`).
- [tenant-document-absent](problems/tenant-document-absent.md): No stored viewer-document layer for `configuratorId` (a 404; `info().document.layers` 'tenant'): the layers below apply.
- [tenant-document-unavailable](problems/tenant-document-unavailable.md): The stored viewer-document layer couldn't be fetched (any failure but a 404); the session runs with the layers below.
- [defaults-unavailable](problems/defaults-unavailable.md): The platform or account defaults couldn't be fetched; built-in defaults apply.
- [document-error](problems/document-error.md): A document layer has an invalid or version-1 key; `didYouMean` names its 2.0 home.
- [apply-failed](problems/apply-failed.md): 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](problems/sync-failed.md): 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](problems/host-disconnected.md): `el` left the document after `boot`, which freed the renderer for good (spec section 6.5).
- [render-lost](problems/render-lost.md): The view stopped drawing: the graphics context was lost and came back neither on its own nor on a fresh canvas.
- [host-unsized](problems/host-unsized.md): `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](problems/unknown-boot-option.md): `boot` got an option this contract doesn't have; it was ignored.
- [unknown-event](problems/unknown-event.md): `on()` got an event name that doesn't exist; it subscribed to nothing.
- [invalid-input](problems/invalid-input.md): A call rejected or threw HoloInputError; recorded so an unawaited one is never silent.
- [hotspot-id-taken](problems/hotspot-id-taken.md): Two hotspot badges share an `id`; the later one is skipped.
- [deprecated](problems/deprecated.md): Reserved for a labs member or value that will change; the strict fake throws on it.
- [not-permitted](problems/not-permitted.md): A gated capability this account may not use (`permits()` is false).
- [unknown-capability](problems/unknown-capability.md): `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](problems/connections-outdated.md): Stored connections whose `connectionsBasis` no longer matches their nodes: none restored.
- [read-while-queued](problems/read-while-queued.md): Strict fake only: code read a target that still had a write queued behind a transaction.

### Input-error codes (`InputErrorCode`)

- [invalid-input](input-errors/invalid-input.md): A value or combination the member refuses, e.g. a zero `PoseInput.scale` component.
- [missing-node-id](input-errors/missing-node-id.md): A node without a `nodeId` (spec section 6.9, ID9).
- [duplicate-node-id](input-errors/duplicate-node-id.md): Two nodes share a `nodeId` (ID9); `normalizeNodeIds` repairs an old save.
- [rotation-twice](input-errors/rotation-twice.md): An untyped pose or patch with both rotations, `rotationDeg` and `quaternion`.
- [unknown-field](input-errors/unknown-field.md): 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](input-errors/unknown-id.md): 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](input-errors/option-in-transaction.md): A commit option passed through a `tx` by an untyped call; always thrown at the call.
- [collection-role-mismatch](input-errors/collection-role-mismatch.md): `collection()` on a live name with another role.
- [collection-options-mismatch](input-errors/collection-options-mismatch.md): `collection()` on a live name with another `attachTo`.
- [duplicate-rule-id](input-errors/duplicate-rule-id.md): Two rules of one `apply()` `rules` list share an id (spec section 6.10, R3).
- [checkpoint-rejected](input-errors/checkpoint-rejected.md): Page state over 256 KB of canonical JSON (`CheckpointOption`).
- [capture-displayed-fixed](input-errors/capture-displayed-fixed.md): `source: 'displayed'` with a `view`, `size`, `pixelRatio` or a `background` other than 'scene'.
- [not-draggable](input-errors/not-draggable.md): `startDrag` on a unit that no live registration names.

### Issue codes (`IssueCode`)

- [element](issues/element.md): `checkAsset`: the manifest's `element` matches none of the contract's globs.
- [part](issues/part.md): `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](issues/slot.md): `checkAsset`: a contract slot the manifest lacks, or one without `uvMetres` where `realSize` asks for it.
- [connector](issues/connector.md): `checkAsset`: fewer connectors of a type than the contract's `count`.
- [animation](issues/animation.md): `checkAsset`: a contract clip name the asset lacks.
- [connector-name-collision](issues/connector-name-collision.md): `checkAsset`: two connector planes whose authored names clean to the same name (spec section 6.9, ID1).
- [connector-id](issues/connector-id.md): `checkAsset`: an `extras.holostep.connector.id` that contains ':' (ID1).
- [not-storable](issues/not-storable.md): `validate`: a value the stored format can't hold.
- [space-not-storable](issues/space-not-storable.md): `validate('configurator')`: `space: 'parent'` in a document meant to be saved.