framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/tools/snapshot.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { DEFAULT_SNAPSHOT_MAX_CHARS, DEFAULT_SNAPSHOT_WAIT_MS, MAX_SNAPSHOT_MAX_CHARS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS, VUE_READY_TIMEOUT_MS, } from "../constants.js";
+import { getSessionPage, withSessionLock } from "../engine/browser.js";
+import { hmrFor } from "../engine/hmr.js";
+import { takeSnapshot } from "../engine/snapshot.js";
+import { componentTree, detectVue, waitForVueReady } from "../engine/vue.js";
+import { describeVue, formatComponentTree } from "../utils/vue-rules.js";
+import { describeScale } from "../utils/format.js";
+import { resizeForOutput, toBase64 } from "../utils/image.js";
+import { loginFormVisible, resolveStorageState, storageStateField, withAuthNote } from "../utils/storage-state.js";
+export const SNAPSHOT_TOOL_NAME = "framewatch_snapshot";
+export const snapshotInputShape = {
+    url: z
+        .string()
+        .url()
+        .optional()
+        .describe("Open this URL first. Omit to read the page left open by framewatch_interact / framewatch_inspect."),
+    selector: z.string().optional().describe("Only this container, e.g. `main` or `#checkout`"),
+    mode: z
+        .enum(["full", "interactive"])
+        .default("full")
+        .describe("`full` is the whole tree with headings and text; `interactive` is a flat list of what can be clicked, typed into or chosen"),
+    max_chars: z
+        .number()
+        .int()
+        .min(200)
+        .max(MAX_SNAPSHOT_MAX_CHARS)
+        .default(DEFAULT_SNAPSHOT_MAX_CHARS)
+        .describe("Cut the tree past this many characters (a note says how many lines went)"),
+    include_screenshot: z.boolean().default(false).describe("Also return a screenshot of the page as it was read"),
+    include_components: z
+        .boolean()
+        .default(false)
+        .describe("On a Vue app: also return the component tree (names and nesting) from the root"),
+    wait_ms: z
+        .number()
+        .int()
+        .min(0)
+        .default(DEFAULT_SNAPSHOT_WAIT_MS)
+        .describe("Settle time (ms) after opening `url`. On a Vue app this is a ceiling: the page is read as soon as the app " +
+        "is mounted and its router ready"),
+    wait_for: z.string().optional().describe("CSS selector to wait for (visible) before reading"),
+    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 snapshotInputSchema = z.object(snapshotInputShape);
+/**
+ * Read the page as a tree of named elements, on the interact session's page so
+ * the refs it hands out are the ones the next `framewatch_interact` or
+ * `framewatch_inspect` can use.
+ */
+export function snapshotPage(rawInput) {
+    return withSessionLock(() => runSnapshot(rawInput));
+}
+async function runSnapshot(rawInput) {
+    const parsed = snapshotInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Snapshot failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    try {
+        const opened = await openSessionPage(input, "Snapshot");
+        if ("error" in opened)
+            return errorResult(opened.error);
+        const { page, vue, auth, login_visible } = opened;
+        const snapshot = await takeSnapshot(page, {
+            ...(input.selector ? { selector: input.selector } : {}),
+            mode: input.mode,
+            max_chars: input.max_chars,
+        });
+        const viewport = page.viewportSize() ?? { width: 0, height: 0 };
+        const title = await page.title().catch(() => "");
+        const lines = [
+            `Snapshot of ${page.url()}${title ? ` — "${title}"` : ""} — ${describeScale(viewport).replace(/, images.*$/, "")} — ${describeCounts(snapshot)}${vue ? ` — ${describeVue(vue)}` : ""}`,
+            ...(input.include_screenshot ? [describeScale(viewport)] : []),
+            ...(input.selector ? [`Scope: ${input.selector}`] : []),
+            REF_HINT,
+            "",
+            snapshot.text,
+            ...(snapshot.cut_lines > 0
+                ? [`… ${snapshot.cut_lines} more lines cut — raise \`max_chars\`, pass \`selector\`, or use mode "interactive".`]
+                : []),
+        ];
+        if (input.include_components) {
+            lines.push("", ...(await describeComponents(page, vue)));
+        }
+        const content = [{ type: "text", text: lines.join("\n") }];
+        if (input.include_screenshot) {
+            const png = await page.screenshot({ type: "png" });
+            content.unshift({ type: "image", data: toBase64(await resizeForOutput(png)), mimeType: "image/png" });
+        }
+        hmrFor(page).markSeen();
+        return withAuthNote({ content }, auth, login_visible);
+    }
+    catch (error) {
+        return errorResult(describeSessionFailure("Snapshot", input, error));
+    }
+}
+const REF_HINT = "Refs: pass one as `ref` to framewatch_interact (to act on it) or framewatch_inspect (to measure it). " +
+    "They stay valid until the page changes — snapshot again after an action that re-rendered. " +
+    'In a framewatch_capture script, target the same element with a selector such as role=button[name="Sign in"].';
+export function describeCounts(snapshot) {
+    return `${snapshot.elements} elements, ${snapshot.interactive} interactive`;
+}
+/** The component tree, or why there is none. */
+async function describeComponents(page, vue) {
+    if (!vue)
+        return ["Components: no Vue app on this page"];
+    if (vue.major < 3)
+        return ["Components: Vue 2 — component details need Vue 3"];
+    if (vue.production)
+        return ["Components: production build — no component data on elements"];
+    const tree = await componentTree(page);
+    if (!tree)
+        return ["Components: could not be read"];
+    return formatComponentTree(tree.root, tree.total);
+}
+export async function openSessionPage(input, toolName) {
+    const options = {};
+    if (input.viewport)
+        options.viewport = input.viewport;
+    const auth = await resolveStorageState(input.storage_state);
+    if (auth)
+        options.storageState = { path: auth.path, state: auth.state };
+    const { page, previousUrl } = await getSessionPage(options);
+    const target = input.url ?? previousUrl;
+    if (target !== undefined) {
+        await page.goto(target, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
+        if (input.wait_for) {
+            await page.waitForSelector(input.wait_for, { state: "visible", timeout: input.wait_for_timeout_ms ?? SELECTOR_TIMEOUT_MS });
+        }
+        // `wait_ms` is a ceiling, not a sleep: a Vue app is read the moment it is
+        // mounted and its router has resolved; a page without one gets the full wait.
+        const { vue } = await waitForVueReady(page, { detect_ms: input.wait_ms ?? 0, ready_ms: VUE_READY_TIMEOUT_MS });
+        if (page.url() === "about:blank")
+            return { error: noPage(toolName) };
+        return { page, vue, auth, login_visible: auth && input.url !== undefined ? await loginFormVisible(page) : false };
+    }
+    if (page.url() === "about:blank")
+        return { error: noPage(toolName) };
+    return { page, vue: await detectVue(page), auth, login_visible: false };
+}
+function noPage(toolName) {
+    return `${toolName} failed: no page is open yet — pass \`url\` to open one (e.g. http://localhost:3000).`;
+}
+export function describeSessionFailure(toolName, input, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = message.split("\n")[0];
+    if (/Executable doesn't exist|browserType\.launch/i.test(message)) {
+        return `${toolName} failed: Playwright's Chromium browser is not installed. Run \`npx playwright install chromium\` and try again. (${firstLine})`;
+    }
+    if (/^page\.goto:/.test(message)) {
+        return `${toolName} failed: could not open ${input.url ?? "the page"} — ${firstLine}`;
+    }
+    if (input.wait_for && /^page\.waitForSelector:/.test(message)) {
+        return `${toolName} failed: selector "${input.wait_for}" did not become visible within ${input.wait_for_timeout_ms ?? SELECTOR_TIMEOUT_MS}ms.`;
+    }
+    return `${toolName} failed: ${firstLine}`;
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+export function registerSnapshotTool(server) {
+    server.registerTool(SNAPSHOT_TOOL_NAME, {
+        title: "Snapshot",
+        description: "Read the page as a tree of named elements — every heading, field, button and link with its accessible name " +
+            "and a short ref like `e8` — so you know what is on the page and what to call it instead of guessing selectors " +
+            "from a screenshot. Pass a ref as `ref` to framewatch_interact to act on that element, or to framewatch_inspect " +
+            "to measure it. Works on the page framewatch_interact keeps open; pass `url` to open one. " +
+            "Use mode `interactive` for a short list of only what can be acted on.",
+        inputSchema: snapshotInputShape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => snapshotPage(args));
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/tools/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/tools/snapshot.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_MAX_CHARS,\n  DEFAULT_SNAPSHOT_WAIT_MS,\n  MAX_SNAPSHOT_MAX_CHARS,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  NAVIGATION_TIMEOUT_MS,\n  SELECTOR_TIMEOUT_MS,\n  VUE_READY_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { getSessionPage, withSessionLock, type SessionOptions } from \"../engine/browser.js\";\nimport { hmrFor } from \"../engine/hmr.js\";\nimport { takeSnapshot, type PageSnapshot } from \"../engine/snapshot.js\";\nimport { componentTree, detectVue, waitForVueReady } from \"../engine/vue.js\";\nimport { describeVue, formatComponentTree, type VueInfo } from \"../utils/vue-rules.js\";\nimport { describeScale } from \"../utils/format.js\";\nimport { resizeForOutput, toBase64 } from \"../utils/image.js\";\nimport { loginFormVisible, resolveStorageState, storageStateField, withAuthNote, type ResolvedAuth } from \"../utils/storage-state.js\";\nimport type { Viewport } from \"../types.js\";\n\nexport const SNAPSHOT_TOOL_NAME = \"framewatch_snapshot\";\n\nexport const snapshotInputShape = {\n  url: z\n    .string()\n    .url()\n    .optional()\n    .describe(\"Open this URL first. Omit to read the page left open by framewatch_interact / framewatch_inspect.\"),\n  selector: z.string().optional().describe(\"Only this container, e.g. `main` or `#checkout`\"),\n  mode: z\n    .enum([\"full\", \"interactive\"])\n    .default(\"full\")\n    .describe(\"`full` is the whole tree with headings and text; `interactive` is a flat list of what can be clicked, typed into or chosen\"),\n  max_chars: z\n    .number()\n    .int()\n    .min(200)\n    .max(MAX_SNAPSHOT_MAX_CHARS)\n    .default(DEFAULT_SNAPSHOT_MAX_CHARS)\n    .describe(\"Cut the tree past this many characters (a note says how many lines went)\"),\n  include_screenshot: z.boolean().default(false).describe(\"Also return a screenshot of the page as it was read\"),\n  include_components: z\n    .boolean()\n    .default(false)\n    .describe(\"On a Vue app: also return the component tree (names and nesting) from the root\"),\n  wait_ms: z\n    .number()\n    .int()\n    .min(0)\n    .default(DEFAULT_SNAPSHOT_WAIT_MS)\n    .describe(\n      \"Settle time (ms) after opening `url`. On a Vue app this is a ceiling: the page is read as soon as the app \" +\n        \"is mounted and its router ready\",\n    ),\n  wait_for: z.string().optional().describe(\"CSS selector to wait for (visible) before reading\"),\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 snapshotInputSchema = z.object(snapshotInputShape);\nexport type SnapshotInput = z.input<typeof snapshotInputSchema>;\n\n/**\n * Read the page as a tree of named elements, on the interact session's page so\n * the refs it hands out are the ones the next `framewatch_interact` or\n * `framewatch_inspect` can use.\n */\nexport function snapshotPage(rawInput: SnapshotInput): Promise<CallToolResult> {\n  return withSessionLock(() => runSnapshot(rawInput));\n}\n\nasync function runSnapshot(rawInput: SnapshotInput): Promise<CallToolResult> {\n  const parsed = snapshotInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Snapshot failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n\n  try {\n    const opened = await openSessionPage(input, \"Snapshot\");\n    if (\"error\" in opened) return errorResult(opened.error);\n    const { page, vue, auth, login_visible } = opened;\n\n    const snapshot = await takeSnapshot(page, {\n      ...(input.selector ? { selector: input.selector } : {}),\n      mode: input.mode,\n      max_chars: input.max_chars,\n    });\n\n    const viewport = page.viewportSize() ?? { width: 0, height: 0 };\n    const title = await page.title().catch(() => \"\");\n    const lines = [\n      `Snapshot of ${page.url()}${title ? ` — \"${title}\"` : \"\"} — ${describeScale(viewport).replace(/, images.*$/, \"\")} — ${describeCounts(snapshot)}${vue ? ` — ${describeVue(vue)}` : \"\"}`,\n      ...(input.include_screenshot ? [describeScale(viewport)] : []),\n      ...(input.selector ? [`Scope: ${input.selector}`] : []),\n      REF_HINT,\n      \"\",\n      snapshot.text,\n      ...(snapshot.cut_lines > 0\n        ? [`… ${snapshot.cut_lines} more lines cut — raise \\`max_chars\\`, pass \\`selector\\`, or use mode \"interactive\".`]\n        : []),\n    ];\n    if (input.include_components) {\n      lines.push(\"\", ...(await describeComponents(page, vue)));\n    }\n\n    const content: CallToolResult[\"content\"] = [{ type: \"text\", text: lines.join(\"\\n\") }];\n    if (input.include_screenshot) {\n      const png = await page.screenshot({ type: \"png\" });\n      content.unshift({ type: \"image\", data: toBase64(await resizeForOutput(png)), mimeType: \"image/png\" });\n    }\n    hmrFor(page).markSeen();\n    return withAuthNote({ content }, auth, login_visible);\n  } catch (error) {\n    return errorResult(describeSessionFailure(\"Snapshot\", input, error));\n  }\n}\n\nconst REF_HINT =\n  \"Refs: pass one as `ref` to framewatch_interact (to act on it) or framewatch_inspect (to measure it). \" +\n  \"They stay valid until the page changes — snapshot again after an action that re-rendered. \" +\n  'In a framewatch_capture script, target the same element with a selector such as role=button[name=\"Sign in\"].';\n\nexport function describeCounts(snapshot: Pick<PageSnapshot, \"elements\" | \"interactive\">): string {\n  return `${snapshot.elements} elements, ${snapshot.interactive} interactive`;\n}\n\n/** The component tree, or why there is none. */\nasync function describeComponents(page: Awaited<ReturnType<typeof getSessionPage>>[\"page\"], vue: VueInfo | null): Promise<string[]> {\n  if (!vue) return [\"Components: no Vue app on this page\"];\n  if (vue.major < 3) return [\"Components: Vue 2 — component details need Vue 3\"];\n  if (vue.production) return [\"Components: production build — no component data on elements\"];\n  const tree = await componentTree(page);\n  if (!tree) return [\"Components: could not be read\"];\n  return formatComponentTree(tree.root, tree.total);\n}\n\n/** Input the session-page tools share: where to open, how long to wait, what size. */\nexport interface SessionPageInput {\n  url?: string;\n  wait_ms?: number;\n  wait_for?: string;\n  wait_for_timeout_ms?: number;\n  viewport?: Viewport;\n  storage_state?: string;\n}\n\n/**\n * The session page, opened at `url` when one is given. Shared by snapshot and\n * inspect, which both read the page interact drives; `toolName` is only for\n * the error wording.\n */\nexport interface OpenedSessionPage {\n  page: Awaited<ReturnType<typeof getSessionPage>>[\"page\"];\n  vue: VueInfo | null;\n  /** The saved auth in force for this call, if any. */\n  auth: ResolvedAuth | null;\n  /** Whether the page showed a login form after opening — only checked when `url` was given. */\n  login_visible: boolean;\n}\n\nexport async function openSessionPage(input: SessionPageInput, toolName: string): Promise<OpenedSessionPage | { error: string }> {\n  const options: SessionOptions = {};\n  if (input.viewport) options.viewport = input.viewport;\n  const auth = await resolveStorageState(input.storage_state);\n  if (auth) options.storageState = { path: auth.path, state: auth.state };\n\n  const { page, previousUrl } = await getSessionPage(options);\n  const target = input.url ?? previousUrl;\n  if (target !== undefined) {\n    await page.goto(target, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n    if (input.wait_for) {\n      await page.waitForSelector(input.wait_for, { state: \"visible\", timeout: input.wait_for_timeout_ms ?? SELECTOR_TIMEOUT_MS });\n    }\n    // `wait_ms` is a ceiling, not a sleep: a Vue app is read the moment it is\n    // mounted and its router has resolved; a page without one gets the full wait.\n    const { vue } = await waitForVueReady(page, { detect_ms: input.wait_ms ?? 0, ready_ms: VUE_READY_TIMEOUT_MS });\n    if (page.url() === \"about:blank\") return { error: noPage(toolName) };\n    return { page, vue, auth, login_visible: auth && input.url !== undefined ? await loginFormVisible(page) : false };\n  }\n  if (page.url() === \"about:blank\") return { error: noPage(toolName) };\n  return { page, vue: await detectVue(page), auth, login_visible: false };\n}\n\nfunction noPage(toolName: string): string {\n  return `${toolName} failed: no page is open yet — pass \\`url\\` to open one (e.g. http://localhost:3000).`;\n}\n\nexport function describeSessionFailure(toolName: string, input: { url?: string; wait_for?: string; wait_for_timeout_ms?: number }, error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n  if (/Executable doesn't exist|browserType\\.launch/i.test(message)) {\n    return `${toolName} failed: Playwright's Chromium browser is not installed. Run \\`npx playwright install chromium\\` and try again. (${firstLine})`;\n  }\n  if (/^page\\.goto:/.test(message)) {\n    return `${toolName} failed: could not open ${input.url ?? \"the page\"} — ${firstLine}`;\n  }\n  if (input.wait_for && /^page\\.waitForSelector:/.test(message)) {\n    return `${toolName} failed: selector \"${input.wait_for}\" did not become visible within ${input.wait_for_timeout_ms ?? SELECTOR_TIMEOUT_MS}ms.`;\n  }\n  return `${toolName} failed: ${firstLine}`;\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\nexport function registerSnapshotTool(server: McpServer): void {\n  server.registerTool(\n    SNAPSHOT_TOOL_NAME,\n    {\n      title: \"Snapshot\",\n      description:\n        \"Read the page as a tree of named elements — every heading, field, button and link with its accessible name \" +\n        \"and a short ref like `e8` — so you know what is on the page and what to call it instead of guessing selectors \" +\n        \"from a screenshot. Pass a ref as `ref` to framewatch_interact to act on that element, or to framewatch_inspect \" +\n        \"to measure it. Works on the page framewatch_interact keeps open; pass `url` to open one. \" +\n        \"Use mode `interactive` for a short list of only what can be acted on.\",\n      inputSchema: snapshotInputShape,\n      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => snapshotPage(args),\n  );\n}\n"]}

package/dist/tools/wait-for.d.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare const WAIT_FOR_TOOL_NAME = "framewatch_wait_for";
+export declare const waitForInputShape: {
+    url: z.ZodOptional<z.ZodString>;
+    until: z.ZodDefault<z.ZodEnum<["hot_update", "vue_ready", "selector", "network_idle"]>>;
+    selector: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    include_screenshot: z.ZodDefault<z.ZodBoolean>;
+    include_snapshot: z.ZodDefault<z.ZodBoolean>;
+    wait_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 waitForInputSchema: z.ZodEffects<z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    until: z.ZodDefault<z.ZodEnum<["hot_update", "vue_ready", "selector", "network_idle"]>>;
+    selector: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    include_screenshot: z.ZodDefault<z.ZodBoolean>;
+    include_snapshot: z.ZodDefault<z.ZodBoolean>;
+    wait_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;
+    timeout_ms: number;
+    include_screenshot: boolean;
+    include_snapshot: boolean;
+    until: "selector" | "hot_update" | "vue_ready" | "network_idle";
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+}, {
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_ms?: number | undefined;
+    storage_state?: string | undefined;
+    timeout_ms?: number | undefined;
+    selector?: string | undefined;
+    include_screenshot?: boolean | undefined;
+    include_snapshot?: boolean | undefined;
+    until?: "selector" | "hot_update" | "vue_ready" | "network_idle" | undefined;
+}>, {
+    wait_ms: number;
+    timeout_ms: number;
+    include_screenshot: boolean;
+    include_snapshot: boolean;
+    until: "selector" | "hot_update" | "vue_ready" | "network_idle";
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+}, {
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_ms?: number | undefined;
+    storage_state?: string | undefined;
+    timeout_ms?: number | undefined;
+    selector?: string | undefined;
+    include_screenshot?: boolean | undefined;
+    include_snapshot?: boolean | undefined;
+    until?: "selector" | "hot_update" | "vue_ready" | "network_idle" | undefined;
+}>;
+export type WaitForInput = z.input<typeof waitForInputSchema>;
+/**
+ * Wait for the session page to reach a state worth looking at, then look.
+ *
+ * The one that earns the tool its place is `hot_update`: after the agent
+ * saves a file, Vite patches the open page in place, and this returns the
+ * moment that patch has landed — no reload, no replayed flow, no guessed
+ * sleep. The other conditions replace the guessed sleeps elsewhere.
+ */
+export declare function waitFor(rawInput: WaitForInput): Promise<CallToolResult>;
+export declare function registerWaitForTool(server: McpServer): void;

package/dist/tools/wait-for.js

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import { DEFAULT_SNAPSHOT_MAX_CHARS, DEFAULT_SNAPSHOT_WAIT_MS, DEFAULT_WAIT_FOR_TIMEOUT_MS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, MAX_WAIT_FOR_TIMEOUT_MS, VUE_DETECT_MS, VUE_READY_TIMEOUT_MS, } from "../constants.js";
+import { withSessionLock } from "../engine/browser.js";
+import { hasViteClient, hmrFor } from "../engine/hmr.js";
+import { takeSnapshot } from "../engine/snapshot.js";
+import { detectVue, waitForVueReady } from "../engine/vue.js";
+import { describeScale } from "../utils/format.js";
+import { resizeForOutput, toBase64 } from "../utils/image.js";
+import { storageStateField, withAuthNote } from "../utils/storage-state.js";
+import { describeVue } from "../utils/vue-rules.js";
+import { describeCounts, describeSessionFailure, openSessionPage } from "./snapshot.js";
+export const WAIT_FOR_TOOL_NAME = "framewatch_wait_for";
+export const waitForInputShape = {
+    url: z
+        .string()
+        .url()
+        .optional()
+        .describe("Open this URL first. Omit to wait on the page left open by framewatch_interact / framewatch_snapshot."),
+    until: z
+        .enum(["hot_update", "vue_ready", "selector", "network_idle"])
+        .default("hot_update")
+        .describe("`hot_update`: Vite applied a hot update (or full reload) newer than the last tool call on this page — " +
+        "use it right after saving a file. `vue_ready`: a Vue app is mounted and its router has resolved. " +
+        "`selector`: `selector` is visible. `network_idle`: no requests for 500ms."),
+    selector: z.string().optional().describe("For `until: selector` — the element to wait for"),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_WAIT_FOR_TIMEOUT_MS)
+        .default(DEFAULT_WAIT_FOR_TIMEOUT_MS)
+        .describe("Give up after this long"),
+    include_screenshot: z.boolean().default(true).describe("Return a screenshot once the condition holds"),
+    include_snapshot: z.boolean().default(false).describe("Also return a framewatch_snapshot with fresh refs"),
+    wait_ms: z.number().int().min(0).default(DEFAULT_SNAPSHOT_WAIT_MS).describe("Settle time (ms) after opening `url`"),
+    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 waitForInputSchema = z.object(waitForInputShape).superRefine((value, ctx) => {
+    if (value.until === "selector" && !value.selector) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "`until: selector` needs a `selector`", path: ["selector"] });
+    }
+});
+/**
+ * Wait for the session page to reach a state worth looking at, then look.
+ *
+ * The one that earns the tool its place is `hot_update`: after the agent
+ * saves a file, Vite patches the open page in place, and this returns the
+ * moment that patch has landed — no reload, no replayed flow, no guessed
+ * sleep. The other conditions replace the guessed sleeps elsewhere.
+ */
+export function waitFor(rawInput) {
+    return withSessionLock(() => runWaitFor(rawInput));
+}
+async function runWaitFor(rawInput) {
+    const parsed = waitForInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Wait failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    try {
+        const opened = await openSessionPage(input, "Wait");
+        if ("error" in opened)
+            return errorResult(opened.error);
+        const { page, auth, login_visible } = opened;
+        const watcher = hmrFor(page);
+        const since = watcher.lastSeen;
+        const started = Date.now();
+        const elapsed = () => Date.now() - started;
+        let headline;
+        let vue = null;
+        switch (input.until) {
+            case "hot_update": {
+                const event = await watcher.waitForEvent(since, input.timeout_ms);
+                if (!event) {
+                    if (!watcher.connected && !(await hasViteClient(page))) {
+                        return errorResult(`Wait failed: ${page.url()} has no Vite dev-server connection (no \`[vite] connected.\` in the console and no /@vite/client script), so there will never be a hot update to wait for. Is this the dev server, or a built page?`);
+                    }
+                    const latest = watcher.latest;
+                    const last = latest ? ` — last one landed ${started - latest.t}ms before this call (${latest.path})` : "";
+                    return errorResult(`Wait failed: No hot update within ${input.timeout_ms}ms${last}. Save the file, then call again.`);
+                }
+                const landed = event.t - started;
+                if (event.kind === "reload") {
+                    await page.waitForLoadState("load", { timeout: input.timeout_ms }).catch(() => undefined);
+                }
+                vue = (await waitForVueReady(page, { detect_ms: VUE_DETECT_MS, ready_ms: VUE_READY_TIMEOUT_MS })).vue;
+                const what = event.kind === "reload" ? "Full reload" : "Hot update";
+                const kind = event.kind === "css" ? " (css)" : "";
+                headline = `${what} landed after ${Math.max(0, landed)}ms${kind}${event.path ? `: ${event.path}` : ""}`;
+                break;
+            }
+            case "vue_ready": {
+                const result = await waitForVueReady(page, { detect_ms: input.timeout_ms, ready_ms: input.timeout_ms });
+                if (!result.vue)
+                    return errorResult(`Wait failed: No Vue app mounted on ${page.url()} within ${input.timeout_ms}ms.`);
+                vue = result.vue;
+                headline = `Vue ready after ${result.waited_ms}ms`;
+                break;
+            }
+            case "selector": {
+                try {
+                    await page.waitForSelector(input.selector, { state: "visible", timeout: input.timeout_ms });
+                }
+                catch {
+                    return errorResult(`Wait failed: "${input.selector}" did not appear within ${input.timeout_ms}ms on ${page.url()}.`);
+                }
+                headline = `"${input.selector}" appeared after ${elapsed()}ms`;
+                vue = await detectVue(page);
+                break;
+            }
+            case "network_idle": {
+                try {
+                    await page.waitForLoadState("networkidle", { timeout: input.timeout_ms });
+                }
+                catch {
+                    return errorResult(`Wait failed: the network did not go idle within ${input.timeout_ms}ms on ${page.url()}.`);
+                }
+                headline = `Network idle after ${elapsed()}ms`;
+                vue = await detectVue(page);
+                break;
+            }
+        }
+        const viewport = page.viewportSize() ?? { width: 0, height: 0 };
+        const lines = [`${headline}${vue ? ` — ${describeVue(vue)}` : ""} — ${page.url()} — ${describeScale(viewport)}`];
+        const content = [{ type: "text", text: lines.join("\n") }];
+        if (input.include_screenshot) {
+            const png = await page.screenshot({ type: "png" });
+            content.push({ type: "image", data: toBase64(await resizeForOutput(png)), mimeType: "image/png" });
+        }
+        if (input.include_snapshot) {
+            const snapshot = await takeSnapshot(page, { mode: "full", max_chars: DEFAULT_SNAPSHOT_MAX_CHARS });
+            const text = [`Snapshot — ${describeCounts(snapshot)} (refs valid until the page changes)`, "", snapshot.text];
+            if (snapshot.cut_lines > 0)
+                text.push(`… ${snapshot.cut_lines} more lines cut — use framewatch_snapshot with \`selector\` or mode "interactive".`);
+            content.push({ type: "text", text: text.join("\n") });
+        }
+        watcher.markSeen();
+        return withAuthNote({ content }, auth, login_visible);
+    }
+    catch (error) {
+        return errorResult(describeSessionFailure("Wait", input, error));
+    }
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+export function registerWaitForTool(server) {
+    server.registerTool(WAIT_FOR_TOOL_NAME, {
+        title: "Wait for",
+        description: "Wait for the open page to reach a state worth looking at, then screenshot it. After you save a file, " +
+            "`until: hot_update` returns the moment Vite has patched the page in place (or reloaded it) — no reload, " +
+            "no replayed flow, no guessed sleep — and names the file that changed. `vue_ready` waits for a Vue app to " +
+            "mount and its router to resolve; `selector` for an element; `network_idle` for requests to stop. " +
+            "Works on the page framewatch_interact / framewatch_snapshot keep open; `include_snapshot` returns fresh refs.",
+        inputSchema: waitForInputShape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => waitFor(args));
+}
+//# sourceMappingURL=wait-for.js.map

package/dist/tools/wait-for.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for.js","sourceRoot":"","sources":["../../src/tools/wait-for.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_MAX_CHARS,\n  DEFAULT_SNAPSHOT_WAIT_MS,\n  DEFAULT_WAIT_FOR_TIMEOUT_MS,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  MAX_WAIT_FOR_TIMEOUT_MS,\n  VUE_DETECT_MS,\n  VUE_READY_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { withSessionLock } from \"../engine/browser.js\";\nimport { hasViteClient, hmrFor } from \"../engine/hmr.js\";\nimport { takeSnapshot } from \"../engine/snapshot.js\";\nimport { detectVue, waitForVueReady } from \"../engine/vue.js\";\nimport { describeScale } from \"../utils/format.js\";\nimport { resizeForOutput, toBase64 } from \"../utils/image.js\";\nimport { storageStateField, withAuthNote } from \"../utils/storage-state.js\";\nimport { describeVue, type VueInfo } from \"../utils/vue-rules.js\";\nimport { describeCounts, describeSessionFailure, openSessionPage } from \"./snapshot.js\";\n\nexport const WAIT_FOR_TOOL_NAME = \"framewatch_wait_for\";\n\nexport const waitForInputShape = {\n  url: z\n    .string()\n    .url()\n    .optional()\n    .describe(\"Open this URL first. Omit to wait on the page left open by framewatch_interact / framewatch_snapshot.\"),\n  until: z\n    .enum([\"hot_update\", \"vue_ready\", \"selector\", \"network_idle\"])\n    .default(\"hot_update\")\n    .describe(\n      \"`hot_update`: Vite applied a hot update (or full reload) newer than the last tool call on this page — \" +\n        \"use it right after saving a file. `vue_ready`: a Vue app is mounted and its router has resolved. \" +\n        \"`selector`: `selector` is visible. `network_idle`: no requests for 500ms.\",\n    ),\n  selector: z.string().optional().describe(\"For `until: selector` — the element to wait for\"),\n  timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .max(MAX_WAIT_FOR_TIMEOUT_MS)\n    .default(DEFAULT_WAIT_FOR_TIMEOUT_MS)\n    .describe(\"Give up after this long\"),\n  include_screenshot: z.boolean().default(true).describe(\"Return a screenshot once the condition holds\"),\n  include_snapshot: z.boolean().default(false).describe(\"Also return a framewatch_snapshot with fresh refs\"),\n  wait_ms: z.number().int().min(0).default(DEFAULT_SNAPSHOT_WAIT_MS).describe(\"Settle time (ms) after opening `url`\"),\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 waitForInputSchema = z.object(waitForInputShape).superRefine((value, ctx) => {\n  if (value.until === \"selector\" && !value.selector) {\n    ctx.addIssue({ code: z.ZodIssueCode.custom, message: \"`until: selector` needs a `selector`\", path: [\"selector\"] });\n  }\n});\nexport type WaitForInput = z.input<typeof waitForInputSchema>;\n\n/**\n * Wait for the session page to reach a state worth looking at, then look.\n *\n * The one that earns the tool its place is `hot_update`: after the agent\n * saves a file, Vite patches the open page in place, and this returns the\n * moment that patch has landed — no reload, no replayed flow, no guessed\n * sleep. The other conditions replace the guessed sleeps elsewhere.\n */\nexport function waitFor(rawInput: WaitForInput): Promise<CallToolResult> {\n  return withSessionLock(() => runWaitFor(rawInput));\n}\n\nasync function runWaitFor(rawInput: WaitForInput): Promise<CallToolResult> {\n  const parsed = waitForInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Wait failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n\n  try {\n    const opened = await openSessionPage(input, \"Wait\");\n    if (\"error\" in opened) return errorResult(opened.error);\n    const { page, auth, login_visible } = opened;\n    const watcher = hmrFor(page);\n    const since = watcher.lastSeen;\n    const started = Date.now();\n    const elapsed = (): number => Date.now() - started;\n\n    let headline: string;\n    let vue: VueInfo | null = null;\n\n    switch (input.until) {\n      case \"hot_update\": {\n        const event = await watcher.waitForEvent(since, input.timeout_ms);\n        if (!event) {\n          if (!watcher.connected && !(await hasViteClient(page))) {\n            return errorResult(\n              `Wait failed: ${page.url()} has no Vite dev-server connection (no \\`[vite] connected.\\` in the console and no /@vite/client script), so there will never be a hot update to wait for. Is this the dev server, or a built page?`,\n            );\n          }\n          const latest = watcher.latest;\n          const last = latest ? ` — last one landed ${started - latest.t}ms before this call (${latest.path})` : \"\";\n          return errorResult(`Wait failed: No hot update within ${input.timeout_ms}ms${last}. Save the file, then call again.`);\n        }\n        const landed = event.t - started;\n        if (event.kind === \"reload\") {\n          await page.waitForLoadState(\"load\", { timeout: input.timeout_ms }).catch(() => undefined);\n        }\n        vue = (await waitForVueReady(page, { detect_ms: VUE_DETECT_MS, ready_ms: VUE_READY_TIMEOUT_MS })).vue;\n        const what = event.kind === \"reload\" ? \"Full reload\" : \"Hot update\";\n        const kind = event.kind === \"css\" ? \" (css)\" : \"\";\n        headline = `${what} landed after ${Math.max(0, landed)}ms${kind}${event.path ? `: ${event.path}` : \"\"}`;\n        break;\n      }\n      case \"vue_ready\": {\n        const result = await waitForVueReady(page, { detect_ms: input.timeout_ms, ready_ms: input.timeout_ms });\n        if (!result.vue) return errorResult(`Wait failed: No Vue app mounted on ${page.url()} within ${input.timeout_ms}ms.`);\n        vue = result.vue;\n        headline = `Vue ready after ${result.waited_ms}ms`;\n        break;\n      }\n      case \"selector\": {\n        try {\n          await page.waitForSelector(input.selector!, { state: \"visible\", timeout: input.timeout_ms });\n        } catch {\n          return errorResult(`Wait failed: \"${input.selector}\" did not appear within ${input.timeout_ms}ms on ${page.url()}.`);\n        }\n        headline = `\"${input.selector}\" appeared after ${elapsed()}ms`;\n        vue = await detectVue(page);\n        break;\n      }\n      case \"network_idle\": {\n        try {\n          await page.waitForLoadState(\"networkidle\", { timeout: input.timeout_ms });\n        } catch {\n          return errorResult(`Wait failed: the network did not go idle within ${input.timeout_ms}ms on ${page.url()}.`);\n        }\n        headline = `Network idle after ${elapsed()}ms`;\n        vue = await detectVue(page);\n        break;\n      }\n    }\n\n    const viewport = page.viewportSize() ?? { width: 0, height: 0 };\n    const lines = [`${headline}${vue ? ` — ${describeVue(vue)}` : \"\"} — ${page.url()} — ${describeScale(viewport)}`];\n    const content: CallToolResult[\"content\"] = [{ type: \"text\", text: lines.join(\"\\n\") }];\n    if (input.include_screenshot) {\n      const png = await page.screenshot({ type: \"png\" });\n      content.push({ type: \"image\", data: toBase64(await resizeForOutput(png)), mimeType: \"image/png\" });\n    }\n    if (input.include_snapshot) {\n      const snapshot = await takeSnapshot(page, { mode: \"full\", max_chars: DEFAULT_SNAPSHOT_MAX_CHARS });\n      const text = [`Snapshot — ${describeCounts(snapshot)} (refs valid until the page changes)`, \"\", snapshot.text];\n      if (snapshot.cut_lines > 0) text.push(`… ${snapshot.cut_lines} more lines cut — use framewatch_snapshot with \\`selector\\` or mode \"interactive\".`);\n      content.push({ type: \"text\", text: text.join(\"\\n\") });\n    }\n    watcher.markSeen();\n    return withAuthNote({ content }, auth, login_visible);\n  } catch (error) {\n    return errorResult(describeSessionFailure(\"Wait\", input, error));\n  }\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\nexport function registerWaitForTool(server: McpServer): void {\n  server.registerTool(\n    WAIT_FOR_TOOL_NAME,\n    {\n      title: \"Wait for\",\n      description:\n        \"Wait for the open page to reach a state worth looking at, then screenshot it. After you save a file, \" +\n        \"`until: hot_update` returns the moment Vite has patched the page in place (or reloaded it) — no reload, \" +\n        \"no replayed flow, no guessed sleep — and names the file that changed. `vue_ready` waits for a Vue app to \" +\n        \"mount and its router to resolve; `selector` for an element; `network_idle` for requests to stop. \" +\n        \"Works on the page framewatch_interact / framewatch_snapshot keep open; `include_snapshot` returns fresh refs.\",\n      inputSchema: waitForInputShape,\n      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },\n    },\n    async (args) => waitFor(args),\n  );\n}\n"]}

package/dist/utils/arabic-text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build Arabic text about as long as `original`.
+ *
+ * `seed` makes the choice deterministic and varied: the same string in the
+ * same place gets the same replacement on every run (so two runs of the tool
+ * are comparable, and the LTR and RTL passes agree), while two different
+ * elements of the same length do not all get the same word.
+ *
+ * A string that is only digits and punctuation keeps its shape and is merely
+ * transliterated — see `ARABIC_DIGITS`.
+ */
+export declare function arabicFor(original: string, seed?: number): string;
+/** Latin digits to Arabic-Indic, leaving everything else alone. */
+export declare function toArabicDigits(value: string): string;