@virtualdisplay.io/client 4.0.0-alpha.3 → 4.0.0-alpha.32

package/CHANGELOG.md

@@ -1,11 +1,264 @@
 # Changelog
 
-## 4.0.0-alpha.3
+## 4.0.0-alpha.32
+
+### Minor Changes
+
+Add `features` to the app passed to `onAppResolved`: the features switched on for the app's owner, absent when there are none.
+
+Let a submit handler registered with `configuration.onSubmit()` reject with a `DOMException` named `AbortError` when the shopper backs out. The button then returns to its label instead of reading done or failed.
+
+### Patch Changes
+
+Fix the annotation marker control governing only the first model's pins when the viewer shows several models. One press now shows or hides every model's, including one added after the viewer started.
+
+Fix the fullscreen button showing, and doing nothing, inside a frame that does not allow fullscreen.
+
+Fix an error thrown while handling a message from the viewer escaping uncaught instead of being logged.
+
+Fix the AR QR dialog staying on its loading state when the QR code cannot be drawn. It now shows the link to open on a phone instead.
+
+Fix the built-in screenshot button starting a second capture on a repeated click. It now waits for the image, and can be used again if a capture fails.
+
+## 4.0.0-alpha.31
+
+### Minor Changes
+
+Add `label` to `AttributeValue`: the word to show for a value, while `value` stays the key you pass back to `select`. Where the model names none it is the value made readable (`redWine` reads as "Red wine"), and on a measurement it is the size in whole millimetres. The viewer's own interface now renders in the language the model is configured in, where it always rendered English before: the toolbar, the camera controls and the configurator panel.
+
+### Patch Changes
+
+Fix the camera control buttons acting on a different rotation limit than the drag. A limit set on one side only, or a window covering a whole turn, no longer disables a button that bounds nothing, and a window that spans the back of the product now stops the buttons where the drag stops.
+
+Darken the configurator's error colour so its button label reads at a higher contrast against it.
+
+Fix the loading animation running indefinitely when the viewer never starts. If nothing is heard from the viewer within 30 seconds, the load-failure message is shown instead, so a blocked or unreachable viewer ends on a next step rather than a spinner. If the viewer does start after that, loading resumes instead of staying stuck on the failure message.
+
+Round the AR QR code dialog's corners to the same radius as the buttons and controls beside it.
+
+## 4.0.0-alpha.30
+
+### Minor Changes
+
+Export the types that public signatures already hand you. `SelectableSnapshot`, `SelectableAttribute`, `CameraPosition`, `CameraPositionState`, `CameraLimits`, `AnnotationVisibility`, `ViewerSettingsOverride`, `ClientAddress`, `ClientOptionsBase`, `ClientLogger` and `AVAILABILITY` can now be imported by name, so a callback you register or a value you receive can be typed without redeclaring its shape.
+
+### Patch Changes
+
+Drop the internal members from the published type definitions. `camera`, `snapshot`, `focus`, `configuration` and the attribute types now list only what you can call, so editor hover and autocomplete match the documented API.
+
+## 4.0.0-alpha.29
+
+### Major Changes
+
+Rename the two selection events from `ui:select` and `ui:selected` to `vd:select` and `vd:selected`, so every event the client dispatches into your page carries the same `vd:` prefix. Change any `client.on('ui:select', ...)` to `client.on('vd:select', ...)`, and the same for `ui:selected`.
+
+### Patch Changes
+
+Fix duplicated type names in the published type definitions: `ViewerSettings`, `PricingDocument`, `AppSubmitSettings` and `Availability` no longer show up as `ViewerSettings$1` in editor hover and type errors. Type documentation now describes the API you call instead of how the viewer is built.
+
+## 4.0.0-alpha.28
+
+### Minor Changes
+
+Add a marker toggle button to the viewer action bar for apps set to the `toggle-shown` or `toggle-hidden` annotation mode: the visitor shows or hides the annotation markers themselves, with the starting state you configured. The button only appears when the model has annotations and a toggle mode is active.
+
+## 4.0.0-alpha.27
+
+### Minor Changes
+
+Add the per-app annotation visibility modes to the `viewerSettings.annotations` override: `'hide'`, `'show'`, `'toggle-shown'` and `'toggle-hidden'`, besides the existing booleans (`true` maps to `'show'`, `false` to `'hide'`). Markers now follow the mode configured on the app, and an override only speaks up when it differs from that mode.
+
+## 4.0.0-alpha.26
+
+### Minor Changes
+
+Add `app` option to `ClientOptions` as an alternative to the `license` and `model` pair, mounting one specific app by its link key. The pair keeps working unchanged; when both are supplied, `app` wins and a warning is logged that the pair was ignored.
+
+Add `AppType` with the known app types. `ResolvedAppInfo.appType` is typed as a plain string so an app type newer than your bundle still reaches `onAppResolved` for explicit handling.
+
+Add a measurement slider for size attributes. A model that offers a size (width, depth, diameter) now renders it as a slider with the formatted value and unit beside it, and the model follows the drag live while only the released value counts as the chosen size.
+
+Add `slug` to the `onAppResolved` callback payload: the resolved app's public slug, so a host page can address the app it embeds without knowing the slug in advance.
+
+Add `onAppResolved(callback)`. The viewer reports which app it resolved (`appType`, `name`, and public submit settings as `ResolvedAppInfo`), and the callback fires immediately when the report already arrived.
+
+## 4.0.0-alpha.25
+
+### Minor Changes
+
+Add `onSelectableChange(callback)` and `getSelectable(name)` to follow which
+attribute values the buyer can still pick under the current selection. The
+standard sidebar greys out values the selection rules out. Models without
+exclusions behave exactly as before.
+
+## 4.0.0-alpha.24
 
 ### Patch Changes
 
