framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/tools/compare.d.ts

@@ -20,6 +20,7 @@ export declare const compareInputShape: {
         width?: number | undefined;
         height?: number | undefined;
     }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
 };
 export declare const compareInputSchema: z.ZodObject<{
     url_a: z.ZodEffects<z.ZodString, string, string>;
@@ -37,6 +38,7 @@ export declare const compareInputSchema: z.ZodObject<{
         width?: number | undefined;
         height?: number | undefined;
     }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     wait_ms: number;
     wait_for_timeout_ms: number;
@@ -47,6 +49,7 @@ export declare const compareInputSchema: z.ZodObject<{
         height: number;
     } | undefined;
     wait_for?: string | undefined;
+    storage_state?: string | undefined;
 }, {
     url_a: string;
     url_b: string;
@@ -57,6 +60,7 @@ export declare const compareInputSchema: z.ZodObject<{
     wait_ms?: number | undefined;
     wait_for?: string | undefined;
     wait_for_timeout_ms?: number | undefined;
+    storage_state?: string | undefined;
 }>;
 export type CompareInput = z.input<typeof compareInputSchema>;
 type ParsedCompareInput = z.output<typeof compareInputSchema>;

package/dist/tools/compare.js

@@ -3,6 +3,7 @@ import { CROP_PADDING_PX, DEFAULT_COMPARE_WAIT_MS, DEFAULT_VIEWPORT, MAX_VIEWPOR
 import { getSessionPage, withPage, withSessionLock } from "../engine/browser.js";
 import { computePixelMask, padBoundingBox } from "../engine/differ.js";
 import { getDimensions, overlayMask, resizeForOutput, toBase64, toGrayscale } from "../utils/image.js";
+import { resolveStorageState, storageStateField, withAuthNote } from "../utils/storage-state.js";
 export const COMPARE_TOOL_NAME = "framewatch_compare";
 /** `url_a` accepts this instead of a URL, meaning "whatever framewatch_interact is looking at". */
 export const CURRENT_PAGE = "current";
@@ -38,6 +39,7 @@ export const compareInputShape = {
     })
         .optional()
         .describe("Viewport for both sides (defaults to 1280x720, or the open page's size when comparing against `current`)"),
+    storage_state: storageStateField,
 };
 export const compareInputSchema = z.object(compareInputShape);
 /**
@@ -69,7 +71,12 @@ export async function comparePages(rawInput) {
     const openIsB = input.url_b === CURRENT_PAGE && input.url_a !== CURRENT_PAGE;
     const [firstSide, secondSide] = openIsB ? [input.url_b, input.url_a] : [input.url_a, input.url_b];
     try {
-        const first = await captureSide(input, firstSide);
+        // Both URL sides get the same saved auth: they are two views of one app,
+        // and a comparison where only one side is signed in compares the login
+        // screen with the app. ("current" is read as it is, never reloaded.)
+        const auth = await resolveStorageState(input.storage_state);
+        const storageState = auth?.state;
+        const first = await captureSide(input, firstSide, undefined, storageState);
         const notes = [];
         let viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };
         if (firstSide === CURRENT_PAGE) {
@@ -81,9 +88,9 @@ export async function comparePages(rawInput) {
             }
             viewport = open;
         }
-        const second = await captureSide(input, secondSide, viewport);
+        const second = await captureSide(input, secondSide, viewport, storageState);
         const [a, b] = openIsB ? [second, first] : [first, second];
-        return await render(input, a, b, notes);
+        return withAuthNote(await render(input, a, b, notes), auth);
     }
     catch (error) {
         return errorResult(describeCompareFailure(input, error));
@@ -99,7 +106,7 @@ export async function comparePages(rawInput) {
  * flow — against a plain URL, and reloading or resizing it would destroy the
  * very thing being compared.
  */
