@buoy-gg/shared-ui 7.0.4 → 7.0.6

package/lib/commonjs/ui/components/ErrorBoundary.js

@@ -7,6 +7,7 @@ exports.ErrorBoundary = void 0;
 var _react = require("react");
 var _reactNative = require("react-native");
 var _index = require("../../icons/index.js");
+var _gameUIColors = require("../gameUI/constants/gameUIColors.js");
 var _jsxRuntime = require("react/jsx-runtime");
 class ErrorBoundary extends _react.Component {
   constructor(props) {
@@ -69,7 +70,7 @@ class ErrorBoundary extends _react.Component {
 exports.ErrorBoundary = ErrorBoundary;
 const styles = _reactNative.StyleSheet.create({
   errorContainer: {
-    backgroundColor: "#171717",
+    backgroundColor: _gameUIColors.buoyColors.card,
     borderRadius: 6,
     borderWidth: 1,
     borderColor: "#EF4444",
@@ -87,7 +88,7 @@ const styles = _reactNative.StyleSheet.create({
     fontWeight: "600"
   },
   errorMessage: {
-    color: "#9CA3AF",
+    color: _gameUIColors.buoyColors.textSecondary,
     fontSize: 12,
     textAlign: "center",
     lineHeight: 16

package/lib/commonjs/ui/components/EventHistoryViewer/EventHistoryViewer.js

@@ -21,6 +21,30 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * This is a dumb component - all state is controlled externally.
  */
 
+/**
+ * Section wrapper for the diff view: a plain flex box normally, or a ScrollView
+ * when the whole section should scroll as one page. Split out so the children
+ * are written once instead of duplicated across both branches.
+ */
+function DiffSectionContainer({
+  scrolls,
+  style,
+  children
+}) {
+  if (!scrolls) return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: style,
+    children: children
+  });
+  // `contentSection` carries `flex: 1`, which is meaningless (and harmful) on a
+  // content container — the scrolling variant uses flexGrow padding instead.
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
+    style: styles.contentScroll,
+    contentContainerStyle: styles.contentScrollInner,
+    showsVerticalScrollIndicator: true,
+    children: children
+  });
+}
+
 /**
  * EventHistoryViewer is the main container for viewing event history.
  * It composes sub-components to display current value or diff views.
@@ -56,6 +80,7 @@ const EventHistoryViewer = exports.EventHistoryViewer = /*#__PURE__*/(0, _react.
   canRightNext,
   onLeftPickerOpen,
   onRightPickerOpen,
+  scrollDiffSection,
   // Footer
   disableInternalFooter,
   footerCurrentIndex,
@@ -65,28 +90,36 @@ const EventHistoryViewer = exports.EventHistoryViewer = /*#__PURE__*/(0, _react.
   onFooterPrevious,
   onFooterNext
 }) {
+  const hasCurrentView = renderCurrentView != null;
   const diffDisabled = footerTotalItems <= 1;
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
     children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
       style: [styles.container, {
-        // Add padding when footer is shown (internal or external via modal)
-        paddingBottom: footerTotalItems > 1 ? 96 : 0
+        // Reserve space ONLY for the internal footer, which is absolutely
+        // positioned and would otherwise cover the content. An external
+        // footer is laid out by the host modal, which already pads the
+        // content area by its own footerHeight — adding this on top of that
+        // left a dead band above the footer (96px of padding for a footer
+        // that isn't in this subtree).
+        paddingBottom: !disableInternalFooter && footerTotalItems > 1 ? 96 : 0
       }],
-      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_ViewToggleCards.ViewToggleCards, {
+      children: [hasCurrentView && /*#__PURE__*/(0, _jsxRuntime.jsx)(_ViewToggleCards.ViewToggleCards, {
         activeView: activeView,
-        onViewChange: onViewChange,
-        currentLabel: currentViewLabel,
-        currentDescription: currentViewDescription,
+        onViewChange: onViewChange ?? (() => {}),
+        currentLabel: currentViewLabel ?? "",
+        currentDescription: currentViewDescription ?? "",
         currentIcon: currentViewIcon,
         diffLabel: diffViewLabel,
         diffDescription: diffViewDescription,
         diffIcon: diffViewIcon,
         diffDisabled: diffDisabled
-      }), activeView === "current" && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
-        style: styles.contentSection,
+      }), hasCurrentView && activeView === "current" && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
+        style: styles.contentScroll,
+        contentContainerStyle: styles.contentScrollInner,
         showsVerticalScrollIndicator: true,
-        children: renderCurrentView()
-      }), activeView === "diff" && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        children: renderCurrentView?.()
+      }), (!hasCurrentView || activeView === "diff") && /*#__PURE__*/(0, _jsxRuntime.jsxs)(DiffSectionContainer, {
+        scrolls: scrollDiffSection,
         style: styles.contentSection,
         children: [diffModeTabs && diffModeTabs.length > 0 && onDiffModeChange && /*#__PURE__*/(0, _jsxRuntime.jsx)(_DiffModeTabs.DiffModeTabs, {
           tabs: diffModeTabs,
@@ -106,7 +139,10 @@ const EventHistoryViewer = exports.EventHistoryViewer = /*#__PURE__*/(0, _react.
           canRightNext: canRightNext,
           onLeftPress: onLeftPickerOpen,
           onRightPress: onRightPickerOpen
-        }), renderDiffContent()]
+        }), scrollDiffSection ? renderDiffContent() : /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+          style: styles.diffContent,
+          children: renderDiffContent()
+        })]
       })]
     }), !disableInternalFooter && /*#__PURE__*/(0, _jsxRuntime.jsx)(_EventStepperFooter.EventStepperFooter, {
       currentIndex: footerCurrentIndex,
@@ -126,7 +162,23 @@ const styles = _reactNative.StyleSheet.create({
   },
   contentSection: {
     flex: 1,
+    minHeight: 0,
     paddingHorizontal: 14,
     paddingVertical: 10
+  },
+  contentScroll: {
+    // No `minHeight: 0` here. On the scroll frame it stops the ScrollView from
+    // constraining itself, so a tall value lays out at full content height and
+    // spills past the panel and the footer instead of scrolling inside it.
+    flex: 1
+  },
+  contentScrollInner: {
+    flexGrow: 1,
+    paddingHorizontal: 14,
+    paddingVertical: 10
+  },
+  diffContent: {
+    flex: 1,
+    minHeight: 0
   }
 });

package/lib/commonjs/ui/components/ExpandableSection.js

@@ -7,6 +7,7 @@ exports.ExpandableSection = ExpandableSection;
 var _react = require("react");
 var _reactNative = require("react-native");
 var _ExpandableSectionHeader = require("./ExpandableSectionHeader.js");
+var _macOSDesignSystemColors = require("../gameUI/constants/macOSDesignSystemColors.js");
 var _jsxRuntime = require("react/jsx-runtime");
 function ExpandableSection({
   icon,
@@ -51,10 +52,10 @@ function ExpandableSection({
 }
 const styles = _reactNative.StyleSheet.create({
   container: {
-    backgroundColor: "#1F1F1F",
+    backgroundColor: _macOSDesignSystemColors.macOSColors.background.card,
     borderRadius: 12,
     borderWidth: 1,
-    borderColor: "rgba(255, 255, 255, 0.08)",
+    borderColor: "rgba(128, 128, 128, 0.16)",
     overflow: "hidden",
     marginHorizontal: 8,
     marginBottom: 16
@@ -65,7 +66,7 @@ const styles = _reactNative.StyleSheet.create({
   divider: {
     height: 1,
     width: "100%",
-    backgroundColor: "rgba(255, 255, 255, 0.06)",
+    backgroundColor: "rgba(128, 128, 128, 0.12)",
     marginBottom: 24
   }
 });

package/lib/commonjs/ui/components/ExpandableSectionHeader.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.ExpandableSectionHeader = ExpandableSectionHeader;
 var _reactNative = require("react-native");
 var _index = require("../../icons/index.js");
+var _gameUIColors = require("../gameUI/constants/gameUIColors.js");
 var _jsxRuntime = require("react/jsx-runtime");
 function ExpandableSectionHeader({
   icon: Icon,
@@ -78,7 +79,7 @@ const styles = _reactNative.StyleSheet.create({
   },
   subtitle: {
     fontSize: 16,
-    color: "#9CA3AF"
+    color: _gameUIColors.buoyColors.textSecondary
   },
   chevronContainer: {
     paddingTop: 6

package/lib/commonjs/ui/components/FilterViewPattern.js

@@ -7,6 +7,7 @@ exports.FilterViewPattern = FilterViewPattern;
 var _reactNative = require("react-native");
 var _index = require("../../icons/index.js");
 var _gameUIColors = require("../gameUI/constants/gameUIColors.js");
+var _macOSDesignSystemColors = require("../gameUI/constants/macOSDesignSystemColors.js");
 var _useFilterManager = require("../../hooks/useFilterManager.js");
 var _FilterComponents = require("./FilterComponents.js");
 var _jsxRuntime = require("react/jsx-runtime");
@@ -122,17 +123,17 @@ const styles = _reactNative.StyleSheet.create({
     backgroundColor: "transparent"
   },
   suggestedContainer: {
-    backgroundColor: "rgba(255, 255, 255, 0.03)",
+    backgroundColor: "rgba(128, 128, 128, 0.06)",
     borderRadius: 8,
     padding: 12,
     marginBottom: 16,
     maxHeight: 300,
     borderWidth: 1,
-    borderColor: "rgba(255, 255, 255, 0.08)"
+    borderColor: "rgba(128, 128, 128, 0.16)"
   },
   suggestedTitle: {
     fontSize: 10,
-    color: "#6B7280",
+    color: _macOSDesignSystemColors.macOSColors.text.icon,
     fontWeight: "600",
     letterSpacing: 0.5,
     marginBottom: 12,
@@ -144,24 +145,24 @@ const styles = _reactNative.StyleSheet.create({
   suggestedItem: {
     flexDirection: "row",
     alignItems: "center",
-    backgroundColor: "rgba(255, 255, 255, 0.02)",
+    backgroundColor: "rgba(128, 128, 128, 0.04)",
     borderRadius: 6,
     paddingHorizontal: 10,
     paddingVertical: 10,
     marginBottom: 6,
     borderWidth: 1,
-    borderColor: "rgba(255, 255, 255, 0.05)"
+    borderColor: "rgba(128, 128, 128, 0.1)"
   },
   suggestedText: {
     flex: 1,
     fontSize: 12,
-    color: "#E5E7EB",
+    color: _gameUIColors.buoyColors.text,
     fontFamily: "monospace",
     marginLeft: 4
   },
   emptyText: {
     fontSize: 11,
-    color: "#6B7280",
+    color: _macOSDesignSystemColors.macOSColors.text.icon,
     fontStyle: "italic",
     padding: 12,
     textAlign: "center"

package/lib/commonjs/ui/components/ListItem.js

@@ -5,6 +5,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.ListItem = ListItem;
 var _reactNative = require("react-native");
+var _macOSDesignSystemColors = require("../gameUI/constants/macOSDesignSystemColors.js");
+var _gameUIColors = require("../gameUI/constants/gameUIColors.js");
 var _jsxRuntime = require("react/jsx-runtime");
 // Base ListItem container component
 
@@ -124,13 +126,13 @@ ListItem.Metadata = Metadata;
 ListItem.Actions = Actions;
 const styles = _reactNative.StyleSheet.create({
   container: {
-    backgroundColor: "#1A1A1A",
+    backgroundColor: _gameUIColors.buoyColors.card,
     borderRadius: 8,
     padding: 12,
     marginHorizontal: 16,
     marginVertical: 4,
     borderWidth: 1,
-    borderColor: "rgba(255, 255, 255, 0.05)"
+    borderColor: "rgba(128, 128, 128, 0.1)"
   },
   header: {
     flexDirection: "row",
@@ -150,17 +152,17 @@ const styles = _reactNative.StyleSheet.create({
   title: {
     fontSize: 16,
     fontWeight: "600",
-    color: "#E5E7EB",
+    color: _gameUIColors.buoyColors.text,
     marginBottom: 4
   },
   subtitle: {
     fontSize: 14,
-    color: "#9CA3AF",
+    color: _gameUIColors.buoyColors.textSecondary,
     lineHeight: 20
   },
   metadata: {
     fontSize: 12,
-    color: "#6B7280"
+    color: _macOSDesignSystemColors.macOSColors.text.icon
   },
   actions: {
     flexDirection: "row",

package/lib/commonjs/ui/components/PowerToggleButton.js

@@ -63,9 +63,12 @@ const styles = _reactNative.StyleSheet.create({
     backgroundColor: _macOSDesignSystemColors.macOSColors.semantic.successBackground,
     borderColor: _macOSDesignSystemColors.macOSColors.semantic.success + "40"
   },
+  // OFF stays red on both chromes: capture being disabled is exactly the kind
+  // of state the user needs to notice, so it keeps its colour.
   disabledButton: {
     backgroundColor: _macOSDesignSystemColors.macOSColors.semantic.errorBackground,
-    borderColor: _macOSDesignSystemColors.macOSColors.semantic.error + "40"
+    borderColor: _macOSDesignSystemColors.macOSColors.semantic.error + "40",
+    borderWidth: 1
   },
   buttonDisabled: {
     opacity: 0.55

package/lib/commonjs/ui/components/TabSelector.js

@@ -47,6 +47,9 @@ const styles = _reactNative.StyleSheet.create({
     flex: 1,
     marginHorizontal: 1
   },
+  /**
+   * The selected tab is marked with an accent ring.
+   */
   tabButtonActive: {
     backgroundColor: _gameUIColors.buoyColors.primary + "20",
     borderWidth: 1,

package/lib/commonjs/ui/console/CyberpunkConsoleSection.js

@@ -505,7 +505,7 @@ const styles = _reactNative.StyleSheet.create({
   },
   glassShimmer: {
     ..._absoluteFill.absoluteFill,
-    backgroundColor: "rgba(255, 255, 255, 0.03)",
+    backgroundColor: "rgba(128, 128, 128, 0.06)",
     opacity: 0.6
   },
   glitchOverlayLayer: {

package/lib/commonjs/ui/console/GalaxyButton.js

@@ -73,7 +73,7 @@ const styles = _reactNative.StyleSheet.create({
     backgroundColor: "rgba(31, 31, 31, 0.85)",
     borderRadius: 12,
     borderWidth: 1,
-    borderColor: "rgba(255, 255, 255, 0.12)",
+    borderColor: "rgba(128, 128, 128, 0.24)",
     overflow: "hidden"
   },
   starsContainer: {

package/lib/commonjs/ui/gameUI/components/GameUICompactStats.js

@@ -168,7 +168,7 @@ const styles = _reactNative.StyleSheet.create({
     marginBottom: 8,
     paddingBottom: 8,
     borderBottomWidth: 1,
-    borderBottomColor: "rgba(255, 255, 255, 0.05)"
+    borderBottomColor: "rgba(128, 128, 128, 0.1)"
   },
   headerLeft: {
     gap: 1
@@ -223,7 +223,7 @@ const styles = _reactNative.StyleSheet.create({
   },
   healthBarBg: {
     height: 4,
-    backgroundColor: "rgba(255, 255, 255, 0.05)",
+    backgroundColor: "rgba(128, 128, 128, 0.1)",
     borderRadius: 2,
     overflow: "hidden"
   },

package/lib/commonjs/ui/gameUI/constants/gameUIColors.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.gameUIColors = exports.dialColors = exports.buoyColors = void 0;
+exports.refreshGameUIColors = exports.gameUIColors = exports.dialColors = exports.buoyColors = void 0;
 var _macOSDesignSystemColors = require("./macOSDesignSystemColors.js");
 /**
  * Game UI Color Palette - Simple Theme Swapping
@@ -129,9 +129,18 @@ const activeTheme = macOSTheme; // macOS - Apple HIG design system
 // GAME UI COLORS (uses selected theme)
 // ============================================
 
-const gameUIColors = exports.gameUIColors = {
-  ...activeTheme,
-  // Defaults (dark-ish) which can be overridden by theme spreads
+/* NOTE ON KEY ORDER — the spread comes LAST on purpose.
+ *
+ * These seven keys are fallbacks for `defaultTheme`, which doesn't define them.
+ * They used to sit AFTER the spread, which meant they silently overrode the
+ * active theme: `background`/`panel`/`buttonBackground` stayed hardcoded dark
+ * and `primary`/`primaryLight` stayed hardcoded white, no matter what palette
+ * was selected, so a theme could not override them at all. With the spread
+ * last, an active theme that defines them wins and only `defaultTheme` falls
+ * back. */
+/** Fallbacks (dark-ish) for themes that don't define these keys — only
+ * `defaultTheme` needs them; `macOSTheme` supplies all seven. */
+const fallbacks = {
   background: "rgba(8, 12, 21, 0.98)",
   panel: "rgba(16, 22, 35, 0.98)",
   backdrop: "rgba(0, 0, 0, 0.85)",
@@ -140,9 +149,21 @@ const gameUIColors = exports.gameUIColors = {
   // Default text colors for dark background
   primary: "#FFFFFF",
   primaryLight: "#F1F5F9"
-
-  // Theme-specific colors (later spread overrides defaults when present)
 };
+const gameUIColors = exports.gameUIColors = {
+  ...fallbacks,
+  ...activeTheme
+};
+/** Re-derive the theme-driven values in place after `macOSColors` has been
+ * re-tinted at runtime (desktop dashboard theme switch only — see
+ * in place). Keeps object identity so every
+ * `gameUIColors.x` read at render time picks the new value up. Module-level
+ * captures (`const BG = gameUIColors.panel`) still need a reload. */
+const refreshGameUIColors = () => {
+  (0, _macOSDesignSystemColors.refreshMacOSGameUIColors)();
+  Object.assign(gameUIColors, activeTheme);
+};
+
 // ============================================
 // BUOY BRAND COLORS
 // ============================================
@@ -150,6 +171,7 @@ const gameUIColors = exports.gameUIColors = {
  * Buoy brand colors - EXACT values from web docs site dark theme.
  * Use these for consistent branding across all Buoy dev tools.
  */
+exports.refreshGameUIColors = refreshGameUIColors;
 const buoyColors = exports.buoyColors = {
   // Backgrounds (dark to light)
   base: "#121212",

package/lib/commonjs/ui/gameUI/constants/macOSDesignSystemColors.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.macOSGameUIColors = exports.macOSColors = void 0;
+exports.refreshMacOSGameUIColors = exports.macOSGameUIColors = exports.macOSColors = void 0;
 /**
  * macOS Desktop App Design System Colors
  * Based on Apple's Human Interface Guidelines with a dark-mode-first approach
@@ -160,8 +160,14 @@ const macOSColors = exports.macOSColors = {
   }
 };
 
-// Create a compatible gameUIColors object for gradual migration
-const macOSGameUIColors = exports.macOSGameUIColors = {
+/* `macOSGameUIColors` is a DERIVED SNAPSHOT: every field below copies a string
+ * value out of `macOSColors` at module-evaluation time, so later edits to
+ * `macOSColors` do not reach it. The desktop dashboard re-tints the palette by
+ * mutating `macOSColors` in place,
+ * which is why the snapshot is built by a factory and can be refreshed with
+ * `refreshMacOSGameUIColors()`. Nested objects (`dataTypes`, `diff`) are shared
+ * REFERENCES, not copies, so those already follow a re-tint on their own. */
+const buildMacOSGameUIColors = () => ({
   // Base backgrounds
   background: macOSColors.background.base,
   panel: macOSColors.background.card,
@@ -203,4 +209,16 @@ const macOSGameUIColors = exports.macOSGameUIColors = {
     secondary: macOSColors.semantic.debug,
     tertiary: macOSColors.semantic.success
   }
-};
+});
+
+// Create a compatible gameUIColors object for gradual migration
+const macOSGameUIColors = exports.macOSGameUIColors = buildMacOSGameUIColors();
+
+/** Re-derive the snapshot above from the current `macOSColors` values, keeping
+ * the object identity so existing importers see the new colors. Only the
+ * desktop dashboard's theme switcher calls this; on device the palette never
+ * changes, so this is a no-op that is never invoked. */
+const refreshMacOSGameUIColors = () => {
+  Object.assign(macOSGameUIColors, buildMacOSGameUIColors());
+};
+exports.refreshMacOSGameUIColors = refreshMacOSGameUIColors;

package/lib/commonjs/utils/index.js

@@ -3,6 +3,12 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "REMOTE_RELOAD_DELAY_MS", {
+  enumerable: true,
+  get: function () {
+    return _reloadApp.REMOTE_RELOAD_DELAY_MS;
+  }
+});
 Object.defineProperty(exports, "Subscribable", {
   enumerable: true,
   get: function () {
@@ -165,12 +171,30 @@ Object.defineProperty(exports, "persistentStorage", {
     return _persistentStorage.persistentStorage;
   }
 });
+Object.defineProperty(exports, "reloadApp", {
+  enumerable: true,
+  get: function () {
+    return _reloadApp.reloadApp;
+  }
+});
+Object.defineProperty(exports, "resolveReloadStrategy", {
+  enumerable: true,
+  get: function () {
+    return _reloadApp.resolveReloadStrategy;
+  }
+});
 Object.defineProperty(exports, "safeStringify", {
   enumerable: true,
   get: function () {
     return _safeStringify.safeStringify;
   }
 });
+Object.defineProperty(exports, "scheduleReloadApp", {
+  enumerable: true,
+  get: function () {
+    return _reloadApp.scheduleReloadApp;
+  }
+});
 Object.defineProperty(exports, "setRenderCaptureProvider", {
   enumerable: true,
   get: function () {
@@ -228,6 +252,7 @@ var _typeHelpers = require("./typeHelpers.js");
 var _valueFormatting = require("./valueFormatting.js");
 var _loadOptionalModule = require("./loadOptionalModule.js");
 var _renderCaptureRegistry = require("./renderCaptureRegistry.js");
+var _reloadApp = require("./reloadApp.js");
 var _subscribable = require("./subscribable.js");
 var _subscriberCountNotifier = require("./subscriberCountNotifier.js");
 var _safeExpoRouter = require("./safeExpoRouter.js");

package/lib/commonjs/utils/reloadApp.js

@@ -0,0 +1,144 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.REMOTE_RELOAD_DELAY_MS = void 0;
+exports.reloadApp = reloadApp;
+exports.resolveReloadStrategy = resolveReloadStrategy;
+exports.scheduleReloadApp = scheduleReloadApp;
+/**
+ * reloadApp
+ *
+ * Programmatic JS-bundle reload primitive. Two strategies, picked at runtime:
+ *
+ * - `dev-settings`: React Native core's `DevSettings.reload()`. Works in
+ *   __DEV__ builds (including Expo Go) with zero deps, but throws in
+ *   release.
+ * - `expo-updates`: `Updates.reloadAsync()` from the `expo-updates`
+ *   package. Works in dev clients and production, but fails in Expo Go
+ *   and is not bundled with any Buoy package — host apps opt in by
+ *   installing `expo-updates` separately.
+ *
+ * "auto" prefers `dev-settings` in __DEV__ and falls back to
+ * `expo-updates` otherwise. The dynamic `require` keeps `expo-updates` an
+ * optional peer — Expo Go users never load it.
+ *
+ * Lives in shared (not in a tool package) because BOTH the always-installed
+ * core — whose `app` sync adapter exposes reload to remote drivers like the
+ * MCP server — and perf-monitor's batch runner (reload between cases) need it,
+ * and reloading must not require a tool with native peer deps.
+ *
+ * IMPORTANT: callers must persist any state they need to survive BEFORE
+ * invoking this. Once the reload fires, the JS realm is gone — there is
+ * no "after" code path.
+ */
+
+/** The concrete mechanism a `ReloadStrategy` resolves to at runtime. */
+
+function loadDevSettings() {
+  try {
+    // Prefer the core RN module; cast to unknown first so TS doesn't try
+    // to follow into RN's typings (the package may not be in the type
+    // graph in some build setups).
+    const rn = require("react-native");
+    const ds = rn?.DevSettings;
+    if (ds && typeof ds.reload === "function") {
+      return ds;
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}
+function loadExpoUpdates() {
+  try {
+    const mod = require("expo-updates");
+    if (mod && typeof mod.reloadAsync === "function") {
+      return mod;
+    }
+  } catch {
+    // expo-updates not installed
+  }
+  return null;
+}
+
+/**
+ * Which mechanism `strategy` would actually use right now, or null when none
+ * is available. Lets a caller check reloadability BEFORE committing (e.g. a
+ * remote driver that must answer "will this work?" over the wire, since after
+ * the reload fires there is no code path left to answer from).
+ */
+function resolveReloadStrategy(strategy = "auto") {
+  if (strategy === "dev-settings") {
+    return loadDevSettings() ? "dev-settings" : null;
+  }
+  if (strategy === "expo-updates") {
+    return loadExpoUpdates() ? "expo-updates" : null;
+  }
+  if (__DEV__ && loadDevSettings()) return "dev-settings";
+  return loadExpoUpdates() ? "expo-updates" : null;
+}
+
+/** Why `strategy` can't run, phrased for the person who has to fix it. */
+function unavailableMessage(strategy) {
+  if (strategy === "dev-settings") {
+    return "[buoy] DevSettings.reload() unavailable — strategy 'dev-settings' requires React Native dev mode.";
+  }
+  if (strategy === "expo-updates") {
+    return "[buoy] expo-updates not installed — strategy 'expo-updates' requires the host app to add the dependency.";
+  }
+  return "[buoy] No reload mechanism available. Run in __DEV__ or install expo-updates.";
+}
+
+/**
+ * Trigger a full JS bundle reload. Resolves to a never-resolving promise
+ * because the realm is being torn down — code after the call should not
+ * execute. Throws synchronously if no strategy is available.
+ */
+async function reloadApp(strategy = "auto", reason = "buoy reload") {
+  const resolved = resolveReloadStrategy(strategy);
+  if (!resolved) throw new Error(unavailableMessage(strategy));
+  if (resolved === "dev-settings") {
+    loadDevSettings().reload(reason);
+  } else {
+    await loadExpoUpdates().reloadAsync();
+  }
+  return await new Promise(() => {});
+}
+
+/**
+ * Delay before a remotely-requested reload actually fires. The realm dies the
+ * instant it does, so a remote caller's acknowledgement (an action result on
+ * the sync socket) must be flushed to the broker first — this is the window
+ * that lets it get out.
+ */
+const REMOTE_RELOAD_DELAY_MS = exports.REMOTE_RELOAD_DELAY_MS = 250;
+
+/**
+ * Arm a reload to fire shortly, and report which mechanism will do it.
+ *
+ * Unlike {@link reloadApp}, this returns — synchronously and BEFORE the realm
+ * is torn down — so a remote driver (Buoy Desktop, the MCP server) can answer
+ * "reload accepted, via dev-settings" over the socket. Throws (without
+ * scheduling anything) when no mechanism is available, so an impossible reload
+ * fails loudly instead of looking accepted and silently doing nothing.
+ */
+function scheduleReloadApp(options) {
+  const strategy = options?.strategy ?? "auto";
+  const resolved = resolveReloadStrategy(strategy);
+  if (!resolved) throw new Error(unavailableMessage(strategy));
+  const delayMs = Math.max(0, options?.delayMs ?? REMOTE_RELOAD_DELAY_MS);
+  const reason = options?.reason ?? "buoy remote reload";
+  setTimeout(() => {
+    void reloadApp(resolved, reason).catch(() => {
+      // Nothing left to report to — the caller already got its ack, and the
+      // pre-flight resolve above means this only trips on a mechanism that
+      // broke between scheduling and firing.
+    });
+  }, delayMs);
+  return {
+    strategy: resolved,
+    delayMs
+  };
+}