@buoy-gg/route-events 3.0.1 → 3.0.2

package/lib/module/components/RoutesSitemap.js

@@ -14,7 +14,7 @@
 import { useState, useCallback, useMemo, useEffect } from "react";
 import { View, Text, TextInput, TouchableOpacity, ScrollView, StyleSheet, Alert } from "react-native";
 import { useSafeRouter } from "@buoy-gg/shared-ui";
-import { Search, ChevronDown, ChevronRight, InlineCopyButton, ToolbarCopyButton, RefreshCw, formatRelativeTime, ProUpgradeModal, buoyColors } from "@buoy-gg/shared-ui";
+import { Search, ChevronDown, ChevronRight, Home, InlineCopyButton, ToolbarCopyButton, RefreshCw, formatRelativeTime, ProUpgradeModal, buoyColors } from "@buoy-gg/shared-ui";
 import { useIsPro } from "@buoy-gg/license";
 import { useRouteSitemap } from "../useRouteSitemap";
 
@@ -22,12 +22,30 @@ import { useRouteSitemap } from "../useRouteSitemap";
 // Types
 // ============================================================================
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Synthetic route representing the app's home/index ("/"). Used by the
+// "Home" toolbar shortcut so navigation works the same as tapping any route.
+const HOME_ROUTE = {
+  path: "/",
+  name: "index",
+  type: "index",
+  params: [],
+  nodeType: "route",
+  contextKey: "/",
+  isInternal: false,
+  children: [],
+  depth: 0
+};
+
 // ============================================================================
 // Main Component
 // ============================================================================
 
 export function RoutesSitemap({
-  style
+  style,
+  injectedRoutes,
+  injectedSource,
+  injectedLastUpdatedAt,
+  onNavigateRoute
 }) {
   const [searchQuery, setSearchQuery] = useState("");
   const [isSearching, setIsSearching] = useState(false);
@@ -49,6 +67,7 @@ export function RoutesSitemap({
     groups,
     stats,
     isLoaded,
+    isSupported,
     filteredRoutes,
     routes,
     refresh,
@@ -56,7 +75,10 @@ export function RoutesSitemap({
     source
   } = useRouteSitemap({
     searchQuery,
-    sortBy: "path"
+    sortBy: "path",
+    injectedRoutes,
+    injectedSource,
+    injectedLastUpdatedAt
   });
 
   // Prepare copy data - memoized so it only rebuilds when dependencies change
@@ -144,6 +166,13 @@ export function RoutesSitemap({
     }], "plain-text");
   }, [router]);
   const handleNavigate = useCallback(route => {
+    // When a navigation delegate is supplied (dashboard → device), hand off
+    // entirely: the delegate owns Pro gating and param resolution.
+    if (onNavigateRoute) {
+      onNavigateRoute(route);
+      return;
+    }
+
     // Gate behind Pro
     if (!isPro) {
       setShowUpgradeModal(true);
@@ -179,7 +208,10 @@ export function RoutesSitemap({
     } catch (error) {
       Alert.alert("Navigation Error", String(error));
     }
-  }, [router, promptForParams, isPro]);
+  }, [router, promptForParams, isPro, onNavigateRoute]);
+  const handleGoHome = useCallback(() => {
+    handleNavigate(HOME_ROUTE);
+  }, [handleNavigate]);
   const handleManualRefresh = useCallback(() => {
     if (isRefreshing) return;
     setIsRefreshing(true);
@@ -214,7 +246,7 @@ export function RoutesSitemap({
         style: styles.loadingContainer,
         children: /*#__PURE__*/_jsx(Text, {
           style: styles.loadingText,
-          children: "Loading routes..."
+          children: isSupported ? "Loading routes..." : "Route sitemap isn't available on the dashboard — the route tree lives on the device. Use the Events tab to see navigation here."
         })
       })
     });
@@ -226,6 +258,20 @@ export function RoutesSitemap({
       children: [/*#__PURE__*/_jsxs(View, {
         style: styles.actionsRow,
         children: [/*#__PURE__*/_jsxs(View, {
+          style: styles.actionWrapper,
+          children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+            style: styles.iconButton,
+            onPress: handleGoHome,
+            accessibilityLabel: "Go to home route",
+            children: /*#__PURE__*/_jsx(Home, {
+              size: 16,
+              color: buoyColors.textSecondary
+            })
+          }), /*#__PURE__*/_jsx(Text, {
+            style: styles.actionLabel,
+            children: "Home"
+          })]
+        }), /*#__PURE__*/_jsxs(View, {
           style: styles.actionWrapper,
           children: [/*#__PURE__*/_jsx(ToolbarCopyButton, {
             value: copyAllData,
@@ -429,82 +475,92 @@ function RouteItemView({
   const hasParams = route.params.length > 0;
   const typeColor = getRouteTypeColor(route.type);
   const canNavigate = route.type !== "layout" && route.type !== "group";
-  return /*#__PURE__*/_jsxs(View, {
+
+  // Leaf routes (no children) have nothing to drill into — expanding would only
+  // reveal the Copy/Go actions, so show those inline instead of behind a toggle.
+  const isExpandable = hasChildren;
+  const showDetails = isExpandable ? isExpanded : true;
+  return /*#__PURE__*/_jsx(View, {
     style: [styles.routeItem, {
       marginLeft: depth * 12
     }],
-    children: [/*#__PURE__*/_jsxs(View, {
+    children: /*#__PURE__*/_jsxs(View, {
       style: styles.routeCard,
-      children: [/*#__PURE__*/_jsxs(TouchableOpacity, {
-        style: styles.routeHeaderLeft,
-        onPress: () => setIsExpanded(!isExpanded),
-        activeOpacity: 0.7,
-        children: [/*#__PURE__*/_jsx(View, {
-          style: styles.expandIndicator,
-          children: isExpanded ? /*#__PURE__*/_jsx(ChevronDown, {
-            size: 14,
-            color: buoyColors.textSecondary
-          }) : /*#__PURE__*/_jsx(ChevronRight, {
-            size: 14,
-            color: buoyColors.textSecondary
-          })
-        }), /*#__PURE__*/_jsx(Text, {
-          style: styles.routePath,
-          numberOfLines: 1,
-          children: route.path
-        })]
-      }), /*#__PURE__*/_jsxs(View, {
-        style: styles.routeHeaderActions,
-        children: [hasChildren && /*#__PURE__*/_jsx(View, {
-          style: styles.childCountBadge,
-          children: /*#__PURE__*/_jsx(Text, {
-            style: styles.childCountText,
-            children: route.children.length
-          })
-        }), /*#__PURE__*/_jsx(View, {
-          style: [styles.typeTag, {
-            backgroundColor: `${typeColor}15`,
-            borderColor: `${typeColor}40`
-          }],
-          children: /*#__PURE__*/_jsx(Text, {
-            style: [styles.typeText, {
-              color: typeColor
-            }],
-            children: route.type.toUpperCase()
-          })
-        })]
-      })]
-    }), isExpanded && /*#__PURE__*/_jsxs(View, {
-      style: styles.routeDetails,
       children: [/*#__PURE__*/_jsxs(View, {
-        style: styles.routeButtons,
-        children: [/*#__PURE__*/_jsx(InlineCopyButton, {
-          value: route.path,
-          buttonStyle: styles.actionButton
-        }), canNavigate && /*#__PURE__*/_jsx(TouchableOpacity, {
-          style: [styles.actionButton, styles.navigateButton],
-          onPress: () => onNavigate(route),
-          children: /*#__PURE__*/_jsx(Text, {
-            style: styles.navigateButtonText,
-            children: "Go"
-          })
-        })]
-      }), hasParams && /*#__PURE__*/_jsxs(View, {
-        style: styles.paramsContainer,
-        children: [/*#__PURE__*/_jsx(Text, {
-          style: styles.paramsLabel,
-          children: "Parameters:"
-        }), /*#__PURE__*/_jsx(View, {
-          style: styles.paramsRow,
-          children: route.params.map(param => /*#__PURE__*/_jsx(View, {
-            style: styles.paramTag,
+        style: styles.routeHeader,
+        children: [isExpandable ? /*#__PURE__*/_jsxs(TouchableOpacity, {
+          style: styles.routeHeaderLeft,
+          onPress: () => setIsExpanded(!isExpanded),
+          activeOpacity: 0.7,
+          children: [/*#__PURE__*/_jsx(View, {
+            style: styles.expandIndicator,
+            children: isExpanded ? /*#__PURE__*/_jsx(ChevronDown, {
+              size: 14,
+              color: buoyColors.textSecondary
+            }) : /*#__PURE__*/_jsx(ChevronRight, {
+              size: 14,
+              color: buoyColors.textSecondary
+            })
+          }), /*#__PURE__*/_jsx(Text, {
+            style: styles.routePath,
+            numberOfLines: 3,
+            children: route.path
+          })]
+        }) :
+        /*#__PURE__*/
+        // Non-toggling header for leaf routes (keeps the chevron column as a
+        // spacer so paths stay aligned with expandable siblings).
+        _jsxs(View, {
+          style: styles.routeHeaderLeft,
+          children: [/*#__PURE__*/_jsx(View, {
+            style: styles.expandIndicator
+          }), /*#__PURE__*/_jsx(Text, {
+            style: styles.routePath,
+            numberOfLines: 3,
+            children: route.path
+          })]
+        }), /*#__PURE__*/_jsxs(View, {
+          style: styles.routeHeaderActions,
+          children: [hasChildren && /*#__PURE__*/_jsx(View, {
+            style: styles.childCountBadge,
             children: /*#__PURE__*/_jsx(Text, {
-              style: styles.paramText,
-              children: param
+              style: styles.childCountText,
+              children: route.children.length
             })
-          }, param))
+          }), /*#__PURE__*/_jsx(View, {
+            style: [styles.typeTag, {
+              backgroundColor: `${typeColor}15`,
+              borderColor: `${typeColor}40`
+            }],
+            children: /*#__PURE__*/_jsx(Text, {
+              style: [styles.typeText, {
+                color: typeColor
+              }],
+              children: route.type.toUpperCase()
+            })
+          }), /*#__PURE__*/_jsx(InlineCopyButton, {
+            value: route.path,
+            buttonStyle: styles.iconAction
+          }), canNavigate && /*#__PURE__*/_jsx(TouchableOpacity, {
+            style: styles.goButton,
+            onPress: () => onNavigate(route),
+            activeOpacity: 0.7,
+            children: /*#__PURE__*/_jsx(Text, {
+              style: styles.goButtonText,
+              children: "Go"
+            })
+          })]
         })]
-      }), hasChildren && /*#__PURE__*/_jsx(View, {
+      }), showDetails && hasParams && /*#__PURE__*/_jsx(View, {
+        style: styles.paramsRow,
+        children: route.params.map(param => /*#__PURE__*/_jsx(View, {
+          style: styles.paramTag,
+          children: /*#__PURE__*/_jsx(Text, {
+            style: styles.paramText,
+            children: param
+          })
+        }, param))
+      }), showDetails && hasChildren && /*#__PURE__*/_jsx(View, {
         style: styles.childrenContainer,
         children: route.children.map((child, index) => /*#__PURE__*/_jsx(RouteItemView, {
           route: child,
@@ -512,7 +568,7 @@ function RouteItemView({
           onNavigate: onNavigate
         }, `${child.path}-${index}`))
       })]
-    })]
+    })
   });
 }
 
@@ -566,7 +622,11 @@ const styles = StyleSheet.create({
   loadingText: {
     color: buoyColors.textSecondary,
     fontSize: 14,
-    fontFamily: "monospace"
+    fontFamily: "monospace",
+    textAlign: "center",
+    lineHeight: 20,
+    paddingHorizontal: 32,
+    maxWidth: 420
   },
   header: {
     flexDirection: "column",
@@ -578,7 +638,7 @@ const styles = StyleSheet.create({
   actionsRow: {
     flexDirection: "row",
     alignItems: "center",
-    justifyContent: "flex-end",
+    justifyContent: "space-between",
     gap: 12,
     paddingBottom: 4
   },
@@ -613,6 +673,7 @@ const styles = StyleSheet.create({
     letterSpacing: 0.5
   },
   actionWrapper: {
+    flex: 1,
     alignItems: "center",
     justifyContent: "center",
     gap: 4,
@@ -780,15 +841,11 @@ const styles = StyleSheet.create({
     marginBottom: 6
   },
   routeCard: {
-    flexDirection: "row",
-    alignItems: "center",
-    justifyContent: "space-between",
-    paddingVertical: 10,
-    paddingHorizontal: 12,
     backgroundColor: buoyColors.card,
     borderRadius: 6,
     borderWidth: 1,
     borderColor: buoyColors.border,
+    overflow: "hidden",
     shadowColor: "#000",
     shadowOffset: {
       width: 0,
@@ -798,8 +855,16 @@ const styles = StyleSheet.create({
     shadowRadius: 2,
     elevation: 1
   },
+  routeHeader: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingVertical: 7,
+    paddingHorizontal: 10,
+    gap: 8
+  },
   expandIndicator: {
-    width: 20,
+    width: 18,
     alignItems: "center"
   },
   routeHeaderLeft: {
@@ -848,34 +913,41 @@ const styles = StyleSheet.create({
     fontWeight: "600",
     fontFamily: "monospace"
   },
-  routeDetails: {
-    paddingHorizontal: 12,
-    paddingTop: 8,
-    paddingBottom: 12,
-    gap: 12,
-    borderTopWidth: 1,
-    borderTopColor: buoyColors.border,
-    backgroundColor: buoyColors.card,
-    borderRadius: 6,
+  // Compact icon-sized Copy button in the header action cluster.
+  iconAction: {
+    width: 28,
+    height: 24,
+    borderRadius: 4,
+    backgroundColor: buoyColors.input,
     borderWidth: 1,
     borderColor: buoyColors.border,
-    borderTopLeftRadius: 0,
-    borderTopRightRadius: 0,
-    marginTop: -6
+    alignItems: "center",
+    justifyContent: "center"
   },
-  paramsContainer: {
-    gap: 6
+  // Small "Go" pill in the header action cluster.
+  goButton: {
+    height: 24,
+    paddingHorizontal: 10,
+    borderRadius: 4,
+    alignItems: "center",
+    justifyContent: "center",
+    backgroundColor: buoyColors.primary + "15",
+    borderWidth: 1,
+    borderColor: buoyColors.primary + "40"
   },
-  paramsLabel: {
-    fontSize: 10,
-    color: buoyColors.textSecondary,
+  goButtonText: {
+    fontSize: 12,
+    color: buoyColors.primary,
     fontFamily: "monospace",
-    marginBottom: 4
+    fontWeight: "600"
   },
   paramsRow: {
     flexDirection: "row",
     flexWrap: "wrap",
-    gap: 6
+    gap: 6,
+    paddingHorizontal: 10,
+    paddingTop: 2,
+    paddingBottom: 8
   },
   paramTag: {
     backgroundColor: "#F59E0B15",
@@ -891,41 +963,12 @@ const styles = StyleSheet.create({
     fontFamily: "monospace",
     fontWeight: "600"
   },
-  routeButtons: {
-    flexDirection: "row",
-    gap: 6,
-    marginBottom: 12
-  },
-  actionButton: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: 4,
-    backgroundColor: buoyColors.input,
-    borderRadius: 4,
-    paddingHorizontal: 12,
-    paddingVertical: 6,
-    borderWidth: 1,
-    borderColor: buoyColors.border
-  },
-  actionButtonText: {
-    fontSize: 12,
-    color: buoyColors.textSecondary,
-    fontFamily: "monospace",
-    fontWeight: "600"
-  },
-  navigateButton: {
-    backgroundColor: buoyColors.primary + "15",
-    borderColor: buoyColors.primary + "40"
-  },
-  navigateButtonText: {
-    fontSize: 12,
-    color: buoyColors.primary,
-    fontFamily: "monospace",
-    fontWeight: "600"
-  },
   childrenContainer: {
     borderLeftWidth: 2,
     borderLeftColor: buoyColors.border,
-    marginLeft: 16
+    marginLeft: 16,
+    marginRight: 8,
+    marginTop: 2,
+    marginBottom: 8
   }
 });

package/lib/module/expoRouterStore.js

@@ -24,10 +24,26 @@ function logOnce(message, error) {
  * The storeRef gets populated when Expo Router's useStore() hook runs.
  * So we cache the store reference but its property values update over time.
  */
+/**
+ * Whether the expo-router store can be loaded in this runtime. The store is
+ * pulled in via CommonJS `require`, which only exists under Metro/Node. On the
+ * web (e.g. the desktop dashboard rendering these RN tools via react-native-web)
+ * `require` is undefined, the route tree lives on the device — not here — and
+ * there is nothing to load. Callers use this to skip polling/logging.
+ */
+export function isExpoRouterStoreSupported() {
+  return typeof require !== "undefined";
+}
 export function getExpoRouterStore() {
   if (cachedStore) {
     return cachedStore;
   }
+
+  // No `require` (web): bail quietly rather than throwing ReferenceError and
+  // logging a misleading "install expo-router" message on the dashboard.
+  if (!isExpoRouterStoreSupported()) {
+    return null;
+  }
   const loadFromBuild = () => {
     try {
       const module = require("expo-router/build/global-state/router-store");

package/lib/module/index.js

@@ -38,6 +38,10 @@ export { useRouteObserverReactNavigation } from "./useRouteObserverReactNavigati
 export { useRouteEvents } from "./hooks/useRouteEvents";
 export { useRouteSitemap, useRoute, useParentRoutes } from "./useRouteSitemap";
 export { useNavigationStack } from "./useNavigationStack";
+// =============================================================================
+// EXTERNAL SYNC (Adapter for @buoy-gg/external-sync's useExternalSync)
+// =============================================================================
+export { routeEventsSyncAdapter } from "./sync/routeEventsSyncAdapter";
 
 // =============================================================================
 // TYPES

package/lib/module/stores/navigationStackStore.js

@@ -0,0 +1,41 @@
+"use strict";
+
+/**
+ * Navigation Stack Store
+ *
+ * Holds the latest serializable navigation stack plus references to the live
+ * navigation action functions. The stack is captured inside the navigation tree
+ * by <RouteTracker /> (which runs useNavigationStack), and read by the
+ * route-events sync adapter so the dashboard can render the Stack tab and drive
+ * navigation on the device remotely.
+ *
+ * The stack itself (StackDisplayItem[]) is JSON-serializable and synced to the
+ * dashboard. The action functions are NOT serialized — they stay on the device
+ * and are invoked when the dashboard sends a remote action.
+ */
+
+class NavigationStackStore {
+  stack = [];
+  actions = null;
+  listeners = new Set();
+  getStack() {
+    return this.stack;
+  }
+  setStack(stack) {
+    this.stack = stack;
+    this.listeners.forEach(listener => listener());
+  }
+  getActions() {
+    return this.actions;
+  }
+  setActions(actions) {
+    this.actions = actions;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+}
+export const navigationStackStore = new NavigationStackStore();

package/lib/module/sync/routeEventsSyncAdapter.js

@@ -0,0 +1,145 @@
+"use strict";
+
+import { getSafeRouter } from "@buoy-gg/shared-ui";
+import { routeEventStore } from "../stores/routeEventStore";
+import { navigationStackStore } from "../stores/navigationStackStore";
+import { RouteParser } from "../RouteParser";
+import { loadRouteNode, getRouteNodeMetadata } from "../expoRouterStore";
+
+/**
+ * Serializable snapshot of the device's route tree, sent to the dashboard so
+ * the Routes tab can render a sitemap (the raw expo-router RouteNode itself is
+ * not JSON-serializable — it holds components/functions — so we send the parsed
+ * RouteInfo[] instead).
+ */
+
+/**
+ * Payload shape for the route-events tool (adapter version 3). Consumers must
+ * tolerate older shapes: v1 sends a bare RouteChangeEvent[]; v2 omits `stack`.
+ */
+
+function getSitemapSnapshot() {
+  const metadata = getRouteNodeMetadata();
+  return {
+    routes: RouteParser.parseRouteTree(loadRouteNode()),
+    source: metadata.source,
+    lastUpdatedAt: metadata.lastLoadedAt
+  };
+}
+
+/**
+ * Sync adapter for the route-events tool, consumed by @buoy-gg/external-sync's
+ * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
+ * this package doesn't need a dependency on it).
+ *
+ * Subscribing attaches the routeObserver listener, so route changes are only
+ * recorded while a dashboard is watching. (Route events still require a
+ * <RouteTracker /> inside the navigation tree to be emitted at all.)
+ *
+ * The snapshot carries both the route-change events AND the parsed route
+ * sitemap, so the dashboard — which has no local expo-router store — can render
+ * the route tree. The `navigate` action lets the dashboard drive navigation on
+ * the device.
+ */
+export const routeEventsSyncAdapter = {
+  version: 3,
+  getSnapshot: () => ({
+    events: routeEventStore.getEvents(),
+    sitemap: getSitemapSnapshot(),
+    stack: navigationStackStore.getStack()
+  }),
+  subscribe: onChange => {
+    const unsubscribeEvents = routeEventStore.subscribeToEvents(onChange);
+    const unsubscribeStack = navigationStackStore.subscribe(onChange);
+
+    // The expo-router route tree can still be populating when a dashboard
+    // starts watching. Poll briefly until it's available and push a snapshot
+    // the moment it loads, so the Routes tab fills in without needing the user
+    // to navigate first. Stops as soon as the tree is found.
+    let pollTimer = null;
+    if (!loadRouteNode()) {
+      let retries = 0;
+      const maxRetries = 100; // ~10s
+      const poll = () => {
+        retries += 1;
+        if (loadRouteNode()) {
+          pollTimer = null;
+          onChange();
+          return;
+        }
+        pollTimer = retries < maxRetries ? setTimeout(poll, 100) : null;
+      };
+      pollTimer = setTimeout(poll, 100);
+    }
+    return () => {
+      unsubscribeEvents();
+      unsubscribeStack();
+      if (pollTimer) clearTimeout(pollTimer);
+    };
+  },
+  actions: {
+    clearEvents: () => {
+      routeEventStore.clearEvents();
+    },
+    /**
+     * Navigate the device to a concrete path. The dashboard resolves any
+     * dynamic params into a concrete path before invoking this.
+     */
+    navigate: params => {
+      const path = params?.path;
+      if (!path) {
+        throw new Error("navigate requires a 'path' param");
+      }
+      const router = getSafeRouter();
+      if (!router) {
+        throw new Error("expo-router is not available on this device");
+      }
+      router.navigate(path);
+      return {
+        navigated: path
+      };
+    },
+    // ── Stack actions: delegate to the live navigation actions captured by
+    //    <RouteTracker /> (they hold the React Navigation container ref). ──
+    stackNavigateToIndex: params => {
+      const index = params?.index;
+      if (typeof index !== "number") {
+        throw new Error("stackNavigateToIndex requires a numeric 'index'");
+      }
+      const actions = navigationStackStore.getActions();
+      if (!actions) throw new Error("navigation stack is not available");
+      actions.navigateToIndex(index);
+      return {
+        navigatedToIndex: index
+      };
+    },
+    stackPopToIndex: params => {
+      const index = params?.index;
+      if (typeof index !== "number") {
+        throw new Error("stackPopToIndex requires a numeric 'index'");
+      }
+      const actions = navigationStackStore.getActions();
+      if (!actions) throw new Error("navigation stack is not available");
+      actions.popToIndex(index);
+      return {
+        poppedToIndex: index
+      };
+    },
+    stackGoBack: () => {
+      const actions = navigationStackStore.getActions();
+      if (!actions) throw new Error("navigation stack is not available");
+      actions.goBack();
+      return {
+        wentBack: true
+      };
+    },
+    stackPopToTop: () => {
+      const actions = navigationStackStore.getActions();
+      if (!actions) throw new Error("navigation stack is not available");
+      actions.popToTop();
+      return {
+        poppedToTop: true
+      };
+    }
+  }
+};