framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/tools/index.js

@@ -1,25 +1,69 @@
+import { fitToBudget } from "../utils/budget.js";
 import { registerAccessibilityTool } from "./accessibility.js";
+import { registerApiMockTool } from "./api-mock.js";
 import { registerCaptureTool } from "./capture.js";
 import { registerCompareTool } from "./compare.js";
+import { registerDeadClicksTool } from "./dead-clicks.js";
+import { registerFormTestTool } from "./form-test.js";
+import { registerInspectTool } from "./inspect.js";
 import { registerInteractTool } from "./interact.js";
+import { registerLinksTool } from "./links.js";
 import { registerResponsiveTool } from "./responsive.js";
+import { registerRtlTool } from "./rtl.js";
+import { registerSaveAuthTool } from "./save-auth.js";
 import { registerScreenshotTool } from "./screenshot.js";
+import { registerSeoTool } from "./seo.js";
 import { registerServerTools } from "./server.js";
+import { registerSnapshotTool } from "./snapshot.js";
+import { registerWaitForTool } from "./wait-for.js";
 export { registerScreenshotTool, takeScreenshot, SCREENSHOT_TOOL_NAME } from "./screenshot.js";
 export { registerCaptureTool, capturePage, CAPTURE_TOOL_NAME } from "./capture.js";
+export { registerApiMockTool, mockApi, API_MOCK_TOOL_NAME } from "./api-mock.js";
 export { registerInteractTool, performInteraction, INTERACT_TOOL_NAME } from "./interact.js";
+export { registerSnapshotTool, snapshotPage, SNAPSHOT_TOOL_NAME } from "./snapshot.js";
+export { registerInspectTool, inspectElements, INSPECT_TOOL_NAME } from "./inspect.js";
+export { registerWaitForTool, waitFor, WAIT_FOR_TOOL_NAME } from "./wait-for.js";
 export { registerResponsiveTool, captureResponsive, RESPONSIVE_TOOL_NAME } from "./responsive.js";
 export { registerAccessibilityTool, auditAccessibility, ACCESSIBILITY_TOOL_NAME } from "./accessibility.js";
 export { registerCompareTool, comparePages, COMPARE_TOOL_NAME, CURRENT_PAGE } from "./compare.js";
+export { registerSaveAuthTool, saveAuth, SAVE_AUTH_TOOL_NAME } from "./save-auth.js";
+export { registerFormTestTool, testForms, FORM_TEST_TOOL_NAME } from "./form-test.js";
+export { registerSeoTool, auditSeo, SEO_TOOL_NAME } from "./seo.js";
+export { registerDeadClicksTool, findDeadClicks, DEAD_CLICKS_TOOL_NAME } from "./dead-clicks.js";
+export { registerLinksTool, checkLinks, LINKS_TOOL_NAME } from "./links.js";
+export { registerRtlTool, testRtl, RTL_TOOL_NAME } from "./rtl.js";
 export { registerServerTools, startServer, stopServer, START_SERVER_TOOL_NAME, STOP_SERVER_TOOL_NAME, } from "./server.js";
-/** Register every FrameWatch tool on the given server. */
+/**
+ * Register every FrameWatch tool on the given server.
+ *
+ * Every handler is wrapped so its result passes through the image budget on
+ * the way out (see `utils/budget.ts`): a result over the client's cap loses
+ * all its images, so this is the one place that guarantees none ever is.
+ */
 export function registerAllTools(server) {
+    budgetEveryTool(server);
     registerScreenshotTool(server);
     registerCaptureTool(server);
     registerInteractTool(server);
+    registerSnapshotTool(server);
+    registerInspectTool(server);
+    registerWaitForTool(server);
     registerResponsiveTool(server);
     registerAccessibilityTool(server);
     registerCompareTool(server);
+    registerSaveAuthTool(server);
+    registerFormTestTool(server);
+    registerSeoTool(server);
+    registerDeadClicksTool(server);
+    registerLinksTool(server);
+    registerApiMockTool(server);
+    registerRtlTool(server);
     registerServerTools(server);
 }