+Accept `undefined` for the optional `ClientOptions` fields `language`, `debug` and `traceparent`. Projects that enable `exactOptionalPropertyTypes` can now pass a possibly-undefined value straight through without a type error.
+
+## 4.0.0-alpha.23
+
+### Patch Changes
+
+Fix the sidebar configurator toggle button appearing separated from the AR and fullscreen buttons on narrow embeds. All three controls now sit together in one row instead of the toggle floating above them.
+
+## 4.0.0-alpha.22
+
+### Patch Changes
+
+Fix the 3D model rendering behind the docked sidebar panel instead of next to it. On wide embeds the viewer now narrows to leave room for the panel, instead of the panel floating over part of the model.
+
+## 4.0.0-alpha.21
+
+### Minor Changes
+
+Add `activateAr()` method to `VirtualdisplayClient`. Triggers the AR flow directly, useful when the built-in AR button is hidden with `viewerSettings.ar = false` and a custom control should start AR instead.
+
+Add `client.onSyncChange(callback)`: subscribe to whether the viewer is currently live-syncing its configuration with another device in a hand-off (e.g. a desktop and the phone it was scanned to). The callback receives a boolean and fires again each time the connection state changes.
+
+### Patch Changes
+
+Change the desktop AR button's QR code to open the model in AR on the phone with the shopper's current configuration, instead of a fresh default viewer. The QR dialog now opens immediately and shows the code as soon as it is ready.
+
+## 4.0.0-alpha.20
+
+### Patch Changes
+
+Internal refactoring.
+
+## 4.0.0-alpha.19
+
+### Patch Changes
+
+Fix the AR and fullscreen buttons being hidden behind the configurator open button when the sidebar layout collapses on narrow embeds.
+
+## 4.0.0-alpha.18
+
+### Patch Changes
+
+Internal improvements.
+
+## 4.0.0-alpha.17
+
+### Minor Changes
+
+Add `client.sessionId`: the viewer's tracking session id, available once the viewer has loaded (and `undefined` before). Use it to correlate your own page events, such as a form conversion, with the viewer session the visitor was using.
+
+## 4.0.0-alpha.16
+
+### Patch Changes
+
+Internal: the client now assembles over a shared `@virtualdisplay.io/client-core` engine (transport, base facades, configurator UI). No public API change.
+
+## 4.0.0-alpha.15
+
+### Patch Changes
+
+`snapshot.take()` now fails with `SNAPSHOT_FAILED` if the viewer does not return the capture within 30 seconds, instead of leaving `photo.onError()` waiting forever when the iframe is unresponsive. Also removed unused internal `VirtualdisplayError` factory helpers (`noMapping`, `attributeNotFound`, `snapshotFailed`); the error codes and public constructor are unchanged.
+
+## 4.0.0-alpha.14
+
+### Major Changes
+
+Remove the `cache` option from `ClientOptions`. It was a test-only override and is gone, so remove it from your options if you passed it.
+
+## 4.0.0-alpha.13
+
+### Minor Changes
+
+Add `client.configuration` for configurator commerce: the buyer's selection resolves to a reference and price, read via `client.configuration.current`, `.onChange`, or the bubbling `vd:configuration-change` event. Register a handler with `.onSubmit(cb, { defaultLabel })` to switch on the call-to-action, which renders the price and a customer-labelled button under the controls.
+
+Show the submit CTA for a configurator without prices. When no pricing document is present, a registered `onSubmit` handler (with a label) is enough to offer the button, and submitting hands over the buyer's current selection. A model with only attributes, or none at all, can now be submitted. With prices, the CTA stays gated on an `available` price.
+
+Add `client.focus` to isolate and frame a single component of a model. `client.focus.set('Seat')` flies the camera to that component and dims the rest; `client.focus.clear()` returns to the overview. Read the current component with `client.focus.current`, react to changes with `client.focus.onChange((state) => ...)`, or listen for the bubbling `vd:focus-change` event (`VD_EVENTS.FOCUS_CHANGE`) on the container. Useful for guiding a buyer through a configurable product part by part.
+
+### Patch Changes
+
+Remove the unused `AttributeRegistry.defaults()` method and mark
+`MutationFailedEvent` fields as `readonly`, matching the other public event
+types. Internal cleanup with no API change.
+
+## 4.0.0-alpha.12
+
+### Minor Changes
+
+Add `configuratorLayout` to `ViewerSettings`: choose where the attribute selector sits — `'inframe-bottom-left'` (default) or `'sidebar-right'` (a docked, scrollable right-hand panel) — or `'hidden'` to drop it (`client.select()` and `client.onChange()` keep working). Configure it per model in the portal, or override it via `viewerSettings`. This replaces the `attributeControls` field; swap `attributeControls: false` for `configuratorLayout: 'hidden'`.
+
+### Patch Changes
+
+Internal build-config fix. Align `vite.config.ts` with vite 7 typings: rename `rolldownOptions` to `rollupOptions` and drop the `oxc` minifier (vite 7 only accepts `terser` and `esbuild` and was silently falling back to esbuild). No change to the published bundle.
+
+`VirtualdisplayClient.destroy()` now fails any pending `snapshot.take()` captures with `SNAPSHOT_FAILED` and clears registered `onMutationFailed` callbacks. Previously, callers awaiting `photo.onError()` after a destroy would wait forever and listeners outlived the client they were attached to.
+
+## 4.0.0-alpha.11
+
+### Patch Changes
+
+Hide the fullscreen button on iPhone Safari, where the browser has no Fullscreen API for non-video elements. The button continues to work on desktop, iPad, and Android Chrome.
+
+## 4.0.0-alpha.10
+
+### Patch Changes
+
+Fix AR button on mobile to launch native AR (Quick Look on iOS, Scene Viewer on Android) instead of the QR modal. Fix fullscreen button on iPhone Safari.
+
+## 4.0.0-alpha.9
+
+### Patch Changes
+
+Fix state mix-up when multiple `VirtualdisplayClient` instances are mounted on the same page. Each client now correctly receives only its own server replies, so loading state, mapping, and mutation results no longer cross between viewers.
+
+## 4.0.0-alpha.8
+
+### Minor Changes
+
+Add `viewerSettings` option to `ClientOptions`. Pass a partial `ViewerSettings` to override fields like `ar`, `fullscreen`, `cameraControls`, `attributeControls`, or `annotations` without changing the model's metadata.
+
+Add annotations API: `client.annotations.setEnabled(enabled)` toggles annotation markers, and `startPlacing()` / `stopPlacing()` / `onPlaced(callback)` enable click-to-place flows for custom annotation editors. New `AnnotationPosition` type is exported.
+
+Add `attributeControls` field to `ViewerSettings`. Set to `false` to hide the built-in attribute selector while keeping `client.select()` and `client.onChange()` available.
+
+Fix toolbar buttons appearing briefly before the loading indicator clears.
+
+Fix annotation markers ignoring `annotations: false` when set via the `viewerSettings` override.
+
+Fix loading indicator hanging when model metadata is unavailable.
+
+Internal code quality improvements.
+
+## 4.0.0-alpha.7
+
+### Patch Changes
+
+Restructure standard interface layout to use corner slots. Camera controls and screenshot button now share a single card when both are enabled.
+
+## 4.0.0-alpha.6
+
+### Patch Changes
+
+Fix camera control buttons accumulating clicks correctly.
+
+## 4.0.0-alpha.5
+
+### Patch Changes
+
+Internal code quality improvements.
+
 Ship complete TypeScript type definitions for all exports.
 
