@jay-framework/editor-client 0.6.0

package/dist/index.cjs

@@ -0,0 +1,247 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const socket_ioClient = require("socket.io-client");
+const uuid = require("uuid");
+const editorProtocol = require("@jay-framework/editor-protocol");
+class ConnectionManager {
+  constructor(options = {}) {
+    __publicField(this, "socket", null);
+    __publicField(this, "connectionState", "disconnected");
+    __publicField(this, "portRange");
+    __publicField(this, "scanTimeout");
+    __publicField(this, "retryAttempts");
+    __publicField(this, "editorId");
+    __publicField(this, "autoReconnect");
+    __publicField(this, "reconnectDelay");
+    __publicField(this, "maxReconnectAttempts");
+    __publicField(this, "reconnectAttempts", 0);
+    __publicField(this, "reconnectTimer", null);
+    __publicField(this, "isManualDisconnect", false);
+    __publicField(this, "pendingRequests", /* @__PURE__ */ new Map());
+    this.portRange = options.portRange || [3101, 3200];
+    this.scanTimeout = options.scanTimeout || 5e3;
+    this.retryAttempts = options.retryAttempts || 3;
+    this.editorId = options.editorId || uuid.v4();
+    this.autoReconnect = options.autoReconnect ?? true;
+    this.reconnectDelay = options.reconnectDelay ?? 1e3;
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+  }
+  async connect() {
+    if (this.connectionState === "connected") {
+      return;
+    }
+    this.isManualDisconnect = false;
+    this.reconnectAttempts = 0;
+    this.connectionState = "connecting";
+    try {
+      const serverPort = await this.discoverServer();
+      await this.establishConnection(serverPort);
+      this.connectionState = "connected";
+    } catch (error) {
+      this.connectionState = "error";
+      throw error;
+    }
+  }
+  async disconnect() {
+    this.isManualDisconnect = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+    this.connectionState = "disconnected";
+  }
+  getConnectionState() {
+    return this.connectionState;
+  }
+  async sendMessage(message) {
+    if (this.connectionState !== "connected") {
+      throw new Error("Not connected to editor server");
+    }
+    if (!this.socket) {
+      throw new Error("Not connected to editor server - Socket not available");
+    }
+    return new Promise((resolve, reject) => {
+      const protocolMessage = editorProtocol.createProtocolMessage(message);
+      this.pendingRequests.set(protocolMessage.id, { resolve, reject });
+      setTimeout(() => {
+        if (this.pendingRequests.has(protocolMessage.id)) {
+          this.pendingRequests.delete(protocolMessage.id);
+          reject(new Error("Request timeout"));
+        }
+      }, this.scanTimeout);
+      this.socket.emit("protocol-message", protocolMessage);
+    });
+  }
+  onConnectionStateChange(callback) {
+    const checkState = () => {
+      const currentState = this.getConnectionState();
+      callback(currentState);
+      if (currentState === "disconnected" && this.autoReconnect && !this.isManualDisconnect) {
+        this.attemptReconnect();
+      }
+    };
+    setInterval(checkState, 1e3);
+  }
+  async discoverServer() {
+    const [startPort, endPort] = this.portRange;
+    const ports = Array.from({ length: endPort - startPort + 1 }, (_, i) => startPort + i);
+    for (let attempt = 0; attempt < this.retryAttempts; attempt++) {
+      for (const port of ports) {
+        try {
+          const response = await this.checkPort(port);
+          if (response) {
+            return port;
+          }
+        } catch (error) {
+        }
+      }
+      if (attempt < this.retryAttempts - 1) {
+        await new Promise((resolve) => setTimeout(resolve, 1e3));
+      }
+    }
+    throw new Error(`No editor server found in port range ${startPort}-${endPort}`);
+  }
+  async checkPort(port) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`Port ${port} timeout`));
+      }, this.scanTimeout);
+      const controller = new AbortController();
+      fetch(`http://localhost:${port}/editor-connect?id=${this.editorId}`, {
+        signal: controller.signal
+      }).then((response) => {
+        clearTimeout(timeout);
+        if (response.ok) {
+          return response.json();
+        }
+        throw new Error(`HTTP ${response.status}`);
+      }).then((data) => {
+        if (data.status === "init" || data.id === this.editorId) {
+          resolve(data);
+        } else {
+          resolve(null);
+        }
+      }).catch((error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+  }
+  async establishConnection(port) {
+    return new Promise((resolve, reject) => {
+      this.socket = socket_ioClient.io(`http://localhost:${port}`, {
+        timeout: this.scanTimeout,
+        forceNew: true
+      });
+      this.socket.on("connect", () => {
+        console.log("Connected to editor server");
+        this.setupSocketHandlers();
+        resolve();
+      });
+      this.socket.on("connect_error", (error) => {
+        console.error("Connection error:", error);
+        reject(error);
+      });
+      this.socket.on("disconnect", () => {
+        console.log("Disconnected from editor server");
+        this.connectionState = "disconnected";
+      });
+    });
+  }
+  setupSocketHandlers() {
+    if (!this.socket)
+      return;
+    this.socket.on("protocol-response", (response) => {
+      const pendingRequest = this.pendingRequests.get(response.id);
+      if (pendingRequest) {
+        this.pendingRequests.delete(response.id);
+        if (response.payload.success) {
+          pendingRequest.resolve(response.payload);
+        } else {
+          pendingRequest.reject(new Error(response.payload.error || "Unknown error"));
+        }
+      }
+    });
+  }
+  async attemptReconnect() {
+    if (this.isManualDisconnect || this.reconnectAttempts >= this.maxReconnectAttempts) {
+      return;
+    }
+    this.reconnectAttempts++;
+    console.log(
+      `Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})`
+    );
+    try {
+      await this.connect();
+      this.reconnectAttempts = 0;
+      console.log("Reconnected successfully");
+    } catch (error) {
+      console.error("Reconnection failed:", error);
+      if (this.reconnectAttempts < this.maxReconnectAttempts) {
+        this.reconnectTimer = setTimeout(() => {
+          this.attemptReconnect();
+        }, this.reconnectDelay * this.reconnectAttempts);
+      } else {
+        console.error("Max reconnection attempts reached");
+      }
+    }
+  }
+}
+function createConnectionManager(options) {
+  return new ConnectionManager(options);
+}
+class EditorClient {
+  constructor(connectionManager) {
+    __publicField(this, "connectionManager");
+    this.connectionManager = connectionManager;
+  }
+  // Connection management - delegate to ConnectionManager
+  async connect() {
+    return this.connectionManager.connect();
+  }
+  async disconnect() {
+    return this.connectionManager.disconnect();
+  }
+  getConnectionState() {
+    return this.connectionManager.getConnectionState();
+  }
+  onConnectionStateChange(callback) {
+    return this.connectionManager.onConnectionStateChange(callback);
+  }
+  // EditorProtocol implementation - delegate to ConnectionManager
+  async publish(params) {
+    return this.connectionManager.sendMessage(params);
+  }
+  async saveImage(params) {
+    return this.connectionManager.sendMessage(params);
+  }
+  async hasImage(params) {
+    return this.connectionManager.sendMessage(params);
+  }
+  // Get access to the underlying connection manager if needed
+  getConnectionManager() {
+    return this.connectionManager;
+  }
+}
+function createEditorClient(options) {
+  const connectionManager = new ConnectionManager(options);
+  return new EditorClient(connectionManager);
+}
+function createEditorClientWithConnectionManager(connectionManager) {
+  return new EditorClient(connectionManager);
+}
+exports.ConnectionManager = ConnectionManager;
+exports.EditorClient = EditorClient;
+exports.createConnectionManager = createConnectionManager;
+exports.createEditorClient = createEditorClient;
+exports.createEditorClientWithConnectionManager = createEditorClientWithConnectionManager;

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import * as _jay_framework_editor_protocol from '@jay-framework/editor-protocol';
+import { ConnectionState, PublishMessage, SaveImageMessage, HasImageMessage, PublishResponse, SaveImageResponse, HasImageResponse, EditorProtocol } from '@jay-framework/editor-protocol';
+
+interface ConnectionManagerOptions {
+    portRange?: [number, number];
+    scanTimeout?: number;
+    retryAttempts?: number;
+    editorId?: string;
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    maxReconnectAttempts?: number;
+}
+declare class ConnectionManager {
+    private socket;
+    private connectionState;
+    private portRange;
+    private scanTimeout;
+    private retryAttempts;
+    private editorId;
+    private autoReconnect;
+    private reconnectDelay;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private isManualDisconnect;
+    private pendingRequests;
+    constructor(options?: ConnectionManagerOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnectionState(): ConnectionState;
+    sendMessage<T extends PublishMessage | SaveImageMessage | HasImageMessage>(message: T): Promise<T extends PublishMessage ? PublishResponse : T extends SaveImageMessage ? SaveImageResponse : T extends HasImageMessage ? HasImageResponse : never>;
+    onConnectionStateChange(callback: (state: ConnectionState) => void): void;
+    private discoverServer;
+    private checkPort;
+    private establishConnection;
+    private setupSocketHandlers;
+    private attemptReconnect;
+}
+declare function createConnectionManager(options?: ConnectionManagerOptions): ConnectionManager;
+
+interface EditorClientOptions extends ConnectionManagerOptions {
+}
+declare class EditorClient implements EditorProtocol {
+    private connectionManager;
+    constructor(connectionManager: ConnectionManager);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnectionState(): _jay_framework_editor_protocol.ConnectionState;
+    onConnectionStateChange(callback: (state: any) => void): void;
+    publish(params: PublishMessage): Promise<PublishResponse>;
+    saveImage(params: SaveImageMessage): Promise<SaveImageResponse>;
+    hasImage(params: HasImageMessage): Promise<HasImageResponse>;
+    getConnectionManager(): ConnectionManager;
+}
+declare function createEditorClient(options?: EditorClientOptions): EditorClient;
+declare function createEditorClientWithConnectionManager(connectionManager: ConnectionManager): EditorClient;
+
+export { ConnectionManager, type ConnectionManagerOptions, EditorClient, type EditorClientOptions, createConnectionManager, createEditorClient, createEditorClientWithConnectionManager };

package/dist/index.js

@@ -0,0 +1,247 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+import { io } from "socket.io-client";
+import { v4 } from "uuid";
+import { createProtocolMessage } from "@jay-framework/editor-protocol";
+class ConnectionManager {
+  constructor(options = {}) {
+    __publicField(this, "socket", null);
+    __publicField(this, "connectionState", "disconnected");
+    __publicField(this, "portRange");
+    __publicField(this, "scanTimeout");
+    __publicField(this, "retryAttempts");
+    __publicField(this, "editorId");
+    __publicField(this, "autoReconnect");
+    __publicField(this, "reconnectDelay");
+    __publicField(this, "maxReconnectAttempts");
+    __publicField(this, "reconnectAttempts", 0);
+    __publicField(this, "reconnectTimer", null);
+    __publicField(this, "isManualDisconnect", false);
+    __publicField(this, "pendingRequests", /* @__PURE__ */ new Map());
+    this.portRange = options.portRange || [3101, 3200];
+    this.scanTimeout = options.scanTimeout || 5e3;
+    this.retryAttempts = options.retryAttempts || 3;
+    this.editorId = options.editorId || v4();
+    this.autoReconnect = options.autoReconnect ?? true;
+    this.reconnectDelay = options.reconnectDelay ?? 1e3;
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+  }
+  async connect() {
+    if (this.connectionState === "connected") {
+      return;
+    }
+    this.isManualDisconnect = false;
+    this.reconnectAttempts = 0;
+    this.connectionState = "connecting";
+    try {
+      const serverPort = await this.discoverServer();
+      await this.establishConnection(serverPort);
+      this.connectionState = "connected";
+    } catch (error) {
+      this.connectionState = "error";
+      throw error;
+    }
+  }
+  async disconnect() {
+    this.isManualDisconnect = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+    this.connectionState = "disconnected";
+  }
+  getConnectionState() {
+    return this.connectionState;
+  }
+  async sendMessage(message) {
+    if (this.connectionState !== "connected") {
+      throw new Error("Not connected to editor server");
+    }
+    if (!this.socket) {
+      throw new Error("Not connected to editor server - Socket not available");
+    }
+    return new Promise((resolve, reject) => {
+      const protocolMessage = createProtocolMessage(message);
+      this.pendingRequests.set(protocolMessage.id, { resolve, reject });
+      setTimeout(() => {
+        if (this.pendingRequests.has(protocolMessage.id)) {
+          this.pendingRequests.delete(protocolMessage.id);
+          reject(new Error("Request timeout"));
+        }
+      }, this.scanTimeout);
+      this.socket.emit("protocol-message", protocolMessage);
+    });
+  }
+  onConnectionStateChange(callback) {
+    const checkState = () => {
+      const currentState = this.getConnectionState();
+      callback(currentState);
+      if (currentState === "disconnected" && this.autoReconnect && !this.isManualDisconnect) {
+        this.attemptReconnect();
+      }
+    };
+    setInterval(checkState, 1e3);
+  }
+  async discoverServer() {
+    const [startPort, endPort] = this.portRange;
+    const ports = Array.from({ length: endPort - startPort + 1 }, (_, i) => startPort + i);
+    for (let attempt = 0; attempt < this.retryAttempts; attempt++) {
+      for (const port of ports) {
+        try {
+          const response = await this.checkPort(port);
+          if (response) {
+            return port;
+          }
+        } catch (error) {
+        }
+      }
+      if (attempt < this.retryAttempts - 1) {
+        await new Promise((resolve) => setTimeout(resolve, 1e3));
+      }
+    }
+    throw new Error(`No editor server found in port range ${startPort}-${endPort}`);
+  }
+  async checkPort(port) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`Port ${port} timeout`));
+      }, this.scanTimeout);
+      const controller = new AbortController();
+      fetch(`http://localhost:${port}/editor-connect?id=${this.editorId}`, {
+        signal: controller.signal
+      }).then((response) => {
+        clearTimeout(timeout);
+        if (response.ok) {
+          return response.json();
+        }
+        throw new Error(`HTTP ${response.status}`);
+      }).then((data) => {
+        if (data.status === "init" || data.id === this.editorId) {
+          resolve(data);
+        } else {
+          resolve(null);
+        }
+      }).catch((error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+  }
+  async establishConnection(port) {
+    return new Promise((resolve, reject) => {
+      this.socket = io(`http://localhost:${port}`, {
+        timeout: this.scanTimeout,
+        forceNew: true
+      });
+      this.socket.on("connect", () => {
+        console.log("Connected to editor server");
+        this.setupSocketHandlers();
+        resolve();
+      });
+      this.socket.on("connect_error", (error) => {
+        console.error("Connection error:", error);
+        reject(error);
+      });
+      this.socket.on("disconnect", () => {
+        console.log("Disconnected from editor server");
+        this.connectionState = "disconnected";
+      });
+    });
+  }
+  setupSocketHandlers() {
+    if (!this.socket)
+      return;
+    this.socket.on("protocol-response", (response) => {
+      const pendingRequest = this.pendingRequests.get(response.id);
+      if (pendingRequest) {
+        this.pendingRequests.delete(response.id);
+        if (response.payload.success) {
+          pendingRequest.resolve(response.payload);
+        } else {
+          pendingRequest.reject(new Error(response.payload.error || "Unknown error"));
+        }
+      }
+    });
+  }
+  async attemptReconnect() {
+    if (this.isManualDisconnect || this.reconnectAttempts >= this.maxReconnectAttempts) {
+      return;
+    }
+    this.reconnectAttempts++;
+    console.log(
+      `Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})`
+    );
+    try {
+      await this.connect();
+      this.reconnectAttempts = 0;
+      console.log("Reconnected successfully");
+    } catch (error) {
+      console.error("Reconnection failed:", error);
+      if (this.reconnectAttempts < this.maxReconnectAttempts) {
+        this.reconnectTimer = setTimeout(() => {
+          this.attemptReconnect();
+        }, this.reconnectDelay * this.reconnectAttempts);
+      } else {
+        console.error("Max reconnection attempts reached");
+      }
+    }
+  }
+}
+function createConnectionManager(options) {
+  return new ConnectionManager(options);
+}
+class EditorClient {
+  constructor(connectionManager) {
+    __publicField(this, "connectionManager");
+    this.connectionManager = connectionManager;
+  }
+  // Connection management - delegate to ConnectionManager
+  async connect() {
+    return this.connectionManager.connect();
+  }
+  async disconnect() {
+    return this.connectionManager.disconnect();
+  }
+  getConnectionState() {
+    return this.connectionManager.getConnectionState();
+  }
+  onConnectionStateChange(callback) {
+    return this.connectionManager.onConnectionStateChange(callback);
+  }
+  // EditorProtocol implementation - delegate to ConnectionManager
+  async publish(params) {
+    return this.connectionManager.sendMessage(params);
+  }
+  async saveImage(params) {
+    return this.connectionManager.sendMessage(params);
+  }
+  async hasImage(params) {
+    return this.connectionManager.sendMessage(params);
+  }
+  // Get access to the underlying connection manager if needed
+  getConnectionManager() {
+    return this.connectionManager;
+  }
+}
+function createEditorClient(options) {
+  const connectionManager = new ConnectionManager(options);
+  return new EditorClient(connectionManager);
+}
+function createEditorClientWithConnectionManager(connectionManager) {
+  return new EditorClient(connectionManager);
+}
+export {
+  ConnectionManager,
+  EditorClient,
+  createConnectionManager,
+  createEditorClient,
+  createEditorClientWithConnectionManager
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jay-framework/editor-client",
+  "version": "0.6.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jay-framework/editor-protocol": "^0.6.0",
+    "get-port": "^7.0.0",
+    "socket.io-client": "^4.7.4",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.6.0",
+    "@jay-framework/jay-cli": "^0.6.0",
+    "@types/node": "^22.15.21",
+    "@types/uuid": "^9.0.7",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,181 @@
+# @jay-framework/editor-client
+
+Socket.io client implementation for editor applications to connect to Jay dev servers.
+
+## Overview
+
+This package provides a Socket.io client that can be used by editor applications to connect to Jay dev servers and perform real-time operations. It includes:
+
+- Automatic port discovery and server connection
+- Socket.io client with automatic reconnection
+- Protocol message handling for publish, saveImage, and hasImage operations
+- Connection state management
+- Type-safe protocol implementation with wrapper message structure
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createEditorClient } from '@jay-framework/editor-client';
+
+// Create the editor client
+const client = createEditorClient({
+  portRange: [3101, 3200],
+  scanTimeout: 5000,
+  retryAttempts: 3,
+  editorId: 'my-editor-123',
+});
+
+// Connect to the dev server
+await client.connect();
+
+// Publish a jay-html file
+const result = await client.publish({
+  type: 'publish',
+  pages: [
+    {
+      route: '/pages',
+      jayHtml: '<div>Hello World</div>',
+      name: 'home',
+    },
+  ],
+});
+
+console.log('Published:', result.status[0].filePath);
+```
+
+### Advanced Usage with Custom Connection Manager
+
+```typescript
+import {
+  createEditorClientWithConnectionManager,
+  createConnectionManager,
+} from '@jay-framework/editor-client';
+
+// Create a custom connection manager
+const connectionManager = createConnectionManager({
+  portRange: [3101, 3200],
+  autoReconnect: true,
+  reconnectDelay: 1000,
+  maxReconnectAttempts: 5,
+});
+
+// Create editor client with the connection manager
+const client = createEditorClientWithConnectionManager(connectionManager);
+
+// Connect and handle state changes
+await client.connect();
+
+client.onConnectionStateChange((state) => {
+  console.log('Connection state:', state);
+});
+
+// Use protocol methods
+const imageResult = await client.saveImage({
+  type: 'saveImage',
+  imageId: 'my-image',
+  imageData:
+    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==',
+});
+
+console.log('Image saved:', imageResult.imageUrl);
+```
+
+## Features
+
+### Port Discovery
+
+- Automatically scans port range to find available dev servers
+- Supports both "init" mode and "configured" mode servers
+- Configurable scan timeout and retry attempts
+
+### Protocol Support
+
+- **Publish**: Send jay-html files to the dev server
+- **Save Image**: Upload base64 image data to server assets
+- **Has Image**: Check if an image already exists on the server
+
+### Connection Management
+
+- Automatic reconnection with exponential backoff
+- Connection state monitoring
+- Request timeout handling
+- Error handling and recovery
+
+### Type Safety
+
+- Full TypeScript support with wrapper message structure
+- Protocol interface compliance with `id`, `timestamp`, and `payload` fields
+- Type-safe request/response handling
+
+## Architecture
+
+The package follows a clean separation of concerns:
+
+- **EditorClient**: High-level API that implements the `EditorProtocol` interface
+- **ConnectionManager**: Handles all connection logic, port discovery, and message transport
+
+### Protocol Message Structure
+
+All messages use a wrapper structure:
+
+```typescript
+interface ProtocolMessage {
+  id: string;
+  timestamp: number;
+  payload: {
+    type: 'publish' | 'saveImage' | 'hasImage';
+    // ... message-specific fields
+  };
+}
+```
+
+## Configuration Options
+
+```typescript
+interface ConnectionManagerOptions {
+  portRange?: [number, number]; // Default: [3101, 3200]
+  scanTimeout?: number; // Default: 5000ms
+  retryAttempts?: number; // Default: 3
+  editorId?: string; // Auto-generated UUID if not provided
+  autoReconnect?: boolean; // Default: true
+  reconnectDelay?: number; // Default: 1000ms
+  maxReconnectAttempts?: number; // Default: 5
+}
+```
+
+## Testing
+
+Comprehensive test suite including:
+
+- Unit tests for all components
+- End-to-end tests with real Socket.io servers
+- Multiple server and client scenarios
+- Connection state and error handling tests
+- Protocol message validation
+
+## Integration with Editor Applications
+
+This package is designed to be used by any editor application that needs to communicate with Jay dev servers, such as:
+
+- Figma plugins
+- Web-based editors
+- Desktop applications
+- Browser extensions
+
+interface EditorClientOptions extends ConnectionManagerOptions {
+// Additional editor-specific options can be added here
+}
+
+```
+
+## Integration with Editor Applications
+
+This package is designed to be used by any editor application that needs to communicate with Jay dev servers, such as:
+
+- Figma plugins
+- Web-based editors
+- Desktop applications
+- Browser extensions
+```