framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/tools/interact.js

@@ -4,13 +4,27 @@ import { getSessionPage, withSessionLock } from "../engine/browser.js";
 import { buildDiffCards } from "../engine/differ.js";
 import { applyContext, layersFor, summariseContext } from "../engine/layers/index.js";
 import { INTERACT_ACTIONS, describeInteraction, executeInteraction, interactionFieldShape, needsTouch, refineInteraction, } from "../engine/interaction.js";
-import { formatCardMeta } from "../utils/format.js";
+import { takeSnapshot } from "../engine/snapshot.js";
+import { describeScale, formatCardMeta } from "../utils/format.js";
+import { refSelector } from "../utils/snapshot-rules.js";
+import { describeAuth, loginFormVisible, resolveStorageState, storageStateField } from "../utils/storage-state.js";
+import { DEFAULT_SNAPSHOT_MAX_CHARS, VUE_DETECT_MS, VUE_READY_TIMEOUT_MS } from "../constants.js";
+import { hmrFor } from "../engine/hmr.js";
+import { detectVue, waitForVueReady } from "../engine/vue.js";
+import { describeVue } from "../utils/vue-rules.js";
+import { describeCounts } from "./snapshot.js";
+import { markImage } from "../utils/budget.js";
 export const INTERACT_TOOL_NAME = "framewatch_interact";
 export const interactInputShape = {
     action: z
         .enum(INTERACT_ACTIONS)
-        .describe("What to do: click, tap, type, scroll, swipe, navigate, select or hover"),
+        .describe("What to do: click, tap, type, key, scroll, swipe, navigate, select or hover"),
     ...interactionFieldShape,
+    ref: z
+        .string()
+        .regex(/^e\d+$/, "a ref looks like `e8` — take one from framewatch_snapshot")
+        .optional()
+        .describe("Element ref from framewatch_snapshot (e.g. `e8`) to act on, instead of a `selector`"),
     url: z
         .string()
         .url()
@@ -51,8 +65,20 @@ export const interactInputShape = {
         .boolean()
         .default(false)
         .describe("Report paint timing and layout shifts measured around the action"),
+    include_snapshot: z
+        .boolean()
+        .default(false)
+        .describe("Append a framewatch_snapshot of the page after the action, with fresh refs for the next call"),
+    storage_state: storageStateField,
 };
-export const interactInputSchema = z.object(interactInputShape).superRefine(refineInteraction);
+export const interactInputSchema = z.object(interactInputShape).superRefine((value, ctx) => {
+    if (value.ref !== undefined && value.selector !== undefined) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "pass either `ref` or `selector`, not both", path: ["ref"] });
+        return;
+    }
+    // A ref is a selector Playwright understands, so the step is validated as one.
+    refineInteraction(value.ref !== undefined ? { ...value, selector: refSelector(value.ref) } : value, ctx);
+});
 /**
  * Perform one interaction on the current page and show what it did.
  *
@@ -79,9 +105,10 @@ async function runInteraction(rawInput) {
         return errorResult(`Interaction failed: invalid input — ${issues}`);
     }
     const input = parsed.data;
+    const selector = input.ref !== undefined ? refSelector(input.ref) : input.selector;
     const step = {
         action: input.action,
-        ...(input.selector !== undefined ? { selector: input.selector } : {}),
+        ...(selector !== undefined ? { selector } : {}),
         ...(input.value !== undefined ? { value: input.value } : {}),
         ...(input.x !== undefined ? { x: input.x } : {}),
         ...(input.y !== undefined ? { y: input.y } : {}),
@@ -95,9 +122,15 @@ async function runInteraction(rawInput) {
         performance: input.include_performance,
     };
     try {
-        const { page, previousUrl } = await getSessionPage({
+        // Cookies and storage are fixed when a context is created, so a state named
+        // here applies to the page this call opens; a session already running on
+        // the same state simply carries on (see `getSessionPage`).
+        const auth = await resolveStorageState(input.storage_state);
+        const storageState = auth ? { path: auth.path, state: auth.state } : undefined;
+        const { page, previousUrl, reopenedFor } = await getSessionPage({
             ...(input.viewport ? { viewport: input.viewport } : {}),
             hasTouch: needsTouch([step]),
+            ...(storageState ? { storageState } : {}),
         });
         // The layers belong to the page, not to this call (see SessionLayers), so
         // they are installed once and emptied here — this call reports what this
@@ -106,22 +139,32 @@ async function runInteraction(rawInput) {
         const layers = layersFor(page);
         await layers.ensure(flags);
         layers.clear();
-        // `previousUrl` means the session had to be reopened to enable touch; go
-        // back to where the user was unless they asked for somewhere else.
+        // `previousUrl` means the session had to be reopened (for touch, or to take
+        // a different auth state); go back to where the user was unless they asked
+        // for somewhere else.
         const target = input.url ?? previousUrl;
         if (target !== undefined) {
             await page.goto(target, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
+            // A Vue app is acted on once it is mounted and its router has resolved;
+            // a plain page gets no extra wait beyond the brief look for one.
+            await waitForVueReady(page, { detect_ms: VUE_DETECT_MS, ready_ms: VUE_READY_TIMEOUT_MS });
         }
         if (page.url() === "about:blank") {
             return errorResult("Interaction failed: no page is open yet — pass `url` to open one (e.g. http://localhost:3000).");
         }
+        const vueBefore = await detectVue(page);
+        // A password field before the action and none after it is a login that
+        // just succeeded — the one moment the agent is thinking about auth.
+        const loginBefore = await loginFormVisible(page);
         const before = await page.screenshot({ type: "png" });
         const startedAt = Date.now();
-        await executeInteraction(page, step, { timeout_ms: input.timeout_ms });
+        const outcome = await executeInteraction(page, step, { timeout_ms: input.timeout_ms });
         if (input.wait_ms > 0) {
             await page.waitForTimeout(input.wait_ms);
         }
         const after = await page.screenshot({ type: "png" });
+        const vueAfter = vueBefore || step.action === "navigate" ? await detectVue(page) : null;
+        const loginAfter = await loginFormVisible(page);
         const frames = [
             { buffer: before, timestamp_ms: 0, is_interaction: false },
             { buffer: after, timestamp_ms: Date.now() - startedAt, is_interaction: true },
@@ -139,9 +182,12 @@ async function runInteraction(rawInput) {
         const context = layers.collect(startedAt, flags);
         applyContext(cards, context);
         const [beforeCard, afterCard] = cards;
+        const viewport = page.viewportSize() ?? { width: 0, height: 0 };
         const headline = [
-            summarise(step, page.url(), afterCard.change_region?.change_percent ?? 0, previousUrl !== undefined),
+            `${summarise(step, page.url(), afterCard.change_region?.change_percent ?? 0, reopenedFor, input.ref, outcome.note)} — ${describeScale(viewport)}`,
+            ...describeRoute(vueBefore, vueAfter),
             ...(summariseContext(context, cards.length) ?? []),
+            ...authLines(auth, input.url !== undefined && loginBefore, loginBefore && !loginAfter),
         ].join("\n");
         const content = [
             { type: "text", text: headline },
@@ -152,19 +198,67 @@ async function runInteraction(rawInput) {
         ];
         const crop = afterCard.change_region?.crop;
         if (crop) {
-            content.push({ type: "image", data: crop, mimeType: "image/png" });
+            content.push(markImage({ type: "image", data: crop, mimeType: "image/png" }, { role: "crop" }));
+        }
+        if (input.include_snapshot) {
+            // Refs are reassigned by every snapshot, so the ones the caller used are
+            // stale the moment this runs — which is the point: these are the fresh ones.
+            const snapshot = await takeSnapshot(page, { mode: "full", max_chars: DEFAULT_SNAPSHOT_MAX_CHARS });
+            const lines = [`Snapshot — ${describeCounts(snapshot)} (refs valid until the page changes)`, "", snapshot.text];
+            if (snapshot.cut_lines > 0)
+                lines.push(`… ${snapshot.cut_lines} more lines cut — use framewatch_snapshot with \`selector\` or mode "interactive".`);
+            content.push({ type: "text", text: lines.join("\n") });
         }
+        hmrFor(page).markSeen();
         return { content };
     }
     catch (error) {
         return errorResult(describeInteractFailure(input, error));
     }
 }
+/**
+ * The auth lines: what saved state was applied (and whether it worked, when
+ * this call opened the page), and — when a login form was there before the
+ * action and gone after it — the reminder to save the session now.
+ */
+function authLines(auth, expired, justSignedIn) {
+    const lines = [];
+    const applied = auth ? describeAuth(auth, expired) : null;
+    if (applied)
+        lines.push(applied);
+    if (justSignedIn) {
+        lines.push("Signed in? Save this session with framewatch_save_auth (same steps, from the login page) so every later call " +
+            "starts here instead of replaying the login.");
+    }
+    return lines;
+}
+/**
+ * The Vue line: the app and its route, and — when the action moved the
+ * router — where it went, by name.
+ */
+function describeRoute(before, after) {
+    const current = after ?? before;
+    if (!current)
+        return [];
+    const from = before?.route;
+    const to = after?.route;
+    if (from && to && from.path !== to.path) {
+        const name = (route) => `${route.path}${route.name ? ` (${route.name})` : ""}`;
+        return [`Vue ${current.version} — route ${name(from)} → ${name(to)}`];
+    }
+    return [describeVue(current)];
+}
 /** One line: what was done, where, and how much of the frame it moved. */