+## 4.0.0-alpha.4
+
+### Minor Changes
+
+Add `language` option to `ClientOptions`. Pass a BCP 47 language tag (e.g. `"nl"`, `"de"`) to override the viewer language at initialisation time. Useful when embedding the same model on multiple pages with different languages.
+
+Add built-in standard interface: loading indicator, toolbar (screenshot, AR, fullscreen), camera controls, and attribute controls are now rendered automatically inside the viewer container. UI is driven by `viewerSettings` received from the server and requires no manual setup.
+
+### Patch Changes
+
+Fix build target: use ESNext in tsconfig to resolve rolldown bundling issues with ES2022 class fields.
+
 ## 4.0.0-alpha.2
 
 ### Patch Changes

package/README.md

@@ -3,6 +3,7 @@
 TypeScript library for embedding interactive 3D product models in web
 applications.
 
+- Built-in viewer UI with loading indicator, product controls, and action bar
 - Simple attribute-based API for product configurators
 - Server-driven configuration, no client-side mapping needed
 - Fire-and-forget messaging with automatic state synchronisation
@@ -54,49 +55,45 @@ The server defines which attributes and values are available for each model.
 The client receives this configuration automatically via postMessage. No
 manual mapping required.
 
+### Mounting a specific app
+
+A model can have several apps (a plain viewer, a configurator), each with its
+own link and its own configuration. Pass the app's link key as `app` to mount
+that exact app:
+
+```typescript
+import { VirtualdisplayClient } from '@virtualdisplay.io/client';
+
+const client = new VirtualdisplayClient({
+  parent: '#product-container',
+  app: 'sofa-deluxe-k3f9dm',
+});
+```
+
+`license` + `model` keeps working unchanged and shows the model's default
+viewer. If both forms are supplied, `app` wins and a warning is logged that the
+pair was ignored, so adding `app` to an existing integration is additive. One
+of the two forms is required; supplying neither is a compile error.
+
 ## How it works
 
 The 3D server hosts the viewer in an iframe, keeping WebGL complexity isolated
 from your application. The client library handles all communication via
 postMessage.
 
