framewatch-mcp-server 0.1.1 → 0.2.0

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;

package/dist/utils/arabic-text.js

@@ -0,0 +1,193 @@
+import { MAX_ARABIC_INJECTION_LENGTH } from "../constants.js";
+/**
+ * Arabic stand-in text, matched to the length of what it replaces.
+ *
+ * `framewatch_rtl` can replace every visible string on a page with Arabic, so
+ * that the layout is tested against text that actually renders right-to-left
+ * rather than against English sitting inside an RTL container. English in an
+ * RTL page is a bidirectional edge case of its own and hides the ordinary
+ * bugs: the Latin run keeps its own direction, so a container that never
+ * mirrored still *looks* plausible.
+ *
+ * The length matching is the part that matters. If "Add to cart" became a
+ * three-character word, the button would shrink and any overflow the tool
+ * reported afterwards would be an artifact of the substitution rather than a
+ * property of the page — and if it became a paragraph, every page would
+ * overflow. So each replacement is built to within a few characters of the
+ * string it replaces, and the report's overflow findings mean what they say.
+ *
+ * Nothing here touches a browser: it is a string in, a string out, so every
+ * case is unit-testable without launching Chromium.
+ */
+/**
+ * The vocabulary, grouped by length so a replacement can be assembled to fit.
+ *
+ * Real words, not lorem ipsum: an Arabic reader glancing at a screenshot
+ * should see a plausible interface, and the shaping/ligature behaviour of real
+ * words is what stresses the text rendering. These are the words a UI is
+ * actually made of — actions, labels, navigation.
+ */
+const WORDS = [
+    // 2–4 characters
+    "نعم",
+    "لا",
+    "حسنا",
+    "بحث",
+    "إغلاق",
+    "حفظ",
+    "فتح",
+    "التالي",
+    "السابق",
+    "رجوع",
+    // 5–8
+    "تسجيل",
+    "الدخول",
+    "الخروج",
+    "الرئيسية",
+    "المنتجات",
+    "الخدمات",
+    "الطلبات",
+    "الحساب",
+    "الإعدادات",
+    "المفضلة",
+    // 9+
+    "أضف إلى السلة",
+    "إتمام الشراء",
+    "تواصل معنا",
+    "من نحن",
+    "الشروط والأحكام",
+    "سياسة الخصوصية",
+    "اشترك في النشرة",
+    "عرض جميع النتائج",
+];
+/** A sentence's worth, for replacing paragraphs rather than labels. */
+const SENTENCES = [
+    "مرحبا بك في متجرنا الإلكتروني",
+    "نقدم لك أفضل المنتجات بأسعار تنافسية",
+    "يمكنك تصفح الأقسام والاطلاع على العروض",
+    "خدمة التوصيل متاحة إلى جميع المناطق",
+    "فريق الدعم جاهز للإجابة عن أسئلتك",
+];
+/**
+ * Arabic-Indic digits, so a number reads as Arabic too.
+ *
+ * Kept as a separate mapping rather than being replaced by words: a price, a
+ * quantity or a date is still a number in an Arabic interface, and turning
+ * "24" into a word would change what the element is rather than what language
+ * it is in — which is the opposite of what this substitution is for.
+ */
+const ARABIC_DIGITS = ["٠", "١", "٢", "٣", "٤", "٥", "٦", "٧", "٨", "٩"];
+/**
+ * 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 function arabicFor(original, seed = 0) {
+    const source = String(original ?? "");
+    const trimmed = source.trim();
+    if (trimmed === "")
+        return source;
+    // Numbers, prices, times: keep the shape, change the digits. Replacing
+    // "١٢:٣٠" with a word would be a different element, not a translated one.
+    if (!/\p{L}/u.test(trimmed))
+        return toArabicDigits(source);
+    const target = Math.min(trimmed.length, MAX_ARABIC_INJECTION_LENGTH);
+    const built = target > 24 ? buildSentence(target, seed) : buildPhrase(target, seed);
+    // Leading/trailing whitespace is layout — a label may rely on it — so the
+    // original's edges are preserved and only the text between them replaced.
+    const leading = source.slice(0, source.length - source.trimStart().length);
+    const trailing = source.slice(source.trimEnd().length);
+    return `${leading}${built}${trailing}`;
+}
+/**
+ * Words joined until they are about `target` characters long.
+ *
+ * Each step picks the word that gets closest to the remaining space rather
+ * than taking the first candidate and giving up when it does not fit. Giving
+ * up is the trap: a 19-character string whose first word happens to be 10
+ * characters would stop there, nine short, and every button on the page would
+ * come back narrower than it really is — which is exactly the measurement
+ * error this whole module exists to avoid.
+ */
+function buildPhrase(target, seed) {
+    // A starting word no longer than the target, so a 3-character label does
+    // not become a 13-character phrase.
+    const candidates = WORDS.filter((word) => word.length <= Math.max(3, target));
+    const pool = candidates.length > 0 ? candidates : WORDS;
+    let out = pool[hash(seed) % pool.length];
+    let step = 1;
+    while (out.length < target - 1 && step <= 40) {
+        const remaining = target - out.length - 1;
+        const next = bestFit(pool, remaining, seed + step);
+        // Nothing left in the vocabulary fits the gap: stop rather than overshoot.
+        if (next === null)
+            break;
+        out = `${out} ${next}`;
+        step += 1;
+    }
+    return out;
+}
+/**
+ * The word closest to `remaining` characters without overshooting by more
+ * than a hair, chosen deterministically among equally good candidates.
+ */
+function bestFit(pool, remaining, seed) {
+    if (remaining <= 0)
+        return null;
+    // A slight overshoot is better than a large undershoot: landing two
+    // characters long is invisible, landing nine short is a different layout.
+    const fitting = pool.filter((word) => word.length <= remaining + 2);
+    if (fitting.length === 0)
+        return null;
+    let best = fitting[0].length;
+    for (const word of fitting) {
+        if (Math.abs(word.length - remaining) < Math.abs(best - remaining))
+            best = word.length;
+    }
+    const closest = fitting.filter((word) => word.length === best);
+    return closest[hash(seed) % closest.length];
+}
+/** Sentences joined until they are about `target` characters long. */
+function buildSentence(target, seed) {
+    let out = SENTENCES[hash(seed) % SENTENCES.length];
+    let step = 1;
+    while (out.length < target - 4) {
+        const next = SENTENCES[hash(seed + step) % SENTENCES.length];
+        if (out.length + 2 + next.length > target + 8) {
+            // No whole sentence fits the remainder; pad with words instead of
+            // overshooting, so a long paragraph still lands near its original length.
+            const filler = buildPhrase(target - out.length - 1, seed + step);
+            out = `${out}، ${filler}`;
+            break;
+        }
+        out = `${out}، ${next}`;
+        step += 1;
+        if (step > 40)
+            break;
+    }
+    return out;
+}
+/** Latin digits to Arabic-Indic, leaving everything else alone. */
+export function toArabicDigits(value) {
+    return String(value ?? "").replace(/[0-9]/g, (digit) => ARABIC_DIGITS[Number(digit)]);
+}
+/**
+ * A small deterministic hash.
+ *
+ * Not for security — for repeatability. `Math.random()` would make two runs of
+ * the same audit disagree about which element overflowed, which is exactly the
+ * kind of flakiness that makes a testing tool untrusted.
+ */
+function hash(seed) {
+    let value = (seed | 0) + 0x9e3779b9;
+    value = Math.imul(value ^ (value >>> 16), 0x21f0aaad);
+    value = Math.imul(value ^ (value >>> 15), 0x735a2d97);
+    return Math.abs(value ^ (value >>> 15));
+}
+//# sourceMappingURL=arabic-text.js.map

