@buoy-gg/route-events 3.0.1 → 3.0.2

package/lib/commonjs/stores/navigationStackStore.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.navigationStackStore = void 0;
+/**
+ * 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);
+    };
+  }
+}
+const navigationStackStore = exports.navigationStackStore = new NavigationStackStore();

package/lib/commonjs/sync/routeEventsSyncAdapter.js

@@ -0,0 +1,148 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.routeEventsSyncAdapter = void 0;
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _routeEventStore = require("../stores/routeEventStore");
+var _navigationStackStore = require("../stores/navigationStackStore");
+var _RouteParser = require("../RouteParser");
+var _expoRouterStore = require("../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 = (0, _expoRouterStore.getRouteNodeMetadata)();
+  return {
+    routes: _RouteParser.RouteParser.parseRouteTree((0, _expoRouterStore.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.
+ */
+const routeEventsSyncAdapter = exports.routeEventsSyncAdapter = {
+  version: 3,
+  getSnapshot: () => ({
+    events: _routeEventStore.routeEventStore.getEvents(),
+    sitemap: getSitemapSnapshot(),
+    stack: _navigationStackStore.navigationStackStore.getStack()
+  }),
+  subscribe: onChange => {
+    const unsubscribeEvents = _routeEventStore.routeEventStore.subscribeToEvents(onChange);
+    const unsubscribeStack = _navigationStackStore.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 (!(0, _expoRouterStore.loadRouteNode)()) {
+      let retries = 0;
+      const maxRetries = 100; // ~10s
+      const poll = () => {
+        retries += 1;
+        if ((0, _expoRouterStore.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.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 = (0, _sharedUi.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.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.navigationStackStore.getActions();
+      if (!actions) throw new Error("navigation stack is not available");
+      actions.popToIndex(index);
+      return {
+        poppedToIndex: index
+      };
+    },
+    stackGoBack: () => {
+      const actions = _navigationStackStore.navigationStackStore.getActions();
+      if (!actions) throw new Error("navigation stack is not available");
+      actions.goBack();
+      return {
+        wentBack: true
+      };
+    },
+    stackPopToTop: () => {
+      const actions = _navigationStackStore.navigationStackStore.getActions();
+      if (!actions) throw new Error("navigation stack is not available");
+      actions.popToTop();
+      return {
+        poppedToTop: true
+      };
+    }
+  }
+};

package/lib/commonjs/useRouteSitemap.js

@@ -96,8 +96,12 @@ function useRouteSitemap(options = {}) {
     searchQuery = "",
     sortBy = "path",
     autoRefresh = false,
-    refreshInterval = 1000
+    refreshInterval = 1000,
+    injectedRoutes,
+    injectedSource = null,
+    injectedLastUpdatedAt = null
   } = options;
+  const hasInjectedRoutes = injectedRoutes != null;
   const [routeTreeState, setRouteTreeState] = (0, _react.useState)(() => {
     const node = (0, _expoRouterStore.loadRouteNode)();
     const metadata = (0, _expoRouterStore.getRouteNodeMetadata)();
@@ -132,6 +136,16 @@ function useRouteSitemap(options = {}) {
     if (routeNode) {
       return;
     }
+
+    // Routes injected from outside (dashboard) don't come from the local store.
+    if (hasInjectedRoutes) {
+      return;
+    }
+
+    // On web (no expo-router) the tree will never load — don't poll forever.
+    if (!(0, _expoRouterStore.isExpoRouterStoreSupported)()) {
+      return;
+    }
     let retryCount = 0;
     const maxRetries = 100; // 10 seconds max
 
@@ -144,7 +158,7 @@ function useRouteSitemap(options = {}) {
     };
     let timeoutRef = setTimeout(poll, 100);
     return () => clearTimeout(timeoutRef);
-  }, [routeNode, refresh]);
+  }, [routeNode, refresh, hasInjectedRoutes]);
 
   // Optional auto-refresh hook for callers that want periodic updates
   (0, _react.useEffect)(() => {
@@ -152,13 +166,19 @@ function useRouteSitemap(options = {}) {
     const interval = setInterval(refresh, refreshInterval);
     return () => clearInterval(interval);
   }, [autoRefresh, refreshInterval, refresh]);
-  const isLoaded = !!routeNode;
 
-  // Parse routes
+  // With injected routes we're "supported" regardless of the local runtime, and
+  // "loaded" once the device has actually sent a non-empty tree (an empty array
+  // means the device is still booting expo-router → keep showing "Loading...").
+  const isLoaded = hasInjectedRoutes ? injectedRoutes.length > 0 : !!routeNode;
+  const isSupported = hasInjectedRoutes ? true : (0, _expoRouterStore.isExpoRouterStoreSupported)();
+
+  // Parse routes (or use the pre-parsed routes injected from the dashboard).
   const routes = (0, _react.useMemo)(() => {
+    if (hasInjectedRoutes) return injectedRoutes;
     if (!routeNode) return [];
     return _RouteParser.RouteParser.parseRouteTree(routeNode);
-  }, [routeNode, routeNodeVersion]);
+  }, [routeNode, routeNodeVersion, hasInjectedRoutes, injectedRoutes]);
 
   // Sort routes
   const sortedRoutes = (0, _react.useMemo)(() => {
@@ -190,11 +210,12 @@ function useRouteSitemap(options = {}) {
     stats,
     filteredRoutes,
     isLoaded,
+    isSupported,
     refresh,
     findRoute,
     getParents,
-    lastUpdatedAt,
-    source
+    lastUpdatedAt: hasInjectedRoutes ? injectedLastUpdatedAt : lastUpdatedAt,
+    source: hasInjectedRoutes ? injectedSource : source
   };
 }
 

package/lib/module/RouteTracker.js

@@ -41,10 +41,13 @@
  * ```
  */
 
+import { useEffect } from "react";
 import { isExpoRouterAvailable } from "@buoy-gg/shared-ui";
 import { useRouteObserver } from "./useRouteObserver";
 import { useRouteObserverReactNavigation } from "./useRouteObserverReactNavigation";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { useNavigationStack } from "./useNavigationStack";
+import { navigationStackStore } from "./stores/navigationStackStore";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 function ExpoRouteTracker() {
   useRouteObserver();
   return null;
@@ -53,10 +56,41 @@ function ReactNavigationRouteTracker() {
   useRouteObserverReactNavigation();
   return null;
 }
+
+/**
+ * Mirrors the live navigation stack (and its action functions) into
+ * navigationStackStore so the route-events sync adapter can expose the Stack
+ * tab to the dashboard. Runs inside the navigation tree where the container ref
+ * context is available.
+ */
+function NavigationStackCapture() {
+  const {
+    stack,
+    navigateToIndex,
+    popToIndex,
+    goBack,
+    popToTop
+  } = useNavigationStack();
+  useEffect(() => {
+    navigationStackStore.setStack(stack);
+  }, [stack]);
+
+  // Keep the action references fresh (they change as the stack changes) so a
+  // remote action always operates on the current navigation state.
+  useEffect(() => {
+    navigationStackStore.setActions({
+      navigateToIndex,
+      popToIndex,
+      goBack,
+      popToTop
+    });
+    return () => navigationStackStore.setActions(null);
+  });
+  return null;
+}
 export function RouteTracker() {
   const hasExpo = isExpoRouterAvailable();
-  if (hasExpo) {
-    return /*#__PURE__*/_jsx(ExpoRouteTracker, {});
-  }
-  return /*#__PURE__*/_jsx(ReactNavigationRouteTracker, {});
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [hasExpo ? /*#__PURE__*/_jsx(ExpoRouteTracker, {}) : /*#__PURE__*/_jsx(ReactNavigationRouteTracker, {}), /*#__PURE__*/_jsx(NavigationStackCapture, {})]
+  });
 }

package/lib/module/components/NavigationStack.js

@@ -17,25 +17,35 @@ import { useNavigationStack } from "../useNavigationStack";
 // ============================================================================
 // Types
 // ============================================================================
+
+/** Stack manipulation a host can be asked to perform on the device. */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // ============================================================================
 // Main Component
 // ============================================================================
 
 export function NavigationStack({
-  style
+  style,
+  injectedStack,
+  onAction
 }) {
-  const {
-    stack,
-    focusedRoute,
-    stackDepth,
-    isAtRoot,
-    isLoaded,
-    error,
-    navigateToIndex,
-    goBack,
-    popToTop
-  } = useNavigationStack();
+  const hookResult = useNavigationStack();
+  const isInjected = injectedStack != null;
+
+  // Data source: injected (dashboard) or the local navigation container.
+  const stack = isInjected ? injectedStack : hookResult.stack;
+  const isLoaded = isInjected ? true : hookResult.isLoaded;
+  const error = isInjected ? null : hookResult.error;
+  const focusedRoute = useMemo(() => stack.find(item => item.isFocused) ?? null, [stack]);
+  const stackDepth = stack.length;
+  const isAtRoot = stackDepth <= 1;
+
+  // Action wrappers: delegate to the host when provided, else act locally.
+  const navigateToIndex = index => onAction ? onAction("navigateToIndex", {
+    index
+  }) : hookResult.navigateToIndex(index);
+  const goBack = () => onAction ? onAction("goBack") : hookResult.goBack();
+  const popToTop = () => onAction ? onAction("popToTop") : hookResult.popToTop();
   const [expandedIndex, setExpandedIndex] = useState(null);
   const [showHelp, setShowHelp] = useState(false);
   const [showUpgradeModal, setShowUpgradeModal] = useState(false);
@@ -124,6 +134,26 @@ export function NavigationStack({
   }
 
   // Handlers
+  // Confirm a destructive action. On device we use the native Alert; when an
+  // action delegate is set (dashboard, react-native-web) Alert button presses
+  // don't fire, so fall back to window.confirm.
+  const confirmDestructive = (title, message, confirmLabel, onConfirm) => {
+    if (onAction) {
+      const confirmFn = globalThis.window?.confirm;
+      if (!confirmFn || confirmFn(`${title}\n\n${message}`)) {
+        onConfirm();
+      }
+      return;
+    }
+    Alert.alert(title, message, [{
+      text: "Cancel",
+      style: "cancel"
+    }, {
+      text: confirmLabel,
+      style: "destructive",
+      onPress: onConfirm
+    }]);
+  };
   const handleGoBack = () => {
     // Gate behind Pro
     if (!isPro) {
@@ -146,14 +176,7 @@ export function NavigationStack({
       Alert.alert("Already at Top", "Stack only has one screen");
       return;
     }
-    Alert.alert("Pop to Top", "This will remove all screens except the root screen.", [{
-      text: "Cancel",
-      style: "cancel"
-    }, {
-      text: "Pop to Top",
-      style: "destructive",
-      onPress: popToTop
-    }]);
+    confirmDestructive("Pop to Top", "This will remove all screens except the root screen.", "Pop to Top", popToTop);
   };
   const toggleExpand = index => {
     setExpandedIndex(expandedIndex === index ? null : index);
@@ -195,17 +218,10 @@ export function NavigationStack({
       return;
     }
     const screensToRemove = stackDepth - 1 - selectedRoute.index;
-    Alert.alert("Pop to Route", `Remove ${screensToRemove} screen${screensToRemove !== 1 ? "s" : ""} above ${selectedRoute.pathname}?`, [{
-      text: "Cancel",
-      style: "cancel"
-    }, {
-      text: "Pop",
-      style: "destructive",
-      onPress: () => {
-        // Navigate to the selected route, which effectively pops everything above it
-        navigateToIndex(selectedRoute.index);
-      }
-    }]);
+    const targetIndex = selectedRoute.index;
+    confirmDestructive("Pop to Route", `Remove ${screensToRemove} screen${screensToRemove !== 1 ? "s" : ""} above ${selectedRoute.pathname}?`, "Pop",
+    // Navigate to the selected route, which effectively pops everything above it
+    () => navigateToIndex(targetIndex));
   };
   return /*#__PURE__*/_jsxs(View, {
     style: [styles.container, style],