feat: enhance control system with improved UI and debug functionality
- Add resize functionality to all controls with hover-only visibility - Replace heading tags with control-title CSS class to prevent content confusion - Implement small circle resize handles positioned in lower-right corner - Add header-only toggle mode for space-efficient control management - Create independent IndexedDB-based debug system with selection filtering - Fix green button backgrounds in debug control (use neutral grey) - Add hover behavior for clean interface (resize handle and close button) - Support document structure scanning for targeted debugging - Enable drag positioning with 16-point compass system - Add persistent storage for debug messages across browser sessions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
173
docs/adr/ADR-001-client-side-debug-storage.md
Normal file
173
docs/adr/ADR-001-client-side-debug-storage.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user