@virtualdisplay.io/client 3.4.1 → 3.5.1

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;
@@ -56,10 +57,15 @@ const EVENT_NAMES = {
   MUTATION_MESSAGE: "mutation:message",
   // Config flow (Client → Server)
   CONFIG_MESSAGE: "config:message",
+  // Camera flow (Client → Server)
+  CAMERA_MESSAGE: "camera:message",
   // 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,
@@ -6928,7 +6934,9 @@ class MappingValidator {
 const MESSAGE_TYPES = {
   MUTATION: "mutation",
   STATE: "state",
-  CONFIG: "config"
+  CONFIG: "config",
+  CAMERA: "camera",
+  SNAPSHOT: "snapshot"
 };
 function createMutationMessage(mutations) {
   if (!Array.isArray(mutations)) {
@@ -6940,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) {
@@ -6956,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();
@@ -7052,6 +7053,61 @@ class AttributeService {
     this.isInitialized = false;
   }
 }
+class Camera {
+  constructor(eventBus) {
+    this.eventBus = eventBus;
+  }
+  commands = [];
+  /**
+   * Rotate camera horizontally
+   * @param degrees - Absolute rotation in degrees (0 = front view)
+   */
+  rotate(degrees) {
+    this.commands.push({ action: "rotate", value: degrees });
+    return this;
+  }
+  /**
+   * Tilt camera vertically
+   * @param degrees - Absolute tilt in degrees (0 = top view, 90 = horizontal)
+   */
+  tilt(degrees) {
+    this.commands.push({ action: "tilt", value: degrees });
+    return this;
+  }
+  /**
+   * Zoom camera
+   * @param percentage - Zoom percentage (100 = normal, >100 = zoom in, <100 = zoom out)
+   */
+  zoom(percentage) {
+    this.commands.push({ action: "zoom", value: percentage });
+    return this;
+  }
+  /**
+   * Execute accumulated camera commands
+   */
+  set() {
+    if (this.commands.length === 0) {
+      return;
+    }
+    const message = {
+      type: MESSAGE_TYPES.CAMERA,
+      commands: this.commands
+    };
+    this.eventBus.emit(EVENT_NAMES.CAMERA_MESSAGE, { message });
+    this.commands = [];
+  }
+  /**
+   * Reset camera to initial position
+   * This is not chainable and executes immediately
+   */
+  reset() {
+    const message = {
+      type: MESSAGE_TYPES.CAMERA,
+      commands: [{ action: "reset" }]
+    };
+    this.eventBus.emit(EVENT_NAMES.CAMERA_MESSAGE, { message });
+  }
+}
 class EventBus {
   listeners = /* @__PURE__ */ new Map();
   on(event, listener) {
@@ -7168,11 +7224,14 @@ class MessageHandler {
   setupOutgoingMessages() {
     const outgoingEvents = [
       EVENT_NAMES.MUTATION_MESSAGE,
-      EVENT_NAMES.CONFIG_MESSAGE
+      EVENT_NAMES.CONFIG_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);
       });
     });
   }
@@ -7360,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) {
@@ -7452,6 +7661,8 @@ class VirtualdisplayClient {
   stateService;
   messageHandler;
   viewerService;
+  cameraApi;
+  snapshotApi;
   options;
   iframe;
   constructor(options) {
@@ -7461,6 +7672,8 @@ class VirtualdisplayClient {
     this.stateService = new StateService(this.eventBus);
     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();
@@ -7554,6 +7767,18 @@ class VirtualdisplayClient {
   get viewer() {
     return this.viewerService;
   }
+  /**
+   * Get the camera control API
+   */
+  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();
@@ -7568,6 +7793,7 @@ class VirtualdisplayClient {
 }
 export {
   AttributeSelector,
+  Camera,
   ERROR_CODES,
   EVENT_NAMES,
   MESSAGE_TYPES,
@@ -7577,6 +7803,8 @@ export {
   Mutation,
   NODE_TYPES,
   NodeSelector,
+  Photo,
+  Snapshot,
   VirtualdisplayClient,
   VirtualdisplayError,
   VirtualdisplayViewerService,