-```mermaid
-graph LR
-    A[Your application] -->|API calls| B[VirtualdisplayClient]
-    B -->|postMessage| C[3D server iframe]
-    C -->|Events| B
-    B -->|State updates| A
-```
+![Architecture overview](docs/arch.png)
 
-On startup, the server tells the client what is available (attributes, values,
-defaults). After that, the client sends commands and the server responds with
-results.
-
-```mermaid
-sequenceDiagram
-    participant UI as Your UI
-    participant Client as VirtualdisplayClient
-    participant Server as 3D server
-
-    UI ->> Client: new VirtualdisplayClient(options)
-    Client ->> Client: Create iframe
-    Note right of Client: Outgoing messages queued
-    Server ->> Client: READY
-    Note right of Client: Queue flushed
-    opt UI or camera options configured
-        Client ->> Server: CONFIG
-    end
-    Server ->> Client: MAPPING (attributes + values + defaults)
-    Client ->> Client: Store attribute definitions
-    Server ->> Client: MUTATION result (defaults, isInitial: true)
-    Client ->> UI: onReady + onChange callbacks fire
-```
+On startup, the server sends the client its configuration (viewer settings,
+camera limits) and available product attributes. The loading indicator shows
+progress while the model downloads.
+
+![Startup sequence](docs/startup-sequence.png)
 
 1. Client creates iframe; outgoing messages are queued until the server is ready.
