@buoy-gg/core 6.0.1 → 7.0.0

package/README.md

@@ -63,7 +63,7 @@ npm i @buoy-gg/{core,network,storage,env,react-query,route-events,debug-borders,
 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.
+- **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
@@ -88,6 +88,12 @@ Everything runs in your app's process. The broker that mirrors the session to de
 
 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)

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

package/lib/commonjs/floatingMenu/optionalRequire.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.reportOptionalRequireError = reportOptionalRequireError;
+const isDev = typeof __DEV__ !== "undefined" && __DEV__;
+const reported = new Set();
+const MODULE_NOT_FOUND_RE = /could not be found within the project|Cannot find module|Unable to resolve module/i;
+
+/**
+ * Call from the CATCH block of a guarded optional require (the require
+ * literal itself must stay lexically inside try{} for Metro to treat the
+ * dependency as optional — this helper only inspects the failure).
+ *
+ * Silent when the package simply isn't installed. Warns once per module
+ * (dev only) when the package IS present but threw during import — a broken
+ * transitive resolve (subpath exports, version skew) or a top-level crash —
+ * which otherwise fails silently and makes tools vanish with no clue.
+ */
+function reportOptionalRequireError(moduleName, err) {
+  if (!isDev) return;
+  const message = err instanceof Error ? err.message : String(err);
+  const code = err?.code;
+  const isNotFound = code === "MODULE_NOT_FOUND" || MODULE_NOT_FOUND_RE.test(message);
+  // "Not found" naming the module itself = expected (not installed).
+  // "Not found" naming a DIFFERENT module = broken transitive dep inside an
+  // installed package — a real error worth surfacing.
+  if (isNotFound && message.includes(moduleName)) return;
+  if (reported.has(moduleName)) return;
+  reported.add(moduleName);
+  console.warn(`[buoy] "${moduleName}" is installed but failed to load — its tools won't appear. ` + `Underlying error: ${message}`);
+}

package/lib/commonjs/floatingMenu/useDesktopSyncStatus.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useDesktopSyncStatus = useDesktopSyncStatus;
+var _react = require("react");
+var _optionalRequire = require("./optionalRequire.js");
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+// Guarded module-level require (same Metro constraint as autoExternalSync:
+// the require literal must sit lexically inside try{} to stay optional).
+let syncModule = null;
+try {
+  syncModule = require("@buoy-gg/external-sync");
+} catch (e) {
+  (0, _optionalRequire.reportOptionalRequireError)("@buoy-gg/external-sync", e);
+}
+const noopSubscribe = () => () => {};
+
+/**
+ * Live desktop-sync status for the settings modal. Returns null when
+ * external-sync isn't installed or predates the sync-status store — the
+ * caller hides the status row in that case.
+ */
+function useDesktopSyncStatus() {
+  return (0, _react.useSyncExternalStore)(syncModule?.subscribeSyncStatus ?? noopSubscribe, () => syncModule?.getSyncStatus?.() ?? null);
+}