@buoy-gg/mcp 7.0.2 → 7.0.4

package/README.md

@@ -18,6 +18,20 @@ One command, non-destructive:
 
 The config it writes launches the server via `npx -y @buoy-gg/mcp@latest`, so every editor restart re-resolves the newest published version — you never get pinned to a stale copy. Restart your editor, open your app with Buoy running, and start with `list_devices`.
 
+### Corporate / private npm registries
+
+If your machine's `.npmrc` points npm at a private registry that isn't reachable (a common setup on work laptops, e.g. off-VPN), `npx @latest` would hang trying to download the package on every editor launch — so `init` probes that registry first and, when it's unreachable, automatically installs a **pinned local copy** (from public npm) and writes a `node <path>` config instead. That takes the network off the startup path entirely.
+
+You can also force it:
+
+```bash
+npx -y @buoy-gg/mcp@latest init --local                 # always install locally, no network on startup
+npx -y @buoy-gg/mcp@latest init --npx                    # always use the auto-updating npx entry
+npx -y @buoy-gg/mcp@latest init --registry <url>         # registry the local install pulls from
+```
+
+To update a local install later, just re-run `init`.
+
 ## What your agent can do
 
 **Read the runtime**

package/dist/{chunk-XIN7JPXX.mjs → chunk-EC6YNLYA.mjs}

