@muloka/figma-console-mcp 0.1.0

package/dist/core/websocket-server.d.ts

@@ -0,0 +1,290 @@
+/**
+ * WebSocket Bridge Server (Multi-Client)
+ *
+ * Creates a WebSocket server that multiple Desktop Bridge plugin instances connect to.
+ * Each instance represents a different Figma file and is identified by its fileKey
+ * (sent via FILE_INFO on connection). Per-file state (selection, document changes,
+ * console logs) is maintained independently.
+ *
+ * Active file tracking: The "active" file is automatically switched when the user
+ * interacts with a file (selection/page changes) or can be set explicitly via
+ * setActiveFile(). All backward-compatible getters return data from the active file.
+ *
+ * Data flow: MCP Server ←WebSocket→ ui.html ←postMessage→ code.js ←figma.*→ Figma
+ */
+import { WebSocket } from 'ws';
+import { EventEmitter } from 'events';
+import type { ConsoleLogEntry } from './types/index.js';
+/**
+ * Extract the PLUGIN_VERSION constant from figma-desktop-bridge/code.js source.
+ * Returns null when the constant is absent or malformed.
+ */
+export declare function parseBundledPluginVersion(codeJsSource: string): string | null;
+/** Version of the plugin files bundled with this server (what a re-import installs). */
+export declare function getBundledPluginVersion(): string;
+/**
+ * A plugin needs re-importing when it reports no version (predates version
+ * reporting) or a version different from the plugin files this server ships.
+ * The server's own package version is irrelevant here.
+ */
+export declare function computePluginUpdateAvailable(pluginVersion: string | null, bundledPluginVersion: string): boolean;
+export interface WebSocketServerOptions {
+    port: number;
+    host?: string;
+    /**
+     * Version of the plugin files shipped with this server, used for the
+     * FILE_INFO version handshake. Defaults to the PLUGIN_VERSION parsed from
+     * the packaged figma-desktop-bridge/code.js. Overridable for tests.
+     */
+    bundledPluginVersion?: string;
+}
+export interface ConnectedFileInfo {
+    fileName: string;
+    fileKey: string | null;
+    currentPage?: string;
+    currentPageId?: string;
+    editorType?: 'figma' | 'figjam' | 'dev';
+    connectedAt: number;
+    /** Version reported by the imported plugin's code.js (FILE_INFO). Null when the plugin predates version reporting. */
+    pluginVersion?: string | null;
+    /** True when the imported plugin's version differs from the plugin files bundled with this server — the user should re-import manifest.json. */
+    pluginUpdateAvailable?: boolean;
+}
+export interface SelectionInfo {
+    nodes: Array<{
+        id: string;
+        name: string;
+        type: string;
+        width?: number;
+        height?: number;
+    }>;
+    count: number;
+    page: string;
+    timestamp: number;
+}
+export interface DocumentChangeEntry {
+    hasStyleChanges: boolean;
+    hasNodeChanges: boolean;
+    changedNodeIds: string[];
+    changeCount: number;
+    timestamp: number;
+}
+/**
+ * v1.25.0: A single metadata-only change captured by the plugin and forwarded
+ * over the WebSocket. Tracks the two fields Figma REST never exposes in version
+ * snapshots — `description` and `annotations` — so `figma_diff_versions` can
+ * surface them by correlating buffer entries to the diff time window.
+ *
+ * The plugin captures these on `figma.on('documentchange')` when a PROPERTY_CHANGE
+ * touches one of those fields. Only the NEW value is captured (Figma's event
+ * doesn't include before/after). The diff engine treats the from-version's
+ * value as "whatever it was at the start of the window" — buffer entries
+ * within the window are interpreted as "during this version range, the field
+ * was edited; final value at end of window is shown."
+ */
+export interface MetadataChangeEntry {
+    node_id: string;
+    node_name: string | null;
+    node_type: string | null;
+    field: 'description' | 'annotations';
+    new_value: any;
+    timestamp: number;
+}
+/**
+ * Per-file client connection state.
+ * Each Figma file with the Desktop Bridge plugin open gets its own ClientConnection.
+ */
+export interface ClientConnection {
+    ws: WebSocket;
+    fileInfo: ConnectedFileInfo;
+    selection: SelectionInfo | null;
+    documentChanges: DocumentChangeEntry[];
+    /** v1.25.0: per-file ring buffer of description/annotation change events */
+    metadataChanges: MetadataChangeEntry[];
+    consoleLogs: ConsoleLogEntry[];
+    lastActivity: number;
+    lastPongAt: number;
+    gracePeriodTimer: ReturnType<typeof setTimeout> | null;
+}
+export declare class FigmaWebSocketServer extends EventEmitter {
+    private wss;
+    private httpServer;
+    /** Named clients indexed by fileKey — each represents a connected Figma file */
+    private clients;
+    /** Clients awaiting FILE_INFO identification, mapped to their pending timeout */
+    private _pendingClients;
+    /** The fileKey of the currently active (targeted) file */
+    private _activeFileKey;
+    private pendingRequests;
+    private requestIdCounter;
+    private options;
+    private _isStarted;
+    private _startedAt;
+    private consoleBufferSize;
+    private documentChangeBufferSize;
+    /** Heartbeat interval for detecting dead connections via ping/pong */
+    private _heartbeatInterval;
+    constructor(options: WebSocketServerOptions);
+    /**
+     * Handle HTTP requests on the same port as WebSocket.
+     * Serves a JSON `/health` (also at `/`) endpoint with version and connected-file
+     * info. No plugin-UI route exists — the plugin loads its own `ui.html` from disk
+     * via the Figma plugin runtime; the legacy `/plugin/ui` bootloader endpoint was
+     * removed in the Phase 3 cleanup.
+     */
+    private handleHttpRequest;
+    /**
+     * Start the HTTP + WebSocket server.
+     * HTTP serves the plugin UI content; WebSocket handles plugin communication.
+     */
+    start(): Promise<void>;
+    /**
+     * Find a named client connection by its WebSocket reference
+     */
+    private findClientByWs;
+    /**
+     * Handle incoming message from a plugin UI WebSocket connection
+     */
+    private handleMessage;
+    /**
+     * Handle FILE_INFO message — promotes pending clients to named clients.
+     * This is the critical multi-client identification step: each plugin reports
+     * its fileKey on connect, allowing the server to track multiple files.
+     */
+    private handleFileInfo;
+    /**
+     * Handle a client WebSocket disconnecting.
+     * Starts a grace period before removing the client to allow reconnection.
+     */
+    private handleClientDisconnect;
+    /**
+     * Send a command to a plugin UI and wait for the response.
+     * By default targets the active file. Pass targetFileKey to target a specific file.
+     */
+    sendCommand(method: string, params?: Record<string, any>, timeoutMs?: number, targetFileKey?: string): Promise<any>;
+    /**
+     * Start the heartbeat interval that pings all connected clients every 30s.
+     * Detects silently dropped connections (e.g., macOS sleep, network change)
+     * that the OS TCP keepalive would take 30-120s to catch.
+     * Browser WebSocket clients auto-respond to pings per RFC 6455.
+     */
+    private startHeartbeat;
+    /**
+     * Check if any named client is connected (transport availability check).
+     * Checks both socket readyState and heartbeat pong freshness to avoid
+     * reporting phantom-connected state on silently dropped connections.
+     */
+    isClientConnected(): boolean;
+    /**
+     * Whether the server has been started
+     */
+    isStarted(): boolean;
+    /**
+     * Get the bound address info (port, host, family).
+     * Only available after the server has started listening.
+     * Returns the actual port — critical when using port 0 for OS-assigned ports.
+     */
+    address(): import('net').AddressInfo | null;
+    /**
+     * Get info about the currently active Figma file.
+     * Returns null if no file is active or connected.
+     */
+    getConnectedFileInfo(): ConnectedFileInfo | null;
+    /**
+     * Get the current user selection in the active Figma file
+     */
+    getCurrentSelection(): SelectionInfo | null;
+    /**
+     * Get buffered document change events from the active file
+     */
+    getDocumentChanges(options?: {
+        count?: number;
+        since?: number;
+    }): DocumentChangeEntry[];
+    /**
+     * Clear document change buffer for the active file
+     */
+    clearDocumentChanges(): number;
+    /**
+     * v1.25.0: Get buffered description/annotation change events for a file.
+     *
+     * Used by `figma_diff_versions` to surface changes that Figma REST doesn't
+     * expose. The diff engine passes a time window (from-version → to-version
+     * `last_modified` timestamps converted to Unix ms) and optional scoping by
+     * node IDs.
+     *
+     * Defaults to the active file if `fileKey` is omitted.
+     */
+    getMetadataChanges(options?: {
+        fileKey?: string;
+        since?: number;
+        until?: number;
+        nodeIds?: string[];
+    }): MetadataChangeEntry[];
+    /**
+     * v1.25.0: Clear metadata-change buffer for the active file.
+     */
+    clearMetadataChanges(): number;
+    /**
+     * Get console logs from the active file with optional filtering
+     */
+    getConsoleLogs(options?: {
+        count?: number;
+        level?: ConsoleLogEntry['level'] | 'all';
+        since?: number;
+    }): ConsoleLogEntry[];
+    /**
+     * Clear console log buffer for the active file
+     */
+    clearConsoleLogs(): number;
+    /**
+     * Get console monitoring status for the active file
+     */
+    getConsoleStatus(): {
+        isMonitoring: boolean;
+        anyClientConnected: boolean;
+        logCount: number;
+        bufferSize: number;
+        workerCount: number;
+        oldestTimestamp: number;
+        newestTimestamp: number;
+    };
+    /**
+     * Get info about all connected Figma files.
+     * Returns an array of ConnectedFileInfo for each file with an active WebSocket.
+     */
+    getConnectedFiles(): (ConnectedFileInfo & {
+        isActive: boolean;
+    })[];
+    /**
+     * Get the last pong timestamp for the active client.
+     * Returns null if no active client or no pong received yet.
+     */
+    getActiveClientLastPongAt(): number | null;
+    /**
+     * Set the active file by fileKey. Returns true if the file is connected.
+     */
+    setActiveFile(fileKey: string): boolean;
+    /**
+     * Get the currently active file's key
+     */
+    getActiveFileKey(): string | null;
+    /**
+     * Get the editor type of the currently active file.
+     * Returns 'figma' if no file is connected or editorType wasn't reported.
+     */
+    getEditorType(): 'figma' | 'figjam' | 'dev';
+    /**
+     * Reject pending requests that were sent to a specific file
+     */
+    private rejectPendingRequestsForFile;
+    /**
+     * Reject all pending requests (used during shutdown)
+     */
+    private rejectPendingRequests;
+    /**
+     * Stop the server and clean up all connections
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=websocket-server.d.ts.map

package/dist/core/websocket-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-server.d.ts","sourceRoot":"","sources":["../../src/core/websocket-server.ts"],"names":[],"mappings":"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"}