markitect-main/TODO.md

# Todofile

This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.

The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).

The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.

***

## [Unreleased] - *Active Vibe-Coding State* 💡

This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.

**🏗️ MAJOR ARCHITECTURE REFACTORING (2025-11-03)**: Critical architecture issues identified requiring comprehensive JavaScript refactoring:

**PROBLEMS IDENTIFIED**:
1. **Monolithic Architecture**: Single 5,188-line `editor.js` file violates separation of concerns
2. **Server-Side Debug Generation**: Debug messages captured during Python HTML generation instead of client-side interaction
3. **Architectural Boundary Violations**: JavaScript editing infrastructure affecting Python md-render code
4. **Tight Coupling**: UI components interdependent and untestable independently
5. **Generic Editor Compromise**: Debug system entangled with rendering instead of being purely client-side

**SOLUTION**: Modular JavaScript Architecture with component separation and proper client-side debugging.

**📊 PREVIOUS STATUS (2025-11-02)**: Systematic JavaScript functionality recovery using TDD methodology had made excellent progress. **5 major features** were successfully implemented and tested:

1. **Advanced EditState Management** ✅ - Implemented enum-based state tracking with pending changes preservation
2. **Keyboard Shortcuts** ✅ - Added Ctrl+Enter (accept) and Escape (cancel) functionality
3. **Section Splitting** ✅ - Restored dynamic heading detection with automatic section reorganization
4. **Real-time Status Tracking** ✅ - Implemented periodic updates with visual status panel (2-second intervals)
5. **Intelligent Filename Generation** ✅ - Added 4-method fallback system (options→title→URL→heading→timestamp)

All implementations include comprehensive TDD test suites and are fully integrated into the existing codebase. The recovery approach has proven highly effective for restoring sophisticated lost functionality.

## 🏗️ JAVASCRIPT ARCHITECTURE REFACTORING ROADMAP

### **Phase 1: Preparation & Backup (CRITICAL)**
* 🚧 Update TODO.md with comprehensive refactoring plan - IN PROGRESS
* ⏳ Commit current monolithic state for rollback safety - PENDING
* ⏳ Create modular directory structure `markitect/static/js/` - PENDING
* ⏳ Set up component template files with proper exports/imports - PENDING

### **Phase 2: Core System Extraction (HIGH)**
* ⏳ Extract SectionManager to `core/section-manager.js` - PENDING
* ⏳ Extract EventSystem to `core/event-system.js` - PENDING
* ⏳ Create EditorCore orchestrator in `core/editor-core.js` - PENDING

### **Phase 3: Component Separation (HIGH)**
* ⏳ Document Controls → `components/document-controls.js` - PENDING
* ⏳ Status Panel → `components/status-panel.js` - PENDING
* ⏳ Debug Panel → `components/debug-panel.js` (pure client-side) - PENDING
* ⏳ Floating Menu → `components/floating-menu.js` - PENDING
* ⏳ Text/Image Editors → separate component files - PENDING

### **Phase 4: Testing Infrastructure (MEDIUM)**
* ⏳ Standalone test runner that doesn't require md-render - PENDING
* ⏳ Component unit tests for individual functionality - PENDING
* ⏳ Integration tests for component interaction - PENDING
* ⏳ Browser-based test runner for direct UI testing - PENDING

### **Phase 5: Integration & Cleanup (MEDIUM)**
* ⏳ Update HTML template to load modular components - PENDING
* ⏳ Remove monolithic editor.js - PENDING
* ⏳ Ensure Python code unchanged - no md-render modifications - PENDING
* ⏳ Validate all functionality works with new architecture - PENDING

### **Directory Structure Plan:**
```
markitect/static/js/
├── core/
│   ├── editor-core.js          # Main editor initialization
│   ├── section-manager.js      # Section state management
│   └── event-system.js         # Event handling system
├── components/
│   ├── document-controls.js    # Document controls panel
│   ├── status-panel.js         # Status display component
│   ├── debug-panel.js          # Debug panel (client-side only)
│   ├── floating-menu.js        # Generic floating menu system
│   ├── text-editor.js          # Text section editor
│   └── image-editor.js         # Image section editor
├── utils/
│   ├── dom-utils.js            # DOM manipulation utilities
│   └── positioning.js          # Layout positioning logic
└── tests/
    ├── test-runner.js          # Standalone test framework
    ├── component-tests.js      # UI component tests
    └── integration-tests.js    # Full workflow tests
```

