@buoy-gg/route-events 7.0.26 → 7.0.28

package/lib/module/components/RoutesSitemap.js

@@ -12,10 +12,10 @@
  */
 
 import { useState, useCallback, useMemo, useEffect } from "react";
-import { macOSColors } from "@buoy-gg/shared-ui";
+import { night } from "@buoy-gg/shared-ui";
 import { View, Text, TextInput, TouchableOpacity, ScrollView, StyleSheet, Alert, Platform } from "react-native";
 import { useSafeRouter } from "@buoy-gg/shared-ui";
-import { Search, ChevronDown, ChevronRight, Home, InlineCopyButton, CopyButton, RefreshCw, formatRelativeTime, ProUpgradeModal, buoyColors } from "@buoy-gg/shared-ui";
+import { Search, ChevronDown, ChevronRight, Home, InlineCopyButton, CopyButton, RefreshCw, formatRelativeTime, ProUpgradeModal } from "@buoy-gg/shared-ui";
 import { useIsPro } from "@buoy-gg/license";
 import { useRouteSitemap } from "../useRouteSitemap";
 
@@ -55,7 +55,7 @@ export function RoutesSitemap({
 }) {
   const [searchQuery, setSearchQuery] = useState("");
   const [isSearching, setIsSearching] = useState(false);
-  const [expandedGroups, setExpandedGroups] = useState(new Set(["Root Routes", "Dynamic Routes"]));
+  const [expandedGroups, setExpandedGroups] = useState(new Set(["Static Routes", "Dynamic Routes"]));
   const [isRefreshing, setIsRefreshing] = useState(false);
   const [showUpgradeModal, setShowUpgradeModal] = useState(false);
 
@@ -261,96 +261,15 @@ export function RoutesSitemap({
   }
   return /*#__PURE__*/_jsxs(View, {
     style: [styles.container, style],
-    children: [!isSearching ? /*#__PURE__*/_jsxs(View, {
-      style: styles.header,
-      children: [/*#__PURE__*/_jsxs(View, {
-        style: styles.actionsRow,
-        children: [/*#__PURE__*/_jsxs(View, {
-          style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
-          children: [/*#__PURE__*/_jsx(TouchableOpacity, {
-            style: [styles.iconButton, IS_DESKTOP && styles.iconButtonDesktop],
-            onPress: handleGoHome,
-            accessibilityLabel: "Go to home route",
-            children: /*#__PURE__*/_jsx(Home, {
-              size: ACTION_ICON_SIZE,
-              color: buoyColors.textSecondary
-            })
-          }), /*#__PURE__*/_jsx(Text, {
-            style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
-            children: "Home"
-          })]
-        }), /*#__PURE__*/_jsxs(View, {
-          style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
-          children: [/*#__PURE__*/_jsx(CopyButton, {
-            value: copyAllData,
-            size: IS_DESKTOP ? ACTION_ICON_SIZE : 14,
-            buttonStyle: IS_DESKTOP ? styles.actionButtonHeaderDesktop : styles.actionButtonHeader
-          }), /*#__PURE__*/_jsx(Text, {
-            style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
-            children: "Copy"
-          })]
-        }), /*#__PURE__*/_jsxs(View, {
-          style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
-          children: [/*#__PURE__*/_jsx(TouchableOpacity, {
-            style: [styles.iconButton, IS_DESKTOP && styles.iconButtonDesktop, isRefreshing && styles.refreshButtonDisabled],
-            onPress: handleManualRefresh,
-            disabled: isRefreshing,
-            children: /*#__PURE__*/_jsx(RefreshCw, {
-              size: ACTION_ICON_SIZE,
-              color: isRefreshing ? buoyColors.textMuted : buoyColors.textSecondary
-            })
-          }), /*#__PURE__*/_jsx(Text, {
-            style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
-            children: "Refresh"
-          })]
-        }), /*#__PURE__*/_jsxs(View, {
-          style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
-          children: [/*#__PURE__*/_jsx(TouchableOpacity, {
-            style: [styles.iconButton, IS_DESKTOP && styles.iconButtonDesktop],
-            onPress: () => setIsSearching(true),
-            children: /*#__PURE__*/_jsx(Search, {
-              size: ACTION_ICON_SIZE,
-              color: buoyColors.textSecondary
-            })
-          }), /*#__PURE__*/_jsx(Text, {
-            style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
-            children: "Search"
-          })]
-        })]
-      }), /*#__PURE__*/_jsxs(View, {
-        style: styles.statsGrid,
-        children: [/*#__PURE__*/_jsx(StatItem, {
-          value: stats.total,
-          label: "Total"
-        }), /*#__PURE__*/_jsx(StatItem, {
-          value: stats.static,
-          label: "Static"
-        }), /*#__PURE__*/_jsx(StatItem, {
-          value: stats.dynamic,
-          label: "Dynamic"
-        }), /*#__PURE__*/_jsx(StatItem, {
-          value: stats.catchAll,
-          label: "Catch-All"
-        }), /*#__PURE__*/_jsx(StatItem, {
-          value: stats.layouts,
-          label: "Layouts"
-        }), /*#__PURE__*/_jsx(StatItem, {
-          value: stats.groups,
-          label: "Groups"
-        })]
-      })]
-    }) :
-    /*#__PURE__*/
-    /* Search mode - full width search bar */
-    _jsxs(View, {
+    children: [isSearching && /*#__PURE__*/_jsxs(View, {
       style: styles.searchContainer,
       children: [/*#__PURE__*/_jsx(Search, {
         size: 16,
-        color: buoyColors.textMuted
+        color: night.color.textTertiary
       }), /*#__PURE__*/_jsx(TextInput, {
         style: styles.searchInput,
         placeholder: "Search routes...",
-        placeholderTextColor: buoyColors.textMuted,
+        placeholderTextColor: night.color.placeholder,
         value: searchQuery,
         onChangeText: setSearchQuery,
         autoCapitalize: "none",
@@ -377,7 +296,85 @@ export function RoutesSitemap({
     }), /*#__PURE__*/_jsxs(ScrollView, {
       style: styles.scrollView,
       contentContainerStyle: styles.scrollContent,
-      children: [displayGroups.length === 0 ? /*#__PURE__*/_jsx(View, {
+      children: [!isSearching && /*#__PURE__*/_jsxs(View, {
+        style: styles.header,
+        children: [/*#__PURE__*/_jsxs(View, {
+          style: styles.actionsRow,
+          children: [/*#__PURE__*/_jsxs(View, {
+            style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
+            children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+              style: [styles.iconButton, IS_DESKTOP && styles.iconButtonDesktop],
+              onPress: handleGoHome,
+              accessibilityLabel: "Go to home route",
+              children: /*#__PURE__*/_jsx(Home, {
+                size: ACTION_ICON_SIZE,
+                color: night.color.textSecondary
+              })
+            }), /*#__PURE__*/_jsx(Text, {
+              style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
+              children: "Home"
+            })]
+          }), /*#__PURE__*/_jsxs(View, {
+            style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
+            children: [/*#__PURE__*/_jsx(CopyButton, {
+              value: copyAllData,
+              size: IS_DESKTOP ? ACTION_ICON_SIZE : 14,
+              buttonStyle: IS_DESKTOP ? styles.actionButtonHeaderDesktop : styles.actionButtonHeader
+            }), /*#__PURE__*/_jsx(Text, {
+              style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
+              children: "Copy"
+            })]
+          }), /*#__PURE__*/_jsxs(View, {
+            style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
+            children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+              style: [styles.iconButton, IS_DESKTOP && styles.iconButtonDesktop, isRefreshing && styles.refreshButtonDisabled],
+              onPress: handleManualRefresh,
+              disabled: isRefreshing,
+              children: /*#__PURE__*/_jsx(RefreshCw, {
+                size: ACTION_ICON_SIZE,
+                color: isRefreshing ? night.color.textTertiary : night.color.textSecondary
+              })
+            }), /*#__PURE__*/_jsx(Text, {
+              style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
+              children: "Refresh"
+            })]
+          }), /*#__PURE__*/_jsxs(View, {
+            style: [styles.actionWrapper, IS_DESKTOP && styles.actionWrapperDesktop],
+            children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+              style: [styles.iconButton, IS_DESKTOP && styles.iconButtonDesktop],
+              onPress: () => setIsSearching(true),
+              children: /*#__PURE__*/_jsx(Search, {
+                size: ACTION_ICON_SIZE,
+                color: night.color.textSecondary
+              })
+            }), /*#__PURE__*/_jsx(Text, {
+              style: [styles.actionLabel, IS_DESKTOP && styles.actionLabelDesktop],
+              children: "Search"
+            })]
+          })]
+        }), /*#__PURE__*/_jsxs(View, {
+          style: styles.statsGrid,
+          children: [/*#__PURE__*/_jsx(StatItem, {
+            value: stats.total,
+            label: "Total"
+          }), /*#__PURE__*/_jsx(StatItem, {
+            value: stats.static,
+            label: "Static"
+          }), /*#__PURE__*/_jsx(StatItem, {
+            value: stats.dynamic,
+            label: "Dynamic"
+          }), /*#__PURE__*/_jsx(StatItem, {
+            value: stats.catchAll,
+            label: "Catch-All"
+          }), /*#__PURE__*/_jsx(StatItem, {
+            value: stats.layouts,
+            label: "Layouts"
+          }), /*#__PURE__*/_jsx(StatItem, {
+            value: stats.groups,
+            label: "Groups"
+          })]
+        })]
+      }), displayGroups.length === 0 ? /*#__PURE__*/_jsx(View, {
         style: styles.emptyState,
         children: /*#__PURE__*/_jsx(Text, {
           style: styles.emptyText,
@@ -444,10 +441,10 @@ function RouteGroupView({
         style: styles.groupHeaderLeft,
         children: [isExpanded ? /*#__PURE__*/_jsx(ChevronDown, {
           size: 14,
-          color: buoyColors.textSecondary
+          color: night.color.textSecondary
         }) : /*#__PURE__*/_jsx(ChevronRight, {
           size: 14,
-          color: buoyColors.textSecondary
+          color: night.color.textSecondary
         }), /*#__PURE__*/_jsx(Text, {
           style: styles.groupTitle,
           children: group.title
@@ -504,10 +501,10 @@ function RouteItemView({
             style: styles.expandIndicator,
             children: isExpanded ? /*#__PURE__*/_jsx(ChevronDown, {
               size: 14,
-              color: buoyColors.textSecondary
+              color: night.color.textSecondary
             }) : /*#__PURE__*/_jsx(ChevronRight, {
               size: 14,
-              color: buoyColors.textSecondary
+              color: night.color.textSecondary
             })
           }), /*#__PURE__*/_jsx(Text, {
             style: styles.routePath,
@@ -611,7 +608,8 @@ function getRouteTypeColor(type) {
 const styles = StyleSheet.create({
   container: {
     flex: 1,
-    backgroundColor: buoyColors.base
+    // Transparent so JsModal's ToolBackground shows through (the modal paints opaque base beneath it).
+    backgroundColor: "transparent"
   },
   loadingContainer: {
     flex: 1,
@@ -619,7 +617,7 @@ const styles = StyleSheet.create({
     alignItems: "center"
   },
   loadingText: {
-    color: buoyColors.textSecondary,
+    color: night.color.textSecondary,
     fontSize: 14,
     fontFamily: "monospace",
     textAlign: "center",
@@ -631,8 +629,9 @@ const styles = StyleSheet.create({
     flexDirection: "column",
     padding: 8,
     borderBottomWidth: 1,
-    borderBottomColor: buoyColors.border,
-    gap: 12
+    borderBottomColor: night.color.border,
+    gap: 12,
+    marginBottom: 8
   },
   actionsRow: {
     flexDirection: "row",
@@ -651,7 +650,7 @@ const styles = StyleSheet.create({
     flexShrink: 1,
     flexBasis: "30%",
     minWidth: 90,
-    backgroundColor: buoyColors.card,
+    backgroundColor: night.color.surface,
     borderRadius: 8,
     paddingVertical: 10,
     paddingHorizontal: 12,
@@ -660,12 +659,12 @@ const styles = StyleSheet.create({
   statValue: {
     fontSize: 18,
     fontWeight: "800",
-    color: buoyColors.text,
+    color: night.color.text,
     fontFamily: "monospace"
   },
   statLabel: {
     fontSize: 10,
-    color: buoyColors.textMuted,
+    color: night.color.textTertiary,
     marginTop: 4,
     fontFamily: "monospace",
     textTransform: "uppercase",
@@ -685,12 +684,12 @@ const styles = StyleSheet.create({
   actionButtonHeader: {
     padding: 6,
     borderRadius: 4,
-    backgroundColor: buoyColors.input
+    backgroundColor: night.color.surfaceElevated
   },
   actionButtonHeaderDesktop: {
     padding: 12,
     borderRadius: 8,
-    backgroundColor: buoyColors.input
+    backgroundColor: night.color.surfaceElevated
   },
   iconButton: {
     padding: 6,
@@ -701,11 +700,11 @@ const styles = StyleSheet.create({
   iconButtonDesktop: {
     padding: 12,
     borderRadius: 8,
-    backgroundColor: buoyColors.input
+    backgroundColor: night.color.surfaceElevated
   },
   actionLabel: {
     fontSize: 8,
-    color: buoyColors.textMuted,
+    color: night.color.textTertiary,
     fontFamily: "monospace",
     textTransform: "uppercase",
     letterSpacing: 0.5
@@ -725,11 +724,11 @@ const styles = StyleSheet.create({
     paddingVertical: 16,
     marginTop: 16,
     borderTopWidth: 1,
-    borderTopColor: buoyColors.border
+    borderTopColor: night.color.border
   },
   metaText: {
     fontSize: 12,
-    color: buoyColors.textSecondary,
+    color: night.color.textSecondary,
     fontFamily: "monospace"
   },
   sourceBadge: {
@@ -737,12 +736,12 @@ const styles = StyleSheet.create({
     paddingVertical: 2,
     borderRadius: 999,
     borderWidth: 1,
-    borderColor: buoyColors.border,
-    backgroundColor: buoyColors.card
+    borderColor: night.color.border,
+    backgroundColor: night.color.surface
   },
   sourceText: {
     fontSize: 11,
-    color: buoyColors.textSecondary,
+    color: night.color.textSecondary,
     textTransform: "capitalize",
     fontFamily: "monospace"
   },
@@ -752,11 +751,11 @@ const styles = StyleSheet.create({
     padding: 8,
     gap: 8,
     borderBottomWidth: 1,
-    borderBottomColor: buoyColors.border
+    borderBottomColor: night.color.border
   },
   searchInput: {
     flex: 1,
-    color: buoyColors.text,
+    color: night.color.text,
     fontSize: 14,
     fontFamily: "monospace"
   },
@@ -764,7 +763,7 @@ const styles = StyleSheet.create({
     padding: 4
   },
   clearButtonText: {
-    color: buoyColors.textMuted,
+    color: night.color.textTertiary,
     fontSize: 18
   },
   closeSearchButton: {
@@ -772,7 +771,7 @@ const styles = StyleSheet.create({
     paddingVertical: 4
   },
   closeSearchText: {
-    color: buoyColors.primary,
+    color: night.color.accent,
     fontSize: 14,
     fontWeight: "600",
     fontFamily: "monospace"
@@ -781,14 +780,14 @@ const styles = StyleSheet.create({
     flex: 1
   },
   scrollContent: {
-    paddingVertical: 8
+    paddingBottom: 8
   },
   emptyState: {
     padding: 32,
     alignItems: "center"
   },
   emptyText: {
-    color: buoyColors.textSecondary,
+    color: night.color.textSecondary,
     fontSize: 14,
     fontFamily: "monospace"
   },
@@ -801,9 +800,9 @@ const styles = StyleSheet.create({
     justifyContent: "space-between",
     padding: 12,
     paddingHorizontal: 16,
-    backgroundColor: buoyColors.card,
+    backgroundColor: night.color.surface,
     borderLeftWidth: 3,
-    borderLeftColor: buoyColors.textSecondary
+    borderLeftColor: night.color.fillTertiary
   },
   groupHeaderLeft: {
     flexDirection: "row",
@@ -814,7 +813,7 @@ const styles = StyleSheet.create({
   groupTitle: {
     fontSize: 12,
     fontWeight: "700",
-    color: buoyColors.text,
+    color: night.color.text,
     fontFamily: "monospace",
     textTransform: "uppercase",
     letterSpacing: 0.8
@@ -837,19 +836,20 @@ const styles = StyleSheet.create({
     fontFamily: "monospace"
   },
   routesList: {
-    backgroundColor: buoyColors.base
+    // Transparent so the night sheet's star field shows through.
+    backgroundColor: "transparent"
   },
   groupDescription: {
     paddingHorizontal: 16,
     paddingVertical: 8,
     marginBottom: 8,
-    backgroundColor: buoyColors.input,
+    backgroundColor: night.color.surfaceElevated,
     borderLeftWidth: 3,
-    borderLeftColor: buoyColors.textSecondary
+    borderLeftColor: night.color.fillTertiary
   },
   groupDescriptionText: {
     fontSize: 11,
-    color: buoyColors.textSecondary,
+    color: night.color.textSecondary,
     fontFamily: "monospace",
     lineHeight: 16
   },
@@ -857,10 +857,10 @@ const styles = StyleSheet.create({
     marginBottom: 6
   },
   routeCard: {
-    backgroundColor: buoyColors.card,
+    backgroundColor: night.color.surface,
     borderRadius: 6,
     borderWidth: 1,
-    borderColor: buoyColors.border,
+    borderColor: night.color.border,
     overflow: "hidden",
     shadowColor: "#000",
     shadowOffset: {
@@ -892,7 +892,7 @@ const styles = StyleSheet.create({
   routePath: {
     fontSize: 13,
     fontWeight: "600",
-    color: buoyColors.text,
+    color: night.color.text,
     fontFamily: "monospace",
     flex: 1
   },
@@ -915,7 +915,7 @@ const styles = StyleSheet.create({
   childCountText: {
     fontSize: 11,
     fontWeight: "600",
-    color: macOSColors.text.icon,
+    color: night.color.textSecondary,
     fontFamily: "monospace"
   },
   typeTag: {
@@ -934,9 +934,9 @@ const styles = StyleSheet.create({
     width: 28,
     height: 24,
     borderRadius: 4,
-    backgroundColor: buoyColors.input,
+    backgroundColor: night.color.surfaceElevated,
     borderWidth: 1,
-    borderColor: buoyColors.border,
+    borderColor: night.color.border,
     alignItems: "center",
     justifyContent: "center"
   },
@@ -947,19 +947,19 @@ const styles = StyleSheet.create({
     borderRadius: 4,
     alignItems: "center",
     justifyContent: "center",
-    backgroundColor: buoyColors.primary + "15",
+    backgroundColor: night.color.accentSoft,
     borderWidth: 1,
-    borderColor: buoyColors.primary + "40"
+    borderColor: night.color.accentBorder
   },
   goButtonText: {
     fontSize: 12,
-    color: buoyColors.primary,
+    color: night.color.accent,
     fontFamily: "monospace",
     fontWeight: "600"
   },
   childrenContainer: {
     borderLeftWidth: 2,
-    borderLeftColor: buoyColors.border,
+    borderLeftColor: night.color.border,
     marginLeft: 16,
     marginRight: 8,
     marginTop: 2,

package/lib/module/sync/routeEventsSyncAdapter.js

@@ -121,7 +121,8 @@ export const routeEventsSyncAdapter = {
      * dynamic params into a concrete path before invoking this.
      */
     navigate: params => {
-      const path = params?.path;
+      const p = params;
+      const path = p?.path;
       if (!path) {
         throw new Error("navigate requires a 'path' param");
       }
@@ -129,9 +130,14 @@ export const routeEventsSyncAdapter = {
       if (!router) {
         throw new Error("expo-router is not available on this device");
       }
-      router.navigate(path);
+      // Push by default so navigate-then-back flows keep working. Callers that
+      // mean "leave this screen" (sitemap Go, agents resetting to home) pass
+      // replace: true — otherwise "Go to home" stacks another `/` on top.
+      const go = p?.replace === true && typeof router.replace === "function" ? router.replace : router.navigate;
+      go(path);
       return {
-        navigated: path
+        navigated: path,
+        replaced: p?.replace === true
       };
     },
     // ── Stack actions: delegate to the live navigation actions captured by

package/lib/module/useNavigationStack.js

@@ -12,16 +12,15 @@
  * - RN CLI: uses NavigationContainerRefContext (works as sibling of navigators)
  */
 
-import { useState, useContext, useEffect, useMemo, useCallback } from "react";
-import { getCommonActions, getStackActions, getNavigationContainerRefContext } from "./utils/safeReactNavigation";
+import { useState, useEffect, useMemo, useCallback } from "react";
+import { getCommonActions, getStackActions, useSafeNavigationContainerRef } from "./utils/safeReactNavigation";
 import { getSafeRouter, isExpoRouterAvailable } from "@buoy-gg/shared-ui";
 
-// Resolved once at module load; null when @react-navigation/native is absent
-// (the fallback context then yields an undefined containerRef, so the
-// dispatch paths below never execute).
+// Resolved once at module load; null when React Navigation is absent
+// (useSafeNavigationContainerRef then yields undefined, so the dispatch
+// paths below never execute).
 const CommonActions = getCommonActions();
 const StackActions = getStackActions();
-const NavigationContainerRefContext = getNavigationContainerRefContext();
 
 // ============================================================================
 // Type Definitions
@@ -199,7 +198,7 @@ function buildStack(navigationState, isExpo) {
  */
 export function useNavigationStack() {
   const isExpo = isExpoRouterAvailable();
-  const containerRef = useContext(NavigationContainerRefContext);
+  const containerRef = useSafeNavigationContainerRef();
   const [navigationState, setNavigationState] = useState(() => containerRef?.getRootState?.() ?? null);
   const [isLoaded, setIsLoaded] = useState(false);
   const [error, setError] = useState(null);

package/lib/module/useRouteObserverReactNavigation.js

@@ -11,14 +11,10 @@
  * a NavigationContainer — does NOT need to be inside a navigator.
  */
 
-import { useContext, useEffect, useRef } from "react";
-import { getNavigationContainerRefContext } from "./utils/safeReactNavigation";
+import { useEffect, useRef } from "react";
+import { useSafeNavigationContainerRef } from "./utils/safeReactNavigation";
 import { routeObserver } from "./RouteObserver";
 
-// Resolved once at module load; falls back to an always-undefined context
-// when @react-navigation/native is absent, so the effect below no-ops.
-const NavigationContainerRefContext = getNavigationContainerRefContext();
-
 /**
  * Walk a React Navigation state tree to find the deepest focused route.
  * Returns the route object and the array of route names from root to leaf.
@@ -82,7 +78,7 @@ function emitRouteEvent(state, previousPathnameRef, previousTimestampRef, callba
  * Works anywhere inside a NavigationContainer (does not need to be inside a navigator).
  */
 export function useRouteObserverReactNavigation(callback) {
-  const containerRef = useContext(NavigationContainerRefContext);
+  const containerRef = useSafeNavigationContainerRef();
   const callbackRef = useRef(callback);
   const previousPathnameRef = useRef(undefined);
   const previousTimestampRef = useRef(undefined);

package/lib/module/utils/safeReactNavigation.js

@@ -7,10 +7,35 @@
  * Falls back to no-op implementations when @react-navigation/native is not installed.
  */
 
-import { createContext, useMemo } from "react";
+import { createContext, useContext, useMemo } from "react";
 let reactNavigation = null;
 let isAvailable = false;
 let checkedAvailability = false;
+
+// Expo Router (SDK 54+) VENDORS React Navigation: its NavigationContainer
+// provides the vendored NavigationContainerRefContext from
+// expo-router/build/react-navigation, NOT the one exported by the
+// @react-navigation/native package (which may not even be installed, or is a
+// second module instance whose context nobody provides). Reading only the npm
+// context in such apps yields undefined forever — the Stack tab then hangs on
+// "Loading navigation stack...". So we load both copies and consult both
+// contexts.
+let vendoredReactNavigation = null;
+let checkedVendored = false;
+function getVendoredReactNavigation() {
+  if (checkedVendored) return vendoredReactNavigation;
+  checkedVendored = true;
+  try {
+    // Compat entry re-exporting the vendored native/core/routers modules.
+    // Older expo-router versions (and RN CLI apps) don't have it — the
+    // require throws and we stay on @react-navigation/native.
+    const vendored = require("expo-router/react-navigation");
+    vendoredReactNavigation = vendored?.NavigationContainerRefContext ? vendored : null;
+  } catch {
+    vendoredReactNavigation = null;
+  }
+  return vendoredReactNavigation;
+}
 function checkReactNavigationAvailability() {
   if (checkedAvailability) return isAvailable;
   try {
@@ -20,6 +45,17 @@ function checkReactNavigationAvailability() {
     isAvailable = false;
     reactNavigation = null;
   }
+
+  // Expo Router apps don't necessarily install @react-navigation/native at
+  // all — the vendored copy then supplies CommonActions/StackActions/hooks
+  // (actions are plain serializable objects, so either copy's work).
+  if (!isAvailable) {
+    const vendored = getVendoredReactNavigation();
+    if (vendored) {
+      reactNavigation = vendored;
+      isAvailable = true;
+    }
+  }
   checkedAvailability = true;
   return isAvailable;
 }
@@ -111,13 +147,33 @@ export function getStackActions() {
   return checkReactNavigationAvailability() ? reactNavigation.StackActions : null;
 }
 
+// Both contexts are resolved ONCE and cached so hook identity/order stays
+// stable for the app lifetime (module presence is constant).
+let npmContainerRefContext = null;
+let vendoredContainerRefContext = null;
+function getContainerRefContexts() {
+  if (npmContainerRefContext == null) {
+    npmContainerRefContext = checkReactNavigationAvailability() && reactNavigation.NavigationContainerRefContext ? reactNavigation.NavigationContainerRefContext : FallbackNavigationContainerRefContext;
+  }
+  if (vendoredContainerRefContext == null) {
+    const vendored = getVendoredReactNavigation();
+    vendoredContainerRefContext = vendored?.NavigationContainerRefContext ?? FallbackNavigationContainerRefContext;
+  }
+  return [npmContainerRefContext, vendoredContainerRefContext];
+}
+
 /**
- * NavigationContainerRefContext, read via @react-navigation/native's
- * re-export (never from @react-navigation/core directly — core is not a
- * declared dependency). Falls back to an always-undefined context.
+ * The navigation container ref for THIS app, whichever module instance
+ * provides it: @react-navigation/native's NavigationContainerRefContext
+ * (RN CLI, older expo-router) or Expo Router's vendored copy (SDK 54+).
+ * Returns undefined when rendered outside any NavigationContainer or when
+ * React Navigation is absent entirely.
  */
-export function getNavigationContainerRefContext() {
-  return checkReactNavigationAvailability() && reactNavigation.NavigationContainerRefContext ? reactNavigation.NavigationContainerRefContext : FallbackNavigationContainerRefContext;
+export function useSafeNavigationContainerRef() {
+  const [npmCtx, vendoredCtx] = getContainerRefContexts();
+  const npmRef = useContext(npmCtx);
+  const vendoredRef = useContext(vendoredCtx);
+  return npmRef ?? vendoredRef;
 }
 
 // ============================================================================