ActivateAROptions.ui ​

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.

Property of ActivateAROptions · labs, @experimental · since 2.0.0

ts
ui?: 'default' | 'headless';

'default' shows Holostep's AR screens; 'headless' lets the page draw its own: Holostep's in-page AR then shows only the camera and the product (no coaching icons, buttons, arrow or sheets) and tells its state through place on 'ar:status'. The page closes it with endAR() (the shopper's back gesture and Escape still close it). A fault that would ask the shopper (the camera or motion refused, the device too hot) ends the session ('xr:end' 'error'), with place saying why. Where the in-page camera route doesn't apply, a headless call opens the native AR viewer (on Android's WebXR route too), or, in an in-app browser where none can open, resolves { launched: false, reason: 'unsupported' } with no sheet. Pair it with overlayRoot for your controls. Check supports('activateAR.ui.headless') first; where it answers false a headless call opens the native AR viewer.

Default: 'default'

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/16-ActivateAROptions.ui.ts):

ts
import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const controls: HTMLElement;
declare const line: HTMLElement;
declare function closeButton(onClick: () => void): void;
const words: Record<string, string> = {
  'point-at-floor': 'Point your phone at the floor',
  'hold-still': 'Hold still',
  'camera-denied': 'Allow the camera to see this in your room',
};
session.on('ar:status', ({ status, place }) => {
  // an id you don't know: show nothing for it (both fields are open sets)
  if (place) line.textContent = words[place.hint] ?? '';
  if (status === 'error') line.textContent = words[place?.hint ?? ''] ?? 'AR did not start.';
}, { signal });
closeButton(() => session.endAR?.());
const headless = session.supports('activateAR.ui.headless');
await session.activateAR(headless ? { ui: 'headless', overlayRoot: controls } : {});

Generic-API test (spec 3.1) ​

Rule Result
1. Neutral name pass: ui names no product
2. A precedent pass: model-viewer canActivateAR and activateAR() (row G66); XRSession.end() (row G66); Navigator.share() (resolves when the share UI closes) (row G66)
3. Two apps, or labs labs (@experimental at a stable path, reached through has() or supports()): it graduates when a second app uses it; apps today: configurator-template, tryon-template
4. The cheaper fix first decided per need in Appendix B: rows G66 at tier labs (a member only where no rule, data, asset or app code serves the need)