@buoy-gg/core 6.0.1 → 7.0.1

package/lib/module/floatingMenu/DevToolsSettingsModal.js

@@ -3,7 +3,8 @@
 import { useState, useEffect, useCallback, useMemo } from "react";
 import { View, Text, StyleSheet, ScrollView, TouchableOpacity, Dimensions, Platform } from "react-native";
 import { settingsBus } from "./settingsBus.js";
-import { SentryBugIcon, WifiCircuitIcon, ImageOverlayIcon, RenderCountIcon, Info, Layers, ChevronRightIcon, ChevronDown, getStorageBackendType, persistentStorage, Database, Trash2, CheckCircle2, AlertTriangle, Zap, FileText, HardDrive, Copy, FileCode, copyToClipboard, LicenseEntryModal, SectionHeader } from "@buoy-gg/shared-ui";
+import { useDesktopSyncStatus } from "./useDesktopSyncStatus.js";
+import { SentryBugIcon, WifiCircuitIcon, ImageOverlayIcon, RenderCountIcon, Globe, Info, Layers, ChevronRightIcon, ChevronDown, getStorageBackendType, persistentStorage, Database, Trash2, CheckCircle2, AlertTriangle, Zap, FileText, HardDrive, Copy, FileCode, copyToClipboard, LicenseEntryModal, SectionHeader } from "@buoy-gg/shared-ui";
 import { EnvIcon, StorageIcon, RoutesIcon, NetworkIcon, QueryIcon, HighlighterIcon, ReduxIcon, EventsIcon } from "@buoy-gg/floating-tools-core";
 import { useDefaultConfig } from "./DefaultConfigContext.js";
 import { JsModal, devToolsStorageKeys } from "@buoy-gg/shared-ui";
@@ -159,6 +160,9 @@ export const DevToolsSettingsModal = ({
   const [activeTabLoaded, setActiveTabLoaded] = useState(false);
   const [expandedSettings, setExpandedSettings] = useState(new Set());
   const [showLicenseModal, setShowLicenseModal] = 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 = useDesktopSyncStatus();
 
   // Load persisted active tab on mount
   useEffect(() => {
@@ -809,6 +813,66 @@ export const DevToolsSettingsModal = ({
               children: clearSuccess ? "CLEARED" : isClearing ? "CLEARING..." : "CLEAR ALL SETTINGS"
             })]
           })]
