@wordbricks/playwright-mcp 0.1.25 → 0.1.26

package/lib/hooks/core.js

@@ -0,0 +1,145 @@
+import { reduce } from "@fxts/core";
+import { consumeEvents } from "./eventConsumer.js";
+import { getEventStore, trackEvent } from "./events.js";
+import { toolNameSchema } from "./schema.js";
+export { Err, Ok } from "../utils/result.js";
+export const runHook = async (hook, ctx) => {
+    const result = await hook.handler(ctx);
+    if (!result.ok)
+        throw result.error;
+    return ctx;
+};
+export const hookRegistryMap = new WeakMap();
+export const createHookRegistry = () => ({
+    tools: new Map(),
+});
+export const setToolHooks = (registry, toolHooks) => ({
+    tools: new Map([...registry.tools, [toolHooks.toolName, toolHooks]]),
+});
+export const getToolHooks = (registry, toolName) => {
+    return registry.tools.get(toolName);
+};
+export const wrapToolWithHooks = (tool, registry) => {
+    const parsedName = toolNameSchema.safeParse(tool.schema.name);
+    if (!parsedName.success)
+        return tool; // Tool name not in our schema, don't apply hooks
+    // NOTE: This means tool call events won't be tracked for tools not in toolNameSchema.
+    // All tools exposed by this MCP server should be added to the schema.
+    const toolName = parsedName.data;
+    const toolHooks = getToolHooks(registry, toolName);
+    // Even if no hooks configured, we still need to consume events and track tool calls
+    if (!toolHooks ||
+        (toolHooks.preHooks.length === 0 && toolHooks.postHooks.length === 0)) {
+        return {
+            ...tool,
+            handle: async (context, params, response) => {
+                const eventStore = getEventStore(context);
+                // Consume pre-tool events
+                consumeEvents(context, eventStore, response);
+                // Track tool execution
+                const startTime = Date.now();
+                let success = true;
+                try {
+                    await tool.handle(context, params, response);
+                }
+                catch (error) {
+                    success = false;
+                    throw error;
+                }
+                finally {
+                    // Record tool call completion
+                    const executionTime = Date.now() - startTime;
+                    trackEvent(context, {
+                        type: "tool-call",
+                        data: {
+                            toolName,
+                            params: params,
+                            executionTime,
+                            success,
+                        },
+                        timestamp: startTime,
+                    });
+                    // Consume post-tool events
+                    consumeEvents(context, eventStore, response);
+                }
+            },
+        };
+    }
+    return {
+        ...tool,
+        handle: async (context, params, response) => {
+            const eventStore = getEventStore(context);
+            // Consume pre-tool events
+            consumeEvents(context, eventStore, response);
+            // Track tool execution
+            const startTime = Date.now();
+            // Run pre-hooks
+            const hookContext = {
+                context,
+                tab: context.currentTab(),
+                params,
+                toolName,
+                response,
+                eventStore,
+            };
+            try {
+                await reduce(async (ctx, hook) => runHook(hook, await ctx), Promise.resolve(hookContext), toolHooks.preHooks);
+            }
+            catch (error) {
+                // Pre-hook already handled messaging (e.g., require-tab pre-hook sets tabs section)
+                // Avoid adding a duplicate error line in the Result section.
+                return;
+            }
+            // Run original tool
+            let success = true;
+            try {
+                await tool.handle(context, params, response);
+            }
+            catch (error) {
+                success = false;
+                throw error;
+            }
+            finally {
+                // Record tool call completion
+                const executionTime = Date.now() - startTime;
+                trackEvent(context, {
+                    type: "tool-call",
+                    data: {
+                        toolName,
+                        params: params,
+                        executionTime,
+                        success,
+                    },
+                    timestamp: startTime,
+                });
+            }
+            // Run post-hooks
+            const postHookContext = {
+                context,
+                tab: context.currentTab(),
+                params,
+                toolName,
+                response,
+                eventStore: getEventStore(context),
+            };
+            try {
+                await reduce(async (ctx, hook) => runHook(hook, await ctx), Promise.resolve(postHookContext), toolHooks.postHooks);
+            }
+            catch (error) {
+                response.addError(error instanceof Error ? error.message : "Post-hook failed");
+            }
+            // Consume post-tool events
+            consumeEvents(context, eventStore, response);
+        },
+    };
+};
+export const getHookRegistry = (context) => {
+    const registry = hookRegistryMap.get(context);
+    return registry || createHookRegistry();
+};
+export const applyHooksToTools = (tools, context) => {
+    const registry = getHookRegistry(context);
+    if (registry.tools.size === 0)
+        return tools;
+    return tools.map((tool) => wrapToolWithHooks(tool, registry));
+};

