@buoy-gg/route-events 6.0.0 → 6.0.1

package/README.md

@@ -1,654 +1,58 @@
-# @buoy/route-events
+# @buoy-gg/route-events
 
-A comprehensive route tracking and visualization toolkit for Expo Router applications. Monitor route changes, inspect navigation state, explore your route sitemap, and visualize the navigation stack.
+[![npm version](https://img.shields.io/npm/v/@buoy-gg/route-events?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/route-events) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/route-events?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/route-events)
 
-## Features
+**See every route in your app, watch navigation happen in real time, and jump to any screen from a full sitemap.**
 
-- **Route Event Tracking**: Automatically track all route changes with detailed event information
-- **Route Sitemap**: Browse all available routes in your app with search and navigation
-- **Navigation Stack Viewer**: Inspect the current navigation stack in real-time
-- **Event Timeline**: View a chronological timeline of all route changes
-- **Filtering & Search**: Filter events by pathname patterns and search through routes
-- **Persistent State**: Remembers your monitoring preferences and filters
-- **Full Modal UI**: Beautiful, production-ready modal interface for all features
+Part of [Buoy](https://github.com/Buoy-gg/buoy) — devtools that live inside your React Native app. Install it and it auto-appears in the floating menu from [`@buoy-gg/core`](https://www.npmjs.com/package/@buoy-gg/core).
 
-## Installation
+![Route Inspector demo](https://github.com/user-attachments/assets/90e55dc7-f8ab-423a-9770-84b9ff9c8446)
 
-This package is part of the React Buoy monorepo and is automatically available to other packages and the example app.
-
-For external projects:
+## Install
 
 ```bash
-npm install @buoy/route-events
-# or
-pnpm add @buoy/route-events
-# or
-yarn add @buoy/route-events
-```
-
-## Quick Start
-
-### Simplest Setup - Just 1 Line!
-
-**Import the preset and add it to your tools array. Done!**
-
-```typescript
-import { routeEventsToolPreset } from '@buoy/route-events';
-import { FloatingDevTools } from '@buoy/core';
-
-const installedApps = [
-  routeEventsToolPreset, // That's it! One line.
-  // ...your other tools
-];
-
-function App() {
-  return (
-    <FloatingDevTools
-      apps={installedApps}
-      environment="local"
-      userRole="admin"
-    />
-  );
-}
+npm install @buoy-gg/core @buoy-gg/route-events
 ```
 
-**Done!** The preset automatically:
-- ✅ Starts tracking routes when opened
-- ✅ Uses the built-in route observer singleton
-- ✅ Provides all three tabs (Routes, Events, Stack)
-- ✅ No configuration, no props, no hooks to call
-
-## Requirements
+## Quick start
 
-`@buoy/route-events` relies on the same core libraries as Expo Router itself:
-
-- `expo-router` ≥ 2.0.0 (the Routes tab reads `store.routeNode` directly)
-- `@react-navigation/native` ≥ 7.x (Stack tab + Expo Router routing hooks)
-- `@react-native-async-storage/async-storage` (state persistence)
-- `react` / `react-native`
-
-These packages are declared as `peerDependencies`, so your app decides the exact versions. When a dependency is missing or not initialized, the devtool logs a clear `[RouteEvents] ...` console message (in dev builds) and gracefully disables the affected feature instead of crashing. See `packages/route-events/docs/ROUTES_SITEMAP_ACCESS_GUIDE.md` for the full data-flow and troubleshooting guide.
-
-### Alternative: Manual Setup
-
-If you're not using FloatingDevTools or want more control:
-
-```typescript
-import { RouteEventsModalWithTabs } from '@buoy/route-events';
-
-function App() {
-  const [showRoutes, setShowRoutes] = useState(false);
+```tsx
+// app/_layout.tsx (Expo Router)
+import { Slot } from "expo-router";
+import { FloatingDevTools } from "@buoy-gg/core";
 
+export default function RootLayout() {
   return (
     <>
-      <Button onPress={() => setShowRoutes(true)}>
-        Open Route Inspector
-      </Button>
-
-      <RouteEventsModalWithTabs
-        visible={showRoutes}
-        onClose={() => setShowRoutes(false)}
-      />
+      <Slot />
+      <FloatingDevTools />
     </>
   );
 }
 ```
 
-## API Reference
-
-### Core Components
-
-#### `RouteEventsModalWithTabs`
-
-The main modal interface with three tabs: Routes, Events, and Stack.
-
-**Props:**
-
-```typescript
-interface RouteEventsModalWithTabsProps {
-  /** Whether the modal is visible */
-  visible: boolean;
-  /** Callback when modal is closed */
-  onClose: () => void;
-  /** Optional back button handler */
-  onBack?: () => void;
-  /** Whether to use shared modal dimensions */
-  enableSharedModalDimensions?: boolean;
-  /** 
-   * Optional route observer instance. 
-   * If not provided, uses the default singleton (recommended).
-   * Route tracking starts automatically when the modal is opened.
-   */
-  routeObserver?: RouteObserver;
-}
-```
-
-**Example:**
-
-```typescript
-<RouteEventsModalWithTabs
-  visible={isVisible}
-  onClose={handleClose}
-/>
-```
-
-**Advanced Example (with custom observer):**
-
-Only needed if you want to use a custom route observer instance:
-
-```typescript
-import { RouteEventsModalWithTabs, routeObserver } from '@buoy/route-events';
-
-<RouteEventsModalWithTabs
-  visible={isVisible}
-  onClose={handleClose}
-  routeObserver={routeObserver} // Optional - uses default if not provided
-/>
-```
-
-#### `RoutesSitemap`
-
-Standalone component for browsing all routes in your application.
-
-**Props:**
-
-```typescript
-interface RoutesSitemapProps {
-  style?: StyleProp<ViewStyle>;
-}
-```
-
-**Example:**
-
-```typescript
-import { RoutesSitemap } from '@buoy/route-events';
-
-function RoutesScreen() {
-  return <RoutesSitemap />;
-}
-```
-
-#### `NavigationStack`
-
-Standalone component for visualizing the current navigation stack.
-
-**Props:**
-
-```typescript
-interface NavigationStackProps {
-  style?: StyleProp<ViewStyle>;
-}
-```
-
-**Example:**
-
-```typescript
-import { NavigationStack } from '@buoy/route-events';
-
-function DebugScreen() {
-  return <NavigationStack />;
-}
-```
-
-### Hooks
-
-#### `useRouteObserver`
-
-Hook to track route changes and emit events to the global observer.
-
-**Note:** You typically don't need to use this hook directly - the `RouteEventsModalWithTabs` component starts tracking automatically. This hook is only needed for advanced use cases like custom analytics.
-
-**Signature:**
-
-```typescript
-function useRouteObserver(
-  callback?: (event: RouteChangeEvent) => void
-): void
-```
-
-**Examples:**
-
-```typescript
-// Only needed for custom analytics - modal handles tracking automatically!
-import { useRouteObserver } from '@buoy/route-events';
-
-export default function RootLayout() {
-  useRouteObserver((event) => {
-    analytics.trackPageView(event.pathname);
-  });
-
-  return <Stack />;
-}
-```
-
-#### `useRouteSitemap`
-
-Access route information from your app's file-based routing structure.
-
-**Signature:**
-
-```typescript
-function useRouteSitemap(
-  options?: UseRouteSitemapOptions
-): UseRouteSitemapResult
-```
-
-**Options:**
-
-```typescript
-interface UseRouteSitemapOptions {
-  /** Whether to include layout routes */
-  includeLayouts?: boolean;
-  /** Whether to include route groups */
-  includeGroups?: boolean;
-}
-```
-
-**Result:**
-
-```typescript
-interface UseRouteSitemapResult {
-  /** All routes in the application */
-  routes: RouteInfo[];
-  /** Routes grouped by directory */
-  groups: RouteGroup[];
-  /** Statistics about the routes */
-  stats: RouteStats;
-  /** Get a specific route by path */
-  getRoute: (path: string) => RouteInfo | undefined;
-  /** Get all parent routes of a path */
-  getParents: (path: string) => RouteInfo[];
-}
-```
-
-**Example:**
-
-```typescript
-import { useRouteSitemap } from '@buoy/route-events';
-
-function RouteDebugger() {
-  const { routes, stats, getRoute } = useRouteSitemap();
-
-  console.log(`Total routes: ${stats.total}`);
-  console.log(`Dynamic routes: ${stats.byType.dynamic}`);
-  
-  const homeRoute = getRoute('/');
-  // { path: '/', type: 'index', ... }
-
-  return (
-    <View>
-      {routes.map(route => (
-        <Text key={route.path}>{route.path}</Text>
-      ))}
-    </View>
-  );
-}
-```
-
-#### `useNavigationStack`
-
-Access and control the current navigation stack.
+That's it. `FloatingDevTools` detects the package, mounts the route tracker for you, and the ROUTES tool shows up in the menu. It auto-detects whether you're on Expo Router or React Navigation and adapts.
 
-**Signature:**
+## What you get
 
-```typescript
-function useNavigationStack(): UseNavigationStackResult
-```
+- **Full sitemap** — browse every route in your app, searchable, with route types (static, dynamic, layout) labeled
+- **Jump to any screen** — tap a route in the sitemap and navigate straight to it, params and all
+- **Live navigation stack** — watch the stack push, pop, and replace as you move through the app
+- **Navigation event timeline** — every navigation logged with path, params, timestamp, and time since the previous one
+- **Filtering & search** — filter events by pathname pattern, search across routes
+- **Zero setup** — no `<RouteTracker />` to place, no config; the core menu wires it automatically
+- **Hooks for custom UIs** — `useRouteEvents`, `useRouteSitemap`, and `useNavigationStack` if you want the data without the modal
 
-**Result:**
-
-```typescript
-interface UseNavigationStackResult {
-  /** The current navigation stack */
-  stack: StackDisplayItem[];
-  /** Whether the data is loading */
-  loading: boolean;
-  /** Navigate to a specific stack index */
-  navigateToIndex: (index: number) => void;
-  /** Pop back to a specific index */
-  popToIndex: (index: number) => void;
-  /** Go back one screen */
-  goBack: () => void;
-  /** Go to the root of the stack */
-  popToTop: () => void;
-}
-```
-
-**Example:**
-
-```typescript
-import { useNavigationStack } from '@buoy/route-events';
-
-function NavigationDebugger() {
-  const { stack, goBack, popToTop } = useNavigationStack();
-
-  return (
-    <View>
-      <Text>Stack Depth: {stack.length}</Text>
-      <Button onPress={goBack}>Go Back</Button>
-      <Button onPress={popToTop}>Go to Root</Button>
-      
-      {stack.map((item, index) => (
-        <Text key={item.key}>
-          {index}: {item.displayPath}
-        </Text>
-      ))}
-    </View>
-  );
-}
-```
-
-### Utilities
-
-#### `RouteObserver`
-
-Singleton instance for observing route changes.
-
-**Methods:**
-
-```typescript
-class RouteObserver {
-  /** Emit a route change event */
-  emit(event: RouteChangeEvent): void;
-  
-  /** Add a listener for route changes */
-  addListener(callback: (event: RouteChangeEvent) => void): () => void;
-  
-  /** Remove a listener */
-  removeListener(callback: (event: RouteChangeEvent) => void): void;
-}
-```
-
-**Example:**
-
-```typescript
-import { routeObserver } from '@buoy/route-events';
-
-// Add listener
-const unsubscribe = routeObserver.addListener((event) => {
-  console.log('Route changed:', event.pathname);
-});
-
-// Later, remove listener
-unsubscribe();
-```
-
-#### `RouteParser`
-
-Utility for parsing Expo Router's route structure.
-
-**Methods:**
-
-```typescript
-class RouteParser {
-  /** Get all routes from the router */
-  static getRoutes(options?: {
-    includeLayouts?: boolean;
-    includeGroups?: boolean;
-  }): RouteInfo[];
-  
-  /** Group routes by directory */
-  static groupRoutes(routes: RouteInfo[]): RouteGroup[];
-  
-  /** Get statistics about routes */
-  static getStats(routes: RouteInfo[]): RouteStats;
-}
-```
-
-### Types
-
-#### `RouteChangeEvent`
-
-```typescript
-interface RouteChangeEvent {
-  /** Current pathname */
-  pathname: string;
-  /** Route parameters */
-  params: Record<string, string | string[]>;
-  /** Route segments */
-  segments: string[];
-  /** Timestamp of the change */
-  timestamp: number;
-  /** Previous pathname (if available) */
-  previousPathname?: string;
-  /** Time since previous navigation in ms */
-  timeSincePrevious?: number;
-}
-```
-
-#### `RouteInfo`
-
-```typescript
-interface RouteInfo {
-  /** Full path of the route */
-  path: string;
-  /** Route type */
-  type: RouteType;
-  /** Route name/file */
-  name: string;
-  /** Dynamic parameters */
-  params: string[];
-  /** Whether it's a layout */
-  isLayout: boolean;
-  /** Whether it's a route group */
-  isGroup: boolean;
-  /** Parent path */
-  parent?: string;
-}
-```
-
-#### `RouteType`
-
-```typescript
-type RouteType =
-  | 'index'      // index routes (/)
-  | 'static'     // static routes (/about)
-  | 'dynamic'    // dynamic routes (/user/[id])
-  | 'catch-all'  // catch-all routes (/docs/[...path])
-  | 'layout'     // layout routes (_layout.tsx)
-  | 'group';     // route groups ((tabs))
-```
-
-## Use Cases
-
-### Analytics Integration
-
-```typescript
-import { useRouteObserver } from '@buoy/route-events';
-
-export default function RootLayout() {
-  useRouteObserver((event) => {
-    // Track page views
-    analytics.trackPageView({
-      path: event.pathname,
-      params: event.params,
-      previousPath: event.previousPathname,
-      timeSpent: event.timeSincePrevious,
-    });
-  });
-
-  return <Stack />;
-}
-```
-
-### Performance Monitoring
-
-```typescript
-import { useRouteObserver } from '@buoy/route-events';
-
-export default function RootLayout() {
-  useRouteObserver((event) => {
-    if (event.timeSincePrevious && event.timeSincePrevious > 1000) {
-      // Log slow navigations
-      console.warn('Slow navigation:', {
-        from: event.previousPathname,
-        to: event.pathname,
-        duration: event.timeSincePrevious,
-      });
-    }
-  });
-
-  return <Stack />;
-}
-```
-
-### Development Tools
-
-```typescript
-import { RouteEventsModalWithTabs, routeObserver } from '@buoy/route-events';
-
-function DevTools() {
-  const [visible, setVisible] = useState(false);
-  
-  // Only show in development
-  if (__DEV__) {
-    return (
-      <>
-        <TouchableOpacity 
-          style={styles.devButton}
-          onPress={() => setVisible(true)}
-        >
-          <Text>🧭 Routes</Text>
-        </TouchableOpacity>
-        
-        <RouteEventsModalWithTabs
-          visible={visible}
-          onClose={() => setVisible(false)}
-          routeObserver={routeObserver}
-        />
-      </>
-    );
-  }
-  
-  return null;
-}
-```
-
-### Route Documentation
-
-```typescript
-import { useRouteSitemap } from '@buoy/route-events';
-
-function RouteDocumentation() {
-  const { routes, groups, stats } = useRouteSitemap({
-    includeLayouts: false,
-    includeGroups: false,
-  });
-
-  return (
-    <ScrollView>
-      <Text>Total Routes: {stats.total}</Text>
-      
-      {groups.map(group => (
-        <View key={group.name}>
-          <Text>{group.name} ({group.routes.length})</Text>
-          {group.routes.map(route => (
-            <Text key={route.path}>
-              {route.path} - {route.type}
-            </Text>
-          ))}
-        </View>
-      ))}
-    </ScrollView>
-  );
-}
-```
-
-## Features in Detail
-
-### Routes Tab
-
-- Browse all routes in your application
-- Search routes by path or name
-- View route types (static, dynamic, catch-all)
-- Navigate to any route directly
-- Handles dynamic route parameters with prompts
-- Group and layout route identification
-
-### Events Tab
-
-- Real-time route change monitoring
-- Toggle monitoring on/off
-- Event timeline with timestamps
-- Filter events by pathname patterns
-- Search through event history
-- View detailed event information
-- Compare route changes (diff view)
-- Clear event history
-- Persistent filter preferences
-
-### Stack Tab
-
-- Real-time navigation stack visualization
-- Stack depth indicator
-- Navigate to any stack level
-- Pop to specific stack index
-- Quick navigation controls
-- Route parameter display
-
-## Dependencies
-
-- `@buoy/shared-ui` - Common UI components and utilities
-- `expo-router` - Expo Router integration (peer dependency)
-- `@react-navigation/native` - React Navigation integration (peer dependency)
-- `@react-native-async-storage/async-storage` - For persistent preferences (peer dependency)
-- React and React Native (peer dependencies)
-
-## Development
-
-### Building
-
-```bash
-pnpm build
-```
-
-### Type Checking
-
-```bash
-pnpm typecheck
-```
-
-### Clean Build
-
-```bash
-pnpm clean
-```
-
-## Package Structure
-
-```
-route-events/
-├── src/
-│   ├── components/           # UI components
-│   │   ├── RouteEventsModalWithTabs.tsx
-│   │   ├── RoutesSitemap.tsx
-│   │   ├── NavigationStack.tsx
-│   │   ├── RouteEventsTimeline.tsx
-│   │   ├── RouteEventItemCompact.tsx
-│   │   ├── RouteEventDetailContent.tsx
-│   │   ├── RouteEventExpandedContent.tsx
-│   │   └── RouteFilterViewV2.tsx
-│   ├── RouteObserver.ts     # Event system
-│   ├── RouteParser.ts       # Route parsing utilities
-│   ├── useRouteObserver.ts  # Route tracking hook
-│   ├── useRouteSitemap.ts   # Sitemap access hook
-│   ├── useNavigationStack.ts # Stack access hook
-│   └── index.tsx            # Main exports
-├── lib/                     # Built output (git ignored)
-├── package.json
-├── tsconfig.json
-├── tsconfig.build.json
-└── README.md
-```
+## Desktop & AI
 
-## License
+The same live session streams to [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop) (free, macOS/Windows/Linux) and to Claude Code or Cursor via the [Buoy MCP server](https://buoy.gg/buoy/latest/docs/mcp).
 
-MIT
+## Free vs Pro
 
-## Contributing
+Every tool is free. [Pro](https://buoy.gg/pricing) unlocks production builds, the MCP server, and unlimited capture. Every weekend, Pro features unlock free for everyone.
 
-See the main repository [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.
+---
 
-## Support
+📚 [Full docs](https://buoy.gg/buoy/latest/docs/tools/routes) · [All Buoy tools](https://github.com/Buoy-gg/buoy)
 
-For issues and feature requests, please visit the [GitHub repository](https://github.com/LovesWorking/react-native-buoy/issues).
+Proprietary software. © Buoy LLC. [Terms](https://buoy.gg/terms)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buoy-gg/route-events",
-  "version": "6.0.0",
-  "description": "route-events package",
+  "version": "6.0.1",
+  "description": "Navigation devtool for React Native — live stack, full sitemap, jump to any screen. Expo Router & React Navigation. Part of Buoy devtools.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "types": "lib/typescript/index.d.ts",
@@ -26,11 +26,11 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@buoy-gg/shared-ui": "6.0.0",
-    "@buoy-gg/floating-tools-core": "6.0.0"
+    "@buoy-gg/floating-tools-core": "6.0.1",
+    "@buoy-gg/shared-ui": "6.0.1"
   },
   "peerDependencies": {
-    "@buoy-gg/license": "6.0.0",
+    "@buoy-gg/license": "6.0.1",
     "@react-native-async-storage/async-storage": "^2.0.0 || ^3.1.0",
     "@react-navigation/native": "*",
     "expo-router": "*",
@@ -49,7 +49,7 @@
     "@types/react-native": "^0.73.0",
     "expo-router": "~5.0.7",
     "typescript": "~5.8.3",
-    "@buoy-gg/license": "6.0.0"
+    "@buoy-gg/license": "6.0.1"
   },
   "react-native-builder-bob": {
     "source": "src",