+        }), desktopSyncStatus && desktopSyncStatus.state !== "idle" && /*#__PURE__*/_jsxs(View, {
+          style: [styles.storageStatusCard, {
+            borderColor: desktopSyncStatus.state === "connected" ? buoyColors.success + "60" : buoyColors.warning + "60"
+          }],
+          children: [/*#__PURE__*/_jsxs(View, {
+            style: styles.storageStatusHeader,
+            children: [/*#__PURE__*/_jsx(View, {
+              style: [styles.storageStatusIcon, {
+                backgroundColor: desktopSyncStatus.state === "connected" ? buoyColors.success + "15" : buoyColors.warning + "15"
+              }],
+              children: /*#__PURE__*/_jsx(Globe, {
+                size: 18,
+                color: desktopSyncStatus.state === "connected" ? buoyColors.success : buoyColors.warning
+              })
+            }), /*#__PURE__*/_jsxs(View, {
+              style: styles.storageStatusInfo,
+              children: [/*#__PURE__*/_jsx(Text, {
+                style: styles.storageStatusLabel,
+                children: "DESKTOP SYNC"
+              }), /*#__PURE__*/_jsxs(View, {
+                style: styles.storageStatusBadgeContainer,
+                children: [/*#__PURE__*/_jsx(View, {
+                  style: [styles.storageStatusBadge, {
+                    backgroundColor: desktopSyncStatus.state === "connected" ? buoyColors.success + "20" : buoyColors.warning + "20",
+                    borderColor: desktopSyncStatus.state === "connected" ? buoyColors.success + "60" : buoyColors.warning + "60"
+                  }],
+                  children: /*#__PURE__*/_jsx(Text, {
+                    style: [styles.storageStatusBadgeText, {
+                      color: desktopSyncStatus.state === "connected" ? buoyColors.success : buoyColors.warning
+                    }],
+                    children: desktopSyncStatus.state === "connected" ? "CONNECTED" : desktopSyncStatus.state === "connecting" ? "CONNECTING..." : "RETRYING"
+                  })
+                }), desktopSyncStatus.state === "connected" ? /*#__PURE__*/_jsx(CheckCircle2, {
+                  size: 14,
+                  color: buoyColors.success
+                }) : /*#__PURE__*/_jsx(AlertTriangle, {
+                  size: 14,
+                  color: buoyColors.warning
+                })]
+              })]
+            })]
+          }), /*#__PURE__*/_jsxs(Text, {
+            style: styles.storageStatusDescription,
+            children: [desktopSyncStatus.state === "connected" ? "Streaming tool data to Buoy Desktop at " : "Trying to reach Buoy Desktop at ", /*#__PURE__*/_jsx(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__*/_jsxs(View, {
+            style: styles.adviceHint,
+            children: [/*#__PURE__*/_jsx(AlertTriangle, {
+              size: 14,
+              color: buoyColors.warning
+            }), /*#__PURE__*/_jsxs(Text, {
+              style: styles.adviceHintText,
+              children: [/*#__PURE__*/_jsx(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."), 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__*/_jsxs(View, {
           style: styles.exportConfigCard,
           children: [/*#__PURE__*/_jsxs(TouchableOpacity, {

package/lib/module/floatingMenu/FloatingDevTools.js

@@ -7,6 +7,7 @@ import { FloatingMenu } from "./FloatingMenu.js";
 import { AppOverlay } from "./AppHost.js";
 import { autoDiscoverPresets, autoDiscoverPresetsWithCustom } from "./autoDiscoverPresets.js";
 import { DevToolsVisibilityProvider } from "./DevToolsVisibilityContext.js";
+import { reportOptionalRequireError } from "./optionalRequire.js";
 import { HintsProvider, LicenseEntryModal, normalizeEnvironment } from "@buoy-gg/shared-ui";
 import { MinimizedToolsProvider } from "./MinimizedToolsContext.js";
 import { validateDialConfig } from "./defaultConfig.js";
@@ -43,7 +44,7 @@ import { AutoExternalSync, isExternalSyncAvailable } from "./autoExternalSync.js
  * You don't need to pass anything to use network, storage, redux, etc. tools!
  * Just install the package and it works automatically.
  */
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * Unified floating development tools component with automatic preset discovery.
  *
@@ -111,6 +112,7 @@ export const FloatingDevTools = ({
   zustandStores,
   environment,
   externalSync = true,
+  headless = false,
   ...props
 }) => {
   const resolvedEnvironment = environment ?? normalizeEnvironment(process.env.NODE_ENV ?? "dev");
@@ -163,8 +165,8 @@ export const FloatingDevTools = ({
         watchStores
       } = require("@buoy-gg/zustand");
       return watchStores(zustandStores);
-    } catch {
-      // @buoy-gg/zustand not installed
+    } catch (e) {
+      reportOptionalRequireError("@buoy-gg/zustand", e);
     }
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
@@ -192,7 +194,7 @@ export const FloatingDevTools = ({
           requiredEnvVars: createEnvVarConfig(requiredEnvVars)
         }));
       } catch (error) {
-        // Package not installed, skip
+        reportOptionalRequireError("@buoy-gg/env", error);
       }
     }
 
@@ -206,7 +208,7 @@ export const FloatingDevTools = ({
           requiredStorageKeys
         }));
       } catch (error) {
-        // Package not installed, skip
+        reportOptionalRequireError("@buoy-gg/storage", error);
       }
     }
     return overrides;
@@ -230,7 +232,8 @@ export const FloatingDevTools = ({
         DebugBordersStandaloneOverlay
       } = require("@buoy-gg/debug-borders");
       return DebugBordersStandaloneOverlay;
-    } catch {
+    } catch (e) {
+      reportOptionalRequireError("@buoy-gg/debug-borders", e);
       return null;
     }
   }, []);
@@ -243,7 +246,8 @@ export const FloatingDevTools = ({
         HighlightUpdatesOverlay: Overlay
       } = require("@buoy-gg/highlight-updates");
       return Overlay;
-    } catch {
+    } catch (e) {
+      reportOptionalRequireError("@buoy-gg/highlight-updates", e);
       return null;
     }
   }, []);
@@ -256,7 +260,8 @@ export const FloatingDevTools = ({
         ImageOverlayStandalone
       } = require("@buoy-gg/image-overlay");
       return ImageOverlayStandalone;
-    } catch {
+    } catch (e) {
+      reportOptionalRequireError("@buoy-gg/image-overlay", e);
       return null;
     }
   }, []);
@@ -269,7 +274,8 @@ export const FloatingDevTools = ({
         PerfMonitorOverlay: Overlay
       } = require("@buoy-gg/perf-monitor");
       return Overlay;
-    } catch {
+    } catch (e) {
+      reportOptionalRequireError("@buoy-gg/perf-monitor", e);
       return null;
     }
   }, []);
@@ -283,7 +289,8 @@ export const FloatingDevTools = ({
         RouteTracker: Tracker
       } = require("@buoy-gg/route-events");
       return Tracker;
-    } catch {
+    } catch (e) {
+      reportOptionalRequireError("@buoy-gg/route-events", e);
       return null;
     }
   }, []);
@@ -296,7 +303,8 @@ export const FloatingDevTools = ({
         ImpersonateOverlay: Overlay
       } = require("@buoy-gg/impersonate");
       return Overlay;
-    } catch {
+    } catch (e) {
+      reportOptionalRequireError("@buoy-gg/impersonate", e);
       return null;
     }
   }, []);