package/lib/hooks/eventConsumer.js

@@ -0,0 +1,52 @@
+import { formatAntiBotEvent, getAntiBotProviderConfigs, } from "./antiBotDetectionHook.js";
+import { getEventsAfter, isEventType, updateLastSeenId } from "./events.js";
+import { formatToolCallEvent } from "./formatToolCallEvent.js";
+import { formatFrameworkStateEvent } from "./frameworkStateHook.js";
+import { planGroupedMessages } from "./grouping.js";
+import { formatJsonLdEvent } from "./jsonLdDetectionHook.js";
+import { isAntiBotUrl } from "./networkFilters.js";
+import { formatNetworkEvent } from "./networkTrackingHook.js";
+import { formatPageHeightEvent } from "./pageHeightHook.js";
+import { formatWaitEvent } from "./waitHook.js";
+const eventFormatters = {
+    wait: formatWaitEvent,
+    "page-height-change": formatPageHeightEvent,
+    "network-request": formatNetworkEvent,
+    "tool-call": formatToolCallEvent,
+    "framework-state": formatFrameworkStateEvent,
+    "json-ld": formatJsonLdEvent,
+    "anti-bot": formatAntiBotEvent,
+};
+const formatEvent = (event) => {
+    const formatter = eventFormatters[event.type];
+    return formatter(event);
+};
+const consumeEvent = (event, response, plan) => {
+    if (plan.skipIds.has(event.id))
+        return;
+    const replacement = plan.replacementById.get(event.id);
+    const formattedMessage = replacement ?? formatEvent(event);
+    response.addEvent(`[${event.id}] ${formattedMessage}`);
+};
+const shouldHideEvent = (event) => {
+    const isNetworkRequest = isEventType("network-request");
+    if (!isNetworkRequest(event))
+        return false;
+    if (isAntiBotUrl(event.data.url))
+        return true;
+    const configs = getAntiBotProviderConfigs().filter((config) => config.provider === "cloudflare-turnstile");
+    return configs.some((config) => config.match(event));
+};
+export const consumeEvents = (context, eventStore, response) => {
+    const unconsumedEvents = getEventsAfter(eventStore, eventStore.lastSeenEventId);
+    if (unconsumedEvents.length === 0)
+        return;
+    const visibleEvents = unconsumedEvents.filter((event) => !shouldHideEvent(event));
+    const plan = planGroupedMessages(visibleEvents);
+    // Consume all events in chronological order
+    for (const event of visibleEvents)
+        consumeEvent(event, response, plan);
+    // Update last seen event ID
+    const latestEvent = unconsumedEvents[unconsumedEvents.length - 1];
+    updateLastSeenId(context, latestEvent.id);
+};

package/lib/hooks/events.js

@@ -0,0 +1,42 @@
+import { filter, pipe, toArray } from "@fxts/core";
+export const isEventType = (type) => (event) => event.type === type;
+export const createEventStore = () => ({
+    events: new Map(),
+    lastSeenEventId: undefined,
+    nextEventId: 1,
+});
+export const trackEvent = (context, params) => {
+    const store = getEventStore(context);
+    const eventId = store.nextEventId++;
+    const event = {
+        id: eventId,
+        type: params.type,
+        data: params.data,
+        timestamp: params.timestamp ?? Date.now(),
+    };
+    store.events.set(eventId, event);
+    return eventId;
+};
+export const updateLastSeenId = (context, eventId) => {
+    const store = getEventStore(context);
+    store.lastSeenEventId = eventId;
+    return context;
+};
+export const getEventsAfter = (store, afterEventId) => {
+    if (!afterEventId) {
+        return pipe(store.events.values(), toArray);
+    }
+    return pipe(store.events.values(), filter((event) => event.id > afterEventId), toArray);
+};
+const eventStoreMap = new WeakMap();
+export const getEventStore = (context) => {
+    let store = eventStoreMap.get(context);
+    if (!store) {
+        store = createEventStore();
+        eventStoreMap.set(context, store);
+    }
+    return store;
+};
+export const setEventStore = (context, store) => {
+    eventStoreMap.set(context, store);
+};

