@mp3wizard/figma-console-mcp 1.14.0

package/dist/apps/design-system-dashboard/server.js

@@ -0,0 +1,160 @@
+/**
+ * Design System Dashboard MCP App - Server Registration
+ *
+ * Registers tools and resource for the Design System Dashboard MCP App.
+ * Uses the official @modelcontextprotocol/ext-apps helpers for proper
+ * MCP Apps protocol compatibility with Claude Desktop.
+ *
+ * Data flow:
+ *   1. LLM calls figma_audit_design_system → server fetches + scores data,
+ *      returns SHORT summary to LLM (avoids context exhaustion)
+ *   2. UI opens, connects, calls ds_dashboard_refresh (app-only visibility)
+ *   3. ds_dashboard_refresh returns full JSON → UI renders
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { scoreDesignSystem } from "./scoring/engine.js";
+const DASHBOARD_URI = "ui://figma-console/design-system-dashboard";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Shared state
+let lastFileUrl;
+/**
+ * Register the Design System Dashboard MCP App with the server.
+ *
+ * @param server - The MCP server instance
+ * @param getDesignSystemData - Function to fetch raw design system data from Figma
+ * @param getCurrentUrl - Optional function to get the current browser URL (for lastFileUrl tracking)
+ */
+export function registerDesignSystemDashboardApp(server, getDesignSystemData, getCurrentUrl) {
+    // Tool: fetches + scores data, returns SHORT summary to LLM
+    registerAppTool(server, "figma_audit_design_system", {
+        title: "Audit Design System Health",
+        description: "Analyze the health and AI-readiness of a Figma file's design system. Produces a scored dashboard evaluating naming conventions, token architecture, component metadata, accessibility, consistency, and coverage. Results are displayed in the dashboard UI.",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL. If not provided, uses the currently active file."),
+        },
+        _meta: {
+            ui: { resourceUri: DASHBOARD_URI },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            // Track the actual URL used (explicit or current browser URL)
+            // This ensures ds_dashboard_refresh uses the correct file
+            lastFileUrl = fileUrl || getCurrentUrl?.() || undefined;
+            const data = await getDesignSystemData(fileUrl);
+            const scored = scoreDesignSystem(data);
+            const categorySummaries = scored.categories
+                .map((c) => `${c.label}: ${c.score}/100`)
+                .join(", ");
+            const fileName = scored.fileInfo?.name || "Unknown file";
+            const unavailableNote = scored.dataAvailability && !scored.dataAvailability.variables
+                ? " Note: Variable/token data was unavailable (requires Enterprise plan or Desktop Bridge). Token Architecture scores reflect missing data, not actual quality."
+                : "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Design System: ${fileName}. Health: ${scored.overall}/100 — ${scored.status}. ${categorySummaries}.${unavailableNote} The dashboard UI is now showing detailed results.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Design System Dashboard error: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: returns full JSON data (app-only, hidden from LLM)
+    registerAppTool(server, "ds_dashboard_refresh", {
+        title: "Dashboard Refresh",
+        description: "Refresh dashboard data (called from MCP App UI)",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL to refresh data for."),
+        },
+        _meta: {
+            ui: {
+                resourceUri: DASHBOARD_URI,
+                visibility: ["app"],
+            },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            const url = fileUrl || lastFileUrl;
+            const data = await getDesignSystemData(url);
+            const scored = scoreDesignSystem(data);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(scored),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            overall: 0,
+                            status: "poor",
+                            categories: [],
+                            summary: [],
+                            meta: {
+                                componentCount: 0,
+                                variableCount: 0,
+                                collectionCount: 0,
+                                styleCount: 0,
+                                componentSetCount: 0,
+                                standaloneCount: 0,
+                                variantCount: 0,
+                                timestamp: Date.now(),
+                            },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Resource: serves the Vite-built HTML
+    registerAppResource(server, "Design System Dashboard App", DASHBOARD_URI, {
+        description: "Interactive dashboard for evaluating design system health and AI-readiness",
+    }, async () => {
+        const htmlPath = resolve(__dirname, "mcp-app.html");
+        const html = await readFile(htmlPath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: DASHBOARD_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/apps/design-system-dashboard/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/apps/design-system-dashboard/server.ts"],"names":[],"mappings":"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"}

package/dist/apps/token-browser/server.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Token Browser MCP App - Server Registration
+ *
+ * Registers tools and resource for the Token Browser MCP App.
+ * Uses the official @modelcontextprotocol/ext-apps helpers for proper
+ * MCP Apps protocol compatibility with Claude Desktop.
+ *
+ * Data flow:
+ *   1. LLM calls figma_browse_tokens → server fetches + caches data,
+ *      returns SHORT summary to LLM (avoids context exhaustion)
+ *   2. UI opens, connects, calls token_browser_refresh (app-only visibility)
+ *   3. token_browser_refresh returns full JSON → UI renders
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register the Token Browser MCP App with the server.
+ *
+ * @param server - The MCP server instance
+ * @param getVariablesHandler - Function to fetch variables data
+ */
+export declare function registerTokenBrowserApp(server: McpServer, getVariablesHandler: (fileUrl?: string) => Promise<{
+    variables: any[];
+    collections: any[];
+    [key: string]: any;
+}>): void;
+//# sourceMappingURL=server.d.ts.map

package/dist/apps/token-browser/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/apps/token-browser/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQzE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAClD,SAAS,EAAE,GAAG,EAAE,CAAC;IACjB,WAAW,EAAE,GAAG,EAAE,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB,CAAC,GACA,IAAI,CAwIN"}

package/dist/apps/token-browser/server.js

@@ -0,0 +1,137 @@
+/**
+ * Token Browser MCP App - Server Registration
+ *
+ * Registers tools and resource for the Token Browser MCP App.
+ * Uses the official @modelcontextprotocol/ext-apps helpers for proper
+ * MCP Apps protocol compatibility with Claude Desktop.
+ *
+ * Data flow:
+ *   1. LLM calls figma_browse_tokens → server fetches + caches data,
+ *      returns SHORT summary to LLM (avoids context exhaustion)
+ *   2. UI opens, connects, calls token_browser_refresh (app-only visibility)
+ *   3. token_browser_refresh returns full JSON → UI renders
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+const TOKEN_BROWSER_URI = "ui://figma-console/token-browser";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Register the Token Browser MCP App with the server.
+ *
+ * @param server - The MCP server instance
+ * @param getVariablesHandler - Function to fetch variables data
+ */
+export function registerTokenBrowserApp(server, getVariablesHandler) {
+    // Shared state: remember last URL so refresh tool can reuse it
+    let lastFileUrl;
+    // Tool: fetches + caches data, returns SHORT summary to LLM
+    registerAppTool(server, "figma_browse_tokens", {
+        title: "Browse Design Tokens",
+        description: "Open an interactive browser to explore design tokens (variables) from a Figma file. Shows tokens organized by collection with search, filtering, and mode switching. Data is displayed in the UI — do not attempt to list or describe the tokens in chat.",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL. If not provided, uses the currently active file."),
+        },
+        _meta: {
+            ui: { resourceUri: TOKEN_BROWSER_URI },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            lastFileUrl = fileUrl;
+            const result = await getVariablesHandler(fileUrl);
+            const varCount = result.variables?.length || 0;
+            const colCount = result.collections?.length || 0;
+            // Count by type
+            const colors = result.variables?.filter((v) => v.resolvedType === "COLOR")
+                .length || 0;
+            const numbers = result.variables?.filter((v) => v.resolvedType === "FLOAT")
+                .length || 0;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Token Browser opened: ${varCount} tokens across ${colCount} collections (${colors} colors, ${numbers} numbers). The interactive UI is now displaying the results — users can search, filter by type, and browse by collection.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Token Browser error: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: returns full JSON data (app-only, hidden from LLM)
+    registerAppTool(server, "token_browser_refresh", {
+        title: "Token Browser Refresh",
+        description: "Refresh token data (called from MCP App UI)",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL to refresh data for."),
+        },
+        _meta: {
+            ui: {
+                resourceUri: TOKEN_BROWSER_URI,
+                visibility: ["app"],
+            },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            const url = fileUrl || lastFileUrl;
+            const result = await getVariablesHandler(url);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            variables: [],
+                            collections: [],
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Resource: serves the Vite-built HTML
+    registerAppResource(server, "Token Browser App", TOKEN_BROWSER_URI, {
+        description: "Interactive browser for exploring Figma design tokens and variables",
+    }, async () => {
+        const htmlPath = resolve(__dirname, "mcp-app.html");
+        const html = await readFile(htmlPath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: TOKEN_BROWSER_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/apps/token-browser/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/apps/token-browser/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,GACf,MAAM,uCAAuC,CAAC;AAE/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,iBAAiB,GAAG,kCAAkC,CAAC;AAE7D,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACtC,MAAiB,EACjB,mBAIE;IAEF,+DAA+D;IAC/D,IAAI,WAA+B,CAAC;IAEpC,4DAA4D;IAC5D,eAAe,CACd,MAAM,EACN,qBAAqB,EACrB;QACC,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EACV,2PAA2P;QAC5P,WAAW,EAAE;YACZ,OAAO,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,QAAQ,EAAE;iBACV,QAAQ,CACR,kEAAkE,CAClE;SACF;QACD,KAAK,EAAE;YACN,EAAE,EAAE,EAAE,WAAW,EAAE,iBAAiB,EAAE;SACtC;KACD,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACrB,IAAI,CAAC;YACJ,WAAW,GAAG,OAAO,CAAC;YACtB,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;YAElD,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC;YAC/C,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,CAAC;YAEjD,gBAAgB;YAChB,MAAM,MAAM,GACX,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,OAAO,CAAC;iBAC9D,MAAM,IAAI,CAAC,CAAC;YACf,MAAM,OAAO,GACZ,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,OAAO,CAAC;iBAC9D,MAAM,IAAI,CAAC,CAAC;YAEf,OAAO;gBACN,OAAO,EAAE;oBACR;wBACC,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,yBAAyB,QAAQ,kBAAkB,QAAQ,iBAAiB,MAAM,YAAY,OAAO,2HAA2H;qBACtO;iBACD;aACD,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,YAAY,GACjB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACxD,OAAO;gBACN,OAAO,EAAE;oBACR;wBACC,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,wBAAwB,YAAY,EAAE;qBAC5C;iBACD;gBACD,OAAO,EAAE,IAAI;aACb,CAAC;QACH,CAAC;IACF,CAAC,CACD,CAAC;IAEF,2DAA2D;IAC3D,eAAe,CACd,MAAM,EACN,uBAAuB,EACvB;QACC,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,6CAA6C;QAC1D,WAAW,EAAE;YACZ,OAAO,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,QAAQ,EAAE;iBACV,QAAQ,CAAC,qCAAqC,CAAC;SACjD;QACD,KAAK,EAAE;YACN,EAAE,EAAE;gBACH,WAAW,EAAE,iBAAiB;gBAC9B,UAAU,EAAE,CAAC,KAAK,CAAC;aACnB;SACD;KACD,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACrB,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,OAAO,IAAI,WAAW,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,GAAG,CAAC,CAAC;YAC9C,OAAO;gBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;aAClE,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,YAAY,GACjB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACxD,OAAO;gBACN,OAAO,EAAE;oBACR;wBACC,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACpB,KAAK,EAAE,YAAY;4BACnB,SAAS,EAAE,EAAE;4BACb,WAAW,EAAE,EAAE;yBACf,CAAC;qBACF;iBACD;gBACD,OAAO,EAAE,IAAI;aACb,CAAC;QACH,CAAC;IACF,CAAC,CACD,CAAC;IAEF,uCAAuC;IACvC,mBAAmB,CAClB,MAAM,EACN,mBAAmB,EACnB,iBAAiB,EACjB;QACC,WAAW,EACV,qEAAqE;KACtE,EACD,KAAK,IAAI,EAAE;QACV,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACpD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO;YACN,QAAQ,EAAE;gBACT;oBACC,GAAG,EAAE,iBAAiB;oBACtB,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI;iBACV;aACD;SACD,CAAC;IACH,CAAC,CACD,CAAC;AACH,CAAC"}

package/dist/browser/base.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Browser Manager Interface
+ * Abstract interface for browser automation across different runtimes
+ */
+/**
+ * Result of a navigateToFigma call indicating what action was taken
+ */
+export interface NavigationResult {
+    page: any;
+    action: 'switched_to_existing' | 'navigated';
+    url: string;
+}
+/**
+ * Browser Manager Interface
+ * Provides unified API for browser automation regardless of runtime (Cloudflare/Local)
+ *
+ * Note: Uses 'any' for Page type to support both puppeteer-core and @cloudflare/puppeteer
+ * implementations which have incompatible type definitions but compatible runtime behavior
+ */
+export interface IBrowserManager {
+    /**
+     * Launch or connect to browser instance
+     */
+    launch(): Promise<void>;
+    /**
+     * Get active page instance
+     */
+    getPage(): Promise<any>;
+    /**
+     * Navigate to Figma URL
+     */
+    navigateToFigma(url?: string): Promise<NavigationResult>;
+    /**
+     * Reload current page
+     */
+    reload(hardReload?: boolean): Promise<void>;
+    /**
+     * Evaluate JavaScript in page context
+     */
+    evaluate<T>(fn: () => T): Promise<T>;
+    /**
+     * Check if browser is running
+     */
+    isRunning(): boolean;
+    /**
+     * Close browser instance
+     */
+    close(): Promise<void>;
+    /**
+     * Get current URL
+     */
+    getCurrentUrl(): string | null;
+    /**
+     * Wait for navigation to complete
+     */
+    waitForNavigation(timeout?: number): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/browser/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/browser/base.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,GAAG,CAAC;IACV,MAAM,EAAE,sBAAsB,GAAG,WAAW,CAAC;IAC7C,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;IAExB;;OAEG;IACH,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEzD;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAKrC;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/browser/base.js

@@ -0,0 +1,6 @@
+/**
+ * Browser Manager Interface
+ * Abstract interface for browser automation across different runtimes
+ */
+export {};
+//# sourceMappingURL=base.js.map

package/dist/browser/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/browser/base.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/browser/local.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Local Browser Manager (Legacy)
+ * Note: This module is maintained for backwards compatibility but is no longer
+ * the primary connection method. Use the WebSocket Desktop Bridge plugin instead.
+ */
+import { type Page } from 'puppeteer-core';
+import type { IBrowserManager, NavigationResult } from './base.js';
+/**
+ * Local browser configuration
+ */
+export interface LocalBrowserConfig {
+    debugPort: number;
+    debugHost: string;
+}
+/**
+ * Local Browser Manager
+ * Connects to existing Figma Desktop instance via remote debugging port
+ */
+export declare class LocalBrowserManager implements IBrowserManager {
+    private browser;
+    private page;
+    private config;
+    constructor(config: LocalBrowserConfig);
+    /**
+     * Connect to Figma Desktop via remote debugging port
+     */
+    launch(): Promise<void>;
+    /**
+     * Find the best page for plugin debugging
+     * Actively searches for pages with workers across ALL tabs
+     */
+    private findBestPage;
+    /**
+     * Find an existing browser tab whose URL matches the given Figma file key
+     */
+    private findPageByFileKey;
+    /**
+     * Get active Figma page or create new one
+     * Prefers pages with active plugin workers for plugin debugging
+     */
+    getPage(): Promise<Page>;
+    /**
+     * Navigate to Figma URL
+     * If the target file is already open in a tab, switches to it instead of navigating.
+     */
+    navigateToFigma(figmaUrl?: string): Promise<NavigationResult>;
+    /**
+     * Reload current page
+     */
+    reload(hardReload?: boolean): Promise<void>;
+    /**
+     * Execute JavaScript in page context
+     */
+    evaluate<T>(fn: () => T): Promise<T>;
+    /**
+     * Check if browser is connected
+     */
+    isRunning(): boolean;
+    /**
+     * Disconnect from browser (doesn't close Figma Desktop)
+     */
+    close(): Promise<void>;
+    /**
+     * Get current page URL
+     */
+    getCurrentUrl(): string | null;
+    /**
+     * Check if the browser connection is still alive
+     * Returns false if connection is stale (e.g., after computer sleep)
+     */
+    isConnectionAlive(): Promise<boolean>;
+    /**
+     * Reconnect to Figma Desktop if connection was lost
+     * Call this before any operation that requires a live connection
+     */
+    ensureConnection(): Promise<void>;
+    /**
+     * Force a complete reconnection to Figma Desktop
+     * Use this when frames become detached or stale even though the browser appears connected
+     */
+    forceReconnect(): Promise<void>;
+    /**
+     * Wait for navigation
+     */
+    waitForNavigation(timeout?: number): Promise<void>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/browser/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/browser/local.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAkB,EAAgB,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGpE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAInE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAC1D,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAqB;gBAEvB,MAAM,EAAE,kBAAkB;IAItC;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAuC7B;;;OAGG;YACW,YAAY;IA4C1B;;OAEG;YACW,iBAAiB;IAuB/B;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;;OAGG;IACG,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsCnE;;OAEG;IACG,MAAM,CAAC,UAAU,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB/C;;OAEG;IACG,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ1C;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;OAEG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAQ9B;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC;IAe3C;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBvC;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBrC;;OAEG;IACG,iBAAiB,CAAC,OAAO,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAUvD"}