@buoy-gg/route-events 1.7.2

package/lib/module/expoRouterStore.js

@@ -0,0 +1,98 @@
+"use strict";
+
+let cachedStore = null;
+let cachedStoreSource = null;
+let importError = null;
+let hasLoggedMissingStore = false;
+let hasLoggedMissingRouteNode = false;
+let lastRouteNodeTimestamp = null;
+function logOnce(message, error) {
+  if (__DEV__) {
+    if (error) {
+      console.error(`[RouteEvents] ${message}`, error);
+    } else {
+      console.warn(`[RouteEvents] ${message}`);
+    }
+  }
+}
+
+/**
+ * Attempt to require the expo-router store from known locations.
+ * Returns null (with a logged error in dev) when expo-router is not available.
+ *
+ * Note: The store uses getters that read from an internal storeRef.
+ * The storeRef gets populated when Expo Router's useStore() hook runs.
+ * So we cache the store reference but its property values update over time.
+ */
+export function getExpoRouterStore() {
+  if (cachedStore) {
+    return cachedStore;
+  }
+  const loadFromBuild = () => {
+    try {
+      const module = require("expo-router/build/global-state/router-store");
+      if (module?.store) {
+        cachedStore = module.store;
+        cachedStoreSource = "build";
+        importError = null;
+        hasLoggedMissingStore = false;
+        return true;
+      }
+    } catch (error) {
+      importError = error;
+    }
+    return false;
+  };
+  const loadFromSrc = () => {
+    try {
+      const module = require("expo-router/src/global-state/router-store");
+      if (module?.store) {
+        cachedStore = module.store;
+        cachedStoreSource = "src";
+        importError = null;
+        hasLoggedMissingStore = false;
+        return true;
+      }
+    } catch (error) {
+      importError = error;
+    }
+    return false;
+  };
+  if (loadFromBuild() || loadFromSrc()) {
+    return cachedStore;
+  }
+  if (!hasLoggedMissingStore) {
+    logOnce("Unable to load expo-router internals. @buoy-gg/route-events requires expo-router >= 2.0.0. Install expo-router and ensure it is configured before using the Routes tab.", importError ?? undefined);
+    hasLoggedMissingStore = true;
+  }
+  return null;
+}
+
+/**
+ * Returns the current RouteNode tree (if available).
+ * Logs a helpful warning in development when the tree is missing even though
+ * the navigation ref is ready.
+ */
+export function loadRouteNode() {
+  const store = getExpoRouterStore();
+  if (!store) {
+    return null;
+  }
+  if (store.routeNode) {
+    hasLoggedMissingRouteNode = false;
+    lastRouteNodeTimestamp = Date.now();
+    return store.routeNode;
+  }
+  const isReady = store.navigationRef?.isReady?.();
+  if (__DEV__ && !hasLoggedMissingRouteNode && isReady) {
+    logOnce("Expo Router route tree is unavailable. Ensure your app directory is configured and that expo-router is initialized before opening the Route Events devtool.");
+    hasLoggedMissingRouteNode = true;
+  }
+  return null;
+}
+export function getRouteNodeMetadata() {
+  return {
+    source: cachedStoreSource,
+    lastLoadedAt: lastRouteNodeTimestamp
+  };
+}

package/lib/module/index.js

@@ -0,0 +1,23 @@
+"use strict";
+
+// Export route events modal (primary export - everything you need!)
+export { RouteEventsModalWithTabs } from "./components/RouteEventsModalWithTabs";
+// Export preset configuration (easiest way to add to FloatingDevTools!)
+export { routeEventsToolPreset, createRouteEventsTool } from "./preset";
+
+// Export RouteTracker component - place inside your navigation tree for route tracking
+export { RouteTracker } from "./RouteTracker";
+
+// Export individual components for advanced usage
+export { RoutesSitemap } from "./components/RoutesSitemap";
+export { NavigationStack } from "./components/NavigationStack";
+// Export advanced/optional utilities
+// Note: Most users won't need these - the modal handles everything automatically
+export { RouteObserver, routeObserver } from "./RouteObserver";
+export { useRouteObserver } from "./useRouteObserver";
+// Export route parser utilities for advanced use cases
+export { RouteParser } from "./RouteParser";
+// Export route sitemap hooks for advanced use cases
+export { useRouteSitemap, useRoute, useParentRoutes } from "./useRouteSitemap";
+// Export navigation stack utilities for advanced use cases
+export { useNavigationStack } from "./useNavigationStack";

package/lib/module/preset.js