package/lib/hooks/formatToolCallEvent.js

@@ -0,0 +1,12 @@
+export const formatToolCallEvent = (event) => {
+    const { toolName, params, executionTime, success } = event.data;
+    // Format parameters (truncate if too long)
+    const paramStr = params && Object.keys(params).length > 0
+        ? ` with params: ${JSON.stringify(params, null, 0).slice(0, 100)}`
+        : "";
+    // Format execution time if available
+    const timeStr = executionTime !== undefined ? ` (${executionTime}ms)` : "";
+    // Format success status if available
+    const statusStr = success !== undefined ? (success ? " ✓" : " ✗") : "";
+    return `Tool ${toolName}${paramStr}${timeStr}${statusStr}`;
+};

package/lib/hooks/frameworkStateHook.js

@@ -0,0 +1,182 @@
+import { FRAMEWORK_STATE_PATTERNS, MAX_DISPLAY_ITEMS, } from "../frameworkPatterns.js";
+import { Ok } from "../utils/result.js";
+import { trackEvent } from "./events.js";
+import { hookNameSchema } from "./schema.js";
+const pageFrameworkStates = new WeakMap();
+const seenFrameworkKeysByContext = new WeakMap();
+const getSeenFrameworkKeys = (context) => {
+    let set = seenFrameworkKeysByContext.get(context);
+    if (!set) {
+        set = new Set();
+        seenFrameworkKeysByContext.set(context, set);
+    }
+    return set;
+};
+export const frameworkStatePreHook = {
+    name: hookNameSchema.enum["framework-state-pre"],
+    handler: async (context) => {
+        const frameworkState = await detectFrameworkState(context);
+        if (frameworkState) {
+            // Store the initial state
+            if (context.tab?.page)
+                pageFrameworkStates.set(context.tab.page, frameworkState);
+            // Track event for newly detected framework state
+            const newKeys = Object.keys(frameworkState).filter((key) => !getSeenFrameworkKeys(context.context).has(key));
+            if (newKeys.length > 0) {
+                trackEvent(context.context, {
+                    type: "framework-state",
+                    data: {
+                        state: frameworkState,
+                        action: "detected",
+                    },
+                });
+                // Mark keys as seen
+                newKeys.forEach((key) => getSeenFrameworkKeys(context.context).add(key));
+            }
+        }
+        return Ok(undefined);
+    },
+};
+export const frameworkStatePostHook = {
+    name: hookNameSchema.enum["framework-state-post"],
+    handler: async (context) => {
+        const newFrameworkState = await detectFrameworkState(context);
+        const initialState = context.tab?.page
+            ? pageFrameworkStates.get(context.tab.page)
+            : undefined;
+        if (newFrameworkState) {
+            const changes = [];
+            if (initialState) {
+                // Compare states
+                const allKeys = new Set([
+                    ...Object.keys(initialState),
+                    ...Object.keys(newFrameworkState),
+                ]);
+                for (const key of allKeys) {
+                    const initVal = initialState[key];
+                    const currVal = newFrameworkState[key];
+                    if (!initVal && currVal)
+                        changes.push(`+ ${key}: ${formatValue(currVal)}`);
+                    else if (initVal && !currVal)
+                        changes.push(`- ${key}`);
+                    else if (initVal &&
+                        currVal &&
+                        JSON.stringify(initVal) !== JSON.stringify(currVal))
+                        changes.push(`~ ${key}: changed`);
+                }
+                if (changes.length > 0) {
+                    trackEvent(context.context, {
+                        type: "framework-state",
+                        data: {
+                            state: newFrameworkState,
+                            changes,
+                            action: "changed",
+                        },
+                    });
+                }
+            }
+            else {
+                // No initial state, but we have state now
+                const newKeys = Object.keys(newFrameworkState).filter((key) => !getSeenFrameworkKeys(context.context).has(key));
+                if (newKeys.length > 0) {
+                    trackEvent(context.context, {
+                        type: "framework-state",
+                        data: {
+                            state: newFrameworkState,
+                            action: "detected",
+                        },
+                    });
+                    newKeys.forEach((key) => getSeenFrameworkKeys(context.context).add(key));
+                }
+            }
+            // Update stored state
+            if (context.tab?.page)
+                pageFrameworkStates.set(context.tab.page, newFrameworkState);
+        }
+        return Ok(undefined);
+    },
+};
+async function detectFrameworkState(context) {
+    if (!context.tab?.page)
+        return null;
+    const result = await context.tab.page.evaluate((patterns) => {
+        const state = {};
+        const MAX_ITEMS = 5;
+        // Scan window object for these patterns
+        for (const pattern of patterns) {
+            if (pattern in window) {
+                try {
+                    const value = window[pattern];
+                    // Only capture if it's a non-empty object or has meaningful content
+                    if (value &&
+                        (typeof value === "object" || typeof value === "string")) {
+                        state[pattern] =
+                            typeof value === "object"
+                                ? {
+                                    type: "object",
+                                    keys: Object.keys(value).slice(0, MAX_ITEMS * 2),
+                                }
+                                : {
+                                    type: typeof value,
+                                    preview: String(value).slice(0, 200),
+                                };
+                    }
+                }
+                catch (e) {
+                    // Skip inaccessible properties
+                }
+            }
+        }
+        // Also check for React Fiber internals
+        const reactRootSelectors = [
+            "#__next",
+            "#root",
+            "#app",
+            "[data-reactroot]",
+        ];
+        for (const selector of reactRootSelectors) {
+            const element = document.querySelector(selector);
+            if (element) {
+                const fiberKey = Object.keys(element).find((key) => key.startsWith("__reactInternalInstance") ||
+                    key.startsWith("__reactFiber") ||
+                    key.startsWith("_reactRootContainer"));
+                if (fiberKey) {
+                    state["React Fiber Root"] = { selector, fiberKey };
+                    break;
+                }
+            }
+        }
+        return Object.keys(state).length > 0 ? state : null;
+    }, FRAMEWORK_STATE_PATTERNS);
+    return result;
+}
+function formatValue(value) {
+    if (typeof value === "object" && value !== null && "type" in value) {
+        if (value.type === "object" && "keys" in value && Array.isArray(value.keys))
+            return `{${value.keys.join(", ")}${value.keys.length >= MAX_DISPLAY_ITEMS * 2 ? ", ..." : ""}}`;
+        else if ("preview" in value && typeof value.preview === "string")
+            return `"${value.preview}${value.preview.length >= 200 ? "..." : ""}"`;
+    }
+    return JSON.stringify(value);
+}
+export const formatFrameworkStateEvent = (event) => {
+    const { state, changes, action } = event.data;
+    const messages = [];
+    if (action === "detected") {
+        messages.push("Framework state detected:");
+        const keys = Object.keys(state);
+        for (const key of keys) {
+            const value = state[key];
+            messages.push(`  ${key}: ${formatValue(value)}`);
+        }
+    }
+    else if (action === "changed" && changes) {
+        messages.push("Framework state changed:");
+        messages.push(...changes.map((change) => `  ${change}`));
+    }
+    return messages.join("\n");
+};
+export const frameworkStateHooks = {
+    pre: frameworkStatePreHook,
+    post: frameworkStatePostHook,
+};