package/dist/utils/arabic-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arabic-text.js","sourceRoot":"","sources":["../../src/utils/arabic-text.ts"],"names":[],"mappings":"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","sourcesContent":["import { MAX_ARABIC_INJECTION_LENGTH } from \"../constants.js\";\n\n/**\n * Arabic stand-in text, matched to the length of what it replaces.\n *\n * `framewatch_rtl` can replace every visible string on a page with Arabic, so\n * that the layout is tested against text that actually renders right-to-left\n * rather than against English sitting inside an RTL container. English in an\n * RTL page is a bidirectional edge case of its own and hides the ordinary\n * bugs: the Latin run keeps its own direction, so a container that never\n * mirrored still *looks* plausible.\n *\n * The length matching is the part that matters. If \"Add to cart\" became a\n * three-character word, the button would shrink and any overflow the tool\n * reported afterwards would be an artifact of the substitution rather than a\n * property of the page — and if it became a paragraph, every page would\n * overflow. So each replacement is built to within a few characters of the\n * string it replaces, and the report's overflow findings mean what they say.\n *\n * Nothing here touches a browser: it is a string in, a string out, so every\n * case is unit-testable without launching Chromium.\n */\n\n/**\n * The vocabulary, grouped by length so a replacement can be assembled to fit.\n *\n * Real words, not lorem ipsum: an Arabic reader glancing at a screenshot\n * should see a plausible interface, and the shaping/ligature behaviour of real\n * words is what stresses the text rendering. These are the words a UI is\n * actually made of — actions, labels, navigation.\n */\nconst WORDS: readonly string[] = [\n  // 2–4 characters\n  \"نعم\",\n  \"لا\",\n  \"حسنا\",\n  \"بحث\",\n  \"إغلاق\",\n  \"حفظ\",\n  \"فتح\",\n  \"التالي\",\n  \"السابق\",\n  \"رجوع\",\n  // 5–8\n  \"تسجيل\",\n  \"الدخول\",\n  \"الخروج\",\n  \"الرئيسية\",\n  \"المنتجات\",\n  \"الخدمات\",\n  \"الطلبات\",\n  \"الحساب\",\n  \"الإعدادات\",\n  \"المفضلة\",\n  // 9+\n  \"أضف إلى السلة\",\n  \"إتمام الشراء\",\n  \"تواصل معنا\",\n  \"من نحن\",\n  \"الشروط والأحكام\",\n  \"سياسة الخصوصية\",\n  \"اشترك في النشرة\",\n  \"عرض جميع النتائج\",\n];\n\n/** A sentence's worth, for replacing paragraphs rather than labels. */\nconst SENTENCES: readonly string[] = [\n  \"مرحبا بك في متجرنا الإلكتروني\",\n  \"نقدم لك أفضل المنتجات بأسعار تنافسية\",\n  \"يمكنك تصفح الأقسام والاطلاع على العروض\",\n  \"خدمة التوصيل متاحة إلى جميع المناطق\",\n  \"فريق الدعم جاهز للإجابة عن أسئلتك\",\n];\n\n/**\n * Arabic-Indic digits, so a number reads as Arabic too.\n *\n * Kept as a separate mapping rather than being replaced by words: a price, a\n * quantity or a date is still a number in an Arabic interface, and turning\n * \"24\" into a word would change what the element is rather than what language\n * it is in — which is the opposite of what this substitution is for.\n */\nconst ARABIC_DIGITS = [\"٠\", \"١\", \"٢\", \"٣\", \"٤\", \"٥\", \"٦\", \"٧\", \"٨\", \"٩\"] as const;\n\n/**\n * Build Arabic text about as long as `original`.\n *\n * `seed` makes the choice deterministic and varied: the same string in the\n * same place gets the same replacement on every run (so two runs of the tool\n * are comparable, and the LTR and RTL passes agree), while two different\n * elements of the same length do not all get the same word.\n *\n * A string that is only digits and punctuation keeps its shape and is merely\n * transliterated — see `ARABIC_DIGITS`.\n */\nexport function arabicFor(original: string, seed = 0): string {\n  const source = String(original ?? \"\");\n  const trimmed = source.trim();\n  if (trimmed === \"\") return source;\n\n  // Numbers, prices, times: keep the shape, change the digits. Replacing\n  // \"١٢:٣٠\" with a word would be a different element, not a translated one.\n  if (!/\\p{L}/u.test(trimmed)) return toArabicDigits(source);\n\n  const target = Math.min(trimmed.length, MAX_ARABIC_INJECTION_LENGTH);\n  const built = target > 24 ? buildSentence(target, seed) : buildPhrase(target, seed);\n\n  // Leading/trailing whitespace is layout — a label may rely on it — so the\n  // original's edges are preserved and only the text between them replaced.\n  const leading = source.slice(0, source.length - source.trimStart().length);\n  const trailing = source.slice(source.trimEnd().length);\n  return `${leading}${built}${trailing}`;\n}\n\n/**\n * Words joined until they are about `target` characters long.\n *\n * Each step picks the word that gets closest to the remaining space rather\n * than taking the first candidate and giving up when it does not fit. Giving\n * up is the trap: a 19-character string whose first word happens to be 10\n * characters would stop there, nine short, and every button on the page would\n * come back narrower than it really is — which is exactly the measurement\n * error this whole module exists to avoid.\n */\nfunction buildPhrase(target: number, seed: number): string {\n  // A starting word no longer than the target, so a 3-character label does\n  // not become a 13-character phrase.\n  const candidates = WORDS.filter((word) => word.length <= Math.max(3, target));\n  const pool = candidates.length > 0 ? candidates : WORDS;\n\n  let out = pool[hash(seed) % pool.length];\n  let step = 1;\n  while (out.length < target - 1 && step <= 40) {\n    const remaining = target - out.length - 1;\n    const next = bestFit(pool, remaining, seed + step);\n    // Nothing left in the vocabulary fits the gap: stop rather than overshoot.\n    if (next === null) break;\n    out = `${out} ${next}`;\n    step += 1;\n  }\n  return out;\n}\n\n/**\n * The word closest to `remaining` characters without overshooting by more\n * than a hair, chosen deterministically among equally good candidates.\n */\nfunction bestFit(pool: readonly string[], remaining: number, seed: number): string | null {\n  if (remaining <= 0) return null;\n  // A slight overshoot is better than a large undershoot: landing two\n  // characters long is invisible, landing nine short is a different layout.\n  const fitting = pool.filter((word) => word.length <= remaining + 2);\n  if (fitting.length === 0) return null;\n\n  let best = fitting[0].length;\n  for (const word of fitting) {\n    if (Math.abs(word.length - remaining) < Math.abs(best - remaining)) best = word.length;\n  }\n  const closest = fitting.filter((word) => word.length === best);\n  return closest[hash(seed) % closest.length];\n}\n\n/** Sentences joined until they are about `target` characters long. */\nfunction buildSentence(target: number, seed: number): string {\n  let out = SENTENCES[hash(seed) % SENTENCES.length];\n  let step = 1;\n  while (out.length < target - 4) {\n    const next = SENTENCES[hash(seed + step) % SENTENCES.length];\n    if (out.length + 2 + next.length > target + 8) {\n      // No whole sentence fits the remainder; pad with words instead of\n      // overshooting, so a long paragraph still lands near its original length.\n      const filler = buildPhrase(target - out.length - 1, seed + step);\n      out = `${out}، ${filler}`;\n      break;\n    }\n    out = `${out}، ${next}`;\n    step += 1;\n    if (step > 40) break;\n  }\n  return out;\n}\n\n/** Latin digits to Arabic-Indic, leaving everything else alone. */\nexport function toArabicDigits(value: string): string {\n  return String(value ?? \"\").replace(/[0-9]/g, (digit) => ARABIC_DIGITS[Number(digit)]);\n}\n\n/**\n * A small deterministic hash.\n *\n * Not for security — for repeatability. `Math.random()` would make two runs of\n * the same audit disagree about which element overflowed, which is exactly the\n * kind of flakiness that makes a testing tool untrusted.\n */\nfunction hash(seed: number): number {\n  let value = (seed | 0) + 0x9e3779b9;\n  value = Math.imul(value ^ (value >>> 16), 0x21f0aaad);\n  value = Math.imul(value ^ (value >>> 15), 0x735a2d97);\n  return Math.abs(value ^ (value >>> 15));\n}\n"]}

