@virtualdisplay.io/client 3.2.2 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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.
 
+## [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))
+
+## [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))
+
 ## [3.2.2](https://github.com/virtualdisplay-io/client/compare/v3.2.1...v3.2.2) (2025-07-01)
 
 ### 🐛 Bug Fixes

package/dist/index.d.ts

@@ -121,13 +121,6 @@ export declare interface AttributeValueConfig {
     readonly isSelected?: boolean;
 }
 
-/**
- * Base message interface
- */
-declare interface BaseMessage {
-    readonly type: MessageType;
-}
-
 /**
  * Configuration options for VirtualdisplayClient
  */
@@ -137,6 +130,17 @@ export declare interface ClientOptions {
     readonly license: string;
     readonly debug?: boolean;
     readonly language?: string;
+    readonly arEnabled?: boolean;
+    readonly fullscreenEnabled?: boolean;
+    readonly loadingIndicatorEnabled?: boolean;
+}
+
+/**
+ * Configuration message sent to server
+ */
+export declare interface ConfigMessage {
+    readonly type: typeof MESSAGE_TYPES.CONFIG;
+    readonly config: ViewerConfig;
 }
 
 declare interface CreateNodeParams {
@@ -151,9 +155,11 @@ declare interface CreateNodeParams {
  */
 export declare interface DomainEvents extends Record<string, unknown> {
     [EVENT_NAMES.IFRAME_READY]: VoidEvent;
-    [EVENT_NAMES.MUTATION_MESSAGE]: MutationMessageEvent;
-    [EVENT_NAMES.MESSAGE_RECEIVED]: MessageReceivedEvent;
+    [EVENT_NAMES.MUTATION_MESSAGE]: MessageEvent_2<MutationMessage>;
+    [EVENT_NAMES.CONFIG_MESSAGE]: MessageEvent_2<ConfigMessage>;
+    [EVENT_NAMES.MESSAGE_RECEIVED]: MessageEvent_2;
     [EVENT_NAMES.STATE_CHANGED]: StateChangedEvent;
+    [EVENT_NAMES.INITIAL_STATE_RECEIVED]: VoidEvent;
 }
 
 export declare function enableDebugMode(): void;
@@ -178,8 +184,10 @@ export declare type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
 export declare const EVENT_NAMES: {
     readonly IFRAME_READY: "iframe:ready";
     readonly MUTATION_MESSAGE: "mutation:message";
+    readonly CONFIG_MESSAGE: "config:message";
     readonly MESSAGE_RECEIVED: "message:received";
     readonly STATE_CHANGED: "state:changed";
+    readonly INITIAL_STATE_RECEIVED: "state:initial-received";
 };
 
 /**
@@ -291,7 +299,7 @@ export declare class MappingValidator {
 /**
  * Union of all possible messages
  */
-export declare type Message = MutationMessage | StateMessage;
+export declare type Message = MutationMessage | StateMessage | ConfigMessage;
 
 /**
  * Types of messages exchanged between client and server
@@ -300,17 +308,16 @@ export declare type Message = MutationMessage | StateMessage;
 export declare const MESSAGE_TYPES: {
     readonly MUTATION: "mutation";
     readonly STATE: "state";
+    readonly CONFIG: "config";
 };
 
 /**
- * State Flow Events (Server → Client)
+ * Generic message event - used for all message passing
  */
-declare interface MessageReceivedEvent {
-    message: unknown;
+declare interface MessageEvent_2<T extends Message = Message> {
+    message: T;
 }
 
-declare type MessageType = typeof MESSAGE_TYPES[keyof typeof MESSAGE_TYPES];
-
 /**
  * Represents a 3D node in the scene
  * Live object that can be updated to reflect state changes
@@ -320,6 +327,7 @@ export declare class ModelNode {
     readonly name: string;
     readonly type: NodeType;
     private visible;
+    onChange?: () => void;
     constructor(params: CreateNodeParams);
     get isVisible(): boolean;
     show(): void;
@@ -371,18 +379,11 @@ export declare interface MutationDto {
 /**
  * Mutation message sent to server
  */
-export declare interface MutationMessage extends BaseMessage {
+export declare interface MutationMessage {
     readonly type: typeof MESSAGE_TYPES.MUTATION;
     readonly mutations: MutationDto[];
 }
 
-/**
- * Mutation Flow Events (Client → Server)
- */
-declare interface MutationMessageEvent {
-    message: MutationMessage;
-}
-
 export declare type MutationType = typeof MUTATION_TYPES[keyof typeof MUTATION_TYPES];
 
 /**
@@ -423,9 +424,10 @@ declare interface StateChangedEvent {
  * State message received from server
  * Contains array of model node DTOs
  */
-export declare interface StateMessage extends BaseMessage {
+export declare interface StateMessage {
     readonly type: typeof MESSAGE_TYPES.STATE;
     readonly nodes: ModelNodeDto[];
+    readonly isInitial: boolean;
 }
 
 /**
@@ -435,6 +437,7 @@ export declare interface StateMessage extends BaseMessage {
 declare class StateService {
     private readonly nodes;
     private readonly eventBus;
+    private hasReceivedInitialSync;
     constructor(eventBus: EventBus);
     private handleMessage;
     private updateState;
@@ -444,10 +447,25 @@ declare class StateService {
     getAllNodes(): ModelNode[];
     get isReady(): boolean;
     get nodeCount(): number;
-    private get hasInitialState();
     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;
+}
+
 /**
  * Main Virtualdisplay Client
  * Provides the public API for 3D product visualization
@@ -457,11 +475,13 @@ export declare class VirtualdisplayClient {
     private readonly attributeService;
     private readonly stateService;
     private readonly messageHandler;
+    private readonly viewerService;
     private readonly options;
     private iframe;
     constructor(options: ClientOptions);
     private initializeLogging;
     private createAndConnectIframe;
+    private setupInitialConfig;
     /**
      * Load attribute mapping configuration
      * @throws {VirtualdisplayError} When mapping configuration is invalid
@@ -480,6 +500,19 @@ export declare class VirtualdisplayClient {
     getNodeSelector(nodeId: string): NodeSelector | undefined;
     getNode(id: string): ModelNode | undefined;
     getNodes(): ModelNode[];
+    /**
+     * Check if the client has received initial state 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;
+    /**
+     * Get the viewer service for UI configuration
+     */
+    get viewer(): VirtualdisplayViewerService;
     destroy(): void;
 }
 
@@ -497,6 +530,48 @@ export declare class VirtualdisplayError extends Error {
     static invalidMutations(reason?: string): VirtualdisplayError;
 }
 
+/**
+ * Service responsible for managing viewer UI configuration
+ * Sends CONFIG messages to control AR button, fullscreen button, and loading indicator
+ */
+export declare class VirtualdisplayViewerService {
+    private readonly eventBus;
+    constructor(eventBus: EventBus);
+    /**
+     * Send initial configuration based on client options
+     * Only sends config when values are false (server defaults to true)
+     */
+    sendInitialConfig(options: ClientOptions): void;
+    /**
+     * Update AR button visibility
+     */
+    setArEnabled(enabled: boolean): void;
+    /**
+     * Update fullscreen button visibility
+     */
+    setFullscreenEnabled(enabled: boolean): void;
+    /**
+     * Update loading indicator visibility
+     */
+    setLoadingIndicatorEnabled(enabled: boolean): void;
+    /**
+     * Update multiple UI settings at once
+     */
+    updateUIConfig(config: Partial<UIConfig>): void;
+    /**
+     * Hide all UI elements
+     */
+    hideAllUI(): void;
+    /**
+     * Show all UI elements
+     */
+    showAllUI(): void;
+    /**
+     * Send UI configuration to server
+     */
+    private sendUIConfig;
+}
+
 declare interface VoidEvent {
 }