@buoy-gg/core 6.0.0 → 7.0.0

package/README.md

@@ -1,43 +1,106 @@
-# @buoy/core
+# @buoy-gg/core
 
-[![npm](https://img.shields.io/npm/v/@buoy%2Fcore)](https://www.npmjs.com/package/@buoy/core)
+[![npm version](https://img.shields.io/npm/v/@buoy-gg/core?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/core)
+[![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/core?style=flat-square&labelColor=1c1c1c&color=10B981&label=downloads%2Fmonth)](https://www.npmjs.com/package/@buoy-gg/core)
 
+**Devtools that live in your app. And answer to your agent.**
 
-Floating dev tools launcher and host provider for React Native apps.
+Buoy is a floating dev menu that ships inside your React Native app. Every request, state change, render, and frame — live on the phone, on your desktop, and in Claude or Cursor. Drop in one component, install the tools you want, and they appear in the menu on their own.
+
+![Buoy demo — the floating dev menu in action](https://github.com/user-attachments/assets/a732d6a3-9963-49e3-b0f1-0d974a0a74d7)
 
 ## Install
+
 ```bash
-pnpm add @buoy/core @buoy/shared-ui
+npm install @buoy-gg/core
 ```
 
-## Quick Start
+## Quick start
+
 ```tsx
-import { AppHostProvider, FloatingMenu } from '@buoy/core';
-import type { InstalledApp } from '@buoy/core';
-import { EnvVarsModal } from '@buoy/env';
-
-const APPS: InstalledApp[] = [
-  {
-    id: 'env',
-    name: 'Environment',
-    icon: '🛰️',
-    component: EnvVarsModal,
-    singleton: true,
-  },
-];
-
-export function DevToolsHost() {
+import { FloatingDevTools } from "@buoy-gg/core";
+
+export default function App() {
   return (
-    <AppHostProvider>
-      <FloatingMenu apps={APPS} />
-    </AppHostProvider>
+    <>
+      {/* Your app */}
+      <FloatingDevTools />
+    </>
   );
 }
 ```
 
-## Key Exports
-- `AppHostProvider` – Context provider that manages installed dev tools.
-- `FloatingMenu` – Cyberpunk-inspired floating entrypoint for tools.
-- `AppOverlay` & `useAppHost()` – Programmatic APIs for opening tools.
+That's the whole setup — a floating dev menu appears inside your app. Install any tool package and it auto-appears in the menu; most need zero config, a few take one line (like passing `zustandStores` or calling `watchAtoms()`). Add a `licenseKey` prop to unlock [Pro](https://buoy.gg/pricing): production builds, the MCP server, and unlimited capture.
+
+## The 15 tools
+
+| Tool | Package | What it does |
+| --- | --- | --- |
+| [Network](https://buoy.gg/buoy/latest/docs/tools/network) | `@buoy-gg/network` | Every request, response, timing & error — GraphQL operations extracted and named |
+| [Storage](https://buoy.gg/buoy/latest/docs/tools/storage) | `@buoy-gg/storage` | Browse & edit AsyncStorage, MMKV & SecureStore with change history |
+| [Env](https://buoy.gg/buoy/latest/docs/tools/env) | `@buoy-gg/env` | Auto-discovers `EXPO_PUBLIC_` vars, validates types, scores config health |
+| [Query](https://buoy.gg/buoy/latest/docs/tools/react-query) | `@buoy-gg/react-query` | TanStack Query cache — refetch, invalidate, simulate loading & error states |
+| [Routes](https://buoy.gg/buoy/latest/docs/tools/routes) | `@buoy-gg/route-events` | Navigation events, the live stack, and the full sitemap — jump to any screen |
+| [Debug Borders](https://buoy.gg/buoy/latest/docs/tools/debug-borders) | `@buoy-gg/debug-borders` | Depth-colored layout borders — tap any label for testID, a11y props & styles |
+| [Highlight Updates](https://buoy.gg/buoy/latest/docs/tools/highlight-updates) | `@buoy-gg/highlight-updates` | Every render, with the cause: mount, state, props, or parent |
+| [Bench](https://buoy.gg/buoy/latest/docs/tools/perf-monitor) | `@buoy-gg/perf-monitor` | UI/JS FPS, CPU, memory & jank on a real device — batch benchmarks, ranked reports |
+| [Events](https://buoy.gg/buoy/latest/docs/tools/events) | `@buoy-gg/events` | One timeline across every tool, with LLM-friendly export presets |
+| [Console](https://buoy.gg/buoy/latest/docs/tools/console) | `@buoy-gg/console` | Chrome-DevTools console on device — read logs with no cable and no Metro |
+| [Redux](https://buoy.gg/buoy/latest/docs/tools/redux) | `@buoy-gg/redux` | Inspect, dispatch & time travel — flags actions that blow the frame budget |
+| [Zustand](https://buoy.gg/buoy/latest/docs/tools/zustand) | `@buoy-gg/zustand` | State, diffs, jump-to-state, one-tap reset — no middleware needed |
+| [Jotai](https://buoy.gg/buoy/latest/docs/tools/jotai) | `@buoy-gg/jotai` | One `watchAtoms()` call — every event shows `prev → next` |
+| [Impersonate](https://buoy.gg/buoy/latest/docs/tools/impersonate) | `@buoy-gg/impersonate` | Switch users, roles & flags without rebuilding |
+| [Overlay](https://buoy.gg/buoy/latest/docs/tools/image-overlay) | `@buoy-gg/image-overlay` | Pin Figma mockups pixel-perfect over the app |
+
+Grab everything in one line:
+
+```bash
+npm i @buoy-gg/{core,network,storage,env,react-query,route-events,debug-borders,highlight-updates,perf-monitor,events,console,redux,zustand,jotai,impersonate,image-overlay}
+```
+
+## Three surfaces, one live session
+
+Every tool runs inside your app's process. The phone, the desktop, and your agent all see the same session, live.
+
+- **On the phone** — tap the floating menu. Works on any device, no cable, no desktop app, no Metro.
+- **On your desktop** — [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop) (free) mirrors the tools to full-screen panels on macOS, Windows & Linux, with a live FPS / CPU / memory HUD and remote control of the device. Devices connect automatically — physical phones included, no URLs to configure.
+- **Through your agent** — the [Buoy MCP server](https://buoy.gg/buoy/latest/docs/mcp) gives Claude Code, Cursor, or any MCP editor structured tool calls into the running app: read live state, tap real buttons, run benchmarks on a physical device.
+
+## Free vs Pro
+
+Every tool is **free** — no key, no signup, no time limit.
+
+**Pro** unlocks production builds, the MCP server, and unlimited capture. Activate with one prop:
+
+```tsx
+<FloatingDevTools licenseKey="YOUR_LICENSE_KEY" />
+```
+
+**Weekend Pass:** every Saturday and Sunday, every Pro feature unlocks free for everyone — built into the product, not a promo. Details at [buoy.gg/pricing](https://buoy.gg/pricing).
+
+## Safe in production
+
+Everything runs in your app's process. The broker that mirrors the session to desktop and MCP binds to localhost only — nothing ever leaves your machine. You decide who sees the tools:
+
+```tsx
+{isInternalUser && <FloatingDevTools />}
+```
+
+That one line is the whole production story: internal builds and flagged users get the full toolkit; everyone else gets nothing.
+
+Need the session with **no on-device UI at all** — field builds or devices handed to non-developers? Headless mode keeps every tool syncing to Buoy Desktop and MCP while rendering nothing on the device:
+
+```tsx
+<FloatingDevTools headless />
+```
+
+## Links
+
+- [Full documentation](https://buoy.gg/buoy/latest/docs/overview)
+- [GitHub](https://github.com/Buoy-gg/buoy)
+- [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop)
+- [Pricing](https://buoy.gg/pricing)
+
+## License
 
-The menu hosts any `InstalledApp` descriptor. Combine it with other `@buoy/*` packages for a full suite of debug panels.
+Proprietary software. © Buoy LLC. All rights reserved. See the [Terms of Service](https://buoy.gg/terms).

package/lib/commonjs/floatingMenu/DevToolsSettingsModal.js

@@ -7,6 +7,7 @@ exports.useDevToolsSettings = exports.DevToolsSettingsModal = void 0;
 var _react = require("react");
 var _reactNative = require("react-native");
 var _settingsBus = require("./settingsBus.js");
+var _useDesktopSyncStatus = require("./useDesktopSyncStatus.js");
 var _sharedUi = require("@buoy-gg/shared-ui");
 var _floatingToolsCore = require("@buoy-gg/floating-tools-core");
 var _DefaultConfigContext = require("./DefaultConfigContext.js");
@@ -158,6 +159,9 @@ const DevToolsSettingsModal = ({
   const [activeTabLoaded, setActiveTabLoaded] = (0, _react.useState)(false);
   const [expandedSettings, setExpandedSettings] = (0, _react.useState)(new Set());
   const [showLicenseModal, setShowLicenseModal] = (0, _react.useState)(false);
+  // null when external-sync isn't installed (or predates the status store);
+  // "idle" until AutoExternalSync initializes — the row hides in both cases.
+  const desktopSyncStatus = (0, _useDesktopSyncStatus.useDesktopSyncStatus)();
 
   // Load persisted active tab on mount
   (0, _react.useEffect)(() => {
@@ -808,6 +812,66 @@ const DevToolsSettingsModal = ({
               children: clearSuccess ? "CLEARED" : isClearing ? "CLEARING..." : "CLEAR ALL SETTINGS"
             })]
           })]
+        }), desktopSyncStatus && desktopSyncStatus.state !== "idle" && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+          style: [styles.storageStatusCard, {
+            borderColor: desktopSyncStatus.state === "connected" ? _sharedUi.buoyColors.success + "60" : _sharedUi.buoyColors.warning + "60"
+          }],
+          children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+            style: styles.storageStatusHeader,
+            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+              style: [styles.storageStatusIcon, {
+                backgroundColor: desktopSyncStatus.state === "connected" ? _sharedUi.buoyColors.success + "15" : _sharedUi.buoyColors.warning + "15"
+              }],
+              children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Globe, {
+                size: 18,
+                color: desktopSyncStatus.state === "connected" ? _sharedUi.buoyColors.success : _sharedUi.buoyColors.warning
+              })
+            }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+              style: styles.storageStatusInfo,
+              children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+                style: styles.storageStatusLabel,
+                children: "DESKTOP SYNC"
+              }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+                style: styles.storageStatusBadgeContainer,
+                children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+                  style: [styles.storageStatusBadge, {
+                    backgroundColor: desktopSyncStatus.state === "connected" ? _sharedUi.buoyColors.success + "20" : _sharedUi.buoyColors.warning + "20",
+                    borderColor: desktopSyncStatus.state === "connected" ? _sharedUi.buoyColors.success + "60" : _sharedUi.buoyColors.warning + "60"
+                  }],
+                  children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+                    style: [styles.storageStatusBadgeText, {
+                      color: desktopSyncStatus.state === "connected" ? _sharedUi.buoyColors.success : _sharedUi.buoyColors.warning
+                    }],
+                    children: desktopSyncStatus.state === "connected" ? "CONNECTED" : desktopSyncStatus.state === "connecting" ? "CONNECTING..." : "RETRYING"
+                  })
+                }), desktopSyncStatus.state === "connected" ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.CheckCircle2, {
+                  size: 14,
+                  color: _sharedUi.buoyColors.success
+                }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.AlertTriangle, {
+                  size: 14,
+                  color: _sharedUi.buoyColors.warning
+                })]
+              })]
+            })]
+          }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
+            style: styles.storageStatusDescription,
+            children: [desktopSyncStatus.state === "connected" ? "Streaming tool data to Buoy Desktop at " : "Trying to reach Buoy Desktop at ", /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+              style: styles.adviceHintCode,
+              children: desktopSyncStatus.targetURL ?? "(unknown URL)"
+            }), desktopSyncStatus.state !== "connected" && " — is the desktop app running? Override with the externalSync socketURL option if it runs elsewhere."]
+          }), desktopSyncStatus.state === "retrying" && desktopSyncStatus.lastError && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+            style: styles.adviceHint,
+            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.AlertTriangle, {
+              size: 14,
+              color: _sharedUi.buoyColors.warning
+            }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
+              style: styles.adviceHintText,
+              children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+                style: styles.adviceHintBold,
+                children: "Last error:"
+              }), " ", desktopSyncStatus.lastError]
+            })]
+          })]
         }), renderGlobalSettingCard("enableSharedModalDimensions", "SHARED MODAL SIZE", "MODAL", "Sync dimensions across all tools", "When enabled, all tool modals will share the same size and position. Resizing one modal will affect all others. When disabled, each tool remembers its own size and position independently.", "Keep OFF for the best experience. This allows you to customize each tool's modal size separately. Enable only if you prefer uniform modal sizes across all dev tools."), _reactNative.Platform.OS !== "web" && renderGlobalSettingCard("expandableWindowControls", "EXPAND CONTROLS", "MODAL", "iPad-style expandable window buttons", "When enabled, the window control buttons (minimize, toggle mode, close) start as small dots and expand into larger, easy-to-tap buttons when pressed — similar to iPad window controls. When disabled, buttons are directly tappable at their small size.", "Keep ON for touch devices where the small buttons are hard to press. Turn OFF if you prefer direct single-tap access (e.g. when using a mouse or simulator)."), isDevelopmentMode && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
           style: styles.exportConfigCard,
           children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {

package/lib/commonjs/floatingMenu/FloatingDevTools.js

@@ -10,6 +10,7 @@ var _AppHost = require("./AppHost.js");
 var _FloatingMenu = require("./FloatingMenu.js");
 var _autoDiscoverPresets = require("./autoDiscoverPresets.js");
 var _DevToolsVisibilityContext = require("./DevToolsVisibilityContext.js");
+var _optionalRequire = require("./optionalRequire.js");
 var _sharedUi = require("@buoy-gg/shared-ui");
 var _MinimizedToolsContext = require("./MinimizedToolsContext.js");
 var _defaultConfig = require("./defaultConfig.js");
@@ -115,6 +116,7 @@ const FloatingDevTools = ({
   zustandStores,
   environment,
   externalSync = true,
+  headless = false,
   ...props
 }) => {
   const resolvedEnvironment = environment ?? (0, _sharedUi.normalizeEnvironment)(process.env.NODE_ENV ?? "dev");
@@ -167,8 +169,8 @@ const FloatingDevTools = ({
         watchStores
       } = require("@buoy-gg/zustand");
       return watchStores(zustandStores);
-    } catch {
-      // @buoy-gg/zustand not installed
+    } catch (e) {
+      (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/zustand", e);
     }
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
@@ -196,7 +198,7 @@ const FloatingDevTools = ({
           requiredEnvVars: createEnvVarConfig(requiredEnvVars)
         }));
       } catch (error) {
-        // Package not installed, skip
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/env", error);
       }
     }
 
