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

package/README.md

@@ -3,10 +3,9 @@
 TypeScript library for embedding interactive 3D product models in web
 applications.
 
-**Key features:**
-
 - Simple attribute-based API for product configurators
-- Fire-and-forget messaging with automatic state synchronization
+- 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
 
@@ -20,14 +19,6 @@ pnpm add @virtualdisplay.io/client
 yarn add @virtualdisplay.io/client
 ```
 
-## What's new in v3.1
-
-- Simplified message handling with unified event system
-- JSON Schema validation using AJV
-- Cleaner, more maintainable codebase
-- Improved TypeScript types
-- Better error messages with specific error codes
-
 ## Quick start
 
 ### Simple product (no options)
@@ -35,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',
@@ -48,436 +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'] },
-      ],
-    },
-  ],
-});
-
-// Control via product options
-client.getAttribute('Color')?.select('Red');
-
-// Or store the attribute for multiple operations
-const sizeAttribute = client.getAttribute('Size');
-if (sizeAttribute) {
-  sizeAttribute.select('Large');
-}
+// 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 and manages state locally using an attribute mapping system.
-
-**Key principles:**
-
-- **Iframe architecture**: 3D server loads the viewer independently
-- **Fire-and-forget**: Send messages without waiting for confirmation
-- **Attribute mapping**: Connect your product options to 3D model parts
-- **State synchronization**: Client and 3D server stay in sync automatically
-- **Domain-driven design**: Clean separation of concerns with simplified
-  architecture
-- **Event-driven**: Loosely coupled components communicate via events
-
-## Product options
-
-### When do you need mapping
-
-Before diving in, it's important to understand when you need attribute mapping:
-
-**No mapping needed:**
+postMessage.
+
+```mermaid
+graph LR
+    A[Your application] -->|API calls| B[VirtualdisplayClient]
+    B -->|postMessage| C[3D server iframe]
+    C -->|Events| B
+    B -->|State updates| A
+```
 
-- Static 3D models that always look the same
-- Product showcases without options
-- Architectural visualizations
-- Art pieces or sculptures
-- Single-configuration products
+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
+```
 
-**Mapping required:**
+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
+```
 
-- Products where users can change colors (different textures/materials per option)
-- Products with size options (different 3D meshes per size)
-- Modular products (parts that can be added/removed)
-- Any product where different options show different 3D elements
+- `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.
 
-### Attribute mapping
+### Selecting values
 
-The mapping system bridges your business logic with the 3D visualization. It
-serves multiple purposes:
+```typescript
+// Select a product option. The 3D model updates automatically.
+client.select('Color', 'blue');
+client.select('Size', 'large');
+```
 
-**Why mapping is essential:**
+Can be called before the server is ready. Mutations are buffered and sent when
+the mapping arrives.
 
-- The 3D server is generic - it doesn't know your specific product options
-- Your business rules (stock, pricing, combinations) change independently from
-  the 3D model
-- You control exactly which parts of the model are shown for each option
-- You can group multiple 3D nodes (meshes, materials) into logical product
-  choices
+### Tracking changes
 
-**How it works:** The mapping connects your product options to specific parts of
-the 3D model:
+Keep your UI in sync with the 3D server state:
 
 ```typescript
-client.setMapping({
-  attributes: [
-    {
-      name: 'Color',
-      values: [
-        {
-          value: 'Red',
-          nodeIds: ['mat_red_sole', 'mat_red_laces', 'mat_red_logo'],
-          isSelected: true,
-        },
-        {
-          value: 'Blue',
-          nodeIds: ['mat_blue_sole', 'mat_blue_laces', 'mat_blue_logo'],
-        },
-      ],
-    },
-    {
-      name: 'Material',
-      values: [
-        { value: 'Leather', nodeIds: ['material_leather_upper'] },
-        {
-          value: 'Canvas',
-          nodeIds: ['material_canvas_upper'],
-          isSelected: true,
-        },
-      ],
-    },
-  ],
+client.onChange('Color', (selectedValue) => {
+  // selectedValue.value is the selected value (e.g. 'blue')
+  // selectedValue.isSelected is true
+  updateColorButton(selectedValue.value);
 });
 ```
 
