@buoy-gg/route-events 5.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/lib/commonjs/components/RouteEventItemCompact.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.RouteEventItemCompact = RouteEventItemCompact;
+exports.RouteEventItemCompact = void 0;
 var _react = require("react");
 var _reactNative = require("react-native");
 var _sharedUi = require("@buoy-gg/shared-ui");
@@ -114,12 +114,17 @@ function getBadgeText(event) {
   // Don't show badge text - route type is already shown in status label
   return undefined;
 }
-function RouteEventItemCompact({
+
+// Memo justified by profiling (tool-bench 2026-07-06): 400 row renders
+// during a 5s dwell at 500 events (timeline re-renders cascaded into all
+// mounted rows via an inline onPress closure).
+const RouteEventItemCompact = exports.RouteEventItemCompact = /*#__PURE__*/(0, _react.memo)(function RouteEventItemCompact({
   event,
   visitNumber,
   isExpanded,
   onPress,
-  onNavigate
+  onNavigate,
+  index
 }) {
   const routeType = (0, _react.useMemo)(() => getRouteType(event), [event]);
   const routeTemplate = (0, _react.useMemo)(() => getRouteTemplate(event.pathname, event.segments), [event.pathname, event.segments]);
@@ -127,7 +132,6 @@ function RouteEventItemCompact({
   const statusLabel = (0, _react.useMemo)(() => getStatusLabel(routeType), [routeType]);
   const statusSublabel = (0, _react.useMemo)(() => getStatusSublabel(event), [event]);
   const badgeText = (0, _react.useMemo)(() => getBadgeText(event), [event]);
-  const timeLabel = (0, _sharedUi.useRelativeTime)(event.timestamp);
   const expandedContent = (0, _react.useMemo)(() => {
     if (!isExpanded) return undefined;
     return /*#__PURE__*/(0, _jsxRuntime.jsx)(_RouteEventExpandedContent.RouteEventExpandedContent, {
@@ -170,14 +174,16 @@ function RouteEventItemCompact({
     badgeText: onNavigate ? undefined : badgeText,
     badgeColor: statusColor,
     customBadge: customBadge,
-    bottomRightText: timeLabel,
+    bottomRightText: /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.RelativeTime, {
+      timestamp: event.timestamp
+    }),
     showChevron: true,
     expandedContent: expandedContent,
     isExpanded: isExpanded,
     expandedGlowColor: statusColor,
-    onPress: onPress
+    onPress: () => onPress(index)
   });
-}
+});
 const styles = _reactNative.StyleSheet.create({
   badgeContainer: {
     flexDirection: "row",

package/lib/commonjs/components/RouteEventsTimeline.js

@@ -42,16 +42,40 @@ function RouteEventsTimeline({
       })]
     });
   }
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
-    contentContainerStyle: styles.listContent,
-    children: events.map((event, index) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_RouteEventItemCompact.RouteEventItemCompact, {
-      event: event,
-      visitNumber: visitCounts.get(index) || 1,
-      isExpanded: expandedIndex === index,
-      onPress: () => handleItemPress(index),
-      onNavigate: onNavigate
-    }, `event-${index}-${event.timestamp}`))
-  });
+  return (
+    /*#__PURE__*/
+    // Virtualized — the previous ScrollView + map mounted ALL events (at
+    // the 500-event cap that measured 32.8 JS FPS during an idle dwell,
+    // tool-bench 2026-07-06). extraData re-renders visible rows when the
+    // expanded row changes.
+    (0, _jsxRuntime.jsx)(_reactNative.FlatList, {
+      contentContainerStyle: styles.listContent,
+      data: events
+      // STABLE content keys — index-based keys remount every row when a new
+      // event prepends (measured 4 JS FPS during automation, which emits
+      // route events on every bounce; tool-bench 2026-07-06).
+      ,
+      keyExtractor: event => `${event.timestamp}-${event.pathname}`,
+      extraData: expandedIndex,
+      renderItem: ({
+        item: event,
+        index
+      }) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_RouteEventItemCompact.RouteEventItemCompact, {
+        event: event,
+        visitNumber: visitCounts.get(index) || 1,
+        isExpanded: expandedIndex === index,
+        index: index,
+        onPress: handleItemPress,
+        onNavigate: onNavigate
+      }),
+      showsVerticalScrollIndicator: true,
+      removeClippedSubviews: true,
+      initialNumToRender: 12,
+      maxToRenderPerBatch: 8,
+      windowSize: 5,
+      updateCellsBatchingPeriod: 50
+    })
+  );
 }
 const styles = _reactNative.StyleSheet.create({
   listContent: {

package/lib/commonjs/hooks/useRouteEvents.js

@@ -51,19 +51,28 @@ function useRouteEvents(options = {}) {
       setIsListening(false);
       return;
     }
+
+    // Frame-coalesced (see network's useNetworkEventList): navigation
+    // bursts land as one commit per frame instead of one per emission.
+    let rafId = null;
+    let pending = null;
     const unsubscribe = _routeEventStore.routeEventStore.subscribeToEvents(allEvents => {
-      // Limit events
-      if (allEvents.length > maxEvents) {
-        setEvents(allEvents.slice(0, maxEvents));
-      } else {
-        setEvents(allEvents);
-      }
+      pending = allEvents;
+      if (rafId != null) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        if (!pending) return;
+        const latest = pending;
+        pending = null;
+        setEvents(latest.length > maxEvents ? latest.slice(0, maxEvents) : latest);
+      });
     });
 
     // Mark as listening after successful subscription
     setIsListening(true);
     return () => {
       unsubscribe();
+      if (rafId != null) cancelAnimationFrame(rafId);
       // Note: Don't set isListening=false here because we might be
       // re-subscribing due to dependency change, not actually stopping
     };

package/lib/module/components/RouteEventItemCompact.js

@@ -6,9 +6,9 @@
  * Uses CompactRow pattern matching network/storage/redux components
  */
 
-import { useMemo } from "react";
+import { memo, useMemo } from "react";
 import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
-import { CompactRow, useRelativeTime, buoyColors } from "@buoy-gg/shared-ui";
+import { CompactRow, RelativeTime, buoyColors } from "@buoy-gg/shared-ui";
 import { RouteEventExpandedContent } from "./RouteEventExpandedContent";
 
 // Route type for color coding
@@ -110,12 +110,17 @@ function getBadgeText(event) {
   // Don't show badge text - route type is already shown in status label
   return undefined;
 }
-export function RouteEventItemCompact({
+
+// Memo justified by profiling (tool-bench 2026-07-06): 400 row renders
+// during a 5s dwell at 500 events (timeline re-renders cascaded into all
+// mounted rows via an inline onPress closure).
+export const RouteEventItemCompact = /*#__PURE__*/memo(function RouteEventItemCompact({
   event,
   visitNumber,
   isExpanded,
   onPress,
-  onNavigate
+  onNavigate,
+  index
 }) {
   const routeType = useMemo(() => getRouteType(event), [event]);
   const routeTemplate = useMemo(() => getRouteTemplate(event.pathname, event.segments), [event.pathname, event.segments]);
@@ -123,7 +128,6 @@ export function RouteEventItemCompact({
   const statusLabel = useMemo(() => getStatusLabel(routeType), [routeType]);
   const statusSublabel = useMemo(() => getStatusSublabel(event), [event]);
   const badgeText = useMemo(() => getBadgeText(event), [event]);
-  const timeLabel = useRelativeTime(event.timestamp);
   const expandedContent = useMemo(() => {
     if (!isExpanded) return undefined;
     return /*#__PURE__*/_jsx(RouteEventExpandedContent, {
@@ -166,14 +170,16 @@ export function RouteEventItemCompact({
     badgeText: onNavigate ? undefined : badgeText,
     badgeColor: statusColor,
     customBadge: customBadge,
-    bottomRightText: timeLabel,
+    bottomRightText: /*#__PURE__*/_jsx(RelativeTime, {
+      timestamp: event.timestamp
+    }),
     showChevron: true,
     expandedContent: expandedContent,
     isExpanded: isExpanded,
     expandedGlowColor: statusColor,
-    onPress: onPress
+    onPress: () => onPress(index)
   });
-}
+});
 const styles = StyleSheet.create({
   badgeContainer: {
     flexDirection: "row",

package/lib/module/components/RouteEventsTimeline.js

@@ -10,7 +10,7 @@
  */
 
 import { useCallback, useState } from "react";
-import { View, Text, ScrollView, StyleSheet } from "react-native";
+import { View, Text, FlatList, StyleSheet } from "react-native";
 import { Navigation, buoyColors } from "@buoy-gg/shared-ui";
 import { RouteEventItemCompact } from "./RouteEventItemCompact";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -38,16 +38,40 @@ export function RouteEventsTimeline({
       })]
     });
   }
-  return /*#__PURE__*/_jsx(ScrollView, {
-    contentContainerStyle: styles.listContent,
-    children: events.map((event, index) => /*#__PURE__*/_jsx(RouteEventItemCompact, {
-      event: event,
-      visitNumber: visitCounts.get(index) || 1,
-      isExpanded: expandedIndex === index,
-      onPress: () => handleItemPress(index),
-      onNavigate: onNavigate
-    }, `event-${index}-${event.timestamp}`))
-  });
+  return (
+    /*#__PURE__*/
+    // Virtualized — the previous ScrollView + map mounted ALL events (at
+    // the 500-event cap that measured 32.8 JS FPS during an idle dwell,
+    // tool-bench 2026-07-06). extraData re-renders visible rows when the
+    // expanded row changes.
+    _jsx(FlatList, {
+      contentContainerStyle: styles.listContent,
+      data: events
+      // STABLE content keys — index-based keys remount every row when a new
+      // event prepends (measured 4 JS FPS during automation, which emits
+      // route events on every bounce; tool-bench 2026-07-06).
+      ,
+      keyExtractor: event => `${event.timestamp}-${event.pathname}`,
+      extraData: expandedIndex,
+      renderItem: ({
+        item: event,
+        index
+      }) => /*#__PURE__*/_jsx(RouteEventItemCompact, {
+        event: event,
+        visitNumber: visitCounts.get(index) || 1,
+        isExpanded: expandedIndex === index,
+        index: index,
+        onPress: handleItemPress,
+        onNavigate: onNavigate
+      }),
+      showsVerticalScrollIndicator: true,
+      removeClippedSubviews: true,
+      initialNumToRender: 12,
+      maxToRenderPerBatch: 8,
+      windowSize: 5,
+      updateCellsBatchingPeriod: 50
+    })
+  );
 }
 const styles = StyleSheet.create({
   listContent: {

package/lib/module/hooks/useRouteEvents.js

@@ -48,19 +48,28 @@ export function useRouteEvents(options = {}) {
       setIsListening(false);
       return;
     }
+
+    // Frame-coalesced (see network's useNetworkEventList): navigation
+    // bursts land as one commit per frame instead of one per emission.
+    let rafId = null;
+    let pending = null;
     const unsubscribe = routeEventStore.subscribeToEvents(allEvents => {
-      // Limit events
-      if (allEvents.length > maxEvents) {
-        setEvents(allEvents.slice(0, maxEvents));
-      } else {
-        setEvents(allEvents);
-      }
+      pending = allEvents;
+      if (rafId != null) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        if (!pending) return;
+        const latest = pending;
+        pending = null;
+        setEvents(latest.length > maxEvents ? latest.slice(0, maxEvents) : latest);
+      });
     });
 
     // Mark as listening after successful subscription
     setIsListening(true);
     return () => {
       unsubscribe();
+      if (rafId != null) cancelAnimationFrame(rafId);
       // Note: Don't set isListening=false here because we might be
       // re-subscribing due to dependency change, not actually stopping
     };

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

@@ -8,8 +8,11 @@ export interface RouteEventItemCompactProps {
     event: RouteChangeEvent;
     visitNumber: number;
     isExpanded: boolean;
-    onPress: () => void;
+    /** Row's list index — passed back through onPress so the handler can
+     * stay a single stable callback (memo-compatible). */
+    index: number;
+    onPress: (index: number) => void;
     onNavigate?: (pathname: string) => void;
 }
-export declare function RouteEventItemCompact({ event, visitNumber, isExpanded, onPress, onNavigate, }: RouteEventItemCompactProps): import("react").JSX.Element;
+export declare const RouteEventItemCompact: import("react").NamedExoticComponent<RouteEventItemCompactProps>;
 //# sourceMappingURL=RouteEventItemCompact.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"RouteEventItemCompact.d.ts","sourceRoot":"","sources":["../../../src/components/RouteEventItemCompact.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AA6GD,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,WAAW,EACX,UAAU,EACV,OAAO,EACP,UAAU,GACX,EAAE,0BAA0B,+BA6D5B"}
+{"version":3,"file":"RouteEventItemCompact.d.ts","sourceRoot":"","sources":["../../../src/components/RouteEventItemCompact.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB;0DACsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAgHD,eAAO,MAAM,qBAAqB,kEAmEhC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"RouteEventsTimeline.d.ts","sourceRoot":"","sources":["../../../src/components/RouteEventsTimeline.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,UAAU,wBAAwB;IAChC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,WAAW,EACX,UAAU,GACX,EAAE,wBAAwB,+BAiC1B"}
+{"version":3,"file":"RouteEventsTimeline.d.ts","sourceRoot":"","sources":["../../../src/components/RouteEventsTimeline.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,UAAU,wBAAwB;IAChC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,WAAW,EACX,UAAU,GACX,EAAE,wBAAwB,+BAoD1B"}

package/lib/typescript/hooks/useRouteEvents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRouteEvents.d.ts","sourceRoot":"","sources":["../../../src/hooks/useRouteEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,uBAAuB;IACvB,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,6DAA6D;IAC7D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CA4CtB"}
+{"version":3,"file":"useRouteEvents.d.ts","sourceRoot":"","sources":["../../../src/hooks/useRouteEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,uBAAuB;IACvB,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,6DAA6D;IAC7D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAoDtB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buoy-gg/route-events",
-  "version": "5.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/floating-tools-core": "5.0.0",
-    "@buoy-gg/shared-ui": "5.0.0"
+    "@buoy-gg/floating-tools-core": "6.0.1",
+    "@buoy-gg/shared-ui": "6.0.1"
   },
   "peerDependencies": {
-    "@buoy-gg/license": "5.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": "5.0.0"
+    "@buoy-gg/license": "6.0.1"
   },
   "react-native-builder-bob": {
     "source": "src",