@weavetab/mcp 2.5.0-beta.0

package/dist/tools/viewport.js

@@ -0,0 +1,230 @@
+export const DEVICE_PRESETS = {
+    'iPhone 15 Pro': {
+        userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+        viewport: { width: 393, height: 852 },
+        deviceScaleFactor: 3,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'iPhone 15 Pro Max': {
+        userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+        viewport: { width: 430, height: 932 },
+        deviceScaleFactor: 3,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'iPhone 14': {
+        userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1',
+        viewport: { width: 390, height: 844 },
+        deviceScaleFactor: 3,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'iPhone 14 Pro': {
+        userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1',
+        viewport: { width: 393, height: 852 },
+        deviceScaleFactor: 3,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'iPad Pro 12.9': {
+        userAgent: 'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+        viewport: { width: 1024, height: 1366 },
+        deviceScaleFactor: 2,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'Samsung Galaxy S24': {
+        userAgent: 'Mozilla/5.0 (Linux; Android 14; SM-S921B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36',
+        viewport: { width: 360, height: 800 },
+        deviceScaleFactor: 3,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'Samsung Galaxy S24 Ultra': {
+        userAgent: 'Mozilla/5.0 (Linux; Android 14; SM-S928B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36',
+        viewport: { width: 412, height: 915 },
+        deviceScaleFactor: 3,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'Pixel 8 Pro': {
+        userAgent: 'Mozilla/5.0 (Linux; Android 14; Pixel 8 Pro) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36',
+        viewport: { width: 412, height: 892 },
+        deviceScaleFactor: 2.625,
+        mobile: true,
+        hasTouch: true,
+        screenOrientation: 'portrait'
+    },
+    'Desktop 1920x1080': {
+        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+        viewport: { width: 1920, height: 1080 },
+        deviceScaleFactor: 1,
+        mobile: false,
+        hasTouch: false,
+        screenOrientation: 'landscape'
+    },
+    'Desktop 1366x768': {
+        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+        viewport: { width: 1366, height: 768 },
+        deviceScaleFactor: 1,
+        mobile: false,
+        hasTouch: false,
+        screenOrientation: 'landscape'
+    },
+    'Laptop 1440x900': {
+        userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+        viewport: { width: 1440, height: 900 },
+        deviceScaleFactor: 1,
+        mobile: false,
+        hasTouch: false,
+        screenOrientation: 'landscape'
+    }
+};
+export async function browserViewport(session, options, _config) {
+    const { action, width, height, deviceScaleFactor = 1, mobile = false, devicePreset, userAgent, geolocation, locale, timezoneId, colorScheme, hasTouch, screenOrientation } = options;
+    if (action === "list") {
+        return {
+            success: true,
+            message: "Available device presets",
+            data: Object.keys(DEVICE_PRESETS).map(key => ({
+                devicePreset: key,
+                ...DEVICE_PRESETS[key]
+            }))
+        };
+    }
+    if (action === "preset") {
+        if (!devicePreset) {
+            throw new Error("devicePreset is required for preset action");
+        }
+        const preset = DEVICE_PRESETS[devicePreset];
+        if (!preset) {
+            throw new Error(`Unknown device preset: ${devicePreset}. Available: ${Object.keys(DEVICE_PRESETS).join(', ')}`);
+        }
+        await applyViewportEmulation(session, {
+            width: preset.viewport.width,
+            height: preset.viewport.height,
+            deviceScaleFactor: preset.deviceScaleFactor,
+            mobile: preset.mobile,
+            hasTouch: preset.hasTouch,
+            screenOrientation: preset.screenOrientation,
+            userAgent: preset.userAgent,
+            geolocation,
+            locale,
+            timezoneId,
+            colorScheme
+        });
+        return {
+            success: true,
+            message: `Applied device preset: ${devicePreset}`,
+            data: { devicePreset, ...preset }
+        };
+    }
+    if (action === "clear") {
+        await session.Emulation.clearDeviceMetricsOverride();
+        await session.Network.setUserAgentOverride({ userAgent: '' });
+        await session.Emulation.clearGeolocationOverride();
+        await session.Emulation.setTimezoneOverride({ timezoneId: '' });
+        return { success: true, message: "Cleared all viewport emulation" };
+    }
+    if (action === "set") {
+        const hasViewport = width !== undefined && height !== undefined;
+        const hasEmulation = geolocation !== undefined || timezoneId !== undefined || locale !== undefined || colorScheme !== undefined;
+        if (!hasViewport && !hasEmulation) {
+            throw new Error("Provide width/height for viewport, or geolocation/timezone/locale/colorScheme for emulation");
+        }
+        if (hasViewport) {
+            await applyViewportEmulation(session, {
+                width,
+                height,
+                deviceScaleFactor,
+                mobile,
+                hasTouch,
+                screenOrientation,
+                userAgent,
+                geolocation,
+                locale,
+                timezoneId,
+                colorScheme
+            });
+            return {
+                success: true,
+                message: `Viewport set to ${width}x${height} (mobile: ${mobile}, dpr: ${deviceScaleFactor}, touch: ${hasTouch})`
+            };
+        }
+        // Emulation-only: apply geo/timezone/locale/colorScheme without touching viewport dimensions
+        const msg = [];
+        if (geolocation) {
+            await session.Emulation.setGeolocationOverride({
+                latitude: geolocation.latitude,
+                longitude: geolocation.longitude,
+                accuracy: geolocation.accuracy || 100
+            });
+            msg.push(`Geolocation set to ${geolocation.latitude}, ${geolocation.longitude}`);
+        }
+        if (timezoneId) {
+            await session.Emulation.setTimezoneOverride({ timezoneId });
+            msg.push(`Timezone set to ${timezoneId}`);
+        }
+        if (locale) {
+            await session.Emulation.setLocaleOverride({ locale });
+            msg.push(`Locale set to ${locale}`);
+        }
+        if (colorScheme && colorScheme !== 'no-preference') {
+            await session.Emulation.setEmulatedMedia({
+                features: [{ name: 'prefers-color-scheme', value: colorScheme }]
+            });
+            msg.push(`Color scheme set to ${colorScheme}`);
+        }
+        return { success: true, message: msg.join('. ') };
+    }
+    throw new Error("Unknown action");
+}
+async function applyViewportEmulation(session, options) {
+    const { width, height, deviceScaleFactor, mobile, hasTouch = mobile, screenOrientation, userAgent, geolocation, locale, timezoneId, colorScheme } = options;
+    // Set device metrics override
+    const orientation = screenOrientation === 'none' ? undefined :
+        screenOrientation === 'landscape'
+            ? { type: 'landscapePrimary', angle: 90 }
+            : { type: 'portraitPrimary', angle: 0 };
+    await session.Emulation.setDeviceMetricsOverride({
+        width,
+        height,
+        deviceScaleFactor,
+        mobile,
+        screenOrientation: orientation
+    });
+    // Set user agent if provided
+    if (userAgent) {
+        await session.Network.setUserAgentOverride({ userAgent });
+    }
+    // Set geolocation if provided
+    if (geolocation) {
+        await session.Emulation.setGeolocationOverride({
+            latitude: geolocation.latitude,
+            longitude: geolocation.longitude,
+            accuracy: geolocation.accuracy || 100
+        });
+    }
+    // Set timezone if provided
+    if (timezoneId) {
+        await session.Emulation.setTimezoneOverride({ timezoneId });
+    }
+    // Set locale if provided
+    if (locale) {
+        await session.Emulation.setLocaleOverride({ locale });
+    }
+    // Set color scheme if provided
+    if (colorScheme && colorScheme !== 'no-preference') {
+        await session.Emulation.setEmulatedMedia({
+            features: [{ name: 'prefers-color-scheme', value: colorScheme }]
+        });
+    }
+}

package/dist/tools/wait.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Weavetab — tools/wait.ts
+ * Smart wait framework: polls/observes until condition is met or timeout expires.
+ * Supports: element, text, url, stable, network, auto
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+import type { Config } from "../config/loader.js";
+export interface WaitResult {
+    success: boolean;
+    found: boolean;
+    elapsed_ms: number;
+    matched_value: string;
+}
+export declare function browserWait(session: CDP.Client, args: {
+    for: "element" | "text" | "url" | "stable" | "network" | "auto";
+    value?: string;
+    timeout?: number;
+}, config: Config): Promise<WaitResult>;

package/dist/tools/wait.js

@@ -0,0 +1,202 @@
+import { logDebug } from "../audit/logger.js";
+import { sessionRegistry } from "../state/session.js";
+import { logAction } from "../audit/logger.js";
+import { sendToExtension } from "../cdp/helpers.js";
+import { getConfigAgentId } from "../config/loader.js";
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+function globMatch(pattern, value) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`, "i").test(value);
+}
+// ── Auto-route: guess the best wait mode from the value string ─────────────
+function autoDetectMode(value) {
+    if (/^https?:\/\//.test(value) || value.includes("://") || value.startsWith("*"))
+        return "url";
+    if (/^[.#\[]/.test(value) || /^[a-z]+\[/.test(value) || value.includes(" > "))
+        return "element";
+    return "text";
+}
+// ── Wait for element via MutationObserver injected into page ──────────────
+async function waitForElement(session, selector, timeout) {
+    const start = Date.now();
+    const res = await session.Runtime.evaluate({
+        expression: `(function(sel, timeout) {
+      return new Promise((resolve) => {
+        // Check immediately first
+        const existing = document.querySelector(sel) ||
+          (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(sel) : null);
+        if (existing) { return resolve({ found: true, tag: existing.tagName }); }
+
+        const obs = new MutationObserver(() => {
+          const el = document.querySelector(sel) ||
+            (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(sel) : null);
+          if (el) { obs.disconnect(); clearTimeout(tid); resolve({ found: true, tag: el.tagName }); }
+        });
+        obs.observe(document.documentElement, { childList: true, subtree: true, attributes: true });
+        const tid = setTimeout(() => { obs.disconnect(); resolve({ found: false }); }, timeout);
+      });
+    })(${JSON.stringify(selector)}, ${timeout})`,
+        awaitPromise: true,
+        returnByValue: true,
+        timeout: timeout + 2000,
+    }).catch(() => null);
+    const found = res?.result?.value?.found === true;
+    return { found, elapsed_ms: Date.now() - start };
+}
+// ── Wait for text via polling + MutationObserver ──────────────────────────
+async function waitForText(session, text, timeout) {
+    const start = Date.now();
+    const res = await session.Runtime.evaluate({
+        expression: `(function(needle, timeout) {
+      return new Promise((resolve) => {
+        const check = () => {
+          const body = document.body?.innerText ?? document.body?.textContent ?? '';
+          if (body.includes(needle)) return true;
+          // Also check visible value attributes
+          const inputs = document.querySelectorAll('input, textarea');
+          for (const inp of inputs) {
+            if ((inp.value || '').includes(needle)) return true;
+          }
+          return false;
+        };
+        if (check()) return resolve({ found: true });
+
+        const obs = new MutationObserver(() => {
+          if (check()) { obs.disconnect(); clearTimeout(tid); resolve({ found: true }); }
+        });
+        obs.observe(document.documentElement, { childList: true, subtree: true, characterData: true });
+        const tid = setTimeout(() => { obs.disconnect(); resolve({ found: false }); }, timeout);
+      });
+    })(${JSON.stringify(text)}, ${timeout})`,
+        awaitPromise: true,
+        returnByValue: true,
+        timeout: timeout + 2000,
+    }).catch(() => null);
+    const found = res?.result?.value?.found === true;
+    return { found, elapsed_ms: Date.now() - start };
+}
+// ── Wait for URL via polling (Page.getFrameTree) ──────────────────────────
+async function waitForUrl(session, pattern, timeout) {
+    const start = Date.now();
+    const interval = 150;
+    while (Date.now() - start < timeout) {
+        try {
+            const { frameTree } = await session.Page.getFrameTree();
+            const currentUrl = frameTree.frame.url;
+            if (globMatch(pattern, currentUrl) || currentUrl.includes(pattern)) {
+                return { found: true, elapsed_ms: Date.now() - start, matched_value: currentUrl };
+            }
+        }
+        catch { /* navigation in progress, keep polling */ }
+        await sleep(interval);
+    }
+    return { found: false, elapsed_ms: Date.now() - start, matched_value: "" };
+}
+// ── Wait for network idle (no pending requests for quietMs) ───────────────
+async function waitForNetwork(session, timeout, quietMs = 500) {
+    const start = Date.now();
+    try {
+        await session.Network.enable({});
+    }
+    catch { /* already enabled */ }
+    return new Promise((resolve) => {
+        let pending = 0;
+        let quietTimer = null;
+        let done = false;
+        const finish = (found) => {
+            if (done)
+                return;
+            done = true;
+            if (quietTimer)
+                clearTimeout(quietTimer);
+            try {
+                session.removeListener("Network.requestWillBeSent", onRequest);
+                session.removeListener("Network.loadingFinished", onComplete);
+                session.removeListener("Network.loadingFailed", onComplete);
+            }
+            catch { /* ignore */ }
+            resolve({ found, elapsed_ms: Date.now() - start });
+        };
+        const resetQuiet = () => {
+            if (quietTimer)
+                clearTimeout(quietTimer);
+            if (pending <= 0) {
+                quietTimer = setTimeout(() => finish(true), quietMs);
+            }
+        };
+        resetQuiet();
+        const onRequest = () => {
+            pending++;
+            if (quietTimer)
+                clearTimeout(quietTimer);
+            quietTimer = null;
+        };
+        const onComplete = () => {
+            pending = Math.max(0, pending - 1);
+            resetQuiet();
+        };
+        session.on("Network.requestWillBeSent", onRequest);
+        session.on("Network.loadingFinished", onComplete);
+        session.on("Network.loadingFailed", onComplete);
+        // Overall timeout guard
+        setTimeout(() => finish(false), timeout);
+    });
+}
+// ── Main export ───────────────────────────────────────────────────────────
+export async function browserWait(session, args, config) {
+    const { for: waitFor, value = "", timeout: rawTimeout = 8000 } = args;
+    const timeout = Math.max(1000, rawTimeout);
+    const start = Date.now();
+    let targetId = "default";
+    const active = sessionRegistry.getActive(getConfigAgentId(config));
+    if (active)
+        targetId = active.targetId;
+    sendToExtension(session, { type: 'Weavetab_STATE', hud: { action: `waiting for ${waitFor}...` } }).catch(() => { });
+    try {
+        // ── Auto-detect mode ─────────────────────────────────────────────────
+        if (waitFor === "auto") {
+            const detected = autoDetectMode(value);
+            return browserWait(session, { for: detected, value, timeout }, config);
+        }
+        // ── Element wait (MutationObserver) ───────────────────────────────────
+        if (waitFor === "element") {
+            const { found, elapsed_ms } = await waitForElement(session, value, timeout);
+            logAction("browser_wait", "element", found ? `found: ${value}` : `timeout after ${elapsed_ms}ms`);
+            return { success: found, found, elapsed_ms, matched_value: found ? value : "" };
+        }
+        // ── Text wait (MutationObserver) ──────────────────────────────────────
+        if (waitFor === "text") {
+            const { found, elapsed_ms } = await waitForText(session, value, timeout);
+            logAction("browser_wait", "text", found ? `found: "${value}"` : `timeout after ${elapsed_ms}ms`);
+            return { success: found, found, elapsed_ms, matched_value: found ? value : "" };
+        }
+        // ── URL wait (polling) ────────────────────────────────────────────────
+        if (waitFor === "url") {
+            const { found, elapsed_ms, matched_value } = await waitForUrl(session, value, timeout);
+            logAction("browser_wait", "url", found ? `matched: ${matched_value}` : `timeout after ${elapsed_ms}ms`);
+            return { success: found, found, elapsed_ms, matched_value };
+        }
+        // ── Stable DOM wait ───────────────────────────────────────────────────
+        if (waitFor === "stable") {
+            const { waitForDOMStable } = await import("../sensors/guard.js");
+            await waitForDOMStable(session, 500, timeout);
+            const elapsed = Date.now() - start;
+            logAction("browser_wait", "stable", `DOM settled after ${elapsed}ms`);
+            return { success: true, found: true, elapsed_ms: elapsed, matched_value: "stable" };
+        }
+        // ── Network idle wait ─────────────────────────────────────────────────
+        if (waitFor === "network") {
+            const { found, elapsed_ms } = await waitForNetwork(session, timeout);
+            logAction("browser_wait", "network", found ? `network idle after ${elapsed_ms}ms` : `timeout after ${elapsed_ms}ms`);
+            return { success: true, found, elapsed_ms, matched_value: found ? "network-idle" : "" };
+        }
+    }
+    catch (e) {
+        logDebug(`[Weavetab] Error in browserWait(${waitFor}): ${e}`);
+    }
+    const elapsed = Date.now() - start;
+    logAction("browser_wait", waitFor, `timeout/error after ${elapsed}ms`);
+    return { success: false, found: false, elapsed_ms: elapsed, matched_value: "" };
+}

package/dist/tools/wait_for.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Weavetab — tools/wait_for.ts
+ * browser_wait_for: Poll the DOM for a CSS selector to appear.
+ *
+ * Use this to explicitly wait for an element to exist in the DOM instead of relying on
+ * hardcoded sleeps. It polls the document using querySelector.
+ * Returns the resolved backendNodeId if found before the timeout.
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+import type { Config } from "../config/loader.js";
+export interface WaitForOptions {
+    selector: string;
+    timeoutMs?: number;
+}
+export interface WaitForResult {
+    success: boolean;
+    selector: string;
+    found: boolean;
+    elapsedMs: number;
+    nodeId?: number;
+}
+export declare function browserWaitFor(session: CDP.Client, options: WaitForOptions, _config: Config): Promise<WaitForResult>;

package/dist/tools/wait_for.js

@@ -0,0 +1,30 @@
+export async function browserWaitFor(session, options, _config) {
+    const { selector, timeoutMs = 10000 } = options;
+    const pollInterval = 200;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const { result } = await session.Runtime.evaluate({
+                expression: `document.querySelector('${selector.replace(/'/g, "\\'")}') !== null`,
+                returnByValue: true
+            });
+            if (result.value === true) {
+                // Find the node id
+                const { root } = await session.DOM.getDocument({ depth: -1 });
+                const { nodeId } = await session.DOM.querySelector({ nodeId: root.nodeId, selector });
+                const elapsed = Date.now() - start;
+                return { success: true, selector, found: true, elapsedMs: elapsed, nodeId };
+            }
+        }
+        catch {
+            // Evaluation might fail if page is navigating, just retry
+        }
+        await new Promise(r => setTimeout(r, pollInterval));
+    }
+    return {
+        success: false,
+        selector,
+        found: false,
+        elapsedMs: Date.now() - start
+    };
+}

package/dist/tools/windows.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Weavetab — tools/windows.ts
+ * Lists and focuses browser windows/popups opened via window.open().
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+import type { Config } from "../config/loader.js";
+export interface WindowInfo {
+    id: string;
+    url: string;
+    title: string;
+    type: string;
+}
+export interface WindowsResult {
+    success: true;
+    windows: WindowInfo[];
+    active_id: string | null;
+}
+export declare function browserWindows(session: CDP.Client, args: {
+    action: "list" | "focus";
+    windowId?: string;
+}, config: Config): Promise<WindowsResult>;

package/dist/tools/windows.js

@@ -0,0 +1,57 @@
+/**
+ * Weavetab — tools/windows.ts
+ * Lists and focuses browser windows/popups opened via window.open().
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+import { getPort } from "../cdp/connector.js";
+import { connectToTab } from "../cdp/connector.js";
+import { sessionRegistry } from "../state/session.js";
+import { logAction } from "../audit/logger.js";
+import { getConfigAgentId } from "../config/loader.js";
+import { readLock } from "../cdp/lock.js";
+/** Resolve active CDP port — live > lock file */
+function resolvePort(_config) {
+    const port = getPort() || readLock()?.port;
+    if (!port)
+        throw new Error("[!] No active browser session. Run browser_go first.");
+    return port;
+}
+export async function browserWindows(session, args, config) {
+    const { action, windowId } = args;
+    const port = resolvePort(config);
+    const targets = await CDP.List({ host: "127.0.0.1", port });
+    // Include ALL target types — pages, popups, iframes
+    const windows = targets
+        .filter((t) => t.type === "page" || t.type === "popup")
+        .map((t) => ({
+        id: t.id,
+        url: t.url,
+        title: t.title,
+        type: t.type === "page" ? "tab/window" : t.type,
+    }));
+    // Auto-attach any popup that isn't in the session registry
+    for (const w of windows) {
+        const known = sessionRegistry.getAll().find((c) => c.targetId === w.id);
+        if (!known) {
+            connectToTab(w.id, port, getConfigAgentId(config)).catch(() => { });
+        }
+    }
+    if (action === "focus" && windowId) {
+        const cleanId = windowId.trim();
+        // Short delay to let auto-attach (above) complete if it was just fired
+        await new Promise(r => setTimeout(r, 150));
+        const client = await connectToTab(cleanId, port, getConfigAgentId(config));
+        await client.session.Target.activateTarget({ targetId: cleanId });
+        sessionRegistry.setActive(cleanId, getConfigAgentId(config));
+        logAction("browser_windows", "focus", cleanId);
+    }
+    else {
+        logAction("browser_windows", "list", `${windows.length} windows`);
+    }
+    return {
+        success: true,
+        windows,
+        active_id: sessionRegistry.getActive(getConfigAgentId(config))?.targetId ?? null,
+    };
+}

package/dist/ui/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/index.js

@@ -0,0 +1,12 @@
+export {};
+// src/ui/index.ts — DEPRECATED: All UI moved to ext-dist/content.js (Chrome extension)
+// Legacy GhostOverlay (tactical overlay, ask modal) has been removed.
+// The extension content script now handles:
+//   - WeaveCursor (canvas-based, shadow-DOM isolated)
+//   - Thought bubble (.wt-bubble with typewriter + hex icon)
+//   - Ask modal (.wt-chat input + Reply button)
+//   - HUD (token recorder, bottom-right)
+//   - X-Ray spotlight, controlled tab indicator, ripple effects
+//
+// This file is kept as a build stub so esbuild doesn't error.
+// It exports nothing and does nothing.

package/docs/DEV_MODE.md

@@ -0,0 +1,68 @@
+# Weavetab Developer Mode (devMode) & Plugin Profiling Guide
+
+This guide explains Developer Mode (`devMode`), how tool execution timing (`execution_ms`) works, and how it empowers **`weavetab-plugin` developers** and AI agents to profile performance.
+
+---
+
+## Enabling Developer Mode
+
+Developer Mode can be enabled in two ways:
+
+1. **Via Configuration (`~/.weavetab/config.json` or `.weavetab/config.json`)**:
+   ```json
+   {
+     "devMode": true
+   }
+   ```
+
+2. **Via Environment Variable**:
+   ```bash
+   WEAVETAB_DEV=1 node dist/index.js
+   ```
+
+---
+
+## What Does `devMode` Add?
+
+When `devMode` is active, Weavetab exposes rich execution metadata, visual debugging tools, and mission logging without altering underlying tool execution behavior.
+
+### 1. `execution_ms` & Tool Performance Profiling
+
+In `devMode`, every tool response automatically includes an **`execution_ms`** field:
+
+```json
+{
+  "success": true,
+  "execution_ms": 14,
+  "result": { ... }
+}
+```
+
+* **Purpose**: Measures the exact millisecond duration required to process and complete that specific tool call.
+* **Essential for Plugin Developers**: Allows community developers building custom Weavetab plugins to profile their handlers, measure bottleneck latency, and optimize tool responsiveness.
+* **Agent Context Awareness**: AI agents and users reading tool outputs can monitor tool performance in real time.
+
+### 2. Extension Visual Overlays & Tool Calls
+
+* **Extension Visuals**: Renders real-time tool execution badges and `toolcalls` counters directly within the extension overlay.
+* **Trajectory & Hitbox Inspection**: Visualizes pointer paths, click target bounding boxes, and action status badges during execution.
+
+### 3. Mission Logs (`/logs/`)
+
+* For every completed mission, Weavetab generates a structured mission log file inside `/logs/` (`~/.weavetab/logs/`).
+* Contains full step-by-step tool traces, `execution_ms` timing distributions, and action histories for auditing and debugging.
+
+---
+
+## Plugin Performance Profiling
+
+Developer Mode is especially valuable for community developers creating Weavetab plugin packages.
+
+* **Profiling Custom Tool Handlers**:
+  When developing a plugin, enabling `devMode` (`WEAVETAB_DEV=1`) allows you to inspect the `execution_ms` timer on every custom tool response to benchmark performance and optimize your code before publishing.
+* **Manifest & Permissions**:
+  Plugins define their metadata, permissions, and entry points in a `weavetab.json` manifest.
+* **Marketplace Screenshots (`/images/`)**:
+  Plugins can include an `/images` directory with screenshots and logos for display on the official Weavetab Marketplace website (`website/`).
+
+> 📖 For full details on building, packaging, and publishing plugins, see [docs/PLUGINS.md](PLUGINS.md).