-**Structure explained:**
-
-- `attribute` - A product feature like Color, Size, or Material
-- `value` - A specific option like Red, Blue, Small, or Large
-- `nodeIds` - The 3D model parts that represent this option
-- `isSelected` - Whether this option is selected by default
-
-**Example benefits:**
+### Querying available values
 
 ```typescript
-// Group related 3D parts into one logical choice
-{
-  value: 'Red',
-  nodeIds: [
-    'mesh_sole_red',      // Red sole mesh
-    'material_laces_red', // Red laces material
-    'texture_logo_red',   // Red logo texture
-    'mesh_stitching_red'  // Red stitching details
-  ]
-}
+// All values for an attribute
+const colors = client.getValues('Color');
+colors.forEach((av) => {
+  console.log(av.value, av.isSelected);
+});
 
-// The server automatically handles showing Red parts
-// and hiding Blue/Green parts when Red is selected
+// A specific value
+const blue = client.getValue('Color', 'blue');
+if (blue?.isSelected) {
+  highlightButton('blue');
+}
 ```
 
-**Key advantages:**
-
-- Full control over what's visible without modifying the 3D model
-- Business logic stays in your application, not in the 3D server
-- Easy to update when products or availability changes
-- Group complex 3D structures into simple user choices
+### Direct attribute access
 
-**Need help with mapping?**
+For advanced use cases, get the `Attribute` instance directly:
 
-- We help you connect your product catalog to your 3D models
-- Visual mapping tool coming soon to simplify this process
-- Contact <support@virtualdisplay.io> for mapping assistance
-
-### Complete flow
-
-Here's how the client, mapping system, and 3D server work together:
+```typescript
+const colorAttr = client.getAttribute('Color');
+if (colorAttr) {
+  colorAttr.select('blue');
+  colorAttr.getValues(); // AttributeValue[]
+  colorAttr.getValue('blue'); // AttributeValue | undefined
+  colorAttr.onChange((value) => { ... });
+}
+```
 
-**Phase by phase breakdown:**
+### Handling failed mutations
 
-#### Phase 0: Initialization (always happens)
+```typescript
+client.onMutationFailed(({ attribute, value }) => {
+  console.error(`Mutation failed: ${attribute} = ${value}`);
+});
+```
 
-- Client creates iframe and loads 3D server
-- Server initializes the 3D model with all nodes visible
-- Server sends complete node state to client
-- Client now knows about all available nodes in the model
+## 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
+```
 
-**Note:** For simple models without options, this is all you need!
+- Filename is validated client-side (extension, no path traversal).
+- Server always responds, either with image data or an error reason.
 
-#### Phase 1: Configuration (only for configurable products)
+### Taking a snapshot
 
-- You call `setMapping()` with your product structure
-- Client stores the attribute mapping locally
-- Client sends mutations for all `isSelected: true` values
-- Server applies these changes and hides non-selected options
-- Server sends back confirmed state
-- Local state updates based on server response
-- onChange callbacks fire for initial UI synchronization
+```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);
+});
 
-#### Phase 2: User interaction (only for configurable products)
+// Handle errors (e.g., canvas not available)
+photo.onError((error) => {
+  console.error('Snapshot failed:', error.message);
+});
+```
 
-- User selects a different option in your UI
-- You call `getAttribute('Color').select('Blue')`
-- Client sends mutation request to server
-- Your code continues immediately (doesn't wait for server response)
-- Server updates the 3D model
-- Server sends back the confirmed state
-- Local state updates based on server response
-- onChange callbacks fire with the actual state
-- UI stays perfectly synchronized with 3D model
+Filename must end with `.png`. The server always returns PNG data.
 
-**Important:** The pattern is identical for both initial mapping and user
-interactions. In both cases:
+## Camera
 
-1. Client sends mutations to server
-2. Server applies changes to 3D model
-3. Server sends back confirmed state
-4. Client updates local state based on server response
-5. onChange callbacks fire with the actual state
+Control the 3D viewer's camera position programmatically. Useful for guided
+product tours, preset views, or syncing camera state with your UI.
 
-This ensures the server remains the single source of truth for all state
-changes.
+```mermaid
+sequenceDiagram
+    participant UI as Your UI
+    participant Client as VirtualdisplayClient
+    participant Server as 3D server
 
