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

package/dist/index.d.ts

@@ -1,193 +1,95 @@
-import { Logger } from '@virtualdisplay-io/logger';
+import { CameraConfig } from '@virtualdisplay.io/messaging';
+import { CameraParameter } from '@virtualdisplay.io/messaging';
+import { CameraPositionMessage } from '@virtualdisplay.io/messaging';
+import { MessageCallback } from '@virtualdisplay.io/messaging';
+import { SnapshotResultMessage } from '@virtualdisplay.io/messaging';
+import { UIConfig } from '@virtualdisplay.io/messaging';
 
 /**
- * Pure domain aggregate for managing attribute values
- * No side effects - only business logic and state management
+ * Represents a single attribute with its available values
+ * Flat API - no source/target translation, works with server values directly
  */
-declare class Attribute {
-    private readonly attributeName;
-    private readonly values;
-    constructor(name: string);
-    addValue(attributeValue: AttributeValue): void;
-    getDefaultMutations(): Mutation[];
-    getCurrentValue(): AttributeValue | undefined;
-    getValue(valueName: string): AttributeValue | undefined;
-    getAllValues(): AttributeValue[];
-    hasValue(valueName: string): boolean;
-    get name(): string;
-    get currentSelection(): string | undefined;
-    clear(): void;
-}
-
-/**
- * Configuration for a single attribute
- */
-export declare interface AttributeConfig {
+export declare class Attribute {
     readonly name: string;
-    readonly values: DynamicValue<AttributeValueConfig[]>;
-}
-
-/**
- * Public API for selecting attribute values
- * Provides fluent interface for client usage
- */
-export declare class AttributeSelector {
-    private readonly attributeService;
-    private readonly attributeName;
-    constructor(attributeService: AttributeService, attributeName: string);
+    readonly defaultValue: string | undefined;
+    private readonly values;
+    private readonly onSelect;
+    private onChangeCallback?;
+    constructor(options: AttributeOptions);
     /**
      * Select a value for this attribute
-     * Fire-and-forget: returns immediately, 3D updates asynchronously
-     * @returns this AttributeSelector for method chaining
-     * @throws {VirtualdisplayError} When value not found for attribute
-     */
-    select(value: string): AttributeSelector;
-    get name(): string;
-    get currentValue(): string | undefined;
-    get availableValues(): string[];
-    /**
-     * Register a callback to be called when any value's selection state changes
-     * This registers the callback on all AttributeValue objects for this attribute
-     * @param callback Function to call when selection state changes
-     * @returns this AttributeSelector for method chaining
-     */
-    onChange(callback: () => void): AttributeSelector;
-    /**
-     * Get all AttributeValue objects for direct property access
-     * @returns Array of AttributeValue objects
+     * @throws {VirtualdisplayError} When value not found
      */
+    select(value: string): void;
     getValues(): AttributeValue[];
-    /**
-     * Get a specific AttributeValue object by value name
-     * @param value The value name to find
-     * @returns AttributeValue object or undefined if not found
-     */
     getValue(value: string): AttributeValue | undefined;
-    private getAttribute;
-}
-
-/**
- * Application service for managing attributes
- * Handles business logic and coordinates with other domains via events
- */
-declare class AttributeService {
-    private attributes;
-    private readonly eventBus;
-    private isInitialized;
-    private mappingConfig;
-    private readonly selections;
-    private readonly currentState;
-    constructor(eventBus: EventBus);
-    /**
-     * Load mapping configuration and apply defaults
-     * @throws {VirtualdisplayError} When mapping configuration is invalid
-     */
-    loadMapping(config: MappingConfiguration): void;
-    selectAttributeValue(attributeName: string, value: string): void;
-    getAttribute(name: string): Attribute | undefined;
-    getAllAttributes(): Attribute[];
-    get initialized(): boolean;
-    private syncStateWithAttributes;
-    clear(): void;
-    /**
-     * Create context for dynamic evaluation
-     */
-    private createContext;
-    /**
-     * Evaluate a property that might be static or dynamic
-     */
-    private evaluateProperty;
-    /**
-     * Evaluate the entire mapping with current context
-     */
-    private evaluateMapping;
-    /**
-     * Create a single attribute from configuration
-     */
-    private createAttributeFromConfig;
-    /**
-     * Initialize selections from default values
-     */
-    private initializeSelections;
-    /**
-     * Check if the mapping configuration contains dynamic elements
-     */
-    private hasDynamicMapping;
     /**
-     * Update current state map with visible nodes per attribute
+     * Register callback that fires when selection changes
+     * Receives the newly selected AttributeValue
      */
-    private updateCurrentState;
-    private getVisibleNodesForAttribute;
+    onChange(callback: (selectedValue: AttributeValue) => void): void;
     /**
-     * Get initial mutations for default selections
+     * Update selection state from server mutation result
+     * Direct value comparison - no source/target translation
      */
-    private getInitialMutations;
-    /**
-     * Calculate mutations by comparing old and new state
-     */
-    private calculateMutations;
-    /**
-     * Check if a node is visible in the given state
-     */
-    private isNodeVisible;
+    handleResult(serverValue: string): void;
+    private createValues;
+}
+
+declare interface AttributeOptions {
+    readonly name: string;
+    readonly values: string[];
+    readonly onSelect: (name: string, value: string) => void;
+    readonly defaultValue?: string;
 }
 
 /**
  * Pure domain entity representing a single attribute value
- * No side effects - only business logic and data
+ * No side effects - only state
  */
-declare class AttributeValue {
-    private readonly attributeValue;
-    private readonly nodeIds;
-    private selected;
-    onChange?: () => void;
-    constructor(value: string, nodeIds: string[], isSelected?: boolean);
-    getMutations(): Mutation[];
-    setSelected(selected: boolean): void;
-    get value(): string;
-    get nodeList(): string[];
-    hasNode(nodeId: string): boolean;
+export declare class AttributeValue {
+    readonly value: string;
+    readonly attribute: string;
+    private isSelectedValue;
+    constructor(value: string, attribute: string);
     get isSelected(): boolean;
-    setOnChange(callback: () => void): void;
+    setSelected(selected: boolean): void;
 }
 
-/**
- * Configuration for a single attribute value
- * All properties can be static or dynamic
- */
-export declare interface AttributeValueConfig {
-    readonly value: DynamicValue<string>;
-    readonly nodeIds: DynamicValue<string[]>;
-    readonly isSelected?: DynamicValue<boolean>;
-}
+declare type Attrs = Record<string, unknown> | unknown;
 
 /**
  * Camera control API for positioning and zoom
  * Uses chaining pattern for building commands
  */
 export declare class Camera {
-    private readonly eventBus;
+    private readonly send;
     private commands;
-    constructor(eventBus: EventBus);
+    constructor(send: MessageCallback);
     /**
      * Rotate camera horizontally
      * @param degrees - Absolute rotation in degrees (0 = front view)
+     * @throws VirtualdisplayError if value is not a finite number
      */
     rotate(degrees: number): this;
     /**
      * Tilt camera vertically
      * @param degrees - Absolute tilt in degrees (0 = top view, 90 = horizontal)
+     * @throws VirtualdisplayError if value is not a finite number
      */
     tilt(degrees: number): this;
     /**
      * Zoom camera
      * @param percentage - Zoom percentage (100 = normal, >100 = zoom in, <100 = zoom out)
+     * @throws VirtualdisplayError if value is not a finite number
      */
     zoom(percentage: number): this;
     /**
      * Execute accumulated camera commands
+     * @throws VirtualdisplayError if no commands have been accumulated
      */
     set(): void;
+    private validateFiniteNumber;
     /**
      * Reset camera to initial position
      * This is not chainable and executes immediately
@@ -196,32 +98,46 @@ export declare class Camera {
 }
 
 /**
- * Camera command
+ * Camera position state
+ * Tracks current rotation, tilt, and zoom values from server updates
  */
-export declare interface CameraCommand {
-    readonly action: 'rotate' | 'tilt' | 'zoom' | 'reset';
-    readonly value?: number;
-}
-
-/**
- * Camera configuration options
- */
-export declare interface CameraConfig {
-    readonly initialRotate?: number;
-    readonly initialTilt?: number;
-    readonly initialZoom?: number;
-    readonly minZoom?: number;
-    readonly maxZoom?: number;
-    readonly minTilt?: number;
-    readonly maxTilt?: number;
+declare class CameraPosition {
+    private readonly state;
+    private readonly changeCallbacks;
+    constructor();
+    /**
+     * Get current rotation in degrees
+     */
+    get rotation(): number;
+    /**
+     * Get current tilt in degrees
+     */
+    get tilt(): number;
+    /**
+     * Get current zoom percentage
+     */
+    get zoom(): number;
+    /**
+     * Subscribe to camera position changes
+     */
+    onChange(callback: (position: CameraPositionState) => void): void;
+    /**
+     * Handle incoming camera position message from server
+     */
+    handlePositionUpdate(message: CameraPositionMessage): void;
+    /**
+     * Update camera position from server transforms
+     */
+    update(transforms: CameraParameter[]): void;
 }
 
 /**
- * Camera message sent to server
+ * Camera position state object
  */
-export declare interface CameraMessage {
-    readonly type: typeof MESSAGE_TYPES.CAMERA;
-    readonly commands: CameraCommand[];
+declare interface CameraPositionState {
+    rotation: number;
+    tilt: number;
+    zoom: number;
 }
 
 /**
@@ -240,39 +156,6 @@ export declare interface ClientOptions {
     readonly camera?: CameraConfig;
 }
 
-/**
- * Configuration message sent to server
- */
-export declare interface ConfigMessage {
-    readonly type: typeof MESSAGE_TYPES.CONFIG;
-    readonly config: ViewerConfig;
-}
-
-declare interface CreateNodeParams {
-    id: string;
-    name: string;
-    type: NodeType;
-    visible: boolean;
-}
-
-/**
- * Central Event Registry
- */
-export declare interface DomainEvents extends Record<string, unknown> {
-    [EVENT_NAMES.IFRAME_READY]: VoidEvent;
-    [EVENT_NAMES.MUTATION_MESSAGE]: MessageEvent_2<MutationMessage>;
-    [EVENT_NAMES.CONFIG_MESSAGE]: MessageEvent_2<ConfigMessage>;
-    [EVENT_NAMES.CAMERA_MESSAGE]: MessageEvent_2<CameraMessage>;
-    [EVENT_NAMES.MESSAGE_RECEIVED]: MessageEvent_2;
-    [EVENT_NAMES.STATE_CHANGED]: StateChangedEvent;
-    [EVENT_NAMES.INITIAL_STATE_RECEIVED]: VoidEvent;
-}
-
-/**
- * A value that can be static or dynamically computed
- */
-declare type DynamicValue<T> = T | ((context: MappingContext) => T);
-
 export declare function enableDebugMode(): void;
 
 /**
@@ -282,287 +165,37 @@ export declare const ERROR_CODES: {
     readonly NO_MAPPING: "NO_MAPPING";
     readonly ATTRIBUTE_NOT_FOUND: "ATTRIBUTE_NOT_FOUND";
     readonly VALUE_NOT_FOUND: "VALUE_NOT_FOUND";
-    readonly INVALID_MAPPING: "INVALID_MAPPING";
     readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
-    readonly INVALID_MUTATIONS: "INVALID_MUTATIONS";
     readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    readonly SNAPSHOT_FAILED: "SNAPSHOT_FAILED";
 };
 
 export declare type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
 
-/**
- * Event name constants for type-safe event communication
- */
-export declare const EVENT_NAMES: {
-    readonly IFRAME_READY: "iframe:ready";
-    readonly MUTATION_MESSAGE: "mutation:message";
-    readonly CONFIG_MESSAGE: "config:message";
-    readonly CAMERA_MESSAGE: "camera:message";
-    readonly MESSAGE_RECEIVED: "message:received";
-    readonly STATE_CHANGED: "state:changed";
-    readonly INITIAL_STATE_RECEIVED: "state:initial-received";
-    readonly SNAPSHOT_MESSAGE: "snapshot:take";
-};
-
-/**
- * EventBus for domain coordination
- * Provides loose coupling between domains via events
- */
-declare class EventBus {
-    private readonly listeners;
-    on<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
-    emit<K extends keyof DomainEvents>(event: K, payload: DomainEvents[K]): void;
-    /**
-     * Register a listener that will be called only once
-     * The listener is automatically removed after the first call
-     */
-    once<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
-    /**
-     * Remove a specific listener for an event
-     */
-    off<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
-}
-
-declare type EventListener_2<T> = (payload: T) => void;
-
 export declare function isDebugMode(): boolean;
 
-export declare const logger: Logger;
-
-/**
- * Complete mapping configuration
- * Defines how product attributes map to 3D nodes
- */
-export declare interface MappingConfiguration {
-    readonly attributes: AttributeConfig[];
-}
-
-/**
- * Context provided to dynamic value functions
- */
-declare interface MappingContext {
-    getValue: (attributeName: string) => string | undefined;
-    getAllValues: () => Map<string, string>;
-}
-
-export declare const mappingSchema: {
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "Virtualdisplay mapping configuration",
-    "description": "Schema for attribute-based 3D model configuration",
-    "type": "object",
-    "required": ["attributes"],
-    "definitions": {
-        "attribute": {
-            "type": "object",
-            "description": "A configurable attribute with multiple possible values",
-            "required": ["name", "values"],
-            "properties": {
-                "name": {
-                    "type": "string",
-                    "description": "Unique attribute name (e.g., 'Color', 'Size')",
-                    "minLength": 1,
-                    "pattern": "^\\S.*\\S$|^\\S$"
-                },
-                "values": {
-                    "type": "array",
-                    "description": "Possible values for this attribute",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/attributeValue"
-                    }
-                }
-            }
-        },
-        "attributeValue": {
-            "type": "object",
-            "description": "A single value option for an attribute",
-            "required": ["value", "nodeIds"],
-            "properties": {
-                "value": {
-                    "type": "string",
-                    "description": "Display value (e.g., 'Red', 'Large')",
-                    "minLength": 1,
-                    "pattern": "^\\S.*\\S$|^\\S$"
-                },
-                "nodeIds": {
-                    "type": "array",
-                    "description": "3D model node IDs controlled by this value",
-                    "items": {
-                        "type": "string",
-                        "description": "Node ID in the 3D model"
-                    }
-                },
-                "isSelected": {
-                    "type": "boolean",
-                    "description": "Whether this value is selected by default",
-                    "default": false
-                }
-            }
-        }
-    },
-    "properties": {
-        "attributes": {
-            "type": "array",
-            "description": "List of all configurable attributes",
-            "minItems": 1,
-            "items": {
-                "$ref": "#/definitions/attribute"
-            }
-        }
-    }
+export declare let logger: {
+    debug: (msg: string, attrs?: Attrs) => void;
+    info: (msg: string, attrs?: Attrs) => void;
+    warn: (msg: string, attrs?: Attrs) => void;
+    error: (msg: string, attrs?: Attrs) => void;
 };
 
-/**
- * Validator for mapping configuration using AJV
- */
-export declare class MappingValidator {
-    private static readonly ajv;
-    private static readonly validateFn;
-    /**
-     * Validate complete mapping configuration
-     * @throws {VirtualdisplayError} When mapping configuration is invalid
-     */
-    static validate(config: MappingConfiguration): void;
-    /**
-     * Check if configuration contains dynamic values (functions)
-     */
-    static containsDynamicValues(config: MappingConfiguration): boolean;
-    /**
-     * Basic structure validation for dynamic mappings
-     */
-    private static validateBasicStructure;
-}
-
-/**
- * Union of all possible messages
- */
-export declare type Message = MutationMessage | StateMessage | ConfigMessage | CameraMessage | SnapshotRequestMessage | SnapshotDevelopedMessage;
-
-/**
- * Types of messages exchanged between client and server
- * Using lowercase format to match server
- */
-export declare const MESSAGE_TYPES: {
-    readonly MUTATION: "mutation";
-    readonly STATE: "state";
-    readonly CONFIG: "config";
-    readonly CAMERA: "camera";
-    readonly SNAPSHOT: "snapshot";
-};
-
-/**
- * Generic message event - used for all message passing
- */
-declare interface MessageEvent_2<T extends Message = Message> {
-    message: T;
-}
-
-/**
- * Represents a 3D node in the scene
- * Live object that can be updated to reflect state changes
- */
-export declare class ModelNode {
-    readonly id: string;
-    readonly name: string;
-    readonly type: NodeType;
-    private visible;
-    onChange?: () => void;
-    constructor(params: CreateNodeParams);
-    get isVisible(): boolean;
-    show(): void;
-    hide(): void;
-}
-
-/**
- * DTO for model node data received from server
- */
-export declare interface ModelNodeDto {
-    readonly id: string;
-    readonly name: string;
-    readonly type: string;
-    readonly visible: boolean;
-}
-
-/**
- * A mutation represents a change to be applied to a 3D node
- * This is a pure data class with no side effects
- */
-export declare class Mutation {
-    readonly type: MutationType;
-    readonly nodeId: string;
-    constructor(type: MutationType, nodeId: string);
-    static show(nodeId: string): Mutation;
-    static hide(nodeId: string): Mutation;
-    inverse(): Mutation;
-    equals(other: Mutation): boolean;
-    toDto(): MutationDto;
+export declare interface MutationFailedEvent {
+    attribute: string;
+    value: string;
 }
 
-/**
- * Types of mutations that can be applied to 3D nodes
- */
-export declare const MUTATION_TYPES: {
-    readonly SHOW: "show";
-    readonly HIDE: "hide";
-};
-
-/**
- * Data Transfer Object for mutations
- * Plain object for client-server communication without methods
- */
-export declare interface MutationDto {
-    readonly type: MutationType;
-    readonly nodeId: string;
-}
-
-/**
- * Mutation message sent to server
- */
-export declare interface MutationMessage {
-    readonly type: typeof MESSAGE_TYPES.MUTATION;
-    readonly mutations: MutationDto[];
-}
-
-export declare type MutationType = typeof MUTATION_TYPES[keyof typeof MUTATION_TYPES];
-
-/**
- * Types of nodes in the 3D scene
- */
-export declare const NODE_TYPES: {
-    readonly MESH: "mesh";
-    readonly VARIANT: "variant";
-};
-
-/**
- * Public API for controlling individual nodes
- * Provides direct node manipulation without attribute mapping
- */
-export declare class NodeSelector {
-    private readonly eventBus;
-    private readonly stateService;
-    private readonly nodeId;
-    constructor(eventBus: EventBus, stateService: StateService, nodeId: string);
-    show(): void;
-    hide(): void;
-    toggle(): void;
-    get id(): string;
-    get isVisible(): boolean;
-    getNode(): ModelNode | undefined;
-    get type(): string | undefined;
-    get name(): string | undefined;
-    private emitMutation;
-}
-
-declare type NodeType = typeof NODE_TYPES[keyof typeof NODE_TYPES];
-
 /**
  * Represents a photo being captured
  * Pure domain object that manages callbacks for when the photo is developed
  */
 export declare class Photo {
     private readonly filename;
-    private readonly callbacks;
+    private readonly developedCallbacks;
+    private readonly errorCallbacks;
     private developed;
+    private failed;
     private photoData;
     constructor(filename: string);
     /**
@@ -573,15 +206,26 @@ export declare class Photo {
      * @returns This Photo instance for chaining
      */
     onDeveloped(callback: (photo: PhotoData) => void): this;
+    /**
+     * Register a callback for when the photo capture fails
+     *
+     * @param callback Function to call with error
+     * @returns This Photo instance for chaining
+     */
+    onError(callback: (error: VirtualdisplayError) => void): this;
     /**
      * Get the filename for this photo
      */
     getFilename(): string;
     /**
      * Mark the photo as developed and notify all callbacks
-     * This method is called by the SnapshotMessageHandler when the photo data arrives
+     * This method is called by Snapshot when the photo data arrives from the server
      */
     develop(photoData: PhotoData): void;
+    /**
+     * Mark the photo as failed and notify error callbacks
+     */
+    fail(error: VirtualdisplayError): void;
 }
 
 export declare interface PhotoData {
@@ -594,10 +238,10 @@ export declare interface PhotoData {
  * Following the camera analogy: take() triggers capture, onDeveloped() gets result
  */
 export declare class Snapshot {
-    private readonly eventBus;
+    private readonly send;
     private readonly validExtensions;
-    private readonly messageHandler;
-    constructor(eventBus: EventBus);
+    private readonly pendingPhotos;
+    constructor(send: MessageCallback);
     /**
      * Take a snapshot of the current 3D model view
      *
@@ -606,125 +250,74 @@ export declare class Snapshot {
      * @throws VirtualdisplayError if filename is invalid
      */
     take(filename: string): Photo;
+    /**
+     * Handle incoming snapshot result from server
+     * Matches the message to a pending photo by filename, then develops or fails it
+     */
+    handleSnapshotResult(message: SnapshotResultMessage): void;
     /**
      * Validate filename has a valid image extension
      */
     private validateFilename;
 }
 
-/**
- * Snapshot developed message received from server
- */
-export declare interface SnapshotDevelopedMessage {
-    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
-    readonly filename: string;
-    readonly data: string;
-}
-
-/**
- * Snapshot request message sent to server
- */
-export declare interface SnapshotRequestMessage {
-    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
-    readonly filename: string;
-}
-
-declare interface StateChangedEvent {
-    nodes: ModelNode[];
-}
-
-/**
- * State message received from server
- * Contains array of model node DTOs
- */
-export declare interface StateMessage {
-    readonly type: typeof MESSAGE_TYPES.STATE;
-    readonly nodes: ModelNodeDto[];
-    readonly isInitial: boolean;
-}
-
-/**
- * Application service for managing node state
- * Handles state updates from server and emits node change events
- */
-declare class StateService {
-    private readonly nodes;
-    private readonly eventBus;
-    private hasReceivedInitialSync;
-    constructor(eventBus: EventBus);
-    private handleMessage;
-    private updateState;
-    private updateOrCreateNode;
-    private createNewNode;
-    getNode(id: string): ModelNode | undefined;
-    getAllNodes(): ModelNode[];
-    get isReady(): boolean;
-    get nodeCount(): number;
-    clear(): void;
-}
-
-/**
- * UI configuration options
- */
-export declare interface UIConfig {
-    readonly arEnabled?: boolean;
-    readonly fullscreenEnabled?: boolean;
-    readonly loadingIndicatorEnabled?: boolean;
-}
-
-/**
- * Viewer configuration
- */
-export declare interface ViewerConfig {
-    readonly ui?: UIConfig;
-    readonly camera?: CameraConfig;
-}
-
 /**
  * Main Virtualdisplay Client
  * Provides the public API for 3D product visualization
+ *
+ * Acts as the composition root: wires all services together with direct dependency injection
  */
 export declare class VirtualdisplayClient {
-    private readonly eventBus;
-    private readonly attributeService;
-    private readonly stateService;
-    private readonly messageHandler;
+    private readonly attributes;
+    private readonly readyStateTracker;
+    private readonly messenger;
     private readonly viewerService;
     private readonly cameraApi;
+    private readonly cameraPositionApi;
     private readonly snapshotApi;
     private readonly options;
     private iframe;
+    private readyCallbacks;
+    private readonly mutationFailedCallbacks;
     constructor(options: ClientOptions);
+    private registerHandlers;
     private initializeLogging;
     private createAndConnectIframe;
-    private setupInitialConfig;
     /**
-     * Load attribute mapping configuration
-     * @throws {VirtualdisplayError} When mapping configuration is invalid
+     * Select a value for an attribute — sends mutation to server.
+     * Can be called immediately; the messenger's publisher queue holds
+     * the message until the iframe is ready.
+     */
+    select(name: string, value: string): void;
+    /**
+     * Get all available values for an attribute
      */
-    setMapping(config: MappingConfiguration): void;
+    getValues(name: string): AttributeValue[];
     /**
-     * Get attribute selector for fluent API
-     * @throws {VirtualdisplayError} When no mapping is configured or attribute not found
+     * Get a specific value for an attribute
      */
-    getAttribute(name: string): AttributeSelector;
+    getValue(name: string, value: string): AttributeValue | undefined;
     /**
-     * Get node selector for direct node control
-     * @param nodeId The node ID to control
-     * @returns NodeSelector if node exists, undefined otherwise
+     * Register callback that fires when an attribute's selection changes
      */
-    getNodeSelector(nodeId: string): NodeSelector | undefined;
-    getNode(id: string): ModelNode | undefined;
-    getNodes(): ModelNode[];
+    onChange(name: string, callback: (selectedValue: AttributeValue) => void): void;
+    /**
+     * Get the Attribute instance for advanced use cases
+     */
+    getAttribute(name: string): Attribute | undefined;
     /**
-     * Check if the client has received initial state and is ready
+     * Check if the client has received initial mutations and is ready
      */
     get isReady(): boolean;
     /**
      * Register a callback to be called when the client is ready
      * If already ready, the callback is called immediately
      */
-    onReady(callback: () => void): void;
+    onReady(callback: (client: VirtualdisplayClient) => void): void;
+    /**
+     * Register a callback for when a mutation fails on the server
+     */
+    onMutationFailed(callback: (event: MutationFailedEvent) => void): void;
     /**
      * Get the viewer service for UI configuration
      */
@@ -733,6 +326,10 @@ export declare class VirtualdisplayClient {
      * Get the camera control API
      */
     get camera(): Camera;
+    /**
+     * Get the camera position tracking API
+     */
+    get cameraPosition(): CameraPosition;
     /**
      * Get the snapshot API for taking screenshots
      */
@@ -749,9 +346,9 @@ export declare class VirtualdisplayError extends Error {
     static noMapping(): VirtualdisplayError;
     static attributeNotFound(attributeName: string): VirtualdisplayError;
     static valueNotFound(attributeName: string, valueName: string): VirtualdisplayError;
-    static invalidMapping(reason?: string): VirtualdisplayError;
     static parentNotFound(selector: string): VirtualdisplayError;
-    static invalidMutations(reason?: string): VirtualdisplayError;
+    static invalidParameter(reason: string): VirtualdisplayError;
+    static snapshotFailed(filename: string, reason: string): VirtualdisplayError;
 }
 
 /**
@@ -759,8 +356,8 @@ export declare class VirtualdisplayError extends Error {
  * Sends CONFIG messages to control AR button, fullscreen button, and loading indicator
  */
 export declare class VirtualdisplayViewerService {
-    private readonly eventBus;
-    constructor(eventBus: EventBus);
+    private readonly send;
+    constructor(send: MessageCallback);
     /**
      * Send initial configuration based on client options
      * Supports both individual properties and ui object
@@ -815,7 +412,4 @@ export declare class VirtualdisplayViewerService {
     private sendConfig;
 }
 
-declare interface VoidEvent {
-}
-
 export { }