diff --git a/docs/adr/ADR-001-client-side-debug-storage.md b/docs/adr/ADR-001-client-side-debug-storage.md new file mode 100644 index 00000000..9c329c59 --- /dev/null +++ b/docs/adr/ADR-001-client-side-debug-storage.md @@ -0,0 +1,173 @@ +# ADR-001: Client-Side Debug Storage Technology + +## Status +**Accepted** - 2025-11-10 + +## Context + +The Markitect application requires a robust client-side debugging infrastructure to track and display debug messages during document editing operations. The previous implementation relied on a tightly-coupled debug panel that expected specific DOM elements and was integrated into old dialog systems. + +### Requirements +- **Independence**: Debug system must be independent of specific UI components +- **Persistence**: Debug messages should survive browser refresh/close +- **Real-time Updates**: UI should reflect new messages immediately +- **Performance**: Should not block the main thread or impact editor performance +- **Storage Capacity**: Must handle 1000+ debug messages efficiently +- **Browser Compatibility**: Work across all modern browsers +- **Developer Experience**: Easy to integrate and use throughout the codebase + +### Problem Statement +The existing debug infrastructure was failing because: +1. Tight coupling to specific DOM elements (`debug-messages-container`, `toggle-debug`) +2. Dependency on old dialog systems +3. No persistence across browser sessions +4. Limited to in-memory storage only + +## Decision + +**We will use IndexedDB as the primary client-side storage technology for the debug system.** + +## Alternatives Considered + +### Option 1: IndexedDB (Selected) +**Technology**: Browser-native object store database +**Implementation**: `window.MarkitectDebugSystem` with async operations + +### Option 2: SQLite via SQL.js +**Technology**: WebAssembly-based SQLite implementation +**Implementation**: SQL.js library with manual persistence + +### Option 3: LocalStorage +**Technology**: Browser key-value storage +**Implementation**: JSON serialization with size limits + +### Option 4: In-Memory Only +**Technology**: JavaScript arrays with no persistence +**Implementation**: Simple message array management + +## Decision Matrix + +| Criteria | IndexedDB | SQLite | LocalStorage | In-Memory | +|----------|-----------|---------|--------------|-----------| +| **Storage Capacity** | ✅ Large (50-100MB+) | ✅ Large | ❌ Limited (5-10MB) | ❌ Session only | +| **Performance** | ✅ Async/Non-blocking | ⚠️ Can block UI | ✅ Fast | ✅ Fastest | +| **Persistence** | ✅ Across sessions | ✅ Across sessions | ✅ Across sessions | ❌ Lost on refresh | +| **Query Capabilities** | ⚠️ Limited | ✅ Full SQL | ❌ None | ❌ JavaScript only | +| **Dependencies** | ✅ Native | ❌ 1.5MB WebAssembly | ✅ Native | ✅ Native | +| **Browser Support** | ✅ Universal modern | ✅ Universal | ✅ Universal | ✅ Universal | +| **API Complexity** | ⚠️ Moderate | ✅ Familiar SQL | ✅ Simple | ✅ Simple | +| **Use Case Fit** | ✅ Perfect match | ⚠️ Overkill | ❌ Too limited | ❌ Insufficient | + +## Rationale + +### Why IndexedDB? + +1. **Native Browser Support**: No external dependencies or WebAssembly files +2. **Asynchronous Operations**: Won't block the UI thread during debug operations +3. **Sufficient Storage**: 50-100MB+ capacity easily handles thousands of debug messages +4. **Appropriate Complexity**: Matches our simple data model without over-engineering +5. **Performance Optimized**: Browsers optimize IndexedDB for web applications +6. **Security**: Runs within browser's security sandbox with proper origin isolation + +### Why Not SQLite? + +While SQLite offers powerful querying capabilities, it's overkill for our use case: + +- **Complexity**: Our data model is simple (timestamp, category, message) +- **Dependencies**: 1.5MB WebAssembly adds significant overhead +- **Synchronous Risk**: Large operations can block the UI thread +- **Manual Persistence**: Requires explicit save/load operations +- **Over-Engineering**: We don't need JOINs, complex queries, or relational features + +### Why Not LocalStorage? + +LocalStorage is too limited: +- **Size Constraints**: 5-10MB limit insufficient for extensive debug logs +- **Synchronous API**: Blocks main thread during operations +- **No Structured Data**: JSON serialization/deserialization overhead +- **Browser Quotas**: Can be evicted under storage pressure + +### Why Not In-Memory? + +In-memory storage is insufficient: +- **No Persistence**: Debug context lost on page refresh +- **Memory Pressure**: Large debug logs consume RAM +- **Development Workflow**: Debugging often requires page reloads + +## Implementation Details + +### Data Structure +```javascript +{ + id: auto_increment_id, + message: "Debug message text", + category: "INFO" | "WARNING" | "ERROR" | "SUCCESS" | "DEBUG", + timestamp: "2025-11-10T23:35:53.123Z", + displayTime: "11:35:53 PM" +} +``` + +### Database Schema +- **Store Name**: `messages` +- **Key Path**: `id` (auto-increment) +- **Indexes**: `timestamp`, `category` +- **Version**: 1 + +### API Design +```javascript +// Core operations +await MarkitectDebugSystem.addMessage(message, category); +await MarkitectDebugSystem.clearMessages(); +const messages = MarkitectDebugSystem.getMessages(category, limit); + +// Advanced features +const unsubscribe = MarkitectDebugSystem.subscribe(callback); +const json = MarkitectDebugSystem.exportMessages(); +``` + +## Consequences + +### Positive +- ✅ **Zero Dependencies**: No external libraries required +- ✅ **High Performance**: Non-blocking operations maintain UI responsiveness +- ✅ **Persistent Debugging**: Debug context preserved across browser sessions +- ✅ **Scalable Storage**: Handles thousands of debug messages efficiently +- ✅ **Future-Proof**: Can add advanced features without architectural changes +- ✅ **Developer-Friendly**: Simple API integration throughout codebase + +### Negative +- ⚠️ **Limited Querying**: Complex filtering requires custom JavaScript code +- ⚠️ **Browser Variations**: Subtle differences in IndexedDB implementations +- ⚠️ **Learning Curve**: Developers may be less familiar with IndexedDB vs SQL + +### Mitigation Strategies +- **Query Limitations**: Implement helper methods for common filtering operations +- **Browser Compatibility**: Use feature detection with graceful fallbacks +- **Developer Experience**: Provide clear API documentation and examples + +## Future Considerations + +### Potential Enhancements +1. **Hybrid Approach**: Add optional SQLite mode for advanced users +2. **Data Export**: Multiple export formats (JSON, CSV, SQL dumps) +3. **Advanced Filtering**: Web Workers for complex query operations +4. **Data Visualization**: Charts and analytics for debug patterns +5. **Remote Sync**: Optional sync to development servers + +### Migration Path +The current IndexedDB implementation provides a foundation that could support: +- Adding SQLite as an "advanced mode" option +- Implementing data export to external analysis tools +- Building analytics dashboards on top of the debug data + +## References +- [IndexedDB API Documentation](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) +- [SQL.js Documentation](https://sql.js.org/) +- [Web Storage API Limitations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API#Storage_limits) + +## Approval + +**Decided by**: Claude Code Development Team +**Date**: 2025-11-10 +**Context**: Independent debug system redesign +**Next Review**: When complex querying requirements emerge \ No newline at end of file diff --git a/markitect/clean_document_manager.py b/markitect/clean_document_manager.py index 975bde44..5e66d478 100644 --- a/markitect/clean_document_manager.py +++ b/markitect/clean_document_manager.py @@ -1182,9 +1182,13 @@ class CleanDocumentManager: // Abstract control properties element: null, isExpanded: false, + isHeaderOnly: false, // New state for header-only mode isDragging: false, + isResizing: false, // New state for resizing mode dragOffset: {{ x: 0, y: 0 }}, + resizeStartSize: {{ width: 280, height: 'auto' }}, originalPosition: {{ top: '80px', left: '20px' }}, + defaultSize: {{ width: 280, minWidth: 200, minHeight: 150 }}, // Configuration properties (to be overridden by subclasses) config: {{ @@ -1266,7 +1270,7 @@ class CleanDocumentManager: