@virtualdisplay.io/client 3.7.0 → 4.0.0-alpha.10

package/CHANGELOG.md

@@ -1,142 +1,172 @@
 # Changelog
 
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+## 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
+
+Build optimisations.
+
+## 4.0.0-alpha.1
+
+### Major Changes
+
+Metadata-driven configuration replaces direct scene node manipulation. The client now receives available attributes and values from the server via a mapping message, instead of managing 3D nodes directly.
+
+### Breaking changes
+
+- **Attribute-only API**: replaces the previous node-based approach with `select()`, `onChange()`, `getValues()`
+- **Removed `isReady` getter** — use `onReady(callback)` instead
+- **Removed `getQueueStatus`** — no longer part of the public API
+- **Package scope changed** from `@virtualdisplay-io/client` to `@virtualdisplay.io/client`
+
+### New features
+
+- Metadata-driven mapping: server sends available attributes and values automatically
+- Camera control API: `camera.rotate()`, `camera.tilt()`, `camera.zoom()`
+- Snapshot API: `snapshot.take()` with `photo.onDeveloped()` callback
+- Viewer configuration: AR, fullscreen, loading indicator controls
+- `onMutationFailed` callback for error handling
+
+All notable changes to this project will be documented in this file.
 
 ## [3.7.0](https://github.com/virtualdisplay-io/client/compare/v3.6.0...v3.7.0) (2025-08-05)
 
 ### ✨ Features
 
