# `boot`

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

Function · `const { boot } = await loadRuntimeAtFloor(runtimeUrl, required);` · stable · since 2.0.0 · section 4. Boot

Starts a session in `el`. Resolves once the viewer document (platform, page, account and stored
layers) is applied and the first frame is drawn; where no frame can come, at once instead: a
hidden page (a background tab), and `el` out of the viewport while the page stays visible (a
cross-origin iframe below the fold, whose frames the browser pauses), as [`idle()`](Session.idle.md) ends there. So
an embed below the fold boots, and its model loads, before the shopper scrolls to it; the
first visible frame draws as usual. That frame is model-less: `boot` reads no
scene model. Your page supplies it: your own server reads the stored configurator with your
API key (`GET https://onsite-backend.holostep.io/api/v1/configurator/load/<id>` with
`Authorization: Bearer <key>`, the answer's `configuration`; never from the page, llms.txt's
"Your server's read"), and your first [`setSceneModel`](Writer.setSceneModel.md) after `boot` is the session's first
model (cause 'load', spec section 6.5), committed and drawn as any [`setSceneModel`](Writer.setSceneModel.md) is (readiness and failed
assets: spec section 6.6), its Problems in its Report. Start that read beside `boot`, as the
example does, so it adds no round trip, and show your own failure state when it fails.
`configuratorId` selects the configurator's stored viewer-document layer and names it in
[`info().session`](InfoReport.session.md); it starts no scene-model request. `boot` never rejects for a document fetch:
HoloBootError is the renderer's.
One live session per element; after [`destroy()`](Session.destroy.md) (or the boot signal's abort) the element can be
booted again, into the same shadow root ([`BootOptions.el`](BootOptions.el.md)). A view of no stored configurator (a
catalogue preview, an empty room) omits `configuratorId`.
Timing: rejects AbortError when `signal` aborts first. Errors: rejects HoloInputError on bad
options; an unknown option records 'unknown-boot-option'; rejects HoloBootError (`reason`) when
the renderer can't start, and at once, before any document request, when the browser has no
WebGL 2. A Problem recorded before `boot` resolves (a stored layer's 'tenant-document-absent',
say) reaches no 'problem' handler and no Report: read [`info().problems`](InfoReport.problems.md) once after `boot`, then
subscribe (spec section 5.1).

## Declaration

```ts
export declare function boot(options: BootOptions): Promise<Session>;
```

## Example

Imports: values (`has`, `validate`, the `Holo*Error` classes, the pure helpers) from `@holostep-configurators/runtime-client`, types from `@holostep-configurators/runtime-client/contract`, `/math` and `/testing` names from those entries; `boot` from the runtime module the root's `loadRuntimeAtFloor` resolves to. A type your page defines is your app's: declare it there, never import it from the package.

Compiled under the contract's strict settings (`examples/declaration/04-boot.ts`):

```ts
import { loadRuntimeAtFloor } from '@holostep-configurators/runtime-client';
import type { SceneModel } from '@holostep-configurators/runtime-client/contract';
declare const signal: AbortSignal;
declare const runtimeUrl: string;                      // src/config/runtime.ts: the compiled pin
declare function loadScene(id: string): Promise<SceneModel>; // your server, with your API key
declare function showLoadError(): void;                // app code: a failure state
const unmount = new AbortController();                 // abort it when the view unmounts
const configuratorId = '66f1c0ffee0000000000abcd';     // omit it for no stored configurator
const scene = loadScene(configuratorId).catch(() => null); // beside boot: no extra round trip
// boot is the runtime module's, not the root's: load the module at your floor first.
const runtime = await loadRuntimeAtFloor(runtimeUrl, {
  apiVersion: '2.0.0',                                 // src/runtime/REQUIRED_CONTRACT.json
  documentSchema: 'holo.viewer-document',
  documentVersion: 2,
});
const session = await runtime.boot({
  el: document.getElementById('viewer')!,
  accountId: 164,
  configuratorId,                                      // its stored viewer-document layer
  contract: '2.0',
  signal: unmount.signal,                              // aborting destroys the session
});
for (const p of session.info().problems) console.warn(p.code, p.message); // recorded during boot
session.on('problem', ({ problem }) => console.warn(problem.code, problem.message), {
  signal: unmount.signal,
});
const model = await scene;
if (model) await session.setSceneModel(model);         // the session's first model
else showLoadError();
```

## Generic-API test (spec 3.1)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `boot` names no product |
| 2. A precedent | not recorded: no ledger row (coverage.json) names this member or its owner |
| 3. Two apps, or labs | pass: 28 apps (fleet cross-check: app-04c2774145, app-0c773a4ee3, app-37356bf09f, app-378d190f1b, app-4762caacdc, app-4f16d2f6da, app-4fd23bc869, app-510d750508 and 20 more) |
| 4. The cheaper fix first | not recorded per member (Appendix B decides it per need) |