@@ -210,7 +212,7 @@ const FloatingDevTools = ({
           requiredStorageKeys
         }));
       } catch (error) {
-        // Package not installed, skip
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/storage", error);
       }
     }
     return overrides;
@@ -234,7 +236,8 @@ const FloatingDevTools = ({
         DebugBordersStandaloneOverlay
       } = require("@buoy-gg/debug-borders");
       return DebugBordersStandaloneOverlay;
-    } catch {
+    } catch (e) {
+      (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/debug-borders", e);
       return null;
     }
   }, []);
@@ -247,7 +250,8 @@ const FloatingDevTools = ({
         HighlightUpdatesOverlay: Overlay
       } = require("@buoy-gg/highlight-updates");
       return Overlay;
-    } catch {
+    } catch (e) {
+      (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/highlight-updates", e);
       return null;
     }
   }, []);
@@ -260,7 +264,8 @@ const FloatingDevTools = ({
         ImageOverlayStandalone
       } = require("@buoy-gg/image-overlay");
       return ImageOverlayStandalone;
-    } catch {
+    } catch (e) {
+      (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/image-overlay", e);
       return null;
     }
   }, []);
@@ -273,7 +278,8 @@ const FloatingDevTools = ({
         PerfMonitorOverlay: Overlay
       } = require("@buoy-gg/perf-monitor");
       return Overlay;
-    } catch {
+    } catch (e) {
+      (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/perf-monitor", e);
       return null;
     }
   }, []);
