@virtualdisplay.io/client 4.0.0-alpha.2 → 4.0.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 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
@@ -60,43 +61,19 @@ 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 +81,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 +95,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
 
@@ -192,22 +153,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 +182,10 @@ 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
+The standard interface includes built-in camera controls when enabled by the
+operator in the portal. The camera can also be controlled programmatically.
 
-    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 +198,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 +218,30 @@ 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,
-  },
-});
-```
+## Standard interface
 
-### At runtime
+The client renders a complete viewer UI automatically: loading indicator,
+attribute controls, camera controls, and an action bar (AR, fullscreen).
 
-```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 });
-```
+Which controls are visible is configured by the model operator in the
+Virtualdisplay portal. The operator decides how the viewer looks and
+behaves, not the developer integrating the code. This way the operator
+can match the viewer to their customers' expectations: enabling AR for
+mobile visitors, choosing which product attributes to expose, or setting
+the default camera angle and language.
 
 ## 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));
 });
 ```
 
@@ -343,25 +259,7 @@ interface ClientOptions {
   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
-  };
+  language?: string; // Match the viewer language to the page: 'nl', 'en', or 'de'
 }
 ```
 
@@ -370,37 +268,14 @@ interface ClientOptions {
 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:**