@@ -296,7 +296,7 @@ async function waitForBroker(url, attempts = 20) {
 var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/version.ts
-var VERSION = "7.0.2" ? "7.0.2" : "0.0.0-dev";
+var VERSION = "7.0.4" ? "7.0.4" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -2006,7 +2006,7 @@ function registerScreenshotTools(server, sync) {
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 
 // src/tools/packs/interact.ts
 import { z as z12 } from "zod";
@@ -2112,6 +2112,439 @@ ${elements.map(formatElement).join("\n")}`);
   );
 }
 
+// src/tools/packs/jsThread.ts
+import { z as z13 } from "zod";
+var JS_TOP_TOOL_ID = "js-top";
+var text11 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail13 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg13 = (e) => e instanceof Error ? e.message : String(e);
+var SPARK_CHARS = "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+function sparkline(values) {
+  const max = Math.max(1, ...values);
+  return values.map((v) => SPARK_CHARS[Math.min(7, Math.floor(v / max * 7.999))]).join("");
+}
+function formatTopMarkdown(snap, durationMs) {
+  const lines = [];
+  lines.push(`## JS thread top (${(durationMs / 1e3).toFixed(1)}s sample)`);
+  lines.push("");
+  lines.push(`Thread busy: **${snap.busyPct.toFixed(1)}%** of the trailing 5s window.`);
+  if (snap.freezeSummary.count > 0) {
+    lines.push(
+      `Freezes (\u226550ms single-task blocks, last 60s): **${snap.freezeSummary.count}**, worst **${snap.freezeSummary.worstMs}ms** \u2014 during these, taps and JS animations stall.`
+    );
+  }
+  if (!snap.tiers.bridge) {
+    lines.push(
+      "_New Architecture device: touch/React commit work appears as \u201Cunattributed\u201D; timers, rAF and Promise chains are fully attributed._"
+    );
+  }
+  lines.push("");
+  lines.push("| # | task origin | api | 5s ms | % busy | calls | avg ms | max ms | freezes |");
+  lines.push("|---|---|---|---|---|---|---|---|---|");
+  snap.rows.slice(0, 15).forEach((r, i) => {
+    const freezeCell = r.freezes > 0 ? `\u26A0 ${r.freezes} (worst ${r.worstFreezeMs}ms)` : "\u2013";
+    lines.push(
+      `| ${i + 1} | ${r.label} | ${r.api} | ${r.windowMs.toFixed(1)} | ${r.pctOfBusy.toFixed(1)} | ${r.calls} | ${r.avgMs.toFixed(2)} | ${r.maxMs.toFixed(1)} | ${freezeCell} |`
+    );
+  });
+  lines.push("");
+  lines.push(
+    "_Drill into any row with `get_js_thread_origin_detail` using its `key` from the JSON below._"
+  );
+  return lines.join("\n");
+}
+function formatDetailMarkdown(d) {
+  const lines = [];
+  lines.push(`## Origin detail \u2014 ${d.label}`);
+  lines.push("");
+  lines.push(`API: \`${d.api}\` \xB7 key: \`${d.key}\``);
+  lines.push("");
+  lines.push(`Activity last 5s (250ms buckets): \`${sparkline(d.buckets)}\` \u2014 ${d.windowMs.toFixed(1)}ms in window, ${d.pctOfBusy.toFixed(1)}% of busy time.`);
+  lines.push("");
+  lines.push("| runs | scheduled | avg/run | max/run | total | last run | freezes (60s) | worst freeze |");
+  lines.push("|---|---|---|---|---|---|---|---|");
+  lines.push(
+    `| ${d.calls} | ${d.scheduleCount} | ${d.avgMs.toFixed(2)}ms | ${d.maxMs.toFixed(1)}ms | ${d.totalMs.toFixed(1)}ms | ${d.lastSeenAgoMs > 0 ? `${Math.round(d.lastSeenAgoMs / 1e3)}s ago` : "\u2014"} | ${d.freezes} | ${d.worstFreezeMs > 0 ? `${d.worstFreezeMs}ms` : "\u2014"} |`
+  );
+  if (d.caller || d.file) {
+    lines.push("");
+    lines.push(`Scheduled from: **${d.caller ? `${d.caller}()` : "unknown caller"}**${d.file ? ` \u2014 ${d.file}${d.line != null ? `:${d.line}` : ""}` : ""}`);
+    if (d.frames?.length) {
+      lines.push(
+        `Raw frames (Hermes bundle offsets): ${d.frames.map((f) => `${f.file}:${f.line}:${f.col}`).join(" \xB7 ")}`
+      );
+    }
+  } else if (d.api !== "unattributed" && d.api !== "other") {
+    lines.push("");
+    lines.push(
+      d.promoted ? "_Scheduling stack not captured yet \u2014 the next schedule from this site records it._" : "_Not hot enough for stack capture yet (threshold: 25 schedules or 50ms total)._"
+    );
+  }
+  return lines.join("\n");
+}
+function registerJsThreadTools(server, sync) {
+  server.registerTool(
+    "get_js_thread_top",
+    {
+      description: "Task Manager for the React Native JS thread: sample for a few seconds and return a ranked table of which task origins (timers, Promise chains, rAF callbacks, bridge call-ins) consumed JS-thread time \u2014 plus thread busy% and freeze (50ms+ block) attribution. Use when JS FPS is low and you need to know WHAT is eating the thread. To profile one specific interaction, pass clearFirst:true, then drive the UI with tap_element while the sample runs. Drill into a row with get_js_thread_origin_detail. Requires @buoy-gg/js-top on the device.",
+      inputSchema: {
+        deviceId: z13.string().optional().describe("Target device id (auto-selected if one is connected)."),
+        durationMs: z13.number().optional().describe("How long to sample before reading the table. Default 3000, max 30000."),
+        clearFirst: z13.boolean().optional().describe("Reset all stats before sampling, so the result attributes only what happens during this sample.")
+      }
+    },
+    async ({ deviceId, durationMs, clearFirst }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const duration = Math.min(Math.max(durationMs ?? 3e3, 250), 3e4);
+        const snap = await sync.callAction(
+          JS_TOP_TOOL_ID,
+          "sample",
+          { durationMs: duration, clearFirst: clearFirst === true },
+          target
+        );
+        if (!snap) return fail13("Device returned no snapshot \u2014 is @buoy-gg/js-top installed in the app?");
+        const md = formatTopMarkdown(snap, duration);
+        const slim = {
+          busyPct: Math.round(snap.busyPct * 10) / 10,
+          freezeSummary: snap.freezeSummary,
+          tiers: snap.tiers,
+          rows: snap.rows.slice(0, 15).map((r) => ({
+            key: r.key,
+            api: r.api,
+            windowMs: Math.round(r.windowMs * 10) / 10,
+            pctOfBusy: Math.round(r.pctOfBusy * 10) / 10,
+            calls: r.calls,
+            avgMs: Math.round(r.avgMs * 100) / 100,
+            maxMs: Math.round(r.maxMs * 10) / 10,
+            totalMs: Math.round(r.totalMs),
+            freezes: r.freezes,
+            worstFreezeMs: r.worstFreezeMs
+          }))
+        };
+        return text11(`${md}
+
+\`\`\`json
+${JSON.stringify(slim)}
+\`\`\``);
+      } catch (e) {
+        return fail13(errMsg13(e));
+      }
+    }
+  );
+  server.registerTool(
+    "get_js_thread_origin_detail",
+    {
+      description: 'Inspect one js-top task origin in depth: schedules vs runs, avg/max/total exclusive ms, a 5s activity sparkline, freeze attribution, and the captured scheduling site (caller function + stack frames). Pass a row `key` from get_js_thread_top\'s JSON (e.g. "interval|pollFeed" or "unattributed" for the system row).',
+      inputSchema: {
+        deviceId: z13.string().optional().describe("Target device id (auto-selected if one is connected)."),
+        key: z13.string().describe("Origin key from get_js_thread_top's JSON rows.")
+      }
+    },
+    async ({ deviceId, key }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const detail = await sync.callAction(
+          JS_TOP_TOOL_ID,
+          "getOriginDetail",
+          { key },
+          target
+        );
+        if (!detail) {
+          return fail13(
+            `Origin "${key}" is not tracked (cleared, evicted, or never existed). Re-run get_js_thread_top for current keys.`
+          );
+        }
+        const md = formatDetailMarkdown(detail);
+        return text11(`${md}
+
+\`\`\`json
+${JSON.stringify(detail)}
+\`\`\``);
+      } catch (e) {
+        return fail13(errMsg13(e));
+      }
+    }
+  );
+  server.registerTool(
+    "clear_js_thread_stats",
+    {
+      description: "Reset the js-top task table, freeze history, and busy history on the device (fresh measurement window).",
+      inputSchema: {
+        deviceId: z13.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async ({ deviceId }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        await sync.callAction(JS_TOP_TOOL_ID, "clear", {}, target);
+        return text11("Cleared js-top stats.");
+      } catch (e) {
+        return fail13(errMsg13(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/images.ts
+import { z as z14 } from "zod";
+var IMAGES_TOOL_ID = "images";
+var text12 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail14 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg14 = (e) => e instanceof Error ? e.message : String(e);
+function uriTail(uri) {
+  if (!uri) return "(no source)";
+  const unstable = uri.match(/[?&]unstable_path=([^&?]+)/);
+  const effective = unstable ? decodeURIComponent(unstable[1]) : uri;
+  const noQuery = effective.split("?")[0] ?? effective;
+  const segs = noQuery.split("/").filter(Boolean);
+  return segs[segs.length - 1] ?? effective;
+}
+function verdictLabel(r) {
+  if (r.oversizeFactor == null) return "\u2013";
+  if (r.oversizeFactor < 0.9) return `${r.oversizeFactor.toFixed(1)}\xD7 upscaled`;
+  if (r.oversizeFactor <= 1.1) return "right-sized";
+  return `${r.oversizeFactor.toFixed(1)}\xD7 oversized (${r.wastedKB}KB wasted)`;
+}
+function cacheLabel(r) {
+  if (r.cache) return r.cache;
+  if (r.progressSeen) return "network";
+  return "?";
+}
+function mb(bytes) {
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function formatListMarkdown(list, limit) {
+  const lines = [];
+  const s = list.stats;
+  lines.push(`## Images registry (${list.total} records, showing ${Math.min(limit, list.records.length)})`);
+  lines.push("");
+  lines.push(
+    `${s.loaded} loaded \xB7 ${s.errors} failed \xB7 ${s.loading} in flight \xB7 \u2248${mb(s.estDecodedBytes)} decoded` + (s.estWastedBytes > 0 ? ` \xB7 **${mb(s.estWastedBytes)} wasted on oversized sources**` : "")
+  );
+  const ins = list.insights;
+  if (ins) {
+    const chips = [];
+    if (ins.duplicates.length > 0)
+      chips.push(`${ins.duplicates.length} duplicate URL(s): ${ins.duplicates.slice(0, 3).map((d) => `${uriTail(d.uri)}\xD7${d.count}`).join(", ")}`);
+    if (ins.retryStorms.length > 0)
+      chips.push(`${ins.retryStorms.length} retry storm(s): ${ins.retryStorms.slice(0, 3).map((r) => `#${r.id}(${r.loadCount} loads)`).join(", ")}`);
+    if (ins.queueSaturated) chips.push("iOS image queue saturated (>4 concurrent loads)");
+    if (ins.missingAlt > 0) chips.push(`${ins.missingAlt} image(s) missing alt/accessibilityLabel`);
+    if (ins.layoutShifters.length > 0)
+      chips.push(`${ins.layoutShifters.length} layout-shifting image(s): ${ins.layoutShifters.slice(0, 3).map((l) => `#${l.id}`).join(", ")} \u2014 reserve explicit dimensions`);
+    if (chips.length > 0) {
+      lines.push("");
+      lines.push(`**Insights:** ${chips.join(" \xB7 ")}`);
+    }
+  }
+  const cs = list.captureStatus;
+  if (cs.rnDecoratorTooLate) {
+    lines.push("");
+    lines.push('\u26A0 RN <Image> capture missed the module-load race \u2014 add `import "@buoy-gg/images/register"` as the FIRST import of the app entry file.');
+  }
+  if (list.globalModes.network !== "normal" || list.globalModes.blank) {
+    lines.push("");
+    lines.push(`\u26A0 Simulation active: network=${list.globalModes.network}${list.globalModes.blank ? ", blank images ON" : ""} (set_image_simulation to reset).`);
+  }
+  lines.push("");
+  lines.push("| id | image | lib | status | cache | ms | decoded px | shown dp | verdict | sim |");
+  lines.push("|---|---|---|---|---|---|---|---|---|---|");
+  for (const r of list.records) {
+    const dims = r.intrinsic ? `${r.intrinsic.width}\xD7${r.intrinsic.height}` : "\u2013";
+    const layout = r.layout ? `${r.layout.width}\xD7${r.layout.height}` : "\u2013";
+    const status = r.status === "error" ? `**error**${r.errorCode ? ` (${r.errorCode})` : ""}` : r.status;
+    lines.push(
+      `| ${r.id} | ${uriTail(r.uri)} | ${r.lib} | ${status}${r.mounted ? "" : " (unmounted)"} | ${cacheLabel(r)} | ${r.ms ?? "\u2013"} | ${dims} | ${layout} | ${verdictLabel(r)} | ${r.overrideLabel ?? "\u2013"} |`
+    );
+  }
+  lines.push("");
+  lines.push("_Act on a row with `image_action` using its `id` (hard_reload / retry / force_error / force_loading / force_blank / swap_url / flash / restore / evict_disk)._");
+  return lines.join("\n");
+}
+var ACTION_MAP = {
+  hard_reload: { action: "hardReload" },
+  retry: { action: "retry" },
+  evict_disk: { action: "evictDisk" },
+  flash: { action: "flash" },
+  restore: { action: "clearOverride" },
+  force_error: { action: "setOverride", params: () => ({ kind: "error" }) },
+  force_loading: { action: "setOverride", params: () => ({ kind: "hang" }) },
+  force_blank: { action: "setOverride", params: () => ({ kind: "blank" }) },
+  swap_url: { action: "setOverride", params: (url) => ({ kind: "url", uri: url }) }
+};
+function registerImagesTools(server, sync) {
+  server.registerTool(
+    "get_images",
+    {
+      description: "Live image registry from the app: every RN <Image> and expo-image load with cache verdict (memory/disk/network), load ms, decoded vs displayed size with an oversize/upscale verdict and wasted-KB estimate, error details, and any active simulation overrides. Image HTTP never hits the JS network stack, so this is the only visibility into image loading. Requires @buoy-gg/images on the device.",
+      inputSchema: {
+        deviceId: z14.string().optional().describe("Target device id (auto-selected if one is connected)."),
+        limit: z14.number().optional().describe("Max records to return (newest first). Default 30, max 200."),
+        status: z14.enum(["pending", "loading", "loaded", "error"]).optional().describe("Only records in this state (e.g. 'error' for the failure log).")
+      }
+    },
+    async ({ deviceId, limit, status }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const capped = Math.min(Math.max(limit ?? 30, 1), 200);
+        const list = await sync.callAction(
+          IMAGES_TOOL_ID,
+          "list",
+          { limit: capped, status },
+          target
+        );
+        if (!list) return fail14("Device returned nothing \u2014 is @buoy-gg/images installed in the app?");
+        const md = formatListMarkdown(list, capped);
+        const slim = {
+          stats: list.stats,
+          insights: list.insights,
+          captureStatus: list.captureStatus,
+          globalModes: list.globalModes,
+          records: list.records.map((r) => ({
+            id: r.id,
+            uri: r.uri,
+            lib: r.lib,
+            status: r.status,
+            mounted: r.mounted,
+            cache: r.cache,
+            ms: r.ms,
+            intrinsic: r.intrinsic,
+            layout: r.layout,
+            oversizeFactor: r.oversizeFactor,
+            wastedKB: r.wastedKB,
+            error: r.error,
+            errorCode: r.errorCode,
+            overrideLabel: r.overrideLabel,
+            loadCount: r.loadCount
+          }))
+        };
+        return text12(`${md}
+
+\`\`\`json
+${JSON.stringify(slim)}
+\`\`\``);
+      } catch (e) {
+        return fail14(errMsg14(e));
+      }
+    }
+  );
+  server.registerTool(
+    "image_action",
+    {
+      description: "Act on one image from get_images (by id): hard_reload (bypass caches + refetch), retry, evict_disk (expo disk entry), flash (red border to locate it on screen), prove_savings (re-encode at displayed size as WebP ON DEVICE and return real byte savings + a previewable file:// uri), or simulation overrides \u2014 force_error (instant offline-safe failure), force_loading (request hangs forever), force_blank, swap_url (requires url), restore (remove override). Returns the record's state after the action so the effect is visible.",
+      inputSchema: {
+        deviceId: z14.string().optional().describe("Target device id (auto-selected if one is connected)."),
+        id: z14.number().describe("Record id from get_images."),
+        action: z14.enum([
+          "hard_reload",
+          "retry",
+          "evict_disk",
+          "flash",
+          "prove_savings",
+          "force_error",
+          "force_loading",
+          "force_blank",
+          "swap_url",
+          "restore"
+        ]).describe("What to do."),
+        url: z14.string().optional().describe("Replacement URL (swap_url only).")
+      }
+    },
+    async ({ deviceId, id, action, url }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        if (action === "prove_savings") {
+          const savings = await sync.callAction(IMAGES_TOOL_ID, "proveSavings", { id }, target);
+          if (!savings) return fail14("Device returned nothing for proveSavings.");
+          if (!savings.ok) return fail14(savings.message);
+          const parts = [`**prove_savings** on #${id}: ${savings.message}`];
+          if (savings.originalBytes != null)
+            parts.push(`Original: ${Math.round(savings.originalBytes / 1024)}KB (${savings.originalBytesSource})`);
+          if (savings.optimizedBytes != null)
+            parts.push(
+              `Optimized: ${Math.round(savings.optimizedBytes / 1024)}KB \u2014 ${savings.optimizedDims?.width}\xD7${savings.optimizedDims?.height} WebP`
+            );
+          if (savings.savedBytes != null)
+            parts.push(`**Saved: ${Math.round(savings.savedBytes / 1024)}KB (${savings.savedPct}%)**`);
+          if (savings.optimizedUri)
+            parts.push(`Preview in place: image_action {id:${id}, action:"swap_url", url:"${savings.optimizedUri}"}`);
+          return text12(parts.join("\n"));
+        }
+        const entry = ACTION_MAP[action];
+        if (!entry) return fail14(`Unknown action: ${action}`);
+        if (action === "swap_url" && !url) return fail14("swap_url requires the `url` param.");
+        const result = await sync.callAction(
+          IMAGES_TOOL_ID,
+          entry.action,
+          { id, ...entry.params?.(url) ?? {} },
+          target
+        );
+        const settleMs = action === "flash" ? 0 : 1500;
+        if (settleMs > 0) await new Promise((r) => setTimeout(r, settleMs));
+        const detail = await sync.callAction(IMAGES_TOOL_ID, "getDetail", { id }, target).catch(() => null);
+        const lines = [
+          `**${action}** on #${id}: ${result?.message ?? (result?.ok === false ? "failed" : "done")}`
+        ];
+        if (detail) {
+          lines.push("");
+          lines.push(
+            `Now: status=${detail.status}${detail.errorCode ? ` (${detail.errorCode})` : ""} \xB7 cache=${cacheLabel(detail)} \xB7 ms=${detail.ms ?? "\u2013"} \xB7 loads=${detail.loadCount}${detail.overrideLabel ? ` \xB7 sim="${detail.overrideLabel}"` : ""}${detail.mounted ? "" : " \xB7 UNMOUNTED"}`
+          );
+          if (detail.error) lines.push(`Error: ${detail.error}`);
+        }
+        return text12(lines.join("\n"));
+      } catch (e) {
+        return fail14(errMsg14(e));
+      }
+    }
+  );
+  server.registerTool(
+    "set_image_simulation",
+    {
+      description: "App-wide image simulation modes: network 'offline' (every NETWORK image load fails immediately, both libs \u2014 bundled assets still load; reload/remount on-screen images to see it), 'cold' (every image bypasses caches \u2014 first-launch behavior, nothing cleared), 'normal' to reset. blankImages renders every image without a source. massAction applies per-image simulations to everything mounted. Also clears the registry or expo caches when asked.",
+      inputSchema: {
+        deviceId: z14.string().optional().describe("Target device id (auto-selected if one is connected)."),
+        network: z14.enum(["normal", "offline", "cold"]).optional().describe("Network simulation mode."),
+        blankImages: z14.boolean().optional().describe("Render all images without a source."),
+        massAction: z14.enum(["error", "loading", "blank", "reload", "flash", "restore"]).optional().describe("Apply to EVERY mounted image at once: force error/loading/blank overrides, hard-reload all, flash all, or restore all overrides."),
+        clearRegistry: z14.boolean().optional().describe("Clear the captured image log."),
+        clearExpoCaches: z14.boolean().optional().describe("Clear expo-image memory + disk caches.")
+      }
+    },
+    async ({ deviceId, network, blankImages, massAction, clearRegistry, clearExpoCaches }) => {
+      try {
+        const target = sync.requireProDevice(deviceId);
+        const done = [];
+        if (massAction) {
+          const r = await sync.callAction(IMAGES_TOOL_ID, "massAction", { kind: massAction }, target);
+          done.push(r?.message ?? `mass ${massAction} applied`);
+        }
+        if (network) {
+          await sync.callAction(IMAGES_TOOL_ID, "setNetworkMode", { mode: network }, target);
+          done.push(`network=${network}`);
+        }
+        if (blankImages != null) {
+          await sync.callAction(IMAGES_TOOL_ID, "setBlankImages", { enabled: blankImages }, target);
+          done.push(`blankImages=${blankImages}`);
+        }
+        if (clearRegistry) {
+          await sync.callAction(IMAGES_TOOL_ID, "clearRecords", {}, target);
+          done.push("registry cleared");
+        }
+        if (clearExpoCaches) {
+          const r = await sync.callAction(IMAGES_TOOL_ID, "clearExpoCaches", {}, target);
+          done.push(r?.message ?? "expo caches cleared");
+        }
+        if (done.length === 0) return fail14("Pass at least one of: network, blankImages, massAction, clearRegistry, clearExpoCaches.");
+        return text12(`Applied: ${done.join(" \xB7 ")}`);
+      } catch (e) {
+        return fail14(errMsg14(e));
+      }
+    }
+  );
+}
+
 // src/server.ts
 var SERVER_INSTRUCTIONS = `Buoy MCP \u2014 drive Buoy dev tools running in a React Native app from your editor.
 
@@ -2134,6 +2567,15 @@ elements (accessibility-style tree with tap points + testIDs, no screenshot), th
 ({ 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.
 
+JS FPS low / app hitching and you need to know WHAT is eating the JS thread? Use
+\`get_js_thread_top\` (a live "Task Manager" of timers, Promise chains, rAF callbacks and
+freezes, ranked by thread time), then \`get_js_thread_origin_detail\` to drill into a row.
+Pass clearFirst:true and drive the UI with \`tap_element\` mid-sample to profile one interaction.
+
+Debugging images (not loading, slow, stale cache, memory)? \`get_images\` lists every RN <Image> /
+expo-image load with cache verdicts and oversize audits; \`image_action\` reloads, retries, or
+simulates failures per image; \`set_image_simulation\` flips app-wide offline/cold/blank modes.
+
 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),
@@ -2162,22 +2604,28 @@ function createMcpServer(sync) {
   registerConsoleTools(server, sync);
   registerScreenshotTools(server, sync);
   registerInteractTools(server, sync);
+  registerJsThreadTools(server, sync);
+  registerImagesTools(server, sync);
   return server;
 }
 var deviceIdField = {
-  deviceId: z13.string().optional().describe(
+  deviceId: z15.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 { spawnSync } from "child_process";
 import fs3 from "fs";
+import os3 from "os";
 import path3 from "path";
+var PUBLIC_REGISTRY = "https://registry.npmjs.org";
+var PROBE_TIMEOUT_MS = 3e3;
 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 entry = resolveEntry(opts, log);
   const done = [];
   upsertMcpConfig(path3.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
   if (fs3.existsSync(path3.join(cwd, ".cursor"))) {
@@ -2194,12 +2642,125 @@ function runInit(opts = {}) {
   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) {
+  if (entry.command === "npx") {
     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\`.`);
+  } else if (!opts.cliPath) {
+    log("");
+    log(`This uses a pinned local install (no network on startup). To update it later,`);
+    log(`re-run init (\`node ${entry.args[0]?.replace(/dist[/\\]cli\.js$/, "") ?? ""}...\` \u2014 or reinstall).`);
   }
 }
+function resolveEntry(opts, log) {
+  if (opts.cliPath) {
+    return { type: "stdio", command: "node", args: [opts.cliPath] };
+  }
+  const mode = opts.mode ?? "auto";
+  if (mode === "npx") {
+    return npxEntry();
+  }
+  if (mode === "local") {
+    return localEntry(opts, log);
+  }
+  const probe = probeRegistry();
+  if (probe.reachable) {
+    return npxEntry();
+  }
+  log(
+    `\u26A0 npm registry ${probe.registry ? `(${probe.registry}) ` : ""}looks unreachable \u2014 \`npx @latest\` would hang your editor at startup. Falling back to a pinned local install.`
+  );
+  return localEntry(opts, log);
+}
+function npxEntry() {
+  return { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`] };
+}
+function localEntry(opts, log) {
+  const installDir = opts.installDir ?? process.env.BUOY_MCP_HOME ?? path3.join(os3.homedir(), ".buoy-mcp");
+  const registry = opts.registry ?? PUBLIC_REGISTRY;
+  const cliPath = installLocalCopy(installDir, registry, log);
+  if (cliPath) {
+    return { type: "stdio", command: "node", args: [cliPath] };
+  }
+  log("\u26A0 local install failed \u2014 writing the npx entry instead (see the error above).");
+  return npxEntry();
+}
+function installLocalCopy(installDir, registry, log) {
+  const spec = `${PACKAGE_NAME}@${VERSION === "0.0.0-dev" ? "latest" : VERSION}`;
+  fs3.mkdirSync(installDir, { recursive: true });
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  log(`Installing ${spec} into ${installDir} from ${registry} \u2026`);
+  const res = spawnSync(
+    npm,
+    [
+      "install",
+      spec,
+      "--prefix",
+      installDir,
+      "--registry",
+      registry,
+      `--@buoy-gg:registry=${registry}`,
+      "--no-audit",
+      "--no-fund",
+      "--loglevel=error"
+    ],
+    { stdio: ["ignore", "ignore", "inherit"], encoding: "utf8" }
+  );
+  if (res.status !== 0) {
+    log(`\u26A0 npm install exited with code ${res.status ?? "?"}${res.error ? ` (${res.error.message})` : ""}.`);
+    return null;
+  }
+  const cliPath = path3.join(installDir, "node_modules", PACKAGE_NAME, "dist", "cli.js");
+  if (!fs3.existsSync(cliPath)) {
+    log(`\u26A0 install finished but ${cliPath} is missing.`);
+    return null;
+  }
+  return cliPath;
+}
+function probeRegistry() {
+  const registry = effectiveRegistry();
+  if (!registry) return { reachable: false, registry: null };
+  if (/^https?:\/\/registry\.npmjs\.org\/?$/i.test(registry)) {
+    return { reachable: true, registry };
+  }
+  return { reachable: hostReachable(registry), registry };
+}
+function effectiveRegistry() {
+  const scoped = npmConfigGet("@buoy-gg:registry");
+  if (scoped) return scoped;
+  const global = npmConfigGet("registry");
+  return global ?? PUBLIC_REGISTRY;
+}
+function npmConfigGet(key) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const res = spawnSync(npm, ["config", "get", key], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS });
+  if (res.status !== 0 || typeof res.stdout !== "string") return null;
+  const val = res.stdout.trim();
+  if (!val || val === "undefined" || val === "null") return null;
+  return val;
+}
+function hostReachable(registry) {
+  const done = spawnSync(
+    process.execPath,
+    ["-e", REACHABILITY_PROBE, registry, String(PROBE_TIMEOUT_MS)],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS + 2e3 }
+  );
+  return done.status === 0;
+}
+var REACHABILITY_PROBE = `
+const url = process.argv[1];
+const ms = Number(process.argv[2]) || 3000;
+const c = new AbortController();
+const t = setTimeout(() => c.abort(), ms);
+fetch(url, { method: 'HEAD', signal: c.signal })
+  .then(() => { clearTimeout(t); process.exit(0); })
+  .catch(() => {
+    // A HEAD may be rejected while the host is up; a bare TCP-level failure is
+    // what we care about. fetch throwing a TypeError = network unreachable.
+    clearTimeout(t);
+    process.exit(1);
+  });
+`;
 function upsertMcpConfig(file, key, entry, cwd, done) {
   let json3 = {};
   if (fs3.existsSync(file)) {