+function budgetEveryTool(server) {
+    const original = server.registerTool.bind(server);
+    // The generic signature cannot be re-expressed around a wrapper without
+    // restating the SDK's types; the shape is (name, config, handler).
+    server.registerTool = (name, config, handler) => original(name, config, async (...args) => fitToBudget((await handler(...args))));
+}
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC5G,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAClG,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAErB,0DAA0D;AAC1D,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAChD,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC","sourcesContent":["import type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { registerAccessibilityTool } from \"./accessibility.js\";\nimport { registerCaptureTool } from \"./capture.js\";\nimport { registerCompareTool } from \"./compare.js\";\nimport { registerInteractTool } from \"./interact.js\";\nimport { registerResponsiveTool } from \"./responsive.js\";\nimport { registerScreenshotTool } from \"./screenshot.js\";\nimport { registerServerTools } from \"./server.js\";\n\nexport { registerScreenshotTool, takeScreenshot, SCREENSHOT_TOOL_NAME } from \"./screenshot.js\";\nexport { registerCaptureTool, capturePage, CAPTURE_TOOL_NAME } from \"./capture.js\";\nexport { registerInteractTool, performInteraction, INTERACT_TOOL_NAME } from \"./interact.js\";\nexport { registerResponsiveTool, captureResponsive, RESPONSIVE_TOOL_NAME } from \"./responsive.js\";\nexport { registerAccessibilityTool, auditAccessibility, ACCESSIBILITY_TOOL_NAME } from \"./accessibility.js\";\nexport { registerCompareTool, comparePages, COMPARE_TOOL_NAME, CURRENT_PAGE } from \"./compare.js\";\nexport {\n  registerServerTools,\n  startServer,\n  stopServer,\n  START_SERVER_TOOL_NAME,\n  STOP_SERVER_TOOL_NAME,\n} from \"./server.js\";\n\n/** Register every FrameWatch tool on the given server. */\nexport function registerAllTools(server: McpServer): void {\n  registerScreenshotTool(server);\n  registerCaptureTool(server);\n  registerInteractTool(server);\n  registerResponsiveTool(server);\n  registerAccessibilityTool(server);\n  registerCompareTool(server);\n  registerServerTools(server);\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { fitToBudget } from \"../utils/budget.js\";\nimport { registerAccessibilityTool } from \"./accessibility.js\";\nimport { registerApiMockTool } from \"./api-mock.js\";\nimport { registerCaptureTool } from \"./capture.js\";\nimport { registerCompareTool } from \"./compare.js\";\nimport { registerDeadClicksTool } from \"./dead-clicks.js\";\nimport { registerFormTestTool } from \"./form-test.js\";\nimport { registerInspectTool } from \"./inspect.js\";\nimport { registerInteractTool } from \"./interact.js\";\nimport { registerLinksTool } from \"./links.js\";\nimport { registerResponsiveTool } from \"./responsive.js\";\nimport { registerRtlTool } from \"./rtl.js\";\nimport { registerSaveAuthTool } from \"./save-auth.js\";\nimport { registerScreenshotTool } from \"./screenshot.js\";\nimport { registerSeoTool } from \"./seo.js\";\nimport { registerServerTools } from \"./server.js\";\nimport { registerSnapshotTool } from \"./snapshot.js\";\nimport { registerWaitForTool } from \"./wait-for.js\";\n\nexport { registerScreenshotTool, takeScreenshot, SCREENSHOT_TOOL_NAME } from \"./screenshot.js\";\nexport { registerCaptureTool, capturePage, CAPTURE_TOOL_NAME } from \"./capture.js\";\nexport { registerApiMockTool, mockApi, API_MOCK_TOOL_NAME } from \"./api-mock.js\";\nexport { registerInteractTool, performInteraction, INTERACT_TOOL_NAME } from \"./interact.js\";\nexport { registerSnapshotTool, snapshotPage, SNAPSHOT_TOOL_NAME } from \"./snapshot.js\";\nexport { registerInspectTool, inspectElements, INSPECT_TOOL_NAME } from \"./inspect.js\";\nexport { registerWaitForTool, waitFor, WAIT_FOR_TOOL_NAME } from \"./wait-for.js\";\nexport { registerResponsiveTool, captureResponsive, RESPONSIVE_TOOL_NAME } from \"./responsive.js\";\nexport { registerAccessibilityTool, auditAccessibility, ACCESSIBILITY_TOOL_NAME } from \"./accessibility.js\";\nexport { registerCompareTool, comparePages, COMPARE_TOOL_NAME, CURRENT_PAGE } from \"./compare.js\";\nexport { registerSaveAuthTool, saveAuth, SAVE_AUTH_TOOL_NAME } from \"./save-auth.js\";\nexport { registerFormTestTool, testForms, FORM_TEST_TOOL_NAME } from \"./form-test.js\";\nexport { registerSeoTool, auditSeo, SEO_TOOL_NAME } from \"./seo.js\";\nexport { registerDeadClicksTool, findDeadClicks, DEAD_CLICKS_TOOL_NAME } from \"./dead-clicks.js\";\nexport { registerLinksTool, checkLinks, LINKS_TOOL_NAME } from \"./links.js\";\nexport { registerRtlTool, testRtl, RTL_TOOL_NAME } from \"./rtl.js\";\nexport {\n  registerServerTools,\n  startServer,\n  stopServer,\n  START_SERVER_TOOL_NAME,\n  STOP_SERVER_TOOL_NAME,\n} from \"./server.js\";\n\n/**\n * Register every FrameWatch tool on the given server.\n *\n * Every handler is wrapped so its result passes through the image budget on\n * the way out (see `utils/budget.ts`): a result over the client's cap loses\n * all its images, so this is the one place that guarantees none ever is.\n */\nexport function registerAllTools(server: McpServer): void {\n  budgetEveryTool(server);\n  registerScreenshotTool(server);\n  registerCaptureTool(server);\n  registerInteractTool(server);\n  registerSnapshotTool(server);\n  registerInspectTool(server);\n  registerWaitForTool(server);\n  registerResponsiveTool(server);\n  registerAccessibilityTool(server);\n  registerCompareTool(server);\n  registerSaveAuthTool(server);\n  registerFormTestTool(server);\n  registerSeoTool(server);\n  registerDeadClicksTool(server);\n  registerLinksTool(server);\n  registerApiMockTool(server);\n  registerRtlTool(server);\n  registerServerTools(server);\n}\n\nfunction budgetEveryTool(server: McpServer): void {\n  const original = server.registerTool.bind(server) as (...args: unknown[]) => unknown;\n  // The generic signature cannot be re-expressed around a wrapper without\n  // restating the SDK's types; the shape is (name, config, handler).\n  (server as unknown as { registerTool: unknown }).registerTool = (name: unknown, config: unknown, handler: (...args: unknown[]) => unknown) =>\n    original(name, config, async (...args: unknown[]) => fitToBudget((await handler(...args)) as Parameters<typeof fitToBudget>[0]));\n}\n"]}