package/lib/hooks/grouping.js

@@ -0,0 +1,72 @@
+const rules = new Map();
+// Helper to define a rule with typed callbacks without using type assertions in callers
+export const defineGroupingRule = (spec) => {
+    const { match } = spec;
+    return {
+        match,
+        keyOf: (e) => {
+            // Planner guarantees keyOf is only called when match(e) is true
+            if (!match(e))
+                return "";
+            return spec.keyOf(e);
+        },
+        summaryOf: (first, run) => {
+            // Build a typed run defensively using the provided type guard
+            const typedRun = [];
+            for (const ev of run) {
+                if (match(ev))
+                    typedRun.push(ev);
+            }
+            const typedFirst = match(first) ? first : typedRun[0];
+            if (!typedFirst)
+                return "";
+            return spec.summaryOf(typedFirst, typedRun);
+        },
+    };
+};
+export const registerGroupingRule = (type, rule) => {
+    rules.set(type, rule);
+};
+const getGroupingRule = (type) => {
+    return rules.get(type);
+};
+export const planGroupedMessages = (events) => {
+    const replacementById = new Map();
+    const skipIds = new Set();
+    let currentType;
+    let currentKey;
+    let run = [];
+    const flush = () => {
+        if (currentType && run.length > 1) {
+            const rule = getGroupingRule(currentType);
+            if (rule) {
+                const first = run[0];
+                const summary = rule.summaryOf(first, run);
+                replacementById.set(first.id, summary);
+                for (let i = 1; i < run.length; i++)
+                    skipIds.add(run[i].id);
+            }
+        }
+        currentType = undefined;
+        currentKey = undefined;
+        run = [];
+    };
+    for (const ev of events) {
+        const rule = getGroupingRule(ev.type);
+        if (!rule || !rule.match(ev)) {
+            flush();
+            continue;
+        }
+        const key = rule.keyOf(ev);
+        if (currentType === ev.type && currentKey === key) {
+            run.push(ev);
+            continue;
+        }
+        flush();
+        currentType = ev.type;
+        currentKey = key;
+        run = [ev];
+    }
+    flush();
+    return { replacementById, skipIds };
+};