@@ -322,6 +330,22 @@ export 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__*/_jsxs(_Fragment, {
+      children: [RouteTracker && /*#__PURE__*/_jsx(RouteTracker, {}), isDevelopment && externalSync !== false && isExternalSyncAvailable() && /*#__PURE__*/_jsx(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__*/_jsx(LicenseEntryModal, {

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

@@ -53,7 +53,8 @@ export function FloatingDevTools({
   availableEnvironments: _availableEnvironments,
   onEnvironmentSwitch: _onEnvironmentSwitch,
   apps,
-  disableHints: _disableHints
+  disableHints: _disableHints,
+  headless = false
 }) {
   // Internal state for dial and settings
   const [isDialOpen, setIsDialOpen] = useState(false);
@@ -131,6 +132,11 @@ export function FloatingDevTools({
     setIsSettingsOpen(true);
   }, []);
   const handleCloseSettings = 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__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(FloatingTools, {
       enablePositionPersistence: true,

package/lib/module/floatingMenu/autoDiscoverPresets.js

@@ -1,5 +1,7 @@
 "use strict";
 
+import { reportOptionalRequireError } from "./optionalRequire.js";
+
 /**
  * Automatically discovers and loads dev tool presets from installed packages.
  *
@@ -63,7 +65,8 @@ export function autoDiscoverPresets() {
           envToolPreset
         } = require("@buoy-gg/env");
         return envToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/env", e);
         return null;
       }
     }
@@ -78,7 +81,8 @@ export function autoDiscoverPresets() {
           networkToolPreset
         } = require("@buoy-gg/network");
         return networkToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/network", e);
         return null;
       }
     }
@@ -93,7 +97,8 @@ export function autoDiscoverPresets() {
           storageToolPreset
         } = require("@buoy-gg/storage");
         return storageToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/storage", e);
         return null;
       }
     }
@@ -109,7 +114,8 @@ export function autoDiscoverPresets() {
           wifiTogglePreset
         } = require("@buoy-gg/react-query");
         return [reactQueryToolPreset, wifiTogglePreset];
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/react-query", e);
         return null;
       }
     }
@@ -124,7 +130,8 @@ export function autoDiscoverPresets() {
           routeEventsToolPreset
         } = require("@buoy-gg/route-events");
         return routeEventsToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/route-events", e);
         return null;
       }
     }
@@ -139,7 +146,8 @@ export function autoDiscoverPresets() {
           debugBordersToolPreset
         } = require("@buoy-gg/debug-borders");
         return debugBordersToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/debug-borders", e);
         return null;
       }
     }
@@ -155,7 +163,8 @@ export function autoDiscoverPresets() {
           highlightUpdatesModalPreset
         } = require("@buoy-gg/highlight-updates");
         return [highlightUpdatesModalPreset, highlightUpdatesPreset];
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/highlight-updates", e);
         return null;
       }
     }
@@ -170,7 +179,8 @@ export function autoDiscoverPresets() {
           reduxToolPreset
         } = require("@buoy-gg/redux");
         return reduxToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/redux", e);
         return null;
       }
     }
@@ -185,7 +195,8 @@ export function autoDiscoverPresets() {
           zustandToolPreset
         } = require("@buoy-gg/zustand");
         return zustandToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/zustand", e);
         return null;
       }
     }
@@ -200,7 +211,8 @@ export function autoDiscoverPresets() {
           eventsToolPreset
         } = require("@buoy-gg/events");
         return eventsToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/events", e);
         return null;
       }
     }
@@ -215,7 +227,8 @@ export function autoDiscoverPresets() {
           jotaiToolPreset
         } = require("@buoy-gg/jotai");
         return jotaiToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/jotai", e);
         return null;
       }
     }
@@ -230,7 +243,8 @@ export function autoDiscoverPresets() {
           imageOverlayToolPreset
         } = require("@buoy-gg/image-overlay");
         return imageOverlayToolPreset;
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/image-overlay", e);
         return null;
       }
     }
@@ -246,7 +260,8 @@ export function autoDiscoverPresets() {
           perfMonitorModalPreset
         } = require("@buoy-gg/perf-monitor");
         return [perfMonitorPreset, perfMonitorModalPreset];
-      } catch {
+      } catch (e) {
+        reportOptionalRequireError("@buoy-gg/perf-monitor", e);
         return null;
       }
     }
@@ -267,8 +282,9 @@ export 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.
+      reportOptionalRequireError(name, error);
     }
   }
   return discoveredPresets;

package/lib/module/floatingMenu/autoExternalSync.js

@@ -5,7 +5,8 @@
  *
  * 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.
@@ -15,6 +16,8 @@
  */
 import { useEffect, useMemo, useRef } from "react";
 import { Platform } from "react-native";
+import { reportOptionalRequireError } from "./optionalRequire.js";
+
 /* eslint-disable @typescript-eslint/no-var-requires */
 
 // Module-level guarded requires: presence is constant for the app lifetime,
@@ -41,85 +44,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) {
+  reportOptionalRequireError("@buoy-gg/external-sync", e);
 }
 try {
   storageModule = require("@buoy-gg/storage");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/storage", e);
 }
 try {
   networkModule = require("@buoy-gg/network");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/network", e);
 }
 try {
   reactQueryModule = require("@buoy-gg/react-query");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/react-query", e);
 }
 try {
   routeEventsModule = require("@buoy-gg/route-events");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/route-events", e);
 }
 try {
   reduxModule = require("@buoy-gg/redux");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/redux", e);
 }
 try {
   zustandModule = require("@buoy-gg/zustand");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/zustand", e);
 }
 try {
   jotaiModule = require("@buoy-gg/jotai");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/jotai", e);
 }
 try {
   eventsModule = require("@buoy-gg/events");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/events", e);
 }
 try {
   consoleModule = require("@buoy-gg/console");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/console", e);
 }
 try {
   envModule = require("@buoy-gg/env");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/env", e);
 }
 try {
   highlightUpdatesModule = require("@buoy-gg/highlight-updates");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/highlight-updates", e);
 }
 try {
   debugBordersModule = require("@buoy-gg/debug-borders");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/debug-borders", e);
 }
 try {
   impersonateModule = require("@buoy-gg/impersonate");
-} catch {
-  // not installed
+} catch (e) {
+  reportOptionalRequireError("@buoy-gg/impersonate", e);
 }
 try {
   perfMonitorModule = require("@buoy-gg/perf-monitor");
-} catch {
-  // not installed
+} catch (e) {
+  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
+  reportOptionalRequireError("expo-constants", e);
 }
 
 /** Whether zero-config sync can run (the external-sync package is installed). */
@@ -159,7 +167,9 @@ export 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: Platform.OS,
     enableLogs: options?.enableLogs

package/lib/module/floatingMenu/optionalRequire.js

@@ -0,0 +1,29 @@
+"use strict";
+
+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.
+ */
+export 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/module/floatingMenu/useDesktopSyncStatus.js

@@ -0,0 +1,25 @@
+"use strict";
+
+import { useSyncExternalStore } from "react";
+import { reportOptionalRequireError } from "./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) {
+  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.
+ */
+export function useDesktopSyncStatus() {
+  return useSyncExternalStore(syncModule?.subscribeSyncStatus ?? noopSubscribe, () => syncModule?.getSyncStatus?.() ?? null);
+}

package/lib/typescript/commonjs/floatingMenu/DevToolsSettingsModal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DevToolsSettingsModal.d.ts","sourceRoot":"","sources":["../../../../src/floatingMenu/DevToolsSettingsModal.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6C,EAAE,EAAE,MAAM,OAAO,CAAC;AAsJtE;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QACvC,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IACF,kDAAkD;IAClD,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED,UAAU,0BAA0B;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxD,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,aAAa,CAAC,EAAE;QACd,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;KAChC,EAAE,CAAC;CACL;AA2DD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,EAAE,CAAC,0BAA0B,CA+8BhE,CAAC;AAwDF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;CAuD/B,CAAC"}
+{"version":3,"file":"DevToolsSettingsModal.d.ts","sourceRoot":"","sources":["../../../../src/floatingMenu/DevToolsSettingsModal.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6C,EAAE,EAAE,MAAM,OAAO,CAAC;AAuJtE;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QACvC,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IACF,kDAAkD;IAClD,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED,UAAU,0BAA0B;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxD,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,aAAa,CAAC,EAAE;QACd,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;KAChC,EAAE,CAAC;CACL;AA2DD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,EAAE,CAAC,0BAA0B,CAwiChE,CAAC;AAwDF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;CAuD/B,CAAC"}

package/lib/typescript/commonjs/floatingMenu/FloatingDevTools.d.ts

@@ -234,9 +234,11 @@ export interface FloatingDevToolsProps extends Omit<FloatingMenuProps, "apps"> {
      * Zero-config sync to the Buoy Desktop dashboard.
      *
      * Enabled by default in dev builds whenever @buoy-gg/external-sync is
-     * installed: connects to the desktop broker (localhost:42831 — a silent
-     * no-op when the desktop app isn't running) and registers a sync adapter
-     * for every installed tool automatically. Nothing else to render.
+     * installed: connects to the desktop broker on port 42831 of the Metro
+     * host (derived from the bundle's scriptURL, so physical devices reach
+     * the dev machine automatically; retries quietly when the desktop app
+     * isn't running) and registers a sync adapter for every installed tool.
+     * Nothing else to render.
      *
      * Pass `false` to disable, or options to customize the device identity /
      * broker URL:
@@ -247,6 +249,18 @@ export interface FloatingDevToolsProps extends Omit<FloatingMenuProps, "apps"> {
      * ```
      */
     externalSync?: boolean | ExternalSyncOptions;
+    /**
+     * Headless (sync-only) mode: mount the desktop sync adapters and route
+     * tracking but render NO on-device UI — no floating bubble, dial, or
+     * overlays. For builds that ship to non-developers (field/associate
+     * builds) where the desktop dashboard is the only debugging surface.
+     *
+     * `requireLicense` is ignored in headless mode (there is no UI to gate);
+     * the production free-tier gate still applies. Native only.
+     *
+     * @default false
+     */
+    headless?: boolean;
 }
 /**
  * Unified floating development tools component with automatic preset discovery.
@@ -302,5 +316,5 @@ export interface FloatingDevToolsProps extends Omit<FloatingMenuProps, "apps"> {
  *
  * @param props - FloatingDevTools props
  */
-export declare const FloatingDevTools: ({ apps, requiredEnvVars, requiredStorageKeys, children, disableHints, defaultFloatingTools, defaultDialTools, requireLicense, licenseKey: licenseKeyProp, zustandStores, environment, externalSync, ...props }: FloatingDevToolsProps) => React.JSX.Element | null;
+export declare const FloatingDevTools: ({ apps, requiredEnvVars, requiredStorageKeys, children, disableHints, defaultFloatingTools, defaultDialTools, requireLicense, licenseKey: licenseKeyProp, zustandStores, environment, externalSync, headless, ...props }: FloatingDevToolsProps) => React.JSX.Element | null;
 //# sourceMappingURL=FloatingDevTools.d.ts.map

package/lib/typescript/commonjs/floatingMenu/FloatingDevTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FloatingDevTools.d.ts","sourceRoot":"","sources":["../../../../src/floatingMenu/FloatingDevTools.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+D,MAAM,OAAO,CAAC;AAGpF,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAMtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN;IACE,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,KAAK,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAC5E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,YAAY,EAAE,CAAC;IAEjC;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE3B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;;;;;;OAaG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,CAAC;IAE7C;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IAErC;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,OAAO,oBAAoB,EAAE,WAAW,EAAE,CAAC;IAEnE;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,oBAAoB,EAAE,WAAW,KAAK,IAAI,CAAC;IAEtF;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,gBAAgB,GAAI,gNAc9B,qBAAqB,6BAoQvB,CAAC"}
+{"version":3,"file":"FloatingDevTools.d.ts","sourceRoot":"","sources":["../../../../src/floatingMenu/FloatingDevTools.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+D,MAAM,OAAO,CAAC;AAGpF,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAMtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK5C,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN;IACE,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,KAAK,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAC5E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,YAAY,EAAE,CAAC;IAEjC;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE3B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;;;;;;OAaG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,CAAC;IAE7C;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IAErC;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,OAAO,oBAAoB,EAAE,WAAW,EAAE,CAAC;IAEnE;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,oBAAoB,EAAE,WAAW,KAAK,IAAI,CAAC;IAEtF;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,gBAAgB,GAAI,0NAe9B,qBAAqB,6BAmSvB,CAAC"}