@buoy-gg/core 7.0.22 → 7.0.24

package/bin/buoy.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * The `buoy` CLI.
+ *
+ * Ships as a bin on @buoy-gg/core rather than its own package so that
+ * `npx buoy login` resolves from the project's own node_modules — anyone who
+ * already installed Buoy has it, with nothing extra to install and no npm
+ * package name to own.
+ *
+ * Plain CommonJS with ZERO dependencies, on purpose: it runs via npx inside
+ * someone else's project, so every dependency would be an install-time cost and
+ * a supply-chain surface for a tool whose entire job takes ten seconds.
+ */
+
+'use strict';
+
+const http = require('node:http');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+
+const SITE = process.env.BUOY_SITE_URL || 'https://buoy.gg';
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+const ESC = '\x1b[';
+const color = (code) => (s) => `${ESC}${code}m${s}${ESC}0m`;
+const cyan = color(36);
+const green = color(32);
+const red = color(31);
+const dim = color(2);
+const bold = color(1);
+
+function log(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+function fail(msg) {
+  process.stderr.write(`${red('x')} ${msg}\n`);
+  process.exit(1);
+}
+
+/**
+ * Open a URL in the user's default browser.
+ *
+ * Failure is not fatal: headless boxes, SSH sessions and locked-down machines
+ * all land here, and the URL is printed regardless so it can be opened by hand.
+ */
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'cmd'
+        : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    /* the URL is printed either way */
+  }
+}
+
+/**
+ * Which env var name this project can actually read.
+ *
+ * Expo only inlines `EXPO_PUBLIC_`-prefixed vars into the bundle, so writing a
+ * bare `BUOY_KEY` there produces a file that looks correct and silently does
+ * nothing — the most likely way this whole flow could waste someone's evening.
+ */
+function detectEnvVarName(root) {
+  try {
+    const pkgPath = path.join(root, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+      if (deps.expo) return 'EXPO_PUBLIC_BUOY_KEY';
+    }
+    if (
+      fs.existsSync(path.join(root, 'app.config.js')) ||
+      fs.existsSync(path.join(root, 'app.config.ts'))
+    ) {
+      return 'EXPO_PUBLIC_BUOY_KEY';
+    }
+    const appJson = path.join(root, 'app.json');
+    if (fs.existsSync(appJson)) {
+      const parsed = JSON.parse(fs.readFileSync(appJson, 'utf8'));
+      if (parsed && parsed.expo) return 'EXPO_PUBLIC_BUOY_KEY';
+    }
+  } catch {
+    /* fall through to the generic name */
+  }
+  return 'BUOY_KEY';
+}
+
+/** Upsert `NAME=value` in .env.local, preserving everything else in the file. */
+function writeEnvVar(root, name, value) {
+  const file = path.join(root, '.env.local');
+  let contents = '';
+  try {
+    contents = fs.readFileSync(file, 'utf8');
+  } catch {
+    /* new file */
+  }
+
+  const line = `${name}=${value}`;
+  const pattern = new RegExp('^' + name + '=.*$', 'm');
+
+  if (pattern.test(contents)) {
+    contents = contents.replace(pattern, line);
+  } else {
+    if (contents && !contents.endsWith('\n')) contents += '\n';
+    contents += `${line}\n`;
+  }
+
+  fs.writeFileSync(file, contents, { mode: 0o600 });
+  return file;
+}
+
+/**
+ * Make sure .env.local is ignored.
+ *
+ * The whole point of a per-developer key is that it identifies one person; a
+ * key committed to a shared repo turns the count back into "repos", which is
+ * exactly what this flow exists to avoid.
+ */
+function ensureGitignored(root) {
+  const file = path.join(root, '.gitignore');
+  let contents = '';
+  try {
+    contents = fs.readFileSync(file, 'utf8');
+  } catch {
+    return false;
+  }
+  if (/^\.env\.local$|^\.env\*|^\*\.local$/m.test(contents)) return false;
+
+  if (contents && !contents.endsWith('\n')) contents += '\n';
+  contents += '\n# Buoy license key (per developer - do not commit)\n.env.local\n';
+  fs.writeFileSync(file, contents);
+  return true;
+}
+
+/**
+ * Loopback auth.
+ *
+ * The browser does the signing in (it already holds the Clerk session), then
+ * hands the key back to a short-lived server on 127.0.0.1. Chosen over a
+ * device-code flow because it needs no server-side pending-code state, and over
+ * redirecting with the key in the URL because that would write a credential
+ * into browser history.
+ */
+function awaitKeyFromBrowser() {
+  return new Promise((resolve, reject) => {
+    const state = crypto.randomBytes(16).toString('hex');
+
+    const server = http.createServer((req, res) => {
+      // The page runs on buoy.gg and posts here cross-origin.
+      if (req.headers.origin === SITE) {
+        res.setHeader('Access-Control-Allow-Origin', SITE);
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+      }
+
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204).end();
+        return;
+      }
+      if (req.method !== 'POST') {
+        res.writeHead(405).end();
+        return;
+      }
+
+      let body = '';
+      req.on('data', (chunk) => {
+        body += chunk;
+        // A local server that accepts unbounded input is a local server that
+        // can be made to eat all your memory.
+        if (body.length > 4096) req.destroy();
+      });
+      req.on('end', () => {
+        let parsed = {};
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          /* handled by the check below */
+        }
+
+        // Any page in any tab can POST to localhost. The nonce is what proves
+        // this response belongs to the login WE just started.
+        if (parsed.state !== state || typeof parsed.key !== 'string' || !parsed.key) {
+          res.writeHead(400).end();
+          return;
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end('{"ok":true}');
+        server.close();
+        resolve({
+          key: parsed.key.trim(),
+          tier: parsed.tier || 'free',
+          email: parsed.email || '',
+        });
+      });
+    });
+
+    server.on('error', reject);
+
+    // Port 0 = let the OS pick. Bound to loopback only, so nothing on the
+    // network can reach it.
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      const url = `${SITE}/cli/login?port=${port}&state=${state}`;
+
+      log('');
+      log(`  Opening ${cyan(url)}`);
+      log(dim('  If your browser did not open, paste that URL into it.'));
+      log('');
+      log(dim('  Waiting for you to finish signing in...'));
+
+      openBrowser(url);
+    });
+
+    setTimeout(() => {
+      server.close();
+      reject(new Error('Timed out waiting for the browser (5 minutes).'));
+    }, LOGIN_TIMEOUT_MS).unref();
+  });
+}
+
+async function login() {
+  const root = process.cwd();
+
+  let result;
+  try {
+    result = await awaitKeyFromBrowser();
+  } catch (err) {
+    fail(`${err.message}\n  Nothing was written.`);
+    return;
+  }
+
+  const varName = detectEnvVarName(root);
+  const file = writeEnvVar(root, varName, result.key);
+  const addedIgnore = ensureGitignored(root);
+  const relative = path.relative(root, file) || '.env.local';
+
+  log('');
+  log(
+    `${green('OK')} Signed in${result.email ? ' as ' + bold(result.email) : ''} - ${bold(result.tier)} tier`
+  );
+  log(`  Wrote ${cyan(varName)} to ${cyan(relative)}`);
+  if (addedIgnore) log(dim('  Added .env.local to .gitignore'));
+  log('');
+  log('  Use it in your app:');
+  log('');
+  log(cyan(`    Buoy.init({ licenseKey: process.env.${varName} });`));
+  log('');
+  log(dim('  Restart your bundler for the new env var to take effect.'));
+  log('');
+}
+
+function help() {
+  log(`
+  ${bold('buoy')} - React Buoy CLI
+
+  ${bold('Usage')}
+    npx buoy <command>
+    npx --package=@buoy-gg/core buoy <command>   ${dim('(if npx picks the wrong one)')}
+
+  ${bold('Commands')}
+    login     Sign in and write your license key to .env.local
+    help      Show this message
+
+  ${bold('Notes')}
+    A free key takes about thirty seconds and needs no card. Paid keys use the
+    same command - it writes whichever key your account already holds.
+
+    Docs: ${SITE}/buoy/latest/docs/installation
+`);
+}
+
+// Only dispatch when run as a program. Without this guard, importing the file
+// in a test would parse the test runner's own argv and exit the process.
+if (require.main === module) {
+  const command = process.argv[2];
+
+  if (command === 'login') {
+    login();
+  } else if (!command || command === 'help' || command === '--help' || command === '-h') {
+    help();
+  } else {
+    fail(`Unknown command: ${command}\n  Run \`npx buoy help\` to see what is available.`);
+  }
+}
+
+module.exports = {
+  detectEnvVarName,
+  writeEnvVar,
+  ensureGitignored,
+  awaitKeyFromBrowser,
+};

