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

package/CHANGELOG.md

@@ -1,142 +1,104 @@
 # 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.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,13 @@
 # Virtualdisplay client
 
-TypeScript library for embedding interactive 3D product models in web applications.
+TypeScript library for embedding interactive 3D product models in web
+applications.
+
+- 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 +26,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 +39,383 @@ 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.
+
+```mermaid
+graph LR
+    A[Your application] -->|API calls| B[VirtualdisplayClient]
+    B -->|postMessage| C[3D server iframe]
+    C -->|Events| B
+    B -->|State updates| A
+```
+
+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
+```
+
+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.
+
+## 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.
+
+```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
+```
+
+- `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 before the server is ready. Mutations are buffered and sent when
+the mapping arrives.
+
+### 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.
+
+```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
+```
+
+- 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);
 });
 
-// Control via product options
-client.getAttribute('Color')?.select('Red');
+// Handle errors (e.g., canvas not available)
+photo.onError((error) => {
+  console.error('Snapshot failed:', error.message);
+});
 ```
 
-## Key features
+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.
+
+```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
+```
+
+- 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 base position (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);
+```
+
+## UI controls
+
+Toggle built-in viewer elements like AR, fullscreen, and the loading indicator.
+All are visible by default.
+
+### Via constructor
+
+```typescript
+const client = new VirtualdisplayClient({
+  parent: '#viewer',
+  license: 'your-license',
+  model: 'product',
+  ui: {
+    arEnabled: false,
+    loadingIndicatorEnabled: false,
+  },
+});
+```
+
+### At runtime
+
+```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 });
+```
+
+## 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()`.
+
+```typescript
+client.onReady(() => {
+  document.getElementById('loading-spinner').hidden = true;
+});
+```
+
+### Cleanup
+
+```typescript
+client.destroy();
+```
+
+## Constructor options
+
+```typescript
+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; // 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
+  };
+}
+```
+
+## Error codes
+
+The client throws `VirtualdisplayError` for known error conditions:
+
+| Code                  | Meaning                                          |
+|-----------------------|--------------------------------------------------|
+| `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:**
 
-- **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.