package/dist/tools/inspect.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare const INSPECT_TOOL_NAME = "framewatch_inspect";
+export declare const inspectInputShape: {
+    url: z.ZodOptional<z.ZodString>;
+    targets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    selector: z.ZodOptional<z.ZodString>;
+    include_screenshot: z.ZodDefault<z.ZodBoolean>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
+};
+export declare const inspectInputSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    targets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    selector: z.ZodOptional<z.ZodString>;
+    include_screenshot: z.ZodDefault<z.ZodBoolean>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    wait_ms: number;
+    wait_for_timeout_ms: number;
+    include_screenshot: boolean;
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_for?: string | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+    targets?: string[] | undefined;
+}, {
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_ms?: number | undefined;
+    wait_for?: string | undefined;
+    wait_for_timeout_ms?: number | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+    include_screenshot?: boolean | undefined;
+    targets?: string[] | undefined;
+}>;
+export type InspectInput = z.input<typeof inspectInputSchema>;
+/**
+ * Measure how elements are built — box, type, colours with contrast, spacing,
+ * alignment — or, with no targets, what the whole page is built from. Runs on
+ * the interact session's page so a ref from the last snapshot resolves.
+ */
+export declare function inspectElements(rawInput: InspectInput): Promise<CallToolResult>;
+export declare function registerInspectTool(server: McpServer): void;