package/lib/hooks/jsonLdDetectionHook.js

@@ -0,0 +1,182 @@
+import { Ok } from "../utils/result.js";
+import { trackEvent } from "./events.js";
+import { hookNameSchema } from "./schema.js";
+const MAX_DISPLAY_ITEMS = 5;
+const pageJsonLdStates = new WeakMap();
+const seenJsonLdTypesByContext = new WeakMap();
+const getSeenJsonLdTypes = (context) => {
+    let set = seenJsonLdTypesByContext.get(context);
+    if (!set) {
+        set = new Set();
+        seenJsonLdTypesByContext.set(context, set);
+    }
+    return set;
+};
+export const jsonLdDetectionPreHook = {
+    name: hookNameSchema.enum["json-ld-detection-pre"],
+    handler: async (context) => {
+        const jsonLdState = await detectJsonLdState(context);
+        if (jsonLdState) {
+            // Store the initial state
+            if (context.tab?.page)
+                pageJsonLdStates.set(context.tab.page, jsonLdState);
+            // Track event for newly detected JSON-LD types
+            const newTypes = Object.keys(jsonLdState).filter((type) => !getSeenJsonLdTypes(context.context).has(type));
+            if (newTypes.length > 0) {
+                trackEvent(context.context, {
+                    type: "json-ld",
+                    data: {
+                        state: jsonLdState,
+                        action: "detected",
+                    },
+                });
+                // Mark types as seen
+                newTypes.forEach((type) => getSeenJsonLdTypes(context.context).add(type));
+            }
+        }
+        return Ok(undefined);
+    },
+};
+export const jsonLdDetectionPostHook = {
+    name: hookNameSchema.enum["json-ld-detection-post"],
+    handler: async (context) => {
+        const newJsonLdState = await detectJsonLdState(context);
+        const initialState = context.tab?.page
+            ? pageJsonLdStates.get(context.tab.page)
+            : undefined;
+        if (newJsonLdState || initialState) {
+            const changes = [];
+            if (initialState && newJsonLdState) {
+                // Compare states
+                const allTypes = new Set([
+                    ...Object.keys(initialState),
+                    ...Object.keys(newJsonLdState),
+                ]);
+                for (const type of allTypes) {
+                    const initInfo = initialState[type];
+                    const currInfo = newJsonLdState[type];
+                    if (!initInfo && currInfo)
+                        changes.push(`+ ${type}${currInfo.count > 1 ? ` (${currInfo.count} instances)` : ""}`);
+                    else if (initInfo && !currInfo)
+                        changes.push(`- ${type}${initInfo.count > 1 ? ` (${initInfo.count} instances)` : ""}`);
+                    else if (initInfo && currInfo && initInfo.count !== currInfo.count)
+                        changes.push(`~ ${type}: ${initInfo.count} → ${currInfo.count} instances`);
+                }
+                if (changes.length > 0) {
+                    trackEvent(context.context, {
+                        type: "json-ld",
+                        data: {
+                            state: newJsonLdState,
+                            changes,
+                            action: "changed",
+                        },
+                    });
+                }
+            }
+            else if (newJsonLdState && !initialState) {
+                // No initial state, but we have state now
+                const newTypes = Object.keys(newJsonLdState).filter((type) => !getSeenJsonLdTypes(context.context).has(type));
+                if (newTypes.length > 0) {
+                    trackEvent(context.context, {
+                        type: "json-ld",
+                        data: {
+                            state: newJsonLdState,
+                            action: "detected",
+                        },
+                    });
+                    newTypes.forEach((type) => getSeenJsonLdTypes(context.context).add(type));
+                }
+            }
+            // Update stored state
+            if (context.tab?.page && newJsonLdState)
+                pageJsonLdStates.set(context.tab.page, newJsonLdState);
+        }
+        return Ok(undefined);
+    },
+};
+async function detectJsonLdState(context) {
+    if (!context.tab?.page)
+        return null;
+    const result = await context.tab.page.evaluate(() => {
+        const state = {};
+        // Find all JSON-LD scripts
+        const scripts = document.querySelectorAll('script[type="application/ld+json"]');
+        scripts.forEach((script, index) => {
+            try {
+                // Parse JSON
+                const data = JSON.parse(script.textContent || "{}");
+                // Extract @type - handle both single and array types
+                let types = [];
+                if (data["@type"]) {
+                    types = Array.isArray(data["@type"])
+                        ? data["@type"]
+                        : [data["@type"]];
+                }
+                else if (data["@graph"] && Array.isArray(data["@graph"])) {
+                    // Handle @graph structures
+                    data["@graph"].forEach((item) => {
+                        if (item["@type"]) {
+                            const itemTypes = Array.isArray(item["@type"])
+                                ? item["@type"]
+                                : [item["@type"]];
+                            types.push(...itemTypes);
+                        }
+                    });
+                }
+                // Count occurrences of each type
+                types.forEach((type) => {
+                    if (!state[type])
+                        state[type] = { count: 0, indices: [] };
+                    state[type].count++;
+                    state[type].indices.push(index);
+                });
+            }
+            catch (e) {
+                state["InvalidJSON-LD"] = state["InvalidJSON-LD"] || {
+                    count: 0,
+                    indices: [],
+                };
+                state["InvalidJSON-LD"].count++;
+                state["InvalidJSON-LD"].indices.push(index);
+            }
+        });
+        return Object.keys(state).length > 0 ? state : null;
+    });
+    return result;
+}
+function buildStateMessages(state, types) {
+    const msgs = [];
+    const targetTypes = types ?? Object.keys(state);
+    // Sort by count (descending) and take top MAX_DISPLAY_ITEMS
+    const sortedTypes = targetTypes
+        .sort((a, b) => (state[b].count || 0) - (state[a].count || 0))
+        .slice(0, MAX_DISPLAY_ITEMS);
+    for (const type of sortedTypes) {
+        const info = state[type];
+        if (info.count === 1)
+            msgs.push(`  ${type}`);
+        else
+            msgs.push(`  ${type} (${info.count} instances)`);
+    }
+    // Add indicator if there are more types
+    if (targetTypes.length > MAX_DISPLAY_ITEMS)
+        msgs.push(`  ... and ${targetTypes.length - MAX_DISPLAY_ITEMS} more type(s)`);
+    return msgs;
+}
+export const formatJsonLdEvent = (event) => {
+    const { state, changes, action } = event.data;
+    const messages = [];
+    if (action === "detected") {
+        messages.push("New JSON-LD types detected:");
+        messages.push(...buildStateMessages(state));
+    }
+    else if (action === "changed" && changes) {
+        messages.push("JSON-LD changes after action:");
+        messages.push(...changes.map((change) => `  ${change}`));
+    }
+    return messages.join("\n");
+};
+export const jsonLdDetectionHooks = {
+    pre: jsonLdDetectionPreHook,
+    post: jsonLdDetectionPostHook,
+};