electron-dev-bridge 0.1.0

package/dist/cdp-tools/dom-query.js

@@ -0,0 +1,307 @@
+import { toolResult } from './helpers.js';
+export function createDomQueryTools(ctx) {
+    const { bridge } = ctx;
+    return [
+        {
+            definition: {
+                name: 'electron_query_selector',
+                description: 'Find a single DOM element matching a CSS selector. Returns attributes and an HTML preview.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector to match.',
+                        },
+                    },
+                    required: ['selector'],
+                },
+            },
+            handler: async ({ selector }) => {
+                bridge.ensureConnected();
+                const client = bridge.getRawClient();
+                const { root } = await client.DOM.getDocument();
+                const { nodeId } = await client.DOM.querySelector({
+                    nodeId: root.nodeId,
+                    selector,
+                });
+                if (nodeId === 0) {
+                    return toolResult({ found: false });
+                }
+                const { attributes: attrArray } = await client.DOM.getAttributes({ nodeId });
+                const { outerHTML } = await client.DOM.getOuterHTML({ nodeId });
+                const attributes = {};
+                for (let i = 0; i < attrArray.length; i += 2) {
+                    attributes[attrArray[i]] = attrArray[i + 1];
+                }
+                return toolResult({
+                    found: true,
+                    nodeId,
+                    attributes,
+                    outerHTMLPreview: outerHTML.slice(0, 500),
+                });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_query_selector_all',
+                description: 'Find all DOM elements matching a CSS selector. Returns up to 50 elements with HTML previews.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector to match.',
+                        },
+                    },
+                    required: ['selector'],
+                },
+            },
+            handler: async ({ selector }) => {
+                bridge.ensureConnected();
+                const client = bridge.getRawClient();
+                const { root } = await client.DOM.getDocument();
+                const { nodeIds } = await client.DOM.querySelectorAll({
+                    nodeId: root.nodeId,
+                    selector,
+                });
+                const limited = nodeIds.slice(0, 50);
+                const elements = await Promise.all(limited.map(async (nid) => {
+                    const { outerHTML } = await client.DOM.getOuterHTML({ nodeId: nid });
+                    return { nodeId: nid, outerHTMLPreview: outerHTML.slice(0, 500) };
+                }));
+                return toolResult({
+                    count: nodeIds.length,
+                    returned: limited.length,
+                    elements,
+                });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_find_by_text',
+                description: 'Find DOM elements containing specific text content using XPath. Returns up to 50 matches.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        text: {
+                            type: 'string',
+                            description: 'Text content to search for (partial match).',
+                        },
+                        tag: {
+                            type: 'string',
+                            description: 'HTML tag to restrict search to (e.g. "button", "span"). Defaults to "*" (any tag).',
+                        },
+                    },
+                    required: ['text'],
+                },
+            },
+            handler: async ({ text, tag = '*' }) => {
+                bridge.ensureConnected();
+                const safeTag = tag.replace(/[^a-zA-Z0-9*]/g, '') || '*';
+                const safeText = JSON.stringify(text);
+                const result = await bridge.evaluate(`
+          (() => {
+            const results = [];
+            const xpath = '//${safeTag}[contains(text(), ${safeText})]';
+            const snapshot = document.evaluate(
+              xpath, document.body, null,
+              XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null
+            );
+            const count = snapshot.snapshotLength;
+            const limit = Math.min(count, 50);
+            for (let i = 0; i < limit; i++) {
+              const el = snapshot.snapshotItem(i);
+              const rect = el.getBoundingClientRect();
+              results.push({
+                tag: el.tagName.toLowerCase(),
+                textPreview: (el.textContent || '').trim().slice(0, 200),
+                id: el.id || null,
+                className: el.className || null,
+                boundingBox: {
+                  x: rect.x, y: rect.y,
+                  width: rect.width, height: rect.height
+                }
+              });
+            }
+            return { count, elements: results };
+          })()
+        `);
+                return toolResult(result);
+            },
+        },
+        {
+            definition: {
+                name: 'electron_find_by_role',
+                description: 'Find DOM elements by ARIA role (explicit or implicit). Returns up to 50 matches.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        role: {
+                            type: 'string',
+                            description: 'ARIA role to search for (e.g. "button", "link", "textbox", "heading").',
+                        },
+                    },
+                    required: ['role'],
+                },
+            },
+            handler: async ({ role }) => {
+                bridge.ensureConnected();
+                const safeRole = JSON.stringify(role);
+                const result = await bridge.evaluate(`
+          (() => {
+            const IMPLICIT_ROLES = {
+              button: ['button', 'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]', 'summary'],
+              link: ['a[href]', 'area[href]'],
+              textbox: ['input:not([type])', 'input[type="text"]', 'input[type="email"]', 'input[type="tel"]', 'input[type="url"]', 'input[type="search"]', 'input[type="password"]', 'textarea'],
+              checkbox: ['input[type="checkbox"]'],
+              radio: ['input[type="radio"]'],
+              combobox: ['select'],
+              img: ['img[alt]'],
+              heading: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+              list: ['ul', 'ol'],
+              listitem: ['li'],
+              navigation: ['nav'],
+              main: ['main'],
+              banner: ['header'],
+              contentinfo: ['footer'],
+              complementary: ['aside'],
+              form: ['form'],
+              table: ['table'],
+              row: ['tr'],
+              cell: ['td'],
+              columnheader: ['th']
+            };
+
+            const role = ${safeRole};
+            const selectors = ['[role="' + role + '"]'];
+            const implicit = IMPLICIT_ROLES[role];
+            if (implicit) {
+              implicit.forEach(s => selectors.push(s));
+            }
+
+            const combined = selectors.join(', ');
+            const all = document.querySelectorAll(combined);
+            const count = all.length;
+            const limit = Math.min(count, 50);
+            const elements = [];
+
+            for (let i = 0; i < limit; i++) {
+              const el = all[i];
+              const rect = el.getBoundingClientRect();
+              elements.push({
+                role: el.getAttribute('role') || role,
+                text: (el.getAttribute('aria-label') || el.textContent || '').trim().slice(0, 200),
+                id: el.id || null,
+                className: el.className || null,
+                boundingBox: {
+                  x: rect.x, y: rect.y,
+                  width: rect.width, height: rect.height
+                }
+              });
+            }
+
+            return { count, elements };
+          })()
+        `);
+                return toolResult(result);
+            },
+        },
+        {
+            definition: {
+                name: 'electron_get_accessibility_tree',
+                description: 'Get a structured accessibility tree of the current page, including roles, names, and interactive states.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        maxDepth: {
+                            type: 'number',
+                            description: 'Maximum depth to traverse the DOM tree. Defaults to 10.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ maxDepth = 10 } = {}) => {
+                bridge.ensureConnected();
+                const tree = await bridge.evaluate(`
+          (() => {
+            const IMPLICIT_ROLES = {
+              BUTTON: 'button', A: 'link', INPUT: 'textbox', TEXTAREA: 'textbox',
+              SELECT: 'combobox', IMG: 'img', H1: 'heading', H2: 'heading',
+              H3: 'heading', H4: 'heading', H5: 'heading', H6: 'heading',
+              UL: 'list', OL: 'list', LI: 'listitem', NAV: 'navigation',
+              MAIN: 'main', HEADER: 'banner', FOOTER: 'contentinfo',
+              ASIDE: 'complementary', FORM: 'form', TABLE: 'table',
+              TR: 'row', TD: 'cell', TH: 'columnheader', SUMMARY: 'button'
+            };
+
+            function walk(el, depth) {
+              if (depth > ${maxDepth}) return null;
+              if (!el || el.nodeType !== 1) return null;
+
+              const style = window.getComputedStyle(el);
+              if (style.display === 'none' || style.visibility === 'hidden') return null;
+
+              const tag = el.tagName.toLowerCase();
+              const role = el.getAttribute('role') || IMPLICIT_ROLES[el.tagName] || null;
+
+              let name = el.getAttribute('aria-label')
+                || el.getAttribute('alt')
+                || el.getAttribute('title')
+                || el.getAttribute('placeholder');
+
+              if (!name && el.id) {
+                const label = document.querySelector('label[for="' + el.id + '"]');
+                if (label) name = label.textContent.trim();
+              }
+
+              if (!name) {
+                let directText = '';
+                for (const child of el.childNodes) {
+                  if (child.nodeType === 3) directText += child.textContent;
+                }
+                directText = directText.trim();
+                if (directText) name = directText.slice(0, 200);
+              }
+
+              const classes = el.className && typeof el.className === 'string'
+                ? el.className.split(/\\\\s+/).slice(0, 5).join(' ')
+                : null;
+
+              const node = { tag };
+              if (role) node.role = role;
+              if (name) node.name = name;
+              if (el.id) node.id = el.id;
+              if (classes) node.class = classes;
+              if (el.dataset && el.dataset.testid) node.dataTestId = el.dataset.testid;
+
+              if (el.value !== undefined && el.value !== '') node.value = String(el.value).slice(0, 200);
+              if (el.type) node.type = el.type;
+              if (el.href) node.href = el.href;
+              if (el.disabled) node.disabled = true;
+              if (el.checked) node.checked = true;
+              const expanded = el.getAttribute('aria-expanded');
+              if (expanded !== null) node.ariaExpanded = expanded;
+              const selected = el.getAttribute('aria-selected');
+              if (selected !== null) node.ariaSelected = selected;
+              const ariaDisabled = el.getAttribute('aria-disabled');
+              if (ariaDisabled !== null) node.ariaDisabled = ariaDisabled;
+
+              const children = [];
+              for (const child of el.children) {
+                const c = walk(child, depth + 1);
+                if (c) children.push(c);
+              }
+              if (children.length > 0) node.children = children;
+
+              return node;
+            }
+
+            return walk(document.body, 0);
+          })()
+        `);
+                return toolResult(tree);
+            },
+        },
+    ];
+}

