wip devtools - squashed

Author: samwillis

.gitignore

@@ -90,6 +90,7 @@ out
 # Nuxt.js build / generate output
 .nuxt
 dist
+build
 
 # Gatsby files
 .cache/

db-devtools-summary.md

@@ -0,0 +1,162 @@
+# TanStack DB DevTools Architecture - Implementation Summary
+
+## What Was Accomplished
+
+Successfully implemented a comprehensive devtools architecture for TanStack DB with the following components:
+
+### 1. Core DevTools Package (`@tanstack/db-devtools`)
+- **Complete implementation** with SolidJS-based UI components
+- Comprehensive collection and transaction monitoring
+- Real-time performance tracking for live queries
+- Garbage collection aware weak reference management
+- Global registry system for collection tracking
+
+#### Key Features:
+- Collection metadata tracking (status, size, transactions, timings)
+- Transaction details with mutation history
+- Live query performance metrics
+- Memory-efficient weak reference system
+- Automatic cleanup and garbage collection
+
+#### Files Created:
+- `packages/db-devtools/src/index.ts` - Main exports
+- `packages/db-devtools/src/devtools.ts` - Core devtools functions
+- `packages/db-devtools/src/registry.ts` - Collection registry implementation
+- `packages/db-devtools/src/types.ts` - TypeScript definitions
+- `packages/db-devtools/src/DbDevtools.tsx` - Main devtools component
+- `packages/db-devtools/src/DbDevtoolsPanel.tsx` - Panel implementation
+- `packages/db-devtools/src/components/` - UI components for collections, transactions, etc.
+
+### 2. React Integration Package (`@tanstack/react-db-devtools`)
+- React wrapper component for the core devtools
+- Proper integration with React applications
+- Dynamic loading and mounting of SolidJS components
+
+#### Files Created:
+- `packages/react-db-devtools/src/ReactDbDevtools.tsx` - React wrapper component
+- `packages/react-db-devtools/src/index.ts` - Exports
+
+### 3. Vue Integration Package (`@tanstack/vue-db-devtools`)
+- Vue wrapper component (basic structure)
+- Type definitions for Vue integration
+
+#### Files Created:
+- `packages/vue-db-devtools/src/VueDbDevtools.vue` - Vue component
+- `packages/vue-db-devtools/src/index.ts` - Exports
+
+### 4. Package Configuration
+- Complete `package.json` files for all three packages
+- Build configurations with `tsup` for JavaScript/TypeScript compilation
+- Proper dependency management and workspace integration
+- ESLint configuration and linting fixes applied
+
+### 5. React Example Integration
+- Added devtools dependency to the React todo example
+- Imported and integrated `ReactDbDevtools` component
+- Updated package.json with workspace reference
+
+## Architecture Overview
+
+### React Integration Solution
+Following TanStack Query and Router patterns, we implemented a mount/unmount class approach:
+
+**Core Package (`@tanstack/db-devtools`)**
+- `TanstackDbDevtools` class with `.mount()` and `.unmount()` methods
+- Uses SolidJS `render()` to mount components into provided DOM elements
+- Registry, types, and SolidJS components all in one package
+- Clean separation between class API and UI implementation
+
+**React Package (`@tanstack/react-db-devtools`)**
+- Simple React wrapper that creates `TanstackDbDevtools` instance
+- Uses `useRef` to get DOM element and calls `devtools.mount(ref.current)`
+- Handles prop updates via class setter methods
+- No component duplication - reuses original SolidJS components
+
+This approach eliminates JSX conflicts by using DOM mounting instead of component transpilation.
+
+### Global Registry System
+```typescript
+interface DbDevtoolsRegistry {
+  collections: Map<string, CollectionRegistryEntry>
+  registerCollection: (collection: CollectionImpl) => void
+  unregisterCollection: (id: string) => void
+  getCollectionMetadata: (id: string) => CollectionMetadata | undefined
+  getAllCollectionMetadata: () => Array<CollectionMetadata>
+  getCollection: (id: string) => CollectionImpl | undefined
+  releaseCollection: (id: string) => void
+  getTransactions: (collectionId?: string) => Array<TransactionDetails>
+  getTransaction: (id: string) => TransactionDetails | undefined
+  cleanup: () => void
+  garbageCollect: () => void
+}
+```
+
+### Memory Management
+- Uses `WeakRef` for collection references to prevent memory leaks
+- Automatic garbage collection of dead collection references
+- Hard references only created when actively viewing collections
+- Polling system for metadata updates with configurable intervals
+
+### Performance Tracking
+- Live query execution timing
+- Incremental run statistics
+- Transaction state monitoring
+- Collection size and status tracking
+
+### UI Components
+- **CollectionList**: Overview of all collections with metadata
+- **CollectionDetails**: Detailed view of individual collections
+- **TransactionList**: List of transactions with filtering
+- **TransactionDetails**: Detailed mutation history view
+- **Query Inspector**: Live query analysis and performance metrics
+
+## Current Status
+
+### ✅ Completed
+- Core devtools architecture and implementation
+- SolidJS-based UI components with full functionality
+- TypeScript definitions and type safety
+- Package structure and build configuration
+- Linting and code quality fixes
+- React wrapper component structure
+- Vue wrapper component basic structure
+
+### ✅ Recently Fixed
+- **React Integration Type Conflicts**: Successfully resolved using TanStack mount/unmount pattern
+- **Component Duplication**: Eliminated by reusing SolidJS components via DOM mounting
+- **Architecture**: Implemented consistent TanStack Query/Router patterns for framework integration
+
+### ⚠️ Partial/In Progress  
+- TypeScript type declarations need to be generated for better developer experience
+- Vue integration is basic structure only
+- React example has some runtime TypeScript errors but functionality works
+
+### 🔄 Next Steps
+1. **Generate Type Declarations**: Add proper .d.ts files for all packages to resolve TypeScript import issues
+2. **Complete Vue Integration**: Implement proper Vue SFC handling in build process  
+3. **Testing**: Add comprehensive test coverage
+4. **Documentation**: Create usage guides and API documentation
+5. **Performance Optimization**: Profile and optimize the devtools overhead
+6. **Polish React Integration**: Fix remaining TypeScript compilation issues
+
+## Technical Challenges Addressed
+
+1. **Cross-Framework Compatibility**: Created a core devtools that can be wrapped by any framework
+2. **Memory Management**: Implemented weak reference system to prevent memory leaks
+3. **Real-time Updates**: Built polling system for live collection metadata
+4. **Type Safety**: Comprehensive TypeScript definitions throughout
+5. **Build System**: Set up proper package compilation with external dependencies
+6. **SolidJS/React Type Conflicts**: Resolved using TanStack mount/unmount pattern, eliminating JSX transpilation conflicts while reusing SolidJS components
+
+## Package Versions and Dependencies
+- Core: `@tanstack/[email protected]`
+- React: `@tanstack/[email protected]` 
+- Vue: `@tanstack/[email protected]`
+
+All packages are properly configured with workspace references and external dependency management.
+
+## Code Quality
+- All packages pass ESLint with consistent formatting
+- Proper TypeScript configuration
+- Clean separation of concerns between core and framework-specific packages
+- Follow TanStack conventions and patterns