npm package: @flightdev/devtools
Description: Development tools and debugging panel for Flight Framework
Latest version: 3.0.1

# @flightdev/devtools

Developer tools for Flight Framework. Inspect routes, debug server actions, and monitor performance.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Features](#features)
- [Configuration](#configuration)
- [Browser Extension](#browser-extension)
- [API](#api)
- [License](#license)

---

## Installation

```bash
npm install -D @flightdev/devtools
```

---

## Quick Start

```typescript
// flight.config.ts
import { defineConfig } from '@flightdev/core';
import { devtools } from '@flightdev/devtools';

export default defineConfig({
    plugins: [
        devtools(),
    ],
});
```

Access the devtools panel at `/__devtools` in development mode.

---

## Features

### Route Inspector
- View all registered routes
- See route parameters and patterns
- Test route matching

### Component Tree
- Visualize component hierarchy
- Inspect props and state
- Highlight rendering

### Server Actions
- Log all server action calls
- View request/response payloads
- Measure execution time

### Cache Inspector
- View cached entries
- Inspect TTL and hit rates
- Manually invalidate entries

### Network Monitor
- Track API requests
- View request/response headers
- Measure response times

### Performance
- Core Web Vitals (LCP, FID, CLS)
- Hydration timing
- Bundle size analysis

---

## Contributing

See the main [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

---

## New in V2: Enhanced Panels

### Hydration Panel

Track island hydration timing and status:

```typescript
import { subscribeToHydration, setupHydrationTracking } from '@flightdev/devtools/hydration';

// Auto-track hydration events
setupHydrationTracking();

// Subscribe to updates
subscribeToHydration((islands, metrics) => {
    console.log(`Hydrated: ${metrics.hydratedCount}/${metrics.totalIslands}`);
    console.log(`Avg time: ${metrics.averageHydrationTime}ms`);
});
```

### Bundle Panel

Monitor chunk loading and sizes:

```typescript
import { subscribeToBundles, setupBundleTracking } from '@flightdev/devtools/bundle';

// Auto-track via Performance API
setupBundleTracking();

// Subscribe to updates
subscribeToBundles((chunks, metrics) => {
    console.log(`Total size: ${metrics.totalSize} bytes`);
    console.log(`Loaded: ${metrics.loadedChunks} chunks`);
});
```

### Enhanced Cache Panel

Advanced cache inspection with tag support:

```typescript
import { subscribeToCache, invalidateByTag } from '@flightdev/devtools/cache';

// Subscribe to cache updates
subscribeToCache((entries, metrics) => {
    console.log(`Hit rate: ${metrics.hitRate}%`);
    console.log(`Tags: ${metrics.uniqueTags.join(', ')}`);
});

// Invalidate by tag
invalidateByTag('user-data');
```

---

## Configuration

```typescript
devtools({
    // Enable in development only (default)
    enabled: process.env.NODE_ENV !== 'production',
    
    // Devtools server port
    port: 9229,
    
    // Open devtools automatically
    open: false,
    
    // Features to enable
    features: {
        routes: true,
        components: true,
        actions: true,
        cache: true,
        network: true,
        performance: true,
    },
    
    // Overlay position
    position: 'bottom-right',
});
```

---

## Browser Extension

Install the Flight DevTools browser extension for an integrated debugging experience:

- **Chrome**: [Flight DevTools](https://chrome.google.com/webstore/...)
- **Firefox**: [Flight DevTools](https://addons.mozilla.org/...)

The extension adds a "Flight" panel to your browser's developer tools.

---

## API

### Programmatic Access

```typescript
import { getDevtools } from '@flightdev/devtools';

const devtools = getDevtools();

// Log custom event
devtools.log('custom', { message: 'Hello' });

// Add custom panel
devtools.addPanel('my-panel', {
    title: 'My Panel',
    render: () => '<div>Custom content</div>',
});
```

### React Hook

```tsx
import { useDevtools } from '@flightdev/devtools/react';

function MyComponent() {
    const { log, measure } = useDevtools();
    
    const handleClick = () => {
        const end = measure('click-handler');
        // ... do work
        end();
    };
    
    return <button onClick={handleClick}>Click</button>;
}
```

---

## License

MIT