@virtualdisplay.io/client 3.5.0 → 3.6.0

package/dist/virtualdisplay.client.es.js

@@ -4,7 +4,8 @@ const ERROR_CODES = {
   VALUE_NOT_FOUND: "VALUE_NOT_FOUND",
   INVALID_MAPPING: "INVALID_MAPPING",
   PARENT_NOT_FOUND: "PARENT_NOT_FOUND",
-  INVALID_MUTATIONS: "INVALID_MUTATIONS"
+  INVALID_MUTATIONS: "INVALID_MUTATIONS",
+  INVALID_PARAMETER: "INVALID_PARAMETER"
 };
 class VirtualdisplayError extends Error {
   code;
@@ -61,7 +62,10 @@ const EVENT_NAMES = {
   // State flow (Server → Client)
   MESSAGE_RECEIVED: "message:received",
   STATE_CHANGED: "state:changed",
-  INITIAL_STATE_RECEIVED: "state:initial-received"
+  INITIAL_STATE_RECEIVED: "state:initial-received",
+  // Snapshot flow
+  SNAPSHOT_MESSAGE: "snapshot:take",
+  SNAPSHOT_DEVELOPED: "snapshot:developed"
 };
 const g = Object.freeze({
   debug: 0,
@@ -6931,7 +6935,8 @@ const MESSAGE_TYPES = {
   MUTATION: "mutation",
   STATE: "state",
   CONFIG: "config",
-  CAMERA: "camera"
+  CAMERA: "camera",
+  SNAPSHOT: "snapshot"
 };
 function createMutationMessage(mutations) {
   if (!Array.isArray(mutations)) {
@@ -6943,14 +6948,7 @@ function createMutationMessage(mutations) {
   };
 }
 function isValidMessage(data) {
-  return isMutationMessage(data) || isStateMessage(data) || isConfigMessage(data);
-}
-function isMutationMessage(data) {
-  if (typeof data !== "object" || data === null) {
-    return false;
-  }
-  const obj = data;
-  return obj.type === MESSAGE_TYPES.MUTATION && Array.isArray(obj.mutations);
+  return isStateMessage(data) || isSnapshotDevelopedMessage(data);
 }
 function isStateMessage(data) {
   if (typeof data !== "object" || data === null) {
@@ -6959,12 +6957,12 @@ function isStateMessage(data) {
   const obj = data;
   return obj.type === MESSAGE_TYPES.STATE && Array.isArray(obj.nodes);
 }
-function isConfigMessage(data) {
+function isSnapshotDevelopedMessage(data) {
   if (typeof data !== "object" || data === null) {
     return false;
   }
   const obj = data;
-  return obj.type === MESSAGE_TYPES.CONFIG && typeof obj.config === "object" && obj.config !== null;
+  return obj.type === MESSAGE_TYPES.SNAPSHOT && typeof obj.filename === "string" && typeof obj.data === "string";
 }
 class AttributeService {
   attributes = /* @__PURE__ */ new Map();
@@ -7227,11 +7225,13 @@ class MessageHandler {
     const outgoingEvents = [
       EVENT_NAMES.MUTATION_MESSAGE,
       EVENT_NAMES.CONFIG_MESSAGE,
-      EVENT_NAMES.CAMERA_MESSAGE
+      EVENT_NAMES.CAMERA_MESSAGE,
+      EVENT_NAMES.SNAPSHOT_MESSAGE
     ];
     outgoingEvents.forEach((eventName) => {
       this.eventBus.on(eventName, (event) => {
-        this.queueOrSend(event.message);
+        const messageEvent = event;
+        this.queueOrSend(messageEvent.message);
       });
     });
   }
@@ -7419,6 +7419,156 @@ class StateService {
     this.hasReceivedInitialSync = false;
   }
 }
+class Photo {
+  constructor(filename) {
+    this.filename = filename;
+  }
+  callbacks = /* @__PURE__ */ new Set();
+  developed = false;
+  photoData = null;
+  /**
+   * Register a callback for when the photo is developed
+   * If the photo is already developed, the callback is called immediately
+   *
+   * @param callback Function to call with photo data
+   * @returns This Photo instance for chaining
+   */
+  onDeveloped(callback) {
+    if (this.developed && this.photoData !== null) {
+      callback(this.photoData);
+      return this;
+    }
+    this.callbacks.add(callback);
+    return this;
+  }
+  /**
+   * Get the filename for this photo
+   */
+  getFilename() {
+    return this.filename;
+  }
+  /**
+   * Mark the photo as developed and notify all callbacks
+   * This method is called by the SnapshotMessageHandler when the photo data arrives
+   */
+  develop(photoData) {
+    if (this.developed) {
+      return;
+    }
+    this.photoData = photoData;
+    this.developed = true;
+    this.callbacks.forEach((callback) => {
+      callback(this.photoData);
+    });
+    this.callbacks.clear();
+  }
+}
+class SnapshotMessageHandler {
+  constructor(eventBus) {
+    this.eventBus = eventBus;
+    logger.debug("SnapshotMessageHandler initialized");
+    this.setupMessageListener();
+  }
+  pendingPhotos = /* @__PURE__ */ new Map();
+  /**
+   * Register a photo to be developed when its data arrives
+   */
+  registerPhoto(photo) {
+    logger.debug("Registering photo for development", { filename: photo.getFilename() });
+    this.pendingPhotos.set(photo.getFilename(), photo);
+    logger.debug("Pending photos count", { count: this.pendingPhotos.size });
+  }
+  setupMessageListener() {
+    logger.debug("Setting up message listener for snapshot messages");
+    this.eventBus.on(EVENT_NAMES.MESSAGE_RECEIVED, (event) => {
+      const { message } = event;
+      if (message.type === MESSAGE_TYPES.SNAPSHOT) {
+        logger.debug("Processing snapshot message");
+        this.handleSnapshotDeveloped(message);
+      }
+    });
+  }
+  handleSnapshotDeveloped(message) {
+    logger.debug("Handling snapshot developed message", {
+      filename: message.filename,
+      dataLength: message.data.length,
+      pendingCount: this.pendingPhotos.size
+    });
+    const photo = this.pendingPhotos.get(message.filename);
+    if (photo !== void 0) {
+      logger.debug("Found pending photo, developing...", { filename: message.filename });
+      const photoData = {
+        filename: message.filename,
+        data: message.data
+      };
+      photo.develop(photoData);
+      this.pendingPhotos.delete(message.filename);
+      logger.debug("Photo developed and removed from pending", {
+        filename: message.filename,
+        remainingCount: this.pendingPhotos.size
+      });
+      return;
+    }
+    logger.warn("No pending photo found for filename", {
+      filename: message.filename,
+      pendingFilenames: Array.from(this.pendingPhotos.keys())
+    });
+  }
+}
+class Snapshot {
+  constructor(eventBus) {
+    this.eventBus = eventBus;
+    this.messageHandler = new SnapshotMessageHandler(eventBus);
+  }
+  validExtensions = [".png", ".jpg", ".jpeg", ".webp"];
+  messageHandler;
+  /**
+   * Take a snapshot of the current 3D model view
+   *
+   * @param filename The filename for the snapshot (must include valid extension)
+   * @returns Photo object for registering callbacks
+   * @throws VirtualdisplayError if filename is invalid
+   */
+  take(filename) {
+    this.validateFilename(filename);
+    logger.debug("Taking snapshot", { filename });
+    const photo = new Photo(filename);
+    this.messageHandler.registerPhoto(photo);
+    this.eventBus.emit(EVENT_NAMES.SNAPSHOT_MESSAGE, {
+      message: {
+        type: MESSAGE_TYPES.SNAPSHOT,
+        filename
+      }
+    });
+    return photo;
+  }
+  /**
+   * Validate filename has a valid image extension
+   */
+  validateFilename(filename) {
+    if (filename === "" || typeof filename !== "string") {
+      throw new VirtualdisplayError(
+        "Filename must be a non-empty string",
+        ERROR_CODES.INVALID_PARAMETER
+      );
+    }
+    const hasValidExtension = this.validExtensions.some(
+      (ext) => filename.toLowerCase().endsWith(ext)
+    );
+    if (!hasValidExtension) {
+      throw new VirtualdisplayError(
+        `Invalid filename: "${filename}". Filename must end with one of: ${this.validExtensions.join(", ")}`,
+        ERROR_CODES.INVALID_PARAMETER
+      );
+    }
+    if (filename.includes("..") || filename.includes("/") || filename.includes("\\")) {
+      throw new VirtualdisplayError(
+        'Filename cannot contain path separators or ".."',
+        ERROR_CODES.INVALID_PARAMETER
+      );
+    }
+  }
+}
 class VirtualdisplayViewerService {
   eventBus;
   constructor(eventBus) {
@@ -7426,50 +7576,88 @@ class VirtualdisplayViewerService {
   }
   /**
    * Send initial configuration based on client options
-   * Only sends config when values are false (server defaults to true)
+   * Supports both individual properties and ui object
    */
   sendInitialConfig(options) {
-    const config = {};
-    if (options.arEnabled === false) {
-      config.arEnabled = false;
-    }
-    if (options.fullscreenEnabled === false) {
-      config.fullscreenEnabled = false;
+    const uiConfig = this.buildUIConfig(options);
+    const viewerConfig = this.buildViewerConfig(uiConfig, options.camera);
+    if (viewerConfig !== void 0) {
+      this.sendConfig(viewerConfig);
     }
-    if (options.loadingIndicatorEnabled === false) {
-      config.loadingIndicatorEnabled = false;
+  }
+  /**
+   * Build UI configuration from client options
+   *
+   * Supports both legacy properties (options.arEnabled) and the newer ui object
+   * for backward compatibility. Legacy properties take precedence when both exist.
+   */
+  buildUIConfig(options) {
+    const uiValues = this.extractUIValues(options);
+    const hasUIConfig = Object.values(uiValues).some((value) => value !== void 0);
+    if (!hasUIConfig) {
+      return void 0;
     }
-    if (Object.keys(config).length > 0) {
-      this.sendUIConfig(config);
+    return {
+      ...uiValues.arEnabled !== void 0 && { arEnabled: uiValues.arEnabled },
+      ...uiValues.fullscreenEnabled !== void 0 && {
+        fullscreenEnabled: uiValues.fullscreenEnabled
+      },
+      ...uiValues.loadingIndicatorEnabled !== void 0 && {
+        loadingIndicatorEnabled: uiValues.loadingIndicatorEnabled
+      }
+    };
+  }
+  /**
+   * Extract UI values from options, with legacy properties taking precedence
+   */
+  extractUIValues(options) {
+    return {
+      arEnabled: options.arEnabled ?? options.ui?.arEnabled,
+      fullscreenEnabled: options.fullscreenEnabled ?? options.ui?.fullscreenEnabled,
+      loadingIndicatorEnabled: options.loadingIndicatorEnabled ?? options.ui?.loadingIndicatorEnabled
+    };
+  }
+  /**
+   * Build viewer configuration from UI config and camera config
+   */
+  buildViewerConfig(uiConfig, cameraConfig) {
+    if (uiConfig === void 0 && cameraConfig === void 0) {
+      return void 0;
     }
+    return {
+      ...uiConfig !== void 0 && { ui: uiConfig },
+      ...cameraConfig !== void 0 && { camera: cameraConfig }
+    };
   }
   /**
    * Update AR button visibility
    */
   setArEnabled(enabled) {
     logger.debug(`Setting AR button enabled: ${enabled}`);
-    this.sendUIConfig({ arEnabled: enabled });
+    this.updateUIConfig({ arEnabled: enabled });
   }
   /**
    * Update fullscreen button visibility
    */
   setFullscreenEnabled(enabled) {
     logger.debug(`Setting fullscreen button enabled: ${enabled}`);
-    this.sendUIConfig({ fullscreenEnabled: enabled });
+    this.updateUIConfig({ fullscreenEnabled: enabled });
   }
   /**
    * Update loading indicator visibility
    */
   setLoadingIndicatorEnabled(enabled) {
     logger.debug(`Setting loading indicator enabled: ${enabled}`);
-    this.sendUIConfig({ loadingIndicatorEnabled: enabled });
+    this.updateUIConfig({ loadingIndicatorEnabled: enabled });
   }
   /**
    * Update multiple UI settings at once
    */
   updateUIConfig(config) {
     logger.debug("Updating UI configuration", config);
-    this.sendUIConfig(config);
+    if (Object.keys(config).length > 0) {
+      this.sendConfig({ ui: config });
+    }
   }
   /**
    * Hide all UI elements
@@ -7497,11 +7685,17 @@ class VirtualdisplayViewerService {
    * Send UI configuration to server
    */
   sendUIConfig(uiConfig) {
-    const config = { ui: uiConfig };
+    this.sendConfig({ ui: uiConfig });
+  }
+  /**
+   * Send full viewer configuration to server
+   */
+  sendConfig(config) {
     const message = {
       type: MESSAGE_TYPES.CONFIG,
       config
     };
+    logger.debug("Sending config", message);
     this.eventBus.emit(EVENT_NAMES.CONFIG_MESSAGE, { message });
   }
 }
@@ -7512,6 +7706,7 @@ class VirtualdisplayClient {
   messageHandler;
   viewerService;
   cameraApi;
+  snapshotApi;
   options;
   iframe;
   constructor(options) {
@@ -7522,6 +7717,7 @@ class VirtualdisplayClient {
     this.messageHandler = new MessageHandler(this.eventBus);
     this.viewerService = new VirtualdisplayViewerService(this.eventBus);
     this.cameraApi = new Camera(this.eventBus);
+    this.snapshotApi = new Snapshot(this.eventBus);
     this.initializeLogging();
     this.createAndConnectIframe();
     this.setupInitialConfig();
@@ -7621,6 +7817,12 @@ class VirtualdisplayClient {
   get camera() {
     return this.cameraApi;
   }
+  /**
+   * Get the snapshot API for taking screenshots
+   */
+  get snapshot() {
+    return this.snapshotApi;
+  }
   destroy() {
     logger.info("Destroying Virtualdisplay client");
     this.attributeService.clear();
@@ -7645,6 +7847,8 @@ export {
   Mutation,
   NODE_TYPES,
   NodeSelector,
+  Photo,
+  Snapshot,
   VirtualdisplayClient,
   VirtualdisplayError,
   VirtualdisplayViewerService,