@virtualdisplay.io/client 3.4.1 → 3.5.1

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.5.1](https://github.com/virtualdisplay-io/client/compare/v3.5.0...v3.5.1) (2025-07-18)
+
+### ♻️ Code Refactoring
+
+* remove validation of outgoing message types ([#5](https://github.com/virtualdisplay-io/client/issues/5)) ([5f4f985](https://github.com/virtualdisplay-io/client/commit/5f4f9853d65af676aec3a865864f43461fdb6ca5))
+
+## [3.5.0](https://github.com/virtualdisplay-io/client/compare/v3.4.1...v3.5.0) (2025-07-16)
+
+### ✨ Features
+
+* camera control API ([#4](https://github.com/virtualdisplay-io/client/issues/4)) ([1e4c147](https://github.com/virtualdisplay-io/client/commit/1e4c14747cad2a4617c4cc763522b50941adaa7f))
+
 ## [3.4.1](https://github.com/virtualdisplay-io/client/compare/v3.4.0...v3.4.1) (2025-07-10)
 
 ### 🐛 Bug Fixes

package/dist/index.d.ts

@@ -121,6 +121,56 @@ export declare interface AttributeValueConfig {
     readonly isSelected?: boolean;
 }
 
+/**
+ * Camera control API for positioning and zoom
+ * Uses chaining pattern for building commands
+ */
+export declare class Camera {
+    private readonly eventBus;
+    private commands;
+    constructor(eventBus: EventBus);
+    /**
+     * Rotate camera horizontally
+     * @param degrees - Absolute rotation in degrees (0 = front view)
+     */
+    rotate(degrees: number): this;
+    /**
+     * Tilt camera vertically
+     * @param degrees - Absolute tilt in degrees (0 = top view, 90 = horizontal)
+     */
+    tilt(degrees: number): this;
+    /**
+     * Zoom camera
+     * @param percentage - Zoom percentage (100 = normal, >100 = zoom in, <100 = zoom out)
+     */
+    zoom(percentage: number): this;
+    /**
+     * Execute accumulated camera commands
+     */
+    set(): void;
+    /**
+     * Reset camera to initial position
+     * This is not chainable and executes immediately
+     */
+    reset(): void;
+}
+
+/**
+ * Camera command
+ */
+export declare interface CameraCommand {
+    readonly action: 'rotate' | 'tilt' | 'zoom' | 'reset';
+    readonly value?: number;
+}
+
+/**
+ * Camera message sent to server
+ */
+export declare interface CameraMessage {
+    readonly type: typeof MESSAGE_TYPES.CAMERA;
+    readonly commands: CameraCommand[];
+}
+
 /**
  * Configuration options for VirtualdisplayClient
  */
@@ -157,6 +207,7 @@ 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;
@@ -174,6 +225,7 @@ export declare const ERROR_CODES: {
     readonly INVALID_MAPPING: "INVALID_MAPPING";
     readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
     readonly INVALID_MUTATIONS: "INVALID_MUTATIONS";
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
 };
 
 export declare type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
@@ -185,9 +237,12 @@ 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";
+    readonly SNAPSHOT_DEVELOPED: "snapshot:developed";
 };
 
 /**
@@ -306,7 +361,7 @@ export declare class MappingValidator {
 /**
  * Union of all possible messages
  */
-export declare type Message = MutationMessage | StateMessage | ConfigMessage;
+export declare type Message = MutationMessage | StateMessage | ConfigMessage | CameraMessage | SnapshotRequestMessage | SnapshotDevelopedMessage;
 
 /**
  * Types of messages exchanged between client and server
@@ -316,6 +371,8 @@ export declare const MESSAGE_TYPES: {
     readonly MUTATION: "mutation";
     readonly STATE: "state";
     readonly CONFIG: "config";
+    readonly CAMERA: "camera";
+    readonly SNAPSHOT: "snapshot";
 };
 
 /**
@@ -423,6 +480,80 @@ export declare class NodeSelector {
 
 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 developed;
+    private photoData;
+    constructor(filename: string);
+    /**
+     * 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: (photo: PhotoData) => 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
+     */
+    develop(photoData: PhotoData): void;
+}
+
+export declare interface PhotoData {
+    readonly filename: string;
+    readonly data: string;
+}
+
+/**
+ * API for taking screenshots of the 3D model
+ * Following the camera analogy: take() triggers capture, onDeveloped() gets result
+ */
+export declare class Snapshot {
+    private readonly eventBus;
+    private readonly validExtensions;
+    private readonly messageHandler;
+    constructor(eventBus: EventBus);
+    /**
+     * 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: string): Photo;
+    /**
+     * 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[];
 }
@@ -483,6 +614,8 @@ export declare class VirtualdisplayClient {
     private readonly stateService;
     private readonly messageHandler;
     private readonly viewerService;
+    private readonly cameraApi;
+    private readonly snapshotApi;
     private readonly options;
     private iframe;
     constructor(options: ClientOptions);
@@ -520,6 +653,14 @@ export declare class VirtualdisplayClient {
      * Get the viewer service for UI configuration
      */
     get viewer(): VirtualdisplayViewerService;
+    /**
+     * Get the camera control API
+     */
+    get camera(): Camera;
+    /**
+     * Get the snapshot API for taking screenshots
+     */
+    get snapshot(): Snapshot;
     destroy(): void;
 }