-## Advanced usage
+    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
+```
 
-### Live state synchronization
+- 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.
 
-Keep your UI in sync with the 3D server state using onChange callbacks:
+### Controlling the camera
 
 ```typescript
-const colorAttribute = client.getAttribute('Color');
+// Chain commands, then send with .set()
+client.camera.rotate(45).set();
+client.camera.rotate(90).tilt(45).zoom(150).set();
 
-colorAttribute?.getValues().forEach((value) => {
-  value.onChange = () => {
-    // Update UI when state changes
-    updateButton(value.value, value.isSelected);
-  };
-});
+// Reset to base position (sends immediately)
+client.camera.reset();
 ```
 
-### Mapping validation
+### Tracking camera position
 
-Validate your mapping configuration during development:
+The current camera position is updated in real-time as the user orbits, zooms,
+or tilts the model.
 
 ```typescript
-import { mappingSchema } from '@virtualdisplay.io/client';
-import Ajv from 'ajv';
+client.cameraPosition.onChange((position) => {
+  console.log(position.rotation, position.tilt, position.zoom);
+});
 
-const validate = new Ajv().compile(mappingSchema);
-if (!validate(myMapping)) {
-  console.error('Invalid mapping:', validate.errors);
-}
+// Read current values directly
+console.log(client.cameraPosition.rotation);
+console.log(client.cameraPosition.tilt);
+console.log(client.cameraPosition.zoom);
 ```
 
-## Real-world integration examples
+## UI controls
 
-### CMS integration
+Toggle built-in viewer elements like AR, fullscreen, and the loading indicator.
+All are visible by default.
 
-The Virtualdisplay client is CMS-agnostic. Store the mapping configuration in
-your CMS alongside your product data:
+### Via constructor
 
 ```typescript
-// Fetch product with 3D mapping from your CMS
-const product = await fetch('/api/products/sneaker-pro').then((r) => r.json());
-
-// Use the stored mapping directly
-client.setMapping(product.server3dMapping);
+const client = new VirtualdisplayClient({
+  parent: '#viewer',
+  license: 'your-license',
+  model: 'product',
+  ui: {
+    arEnabled: false,
+    loadingIndicatorEnabled: false,
+  },
+});
 ```
 
-**Best practices:**
-
-- Store the complete mapping configuration with each product
-- Update mappings when product options or availability changes
-- Let your CMS handle filtering of unavailable combinations
-- Version your mappings when 3D models are updated
-
-## Example
-
-See the [color configurator example](./examples/color-configurator/) for a
-complete working implementation that demonstrates:
-
-- Setting up the client
-- Defining attribute mappings
-- Binding UI controls to attributes
-- Real-time state synchronization
-
-## API reference
-
-### ClientOptions
+### At runtime
 
 ```typescript
-interface ClientOptions {
-  parent: string | HTMLElement; // Container element or selector
-  license: string; // Your license key
-  model: string; // Model ID to load
-  debug?: boolean; // Enable debug logging (default: false)
-  language?: string; // Language for UI inside the iframe (default: 'nl', supported: 'nl', 'en', 'de')
-}
+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 });
 ```
 
-### Methods
+## Lifecycle
 
-#### `setMapping(configuration: MappingConfiguration): void`
+### Ready state
 
-Configure attribute-to-node mapping for product variants. This is the primary
-method for setting up your product configurator. Call this once with your
-complete configuration - the client efficiently handles all updates.
+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.setMapping({
-  attributes: [
-    {
-      name: 'Color',
-      values: [
-        { value: 'Red', nodeIds: ['node1', 'node2'], isSelected: true },
-        { value: 'Blue', nodeIds: ['node3', 'node4'] },
-      ],
-    },
-  ],
+client.onReady(() => {
+  document.getElementById('loading-spinner').hidden = true;
 });
 ```
 
-#### `getAttribute(name: string): AttributeSelector | undefined`
-
-Get an attribute selector for changing values. Returns undefined if the
-attribute doesn't exist.
+### Cleanup
 
 ```typescript
-const colorAttr = client.getAttribute('Color');
-if (colorAttr) {
-  colorAttr.select('Blue');
-}
+client.destroy();
 ```
 