-function summarise(step, url, changePercent, reopened) {
-    const note = reopened ? " (page reopened to enable touch — page state was reset)" : "";
+function summarise(step, url, changePercent, reopenedFor, ref, note) {
+    const reopened = reopenedFor === "touch"
+        ? " (page reopened to enable touch — page state was reset)"
+        : reopenedFor === "auth"
+            ? " (page reopened with the saved auth state — page state was reset)"
+            : "";
     const changed = changePercent > 0 ? `${changePercent.toFixed(1)}% of the frame changed` : "no visual change";
-    return `${describeInteraction(step)} on ${url}${note} — ${changed}`;
+    // The step carries the ref as an `aria-ref=` selector; the caller wrote `e8`.
+    const what = (ref !== undefined ? describeInteraction(step).replaceAll(`"${refSelector(ref)}"`, ref) : describeInteraction(step)) + (note ?? "");
+    return `${what} on ${url}${reopened} — ${changed}`;
 }
 function errorResult(text) {
     return { isError: true, content: [{ type: "text", text }] };
@@ -178,6 +272,10 @@ function errorResult(text) {
 export function describeInteractFailure(input, error) {
     const message = error instanceof Error ? error.message : String(error);
     const firstLine = message.split("\n")[0];
+    if (input.ref !== undefined && message.includes(refSelector(input.ref))) {
+        return (`Interaction failed: ref ${input.ref} did not resolve — the page has changed since that snapshot, or none was ` +
+            `taken on this page. Run framewatch_snapshot again and use a ref from it. (${firstLine.replaceAll(`"${refSelector(input.ref)}"`, input.ref)})`);
+    }
     if (/Executable doesn't exist|browserType\.launch/i.test(message)) {
         return ("Interaction failed: Playwright's Chromium browser is not installed. " +
             `Run \`npx playwright install chromium\` and try again. (${firstLine})`);
@@ -193,6 +291,8 @@ export function registerInteractTool(server) {
         description: "Perform one interaction (click, tap, type, scroll, swipe, hover, select, navigate) on a page and return " +
             "before/after screenshots plus a crop of what changed. The page stays open between calls, so you can " +
             "click, look, type and look again without replaying the whole flow — pass `url` only to open or move it. " +
+            "Target an element by `ref` from framewatch_snapshot (e.g. `e8`) instead of guessing a selector; " +
+            "`include_snapshot` returns the fresh refs after the action. " +
             "Each call also reports the context its own action produced: console output and uncaught errors (on by " +
             "default), plus network requests, DOM mutations and paint/layout-shift timing via `include_network`, " +
             "`include_dom` and `include_performance` — that is how you find out why a click did nothing.",

package/dist/tools/interact.js.map

@@ -1 +1 @@
-{"version":3,"file":"interact.js","sourceRoot":"","sources":["../../src/tools/interact.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  DEFAULT_INTERACT_WAIT_MS,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  NAVIGATION_TIMEOUT_MS,\n  SELECTOR_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { getSessionPage, withSessionLock } from \"../engine/browser.js\";\nimport { buildDiffCards } from \"../engine/differ.js\";\nimport { applyContext, layersFor, summariseContext, type LayerFlags } from \"../engine/layers/index.js\";\nimport {\n  INTERACT_ACTIONS,\n  describeInteraction,\n  executeInteraction,\n  interactionFieldShape,\n  needsTouch,\n  refineInteraction,\n  type Interaction,\n} from \"../engine/interaction.js\";\nimport type { RawFrame } from \"../types.js\";\nimport { formatCardMeta } from \"../utils/format.js\";\n\nexport const INTERACT_TOOL_NAME = \"framewatch_interact\";\n\nexport const interactInputShape = {\n  action: z\n    .enum(INTERACT_ACTIONS)\n    .describe(\"What to do: click, tap, type, scroll, swipe, navigate, select or hover\"),\n  ...interactionFieldShape,\n  url: z\n    .string()\n    .url()\n    .optional()\n    .describe(\"Open this URL first. Omit to act on the page left open by the previous call.\"),\n  wait_ms: z\n    .number()\n    .int()\n    .min(0)\n    .default(DEFAULT_INTERACT_WAIT_MS)\n    .describe(\"Wait time (ms) after the action before the 'after' screenshot, so animations can settle\"),\n  timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .default(SELECTOR_TIMEOUT_MS)\n    .describe(\"Max time (ms) to wait for the target element\"),\n  viewport: z\n    .object({\n      width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH),\n      height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT),\n    })\n    .optional()\n    .describe(\"Resize the page to this before acting (defaults to leaving it as it is)\"),\n  include_console: z\n    .boolean()\n    .default(true)\n    .describe(\"Report console logs, uncaught errors and unhandled rejections the action caused\"),\n  include_network: z\n    .boolean()\n    .default(false)\n    .describe(\"Report network requests (method, url, status, duration) the action caused\"),\n  include_dom: z\n    .boolean()\n    .default(false)\n    .describe(\"Report the DOM mutations the action caused — which elements were added, removed or restyled\"),\n  include_performance: z\n    .boolean()\n    .default(false)\n    .describe(\"Report paint timing and layout shifts measured around the action\"),\n};\n\nexport const interactInputSchema = z.object(interactInputShape).superRefine(refineInteraction);\nexport type InteractInput = z.input<typeof interactInputSchema>;\n\n/**\n * Perform one interaction on the current page and show what it did.\n *\n * Unlike every other FrameWatch tool this one is stateful on purpose: the page\n * stays open between calls (see `getSessionPage`), which is what makes\n * click → look → type → look iteration possible. Pass `url` to open or move\n * the page; omit it to keep working on what is already there.\n *\n * The result is a two-frame diff card sequence — before, after, and the\n * change region between them — reusing the same diff engine as\n * `framewatch_capture` so the change bbox and crop mean the same thing in\n * both tools.\n *\n * Calls are serialised through `withSessionLock`, which every tool that\n * touches the session page shares: one page, one hand.\n */\nexport function performInteraction(rawInput: InteractInput): Promise<CallToolResult> {\n  return withSessionLock(() => runInteraction(rawInput));\n}\n\nasync function runInteraction(rawInput: InteractInput): Promise<CallToolResult> {\n  const parsed = interactInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Interaction failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n  const step: Interaction = {\n    action: input.action,\n    ...(input.selector !== undefined ? { selector: input.selector } : {}),\n    ...(input.value !== undefined ? { value: input.value } : {}),\n    ...(input.x !== undefined ? { x: input.x } : {}),\n    ...(input.y !== undefined ? { y: input.y } : {}),\n    ...(input.delta_x !== undefined ? { delta_x: input.delta_x } : {}),\n    ...(input.delta_y !== undefined ? { delta_y: input.delta_y } : {}),\n  };\n\n  const flags: LayerFlags = {\n    console: input.include_console,\n    network: input.include_network,\n    dom: input.include_dom,\n    performance: input.include_performance,\n  };\n\n  try {\n    const { page, previousUrl } = await getSessionPage({\n      ...(input.viewport ? { viewport: input.viewport } : {}),\n      hasTouch: needsTouch([step]),\n    });\n\n    // The layers belong to the page, not to this call (see SessionLayers), so\n    // they are installed once and emptied here — this call reports what this\n    // action caused, not what the last twenty did. Both happen before the\n    // navigation, so a page opened by `url` has its load watched too.\n    const layers = layersFor(page);\n    await layers.ensure(flags);\n    layers.clear();\n\n    // `previousUrl` means the session had to be reopened to enable touch; go\n    // back to where the user was unless they asked for somewhere else.\n    const target = input.url ?? previousUrl;\n    if (target !== undefined) {\n      await page.goto(target, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n    }\n    if (page.url() === \"about:blank\") {\n      return errorResult(\n        \"Interaction failed: no page is open yet — pass `url` to open one (e.g. http://localhost:3000).\",\n      );\n    }\n\n    const before = await page.screenshot({ type: \"png\" });\n    const startedAt = Date.now();\n    await executeInteraction(page, step, { timeout_ms: input.timeout_ms });\n    if (input.wait_ms > 0) {\n      await page.waitForTimeout(input.wait_ms);\n    }\n    const after = await page.screenshot({ type: \"png\" });\n\n    const frames: RawFrame[] = [\n      { buffer: before, timestamp_ms: 0, is_interaction: false },\n      { buffer: after, timestamp_ms: Date.now() - startedAt, is_interaction: true },\n    ];\n    // sensitivity 0 keeps both frames however small the change is — the point\n    // of this tool is to show what one action did, including \"nothing\".\n    const { cards } = await buildDiffCards(frames, { sensitivity: 0, max_frames: 2 });\n    if (cards.length < 2) {\n      return errorResult(`Interaction failed: ${describeInteraction(step)} ran, but the screenshots could not be compared.`);\n    }\n\n    // `startedAt` is the instant of the \"before\" frame, which puts the split\n    // exactly where it belongs: everything from opening the page lands on the\n    // before card (negative, i.e. \"how we got here\") and everything the action\n    // caused lands on the after card.\n    const context = layers.collect(startedAt, flags);\n    applyContext(cards, context);\n\n    const [beforeCard, afterCard] = cards;\n    const headline = [\n      summarise(step, page.url(), afterCard.change_region?.change_percent ?? 0, previousUrl !== undefined),\n      ...(summariseContext(context, cards.length) ?? []),\n    ].join(\"\\n\");\n\n    const content: CallToolResult[\"content\"] = [\n      { type: \"text\", text: headline },\n      { type: \"image\", data: beforeCard.full_frame, mimeType: \"image/png\" },\n      { type: \"text\", text: `Before — ${formatCardMeta(beforeCard)}` },\n      { type: \"image\", data: afterCard.full_frame, mimeType: \"image/png\" },\n      { type: \"text\", text: `After — ${formatCardMeta(afterCard)}` },\n    ];\n    const crop = afterCard.change_region?.crop;\n    if (crop) {\n      content.push({ type: \"image\", data: crop, mimeType: \"image/png\" });\n    }\n    return { content };\n  } catch (error) {\n    return errorResult(describeInteractFailure(input, error));\n  }\n}\n\n/** One line: what was done, where, and how much of the frame it moved. */\nfunction summarise(step: Interaction, url: string, changePercent: number, reopened: boolean): string {\n  const note = reopened ? \" (page reopened to enable touch — page state was reset)\" : \"\";\n  const changed = changePercent > 0 ? `${changePercent.toFixed(1)}% of the frame changed` : \"no visual change\";\n  return `${describeInteraction(step)} on ${url}${note} — ${changed}`;\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * Turn a failure into one actionable line. Interaction errors already name the\n * step and the reason (see `executeInteraction`), so they are passed through\n * with the page appended for context; everything else is a navigation or\n * browser problem, worded as in the other tools.\n */\nexport function describeInteractFailure(input: { url?: string }, error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n\n  if (/Executable doesn't exist|browserType\\.launch/i.test(message)) {\n    return (\n      \"Interaction failed: 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    return `Interaction failed: could not open ${input.url ?? \"the page\"} — ${firstLine}`;\n  }\n  return input.url ? `${firstLine} (page: ${input.url})` : firstLine;\n}\n\nexport function registerInteractTool(server: McpServer): void {\n  server.registerTool(\n    INTERACT_TOOL_NAME,\n    {\n      title: \"Interact\",\n      description:\n        \"Perform one interaction (click, tap, type, scroll, swipe, hover, select, navigate) on a page and return \" +\n        \"before/after screenshots plus a crop of what changed. The page stays open between calls, so you can \" +\n        \"click, look, type and look again without replaying the whole flow — pass `url` only to open or move it. \" +\n        \"Each call also reports the context its own action produced: console output and uncaught errors (on by \" +\n        \"default), plus network requests, DOM mutations and paint/layout-shift timing via `include_network`, \" +\n        \"`include_dom` and `include_performance` — that is how you find out why a click did nothing.\",\n      inputSchema: interactInputShape,\n      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },\n    },\n    async (args) => performInteraction(args),\n  );\n}\n"]}
+{"version":3,"file":"interact.js","sourceRoot":"","sources":["../../src/tools/interact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAmB,MAAM,2BAA2B,CAAC;AACvG,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,UAAU,EACV,iBAAiB,GAElB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnH,OAAO,EAAE,0BAA0B,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAgB,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,MAAM,CAAC,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAExD,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,CAAC,6EAA6E,CAAC;IAC1F,GAAG,qBAAqB;IACxB,GAAG,EAAE,CAAC;SACH,MAAM,EAAE;SACR,KAAK,CAAC,QAAQ,EAAE,2DAA2D,CAAC;SAC5E,QAAQ,EAAE;SACV,QAAQ,CAAC,qFAAqF,CAAC;IAClG,GAAG,EAAE,CAAC;SACH,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,CAAC,8EAA8E,CAAC;IAC3F,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,wBAAwB,CAAC;SACjC,QAAQ,CAAC,yFAAyF,CAAC;IACtG,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,mBAAmB,CAAC;SAC5B,QAAQ,CAAC,8CAA8C,CAAC;IAC3D,QAAQ,EAAE,CAAC;SACR,MAAM,CAAC;QACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC;QACtD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC;KACzD,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,yEAAyE,CAAC;IACtF,eAAe,EAAE,CAAC;SACf,OAAO,EAAE;SACT,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,iFAAiF,CAAC;IAC9F,eAAe,EAAE,CAAC;SACf,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,2EAA2E,CAAC;IACxF,WAAW,EAAE,CAAC;SACX,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,6FAA6F,CAAC;IAC1G,mBAAmB,EAAE,CAAC;SACnB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,kEAAkE,CAAC;IAC/E,gBAAgB,EAAE,CAAC;SAChB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,8FAA8F,CAAC;IAC3G,aAAa,EAAE,iBAAiB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IACzF,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5D,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,2CAA2C,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnH,OAAO;IACT,CAAC;IACD,+EAA+E;IAC/E,iBAAiB,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC3G,CAAC,CAAC,CAAC;AAGH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAuB;IACxD,OAAO,eAAe,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,QAAuB;IACnD,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzG,OAAO,WAAW,CAAC,uCAAuC,MAAM,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;IAC1B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;IACnF,MAAM,IAAI,GAAgB;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnE,CAAC;IAEF,MAAM,KAAK,GAAe;QACxB,OAAO,EAAE,KAAK,CAAC,eAAe;QAC9B,OAAO,EAAE,KAAK,CAAC,eAAe;QAC9B,GAAG,EAAE,KAAK,CAAC,WAAW;QACtB,WAAW,EAAE,KAAK,CAAC,mBAAmB;KACvC,CAAC;IAEF,IAAI,CAAC;QACH,4EAA4E;QAC5E,yEAAyE;QACzE,2DAA2D;QAC3D,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC5D,MAAM,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAE/E,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,MAAM,cAAc,CAAC;YAC9D,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,QAAQ,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;YAC5B,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C,CAAC,CAAC;QAEH,0EAA0E;QAC1E,yEAAyE;QACzE,sEAAsE;QACtE,kEAAkE;QAClE,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,MAAM,CAAC,KAAK,EAAE,CAAC;QAEf,4EAA4E;QAC5E,2EAA2E;QAC3E,sBAAsB;QACtB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,IAAI,WAAW,CAAC;QACxC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC,CAAC;YAC/E,wEAAwE;YACxE,iEAAiE;YACjE,MAAM,eAAe,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,KAAK,aAAa,EAAE,CAAC;YACjC,OAAO,WAAW,CAChB,gGAAgG,CACjG,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;QACxC,uEAAuE;QACvE,oEAAoE;QACpE,MAAM,WAAW,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QACvF,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxF,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAe;YACzB,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE;YAC1D,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE;SAC9E,CAAC;QACF,0EAA0E;QAC1E,oEAAoE;QACpE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;QAClF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,WAAW,CAAC,uBAAuB,mBAAmB,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;QACzH,CAAC;QAED,yEAAyE;QACzE,0EAA0E;QAC1E,2EAA2E;QAC3E,kCAAkC;QAClC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACjD,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAE7B,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAChE,MAAM,QAAQ,GAAG;YACf,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,CAAC,aAAa,EAAE,cAAc,IAAI,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,aAAa,CAAC,QAAQ,CAAC,EAAE;YACjJ,GAAG,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAC;YACrC,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAClD,GAAG,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,WAAW,EAAE,WAAW,IAAI,CAAC,UAAU,CAAC;SACvF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,MAAM,OAAO,GAA8B;YACzC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;YAChC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE;YACrE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,cAAc,CAAC,UAAU,CAAC,EAAE,EAAE;YAChE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE;YACpE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE;SAC/D,CAAC;QACF,MAAM,IAAI,GAAG,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC;QAC3C,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QAClG,CAAC;QACD,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAC3B,yEAAyE;YACzE,6EAA6E;YAC7E,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,0BAA0B,EAAE,CAAC,CAAC;YACnG,MAAM,KAAK,GAAG,CAAC,cAAc,cAAc,CAAC,QAAQ,CAAC,sCAAsC,EAAE,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;YAChH,IAAI,QAAQ,CAAC,SAAS,GAAG,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,SAAS,oFAAoF,CAAC,CAAC;YACpJ,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,WAAW,CAAC,uBAAuB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAqD,EAAE,OAAgB,EAAE,YAAqB;IAC/G,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,IAAI,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,YAAY,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CACR,+GAA+G;YAC7G,6CAA6C,CAChD,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,MAAsB,EAAE,KAAqB;IAClE,MAAM,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC;IAChC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,IAAI,GAAG,MAAM,EAAE,KAAK,CAAC;IAC3B,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC;IACxB,IAAI,IAAI,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,CAAC,KAAsC,EAAU,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACxH,OAAO,CAAC,OAAO,OAAO,CAAC,OAAO,YAAY,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,0EAA0E;AAC1E,SAAS,SAAS,CAChB,IAAiB,EACjB,GAAW,EACX,aAAqB,EACrB,WAA8B,EAC9B,GAAY,EACZ,IAAa;IAEb,MAAM,QAAQ,GACZ,WAAW,KAAK,OAAO;QACrB,CAAC,CAAC,yDAAyD;QAC3D,CAAC,CAAC,WAAW,KAAK,MAAM;YACtB,CAAC,CAAC,mEAAmE;YACrE,CAAC,CAAC,EAAE,CAAC;IACX,MAAM,OAAO,GAAG,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAC7G,8EAA8E;IAC9E,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACjJ,OAAO,GAAG,IAAI,OAAO,GAAG,GAAG,QAAQ,MAAM,OAAO,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAqC,EAAE,KAAc;IAC3F,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzC,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACxE,OAAO,CACL,2BAA2B,KAAK,CAAC,GAAG,2EAA2E;YAC/G,6EAA6E,SAAS,CAAC,UAAU,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAC/I,CAAC;IACJ,CAAC;IAED,IAAI,+CAA+C,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClE,OAAO,CACL,sEAAsE;YACtE,2DAA2D,SAAS,GAAG,CACxE,CAAC;IACJ,CAAC;IACD,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,OAAO,sCAAsC,KAAK,CAAC,GAAG,IAAI,UAAU,MAAM,SAAS,EAAE,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,WAAW,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,MAAM,CAAC,YAAY,CACjB,kBAAkB,EAClB;QACE,KAAK,EAAE,UAAU;QACjB,WAAW,EACT,0GAA0G;YAC1G,sGAAsG;YACtG,0GAA0G;YAC1G,kGAAkG;YAClG,8DAA8D;YAC9D,wGAAwG;YACxG,sGAAsG;YACtG,6FAA6F;QAC/F,WAAW,EAAE,kBAAkB;QAC/B,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE;KACzG,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CACzC,CAAC;AACJ,CAAC","sourcesContent":["import { z } from \"zod\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  DEFAULT_INTERACT_WAIT_MS,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  NAVIGATION_TIMEOUT_MS,\n  SELECTOR_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { getSessionPage, withSessionLock } from \"../engine/browser.js\";\nimport { buildDiffCards } from \"../engine/differ.js\";\nimport { applyContext, layersFor, summariseContext, type LayerFlags } from \"../engine/layers/index.js\";\nimport {\n  INTERACT_ACTIONS,\n  describeInteraction,\n  executeInteraction,\n  interactionFieldShape,\n  needsTouch,\n  refineInteraction,\n  type Interaction,\n} from \"../engine/interaction.js\";\nimport { takeSnapshot } from \"../engine/snapshot.js\";\nimport type { RawFrame } from \"../types.js\";\nimport { describeScale, formatCardMeta } from \"../utils/format.js\";\nimport { refSelector } from \"../utils/snapshot-rules.js\";\nimport { describeAuth, loginFormVisible, resolveStorageState, storageStateField } from \"../utils/storage-state.js\";\nimport { DEFAULT_SNAPSHOT_MAX_CHARS, VUE_DETECT_MS, VUE_READY_TIMEOUT_MS } from \"../constants.js\";\nimport { hmrFor } from \"../engine/hmr.js\";\nimport { detectVue, waitForVueReady } from \"../engine/vue.js\";\nimport { describeVue, type VueInfo } from \"../utils/vue-rules.js\";\nimport { describeCounts } from \"./snapshot.js\";\nimport { markImage } from \"../utils/budget.js\";\n\nexport const INTERACT_TOOL_NAME = \"framewatch_interact\";\n\nexport const interactInputShape = {\n  action: z\n    .enum(INTERACT_ACTIONS)\n    .describe(\"What to do: click, tap, type, key, scroll, swipe, navigate, select or hover\"),\n  ...interactionFieldShape,\n  ref: z\n    .string()\n    .regex(/^e\\d+$/, \"a ref looks like `e8` — take one from framewatch_snapshot\")\n    .optional()\n    .describe(\"Element ref from framewatch_snapshot (e.g. `e8`) to act on, instead of a `selector`\"),\n  url: z\n    .string()\n    .url()\n    .optional()\n    .describe(\"Open this URL first. Omit to act on the page left open by the previous call.\"),\n  wait_ms: z\n    .number()\n    .int()\n    .min(0)\n    .default(DEFAULT_INTERACT_WAIT_MS)\n    .describe(\"Wait time (ms) after the action before the 'after' screenshot, so animations can settle\"),\n  timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .default(SELECTOR_TIMEOUT_MS)\n    .describe(\"Max time (ms) to wait for the target element\"),\n  viewport: z\n    .object({\n      width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH),\n      height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT),\n    })\n    .optional()\n    .describe(\"Resize the page to this before acting (defaults to leaving it as it is)\"),\n  include_console: z\n    .boolean()\n    .default(true)\n    .describe(\"Report console logs, uncaught errors and unhandled rejections the action caused\"),\n  include_network: z\n    .boolean()\n    .default(false)\n    .describe(\"Report network requests (method, url, status, duration) the action caused\"),\n  include_dom: z\n    .boolean()\n    .default(false)\n    .describe(\"Report the DOM mutations the action caused — which elements were added, removed or restyled\"),\n  include_performance: z\n    .boolean()\n    .default(false)\n    .describe(\"Report paint timing and layout shifts measured around the action\"),\n  include_snapshot: z\n    .boolean()\n    .default(false)\n    .describe(\"Append a framewatch_snapshot of the page after the action, with fresh refs for the next call\"),\n  storage_state: storageStateField,\n};\n\nexport const interactInputSchema = z.object(interactInputShape).superRefine((value, ctx) => {\n  if (value.ref !== undefined && value.selector !== undefined) {\n    ctx.addIssue({ code: z.ZodIssueCode.custom, message: \"pass either `ref` or `selector`, not both\", path: [\"ref\"] });\n    return;\n  }\n  // A ref is a selector Playwright understands, so the step is validated as one.\n  refineInteraction(value.ref !== undefined ? { ...value, selector: refSelector(value.ref) } : value, ctx);\n});\nexport type InteractInput = z.input<typeof interactInputSchema>;\n\n/**\n * Perform one interaction on the current page and show what it did.\n *\n * Unlike every other FrameWatch tool this one is stateful on purpose: the page\n * stays open between calls (see `getSessionPage`), which is what makes\n * click → look → type → look iteration possible. Pass `url` to open or move\n * the page; omit it to keep working on what is already there.\n *\n * The result is a two-frame diff card sequence — before, after, and the\n * change region between them — reusing the same diff engine as\n * `framewatch_capture` so the change bbox and crop mean the same thing in\n * both tools.\n *\n * Calls are serialised through `withSessionLock`, which every tool that\n * touches the session page shares: one page, one hand.\n */\nexport function performInteraction(rawInput: InteractInput): Promise<CallToolResult> {\n  return withSessionLock(() => runInteraction(rawInput));\n}\n\nasync function runInteraction(rawInput: InteractInput): Promise<CallToolResult> {\n  const parsed = interactInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Interaction failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n  const selector = input.ref !== undefined ? refSelector(input.ref) : input.selector;\n  const step: Interaction = {\n    action: input.action,\n    ...(selector !== undefined ? { selector } : {}),\n    ...(input.value !== undefined ? { value: input.value } : {}),\n    ...(input.x !== undefined ? { x: input.x } : {}),\n    ...(input.y !== undefined ? { y: input.y } : {}),\n    ...(input.delta_x !== undefined ? { delta_x: input.delta_x } : {}),\n    ...(input.delta_y !== undefined ? { delta_y: input.delta_y } : {}),\n  };\n\n  const flags: LayerFlags = {\n    console: input.include_console,\n    network: input.include_network,\n    dom: input.include_dom,\n    performance: input.include_performance,\n  };\n\n  try {\n    // Cookies and storage are fixed when a context is created, so a state named\n    // here applies to the page this call opens; a session already running on\n    // the same state simply carries on (see `getSessionPage`).\n    const auth = await resolveStorageState(input.storage_state);\n    const storageState = auth ? { path: auth.path, state: auth.state } : undefined;\n\n    const { page, previousUrl, reopenedFor } = await getSessionPage({\n      ...(input.viewport ? { viewport: input.viewport } : {}),\n      hasTouch: needsTouch([step]),\n      ...(storageState ? { storageState } : {}),\n    });\n\n    // The layers belong to the page, not to this call (see SessionLayers), so\n    // they are installed once and emptied here — this call reports what this\n    // action caused, not what the last twenty did. Both happen before the\n    // navigation, so a page opened by `url` has its load watched too.\n    const layers = layersFor(page);\n    await layers.ensure(flags);\n    layers.clear();\n\n    // `previousUrl` means the session had to be reopened (for touch, or to take\n    // a different auth state); go back to where the user was unless they asked\n    // for somewhere else.\n    const target = input.url ?? previousUrl;\n    if (target !== undefined) {\n      await page.goto(target, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n      // A Vue app is acted on once it is mounted and its router has resolved;\n      // a plain page gets no extra wait beyond the brief look for one.\n      await waitForVueReady(page, { detect_ms: VUE_DETECT_MS, ready_ms: VUE_READY_TIMEOUT_MS });\n    }\n    if (page.url() === \"about:blank\") {\n      return errorResult(\n        \"Interaction failed: no page is open yet — pass `url` to open one (e.g. http://localhost:3000).\",\n      );\n    }\n\n    const vueBefore = await detectVue(page);\n    // A password field before the action and none after it is a login that\n    // just succeeded — the one moment the agent is thinking about auth.\n    const loginBefore = await loginFormVisible(page);\n    const before = await page.screenshot({ type: \"png\" });\n    const startedAt = Date.now();\n    const outcome = await executeInteraction(page, step, { timeout_ms: input.timeout_ms });\n    if (input.wait_ms > 0) {\n      await page.waitForTimeout(input.wait_ms);\n    }\n    const after = await page.screenshot({ type: \"png\" });\n    const vueAfter = vueBefore || step.action === \"navigate\" ? await detectVue(page) : null;\n    const loginAfter = await loginFormVisible(page);\n\n    const frames: RawFrame[] = [\n      { buffer: before, timestamp_ms: 0, is_interaction: false },\n      { buffer: after, timestamp_ms: Date.now() - startedAt, is_interaction: true },\n    ];\n    // sensitivity 0 keeps both frames however small the change is — the point\n    // of this tool is to show what one action did, including \"nothing\".\n    const { cards } = await buildDiffCards(frames, { sensitivity: 0, max_frames: 2 });\n    if (cards.length < 2) {\n      return errorResult(`Interaction failed: ${describeInteraction(step)} ran, but the screenshots could not be compared.`);\n    }\n\n    // `startedAt` is the instant of the \"before\" frame, which puts the split\n    // exactly where it belongs: everything from opening the page lands on the\n    // before card (negative, i.e. \"how we got here\") and everything the action\n    // caused lands on the after card.\n    const context = layers.collect(startedAt, flags);\n    applyContext(cards, context);\n\n    const [beforeCard, afterCard] = cards;\n    const viewport = page.viewportSize() ?? { width: 0, height: 0 };\n    const headline = [\n      `${summarise(step, page.url(), afterCard.change_region?.change_percent ?? 0, reopenedFor, input.ref, outcome.note)} — ${describeScale(viewport)}`,\n      ...describeRoute(vueBefore, vueAfter),\n      ...(summariseContext(context, cards.length) ?? []),\n      ...authLines(auth, input.url !== undefined && loginBefore, loginBefore && !loginAfter),\n    ].join(\"\\n\");\n\n    const content: CallToolResult[\"content\"] = [\n      { type: \"text\", text: headline },\n      { type: \"image\", data: beforeCard.full_frame, mimeType: \"image/png\" },\n      { type: \"text\", text: `Before — ${formatCardMeta(beforeCard)}` },\n      { type: \"image\", data: afterCard.full_frame, mimeType: \"image/png\" },\n      { type: \"text\", text: `After — ${formatCardMeta(afterCard)}` },\n    ];\n    const crop = afterCard.change_region?.crop;\n    if (crop) {\n      content.push(markImage({ type: \"image\", data: crop, mimeType: \"image/png\" }, { role: \"crop\" }));\n    }\n    if (input.include_snapshot) {\n      // Refs are reassigned by every snapshot, so the ones the caller used are\n      // stale the moment this runs — which is the point: these are the fresh ones.\n      const snapshot = await takeSnapshot(page, { mode: \"full\", max_chars: DEFAULT_SNAPSHOT_MAX_CHARS });\n      const lines = [`Snapshot — ${describeCounts(snapshot)} (refs valid until the page changes)`, \"\", snapshot.text];\n      if (snapshot.cut_lines > 0) lines.push(`… ${snapshot.cut_lines} more lines cut — use framewatch_snapshot with \\`selector\\` or mode \"interactive\".`);\n      content.push({ type: \"text\", text: lines.join(\"\\n\") });\n    }\n    hmrFor(page).markSeen();\n    return { content };\n  } catch (error) {\n    return errorResult(describeInteractFailure(input, error));\n  }\n}\n\n/**\n * The auth lines: what saved state was applied (and whether it worked, when\n * this call opened the page), and — when a login form was there before the\n * action and gone after it — the reminder to save the session now.\n */\nfunction authLines(auth: Awaited<ReturnType<typeof resolveStorageState>>, expired: boolean, justSignedIn: boolean): string[] {\n  const lines: string[] = [];\n  const applied = auth ? describeAuth(auth, expired) : null;\n  if (applied) lines.push(applied);\n  if (justSignedIn) {\n    lines.push(\n      \"Signed in? Save this session with framewatch_save_auth (same steps, from the login page) so every later call \" +\n        \"starts here instead of replaying the login.\",\n    );\n  }\n  return lines;\n}\n\n/**\n * The Vue line: the app and its route, and — when the action moved the\n * router — where it went, by name.\n */\nfunction describeRoute(before: VueInfo | null, after: VueInfo | null): string[] {\n  const current = after ?? before;\n  if (!current) return [];\n  const from = before?.route;\n  const to = after?.route;\n  if (from && to && from.path !== to.path) {\n    const name = (route: { path: string; name?: string }): string => `${route.path}${route.name ? ` (${route.name})` : \"\"}`;\n    return [`Vue ${current.version} — route ${name(from)} → ${name(to)}`];\n  }\n  return [describeVue(current)];\n}\n\n/** One line: what was done, where, and how much of the frame it moved. */\nfunction summarise(\n  step: Interaction,\n  url: string,\n  changePercent: number,\n  reopenedFor?: \"touch\" | \"auth\",\n  ref?: string,\n  note?: string,\n): string {\n  const reopened =\n    reopenedFor === \"touch\"\n      ? \" (page reopened to enable touch — page state was reset)\"\n      : reopenedFor === \"auth\"\n        ? \" (page reopened with the saved auth state — page state was reset)\"\n        : \"\";\n  const changed = changePercent > 0 ? `${changePercent.toFixed(1)}% of the frame changed` : \"no visual change\";\n  // The step carries the ref as an `aria-ref=` selector; the caller wrote `e8`.\n  const what = (ref !== undefined ? describeInteraction(step).replaceAll(`\"${refSelector(ref)}\"`, ref) : describeInteraction(step)) + (note ?? \"\");\n  return `${what} on ${url}${reopened} — ${changed}`;\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * Turn a failure into one actionable line. Interaction errors already name the\n * step and the reason (see `executeInteraction`), so they are passed through\n * with the page appended for context; everything else is a navigation or\n * browser problem, worded as in the other tools.\n */\nexport function describeInteractFailure(input: { url?: string; ref?: string }, error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n\n  if (input.ref !== undefined && message.includes(refSelector(input.ref))) {\n    return (\n      `Interaction failed: ref ${input.ref} did not resolve — the page has changed since that snapshot, or none was ` +\n      `taken on this page. Run framewatch_snapshot again and use a ref from it. (${firstLine.replaceAll(`\"${refSelector(input.ref)}\"`, input.ref)})`\n    );\n  }\n\n  if (/Executable doesn't exist|browserType\\.launch/i.test(message)) {\n    return (\n      \"Interaction failed: 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    return `Interaction failed: could not open ${input.url ?? \"the page\"} — ${firstLine}`;\n  }\n  return input.url ? `${firstLine} (page: ${input.url})` : firstLine;\n}\n\nexport function registerInteractTool(server: McpServer): void {\n  server.registerTool(\n    INTERACT_TOOL_NAME,\n    {\n      title: \"Interact\",\n      description:\n        \"Perform one interaction (click, tap, type, scroll, swipe, hover, select, navigate) on a page and return \" +\n        \"before/after screenshots plus a crop of what changed. The page stays open between calls, so you can \" +\n        \"click, look, type and look again without replaying the whole flow — pass `url` only to open or move it. \" +\n        \"Target an element by `ref` from framewatch_snapshot (e.g. `e8`) instead of guessing a selector; \" +\n        \"`include_snapshot` returns the fresh refs after the action. \" +\n        \"Each call also reports the context its own action produced: console output and uncaught errors (on by \" +\n        \"default), plus network requests, DOM mutations and paint/layout-shift timing via `include_network`, \" +\n        \"`include_dom` and `include_performance` — that is how you find out why a click did nothing.\",\n      inputSchema: interactInputShape,\n      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },\n    },\n    async (args) => performInteraction(args),\n  );\n}\n"]}

package/dist/tools/links.d.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare const LINKS_TOOL_NAME = "framewatch_links";
+export declare const linksInputShape: {
+    url: z.ZodString;
+    depth: z.ZodDefault<z.ZodNumber>;
+    check_external: z.ZodDefault<z.ZodBoolean>;
+    include_resources: z.ZodDefault<z.ZodBoolean>;
+    check_fragments: z.ZodDefault<z.ZodBoolean>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    max_links: z.ZodDefault<z.ZodNumber>;
+    max_pages: z.ZodDefault<z.ZodNumber>;
+    selector: z.ZodOptional<z.ZodString>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: 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 linksInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    depth: z.ZodDefault<z.ZodNumber>;
+    check_external: z.ZodDefault<z.ZodBoolean>;
+    include_resources: z.ZodDefault<z.ZodBoolean>;
+    check_fragments: z.ZodDefault<z.ZodBoolean>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    max_links: z.ZodDefault<z.ZodNumber>;
+    max_pages: z.ZodDefault<z.ZodNumber>;
+    selector: z.ZodOptional<z.ZodString>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: 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;
+    timeout_ms: number;
+    full_page: boolean;
+    include_resources: boolean;
+    depth: number;
+    check_external: boolean;
+    check_fragments: boolean;
+    concurrency: number;
+    max_links: number;
+    max_pages: number;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_for?: string | undefined;
+    storage_state?: string | undefined;
+    selector?: 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;
+    storage_state?: string | undefined;
+    timeout_ms?: number | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    include_resources?: boolean | undefined;
+    depth?: number | undefined;
+    check_external?: boolean | undefined;
+    check_fragments?: boolean | undefined;
+    concurrency?: number | undefined;
+    max_links?: number | undefined;
+    max_pages?: number | undefined;
+}>;
+export type LinksInput = z.input<typeof linksInputSchema>;
+/**
+ * Check every link on a page — and, on request, every link on the pages it
+ * leads to — and report the ones that do not work.
+ *
+ * The page is read after it has rendered rather than from its HTML source, so
+ * a client-rendered app is checked properly instead of being reported as
+ * having no links. The checks go out through the browser context, carrying the
+ * same cookies as the page, so a link behind a login is checked as the
+ * signed-in visitor sees it.
+ *
+ * Three things separate this from a HEAD loop. A HEAD that fails is retried as
+ * a GET before anything is called broken, because a great many servers refuse
+ * the method and serve the URL perfectly well. A status that means "I will not
+ * answer that" (401, 403, 429) is reported apart from one that means "there is
+ * nothing here", because a report that cries wolf gets ignored. And a
+ * same-page `#fragment` is checked against the document, which is the one
+ * broken link no HTTP check can ever find.
+ */
+export declare function checkLinks(rawInput: LinksInput): Promise<CallToolResult>;
+/**
+ * One actionable line for a check 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 describeLinksFailure(input: {
+    url: string;
+    wait_for?: string;
+    wait_for_timeout_ms: number;
+}, error: unknown): string;
+export declare function registerLinksTool(server: McpServer): void;