@buoy-gg/route-events 3.0.1 → 4.0.1

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
+      };
+    }
+  }
+};

package/lib/module/useRouteSitemap.js

@@ -9,7 +9,7 @@
 
 import { useState, useEffect, useMemo, useCallback } from "react";
 import { RouteParser } from "./RouteParser";
-import { getRouteNodeMetadata, loadRouteNode } from "./expoRouterStore";
+import { getRouteNodeMetadata, isExpoRouterStoreSupported, loadRouteNode } from "./expoRouterStore";
 
 // Type-only definition to avoid Metro resolution issues
 
@@ -91,8 +91,12 @@ export 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] = useState(() => {
     const node = loadRouteNode();
     const metadata = getRouteNodeMetadata();
@@ -127,6 +131,16 @@ export 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 (!isExpoRouterStoreSupported()) {
+      return;
+    }
     let retryCount = 0;
     const maxRetries = 100; // 10 seconds max
 
@@ -139,7 +153,7 @@ export 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
   useEffect(() => {
@@ -147,13 +161,19 @@ export 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 : isExpoRouterStoreSupported();
+
+  // Parse routes (or use the pre-parsed routes injected from the dashboard).
   const routes = useMemo(() => {
+    if (hasInjectedRoutes) return injectedRoutes;
     if (!routeNode) return [];
     return RouteParser.parseRouteTree(routeNode);
-  }, [routeNode, routeNodeVersion]);
+  }, [routeNode, routeNodeVersion, hasInjectedRoutes, injectedRoutes]);
 
   // Sort routes
   const sortedRoutes = useMemo(() => {
@@ -185,11 +205,12 @@ export function useRouteSitemap(options = {}) {
     stats,
     filteredRoutes,
     isLoaded,
+    isSupported,
     refresh,
     findRoute,
     getParents,
-    lastUpdatedAt,
-    source
+    lastUpdatedAt: hasInjectedRoutes ? injectedLastUpdatedAt : lastUpdatedAt,
+    source: hasInjectedRoutes ? injectedSource : source
   };
 }
 

package/lib/typescript/RouteTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouteTracker.d.ts","sourceRoot":"","sources":["../../src/RouteTracker.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAgBH,wBAAgB,YAAY,gCAM3B"}
+{"version":3,"file":"RouteTracker.d.ts","sourceRoot":"","sources":["../../src/RouteTracker.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAgDH,wBAAgB,YAAY,gCAQ3B"}

package/lib/typescript/components/NavigationStack.d.ts

@@ -4,8 +4,31 @@
  * Shows all screens currently mounted in memory, which one is visible,
  * and provides controls to manipulate the stack.
  */
+import { type StackDisplayItem } from "../useNavigationStack";
+/** Stack manipulation a host can be asked to perform on the device. */
+export type NavigationStackActionType = "navigateToIndex" | "popToIndex" | "goBack" | "popToTop";
 export interface NavigationStackProps {
     style?: any;
+    /**
+     * Pre-captured stack supplied from outside the local runtime (the desktop
+     * dashboard receives it over the sync socket). When provided, the component
+     * renders this instead of reading the local navigation container.
+     */
+    injectedStack?: StackDisplayItem[];
+    /**
+     * Action delegate. When provided, stack actions (Back / Go / Pop To) call
+     * this instead of the local navigation container — the dashboard uses it to
+     * drive navigation on the connected device.
+     */
+    onAction?: (action: NavigationStackActionType, payload?: {
+        index?: number;
+    }) => void;
+    /**
+     * Reports the serialized stack (used for the "copy" toolbar action) up to the
+     * host so the copy button can live in the shared navbar instead of inside
+     * this component. Called whenever the stack changes.
+     */
+    onCopyValueChange?: (value: string) => void;
 }
-export declare function NavigationStack({ style }: NavigationStackProps): import("react").JSX.Element;
+export declare function NavigationStack({ style, injectedStack, onAction, onCopyValueChange, }: NavigationStackProps): import("react").JSX.Element;
 //# sourceMappingURL=NavigationStack.d.ts.map

package/lib/typescript/components/NavigationStack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NavigationStack.d.ts","sourceRoot":"","sources":["../../../src/components/NavigationStack.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,GAAG,CAAC;CACb;AAMD,wBAAgB,eAAe,CAAC,EAAE,KAAK,EAAE,EAAE,oBAAoB,+BAya9D"}
+{"version":3,"file":"NavigationStack.d.ts","sourceRoot":"","sources":["../../../src/components/NavigationStack.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAM/B,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,YAAY,GACZ,QAAQ,GACR,UAAU,CAAC;AAEf,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,GAAG,CAAC;IAEZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CACT,MAAM,EAAE,yBAAyB,EACjC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KACzB,IAAI,CAAC;IAEV;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7C;AAMD,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,aAAa,EACb,QAAQ,EACR,iBAAiB,GAClB,EAAE,oBAAoB,+BAgbtB"}

package/lib/typescript/components/RouteEventsModalWithTabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouteEventsModalWithTabs.d.ts","sourceRoot":"","sources":["../../../src/components/RouteEventsModalWithTabs.tsx"],"names":[],"mappings":"AAqDA,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,KAAK,IAAI,CAAC;IACvC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AA8CD,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,OAAO,EACP,MAAM,EACN,UAAU,EACV,2BAAmC,GACpC,EAAE,6BAA6B,sCAgiB/B"}
+{"version":3,"file":"RouteEventsModalWithTabs.d.ts","sourceRoot":"","sources":["../../../src/components/RouteEventsModalWithTabs.tsx"],"names":[],"mappings":"AAqDA,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,KAAK,IAAI,CAAC;IACvC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AA8CD,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,OAAO,EACP,MAAM,EACN,UAAU,EACV,2BAAmC,GACpC,EAAE,6BAA6B,sCA8iB/B"}

package/lib/typescript/components/RoutesSitemap.d.ts

@@ -8,8 +8,26 @@
  * - Copy to clipboard
  * - Navigation
  */
+import type { RouteInfo } from "../RouteParser";
 export interface RoutesSitemapProps {
     style?: any;
+    /**
+     * Pre-parsed route tree supplied from outside the local runtime (the desktop
+     * dashboard receives it over the sync socket). When provided, the component
+     * renders these routes instead of reading the local expo-router store.
+     */
+    injectedRoutes?: RouteInfo[];
+    /** Source label to display with injected routes. */
+    injectedSource?: "build" | "src" | null;
+    /** Last-updated timestamp to display with injected routes. */
+    injectedLastUpdatedAt?: number | null;
+    /**
+     * Navigation delegate. When provided, taps on a route call this instead of
+     * the local expo-router (the dashboard uses it to drive navigation on the
+     * connected device). The caller is responsible for any param resolution and
+     * Pro gating.
+     */
+    onNavigateRoute?: (route: RouteInfo) => void;
 }
-export declare function RoutesSitemap({ style }: RoutesSitemapProps): import("react").JSX.Element;
+export declare function RoutesSitemap({ style, injectedRoutes, injectedSource, injectedLastUpdatedAt, onNavigateRoute, }: RoutesSitemapProps): import("react").JSX.Element;
 //# sourceMappingURL=RoutesSitemap.d.ts.map

package/lib/typescript/components/RoutesSitemap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RoutesSitemap.d.ts","sourceRoot":"","sources":["../../../src/components/RoutesSitemap.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgCH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,GAAG,CAAC;CACb;AAmBD,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,EAAE,kBAAkB,+BA2W1D"}
+{"version":3,"file":"RoutesSitemap.d.ts","sourceRoot":"","sources":["../../../src/components/RoutesSitemap.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA4BH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,gBAAgB,CAAC;AAM5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,GAAG,CAAC;IAEZ;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,EAAE,CAAC;IAE7B,oDAAoD;IACpD,cAAc,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;IAExC,8DAA8D;IAC9D,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC9C;AAsCD,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,eAAe,GAChB,EAAE,kBAAkB,+BA8YpB"}

package/lib/typescript/expoRouterStore.d.ts

@@ -13,6 +13,14 @@ type ExpoRouterStore = {
  * 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 declare function isExpoRouterStoreSupported(): boolean;
 export declare function getExpoRouterStore(): ExpoRouterStore | null;
 /**
  * Returns the current RouteNode tree (if available).

package/lib/typescript/expoRouterStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expoRouterStore.d.ts","sourceRoot":"","sources":["../../src/expoRouterStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,KAAK,eAAe,GAAG;IACrB,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;KACzB,CAAC;CACH,CAAC;AAmBF;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAkD3D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,SAAS,GAAG,IAAI,CAqBhD;AAED,wBAAgB,oBAAoB,IAAI;IACtC,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAKA"}
+{"version":3,"file":"expoRouterStore.d.ts","sourceRoot":"","sources":["../../src/expoRouterStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,KAAK,eAAe,GAAG;IACrB,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;KACzB,CAAC;CACH,CAAC;AAmBF;;;;;;;GAOG;AACH;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAwD3D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,SAAS,GAAG,IAAI,CAqBhD;AAED,wBAAgB,oBAAoB,IAAI;IACtC,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAKA"}

package/lib/typescript/index.d.ts

@@ -13,7 +13,7 @@ export { RouteTracker } from "./RouteTracker";
 export { RoutesSitemap } from "./components/RoutesSitemap";
 export type { RoutesSitemapProps } from "./components/RoutesSitemap";
 export { NavigationStack } from "./components/NavigationStack";
-export type { NavigationStackProps } from "./components/NavigationStack";
+export type { NavigationStackProps, NavigationStackActionType, } from "./components/NavigationStack";
 export { RouteEventItemCompact } from "./components/RouteEventItemCompact";
 export type { RouteEventItemCompactProps } from "./components/RouteEventItemCompact";
 export { RouteEventExpandedContent } from "./components/RouteEventExpandedContent";
@@ -26,6 +26,8 @@ export { useRouteSitemap, useRoute, useParentRoutes } from "./useRouteSitemap";
 export type { UseRouteSitemapOptions, UseRouteSitemapResult, } from "./useRouteSitemap";
 export { useNavigationStack } from "./useNavigationStack";
 export type { UseNavigationStackResult, StackDisplayItem, } from "./useNavigationStack";
+export { routeEventsSyncAdapter } from "./sync/routeEventsSyncAdapter";
+export type { RouteSitemapSnapshot, RouteEventsSyncPayload, } from "./sync/routeEventsSyncAdapter";
 export type { RouteChangeEvent } from "./RouteObserver";
 export type { RouteInfo, RouteType, RouteGroup, RouteStats, } from "./RouteParser";
 export { RouteParser } from "./RouteParser";

package/lib/typescript/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAKxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,YAAY,EAAE,6BAA6B,EAAE,MAAM,uCAAuC,CAAC;AAK3F,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAK9C,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,YAAY,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACnF,YAAY,EAAE,8BAA8B,EAAE,MAAM,wCAAwC,CAAC;AAK7F,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EACV,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAK9B,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,UAAU,GACX,MAAM,eAAe,CAAC;AAKvB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAKhD,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,qEAAqE;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAKxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,YAAY,EAAE,6BAA6B,EAAE,MAAM,uCAAuC,CAAC;AAK3F,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAK9C,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EACV,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,YAAY,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACnF,YAAY,EAAE,8BAA8B,EAAE,MAAM,wCAAwC,CAAC;AAK7F,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EACV,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,YAAY,EACV,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AAKvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,UAAU,GACX,MAAM,eAAe,CAAC;AAKvB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAKhD,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,qEAAqE;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC"}

package/lib/typescript/stores/navigationStackStore.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+import type { StackDisplayItem } from "../useNavigationStack";
+export interface NavigationStackActions {
+    navigateToIndex: (index: number) => void;
+    popToIndex: (index: number) => void;
+    goBack: () => void;
+    popToTop: () => void;
+}
+declare class NavigationStackStore {
+    private stack;
+    private actions;
+    private listeners;
+    getStack(): StackDisplayItem[];
+    setStack(stack: StackDisplayItem[]): void;
+    getActions(): NavigationStackActions | null;
+    setActions(actions: NavigationStackActions | null): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare const navigationStackStore: NavigationStackStore;
+export {};
+//# sourceMappingURL=navigationStackStore.d.ts.map

package/lib/typescript/stores/navigationStackStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigationStackStore.d.ts","sourceRoot":"","sources":["../../../src/stores/navigationStackStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,cAAM,oBAAoB;IACxB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,SAAS,CAAyB;IAE1C,QAAQ,IAAI,gBAAgB,EAAE;IAI9B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAKzC,UAAU,IAAI,sBAAsB,GAAG,IAAI;IAI3C,UAAU,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,IAAI;IAIxD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CAM5C;AAED,eAAO,MAAM,oBAAoB,sBAA6B,CAAC"}

package/lib/typescript/sync/routeEventsSyncAdapter.d.ts

@@ -0,0 +1,69 @@
+import { type RouteInfo } from "../RouteParser";
+import type { RouteChangeEvent } from "../RouteObserver";
+import type { StackDisplayItem } from "../useNavigationStack";
+/**
+ * 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).
+ */
+export interface RouteSitemapSnapshot {
+    /** Parsed, nested route tree (same shape useRouteSitemap parses locally). */
+    routes: RouteInfo[];
+    /** Which expo-router path provided the store ("build" | "src"). */
+    source: "build" | "src" | null;
+    /** Timestamp of the most recent successful route-tree read on the device. */
+    lastUpdatedAt: number | null;
+}
+/**
+ * Payload shape for the route-events tool (adapter version 3). Consumers must
+ * tolerate older shapes: v1 sends a bare RouteChangeEvent[]; v2 omits `stack`.
+ */
+export interface RouteEventsSyncPayload {
+    events: RouteChangeEvent[];
+    sitemap: RouteSitemapSnapshot;
+    /** Live navigation stack (top-most last). Empty until a stack is captured. */
+    stack: StackDisplayItem[];
+}
+/**
+ * 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 declare const routeEventsSyncAdapter: {
+    version: number;
+    getSnapshot: () => RouteEventsSyncPayload;
+    subscribe: (onChange: () => void) => () => void;
+    actions: {
+        clearEvents: () => void;
+        /**
+         * Navigate the device to a concrete path. The dashboard resolves any
+         * dynamic params into a concrete path before invoking this.
+         */
+        navigate: (params: unknown) => {
+            navigated: string;
+        };
+        stackNavigateToIndex: (params: unknown) => {
+            navigatedToIndex: number;
+        };
+        stackPopToIndex: (params: unknown) => {
+            poppedToIndex: number;
+        };
+        stackGoBack: () => {
+            wentBack: boolean;
+        };
+        stackPopToTop: () => {
+            poppedToTop: boolean;
+        };
+    };
+};
+//# sourceMappingURL=routeEventsSyncAdapter.d.ts.map

package/lib/typescript/sync/routeEventsSyncAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeEventsSyncAdapter.d.ts","sourceRoot":"","sources":["../../../src/sync/routeEventsSyncAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,mEAAmE;IACnE,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;IAC/B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,8EAA8E;IAC9E,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAWD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB;;uBAEhB,sBAAsB;0BAKjB,MAAM,IAAI;;;QAkC9B;;;WAGG;2BACgB,OAAO;;;uCAcK,OAAO;;;kCAUZ,OAAO;;;;;;;;;;CAuBpC,CAAC"}

package/lib/typescript/useRouteSitemap.d.ts

@@ -24,6 +24,18 @@ export interface UseRouteSitemapOptions {
      * @default 1000
      */
     refreshInterval?: number;
+    /**
+     * Pre-parsed routes supplied from outside the local runtime (e.g. the desktop
+     * dashboard, which receives the device's route tree over the sync socket
+     * rather than reading expo-router directly). When provided, the local
+     * expo-router store is ignored: these routes drive the sort/filter/group/stats
+     * pipeline and `isSupported` is forced true.
+     */
+    injectedRoutes?: RouteInfo[];
+    /** Source label to surface alongside injected routes. */
+    injectedSource?: "build" | "src" | null;
+    /** Last-updated timestamp to surface alongside injected routes. */
+    injectedLastUpdatedAt?: number | null;
 }
 export interface UseRouteSitemapResult {
     /**
@@ -46,6 +58,11 @@ export interface UseRouteSitemapResult {
      * Is route data loaded
      */
     isLoaded: boolean;
+    /**
+     * Whether the route sitemap can be read in this runtime at all. False on the
+     * web/dashboard, where the route tree lives on the device rather than locally.
+     */
+    isSupported: boolean;
     /**
      * Manually refresh route data
      */

package/lib/typescript/useRouteSitemap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRouteSitemap.d.ts","sourceRoot":"","sources":["../../src/useRouteSitemap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAoEvB,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAElC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,SAAS,EAAE,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,UAAU,EAAE,CAAC;IAErB;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB;;OAEG;IACH,cAAc,EAAE,SAAS,EAAE,CAAC;IAE5B;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;IAE9C;;OAEG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;IAE1C;;OAEG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;OAEG;IACH,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;CAChC;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAuHvB;AAMD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAGzD"}
+{"version":3,"file":"useRouteSitemap.d.ts","sourceRoot":"","sources":["../../src/useRouteSitemap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAwEvB,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAElC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,SAAS,EAAE,CAAC;IAE7B,yDAAyD;IACzD,cAAc,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;IAExC,mEAAmE;IACnE,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,SAAS,EAAE,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,UAAU,EAAE,CAAC;IAErB;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB;;OAEG;IACH,cAAc,EAAE,SAAS,EAAE,CAAC;IAE5B;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;IAE9C;;OAEG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;IAE1C;;OAEG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;OAEG;IACH,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;CAChC;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CA4IvB;AAMD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAGzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/route-events",
-  "version": "3.0.1",
+  "version": "4.0.1",
   "description": "route-events package",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -26,12 +26,12 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@buoy-gg/floating-tools-core": "3.0.1",
-    "@buoy-gg/shared-ui": "3.0.1"
+    "@buoy-gg/floating-tools-core": "4.0.1",
+    "@buoy-gg/shared-ui": "4.0.1"
   },
   "peerDependencies": {
-    "@buoy-gg/license": "3.0.1",
-    "@react-native-async-storage/async-storage": "*",
+    "@buoy-gg/license": "4.0.1",
+    "@react-native-async-storage/async-storage": "^2.0.0 || ^3.1.0",
     "@react-navigation/native": "*",
     "expo-router": "*",
     "react": "*",
@@ -49,7 +49,7 @@
     "@types/react-native": "^0.73.0",
     "expo-router": "~5.0.7",
     "typescript": "~5.8.3",
-    "@buoy-gg/license": "3.0.1"
+    "@buoy-gg/license": "4.0.1"
   },
   "react-native-builder-bob": {
     "source": "src",