@buoy-gg/mcp 4.0.1 → 5.0.0

package/dist/chunk-SQKZOREF.mjs

@@ -0,0 +1,2236 @@
+// src/config.ts
+import { DEFAULT_BROKER_PORT } from "@buoy-gg/sync-broker";
+var BROKER_PORT = DEFAULT_BROKER_PORT;
+var BROKER_URL = `http://localhost:${BROKER_PORT}`;
+var DEFAULT_ACTION_TIMEOUT_MS = 15e3;
+var DEFAULT_SNAPSHOT_TIMEOUT_MS = 5e3;
+var DASHBOARD_NAME = "Dashboard";
+var ALL_DEVICES = "All";
+
+// src/sync/SyncClient.ts
+import http from "http";
+import { randomUUID } from "crypto";
+import { io as ioClient } from "socket.io-client";
+import {
+  createBroker
+} from "@buoy-gg/sync-broker";
+var SyncClient = class {
+  constructor(opts = {}) {
+    this.socket = null;
+    this.broker = null;
+    /** Latest capabilities announce per deviceId. */
+    this.capabilities = /* @__PURE__ */ new Map();
+    /** Latest device list from the broker's `all-devices-update`. */
+    this.devices = [];
+    /** Latest snapshot payload per `${deviceId}::${toolId}`. */
+    this.snapshots = /* @__PURE__ */ new Map();
+    /** Tools we've asked the broker to keep streaming, as `${deviceId}::${toolId}`. */
+    this.watching = /* @__PURE__ */ new Set();
+    /** In-flight actions awaiting a result, keyed by requestId. */
+    this.pendingActions = /* @__PURE__ */ new Map();
+    /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
+    this.snapshotWaiters = /* @__PURE__ */ new Map();
+    this.port = opts.port ?? BROKER_PORT;
+    this.url = opts.url ?? (opts.port ? `http://localhost:${opts.port}` : BROKER_URL);
+    this.actionTimeoutMs = opts.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
+    this.log = opts.log ?? ((msg) => process.stderr.write(`[buoy-mcp] ${msg}
+`));
+    this.autoSpawn = opts.autoSpawnBroker ?? true;
+  }
+  // ----------------------------------------------------------------
+  // Lifecycle
+  // ----------------------------------------------------------------
+  /** Connect to a running broker, or spawn one in-process, then handshake. */
+  async start() {
+    const running = await probeBroker(this.url);
+    let mode = "connected";
+    if (!running) {
+      if (!this.autoSpawn) {
+        throw new Error(
+          `No Buoy broker reachable at ${this.url} and autoSpawnBroker is off. Start the Buoy desktop app, or enable autoSpawnBroker.`
+        );
+      }
+      this.log(`no broker at ${this.url} \u2014 spawning one in-process on :${this.port}`);
+      this.broker = createBroker({
+        port: this.port,
+        onError: (e) => this.log(`broker error: ${e.code ?? e.message}`)
+      });
+      await waitForBroker(this.url);
+      mode = "spawned";
+    } else {
+      this.log(`found a running broker at ${this.url} \u2014 connecting as a dashboard`);
+    }
+    await this.connectSocket();
+    return mode;
+  }
+  connectSocket() {
+    return new Promise((resolve, reject) => {
+      const socket = ioClient(this.url, {
+        transports: ["websocket"],
+        query: { deviceName: DASHBOARD_NAME },
+        reconnection: true,
+        reconnectionDelay: 500,
+        timeout: 4e3
+      });
+      this.socket = socket;
+      let settled = false;
+      const onConnect = () => {
+        if (settled) return;
+        settled = true;
+        this.log("connected to broker");
+        resolve();
+      };
+      socket.on("connect", onConnect);
+      socket.once("connect_error", (err) => {
+        if (settled) return;
+        settled = true;
+        reject(new Error(`failed to connect to broker at ${this.url}: ${err.message}`));
+      });
+      socket.on("devtool-capabilities", (msg) => {
+        this.capabilities.set(msg.persistentDeviceId, msg);
+      });
+      socket.on("all-devices-update", (list) => {
+        if (Array.isArray(list)) this.devices = list;
+      });
+      socket.on("devtool-sync", (msg) => {
+        const key = snapKey(msg.persistentDeviceId, msg.toolId);
+        this.snapshots.set(key, msg.payload);
+        const waiters = this.snapshotWaiters.get(key);
+        if (waiters && waiters.length) {
+          this.snapshotWaiters.set(key, []);
+          for (const w of waiters) w(msg.payload);
+        }
+      });
+      socket.on("devtool-action-result", (msg) => {
+        const pending = this.pendingActions.get(msg.requestId);
+        if (!pending) return;
+        this.pendingActions.delete(msg.requestId);
+        clearTimeout(pending.timer);
+        pending.resolve(msg);
+      });
+    });
+  }
+  /** Disconnect and tear down a spawned broker, if any. */
+  async stop() {
+    for (const [, p] of this.pendingActions) {
+      clearTimeout(p.timer);
+      p.reject(new Error("SyncClient stopped"));
+    }
+    this.pendingActions.clear();
+    this.socket?.close();
+    this.socket = null;
+    if (this.broker) {
+      await this.broker.close();
+      this.broker = null;
+    }
+  }
+  // ----------------------------------------------------------------
+  // Queries
+  // ----------------------------------------------------------------
+  /** All devices the broker knows about, merged with their advertised tools. */
+  listDevices() {
+    return this.devices.filter((d) => d.deviceName !== DASHBOARD_NAME && d.deviceId).map((d) => {
+      const caps = this.capabilities.get(d.deviceId);
+      return {
+        deviceId: d.deviceId,
+        deviceName: d.deviceName,
+        platform: d.platform,
+        isConnected: d.isConnected !== false,
+        isPro: d.isPro === true,
+        tools: caps?.tools ?? []
+      };
+    });
+  }
+  /** Connected devices only. */
+  connectedDevices() {
+    return this.listDevices().filter((d) => d.isConnected);
+  }
+  /** Actions advertised for a tool, with the devices offering it. */
+  toolActions(toolId) {
+    return this.listDevices().map((d) => {
+      const tool = d.tools.find((t) => t.toolId === toolId);
+      return tool ? { deviceId: d.deviceId, deviceName: d.deviceName, actions: tool.actions } : null;
+    }).filter((x) => x !== null);
+  }
+  /**
+   * Resolve a concrete target deviceId. If `deviceId` is given it's used as-is.
+   * Otherwise, if exactly one device is connected, that one is chosen; if none
+   * or many, an informative error is thrown (callers can pass "All" explicitly).
+   */
+  resolveDevice(deviceId) {
+    if (deviceId) return deviceId;
+    const connected = this.connectedDevices();
+    if (connected.length === 1) return connected[0].deviceId;
+    if (connected.length === 0) {
+      throw new Error("No devices are connected to the broker. Open the app with Buoy devtools running.");
+    }
+    const list = connected.map((d) => `${d.deviceName} (${d.deviceId})`).join(", ");
+    throw new Error(`Multiple devices connected \u2014 specify deviceId. Connected: ${list}`);
+  }
+  /**
+   * Resolve a target device AND require it to be on Buoy Pro. The Buoy MCP is a
+   * Pro feature: data/action tools call this so a free app can't be driven
+   * through the MCP. The app's Keygen-validated license is the source of truth
+   * (the device reports it over the broker); this just reads that flag.
+   *
+   * `list_devices` deliberately does NOT call this — a free user can still see
+   * their device and that it's unlicensed, which explains why everything else
+   * is blocked.
+   */
+  requireProDevice(deviceId) {
+    const proMsg = (name) => `Buoy Pro is required to use the MCP.${name ? ` The connected app "${name}" is on the free tier.` : ""} Upgrade to Buoy Pro in the app to enable MCP access (run \`list_devices\` to check status).`;
+    if (deviceId === ALL_DEVICES) {
+      if (!this.connectedDevices().some((d) => d.isPro)) throw new Error(proMsg());
+      return ALL_DEVICES;
+    }
+    const target = this.resolveDevice(deviceId);
+    const dev = this.connectedDevices().find((d) => d.deviceId === target);
+    if (!dev?.isPro) throw new Error(proMsg(dev?.deviceName));
+    return target;
+  }
+  // ----------------------------------------------------------------
+  // Watch + snapshots
+  // ----------------------------------------------------------------
+  ensureWatching(toolId, targetDeviceId) {
+    const key = snapKey(targetDeviceId, toolId);
+    if (this.watching.has(key)) return;
+    this.watching.add(key);
+    this.socket?.emit("devtool-watch", { toolId, targetDeviceId, watching: true });
+  }
+  /** Stop streaming a tool (releases the device-side backpressure). */
+  unwatch(toolId, targetDeviceId) {
+    const key = snapKey(targetDeviceId, toolId);
+    if (!this.watching.delete(key)) return;
+    this.socket?.emit("devtool-watch", { toolId, targetDeviceId, watching: false });
+  }
+  /** Last snapshot received for a tool/device, if any. */
+  cachedSnapshot(toolId, deviceId) {
+    return this.snapshots.get(snapKey(deviceId, toolId));
+  }
+  /**
+   * Get a tool's current state. Starts watching (so the device begins emitting),
+   * explicitly requests state, and resolves with the next snapshot. Falls back
+   * to the last cached snapshot if the request times out.
+   */
+  async getSnapshot(toolId, deviceId, opts = {}) {
+    const target = this.resolveDevice(deviceId);
+    const key = snapKey(target, toolId);
+    this.ensureWatching(toolId, target);
+    const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
+    this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
+    const payload = await next;
+    if (payload !== void 0) return { deviceId: target, payload };
+    const cached = this.snapshots.get(key);
+    if (cached !== void 0) return { deviceId: target, payload: cached };
+    throw new Error(`Timed out waiting for "${toolId}" state from ${target} (is the tool active?)`);
+  }
+  waitForSnapshot(key, timeoutMs) {
+    return new Promise((resolve) => {
+      const waiters = this.snapshotWaiters.get(key) ?? [];
+      const timer = setTimeout(() => {
+        const remaining = (this.snapshotWaiters.get(key) ?? []).filter((w) => w !== onSnap);
+        this.snapshotWaiters.set(key, remaining);
+        resolve(void 0);
+      }, timeoutMs);
+      const onSnap = (payload) => {
+        clearTimeout(timer);
+        resolve(payload);
+      };
+      waiters.push(onSnap);
+      this.snapshotWaiters.set(key, waiters);
+    });
+  }
+  // ----------------------------------------------------------------
+  // Actions
+  // ----------------------------------------------------------------
+  /**
+   * Invoke a remote action on a device and await its result. Pass deviceId to
+   * target one device, or "All" to broadcast (resolves with the first responder).
+   */
+  async callAction(toolId, action, params, deviceId, opts = {}) {
+    const target = deviceId === ALL_DEVICES ? ALL_DEVICES : this.resolveDevice(deviceId);
+    if (!this.socket) throw new Error("SyncClient is not connected");
+    const requestId = randomUUID();
+    const timeoutMs = opts.timeoutMs ?? this.actionTimeoutMs;
+    const result = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingActions.delete(requestId);
+        reject(new Error(`Action "${toolId}.${action}" timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pendingActions.set(requestId, { resolve, reject, timer });
+      this.socket.emit("devtool-action", {
+        requestId,
+        toolId,
+        targetDeviceId: target,
+        action,
+        params: params ?? {}
+      });
+    });
+    if (!result.ok) {
+      throw new Error(result.error || `Action "${toolId}.${action}" failed on device`);
+    }
+    return result.result;
+  }
+};
+var snapKey = (deviceId, toolId) => `${deviceId}::${toolId}`;
+function probeBroker(url, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const req = http.get(url, (res) => {
+      res.resume();
+      resolve((res.statusCode ?? 0) > 0);
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on("error", () => resolve(false));
+  });
+}
+async function waitForBroker(url, attempts = 20) {
+  for (let i = 0; i < attempts; i++) {
+    if (await probeBroker(url, 300)) return;
+    await delay(50);
+  }
+  throw new Error(`Spawned broker never became reachable at ${url}`);
+}
+var delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// src/version.ts
+var VERSION = "5.0.0" ? "5.0.0" : "0.0.0-dev";
+var PACKAGE_NAME = "@buoy-gg/mcp";
+
+// src/update/checkForUpdate.ts
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+var CHECK_TTL_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1500;
+var REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+var CACHE_FILE = path.join(os.tmpdir(), "buoy-mcp-update-check.json");
+function isNewer(a, b) {
+  const parse = (v) => v.split("-")[0].split(".").map((n) => Number(n) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
+async function readCache() {
+  try {
+    const raw = await fs.readFile(CACHE_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.checkedAt === "number" && typeof parsed.latest === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+async function fetchLatest(now) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const latest = typeof body.version === "string" ? body.version : null;
+    if (latest) {
+      await fs.writeFile(CACHE_FILE, JSON.stringify({ checkedAt: now, latest })).catch(() => {
+      });
+    }
+    return latest;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function resolveLatest(now) {
+  const cache = await readCache();
+  if (cache && now - cache.checkedAt < CHECK_TTL_MS) return cache.latest;
+  return fetchLatest(now);
+}
+async function getUpdateNotice(now = Date.now()) {
+  if (VERSION === "0.0.0-dev") return null;
+  try {
+    const latest = await resolveLatest(now);
+    if (latest && isNewer(latest, VERSION)) {
+      return `A newer buoy-mcp is available (${latest}; you're on ${VERSION}). Update by re-running: npx -y ${PACKAGE_NAME}@latest init \u2014 then restart your editor.`;
+    }
+  } catch {
+  }
+  return null;
+}
+
+// src/tools/generic.ts
+import { z } from "zod";
+function json(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function fail(message) {
+  return { isError: true, content: [{ type: "text", text: message }] };
+}
+function registerGenericTools(server, sync) {
+  server.registerTool(
+    "list_devices",
+    {
+      description: "List the React Native devices connected to the Buoy broker and the dev tools each one exposes (toolId, version, available actions). Start here.",
+      inputSchema: {}
+    },
+    async () => {
+      const updateNotice = await getUpdateNotice();
+      const devices = sync.listDevices();
+      if (devices.length === 0) {
+        return json({
+          devices: [],
+          hint: "No devices connected. Open the app with Buoy devtools running, then retry.",
+          ...updateNotice ? { updateAvailable: updateNotice } : {}
+        });
+      }
+      const anyPro = devices.some((d) => d.isConnected && d.isPro);
+      return json({
+        devices,
+        ...anyPro ? {} : {
+          hint: "The Buoy MCP is a Pro feature \u2014 no connected device has an active Buoy Pro license, so data/action tools are blocked. Upgrade to Buoy Pro in the app to enable them."
+        },
+        ...updateNotice ? { updateAvailable: updateNotice } : {}
+      });
+    }
+  );
+  server.registerTool(
+    "list_tool_actions",
+    {
+      description: "List the actions a given tool exposes, and which connected devices offer it. Use the action names with call_action.",
+      inputSchema: {
+        toolId: z.string().describe('The tool id, e.g. "perf-monitor", "network", "react-query".')
+      }
+    },
+    async ({ toolId }) => {
+      const offerings = sync.toolActions(toolId);
+      if (offerings.length === 0) {
+        return fail(
+          `No connected device exposes tool "${toolId}". Call list_devices to see available tools.`
+        );
+      }
+      return json({ toolId, offerings });
+    }
+  );
+  server.registerTool(
+    "get_snapshot",
+    {
+      description: "Read a tool's current state (its sync snapshot) from a device. Starts watching the tool and returns the next fresh snapshot.",
+      inputSchema: {
+        toolId: z.string().describe("The tool id to read state from."),
+        deviceId: z.string().optional().describe("Target device id. Omit to auto-select when one device is connected."),
+        timeoutMs: z.number().optional().describe("How long to wait for a fresh snapshot before falling back to the cached one.")
+      }
+    },
+    async ({ toolId, deviceId, timeoutMs }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const { payload } = await sync.getSnapshot(toolId, target, { timeoutMs });
+        return json({ toolId, deviceId: target, snapshot: payload });
+      } catch (e) {
+        return fail(errMsg(e));
+      }
+    }
+  );
+  server.registerTool(
+    "call_action",
+    {
+      description: "Invoke any action a tool exposes (see list_tool_actions) and return its result. This is the generic escape hatch that works for every Buoy tool.",
+      inputSchema: {
+        toolId: z.string().describe('The tool id, e.g. "perf-monitor".'),
+        action: z.string().describe('The action name, e.g. "startRecording", "clearAll".'),
+        params: z.record(z.unknown()).optional().describe("JSON params object for the action (shape depends on the action)."),
+        deviceId: z.string().optional().describe('Target device id. Omit to auto-select one device, or "All" to broadcast.'),
+        timeoutMs: z.number().optional().describe("Max time to wait for the device's result.")
+      }
+    },
+    async ({ toolId, action, params, deviceId, timeoutMs }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const result = await sync.callAction(toolId, action, params, target, { timeoutMs });
+        return json({ toolId, action, ok: true, result: result ?? null });
+      } catch (e) {
+        return fail(errMsg(e));
+      }
+    }
+  );
+}
+function errMsg(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+
+// src/tools/packs/perfRanking.ts
+var clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+var FALLBACK = {
+  perCaseDurationMs: 5e3,
+  settleMs: 600,
+  navTimeoutMs: 5e3,
+  runsPerCase: 3,
+  coolDownMs: 2e3,
+  discardWarmupRuns: 0
+};
+function pick(override, saved, fallback) {
+  return override ?? saved ?? fallback;
+}
+function buildAutomationConfig(input, base = {}) {
+  const warnings = [];
+  const targetRoute = (input.targetRoute || "").trim();
+  if (!targetRoute) throw new Error("targetRoute is required (the screen to benchmark).");
+  let bounceRoute = (input.bounceRoute || "").trim();
+  if (!bounceRoute) bounceRoute = targetRoute === "/" ? "/_buoy_bounce" : "/";
+  if (bounceRoute === targetRoute) {
+    throw new Error(
+      `bounceRoute ("${bounceRoute}") must differ from targetRoute \u2014 it's the screen we bounce to so the test screen fully remounts each run.`
+    );
+  }
+  if (!Array.isArray(input.cases) || input.cases.length === 0) {
+    throw new Error("At least one case is required.");
+  }
+  const cases = input.cases.map((c, i) => {
+    const name = (c.name || "").trim() || `case ${i + 1}`;
+    return { id: `case-${i}`, name, params: c.params ?? {}, route: c.route };
+  });
+  const runsPerCase = clamp(Math.round(pick(input.runsPerCase, base.runsPerCase, FALLBACK.runsPerCase)), 1, 10);
+  const coolDownMs = clamp(Math.round(pick(input.coolDownMs, base.coolDownMs, FALLBACK.coolDownMs)), 0, 3e4);
+  const discardWarmupRuns = clamp(
+    Math.round(pick(input.discardWarmupRuns, base.discardWarmupRuns, FALLBACK.discardWarmupRuns)),
+    0,
+    runsPerCase - 1
+  );
+  const shuffleCases = input.shuffleCases ?? base.shuffleCases ?? cases.length > 3;
+  if (cases.length > 3 && shuffleCases === false) {
+    warnings.push(
+      "shuffleCases is off with >3 cases \u2014 later cases may be thermally throttled, biasing results. Consider enabling it."
+    );
+  }
+  if (runsPerCase === 1) {
+    warnings.push("runsPerCase=1 \u2014 no median/variance; a single noisy run can mislead. 3+ is recommended.");
+  }
+  const config = {
+    targetRoute,
+    bounceRoute,
+    perCaseDurationMs: clamp(
+      Math.round(pick(input.perCaseDurationMs, base.perCaseDurationMs, FALLBACK.perCaseDurationMs)),
+      1e3,
+      6e4
+    ),
+    settleMs: clamp(Math.round(pick(input.settleMs, base.settleMs, FALLBACK.settleMs)), 0, 1e4),
+    navTimeoutMs: clamp(Math.round(pick(input.navTimeoutMs, base.navTimeoutMs, FALLBACK.navTimeoutMs)), 1e3, 3e4),
+    cases,
+    runsPerCase,
+    coolDownMs,
+    discardWarmupRuns,
+    shuffleCases,
+    reloadBetweenCases: input.reloadBetweenCases ?? base.reloadBetweenCases ?? false
+  };
+  return { config, warnings };
+}
+function describeBenchmarkSettings(config) {
+  const secs = (ms) => ms >= 1e3 ? `${(ms / 1e3).toFixed(ms % 1e3 ? 1 : 0)}s` : `${ms}ms`;
+  const runs = config.runsPerCase ?? 1;
+  const estMs = estimateBatchMs(config);
+  const estMin = estMs / 6e4;
+  const est = estMin >= 1 ? `~${estMin.toFixed(1)} min` : `~${Math.round(estMs / 1e3)}s`;
+  const parts = [
+    `**${secs(config.perCaseDurationMs)} measured per page**`,
+    runs > 1 ? `**${runs} runs each** (median taken)` : `**1 run each** (no median \u2014 noisier)`,
+    config.reloadBetweenCases ? "**full reload between pages** (no state leaks across tests)" : "no reload between pages",
+    config.shuffleCases ? "shuffled order (cancels thermal bias)" : "fixed order"
+  ];
+  const perPageMs = config.settleMs + config.perCaseDurationMs + (config.coolDownMs ?? 0) + 1800;
+  return `${parts.join(", ")}. That's ~${secs(perPageMs)} wall-clock per page; for ${config.cases.length} page(s) \xD7 ${runs} run(s), **${est}** total.`;
+}
+function estimateBatchMs(config) {
+  const NAV_OVERHEAD = 1800;
+  const perRun = config.settleMs + config.perCaseDurationMs + config.coolDownMs + NAV_OVERHEAD;
+  let total = config.cases.length * (config.runsPerCase ?? 1) * perRun;
+  if (config.reloadBetweenCases) total += config.cases.length * 3e3;
+  return total;
+}
+function computeFlags(r) {
+  const flags = [];
+  const max = r.deviceMaxRefreshRate;
+  if (r.uiFps != null && max && r.uiFps < max * 0.95) {
+    flags.push("UI thread drops frames");
+  } else if (r.uiJank != null && r.uiJank >= 2) {
+    flags.push("UI jank spikes");
+  }
+  if (r.cpu != null && r.cpu >= 90) flags.push("CPU near cap");
+  if (r.jsJank != null && r.jsJank >= 5) flags.push("JS thread stalls");
+  return flags;
+}
+function rankBatchFromIndex(index, batchId, casesOrder, failures = []) {
+  const entries = index.filter((e) => e.batchId === batchId);
+  const failureByIndex = new Map(failures.map((f) => [f.index, f.reason]));
+  const indexes = casesOrder ? casesOrder.map((_, i) => i) : Array.from(new Set(entries.map((e) => e.batchIndex ?? 0))).sort((a, b) => a - b);
+  const medianForCase = (batchIndex) => {
+    const runs = entries.filter((e) => (e.batchIndex ?? 0) === batchIndex);
+    if (runs.length === 0) return void 0;
+    return runs.find((e) => e.isMedianRun === true) ?? runs.find((e) => e.runIndex === 0 || e.runIndex === void 0) ?? runs[0];
+  };
+  const num = (v) => typeof v === "number" ? v : null;
+  const rows = indexes.map((batchIndex) => {
+    const median = medianForCase(batchIndex);
+    const runs = entries.filter((e) => (e.batchIndex ?? 0) === batchIndex).length;
+    const caseName = casesOrder?.[batchIndex]?.name ?? median?.name ?? `case ${batchIndex + 1}`;
+    const failureReason = failureByIndex.get(batchIndex) ?? median?.batchFailureReason;
+    const failed = Boolean(failureReason) || !median;
+    const base = {
+      batchIndex,
+      caseName,
+      params: median?.params ?? {},
+      runs,
+      failed,
+      failureReason: failed ? failureReason ?? "no run recorded" : void 0,
+      uiFps: num(median?.uiFpsAvg),
+      jsFps: num(median?.jsFpsAvg),
+      cpu: num(median?.cpuAvg),
+      memMb: num(median?.memMaxMb),
+      jsJank: num(median?.jsJankFrames),
+      uiJank: num(median?.uiJankFrames),
+      deviceMaxRefreshRate: num(median?.deviceMaxRefreshRate),
+      deltaUiFps: null,
+      deltaJsFps: null
+    };
+    return { ...base, flags: failed ? [] : computeFlags(base) };
+  });
+  const baseline = rows[0];
+  if (baseline) {
+    for (const r of rows) {
+      if (r === baseline) continue;
+      if (r.uiFps != null && baseline.uiFps != null) r.deltaUiFps = round(r.uiFps - baseline.uiFps, 1);
+      if (r.jsFps != null && baseline.jsFps != null) r.deltaJsFps = round(r.jsFps - baseline.jsFps, 1);
+    }
+  }
+  const live = rows.filter((r) => !r.failed);
+  const leaderBy = (sel, better) => {
+    let best;
+    let bestV = NaN;
+    for (const r of live) {
+      const v = sel(r);
+      if (v == null) continue;
+      if (best === void 0 || better(v, bestV)) {
+        best = r;
+        bestV = v;
+      }
+    }
+    return best?.caseName;
+  };
+  const totalJank = (r) => r.jsJank == null && r.uiJank == null ? null : (r.jsJank ?? 0) + (r.uiJank ?? 0);
+  const leaders = {
+    uiFps: leaderBy((r) => r.uiFps, (a, b) => a > b),
+    jsFps: leaderBy((r) => r.jsFps, (a, b) => a > b),
+    lowestCpu: leaderBy((r) => r.cpu, (a, b) => a < b),
+    lowestMem: leaderBy((r) => r.memMb, (a, b) => a < b),
+    fewestJank: leaderBy(totalJank, (a, b) => a < b)
+  };
+  const flagged = live.filter((r) => r.flags.length > 0).map((r) => ({ caseName: r.caseName, flags: r.flags }));
+  const balanced = live.filter((r) => r.flags.length === 0).sort(
+    (a, b) => (b.uiFps ?? 0) - (a.uiFps ?? 0) || (a.cpu ?? Infinity) - (b.cpu ?? Infinity) || (a.memMb ?? Infinity) - (b.memMb ?? Infinity)
+  ).map((r) => r.caseName);
+  return {
+    batchId,
+    baselineName: baseline?.caseName ?? null,
+    deviceMaxRefreshRate: live.find((r) => r.deviceMaxRefreshRate != null)?.deviceMaxRefreshRate ?? null,
+    rows,
+    leaders,
+    flagged,
+    balanced
+  };
+}
+function formatRankingMarkdown(ranking) {
+  const f = (v, d = 1) => v == null ? "\u2014" : v.toFixed(d);
+  const delta = (v) => v == null ? "" : v > 0 ? ` (+${v.toFixed(1)})` : ` (${v.toFixed(1)})`;
+  const lines = [];
+  lines.push(`### Benchmark batch \`${ranking.batchId}\``);
+  lines.push(
+    `**No single winner \u2014 weigh the trade-offs.** UI-thread health matters more than raw averages: a cheap run that drops UI frames is worse than a pricier one that holds them.`
+  );
+  lines.push("");
+  lines.push("| # | Case | UI FPS | JS FPS | CPU % | Mem MB | JS jank | UI jank | Flags |");
+  lines.push("|---|------|-------:|-------:|------:|-------:|--------:|--------:|-------|");
+  for (const r of ranking.rows) {
+    if (r.failed) {
+      lines.push(`| ${r.batchIndex} | ${r.caseName} | \u2014 | \u2014 | \u2014 | \u2014 | \u2014 | \u2014 | \u274C FAILED (${r.failureReason}) |`);
+      continue;
+    }
+    const flagCell = r.flags.length ? `\u26A0\uFE0F ${r.flags.join("; ")}` : "\u2713 clean";
+    lines.push(
+      `| ${r.batchIndex} | ${r.caseName} | ${f(r.uiFps)}${delta(r.deltaUiFps)} | ${f(r.jsFps)}${delta(
+        r.deltaJsFps
+      )} | ${f(r.cpu)} | ${f(r.memMb)} | ${f(r.jsJank, 0)} | ${f(r.uiJank, 0)} | ${flagCell} |`
+    );
+  }
+  lines.push("");
+  const L = ranking.leaders;
+  const leaderLine = [
+    L.uiFps && `UI FPS \u2192 **${L.uiFps}**`,
+    L.jsFps && `JS FPS \u2192 **${L.jsFps}**`,
+    L.lowestCpu && `lowest CPU \u2192 **${L.lowestCpu}**`,
+    L.lowestMem && `lowest mem \u2192 **${L.lowestMem}**`,
+    L.fewestJank && `fewest jank \u2192 **${L.fewestJank}**`
+  ].filter(Boolean).join(" \xB7 ");
+  if (leaderLine) lines.push(`**Per-metric best:** ${leaderLine}`);
+  lines.push(
+    ranking.balanced.length ? `**Balanced (caps nothing):** ${ranking.balanced.join(", ")}` : `**Balanced (caps nothing):** none \u2014 every case stressed at least one axis; pick by which trade-off you can accept.`
+  );
+  if (ranking.flagged.length) {
+    lines.push(
+      `**\u26A0\uFE0F At-risk:** ${ranking.flagged.map((x) => `${x.caseName} (${x.flags.join("; ")})`).join(" \xB7 ")}`
+    );
+  }
+  lines.push("");
+  lines.push(
+    `_Deltas vs baseline (case #0). Don't pick on one metric \u2014 explain the trade-off (e.g. "A is cheapest but drops UI frames \u2192 jank risk; B costs more CPU but caps nothing")._`
+  );
+  return lines.join("\n");
+}
+function compareReportStats(a, b) {
+  const ch = (x, y) => ({
+    a: { avg: round(x.avg, 1), p95: round(x.p95, 1) },
+    b: { avg: round(y.avg, 1), p95: round(y.p95, 1) },
+    deltaAvg: round(y.avg - x.avg, 1)
+  });
+  return {
+    a: a.name,
+    b: b.name,
+    uiFps: ch(a.stats.uiFps, b.stats.uiFps),
+    jsFps: ch(a.stats.jsFps, b.stats.jsFps),
+    cpuUsage: ch(a.stats.cpuUsage, b.stats.cpuUsage),
+    memoryUsage: ch(a.stats.memoryUsage, b.stats.memoryUsage),
+    jsJankFrames: { a: a.stats.jsJankFrames, b: b.stats.jsJankFrames, delta: b.stats.jsJankFrames - a.stats.jsJankFrames },
+    uiJankFrames: { a: a.stats.uiJankFrames, b: b.stats.uiJankFrames, delta: b.stats.uiJankFrames - a.stats.uiJankFrames }
+  };
+}
+function round(n, d) {
+  const p = Math.pow(10, d);
+  return Math.round(n * p) / p;
+}
+
+// src/tools/packs/perfMonitor.ts
+import { z as z2 } from "zod";
+
+// src/tools/packs/perfMonitorTypes.ts
+var PERF_TOOL_ID = "perf-monitor";
+
+// src/tools/packs/perfMonitor.ts
+var POLL_INTERVAL_MS = 1500;
+var delay2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var json2 = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+var text = (s) => ({ content: [{ type: "text", text: s }] });
+var fail2 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg2 = (e) => e instanceof Error ? e.message : String(e);
+var caseSchema = z2.object({
+  name: z2.string().describe("Display name for this variant (becomes the saved run's name)."),
+  params: z2.record(z2.string()).optional().describe('Query params applied to the route for this case, e.g. { "renderer": "v2", "count": "100" }.'),
+  route: z2.string().optional().describe("Optional per-case route override; defaults to targetRoute.")
+});
+async function readDeviceSettings(sync, deviceId) {
+  try {
+    const cfg = await sync.callAction(PERF_TOOL_ID, "getAutomationConfig", {}, deviceId);
+    if (!cfg) return {};
+    const {
+      perCaseDurationMs,
+      settleMs,
+      navTimeoutMs,
+      runsPerCase,
+      coolDownMs,
+      discardWarmupRuns,
+      shuffleCases,
+      reloadBetweenCases
+    } = cfg;
+    return {
+      perCaseDurationMs,
+      settleMs,
+      navTimeoutMs,
+      runsPerCase,
+      coolDownMs,
+      discardWarmupRuns,
+      shuffleCases,
+      reloadBetweenCases
+    };
+  } catch {
+    return {};
+  }
+}
+async function readPerfSnapshot(sync, deviceId) {
+  const { payload } = await sync.getSnapshot(PERF_TOOL_ID, deviceId, { timeoutMs: 4e3 });
+  return payload;
+}
+function batchIdsIn(index) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const e of index ?? []) if (e.batchId) ids.add(e.batchId);
+  return ids;
+}
+function runCountFor(index, batchId) {
+  return (index ?? []).filter((e) => e.batchId === batchId).length;
+}
+function newestBatchId(index) {
+  let best = null;
+  for (const e of index ?? []) {
+    if (e.batchId && (!best || e.createdAt > best.at)) best = { id: e.batchId, at: e.createdAt };
+  }
+  return best?.id ?? null;
+}
+function failuresFromIndex(index, batchId) {
+  const byCase = /* @__PURE__ */ new Map();
+  for (const e of index ?? []) {
+    if (e.batchId === batchId && e.batchFailureReason && !byCase.has(e.batchIndex ?? 0)) {
+      byCase.set(e.batchIndex ?? 0, e.batchFailureReason);
+    }
+  }
+  return [...byCase.entries()].map(([index2, reason]) => ({ index: index2, reason }));
+}
+async function waitForBatchByIndex(sync, deviceId, opts) {
+  const { preBatchIds, expectedRuns, maxWaitMs, log } = opts;
+  const start = Date.now();
+  let lastPhase = "";
+  let sawActive = false;
+  let idleStreak = 0;
+  while (Date.now() - start < maxWaitMs) {
+    let snap2;
+    try {
+      snap2 = await readPerfSnapshot(sync, deviceId);
+    } catch {
+      await delay2(POLL_INTERVAL_MS);
+      continue;
+    }
+    const index = snap2.index ?? [];
+    const phase = snap2.live?.automation?.phase ?? "idle";
+    const completed = snap2.live?.automationCompleted;
+    if (completed?.phase === "cancelled" && !preBatchIds.has(completed.batchId)) {
+      return { batchId: completed.batchId, failures: [], cancelled: true };
+    }
+    if (completed?.phase === "done" && !preBatchIds.has(completed.batchId)) {
+      return { batchId: completed.batchId, failures: completed.failures ?? failuresFromIndex(index, completed.batchId) };
+    }
+    if (phase !== "idle") sawActive = true;
+    if (phase !== lastPhase) {
+      lastPhase = phase;
+      log(`automation phase: ${phase}`);
+    }
+    const newId2 = [...batchIdsIn(index)].find((id) => !preBatchIds.has(id));
+    if (newId2) {
+      const count = runCountFor(index, newId2);
+      if (expectedRuns > 0 && count >= expectedRuns) {
+        log(`batch ${newId2} complete (${count}/${expectedRuns} runs saved)`);
+        return { batchId: newId2, failures: failuresFromIndex(index, newId2) };
+      }
+      if (phase === "idle" && sawActive && count > 0) {
+        if (++idleStreak >= 3) {
+          log(`batch ${newId2} settled (${count} runs, automation idle)`);
+          return { batchId: newId2, failures: failuresFromIndex(index, newId2) };
+        }
+      } else {
+        idleStreak = 0;
+      }
+    }
+    await delay2(POLL_INTERVAL_MS);
+  }
+  const snap = await readPerfSnapshot(sync, deviceId).catch(() => null);
+  const newId = snap ? [...batchIdsIn(snap.index)].find((id) => !preBatchIds.has(id)) : void 0;
+  if (newId && snap) return { batchId: newId, failures: failuresFromIndex(snap.index, newId), timedOut: true };
+  throw new Error(
+    `Batch did not start within ${Math.round(maxWaitMs / 1e3)}s (last phase: ${lastPhase || "idle"}). Check get_automation_status \u2014 the device may not have navigated.`
+  );
+}
+function registerPerfMonitorTools(server, sync) {
+  server.registerTool(
+    "run_benchmark_batch",
+    {
+      description: "Run a perf-monitor benchmark batch and return a RANKED comparison of all cases (winner by UI FPS). Give it a target route and a matrix of cases (each a name + query params that select a variant on that route); it navigates, records, and benchmarks each case on the device, then ranks them. This blocks until the batch completes (can be minutes for large batches). The app must have the target route render its variants from the params.",
+      inputSchema: {
+        targetRoute: z2.string().describe('The screen to benchmark, e.g. "/perf-test". Reads case params to pick a variant.'),
+        cases: z2.array(caseSchema).min(1).describe("The variants to compare. Case #0 is the baseline for deltas."),
+        bounceRoute: z2.string().optional().describe('Screen to bounce to between runs so the test screen fully remounts. Defaults to "/" (or a stub if target is "/").'),
+        runsPerCase: z2.number().optional().describe("Runs per case; the median becomes the canonical result. Default 3 (1\u201310)."),
+        perCaseDurationMs: z2.number().optional().describe("How long to record each run. Default 5000."),
+        settleMs: z2.number().optional().describe("Idle gap after navigation before recording. Default 600."),
+        coolDownMs: z2.number().optional().describe("Idle between runs/cases for thermal recovery. Default 2000."),
+        navTimeoutMs: z2.number().optional().describe("Max wait for navigation per run. Default 5000."),
+        discardWarmupRuns: z2.number().optional().describe("Discard first N runs of each case before taking the median. Default 0."),
+        shuffleCases: z2.boolean().optional().describe("Interleave + shuffle case order to cancel thermal bias. Default on for >3 cases."),
+        reloadBetweenCases: z2.boolean().optional().describe("Fully reload JS between cases (needs <AutomationResumer/> mounted). Default false."),
+        deviceId: z2.string().optional().describe("Target device id. Omit to auto-select when one device is connected."),
+        maxWaitMs: z2.number().optional().describe("Safety cap for how long to wait for completion. Defaults to ~3\xD7 the estimate + 60s.")
+      }
+    },
+    async (args) => {
+      const log = (m) => process.stderr.write(`[buoy-mcp] ${m}
+`);
+      try {
+        const deviceId = sync.requireProDevice(args.deviceId);
+        const base = await readDeviceSettings(sync, deviceId);
+        const { config, warnings } = buildAutomationConfig(args, base);
+        const estimateMs = estimateBatchMs(config);
+        const maxWaitMs = args.maxWaitMs ?? estimateMs * 3 + 6e4;
+        const expectedRuns = config.cases.length * (config.runsPerCase ?? 1);
+        await sync.callAction(PERF_TOOL_ID, "acknowledgeAutomation", {}, deviceId).catch(() => {
+        });
+        await sync.callAction(PERF_TOOL_ID, "setEnabled", { enabled: true }, deviceId).catch(() => {
+        });
+        await sync.callAction(PERF_TOOL_ID, "refreshIndex", {}, deviceId).catch(() => {
+        });
+        const before = await readPerfSnapshot(sync, deviceId);
+        const preBatchIds = batchIdsIn(before.index);
+        log(
+          `starting batch: ${config.cases.length} cases \xD7 ${config.runsPerCase} runs (~${Math.round(estimateMs / 1e3)}s estimated) on ${deviceId}`
+        );
+        await sync.callAction(PERF_TOOL_ID, "startAutomation", { config }, deviceId);
+        const outcome = await waitForBatchByIndex(sync, deviceId, {
+          preBatchIds,
+          expectedRuns,
+          maxWaitMs,
+          log
+        });
+        if (outcome.cancelled) {
+          await sync.callAction(PERF_TOOL_ID, "acknowledgeAutomation", {}, deviceId).catch(() => {
+          });
+          return fail2(`Batch ${outcome.batchId} was cancelled before completing.`);
+        }
+        await sync.callAction(PERF_TOOL_ID, "refreshIndex", {}, deviceId).catch(() => {
+        });
+        const snap = await readPerfSnapshot(sync, deviceId);
+        const ranking = rankBatchFromIndex(snap.index ?? [], outcome.batchId, config.cases, outcome.failures);
+        await sync.callAction(PERF_TOOL_ID, "acknowledgeAutomation", {}, deviceId).catch(() => {
+        });
+        await sync.callAction(PERF_TOOL_ID, "setEnabled", { enabled: false }, deviceId).catch(() => {
+        });
+        const md = formatRankingMarkdown(ranking);
+        const summary = {
+          batchId: outcome.batchId,
+          leaders: ranking.leaders,
+          balanced: ranking.balanced,
+          flagged: ranking.flagged,
+          rows: ranking.rows,
+          failures: outcome.failures,
+          warnings,
+          estimateMs,
+          ...outcome.timedOut ? { note: "Wait cap hit \u2014 results may be partial (some runs may still be saving)." } : {}
+        };
+        return text(`${md}
+
+\`\`\`json
+${JSON.stringify(summary, null, 2)}
+\`\`\``);
+      } catch (e) {
+        return fail2(errMsg2(e));
+      }
+    }
+  );
+  server.registerTool(
+    "get_automation_status",
+    {
+      description: "Get the perf-monitor automation batch status (current phase + last completed batch) without waiting.",
+      inputSchema: { deviceId: z2.string().optional().describe("Target device id (auto-selected if one is connected).") }
+    },
+    async ({ deviceId }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const snap = await readPerfSnapshot(sync, target);
+        return json2({
+          deviceId: target,
+          automation: snap.live?.automation ?? { phase: "idle" },
+          automationCompleted: snap.live?.automationCompleted ?? null
+        });
+      } catch (e) {
+        return fail2(errMsg2(e));
+      }
+    }
+  );
+  server.registerTool(
+    "wait_for_automation",
+    {
+      description: "Block until the in-flight perf-monitor batch finishes, then return its ranked comparison. Use this if a batch was started another way (e.g. on the device).",
+      inputSchema: {
+        deviceId: z2.string().optional().describe("Target device id (auto-selected if one is connected)."),
+        maxWaitMs: z2.number().optional().describe("Max time to wait. Default 600000 (10 min).")
+      }
+    },
+    async ({ deviceId, maxWaitMs }) => {
+      const log = (m) => process.stderr.write(`[buoy-mcp] ${m}
+`);
+      const cap = maxWaitMs ?? 6e5;
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const start = Date.now();
+        let sawActive = false;
+        let idleStreak = 0;
+        let lastCount = -1;
+        let resolved = null;
+        while (Date.now() - start < cap) {
+          let snap2;
+          try {
+            snap2 = await readPerfSnapshot(sync, target);
+          } catch {
+            await delay2(POLL_INTERVAL_MS);
+            continue;
+          }
+          const completed = snap2.live?.automationCompleted;
+          if (completed?.phase === "cancelled") return fail2(`Batch ${completed.batchId} was cancelled.`);
+          if (completed?.phase === "done") {
+            resolved = { batchId: completed.batchId, failures: completed.failures ?? failuresFromIndex(snap2.index, completed.batchId) };
+            break;
+          }
+          const phase = snap2.live?.automation?.phase ?? "idle";
+          if (phase !== "idle") sawActive = true;
+          const newest = newestBatchId(snap2.index);
+          if (phase === "idle" && newest) {
+            const count = runCountFor(snap2.index, newest);
+            if (count === lastCount) {
+              if (sawActive && ++idleStreak >= 3) {
+                resolved = { batchId: newest, failures: failuresFromIndex(snap2.index, newest) };
+                break;
+              }
+              if (!sawActive && Date.now() - start > 4e3) {
+                resolved = { batchId: newest, failures: failuresFromIndex(snap2.index, newest) };
+                break;
+              }
+            } else {
+              idleStreak = 0;
+              lastCount = count;
+            }
+          } else {
+            idleStreak = 0;
+          }
+          await delay2(POLL_INTERVAL_MS);
+        }
+        if (!resolved) return fail2("No automation batch completed within the wait window.");
+        await sync.callAction(PERF_TOOL_ID, "refreshIndex", {}, target).catch(() => {
+        });
+        const snap = await readPerfSnapshot(sync, target);
+        const ranking = rankBatchFromIndex(snap.index ?? [], resolved.batchId, void 0, resolved.failures);
+        await sync.callAction(PERF_TOOL_ID, "acknowledgeAutomation", {}, target).catch(() => {
+        });
+        return text(`${formatRankingMarkdown(ranking)}
+
+\`\`\`json
+${JSON.stringify(ranking, null, 2)}
+\`\`\``);
+      } catch (e) {
+        return fail2(errMsg2(e));
+      }
+    }
+  );
+  server.registerTool(
+    "get_batch_report",
+    {
+      description: "Re-rank a previously-run benchmark batch by its batchId (from the saved recordings index).",
+      inputSchema: {
+        batchId: z2.string().describe("The batch id to report on."),
+        deviceId: z2.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async ({ batchId, deviceId }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        await sync.callAction(PERF_TOOL_ID, "refreshIndex", {}, target).catch(() => {
+        });
+        const snap = await readPerfSnapshot(sync, target);
+        const entries = (snap.index ?? []).filter((e) => e.batchId === batchId);
+        if (entries.length === 0) return fail2(`No saved runs found for batch "${batchId}".`);
+        const ranking = rankBatchFromIndex(snap.index ?? [], batchId);
+        return text(`${formatRankingMarkdown(ranking)}
+
+\`\`\`json
+${JSON.stringify(ranking, null, 2)}
+\`\`\``);
+      } catch (e) {
+        return fail2(errMsg2(e));
+      }
+    }
+  );
+  server.registerTool(
+    "compare_reports",
+    {
+      description: "Compare two saved benchmark runs head-to-head (avg + p95 for FPS/CPU/memory, jank, with deltas).",
+      inputSchema: {
+        reportIdA: z2.string().describe("First (baseline) report id."),
+        reportIdB: z2.string().describe("Second report id to compare against the baseline."),
+        deviceId: z2.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async ({ reportIdA, reportIdB, deviceId }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const [a, b] = await Promise.all([
+          sync.callAction(PERF_TOOL_ID, "loadReport", { id: reportIdA }, target),
+          sync.callAction(PERF_TOOL_ID, "loadReport", { id: reportIdB }, target)
+        ]);
+        if (!a) return fail2(`Report "${reportIdA}" not found.`);
+        if (!b) return fail2(`Report "${reportIdB}" not found.`);
+        return json2(
+          compareReportStats(
+            { name: a.metadata.name, stats: a.stats },
+            { name: b.metadata.name, stats: b.stats }
+          )
+        );
+      } catch (e) {
+        return fail2(errMsg2(e));
+      }
+    }
+  );
+  server.registerTool(
+    "get_benchmark_settings",
+    {
+      description: "Read the device's saved benchmark settings (per-page duration, runs, cooldown, reload, shuffle) in plain English with a time estimate. Call this before run_benchmark_batch so you can tell the user what the run will do \u2014 run_benchmark_batch inherits these unless you override them.",
+      inputSchema: {
+        pages: z2.number().optional().describe("How many pages/variants you plan to test, for a total-time estimate. Default 1."),
+        deviceId: z2.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async ({ pages, deviceId }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const settings = await readDeviceSettings(sync, target);
+        const n = Math.max(1, Math.round(pages ?? 1));
+        const { config } = buildAutomationConfig(
+          { targetRoute: "/_preview", cases: Array.from({ length: n }, (_, i) => ({ name: `page ${i + 1}` })) },
+          settings
+        );
+        const source = Object.keys(settings).length > 0 ? "this device's saved settings" : "default profile (none saved)";
+        return text(
+          `**Benchmark settings (${source}):** ${describeBenchmarkSettings(config)}
+
+\`\`\`json
+${JSON.stringify(settings, null, 2)}
+\`\`\``
+        );
+      } catch (e) {
+        return fail2(errMsg2(e));
+      }
+    }
+  );
+  server.registerTool(
+    "set_benchmark_settings",
+    {
+      description: `PERSIST benchmark settings on the device so they stick across runs. Only use when the user explicitly wants to save a change ("always", "save this"). For a one-off, pass overrides to run_benchmark_batch instead \u2014 don't change their saved profile.`,
+      inputSchema: {
+        perCaseDurationMs: z2.number().optional().describe("Recording length per page (ms)."),
+        settleMs: z2.number().optional().describe("Idle after navigation before recording (ms)."),
+        coolDownMs: z2.number().optional().describe("Idle between runs/cases (ms)."),
+        navTimeoutMs: z2.number().optional().describe("Max wait for navigation per run (ms)."),
+        runsPerCase: z2.number().optional().describe("Runs per page; median is the canonical result (1\u201310)."),
+        discardWarmupRuns: z2.number().optional().describe("Discard first N runs of each page before the median."),
+        shuffleCases: z2.boolean().optional().describe("Interleave + shuffle case order to cancel thermal bias."),
+        reloadBetweenCases: z2.boolean().optional().describe("Fully reload JS between pages (needs <AutomationResumer/> mounted)."),
+        deviceId: z2.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const current = await sync.callAction(PERF_TOOL_ID, "getAutomationConfig", {}, target) ?? {};
+        const keys = [
+          "perCaseDurationMs",
+          "settleMs",
+          "coolDownMs",
+          "navTimeoutMs",
+          "runsPerCase",
+          "discardWarmupRuns",
+          "shuffleCases",
+          "reloadBetweenCases"
+        ];
+        const overrides = {};
+        for (const k of keys) {
+          const v = args[k];
+          if (v !== void 0) overrides[k] = v;
+        }
+        if (Object.keys(overrides).length === 0) {
+          return fail2("No settings provided to save. Pass at least one field (e.g. perCaseDurationMs).");
+        }
+        const next = { ...current, ...overrides };
+        const saved = await sync.callAction(PERF_TOOL_ID, "setAutomationConfig", { config: next }, target);
+        const settings = await readDeviceSettings(sync, target);
+        const { config } = buildAutomationConfig(
+          { targetRoute: "/_preview", cases: [{ name: "page 1" }] },
+          settings
+        );
+        return text(
+          `Saved. **New benchmark settings:** ${describeBenchmarkSettings(config)}
+
+\`\`\`json
+${JSON.stringify(saved ?? settings, null, 2)}
+\`\`\``
+        );
+      } catch (e) {
+        return fail2(errMsg2(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/events.ts
+import { z as z3 } from "zod";
+var EVENTS_TOOL_ID = "events";
+var text2 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail3 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg3 = (e) => e instanceof Error ? e.message : String(e);
+var SOURCE_ALIASES = {
+  storage: ["storage-async", "storage-mmkv"],
+  "react-query": ["react-query", "react-query-query", "react-query-mutation"]
+};
+function expandSources(sources) {
+  if (!sources || sources.length === 0) return void 0;
+  return [...new Set(sources.flatMap((s) => SOURCE_ALIASES[s] ?? [s]))];
+}
+function registerEventsTools(server, sync) {
+  server.registerTool(
+    "get_events",
+    {
+      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
+      inputSchema: {
+        limit: z3.number().optional().describe("Most-recent N events to include. Default 25."),
+        sources: z3.array(z3.string()).optional().describe('Only these sources. Coarse names accepted: "network", "redux", "react-query", "storage", "route", "render", "zustand", "jotai". Omit for all.'),
+        status: z3.enum(["all", "errors", "success", "pending"]).optional().describe("Filter by status. Default all."),
+        includeData: z3.boolean().optional().describe("Include each event's full raw payload (HEAVY \u2014 network bodies, state trees). Default false (compact)."),
+        format: z3.enum(["markdown", "json", "text", "mermaid"]).optional().describe("Output format. Default markdown."),
+        preset: z3.enum(["llm", "bugReport", "json", "errors", "minimal", "mermaid"]).optional().describe("Start from a named Copy-Settings preset (then your other args override it)."),
+        deviceId: z3.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const settings = {};
+        const sources = expandSources(args.sources);
+        if (sources) settings.filterSources = sources;
+        if (args.status) settings.filterMode = args.status;
+        if (args.includeData !== void 0) settings.includeEventData = args.includeData;
+        if (args.format) settings.format = args.format === "text" ? "plaintext" : args.format;
+        const res = await sync.callAction(
+          EVENTS_TOOL_ID,
+          "exportEvents",
+          { preset: args.preset, settings, limit: args.limit ?? 25 },
+          target
+        );
+        if (!res || typeof res.output !== "string") {
+          return fail3(
+            "No events result from the device. The events tool may be inactive, or the app needs a newer Buoy (get_events requires the exportEvents action)."
+          );
+        }
+        const more = res.includedData ? "" : " \u2014 compact view; pass includeData:true, a specific source, or a bigger limit for full payloads";
+        const note = `
+
+_Showing ${res.returned} of ${res.totalAvailable} captured event(s)${more}._`;
+        return text2((res.output || "(no events captured)") + note);
+      } catch (e) {
+        return fail3(errMsg3(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/reactQuery.ts
+import { z as z4 } from "zod";
+var RQ_TOOL_ID = "react-query";
+var text3 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail4 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg4 = (e) => e instanceof Error ? e.message : String(e);
+var STATUS_ICON = {
+  fresh: "\u{1F7E2}",
+  stale: "\u{1F7E1}",
+  fetching: "\u{1F504}",
+  error: "\u{1F534}",
+  inactive: "\u26AA\uFE0F",
+  paused: "\u23F8\uFE0F",
+  disabled: "\u{1F6AB}"
+};
+function relTime(ts) {
+  if (!ts) return "\u2014";
+  const s = Math.round((Date.now() - ts) / 1e3);
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.round(s / 60)}m ago`;
+  if (s < 86400) return `${Math.round(s / 3600)}h ago`;
+  return `${Math.round(s / 86400)}d ago`;
+}
+function registerReactQueryTools(server, sync) {
+  server.registerTool(
+    "get_react_query",
+    {
+      description: "Read the app's CURRENT React Query cache \u2014 every query with its status (fresh/stale/fetching/error), staleness, observer count, last-updated time, and any error. Compact by DEFAULT (no cached payloads) so it's token-cheap; pass includeData:true for the actual cached data, or staleOnly:true to see just stale queries. Use this for 'what's in the cache / why is this stale / which queries errored'. (For the history of query updates over time, use get_events with sources:['react-query'].) Each row's hash is what you pass to react_query_action.",
+      inputSchema: {
+        includeData: z4.boolean().optional().describe("Include each query's full cached data payload (HEAVY). Default false."),
+        staleOnly: z4.boolean().optional().describe("Only stale queries. Default false."),
+        limit: z4.number().optional().describe("Most-recently-updated N queries. Default 25."),
+        deviceId: z4.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          RQ_TOOL_ID,
+          "listQueries",
+          { includeData: args.includeData ?? false, staleOnly: args.staleOnly ?? false, limit: args.limit ?? 25 },
+          target
+        );
+        if (!res || !Array.isArray(res.queries)) {
+          return fail4(
+            "No react-query result from the device. The react-query tool may be inactive, or the app needs a newer Buoy (get_react_query requires the listQueries action)."
+          );
+        }
+        if (res.queries.length === 0) {
+          return text3(`React Query cache is empty (0 of ${res.total} queries${args.staleOnly ? " match staleOnly" : ""}).`);
+        }
+        const lines = res.queries.map((q, i) => {
+          const icon = STATUS_ICON[q.status] ?? "\u2022";
+          const base = `${i + 1}. ${icon} ${q.status} \xB7 \`${q.queryHash}\` \xB7 ${q.observers} obs \xB7 ${relTime(q.updatedAt)}`;
+          const errSuffix = q.error ? ` \u2014 \u26A0\uFE0F ${q.error}` : "";
+          const dataSuffix = res.includedData ? `
+   data: ${JSON.stringify(q.data)}` : "";
+          return base + errSuffix + dataSuffix;
+        });
+        const staleCount = res.queries.filter((q) => q.isStale).length;
+        const header = `**React Query cache \u2014 ${res.total} queries (showing ${res.returned}, ${staleCount} stale):**`;
+        const note = res.includedData ? "" : "\n\n_Compact view. Pass includeData:true for cached payloads, staleOnly:true to narrow. Act on one with react_query_action using the `hash` in backticks._";
+        return text3(`${header}
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail4(errMsg4(e));
+      }
+    }
+  );
+  server.registerTool(
+    "react_query_action",
+    {
+      description: "Mutate the app's React Query cache: invalidate / refetch / reset / remove a single query (by queryHash, from get_react_query), or clear the entire query cache. Use this to fix stale data, force a refetch, or reset state during debugging.",
+      inputSchema: {
+        action: z4.enum(["invalidate", "refetch", "reset", "remove", "clear"]).describe("invalidate/refetch/reset/remove a single query (needs queryHash); clear empties the whole query cache."),
+        queryHash: z4.string().optional().describe("The target query's hash (from get_react_query, shown in backticks). Required for all actions except clear."),
+        deviceId: z4.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        if (args.action === "clear") {
+          await sync.callAction(RQ_TOOL_ID, "clearQueryCache", {}, target);
+          return text3("Cleared the entire React Query cache.");
+        }
+        if (!args.queryHash) {
+          return fail4(`'${args.action}' needs a queryHash. Call get_react_query first and use a row's hash (in backticks).`);
+        }
+        await sync.callAction(RQ_TOOL_ID, args.action, { queryHash: args.queryHash }, target);
+        return text3(`Ran ${args.action} on query \`${args.queryHash}\`.`);
+      } catch (e) {
+        return fail4(errMsg4(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/zustand.ts
+import { z as z5 } from "zod";
+var ZUSTAND_TOOL_ID = "zustand";
+var text4 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail5 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg5 = (e) => e instanceof Error ? e.message : String(e);
+function registerZustandTools(server, sync) {
+  server.registerTool(
+    "get_zustand_state",
+    {
+      description: "Read the app's CURRENT Zustand store state \u2014 each registered store with its name, change count, persistence, and (by default) just its top-level keys so it's token-cheap. Pass includeValues:true for the full state objects. Use this for 'what's in my zustand stores / what's the current count'. (For the history of state changes over time, use get_events with sources:['zustand'].)",
+      inputSchema: {
+        includeValues: z5.boolean().optional().describe("Include each store's full current state object (HEAVY). Default false (keys only)."),
+        limit: z5.number().optional().describe("First N stores. Default all."),
+        deviceId: z5.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          ZUSTAND_TOOL_ID,
+          "listStores",
+          { includeValues: args.includeValues ?? false, limit: args.limit },
+          target
+        );
+        if (!res || !Array.isArray(res.stores)) {
+          return fail5(
+            "No zustand result from the device. The zustand tool may be inactive, or the app needs a newer Buoy (get_zustand_state requires the listStores action)."
+          );
+        }
+        if (res.stores.length === 0) {
+          return text4("No Zustand stores are registered (call watchStores to register them).");
+        }
+        const lines = res.stores.map((s, i) => {
+          const persist = s.isPersisted ? ` \xB7 persisted${s.persistName ? ` (${s.persistName})` : ""}` : "";
+          const body = res.includedValues ? `
+   ${JSON.stringify(s.currentState)}` : ` \xB7 keys: ${(s.keys ?? []).join(", ") || "\u2014"}`;
+          return `${i + 1}. **${s.name}** \xB7 ${s.changes} changes${persist}${body}`;
+        });
+        const note = res.includedValues ? "" : "\n\n_Compact view (keys only). Pass includeValues:true for full state. Mutate with zustand_action({store, state})._";
+        return text4(`**Zustand stores \u2014 ${res.total} (showing ${res.returned}):**
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail5(errMsg5(e));
+      }
+    }
+  );
+  server.registerTool(
+    "zustand_action",
+    {
+      description: "Set the state of a Zustand store (time-travel / reset / tweak during debugging). Targets a store by name (from get_zustand_state). By default replaces the whole state; pass replace:false to merge a partial.",
+      inputSchema: {
+        store: z5.string().describe("Store name to target (from get_zustand_state)."),
+        state: z5.record(z5.string(), z5.unknown()).describe("The new state object."),
+        replace: z5.boolean().optional().describe("Replace the whole state (default true) or merge a partial (false)."),
+        deviceId: z5.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(
+          ZUSTAND_TOOL_ID,
+          "setState",
+          { storeName: args.store, state: args.state, replace: args.replace ?? true },
+          target
+        );
+        return text4(`Set state on Zustand store "${args.store}" (${args.replace === false ? "merged" : "replaced"}).`);
+      } catch (e) {
+        return fail5(errMsg5(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/jotai.ts
+import { z as z6 } from "zod";
+var JOTAI_TOOL_ID = "jotai";
+var text5 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail6 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg6 = (e) => e instanceof Error ? e.message : String(e);
+function registerJotaiTools(server, sync) {
+  server.registerTool(
+    "get_jotai_state",
+    {
+      description: "Read the app's CURRENT Jotai atom values \u2014 each watched atom with its label, change count, and whether it's writable. Compact by DEFAULT (no values) so it's token-cheap; pass includeValues:true for the actual current values. Use this for 'what are my jotai atoms / what's the current value'. (For the history of atom changes over time, use get_events with sources:['jotai'].)",
+      inputSchema: {
+        includeValues: z6.boolean().optional().describe("Include each atom's current value (HEAVY). Default false."),
+        limit: z6.number().optional().describe("First N atoms. Default all."),
+        deviceId: z6.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          JOTAI_TOOL_ID,
+          "listAtoms",
+          { includeValues: args.includeValues ?? false, limit: args.limit },
+          target
+        );
+        if (!res || !Array.isArray(res.atoms)) {
+          return fail6(
+            "No jotai result from the device. The jotai tool may be inactive, or the app needs a newer Buoy (get_jotai_state requires the listAtoms action)."
+          );
+        }
+        if (res.atoms.length === 0) {
+          return text5("No Jotai atoms are being watched (call watchAtoms to register them).");
+        }
+        const lines = res.atoms.map((a, i) => {
+          const kind = a.writable ? "writable" : "read-only";
+          const value = res.includedValues ? `
+   ${JSON.stringify(a.currentValue)}` : "";
+          return `${i + 1}. **${a.label}** \xB7 ${a.changes} changes \xB7 ${kind}${value}`;
+        });
+        const note = res.includedValues ? "" : "\n\n_Compact view. Pass includeValues:true for current values. Set a writable atom with jotai_action({atom, value})._";
+        return text5(`**Jotai atoms \u2014 ${res.total} (showing ${res.returned}):**
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail6(errMsg6(e));
+      }
+    }
+  );
+  server.registerTool(
+    "jotai_action",
+    {
+      description: "Set the value of a writable Jotai atom (by label, from get_jotai_state). Read-only/derived atoms cannot be set (you'll get a clear error). Use for tweaking state during debugging.",
+      inputSchema: {
+        atom: z6.string().describe("Atom label to set (from get_jotai_state; must be writable)."),
+        value: z6.unknown().describe("The new value (any JSON \u2014 number, string, object, etc.)."),
+        deviceId: z6.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(JOTAI_TOOL_ID, "setAtom", { label: args.atom, value: args.value }, target);
+        return text5(`Set Jotai atom "${args.atom}" to ${JSON.stringify(args.value)}.`);
+      } catch (e) {
+        return fail6(errMsg6(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/redux.ts
+import { z as z7 } from "zod";
+var REDUX_TOOL_ID = "redux";
+var text6 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail7 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg7 = (e) => e instanceof Error ? e.message : String(e);
+var NO_STORE = "No instrumented Redux store found. Open the app with Buoy redux devtools active (auto-instrumentation), then retry.";
+function registerReduxTools(server, sync) {
+  server.registerTool(
+    "get_redux_state",
+    {
+      description: "Read the app's CURRENT Redux state. Compact by DEFAULT \u2014 just the top-level slice names \u2014 so it's token-cheap; pass includeValues:true for the full state tree. Use this for 'what's in my redux store / current auth state'. (For the history of dispatched actions over time, use get_events with sources:['redux'].)",
+      inputSchema: {
+        includeValues: z7.boolean().optional().describe("Include the full current state tree (HEAVY). Default false (slice names only)."),
+        deviceId: z7.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          REDUX_TOOL_ID,
+          "getState",
+          { includeValues: args.includeValues ?? false },
+          target
+        );
+        if (!res) {
+          return fail7(
+            "No redux result from the device. The redux tool may be inactive, or the app needs a newer Buoy (get_redux_state requires the getState action)."
+          );
+        }
+        if (!res.available) return text6(NO_STORE);
+        const slices = res.slices.length ? res.slices.join(", ") : "(none)";
+        if (args.includeValues) {
+          return text6(`**Redux store \u2014 slices: ${slices}**
+
+\`\`\`json
+${JSON.stringify(res.state, null, 2)}
+\`\`\``);
+        }
+        return text6(
+          `**Redux store \u2014 slices: ${slices}**
+
+_Compact view. Pass includeValues:true for the full state tree. Dispatch with redux_dispatch({type, payload})._`
+        );
+      } catch (e) {
+        return fail7(errMsg7(e));
+      }
+    }
+  );
+  server.registerTool(
+    "redux_dispatch",
+    {
+      description: "Dispatch a Redux action to the app's store (e.g. to trigger a state change while debugging). Provide the action type and optional payload \u2014 they're sent as { type, payload }.",
+      inputSchema: {
+        type: z7.string().describe('The action type, e.g. "counter/increment" or "auth/logout".'),
+        payload: z7.unknown().optional().describe("Optional action payload (any JSON)."),
+        deviceId: z7.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const action = { type: args.type };
+        if (args.payload !== void 0) action.payload = args.payload;
+        const res = await sync.callAction(REDUX_TOOL_ID, "dispatch", { action }, target);
+        if (!res || !res.dispatched) return fail7(NO_STORE);
+        return text6(`Dispatched \`${args.type}\`${args.payload !== void 0 ? ` with payload ${JSON.stringify(args.payload)}` : ""}.`);
+      } catch (e) {
+        return fail7(errMsg7(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/storage.ts
+import { z as z8 } from "zod";
+var STORAGE_TOOL_ID = "storage";
+var text7 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail8 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg8 = (e) => e instanceof Error ? e.message : String(e);
+function truncate(v, n = 200) {
+  if (v === null || v === void 0) return "(null)";
+  const s = typeof v === "string" ? v : JSON.stringify(v);
+  return s.length > n ? `${s.slice(0, n)}\u2026(+${s.length - n} chars)` : s;
+}
+function registerStorageTools(server, sync) {
+  server.registerTool(
+    "get_storage",
+    {
+      description: "Read the app's AsyncStorage keys. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out. Use for 'what's in storage / read this key'.",
+      inputSchema: {
+        pattern: z8.string().optional().describe("Only keys containing this substring (case-insensitive)."),
+        includeValues: z8.boolean().optional().describe("Include each key's value (truncated). Default false (keys only)."),
+        limit: z8.number().optional().describe("Max keys to return. Default 100."),
+        deviceId: z8.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const allKeys = await sync.callAction(STORAGE_TOOL_ID, "async.getAllKeys", {}, target);
+        if (!Array.isArray(allKeys)) {
+          return fail8("No storage result from the device. The storage tool may be inactive.");
+        }
+        const pattern = args.pattern?.toLowerCase();
+        const matched = pattern ? allKeys.filter((k) => k.toLowerCase().includes(pattern)) : allKeys;
+        const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : 100;
+        const keys = matched.slice(0, limit);
+        if (keys.length === 0) {
+          return text7(`No storage keys${pattern ? ` matching "${args.pattern}"` : ""} (${allKeys.length} total).`);
+        }
+        let lines;
+        if (args.includeValues) {
+          const pairs = await sync.callAction(STORAGE_TOOL_ID, "async.multiGet", { keys }, target);
+          const map = new Map((pairs ?? []).map(([k, v]) => [k, v]));
+          lines = keys.map((k) => `- \`${k}\` = ${truncate(map.get(k) ?? null)}`);
+        } else {
+          lines = keys.map((k) => `- \`${k}\``);
+        }
+        const filteredNote = pattern ? ` matching "${args.pattern}"` : "";
+        const header = `**Storage \u2014 ${allKeys.length} keys (showing ${keys.length}${filteredNote}):**`;
+        const note = args.includeValues ? "" : "\n\n_Keys only. Pass includeValues:true for values, or a pattern to filter. Modify with storage_action._";
+        return text7(`${header}
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail8(errMsg8(e));
+      }
+    }
+  );
+  server.registerTool(
+    "storage_action",
+    {
+      description: "Modify the app's AsyncStorage: set a key, remove a key, or clear all app storage (Buoy's own devtool keys are preserved). Values are stored as strings \u2014 JSON-encode objects yourself.",
+      inputSchema: {
+        action: z8.enum(["set", "remove", "clear"]).describe("set/remove a key, or clear all app storage."),
+        key: z8.string().optional().describe("The key (required for set and remove)."),
+        value: z8.string().optional().describe("The string value to store (required for set; JSON-encode objects)."),
+        deviceId: z8.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        if (args.action === "clear") {
+          await sync.callAction(STORAGE_TOOL_ID, "clearAppStorage", {}, target);
+          return text7("Cleared all app storage (Buoy's own devtool keys preserved).");
+        }
+        if (!args.key) {
+          return fail8(`'${args.action}' needs a key.`);
+        }
+        if (args.action === "remove") {
+          await sync.callAction(STORAGE_TOOL_ID, "async.removeItem", { key: args.key }, target);
+          return text7(`Removed storage key "${args.key}".`);
+        }
+        if (args.value === void 0) {
+          return fail8("'set' needs a value (a string).");
+        }
+        await sync.callAction(STORAGE_TOOL_ID, "async.setItem", { key: args.key, value: args.value }, target);
+        return text7(`Set storage key "${args.key}".`);
+      } catch (e) {
+        return fail8(errMsg8(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/routes.ts
+import { z as z9 } from "zod";
+var ROUTES_TOOL_ID = "route-events";
+var text8 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail9 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg9 = (e) => e instanceof Error ? e.message : String(e);
+function flattenRoutes(routes, acc = []) {
+  for (const r of routes ?? []) {
+    if (r.path) acc.push(r.path);
+    if (r.children?.length) flattenRoutes(r.children, acc);
+  }
+  return acc;
+}
+function registerRoutesTools(server, sync) {
+  server.registerTool(
+    "get_routes",
+    {
+      description: "Read the app's CURRENT route + navigation stack (where the user is and how they got there). Compact by DEFAULT; pass includeSitemap:true to also list every route path the app defines (useful before navigate). Use for 'what screen am I on / what's the nav stack / what routes exist'. (For navigation history over time, use get_events with sources:['route'].)",
+      inputSchema: {
+        includeSitemap: z9.boolean().optional().describe("Also list all defined route paths (can be long). Default false."),
+        deviceId: z9.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const { payload } = await sync.getSnapshot(ROUTES_TOOL_ID, target);
+        const p = Array.isArray(payload) ? { events: payload } : payload ?? {};
+        const stack = Array.isArray(p.stack) ? p.stack : [];
+        const focused = stack.find((s) => s.isFocused) ?? stack[stack.length - 1];
+        const current = focused?.pathname ?? "(unknown)";
+        const parts = [`**Current route:** \`${current}\``];
+        if (stack.length) {
+          const stackLines = stack.map(
+            (s, i) => `${i + 1}. \`${s.pathname ?? s.name ?? "?"}\`${s.isFocused ? " \u2190 focused" : ""}`
+          );
+          parts.push(`
+**Navigation stack** (top last):
+${stackLines.join("\n")}`);
+        }
+        const allPaths = flattenRoutes(p.sitemap?.routes);
+        if (args.includeSitemap) {
+          const shown = allPaths.slice(0, 200);
+          parts.push(
+            `
+**Sitemap (${allPaths.length} routes${shown.length < allPaths.length ? `, showing ${shown.length}` : ""}):**
+${shown.map((r) => `- \`${r}\``).join("\n")}`
+          );
+        } else {
+          parts.push(`
+**Sitemap:** ${allPaths.length} routes _(pass includeSitemap:true to list them)_`);
+        }
+        parts.push("\n_Navigate with navigate({ path })._");
+        return text8(parts.join("\n"));
+      } catch (e) {
+        return fail9(errMsg9(e));
+      }
+    }
+  );
+  server.registerTool(
+    "navigate",
+    {
+      description: "Navigate the app to a route path (e.g. '/pokemon/25' or '/settings'). Use a concrete path \u2014 resolve any dynamic segments (like [id]) to real values first. See get_routes with includeSitemap:true for valid paths.",
+      inputSchema: {
+        path: z9.string().describe("The concrete path to navigate to, e.g. '/pokemon/25'."),
+        deviceId: z9.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(ROUTES_TOOL_ID, "navigate", { path: args.path }, target);
+        return text8(`Navigated to \`${args.path}\`.`);
+      } catch (e) {
+        return fail9(errMsg9(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/console.ts
+import { z as z10 } from "zod";
+var CONSOLE_TOOL_ID = "console";
+var text9 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail10 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg10 = (e) => e instanceof Error ? e.message : String(e);
+var SEVERITY = { verbose: 0, info: 1, warning: 2, error: 3 };
+var TAG = { verbose: "\xB7", info: "info", warning: "warn", error: "ERR" };
+function hhmmss(ts) {
+  const d = new Date(ts);
+  const p = (n, l = 2) => String(n).padStart(l, "0");
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+}
+function registerConsoleTools(server, sync) {
+  server.registerTool(
+    "get_console",
+    {
+      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. Use for 'what's logging / any console errors'. For full args/stack of an entry, fall back to get_snapshot('console').",
+      inputSchema: {
+        level: z10.enum(["verbose", "info", "warning", "error"]).optional().describe("Minimum level to include (severity threshold). e.g. 'warning' = warnings + errors. Default all."),
+        limit: z10.number().optional().describe("Most-recent N entries. Default 50."),
+        pattern: z10.string().optional().describe("Only entries whose message contains this substring (case-insensitive)."),
+        deviceId: z10.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const { payload } = await sync.getSnapshot(CONSOLE_TOOL_ID, target);
+        const p = Array.isArray(payload) ? { entries: payload } : payload ?? {};
+        const all = Array.isArray(p.entries) ? p.entries : [];
+        const minSev = args.level ? SEVERITY[args.level] : 0;
+        const pattern = args.pattern?.toLowerCase();
+        const filtered = all.filter(
+          (e) => SEVERITY[e.level] >= minSev && (!pattern || (e.message ?? "").toLowerCase().includes(pattern))
+        );
+        const sorted = [...filtered].sort((a, b) => a.id - b.id);
+        const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : 50;
+        const shown = sorted.slice(-limit);
+        if (shown.length === 0) {
+          return text9(`No console entries${args.level ? ` at level \u2265 ${args.level}` : ""}${pattern ? ` matching "${args.pattern}"` : ""} (${all.length} total captured).`);
+        }
+        const lines = shown.map((e) => `${hhmmss(e.timestamp)} [${TAG[e.level] ?? e.level}] ${e.message}`);
+        const levelNote = args.level ? `, level \u2265 ${args.level}` : "";
+        const header = `**Console \u2014 ${all.length} entries (showing ${shown.length}${levelNote}):**`;
+        return text9(`${header}
+
+\`\`\`
+${lines.join("\n")}
+\`\`\`
+
+_Tail of recent logs. Use get_snapshot('console') for full args/stacks._`);
+      } catch (e) {
+        return fail10(errMsg10(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/screenshot.ts
+import { z as z11 } from "zod";
+
+// src/capture/simctl.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { promises as fs2 } from "fs";
+import os2 from "os";
+import path2 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+var execFileAsync = promisify(execFile);
+var clamp2 = (n, lo, hi) => Math.min(Math.max(n, lo), hi);
+function humanizeSimctlError(err) {
+  const e = err;
+  if (e?.code === "ENOENT") {
+    return "Xcode command-line tools (xcrun) not found. Install Xcode to capture the iOS Simulator.";
+  }
+  const msg = String(e?.stderr || e?.message || err);
+  if (/No devices are booted|Unable to find device|current device/i.test(msg)) {
+    return "No booted iOS Simulator found. Boot the Simulator with your app running, then try again.";
+  }
+  return msg.trim() || "Failed to capture the iOS Simulator.";
+}
+function pngSize(buf) {
+  const SIG = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (buf.length < 24 || !SIG.every((b, i) => buf[i] === b)) return null;
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+async function captureIosFramebuffer() {
+  if (process.platform !== "darwin") {
+    return {
+      ok: false,
+      error: "Screenshotting a component requires macOS with Xcode's iOS Simulator (uses `xcrun simctl`)."
+    };
+  }
+  const out = path2.join(os2.tmpdir(), `buoy-mcp-sim-${randomUUID2()}.png`);
+  try {
+    await execFileAsync("xcrun", ["simctl", "io", "booted", "screenshot", "--type=png", out], {
+      timeout: 15e3
+    });
+  } catch (err) {
+    return { ok: false, error: humanizeSimctlError(err) };
+  }
+  try {
+    const buf = await fs2.readFile(out);
+    const size = pngSize(buf);
+    if (!size) return { ok: false, error: "Captured file wasn't a valid PNG." };
+    return { ok: true, srcPath: out, width: size.width, height: size.height };
+  } catch (err) {
+    return { ok: false, error: `Failed to read screenshot: ${err.message}` };
+  }
+}
+async function cropToBuffer(srcPath, full, region) {
+  const x = clamp2(Math.round(region.x), 0, Math.max(0, full.width - 1));
+  const y = clamp2(Math.round(region.y), 0, Math.max(0, full.height - 1));
+  const width = clamp2(Math.round(region.width), 1, full.width - x);
+  const height = clamp2(Math.round(region.height), 1, full.height - y);
+  const out = path2.join(os2.tmpdir(), `buoy-mcp-crop-${randomUUID2()}.png`);
+  try {
+    await execFileAsync(
+      "sips",
+      ["-c", String(height), String(width), "--cropOffset", String(y), String(x), srcPath, "--out", out],
+      { timeout: 1e4 }
+    );
+    const buf = await fs2.readFile(out);
+    return { ok: true, buffer: buf, width, height };
+  } catch (err) {
+    const e = err;
+    return { ok: false, error: `Crop failed: ${e?.stderr || e?.message || err}` };
+  } finally {
+    await fs2.unlink(out).catch(() => {
+    });
+    await fs2.unlink(srcPath).catch(() => {
+    });
+  }
+}
+
+// src/tools/packs/screenshot.ts
+var TOOL_ID = "highlight-updates";
+var MARGIN_PT = 12;
+var CAPTURE_PADDING_PT = 6;
+var fail11 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg11 = (e) => e instanceof Error ? e.message : String(e);
+function reasonMessage(res, query) {
+  switch (res.reason) {
+    case "no-renders":
+      return "No components are tracked yet. Navigate to the screen with the target component in the running app (it needs to render at least once), then retry.";
+    case "no-match":
+      return query ? `Nothing matched "${query}".` : "No query or nativeTag given \u2014 pass one, or a testID/name to search for.";
+    case "no-measurement":
+      return "Found the component but couldn't measure it \u2014 it may have just unmounted. Re-navigate to it and retry.";
+    default:
+      return res.reason ? `Locate failed: ${res.reason}` : "Couldn't locate that component.";
+  }
+}
+function candidatesText(candidates) {
+  if (!candidates || candidates.length === 0) return "";
+  const lines = candidates.map((c) => {
+    const id = c.testID || c.nativeID;
+    return `- ${c.componentName || c.viewType}${id ? ` (${id})` : ""} \u2014 nativeTag ${c.nativeTag}, rendered \xD7${c.renderCount}`;
+  });
+  return `
+
+Closest matches (retry with a more precise query, or pass nativeTag directly):
+${lines.join("\n")}`;
+}
+function registerScreenshotTools(server, sync) {
+  server.registerTool(
+    "screenshot_component",
+    {
+      description: "Take a tight, cropped screenshot of a single React Native component running in the iOS Simulator \u2014 no manual coordinates needed. Give a testID, nativeID, accessibilityLabel, or component name in `query` (or an exact `nativeTag` from a previous call's candidates) and it locates the live component on-device (scrolling it into view), then captures + crops the Simulator framebuffer to just that component. The component must have rendered at least once since the app opened for it to be trackable \u2014 if nothing matches, navigate to the screen that renders it and retry. iOS Simulator only, and the MCP server must be running on the same Mac as the booted Simulator (uses `xcrun simctl` + `sips`). Requires Buoy Pro.",
+      inputSchema: {
+        query: z11.string().optional().describe('Fuzzy match against testID, nativeID, accessibilityLabel, component name, or view type \u2014 e.g. "submit-button".'),
+        nativeTag: z11.number().optional().describe("An exact nativeTag (from a previous call's candidates) to skip fuzzy matching."),
+        scrollIntoView: z11.boolean().optional().describe("Scroll the component into view before capturing, if it's off-screen. Default true."),
+        deviceId: z11.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(TOOL_ID, "setSilentTracking", { enabled: true }, target).catch(() => {
+        });
+        const res = await sync.callAction(
+          TOOL_ID,
+          "locateComponent",
+          {
+            query: args.query,
+            nativeTag: args.nativeTag,
+            scrollIntoView: args.scrollIntoView ?? true,
+            margin: MARGIN_PT
+          },
+          target
+        );
+        if (!res.matched || !res.rect || !res.screen) {
+          return fail11(reasonMessage(res, args.query) + candidatesText(res.candidates));
+        }
+        const shot = await captureIosFramebuffer();
+        if (!shot.ok || !shot.srcPath || !shot.width || !shot.height) {
+          return fail11(shot.error ?? "Screenshot capture failed.");
+        }
+        const pxScale = shot.width / res.screen.width;
+        const r = res.rect;
+        const pad = CAPTURE_PADDING_PT;
+        const crop = await cropToBuffer(
+          shot.srcPath,
+          { width: shot.width, height: shot.height },
+          {
+            x: (r.x - pad) * pxScale,
+            y: (r.y - pad) * pxScale,
+            width: (r.width + pad * 2) * pxScale,
+            height: (r.height + pad * 2) * pxScale
+          }
+        );
+        if (!crop.ok || !crop.buffer) {
+          return fail11(crop.error ?? "Crop failed.");
+        }
+        const label = res.componentName || "component";
+        const idPart = res.testID ? ` (testID: "${res.testID}")` : "";
+        const warn = res.inView === false ? "\n\nNote: the component is partly off-screen even after scrolling, so the crop is clamped to the screen edge." : "";
+        const summary = `Captured "${label}"${idPart} \u2014 ${crop.width}\xD7${crop.height}px.${warn}`;
+        return {
+          content: [
+            { type: "image", data: crop.buffer.toString("base64"), mimeType: "image/png" },
+            { type: "text", text: summary }
+          ]
+        };
+      } catch (e) {
+        return fail11(errMsg11(e));
+      }
+    }
+  );
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z13 } from "zod";
+
+// src/tools/packs/interact.ts
+import { z as z12 } from "zod";
+var TOOL_ID2 = "highlight-updates";
+var text10 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail12 = (message) => ({
+  isError: true,
+  content: [{ type: "text", text: message }]
+});
+var errMsg12 = (e) => e instanceof Error ? e.message : String(e);
+function formatElement(e) {
+  let line = e.interactive ? "\u2022 " : "  ";
+  line += e.name;
+  const display = e.text ?? e.label;
+  if (display) line += ` "${display}"`;
+  if (e.role) line += ` <${e.role}>`;
+  if (e.control) line += ` {${e.control}${e.value !== void 0 ? `=${JSON.stringify(e.value)}` : ""}}`;
+  if (e.testID) line += ` [testID=${e.testID}]`;
+  if (e.tap) line += ` (tap: ${e.tap.x},${e.tap.y})`;
+  if (e.nativeTag != null) line += ` #${e.nativeTag}`;
+  return line;
+}
+function registerInteractTools(server, sync) {
+  server.registerTool(
+    "describe_screen",
+    {
+      description: "List the interactive / labeled elements currently on screen \u2014 the app's live accessibility-style tree walked from the React fiber tree. Each row shows the component name, visible text/label, role, testID, a normalized tap point (tap: x,y in 0\u20131), and its #nativeTag. Rows marked with \u2022 are tappable (have an onPress). Use this to see what's on screen and pick something to tap with tap_element \u2014 no screenshot needed. Re-run after navigating or when the screen changes, since positions move. Requires Buoy Pro.",
+      inputSchema: {
+        interactiveOnly: z12.boolean().optional().describe("Only return tappable (onPress) elements. Default false (include labels/text for context)."),
+        deviceId: z12.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(TOOL_ID2, "describeScreen", {}, target);
+        const all = res?.elements ?? [];
+        const elements = args.interactiveOnly ? all.filter((e) => e.interactive) : all;
+        if (elements.length === 0) {
+          return text10(
+            "No elements found on screen. If the app just navigated, wait a moment and retry; make sure highlight-updates is enabled in the app."
+          );
+        }
+        const header = `Screen ${res.screen.width}\xD7${res.screen.height} \u2014 ${elements.length} element${elements.length === 1 ? "" : "s"} (\u2022 = tappable). Tap with tap_element({ testID | query | nativeTag }).`;
+        return text10(`${header}
+
+${elements.map(formatElement).join("\n")}`);
+      } catch (e) {
+        return fail12(errMsg12(e));
+      }
+    }
+  );
+  server.registerTool(
+    "tap_element",
+    {
+      description: "Interact with an on-screen element by invoking its handler directly in JS (no screenshot, no coordinate math, works on real devices). Handles buttons (onPress), toggles/switches and sliders (onValueChange), and text inputs (onChangeText) \u2014 see each element's `control` in describe_screen. Identify the target with an exact `nativeTag` or `testID`, or a fuzzy `query`. For a toggle, pass `value:true/false` (omit to flip); for a slider, pass a numeric `value` (omit to jump to the far end); for a text input, pass `text`. If the element is off-screen it's scrolled into view first (scrollIntoView:false to skip). Call describe_screen first to see options + current values. Requires Buoy Pro.",
+      inputSchema: {
+        nativeTag: z12.number().optional().describe("Exact nativeTag from describe_screen (most precise)."),
+        testID: z12.string().optional().describe("Exact testID of the element."),
+        query: z12.string().optional().describe('Fuzzy match against testID / label / visible text / component name \u2014 e.g. "Sign in".'),
+        value: z12.union([z12.number(), z12.boolean()]).optional().describe("For a toggle: true/false (omit to flip). For a slider: the numeric value (omit to jump to the far end)."),
+        text: z12.string().optional().describe("For a text input: the string to set via onChangeText."),
+        scrollIntoView: z12.boolean().optional().describe("Scroll the target into view first if it's off-screen. Default true."),
+        deviceId: z12.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        if (args.nativeTag == null && !args.testID && !args.query) {
+          return fail12("Provide one of: nativeTag, testID, or query (from describe_screen).");
+        }
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          TOOL_ID2,
+          "tapElement",
+          {
+            nativeTag: args.nativeTag,
+            testID: args.testID,
+            query: args.query,
+            value: args.value,
+            text: args.text,
+            scrollIntoView: args.scrollIntoView
+          },
+          target
+        );
+        if (res?.tapped && res.matched) {
+          const m = res.matched;
+          const label = m.text ?? m.label ?? m.name;
+          const id = m.testID ? ` [testID=${m.testID}]` : m.nativeTag != null ? ` #${m.nativeTag}` : "";
+          const scrolledNote = res.scrolled ? " (scrolled into view)" : "";
+          const verb = m.via === "onValueChange" ? `Set "${label}"${id} \u2192 ${JSON.stringify(m.value)}` : m.via === "onChangeText" ? `Typed ${JSON.stringify(m.value)} into "${label}"${id}` : `Tapped "${label}"${id}${m.via === "onLongPress" ? " (via onLongPress)" : ""}`;
+          return text10(`${verb}${scrolledNote}.`);
+        }
+        let msg = res?.reason ?? "Tap failed.";
+        if (res?.candidates?.length) {
+          msg += "\n\nTappable candidates:\n" + res.candidates.map((c) => `- ${c.name}${c.text ? ` "${c.text}"` : ""}${c.testID ? ` [testID=${c.testID}]` : ""}${c.nativeTag != null ? ` #${c.nativeTag}` : ""}`).join("\n");
+        }
+        return fail12(msg);
+      } catch (e) {
+        return fail12(errMsg12(e));
+      }
+    }
+  );
+}
+
+// src/server.ts
+var SERVER_INSTRUCTIONS = `Buoy MCP \u2014 drive Buoy dev tools running in a React Native app from your editor.
+
+Buoy tools live inside the app and sync to a local broker; this server connects to that
+broker as a dashboard client. Start by calling \`list_devices\` to see which device(s) are
+connected and which tools (e.g. "perf-monitor", "network", "react-query") they expose.
+
+To inspect what's HAPPENING at runtime \u2014 network requests, state changes (redux/zustand/jotai),
+react-query updates, storage writes, route changes, renders \u2014 use \`get_events\` with a \`sources\`
+filter (e.g. sources:["network"] to list HTTP requests). It's the universal, token-bounded
+activity reader across ALL tools and is compact by default \u2014 reach for it before reading source
+code, and prefer it over \`get_snapshot\` for any "what happened / show me the requests" question.
+
+Need to SEE a component (verify a UI change, check styling/layout)? Use \`screenshot_component\` with
+a testID/name \u2014 it locates the live component on-device and returns a cropped screenshot inline.
+iOS Simulator only, and only works when this MCP server runs on the same Mac as the booted Simulator.
+
+Need to DRIVE the UI (tap a button, follow a flow)? Use \`describe_screen\` to list the on-screen
+elements (accessibility-style tree with tap points + testIDs, no screenshot), then \`tap_element\`
+({ testID | query | nativeTag }) to tap one \u2014 it invokes the element's onPress directly in JS, so
+it's fast and works on physical devices too. Re-run \`describe_screen\` after the screen changes.
+
+For everything else:
+- \`list_tool_actions\` to see what a tool can do,
+- \`get_snapshot\` ONLY when you need a tool's full current state (returns raw, heavy payloads),
+- \`call_action\` to invoke any tool action generically.
+
+Higher-level tools (e.g. perf-monitor's \`run_benchmark_batch\`) wrap these for common workflows.
+If no device is connected, open the app with Buoy devtools running and try again.
+
+The Buoy MCP is a Pro feature: \`list_devices\` is always available, but data/action tools
+require the connected app to have an active Buoy Pro license. If they error with "Buoy Pro
+required", tell the user to upgrade to Buoy Pro in the app \u2014 don't try to work around it.`;
+function createMcpServer(sync) {
+  const server = new McpServer(
+    { name: "buoy", version: VERSION },
+    { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
+  );
+  registerGenericTools(server, sync);
+  registerPerfMonitorTools(server, sync);
+  registerEventsTools(server, sync);
+  registerReactQueryTools(server, sync);
+  registerZustandTools(server, sync);
+  registerJotaiTools(server, sync);
+  registerReduxTools(server, sync);
+  registerStorageTools(server, sync);
+  registerRoutesTools(server, sync);
+  registerConsoleTools(server, sync);
+  registerScreenshotTools(server, sync);
+  registerInteractTools(server, sync);
+  return server;
+}
+var deviceIdField = {
+  deviceId: z13.string().optional().describe(
+    'Target device id (from list_devices). Omit to auto-select when exactly one device is connected. Use "All" to broadcast.'
+  )
+};
+
+// src/init.ts
+import fs3 from "fs";
+import path3 from "path";
+function runInit(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const skillSrcDir = opts.skillSrcDir ?? path3.resolve(__dirname, "../skill");
+  const log = opts.log ?? ((m) => process.stdout.write(m + "\n"));
+  const entry = opts.cliPath ? { type: "stdio", command: "node", args: [opts.cliPath] } : { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`] };
+  const done = [];
+  upsertMcpConfig(path3.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
+  if (fs3.existsSync(path3.join(cwd, ".cursor"))) {
+    upsertMcpConfig(path3.join(cwd, ".cursor", "mcp.json"), "mcpServers", entry, cwd, done);
+  }
+  if (fs3.existsSync(path3.join(cwd, ".vscode"))) {
+    upsertMcpConfig(path3.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
+  }
+  installSkills(skillSrcDir, cwd, done);
+  log("Buoy MCP installed:");
+  for (const line of done) log("  \u2022 " + line);
+  log("");
+  log("Next steps:");
+  log("  1. Restart your editor (or reconnect the MCP server) to load `buoy`.");
+  log("  2. Open your app with Buoy devtools running on a device or simulator.");
+  log('  3. Say "buoy optimize" to start a guided performance pass.');
+  if (!opts.cliPath) {
+    log("");
+    log(`This launches the server via \`npx -y ${PACKAGE_NAME}@latest\`, so it stays`);
+    log(`up to date automatically. To force-refresh, re-run \`npx -y ${PACKAGE_NAME}@latest init\`.`);
+  }
+}
+function upsertMcpConfig(file, key, entry, cwd, done) {
+  let json3 = {};
+  if (fs3.existsSync(file)) {
+    try {
+      json3 = JSON.parse(fs3.readFileSync(file, "utf8"));
+    } catch {
+      fs3.copyFileSync(file, file + ".bak");
+      done.push(`existing ${rel(file, cwd)} was invalid JSON \u2014 backed up to ${rel(file, cwd)}.bak`);
+      json3 = {};
+    }
+  } else {
+    fs3.mkdirSync(path3.dirname(file), { recursive: true });
+  }
+  const servers = json3[key] && typeof json3[key] === "object" ? json3[key] : {};
+  const existed = "buoy" in servers;
+  servers.buoy = entry;
+  json3[key] = servers;
+  fs3.writeFileSync(file, JSON.stringify(json3, null, 2) + "\n");
+  done.push(`${existed ? "updated" : "added"} \`buoy\` in ${rel(file, cwd)}`);
+}
+function installSkills(skillSrcDir, cwd, done) {
+  if (!fs3.existsSync(skillSrcDir)) {
+    done.push("\u26A0 no bundled skills found \u2014 skipped");
+    return;
+  }
+  const skills = fs3.readdirSync(skillSrcDir, { withFileTypes: true }).filter((e) => e.isDirectory() && fs3.existsSync(path3.join(skillSrcDir, e.name, "SKILL.md")));
+  if (skills.length === 0) {
+    done.push("\u26A0 no skills with a SKILL.md found \u2014 skipped");
+    return;
+  }
+  for (const skill of skills) {
+    const from = path3.join(skillSrcDir, skill.name);
+    const to = path3.join(cwd, ".claude", "skills", skill.name);
+    copyDir(from, to);
+    done.push(`installed the ${skill.name} skill \u2192 ${rel(path3.join(to, "SKILL.md"), cwd)}`);
+  }
+}
+function copyDir(from, to) {
+  fs3.mkdirSync(to, { recursive: true });
+  for (const entry of fs3.readdirSync(from, { withFileTypes: true })) {
+    const s = path3.join(from, entry.name);
+    const d = path3.join(to, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs3.copyFileSync(s, d);
+  }
+}
+function rel(file, cwd) {
+  const r = path3.relative(cwd, file);
+  return r && !r.startsWith("..") ? r : file;
+}
+
+export {
+  BROKER_PORT,
+  BROKER_URL,
+  DEFAULT_ACTION_TIMEOUT_MS,
+  DEFAULT_SNAPSHOT_TIMEOUT_MS,
+  DASHBOARD_NAME,
+  ALL_DEVICES,
+  SyncClient,
+  VERSION,
+  PACKAGE_NAME,
+  getUpdateNotice,
+  registerGenericTools,
+  buildAutomationConfig,
+  estimateBatchMs,
+  rankBatchFromIndex,
+  formatRankingMarkdown,
+  compareReportStats,
+  registerPerfMonitorTools,
+  registerEventsTools,
+  registerReactQueryTools,
+  registerZustandTools,
+  registerJotaiTools,
+  registerReduxTools,
+  registerStorageTools,
+  registerRoutesTools,
+  registerConsoleTools,
+  registerScreenshotTools,
+  createMcpServer,
+  runInit
+};