@wordbricks/playwright-mcp 0.1.25 → 0.1.27

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,
+};

package/lib/hooks/networkFilters.js

@@ -0,0 +1,82 @@
+const MEANINGFUL_RESOURCE_TYPES = ["document", "xhr", "fetch"];
+const ALLOWED_METHODS = ["GET", "POST"];
+const EXCLUDED_EXTENSIONS = [
+    ".svg",
+    ".css",
+    ".map", // JS files and source maps
+];
+const hasExcludedExtension = (url) => {
+    return EXCLUDED_EXTENSIONS.some((ext) => {
+        const extRegex = new RegExp(`${ext.replace(".", "\\.")}(\\?|#|$)`, "i");
+        return extRegex.test(url);
+    });
+};
+export const isAntiBotUrl = (url) => {
+    if (url.includes("challenges.cloudflare.com"))
+        return true;
+    if (url.includes(".awswaf.com"))
+        return true;
+    return false;
+};
+const isSuccessfulStatus = (status) => {
+    // Status 0 is for failed requests, which we want to capture
+    // 2xx status codes are successful
+    // Exclude 204 No Content
+    return status === 0 || (status >= 200 && status < 300 && status !== 204);
+};
+export const shouldCaptureRequest = (method, url, status, resourceType) => {
+    if (isAntiBotUrl(url))
+        return true;
+    return (!hasExcludedExtension(url) &&
+        MEANINGFUL_RESOURCE_TYPES.includes(resourceType) &&
+        ALLOWED_METHODS.includes(method) &&
+        isSuccessfulStatus(status));
+};
+/**
+ * Format URL with trimmed parameters
+ */
+export const formatUrlWithTrimmedParams = (url) => {
+    try {
+        const urlObj = new URL(url);
+        const params = urlObj.searchParams;
+        if (params.toString()) {
+            const trimmedParams = new URLSearchParams();
+            params.forEach((value, key) => {
+                if (value.length > 5)
+                    trimmedParams.set(key, value.substring(0, 5) + "...");
+                else
+                    trimmedParams.set(key, value);
+            });
+            return `${urlObj.origin}${urlObj.pathname}?${trimmedParams.toString()}`;
+        }
+        return url;
+    }
+    catch {
+        // If URL parsing fails, return as is
+        return url;
+    }
+};
+/**
+ * Normalize a pathname by removing trailing slashes (except root)
+ */
+export const normalizePathname = (pathname) => {
+    if (!pathname)
+        return "/";
+    if (pathname === "/")
+        return "/";
+    return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+};
+/**
+ * Normalize URL for grouping by ignoring query/hash and trailing slash
+ */
+export const normalizeUrlForGrouping = (url) => {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${normalizePathname(u.pathname)}`;
+    }
+    catch {
+        // Fallback for non-standard/relative URLs: strip query/hash and trailing slash
+        const base = url.split(/[?#]/)[0] || "/";
+        return normalizePathname(base);
+    }
+};

package/lib/hooks/networkSetup.js

@@ -0,0 +1,61 @@
+import { trackEvent } from "./events.js";
+import { shouldCaptureRequest } from "./networkFilters.js";
+const eventIdToEntryMap = new WeakMap();
+const getEventIdMap = (context) => {
+    let map = eventIdToEntryMap.get(context);
+    if (!map) {
+        map = new Map();
+        eventIdToEntryMap.set(context, map);
+    }
+    return map;
+};
+export const getNetworkEventEntry = (context, id) => getEventIdMap(context).get(id);
+export const setupNetworkTracking = (context, page) => {
+    page.on("response", async (response) => {
+        const request = response.request();
+        const method = request.method();
+        const url = request.url();
+        const status = response.status();
+        const resourceType = request.resourceType();
+        // Apply filters before saving the event
+        if (shouldCaptureRequest(method, url, status, resourceType)) {
+            const setCookies = await response
+                .headerValues("set-cookie")
+                .catch(() => []);
+            const cookieValues = setCookies.length ? setCookies : undefined;
+            const networkData = {
+                method,
+                url,
+                status,
+                resourceType,
+                postData: request.postData() || undefined,
+                setCookies: cookieValues,
+            };
+            const id = trackEvent(context, {
+                type: "network-request",
+                data: networkData,
+            });
+            getEventIdMap(context).set(id, { request, response });
+        }
+    });
+    page.on("requestfailed", (request) => {
+        const method = request.method();
+        const url = request.url();
+        const status = 0; // Failed requests have status 0
+        const resourceType = request.resourceType();
+        if (shouldCaptureRequest(method, url, status, resourceType)) {
+            const networkData = {
+                method,
+                url,
+                status,
+                resourceType,
+                postData: request.postData() || undefined,
+            };
+            const id = trackEvent(context, {
+                type: "network-request",
+                data: networkData,
+            });
+            getEventIdMap(context).set(id, { request });
+        }
+    });
+};

package/lib/hooks/networkTrackingHook.js

@@ -0,0 +1,67 @@
+import { filter, pipe, toArray } from "@fxts/core";
+import { parseGraphQLRequestFromHttp } from "../utils/graphql.js";
+import { formatNetworkSummaryLine } from "../utils/networkFormat.js";
+import { Ok } from "../utils/result.js";
+import { getEventStore, isEventType } from "./events.js";
+import { defineGroupingRule } from "./grouping.js";
+import { normalizeUrlForGrouping } from "./networkFilters.js";
+import { hookNameSchema } from "./schema.js";
+const networkTrackingPreHook = {
+    name: hookNameSchema.enum["network-tracking-pre"],
+    handler: async (_ctx) => {
+        // Pre-hook now just acts as a marker, event consumption happens elsewhere
+        return Ok(undefined);
+    },
+};
+const networkTrackingPostHook = {
+    name: hookNameSchema.enum["network-tracking-post"],
+    handler: async (_ctx) => {
+        // Post-hook now just acts as a marker, network event collection happens automatically
+        return Ok(undefined);
+    },
+};
+export const networkTrackingHooks = {
+    pre: networkTrackingPreHook,
+    post: networkTrackingPostHook,
+};
+export const formatNetworkEvent = (event) => {
+    const { method, url, status, postData, setCookies } = event.data;
+    const summary = formatNetworkSummaryLine({ method, url, status, postData });
+    if (!setCookies || setCookies.length === 0)
+        return summary;
+    const names = setCookies
+        .map((cookie) => {
+        const firstPart = cookie.split(";", 1)[0];
+        const [name] = firstPart.split("=", 1);
+        return name?.trim();
+    })
+        .filter((name) => !!name);
+    if (!names.length)
+        return summary;
+    return `${summary} | Set-Cookie keys: ${names.join(", ")}`;
+};
+const computeNetworkGroupKey = (event) => {
+    const method = (event.data.method || "").toUpperCase();
+    const baseUrl = normalizeUrlForGrouping(event.data.url);
+    const gql = parseGraphQLRequestFromHttp(event.data.method, event.data.url, {}, event.data.postData);
+    if (gql) {
+        const type = gql.operationType === "unknown" ? "operation" : gql.operationType;
+        const op = gql.operationName ? `${type} ${gql.operationName}` : type;
+        return `${method} ${baseUrl} [GraphQL: ${op}]`;
+    }
+    return `${method} ${baseUrl}`;
+};
+export const networkGroupingRule = defineGroupingRule({
+    match: (e) => e.type === "network-request",
+    keyOf: (e) => computeNetworkGroupKey(e),
+    summaryOf: (first, run) => {
+        const key = computeNetworkGroupKey(first);
+        const count = run.length;
+        const firstStatus = first.data.status;
+        const allSameStatus = run.every((e) => e.data.status === firstStatus);
+        return allSameStatus
+            ? `${key} → ${firstStatus} (x${count})`
+            : `${key} (x${count})`;
+    },
+});
+export const listNetworkEvents = (context) => pipe(context, getEventStore, (store) => store.events.values(), filter(isEventType("network-request")), toArray);