-2. Server sends `READY` when its message listener is active; client flushes queue.
-3. `CONFIG` is only sent if UI or camera options were provided in the constructor.
-4. Server sends `MAPPING` with attribute definitions, loads the 3D model, applies defaults.
-5. `onReady` fires after the first initial mutation result arrives.
+2. Server sends `HANDSHAKE` when its message listener is active; client flushes queue.
+3. Server sends progress updates while the model downloads. The client displays these in the loading indicator.
+4. Server sends `CONFIG` with viewer settings and camera limits from model metadata.
+5. Server sends `MAPPING` with attribute definitions, values, and defaults. `onReady` fires.
 
 ## Product configuration
 
@@ -104,23 +101,7 @@ Configure product options by selecting attribute values. The server defines
 which attributes exist (e.g. "Color", "Size") and which values each has
 (e.g. "red", "blue"). You select values; the 3D model updates automatically.
 
-```mermaid
-sequenceDiagram
-    participant UI as Your UI
-    participant Client as VirtualdisplayClient
-    participant Server as 3D server
-
-    UI ->> Client: client.select('Color', 'blue')
-    Client ->> Server: MUTATION
-    Note right of Client: Fire-and-forget
-    Server ->> Server: Apply 3D changes
-    Server ->> Client: MUTATION result
-    alt All succeeded
-        Client ->> UI: onChange callbacks fire
-    else Some failed
-        Client ->> UI: onMutationFailed callbacks fire
-    end
-```
+![Product configuration sequence](docs/mutation.png)
 
 - `select()` returns immediately; the result arrives asynchronously.
 - Each attribute in the result has its own `success` flag and optional `error`.
@@ -134,8 +115,8 @@ client.select('Color', 'blue');
 client.select('Size', 'large');
 ```
 
-Can be called before the server is ready. Mutations are buffered and sent when
-the mapping arrives.
+Can be called immediately after construction. Selections are buffered until the
+server handshake completes.
 
 ### Tracking changes
 
@@ -174,6 +155,14 @@ const colorAttr = client.getAttribute('Color');
 if (colorAttr) {
   colorAttr.select('blue');
   colorAttr.getValues(); // AttributeValue[]
+
+  // Each value carries the word to render. `value` is the key you pass back to
+  // `select`; `label` is what to show, which the model may name
+  // ({ value: 'RAL3020', label: 'Signaalrood' }). Where the model names none,
+  // `label` is the value made readable: `redWine` reads as "Red wine".
+  // A measurement is the exception: its values are millimetres, and what to
+  // show depends on the model's unit and the reader's locale.
+  colorAttr.getValues().map((v) => ({ key: v.value, shown: v.label }));
   colorAttr.getValue('blue'); // AttributeValue | undefined
   colorAttr.onChange((value) => { ... });
 }
@@ -192,22 +181,7 @@ client.onMutationFailed(({ attribute, value }) => {
 Capture the current 3D view as an image. Useful for product shots, social
 sharing, or saving configurations.
 
-```mermaid
-sequenceDiagram
-    participant UI as Your UI
-    participant Client as VirtualdisplayClient
-    participant Server as 3D server
-
-    UI ->> Client: client.snapshot.take('photo.png')
-    Client ->> Server: SNAPSHOT request
-    alt Success
-        Server ->> Client: SNAPSHOT data (base64)
-        Client ->> UI: onDeveloped callback fires
-    else Failure (e.g. no canvas)
-        Server ->> Client: SNAPSHOT error
-        Client ->> UI: onError callback fires
-    end
-```
+![Snapshot sequence](docs/snapshot.png)
 
 - Filename is validated client-side (extension, no path traversal).
 - Server always responds, either with image data or an error reason.
@@ -236,21 +210,11 @@ Filename must end with `.png`. The server always returns PNG data.
 
 ## Camera
 
-Control the 3D viewer's camera position programmatically. Useful for guided
-product tours, preset views, or syncing camera state with your UI.
+The standard interface includes built-in camera controls when they are
+enabled in the Virtualdisplay portal. The camera can also be controlled
+programmatically.
 
-```mermaid
-sequenceDiagram
-    participant UI as Your UI
-    participant Client as VirtualdisplayClient
-    participant Server as 3D server
-
-    UI ->> Client: client.camera.rotate(45).tilt(30).set()
-    Client ->> Server: CAMERA commands
-    Server ->> Client: CAMERA position
-    Client ->> UI: camera.onChange callbacks fire
-    Note right of Server: Position updates also fire on user<br/>interaction with the 3D viewport
-```
+![Camera sequence](docs/camera.png)
 
 - Commands accumulate via chaining; `.set()` sends them all at once.
 - `.reset()` sends immediately without chaining.
@@ -263,7 +227,7 @@ sequenceDiagram
 client.camera.rotate(45).set();
 client.camera.rotate(90).tilt(45).zoom(150).set();
 
-// Reset to base position (sends immediately)
+// Reset to the default position configured in the portal (sends immediately)
 client.camera.reset();
 ```
 
