@obra-studio/figma-console-mcp 1.32.0

package/dist/browser/local.js

@@ -0,0 +1,318 @@
+/**
+ * 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 puppeteer from 'puppeteer-core';
+import { createChildLogger } from '../core/logger.js';
+import { extractFileKey } from '../core/figma-api.js';
+const logger = createChildLogger({ component: 'local-browser' });
+/**
+ * Local Browser Manager
+ * Connects to existing Figma Desktop instance via remote debugging port
+ */
+export class LocalBrowserManager {
+    constructor(config) {
+        this.browser = null;
+        this.page = null;
+        this.config = config;
+    }
+    /**
+     * Connect to Figma Desktop via remote debugging port
+     */
+    async launch() {
+        if (this.browser) {
+            logger.info('Browser already connected, reusing instance');
+            return;
+        }
+        const { debugHost, debugPort } = this.config;
+        const browserURL = `http://${debugHost}:${debugPort}`;
+        logger.info({ browserURL }, 'Connecting to Figma Desktop');
+        try {
+            // Connect to existing browser (Figma Desktop)
+            this.browser = await puppeteer.connect({
+                browserURL,
+                defaultViewport: null, // Use Figma's viewport
+            });
+            logger.info('Connected to Figma Desktop successfully');
+            // Handle disconnection
+            this.browser.on('disconnected', () => {
+                logger.warn('Disconnected from Figma Desktop');
+                this.browser = null;
+                this.page = null;
+            });
+        }
+        catch (error) {
+            logger.error({ error, browserURL }, 'Failed to connect to Figma Desktop');
+            throw new Error(`Failed to connect to Figma Desktop.\n\n` +
+                `Please open the Desktop Bridge plugin in Figma:\n` +
+                `  Plugins → Development → Figma Desktop Bridge\n\n` +
+                `Error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Find the best page for plugin debugging
+     * Actively searches for pages with workers across ALL tabs
+     */
+    async findBestPage() {
+        if (!this.browser) {
+            return null;
+        }
+        const pages = await this.browser.pages();
+        // Find Figma pages with workers
+        const figmaPages = pages.filter(p => {
+            const url = p.url();
+            return url.includes('figma.com') && !url.includes('devtools');
+        });
+        if (figmaPages.length === 0) {
+            return null;
+        }
+        // Check each page for workers
+        const pagesWithWorkers = figmaPages
+            .map(p => ({
+            page: p,
+            workerCount: p.workers().length,
+            url: p.url()
+        }))
+            .filter(p => p.workerCount > 0)
+            .sort((a, b) => b.workerCount - a.workerCount); // Most workers first
+        if (pagesWithWorkers.length > 0) {
+            logger.info({
+                url: pagesWithWorkers[0].url,
+                workerCount: pagesWithWorkers[0].workerCount,
+                totalPagesWithWorkers: pagesWithWorkers.length
+            }, 'Found page with active plugin workers');
+            return pagesWithWorkers[0].page;
+        }
+        // No workers found - prefer design/file pages
+        const designPage = figmaPages.find(p => p.url().includes('/design/') || p.url().includes('/file/'));
+        return designPage || figmaPages[0];
+    }
+    /**
+     * Find an existing browser tab whose URL matches the given Figma file key
+     */
+    async findPageByFileKey(targetFileKey) {
+        if (!this.browser) {
+            return null;
+        }
+        const pages = await this.browser.pages();
+        for (const page of pages) {
+            const pageUrl = page.url();
+            if (!pageUrl.includes('figma.com') || pageUrl.includes('devtools')) {
+                continue;
+            }
+            const pageFileKey = extractFileKey(pageUrl);
+            if (pageFileKey && pageFileKey === targetFileKey) {
+                logger.info({ url: pageUrl, fileKey: pageFileKey }, 'Found existing tab for file key');
+                return page;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get active Figma page or create new one
+     * Prefers pages with active plugin workers for plugin debugging
+     */
+    async getPage() {
+        // Ensure connection is alive before proceeding
+        await this.ensureConnection();
+        if (!this.browser) {
+            await this.launch();
+        }
+        // If we already have a page from explicit navigation, use it (don't override with findBestPage)
+        if (this.page && !this.page.isClosed()) {
+            return this.page;
+        }
+        // No explicit page set — find the best page (most workers) for initial connection
+        const bestPage = await this.findBestPage();
+        if (bestPage) {
+            const workerCount = bestPage.workers().length;
+            logger.info({
+                url: bestPage.url(),
+                workerCount
+            }, 'Selected page for monitoring (auto-detected)');
+            this.page = bestPage;
+            return this.page;
+        }
+        // Fallback: Get any existing page or create new one
+        const pages = await this.browser.pages();
+        if (pages.length > 0 && pages[0].url() !== 'about:blank') {
+            logger.warn({ url: pages[0].url() }, 'No Figma pages found, using first available page');
+            this.page = pages[0];
+            return this.page;
+        }
+        // Last resort: Create new page
+        logger.warn('No suitable pages found, creating new page in Figma Desktop');
+        this.page = await this.browser.newPage();
+        return this.page;
+    }
+    /**
+     * Navigate to Figma URL
+     * If the target file is already open in a tab, switches to it instead of navigating.
+     */
+    async navigateToFigma(figmaUrl) {
+        // Ensure connection is alive before navigation
+        await this.ensureConnection();
+        // Default to Figma homepage if no URL provided
+        const url = figmaUrl || 'https://www.figma.com';
+        // Check if the target file is already open in an existing tab
+        const targetFileKey = extractFileKey(url);
+        if (targetFileKey) {
+            const existingPage = await this.findPageByFileKey(targetFileKey);
+            if (existingPage) {
+                logger.info({ url, fileKey: targetFileKey }, 'Switching to existing tab instead of navigating');
+                await existingPage.bringToFront();
+                this.page = existingPage;
+                return { page: existingPage, action: 'switched_to_existing', url: existingPage.url() };
+            }
+        }
+        // No existing tab found — fall through to normal navigation
+        const page = await this.getPage();
+        logger.info({ url }, 'Navigating to Figma');
+        try {
+            await page.goto(url, {
+                waitUntil: 'networkidle2',
+                timeout: 30000,
+            });
+            logger.info({ url }, 'Navigation successful');
+            return { page, action: 'navigated', url };
+        }
+        catch (error) {
+            logger.error({ error, url }, 'Navigation failed');
+            throw new Error(`Failed to navigate to ${url}: ${error}`);
+        }
+    }
+    /**
+     * Reload current page
+     */
+    async reload(hardReload = false) {
+        if (!this.page || this.page.isClosed()) {
+            throw new Error('No active page to reload');
+        }
+        logger.info({ hardReload }, 'Reloading page');
+        try {
+            await this.page.reload({
+                waitUntil: 'networkidle2',
+                timeout: 30000,
+            });
+            logger.info('Page reloaded successfully');
+        }
+        catch (error) {
+            logger.error({ error }, 'Page reload failed');
+            throw new Error(`Page reload failed: ${error}`);
+        }
+    }
+    /**
+     * Execute JavaScript in page context
+     */
+    async evaluate(fn) {
+        const page = await this.getPage();
+        return page.evaluate(fn);
+    }
+    // Screenshot functionality removed - use Figma REST API's getImages() instead
+    // See: figma_take_screenshot and figma_get_component_image tools
+    /**
+     * Check if browser is connected
+     */
+    isRunning() {
+        return this.browser !== null && this.browser.isConnected();
+    }
+    /**
+     * Disconnect from browser (doesn't close Figma Desktop)
+     */
+    async close() {
+        if (!this.browser) {
+            return;
+        }
+        logger.info('Disconnecting from Figma Desktop');
+        try {
+            // Just disconnect, don't close Figma Desktop
+            this.browser.disconnect();
+            this.browser = null;
+            this.page = null;
+            logger.info('Disconnected from Figma Desktop successfully');
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to disconnect from browser');
+            throw error;
+        }
+    }
+    /**
+     * Get current page URL
+     */
+    getCurrentUrl() {
+        if (!this.page || this.page.isClosed()) {
+            return null;
+        }
+        return this.page.url();
+    }
+    /**
+     * Check if the browser connection is still alive
+     * Returns false if connection is stale (e.g., after computer sleep)
+     */
+    async isConnectionAlive() {
+        try {
+            if (!this.browser || !this.page) {
+                return false;
+            }
+            // Try to get the page title - this will fail if connection is dead
+            await this.page.title();
+            return true;
+        }
+        catch (error) {
+            logger.warn({ error }, 'Browser connection appears to be dead');
+            return false;
+        }
+    }
+    /**
+     * Reconnect to Figma Desktop if connection was lost
+     * Call this before any operation that requires a live connection
+     */
+    async ensureConnection() {
+        const isAlive = await this.isConnectionAlive();
+        if (!isAlive) {
+            logger.info('Connection lost, attempting to reconnect to Figma Desktop');
+            // Clear stale references
+            this.browser = null;
+            this.page = null;
+            // Reconnect
+            await this.launch();
+            logger.info('Successfully reconnected to Figma Desktop');
+        }
+    }
+    /**
+     * Force a complete reconnection to Figma Desktop
+     * Use this when frames become detached or stale even though the browser appears connected
+     */
+    async forceReconnect() {
+        logger.info('Force reconnecting to Figma Desktop');
+        // Disconnect current connection if exists
+        if (this.browser) {
+            try {
+                this.browser.disconnect();
+            }
+            catch (e) {
+                // Ignore disconnect errors
+            }
+        }
+        // Clear all references
+        this.browser = null;
+        this.page = null;
+        // Reconnect
+        await this.launch();
+        logger.info('Force reconnect completed');
+    }
+    /**
+     * Wait for navigation
+     */
+    async waitForNavigation(timeout = 30000) {
+        if (!this.page || this.page.isClosed()) {
+            throw new Error('No active page');
+        }
+        await this.page.waitForNavigation({
+            waitUntil: 'networkidle2',
+            timeout,
+        });
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/browser/local.js.map

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

package/dist/core/accessibility-tools.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Code-side accessibility scanning via axe-core + JSDOM.
+ *
+ * Delegates all rule logic to axe-core (Deque) — the MCP never owns
+ * a rule database. JSDOM provides a lightweight DOM for structural checks
+ * (~50 rules: ARIA, semantics, alt text, form labels, headings, landmarks).
+ *
+ * Visual rules (color contrast, focus-visible) are NOT available via JSDOM —
+ * those are handled by the design-side figma_lint_design tool.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Extract a CodeSpec.accessibility object from HTML + axe-core results.
+ * This bridges Phase 3 (code scanning) → Phase 4 (parity comparison).
+ *
+ * Parses the HTML to extract semantic element, ARIA attributes, and states.
+ * Uses axe-core results to infer what the code supports.
+ */
+export declare function axeResultsToCodeSpec(html: string, axeResults: any): Record<string, any>;
+export declare function registerAccessibilityTools(server: McpServer): void;
+//# sourceMappingURL=accessibility-tools.d.ts.map

package/dist/core/accessibility-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility-tools.d.ts","sourceRoot":"","sources":["../../src/core/accessibility-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA6FpE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAoGvF;AA+DD,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,SAAS,GACf,IAAI,CAyEN"}

package/dist/core/accessibility-tools.js

@@ -0,0 +1,307 @@
+/**
+ * Code-side accessibility scanning via axe-core + JSDOM.
+ *
+ * Delegates all rule logic to axe-core (Deque) — the MCP never owns
+ * a rule database. JSDOM provides a lightweight DOM for structural checks
+ * (~50 rules: ARIA, semantics, alt text, form labels, headings, landmarks).
+ *
+ * Visual rules (color contrast, focus-visible) are NOT available via JSDOM —
+ * those are handled by the design-side figma_lint_design tool.
+ */
+import { z } from "zod";
+import { logger } from "./logger.js";
+// Lazy-load axe-core and jsdom to keep them optional
+let axeCore = null;
+let JSDOM = null;
+let depsLoaded = false;
+let depsError = null;
+async function loadDeps() {
+    if (depsLoaded)
+        return;
+    try {
+        axeCore = await import("axe-core");
+        // axe-core's default export structure
+        if (axeCore.default)
+            axeCore = axeCore.default;
+        const jsdomModule = await import("jsdom");
+        JSDOM = jsdomModule.JSDOM;
+        depsLoaded = true;
+    }
+    catch (e) {
+        depsError = `axe-core or jsdom not installed. Run: npm install axe-core jsdom\n${e.message}`;
+        throw new Error(depsError);
+    }
+}
+/**
+ * Run axe-core against an HTML string using JSDOM.
+ *
+ * JSDOM limitations: no computed styles, no layout, no visual rendering.
+ * This means ~50-60 structural rules work, but visual rules
+ * (color-contrast, focus-visible, etc.) will report as "incomplete".
+ */
+async function scanHtmlWithAxe(html, options = {}) {
+    await loadDeps();
+    // Wrap HTML fragment in a full document if needed
+    const fullHtml = html.includes("<html") || html.includes("<!DOCTYPE")
+        ? html
+        : `<!DOCTYPE html><html lang="en"><head><title>Scan</title></head><body>${html}</body></html>`;
+    const dom = new JSDOM(fullHtml, {
+        runScripts: "dangerously",
+        pretendToBeVisual: true,
+        url: "http://localhost",
+    });
+    const { document, window } = dom.window;
+    // Inject axe-core into the JSDOM window
+    const axeSource = axeCore.source;
+    const scriptEl = document.createElement("script");
+    scriptEl.textContent = axeSource;
+    document.head.appendChild(scriptEl);
+    // Configure axe run options
+    const runOptions = {};
+    if (options.tags && options.tags.length > 0) {
+        runOptions.runOnly = { type: "tag", values: options.tags };
+    }
+    // Disable rules that require visual rendering (always fail/incomplete in JSDOM)
+    if (options.disableVisualRules !== false) {
+        runOptions.rules = {
+            "color-contrast": { enabled: false },
+            "color-contrast-enhanced": { enabled: false },
+            "link-in-text-block": { enabled: false },
+        };
+    }
+    // Determine scan context
+    const context = options.context || document;
+    try {
+        const results = await window.axe.run(context, runOptions);
+        // Clean up
+        dom.window.close();
+        return results;
+    }
+    catch (err) {
+        dom.window.close();
+        throw new Error(`axe-core scan failed: ${err.message}`);
+    }
+}
+/**
+ * Extract a CodeSpec.accessibility object from HTML + axe-core results.
+ * This bridges Phase 3 (code scanning) → Phase 4 (parity comparison).
+ *
+ * Parses the HTML to extract semantic element, ARIA attributes, and states.
+ * Uses axe-core results to infer what the code supports.
+ */
+export function axeResultsToCodeSpec(html, axeResults) {
+    const spec = {};
+    // Parse HTML to extract attributes (lightweight regex-based, no DOM needed)
+    const htmlLower = html.toLowerCase();
+    // Semantic element: find the root/first meaningful element
+    const rootElementMatch = html.match(/<(button|a|input|select|textarea|details|dialog|nav|main|form|label|fieldset)\b/i);
+    if (rootElementMatch) {
+        spec.semanticElement = rootElementMatch[1].toLowerCase();
+    }
+    else {
+        const firstElementMatch = html.match(/<(\w+)[\s>]/);
+        if (firstElementMatch && !["div", "span", "html", "head", "body", "script", "style", "!doctype"].includes(firstElementMatch[1].toLowerCase())) {
+            spec.semanticElement = firstElementMatch[1].toLowerCase();
+        }
+        else {
+            spec.semanticElement = "div";
+        }
+    }
+    // ARIA role
+    const roleMatch = html.match(/role=["']([^"']+)["']/i);
+    if (roleMatch) {
+        spec.role = roleMatch[1];
+    }
+    // ARIA label
+    const ariaLabelMatch = html.match(/aria-label=["']([^"']+)["']/i);
+    if (ariaLabelMatch) {
+        spec.ariaLabel = ariaLabelMatch[1];
+    }
+    // Focus visible: check for :focus-visible or :focus in inline styles/class names,
+    // or infer from element type (native interactive elements have default focus)
+    const nativeFocusElements = ["button", "a", "input", "select", "textarea"];
+    const hasFocusCSS = /focus-visible|:focus\b|outline.*focus|ring.*focus|focus.*ring/i.test(html);
+    spec.focusVisible = hasFocusCSS || nativeFocusElements.includes(spec.semanticElement || "");
+    // Disabled support: only assert true when we find positive evidence.
+    // Absence of disabled/aria-disabled in a single HTML snapshot does NOT mean
+    // the component lacks disabled support — it may be in a non-disabled state.
+    if (/\bdisabled\b|aria-disabled/i.test(htmlLower)) {
+        spec.supportsDisabled = true;
+    }
+    // (leave undefined when not found — absence ≠ lack of support)
+    // Error support: same principle — only assert true on positive evidence.
+    // A default-state HTML snippet won't have aria-invalid; that doesn't mean
+    // the component can't enter an error state.
+    if (/aria-invalid|aria-errormessage|aria-describedby.*error/i.test(htmlLower)) {
+        spec.supportsError = true;
+    }
+    // (leave undefined when not found — scan a different state to confirm)
+    // Required: check for required or aria-required attributes
+    if (/aria-required=["']true["']|required(?!=)/i.test(html)) {
+        spec.ariaRequired = true;
+    }
+    else if (/aria-required=["']false["']/i.test(html)) {
+        spec.ariaRequired = false;
+    }
+    // Keyboard interactions: infer from element type
+    const keyboardInteractions = [];
+    if (spec.semanticElement === "button" || spec.role === "button") {
+        keyboardInteractions.push("Enter", "Space");
+    }
+    else if (spec.semanticElement === "a" || spec.role === "link") {
+        keyboardInteractions.push("Enter");
+    }
+    else if (spec.semanticElement === "input" || spec.semanticElement === "textarea") {
+        keyboardInteractions.push("Tab (focus)", "Type (input)");
+    }
+    else if (spec.semanticElement === "select" || spec.role === "listbox") {
+        keyboardInteractions.push("Arrow keys", "Enter", "Space");
+    }
+    else if (spec.role === "checkbox" || spec.role === "switch") {
+        keyboardInteractions.push("Space");
+    }
+    else if (spec.role === "tab") {
+        keyboardInteractions.push("Arrow keys");
+    }
+    // Check HTML for custom keyboard handlers
+    if (/onkeydown|onkeyup|onkeypress|@keydown|@keyup|v-on:keydown/i.test(html)) {
+        if (!keyboardInteractions.includes("Custom key handler")) {
+            keyboardInteractions.push("Custom key handler");
+        }
+    }
+    if (keyboardInteractions.length > 0) {
+        spec.keyboardInteractions = keyboardInteractions;
+    }
+    // Use axe-core results to refine: if certain violations exist, it tells us what's missing
+    if (axeResults?.violations) {
+        for (const v of axeResults.violations) {
+            // If button-name violation exists, the button has no accessible name
+            if (v.id === "button-name") {
+                spec.ariaLabel = undefined; // Explicitly missing
+            }
+            // If label violation exists, input lacks a label
+            if (v.id === "label") {
+                spec.ariaLabel = undefined;
+            }
+        }
+    }
+    return spec;
+}
+/**
+ * Format axe-core results into our standard lint-like output structure.
+ */
+function formatAxeResults(axeResults) {
+    const categories = [];
+    const severityMap = {
+        critical: "critical",
+        serious: "critical",
+        moderate: "warning",
+        minor: "info",
+    };
+    // Group violations
+    for (const violation of axeResults.violations || []) {
+        const severity = severityMap[violation.impact] || "warning";
+        const nodes = violation.nodes.map((node) => ({
+            html: node.html?.substring(0, 200),
+            target: node.target,
+            failureSummary: node.failureSummary?.substring(0, 300),
+        }));
+        categories.push({
+            rule: violation.id,
+            severity,
+            count: violation.nodes.length,
+            description: violation.help,
+            wcagTags: violation.tags.filter((t) => t.startsWith("wcag") || t.startsWith("best-practice")),
+            helpUrl: violation.helpUrl,
+            nodes: nodes.slice(0, 10), // Cap at 10 per rule
+        });
+    }
+    // Sort: critical first, then by count
+    categories.sort((a, b) => {
+        const sevOrder = { critical: 0, warning: 1, info: 2 };
+        if (sevOrder[a.severity] !== sevOrder[b.severity]) {
+            return sevOrder[a.severity] - sevOrder[b.severity];
+        }
+        return b.count - a.count;
+    });
+    // Summary
+    const summary = { critical: 0, warning: 0, info: 0, total: 0 };
+    for (const cat of categories) {
+        summary[cat.severity] += cat.count;
+        summary.total += cat.count;
+    }
+    return {
+        engine: "axe-core",
+        version: axeResults.testEngine?.version || "unknown",
+        mode: "jsdom-structural",
+        note: "JSDOM mode: structural/semantic checks only. Visual rules (color contrast, focus visibility) are disabled — use figma_lint_design for visual accessibility checks.",
+        categories,
+        summary,
+        passes: axeResults.passes?.length || 0,
+        incomplete: axeResults.incomplete?.length || 0,
+        inapplicable: axeResults.inapplicable?.length || 0,
+    };
+}
+export function registerAccessibilityTools(server) {
+    server.tool("figma_scan_code_accessibility", "Scan HTML code for accessibility violations using axe-core (Deque). " +
+        "Runs structural/semantic checks via JSDOM: ARIA attributes, roles, labels, alt text, " +
+        "form labels, heading order, landmarks, semantic HTML, tabindex, duplicate IDs, lang attribute, and ~50 more rules. " +
+        "Visual checks (color contrast, focus visibility) are disabled in this mode — use figma_lint_design for visual a11y on the design side. " +
+        "Together, these two tools provide full-spectrum accessibility coverage across design and code. " +
+        "Pass component HTML directly or use with figma_check_design_parity for design-to-code a11y comparison. " +
+        "No Figma connection required — this is a standalone code analysis tool.", {
+        html: z.string().describe("HTML string to scan. Can be a full document or a component fragment (will be wrapped in a valid document)."),
+        tags: z.array(z.string()).optional().describe("WCAG tag filter. Examples: ['wcag2a'], ['wcag2aa'], ['wcag21aa'], ['wcag22aa'], ['best-practice']. " +
+            "Defaults to all structural rules if omitted."),
+        context: z.string().optional().describe("CSS selector to scope the scan to a specific element (e.g., '#my-component', '.card'). Scans entire document if omitted."),
+        includePassingRules: z.boolean().optional().describe("If true, includes count of passing and incomplete rules in the response (default: false)."),
+        mapToCodeSpec: z.boolean().optional().describe("If true, includes a codeSpec.accessibility object auto-extracted from the HTML + scan results. " +
+            "Pass this directly into figma_check_design_parity's codeSpec.accessibility field for automated design-to-code a11y parity checking."),
+    }, async ({ html, tags, context, includePassingRules, mapToCodeSpec }) => {
+        try {
+            const axeResults = await scanHtmlWithAxe(html, {
+                tags: tags || undefined,
+                context: context || undefined,
+            });
+            const formatted = formatAxeResults(axeResults);
+            // Optionally strip pass/incomplete counts to save tokens
+            if (!includePassingRules) {
+                delete formatted.passes;
+                delete formatted.incomplete;
+                delete formatted.inapplicable;
+            }
+            // Auto-generate CodeSpec.accessibility from HTML + results
+            if (mapToCodeSpec) {
+                formatted.codeSpecAccessibility = axeResultsToCodeSpec(html, axeResults);
+                formatted.codeSpecAccessibility._usage = "Pass this object as codeSpec.accessibility in figma_check_design_parity for automated a11y parity checking.";
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(formatted, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const isDepsError = error.message?.includes("not installed");
+            logger.error({ error }, "Failed to scan code accessibility");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error.message,
+                            hint: isDepsError
+                                ? "Install dependencies: npm install axe-core jsdom"
+                                : "Check that the HTML is valid. For visual accessibility checks, use figma_lint_design instead.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=accessibility-tools.js.map