@@ -0,0 +1,79 @@
+"use strict";
+
+/**
+ * Pre-configured route events tool for FloatingDevTools
+ *
+ * This preset provides a zero-config way to add route tracking to your dev tools.
+ * Just import and spread it into your apps array!
+ *
+ * @example
+ * ```tsx
+ * import { routeEventsToolPreset } from '@buoy-gg/route-events';
+ *
+ * const installedApps = [
+ *   routeEventsToolPreset, // That's it!
+ *   // ...other tools
+ * ];
+ * ```
+ */
+
+import { RoutesIcon } from "@buoy-gg/floating-tools-core";
+import { RouteEventsModalWithTabs } from "./components/RouteEventsModalWithTabs";
+
+/**
+ * Pre-configured route events tool for FloatingDevTools.
+ * Includes:
+ * - Route sitemap browser
+ * - Event timeline with filtering
+ * - Navigation stack visualization
+ * - Automatic route tracking (no setup needed)
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export const routeEventsToolPreset = {
+  id: "route-events",
+  name: "ROUTES",
+  description: "Route tracking & navigation inspector",
+  slot: "both",
+  icon: ({
+    size
+  }) => /*#__PURE__*/_jsx(RoutesIcon, {
+    size: size
+  }),
+  component: RouteEventsModalWithTabs,
+  props: {
+    enableSharedModalDimensions: false
+  }
+};
+
+/**
+ * Create a custom route events tool configuration.
+ * Use this if you want to override default settings.
+ *
+ * @example
+ * ```tsx
+ * import { createRouteEventsTool } from '@buoy-gg/route-events';
+ *
+ * const myRouteTool = createRouteEventsTool({
+ *   name: "MY ROUTES",
+ *   color: "#a78bfa",
+ *   enableSharedModalDimensions: true,
+ * });
+ * ```
+ */
+export function createRouteEventsTool(options) {
+  return {
+    id: options?.id || "route-events",
+    name: options?.name || "ROUTES",
+    description: options?.description || "Route tracking & navigation inspector",
+    slot: "both",
+    icon: ({
+      size
+    }) => /*#__PURE__*/_jsx(RoutesIcon, {
+      size: size
+    }),
+    component: RouteEventsModalWithTabs,
+    props: {
+      enableSharedModalDimensions: options?.enableSharedModalDimensions !== undefined ? options.enableSharedModalDimensions : false
+    }
+  };
+}

package/lib/module/useNavigationStack.js

@@ -0,0 +1,238 @@
+"use strict";
+
+/**
+ * useNavigationStack - Hook to access current navigation stack state
+ *
+ * Provides real-time access to the navigation stack from Expo Router,
+ * showing what screens are currently mounted in memory and which is visible.
+ *
+ * Data source: @react-navigation/native
+ */
+
+import { useState, useEffect, useMemo } from "react";
+import { useNavigation, useNavigationState } from "@react-navigation/native";
+import { router } from "expo-router";
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+// ============================================================================
+// Main Hook
+// ============================================================================
+
+/**
+ * Recursively collect all routes from the navigation state tree
+ */
+function collectRoutesFromState(state, depth = 0, parentPath = "") {
+  if (!state || !state.routes) return [];
+  const routes = [];
+  for (let i = 0; i < state.routes.length; i++) {
+    const route = state.routes[i];
+    const isFocused = i === state.index;
+
+    // Build the path
+    let pathname = route.name;
+    if (route.name === "index") {
+      pathname = "/";
+    } else if (!pathname.startsWith("/")) {
+      pathname = `/${pathname}`;
+    }
+
+    // Add parent path
+    if (parentPath && parentPath !== "/") {
+      pathname = `${parentPath}${pathname}`;
+    }
+
+    // Add params to pathname for dynamic routes
+    if (route.params) {
+      const paramEntries = Object.entries(route.params);
+      if (paramEntries.length > 0) {
+        pathname = pathname.replace(/\[([^\]]+)\]/g, (match, param) => {
+          return route.params[param] || match;
+        });
+      }
+    }
+    routes.push({
+      key: route.key,
+      name: route.name,
+      path: pathname,
+      params: route.params || {},
+      state: route.state
+    });
+
+    // If this route has nested state and is focused, recurse
+    if (isFocused && route.state) {
+      const nestedRoutes = collectRoutesFromState(route.state, depth + 1, pathname);
+      routes.push(...nestedRoutes);
+    }
+  }
+  return routes;
+}
+
+/**
+ * Access the current navigation stack from Expo Router
+ *
+ * @example
+ * ```tsx
+ * const { stack, focusedRoute, goBack, popToTop } = useNavigationStack();
+ *
+ * // Display stack
+ * stack.map(item => (
+ *   <View key={item.key}>
+ *     <Text>{item.pathname}</Text>
+ *     {item.isFocused && <Text>VISIBLE</Text>}
+ *   </View>
+ * ));
+ * ```
+ */
+export function useNavigationStack() {
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState(null);
+  const navigation = useNavigation();
+
+  // Subscribe to navigation state changes - this will cause re-renders when state updates
+  const navigationState = useNavigationState(state => state);
+
+  // Mark as loaded once we have navigation
+  useEffect(() => {
+    setIsLoaded(true);
+  }, []);
+
+  // Transform navigation state into display items
+  const stack = useMemo(() => {
+    if (!navigationState) return [];
+    try {
+      const routes = collectRoutesFromState(navigationState);
+
+      // Filter out internal Expo Router routes (layouts, __root, etc.)
+      const filteredRoutes = routes.filter(route => {
+        // Remove __root and other internal routes
+        if (route.name.startsWith("__")) return false;
+        if (route.name.includes("_layout")) return false;
+        if (route.name.startsWith("+not-found")) return false;
+        return true;
+      });
+
+      // If we filtered everything out, just keep the last route
+      const finalRoutes = filteredRoutes.length > 0 ? filteredRoutes : routes.slice(-1);
+
+      // The last route in the collected list is the focused one
+      return finalRoutes.map((route, index) => {
+        // Clean up pathname by removing /__root prefix
+        let cleanPath = route.path || `/${route.name}`;
+        cleanPath = cleanPath.replace(/^\/__root/, "");
+        // Ensure we always have at least a /
+        if (!cleanPath || cleanPath === "") {
+          cleanPath = "/";
+        }
+        return {
+          key: route.key,
+          name: route.name,
+          pathname: cleanPath,
+          params: route.params || {},
+          isFocused: index === finalRoutes.length - 1,
+          index,
+          canPop: index > 0
+        };
+      });
+    } catch (err) {
+      console.error("Error transforming navigation state:", err);
+      return [];
+    }
+  }, [navigationState]);
+
+  // Get focused route
+  const focusedRoute = useMemo(() => {
+    return stack.find(item => item.isFocused) || null;
+  }, [stack]);
+
+  // Helper properties
+  const stackDepth = stack.length;
+  const isAtRoot = stackDepth <= 1;
+
+  // Manual refresh (no-op since we're using React Navigation's state)
+  const refresh = () => {
+    // Navigation state updates automatically via useNavigationState
+  };
+
+  // Navigation actions
+  const navigateToIndex = index => {
+    if (index >= stack.length || index < 0) {
+      return;
+    }
+    const targetRoute = stack[index];
+    if (!targetRoute) {
+      return;
+    }
+
+    // Use router directly from expo-router
+    if (!router) {
+      return;
+    }
+    try {
+      router.navigate(targetRoute.pathname);
+    } catch (err) {
+      console.error("Failed to navigate:", err);
+    }
+  };
+  const popToIndex = index => {
+    if (index >= stack.length || index < 0) {
+      return;
+    }
+    const currentIndex = stack.length - 1;
+    const popCount = currentIndex - index;
+    if (popCount <= 0) {
+      return;
+    }
+
+    // Use router directly from expo-router
+    if (!router) {
+      return;
+    }
+    try {
+      // Pop multiple times
+      for (let i = 0; i < popCount; i++) {
+        router.back();
+      }
+    } catch (err) {
+      console.error("Failed to pop:", err);
+    }
+  };
+  const goBack = () => {
+    if (isAtRoot) {
+      return;
+    }
+
+    // Use router directly from expo-router
+    if (!router) {
+      return;
+    }
+    try {
+      router.back();
+    } catch (err) {
+      console.error("Failed to go back:", err);
+    }
+  };
+  const popToTop = () => {
+    if (isAtRoot) {
+      return;
+    }
+
+    // Pop to index 0 (root)
+    popToIndex(0);
+  };
+  return {
+    stack,
+    focusedRoute,
+    stackDepth,
+    isAtRoot,
+    isLoaded,
+    error,
+    refresh,
+    navigateToIndex,
+    popToIndex,
+    goBack,
+    popToTop
+  };
+}

