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.

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