@@ -287,7 +293,8 @@ const FloatingDevTools = ({
         RouteTracker: Tracker
       } = require("@buoy-gg/route-events");
       return Tracker;
-    } catch {
+    } catch (e) {
+      (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/route-events", e);
       return null;
     }
   }, []);
@@ -300,7 +307,8 @@ const FloatingDevTools = ({
         ImpersonateOverlay: Overlay
       } = require("@buoy-gg/impersonate");
       return Overlay;
-    } catch {
+    } catch (e) {
+      (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/impersonate", e);
       return null;
     }
   }, []);
@@ -326,6 +334,22 @@ const FloatingDevTools = ({
     return null;
   }
 
+  // Headless (sync-only): tool adapters + route tracking + desktop sync, no
+  // on-device UI. requireLicense is intentionally skipped — there's nothing
+  // to gate. All hooks above already ran, so hook order is preserved, and
+  // AutoExternalSync is additionally dev-gated (the broker must never be
+  // contacted in production).
+  if (headless) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
+      children: [RouteTracker && /*#__PURE__*/(0, _jsxRuntime.jsx)(RouteTracker, {}), isDevelopment && externalSync !== false && (0, _autoExternalSync.isExternalSyncAvailable)() && /*#__PURE__*/(0, _jsxRuntime.jsx)(_autoExternalSync.AutoExternalSync, {
+        options: typeof externalSync === "object" ? externalSync : undefined,
+        requiredEnvVars: requiredEnvVars,
+        isPro: isLicensed,
+        licenseKey: licenseKey
+      })]
+    });
+  }
+
   // Gate: If requireLicense is enabled and no license, show only the license modal
   if (requireLicense && isInitialized && !licenseKey) {
     return /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.LicenseEntryModal, {

package/lib/commonjs/floatingMenu/FloatingDevTools.web.js

@@ -57,7 +57,8 @@ function FloatingDevTools({
   availableEnvironments: _availableEnvironments,
   onEnvironmentSwitch: _onEnvironmentSwitch,
   apps,
-  disableHints: _disableHints
+  disableHints: _disableHints,
+  headless = false
 }) {
   // Internal state for dial and settings
   const [isDialOpen, setIsDialOpen] = (0, _react.useState)(false);
@@ -135,6 +136,11 @@ function FloatingDevTools({
     setIsSettingsOpen(true);
   }, []);
   const handleCloseSettings = (0, _react.useCallback)(() => setIsSettingsOpen(false), []);
+
+  // Headless: desktop sync is native-only, so there is nothing to mount on
+  // web — accept the prop for API parity and render nothing. (After all
+  // hooks so hook order is preserved.)
+  if (headless) return null;
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
     children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_floatingToolsWeb.FloatingTools, {
       enablePositionPersistence: true,

package/lib/commonjs/floatingMenu/autoDiscoverPresets.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.autoDiscoverPresets = autoDiscoverPresets;
 exports.autoDiscoverPresetsWithCustom = autoDiscoverPresetsWithCustom;
+var _optionalRequire = require("./optionalRequire.js");
 /**
  * Automatically discovers and loads dev tool presets from installed packages.
  *
@@ -68,7 +69,8 @@ function autoDiscoverPresets() {
           envToolPreset
         } = require("@buoy-gg/env");
         return envToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/env", e);
         return null;
       }
     }
@@ -83,7 +85,8 @@ function autoDiscoverPresets() {
           networkToolPreset
         } = require("@buoy-gg/network");
         return networkToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/network", e);
         return null;
       }
     }
@@ -98,7 +101,8 @@ function autoDiscoverPresets() {
           storageToolPreset
         } = require("@buoy-gg/storage");
         return storageToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/storage", e);
         return null;
       }
     }
@@ -114,7 +118,8 @@ function autoDiscoverPresets() {
           wifiTogglePreset
         } = require("@buoy-gg/react-query");
         return [reactQueryToolPreset, wifiTogglePreset];
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/react-query", e);
         return null;
       }
     }
@@ -129,7 +134,8 @@ function autoDiscoverPresets() {
           routeEventsToolPreset
         } = require("@buoy-gg/route-events");
         return routeEventsToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/route-events", e);
         return null;
       }
     }
@@ -144,7 +150,8 @@ function autoDiscoverPresets() {
           debugBordersToolPreset
         } = require("@buoy-gg/debug-borders");
         return debugBordersToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/debug-borders", e);
         return null;
       }
     }
@@ -160,7 +167,8 @@ function autoDiscoverPresets() {
           highlightUpdatesModalPreset
         } = require("@buoy-gg/highlight-updates");
         return [highlightUpdatesModalPreset, highlightUpdatesPreset];
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/highlight-updates", e);
         return null;
       }
     }
@@ -175,7 +183,8 @@ function autoDiscoverPresets() {
           reduxToolPreset
         } = require("@buoy-gg/redux");
         return reduxToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/redux", e);
         return null;
       }
     }
@@ -190,7 +199,8 @@ function autoDiscoverPresets() {
           zustandToolPreset
         } = require("@buoy-gg/zustand");
         return zustandToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/zustand", e);
         return null;
       }
     }
@@ -205,7 +215,8 @@ function autoDiscoverPresets() {
           eventsToolPreset
         } = require("@buoy-gg/events");
         return eventsToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/events", e);
         return null;
       }
     }
@@ -220,7 +231,8 @@ function autoDiscoverPresets() {
           jotaiToolPreset
         } = require("@buoy-gg/jotai");
         return jotaiToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/jotai", e);
         return null;
       }
     }
@@ -235,7 +247,8 @@ function autoDiscoverPresets() {
           imageOverlayToolPreset
         } = require("@buoy-gg/image-overlay");
         return imageOverlayToolPreset;
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/image-overlay", e);
         return null;
       }
     }
@@ -251,7 +264,8 @@ function autoDiscoverPresets() {
           perfMonitorModalPreset
         } = require("@buoy-gg/perf-monitor");
         return [perfMonitorPreset, perfMonitorModalPreset];
-      } catch {
+      } catch (e) {
+        (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/perf-monitor", e);
         return null;
       }
     }
@@ -272,8 +286,9 @@ function autoDiscoverPresets() {
         }
       }
     } catch (error) {
-      // Silently skip packages that aren't installed
-      // This is expected behavior - not all packages will be installed
+      // Loaders swallow their own require failures; anything reaching here
+      // is a preset-shape problem in an installed package — surface it.
+      (0, _optionalRequire.reportOptionalRequireError)(name, error);
     }
   }
   return discoveredPresets;

package/lib/commonjs/floatingMenu/autoExternalSync.js

@@ -7,12 +7,14 @@ exports.AutoExternalSync = AutoExternalSync;
 exports.isExternalSyncAvailable = isExternalSyncAvailable;
 var _react = require("react");
 var _reactNative = require("react-native");
+var _optionalRequire = require("./optionalRequire.js");
 /**
  * Zero-config device→desktop sync for FloatingDevTools.
  *
  * When @buoy-gg/external-sync is installed, FloatingDevTools renders
  * <AutoExternalSync /> in dev builds: it connects to the Buoy Desktop broker
- * (localhost:42831 — a silent no-op when the desktop app isn't running) and
+ * (port 42831 on the Metro host, so physical devices reach the dev machine
+ * automatically — a background retry when the desktop app isn't running) and
  * registers a sync adapter for every installed tool package, discovered with
  * the same guarded-require pattern as autoDiscoverPresets. No <DevToolsSync>
  * wiring needed in the app.
@@ -47,85 +49,90 @@ let debugBordersModule = null;
 let impersonateModule = null;
 let perfMonitorModule = null;
 let expoConstantsModule = null;
+
+// Catch bodies report through reportOptionalRequireError: silent for a
+// genuinely absent package, one dev warning when an installed package fails
+// to load (broken transitive resolve, top-level crash).
 try {
   externalSyncModule = require("@buoy-gg/external-sync");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/external-sync", e);
 }
 try {
   storageModule = require("@buoy-gg/storage");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/storage", e);
 }
 try {
   networkModule = require("@buoy-gg/network");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/network", e);
 }
 try {
   reactQueryModule = require("@buoy-gg/react-query");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/react-query", e);
 }
 try {
   routeEventsModule = require("@buoy-gg/route-events");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/route-events", e);
 }
 try {
   reduxModule = require("@buoy-gg/redux");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/redux", e);
 }
 try {
   zustandModule = require("@buoy-gg/zustand");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/zustand", e);
 }
 try {
   jotaiModule = require("@buoy-gg/jotai");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/jotai", e);
 }
 try {
   eventsModule = require("@buoy-gg/events");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/events", e);
 }
 try {
   consoleModule = require("@buoy-gg/console");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/console", e);
 }
 try {
   envModule = require("@buoy-gg/env");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/env", e);
 }
 try {
   highlightUpdatesModule = require("@buoy-gg/highlight-updates");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/highlight-updates", e);
 }
 try {
   debugBordersModule = require("@buoy-gg/debug-borders");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/debug-borders", e);
 }
 try {
   impersonateModule = require("@buoy-gg/impersonate");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/impersonate", e);
 }
 try {
   perfMonitorModule = require("@buoy-gg/perf-monitor");
-} catch {
-  // not installed
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/perf-monitor", e);
 }
 try {
   expoConstantsModule = require("expo-constants");
-} catch {
-  // not installed (RN CLI apps)
+} catch (e) {
+  // not installed (RN CLI apps) — still report real load failures
+  (0, _optionalRequire.reportOptionalRequireError)("expo-constants", e);
 }
 
 /** Whether zero-config sync can run (the external-sync package is installed). */
@@ -165,7 +172,9 @@ function AutoExternalSync({
     socket
   } = useExternalSyncSocket({
     deviceName: options?.deviceName ?? identity.deviceName,
-    socketURL: options?.socketURL ?? "http://localhost:42831",
+    // Older external-sync versions predate getDefaultSocketURL and require
+    // an explicit URL — keep the literal fallback for them.
+    socketURL: options?.socketURL ?? externalSyncModule.getDefaultSocketURL?.() ?? "http://localhost:42831",
     persistentDeviceId: deviceId,
     platform: _reactNative.Platform.OS,
     enableLogs: options?.enableLogs