package/dist/tools/inspect.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { DEFAULT_SNAPSHOT_WAIT_MS, HIGHLIGHT_INSPECT_COLOUR, MAX_INSPECT_TARGETS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, SELECTOR_TIMEOUT_MS, } from "../constants.js";
+import { withSessionLock } from "../engine/browser.js";
+import { hmrFor } from "../engine/hmr.js";
+import { inventoryPage, measureElements } from "../engine/inspect.js";
+import { describeScale } from "../utils/format.js";
+import { clearHighlights, highlightElements } from "../utils/highlight.js";
+import { resizeForOutput, toBase64 } from "../utils/image.js";
+import { storageStateField, withAuthNote } from "../utils/storage-state.js";
+import { formatInspection, formatInventory } from "../utils/style-rules.js";
+import { describeVue, formatComponentLine } from "../utils/vue-rules.js";
+import { describeSessionFailure, openSessionPage } from "./snapshot.js";
+export const INSPECT_TOOL_NAME = "framewatch_inspect";
+export const inspectInputShape = {
+    url: z
+        .string()
+        .url()
+        .optional()
+        .describe("Open this URL first. Omit to measure the page left open by framewatch_interact / framewatch_snapshot."),
+    targets: z
+        .array(z.string().min(1))
+        .max(MAX_INSPECT_TARGETS)
+        .optional()
+        .describe("What to measure: snapshot refs (`e8`) and/or CSS selectors, in order. Omit for a design inventory of the whole page instead."),
+    selector: z.string().optional().describe("For the inventory: only count elements inside this container"),
+    include_screenshot: z.boolean().default(true).describe("With `targets`: return a screenshot with each target boxed and numbered"),
+    wait_ms: z
+        .number()
+        .int()
+        .min(0)
+        .default(DEFAULT_SNAPSHOT_WAIT_MS)
+        .describe("Settle time (ms) after opening `url`, so a client-rendered app has drawn"),
+    wait_for: z.string().optional().describe("CSS selector to wait for (visible) before measuring"),
+    wait_for_timeout_ms: z.number().int().min(1).default(SELECTOR_TIMEOUT_MS).describe("Max time (ms) to wait for `wait_for`"),
+    viewport: z
+        .object({
+        width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH),
+        height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT),
+    })
+        .optional()
+        .describe("Resize the page to this first (defaults to leaving it as it is)"),
+    storage_state: storageStateField,
+};
+export const inspectInputSchema = z.object(inspectInputShape);
+/**
+ * Measure how elements are built — box, type, colours with contrast, spacing,
+ * alignment — or, with no targets, what the whole page is built from. Runs on
+ * the interact session's page so a ref from the last snapshot resolves.
+ */
+export function inspectElements(rawInput) {
+    return withSessionLock(() => runInspect(rawInput));
+}
+async function runInspect(rawInput) {
+    const parsed = inspectInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Inspect failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    try {
+        const opened = await openSessionPage(input, "Inspect");
+        if ("error" in opened)
+            return errorResult(opened.error);
+        const { page, vue, auth, login_visible } = opened;
+        const viewport = page.viewportSize() ?? { width: 0, height: 0 };
+        const vueLine = vue ? ` — ${describeVue(vue)}` : "";
+        if (!input.targets || input.targets.length === 0) {
+            const inventory = await inventoryPage(page, input.selector);
+            const lines = formatInventory(inventory);
+            lines.push(`Page: ${page.url()} — ${describeScale(viewport).replace(/, images.*$/, "")}${vueLine}${input.selector ? ` — scope ${input.selector}` : ""}`);
+            hmrFor(page).markSeen();
+            return withAuthNote({ content: [{ type: "text", text: lines.join("\n") }] }, auth, login_visible);
+        }
+        // Component data is only worth asking for on a Vue page; elsewhere the
+        // question costs an evaluate per target and always answers "none".
+        const results = await measureElements(page, input.targets, { components: vue !== null });
+        const measured = results.filter((r) => r.measurement !== undefined).length;
+        const lines = [
+            `Inspected ${measured} of ${results.length} targets on ${page.url()} — ${describeScale(viewport)}${vueLine}`,
+            ...results.flatMap((result, i) => formatResult(result, i + 1)),
+        ];
+        const content = [{ type: "text", text: lines.join("\n") }];
+        if (input.include_screenshot && measured > 0) {
+            content.push({ type: "image", data: await boxedScreenshot(page, results), mimeType: "image/png" });
+        }
+        hmrFor(page).markSeen();
+        return withAuthNote({ content }, auth, login_visible);
+    }
+    catch (error) {
+        return errorResult(describeSessionFailure("Inspect", input, error));
+    }
+}
+function formatResult(result, index) {
+    if (!result.measurement)
+        return [`${index}. ${result.target} — ${result.error ?? "not measured"}`];
+    const lines = formatInspection(result.measurement, index);
+    if (result.component)
+        lines.push(`   ${formatComponentLine(result.component)}`);
+    return lines;
+}
+/** The page with every measured target boxed, numbered to match the list. */
+async function boxedScreenshot(page, results) {
+    const highlights = [];
+    results.forEach((result, i) => {
+        const m = result.measurement;
+        if (!m || m.box.width <= 0 || m.box.height <= 0)
+            return;
+        highlights.push({ selector: result.target, box: m.box, label: String(i + 1), colour: HIGHLIGHT_INSPECT_COLOUR });
+    });
+    await highlightElements(page, highlights);
+    try {
+        const png = await page.screenshot({ type: "png" });
+        return toBase64(await resizeForOutput(png));
+    }
+    finally {
+        await clearHighlights(page);
+    }
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+export function registerInspectTool(server) {
+    server.registerTool(INSPECT_TOOL_NAME, {
+        title: "Inspect",
+        description: "Measure how elements are actually built, to check UI work against what was intended: the box in viewport " +
+            "pixels, font family/size/weight/line-height, text and effective background colour with the WCAG contrast " +
+            "ratio, padding, margin, gap, border and radius, whether it is visible, clipped or overflowing, and how it " +
+            "aligns to its parent and previous sibling — plus a screenshot with each target boxed. Targets are refs from " +
+            "framewatch_snapshot (`e8`) or CSS selectors. With no targets it returns a design inventory of the page: every " +
+            "font, size, weight, colour, spacing value and radius in use, with counts — the fastest way to spot the one " +
+            "13px label on a 14px page.",
+        inputSchema: inspectInputShape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => inspectElements(args));
+}
+//# sourceMappingURL=inspect.js.map

package/dist/tools/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/tools/inspect.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_SNAPSHOT_WAIT_MS,\n  HIGHLIGHT_INSPECT_COLOUR,\n  MAX_INSPECT_TARGETS,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  SELECTOR_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { withSessionLock } from \"../engine/browser.js\";\nimport { hmrFor } from \"../engine/hmr.js\";\nimport { inventoryPage, measureElements, type InspectResult } from \"../engine/inspect.js\";\nimport { describeScale } from \"../utils/format.js\";\nimport { clearHighlights, highlightElements, type Highlight } from \"../utils/highlight.js\";\nimport { resizeForOutput, toBase64 } from \"../utils/image.js\";\nimport { storageStateField, withAuthNote } from \"../utils/storage-state.js\";\nimport { formatInspection, formatInventory } from \"../utils/style-rules.js\";\nimport { describeVue, formatComponentLine } from \"../utils/vue-rules.js\";\nimport { describeSessionFailure, openSessionPage } from \"./snapshot.js\";\n\nexport const INSPECT_TOOL_NAME = \"framewatch_inspect\";\n\nexport const inspectInputShape = {\n  url: z\n    .string()\n    .url()\n    .optional()\n    .describe(\"Open this URL first. Omit to measure the page left open by framewatch_interact / framewatch_snapshot.\"),\n  targets: z\n    .array(z.string().min(1))\n    .max(MAX_INSPECT_TARGETS)\n    .optional()\n    .describe(\n      \"What to measure: snapshot refs (`e8`) and/or CSS selectors, in order. Omit for a design inventory of the whole page instead.\",\n    ),\n  selector: z.string().optional().describe(\"For the inventory: only count elements inside this container\"),\n  include_screenshot: z.boolean().default(true).describe(\"With `targets`: return a screenshot with each target boxed and numbered\"),\n  wait_ms: z\n    .number()\n    .int()\n    .min(0)\n    .default(DEFAULT_SNAPSHOT_WAIT_MS)\n    .describe(\"Settle time (ms) after opening `url`, so a client-rendered app has drawn\"),\n  wait_for: z.string().optional().describe(\"CSS selector to wait for (visible) before measuring\"),\n  wait_for_timeout_ms: z.number().int().min(1).default(SELECTOR_TIMEOUT_MS).describe(\"Max time (ms) to wait for `wait_for`\"),\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 first (defaults to leaving it as it is)\"),\n  storage_state: storageStateField,\n};\n\nexport const inspectInputSchema = z.object(inspectInputShape);\nexport type InspectInput = z.input<typeof inspectInputSchema>;\n\n/**\n * Measure how elements are built — box, type, colours with contrast, spacing,\n * alignment — or, with no targets, what the whole page is built from. Runs on\n * the interact session's page so a ref from the last snapshot resolves.\n */\nexport function inspectElements(rawInput: InspectInput): Promise<CallToolResult> {\n  return withSessionLock(() => runInspect(rawInput));\n}\n\nasync function runInspect(rawInput: InspectInput): Promise<CallToolResult> {\n  const parsed = inspectInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Inspect failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n\n  try {\n    const opened = await openSessionPage(input, \"Inspect\");\n    if (\"error\" in opened) return errorResult(opened.error);\n    const { page, vue, auth, login_visible } = opened;\n    const viewport = page.viewportSize() ?? { width: 0, height: 0 };\n    const vueLine = vue ? ` — ${describeVue(vue)}` : \"\";\n\n    if (!input.targets || input.targets.length === 0) {\n      const inventory = await inventoryPage(page, input.selector);\n      const lines = formatInventory(inventory);\n      lines.push(`Page: ${page.url()} — ${describeScale(viewport).replace(/, images.*$/, \"\")}${vueLine}${input.selector ? ` — scope ${input.selector}` : \"\"}`);\n      hmrFor(page).markSeen();\n      return withAuthNote({ content: [{ type: \"text\", text: lines.join(\"\\n\") }] }, auth, login_visible);\n    }\n\n    // Component data is only worth asking for on a Vue page; elsewhere the\n    // question costs an evaluate per target and always answers \"none\".\n    const results = await measureElements(page, input.targets, { components: vue !== null });\n    const measured = results.filter((r) => r.measurement !== undefined).length;\n    const lines = [\n      `Inspected ${measured} of ${results.length} targets on ${page.url()} — ${describeScale(viewport)}${vueLine}`,\n      ...results.flatMap((result, i) => formatResult(result, i + 1)),\n    ];\n\n    const content: CallToolResult[\"content\"] = [{ type: \"text\", text: lines.join(\"\\n\") }];\n    if (input.include_screenshot && measured > 0) {\n      content.push({ type: \"image\", data: await boxedScreenshot(page, results), mimeType: \"image/png\" });\n    }\n    hmrFor(page).markSeen();\n    return withAuthNote({ content }, auth, login_visible);\n  } catch (error) {\n    return errorResult(describeSessionFailure(\"Inspect\", input, error));\n  }\n}\n\nfunction formatResult(result: InspectResult, index: number): string[] {\n  if (!result.measurement) return [`${index}. ${result.target} — ${result.error ?? \"not measured\"}`];\n  const lines = formatInspection(result.measurement, index);\n  if (result.component) lines.push(`   ${formatComponentLine(result.component)}`);\n  return lines;\n}\n\n/** The page with every measured target boxed, numbered to match the list. */\nasync function boxedScreenshot(page: Parameters<typeof highlightElements>[0], results: InspectResult[]): Promise<string> {\n  const highlights: Highlight[] = [];\n  results.forEach((result, i) => {\n    const m = result.measurement;\n    if (!m || m.box.width <= 0 || m.box.height <= 0) return;\n    highlights.push({ selector: result.target, box: m.box, label: String(i + 1), colour: HIGHLIGHT_INSPECT_COLOUR });\n  });\n  await highlightElements(page, highlights);\n  try {\n    const png = await page.screenshot({ type: \"png\" });\n    return toBase64(await resizeForOutput(png));\n  } finally {\n    await clearHighlights(page);\n  }\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\nexport function registerInspectTool(server: McpServer): void {\n  server.registerTool(\n    INSPECT_TOOL_NAME,\n    {\n      title: \"Inspect\",\n      description:\n        \"Measure how elements are actually built, to check UI work against what was intended: the box in viewport \" +\n        \"pixels, font family/size/weight/line-height, text and effective background colour with the WCAG contrast \" +\n        \"ratio, padding, margin, gap, border and radius, whether it is visible, clipped or overflowing, and how it \" +\n        \"aligns to its parent and previous sibling — plus a screenshot with each target boxed. Targets are refs from \" +\n        \"framewatch_snapshot (`e8`) or CSS selectors. With no targets it returns a design inventory of the page: every \" +\n        \"font, size, weight, colour, spacing value and radius in use, with counts — the fastest way to spot the one \" +\n        \"13px label on a 14px page.\",\n      inputSchema: inspectInputShape,\n      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => inspectElements(args),\n  );\n}\n"]}