package/dist/utils/budget.d.ts

@@ -0,0 +1,41 @@
+import type { CallToolResult, ImageContent } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * The image budget.
+ *
+ * Claude Code caps one MCP tool result at `MAX_MCP_OUTPUT_TOKENS` (25,000 by
+ * default) and counts base64 image data toward it. A result over the cap is
+ * written to a file and replaced with a reference, so the model sees no
+ * images at all — and a single screenshot of a real page is 180 KB of PNG,
+ * which is over on its own. Every result therefore passes through here on
+ * its way out: each image is encoded the cheapest way that is still faithful,
+ * and if the result still does not fit it is degraded in a fixed order —
+ * crops first, then frame size, then frames from the middle — and says so.
+ * Fewer images that arrive beat all of them lost.
+ */
+export interface ImageMark {
+    /** A `crop` duplicates part of a frame and is the first thing to go. */
+    role?: "frame" | "crop";
+    /** Never dropped while any unmarked frame remains (first/last/interaction frames). */
+    keep?: boolean;
+}
+/** Stamp an image block with its role, for `fitToBudget` to read (and strip). */
+export declare function markImage(block: ImageContent, mark: ImageMark): ImageContent;
+/** The cap in force: what the shell that started Claude Code exported, or the default. */
+export declare function capFromEnv(env?: NodeJS.ProcessEnv): number;
+/** Base64 characters of image data a result may carry once its text is paid for. */
+export declare function imageBudgetChars(capTokens: number, textChars: number): number;
+export interface BudgetStats {
+    total: number;
+    kept: number;
+    crops_dropped: number;
+    frames_dropped: number;
+    /** Width the surviving frames were shrunk to, or undefined when untouched. */
+    width?: number;
+    cap_tokens: number;
+}
+export declare function describeBudget(stats: BudgetStats): string;
+export interface FitOptions {
+    /** Override the cap (tests); defaults to `capFromEnv()`. */
+    cap_tokens?: number;
+}
+export declare function fitToBudget(result: CallToolResult, options?: FitOptions): Promise<CallToolResult>;