-#### `destroy(): void`
-
-Clean up and remove the client connection. Always call this when unmounting your
-component.
+## Constructor options
 
 ```typescript
-// React example
-useEffect(() => {
-  const client = new VirtualdisplayClient({ ... });
-  return () => client.destroy();
-}, []);
-```
-
-### Types
-
-```typescript
-interface MappingConfiguration {
-  attributes: AttributeConfig[];
-}
-
-interface AttributeConfig {
-  name: string; // Attribute name (e.g., 'Color')
-  values: AttributeValueConfig[]; // Possible values
-}
-
-interface AttributeValueConfig {
-  value: string; // Value name (e.g., 'Red')
-  nodeIds: string[]; // 3D node IDs for this value
-  isSelected?: boolean; // Default selection state
-}
-
-class AttributeSelector {
-  // Properties
-  name: string; // Attribute name (getter)
-  currentValue: string | undefined; // Current selected value (getter)
-  availableValues: string[]; // All possible values (getter)
-
-  // Methods
-  select(value: string): AttributeSelector; // Select a value (chainable)
-  onChange(callback: () => void): AttributeSelector; // Register change callback (chainable)
-  getValues(): AttributeValue[]; // Get all AttributeValue objects
-  getValue(value: string): AttributeValue | undefined; // Get specific AttributeValue
-}
+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;
+  };
 
-class AttributeValue {
-  // Properties
-  value: string; // The value name (e.g., 'Red') - getter
-  nodeList: string[]; // Associated 3D node IDs - getter
-  isSelected: boolean; // Current selection state - getter
-  onChange?: () => void; // Callback when selection changes - property
+  // 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
+  };
 }
 ```
 
-#### NodeSelector
-
-The client exports `NodeSelector` for direct node manipulation. This is intended
-for specialized tools like mapping editors and inspectors, not for typical
-product configurators. For product configurators, use the attribute-based API.
-
-### Error handling
+## Error codes
 
 The client throws `VirtualdisplayError` for known error conditions:
 
-```typescript
-import {
-  VirtualdisplayClient,
-  VirtualdisplayError,
-  ERROR_CODES,
-} from '@virtualdisplay.io/client';
-
-try {
-  client.getAttribute('NonExistent').select('Value');
-} catch (error) {
-  if (error instanceof VirtualdisplayError) {
-    switch (error.code) {
-      case ERROR_CODES.ATTRIBUTE_NOT_FOUND:
-        console.error('Attribute does not exist');
-        break;
-      case ERROR_CODES.NO_MAPPING:
-        console.error('Call setMapping() first');
-        break;
-      // Handle other error codes
-    }
-  }
-}
-```
+| 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            |
 
-**Error codes:**
+## Real-world example
 
-- `NO_MAPPING` - No mapping configuration set
-- `ATTRIBUTE_NOT_FOUND` - Requested attribute doesn't exist
-- `VALUE_NOT_FOUND` - Requested value doesn't exist for attribute
-- `INVALID_MAPPING` - Mapping configuration is invalid
-- `PARENT_NOT_FOUND` - Parent element for iframe not found
+```typescript
+const client = new VirtualdisplayClient({
+  parent: '#product-viewer',
+  license: 'your-license',
+  model: 'dining-table',
+});
 
-## Contributing
+// 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);
+  });
+});
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
+// 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
 
-### Common issues
-
 **Iframe not loading:**
 
 - Check that the parent element exists in the DOM
 - Verify your license key is valid
-- Ensure the model ID matches your license
+- Ensure the model ID matches your licence
 
 **Attributes not working:**
 
-- Make sure you call `setMapping()` before using `getAttribute()`
 - Verify attribute names match exactly (case-sensitive)
-- Check that node IDs in your mapping exist in the 3D model
+- Check that the value exists for the attribute
+- Use `onMutationFailed` to catch server-side errors
 
 ## Changelog
 
-See the [GitHub releases](https://github.com/virtualdisplay-io/client/releases)
-for release notes and version history.
+See the [npm version history](https://www.npmjs.com/package/@virtualdisplay.io/client?activeTab=versions)
+for release notes.