package/dist/tools/interact.d.ts

@@ -3,6 +3,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export declare const INTERACT_TOOL_NAME = "framewatch_interact";
 export declare const interactInputShape: {
+    ref: z.ZodOptional<z.ZodString>;
     url: z.ZodOptional<z.ZodString>;
     wait_ms: z.ZodDefault<z.ZodNumber>;
     timeout_ms: z.ZodDefault<z.ZodNumber>;
@@ -20,15 +21,18 @@ export declare const interactInputShape: {
     include_network: z.ZodDefault<z.ZodBoolean>;
     include_dom: z.ZodDefault<z.ZodBoolean>;
     include_performance: z.ZodDefault<z.ZodBoolean>;
+    include_snapshot: z.ZodDefault<z.ZodBoolean>;
+    storage_state: z.ZodOptional<z.ZodString>;
     selector: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
     x: z.ZodOptional<z.ZodNumber>;
     y: z.ZodOptional<z.ZodNumber>;
     delta_x: z.ZodOptional<z.ZodNumber>;
     delta_y: z.ZodOptional<z.ZodNumber>;
-    action: z.ZodEnum<["click", "tap", "type", "scroll", "swipe", "navigate", "select", "hover"]>;
+    action: z.ZodEnum<["click", "tap", "type", "key", "scroll", "swipe", "navigate", "select", "hover"]>;
 };
 export declare const interactInputSchema: z.ZodEffects<z.ZodObject<{
+    ref: z.ZodOptional<z.ZodString>;
     url: z.ZodOptional<z.ZodString>;
     wait_ms: z.ZodDefault<z.ZodNumber>;
     timeout_ms: z.ZodDefault<z.ZodNumber>;
@@ -46,43 +50,50 @@ export declare const interactInputSchema: z.ZodEffects<z.ZodObject<{
     include_network: z.ZodDefault<z.ZodBoolean>;
     include_dom: z.ZodDefault<z.ZodBoolean>;
     include_performance: z.ZodDefault<z.ZodBoolean>;
+    include_snapshot: z.ZodDefault<z.ZodBoolean>;
+    storage_state: z.ZodOptional<z.ZodString>;
     selector: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
     x: z.ZodOptional<z.ZodNumber>;
     y: z.ZodOptional<z.ZodNumber>;
     delta_x: z.ZodOptional<z.ZodNumber>;
     delta_y: z.ZodOptional<z.ZodNumber>;
-    action: z.ZodEnum<["click", "tap", "type", "scroll", "swipe", "navigate", "select", "hover"]>;
+    action: z.ZodEnum<["click", "tap", "type", "key", "scroll", "swipe", "navigate", "select", "hover"]>;
 }, "strip", z.ZodTypeAny, {
     wait_ms: number;
-    action: "type" | "click" | "tap" | "scroll" | "swipe" | "navigate" | "select" | "hover";
+    timeout_ms: number;
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "navigate";
     include_console: boolean;
     include_network: boolean;
     include_dom: boolean;
     include_performance: boolean;
-    timeout_ms: number;
+    include_snapshot: boolean;
+    url?: string | undefined;
+    value?: string | undefined;
     viewport?: {
         width: number;
         height: number;
     } | undefined;
-    value?: string | undefined;
-    url?: string | undefined;
+    storage_state?: string | undefined;
     x?: number | undefined;
     y?: number | undefined;
     selector?: string | undefined;
     delta_x?: number | undefined;
     delta_y?: number | undefined;
+    ref?: string | undefined;
 }, {
-    action: "type" | "click" | "tap" | "scroll" | "swipe" | "navigate" | "select" | "hover";
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "navigate";
+    url?: string | undefined;
+    value?: string | undefined;
     viewport?: {
         width: number;
         height: number;
     } | undefined;
-    value?: string | undefined;
-    url?: string | undefined;
     wait_ms?: number | undefined;
+    storage_state?: string | undefined;
     x?: number | undefined;
     y?: number | undefined;
+    timeout_ms?: number | undefined;
     selector?: string | undefined;
     delta_x?: number | undefined;
     delta_y?: number | undefined;
@@ -90,37 +101,43 @@ export declare const interactInputSchema: z.ZodEffects<z.ZodObject<{
     include_network?: boolean | undefined;
     include_dom?: boolean | undefined;
     include_performance?: boolean | undefined;
-    timeout_ms?: number | undefined;
+    ref?: string | undefined;
+    include_snapshot?: boolean | undefined;
 }>, {
     wait_ms: number;
-    action: "type" | "click" | "tap" | "scroll" | "swipe" | "navigate" | "select" | "hover";
+    timeout_ms: number;
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "navigate";
     include_console: boolean;
     include_network: boolean;
     include_dom: boolean;
     include_performance: boolean;
-    timeout_ms: number;
+    include_snapshot: boolean;
+    url?: string | undefined;
+    value?: string | undefined;
     viewport?: {
         width: number;
         height: number;
     } | undefined;
-    value?: string | undefined;
-    url?: string | undefined;
+    storage_state?: string | undefined;
     x?: number | undefined;
     y?: number | undefined;
     selector?: string | undefined;
     delta_x?: number | undefined;
     delta_y?: number | undefined;
+    ref?: string | undefined;
 }, {
-    action: "type" | "click" | "tap" | "scroll" | "swipe" | "navigate" | "select" | "hover";
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "navigate";
+    url?: string | undefined;
+    value?: string | undefined;
     viewport?: {
         width: number;
         height: number;
     } | undefined;
-    value?: string | undefined;
-    url?: string | undefined;
     wait_ms?: number | undefined;
+    storage_state?: string | undefined;
     x?: number | undefined;
     y?: number | undefined;
+    timeout_ms?: number | undefined;
     selector?: string | undefined;
     delta_x?: number | undefined;
     delta_y?: number | undefined;
@@ -128,7 +145,8 @@ export declare const interactInputSchema: z.ZodEffects<z.ZodObject<{
     include_network?: boolean | undefined;
     include_dom?: boolean | undefined;
     include_performance?: boolean | undefined;
-    timeout_ms?: number | undefined;
+    ref?: string | undefined;
+    include_snapshot?: boolean | undefined;
 }>;
 export type InteractInput = z.input<typeof interactInputSchema>;
 /**
@@ -156,5 +174,6 @@ export declare function performInteraction(rawInput: InteractInput): Promise<Cal
  */
 export declare function describeInteractFailure(input: {
     url?: string;
+    ref?: string;
 }, error: unknown): string;
 export declare function registerInteractTool(server: McpServer): void;