@@ -283,49 +247,83 @@ console.log(client.cameraPosition.tilt);
 console.log(client.cameraPosition.zoom);
 ```
 
-## UI controls
+## Annotations
 
-Toggle built-in viewer elements like AR, fullscreen, and the loading indicator.
-All are visible by default.
+Annotations are interactive markers placed on the 3D model. They are
+configured and saved in the Virtualdisplay portal. The client library
+exposes an API to toggle their visibility.
 
-### Via constructor
+### Toggling annotations
 
 ```typescript
-const client = new VirtualdisplayClient({
-  parent: '#viewer',
-  license: 'your-license',
-  model: 'product',
-  ui: {
-    arEnabled: false,
-    loadingIndicatorEnabled: false,
-  },
-});
+client.annotations.setEnabled(false); // Hide the markers
+client.annotations.setEnabled(true); // Show them again
 ```
 
-### At runtime
+In an app that shows several models, this toggles the first model's markers.
+`viewerSettings.annotations` (see below) and the marker button in the standard
+interface govern every model's.
+
+## Standard interface
+
+The client renders a complete viewer UI automatically: loading indicator,
+attribute controls, camera controls, and an action bar with AR, fullscreen,
+and screenshot buttons. Each element is shown or hidden based on viewer
+settings configured in the Virtualdisplay portal.
+
+### Available settings
+
+| Field                | Type      | Effect when `false`                                                                                                                                                                                                                                 |
+| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ar`                 | `boolean` | Hides the AR button                                                                                                                                                                                                                                 |
+| `fullscreen`         | `boolean` | Hides the fullscreen button                                                                                                                                                                                                                         |
+| `screenshot`         | `boolean` | Hides the screenshot button                                                                                                                                                                                                                         |
+| `cameraControls`     | `boolean` | Hides the camera control buttons                                                                                                                                                                                                                    |
+| `annotations`        | `boolean` | Hides all annotation markers                                                                                                                                                                                                                        |
+| `language`           | `string`  | Sets the viewer UI language (BCP 47, e.g. `'nl'`, `'en'`, `'de'`)                                                                                                                                                                                   |
+| `configuratorLayout` | `string`  | Where the attribute controls sit, or whether they show: `'inframe-bottom-left'` (default), `'sidebar-right'` (a docked, scrollable right-hand panel), or `'hidden'` (no built-in selector, `client.select()` and `client.onChange()` keep working). |
+
+### Overriding settings
+
+The portal is the recommended place to change these settings: one source of
+truth, and the viewer behaves the same wherever it is embedded.
+
+We know there are situations where the portal alone cannot cover the case at
+hand. For those, `ClientOptions.viewerSettings` accepts a partial override of
+the same fields. Use it sparingly: every override is one more place where
+the embedded viewer disagrees with the portal. Omitted fields fall back to
+the metadata value.
+
+Any override that differs from the metadata is logged with `console.warn`.
+The warning is always emitted, so the deviation stays traceable when
+something needs explaining.
 
 ```typescript
-client.viewer.setArEnabled(false);
-client.viewer.setFullscreenEnabled(true);
-client.viewer.setLoadingIndicatorEnabled(false);
-
-// Bulk operations
-client.viewer.hideAllUI();
-client.viewer.showAllUI();
-client.viewer.updateUIConfig({ arEnabled: false, fullscreenEnabled: true });
+const client = new VirtualdisplayClient({
+  parent: '#product-container',
+  license: 'your-license-key',
+  model: 'sneaker',
+  viewerSettings: {
+    cameraControls: false,
+  },
+});
 ```
 
 ## Lifecycle
 
 ### Ready state
 