### **PREVIOUS COMPLETED FEATURES (Now requiring refactoring):**
* **To Add:**
    * ✅ Advanced state management with EditState enum and pending changes (CRITICAL) - COMPLETED
    * ✅ Keyboard shortcuts (Ctrl+Enter accept, Escape cancel) (CRITICAL) - COMPLETED
    * ✅ Section splitting functionality for dynamic heading detection (HIGH) - COMPLETED
    * ✅ Real-time status tracking with periodic updates (HIGH) - COMPLETED
    * ✅ Intelligent save filename generation with 4-method fallback (MEDIUM) - COMPLETED
    * 🔄 Professional message system with color-coded positioning (MEDIUM) - NEEDS REFACTORING
    * 🔄 Multiple concurrent editing sessions support (MEDIUM) - NEEDS REFACTORING
    * 🔄 Enhanced DOM event system with 6 event types (LOW) - NEEDS REFACTORING
    * 🔄 Automatic section type detection (heading, code, list, etc) (LOW) - NEEDS REFACTORING
    * 🔄 Sophisticated section ID generation with hash-based algorithm (LOW) - NEEDS REFACTORING

* **To Fix:**
    * Comprehensive status reporting dialog with detailed stats (HIGH)
    * Floating global control panel with professional styling (MEDIUM)
    * Enhanced setupSectionElement with comprehensive styling (LOW)

* **To Refactor:**
    * ✅ stopEditing method with state preservation (CRITICAL) - COMPLETED
    * ✅ getAllSections method for section collection management (MEDIUM) - COMPLETED
    * ✅ hasChanges detection for unsaved modifications (HIGH) - COMPLETED
    * ✅ updateGlobalStatus method with 2-second interval updates (MEDIUM) - COMPLETED
    * ✅ handleSectionSplit for dynamic section reorganization (LOW) - COMPLETED
    * ✅ checkForSectionSplits automatic heading detection (LOW) - COMPLETED

* **To Remove:**
    * None currently identified


***

## Completed Tasks

**Asset Shipping for md-render - COMPLETED ✅**:
- ✅ Implemented automatic asset copying when rendering markdown to different output directories
- ✅ Added asset discovery functionality parsing markdown for image/link references
- ✅ Implemented timestamp-based asset copying (only copy if source newer than destination)
- ✅ Added `--ship-assets` and `--no-ship-assets` CLI flags for explicit control
- ✅ Added `MARKITECT_OUTPUT_DIR` environment variable support for default output directory
- ✅ Smart defaults: assets ship automatically when output is directory, disabled for specific files
- ✅ Preserved relative path structure in output directory maintaining markdown link compatibility
- ✅ Graceful handling of missing assets with warning messages
- ✅ Full backward compatibility with existing md-render workflows
- ✅ Comprehensive TDD test suite covering all functionality and edge cases

**Feature Capabilities**:
- Environment variable priority: CLI `--output` > `MARKITECT_OUTPUT_DIR` > input file directory
- Automatic asset discovery from standard markdown syntax: `![alt](path)` and `[text](path)`
- Timestamp-based incremental copying prevents unnecessary file operations
- Directory structure preservation maintains working relative links in output HTML
- Support for images, documents, and other asset types referenced in markdown

**CHANGELOG.md Enhancement - COMPLETED ✅**:
- ✅ Added missing version entries for 0.1.0, 0.2.0, and 0.3.0
- ✅ Added standard Keep a Changelog header with proper format
- ✅ Included Unreleased section
- ✅ Research completed for all historical versions using git log analysis
- ✅ All entries follow Keep a Changelog categories (Added, Changed, Fixed)
- ✅ Chronological order maintained with latest versions first
- ✅ Appropriate release dates included based on git commit timestamps

**Version Details Added**:
- v0.1.0 (2025-10-15): Development infrastructure, TDD workspace, issue management
- v0.2.0 (2025-10-20): Advanced Markdown Engine with GraphQL, search, plugins
- v0.3.0 (2025-10-25): Architectural improvements with kaizen-agentic integration