package/dist/cdp-tools/helpers.d.ts

@@ -0,0 +1,17 @@
+import type { CdpBridge } from '../server/cdp-bridge.js';
+export declare function toolResult(data: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toolError(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+export declare function getBoundingBox(bridge: CdpBridge, selector: string): Promise<any>;
+export declare function evaluateSelector(bridge: CdpBridge, selector: string, expression: string): Promise<any>;
+export declare function dispatchClick(client: any, x: number, y: number): Promise<void>;

package/dist/cdp-tools/helpers.js

@@ -0,0 +1,48 @@
+export function toolResult(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function toolError(message) {
+    return { content: [{ type: 'text', text: 'Error: ' + message }], isError: true };
+}
+export async function getBoundingBox(bridge, selector) {
+    const box = await bridge.evaluate(`
+    (() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return null;
+      const rect = el.getBoundingClientRect();
+      return {
+        x: rect.x, y: rect.y,
+        width: rect.width, height: rect.height,
+        top: rect.top, right: rect.right,
+        bottom: rect.bottom, left: rect.left
+      };
+    })()
+  `);
+    if (!box) {
+        throw new Error(`Element not found: ${selector}`);
+    }
+    return box;
+}
+export async function evaluateSelector(bridge, selector, expression) {
+    return bridge.evaluate(`
+    (() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) throw new Error('Element not found: ' + ${JSON.stringify(selector)} + '. Check that the selector is correct.');
+      return ${expression};
+    })()
+  `);
+}
+export async function dispatchClick(client, x, y) {
+    await client.Input.dispatchMouseEvent({
+        type: 'mousePressed',
+        x, y,
+        button: 'left',
+        clickCount: 1,
+    });
+    await client.Input.dispatchMouseEvent({
+        type: 'mouseReleased',
+        x, y,
+        button: 'left',
+        clickCount: 1,
+    });
+}

package/dist/cdp-tools/index.d.ts

@@ -0,0 +1,5 @@
+import type { AppConfig, ScreenshotConfig } from '../index.js';
+import type { CdpBridge } from '../server/cdp-bridge.js';
+import type { CdpTool } from './types.js';
+export type { CdpTool, CdpToolDefinition } from './types.js';
+export declare function getCdpTools(bridge: CdpBridge, appConfig: AppConfig, screenshotConfig?: ScreenshotConfig): CdpTool[];

package/dist/cdp-tools/index.js

@@ -0,0 +1,26 @@
+import { createDomQueryTools } from './dom-query.js';
+import { createInteractionTools } from './interaction.js';
+import { createLifecycleTools } from './lifecycle.js';
+import { createNavigationTools } from './navigation.js';
+import { createStateTools } from './state.js';
+import { createVisualTools } from './visual.js';
+export function getCdpTools(bridge, appConfig, screenshotConfig) {
+    const ctx = {
+        bridge,
+        appConfig,
+        screenshotDir: screenshotConfig?.dir || '.screenshots',
+        screenshotFormat: screenshotConfig?.format || 'png',
+        state: {
+            screenshotCounter: 0,
+            electronProcess: null,
+        },
+    };
+    return [
+        ...createLifecycleTools(ctx),
+        ...createDomQueryTools(ctx),
+        ...createInteractionTools(ctx),
+        ...createStateTools(ctx),
+        ...createNavigationTools(ctx),
+        ...createVisualTools(ctx),
+    ];
+}

package/dist/cdp-tools/interaction.d.ts

@@ -0,0 +1,2 @@
+import type { CdpTool, ToolContext } from './types.js';
+export declare function createInteractionTools(ctx: ToolContext): CdpTool[];

package/dist/cdp-tools/interaction.js

@@ -0,0 +1,195 @@
+import { dispatchClick, getBoundingBox, toolResult } from './helpers.js';
+const KEY_MAP = {
+    Enter: { keyCode: 13, code: 'Enter', key: 'Enter', text: '\r' },
+    Tab: { keyCode: 9, code: 'Tab', key: 'Tab' },
+    Escape: { keyCode: 27, code: 'Escape', key: 'Escape' },
+    Backspace: { keyCode: 8, code: 'Backspace', key: 'Backspace' },
+    Delete: { keyCode: 46, code: 'Delete', key: 'Delete' },
+    ArrowUp: { keyCode: 38, code: 'ArrowUp', key: 'ArrowUp' },
+    ArrowDown: { keyCode: 40, code: 'ArrowDown', key: 'ArrowDown' },
+    ArrowLeft: { keyCode: 37, code: 'ArrowLeft', key: 'ArrowLeft' },
+    ArrowRight: { keyCode: 39, code: 'ArrowRight', key: 'ArrowRight' },
+    Home: { keyCode: 36, code: 'Home', key: 'Home' },
+    End: { keyCode: 35, code: 'End', key: 'End' },
+    Space: { keyCode: 32, code: 'Space', key: ' ', text: ' ' },
+};
+export function createInteractionTools(ctx) {
+    const { bridge } = ctx;
+    return [
+        {
+            definition: {
+                name: 'electron_click',
+                description: 'Click on an element by CSS selector or at specific x/y coordinates.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the element to click.',
+                        },
+                        x: {
+                            type: 'number',
+                            description: 'X coordinate to click at (used if no selector).',
+                        },
+                        y: {
+                            type: 'number',
+                            description: 'Y coordinate to click at (used if no selector).',
+                        },
+                    },
+                },
+            },
+            handler: async ({ selector, x, y } = {}) => {
+                bridge.ensureConnected();
+                let clickX;
+                let clickY;
+                if (selector) {
+                    const box = await getBoundingBox(bridge, selector);
+                    clickX = box.x + box.width / 2;
+                    clickY = box.y + box.height / 2;
+                }
+                else if (x !== undefined && y !== undefined) {
+                    clickX = x;
+                    clickY = y;
+                }
+                else {
+                    throw new Error('Provide either a selector or both x and y coordinates to click.');
+                }
+                const client = bridge.getRawClient();
+                await dispatchClick(client, clickX, clickY);
+                return toolResult({ clicked: true, x: clickX, y: clickY });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_type_text',
+                description: 'Type text into the focused element or a specific element (clicks it first if selector provided).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        text: {
+                            type: 'string',
+                            description: 'Text string to type.',
+                        },
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the element to type into. Will be clicked to focus first.',
+                        },
+                    },
+                    required: ['text'],
+                },
+            },
+            handler: async ({ text, selector }) => {
+                bridge.ensureConnected();
+                const client = bridge.getRawClient();
+                if (selector) {
+                    const box = await getBoundingBox(bridge, selector);
+                    await dispatchClick(client, box.x + box.width / 2, box.y + box.height / 2);
+                }
+                for (const char of text) {
+                    await client.Input.dispatchKeyEvent({
+                        type: 'keyDown',
+                        text: char,
+                        key: char,
+                        unmodifiedText: char,
+                    });
+                    await client.Input.dispatchKeyEvent({
+                        type: 'keyUp',
+                        key: char,
+                    });
+                }
+                return toolResult({ typed: true, length: text.length });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_press_key',
+                description: 'Press a special key (Enter, Tab, Escape, arrow keys, etc.).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        key: {
+                            type: 'string',
+                            description: 'Key name: Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, Space.',
+                        },
+                    },
+                    required: ['key'],
+                },
+            },
+            handler: async ({ key }) => {
+                bridge.ensureConnected();
+                const mapped = KEY_MAP[key];
+                if (!mapped) {
+                    throw new Error(`Unsupported key: "${key}". Supported keys: ${Object.keys(KEY_MAP).join(', ')}`);
+                }
+                const downEvent = {
+                    type: 'keyDown',
+                    key: mapped.key,
+                    code: mapped.code,
+                    windowsVirtualKeyCode: mapped.keyCode,
+                    nativeVirtualKeyCode: mapped.keyCode,
+                };
+                if (mapped.text)
+                    downEvent.text = mapped.text;
+                const client = bridge.getRawClient();
+                await client.Input.dispatchKeyEvent(downEvent);
+                await client.Input.dispatchKeyEvent({
+                    type: 'keyUp',
+                    key: mapped.key,
+                    code: mapped.code,
+                    windowsVirtualKeyCode: mapped.keyCode,
+                    nativeVirtualKeyCode: mapped.keyCode,
+                });
+                return toolResult({ pressed: key });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_select_option',
+                description: 'Select an option in a <select> element by value or visible text.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the <select> element.',
+                        },
+                        value: {
+                            type: 'string',
+                            description: 'Option value or visible text to select.',
+                        },
+                    },
+                    required: ['selector', 'value'],
+                },
+            },
+            handler: async ({ selector, value }) => {
+                bridge.ensureConnected();
+                const result = await bridge.evaluate(`
+          (() => {
+            const select = document.querySelector(${JSON.stringify(selector)});
+            if (!select) throw new Error('Select element not found: ' + ${JSON.stringify(selector)});
+            if (select.tagName !== 'SELECT') throw new Error('Element is not a <select>');
+
+            const value = ${JSON.stringify(value)};
+            let found = false;
+
+            for (const opt of select.options) {
+              if (opt.value === value || opt.textContent.trim() === value) {
+                select.value = opt.value;
+                found = true;
+                break;
+              }
+            }
+
+            if (!found) throw new Error('Option not found: ' + value);
+
+            select.dispatchEvent(new Event('change', { bubbles: true }));
+            select.dispatchEvent(new Event('input', { bubbles: true }));
+
+            return { success: true, selected: value };
+          })()
+        `);
+                return toolResult(result);
+            },
+        },
+    ];
+}

package/dist/cdp-tools/lifecycle.d.ts

@@ -0,0 +1,2 @@
+import type { CdpTool, ToolContext } from './types.js';
+export declare function createLifecycleTools(ctx: ToolContext): CdpTool[];