-Use `onReady` to know when the 3D model has loaded. For example, to hide
-your own loading spinner. It is **not** required before calling `select()` or
-`onChange()`.
+Use `onReady` to know when the model and attribute definitions are available.
+Not required before calling `select()` or `onChange()`, those are buffered
+automatically.
 
 ```typescript
 client.onReady(() => {
-  document.getElementById('loading-spinner').hidden = true;
+  const values = client.getValues('Color');
+  console.log(
+    'Available colours:',
+    values.map((v) => v.value)
+  );
 });
 ```
 
@@ -338,76 +336,49 @@ client.destroy();
 ## Constructor options
 
 ```typescript
+import type { ViewerSettings } from '@virtualdisplay.io/client';
+
 interface ClientOptions {
   parent: string | HTMLElement; // Where to embed the 3D viewer
-  license: string; // License key from your Virtualdisplay account
+  app?: string; // An app's link key: the alternative to license + model (see Mounting a specific app)
+  license: string; // License key from your Virtualdisplay account; with model, the classic address form
   model: string; // Which 3D model to load
   debug?: boolean; // Shows console logs for troubleshooting
-  language?: string; // UI language: 'nl', 'en', or 'de' (default: 'nl')
-
-  // UI elements (all visible by default)
-  ui?: {
-    arEnabled?: boolean;
-    fullscreenEnabled?: boolean;
-    loadingIndicatorEnabled?: boolean;
-  };
-
-  // Camera behaviour
-  camera?: {
-    initialRotate?: number; // Starting view angle (-180 to 180, 0 = front)
-    initialTilt?: number; // Starting elevation (0 = top view, 90 = side view)
-    initialZoom?: number; // Starting distance (100 = default, may need adjustment)
-    minZoom?: number; // Minimum zoom level constraint
-    maxZoom?: number; // Maximum zoom level constraint
-    minTilt?: number; // Minimum tilt angle constraint
-    maxTilt?: number; // Maximum tilt angle constraint
-  };
+  language?: string; // Viewer language: 'nl', 'en', or 'de'
+  viewerSettings?: Partial<ViewerSettings>; // Override fields from model metadata (see Standard interface)
 }
 ```
 
+One of the two address forms is required: `app`, or `license` + `model`. The
+real type is a union that enforces this at compile time; the block above is the
+flattened reference.
+
+```typescript
+type ClientAddress =
+  | { app: string } // an app's link key
+  | { license: string; model: string }; // the classic address form
+```
+
 ## Error codes
 
 The client throws `VirtualdisplayError` for known error conditions:
 
 | Code                  | Meaning                                          |
-|-----------------------|--------------------------------------------------|
+| --------------------- | ------------------------------------------------ |
+| `NO_MAPPING`          | Attribute data not yet available from the server |
 | `ATTRIBUTE_NOT_FOUND` | Requested attribute doesn't exist in the mapping |
 | `VALUE_NOT_FOUND`     | Requested value doesn't exist for attribute      |
 | `PARENT_NOT_FOUND`    | Parent element for iframe not found              |
 | `INVALID_PARAMETER`   | Invalid parameter (e.g. snapshot filename)       |
 | `SNAPSHOT_FAILED`     | Server could not capture the snapshot            |
 
-## Real-world example
-
-```typescript
-const client = new VirtualdisplayClient({
-  parent: '#product-viewer',
-  license: 'your-license',
-  model: 'dining-table',
-});
-
-// Wire up your product option buttons. Selections are buffered until ready.
-document.querySelectorAll('.color-option').forEach((button) => {
-  button.addEventListener('click', () => {
-    client.select('topMaterial', button.dataset.value);
-  });
-});
-
-// Keep buttons in sync with 3D state
-client.onChange('topMaterial', (selectedValue) => {
-  document.querySelectorAll('.color-option').forEach((btn) => {
-    btn.classList.toggle('active', btn.dataset.value === selectedValue.value);
-  });
-});
-```
-
 ## Troubleshooting
 
 **Iframe not loading:**
 
 - Check that the parent element exists in the DOM
 - Verify your license key is valid
-- Ensure the model ID matches your licence
+- Ensure the model ID matches your license
 
 **Attributes not working:**