@concavejs/devtools 0.0.1-alpha.4

package/README.md

@@ -0,0 +1,263 @@
+# Concave DevTools
+
+Professional development tools for Convex/Concave applications. A high-signal browser DevTools focused on operation debugging, subscriptions, logs, and performance.
+
+## Features
+
+### 🔎 Activity Panel
+- Unified list of queries, mutations, and actions
+- Fast filter/search with keyboard navigation
+- Search across function path, IDs, args, results, errors, and log lines
+- Incremental history loading for long sessions
+- Arguments and results inspection
+- Inline error visibility with focused details pane
+
+### 📈 Performance Monitoring
+- Average and P95 latency metrics
+- Slowest operations tracking
+- Queries, mutations, and actions statistics
+- Performance trend analysis
+- Click-through from slow operations to full Activity details
+
+### 📡 Subscriptions Panel
+- Live subscribed query tracking
+- Update counts, status, and component context
+
+### 📝 Logs Panel
+- Centralized console logs from all functions
+- Filter by log level (log, info, warn, error)
+- Auto-scroll and search
+- Search by related operation path/ID
+- Related event tracking
+
+### ⚙️ Settings & Advanced Features
+- **Pause/Resume Recording**: Control when events are captured
+- **Export/Import Sessions**: Save and share debugging sessions
+- **Time-Travel Debugging**: Create snapshots and restore state
+- **Persistent Storage**: Events persist across page reloads
+- **Keyboard Shortcuts**: Fast access to all features
+
+## Installation
+
+```bash
+npm install @concavejs/devtools
+```
+
+## Usage
+
+### Vite Plugin
+
+Add the devtools plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+import { concaveDevTools } from "@concavejs/devtools/vite";
+
+export default defineConfig({
+  plugins: [
+    concaveDevTools({
+      // Only enable in development (default: true in dev mode)
+      enabled: true,
+      
+      // Position of the devtools overlay
+      position: "bottom-right", // "bottom-right" | "bottom-left" | "top-right" | "top-left"
+    }),
+  ],
+});
+```
+
+That's it! The devtools will automatically initialize when your app loads in development mode.
+
+### Manual Installation (without Vite plugin)
+
+If you're not using Vite or want manual control:
+
+```typescript
+import { initDevTools } from "@concavejs/devtools/client";
+
+// Initialize devtools
+initDevTools({
+  position: "bottom-right",
+});
+```
+
+## Keyboard Shortcuts
+
+- **Cmd/Ctrl + Shift + D**: Toggle DevTools
+- **Cmd/Ctrl + K**: Focus search
+- **Cmd/Ctrl + E**: Export session
+- **Cmd/Ctrl + P**: Pause/Resume recording
+
+## API
+
+### Event Store
+
+The devtools use a global event store that you can access programmatically:
+
+```typescript
+import { getGlobalEventStore } from "@concavejs/devtools";
+
+const store = getGlobalEventStore();
+
+// Subscribe to events
+const unsubscribe = store.subscribe((event) => {
+  console.log("New event:", event);
+});
+
+// Get all events
+const events = store.getAllEvents();
+
+// Get events by type
+const queries = store.getEventsByType("query");
+
+// Get active subscriptions
+const subscriptions = store.getActiveSubscriptions();
+
+// Get performance metrics
+const metrics = store.getPerformanceMetrics();
+
+// Export session
+const session = store.exportSession();
+
+// Import session
+store.importSession(session);
+
+// Pause/Resume
+store.pause();
+store.resume();
+
+// Clear all data
+store.clear();
+```
+
+### WebSocket Interceptor
+
+The devtools automatically intercept WebSocket communication with the Convex/Concave backend. You can also use the interceptor directly:
+
+```typescript
+import { WebSocketInterceptor, EventStore } from "@concavejs/devtools";
+
+const eventStore = new EventStore();
+const interceptor = new WebSocketInterceptor(eventStore);
+
+// Install the interceptor
+interceptor.install();
+
+// Uninstall when done
+interceptor.uninstall();
+```
+
+## Components
+
+You can use the devtools components in your own React application:
+
+```typescript
+import { DevToolbar } from "@concavejs/devtools";
+import { getGlobalEventStore } from "@concavejs/devtools";
+
+function MyApp() {
+  const eventStore = getGlobalEventStore();
+
+  return <DevToolbar eventStore={eventStore} position="bottom-right" />;
+}
+```
+
+## Session Management
+
+### Export Session
+
+Export your debugging session to share with team members or for later analysis:
+
+1. Open DevTools
+2. Click the 💾 button or press **Cmd/Ctrl + E**
+3. Save the `.json` file
+
+### Import Session
+
+Import a previously exported session:
+
+1. Open DevTools
+2. Go to Settings tab
+3. Click "Import Session"
+4. Select the `.json` file
+
+### Time-Travel Debugging
+
+Create snapshots of your application state:
+
+1. Open DevTools → Settings
+2. Click "Create Snapshot"
+3. Continue using your app
+4. Click "Restore" on any snapshot to go back in time
+
+## Configuration
+
+### Event Store Settings
+
+Configure the event store behavior:
+
+```typescript
+import { getGlobalEventStore } from "@concavejs/devtools";
+
+const store = getGlobalEventStore();
+
+store.saveSettings({
+  // Persist events across page reloads
+  persistEvents: true,
+  
+  // Maximum number of events to store
+  maxEvents: 1000,
+  
+  // Capture console logs from functions
+  captureLogLines: true,
+});
+```
+
+## Performance
+
+The devtools are designed to have minimal impact on your application:
+
+- Events are stored in a circular buffer (configurable max size)
+- WebSocket interception uses native proxies for minimal overhead
+- React components are optimized with proper memoization
+- Persistence uses localStorage with size limits
+
+## Browser Support
+
+- Chrome/Edge: ✅ Full support
+- Firefox: ✅ Full support
+- Safari: ✅ Full support
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Type check
+npm run type-check
+
+# Watch mode (for development)
+npm run dev
+```
+
+## Architecture
+
+The devtools consist of several key components:
+
+1. **Vite Plugin**: Injects the devtools into your app during development
+2. **WebSocket Interceptor**: Captures Convex sync protocol messages
+3. **Event Store**: Maintains a history of all captured events
+4. **React UI**: Full-featured devtools interface
+5. **Client Entry**: Initializes everything and mounts the UI
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.