react-vnc-lib/dist/index.d.mts

A modern, lightweight VNC client library for React, Next.js, Node.js, and Bun with TypeScript support

import React$1 from 'react';

interface VNCClientOptions {
    /** WebSocket URL to VNC server */
    url: string;
    /** Username for authentication */
    username?: string;
    /** Password for authentication */
    password?: string;
    /** Enable/disable view only mode */
    viewOnly?: boolean;
    /** Quality setting (0-9, where 9 is best quality) */
    quality?: number;
    /** Compression level (0-9, where 9 is max compression) */
    compression?: number;
    /** Auto-resize canvas to match server resolution */
    autoResize?: boolean;
    /** Scale factor for display (0.1 to 2.0) */
    scale?: number;
    /** Connection timeout in milliseconds */
    timeout?: number;
    /** Enable debug logging */
    debug?: boolean;
}
interface VNCConnectionState {
    connected: boolean;
    connecting: boolean;
    error: string | null;
    serverName: string | null;
    width: number;
    height: number;
}
interface VNCRect {
    x: number;
    y: number;
    width: number;
    height: number;
}
interface VNCPixelFormat {
    bitsPerPixel: number;
    depth: number;
    bigEndian: boolean;
    trueColor: boolean;
    redMax: number;
    greenMax: number;
    blueMax: number;
    redShift: number;
    greenShift: number;
    blueShift: number;
}
interface VNCServerInitMessage {
    width: number;
    height: number;
    pixelFormat: VNCPixelFormat;
    name: string;
}
interface VNCFramebufferUpdate {
    rectangles: VNCRect[];
    imageData?: ImageData;
}
interface VNCKeyEvent {
    key: string;
    code: string;
    down: boolean;
    altKey?: boolean;
    ctrlKey?: boolean;
    shiftKey?: boolean;
    metaKey?: boolean;
}
interface VNCPointerEvent {
    x: number;
    y: number;
    buttons: number;
}
type VNCEventType = 'connecting' | 'connected' | 'disconnected' | 'error' | 'framebuffer-update' | 'server-cut-text' | 'bell' | 'resize';
interface VNCEvent {
    type: VNCEventType;
    data?: any;
}
type VNCEventHandler = (event: VNCEvent) => void;

declare class VNCClient {
    private ws;
    private options;
    private state;
    private eventHandlers;
    private serverInit;
    private pixelFormat;
    private connectionTimeout;
    private reconnectAttempts;
    private maxReconnectAttempts;
    private vncState;
    constructor(options: VNCClientOptions);
    /**
     * Connect to VNC server
     */
    connect(): Promise<void>;
    /**
     * Validate WebSocket URL
     */
    private isValidWebSocketUrl;
    /**
     * Disconnect from VNC server
     */
    disconnect(): void;
    /**
     * Reset reconnection attempts (useful for manual retry)
     */
    resetReconnectionAttempts(): void;
    /**
     * Send key event
     */
    sendKeyEvent(event: VNCKeyEvent): void;
    /**
     * Send pointer event
     */
    sendPointerEvent(event: VNCPointerEvent): void;
    /**
     * Request framebuffer update
     */
    requestFramebufferUpdate(incremental?: boolean): void;
    /**
     * Get current connection state
     */
    getState(): VNCConnectionState;
    /**
     * Add event listener
     */
    on(event: string, handler: VNCEventHandler): void;
    /**
     * Remove event listener
     */
    off(event: string, handler: VNCEventHandler): void;
    /**
     * Emit event
     */
    private emit;
    /**
     * Update internal state
     */
    private setState;
    /**
     * Setup WebSocket event handlers
     */
    private setupWebSocketHandlers;
    /**
     * Handle successful WebSocket connection
     */
    private handleConnectionOpen;
    /**
     * Handle WebSocket connection close
     */
    private handleConnectionClose;
    /**
     * Handle WebSocket errors
     */
    private handleConnectionError;
    /**
     * Check if we should attempt reconnection
     */
    private shouldAttemptReconnect;
    /**
     * Attempt to reconnect
     */
    private attemptReconnect;
    /**
     * Setup connection timeout
     */
    private setupConnectionTimeout;
    /**
     * Handle VNC protocol version handshake
     */
    private handleProtocolVersion;
    /**
     * Handle server messages based on VNC protocol state
     */
    private handleServerMessage;
    /**
     * Handle version response from server
     */
    private handleVersionResponse;
    /**
     * Handle security types from server
     */
    private handleSecurityResponse;
    /**
     * Handle VNC authentication challenge
     */
    private handleAuthResponse;
    /**
     * Send client init message
     */
    private sendClientInit;
    /**
     * Handle server init message
     */
    private handleServerInit;
    /**
     * Handle VNC protocol messages after connection established
     */
    private handleProtocolMessage;
    /**
     * VNC DES encryption for authentication
     * Based on RFC 6143 with bit reversal fix (Errata ID 4951) and proven VNC implementations
     * Implementation derived from established VNC clients that work with all major VNC servers
     */
    private vncEncrypt;
    /**
     * Proper VNC DES encryption implementation
     * Based on proven VNC implementations and RFC 6143 compliance
     * This implements the actual DES algorithm that VNC servers expect
     */
    private vncDesEncrypt;
    /**
     * Send binary message
     */
    private sendMessage;
    /**
     * Send raw string message as binary data
     */
    private sendRawMessage;
    /**
     * Convert keyboard event to VNC key code
     */
    private keyToVNCKey;
    /**
     * Debug logging
     */
    private log;
    /**
     * Clean up existing connection state without triggering disconnect events
     */
    private cleanupExistingConnection;
}