-* dynamic mapping - proxy release ([#9](https://github.com/virtualdisplay-io/client/issues/9)) ([a95f0e7](https://github.com/virtualdisplay-io/client/commit/a95f0e7a7672b844571b11307637083c6b487f3f)), closes [#8](https://github.com/virtualdisplay-io/client/issues/8)
+- dynamic mapping - proxy release ([#9](https://github.com/virtualdisplay-io/client/issues/9)) ([a95f0e7](https://github.com/virtualdisplay-io/client/commit/a95f0e7a7672b844571b11307637083c6b487f3f)), closes [#8](https://github.com/virtualdisplay-io/client/issues/8)
 
 ### 🔧 Maintenance
 
-* various fixes and documentation updates ([#7](https://github.com/virtualdisplay-io/client/issues/7)) ([325150b](https://github.com/virtualdisplay-io/client/commit/325150b41bd557e7426e6dae6780cd4fd7660deb))
+- various fixes and documentation updates ([#7](https://github.com/virtualdisplay-io/client/issues/7)) ([325150b](https://github.com/virtualdisplay-io/client/commit/325150b41bd557e7426e6dae6780cd4fd7660deb))
 
 ## [3.6.0](https://github.com/virtualdisplay-io/client/compare/v3.5.1...v3.6.0) (2025-07-23)
 
 ### ✨ Features
 
-* add camera configuration support ([#6](https://github.com/virtualdisplay-io/client/issues/6)) ([a6bce4b](https://github.com/virtualdisplay-io/client/commit/a6bce4bfd0d55362e76c893ddf5ed28409dc8bec))
+- add camera configuration support ([#6](https://github.com/virtualdisplay-io/client/issues/6)) ([a6bce4b](https://github.com/virtualdisplay-io/client/commit/a6bce4bfd0d55362e76c893ddf5ed28409dc8bec))
 
 ## [3.5.1](https://github.com/virtualdisplay-io/client/compare/v3.5.0...v3.5.1) (2025-07-18)
 
 ### ♻️ Code Refactoring
 
-* remove validation of outgoing message types ([#5](https://github.com/virtualdisplay-io/client/issues/5)) ([5f4f985](https://github.com/virtualdisplay-io/client/commit/5f4f9853d65af676aec3a865864f43461fdb6ca5))
+- remove validation of outgoing message types ([#5](https://github.com/virtualdisplay-io/client/issues/5)) ([5f4f985](https://github.com/virtualdisplay-io/client/commit/5f4f9853d65af676aec3a865864f43461fdb6ca5))
 
 ## [3.5.0](https://github.com/virtualdisplay-io/client/compare/v3.4.1...v3.5.0) (2025-07-16)
 
 ### ✨ Features
 
-* camera control API ([#4](https://github.com/virtualdisplay-io/client/issues/4)) ([1e4c147](https://github.com/virtualdisplay-io/client/commit/1e4c14747cad2a4617c4cc763522b50941adaa7f))
+- camera control API ([#4](https://github.com/virtualdisplay-io/client/issues/4)) ([1e4c147](https://github.com/virtualdisplay-io/client/commit/1e4c14747cad2a4617c4cc763522b50941adaa7f))
 
 ## [3.4.1](https://github.com/virtualdisplay-io/client/compare/v3.4.0...v3.4.1) (2025-07-10)
 
 ### 🐛 Bug Fixes
 
-* EventBus once handlers and logging improvements ([#3](https://github.com/virtualdisplay-io/client/issues/3)) ([5a99d8d](https://github.com/virtualdisplay-io/client/commit/5a99d8d6ef82d058799734b54c98ca171d17dd36))
+- EventBus once handlers and logging improvements ([#3](https://github.com/virtualdisplay-io/client/issues/3)) ([5a99d8d](https://github.com/virtualdisplay-io/client/commit/5a99d8d6ef82d058799734b54c98ca171d17dd36))
 
 ## [3.4.0](https://github.com/virtualdisplay-io/client/compare/v3.3.0...v3.4.0) (2025-07-09)
 
 ### ✨ Features
 
-* implement UI configuration via PostMessage CONFIG messages ([#2](https://github.com/virtualdisplay-io/client/issues/2)) ([abc2294](https://github.com/virtualdisplay-io/client/commit/abc229414f9f70c54f37db903c46c0612c5eb6cf))
+- implement UI configuration via PostMessage CONFIG messages ([#2](https://github.com/virtualdisplay-io/client/issues/2)) ([abc2294](https://github.com/virtualdisplay-io/client/commit/abc229414f9f70c54f37db903c46c0612c5eb6cf))
 
 ## [3.3.0](https://github.com/virtualdisplay-io/client/compare/v3.2.2...v3.3.0) (2025-07-07)
 
 ### ✨ Features
 
-* add isInitial flag to StateMessage ([#50](https://github.com/virtualdisplay-io/client/issues/50)) ([8590354](https://github.com/virtualdisplay-io/client/commit/859035423e161f43791433baac203b2adb95c9fd))
+- add isInitial flag to StateMessage ([#50](https://github.com/virtualdisplay-io/client/issues/50)) ([8590354](https://github.com/virtualdisplay-io/client/commit/859035423e161f43791433baac203b2adb95c9fd))
 
 ## [3.2.2](https://github.com/virtualdisplay-io/client/compare/v3.2.1...v3.2.2) (2025-07-01)
 
 ### 🐛 Bug Fixes
 
-* change default logger level to warn ([#49](https://github.com/virtualdisplay-io/client/issues/49)) ([a567db2](https://github.com/virtualdisplay-io/client/commit/a567db23a50173e3b167238af2197e545bda6320))
+- change default logger level to warn ([#49](https://github.com/virtualdisplay-io/client/issues/49)) ([a567db2](https://github.com/virtualdisplay-io/client/commit/a567db23a50173e3b167238af2197e545bda6320))
 
 ## [3.2.1](https://github.com/virtualdisplay-io/client/compare/v3.2.0...v3.2.1) (2025-06-30)
 
 ### 🐛 Bug Fixes
 
-* prevent .env from being used in production builds ([#48](https://github.com/virtualdisplay-io/client/issues/48)) ([7ab54d0](https://github.com/virtualdisplay-io/client/commit/7ab54d02a9aad94daf5a53899fefa9299f9bf73f))
+- prevent .env from being used in production builds ([#48](https://github.com/virtualdisplay-io/client/issues/48)) ([7ab54d0](https://github.com/virtualdisplay-io/client/commit/7ab54d02a9aad94daf5a53899fefa9299f9bf73f))
 
 ## [3.2.0](https://github.com/virtualdisplay-io/client/compare/v3.1.0...v3.2.0) (2025-06-27)
 
 ### ✨ Features
 
-* publish client package to npm registry ([#45](https://github.com/virtualdisplay-io/client/issues/45)) ([825810b](https://github.com/virtualdisplay-io/client/commit/825810b0ca56da8e50f34f2afac9f75a87acbc40))
+- publish client package to npm registry ([#45](https://github.com/virtualdisplay-io/client/issues/45)) ([825810b](https://github.com/virtualdisplay-io/client/commit/825810b0ca56da8e50f34f2afac9f75a87acbc40))
 
 ### 🐛 Bug Fixes
 
-* improve GitHub Actions authentication and remove .env.act ([#47](https://github.com/virtualdisplay-io/client/issues/47)) ([3acc86e](https://github.com/virtualdisplay-io/client/commit/3acc86e5c27a26af0b77cc23ddff397eee141de5))
-* use GITHUB_TOKEN for checkout action ([#46](https://github.com/virtualdisplay-io/client/issues/46)) ([f8d60fb](https://github.com/virtualdisplay-io/client/commit/f8d60fba2547950137de10838bcfc874e78d9f33))
+- improve GitHub Actions authentication and remove .env.act ([#47](https://github.com/virtualdisplay-io/client/issues/47)) ([3acc86e](https://github.com/virtualdisplay-io/client/commit/3acc86e5c27a26af0b77cc23ddff397eee141de5))
+- use GITHUB_TOKEN for checkout action ([#46](https://github.com/virtualdisplay-io/client/issues/46)) ([f8d60fb](https://github.com/virtualdisplay-io/client/commit/f8d60fba2547950137de10838bcfc874e78d9f33))
 
 ### 📝 Documentation
 
-* update README version reference to v3.1 ([#44](https://github.com/virtualdisplay-io/client/issues/44)) ([1652c15](https://github.com/virtualdisplay-io/client/commit/1652c157890ca43d1e366b302a37f02465d6450b))
+- update README version reference to v3.1 ([#44](https://github.com/virtualdisplay-io/client/issues/44)) ([1652c15](https://github.com/virtualdisplay-io/client/commit/1652c157890ca43d1e366b302a37f02465d6450b))
 
 ## [3.1.0](https://github.com/virtualdisplay-io/client/compare/v3.0.0...v3.1.0) (2025-06-25)
 
-### ⚠ BREAKING CHANGES
-
-* Complete API redesign with the following changes:
-- Removed isReady getter - use onReady callback instead
-- Removed getQueueStatus method - internal implementation detail
-- Removed toJSON from ModelNode - not needed for public API
-- Complete restructure from core/ to src/ with domain-driven design
-- New attribute-based API is now the only way to interact with 3D models
-- Fire-and-forget messaging pattern for all operations
-- JSON Schema validation for mapping configuration
-
-Features:
-- Simplified color configurator demo (300 lines → 160 lines)
-- Bundled @virtualdisplay-io/logger package
-- Domain-driven directory structure
-- Proper error handling with error codes
-- Event-driven architecture with EventBus
-- onChange callbacks for real-time UI synchronization
-- Comprehensive test coverage
-
-Documentation:
-- Complete README rewrite focusing on actual functionality
-- Added terminology standards for consistent communication
-- Removed unimplemented accessibility claims
-- Clear separation between simple and configurable products
-
-* fix: update lockfile after removing translator dependency
-
-* docs: update README for v4.0 release
-
-* fix: add GitHub registry configuration for @virtualdisplay-io scope
-
-* fix: add npm authentication to bundle-size workflow and package permissions
-
-* fix: use GITHUB_TOKEN for npm auth and add trailing slash to registry URL
-
-* chore: update lockfile with fresh install
-
-* fix: use GH_PAT instead of GITHUB_TOKEN for package authentication
-
-- Replace GITHUB_TOKEN with GH_PAT in all workflows to avoid conflicts with GitHub's reserved token
-- Update CI, release, and bundle-size workflows to use new token variable
-- Add .env.act for local testing with act
-- Required because GitHub's automatic GITHUB_TOKEN cannot access private organization packages
-
-* fix: remove push trigger from bundle-size workflow
-
-- Bundle size analysis should only run on pull requests
-- Prevents duplicate runs and confusion about which branch is being tested
-- Aligns with CI/CD best practices for PR-based workflows
-
-### ✨ Features
-
-* v4.0.0 - simplified architecture and attribute-only API ([#41](https://github.com/virtualdisplay-io/client/issues/41)) ([dc649c1](https://github.com/virtualdisplay-io/client/commit/dc649c1b863b2427bf6e0350960c4d2e2a2dacb8))
-
 ### 🐛 Bug Fixes
 
-* add missing conventional-changelog-conventionalcommits dependency ([8a15743](https://github.com/virtualdisplay-io/client/commit/8a15743de3984c742ccb5de0537333f321108cd4))
-* use NODE_AUTH_TOKEN for npm authentication ([#43](https://github.com/virtualdisplay-io/client/issues/43)) ([c148c6c](https://github.com/virtualdisplay-io/client/commit/c148c6cba6b6b4d1fc431ca5618ad2c3c26638c2))
-
-### 🔧 Maintenance
-
-* trigger release workflow to test GH_PAT secret ([9b07140](https://github.com/virtualdisplay-io/client/commit/9b07140e01d72ccc3774f20733afd197f52c4cde))
+- add missing conventional-changelog-conventionalcommits dependency ([8a15743](https://github.com/virtualdisplay-io/client/commit/8a15743de3984c742ccb5de0537333f321108cd4))
+- use NODE_AUTH_TOKEN for npm authentication ([#43](https://github.com/virtualdisplay-io/client/issues/43)) ([c148c6c](https://github.com/virtualdisplay-io/client/commit/c148c6cba6b6b4d1fc431ca5618ad2c3c26638c2))

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Virtualdisplay
+Copyright (c) 2025-2026 Virtualdisplay
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,14 @@
 # Virtualdisplay client
 
-TypeScript library for embedding interactive 3D product models in web applications.
+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
+- Zero external dependencies (all bundled)
+- Works with any frontend framework or vanilla JavaScript
 
 ## Installation
 
@@ -19,7 +27,7 @@ yarn add @virtualdisplay.io/client
 ```typescript
 import { VirtualdisplayClient } from '@virtualdisplay.io/client';
 
-// That's it! Your 3D model is now displayed
+// Your 3D model is now displayed
 const client = new VirtualdisplayClient({
   parent: '#product-container',
   license: 'your-license-key',
@@ -32,47 +40,330 @@ const client = new VirtualdisplayClient({
 ```typescript
 import { VirtualdisplayClient } from '@virtualdisplay.io/client';
 
-// Create client instance
 const client = new VirtualdisplayClient({
   parent: '#product-container',
   license: 'your-license-key',
   model: 'sneaker',
 });
 
-// Map product options to 3D parts
-client.setMapping({
-  attributes: [
-    {
-      name: 'Color',
-      values: [
-        { value: 'Red', nodeIds: ['laces_red', 'sole_red'], isSelected: true },
-        { value: 'Blue', nodeIds: ['laces_blue', 'sole_blue'] },
-      ],
-    },
-  ],
+// Select a product option. The 3D model updates automatically.
+// Calls are buffered until the server provides the attribute mapping
+client.select('Color', 'red');
+```
+
+The server defines which attributes and values are available for each model.
+The client receives this configuration automatically via postMessage. No
+manual mapping required.
+
+## 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.
+
+![Architecture overview](docs/arch.png)
+
+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 `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
+
+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.
+
+![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`.
+- Attributes within the same component fail as a group.
+
+### Selecting values
+
+```typescript
+// Select a product option. The 3D model updates automatically.
+client.select('Color', 'blue');
+client.select('Size', 'large');
+```
+
+Can be called immediately after construction. Selections are buffered until the
+server handshake completes.
+
+### Tracking changes
+
+Keep your UI in sync with the 3D server state:
+
+```typescript
+client.onChange('Color', (selectedValue) => {
+  // selectedValue.value is the selected value (e.g. 'blue')
+  // selectedValue.isSelected is true
+  updateColorButton(selectedValue.value);
+});
+```
+
+### Querying available values
+
+```typescript
+// All values for an attribute
+const colors = client.getValues('Color');
+colors.forEach((av) => {
+  console.log(av.value, av.isSelected);
+});
+
+// A specific value
+const blue = client.getValue('Color', 'blue');
+if (blue?.isSelected) {
+  highlightButton('blue');
+}
+```
+
+### Direct attribute access
+
+For advanced use cases, get the `Attribute` instance directly:
+
+```typescript
+const colorAttr = client.getAttribute('Color');
+if (colorAttr) {
+  colorAttr.select('blue');
+  colorAttr.getValues(); // AttributeValue[]
+  colorAttr.getValue('blue'); // AttributeValue | undefined
+  colorAttr.onChange((value) => { ... });
+}
+```
+
+### Handling failed mutations
+
+```typescript
+client.onMutationFailed(({ attribute, value }) => {
+  console.error(`Mutation failed: ${attribute} = ${value}`);
+});
+```
+
+## Snapshots
+
+Capture the current 3D view as an image. Useful for product shots, social
+sharing, or saving configurations.
+
+![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.
+
+### Taking a snapshot
+
+```typescript
+const photo = client.snapshot.take('product-hero-shot.png');
+
+// Register callback for when image is ready
+photo.onDeveloped((photoData) => {
+  // photoData.filename - The filename you provided
+  // photoData.data - Base64 encoded image data
+  const img = document.createElement('img');
+  img.src = photoData.data;
+  document.body.appendChild(img);
+});
+
+// Handle errors (e.g., canvas not available)
+photo.onError((error) => {
+  console.error('Snapshot failed:', error.message);
+});
+```
+
+Filename must end with `.png`. The server always returns PNG data.
+
+## Camera
+
+The standard interface includes built-in camera controls when they are
+enabled in the Virtualdisplay portal. The camera can also be controlled
+programmatically.
+
+![Camera sequence](docs/camera.png)
+
+- Commands accumulate via chaining; `.set()` sends them all at once.
+- `.reset()` sends immediately without chaining.
+- Position updates are continuous. They fire on both programmatic and user-driven camera movement.
+
+### Controlling the camera
+
+```typescript
+// Chain commands, then send with .set()
+client.camera.rotate(45).set();
+client.camera.rotate(90).tilt(45).zoom(150).set();
+
+// Reset to the default position configured in the portal (sends immediately)
+client.camera.reset();
+```
+
+### Tracking camera position
+
+The current camera position is updated in real-time as the user orbits, zooms,
+or tilts the model.
+
+```typescript
+client.cameraPosition.onChange((position) => {
+  console.log(position.rotation, position.tilt, position.zoom);
+});
+
+// Read current values directly
+console.log(client.cameraPosition.rotation);
+console.log(client.cameraPosition.tilt);
+console.log(client.cameraPosition.zoom);
+```
+
+## Annotations
+
+Annotations are interactive markers placed on the 3D model. They are
+configured and saved in the Virtualdisplay portal. The client library
+exposes APIs to toggle their visibility and to build custom annotation
+editors.
+
+### Toggling annotations
+
+```typescript
+client.annotations.setEnabled(false); // Hide all markers
+client.annotations.setEnabled(true);  // Show them again
+```
+
+Visibility can also be controlled via `viewerSettings.annotations` (see below).
+
+### Placing annotations
+
+For building a custom annotation editor, the client supports click-to-place
+mode. Enter the mode, listen for the placed position, then exit.
+
+```typescript
+client.annotations.onPlaced((position) => {
+  // position has x, y, z coordinates on the model surface
+  console.log(position);
+});
+
+// Enter placement mode. The next click on the model fires onPlaced.
+client.annotations.startPlacing();
+
+// Cancel placement mode without recording a click.
+client.annotations.stopPlacing();
+```
+
+The position type is `AnnotationPosition`, exported from the package.
+
+## 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                                                               |
+| `attributeControls` | `boolean` | Hides the built-in attribute selector. `client.select()` and `client.onChange()` keep working. |
+| `annotations`       | `boolean` | Hides all annotation markers                                                                   |
+| `language`          | `string`  | Sets the viewer UI language (BCP 47, e.g. `'nl'`, `'en'`, `'de'`)                              |
+
+### 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
+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 model and attribute definitions are available.
+Not required before calling `select()` or `onChange()`, those are buffered
+automatically.
+
+```typescript
+client.onReady(() => {
+  const values = client.getValues('Color');
+  console.log('Available colours:', values.map(v => v.value));
 });
+```
+
+### Cleanup
+
+```typescript
+client.destroy();
+```
 
-// Control via product options
-client.getAttribute('Color')?.select('Red');
+## 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
+  model: string;                            // Which 3D model to load
+  debug?: boolean;                          // Shows console logs for troubleshooting
+  language?: string;                        // Viewer language: 'nl', 'en', or 'de'
+  viewerSettings?: Partial<ViewerSettings>; // Override fields from model metadata (see Standard interface)
+}
 ```
 
-## Key features
+## 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            |
+
+## Troubleshooting
+
+**Iframe not loading:**
 
-- **Simple API**: Attribute-based product configuration
-- **Fire-and-forget**: Send commands without waiting for responses
-- **State sync**: Automatic synchronization between client and 3D viewer
-- **Framework-agnostic**: Works with React, Vue, Angular, or vanilla JS
-- **TypeScript first**: Full type safety and IntelliSense support
-- **Minimal dependencies**: Only essential validation and logging included
+- Check that the parent element exists in the DOM
+- Verify your license key is valid
+- Ensure the model ID matches your licence
 
-## Documentation
+**Attributes not working:**
 
-For complete documentation including:
+- Verify attribute names match exactly (case-sensitive)
+- Check that the value exists for the attribute
+- Use `onMutationFailed` to catch server-side errors
 
-- API reference
-- Advanced examples
-- Integration guides
-- Architecture diagrams
-- Troubleshooting
+## Changelog
 
-Visit our [GitHub repository](https://github.com/virtualdisplay-io/client)
+See the [npm version history](https://www.npmjs.com/package/@virtualdisplay.io/client?activeTab=versions)
+for release notes.