package/lib/commonjs/Buoy.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = exports.Buoy = void 0;
+exports.isTelemetryEnabled = isTelemetryEnabled;
 var _license = require("@buoy-gg/license");
 /**
  * Buoy SDK - Main entry point for React Buoy configuration
@@ -20,6 +21,17 @@ var _license = require("@buoy-gg/license");
  * ```
  */
 
+/**
+ * Telemetry stays on unless an app explicitly opts out. Read at ping time
+ * rather than captured, so `Buoy.init()` still wins if it runs after mount.
+ */
+let telemetryEnabled = true;
+
+/** Whether the anonymous install ping is allowed to fire. */
+function isTelemetryEnabled() {
+  return telemetryEnabled;
+}
+
 /**
  * Buoy SDK namespace
  *
@@ -48,6 +60,8 @@ const Buoy = exports.Buoy = {
    * ```
    */
   init(config) {
+    if (config.telemetry === false) telemetryEnabled = false;
+
     // If no license key or empty string, clear any cached license
     if (!config.licenseKey || config.licenseKey.trim() === "") {
       _license.LicenseManager.initialize().then(() => _license.LicenseManager.clearLicense()).catch(() => {});

package/lib/commonjs/floatingMenu/FloatingDevTools.js

@@ -9,6 +9,8 @@ var _reactNative = require("react-native");
 var _AppHost = require("./AppHost");
 var _FloatingMenu = require("./FloatingMenu.js");
 var _autoDiscoverPresets = require("./autoDiscoverPresets.js");
+var _installPing = require("../telemetry/installPing.js");
+var _Buoy = require("../Buoy.js");
 var _AppIcon = require("./AppIcon.js");
 var _DevToolsVisibilityContext = require("./DevToolsVisibilityContext.js");
 var _optionalRequire = require("./optionalRequire.js");
@@ -18,6 +20,7 @@ var _defaultConfig = require("./defaultConfig.js");
 var _DefaultConfigContext = require("./DefaultConfigContext.js");
 var _license = require("@buoy-gg/license");
 var _autoExternalSync = require("./autoExternalSync.js");
+var _externalSyncGate = require("./externalSyncGate.js");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
@@ -133,8 +136,20 @@ const FloatingDevTools = ({
   // Get full license state for requireLicense gating
   const {
     licenseKey,
-    isInitialized
+    isInitialized,
+    tier
   } = (0, _license.useLicense)();
+
+  // Anonymous install ping — dev-only, once a day, no project or tool data.
+  // Deliberately waits for the license to resolve so the tier it reports is
+  // the real one rather than the "anonymous" the manager starts at.
+  (0, _react.useEffect)(() => {
+    if (!isInitialized) return;
+    void (0, _installPing.sendInstallPing)({
+      tier,
+      enabled: (0, _Buoy.isTelemetryEnabled)()
+    });
+  }, [isInitialized, tier]);
   const [showLicenseModal, setShowLicenseModal] = (0, _react.useState)(false);
 
   // Initialize license manager on mount, and set/clear license key when prop changes.
@@ -379,25 +394,47 @@ const FloatingDevTools = ({
     });
   }, [finalApps]);
 
-  // Gate: Free tier only works in development mode
-  // Pro users can use DevTools everywhere (dev + production)
+  // Gate: only a PAID license works outside development.
+  //
+  // Both untiered surfaces below it — anonymous (no key) and free (a key on the
+  // Free policy) — stay dev-only. `isLicensed` is safe to gate on because
+  // `isPro` is a strict mirror of `tier === "pro"`, so a free key reports false
+  // here even though it validates perfectly well.
+  //
+  // When Business on-device login lands, this becomes the boundary that a
+  // logged-in QA/support seat crosses WITHOUT a key in the build — i.e.
+  // `isLicensed || tierSource === "session"`. Nothing else should.
   const isDevelopment = typeof __DEV__ !== "undefined" && __DEV__;
   if (!isDevelopment && !isLicensed) {
-    // Free user in production - don't render DevTools
+    // Anonymous or free user in production - don't render DevTools.
+    // NOTE for whoever relaxes this for the free tier: desktop sync does NOT
+    // ride on this check. It re-tests `isLicensed` itself (externalSyncGate),
+    // so opening this door does not open a broker socket. Keep it that way.
     return null;
   }
 
+  // Zero-config in dev; in a release bundle the app must opt in explicitly
+  // (externalSync.enableInRelease) AND hold a real Pro license — see
+  // externalSyncGate.ts for why both halves are required.
+  const syncEnabled = (0, _externalSyncGate.shouldMountExternalSync)({
+    isDevelopment,
+    isLicensed,
+    externalSync,
+    isAvailable: (0, _autoExternalSync.isExternalSyncAvailable)()
+  });
+
   // 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).
+  // AutoExternalSync still obeys `syncEnabled` (the broker must never be
+  // contacted from a shipped build that didn't ask for it).
   if (headless) {
     return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-      children: [ReduxAutoInstrument && /*#__PURE__*/(0, _jsxRuntime.jsx)(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/(0, _jsxRuntime.jsx)(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/(0, _jsxRuntime.jsx)(RouteTracker, {}), isDevelopment && externalSync !== false && (0, _autoExternalSync.isExternalSyncAvailable)() && /*#__PURE__*/(0, _jsxRuntime.jsx)(_autoExternalSync.AutoExternalSync, {
-        options: typeof externalSync === "object" ? externalSync : undefined,
+      children: [ReduxAutoInstrument && /*#__PURE__*/(0, _jsxRuntime.jsx)(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/(0, _jsxRuntime.jsx)(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/(0, _jsxRuntime.jsx)(RouteTracker, {}), syncEnabled && /*#__PURE__*/(0, _jsxRuntime.jsx)(_autoExternalSync.AutoExternalSync, {
+        options: (0, _externalSyncGate.externalSyncOptions)(externalSync),
         requiredEnvVars: requiredEnvVars,
         isPro: isLicensed,
+        tier: tier,
         licenseKey: licenseKey,
         customApps: syncApps
       })]
@@ -435,10 +472,11 @@ const FloatingDevTools = ({
                 environment: resolvedEnvironment
               }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_AppHost.AppOverlay, {})]
             })
-          }), children, DebugBordersOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(DebugBordersOverlay, {}), HighlightUpdatesOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(HighlightUpdatesOverlay, {}), ImageOverlayOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(ImageOverlayOverlay, {}), PerfMonitorOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(PerfMonitorOverlay, {}), JsTopOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(JsTopOverlay, {}), ImpersonateOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(ImpersonateOverlay, {}), ReduxAutoInstrument && /*#__PURE__*/(0, _jsxRuntime.jsx)(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/(0, _jsxRuntime.jsx)(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/(0, _jsxRuntime.jsx)(RouteTracker, {}), isDevelopment && externalSync !== false && (0, _autoExternalSync.isExternalSyncAvailable)() && /*#__PURE__*/(0, _jsxRuntime.jsx)(_autoExternalSync.AutoExternalSync, {
-            options: typeof externalSync === "object" ? externalSync : undefined,
+          }), children, DebugBordersOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(DebugBordersOverlay, {}), HighlightUpdatesOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(HighlightUpdatesOverlay, {}), ImageOverlayOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(ImageOverlayOverlay, {}), PerfMonitorOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(PerfMonitorOverlay, {}), JsTopOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(JsTopOverlay, {}), ImpersonateOverlay && /*#__PURE__*/(0, _jsxRuntime.jsx)(ImpersonateOverlay, {}), ReduxAutoInstrument && /*#__PURE__*/(0, _jsxRuntime.jsx)(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/(0, _jsxRuntime.jsx)(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/(0, _jsxRuntime.jsx)(RouteTracker, {}), syncEnabled && /*#__PURE__*/(0, _jsxRuntime.jsx)(_autoExternalSync.AutoExternalSync, {
+            options: (0, _externalSyncGate.externalSyncOptions)(externalSync),
             requiredEnvVars: requiredEnvVars,
             isPro: isLicensed,
+            tier: tier,
             licenseKey: licenseKey,
             customApps: syncApps
           })]

package/lib/commonjs/floatingMenu/ToolHost.js

@@ -30,6 +30,7 @@ const FALLBACK_CONTEXT = {
   isSearchActive: false,
   clearSearch: noop,
   close: noop,
+  minimize: noop,
   showToast: noop,
   setHeaderOverride: noop
 };
@@ -160,10 +161,13 @@ function ToolModalShell({
     isSearchActive,
     clearSearch,
     close: onClose,
+    // Bare call: JsModal persists its own dimensions, so restoring brings
+    // the tool back the size the user last left it.
+    minimize: () => onMinimize(),
     showToast,
     setHeaderOverride,
     instanceId: app.instanceId
-  }), [search, isSearchActive, clearSearch, onClose, showToast, app.instanceId]);
+  }), [search, isSearchActive, clearSearch, onClose, onMinimize, showToast, app.instanceId]);
   const title = headerOverride?.title ?? config.title ?? app.title ?? app.id;
   const subtitle = headerOverride?.subtitle ?? config.subtitle;
   const onBack = headerOverride?.onBack;

package/lib/commonjs/floatingMenu/autoExternalSync.js

@@ -13,12 +13,13 @@ var _appSyncAdapter = require("./sync/appSyncAdapter.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
- * (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.
+ * <AutoExternalSync /> in dev builds (and in release builds that opted in via
+ * externalSync.enableInRelease — see externalSyncGate.ts): it connects to the
+ * Buoy Desktop broker (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.
  *
  * Identity defaults come from expo-constants when available (app name →
  * "MyApp (ios)" / "myapp-ios"), overridable via the `externalSync` prop.
@@ -180,6 +181,7 @@ function AutoExternalSync({
   options,
   requiredEnvVars,
   isPro,
+  tier,
   licenseKey,
   customApps
 }) {
@@ -213,10 +215,12 @@ function AutoExternalSync({
   // record and rebroadcasts, so the desktop dashboard can auto-adopt the key.
   const licenseRef = (0, _react.useRef)({
     isPro,
+    tier,
     licenseKey
   });
   licenseRef.current = {
     isPro,
+    tier,
     licenseKey
   };
   (0, _react.useEffect)(() => {
@@ -224,6 +228,8 @@ function AutoExternalSync({
     const emitLicense = () => {
       socket.emit("device-license", {
         isPro: licenseRef.current.isPro ? "1" : "0",
+        // Brokers older than the tier split ignore this; newer ones prefer it.
+        tier: licenseRef.current.tier ?? (licenseRef.current.isPro ? "pro" : "anonymous"),
         licenseKey: licenseRef.current.licenseKey ?? ""
       });
     };
@@ -232,7 +238,7 @@ function AutoExternalSync({
     return () => {
       socket.off("connect", emitLicense);
     };
-  }, [socket, isPro, licenseKey]);
+  }, [socket, isPro, tier, licenseKey]);
   const tools = (0, _react.useMemo)(() => {
     // Core's own adapter — device-level capabilities (JS-bundle reload) that
     // don't belong to any tool package. Registered unconditionally so remote

package/lib/commonjs/floatingMenu/externalSyncGate.js

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.externalSyncOptions = externalSyncOptions;
+exports.shouldMountExternalSync = shouldMountExternalSync;
+/**
+ * Decides whether FloatingDevTools mounts <AutoExternalSync /> — i.e. whether
+ * this build is allowed to dial the Buoy Desktop broker.
+ *
+ * Kept as a pure function in its own module (no react-native / no guarded
+ * requires) so the rule is unit-testable: the gate used to be an inline
+ * `isDevelopment && ...` in JSX, which silently made release builds unable to
+ * reach the desktop dashboard or MCP with no way to opt in from app code.
+ *
+ * The rule has two halves that must BOTH hold in a release build, because a
+ * shipped app must never contact a broker on an end user's device:
+ *   1. a real Pro license (never the Weekend Pass — see useProAccess), and
+ *   2. an EXPLICIT opt-in from app code (`externalSync.enableInRelease`).
+ * Dev builds keep the zero-config behavior: sync is on unless turned off.
+ */
+
+/** The options object from the prop, or undefined when it's a boolean. */
+function externalSyncOptions(externalSync) {
+  return typeof externalSync === "object" && externalSync !== null ? externalSync : undefined;
+}
+function shouldMountExternalSync({
+  isDevelopment,
+  isLicensed,
+  externalSync,
+  isAvailable
+}) {
+  // Turned off outright, or the package isn't installed — nothing to mount.
+  if (externalSync === false) return false;
+  if (!isAvailable) return false;
+
+  // Dev builds: zero-config, on by default (historical behavior).
+  if (isDevelopment) return true;
+
+  // Release builds: opt-in only, and Pro only. `enableInRelease` has to be set
+  // by the app itself, so an app that just ships FloatingDevTools with a Pro
+  // key still never opens a socket on a customer's phone.
+  //
+  // The `isLicensed` half is belt-and-braces: FloatingDevTools already renders
+  // nothing at all for an unlicensed release build. Keep it anyway so this rule
+  // stands on its own and can't be broken by a change to that earlier return.
+  return isLicensed && externalSyncOptions(externalSync)?.enableInRelease === true;
+}