package/lib/module/useRouteObserver.js

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * useRouteObserver - React hook for observing route changes
+ *
+ * Uses public Expo Router hooks to track route changes and emits them
+ * to the global RouteObserver singleton.
+ */
+
+import { useEffect, useRef } from "react";
+import { usePathname, useSegments, useGlobalSearchParams } from "expo-router";
+import { routeObserver } from "./RouteObserver";
+
+/**
+ * Hook to observe route changes in Expo Router
+ * Automatically emits events to the global RouteObserver
+ *
+ * @param callback - Optional function to call on route changes (in addition to the observer)
+ *
+ * @example
+ * ```tsx
+ * // Just track routes (no custom callback)
+ * useRouteObserver();
+ *
+ * // Track routes with custom callback
+ * useRouteObserver((event) => {
+ *   // Handle route change
+ *   analytics.trackPageView(event.pathname);
+ * });
+ * ```
+ */
+export function useRouteObserver(callback) {
+  const pathname = usePathname();
+  const segments = useSegments();
+  const params = useGlobalSearchParams();
+  const callbackRef = useRef(callback);
+  const previousPathnameRef = useRef(undefined);
+  const previousTimestampRef = useRef(undefined);
+
+  // Update ref when callback changes
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  // Trigger observer and callback whenever route changes
+  useEffect(() => {
+    const now = Date.now();
+    const timeSincePrevious = previousTimestampRef.current ? now - previousTimestampRef.current : undefined;
+    const event = {
+      pathname,
+      params: params,
+      segments: segments,
+      timestamp: now,
+      previousPathname: previousPathnameRef.current,
+      timeSincePrevious
+    };
+
+    // Update refs for next navigation
+    previousPathnameRef.current = pathname;
+    previousTimestampRef.current = now;
+
+    // Emit to the global observer (this notifies the modal)
+    routeObserver.emit(event);
+
+    // Also call the custom callback if provided
+    if (callbackRef.current) {
+      callbackRef.current(event);
+    }
+  }, [pathname, segments, params]);
+}