declare class VNCProtocolUtils {
    /**
     * Convert string to Uint8Array
     */
    static stringToUint8Array(str: string): Uint8Array;
    /**
     * Convert Uint8Array to string
     */
    static uint8ArrayToString(arr: Uint8Array): string;
    /**
     * Read uint8 from buffer at offset
     */
    static readUint8(buffer: ArrayBuffer, offset: number): number;
    /**
     * Read uint16 big endian from buffer at offset
     */
    static readUint16BE(buffer: ArrayBuffer, offset: number): number;
    /**
     * Read uint32 big endian from buffer at offset
     */
    static readUint32BE(buffer: ArrayBuffer, offset: number): number;
    /**
     * Write uint8 to buffer at offset
     */
    static writeUint8(buffer: ArrayBuffer, offset: number, value: number): void;
    /**
     * Write uint16 big endian to buffer at offset
     */
    static writeUint16BE(buffer: ArrayBuffer, offset: number, value: number): void;
    /**
     * Write uint32 big endian to buffer at offset
     */
    static writeUint32BE(buffer: ArrayBuffer, offset: number, value: number): void;
    /**
     * Parse VNC server init message
     */
    static parseServerInit(data: ArrayBuffer): VNCServerInitMessage;
    /**
     * Create client init message
     */
    static createClientInit(shared?: boolean): ArrayBuffer;
    /**
     * Create set pixel format message
     */
    static createSetPixelFormat(pixelFormat: VNCPixelFormat): ArrayBuffer;
    /**
     * Create framebuffer update request
     */
    static createFramebufferUpdateRequest(incremental: boolean, x: number, y: number, width: number, height: number): ArrayBuffer;
    /**
     * Create key event message
     */
    static createKeyEvent(down: boolean, key: number): ArrayBuffer;
    /**
     * Create pointer event message
     */
    static createPointerEvent(buttonMask: number, x: number, y: number): ArrayBuffer;
    /**
     * Get default pixel format (32-bit RGBA)
     */
    static getDefaultPixelFormat(): VNCPixelFormat;
}

interface UseVNCOptions extends VNCClientOptions {
    /** Auto-connect on mount */
    autoConnect?: boolean;
    /** Auto-disconnect on unmount */
    autoDisconnect?: boolean;
}
interface UseVNCReturn {
    /** VNC client instance */
    client: VNCClient | null;
    /** Connection state */
    state: VNCConnectionState;
    /** Connect to VNC server */
    connect: () => Promise<void>;
    /** Disconnect from VNC server */
    disconnect: () => void;
    /** Send key event */
    sendKeyEvent: (event: VNCKeyEvent) => void;
    /** Send pointer event */
    sendPointerEvent: (event: VNCPointerEvent) => void;
    /** Request framebuffer update */
    requestUpdate: (incremental?: boolean) => void;
    /** Canvas ref for rendering */
    canvasRef: React.RefObject<HTMLCanvasElement>;
    /** Error message */
    error: string | null;
    /** Loading state */
    loading: boolean;
}
/**
 * React hook for VNC client functionality
 */
declare function useVNC(options: UseVNCOptions): UseVNCReturn;

interface VNCViewerProps extends UseVNCOptions {
    /** Custom CSS class name */
    className?: string;
    /** Custom styles */
    style?: React$1.CSSProperties;
    /** Show connection status */
    showStatus?: boolean;
    /** Show loading indicator */
    showLoading?: boolean;
    /** Custom loading component */
    loadingComponent?: React$1.ReactNode;
    /** Custom error component */
    errorComponent?: React$1.ReactNode;
    /** Disable keyboard input */
    disableKeyboard?: boolean;
    /** Disable mouse input */
    disableMouse?: boolean;
    /** Handle focus automatically */
    autoFocus?: boolean;
    /** Custom connection button text */
    connectButtonText?: string;
    /** Custom disconnect button text */
    disconnectButtonText?: string;
    /** Show blinking cursor when ready to type */
    showCursor?: boolean;
}
declare const VNCViewer: React$1.FC<VNCViewerProps>;

export { type UseVNCOptions, type UseVNCReturn, VNCClient, type VNCClientOptions, type VNCConnectionState, type VNCEvent, type VNCEventHandler, type VNCEventType, type VNCFramebufferUpdate, type VNCKeyEvent, type VNCPixelFormat, type VNCPointerEvent, VNCProtocolUtils, type VNCRect, type VNCServerInitMessage, VNCViewer, type VNCViewerProps, VNCClient as default, useVNC };