-async function captureSide(input, side, viewport) {
+async function captureSide(input, side, viewport, storageState) {
     if (side === CURRENT_PAGE) {
         // Under the session lock: an interaction running in parallel would
         // otherwise be screenshotted half way through.
@@ -112,7 +119,11 @@ async function captureSide(input, side, viewport) {
             return { png: await page.screenshot({ type: "png" }), url: page.url(), title: await safeTitle(page) };
         });
     }
-    return withPage({ viewport: viewport ?? input.viewport ?? { ...DEFAULT_VIEWPORT } }, async (page) => {
+    const options = {
+        viewport: viewport ?? input.viewport ?? { ...DEFAULT_VIEWPORT },
+        ...(storageState ? { contextOptions: { storageState } } : {}),
+    };
+    return withPage(options, async (page) => {
         await page.goto(side, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
         if (input.wait_for) {
             await page.waitForSelector(input.wait_for, { state: "visible", timeout: input.wait_for_timeout_ms });

package/dist/tools/compare.js.map

@@ -1 +1 @@
-{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/tools/compare.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { Page } from \"playwright\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  CROP_PADDING_PX,\n  DEFAULT_COMPARE_WAIT_MS,\n  DEFAULT_VIEWPORT,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  NAVIGATION_TIMEOUT_MS,\n  PAGE_INFO_TIMEOUT_MS,\n  SELECTOR_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { getSessionPage, withPage, withSessionLock } from \"../engine/browser.js\";\nimport { computePixelMask, padBoundingBox } from \"../engine/differ.js\";\nimport type { BoundingBox, Viewport } from \"../types.js\";\nimport { getDimensions, overlayMask, resizeForOutput, toBase64, toGrayscale } from \"../utils/image.js\";\n\nexport const COMPARE_TOOL_NAME = \"framewatch_compare\";\n\n/** `url_a` accepts this instead of a URL, meaning \"whatever framewatch_interact is looking at\". */\nexport const CURRENT_PAGE = \"current\";\n\n/**\n * Either a URL or the literal \"current\". `z.string().url()` cannot express\n * that, so the check is spelled out — and the message says both options,\n * because \"invalid url\" on the word `current` is a confusing thing to read.\n */\nconst sideSchema = z.string().refine((value) => value === CURRENT_PAGE || isUrl(value), {\n  message: `must be a URL, or \"${CURRENT_PAGE}\" to use the page framewatch_interact currently has open`,\n});\n\nexport const compareInputShape = {\n  url_a: sideSchema.describe(\n    `First URL — the \"before\" side. Pass \"${CURRENT_PAGE}\" to compare against the page framewatch_interact has open, ` +\n      \"in whatever state your interactions left it.\",\n  ),\n  url_b: sideSchema.describe('Second URL — the \"after\" side.'),\n  wait_ms: z\n    .number()\n    .int()\n    .min(0)\n    .default(DEFAULT_COMPARE_WAIT_MS)\n    .describe(\"Wait time (ms) after page load before each screenshot\"),\n  wait_for: z.string().optional().describe(\"CSS selector to wait for (visible) on both sides before capturing\"),\n  wait_for_timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .default(SELECTOR_TIMEOUT_MS)\n    .describe(\"Max time (ms) to wait for `wait_for` to appear (must be > 0)\"),\n  viewport: z\n    .object({\n      width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH).default(DEFAULT_VIEWPORT.width),\n      height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT).default(DEFAULT_VIEWPORT.height),\n    })\n    .optional()\n    .describe(\"Viewport for both sides (defaults to 1280x720, or the open page's size when comparing against `current`)\"),\n};\n\nexport const compareInputSchema = z.object(compareInputShape);\nexport type CompareInput = z.input<typeof compareInputSchema>;\ntype ParsedCompareInput = z.output<typeof compareInputSchema>;\n\n/** One captured side of the comparison. */\ninterface Side {\n  png: Buffer;\n  /** Where the shot was actually taken (after redirects), or the open page's URL. */\n  url: string;\n  title?: string;\n}\n\n/**\n * Compare two pages — or the same page before and after a change — and show\n * what moved.\n *\n * Returns both screenshots plus an overlay: side B with every differing pixel\n * tinted, which is the part that turns \"3.4% changed\" into something a reader\n * can act on. The comparison is the same pixel comparison the capture engine\n * uses between frames, so a change region here means what it means there.\n *\n * The two sides are captured one after the other rather than at once, so both\n * get an unloaded machine and the same `wait_ms` means the same thing for\n * each; a difference in the result should come from the pages, not from which\n * of them was competing for the CPU. (Which of the two goes first is decided\n * by `\"current\"` — see below — not by their order in the input.)\n */\nexport async function comparePages(rawInput: CompareInput): Promise<CallToolResult> {\n  const parsed = compareInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Compare failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n\n  // The open page is the one side that cannot be resized — doing so would\n  // change the state being compared — so it is captured first whichever side\n  // it is, and its size is what the other side is then captured at. Frames of\n  // two different sizes cannot be compared pixel for pixel at all.\n  const openIsB = input.url_b === CURRENT_PAGE && input.url_a !== CURRENT_PAGE;\n  const [firstSide, secondSide] = openIsB ? [input.url_b, input.url_a] : [input.url_a, input.url_b];\n\n  try {\n    const first = await captureSide(input, firstSide);\n    const notes: string[] = [];\n    let viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };\n\n    if (firstSide === CURRENT_PAGE) {\n      const open = await sizeOf(first.png);\n      if (input.viewport && (input.viewport.width !== open.width || input.viewport.height !== open.height)) {\n        notes.push(\n          `Ignored \\`viewport\\` ${input.viewport.width}x${input.viewport.height}: the open page is ` +\n            `${open.width}x${open.height} and resizing it would change the state being compared. ` +\n            \"Both sides were captured at the open page's size.\",\n        );\n      }\n      viewport = open;\n    }\n\n    const second = await captureSide(input, secondSide, viewport);\n    const [a, b] = openIsB ? [second, first] : [first, second];\n    return await render(input, a, b, notes);\n  } catch (error) {\n    return errorResult(describeCompareFailure(input, error));\n  }\n}\n\n/**\n * Screenshot one side.\n *\n * A URL gets a fresh context, so nothing from the other side (or from an\n * earlier tool call) can leak into it. \"current\" instead reads the page\n * `framewatch_interact` has open, *without* touching it: the whole point of\n * that option is to compare a hand-built state — three clicks deep into a\n * flow — against a plain URL, and reloading or resizing it would destroy the\n * very thing being compared.\n */\nasync function captureSide(input: ParsedCompareInput, side: string, viewport?: Viewport): Promise<Side> {\n  if (side === CURRENT_PAGE) {\n    // Under the session lock: an interaction running in parallel would\n    // otherwise be screenshotted half way through.\n    return withSessionLock(async () => {\n      const { page } = await getSessionPage();\n      if (page.url() === \"about:blank\") {\n        throw new Error(\n          `no page is open, so there is no \"${CURRENT_PAGE}\" state to compare — ` +\n            \"use framewatch_interact first, or pass a URL here.\",\n        );\n      }\n      return { png: await page.screenshot({ type: \"png\" }), url: page.url(), title: await safeTitle(page) };\n    });\n  }\n\n  return withPage({ viewport: viewport ?? input.viewport ?? { ...DEFAULT_VIEWPORT } }, async (page) => {\n    await page.goto(side, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n    if (input.wait_for) {\n      await page.waitForSelector(input.wait_for, { state: \"visible\", timeout: input.wait_for_timeout_ms });\n    }\n    if (input.wait_ms > 0) {\n      await page.waitForTimeout(input.wait_ms);\n    }\n    return { png: await page.screenshot({ type: \"png\" }), url: page.url(), title: await safeTitle(page) };\n  });\n}\n\n/**\n * Build the result: a summary, both frames, and (when the two are comparable\n * and actually differ) the overlay.\n *\n * Sides of different sizes are reported as such rather than being stretched to\n * match. Rescaling one of them would resample every pixel in it, and the\n * \"differences\" that came back would be the resampling, not the pages.\n */\nasync function render(input: ParsedCompareInput, a: Side, b: Side, notes: string[]): Promise<CallToolResult> {\n  const [grayA, grayB] = await Promise.all([toGrayscale(a.png), toGrayscale(b.png)]);\n  const nameA = describeSide(input.url_a, a);\n  const nameB = describeSide(input.url_b, b);\n  const sameSize = grayA.width === grayB.width && grayA.height === grayB.height;\n\n  const lines: string[] = [];\n  let overlay: Buffer | undefined;\n  let overlayNote = \"\";\n\n  if (!sameSize) {\n    lines.push(\n      `Compared ${nameA} against ${nameB} — the two frames are different sizes ` +\n        `(${grayA.width}x${grayA.height} vs ${grayB.width}x${grayB.height}), so they cannot be compared pixel ` +\n        \"for pixel. Both are below.\",\n    );\n  } else {\n    const diff = computePixelMask(grayA.data, grayB.data, grayA.width, grayA.height);\n    const region: BoundingBox | null =\n      diff.bbox === null ? null : padBoundingBox(diff.bbox, CROP_PADDING_PX, grayA.width, grayA.height);\n\n    lines.push(\n      `Compared ${nameA} against ${nameB} at ${grayA.width}x${grayA.height} — ` +\n        `${diff.changePercent.toFixed(2)}% of pixels differ` +\n        (region === null\n          ? \". The two are pixel-identical.\"\n          : `, all of it within ${region.x},${region.y} ${region.width}x${region.height}.`),\n    );\n\n    if (region !== null) {\n      overlay = await resizeForOutput(await overlayMask(b.png, diff.mask, grayA.width, grayA.height));\n      overlayNote =\n        `Diff overlay — B with every differing pixel tinted. ${diff.changedPixels} of ${diff.totalPixels} ` +\n        `pixels changed (${diff.changePercent.toFixed(2)}%), within ` +\n        `${region.x},${region.y} ${region.width}x${region.height}.`;\n    }\n  }\n\n  const content: CallToolResult[\"content\"] = [{ type: \"text\", text: [...lines, ...notes].join(\"\\n\") }];\n  await pushFrame(content, a.png, `A — ${nameA}`);\n  await pushFrame(content, b.png, `B — ${nameB}`);\n  if (overlay) {\n    content.push({ type: \"image\", data: toBase64(overlay), mimeType: \"image/png\" });\n    content.push({ type: \"text\", text: overlayNote });\n  }\n  return { content };\n}\n\nasync function pushFrame(content: CallToolResult[\"content\"], png: Buffer, label: string): Promise<void> {\n  const resized = await resizeForOutput(png);\n  const { width, height } = await getDimensions(resized);\n  content.push({ type: \"image\", data: toBase64(resized), mimeType: \"image/png\" });\n  content.push({ type: \"text\", text: `${label} — image ${width}x${height}` });\n}\n\n/** How a side is named in the output: where it ended up, and its title if it has one. */\nfunction describeSide(requested: string, side: Side): string {\n  const where = requested === CURRENT_PAGE ? `the open page (${side.url})` : side.url;\n  return side.title ? `${where} \"${side.title}\"` : where;\n}\n\n/** Cosmetic, and never allowed to fail or stall: a busy page still gets compared. */\nasync function safeTitle(page: Page): Promise<string | undefined> {\n  return Promise.race([\n    page.title().catch(() => undefined),\n    new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), PAGE_INFO_TIMEOUT_MS)),\n  ]);\n}\n\nasync function sizeOf(png: Buffer): Promise<Viewport> {\n  const { width, height } = await getDimensions(png);\n  return { width, height };\n}\n\nfunction isUrl(value: string): boolean {\n  try {\n    new URL(value);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * One actionable line for a failed comparison. Mirrors `describeFailure` in\n * screenshot.ts, with one addition: a `page.goto` failure names which of the\n * two sides could not be opened, which is the first thing you want to know.\n */\nexport function describeCompareFailure(\n  input: Pick<ParsedCompareInput, \"url_a\" | \"url_b\" | \"wait_for\" | \"wait_for_timeout_ms\">,\n  error: unknown,\n): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n  const prefix = \"Compare failed:\";\n\n  if (/Executable doesn't exist|browserType\\.launch/i.test(message)) {\n    return (\n      `${prefix} Playwright's Chromium browser is not installed. ` +\n      `Run \\`npx playwright install chromium\\` and try again. (${firstLine})`\n    );\n  }\n  if (/^page\\.goto:/.test(message)) {\n    const side = failingSide(input, message);\n    return `${prefix} could not open ${side} — ${firstLine}`;\n  }\n  if (input.wait_for && /^page\\.waitForSelector:/.test(message)) {\n    return `${prefix} selector \"${input.wait_for}\" did not become visible within ${input.wait_for_timeout_ms}ms.`;\n  }\n  return `${prefix} ${firstLine}`;\n}\n\n/** Playwright quotes the URL it tried in a goto failure; that says which side broke. */\nfunction failingSide(input: Pick<ParsedCompareInput, \"url_a\" | \"url_b\">, message: string): string {\n  if (input.url_b !== CURRENT_PAGE && message.includes(input.url_b)) return `url_b (${input.url_b})`;\n  if (input.url_a !== CURRENT_PAGE && message.includes(input.url_a)) return `url_a (${input.url_a})`;\n  return \"one of the two pages\";\n}\n\nexport function registerCompareTool(server: McpServer): void {\n  server.registerTool(\n    COMPARE_TOOL_NAME,\n    {\n      title: \"Compare\",\n      description:\n        \"Compare two pages — two URLs, or the same URL before and after a code change — and show what moved. \" +\n        \"Returns both screenshots, the percentage of pixels that differ, the region they differ in, and an \" +\n        `overlay of the second page with every changed pixel tinted. Pass \"${CURRENT_PAGE}\" as \\`url_a\\` to ` +\n        \"compare against the page framewatch_interact has open, in whatever state your interactions left it.\",\n      inputSchema: compareInputShape,\n      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => comparePages(args),\n  );\n}\n"]}
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/tools/compare.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { Page } from \"playwright\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  CROP_PADDING_PX,\n  DEFAULT_COMPARE_WAIT_MS,\n  DEFAULT_VIEWPORT,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  NAVIGATION_TIMEOUT_MS,\n  PAGE_INFO_TIMEOUT_MS,\n  SELECTOR_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { getSessionPage, withPage, withSessionLock } from \"../engine/browser.js\";\nimport { computePixelMask, padBoundingBox } from \"../engine/differ.js\";\nimport type { BoundingBox, Viewport } from \"../types.js\";\nimport { getDimensions, overlayMask, resizeForOutput, toBase64, toGrayscale } from \"../utils/image.js\";\nimport { resolveStorageState, storageStateField, withAuthNote, type StorageState } from \"../utils/storage-state.js\";\n\nexport const COMPARE_TOOL_NAME = \"framewatch_compare\";\n\n/** `url_a` accepts this instead of a URL, meaning \"whatever framewatch_interact is looking at\". */\nexport const CURRENT_PAGE = \"current\";\n\n/**\n * Either a URL or the literal \"current\". `z.string().url()` cannot express\n * that, so the check is spelled out — and the message says both options,\n * because \"invalid url\" on the word `current` is a confusing thing to read.\n */\nconst sideSchema = z.string().refine((value) => value === CURRENT_PAGE || isUrl(value), {\n  message: `must be a URL, or \"${CURRENT_PAGE}\" to use the page framewatch_interact currently has open`,\n});\n\nexport const compareInputShape = {\n  url_a: sideSchema.describe(\n    `First URL — the \"before\" side. Pass \"${CURRENT_PAGE}\" to compare against the page framewatch_interact has open, ` +\n      \"in whatever state your interactions left it.\",\n  ),\n  url_b: sideSchema.describe('Second URL — the \"after\" side.'),\n  wait_ms: z\n    .number()\n    .int()\n    .min(0)\n    .default(DEFAULT_COMPARE_WAIT_MS)\n    .describe(\"Wait time (ms) after page load before each screenshot\"),\n  wait_for: z.string().optional().describe(\"CSS selector to wait for (visible) on both sides before capturing\"),\n  wait_for_timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .default(SELECTOR_TIMEOUT_MS)\n    .describe(\"Max time (ms) to wait for `wait_for` to appear (must be > 0)\"),\n  viewport: z\n    .object({\n      width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH).default(DEFAULT_VIEWPORT.width),\n      height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT).default(DEFAULT_VIEWPORT.height),\n    })\n    .optional()\n    .describe(\"Viewport for both sides (defaults to 1280x720, or the open page's size when comparing against `current`)\"),\n  storage_state: storageStateField,\n};\n\nexport const compareInputSchema = z.object(compareInputShape);\nexport type CompareInput = z.input<typeof compareInputSchema>;\ntype ParsedCompareInput = z.output<typeof compareInputSchema>;\n\n/** One captured side of the comparison. */\ninterface Side {\n  png: Buffer;\n  /** Where the shot was actually taken (after redirects), or the open page's URL. */\n  url: string;\n  title?: string;\n}\n\n/**\n * Compare two pages — or the same page before and after a change — and show\n * what moved.\n *\n * Returns both screenshots plus an overlay: side B with every differing pixel\n * tinted, which is the part that turns \"3.4% changed\" into something a reader\n * can act on. The comparison is the same pixel comparison the capture engine\n * uses between frames, so a change region here means what it means there.\n *\n * The two sides are captured one after the other rather than at once, so both\n * get an unloaded machine and the same `wait_ms` means the same thing for\n * each; a difference in the result should come from the pages, not from which\n * of them was competing for the CPU. (Which of the two goes first is decided\n * by `\"current\"` — see below — not by their order in the input.)\n */\nexport async function comparePages(rawInput: CompareInput): Promise<CallToolResult> {\n  const parsed = compareInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Compare failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n\n  // The open page is the one side that cannot be resized — doing so would\n  // change the state being compared — so it is captured first whichever side\n  // it is, and its size is what the other side is then captured at. Frames of\n  // two different sizes cannot be compared pixel for pixel at all.\n  const openIsB = input.url_b === CURRENT_PAGE && input.url_a !== CURRENT_PAGE;\n  const [firstSide, secondSide] = openIsB ? [input.url_b, input.url_a] : [input.url_a, input.url_b];\n\n  try {\n    // Both URL sides get the same saved auth: they are two views of one app,\n    // and a comparison where only one side is signed in compares the login\n    // screen with the app. (\"current\" is read as it is, never reloaded.)\n    const auth = await resolveStorageState(input.storage_state);\n    const storageState = auth?.state;\n\n    const first = await captureSide(input, firstSide, undefined, storageState);\n    const notes: string[] = [];\n    let viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };\n\n    if (firstSide === CURRENT_PAGE) {\n      const open = await sizeOf(first.png);\n      if (input.viewport && (input.viewport.width !== open.width || input.viewport.height !== open.height)) {\n        notes.push(\n          `Ignored \\`viewport\\` ${input.viewport.width}x${input.viewport.height}: the open page is ` +\n            `${open.width}x${open.height} and resizing it would change the state being compared. ` +\n            \"Both sides were captured at the open page's size.\",\n        );\n      }\n      viewport = open;\n    }\n\n    const second = await captureSide(input, secondSide, viewport, storageState);\n    const [a, b] = openIsB ? [second, first] : [first, second];\n    return withAuthNote(await render(input, a, b, notes), auth);\n  } catch (error) {\n    return errorResult(describeCompareFailure(input, error));\n  }\n}\n\n/**\n * Screenshot one side.\n *\n * A URL gets a fresh context, so nothing from the other side (or from an\n * earlier tool call) can leak into it. \"current\" instead reads the page\n * `framewatch_interact` has open, *without* touching it: the whole point of\n * that option is to compare a hand-built state — three clicks deep into a\n * flow — against a plain URL, and reloading or resizing it would destroy the\n * very thing being compared.\n */\nasync function captureSide(\n  input: ParsedCompareInput,\n  side: string,\n  viewport?: Viewport,\n  storageState?: StorageState,\n): Promise<Side> {\n  if (side === CURRENT_PAGE) {\n    // Under the session lock: an interaction running in parallel would\n    // otherwise be screenshotted half way through.\n    return withSessionLock(async () => {\n      const { page } = await getSessionPage();\n      if (page.url() === \"about:blank\") {\n        throw new Error(\n          `no page is open, so there is no \"${CURRENT_PAGE}\" state to compare — ` +\n            \"use framewatch_interact first, or pass a URL here.\",\n        );\n      }\n      return { png: await page.screenshot({ type: \"png\" }), url: page.url(), title: await safeTitle(page) };\n    });\n  }\n\n  const options = {\n    viewport: viewport ?? input.viewport ?? { ...DEFAULT_VIEWPORT },\n    ...(storageState ? { contextOptions: { storageState } } : {}),\n  };\n  return withPage(options, async (page) => {\n    await page.goto(side, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n    if (input.wait_for) {\n      await page.waitForSelector(input.wait_for, { state: \"visible\", timeout: input.wait_for_timeout_ms });\n    }\n    if (input.wait_ms > 0) {\n      await page.waitForTimeout(input.wait_ms);\n    }\n    return { png: await page.screenshot({ type: \"png\" }), url: page.url(), title: await safeTitle(page) };\n  });\n}\n\n/**\n * Build the result: a summary, both frames, and (when the two are comparable\n * and actually differ) the overlay.\n *\n * Sides of different sizes are reported as such rather than being stretched to\n * match. Rescaling one of them would resample every pixel in it, and the\n * \"differences\" that came back would be the resampling, not the pages.\n */\nasync function render(input: ParsedCompareInput, a: Side, b: Side, notes: string[]): Promise<CallToolResult> {\n  const [grayA, grayB] = await Promise.all([toGrayscale(a.png), toGrayscale(b.png)]);\n  const nameA = describeSide(input.url_a, a);\n  const nameB = describeSide(input.url_b, b);\n  const sameSize = grayA.width === grayB.width && grayA.height === grayB.height;\n\n  const lines: string[] = [];\n  let overlay: Buffer | undefined;\n  let overlayNote = \"\";\n\n  if (!sameSize) {\n    lines.push(\n      `Compared ${nameA} against ${nameB} — the two frames are different sizes ` +\n        `(${grayA.width}x${grayA.height} vs ${grayB.width}x${grayB.height}), so they cannot be compared pixel ` +\n        \"for pixel. Both are below.\",\n    );\n  } else {\n    const diff = computePixelMask(grayA.data, grayB.data, grayA.width, grayA.height);\n    const region: BoundingBox | null =\n      diff.bbox === null ? null : padBoundingBox(diff.bbox, CROP_PADDING_PX, grayA.width, grayA.height);\n\n    lines.push(\n      `Compared ${nameA} against ${nameB} at ${grayA.width}x${grayA.height} — ` +\n        `${diff.changePercent.toFixed(2)}% of pixels differ` +\n        (region === null\n          ? \". The two are pixel-identical.\"\n          : `, all of it within ${region.x},${region.y} ${region.width}x${region.height}.`),\n    );\n\n    if (region !== null) {\n      overlay = await resizeForOutput(await overlayMask(b.png, diff.mask, grayA.width, grayA.height));\n      overlayNote =\n        `Diff overlay — B with every differing pixel tinted. ${diff.changedPixels} of ${diff.totalPixels} ` +\n        `pixels changed (${diff.changePercent.toFixed(2)}%), within ` +\n        `${region.x},${region.y} ${region.width}x${region.height}.`;\n    }\n  }\n\n  const content: CallToolResult[\"content\"] = [{ type: \"text\", text: [...lines, ...notes].join(\"\\n\") }];\n  await pushFrame(content, a.png, `A — ${nameA}`);\n  await pushFrame(content, b.png, `B — ${nameB}`);\n  if (overlay) {\n    content.push({ type: \"image\", data: toBase64(overlay), mimeType: \"image/png\" });\n    content.push({ type: \"text\", text: overlayNote });\n  }\n  return { content };\n}\n\nasync function pushFrame(content: CallToolResult[\"content\"], png: Buffer, label: string): Promise<void> {\n  const resized = await resizeForOutput(png);\n  const { width, height } = await getDimensions(resized);\n  content.push({ type: \"image\", data: toBase64(resized), mimeType: \"image/png\" });\n  content.push({ type: \"text\", text: `${label} — image ${width}x${height}` });\n}\n\n/** How a side is named in the output: where it ended up, and its title if it has one. */\nfunction describeSide(requested: string, side: Side): string {\n  const where = requested === CURRENT_PAGE ? `the open page (${side.url})` : side.url;\n  return side.title ? `${where} \"${side.title}\"` : where;\n}\n\n/** Cosmetic, and never allowed to fail or stall: a busy page still gets compared. */\nasync function safeTitle(page: Page): Promise<string | undefined> {\n  return Promise.race([\n    page.title().catch(() => undefined),\n    new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), PAGE_INFO_TIMEOUT_MS)),\n  ]);\n}\n\nasync function sizeOf(png: Buffer): Promise<Viewport> {\n  const { width, height } = await getDimensions(png);\n  return { width, height };\n}\n\nfunction isUrl(value: string): boolean {\n  try {\n    new URL(value);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * One actionable line for a failed comparison. Mirrors `describeFailure` in\n * screenshot.ts, with one addition: a `page.goto` failure names which of the\n * two sides could not be opened, which is the first thing you want to know.\n */\nexport function describeCompareFailure(\n  input: Pick<ParsedCompareInput, \"url_a\" | \"url_b\" | \"wait_for\" | \"wait_for_timeout_ms\">,\n  error: unknown,\n): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n  const prefix = \"Compare failed:\";\n\n  if (/Executable doesn't exist|browserType\\.launch/i.test(message)) {\n    return (\n      `${prefix} Playwright's Chromium browser is not installed. ` +\n      `Run \\`npx playwright install chromium\\` and try again. (${firstLine})`\n    );\n  }\n  if (/^page\\.goto:/.test(message)) {\n    const side = failingSide(input, message);\n    return `${prefix} could not open ${side} — ${firstLine}`;\n  }\n  if (input.wait_for && /^page\\.waitForSelector:/.test(message)) {\n    return `${prefix} selector \"${input.wait_for}\" did not become visible within ${input.wait_for_timeout_ms}ms.`;\n  }\n  return `${prefix} ${firstLine}`;\n}\n\n/** Playwright quotes the URL it tried in a goto failure; that says which side broke. */\nfunction failingSide(input: Pick<ParsedCompareInput, \"url_a\" | \"url_b\">, message: string): string {\n  if (input.url_b !== CURRENT_PAGE && message.includes(input.url_b)) return `url_b (${input.url_b})`;\n  if (input.url_a !== CURRENT_PAGE && message.includes(input.url_a)) return `url_a (${input.url_a})`;\n  return \"one of the two pages\";\n}\n\nexport function registerCompareTool(server: McpServer): void {\n  server.registerTool(\n    COMPARE_TOOL_NAME,\n    {\n      title: \"Compare\",\n      description:\n        \"Compare two pages — two URLs, or the same URL before and after a code change — and show what moved. \" +\n        \"Returns both screenshots, the percentage of pixels that differ, the region they differ in, and an \" +\n        `overlay of the second page with every changed pixel tinted. Pass \"${CURRENT_PAGE}\" as \\`url_a\\` to ` +\n        \"compare against the page framewatch_interact has open, in whatever state your interactions left it.\",\n      inputSchema: compareInputShape,\n      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => comparePages(args),\n  );\n}\n"]}

package/dist/tools/dead-clicks.d.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ClickEffect, type Clickable, type HoverProbe } from "../engine/clicks.js";
+export declare const DEAD_CLICKS_TOOL_NAME = "framewatch_dead_clicks";
+export declare const deadClicksInputShape: {
+    url: z.ZodString;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    settle_ms: z.ZodDefault<z.ZodNumber>;
+    selector: z.ZodOptional<z.ZodString>;
+    exclude: z.ZodOptional<z.ZodString>;
+    include_pointer: z.ZodDefault<z.ZodBoolean>;
+    include_hover: z.ZodDefault<z.ZodBoolean>;
+    max_elements: z.ZodDefault<z.ZodNumber>;
+    full_page: z.ZodDefault<z.ZodBoolean>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+    }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
+};
+export declare const deadClicksInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    settle_ms: z.ZodDefault<z.ZodNumber>;
+    selector: z.ZodOptional<z.ZodString>;
+    exclude: z.ZodOptional<z.ZodString>;
+    include_pointer: z.ZodDefault<z.ZodBoolean>;
+    include_hover: z.ZodDefault<z.ZodBoolean>;
+    max_elements: z.ZodDefault<z.ZodNumber>;
+    full_page: z.ZodDefault<z.ZodBoolean>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+    }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    wait_ms: number;
+    wait_for_timeout_ms: number;
+    max_elements: number;
+    include_pointer: boolean;
+    settle_ms: number;
+    include_hover: boolean;
+    full_page: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_for?: string | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+    exclude?: string | undefined;
+}, {
+    url: string;
+    viewport?: {
+        width?: number | undefined;
+        height?: number | undefined;
+    } | undefined;
+    wait_ms?: number | undefined;
+    wait_for?: string | undefined;
+    wait_for_timeout_ms?: number | undefined;
+    max_elements?: number | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+    exclude?: string | undefined;
+    include_pointer?: boolean | undefined;
+    settle_ms?: number | undefined;
+    include_hover?: boolean | undefined;
+    full_page?: boolean | undefined;
+}>;
+export type DeadClicksInput = z.input<typeof deadClicksInputSchema>;
+type ParsedDeadClicksInput = z.output<typeof deadClicksInputSchema>;
+/** What one element did — or did not do — when it was clicked. */
+export interface Verdict {
+    clickable: Clickable;
+    /** Everything the click caused. Empty means the click did nothing at all. */
+    effects: ClickEffect[];
+    /** Set when the element was never clicked, and why. */
+    skipped?: string;
+    /** How the page reacts to the pointer, asked only of dead elements. */
+    hover?: HoverProbe;
+}
+/**
+ * Find the elements on a page that look clickable and do nothing.
+ *
+ * Every candidate is clicked for real, and the page is then interrogated from
+ * every angle at once — URL, DOM mutations, form state, storage, scroll,
+ * focus, console, network, dialogs, popups, downloads. An element is only
+ * called dead when all of them stayed silent (see engine/clicks.ts).
+ *
+ * Two things make the answer trustworthy rather than merely plausible. The
+ * page is measured once with nobody clicking, so a ticking clock or a polling
+ * fetch cannot make every element look alive. And the page is reloaded after
+ * any click that changed it, so element five is judged on the page as it
+ * shipped rather than on whatever elements one to four left behind — a click
+ * that changed nothing needs no reload, which is exactly the case this tool is
+ * looking for, so a page full of dead controls is also the fastest to sweep.
+ *
+ * This is the one read-only-looking tool that is not read-only: it presses
+ * every button on the page, including the one that deletes the account. Use
+ * `exclude` (or `selector`) on anything that matters.
+ */
+export declare function findDeadClicks(rawInput: DeadClicksInput): Promise<CallToolResult>;
+/**
+ * One actionable line for a sweep that could not run. Mirrors `describeFailure`
+ * in screenshot.ts: match on the failing Playwright call, never on substrings
+ * of a user-supplied selector.
+ */
+export declare function describeDeadClicksFailure(input: Pick<ParsedDeadClicksInput, "url" | "wait_for" | "wait_for_timeout_ms">, error: unknown): string;
+export declare function registerDeadClicksTool(server: McpServer): void;
+export {};