@wong2kim/wmux 1.1.1 → 2.0.0

package/dist/mcp/mcp/index.js

@@ -5,6 +5,15 @@ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const zod_1 = require("zod");
 const wmux_client_1 = require("./wmux-client");
+const PlaywrightEngine_1 = require("./playwright/PlaywrightEngine");
+const navigation_1 = require("./playwright/tools/navigation");
+const interaction_1 = require("./playwright/tools/interaction");
+const inspection_1 = require("./playwright/tools/inspection");
+const state_1 = require("./playwright/tools/state");
+const wait_1 = require("./playwright/tools/wait");
+const file_1 = require("./playwright/tools/file");
+const utility_1 = require("./playwright/tools/utility");
+const extraction_1 = require("./playwright/tools/extraction");
 const server = new mcp_js_1.McpServer({
     name: 'wmux',
     version: '1.0.0',
@@ -15,30 +24,29 @@ async function callRpc(method, params = {}) {
     const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
     return { content: [{ type: 'text', text }] };
 }
-// Optional surfaceId schema used by browser and terminal tools
-const optionalSurfaceId = zod_1.z.string().optional().describe('Target a specific surface by ID. Omit to use the active surface.');
-// === Browser tools ===
+// === Browser tools (RPC-based: surface management stays in main process) ===
 server.tool('browser_open', 'Open a new browser panel in the active pane. Use this when no browser surface exists yet.', {
     url: zod_1.z.string().optional().describe('Initial URL to load (defaults to google.com)'),
 }, async ({ url }) => callRpc('browser.open', url ? { url } : {}));
-server.tool('browser_navigate', 'Navigate the wmux browser panel to a URL', {
-    url: zod_1.z.string().describe('The URL to navigate to'),
-    surfaceId: optionalSurfaceId,
-}, async ({ url, surfaceId }) => callRpc('browser.navigate', { url, ...(surfaceId && { surfaceId }) }));
-server.tool('browser_snapshot', 'Get the full HTML content of the current page in the wmux browser panel', { surfaceId: optionalSurfaceId }, async ({ surfaceId }) => callRpc('browser.snapshot', surfaceId ? { surfaceId } : {}));
-server.tool('browser_click', 'Click an element in the wmux browser panel by CSS selector', {
-    selector: zod_1.z.string().describe('CSS selector of the element to click'),
-    surfaceId: optionalSurfaceId,
-}, async ({ selector, surfaceId }) => callRpc('browser.click', { selector, ...(surfaceId && { surfaceId }) }));
-server.tool('browser_fill', 'Fill an input field in the wmux browser panel by CSS selector', {
-    selector: zod_1.z.string().describe('CSS selector of the input element'),
-    text: zod_1.z.string().describe('Text to fill into the input'),
-    surfaceId: optionalSurfaceId,
-}, async ({ selector, text, surfaceId }) => callRpc('browser.fill', { selector, text, ...(surfaceId && { surfaceId }) }));
-server.tool('browser_eval', 'Execute JavaScript in the wmux browser panel and return the result', {
-    code: zod_1.z.string().describe('JavaScript code to execute in the browser context'),
-    surfaceId: optionalSurfaceId,
-}, async ({ code, surfaceId }) => callRpc('browser.eval', { code, ...(surfaceId && { surfaceId }) }));
+server.tool('browser_close', 'Close the browser panel in the active pane', {
+    surfaceId: zod_1.z.string().optional().describe('Target a specific surface by ID. Omit to use the active surface.'),
+}, async ({ surfaceId }) => callRpc('browser.close', surfaceId ? { surfaceId } : {}));
+// === Playwright browser tools ===
+(0, navigation_1.registerNavigationTools)(server);
+(0, interaction_1.registerInteractionTools)(server);
+(0, inspection_1.registerInspectionTools)(server);
+(0, state_1.registerStateTools)(server);
+(0, wait_1.registerWaitTools)(server);
+(0, file_1.registerFileTools)(server);
+(0, utility_1.registerUtilityTools)(server);
+(0, extraction_1.registerExtractionTools)(server);
+// === Browser session tools ===
+server.tool('browser_session_start', 'Start a browser session with the specified profile', {
+    profile: zod_1.z.string().optional().describe('Profile name to use (defaults to "default")'),
+}, async ({ profile }) => callRpc('browser.session.start', profile ? { profile } : {}));
+server.tool('browser_session_stop', 'Stop the current browser session', {}, async () => callRpc('browser.session.stop'));
+server.tool('browser_session_status', 'Get current browser session status', {}, async () => callRpc('browser.session.status'));
+server.tool('browser_session_list', 'List available browser profiles', {}, async () => callRpc('browser.session.list'));
 // === Terminal tools ===
 server.tool('terminal_read', 'Read the current visible text from the active terminal in wmux', {}, async () => callRpc('input.readScreen'));
 server.tool('terminal_send', 'Send text to the active terminal in wmux', { text: zod_1.z.string().describe('Text to send to the terminal') }, async ({ text }) => callRpc('input.send', { text }));
@@ -53,6 +61,18 @@ server.tool('pane_list', 'List all panes in the current workspace', {}, async ()
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
+    // Clean up Playwright connection when transport closes
+    transport.onclose = async () => {
+        console.log('[wmux-mcp] Transport closed, disconnecting Playwright');
+        await PlaywrightEngine_1.PlaywrightEngine.getInstance().disconnect();
+    };
+    // Graceful shutdown
+    const shutdown = async () => {
+        await PlaywrightEngine_1.PlaywrightEngine.getInstance().disconnect();
+        process.exit(0);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
 }
 main().catch((err) => {
     console.error('wmux MCP server failed to start:', err);

package/dist/mcp/mcp/playwright/PlaywrightEngine.js

@@ -0,0 +1,293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaywrightEngine = void 0;
+const playwright_core_1 = require("playwright-core");
+const wmux_client_1 = require("../wmux-client");
+const MAX_CONNECT_RETRIES = 1;
+const RETRY_DELAY_MS = 500;
+const PAGE_FIND_RETRIES = 1;
+const PAGE_FIND_DELAY_MS = 300;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Returns true if the URL belongs to the Electron main renderer window.
+ */
+function isElectronShellUrl(url) {
+    return (url.startsWith('http://localhost:') ||
+        url.startsWith('http://127.0.0.1:') ||
+        url.startsWith('devtools://') ||
+        url.startsWith('chrome://'));
+}
+/**
+ * PlaywrightEngine -- singleton wrapper around playwright-core's Chromium CDP connection.
+ *
+ * Strategy: Connect to the Electron browser endpoint, then use CDP Target domain
+ * to discover and attach to webview targets that aren't visible as regular pages.
+ */
+class PlaywrightEngine {
+    constructor() {
+        this.browser = null;
+        this.cdpPort = null;
+        this.playwrightFailed = false;
+    }
+    static getInstance() {
+        if (!PlaywrightEngine.instance) {
+            PlaywrightEngine.instance = new PlaywrightEngine();
+        }
+        return PlaywrightEngine.instance;
+    }
+    async connect(cdpPort) {
+        if (this.browser && this.cdpPort === cdpPort && this.browser.isConnected()) {
+            return;
+        }
+        await this.disconnect();
+        this.browser = await playwright_core_1.chromium.connectOverCDP(`http://localhost:${cdpPort}`);
+        this.cdpPort = cdpPort;
+        console.error(`[PlaywrightEngine] Connected to CDP on port ${cdpPort}`);
+        // Enable auto-attach so Electron webview targets become discoverable as Playwright pages.
+        // Without this, <webview> tags in Electron are separate renderer processes that
+        // don't appear in browser.contexts().pages().
+        try {
+            const session = await this.browser.newBrowserCDPSession();
+            await session.send('Target.setAutoAttach', {
+                autoAttach: true,
+                waitForDebuggerOnStart: false,
+                flatten: true,
+            });
+            console.error(`[PlaywrightEngine] Auto-attach enabled`);
+        }
+        catch (err) {
+            console.error('[PlaywrightEngine] setAutoAttach warning:', err instanceof Error ? err.message : String(err));
+        }
+    }
+    async disconnect() {
+        if (this.browser) {
+            this.browser = null;
+            this.cdpPort = null;
+            console.error('[PlaywrightEngine] Disconnected');
+        }
+    }
+    async ensureConnected() {
+        if (this.browser?.isConnected())
+            return;
+        for (let attempt = 1; attempt <= MAX_CONNECT_RETRIES; attempt++) {
+            try {
+                const info = (await (0, wmux_client_1.sendRpc)('browser.cdp.info'));
+                await this.connect(info.cdpPort);
+                return;
+            }
+            catch (err) {
+                console.error(`[PlaywrightEngine] Connection attempt ${attempt}/${MAX_CONNECT_RETRIES} failed:`, err instanceof Error ? err.message : String(err));
+                if (attempt < MAX_CONNECT_RETRIES) {
+                    await sleep(RETRY_DELAY_MS);
+                }
+            }
+        }
+        throw new Error(`[PlaywrightEngine] Failed to connect after ${MAX_CONNECT_RETRIES} attempts`);
+    }
+    /**
+     * Collect all Playwright Page objects from all contexts.
+     */
+    getAllPages() {
+        if (!this.browser || !this.browser.isConnected())
+            return [];
+        const pages = [];
+        for (const ctx of this.browser.contexts()) {
+            pages.push(...ctx.pages());
+        }
+        return pages;
+    }
+    /**
+     * Find a webview page using multiple strategies:
+     * 1. Check existing Playwright pages (works if webview is in a discoverable context)
+     * 2. Use CDP Target domain to find and attach to webview targets directly
+     * 3. Fetch /json endpoint for target discovery
+     */
+    async getPage(surfaceId) {
+        // Fast-fail if Playwright has already failed to find webview pages.
+        // MCP tools with RPC fallbacks will skip directly to the fast RPC path.
+        if (this.playwrightFailed)
+            return null;
+        await this.ensureConnected();
+        for (let attempt = 1; attempt <= PAGE_FIND_RETRIES; attempt++) {
+            try {
+                // Strategy 1: Check existing pages
+                const allPages = this.getAllPages();
+                console.error(`[PlaywrightEngine] Attempt ${attempt}: ${allPages.length} pages in ${this.browser?.contexts().length ?? 0} contexts`);
+                const safePage = allPages.find((p) => !isElectronShellUrl(p.url()));
+                if (safePage) {
+                    console.error(`[PlaywrightEngine] Found page via contexts: ${safePage.url()}`);
+                    return safePage;
+                }
+                // Strategy 2: Use CDP Target.getTargets to find webview targets
+                if (this.browser) {
+                    const page = await this.findViaTargetDomain(surfaceId);
+                    if (page)
+                        return page;
+                }
+                // Strategy 3: Use /json endpoint + match registered targets
+                if (this.cdpPort) {
+                    const page = await this.findViaJsonEndpoint(surfaceId);
+                    if (page)
+                        return page;
+                }
+                if (attempt < PAGE_FIND_RETRIES) {
+                    console.error(`[PlaywrightEngine] No page found, reconnecting... (${attempt}/${PAGE_FIND_RETRIES})`);
+                    await sleep(PAGE_FIND_DELAY_MS);
+                    await this.disconnect();
+                    await this.ensureConnected();
+                }
+            }
+            catch (err) {
+                console.error(`[PlaywrightEngine] getPage attempt ${attempt} failed:`, err instanceof Error ? err.message : String(err));
+                if (attempt < PAGE_FIND_RETRIES) {
+                    await sleep(PAGE_FIND_DELAY_MS);
+                    await this.disconnect();
+                    await this.ensureConnected();
+                }
+            }
+        }
+        console.error('[PlaywrightEngine] No webview page found after all retries — marking as failed');
+        this.playwrightFailed = true;
+        return null;
+    }
+    /**
+     * Use CDP Target domain to discover webview targets and create a page for them.
+     */
+    async findViaTargetDomain(surfaceId) {
+        if (!this.browser)
+            return null;
+        try {
+            // Get the default context's first page to create a CDP session
+            const defaultContext = this.browser.contexts()[0];
+            if (!defaultContext) {
+                console.error('[PlaywrightEngine] No default context available');
+                return null;
+            }
+            let cdpSession;
+            const existingPages = defaultContext.pages();
+            if (existingPages.length > 0) {
+                cdpSession = await existingPages[0].context().newCDPSession(existingPages[0]);
+            }
+            else {
+                cdpSession = await this.browser.newBrowserCDPSession();
+            }
+            // Get all targets
+            const { targetInfos } = await cdpSession.send('Target.getTargets');
+            console.error(`[PlaywrightEngine] CDP targets: ${targetInfos.map(t => `${t.type}:${t.url.substring(0, 40)}`).join(', ')}`);
+            // Get registered wmux targets for matching
+            const info = (await (0, wmux_client_1.sendRpc)('browser.cdp.info'));
+            const wmuxTarget = surfaceId
+                ? info.targets.find((t) => t.surfaceId === surfaceId)
+                : info.targets[0];
+            // Find the webview target — match by targetId from WebviewCdpManager
+            let webviewTarget = wmuxTarget
+                ? targetInfos.find((t) => t.targetId === wmuxTarget.targetId)
+                : undefined;
+            // Fallback: find any page target that isn't the Electron shell
+            if (!webviewTarget) {
+                webviewTarget = targetInfos.find((t) => t.type === 'page' && !isElectronShellUrl(t.url) && t.url !== 'about:blank');
+            }
+            if (!webviewTarget) {
+                console.error('[PlaywrightEngine] No webview target found in Target.getTargets');
+                return null;
+            }
+            console.error(`[PlaywrightEngine] Found webview target: ${webviewTarget.targetId} url=${webviewTarget.url}`);
+            // Try to attach to the target and get a page
+            // Attach with flatten:true creates a session in the current connection
+            if (!webviewTarget.attached) {
+                await cdpSession.send('Target.attachToTarget', {
+                    targetId: webviewTarget.targetId,
+                    flatten: true,
+                });
+                console.error(`[PlaywrightEngine] Attached to target ${webviewTarget.targetId}`);
+            }
+            // After attaching, check if new pages appeared
+            await sleep(500);
+            const newPages = this.getAllPages();
+            console.error(`[PlaywrightEngine] After attach: ${newPages.length} pages`);
+            const matchedPage = newPages.find((p) => !isElectronShellUrl(p.url()));
+            if (matchedPage) {
+                console.error(`[PlaywrightEngine] Found page after attach: ${matchedPage.url()}`);
+                return matchedPage;
+            }
+            // If pages still empty, try creating a new CDP connection specifically to the webview
+            // by reconnecting — this forces Playwright to re-discover all targets
+            console.error('[PlaywrightEngine] Attach did not create a page, will retry with reconnect');
+            return null;
+        }
+        catch (err) {
+            console.error('[PlaywrightEngine] findViaTargetDomain error:', err instanceof Error ? err.message : String(err));
+            return null;
+        }
+    }
+    /**
+     * Use the /json HTTP endpoint to find webview targets and attach via CDP.
+     */
+    async findViaJsonEndpoint(surfaceId) {
+        if (!this.cdpPort || !this.browser)
+            return null;
+        try {
+            const resp = await fetch(`http://127.0.0.1:${this.cdpPort}/json`);
+            const targets = (await resp.json());
+            console.error(`[PlaywrightEngine] /json targets: ${targets.map(t => `${t.type}:${t.url.substring(0, 40)}`).join(', ')}`);
+            // Get registered wmux targets
+            const info = (await (0, wmux_client_1.sendRpc)('browser.cdp.info'));
+            const wmuxTarget = surfaceId
+                ? info.targets.find((t) => t.surfaceId === surfaceId)
+                : info.targets[0];
+            // Find the webview in /json
+            let jsonTarget = wmuxTarget
+                ? targets.find((t) => t.id === wmuxTarget.targetId)
+                : undefined;
+            if (!jsonTarget) {
+                jsonTarget = targets.find((t) => t.type === 'page' && !isElectronShellUrl(t.url) && t.url !== 'about:blank');
+            }
+            if (!jsonTarget) {
+                console.error('[PlaywrightEngine] No webview found in /json');
+                return null;
+            }
+            console.error(`[PlaywrightEngine] Found target in /json: ${jsonTarget.id} url=${jsonTarget.url}`);
+            // Attach to the target via browser-level CDP session (don't disconnect!)
+            try {
+                const session = await this.browser.newBrowserCDPSession();
+                // Re-enable auto-attach to pick up the webview target
+                await session.send('Target.setAutoAttach', {
+                    autoAttach: true,
+                    waitForDebuggerOnStart: false,
+                    flatten: true,
+                });
+                // Also explicitly attach to the discovered target
+                await session.send('Target.attachToTarget', {
+                    targetId: jsonTarget.id,
+                    flatten: true,
+                });
+                console.error(`[PlaywrightEngine] Attached to target ${jsonTarget.id} via /json`);
+                // Brief wait for Playwright to process the attached target
+                await sleep(200);
+                const pages = this.getAllPages();
+                console.error(`[PlaywrightEngine] After /json attach: ${pages.length} pages`);
+                const matchedPage = pages.find((p) => !isElectronShellUrl(p.url()));
+                if (matchedPage) {
+                    console.error(`[PlaywrightEngine] Found page via /json attach: ${matchedPage.url()}`);
+                    return matchedPage;
+                }
+            }
+            catch (attachErr) {
+                console.error(`[PlaywrightEngine] /json attach failed: ${attachErr instanceof Error ? attachErr.message : String(attachErr)}`);
+            }
+            return null;
+        }
+        catch (err) {
+            console.error('[PlaywrightEngine] findViaJsonEndpoint error:', err instanceof Error ? err.message : String(err));
+            return null;
+        }
+    }
+    async getBrowser() {
+        await this.ensureConnected();
+        return this.browser;
+    }
+}
+exports.PlaywrightEngine = PlaywrightEngine;
+PlaywrightEngine.instance = null;

package/dist/mcp/mcp/playwright/anti-detection.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyAntiDetection = applyAntiDetection;
+exports.evaluateWithGesture = evaluateWithGesture;
+// ---------------------------------------------------------------------------
+// Anti-detection helpers
+// ---------------------------------------------------------------------------
+/**
+ * Apply anti-detection measures to the page via init scripts.
+ *
+ * Currently patches `navigator.webdriver` to return `undefined` so that
+ * common bot-detection scripts do not flag the session.
+ */
+async function applyAntiDetection(page) {
+    await page.context().addInitScript(() => {
+        // Override navigator.webdriver to hide automation flag
+        Object.defineProperty(navigator, 'webdriver', {
+            get: () => undefined,
+            configurable: true,
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// CDP-powered evaluate with user gesture
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate a JavaScript expression in the page context via CDP
+ * `Runtime.evaluate`.
+ *
+ * @param page       - The Playwright page to evaluate in.
+ * @param expression - The JavaScript expression to evaluate.
+ * @param options    - Optional settings.
+ * @param options.userGesture - When `true`, the evaluation is treated as if
+ *   triggered by a user gesture (transient activation). Defaults to `false`
+ *   to follow the principle of least privilege. Callers that genuinely need
+ *   user activation (e.g. opening popups, triggering downloads) should
+ *   explicitly pass `true`.
+ *
+ * Internally opens a CDP session and calls `Runtime.evaluate`.
+ */
+async function evaluateWithGesture(page, expression, options) {
+    const client = await page.context().newCDPSession(page);
+    try {
+        const result = await client.send('Runtime.evaluate', {
+            expression,
+            userGesture: options?.userGesture ?? false,
+            returnByValue: true,
+            awaitPromise: true,
+        });
+        if (result.exceptionDetails) {
+            const msg = result.exceptionDetails.exception?.description ??
+                result.exceptionDetails.text ??
+                'CDP Runtime.evaluate threw an exception';
+            throw new Error(msg);
+        }
+        return result.result.value;
+    }
+    finally {
+        await client.detach().catch(() => {
+            /* best-effort cleanup */
+        });
+    }
+}

package/dist/mcp/mcp/playwright/dom-intelligence.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSmartSnapshot = getSmartSnapshot;
+exports.getLocatorByRef = getLocatorByRef;
+exports.clearElementCache = clearElementCache;
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_CONTENT_LENGTH = 3000;
+/** Roles considered interactive — elements with these roles get indexed */
+const INTERACTIVE_ROLES = new Set([
+    'button',
+    'link',
+    'textbox',
+    'checkbox',
+    'radio',
+    'combobox',
+    'listbox',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'searchbox',
+    'slider',
+    'spinbutton',
+    'switch',
+    'tab',
+    'treeitem',
+]);
+// ---------------------------------------------------------------------------
+// Element cache — stores indexed elements from the last snapshot
+// ---------------------------------------------------------------------------
+let elementCache = [];
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Escape special characters in a string for use inside a Playwright
+ * locator expression (e.g. `getByRole('button', { name: '...' })`).
+ */
+function escapeLocatorName(name) {
+    return name.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/**
+ * Build a Playwright locator string for a given role and name.
+ *
+ * If the name is empty, falls back to `getByRole('role')` without a
+ * name filter. When duplicate names exist for the same role, callers
+ * should use `.nth()` — but we provide the base locator here.
+ */
+function buildLocatorString(role, name) {
+    if (!name) {
+        return `getByRole('${role}')`;
+    }
+    return `getByRole('${role}', { name: '${escapeLocatorName(name)}' })`;
+}
+/**
+ * Recursively walk the CDP accessibility tree and collect interactive
+ * elements into the provided array, assigning 1-based ref numbers.
+ */
+function collectInteractiveElements(nodeMap, node, elements) {
+    if (node.ignored)
+        return;
+    const role = node.role?.value ?? 'none';
+    const name = node.name?.value ?? '';
+    if (INTERACTIVE_ROLES.has(role)) {
+        const ref = elements.length + 1; // 1-based
+        const element = {
+            ref,
+            role,
+            name,
+            locator: buildLocatorString(role, name),
+        };
+        if (node.value?.value) {
+            element.value = node.value.value;
+        }
+        if (node.description?.value) {
+            element.description = node.description.value;
+        }
+        elements.push(element);
+    }
+    // Recurse into children
+    if (node.childIds) {
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (child) {
+                collectInteractiveElements(nodeMap, child, elements);
+            }
+        }
+    }
+}
+/**
+ * Fetch the full accessibility tree via CDP and return indexed interactive
+ * elements.
+ */
+async function getInteractiveElements(page) {
+    const client = await page.context().newCDPSession(page);
+    try {
+        const { nodes } = (await client.send('Accessibility.getFullAXTree'));
+        if (nodes.length === 0)
+            return [];
+        // Build a map for quick lookup by nodeId
+        const nodeMap = new Map();
+        for (const n of nodes)
+            nodeMap.set(n.nodeId, n);
+        const elements = [];
+        collectInteractiveElements(nodeMap, nodes[0], elements);
+        return elements;
+    }
+    finally {
+        await client.detach().catch(() => {
+            /* best-effort cleanup */
+        });
+    }
+}
+/**
+ * Retrieve truncated page text content.
+ */
+async function getPageContent(page, maxLength) {
+    try {
+        const text = await page.innerText('body');
+        if (text.length <= maxLength)
+            return text;
+        return text.slice(0, maxLength) + '\n... (truncated)';
+    }
+    catch {
+        return '';
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate a "smart snapshot" of the page: a structured representation
+ * containing only interactive elements (with 1-based ref indices) plus a
+ * truncated text summary of the page content.
+ *
+ * The indexed elements are cached internally so that `getLocatorByRef()`
+ * can resolve a ref number back to a Playwright locator string without
+ * re-querying the page.
+ */
+async function getSmartSnapshot(page, options) {
+    const maxContentLength = options?.maxContentLength ?? DEFAULT_MAX_CONTENT_LENGTH;
+    const [url, title, elements, content] = await Promise.all([
+        Promise.resolve(page.url()),
+        page.title(),
+        getInteractiveElements(page),
+        getPageContent(page, maxContentLength),
+    ]);
+    // Update element cache
+    elementCache = elements;
+    return { url, title, elements, content };
+}
+/**
+ * Look up a Playwright locator string by the 1-based ref number assigned
+ * during the most recent `getSmartSnapshot()` call.
+ *
+ * Returns `null` if the ref is out of range or no snapshot has been taken.
+ */
+function getLocatorByRef(ref) {
+    if (ref < 1 || ref > elementCache.length)
+        return null;
+    return elementCache[ref - 1].locator;
+}
+/**
+ * Clear the cached element list. Useful when navigating to a new page
+ * to avoid stale refs.
+ */
+function clearElementCache() {
+    elementCache = [];
+}

package/dist/mcp/mcp/playwright/human-typing.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDelaySchedule = generateDelaySchedule;
+exports.typeHumanlike = typeHumanlike;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_MIN_DELAY = 50;
+const DEFAULT_MAX_DELAY = 150;
+function randomDelay(min, max) {
+    return Math.random() * (max - min) + min;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate an array of per-character delay values (in ms) for the given
+ * text.  This mirrors `HumanBehavior.generateTypingSchedule()` from the
+ * main process but is independent of that class.
+ */
+function generateDelaySchedule(text, options) {
+    const min = options?.minDelay ?? DEFAULT_MIN_DELAY;
+    const max = options?.maxDelay ?? DEFAULT_MAX_DELAY;
+    return Array.from({ length: text.length }, () => randomDelay(min, max));
+}
+/**
+ * Type `text` into the element identified by `selector` with randomised
+ * inter-keystroke delays that mimic human typing.
+ *
+ * Each character is pressed individually via `page.keyboard.press()` with
+ * a random pause between `minDelay` and `maxDelay` milliseconds.
+ *
+ * If `selector` is provided the element is clicked first to ensure focus.
+ */
+async function typeHumanlike(page, selector, text, options) {
+    // Focus the target element
+    if (selector) {
+        await page.click(selector);
+    }
+    const delays = generateDelaySchedule(text, options);
+    for (let i = 0; i < text.length; i++) {
+        await page.keyboard.press(text[i]);
+        await sleep(delays[i]);
+    }
+}